@menasehk/sera 1.0.2 → 1.0.3

package/README.md

@@ -1,376 +1,178 @@
-# SERA / ስራ — Your AI-Powered Work Command Center
+# SERA / ስራ
 
-> **ስራ** means *work* in Amharic. Manage tasks, appointments, notes, calendar, contacts, and system automation through natural language — directly from your terminal.
-
-```
-╔══════════════════════════════════════════════════╗
-║                                                  ║
-║   ███████╗███████╗██████╗  █████╗                ║
-║   ██╔════╝██╔════╝██╔══██╗██╔══██╗               ║
-║   ██╔████║██║   ██║██║   ██║ ███████║          ║
-║   ██║╚███║██║   ██║╚██╗ ██╔╝ ██╔══██║          ║
-║   ██║ ╚██║╚██████╔╝ ╚████╔╝  ██║  ██║          ║
-║   ╚═╝  ╚═╝ ╚═════╝   ╚═══╝   ╚═╝  ╚═╝          ║
-║                                                 ║
-║   Your AI-Powered Daily Command Center  v1.0.0  ║
-╚═════════════════════════════════════════════════╝
-```
+> **ስራ** means *work* in Amharic. Your AI-powered daily work command center — manage tasks, calendar, contacts, notes, and automate your computer through natural conversation, right from your terminal.
 
 ---
 
-## What is SERA?
-
-SERA is a CLI productivity assistant powered by your choice of AI model. You talk to it in plain English and it acts — creating tasks, scheduling appointments, running shell commands, querying your custom databases, and more. It runs entirely on your machine with full access to your filesystem, controlled by a granular permission system.
-
-**Supported AI providers:** OpenAI · Anthropic (Claude) · Ollama (local) · Groq
-
----
-
-## Installation
-
-**Prerequisites:** Node.js 18 or higher
+## Install
 
 ```bash
-# 1. Clone and enter the project
-git clone <repo-url>
-cd sera
-
-# 2. Install dependencies
-npm install
-
-# 3. Build
-npm run build
-
-# 4. Install globally
-npm install -g .
+npm install -g @menasehk/sera
 ```
 
-After installation, run `sera` from any directory.
-
----
-
-## Quick Start
+Then run setup once to connect your AI provider:
 
 ```bash
-sera setup      # Configure your AI provider and preferences (run this first)
-sera            # Launch interactive AI chat
-sera today      # See today's tasks and appointments
-sera how        # Full usage guide
+sera setup
 ```
 
 ---
 
-## Configuration
-
-Run `sera setup` to configure SERA interactively. Settings are saved to `~/.sera/config.json`.
+## What you can do
 
-| Setting | Description |
-|---|---|
-| **AI Provider** | OpenAI, Anthropic, Ollama, or Groq |
-| **Model** | e.g. `gpt-4o`, `claude-sonnet-4-20250514`, `llama3.1` |
-| **API Key** | Your provider API key (not needed for Ollama) |
-| **Storage** | JSON (default) or SQLite |
-| **Permissions** | How strictly to ask before running tools |
+Just open SERA and talk to it naturally. No special syntax needed.
 
 ```bash
-sera config           # View current settings
-sera config --reset   # Reset and re-run setup
+sera        # open and start chatting
 ```
 
----
-
-## Commands
-
-### Core
-
-| Command | Description |
-|---|---|
-| `sera` | Start interactive AI chat session |
-| `sera setup` | Run the interactive setup wizard |
-| `sera today` | Today's summary: tasks, appointments, overdue items |
-| `sera how` | Full usage guide with examples |
-
-### Tasks
-
-```bash
-sera add "Fix the login bug"                    # Quick-add (AI infers priority)
-sera add "Submit report" -p high -d friday      # With priority and due date
-sera done "Fix the login bug"                   # Mark done by name
-sera tasks                                      # View active tasks
-sera tasks --all                                # Include done & cancelled
-sera tasks --priority urgent                    # Filter by priority
-sera tasks --status in_progress                 # Filter by status
+```
+"Show my tasks for today"
+"Add a meeting tomorrow at 2pm with the design team"
+"Remind me to take my meds at 8pm"
+"I finished the login bug fix, mark it done"
+"Add Sarah Connor to my contacts, phone 555-0123"
+"What do I have on Friday?"
+"Remember that I prefer short responses"
+"Create a collection to track my expenses"
+"Show all expenses over $50 this month"
 ```
 
-**Priority levels:** `low` · `medium` · `high` · `urgent`
+SERA figures out what you mean and does it — including creating tasks, scheduling calendar events, saving contacts, running shell commands, reading files, and more.
 
-**In chat:**
-```
-"Mark all overdue tasks as cancelled"
-"Show me everything due this week"
-"What's still in progress?"
-```
+---
 
-### Appointments & Reminders
+## Quick commands
 
 ```bash
-sera cal                       # Upcoming appointments (next 7 days)
-sera cal --days 30             # Next 30 days
-sera remind 30 "Take meds"     # Desktop notification in 30 minutes
+sera                            # Start chatting with your AI
+sera setup                      # First-time setup (AI provider, API key, preferences)
+sera today                      # Today's tasks and appointments at a glance
+sera tasks                      # View all active tasks
+sera add "Buy groceries" -p low # Quick-add a task
+sera done "Buy groceries"       # Mark a task done
+sera cal                        # Upcoming appointments
+sera remind 15 "Stand up call"  # Desktop notification in 15 minutes
+sera note "Great idea I had"    # Save a quick note
+sera notes                      # View all notes
+sera memory                     # See what SERA remembers about you
+sera daemon start               # Run in the background (notifications when not open)
+sera daemon install             # Auto-start at login
+sera export                     # Back up all your data
 ```
 
-**In chat:**
-```
-"Add dentist appointment next Tuesday 2pm"
-"Reschedule my 3pm meeting to 4:30pm"
-"Remind me to call mom at 6pm"
-"What do I have this week?"
-```
+---
 
-### Notes
+## Supported AI providers
 
-```bash
-sera note "Buy oat milk"                  # Quick capture
-sera note "Meeting notes" -t work,q2      # With tags
-sera notes                                # View all notes
-```
+| Provider | Models |
+|---|---|
+| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-4-turbo, … |
+| **Anthropic** | claude-opus-4, claude-sonnet-4, … |
+| **Ollama** | llama3.1, mistral, gemma3 (runs locally, free) |
+| **Groq** | llama-3.3-70b, mixtral, … |
 
-**In chat:**
-```
-"Search my notes for anything about the Q2 launch"
-"Summarise my work notes from this week"
-```
+Run `sera setup` to choose your provider and paste in your API key. For Ollama no API key is needed.
 
-### Custom Database Collections
+---
 
-SERA can create and manage custom data collections for anything you want to track — expenses, contacts, gym logs, medications, habits, reading lists, and more.
+## AI Memory
 
-```bash
-sera db                          # List all collections
-sera db --show expenses          # View records in a collection
-sera db --schema expenses        # View the schema (fields and types)
-```
+SERA remembers things about you across sessions automatically — no prompting needed. Just chat normally.
 
-**In chat:**
 ```
-"Create a collection to track my expenses with: amount, category, description, date"
-"Add an expense: $45 lunch, category: food"
-"Show all expenses over $100 this month"
-"Add a 'notes' field to my expenses collection"
-"Create a contacts table: name, email, phone, company"
-"Delete the old habits collection"
-"Back up all my data"
+"My name is Kassu and I live in Helsinki"
+"I prefer bullet points in answers"
+"I'm working on a mobile app called Fana"
 ```
 
-**Field types:** `string` · `number` · `boolean` · `date` · `json`
-
-### AI Memory
-
-SERA remembers facts about you across sessions — name, timezone, preferences, work context, goals, and more. No prompting needed; it picks things up naturally from your conversations.
+Next time you open SERA it already knows all of this. View or clear memories any time:
 
 ```bash
-sera memory                        # View all stored memories
-sera memory --category work        # Filter by category
-sera memory --forget "timezone"    # Delete a specific memory
-sera memory --forget-all           # Clear everything
+sera memory                       # See everything SERA remembers
+sera memory --forget "timezone"   # Remove one memory
+sera memory --forget-all          # Start fresh
 ```
 
-**In chat:**
-```
-"Remember that I prefer concise answers"
-"My timezone is CET"
-"Forget that I work at Acme"
-```
-**Slash command (interactive mode):** `/memory`
-
-**Categories:** `personal` · `work` · `preferences` · `health` · `goals` · `context`
+Or type `/memory` while chatting.
 
-### Calendar & Contacts
+---
 
-SERA can add events to your calendar and contacts to your address book directly from chat.
+## Calendar & Contacts
 
-**macOS** — uses Calendar.app and Contacts.app natively (no extra setup).
-**Other platforms** — creates an `.ics` or `.vcf` file and opens it with your default app.
+On macOS SERA talks directly to Calendar.app and Contacts.app. On other platforms it creates `.ics` / `.vcf` files that open in whatever app you use.
 
 ```
-"Add a dentist appointment on Friday at 3pm"
-"Create an event: Team standup every Monday 9am"
-"Add John Smith to my contacts, phone 555-1234, email john@acme.com"
+"Add dentist appointment Friday 3pm, set a 30 minute reminder"
+"Add John Smith to my contacts, email john@acme.com, phone 555-1234"
 "Look up Alice in my contacts"
-"Add this to Google Calendar: product launch party, Saturday 7pm"
+"Put this on my Google Calendar: team lunch, Thursday noon"
 ```
 
-SERA will always ask your permission before touching your calendar or contacts.
+SERA always asks your permission before touching your calendar or contacts.
 
-### Background Daemon
-
-The daemon runs quietly in the background and sends desktop notifications so you never miss anything — even when SERA isn't open.
-
-```bash
-sera daemon start      # Start the background monitor
-sera daemon stop       # Stop it
-sera daemon restart    # Restart
-sera daemon status     # Is it running?
-sera daemon logs       # View recent log output
-sera daemon install    # Auto-start at login (launchd on macOS, systemd on Linux)
-```
+---
 
-**What the daemon monitors:**
-- Task overdue alerts — fires the moment a task deadline passes
-- Appointment reminders — 15 minutes before + when it starts
-- Morning briefing — 9 AM summary of the day's tasks and appointments
+## Background daemon
 
-### Backup & Export
+Keep SERA running silently in the background so you get notified even when the app is closed.
 
 ```bash
-sera export                          # Export all data → ~/sera-backup-<date>.json
-sera export -o ~/my-backup.json      # Export to a specific path
-sera import ~/my-backup.json         # Restore from a backup file
+sera daemon start      # Start background monitoring
+sera daemon install    # Auto-start every time you log in
+sera daemon status     # Check if it's running
+sera daemon stop       # Turn it off
 ```
 
-### System Automation (in chat)
-
-SERA can run shell commands, read/write files, and interact with your OS — subject to your permission settings.
-
-```
-"Run my backup script at ~/scripts/backup.sh"
-"List all PDF files in my Downloads folder"
-"Create a folder called Projects on my Desktop"
-"Open github.com in my browser"
-"What's my current git branch?"
-"Copy 'hello world' to my clipboard"
-"Show me system memory usage"
-```
-
----
-
-## In-Chat Slash Commands
-
-While in an interactive session (`sera`), these commands are available:
-
-| Command | Description |
-|---|---|
-| `/help` | Show this list |
-| `/guide` | Full usage guide with examples |
-| `/clear` | Clear the conversation and screen |
-| `/history` | Recent chat messages |
-| `/tools` | All available AI tools by category and risk level |
-| `/perms` | Saved permission rules |
-| `/config` | Current configuration |
-| `/db` | Quick view of all custom collections |
-| `/memory` | View stored memories about you |
-| `/tokens` | Current conversation message count |
-| `/quit` | Exit SERA |
+The daemon sends desktop notifications for overdue tasks, upcoming appointments (15 min warning + at start time), and a 9 AM morning briefing.
 
 ---
 
 ## Permissions
 
-SERA asks for confirmation before running tools that touch your system. You control how strict this is.
-
-**Permission levels** (set during `sera setup`):
+SERA asks before doing anything that touches your system. You choose how strict:
 
-- `ask` — prompt for every tool call *(most secure)*
-- `auto` — auto-approve low-risk tools, ask for high-risk
-- `allow` — allow everything without asking *(fastest)*
+- `ask` — confirm every action
+- `auto` — auto-allow safe actions, ask for risky ones
+- `allow` — allow everything
 
-When prompted, you can choose:
-- **Allow once** — allow this single call
-- **Always allow** — save a permanent rule for this tool
-- **Allow this session** — allow until you exit
-- **Deny** / **Deny always**
-
-```bash
-sera perms              # View saved rules
-sera perms --clear      # Reset all rules
-```
+You can always allow or deny permanently per tool so you're never asked twice for the same thing.
 
 ---
 
-## Error Handling
-
-SERA gives clear, actionable error messages. For example, if your API key doesn't have access to a model:
-
-```
-  ✖  Project does not have access to model gpt-4-turbo  [model_not_found]
-
-  ◆  Run  sera setup  to pick a different model (e.g. gpt-4o-mini).
-```
-
-SERA also automatically retries on rate limits (429) and transient server errors (5xx) with exponential backoff, so temporary blips don't interrupt your workflow.
-
----
+## Your data
 
-## Data & Privacy
+Everything stays on your machine. No cloud sync, no tracking.
 
-All your data lives locally on your machine:
-
-| File | Contents |
+| File | What's in it |
 |---|---|
-| `~/.sera/config.json` | Configuration and permission rules |
-| `~/.sera/data.json` | Tasks, appointments, and notes |
-| `~/.sera/collections.json` | Custom database collections |
+| `~/.ai-daily-cli/config.json` | Your settings and API key |
+| `~/.ai-daily-cli/data.json` | Tasks, appointments, notes |
+| `~/.ai-daily-cli/memory.json` | Things SERA remembers about you |
+| `~/.ai-daily-cli/collections.json` | Custom data collections |
 
-Your data is never sent anywhere other than your chosen AI provider's API for chat completions. SERA does not phone home.
+The only outbound traffic is your conversation being sent to your chosen AI provider's API.
 
 ---
 
-## Development
-
-```bash
-npm run build            # Compile TypeScript → dist/
-npm run dev              # Run directly with ts-node (no build step)
-npm test                 # Run the test suite
-npm run test:watch       # Watch mode
-npm run test:coverage    # With coverage report
-```
-
-**Test suite covers:**
-- Shell command sanitization (safe commands + 14 blocked dangerous patterns)
-- Retry logic (rate limits, server errors, network failures, custom predicates)
-- AI provider response parsing (OpenAI + Anthropic, including tool calls)
-- Database CRUD, schema management, field validation, backup/restore
+## In-chat slash commands
 
-### Project Structure
+While chatting you can type these shortcuts:
 
-```
-src/
-├── index.ts              # CLI commands, UI rendering, interactive loop
-├── types.ts              # Shared TypeScript interfaces
-├── providers/            # AI provider adapters
-│   ├── openai.ts         # OpenAI & Groq (same API format)
-│   ├── anthropic.ts      # Anthropic Claude
-│   ├── ollama.ts         # Ollama (local models)
-│   └── index.ts          # Provider factory
-├── tools/                # AI-callable tools
-│   ├── shell.ts          # Shell command execution (with sanitization)
-│   ├── filesystem.ts     # File read/write/list/delete
-│   ├── browser.ts        # Open URL, web search
-│   ├── system.ts         # System info, datetime, clipboard
-│   ├── notification.ts   # Desktop notifications
-│   ├── tasks.ts          # Task, appointment & note tools
-│   ├── database.ts       # Custom collection manager + tools
-│   └── index.ts          # Tool registry
-├── managers/
-│   ├── conversation.ts   # Agentic AI loop with tool calling
-│   └── setup.ts          # Interactive setup wizard
-├── storage/              # Storage backends (JSON / SQLite)
-├── utils/
-│   ├── config.ts         # Config read/write
-│   ├── permissions.ts    # Permission prompt system
-│   ├── retry.ts          # Exponential backoff for API calls
-│   ├── sanitize.ts       # Shell command safety filter
-│   ├── errors.ts         # API error parsing & friendly messages
-│   └── logger.ts         # Debug logger
-└── __tests__/            # Jest test suite
-    ├── sanitize.test.ts
-    ├── retry.test.ts
-    ├── providers.test.ts
-    └── database.test.ts
-```
+| Command | What it does |
+|---|---|
+| `/help` | Show all slash commands |
+| `/memory` | View stored memories |
+| `/tools` | List all available AI tools |
+| `/history` | Recent messages |
+| `/perms` | Saved permission rules |
+| `/config` | Current configuration |
+| `/db` | Quick view of custom collections |
+| `/clear` | Clear conversation and screen |
+| `/quit` | Exit |
 
 ---
 
 ## License
 
-MIT
+MIT © tagcodi