clementine-agent 1.5.0 → 1.6.0

package/README.md

@@ -20,43 +20,15 @@ Connects to Discord, Slack, Telegram, WhatsApp, and webhooks. Remembers everythi
 
 ## How it works
 
-Clementine is three layers stacked on a shared memory store:
-
-```
-                    ┌─────────────────────────────────────────┐
-                    │            Channel Layer                 │
-                    │  Discord · Slack · Telegram · WhatsApp   │
-                    │  Webhook API · Discord Guild Channels     │
-                    └────────────────┬────────────────────────┘
-                                     │
-                    ┌────────────────▼────────────────────────┐
-                    │           Gateway Layer                  │
-                    │  Router · Session Manager · Heartbeat    │
-                    │  Cron Scheduler · Unleashed Engine       │
-                    │  Notification Dispatch                   │
-                    └────────────────┬────────────────────────┘
-                                     │
-                    ┌────────────────▼────────────────────────┐
-                    │            Agent Layer                   │
-                    │  Claude Code SDK · Security Hooks        │
-                    │  Auto-Memory · Session Rotation          │
-                    │  Agent Profiles · Sub-Agent Teams        │
-                    │  Self-Improvement Loop                   │
-                    └────────────────┬────────────────────────┘
-                                     │
-                    ┌────────────────▼────────────────────────┐
-                    │          MCP Tool Server                 │
-                    │  30+ tools over stdio transport          │
-                    │  Memory · Tasks · Vault · Workspace      │
-                    └────────────────┬────────────────────────┘
-                                     │
-              ┌──────────────────────▼──────────────────────┐
-              │              Memory Store                    │
-              │  SQLite FTS5 · Salience Scoring · Decay     │
-              │  Episodic Memory · Wikilink Graph            │
-              │  FalkorDB Knowledge Graph · Procedural Skills│
-              │  Obsidian Vault (source of truth)            │
-              └─────────────────────────────────────────────┘
+Clementine is four layers over a shared memory store:
+
+```
+  Channels   →   Gateway     →   Agent           →   MCP tools  →   Memory
+  Discord        Router          Claude SDK          100+ tools     SQLite FTS5
+  Slack          Sessions        Security hooks      stdio          + vectors
+  Telegram       Heartbeats      Auto-memory                        Knowledge graph
+  WhatsApp       Cron + queues   Sub-agents                         Obsidian vault
+  Webhook        Delivery        Self-improve                       (source of truth)
 ```
 
 ### The memory loop
@@ -86,7 +58,7 @@ clementine dashboard      # open the web command center
 
 Already installed? Update in place with `clementine update`.
 
-### Troubleshooting
+### Install issues
 
 **`EACCES: permission denied` on `npm install -g`.** Your Node was installed system-wide (`/usr/local/lib/...`) and npm can't write there without sudo. Fix it once, permanently:
 
@@ -127,72 +99,34 @@ Handles system dependencies (redis, libomp, build tools), npm packages, TypeScri
 ~/.clementine/                     ← Data home (created on first run)
 ├── .env                           ← Configuration (created by setup wizard)
 ├── .sessions.json                 ← Session persistence
-├── .memory.db                     ← (legacy, unused — real DB is vault/.memory.db)
 ├── .clementine.pid                ← Daemon PID lock
-├── logs/
-│   ├── clementine.log             ← Daemon stdout/stderr
-│   └── audit.log                  ← Security audit trail
+├── logs/                          ← Daemon log + security audit log
 ├── cron/runs/                     ← Per-job JSONL run logs
-├── unleashed/                     ← Unleashed task progress & checkpoints
-│   └── <task>/
-│       ├── status.json            ← Current status, phase, timing
-│       └── progress.jsonl         ← Phase-by-phase event log
-├── self-improve/                  ← Self-improvement state
-│   ├── experiment-log.jsonl       ← Append-only experiment history
-│   ├── state.json                 ← Loop status, baseline metrics
-│   └── pending-changes/           ← Proposed diffs awaiting approval
-│       └── {experiment-id}.json
-└── vault/                         ← Obsidian-compatible vault
-    ├── 00-System/                 ← SOUL.md, MEMORY.md, HEARTBEAT.md, CRON.md
-    │   └── skills/                ← Procedural memory (auto-extracted from successful tasks)
-    ├── 01-Daily-Notes/            ← Auto-generated daily logs (YYYY-MM-DD.md)
-    ├── 02-People/                 ← Person notes (auto-created from conversations)
-    ├── 03-Projects/               ← Project notes
-    ├── 04-Topics/                 ← Knowledge topics
-    ├── 05-Tasks/                  ← TASKS.md master list ({T-NNN} IDs)
-    ├── 06-Templates/              ← Note templates
-    └── 07-Inbox/                  ← Quick captures
-
-src/                               ← Package code (wherever npm installed it)
-├── agent/
-│   ├── assistant.ts               ← PersonalAssistant — the brain
-│   ├── hooks.ts                   ← Security enforcement (3-tier model)
-│   ├── profiles.ts                ← Agent profile switching
-│   └── self-improve.ts            ← Nightly self-improvement loop engine
-├── channels/
-│   ├── discord.ts                 ← Discord.js adapter
-│   ├── slack.ts                   ← Slack Socket Mode adapter
-│   ├── telegram.ts                ← grammY adapter
-│   ├── whatsapp.ts                ← Twilio WhatsApp bridge
-│   └── webhook.ts                 ← HTTP webhook API
-├── gateway/
-│   ├── router.ts                  ← Message routing + session management
-│   ├── heartbeat.ts               ← HeartbeatScheduler + CronScheduler
-│   └── notifications.ts           ← Channel-agnostic notification fan-out
-├── memory/
-│   ├── store.ts                   ← SQLite FTS5 memory store + embedding backfill
-│   ├── embeddings.ts              ← TF-IDF embedding provider (local, 512-dim vectors)
-│   ├── search.ts                  ← Temporal decay, dedup, formatting
-│   ├── chunker.ts                 ← Vault file parser (## headers, frontmatter)
-│   ├── mmr.ts                     ← Maximal Marginal Relevance reranker
-│   ├── consolidation.ts           ← Evening consolidation engine (dedup, summarize, extract)
-│   ├── context-assembler.ts       ← Token-budgeted context slot filler
-│   └── graph-store.ts             ← FalkorDB knowledge graph layer (optional)
-├── tools/                         ← MCP stdio server (30+ tools, decomposed by domain)
-│   ├── mcp-server.ts             ← Server entry + registration
-│   ├── goal-tools.ts             ← Goal lifecycle tools
-│   ├── vault-tools.ts            ← Vault read/write/search tools
-│   ├── team-tools.ts             ← Team agent tools
-│   ├── session-tools.ts          ← Session management tools
-│   └── admin-tools.ts            ← System admin tools
-├── cli/
-│   ├── index.ts                   ← CLI commands (launch, stop, status, config, doctor)
-│   ├── setup.ts                   ← Interactive configuration wizard
-│   ├── dashboard.ts               ← Local web dashboard (command center)
-│   └── cron.ts                    ← Cron job runner and scheduler
-├── config.ts                      ← Paths, secrets, models (never pollutes process.env)
-├── types.ts                       ← Shared TypeScript interfaces
-└── index.ts                       ← Main entry point (multi-channel startup)
+├── unleashed/<task>/              ← Long-running task progress + status
+├── self-improve/                  ← Experiment log, state, pending proposals
+├── heartbeat/agents/<slug>/       ← Per-agent heartbeat state
+└── vault/                         ← Obsidian-compatible vault (see Vault section)
+    └── .memory.db                 ← SQLite FTS5 + vector index
+
+src/                               ← Package code (npm install location)
+├── agent/                         ← The brain: assistant, hooks, agent manager,
+│                                    proactive engine, self-improvement, advisor,
+│                                    skill extraction, complexity classifier, …
+├── channels/                      ← Discord, Slack, Telegram, WhatsApp, Webhook
+│                                    (+ per-agent Discord/Slack bot managers)
+├── gateway/                       ← Router, heartbeat schedulers, cron scheduler,
+│                                    delivery queue, failure monitor
+├── memory/                        ← SQLite FTS5 store, embeddings, MMR rerank,
+│                                    chunker, consolidation, graph store
+├── tools/                         ← MCP stdio server (100+ tools, by domain)
+├── cli/                           ← CLI entry, setup wizard, dashboard, cron runner
+├── brain/                         ← Ingestion pipeline + connectors
+├── analytics/                     ← Tool-usage telemetry
+├── security/, secrets/            ← Secret/credential helpers, hardening
+├── vault-migrations/              ← Versioned vault upgrades
+├── config.ts                      ← Paths, secrets, models (never leaks to env)
+├── types.ts                       ← Shared TypeScript types
+└── index.ts                       ← Multi-channel startup entry
 ```
 
 ### Code vs. data separation
@@ -220,143 +154,99 @@ Secrets never reach the Claude subprocess — `SAFE_ENV` filters credentials fro
 
 ### Memory architecture
 
-Three-layer retrieval merges full-text, vector, and recency signals into a single ranked context window:
-
-```
-User message
-    │
-    ├──▶ Layer 1: FTS5 (BM25 relevance)
-    ├──▶ Layer 2: TF-IDF vector similarity (cosine, threshold 0.15)
-    ├──▶ Layer 3: Recent chunks (time-windowed)
-    │
-    ▼
-┌──────────────────┐     ┌────────────────────┐
-│ MMR rerank       │────▶│ Context assembly    │──▶ System prompt
-│ + deduplication  │     │ (token-budgeted)    │
-└──────────────────┘     └────────────────────┘
-    │
-    │ salience boost on retrieval
-    ▼
-┌──────────────┐     ┌────────────────────┐
-│ Assistant     │────▶│ Auto-memory pass   │──▶ Vault writes
-│ responds     │     │ (background Sonnet) │    (MEMORY.md, people, tasks)
-└──────────────┘     └────────────────────┘
-    │
-    ▼
-┌──────────────┐
-│ Session       │──▶ Episodic chunk indexed
-│ summarization │    (sector='episodic')
-└──────────────┘
-    │
-    ▼
-┌──────────────────────┐
-│ Evening consolidation │──▶ Dedup (Jaccard) + topic summarization (LLM)
-│ + embedding rebuild   │    + principle extraction + TF-IDF vocab rebuild
-└──────────────────────┘
-    │
-    ▼
-┌──────────────┐
-│ Startup       │──▶ Temporal decay + pruning
-│ maintenance   │    (stale memories sink, old data trimmed)
-└──────────────┘
-```
-
-- **FTS5** — Full-text search with BM25 ranking, zero-cost, zero-latency
-- **TF-IDF embeddings** — Local 512-dim vectors (no API calls), vocabulary rebuilt during sync and evening consolidation, cosine similarity search over recent chunks
-- **MMR reranking** — Maximal Marginal Relevance via Jaccard similarity removes near-duplicates and promotes diversity in results
-- **Salience scoring** — Chunks gain score on retrieval, decay over time (7-day half-life). Formula: `log(access_count + 1) * 0.15 + recency_decay * 0.3`
+Retrieval merges three signals (FTS5 BM25, TF-IDF cosine, recency), reranks with MMR for diversity, and fills a token-budgeted context window. After each turn, a background Sonnet pass extracts memories to the vault. Sessions get summarized into episodic chunks. A nightly consolidation pass dedups, summarizes, and rebuilds the embedding vocabulary. Startup applies temporal decay and prunes old data.
+
+- **FTS5** — Full-text BM25 search, local, zero-cost
+- **TF-IDF embeddings** — Local 512-dim vectors (no API calls), rebuilt nightly
+- **MMR reranking** — Jaccard-based diversity, removes near-duplicates
+- **Salience** — Boost on retrieval, 7-day half-life decay
 - **Episodic memory** — Session summaries indexed as searchable chunks
-- **Wikilink graph** — `[[wikilinks]]` parsed and queryable for connection discovery
-- **Knowledge graph** — FalkorDB-powered typed relationships and multi-hop traversal (people → projects → topics). Visualized on a dark canvas in the dashboard with type legend and edge labels.
-- **Procedural skills** — Reusable how-to recipes auto-extracted from successful task executions. Stored as Markdown in `vault/00-System/skills/` and injected into cron jobs and unleashed tasks at runtime. Teach new skills manually via the dashboard Skills tab or let Clementine learn them from conversations.
-- **Evening consolidation** — Nightly pass: deduplicates chunks by Jaccard similarity (>70%), summarizes topic groups via LLM (Haiku), extracts recurring behavioral corrections into permanent rules, and rebuilds TF-IDF vocabulary + backfills embeddings
-- **Agent isolation** — Per-agent memory scoping via `agent_slug` column. Soft mode (default) boosts matching agent chunks 1.4x; strict mode filters to agent + global only
-- **Memory transparency** — Every memory write is logged to `memory_extractions` with user correction/dismissal support from the dashboard
-- **Temporal decay** — Applied on every startup; stale memories naturally sink
-- **Pruning** — Episodic chunks >90 days with salience <0.01 are removed; old transcripts, access logs, and orphaned references trimmed
-
-### MCP tools (30+)
-
-| Tool | Description |
-|------|-------------|
-| `memory_read` | Read vault notes (shortcuts: today, yesterday, memory, tasks, soul) |
-| `memory_write` | Write/append to vault (daily log, MEMORY.md sections, arbitrary notes) |
-| `memory_search` | FTS5 full-text search across all vault notes |
-| `memory_recall` | Combined FTS5 + recency search with salience boost |
-| `memory_connections` | Query the wikilink graph for a note |
-| `memory_timeline` | Chronological view of vault changes by date range |
-| `transcript_search` | Search past conversation transcripts |
-| `note_create` | Create notes (person, project, topic, task, inbox) |
-| `note_take` | Quick timestamped capture to daily log |
-| `daily_note` | Create or read today's daily note |
-| `task_list` | List tasks with status/project filters |
-| `task_add` | Add tasks with priority, due dates, projects |
-| `task_update` | Update task status (supports recurring tasks) |
-| `vault_stats` | Dashboard of vault health and activity |
-| `rss_fetch` | Fetch and parse RSS/Atom feeds |
-| `github_prs` | Check GitHub PRs (review-requested + authored) |
-| `browser_screenshot` | Take screenshots via Kernel cloud browser |
-| `set_timer` | Set short-term reminders (notifies via active channels) |
-| `outlook_inbox` | Read recent emails from Outlook inbox |
-| `outlook_search` | Search Outlook emails by query |
-| `outlook_calendar` | View upcoming calendar events |
-| `outlook_draft` | Create an email draft in Outlook |
-| `outlook_send` | Send an email from Outlook (Tier 3, requires approval) |
-| `discord_channel_send` | Post messages to any Discord text channel by ID |
-| `workspace_config` | Add, remove, or list workspace directories at runtime |
-| `workspace_list` | Scan workspace directories for local project roots |
-| `workspace_info` | Read a project's README, CLAUDE.md, manifest, and directory tree |
-| `add_cron_job` | Create scheduled tasks (supports standard and unleashed mode, project context) |
-| `self_restart` | Restart the daemon (for self-updates and config changes) |
-| `analyze_image` | Analyze images with vision capabilities |
-| `memory_report` | Generate a transparency report of all memory extractions |
-| `memory_correct` | Correct or dismiss a previously extracted memory |
-| `feedback_log` | Log user feedback on responses |
-| `feedback_report` | View feedback history and patterns |
-| `team_list` | List all team agents with status, channel, and capabilities |
-| `team_message` | Send a message to another agent (permission-scoped, synchronous) |
-| `create_agent` | Create a new agent with name, role, tools, project, and team connections |
-| `self_improve_status` | Check self-improvement state, pending approvals, experiment history |
-| `self_improve_run` | Trigger a self-improvement analysis cycle |
+- **Wikilink + knowledge graph** — `[[wikilinks]]` graph + optional FalkorDB typed relationships (visualized in dashboard)
+- **Procedural skills** — Auto-extracted from successful tasks, stored at `vault/00-System/skills/`, injected into future runs
+- **Evening consolidation** — Nightly: Jaccard dedup (>70%), topic summarization (Haiku), behavioral-rule extraction, vocabulary rebuild
+- **Agent isolation** — Per-agent scoping via `agent_slug`; soft (1.4× boost) or strict modes
+- **Transparency** — Every write logged to `memory_extractions`; correct/dismiss from dashboard
+- **Pruning** — Episodic >90 days with salience <0.01 removed; old transcripts and access logs trimmed
+
+### MCP tools (100+)
+
+Tools are grouped by domain. Run `clementine tools` to see the live list.
+
+| Group | Examples |
+|-------|----------|
+| **Memory** | `memory_read`, `memory_write`, `memory_search`, `memory_recall`, `memory_connections`, `memory_timeline`, `memory_consolidate`, `memory_correct`, `memory_report`, `memory_graph_*` |
+| **Vault & notes** | `note_create`, `note_take`, `daily_note`, `task_list`, `task_add`, `task_update`, `vault_stats`, `transcript_search` |
+| **Workspace** | `workspace_config`, `workspace_list`, `workspace_info` |
+| **External** | `web_search`, `rss_fetch`, `github_prs`, `browser_screenshot`, `analyze_image`, `outlook_*`, `sf_*` (Salesforce), `discord_channel_*` |
+| **Agents & teams** | `create_agent`, `update_agent`, `delete_agent`, `team_list`, `team_message`, `team_request`, `team_status`, `delegate_task`, `wake_agent` |
+| **Goals & background** | `goal_create`, `goal_update`, `goal_work`, `start_background_task`, `get_background_task`, `discover_work` |
+| **Cron & workflows** | `add_cron_job`, `cron_list`, `cron_run_history`, `trigger_cron_job`, `workflow_create`, `workflow_run`, `workflow_save`, `workflow_*` |
+| **Self-improvement** | `self_improve_run`, `self_improve_status`, `self_edit_source`, `prompt_override_*`, `decision_reflection`, `feedback_log`, `feedback_report` |
+| **System** | `self_restart`, `self_update`, `set_timer`, `env_set`, `allow_tool`, `setup_integration`, `auth_profile_status` |
 
 ---
 
 ## CLI reference
 
+Run `clementine --help` to see everything; the most common commands:
+
+**Daemon**
+```
+clementine launch [-f] [--install]   Start daemon (foreground / macOS login service)
+clementine stop | restart | rebuild  Lifecycle controls
+clementine status                    PID, uptime, active channels
+clementine update [--dry-run]        Pull latest, rebuild, reinstall (preserves config)
+clementine doctor [--fix]            Verify (and optionally repair) config and vault
+clementine dashboard                 Open the web command center (localhost:3030)
+clementine tools                     List available MCP tools, plugins, and channels
+```
+
+**Config & secrets**
 ```
-clementine launch              Start as background daemon (default)
-clementine launch -f           Start in foreground (debug mode)
-clementine launch --install    Install as macOS login service (survives reboots)
-clementine stop                Stop the daemon
-clementine restart             Stop + relaunch
-clementine rebuild             Build + restart daemon + dashboard in one step
-clementine status              Show PID, uptime, active channels
-clementine update              Pull latest, rebuild, reinstall (preserves config)
-clementine update --dry-run    Preview update without making changes
-clementine doctor              Verify configuration and vault health
-clementine doctor --fix        Auto-fix common issues (redis, sqlite, FalkorDB)
-clementine dashboard           Open the local web command center (localhost:3030)
-clementine tools               List available MCP tools, plugins, and channels
-clementine config setup        Interactive configuration wizard
-clementine config set KEY VAL  Set a single config value
-clementine config get KEY      Read a config value
-clementine config edit         Open .env in your editor ($EDITOR)
-clementine memory search <q>   Search memory from the terminal (FTS5)
-clementine projects list       Show all linked projects
-clementine projects add <path> Link a project directory (-d desc, -k keywords)
-clementine projects remove <p> Unlink a project directory
-clementine cron list           List all cron jobs and last run status
-clementine cron run <job>      Run a specific cron job
-clementine cron run-due        Run all due jobs (for OS scheduler)
-clementine cron runs [job]     View run history (with retry/error details)
-clementine cron install        Install OS-level scheduler (launchd/crontab)
-clementine cron uninstall      Remove OS-level scheduler
-clementine heartbeat           Run a one-shot heartbeat check
-clementine self-improve status Show self-improvement state and baseline metrics
-clementine self-improve run    Trigger a self-improvement cycle
-clementine self-improve history Show experiment history
-clementine self-improve apply <id>  Approve and apply a pending change
-clementine --help              Show all commands
+clementine setup                     Interactive setup wizard
+clementine config set KEY VAL        Write to ~/.clementine/.env
+clementine config get KEY
+clementine config list               Show all overrides
+clementine config edit               Open .env in $EDITOR
+clementine login | auth              Authenticate Claude Code / OAuth providers
+```
+
+**Chat & memory**
+```
+clementine chat                      Interactive REPL
+clementine memory status             Index size, recent activity
+clementine memory search <q>         FTS5 search
+clementine memory dedup | reembed    Maintenance
+clementine brain digest              Run the brain digest pipeline
+```
+
+**Projects & agents**
+```
+clementine projects list | add <p> | remove <p>
+clementine agent list | new <slug> | show <slug>
+clementine skills list | pending | approve <name> | reject <name> | search <q>
+```
+
+**Cron, workflows, heartbeat**
+```
+clementine cron list | run <job> | run-due | runs [job]
+clementine cron add <name> <schedule> <prompt>
+clementine cron install | uninstall  OS-level scheduler (launchd / crontab)
+clementine workflow list | run <name>
+clementine heartbeat                 One-shot heartbeat tick
+```
+
+**Self-improvement**
+```
+clementine self-improve status | run | history | pending | apply <id>
+```
+
+**Diagnostics**
+```
+clementine advisor | rules           Live advisor rules
+clementine mode <mode>               Switch operating mode
+clementine analytics | tool-usage    Telemetry on tool usage
+clementine ingest seed <path> | run <slug> | list
 ```
 
 ### Daemon behavior
@@ -369,27 +259,17 @@ clementine --help              Show all commands
 
 ### Dashboard
 
-Run `clementine dashboard` to open a local web command center at `http://localhost:3030`. The dashboard provides:
-
-- **Metrics** — Time saved estimates, session counts, cron job stats, memory size
-- **Chat** — Talk to your assistant directly from the browser
-- **Memory search** — Full-text search across all vault notes (FTS5)
-- **Scheduled tasks** — Create, edit, run, toggle, and delete cron jobs with a visual schedule builder
-- **Project-aware cron** — Assign cron jobs to specific project directories
-- **Unleashed mode** — Create long-running autonomous tasks, monitor phase progress, cancel running tasks
-- **Projects** — Browse all discovered workspace projects with type, description, and tool badges
-- **Live status** — Daemon health, LaunchAgent status, active channels
-- **Sessions** — View and manage active conversation sessions
-- **The Office** — Visual agent management with desk-station cards showing status, avatars, channels, and tools
-- **Hiring Interview** — Click "Hire a New Employee" and Clementine interviews you to build the agent config conversationally
-- **Manual Agent Setup** — Form modal with project dropdown (auto-populated from discovered projects) and categorized tool browser with checkboxes
-- **Auto-restart** — Daemon restarts automatically when the agent roster changes (from either the interview or manual path)
-- **Training Center** — Click any agent to open a 4-tab detail view: Schedule (per-agent cron jobs), Skills (per-agent procedural memory), Execution Traces (tool call history with timing), and Prompt Lab (test prompts against the agent)
-- **Skills** — Teach, view, and delete procedural skills. Skills are auto-extracted from successful tasks or taught manually via the dashboard.
-- **Self-Improvement** — View experiment history, approve/deny pending proposals, monitor baseline metrics
-- **Settings** — API key management, model config, custom env vars, service status
-
-No extra dependencies — the dashboard uses Express, which is already installed.
+Run `clementine dashboard` to open the command center at `http://localhost:3030`. Five pages:
+
+| Page | What's there |
+|------|--------------|
+| **Home** | Chat with Clementine, today's briefing, recent activity, KPIs |
+| **Build** | Workflows, scheduled tasks (visual cron builder), skills, unleashed tasks |
+| **Team** | Agents (hire / edit / let go), goals, delegations, decision-reflection reports |
+| **Brain** | Memory search (FTS5), knowledge graph, ingestion sources, vault health |
+| **Settings** | Channels, integrations, API keys, model config, env vars, service status |
+
+Cron jobs can be project-aware (assign a `work_dir`) and switched between standard and unleashed mode. The agent roster auto-restarts the daemon on changes. No extra deps — runs on Express.
 
 ---
 
@@ -475,13 +355,13 @@ clementine restart
 
 ## Models
 
-| Tier | Model Alias | Use case |
-|------|-------------|----------|
-| `haiku` | `haiku` (latest Haiku) | Lightweight tasks, cron noise filtering |
-| `sonnet` | `sonnet` (latest Sonnet) | Default conversation + auto-memory extraction |
-| `opus` | `opus` (latest Opus) | Available via config or agent profiles |
+| Tier | Use case |
+|------|----------|
+| `haiku` | Lightweight tasks, cron noise filtering |
+| `sonnet` | Default conversation + auto-memory extraction |
+| `opus` | Per-agent override or global default |
 
-Model aliases always resolve to the latest version via the Claude Code SDK. To pin a specific version, set `DEFAULT_MODEL_TIER` to a full model name (e.g. `claude-sonnet-4-6`).
+Aliases resolve to the latest version via the Claude Code SDK. To pin a specific version, set `DEFAULT_MODEL_TIER` to a full model name (e.g. `claude-sonnet-4-6`). Each agent can override the model in its `agent.md` frontmatter.
 
 Change the default with `clementine config set DEFAULT_MODEL_TIER opus`, then `clementine restart`.
 
@@ -545,14 +425,12 @@ Clementine supports multi-agent teams — each agent gets its own Discord bot, c
 
 ### Creating agents
 
-Two paths to create a new agent:
+Open the **Team** page in the dashboard, then either:
 
-| Method | How |
-|--------|-----|
-| **Hiring interview** | Click "Hire a New Employee" in the dashboard (or an empty desk card). Clementine asks 3–5 questions about the agent's name, role, tools, project, and team connections, then calls `create_agent` automatically. |
-| **Manual setup** | Click "Manual Setup" to open a form with project dropdown, categorized tool browser, model selector, and team connection fields. |
+- **Hire a New Employee** — Clementine interviews you (3–5 questions: name, role, tools, project, team connections) and calls `create_agent`.
+- **Manual Setup** — form with project dropdown, categorized tool browser, model selector, and team-connection fields.
 
-Both paths trigger an automatic daemon restart when the new agent is detected.
+Both paths auto-restart the daemon when the new agent appears.
 
 ### Agent configuration
 
@@ -577,14 +455,6 @@ Agents communicate via the `team_message` tool. Messages are permission-scoped
 
 Messages are delivered synchronously: the sender waits for the recipient's response. Conversation depth is tracked to prevent infinite loops.
 
-### The Office (dashboard)
-
-The dashboard's "The Office" page shows each agent as an animated desk station with:
-- Live status indicator (online / connecting / error / offline)
-- Discord bot avatar (auto-pulled) or initial
-- Channel assignment, model badge, project badge, tool count
-- Edit and "Let Go" (delete) actions
-
 ### Decision-loop reflection
 
 Each agent's autonomous decisions are recorded to a proactive ledger (action chosen, signal source, eventual outcome). The `decision_reflection` MCP tool reads that ledger, computes per-action success rates, and surfaces calibration patterns:
@@ -657,20 +527,14 @@ The dashboard provides a visual schedule builder with dropdowns for frequency (d
 
 ## Unleashed mode
 
-For tasks that take hours — codebase refactors, research projects, content generation pipelines — unleashed mode runs autonomously with phased execution and checkpointing.
-
-```
-Phase 1 (75 turns) ──▶ Checkpoint ──▶ Phase 2 (75 turns) ──▶ Checkpoint ──▶ ...
-     │                      │                │                      │
-     └─ Session resume ─────┘                └─ Session resume ─────┘
-```
+For tasks that take hours — codebase refactors, research projects, content pipelines — unleashed mode runs autonomously in phases with session resumption between each.
 
 ### How it works
 
-1. The task runs in phases (default 75 turns per phase)
-2. Between phases, the SDK session is **resumed** — the agent keeps its full conversation history
-3. Progress is saved to `~/.clementine/unleashed/<task>/` (JSONL log + status file)
-4. The agent can spawn sub-agents for parallel work streams
+1. Runs in phases (default 75 turns each)
+2. Between phases, the SDK session is **resumed** — full conversation history preserved
+3. Progress saved to `~/.clementine/unleashed/<task>/` (status + JSONL log)
+4. Can spawn sub-agents for parallel work
 5. Cancel anytime via the dashboard or by touching a `CANCEL` file
 
 ### Safety guardrails
@@ -719,19 +583,7 @@ Progress is also logged to `~/.clementine/unleashed/<task>/progress.jsonl` for d
 
 ## Self-improvement
 
-Clementine can autonomously improve herself using an iterative loop inspired by Karpathy's autoresearch pattern: **gather data, diagnose weaknesses, hypothesize a fix, evaluate the fix, and propose the change for approval**.
-
-```
-  ┌──────────┐    ┌──────────┐    ┌─────────────┐    ┌──────────┐    ┌──────────┐
-  │  Gather  │───▶│ Diagnose │───▶│ Hypothesize │───▶│ Evaluate │───▶│   Gate   │
-  │ feedback │    │ weakness │    │  a change   │    │ LLM judge│    │ approve? │
-  │ cron logs│    │ patterns │    │  (minimal)  │    │  0-10    │    │          │
-  └──────────┘    └──────────┘    └─────────────┘    └──────────┘    └──────────┘
-       │                                                                   │
-       │              ┌──────────────────────────────────────┐             │
-       └──────────────│  Repeat until plateau or time limit  │◀────────────┘
-                      └──────────────────────────────────────┘
-```
+Clementine runs an iterative self-improvement loop: **gather data → diagnose weakness → hypothesize a fix → LLM-judge it → gate for human approval**. Repeats until plateau or time limit.
 
 ### What it targets
 
@@ -800,6 +652,21 @@ After the loop completes, memory maintenance runs automatically (temporal decay
 
 The vault is an Obsidian-compatible folder of Markdown files with YAML frontmatter, `[[wikilinks]]`, and `#tags`. Open `~/.clementine/vault/` in Obsidian to browse your assistant's memory visually.
 
+Folder structure under `~/.clementine/vault/`:
+
+```
+00-System/         SOUL.md, MEMORY.md, HEARTBEAT.md, CRON.md, AGENTS.md
+                   agents/<slug>/agent.md   ← per-agent config
+                   skills/                  ← procedural skills
+01-Daily-Notes/    YYYY-MM-DD.md auto-generated daily logs
+02-People/         Person notes (auto-created from conversations)
+03-Projects/       Project notes
+04-Topics/         Knowledge topics
+05-Tasks/          TASKS.md master list with {T-NNN} IDs
+06-Templates/      Note templates
+07-Inbox/          Quick captures
+```
+
 Key system files:
 
 | File | Purpose |
@@ -807,7 +674,8 @@ Key system files:
 | `SOUL.md` | Core personality and behavioral instructions |
 | `MEMORY.md` | Auto-extracted facts, preferences, people context |
 | `HEARTBEAT.md` | Autonomous check-in configuration |
-| `CRON.md` | Scheduled task definitions (cron syntax) |
+| `CRON.md` | Scheduled task definitions |
+| `AGENTS.md` | Master roster of agents |
 | `TASKS.md` | Master task list with `{T-NNN}` IDs |
 
 ---

package/dist/cli/browser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Clementine CLI — browser-harness integration (Phase 1, beta).
+ *
+ * Subcommands:
+ *   clementine browser status   — show install / enable / CDP state
+ *   clementine browser install  — set up Python venv + clone harness
+ *   clementine browser enable   — register MCP server in mcp-servers.json
+ *   clementine browser disable  — remove the MCP entry (keeps files)
+ *
+ * Safety:
+ *   - All subcommands fail soft. Missing Python or unsupported OS just prints
+ *     a clear message and exits 0 (or 1 for hard errors); the daemon never
+ *     auto-installs anything.
+ *   - Enabling only writes a single entry to ~/.clementine/mcp-servers.json
+ *     that mcp-bridge.ts already understands. No changes to assistant.ts.
+ *   - If Python or the MCP server fail at runtime, the SDK logs the error and
+ *     the rest of Clementine keeps running (every other MCP server is
+ *     unaffected).
+ */
+export declare function cmdBrowserStatus(): Promise<void>;
+export declare function cmdBrowserInstall(): Promise<void>;
+export declare function cmdBrowserEnable(): Promise<void>;
+export declare function cmdBrowserDisable(): Promise<void>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/cli/browser.js

@@ -0,0 +1,224 @@
+/**
+ * Clementine CLI — browser-harness integration (Phase 1, beta).
+ *
+ * Subcommands:
+ *   clementine browser status   — show install / enable / CDP state
+ *   clementine browser install  — set up Python venv + clone harness
+ *   clementine browser enable   — register MCP server in mcp-servers.json
+ *   clementine browser disable  — remove the MCP entry (keeps files)
+ *
+ * Safety:
+ *   - All subcommands fail soft. Missing Python or unsupported OS just prints
+ *     a clear message and exits 0 (or 1 for hard errors); the daemon never
+ *     auto-installs anything.
+ *   - Enabling only writes a single entry to ~/.clementine/mcp-servers.json
+ *     that mcp-bridge.ts already understands. No changes to assistant.ts.
+ *   - If Python or the MCP server fail at runtime, the SDK logs the error and
+ *     the rest of Clementine keeps running (every other MCP server is
+ *     unaffected).
+ */
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[0;90m';
+const GREEN = '\x1b[0;32m';
+const YELLOW = '\x1b[1;33m';
+const RED = '\x1b[0;31m';
+const CYAN = '\x1b[0;36m';
+const RESET = '\x1b[0m';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const BASE_DIR = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const MCP_SCRIPT = path.join(PACKAGE_ROOT, 'vendor', 'browser-harness-mcp', 'server.py');
+const HARNESS_HOME = path.join(BASE_DIR, 'browser-harness');
+const VENV_DIR = path.join(BASE_DIR, 'browser-harness-mcp-venv');
+const VENV_PYTHON = path.join(VENV_DIR, 'bin', 'python3');
+const MCP_SERVERS_FILE = path.join(BASE_DIR, 'mcp-servers.json');
+const HARNESS_REPO = 'https://github.com/browser-use/browser-harness.git';
+const SERVER_NAME = 'browser-harness';
+function commandExists(cmd) {
+    const result = spawnSync('which', [cmd], { stdio: 'pipe' });
+    return result.status === 0;
+}
+function pythonVersion() {
+    try {
+        const out = execSync('python3 --version', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return out.trim();
+    }
+    catch {
+        return null;
+    }
+}
+function loadMcpServers() {
+    if (!existsSync(MCP_SERVERS_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(MCP_SERVERS_FILE, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveMcpServers(servers) {
+    if (!existsSync(BASE_DIR))
+        mkdirSync(BASE_DIR, { recursive: true });
+    writeFileSync(MCP_SERVERS_FILE, JSON.stringify(servers, null, 2) + '\n');
+}
+export async function cmdBrowserStatus() {
+    const py = pythonVersion();
+    const mcpScriptOk = existsSync(MCP_SCRIPT);
+    const venvOk = existsSync(VENV_PYTHON);
+    const harnessOk = existsSync(path.join(HARNESS_HOME, 'src'));
+    const servers = loadMcpServers();
+    const enabled = Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+    console.log();
+    console.log(`  ${BOLD}Browser Harness${RESET} ${DIM}(beta)${RESET}`);
+    console.log();
+    console.log(`  ${py ? GREEN + '✓' : RED + '✗'}${RESET} python3            ${DIM}${py ?? 'not found'}${RESET}`);
+    console.log(`  ${mcpScriptOk ? GREEN + '✓' : RED + '✗'}${RESET} MCP wrapper       ${DIM}${MCP_SCRIPT}${RESET}`);
+    console.log(`  ${venvOk ? GREEN + '✓' : YELLOW + '○'}${RESET} venv installed    ${DIM}${VENV_DIR}${RESET}`);
+    console.log(`  ${harnessOk ? GREEN + '✓' : YELLOW + '○'}${RESET} harness cloned    ${DIM}${HARNESS_HOME}${RESET}`);
+    console.log(`  ${enabled ? GREEN + '✓' : DIM + '○'}${RESET} MCP entry         ${DIM}${enabled ? 'enabled' : 'disabled'} in mcp-servers.json${RESET}`);
+    console.log();
+    if (!py) {
+        console.log(`  ${YELLOW}Install Python 3.10+ first:${RESET}`);
+        console.log(`    ${CYAN}brew install python@3.12${RESET}`);
+        console.log();
+    }
+    else if (!venvOk || !harnessOk) {
+        console.log(`  Next: ${BOLD}clementine browser install${RESET}`);
+        console.log();
+    }
+    else if (!enabled) {
+        console.log(`  Next: ${BOLD}clementine browser enable${RESET}`);
+        console.log();
+    }
+    else {
+        console.log(`  ${GREEN}Ready.${RESET} ${DIM}Restart the daemon to pick up changes: clementine restart${RESET}`);
+        console.log();
+    }
+}
+export async function cmdBrowserInstall() {
+    console.log();
+    console.log(`  ${BOLD}Installing browser-harness${RESET} ${DIM}(beta)${RESET}`);
+    console.log();
+    if (!pythonVersion()) {
+        console.error(`  ${RED}python3 not found.${RESET} Install Python 3.10+ first:`);
+        console.error(`    ${CYAN}brew install python@3.12${RESET}`);
+        console.error();
+        process.exit(1);
+    }
+    if (!existsSync(MCP_SCRIPT)) {
+        console.error(`  ${RED}MCP wrapper not found at:${RESET} ${MCP_SCRIPT}`);
+        console.error(`  ${DIM}This means the package was installed without vendor/ files. Reinstall:${RESET}`);
+        console.error(`    ${CYAN}npm install -g clementine-agent@latest${RESET}`);
+        process.exit(1);
+    }
+    if (!existsSync(BASE_DIR))
+        mkdirSync(BASE_DIR, { recursive: true });
+    // Step 1: clone the harness if missing
+    if (!existsSync(HARNESS_HOME)) {
+        if (!commandExists('git')) {
+            console.error(`  ${RED}git not found.${RESET} Install git, then re-run.`);
+            process.exit(1);
+        }
+        console.log(`  ${DIM}→ cloning ${HARNESS_REPO}${RESET}`);
+        try {
+            execSync(`git clone --depth 1 ${HARNESS_REPO} "${HARNESS_HOME}"`, { stdio: 'inherit' });
+        }
+        catch {
+            console.error(`  ${RED}Clone failed.${RESET} Check network / git access and try again.`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log(`  ${GREEN}✓${RESET} harness already cloned at ${DIM}${HARNESS_HOME}${RESET}`);
+    }
+    // Step 2: create venv if missing
+    if (!existsSync(VENV_PYTHON)) {
+        console.log(`  ${DIM}→ creating venv at ${VENV_DIR}${RESET}`);
+        try {
+            execSync(`python3 -m venv "${VENV_DIR}"`, { stdio: 'inherit' });
+        }
+        catch {
+            console.error(`  ${RED}venv creation failed.${RESET}`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log(`  ${GREEN}✓${RESET} venv already exists`);
+    }
+    // Step 3: install MCP deps + harness deps
+    console.log(`  ${DIM}→ installing python deps (mcp, websockets, browser-harness)${RESET}`);
+    try {
+        execSync(`"${VENV_PYTHON}" -m pip install --upgrade pip --quiet`, { stdio: 'inherit' });
+        execSync(`"${VENV_PYTHON}" -m pip install --quiet "mcp>=1.0.0" "websockets>=12.0"`, { stdio: 'inherit' });
+        // Install harness deps from its pyproject.toml if present
+        const harnessPyproject = path.join(HARNESS_HOME, 'pyproject.toml');
+        if (existsSync(harnessPyproject)) {
+            execSync(`"${VENV_PYTHON}" -m pip install --quiet -e "${HARNESS_HOME}"`, { stdio: 'inherit' });
+        }
+    }
+    catch {
+        console.error(`  ${RED}pip install failed.${RESET} Inspect output above and re-run when fixed.`);
+        process.exit(1);
+    }
+    console.log();
+    console.log(`  ${GREEN}✓${RESET} Install complete.`);
+    console.log();
+    console.log(`  ${BOLD}Next steps:${RESET}`);
+    console.log(`  1. Enable Chrome remote debugging — open Chrome with:`);
+    console.log(`       ${CYAN}/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome \\${RESET}`);
+    console.log(`         ${CYAN}--remote-debugging-port=9222${RESET}`);
+    console.log(`  2. Enable the MCP server:  ${BOLD}clementine browser enable${RESET}`);
+    console.log(`  3. Restart the daemon:     ${BOLD}clementine restart${RESET}`);
+    console.log();
+}
+export async function cmdBrowserEnable() {
+    if (!existsSync(VENV_PYTHON) || !existsSync(MCP_SCRIPT)) {
+        console.error();
+        console.error(`  ${RED}Not installed yet.${RESET} Run ${BOLD}clementine browser install${RESET} first.`);
+        console.error();
+        process.exit(1);
+    }
+    const servers = loadMcpServers();
+    servers[SERVER_NAME] = {
+        type: 'stdio',
+        command: VENV_PYTHON,
+        args: [MCP_SCRIPT],
+        env: {
+            BROWSER_HARNESS_HOME: HARNESS_HOME,
+            BROWSER_CDP_URL: process.env.BROWSER_CDP_URL || 'ws://localhost:9222',
+        },
+        description: 'Drive the user\'s real Chrome via CDP (browser-use/browser-harness)',
+        enabled: true,
+        source: 'user',
+    };
+    saveMcpServers(servers);
+    console.log();
+    console.log(`  ${GREEN}✓${RESET} Registered ${BOLD}${SERVER_NAME}${RESET} in mcp-servers.json`);
+    console.log(`  ${DIM}Restart the daemon to pick up the change: clementine restart${RESET}`);
+    console.log();
+}
+export async function cmdBrowserDisable() {
+    const servers = loadMcpServers();
+    if (!Object.prototype.hasOwnProperty.call(servers, SERVER_NAME)) {
+        console.log();
+        console.log(`  ${DIM}${SERVER_NAME} is already disabled.${RESET}`);
+        console.log();
+        return;
+    }
+    delete servers[SERVER_NAME];
+    saveMcpServers(servers);
+    console.log();
+    console.log(`  ${GREEN}✓${RESET} Removed ${BOLD}${SERVER_NAME}${RESET} from mcp-servers.json`);
+    console.log(`  ${DIM}venv and harness clone are kept. To fully remove:${RESET}`);
+    console.log(`    ${CYAN}rm -rf "${VENV_DIR}" "${HARNESS_HOME}"${RESET}`);
+    console.log(`  ${DIM}Restart the daemon: clementine restart${RESET}`);
+    console.log();
+}
+//# sourceMappingURL=browser.js.map

package/dist/cli/index.js

@@ -24,6 +24,7 @@ import { cmdCronList, cmdCronRun, cmdCronRunDue, cmdCronRuns, cmdCronAdd, cmdCro
 import { cmdDashboard } from './dashboard.js';
 import { cmdChat } from './chat.js';
 import { cmdIngestSeed, cmdIngestRun, cmdIngestList, cmdIngestStatus } from './ingest.js';
+import { cmdBrowserStatus, cmdBrowserInstall, cmdBrowserEnable, cmdBrowserDisable } from './browser.js';
 import { isSensitiveEnvKey } from '../secrets/sensitivity.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -4549,5 +4550,25 @@ ingestCmd
     .command('status <slug>')
     .description('Show recent runs and metadata for a source')
     .action(cmdIngestStatus);
+// ── Browser harness (beta) ──────────────────────────────────────────
+const browserCmd = program
+    .command('browser')
+    .description('Browser harness — drive your real Chrome via CDP (beta, opt-in)');
+browserCmd
+    .command('status')
+    .description('Show install and enable state of the browser harness MCP')
+    .action(cmdBrowserStatus);
+browserCmd
+    .command('install')
+    .description('Clone browser-harness and install Python deps into a private venv')
+    .action(cmdBrowserInstall);
+browserCmd
+    .command('enable')
+    .description('Register the browser harness MCP server in mcp-servers.json')
+    .action(cmdBrowserEnable);
+browserCmd
+    .command('disable')
+    .description('Remove the browser harness MCP entry (keeps installed files)')
+    .action(cmdBrowserDisable);
 program.parse();
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",
@@ -86,6 +86,7 @@
     "dist/",
     "vault/",
     "scripts/",
+    "vendor/",
     "install.sh",
     "README.md",
     ".env.example"

package/vendor/browser-harness-mcp/README.md

@@ -0,0 +1,27 @@
+# Browser Harness MCP Bridge
+
+Stdio MCP server that wraps [browser-use/browser-harness](https://github.com/browser-use/browser-harness) so Clementine can drive your real Chrome via CDP.
+
+**Status:** Phase 1 plumbing — tools return `[stub]` placeholders until the harness primitives are wired in.
+
+## Setup
+
+```bash
+clementine browser install   # clone harness + install Python deps
+clementine browser enable    # register MCP server in ~/.clementine/mcp-servers.json
+clementine restart
+```
+
+To remove: `clementine browser disable` (the venv and harness clone are kept; delete `~/.clementine/browser-harness*` to fully remove).
+
+## Tools
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `browser_status` | 1 | Diagnostic: install state + CDP URL |
+| `browser_screenshot` | 1 | Capture active tab |
+| `browser_inspect` | 1 | Read page HTML or selector |
+| `browser_navigate` | 2 | Open a URL in connected Chrome |
+| `browser_run_python` | 3 | Execute Python in `agent-workspace/` (approval required) |
+
+Tier policies are enforced by Clementine's `src/agent/hooks.ts`. Tier 3 actions require explicit approval and run only with a per-domain allowlist (Phase 2).

package/vendor/browser-harness-mcp/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "clementine-browser-harness-mcp"
+version = "0.1.0"
+description = "MCP bridge between Clementine and browser-use/browser-harness"
+requires-python = ">=3.10"
+dependencies = [
+  "mcp>=1.0.0",
+  "websockets>=12.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

package/vendor/browser-harness-mcp/server.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Clementine ↔ browser-harness MCP bridge.
+
+Stdio MCP server that exposes browser-harness primitives to the Claude Agent
+SDK. Fails gracefully: if browser-harness or its deps aren't installed, the
+server still starts and every tool returns a clear "not installed" message
+so the rest of Clementine keeps working.
+
+Wire-up:
+  mcpServers in ~/.clementine/mcp-servers.json:
+    {
+      "browser-harness": {
+        "type": "stdio",
+        "command": "<venv>/bin/python3",
+        "args": ["<package>/vendor/browser-harness-mcp/server.py"],
+        "env": {
+          "BROWSER_HARNESS_HOME": "~/.clementine/browser-harness",
+          "BROWSER_CDP_URL": "ws://localhost:9222"
+        }
+      }
+    }
+
+Run `clementine browser install` and `clementine browser enable` to set up.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Best-effort: load browser-harness from the user's data home.
+HARNESS_HOME = Path(
+    os.environ.get(
+        "BROWSER_HARNESS_HOME",
+        Path.home() / ".clementine" / "browser-harness",
+    )
+).expanduser()
+
+CDP_URL = os.environ.get("BROWSER_CDP_URL", "ws://localhost:9222")
+
+_HARNESS_AVAILABLE = False
+_HARNESS_ERROR: str | None = None
+
+try:
+    if (HARNESS_HOME / "src").is_dir():
+        sys.path.insert(0, str(HARNESS_HOME / "src"))
+    # The actual harness module — import is lazy to keep startup cheap.
+    import browser_harness  # type: ignore  # noqa: F401
+    _HARNESS_AVAILABLE = True
+except Exception as e:  # noqa: BLE001
+    _HARNESS_ERROR = f"{type(e).__name__}: {e}"
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except Exception as e:  # noqa: BLE001
+    sys.stderr.write(
+        "browser-harness MCP: 'mcp' package not installed. "
+        "Run `clementine browser install` to set up.\n"
+        f"Underlying error: {e}\n"
+    )
+    sys.exit(1)
+
+
+server = FastMCP("browser-harness")
+
+
+def _not_ready_message() -> str:
+    if _HARNESS_AVAILABLE:
+        return ""
+    return (
+        "browser-harness is not installed. Run `clementine browser install` "
+        "to clone the harness into ~/.clementine/browser-harness and install "
+        f"Python dependencies. (Underlying: {_HARNESS_ERROR})"
+    )
+
+
+@server.tool()
+def browser_status() -> str:
+    """Report whether browser-harness is installed and the CDP target it's pointed at."""
+    parts = [
+        f"harness_installed: {_HARNESS_AVAILABLE}",
+        f"harness_home: {HARNESS_HOME}",
+        f"cdp_url: {CDP_URL}",
+    ]
+    if not _HARNESS_AVAILABLE and _HARNESS_ERROR:
+        parts.append(f"error: {_HARNESS_ERROR}")
+    return "\n".join(parts)
+
+
+@server.tool()
+def browser_navigate(url: str) -> str:
+    """Open a URL in the connected Chrome via CDP. Tier 2 (logged)."""
+    msg = _not_ready_message()
+    if msg:
+        return msg
+    # TODO: implement via browser_harness CDP helpers
+    return f"[stub] would navigate to {url} via {CDP_URL}"
+
+
+@server.tool()
+def browser_screenshot() -> str:
+    """Capture a screenshot of the active tab and return its file path. Tier 1."""
+    msg = _not_ready_message()
+    if msg:
+        return msg
+    # TODO: implement via browser_harness CDP helpers
+    return f"[stub] would screenshot active tab via {CDP_URL}"
+
+
+@server.tool()
+def browser_inspect(selector: str = "body") -> str:
+    """Read the current page HTML or a specific selector. Tier 1 (read-only)."""
+    msg = _not_ready_message()
+    if msg:
+        return msg
+    # TODO: implement via browser_harness CDP helpers
+    return f"[stub] would inspect '{selector}' via {CDP_URL}"
+
+
+@server.tool()
+def browser_run_python(code: str) -> str:
+    """Run Python in the harness workspace. Tier 3 (autonomous-blocked, requires approval)."""
+    msg = _not_ready_message()
+    if msg:
+        return msg
+    # TODO: thread through agent-workspace/agent_helpers.py — see SKILL.md
+    return f"[stub] would run python ({len(code)} bytes) in {HARNESS_HOME}/agent-workspace"
+
+
+if __name__ == "__main__":
+    # FastMCP handles stdio transport automatically.
+    server.run()