constella 0.1.0

package/docs/en/KB_RAG.md

@@ -0,0 +1,356 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/KB_RAG.md) · [✦ Constella](../../README.md)
+
+# Knowledge Base & RAG ✦ The Memory Nebula 🌌
+
+![](../assets/divider-orbit.svg)
+
+> The control plane's long-term memory. Every decision, fix, pattern and finding agents accumulate condenses into a curated, classified, state-aware nebula — and gravity (semantic retrieval) pulls the right knowledge back into context when it's needed.
+
+Constella runs **two cooperating layers** over the same store:
+
+- **RAG** (`src/server/rag.ts`) — raw retrieval over workspace Markdown + chat transcripts. Embeddings when a local model is up; keyword heuristic otherwise.
+- **KB** (`src/server/kb.ts`) — the curated layer the Knowledge agent (**Vannevar**) owns: typed entries, content-hash dedup, lifecycle (active → superseded → obsolete → archived), state-aware retrieval, a multi-hop knowledge graph, and budget-gated LLM curation.
+
+Both write into one physical table — `rag_chunk` — and KB entries simply emit their own chunks (path `kb/<type>/<id>`) so a single retrieval pass spans docs, chat **and** curated knowledge.
+
+---
+
+## 1. When to use 🪐
+
+| You want to… | Layer / entry point |
+|---|---|
+| Let agents recall what was decided/built without re-reading every file | RAG `retrieve()` + KB `kbQuery()` |
+| Capture a reusable learning deterministically (no LLM) | `ingestKnowledge()` |
+| Have an agent self-record a fact mid-run | `[[REMEMBER type=<t>: <fact>]]` token |
+| Have an agent ask the KB before acting | `[[CONSULT: <question>]]` token |
+| Trigger reindex / chat re-index / embed health from a run | `[[KB: reindex|index-chat|health]]` token |
+| Ask the KB a clean, curated question (chat / `/kb`) | `kbAnswer()` |
+| Walk related knowledge from a goal/spec/issue | `relatedKnowledge()` |
+| Dedupe, retire and tighten the KB | `runKbCuration()` (Vannevar) |
+| Distill recurring learnings into new skills (P3) | `proposeSkillsFromLearnings()` |
+
+See also [KB_AGENT.md](./KB_AGENT.md) (Vannevar's persona & ritual), [MEMORY_RAG.md](./MEMORY_RAG.md), [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md) (canonical blocks), and [MODELS.md](./MODELS.md) (the local embed/chat servers).
+
+---
+
+## 2. How it works 🛰️
+
+### RAG store (`rag.ts`)
+
+- **Indexed dirs** (`RAG_DIRS`): `.claude`, `DOCS`, `PO`, `Reports`, `specs`, `issues`. Plus the attached `mock/` prototype (text files: `.md .html .css .js/jsx .ts/tsx .txt .json`).
+- **Excluded plumbing**: `.claude/kb/` (the KB agent's own prompt/taxonomy) and `.claude/skills/` are never indexed — a question would otherwise retrieve Constella's internals.
+- **Chunking** (`chunksOf`): split on H1–H3 headers (`/\n(?=#{1,3}\s)/`); each part ≤ **1200 chars** (longer parts hard-split); **max 40 chunks** per document.
+- **Embeddings** (`embed`): two backends, tried in order —
+  1. **Ollama** (`OLLAMA_URL`, default `http://127.0.0.1:11434`) with model `CONSTELLA_EMBED_MODEL` (default `nomic-embed-text`).
+  2. **Dedicated llama.cpp embed server** (`CONSTELLA_EMBED_URL`, default `http://127.0.0.1:8083`), OpenAI-compatible `/v1/embeddings`.
+  - Returns `null` if both are down → the caller falls back to keyword search.
+- **Asymmetric nomic prefixes**: nomic-embed-text was trained with task prefixes and *requires* them. Documents are embedded as `search_document: …`, queries as `search_query: …`. Both index and query sides must use the same model + matching prefix or cosine similarity is meaningless.
+- **Chat transcripts** (`indexChat`): the team room, DMs and Telegram are grouped per channel, the **last 400 lines** of each are embedded under path `chat/<channel>`, so agents recall what was *said*, not just what's in the docs.
+
+### The local embed server (`local-models.ts`)
+
+`ensureEmbedServer()` brings up a **separate** llama.cpp instance serving the local nomic GGUF with `--embeddings` on **:8083** (distinct from the chat server on **:8082**). It runs on boot and after an embedding model is downloaded, so retrieval is semantic with no manual setup:
+
+```bash
+llama-server -m <nomic.gguf> --embeddings --host 127.0.0.1 --port 8083 -c 2048 --pooling mean [<gpu-offload args>]
+```
+
+`embedServerUp()` checks `GET <EMBED_URL>/health`; `llamaServerStatus()` checks the chat server's `/v1/models`.
+
+### KB layer (`kb.ts`)
+
+A `kb_entry` is **one unit of reusable knowledge** — a decision, code-change, finding, spec, fix, pattern… It is:
+- **classified** by `type` + work/file refs,
+- **deduped** by a SHA-256 content hash,
+- **lifecycle-tracked** (`active → superseded → obsolete → archived`),
+- and **emits its own `rag_chunk(s)`** under path `kb/<type>/<id>` for semantic retrieval.
+
+All KB capture is **best-effort and fire-and-forget**: a bad item never aborts a batch, and KB work must never break a task run.
+
+---
+
+## 3. Main flow 🌠
+
+```mermaid
+flowchart TD
+  subgraph Ingest["Ingest — deterministic, no LLM"]
+    A["Agent reply / task output"] -->|"[[REMEMBER type=…: fact]]"| EX["extractRemembered()"]
+    EX --> IK["ingestKnowledge(items)"]
+    DOC["Doc / spec / decision written"] --> IK
+    IK --> SCRUB{"scrubSecrets changes text?"}
+    SCRUB -- "yes (secret-shaped)" --> REFUSE["refuse · console.warn"]
+    SCRUB -- "no" --> HASH["sha256 hash"]
+    HASH --> DUP{"hash exists?"}
+    DUP -- "yes" --> TOUCH["touch updatedAt · skip"]
+    DUP -- "no" --> SLOT{"same type+source slot?"}
+    SLOT -- "yes" --> UPD["update-in-place"]
+    SLOT -- "no" --> INS["insert kb_entry"]
+    UPD --> EMB["embedEntry → rag_chunk kb/<type>/<id>"]
+    INS --> EMB
+    EMB --> CUR["scheduleKbCuration (debounced)"]
+  end
+
+  subgraph Query["Query — state-aware retrieval"]
+    Q["[[CONSULT]] · /kb · kbQuery()"] --> SEL["select rag_chunk WHERE obsolete=0"]
+    SEL --> QV{"embed(query) available?"}
+    QV -- "yes + vectors exist" --> COS["cosine top-k · mode=semantic"]
+    QV -- "no" --> KW["keyword overlap top-k · mode=heuristic"]
+    COS --> REFS["refsFor() → spec:/issue:/goal:/file:"]
+    KW --> REFS
+    REFS --> LOG["logQuery → kb_query_log"]
+    LOG --> ANS["KbAnswer{context, sources, refs, sufficient}"]
+  end
+
+  CUR -.->|"Vannevar (budget-gated)"| RUNCUR["runKbCuration() · merge/retire/tighten"]
+```
+
+---
+
+## 4. Key concepts 🕳️
+
+- **Deterministic capture, LLM curation** — the *hot path* (`ingestKnowledge`) never calls a model; the *cold path* (`runKbCuration`) does, off the critical path, budget-gated. The KB keeps working even if curation never runs.
+- **Update-in-place vs insert** — an item with the same `(type, sourceKind, sourceRef)` slot is treated as an *update* of that knowledge (rewrites the row); a different slot inserts a new entry. Identical content (same hash) just touches `updatedAt`.
+- **State-aware retrieval** — `kbQuery` only selects `rag_chunk WHERE obsolete = 0`. Superseded/obsolete entries and the chunks of cancelled/archived goals are flagged `obsolete = 1`, so stale knowledge stops surfacing automatically.
+- **Insufficiency signal** — `KbAnswer.sufficient` is honest: when nothing relevant is found, the answer says so rather than inventing.
+- **Knowledge graph** — `relatedKnowledge` walks the `goalId/specId/issueId` link columns + the `supersedesId` chain up to `hops` (default 2), grouping connected, *active* knowledge by type. Decisions are themselves `kb_entry` rows (`type="decision"`), so this naturally links decisions ↔ specs ↔ issues ↔ prior fixes.
+- **Secrets never enter the KB** — before ingest, `scrubSecrets(blob)` runs; if the text changes (a secret shape was present), the item is **refused**. See [SECURITY.md](./SECURITY.md).
+- **Local-first generation** — KB *answers* and *curation* prefer the local llama.cpp chat server (`LLAMACPP_URL`, default `:8082`); only if it's down does it fall back to the agent's (possibly paid) CLI. `<think>…</think>` blocks from reasoning GGUFs are stripped.
+
+---
+
+## 5. The knowledge taxonomy 🌌
+
+`KbType` — the full set (from `kb.ts`). `note` is the catch-all.
+
+| type | What it captures |
+|---|---|
+| `decision` | An architectural/product decision and its rationale |
+| `spec` | A specification unit |
+| `issue` | An issue/work item finding |
+| `goal` | Goal-level knowledge |
+| `plan` | Planning knowledge |
+| `architecture` | System/structure knowledge |
+| `business-rule` | A domain/business rule |
+| `code-change` | A meaningful code change |
+| `dependency` | A dependency / library fact |
+| `integration` | An external integration detail |
+| `bug` | A bug observed |
+| `fix` | A fix applied |
+| `test` | Test knowledge / coverage |
+| `review` | A review finding |
+| `vuln` | A security vulnerability |
+| `doc` | Documentation knowledge |
+| `user-context` | Operator/user context |
+| `history` | Historical context |
+| `command` | A useful command |
+| `file-structure` | File/layout knowledge |
+| `ui-pattern` | A reusable UI pattern |
+| `stack` | Project-stack fact |
+| `env-config` | Environment/config fact |
+| `note` | Catch-all (default) |
+
+**Agent self-capture** (`[[REMEMBER type=…]]`) accepts a narrower set — `KB_LEARN_TYPES` — and anything outside it falls back to `note`:
+`decision, architecture, business-rule, integration, dependency, bug, fix, test, review, vuln, ui-pattern, stack, env-config, command, note`.
+
+---
+
+## 6. Agent tokens 🚀
+
+Agents read/write the KB inline by emitting double-square-bracket tokens. The runner parses them out and strips them from the visible reply.
+
+| Token | Direction | Handler | Effect |
+|---|---|---|---|
+| `[[REMEMBER type=<t>: <fact>]]` | producer | `extractRemembered()` | Becomes a typed `KbItem` (fact ≥ 8 chars), ingested via `ingestKnowledge` |
+| `[[CONSULT: <question>]]` | consumer | `answerConsults()` | Runs `kbQuery` (k=6), posts the answer back into the thread so it's in context next turn (question ≥ 4 chars) |
+| `[[KB: reindex]]` | maintenance | `runKbTools()` | `indexRag(orgId)` → reports chunk count |
+| `[[KB: index-chat]]` | maintenance | `runKbTools()` | `indexChat(orgId)` → re-embeds conversations |
+| `[[KB: health]]` | maintenance | `runKbTools()` | `llamaServerStatus()` → embed server up/down |
+
+All three are **best-effort**: an unknown verb, a failed query or a too-short fact is silently skipped.
+
+---
+
+## 7. Tables 🪐
+
+### `rag_chunk` — the physical store (RAG + KB share it)
+
+| column | type | notes |
+|---|---|---|
+| `id` | text PK | |
+| `workspace_id` | text → `workspace` | cascade delete |
+| `path` | text | source path (`DOCS/…`, `chat/<channel>`, `kb/<type>/<id>`) |
+| `chunk` | text | the chunk text |
+| `vector` | text (JSON float[]) | `null` when not embedded (keyword fallback) |
+| `kb_entry_id` | text | set when the chunk came from a `kb_entry` |
+| `obsolete` | int(bool) | `1` → dropped by state-aware retrieval |
+| `updated_at` | timestamp | |
+
+### `kb_entry` — the curated knowledge unit
+
+| column | type | notes |
+|---|---|---|
+| `id` | text PK | |
+| `workspace_id` | text → `workspace` | cascade delete |
+| `type` | text | one of `KbType` (default `note`) |
+| `title` | text | ≤ 200 chars |
+| `summary` | text | technical summary (Vannevar curates), ≤ 1200 chars |
+| `body` | text | ≤ 8000 chars |
+| `status` | text | `active \| superseded \| obsolete \| archived` |
+| `goal_id` / `spec_id` / `issue_id` / `task_id` | text | nullable work refs |
+| `module` | text | ≤ 120 chars |
+| `paths` | JSON string[] | files this knowledge concerns (≤ 40) |
+| `agent_handle` | text | who produced it |
+| `source_kind` | text | `task \| goal \| review \| test \| decision \| spec \| issue \| note \| chat` |
+| `source_ref` | text | origin id/key (jump-back); dedup slot key with `type`+`source_kind` |
+| `supersedes_id` | text | the entry this one replaces |
+| `hash` | text | SHA-256 content hash → dedup / update-in-place |
+| `confidence` | int | 0..100 (default 70) |
+| `created_at` / `updated_at` | timestamp | |
+
+### `kb_query_log` — every consultation
+
+| column | type | notes |
+|---|---|---|
+| `id` | text PK | |
+| `workspace_id` | text → `workspace` | |
+| `agent_handle` | text | who asked (`operator` for `/kb`) |
+| `query` | text | ≤ 500 chars |
+| `hits` | int | number of source paths returned |
+| `mode` | text | `semantic \| heuristic \| none` |
+| `refs` | JSON string[] | `kind:ref` jump-backs |
+| `answered_at` | timestamp | indexed for the recent-recall view |
+
+---
+
+## 8. Embedding & retrieval diagram 🛰️
+
+```mermaid
+flowchart LR
+  T["text chunk / query"] --> O{"Ollama up?\n(OLLAMA_URL :11434)"}
+  O -- "yes" --> OE["nomic prefix → /api/embeddings"]
+  O -- "no" --> L{"llama.cpp embed up?\n(CONSTELLA_EMBED_URL :8083)"}
+  L -- "yes" --> LE["nomic prefix → /v1/embeddings"]
+  L -- "no" --> NULL["return null"]
+  OE --> VEC["float[] vector"]
+  LE --> VEC
+  NULL --> KW["keyword heuristic (term overlap)"]
+  VEC --> COS["cosine() similarity"]
+  COS --> TOPK["top-k chunks"]
+  KW --> TOPK
+```
+
+---
+
+## 9. Step-by-step 🌠
+
+### Capture a learning (deterministic)
+1. A doc is written **or** an agent emits `[[REMEMBER type=decision: We chose SQLite WAL for the index]]`.
+2. `extractRemembered` turns the token into a `KbItem`.
+3. `ingestKnowledge` runs `scrubSecrets` (refuses secret-shaped content), hashes the content, and either touches a duplicate, updates the same slot, or inserts a new `kb_entry`.
+4. `embedEntry` drops the old chunks for that path and re-embeds `# <title>\n<summary|body>` (≤ 6000 chars) into `rag_chunk` (path `kb/<type>/<id>`).
+5. `scheduleKbCuration` arms a debounced curation pass.
+
+### Consult before acting
+1. An agent emits `[[CONSULT: how do we store secrets?]]`.
+2. `answerConsults` calls `kbQuery(orgId, q, { k: 6 })`.
+3. `kbQuery` selects active (`obsolete=0`) chunks, ranks by cosine (semantic) or term overlap (heuristic), builds internal refs, logs to `kb_query_log`.
+4. The answer (context + sources + an explicit insufficiency flag) is posted back so it's in the agent's next-turn context.
+
+### Curate (Vannevar)
+1. After enough ingests (≥ 4 entries), the debounced (4 min) + cooldown'd (30 min) trigger fires `runKbCuration`.
+2. Vannevar reviews ~60 recent active/superseded entries, returns JSON: `merges`, `obsolete`, `summaries`, `gaps`.
+3. Merges → drops marked `superseded` (+ `supersedesId`); obsolete → `obsolete`; summaries rewritten + re-embedded; their chunks flagged `obsolete=1`.
+4. A `Reports/kb-health.md` report is written (RAG-indexed) and the operator is notified.
+
+---
+
+## 10. Examples 🪐
+
+**Ask the KB from chat or `/kb`:**
+
+```text
+/kb how do we authenticate the worker process?
+```
+
+`kbAnswer` routes meta/status questions ("how is the KB?", "coverage", "gaps") to a deterministic **overview card**; content questions retrieve then get a short Vannevar-written answer with a tidy Sources line — it never dumps raw chunks.
+
+**Self-capture + consult in one agent run:**
+
+```text
+[[CONSULT: what DB does this project use?]]
+… work …
+[[REMEMBER type=stack: Project uses Drizzle ORM over better-sqlite3]]
+[[KB: reindex]]
+```
+
+**Cancel a goal → its knowledge retires automatically** (`markKbObsoleteForGoal`): the goal's `kb_entry` rows flip to `obsolete` and their `rag_chunk`s to `obsolete=1`, so retrieval stops surfacing them.
+
+---
+
+## 11. Possible states 🕳️
+
+**`kb_entry.status`**
+
+| state | meaning |
+|---|---|
+| `active` | current, retrievable |
+| `superseded` | merged into a canonical entry (`supersedesId` set); not retrieved |
+| `obsolete` | contradicted / retired (also: goal cancelled/archived); not retrieved |
+| `archived` | parked (counted separately in the lifecycle view) |
+
+**`kbQuery` / `retrieve` mode**
+
+| mode | meaning |
+|---|---|
+| `semantic` | cosine over real vectors (embed backend up) |
+| `heuristic` | keyword term-overlap fallback (no embeddings) |
+| `none` | index empty / nothing matched |
+
+**`KbReply.mode`** (from `kbAnswer`): `overview` (the structured KB card), `answer` (model-written), `none` (insufficient knowledge).
+
+---
+
+## 12. Related integrations 🛰️
+
+- **Sync engine** — the watcher calls `scheduleRagReindex` / `indexRagFile` / `deindexRagFile` (debounced 2.5 s) so RAG tracks file changes; disk is truth. See [ARCHITECTURE.md](./ARCHITECTURE.md).
+- **Chat** — every posted message arms `scheduleChatReindex` (debounced 6 s) → `indexChat`. See [TEAM_ROOM.md](./TEAM_ROOM.md), [DM.md](./DM.md), [TELEGRAM.md](./TELEGRAM.md).
+- **Local models** — `ensureEmbedServer` (:8083) + `ensureLlamaServer` (:8082); GPU offload when it fits. See [MODELS.md](./MODELS.md).
+- **Skills (P3)** — `proposeSkillsFromLearnings` distills strong recurring knowledge into **provisional** skills for operator approval. See [SKILLS.md](./SKILLS.md).
+- **Synced blocks** — canonical named knowledge (`mission`, `official-stack`, `business-rules`) the overview card nudges you to create. See [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md).
+- **Commands** — `/kb` (`/ask-kb`), `/reindex`, `/curate`, `/search`, `/graph`. See [CHAT_COMMANDS.md](./CHAT_COMMANDS.md).
+
+---
+
+## 13. Security 🕳️
+
+- **Secret gate on ingest** — `scrubSecrets(blob) !== blob` ⇒ the item is refused and a `console.warn` is logged. No API key, token, PEM, bearer or credentialed DB URL ever lands in the KB.
+- **Org isolation** — every query/index is scoped by `workspace_id` (resolved from `orgId`); only the active org's chunks are ever read or returned.
+- **Internal plumbing hidden** — `.claude/kb/` and `.claude/skills/` are excluded from indexing so a question can't surface Constella's own prompts/skills.
+- **Budget-gated LLM** — curation and skill-proposal runs check the agent's `dailyCapUsd` (`overCap`) before spending, and cost is booked to `cost_entry`.
+- **Opt-outs** — `CONSTELLA_KB_CURATION=0` disables the automatic curation pass entirely.
+
+---
+
+## 14. Troubleshooting 🚀
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Retrieval is `heuristic`, never `semantic` | No embed backend up | Start Ollama with `nomic-embed-text`, or download a nomic GGUF so `ensureEmbedServer` brings up :8083. Check with `[[KB: health]]`. |
+| `/kb` says "not enough in the Knowledge Base" | Empty/cold index | Run `/reindex` (or `[[KB: reindex]]`); knowledge also fills in as agents complete work. |
+| New docs not retrieved | File outside `RAG_DIRS`, or watcher not running | Put docs under `.claude/DOCS/PO/Reports/specs/issues`; ensure the worker process is up. |
+| Old/cancelled knowledge still surfacing | Chunks not flagged | Cancelling/archiving a goal calls `markKbObsoleteForGoal`; a manual `/curate` also retires contradicted entries. |
+| Curation never runs | Cooldown / cap / opt-out | Needs ≥ 4 entries, respects 30-min cooldown + the agent's daily cap; check `CONSTELLA_KB_CURATION`. |
+| Embeddings look wrong (poor matches) | Mismatched nomic prefixes or a non-nomic model | Keep `CONSTELLA_EMBED_MODEL` nomic, or ensure both index+query use the same model/prefix scheme. |
+
+---
+
+## 15. Related links 🌌
+
+- [KB_AGENT.md](./KB_AGENT.md) — Vannevar, the Knowledge agent
+- [MEMORY_RAG.md](./MEMORY_RAG.md) — how memory feeds back into context
+- [SYNCED_BLOCKS.md](./SYNCED_BLOCKS.md) — canonical knowledge blocks
+- [SKILLS.md](./SKILLS.md) — learning → skills (P3)
+- [MODELS.md](./MODELS.md) — local embed (:8083) & chat (:8082) servers
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — `/kb`, `/reindex`, `/curate`, `/graph`
+- [ARCHITECTURE.md](./ARCHITECTURE.md) · [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — where KB/RAG sits in the ship
+- [SECURITY.md](./SECURITY.md) — scrub, isolation, vault

package/docs/en/MCP.md

@@ -0,0 +1,313 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/MCP.md) · [✦ Constella](../../README.md)
+
+# 🛰️ MCP Server — Driving the Central Ship from Orbit
+
+![](../assets/divider-orbit.svg)
+
+A self-contained **Model Context Protocol** server (`scripts/mcp-server.mjs`) that exposes Constella's public REST API as MCP tools, so an external AI host — Claude Desktop, Cursor, or any MCP client — can pilot your Constella control plane through natural language.
+
+---
+
+## When to use
+
+Reach for the MCP server when you want an **outside AI** to observe and steer Constella without opening the web UI:
+
+- Ask Claude Desktop "what's the status of my agent-company?" and have it call `constella_status`.
+- Approve a pending plan, flip 24/7 execution, or start new work from inside Cursor's chat.
+- Wire Constella into any agentic host that speaks MCP, using a scoped Personal Access Token as the only credential.
+
+This is the **outbound-to-Constella** direction: an AI host *drives* Constella. It is the mirror image of Constella's own constellation of agents *consuming* external MCP servers — see [Two MCP directions](#-two-mcp-directions-dont-confuse-them) below.
+
+---
+
+## How it works 🌌
+
+The MCP server is a thin, dependency-free bridge. It speaks **JSON-RPC over stdio** to the MCP host, and each tool call is translated into a single HTTPS-style request against the Public REST API v1 (`/api/v1/...`), authenticated with a Personal Access Token (PAT).
+
+```
+MCP host (Claude Desktop / Cursor)
+        │  JSON-RPC over stdio
+        ▼
+scripts/mcp-server.mjs  ──Bearer cn_…──►  /api/v1/[[...path]]  ──►  Constella cores
+```
+
+Key properties straight from the source:
+
+- **Zero dependencies.** `scripts/mcp-server.mjs` imports only `node:readline` and uses the global `fetch` (Node 18+). It ships in the compiled distribution unchanged.
+- **Hand-rolled MCP.** It implements the JSON-RPC methods `initialize`, `notifications/initialized`, `ping`, `tools/list` and `tools/call` directly — no SDK.
+- **Thin mapping.** Every tool's `build(args)` returns `{ method, path, body? }`, which `callApi` sends to `${BASE}/api/v1${path}` with `Authorization: Bearer ${PAT}` (and `x-constella-org` when `CONSTELLA_ORG` is set).
+- **One credential.** The REST layer (`authenticatePAT` in `src/server/api/pat-auth.ts`) is PAT-only; there is no session. Scope (`read` / `write`) is enforced server-side.
+- **Request timeout.** Each REST call uses `AbortSignal.timeout(30_000)` — a 30-second ceiling per tool call.
+
+---
+
+## Main flow 🚀
+
+```mermaid
+sequenceDiagram
+    participant Host as MCP host (Claude Desktop)
+    participant MCP as mcp-server.mjs
+    participant API as /api/v1 dispatcher
+    participant Core as plan-ops / work-ops / kb
+
+    Host->>MCP: initialize (stdio)
+    MCP-->>Host: serverInfo {name: constella}
+    Host->>MCP: tools/list
+    MCP-->>Host: 13 constella_* tools
+    Host->>MCP: tools/call constella_status
+    MCP->>API: GET /api/v1/status (Bearer cn_…)
+    API->>API: authenticatePAT + rate-limit
+    API->>Core: apiStatus(workspace)
+    Core-->>API: counts
+    API-->>MCP: {ok:true, data:{…}}
+    MCP-->>Host: content[text] (pretty JSON)
+```
+
+The lifecycle, step by step:
+
+1. **Handshake.** The host sends `initialize`; the server replies with `protocolVersion` (echoing the host's, default `2024-11-05`), `capabilities: { tools: {} }`, and `serverInfo: { name: "constella", version: "1.0.0" }`.
+2. **Discovery.** On `tools/list`, the server returns all tools (`name`, `description`, `inputSchema`).
+3. **Invocation.** On `tools/call`, it looks up the tool by name, calls `build(arguments)`, fires the REST request via `callApi`, and wraps the JSON response as `{ content: [{ type: "text", text }], isError: data?.ok === false }`.
+4. **Auth & scope.** The REST dispatcher authenticates the PAT, applies a sliding-window rate limit (120 req/min/token), and rejects write routes when the token has `read` scope.
+
+---
+
+## Key concepts ✦
+
+| Concept | Where | Meaning |
+|---|---|---|
+| **Outbound MCP** | `scripts/mcp-server.mjs` | An external AI host drives Constella through PAT-authenticated REST. |
+| **PAT** | `personalAccessToken` table | `cn_…` token, SHA-256 hashed, scope `read` or `write`, plaintext shown once. |
+| **Scope gate** | `route.ts` `needWrite()` | `write` tokens may mutate; `read` tokens get `403` on POST mutations. |
+| **Org selection** | `CONSTELLA_ORG` → `x-constella-org` | Picks which org a multi-org user acts on (membership-validated). |
+| **Rate limit** | `route.ts` `rateLimited()` | In-memory sliding 60s window, max 120 requests per token. |
+| **Envelope** | `route.ts` `ok()` / `fail()` | Every response is `{ ok: true, data }` or `{ ok: false, error }`. |
+
+---
+
+## Environment variables 🪐
+
+The MCP server is configured purely through env vars passed by the host:
+
+| Variable | Default | Required | Purpose |
+|---|---|---|---|
+| `CONSTELLA_PAT` | — | **Yes** | The `cn_…` Personal Access Token. Use a **write** token to allow approve/execution/new-work; a **read** token for read-only. If unset, every tool returns `{ ok: false, error: "CONSTELLA_PAT is not set" }`. |
+| `CONSTELLA_BASE_URL` | `http://localhost:3000` | No | Base URL of the running Constella server. Trailing slashes are stripped. |
+| `CONSTELLA_ORG` | — | No | An `orgId` for multi-org users; sent as the `X-Constella-Org` header. |
+
+> 🕳️ The token is **never logged** by either side. `pat-auth.ts` validates the bearer against the stored `tokenHash` and resolves the org/workspace through a membership join, so a token can't be pointed at a foreign tenant.
+
+---
+
+## Tool catalog — every `constella_*` mapped to its REST route 🌠
+
+All 13 tools are defined in the `TOOLS` array of `scripts/mcp-server.mjs`. Each maps 1:1 onto a v1 route.
+
+| MCP tool | Scope | REST | Inputs | What it does |
+|---|---|---|---|---|
+| `constella_status` | read | `GET /status` | — | Counts of goals, issues, tasks and the plan state. |
+| `constella_review` | read | `GET /review` | — | Readable text summary of plan, issues, tasks and next steps. |
+| `constella_goals` | read | `GET /goals` | — | List goals. |
+| `constella_issues` | read | `GET /issues` | — | List issues. |
+| `constella_tasks` | read | `GET /tasks` | — | List tasks. |
+| `constella_specs` | read | `GET /specs` | — | List specs. |
+| `constella_kb` | read | `POST /kb` | `q` (required) | Ask the Knowledge Base a question. |
+| `constella_approve_plan` | **write** | `POST /plan/approve` | — | Approve the pending plan and queue tasks. |
+| `constella_reject_plan` | **write** | `POST /plan/reject` | `reason` (optional) | Send the plan back to the CEO for revision. |
+| `constella_set_execution` | **write** | `POST /execution` | `on` (required, bool) | Turn 24/7 autonomous execution on or off. |
+| `constella_new_work` | **write** | `POST /work` | `brief` (required), `title` (optional) | Start a new unit of work — the CEO drafts specs/issues for approval. |
+| `constella_cancel_goal` | **write** | `POST /goals/{id}/cancel` | `id` (required) | Cancel a goal by id. |
+| `constella_archive_goal` | **write** | `POST /goals/{id}/archive` | `id` (required) | Archive a goal by id. |
+
+### Server-side handlers
+
+Each route lands in the `dispatch()` switch of `src/app/api/v1/[[...path]]/route.ts`, which reuses the same session-less cores the Telegram remote control uses:
+
+| REST route | Handler |
+|---|---|
+| `GET /status` | `apiStatus(ws)` |
+| `GET /review` | `reviewSummaryFor(ws)` |
+| `GET /goals` `/issues` `/tasks` `/specs` | `apiGoals` / `apiIssues` / `apiTasks` / `apiSpecs` |
+| `POST /kb`, `GET /kb?q=` | `kbAnswer(org.id, q)` |
+| `POST /plan/approve` | `approvePlanFor(org.id, ws)` |
+| `POST /plan/reject` | `requestPlanChangesFor(ws.id, reason)` |
+| `POST /execution` | `setAuto247For(ws.id, on)` |
+| `POST /work` | `startNewWorkFor(org.id, ws, { brief, title })` |
+| `POST /goals/{id}/cancel` | `cancelGoalFor(ws.id, id)` |
+| `POST /goals/{id}/archive` | `archiveGoalFor(org.id, ws.id, id)` |
+
+> Note: the host-side tool list does **not** include a `me` tool, but the REST API does expose `GET /api/v1` (or `/me`) returning the token's user, org, workspace and scope. Hosts can reach it through the [Public API](./PUBLIC_API.md) directly.
+
+---
+
+## Step-by-step: configuring an MCP host
+
+### 1. Mint a Personal Access Token
+
+In the Constella web UI: **Profile → Personal access tokens → New token**. Choose a scope:
+
+- **read** — for status/review/list/KB tools only.
+- **write** — to also allow approve, reject, execution, new-work, cancel and archive.
+
+The plaintext `cn_…` value is shown **once** (`createPAT` returns it; only the SHA-256 hash is persisted). Copy it immediately.
+
+### 2. Make sure Constella is running
+
+The MCP server talks to a live server at `CONSTELLA_BASE_URL` (default `http://localhost:3000`). Start Constella normally (`constella` / `npm start`).
+
+### 3. Register the server in your host
+
+**Claude Desktop** — edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "constella": {
+      "command": "node",
+      "args": ["C:/Users/Usuario/Documents/constella/scripts/mcp-server.mjs"],
+      "env": {
+        "CONSTELLA_PAT": "cn_your_write_token_here",
+        "CONSTELLA_BASE_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — add the same block under `mcpServers` in Cursor's MCP settings (`.cursor/mcp.json` or the global MCP config). For a multi-org user, add `"CONSTELLA_ORG": "<orgId>"` to `env`.
+
+### 4. Use it
+
+Restart the host, open a chat, and ask in plain language — the host will discover the 13 `constella_*` tools via `tools/list` and call them as needed:
+
+> "Use Constella to show me the current status, then approve the pending plan."
+
+---
+
+## Examples 🌌
+
+### Smoke-test the server by hand
+
+You can drive the stdio protocol directly to confirm it's wired up:
+
+```bash
+CONSTELLA_PAT=cn_xxx CONSTELLA_BASE_URL=http://localhost:3000 \
+  node scripts/mcp-server.mjs <<'EOF'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"constella_status","arguments":{}}}
+EOF
+```
+
+Each line is newline-delimited JSON-RPC; the server replies one JSON object per line.
+
+### A `tools/call` request and response
+
+Request from the host:
+
+```json
+{"jsonrpc":"2.0","id":7,"method":"tools/call",
+ "params":{"name":"constella_new_work",
+           "arguments":{"brief":"Add a dark-mode toggle to settings","title":"Dark mode"}}}
+```
+
+Server reply (the REST envelope is pretty-printed into a text content block):
+
+```json
+{"jsonrpc":"2.0","id":7,"result":{
+  "content":[{"type":"text","text":"{\n  \"ok\": true,\n  \"data\": { ... }\n}"}],
+  "isError":false}}
+```
+
+If the PAT had `read` scope, the REST layer returns `403` and the content's `ok` is `false`, so `isError` becomes `true`.
+
+---
+
+## Possible states 🕳️
+
+| Situation | Where it surfaces | Result |
+|---|---|---|
+| `CONSTELLA_PAT` unset | `callApi` | `{ ok: false, error: "CONSTELLA_PAT is not set" }` (no network call). |
+| Malformed / missing bearer | `authenticatePAT` | HTTP `401` `"missing or malformed bearer token"`. |
+| Unknown token hash | `authenticatePAT` | HTTP `401` `"invalid token"`. |
+| No org / archived org | `authenticatePAT` | HTTP `404` / `409`. |
+| Read token hits a write route | `needWrite()` | HTTP `403` `"this token has read scope; a write-scope token is required"`. |
+| Over 120 req/min | `rateLimited()` | HTTP `429` `"rate limit exceeded (120 req/min)"`. |
+| Unknown tool name | `tools/call` | JSON-RPC error `-32602` `unknown tool: …`. |
+| Unknown JSON-RPC method | `handle()` | JSON-RPC error `-32601` `method not found: …`. |
+| Handler throws | `rl.on("line")` | JSON-RPC error `-32603` (internal). |
+| Non-JSON stdin line | `rl.on("line")` | Silently ignored. |
+| REST returns non-JSON | `callApi` | `{ ok: false, error: "non-JSON response (http <status>)" }`. |
+
+---
+
+## 🪐 Two MCP directions — don't confuse them
+
+Constella touches MCP in **two opposite directions**:
+
+| Direction | Who drives whom | Mechanism |
+|---|---|---|
+| **Outbound (this doc)** | An external AI host drives **Constella** | `scripts/mcp-server.mjs` → Public REST API v1, PAT-authenticated. |
+| **Inbound (agents consume external MCPs)** | **Constella's agents** drive external MCP servers | Configured through the `claude` CLI's `~/.claude` config; **not** through Constella's `plugin` table. |
+
+```mermaid
+flowchart LR
+    subgraph Outbound
+      H["Claude Desktop / Cursor"] -->|stdio JSON-RPC| M["mcp-server.mjs"]
+      M -->|"Bearer cn_…"| R["/api/v1"]
+      R --> C["Constella cores"]
+    end
+    subgraph Inbound
+      A["Constella agent (claude CLI)"] -->|"~/.claude MCP config"| X["External MCP server"]
+    end
+```
+
+The inbound direction is operator-level configuration of the `claude` CLI and is unrelated to Constella's [Plugins](./PLUGINS.md) registry. See [Agents](./AGENTS.md) and [AI Architecture](./AI_ARCHITECTURE.md) for how agents run.
+
+---
+
+## Related integrations
+
+- **[Public API](./PUBLIC_API.md)** — the REST v1 surface the MCP server wraps; same PATs and scopes.
+- **[Telegram](./TELEGRAM.md)** — another remote-control surface reusing the same session-less cores (`plan-ops.ts` / `work-ops.ts`).
+- **[Plugins](./PLUGINS.md)** — Constella's native plugin registry (GitHub, Telegram, Vault, Web Search); distinct from external MCP consumption.
+- **[KB & RAG](./KB_RAG.md)** — what `constella_kb` queries under the hood.
+
+---
+
+## Security 🔒
+
+- **PAT-only, hashed at rest.** Only the SHA-256 `tokenHash` is stored (`personalAccessToken` table). The plaintext `cn_…` appears once at creation and is never logged on either side.
+- **Membership-secure org resolution.** `getActiveOrg(userId, orgHeader)` validates the requested org through a membership join — a token cannot be aimed at another tenant.
+- **Scope enforcement.** Mutations require `write`; the `read` scope is locked to GET-style tools plus KB queries.
+- **Rate limiting.** 120 requests/min/token (sliding 60s window), resetting on server restart.
+- **Loopback by default.** With `CONSTELLA_BASE_URL` defaulting to `http://localhost:3000`, the MCP server reaches Constella on the loopback interface unless you deliberately point it elsewhere.
+- **Bounded calls.** Each REST request is capped at 30 seconds (`AbortSignal.timeout(30_000)`).
+- **Least privilege.** Prefer a **read** token for monitoring hosts; reserve **write** tokens for hosts you truly trust to approve plans and start work.
+
+---
+
+## Troubleshooting 🛠️
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Every tool returns `"CONSTELLA_PAT is not set"` | Env var missing in the host's `env` block | Add `CONSTELLA_PAT` to the MCP server entry and restart the host. |
+| `401 invalid token` | Token revoked, mistyped, or from another instance | Mint a fresh PAT; confirm `CONSTELLA_BASE_URL` points at the same instance. |
+| `403 … write-scope token is required` | Using a read token for approve/execution/new-work | Create a **write**-scope token. |
+| `429 rate limit exceeded` | More than 120 calls/min on one token | Slow down or use a second token. |
+| Connection refused / non-JSON response | Constella not running or wrong base URL | Start Constella; verify `CONSTELLA_BASE_URL`. |
+| Host shows no Constella tools | Server failed to launch | Check the host's MCP logs; verify the `node` command and absolute path to `scripts/mcp-server.mjs`. |
+| `409 organization is archived` | The token's org was archived | Use a token whose org is active, or set a valid `CONSTELLA_ORG`. |
+
+---
+
+## Related links
+
+- [Public API](./PUBLIC_API.md)
+- [Telegram](./TELEGRAM.md)
+- [Plugins](./PLUGINS.md)
+- [Agents](./AGENTS.md)
+- [AI Architecture](./AI_ARCHITECTURE.md)
+- [KB & RAG](./KB_RAG.md)
+- [Security](./SECURITY.md)
+- [Architecture](./ARCHITECTURE.md)