constellai 0.3.0

package/docs/en/ARCHITECTURE.md

@@ -0,0 +1,334 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/ARCHITECTURE.md) · [✦ Constella](../../README.md)
+
+# 🌌 Architecture — the central ship
+
+Constella is a local-first control plane: a single Node process supervises a **web server** and a **24/7 worker**, both orbiting one runtime root on disk where every organization keeps an isolated workspace. The directory is the source of truth; SQLite is the index that lets the UI and search agree.
+
+> ✦ This document maps the *structural* layer: process topology, runtime root + org isolation, the filesystem jail, the SQLite/Drizzle store, the sync engine + file-watcher, and the cron tick that drives autonomous work. For the *cognitive* layer (how agents think, RAG, KB) see [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## 🛰️ When to use this doc
+
+- You need to understand **how Constella boots** and which process does what.
+- You are debugging **why a file edit did not appear** in the UI (sync engine).
+- You are reasoning about **multi-tenant isolation** (one runtime root, many orgs).
+- You are hardening or auditing the **worker ↔ web** trust boundary.
+- You want the **table-level map** of the database (`src/db/schema.ts`).
+
+---
+
+## 🚀 How it works (high level)
+
+A single launcher — `bin/constella.mjs` — resolves the run mode, prepares the runtime root and secrets, applies the database migrations, then **supervises two long-lived children**:
+
+| Child | Entry | Role |
+| --- | --- | --- |
+| **web** | `next start -H <host> -p <port>` (from `PKG_ROOT`) | The Next.js 16 app: UI, server actions, all `/api` routes, agent orchestration. |
+| **worker** | `bin/worker.mjs` | Headless 24/7 driver: cron tick, the chokidar file-watcher, the Telegram long-poll. Talks to the web over loopback HTTP. |
+
+The worker never touches the database directly. It only makes authenticated HTTP calls back into the web server (`x-worker-secret`), so all writes funnel through one process and one set of server actions. This keeps the trust boundary small and the DB single-writer.
+
+```mermaid
+flowchart TB
+  subgraph Launcher["bin/constella.mjs (supervisor)"]
+    SUP["supervise(): restart on crash<br/>max 5 / 60s"]
+  end
+
+  SUP -->|spawn| WEB["web<br/>next start @ host:port<br/>cwd = PKG_ROOT"]
+  SUP -->|spawn| WK["worker<br/>bin/worker.mjs"]
+
+  WK -->|"POST /api/cron/tick<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/sync/file<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/telegram/poll"| WEB
+  WK -->|"chokidar watch"| DISK[("Runtime root<br/>~/.constella")]
+
+  WEB -->|drizzle / better-sqlite3| DB[("constella.db<br/>WAL")]
+  WEB -->|"fs-workspace safe()"| DISK
+  WEB -->|spawn claude / codex| CLI["agent CLIs<br/>cwd = org workspace (FS jail)"]
+  CLI -->|edit files| DISK
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DB,DISK store
+```
+
+---
+
+## 🌠 Main flow — boot to steady state
+
+The launcher's boot sequence (`bin/constella.mjs`), in order:
+
+1. **Resolve install target** — an explicit launch flag (`--start|--vps|--portable`) wins, then legacy `--bind`. A bare `constella` prints usage and exits. Authentication (email + password) is required on every target. See [START_MODE](./START_MODE.md), [VPS_MODE](./VPS_MODE.md), [PORTABLE_MODE](./PORTABLE_MODE.md).
+2. **Resolve the runtime root** — `CONSTELLA_HOME` / `--path` wins; otherwise `~/.constella`. Portable mode with no path enumerates removable USB drives and prompts. `mkdir -p <HOME>/organizations`.
+3. **Pin paths** — `DATABASE_URL=file:<HOME>/constella.db`, `CONSTELLA_PKG_ROOT=<install dir>`. `PKG_ROOT` is where the prebuilt `.next`, `drizzle/` migrations and configs live (not the launch dir).
+4. **Persist secrets** — read/generate `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET` and write them to `<HOME>/.env` with mode `0o600`. Generated once; reused across restarts so sessions + the encrypted vault survive.
+5. **Portable disk check** — refuse `< 32 GB` free (fatal); `≥ 32 GB` is fine.
+6. **Apply migrations** — `drizzle-kit migrate --config drizzle.config.mjs` from `PKG_ROOT`. Idempotent. A *fresh* DB that fails to migrate aborts the boot (no tables → every request 500s).
+7. **Build-on-first-run (fallback only)** — the published package ships a prebuilt `.next`, so this is skipped. From a source tree without a build it runs `next build`; it refuses to silently fall back to `next dev` in a public run unless `CONSTELLA_DEV=1`.
+8. **Supervise web + worker** — spawn the web server, then ~1.5 s later the worker (so Next has a head start). Each child is wrapped in `supervise()`; on an unexpected exit it auto-restarts (bounded: `MAX_RESTARTS = 5` within `WINDOW_MS = 60_000`), else the supervisor gives up and exits.
+
+Once steady, the **worker** waits for the server to answer (`waitForServer`, up to ~90 s), then:
+
+- Fires the **cron tick** immediately and every `INTERVAL` (`CONSTELLA_WORKER_INTERVAL_MS`, default `60_000` ms).
+- Starts the **chokidar watcher** over `<HOME>/organizations`.
+- Runs the **Telegram long-poll** loop (`getUpdates` waits ~25 s server-side; gap ~1 s between polls).
+
+---
+
+## 🪐 Key concepts
+
+### Runtime root + per-org isolation
+
+```
+~/.constella/                         ← runtime root (CONSTELLA_HOME or --path)
+├─ .env                               ← persisted secrets (mode 0600)
+├─ constella.db                       ← SQLite (WAL) — the index
+├─ cache/                             ← models.dev cache, etc.
+├─ backups/                           ← .env + db backups on update
+└─ organizations/
+   └─ <orgId>/
+      └─ workspace/                   ← the org's isolated, sandboxed tree
+         ├─ .claude/                  ← agents/, skills/, BRIEF.md (config INSIDE the workspace)
+         ├─ DOCS/  PO/  Reports/
+         ├─ specs/ issues/ mock/
+         ├─ uploads/                  ← operator attachments, Telegram media
+         └─ <the product the agents build>
+```
+
+The workspace directory is keyed by the **stable `organization.id`** (never the renameable slug). A one-time boot migration renames a legacy `constella/` dir to `workspace/` so existing orgs keep their data (falling back to a copy on a cross-device move, never deleting the legacy dir).
+
+### The filesystem jail — `safe()`
+
+Every workspace read/write goes through `safe(root, rel)` in `src/lib/fs-workspace.ts`. It is the single chokepoint that keeps a prompt-injected agent (or a buggy path) inside its own org:
+
+1. **Lexical check** — `normalize(join(root, rel))` must equal `root` or start with `root + sep`. Because `join` re-roots absolute, drive-letter and UNC paths under `root`, this blocks `../`, absolute escapes and Windows drive tricks.
+2. **Symlink check** — it resolves the real path of the nearest existing ancestor (`realAncestor`) and re-verifies it is still under the real `root`. This defeats a symlink *planted inside* the workspace that would otherwise tunnel out to another org or the wider filesystem.
+
+`orgRoot()` additionally validates the org id (`/^[A-Za-z0-9_-]{6,64}$/`) before it ever touches a path, so a malformed id can't traverse. Heavy build/dependency dirs (`node_modules`, `.git`, `.next`, `dist`, `.testdev`, …) are skipped by `listFiles()` via `HEAVY_DIRS`.
+
+### Directory is truth, DB is the index
+
+The filesystem is canonical; the database **mirrors** it. Indexers in `src/server/sync.ts` are idempotent upserts and **disk always wins on conflict**. The same file written by an agent and later re-indexed by the watcher updates *one* row (keyed by H1 title or relative path), never duplicates.
+
+### SQLite + Drizzle
+
+`src/db/index.ts` opens `better-sqlite3` against the resolved `DATABASE_URL`, sets `journal_mode = WAL` and `foreign_keys = ON`, and wraps it with `drizzle-orm`. It also exports the raw `sqlite` handle for **migration-free boot DDL** (`CREATE TABLE IF NOT EXISTS` + guarded `ALTER ADD COLUMN`) — used to add tables/columns to existing DBs *without* `drizzle-kit push`, which would drift this project's migration history. See [SECURITY](./SECURITY.md) and [TROUBLESHOOTING](./TROUBLESHOOTING.md) for the `db:push` caveat.
+
+### Worker ↔ web trust boundary
+
+The worker holds the privileged `CONSTELLA_WORKER_SECRET` and attaches it as `x-worker-secret` to every call. Two protections matter:
+
+- **Fail closed on the server**: `/api/cron/tick` and `/api/sync/file` return `401` unless the header equals the configured secret. An unset secret does **not** leave them open — they reject everyone.
+- **SSRF / exfil guard on the worker**: the worker refuses to send the secret to a non-loopback host. The launcher always sets `CONSTELLA_BASE_URL=http://127.0.0.1:<port>` (loopback even when the web binds `0.0.0.0` for vps/portable). A genuine remote worker must opt in with `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1`, and over plain `http://` it warns that the secret travels in cleartext.
+
+---
+
+## 🗃️ Tables
+
+### Process / runtime environment
+
+| Env var | Set by | Meaning |
+| --- | --- | --- |
+| `CONSTELLA_HOME` | launcher (`--path` / default `~/.constella`) | Runtime root. Relative values are anchored to the launch dir (`INIT_CWD`). |
+| `DATABASE_URL` | launcher | `file:<HOME>/constella.db` (absolute, so app + `drizzle-kit migrate` open the same DB). |
+| `CONSTELLA_PKG_ROOT` | launcher | Installed package root (prebuilt `.next`, `drizzle/`, bundled `skills/`). |
+| `CONSTELLA_RUN_MODE` | launcher | `start \| vps \| portable`. Auth (email + password) is required on all of them. |
+| `CONSTELLA_PUBLIC` | launcher (`=1`) | A CLI launch is the public runtime → the UI target-picker is hidden. |
+| `CONSTELLA_VERSION` | launcher | Installed version, for the in-app Update check. |
+| `BETTER_AUTH_SECRET` | `<HOME>/.env` | Session signing key (real, never the public default). |
+| `CONSTELLA_VAULT_KEY` | `<HOME>/.env` | AES-256-GCM key for the `vault` table. |
+| `CONSTELLA_WORKER_SECRET` | `<HOME>/.env` | Shared secret for worker → web auth (`x-worker-secret`). |
+| `CONSTELLA_BASE_URL` | launcher → worker | `http://127.0.0.1:<port>` — loopback target for worker calls. |
+| `CONSTELLA_WORKER_INTERVAL_MS` | optional | Cron tick interval (default `60_000`). |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | optional (`=1`) | Allow the worker to call a non-loopback host. |
+| `CONSTELLA_WEB_HEAP_MB` | optional | `--max-old-space-size` for the web child. |
+| `CONSTELLA_DEV` | optional (`=1`) | Permit a `next dev` fallback from a source tree without a build. |
+
+### Core tenancy + structural tables (`src/db/schema.ts`)
+
+| Table | Key columns | Purpose |
+| --- | --- | --- |
+| `organization` | `id`, `ownerId`, `runMode` (`start\|vps\|portable`), `archived` | Tenant. `runMode` is the persisted install target. |
+| `member` | `orgId`, `userId`, `role` (`owner\|admin\|member`) | Org membership + roles. |
+| `workspace` | `id`, `orgId`, `slug` (unique), `stack` (JSON), `runMode`, `bootstrap`, `settings` (JSON) | One workspace per org; `settings` holds Telegram/GitHub/source/agents config. |
+| `agent` | `handle`, `role`, `adapter`, `model`, `status`, `health`, `reportsTo`, `dailyCapUsd` | The 10-agent constellation. |
+| `skill` / `agentSkill` | `name`, `native`, `indexed`; join `auto` | Markdown procedures + per-agent enablement. |
+| `goal` / `spec` / `issue` / `task` / `plan` | lifecycle `status`/`col`, `approved`, `auto247` | The work pipeline ([GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)). |
+| `message` / `chatSession` / `event` / `decision` | `channel`, `runId`, `seq` | Team Room, DM sessions, live run events, decision log. |
+| `ragChunk` / `kbEntry` / `syncedBlock` / `docIndex` | embeddings + KB layer | Memory nebula ([KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md)). |
+| `file` | `path`, `gitStatus` (`""\|M\|A\|U\|D`) | Editor mirror + git porcelain status. |
+| `vault` | `ref`, `ciphertext`, `iv` | AES-GCM secrets keyed by provider. |
+| `fileLock` | `workspaceId+path` (PK), `taskId`, `heartbeatAt` | Per-file lock so parallel agents never edit the same file ([SECURITY](./SECURITY.md)). |
+
+> The schema defines ~60 tables. The list above covers the ones load-bearing for *architecture*; the work, KB and model tables are documented in their own pages.
+
+### Sync engine — indexed prefixes
+
+`bin/worker.mjs` only forwards files matching the `INDEXED` regex; `src/server/sync.ts` then routes each path to a per-type indexer:
+
+| Path pattern | Indexer | DB target |
+| --- | --- | --- |
+| `.claude/skills/<name>.md` | `indexSkillFile` | `skill` |
+| `.claude/agents/<handle>/(Agent\|skills).md` | `indexAgentFile` | `agent` (+ `agentSkill`) |
+| `Reports/**.md` | `indexReportFile` | `report` |
+| `DOCS/**.md` | `indexDocFile` (kind `docs`) | `docIndex` |
+| `PO/**.md` | `indexDocFile` (kind `po`) | `docIndex` |
+
+Any change to a RAG file also schedules a debounced incremental re-embed via `scheduleRagReindex`; a delete drops its chunks via `deindexRagFile`.
+
+---
+
+## 🌌 Mermaid — the sync engine (disk → DB)
+
+```mermaid
+sequenceDiagram
+    participant FS as Workspace files
+    participant W as worker (chokidar)
+    participant API as POST /api/sync/file
+    participant SYNC as src/server/sync.ts
+    participant DB as SQLite
+
+    FS->>W: add / change / unlink
+    Note over W: parse() → {orgId, rel}<br/>INDEXED regex gate<br/>debounce 400ms per key
+    W->>API: POST {orgId, rel, event}<br/>x-worker-secret
+    API->>API: 401 unless secret matches
+    alt event = unlink
+        API->>SYNC: deindexFile(orgId, rel)
+        SYNC->>DB: delete row + drop RAG chunks
+    else add / change
+        API->>SYNC: indexFile(orgId, rel)
+        SYNC->>SYNC: scheduleRagReindex(orgId, rel)
+        SYNC->>DB: upsert (disk wins) + revalidatePath
+    end
+```
+
+---
+
+## 🛰️ Mermaid — the prompt flow (tick → agent → disk → index)
+
+This is the full loop that turns an autonomous tick into real work on disk, then back into the UI.
+
+```mermaid
+flowchart LR
+  T["worker tick<br/>every 60s"] -->|"POST /api/cron/tick"| API["/api/cron/tick<br/>(401 unless x-worker-secret)"]
+  API --> RUN["tickAll({ execute:true, auto:true })"]
+  RUN -->|"per active workspace"| TW["tickWorkspace()"]
+  TW --> SPAWN["spawn claude / codex<br/>--output-format json<br/>cwd = org workspace"]
+  SPAWN -->|"FS jail safe()"| EDIT["agent edits files"]
+  EDIT --> DISK[("workspace/ on disk")]
+  DISK -->|"chokidar"| WATCH["worker watcher"]
+  WATCH -->|"POST /api/sync/file"| SYNC["indexFile()"]
+  SYNC --> DB[("SQLite index")]
+  DB -->|"revalidatePath"| UI["Next.js UI updates"]
+  EDIT -.->|"event rows (runId, seq)"| DB
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DISK,DB store
+```
+
+The agent run itself (model, permission mode, web research, timeouts) is detailed in [AGENTS](./AGENTS.md) and [AI_ARCHITECTURE](./AI_ARCHITECTURE.md). Architecturally, the key point is the **closed loop**: tick → spawn (jailed CLI) → disk → watcher → sync → DB → UI.
+
+---
+
+## 🚀 Step-by-step — trace a single edit end-to-end
+
+1. The cron tick (or a DM) advances a workspace; the runner spawns a CLI agent with `cwd` = the org workspace (the FS jail).
+2. The agent writes a file (e.g. `Reports/sprint-3.md`). All writes from server code go through `writeWorkspaceFile` → `safe()`; the CLI itself is confined by `cwd` + the guard/lock hooks.
+3. chokidar (`awaitWriteFinish`, 300 ms stability) fires `add`/`change`.
+4. `parse(abs)` derives `{orgId, rel}` from `<orgId>/workspace/<rel>` and tests the `INDEXED` regex. Non-indexed files are ignored.
+5. A 400 ms per-key debounce coalesces rapid saves, then `POST /api/sync/file` with `x-worker-secret`.
+6. The route authenticates and calls `indexFile(orgId, rel)` → `indexReportFile` → upsert into `report`, plus `scheduleRagReindex`.
+7. `revalidatePath("/reports")` (and `/code`) refresh the UI on next navigation.
+
+---
+
+## 🌠 Examples
+
+**Boot from npm (start mode):**
+```bash
+npx constellai                 # default = start mode, 127.0.0.1:3000
+# Constella runtime root : C:\Users\you\.constella
+# Mode                   : start  ·  127.0.0.1:3000
+# • Starting: next start -H 127.0.0.1 -p 3000  +  worker
+# watching C:\Users\you\.constella\organizations
+```
+
+**Point the runtime root at a project folder (dev):**
+```bash
+CONSTELLA_HOME=./.constella npx constellai --start --port 4000
+```
+
+**Run web + worker together in development (no global install):**
+```bash
+pnpm dev:all       # scripts/dev-all.mjs → next dev + worker (Telegram poll works in dev)
+pnpm start         # scripts/start-all.mjs → next start + worker (prod build)
+```
+
+**Inspect the index directly:**
+```bash
+sqlite3 ~/.constella/constella.db ".tables"
+sqlite3 ~/.constella/constella.db "SELECT handle,status,health FROM agent;"
+```
+
+---
+
+## 🕳️ Possible states
+
+| Surface | States |
+| --- | --- |
+| Supervised child | running · auto-restarting (`n/5 within 60s`) · gave up (supervisor exits) |
+| `organization.runMode` | `start` · `vps` · `portable` |
+| `workspace.runMode` | `off` · `start` · `vps` · `portable` (`off` is excluded from `tickAll`) |
+| `workspace.bootstrap` | `pending` · `template-only` · `enriching` · `done` |
+| `agent.status` | `idle` · `working` · `review` · `blocked` |
+| `agent.health` | `alive` · `stale` · `down` |
+| `file.gitStatus` | `""` · `M` · `A` · `U` · `D` |
+| Worker base URL guard | loopback (allowed) · non-loopback + `ALLOW_REMOTE` · refused (exit 1) |
+
+---
+
+## 🛰️ Related integrations
+
+- **Worker endpoints**: `/api/cron/tick`, `/api/sync/file`, `/api/telegram/poll` — all behind `x-worker-secret`.
+- **Telegram** long-poll runs inside the worker → [TELEGRAM](./TELEGRAM.md).
+- **GitHub** git status flows into `file.gitStatus` → [GITHUB](./GITHUB.md).
+- **RAG/KB** re-embedding is triggered by the sync engine → [KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md).
+- **Public API / MCP** are separate inbound surfaces (not worker-secret) → [PUBLIC_API](./PUBLIC_API.md), [MCP](./MCP.md).
+
+---
+
+## 🕳️ Security
+
+- **FS jail** `safe()` — lexical + symlink checks; the workspace root is never deletable through it. Org id is validated before any path is built.
+- **Worker secret fails closed** — `/api/cron/tick` and `/api/sync/file` reject every request when no secret is configured (an unset secret is *not* an open door).
+- **SSRF guard** — the worker only sends its secret to loopback unless explicitly overridden; cleartext remote use is warned.
+- **Vault** — secrets live only in the `vault` table (AES-256-GCM via `CONSTELLA_VAULT_KEY`), never on provider rows; `.env` is written `0o600`.
+- **Single writer** — the worker has no DB handle; all writes go through the web process, so there is one authority for consistency.
+- Full detail in [SECURITY](./SECURITY.md).
+
+---
+
+## 🌌 Troubleshooting
+
+| Symptom | Likely cause | Where to look |
+| --- | --- | --- |
+| File edited but UI stale | watcher not running, or path not in `INDEXED` | worker logs (`watching …`); `bin/worker.mjs` `INDEXED` regex |
+| `401 unauthorized` on tick/sync | `CONSTELLA_WORKER_SECRET` mismatch between web + worker | `<HOME>/.env`; both children inherit it from the launcher |
+| Worker exits at start | `CONSTELLA_BASE_URL` is non-loopback without override | set loopback or `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` |
+| Two separate databases appear | standalone server chdir without `INIT_CWD` | use `pnpm start` / the CLI (they set `INIT_CWD`); see `src/lib/runtime-root.ts` warning |
+| Fresh DB has no tables | `drizzle-kit migrate` failed on first boot | reinstall the package; check `drizzle/` ships; boot aborts on a fresh-DB migrate failure by design |
+| Crash-loop "giving up" | a child crashed 5× in 60s | check the OOM hint; raise `CONSTELLA_WEB_HEAP_MB` if it's a JS-heap OOM |
+
+More in [TROUBLESHOOTING](./TROUBLESHOOTING.md) and [FAQ](./FAQ.md).
+
+---
+
+## ✦ Related links
+
+- [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) — the cognitive layer (agents, RAG, context).
+- [AGENTS](./AGENTS.md) — the 10-agent constellation and how runs are spawned.
+- [CONFIGURATION](./CONFIGURATION.md) — env vars and settings in depth.
+- [INSTALLATION](./INSTALLATION.md) · [START_MODE](./START_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md) · [SYNCED_BLOCKS](./SYNCED_BLOCKS.md)
+- [SECURITY](./SECURITY.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)
+- [TELEGRAM](./TELEGRAM.md) · [GITHUB](./GITHUB.md) · [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md)

package/docs/en/CHAT_COMMANDS.md

@@ -0,0 +1,305 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/CHAT_COMMANDS.md) · [✦ Constella](../../README.md)
+
+# 🛰️ Chat Commands
+
+![](../assets/divider-orbit.svg)
+
+> Slash commands are the control panel of the central ship. Type a `/command` in the Team Room or any DM and the server runs a real action server-side, then posts the result back into the same thread — no agent round-trip required.
+
+---
+
+## 2. Short description
+
+Chat slash commands are parsed from a leading `/` in the message-send path. They are intercepted **before** the normal conversational path (the `[[CREATE_WORK]]` token and `@mention` routing) and executed by `runSlashCommand` in `src/server/commands.ts`. Each command posts its result straight into the active channel; a handful also hand off to an agent who replies next.
+
+---
+
+## 3. When to use
+
+Use slash commands when you want a **deterministic, immediate action** rather than a conversation:
+
+- Drive the work lifecycle without prose: `/approve`, `/run-247`, `/pause`, `/reject`, `/cancel`, `/archive`.
+- Query the constellation's state at a glance: `/status`, `/agents`, `/agent`, `/locks`, `/models`, `/skills`, `/telegram`.
+- Tap the memory nebula: `/kb`, `/search`, `/graph`, `/reindex`, `/curate`.
+- Trigger gates and pipelines: `/test-dev`, `/review`, `/github`, `/prepare-deploy`, `/export-source`.
+- Seed new work or board items: `/new-goal`, `/new-issue`, `/new-spec`, `/generate-plan`, `/assign`, `/close-sprint`.
+
+For free-form requests ("build me a billing page"), just talk to **@ada** in the Team Room or use `/new-goal` — see [DM.md](./DM.md) and [WORKFLOW.md](./WORKFLOW.md).
+
+---
+
+## 4. How it works 🌌
+
+The send path lives in `src/server/chat.ts`. After resolving the org, workspace and agent roster, it inspects the trimmed message text:
+
+```ts
+// src/server/chat.ts — slash commands (room + DM, not Telegram)
+const trimmed = (text ?? "").trim();
+if (trimmed.startsWith("/") && channel !== "telegram") {
+  const { runSlashCommand } = await import("@/server/commands");
+  const r = await runSlashCommand(org.id, workspace.id, agents, channel, trimmed);
+  if (r.handled) { revalidatePath("/", "layout"); return { responders: r.responders }; }
+}
+```
+
+Key facts grounded in the code:
+
+- **Channels**: slash commands are honoured in the **Team Room** (`room`) and **DMs** (`dm:<handle>`). They are **not** parsed in the `telegram` channel — Telegram has its own remote-control command handler (`handleCommand` in `src/server/telegram.ts`). See [TELEGRAM.md](./TELEGRAM.md).
+- **Parsing**: `runSlashCommand` splits on the first space. The token before the space is lower-cased into `cmd`; everything after is trimmed into `rest` (the argument).
+- **Echo + reply**: most commands first echo your raw input with `postOp(...)` (as the operator), then post a result with `post(...)`. The result author is usually `system`, but several commands post **as a specific agent** (e.g. Vannevar, Edsger, Werner, Donald, Ada).
+- **Responders**: `runSlashCommand` returns `{ handled, responders }`. A non-empty `responders` array means the named agent(s) should reply next — used by `/new-goal`, `/review`.
+- **Wake**: every handled command calls `wake(wsId)` (via the internal `done()` helper) to nudge the worker/bus.
+- **Sessions**: `ensureActiveSession(wsId, channel)` attaches the result to the channel's active `chatSession`.
+
+### Room auto-routing
+
+In the Team Room, plain text that is **not** a `/command` and **not** an `@mention` is auto-prefixed to `/kb` before sending (see `welcome-chat.tsx` and `home-command-bar.tsx`). So typing `how does auth work?` in the room is equivalent to `/kb how does auth work?`. In a DM, text is sent as-is to that agent.
+
+### Home command bar
+
+The Welcome Home command bar (`src/components/modules/home-command-bar.tsx`) reuses the same dispatch and shows an autocomplete menu for a curated subset: `/kb`, `/status`, `/new-goal`, `/agents`, `/reindex`, `/curate`, `/help`. The full command set below works in any room/DM input regardless of the menu.
+
+---
+
+## 5. Main flow
+
+```mermaid
+flowchart TD
+  A["Operator types a message"] --> B{"starts with '/'\nand channel != telegram?"}
+  B -- "no" --> C["Normal path:\n@mention routing / KB auto-route"]
+  B -- "yes" --> D["runSlashCommand(orgId, wsId, agents, channel, raw)"]
+  D --> E["ensureActiveSession + split cmd / rest"]
+  E --> F{"switch (cmd)"}
+  F --> G["postOp: echo operator input"]
+  G --> H["Run the action\n(plan-ops / work-ops / kb / rag / github / …)"]
+  H --> I["post result as system or a named agent"]
+  I --> J["done(): wake(wsId)\nreturn { handled:true, responders }"]
+  J --> K{"responders non-empty?"}
+  K -- "yes" --> L["Agent replies next\n(ada / reviewer)"]
+  K -- "no" --> M["Thread updated; no agent turn"]
+```
+
+---
+
+## 6. Key concepts 🪐
+
+| Concept | Meaning |
+| --- | --- |
+| `cmd` | The lower-cased token before the first space (e.g. `/approve`). |
+| `rest` | Trimmed text after the first space — the command argument. |
+| `responders` | Agent handles that should reply after the command (handoff). |
+| `postOp` | Inserts your raw input as a `fromKind: operator` message. |
+| `post` | Inserts the result as `fromKind: agent` with a `fromHandle` (often `system`). |
+| `kind` | Optional message render hint: `kb-card`, `agent-card`, `cleared`. |
+| `sources` | Citation references attached to KB answers. |
+| `done()` | Internal helper: calls `wake(wsId)` and returns `{ handled:true, responders }`. |
+
+---
+
+## 7. The command catalogue (one big table) ✦
+
+Every command parsed by `runSlashCommand`, grouped by category. "Responds as" is the `fromHandle` of the result message; "Hands off" is the agent in the returned `responders` array (replies next).
+
+### Help & info
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/help` | — | Posts the full command list. | `system` | — |
+| `/status` | — | Counts active goals, open issues (col ≠ `done`) and tasks in flight (col = `doing`). | `system` | — |
+| `/agents` | — | Lists the roster: `@handle — name (role, status)`. | `system` | — |
+| `/agent <handle>` | `<handle>` (with or without `@`) | Inspects one agent: name, role, status, health, runtime (adapter / model) + link to Agent Studio. | the agent's own handle (card) | — |
+
+### Knowledge & memory nebula 🌠
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/kb` (`/ask-kb`) | `<question>` | Asks the Knowledge Base via `kbAnswer`; answers with references (`sources`). Overview answers render as a `kb-card`. Schedules a chat reindex. | `vannevar` | — |
+| `/search <q>` | `<query>` | Same engine as `/kb` (`kbAnswer`) — a search-flavoured alias with its own empty-arg prompt. | `vannevar` | — |
+| `/graph <key>` | spec key, issue key, or goal-title substring | Resolves the seed (spec → issue → goal) and shows connected knowledge via `relatedKnowledge`, grouped by type. | `vannevar` | — |
+| `/reindex` | — | Rebuilds the RAG/KB index now (`indexRag`); reports chunk count and whether semantic or keyword-fallback. | `vannevar` | — |
+| `/curate` | — | Runs Vannevar's KB curation pass (`runKbCuration`): dedup / retire / re-summarise / find gaps. Budget-gated. Details to `Reports/kb-health.md`. | `vannevar` | — |
+
+### Work lifecycle 🚀
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/new-goal` (`/new-work`) | `<brief>` | Hands the brief to the CEO via the normal new-work pipeline (re-sends as `@ada <brief>`). Schedules a chat reindex. | (operator echo) | `ada` |
+| `/generate-plan` | `<brief>` (optional) | Calls `generatePlanFor` — drafts specs → issues → TODOs into the CEO Planner for approval. | `ada` | — |
+| `/approve` | — | Approves the pending plan (`approvePlanFor`) and queues tasks; reports the count. | `system` | — |
+| `/reject` | `<reason>` (optional) | Sends the plan back to the CEO (`requestPlanChangesFor`); records the reason if given. | `system` | — |
+| `/run-247` (`/resume`) | — | Turns 24/7 autonomous execution **ON** (`setAuto247For(..., true)`). | `system` | — |
+| `/pause` | — | Turns 24/7 autonomous execution **OFF** (`setAuto247For(..., false)`). | `system` | — |
+| `/cancel` | — | Cancels the most recent **active** goal (`cancelGoalFor`); execution stops. | `system` | — |
+| `/archive` | — | Archives the most recent **active** goal (`archiveGoalFor`); reports the archive path. | `system` | — |
+| `/close-sprint` | — | Closes the sprint (`closeSprintFor`): counts shipped vs carried, writes a retro file. | `donald` | — |
+
+### Board items
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/new-issue <title>` | `<title>` | Creates a single issue (`col: todo`, `prio: med`) with an auto-incremented numeric key. | `system` | — |
+| `/new-spec <title>` | `<title>` | Creates a single spec with key `SPEC-NN` (zero-padded). | `system` | — |
+| `/assign <issue> <@agent>` | `<issue-key> <@agent>` | Sets `issue.assigneeId` to the named agent. | `system` | — |
+
+### Gates, pipelines & integrations 🛰️
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/test-dev` | — | Runs the Test Dev validation gate (`runTestDevAction`); reports `PASS`/`FAIL`/`INCONCLUSIVE` + summary. | `edsger` | — |
+| `/review` | `<note>` (optional) | Picks a reviewer (CyberSec/QA role, else `whitfield`) and asks them to review recent board changes. | (operator echo) | the reviewer (e.g. `whitfield`) |
+| `/github` | — | Refreshes the repository status (`refreshGitStatus`); reports the count of changed files. | `werner` | — |
+| `/prepare-deploy` | — | Runs the Prepare-Deploy pipeline (`runDeployPipeline`); reports status + summary. | `werner` | — |
+| `/export-source <repo>` | `<github-repo>` | Exports the clean product source to a separate repo (`exportCleanSource`); blocks on secret findings. | `werner` | — |
+| `/telegram` | — | Reports Telegram integration status (`getTelegramConfig`). | `system` | — |
+| `/models` | — | Reports local-model status: llama.cpp (`llamaServerStatus`) + Ollama (`ollamaInfo`). | `system` | — |
+| `/skills` | — | Reports the skills library size + a sample of names (`allLibrarySkillNames`). | `system` | — |
+| `/locks` | — | Lists file locks currently held (`activeLocks`): `path — @agent`. | `system` | — |
+
+### Maintenance
+
+| Command (aliases) | Args | What it does | Responds as | Hands off |
+| --- | --- | --- | --- | --- |
+| `/clear` | `confirm` \| `yes` \| `sim` | Permanently deletes EVERY message, the compacted summary and run events **for this channel**. Requires a confirm token; otherwise posts a warning. Board/goals/specs/KB are NOT affected. | `system` (`cleared` kind) | — |
+| _unknown_ | — | Any other `/token` echoes and replies `Unknown command — Try /help`. | `system` | — |
+
+---
+
+## 8. Aliases at a glance
+
+| Canonical | Aliases |
+| --- | --- |
+| `/kb` | `/ask-kb` |
+| `/new-goal` | `/new-work` |
+| `/run-247` | `/resume` |
+
+> Note: `/cancel` and `/archive` share one `case` block but are **distinct** commands (different effects), not aliases of each other.
+
+---
+
+## 9. Step-by-step
+
+### Approve a plan and start the team
+
+1. In the Team Room, type `/approve`.
+2. The server runs `approvePlanFor` and posts `✅ Plan approved — N task(s) queued.` as `system`.
+3. Type `/run-247` to flip 24/7 autonomous execution ON.
+4. Watch progress with `/status` and `/locks`.
+
+### Ask the memory nebula
+
+1. Type `/kb how does the calculation engine work?` (or just the plain question in the room).
+2. Vannevar answers with `sources`; an overview answer renders as a `kb-card`.
+3. If knowledge feels stale, run `/reindex`, then `/curate`.
+
+### Inspect a working constellation
+
+1. `/agents` to see the roster.
+2. `/agent margaret` for runtime details + an Agent Studio link.
+3. `/locks` to see which files agents are holding.
+
+---
+
+## 10. Examples
+
+```text
+/help
+/status
+/agents
+/agent ada
+/kb how does auth work?
+/ask-kb where are sessions stored?
+/search rate limiting
+/graph SPEC-01
+/reindex
+/curate
+/new-goal a billing page with Stripe checkout
+/new-work add 2FA to the login screen
+/generate-plan migrate the database to Postgres
+/approve
+/reject the spec is missing the refund flow
+/run-247
+/resume
+/pause
+/cancel
+/archive
+/new-issue add a logout button
+/new-spec billing architecture
+/assign 3 @margaret
+/test-dev
+/review focus on the new payment endpoint
+/github
+/prepare-deploy
+/export-source myorg/constella-public
+/telegram
+/models
+/skills
+/locks
+/close-sprint
+/clear
+/clear confirm
+```
+
+---
+
+## 11. Possible states 🕳️
+
+| Situation | What you see |
+| --- | --- |
+| Empty arg on a command that needs one | A usage hint (e.g. `Ask a question, e.g. /kb …`). |
+| `/agent <handle>` not on roster | `No agent @handle on the roster. Use /agents …`. |
+| `/cancel` / `/archive` with no active goal | `No active goal to cancel/archive.`. |
+| `/assign` malformed | `Usage: /assign <issue-key> <@agent> …`. |
+| `/assign` unknown issue / agent | `No issue #key …` / `No agent @handle …`. |
+| `/graph` no match | `No goal / spec / issue matches …`. |
+| `/graph` match but no connections yet | `No connected knowledge for … yet`. |
+| `/reindex` with embed server down | `… (keyword fallback — embed server down).`. |
+| `/curate` nothing to do / no budget | `Nothing to curate right now …`. |
+| `/export-source` blocked by secrets | `🛑 Export blocked — N secret finding(s).`. |
+| `/clear` without confirm | A `⚠️` warning; nothing deleted. |
+| Unknown command | `Unknown command — Try /help`. |
+
+---
+
+## 12. Related integrations
+
+- **Plan / work ops** — `/approve`, `/reject`, `/run-247`, `/pause` call shared cores in `src/server/plan-ops.ts` and `src/server/work-ops.ts`, the same ones used by the [Public API](./PUBLIC_API.md) and [Telegram](./TELEGRAM.md).
+- **Knowledge Base / RAG** — `/kb`, `/search`, `/graph`, `/reindex`, `/curate` route into [KB_AGENT.md](./KB_AGENT.md), [KB_RAG.md](./KB_RAG.md) and [MEMORY_RAG.md](./MEMORY_RAG.md).
+- **Pipelines** — `/test-dev` → [TEST_DEV.md](./TEST_DEV.md); `/prepare-deploy` + `/export-source` → [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md) and [DEPLOY.md](./DEPLOY.md); `/github` → [GITHUB.md](./GITHUB.md).
+- **Models & skills** — `/models` → [MODELS.md](./MODELS.md); `/skills` → [SKILLS.md](./SKILLS.md).
+
+---
+
+## 13. Security 🔒
+
+- Slash commands run **server-side** under the operator's session — the message-send path resolves the org/workspace before dispatch.
+- `/clear` is the only destructive command on conversation data and is **double-gated** (requires `confirm`/`yes`/`sim`). It never touches board work, goals, specs or the KB.
+- `/export-source` is **secret-scan gated** — it refuses to push if findings exist (see [SECURITY.md](./SECURITY.md)).
+- Telegram does **not** share this parser; its remote commands run through a separate allowlisted handler — see [TELEGRAM.md](./TELEGRAM.md).
+- Result text is truncated to 4000 chars on insert (`text.slice(0, 4000)`).
+
+---
+
+## 14. Troubleshooting
+
+| Symptom | Likely cause / fix |
+| --- | --- |
+| `/command` was treated as plain text | You typed it in the **Telegram** channel (uses a different handler) or with a leading space. Slash must be the first character. |
+| Plain text in the room "became" a `/kb` query | Expected: room auto-routes non-command, non-mention text to `/kb`. Prefix with `@handle` to talk to an agent instead. |
+| `/reindex` says "keyword fallback" | The embed server is down — start it (see [MEMORY_RAG.md](./MEMORY_RAG.md)). KB still works via keyword search. |
+| `/approve` / `/cancel` says "No workspace/active goal" | There is no pending plan or active goal yet — create work with `/new-goal` first. |
+| `/curate` does nothing | Needs a few KB entries **and** available budget. |
+| Unknown command | Check spelling and aliases above, or run `/help`. |
+
+---
+
+## 15. Related links
+
+- [DM.md](./DM.md) — direct messages with a single agent
+- [TEAM_ROOM.md](./TEAM_ROOM.md) — the shared room and @mention routing
+- [WORKFLOW.md](./WORKFLOW.md) — Goal → Spec → Issue → Plan → Execution lifecycle
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — board items created by `/new-issue` / `/new-spec`
+- [AGENTS.md](./AGENTS.md) — the roster behind `/agents` and `/agent`
+- [KB_AGENT.md](./KB_AGENT.md) · [KB_RAG.md](./KB_RAG.md) · [MEMORY_RAG.md](./MEMORY_RAG.md) — the memory nebula behind `/kb`, `/search`, `/graph`, `/reindex`, `/curate`
+- [TEST_DEV.md](./TEST_DEV.md) · [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md) · [GITHUB.md](./GITHUB.md) — the gates behind `/test-dev`, `/prepare-deploy`, `/github`
+- [TELEGRAM.md](./TELEGRAM.md) — the separate remote-control command set
+- [PUBLIC_API.md](./PUBLIC_API.md) — the same plan/work ops over HTTP