constella 0.1.0

package/docs/en/TEAM_ROOM.md

@@ -0,0 +1,285 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/TEAM_ROOM.md) · [✦ Constella](../../README.md)
+
+# Team Room — The Shared Constellation 🌌🛰️
+
+![](../assets/divider-orbit.svg)
+
+The **Team Room** is the single shared channel where the operator and the agent constellation talk in the open. A message must `@mention` a teammate to be answered; up to **three** stars light up per turn, and from there the conversation can relay itself agent-to-agent down a bounded **hand-off chain** until the work is reported back.
+
+## When to use
+
+- You want to **address one or more agents in the open** (the whole team can see the thread), as opposed to a private [DM](./DM.md).
+- You want to **kick off a hand-off** — ask QA to test, then have them ask the engineer to fix, then ask Docs to document — without micromanaging every step.
+- You want to turn a chat line into **new work** by asking the CEO (Ada) or a planner to "build / fix / change" something (the spec→issue→plan ritual; see [WORKFLOW](./WORKFLOW.md)).
+- You want the **traceability** of a message back to its board task → issue → goal.
+
+Use a **DM** (`dm:<handle>`) when you want a private 1:1 with one agent; use **[Telegram](./TELEGRAM.md)** when you're remote. The Team Room is the public square.
+
+## How it works ✦
+
+The Team Room is the `message` channel literally named **`"room"`**. Two server actions in `src/server/chat.ts` drive it, backed by the relay engine in `src/server/collab.ts`:
+
+| Function | File | Responsibility |
+|---|---|---|
+| `sendMessage(channel, text, attachments?)` | `chat.ts` | Stores the operator's message, parses `@mentions`, returns up to **3** responder handles. Intercepts slash commands first. |
+| `agentRespond(channel, handle)` | `chat.ts` | Runs one agent's reply via `replyInChannel`, then (in the room) fires the autonomous hand-off chain via `relayRoomMentions`. |
+| `replyInChannel(orgId, ws, channel, a, mode, handoff?)` | `collab.ts` | One real agent turn: builds the prompt, runs the CLI runtime, scrubs secrets, stores the reply, books cost. `mode` = `chat` or `work`. |
+| `relayRoomMentions(orgId, ws, fromHandle, text, depth, fired)` | `collab.ts` | Recursive hand-off: for each teammate the reply `@mentions`, have them **act** in work mode, then recurse on their reply's mention. |
+
+The flow is deliberately **chat-first**: nothing is faked. Each agent turn is a real `claude`/`codex` CLI process running with the workspace as its current directory (the FS jail), producing real output, booking real `costEntry` rows.
+
+### Channels at a glance
+
+The `message.channel` column distinguishes where a message lives:
+
+| `channel` value | Meaning | Responders |
+|---|---|---|
+| `room` | The Team Room (this doc) | The `@mentioned` handles, max 3 |
+| `dm:<handle>` | A private 1:1 with one agent | Always that handle |
+| `telegram` | The isolated remote thread | Always the CEO (`ada`), falls back to the first agent |
+
+## Main flow 🌠
+
+```mermaid
+sequenceDiagram
+    actor Op as Operator
+    participant Room as Team Room (channel "room")
+    participant Send as sendMessage
+    participant Resp as agentRespond
+    participant Reply as replyInChannel
+    participant Relay as relayRoomMentions
+
+    Op->>Send: "@edsger please test the login flow"
+    Send->>Send: mentions() → ["edsger"] (max 3)
+    Send->>Room: insert operator message (fromKind=operator)
+    Send-->>Resp: responders = ["edsger"]
+    Resp->>Reply: edsger, mode "chat"
+    Reply->>Room: insert edsger reply ("Failing — @margaret please fix login")
+    Resp->>Relay: relayRoomMentions(from=edsger, text, depth 0)
+    Relay->>Reply: margaret, mode "work", handoff={from:edsger}
+    Reply->>Room: insert margaret reply ("Fixed. @barbara document it")
+    Relay->>Reply: barbara, mode "work", handoff={from:margaret}
+    Reply->>Room: insert barbara reply (no mention → chain ends)
+```
+
+1. The operator posts a message. `sendMessage` checks for a leading `/` (slash command) — if so it is dispatched to `runSlashCommand` and the normal path is skipped.
+2. Otherwise `sendMessage` extracts `@mentions`, keeps only handles that are **real agents**, and slices to the first **3**. If none match, **nothing is posted as a responder set** (`return { responders: [] }`) — the room never holds a dead-end message.
+3. The operator message is stored (`fromKind: "operator"`), the SSE stream is woken (`wake`), the chat is scheduled for RAG re-index, and — if the message is substantive (≥15 chars) — it is logged as a **decision** (`source: "operator-instruction"`).
+4. The UI calls `agentRespond` for each responder. Each runs `replyInChannel` in **`chat`** mode (conversational, no file edits) and the reply is stored.
+5. In the room, `agentRespond` then calls `relayRoomMentions` — the autonomous hand-off chain. Relayed agents run in **`work`** mode (they may read/edit/run files), and the chain continues to whoever they `@mention`.
+
+## Key concepts ✦
+
+### `@mentions` and the max-3 rule
+
+A Team Room message is only answered if it `@mentions` a real teammate. The regex is `@([a-z0-9-]+)`:
+
+- In `sendMessage`, `mentions(text)` lowercases each handle, filters to known agents, and **`.slice(0, 3)`** — at most three agents respond to a single operator message.
+- The client-side composer blocks an un-mentioned post; the server check is the authoritative guard.
+- `@operator` is a special target: when an agent `@mentions @operator`, no agent fires (operator isn't an agent) but a persistent notification + Inbox item is raised (see [INBOX](./INBOX.md)).
+
+### `chat` mode vs `work` mode
+
+`replyInChannel` takes a `mode`:
+
+| Mode | Used by | Behaviour |
+|---|---|---|
+| `chat` | The direct response to an operator mention (`agentRespond`) | "Reply in 1-3 sentences as yourself. **Do not modify files.**" Conversational only. |
+| `work` | Relayed hand-offs (`relayRoomMentions`) | "Do what's needed in the workspace now… then post a SHORT update… END by `@mentioning` EXACTLY ONE teammate with a concrete ask." The agent reads/edits/runs files. |
+
+In `work` mode, when a hand-off is present the prompt makes it explicit: *"Your teammate `@<from>` just handed off to YOU… that hand-off IS your instruction — there is NO separate operator message."* This fixed the "I don't see a message from the operator" confusion.
+
+### The hand-off chain (relay)
+
+`relayRoomMentions` is the autonomous backbone. It is **bounded by design** so a single mention can never fan out into runaway token spend:
+
+| Constant | File | Value | Effect |
+|---|---|---|---|
+| `MAX_DEPTH` | `collab.ts` | `2` | The chain stops after 2 hops. |
+| `MAX_FANOUT` | `collab.ts` | `1` | A single message hands off to **one** teammate, not many — it's a chain, not a tree. |
+
+Additional relay guards (all in `collab.ts`):
+
+- **`fired` set** — each agent is relay-fired at most **once per chain**.
+- **Never re-fire the sender** — the agent who just spoke is excluded (`h !== fromHandle`).
+- **`busyOnBoard`** — an agent with status `working`, or who owns a board task in column `doing`, is **skipped**. A "doing" task is that agent's coordinated unit of work; a parallel relay would have them re-edit the same files (the "same agent keeps touching the same file" chaos).
+- **`agentAtCap`** — an agent over its `dailyCapUsd` budget is skipped (see [MODELS](./MODELS.md) for caps).
+- **`isNoisePing`** — a content-free ping (only mentions/emoji/punctuation, or filler like "on it", "got it", "done") does **not** trigger a hand-off. The stored message is untouched; only the relay is governed.
+- **`sanitizeForRelay`** — collapses emoji runs in the context the next agent sees.
+
+### Decisions
+
+A substantive operator line in the room is a directive the agents must honor, so it is recorded in the durable `decision` log (`logDecision`, `src/server/decisions.ts`):
+
+- Triggered when `channel === "room"` and `text.trim().length >= 15`.
+- Stored with `by: "operator"`, `source: "operator-instruction"`.
+- Mirrored into the Knowledge Base as a `decision` entry (best-effort), so any agent recalls it via state-aware retrieval (see [KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md)).
+
+The Context Manager surfaces the decision log to every agent regardless of model, keeping continuity across runs.
+
+### Attachments
+
+The operator can attach up to **10** files per message (photos / PDF / docs). They are saved under `uploads/` in the workspace (so the agent can read them with its file tools) and stored as JSON on the `message.attachments` column. In `replyInChannel`, the last 6 messages' attachment paths (capped at 12) are injected into the prompt as **data, not instructions** — a filename can't smuggle a directive (`<<attached-files>>` block).
+
+### Task traceability
+
+When the **runner** posts a task result to the room (`src/server/runner.ts`), it sets `message.taskId`. `taskRef(taskId)` in `chat.ts` resolves the chip:
+
+```
+task key · issue key · goal title · column
+```
+
+So a room post that came from board work links back to its `task` → `issue` → `goal`, and the column (`triage|todo|doing|blocked|review|done`). See [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md).
+
+### Knowledge capture in chat
+
+Inside `replyInChannel`, agent replies are scanned for KB tokens (each on its own line, wrapped in double square brackets):
+
+- `[[REMEMBER type=<…>: <fact>]]` → ingested into the KB (deduped), token stripped from the shown reply.
+- `[[CONSULT: <question>]]` → answered by Vannevar into the same thread (posted as a `🔎 KB consult` message), available next turn.
+- `[[KB: reindex|index-chat|health]]` → only for the Knowledge agent; results posted as `🛠️ KB tools`.
+
+See [KB_AGENT](./KB_AGENT.md) and [KB_RAG](./KB_RAG.md) for the full token grammar.
+
+### Turning chat into new work
+
+In `chat` mode, the prompt lets **any** agent turn an explicit build request into new work. If the operator asks to BUILD / IMPLEMENT / ADD / FIX / CHANGE something, the agent confirms briefly and outputs the machine token `[[CREATE_WORK]]` on a final line. `agentRespond` detects `planRequested`, strips the token, and runs `planFromConversation` — the same spec→issue→plan ritual as the first plan, waiting for operator approval. See [WORKFLOW](./WORKFLOW.md) and [PO_AGENT](./PO_AGENT.md).
+
+## Tables 🪐
+
+### `message` (the room's spine — `src/db/schema.ts`)
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | text PK | UUID |
+| `workspaceId` | text | FK → `workspace`, cascade delete |
+| `channel` | text | `room` \| `dm:<handle>` \| `telegram` (default `room`) |
+| `fromKind` | enum | `operator` \| `agent` |
+| `fromHandle` | text | agent handle (NULL for operator) |
+| `text` | text | message body (replies stored ≤4000 chars) |
+| `sources` | json `string[]` | workspace files the agent retrieved (RAG) to produce this reply → source chips |
+| `attachments` | json | `{ name, type, size, path }[]`, ≤10/message |
+| `sessionId` | text | DM session (`chat_session`); NULL for room/Telegram |
+| `taskId` | text | the board task this message reports on → traceability chip |
+| `kind` | text | render hint (e.g. `kb-card`); NULL = normal message |
+| `blocks` | json `string[]` | synced-block slugs a reply proposed an edit to (see [SYNCED_BLOCKS](./SYNCED_BLOCKS.md)) |
+| `createdAt` | timestamp | default `unixepoch()` |
+
+Index: `msg_ws_chan_idx` on `(workspaceId, channel)`.
+
+### `decision` (`src/db/schema.ts`)
+
+| Column | Notes |
+|---|---|
+| `text` | the decision (operator instruction, ≤400 chars from the room line) |
+| `by` | `operator` or an agent handle |
+| `source` | `operator-instruction` here; also `plan-approve` \| `issue-block` \| `spec-reject` \| `task-done` |
+| `rationale`, `refKey`, `goalId` | optional links for jump-back |
+
+### `messageSummary` & `event`
+
+| Table | Role |
+|---|---|
+| `messageSummary` | Compacted summary of older messages per `(workspace, channel, sessionId)` — feeds the Context Manager so long threads don't blow the model's window. Wiped on `clearConversation`. |
+| `event` | Live runtime steps streamed from an agent run (`read`/`create`/`edit`/`run`/`search`/`thinking`/`text`/`done`), grouped by `runId` into Team Room **work-blocks**. Pruned by `pruneRunEvents`. |
+
+## Diagram — mention → responders → hand-off 🛰️
+
+```mermaid
+flowchart TD
+    A["Operator posts in room"] --> B{"Starts with '/'?"}
+    B -- "yes" --> C["runSlashCommand"]
+    B -- "no" --> D["mentions() → real handles"]
+    D --> E{"any handle?"}
+    E -- "no" --> X["no responders — nothing posted"]
+    E -- "yes" --> F["slice(0,3) responders"]
+    F --> G["store operator msg + logDecision if ≥15 chars"]
+    G --> H["agentRespond per responder (chat mode)"]
+    H --> I["relayRoomMentions(depth 0)"]
+    I --> J{"reply @mentions a teammate?"}
+    J -- "no / noise ping" --> K["chain ends"]
+    J -- "yes" --> L{"guards: fired? busyOnBoard? atCap? depth<MAX_DEPTH?"}
+    L -- "blocked" --> K
+    L -- "ok" --> M["teammate replies in WORK mode (handoff context)"]
+    M --> I
+```
+
+## Step-by-step
+
+1. **Mention a teammate.** Type `@edsger run the e2e suite on the checkout flow` in the room. The composer requires at least one valid `@handle`.
+2. **Up to 3 respond.** `@margaret @grace @edsger triage this bug` lights up all three; a fourth mention is dropped by `.slice(0, 3)`.
+3. **Watch the hand-off.** If Edsger replies "Failing — `@margaret` please fix the null check", Margaret is fired in **work** mode with Edsger's message as explicit hand-off context, edits the file, and replies "Fixed — `@barbara` document the change."
+4. **Chain ends.** After `MAX_DEPTH` (2) hops, or when a reply mentions no one (or only emits a noise ping), the relay stops.
+5. **Ask the operator.** When an agent needs your call, it ends with `@operator` — you get an Inbox item + notification, not another agent turn.
+6. **Promote to KB.** Use the per-message action to send a useful line to the Knowledge Base (`sendMessageToKb` → a `note` entry).
+7. **Clear it.** "Clear conversation" on the Welcome Home calls `clearConversation("room")` — deletes the room's messages, its summary, and its run events.
+
+## Examples
+
+```text
+# A bounded QA → fix → docs chain (3 hops would be capped at 2):
+Operator: @edsger smoke-test the new /settings page
+Edsger:   404 on save — @margaret the PUT handler is missing
+Margaret: Added the handler + test, green now — @barbara update the API doc
+# chain ends at depth 2 (barbara's reply, if it mentions anyone, is NOT relayed)
+
+# Address the human for a decision:
+Grace: Two layout options attached — @operator which do you prefer?
+# → Inbox "question" item + notification; no agent fires
+
+# Turn a request into new work (any agent, runs the ritual):
+Operator: @ada add a CSV export to the reports page
+Ada:      Got it — I'll turn this into a spec + issues for your approval.
+# (Ada emits [[CREATE_WORK]] internally → planFromConversation → CEO Planner)
+```
+
+## Possible states
+
+| State | Where | Meaning |
+|---|---|---|
+| no responders | `sendMessage` returns `{ responders: [] }` | message `@mentioned` no real agent → nothing answers |
+| responding | agent `status = working` | the agent's CLI run is in flight |
+| relayed | `relayRoomMentions` fires a teammate | hand-off in work mode |
+| chain end | `depth >= MAX_DEPTH`, no mention, or noise ping | the autonomous chain stops |
+| skipped (busy) | `busyOnBoard` true | agent already executing a board task → not relay-fired |
+| skipped (cap) | `agentAtCap` true | agent over `dailyCapUsd` → not relay-fired |
+| addressed-to-operator | `@operator` detected | Inbox + notification raised, no agent fires |
+| failed | reply stored as `(<name> couldn't respond: …)` | the CLI run errored or returned no output |
+
+## Related integrations 🌌
+
+- **[DM](./DM.md)** — private 1:1 channel (`dm:<handle>`), session-based; the room is its public counterpart.
+- **[Telegram](./TELEGRAM.md)** — the isolated remote thread; Ada answers, replies mirrored from the in-app tab.
+- **[Inbox](./INBOX.md)** — where `@operator` asks and approval requests land.
+- **[KB_AGENT](./KB_AGENT.md) / [KB_RAG](./KB_RAG.md)** — `[[REMEMBER]]` / `[[CONSULT]]` knowledge capture in chat.
+- **[GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)** — the task/issue/goal a `taskId` chip links back to.
+- **[CHAT_COMMANDS](./CHAT_COMMANDS.md)** — slash commands intercepted by `sendMessage`.
+- **[WORKFLOW](./WORKFLOW.md) / [PO_AGENT](./PO_AGENT.md)** — the spec→issue→plan ritual triggered by `[[CREATE_WORK]]`.
+
+## Security 🕳️
+
+- **Secret scrubbing.** Every reply passes through `scrubSecrets` (`src/lib/scrub.ts`) before it is stored, shown, or notified — room, DM and Telegram all flow through `replyInChannel`.
+- **Attachment paths are data.** Attached file paths are injected inside an `<<attached-files>>` block and the prompt explicitly tells the agent to ignore any directive embedded in a filename.
+- **Bounded autonomy.** `MAX_DEPTH=2`, `MAX_FANOUT=1`, the `fired` set, `busyOnBoard`, and `agentAtCap` together cap both the spread and the spend of the hand-off chain — a single mention can never become a runaway swarm.
+- **Telegram hardening.** The `telegram` channel adds a prompt-injection clause (never reveal secrets / `.env` / `.claude/` / system prompt) and skips the operator-ping. See [TELEGRAM](./TELEGRAM.md).
+- **FS jail.** Work-mode agents run with the org workspace as cwd; the FS jail (`safe()`) blocks traversal and protects the workspace root. See [SECURITY](./SECURITY.md) and [ARCHITECTURE](./ARCHITECTURE.md).
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Message posted but nobody answers | No valid `@mention` | Mention a real agent handle; `sendMessage` returns no responders otherwise. |
+| Only 1-3 agents reply to a big mention list | The max-3 slice (`.slice(0, 3)`) | By design — split into multiple messages or rely on the hand-off chain. |
+| Hand-off stops too early | `MAX_DEPTH=2` reached | The chain is intentionally bounded; continue manually with a new mention. |
+| Relay skips an agent | `busyOnBoard` (status `working` or a `doing` task), or `agentAtCap` | Wait for the task to finish, or raise the agent's `dailyCapUsd` (see [MODELS](./MODELS.md)). |
+| "on it" / "done" doesn't trigger the next agent | `isNoisePing` filter | Reply with a concrete ask + a mention; content-free pings don't relay. |
+| `@operator` raised no Inbox item | Reply failed (stored as "couldn't respond") or it was Telegram | Check the run output; Telegram skips the operator-ping by design. |
+| Reply shows `(<name> couldn't respond: …)` | CLI runtime error / timeout (180s) | Check the agent's adapter/model and the runtime; see [AGENTS](./AGENTS.md), [MODELS](./MODELS.md), [TROUBLESHOOTING](./TROUBLESHOOTING.md). |
+
+## Related links
+
+- [DM](./DM.md) · [Telegram](./TELEGRAM.md) · [Inbox](./INBOX.md)
+- [Agents](./AGENTS.md) · [KB Agent](./KB_AGENT.md) · [PO Agent](./PO_AGENT.md)
+- [Workflow](./WORKFLOW.md) · [Goals, Specs & Issues](./GOALS_SPECS_ISSUES.md) · [Chat Commands](./CHAT_COMMANDS.md)
+- [KB & RAG](./KB_RAG.md) · [Memory & RAG](./MEMORY_RAG.md) · [Synced Blocks](./SYNCED_BLOCKS.md)
+- [Architecture](./ARCHITECTURE.md) · [AI Architecture](./AI_ARCHITECTURE.md) · [Security](./SECURITY.md) · [Troubleshooting](./TROUBLESHOOTING.md)

package/docs/en/TELEGRAM.md

@@ -0,0 +1,294 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/TELEGRAM.md) · [✦ Constella](../../README.md)
+
+# 🛰️ Telegram — the pocket bridge to your constellation
+
+![](../assets/divider-orbit.svg)
+
+A single private Telegram chat becomes a remote bridge to your agent-company: talk to the CEO (Ada), approve plans, start or pause 24/7 execution, kick off new work, and query the Knowledge Base — all from your phone, while the control ship keeps running headless.
+
+> Source of truth: `src/server/telegram.ts` (ingest + commands + callbacks), `src/lib/telegram.ts` (Bot API client + token shape), `bin/worker.mjs` (long-poll loop), `src/app/api/telegram/poll/route.ts` (worker-only entry), `src/server/actions/profile-actions.ts` (`connectTelegram`), `src/lib/scrub.ts` (secret scrub).
+
+---
+
+## 2. What it is
+
+A bidirectional Telegram bot, scoped to **one** allowlisted private chat per workspace. Inbound messages reach the CEO agent over an **isolated** channel (`telegram`), and a set of slash-commands + inline buttons act as a real remote control over the work lifecycle. Outbound: agent replies typed in the in-app Telegram tab are mirrored back to the phone, so the thread stays single regardless of where you type.
+
+## 3. When to use 🌠
+
+- You are away from the control ship but want to **check status**, **approve a pending plan**, or **flip 24/7 execution** on/off.
+- You want to **start new work** from a one-line brief (`/new …`) and let the CEO turn it into specs · issues · TODOs.
+- You want to **ask the Knowledge Base** a question (`/kb …`) without opening the app.
+- You want to **chat with the CEO** (Ada) like any DM, but from your phone.
+
+Telegram is optional. It is a native plugin and the integration toggle (`settings.integrations.telegram`) defaults **ON**, but nothing happens until you connect a bot token + chat id from the Profile screen. If unconfigured, every Telegram path is an honest no-op.
+
+## 4. How it works 🌌
+
+### The two processes
+
+Constella runs a **web** process (Next.js) and a separate **worker** (`bin/worker.mjs`). Telegram polling lives in the worker:
+
+- The worker runs `telegramLoop()` — an infinite loop that POSTs `BASE/api/telegram/poll` with the privileged `x-worker-secret` header.
+- That route (`src/app/api/telegram/poll/route.ts`) is **fail-closed**: it requires `CONSTELLA_WORKER_SECRET` and returns `401` if the header is missing/wrong. On `401`, the worker backs off 30s (treated as "not configured / secret mismatch").
+- The route calls `pollTelegram()` (in `src/server/telegram.ts`), which does the real work, then returns `{ ok, updates }`.
+
+### Long-polling, per workspace
+
+`pollTelegram()` iterates **every** workspace. For each one it:
+
+1. Skips the workspace if the integration is off (`integrationOn(settings.integrations, "telegram")` — see `src/lib/integrations.ts`).
+2. Loads the vaulted config via `getTelegramConfig(ws.id)`; skips if absent or the token is malformed.
+3. Registers the bot's `/` command menu **once per bot per process** (`tgSetMyCommands`, guarded by an in-memory `commandsRegistered` set).
+4. Calls `tgGetUpdates(token, offset)` — Telegram `getUpdates` with `timeout=25` (a ~25s **server-side long-poll**) and `allowed_updates=["message","callback_query"]`.
+5. Ingests each update, advances the cursor (`maxId = update_id + 1`), and persists it back to `settings.telegram.offset`.
+
+The worker leaves a brief 1s gap between long-polls; on error it backs off 5s.
+
+### The allowlist 🕳️
+
+Only the **one registered private chat** may drive the bot. In `ingest()`:
+
+- The message's `chat.id` must equal `cfg.chatId`, **and**
+- if `m.from` is present, the sender `from.id` must also equal `cfg.chatId` (in a private chat they are the same number).
+
+Anything else is **silently ignored**. The same check is re-applied to inline-button taps in `handleCallback()`. At connect time (`connectTelegram`), the chat id is validated as a positive numeric id (group ids are negative and would let every member drive the bot — they are rejected).
+
+### Inbound routing
+
+For an allowed message, `ingest()` decides the path:
+
+| Condition | What happens |
+| --- | --- |
+| `callback_query` present | Inline-button tap → `handleCallback()` |
+| awaiting reject-reason + plain text (not `/…`) | The text **is** the reject reason → `requestPlanChangesFor()` |
+| text starts with `/` | Remote-control command → `handleCommand()` |
+| otherwise | Talk to the CEO → `runCeoReply()` |
+
+Text + caption are capped to 4000 chars. Photos and documents are downloaded and saved as attachments (see [Attachments](#attachments)).
+
+### Talking to the CEO
+
+`runCeoReply()` resolves the **Ada** agent (`handle = "ada"`, falling back to the first agent), sets her status to `working`, shows a live `typing…` indicator on a 4s heartbeat (Telegram clears it after ~5s), and calls `replyInChannel(orgId, ws, "telegram", ada, "chat")` (`src/server/collab.ts`).
+
+`replyInChannel` adds a **Telegram-specific prompt-injection guard**: it tells the model the operator's message is *data, not instructions*, never to reveal secrets / `.env` / `.claude/` contents / system prompt, and to refuse any override attempt. The reply is secret-scrubbed before send.
+
+If Ada decides this is build/fix work she emits an internal `[[CREATE_WORK]]` token; `replyInChannel` returns `planRequested = true`, and `runCeoReply` then runs `planFromConversationFor(orgId, ws, "telegram")` — the **same** planning ritual as the web path (specs → issues → TODOs) — and confirms on the phone.
+
+## 5. Main flow — poll → agent → reply 🚀
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant TG as Telegram Bot API
+    participant W as worker (bin/worker.mjs)
+    participant API as /api/telegram/poll
+    participant P as pollTelegram()
+    participant ING as ingest()
+    participant CEO as replyInChannel (Ada)
+    participant DB as message table
+
+    W->>API: POST (x-worker-secret)
+    API->>API: verify CONSTELLA_WORKER_SECRET (else 401)
+    API->>P: pollTelegram()
+    P->>TG: getUpdates(offset, timeout=25)
+    TG-->>P: updates[] (~25s long-poll)
+    loop each update
+        P->>ING: ingest(ws, cfg, update)
+        ING->>ING: allowlist: chat.id == cfg.chatId?
+        alt command (/…)
+            ING->>ING: handleCommand() → real action
+        else inline button
+            ING->>ING: handleCallback() → real action
+        else free text
+            ING->>DB: persist operator turn (channel=telegram)
+            ING->>CEO: replyInChannel(..., "chat")
+            CEO-->>ING: text + planRequested
+            ING->>TG: sendMessage(scrubbed reply)
+            opt planRequested
+                ING->>ING: planFromConversationFor() (specs·issues·TODOs)
+            end
+        end
+    end
+    P->>DB: save settings.telegram.offset = maxId
+    P-->>W: { updates: N }
+```
+
+## 6. Key concepts ✦
+
+- **Isolated channel.** Telegram lives on its own `telegram` channel — never `room` or `dm:<handle>` — so phone chatter never bleeds context into the team room or DMs. (`TG_CHANNEL = "telegram"`.)
+- **Vaulted credentials.** The bot token + chat id are stored encrypted in the vault under ref `telegram_bot` as JSON `{botToken, chatId, allowedName}`. They are never persisted in plaintext settings.
+- **Offset cursor.** `settings.telegram.offset` is the Telegram update cursor; advancing it acknowledges processed updates so they are never re-delivered.
+- **Reject-reason wait.** An in-memory `awaitingReason` set remembers that you tapped the **↩️ Reject** button; your next free-text message becomes the reason. In-memory is fine — a server restart simply drops the pending wait (re-tap to retry).
+- **Command-menu registration.** `commandsRegistered` ensures `setMyCommands` runs once per bot per process — even bots connected before that feature existed get their menu on the next poll.
+- **Secret scrub.** Every outbound string passes through `scrubSecrets(text, [cfg.botToken])` (`src/lib/scrub.ts`) — redacting the bot token, the standard env secrets, and high-confidence credential shapes (OpenAI/Anthropic `sk-…`, GitHub tokens, AWS keys, JWTs, PEM keys, Constella `cn_…` PATs, and even other Telegram tokens).
+
+## 7. Tables
+
+### Telegram slash commands (`handleCommand`)
+
+| Command | Aliases | Action |
+| --- | --- | --- |
+| `/help` | — | Show the remote-control help text |
+| `/status` | — | `planStatusFor(ws)` — quick status |
+| `/review` | — | `reviewSummaryFor(ws)` — plan / issues / tasks summary |
+| `/tasks` | — | `tasksListFor(ws)` — what's in flight now |
+| `/approve` | — | `approvePlanFor()` — approve pending plan, queue tasks |
+| `/start_execution` | `/start`, `/run` | `approvePlanFor()` + `setAuto247For(true)` — approve and run 24/7 |
+| `/pause` | `/stop` | `setAuto247For(false)` — pause 24/7 |
+| `/resume` | — | `setAuto247For(true)` — resume 24/7 |
+| `/reject <reason>` | — | `requestPlanChangesFor()` — send plan back to the CEO |
+| `/new <brief>` | `/new-work`, `/new-goal` | Seed an operator turn + run the CEO → goal · specs · issues |
+| `/cancel` | — | `cancelGoalFor()` on the latest active goal — stops execution |
+| `/archive` | — | `archiveGoalFor()` on the latest active goal — zips + parks it |
+| `/kb <question>` | `/ask-kb` | `kbAnswer(orgId, q)` — ask the Knowledge Base |
+| *(unknown)* | — | Replies "Unknown command" + help |
+
+> The `/` menu Telegram shows is registered from `TG_BOT_COMMANDS` in `src/lib/telegram.ts` and must mirror `handleCommand`. The displayed menu omits aliases.
+
+### Inline-button callbacks (`handleCallback`)
+
+| `callback_data` | Action | Toast | One-shot? |
+| --- | --- | --- | --- |
+| `approve_plan` | `approvePlanFor()` | ✅ Approved | yes (keyboard stripped) |
+| `start_exec` | `approvePlanFor()` + `setAuto247For(true)` | ▶️ Executing | yes |
+| `reject_plan` | `requestPlanChangesFor()` + arm reject-reason wait | ↩️ Sent back | yes |
+| `review` | `reviewSummaryFor(ws)` | 📝 Review | no |
+| `status` | `planStatusFor(ws)` | 📊 Status | no |
+| `pause` | `setAuto247For(false)` | ⏸ Paused | no |
+| `resume` | `setAuto247For(true)` | ▶️ Resumed | no |
+| *(unknown)* | — | Unknown action | — |
+
+One-shot actions (`approve_plan` / `start_exec` / `reject_plan`) have their inline keyboard stripped via `tgClearButtons` so a second tap can't re-fire them.
+
+### Vaulted config & settings
+
+| Where | Key / column | Meaning |
+| --- | --- | --- |
+| vault | ref `telegram_bot` | encrypted JSON `{botToken, chatId, allowedName}` |
+| `workspace.settings` | `integrations.telegram` | integration toggle (defaults `true`) |
+| `workspace.settings` | `telegram.offset` | Telegram `getUpdates` cursor |
+
+### `message` rows written by Telegram
+
+| Column | Value on the Telegram path |
+| --- | --- |
+| `channel` | `"telegram"` (constant `TG_CHANNEL`) |
+| `fromKind` | `"operator"` (inbound) / `"agent"` (replies) |
+| `fromHandle` | `"system"` for control replies; Ada's handle for CEO replies |
+| `text` | message text or `"(attachment)"`, capped 4000 |
+| `attachments` | saved file descriptors, or `null` |
+
+## 8. Bot API surface 🪐
+
+All HTTP calls go through `src/lib/telegram.ts` against `https://api.telegram.org`. Every helper first checks `isTelegramToken()` — token shape `^\d{6,}:[A-Za-z0-9_-]{30,}$` — so a malformed value can never repoint the request URL.
+
+| Helper | Bot API method | Purpose |
+| --- | --- | --- |
+| `tgGetMe` | `getMe` | verify token → `@username` (at connect time) |
+| `tgSetMyCommands` | `setMyCommands` | register the `/` command menu |
+| `tgGetUpdates` | `getUpdates` | long-poll (`timeout=25`, `message` + `callback_query`) |
+| `tgGetFile` | `getFile` + `/file/bot…` | download a photo/document → bytes |
+| `tgSendChatAction` | `sendChatAction` | `typing…` indicator |
+| `sendTelegramTo` | `sendMessage` | plain-text reply (no Markdown) |
+| `sendTelegram` | `sendMessage` | notification send (Markdown) |
+| `sendTelegramButtons` | `sendMessage` + `inline_keyboard` | message with remote-control buttons |
+| `tgAnswerCallback` | `answerCallbackQuery` | ACK a button tap + optional toast |
+| `tgClearButtons` | `editMessageReplyMarkup` | strip a one-shot keyboard |
+
+Agent replies use `sendTelegramTo` (plain text, no `parse_mode`) on purpose — arbitrary content (issue titles, code, workspace names) must never break the send or be parsed as Markdown.
+
+## 9. Attachments
+
+Photos and documents on an inbound message are downloaded and stored in the workspace:
+
+- A short per-message download id is generated (`uid().slice(0,8)`).
+- Each file is fetched via `tgGetFile`, its name sanitized (`[^\w.\-]` → `_`, last 60 chars), and written to `uploads/tg-<dlId>/<safe-name>` under the **org root** (`orgRoot(ws.orgId)`).
+- An attachment descriptor `{name, type, size, path}` is appended to the persisted `message.attachments`.
+- Photos use the largest available size; documents keep their original `file_name` and `mime_type`.
+
+A message with neither text nor any saved attachment is dropped.
+
+## 10. Step-by-step — connect & drive 🛰️
+
+### Connect the bot (`connectTelegram`)
+
+1. Create a bot with Telegram's **@BotFather** and copy its token.
+2. Find your **personal numeric chat id** (a private chat — not a group).
+3. In Constella's **Profile** screen, enter the token + chat id (and an optional display name).
+4. `connectTelegram()` validates the token shape, rejects non-positive/group ids, calls `tgGetMe` to verify the token actually works, then stores `{botToken, chatId, allowedName}` in the vault and registers the `/` menu (`tgSetMyCommands`).
+5. The worker picks it up on its next poll — message the bot to confirm.
+
+> `telegramStatus()` powers the in-app card and masks the chat id (`12•••89`). `disconnectTelegram()` deletes the vault ref `telegram_bot`.
+
+### Drive it from the phone
+
+```text
+/status                      → quick status
+/review                      → full plan / issues / tasks summary
+/new a billing page with checkout
+                             → CEO drafts goal · specs · issues · TODOs
+/approve                     → queue tasks
+/start_execution             → approve + 24/7 ON
+/pause   /resume             → flip 24/7
+/reject use Stripe not PayPal→ send plan back with a reason
+/cancel  /archive            → stop / park the active goal
+/kb how does auth work?      → ask the Knowledge Base
+just talk normally           → chat with the CEO (Ada)
+```
+
+### Mirroring (in-app → phone)
+
+When you reply from the **in-app Telegram tab**, `src/server/chat.ts` calls `mirrorToTelegram(workspace.id, reply)`. It loads the vaulted config and sends the scrubbed reply out to the real chat — so the bot conversation stays a single thread regardless of where you typed.
+
+## 11. Possible states
+
+| State | Symptom | Cause |
+| --- | --- | --- |
+| **Unconfigured** | Bot never replies; poll route returns `401` then 30s back-off | no `telegram_bot` vault secret |
+| **Integration off** | Configured but ignored | `settings.integrations.telegram = false` |
+| **Connected** | Replies, commands and buttons work | valid token + matching chat id |
+| **Foreign chat** | Silence | sender / chat id ≠ `cfg.chatId` (silently ignored) |
+| **Awaiting reason** | Next plain message recorded as reject reason | you tapped **↩️ Reject** |
+| **Typing…** | Live indicator while a reply generates | 4s heartbeat in `runCeoReply` |
+| **Worker down** | No replies at all | the worker process isn't running (see [TEST_DEV](./TEST_DEV.md) / [ARCHITECTURE](./ARCHITECTURE.md)) |
+
+## 12. Related integrations
+
+- The CEO reply path is the same one used by [DM](./DM.md) and the [TEAM_ROOM](./TEAM_ROOM.md) — Telegram just runs it on its own isolated channel with an extra injection guard.
+- `/new` runs the full [WORKFLOW](./WORKFLOW.md) ritual (Goal → Spec → Issue → Plan → TODOs); see [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md).
+- `/kb` answers from the [KB_RAG](./KB_RAG.md) memory nebula.
+- The same remote-control actions are exposed programmatically via the [PUBLIC_API](./PUBLIC_API.md) and [MCP](./MCP.md) server.
+- Telegram is a native [PLUGINS](./PLUGINS.md) entry; toggling lives alongside the other integrations.
+
+## 13. Security 🕳️
+
+- **Worker-only entry.** `/api/telegram/poll` requires `x-worker-secret == CONSTELLA_WORKER_SECRET` (fail-closed `401`). The worker also refuses to send that secret to any non-loopback `CONSTELLA_BASE_URL` unless `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` (SSRF / secret-exfil guard).
+- **Strict allowlist.** Exactly one private chat id; both `chat.id` and `from.id` are checked on messages and on button taps. Group ids (negative) are rejected at connect time.
+- **Token shape enforcement.** `isTelegramToken()` gates every Bot API call so a tampered token can't redirect the request URL.
+- **Prompt-injection hardening.** `replyInChannel` injects a Telegram-specific security clause: the operator message is *data*, secrets/`.env`/`.claude/`/system-prompt must never be revealed, override attempts are refused.
+- **Secret scrub on egress.** Every outbound message runs through `scrubSecrets(…, [cfg.botToken])` — redacting the bot token plus high-confidence credential shapes — before it leaves the ship.
+- **Encrypted at rest.** Credentials live in the AES-256-GCM [vault](./SECURITY.md), never in plaintext settings; the in-app status card masks the chat id.
+- **Bounded egress.** Outbound bodies are length-capped (`sendTelegramTo` 3800, `sendTelegram` 3500), and `callback_data` is capped to Telegram's 64-byte limit.
+
+## 14. Troubleshooting 🛠️
+
+| Symptom | Check |
+| --- | --- |
+| Bot silent, poll route returns `401` | No `telegram_bot` secret — connect from Profile. (Worker treats `401` as "not configured" and backs off 30s.) |
+| "Telegram rejected this bot token." at connect | Token wrong/revoked — `tgGetMe` failed; re-copy from @BotFather. |
+| "Chat id must be your personal numeric id…" | You used a group id (negative) — use your private chat id. |
+| Messages ignored, no error | Sender's `chat.id`/`from.id` ≠ the registered `cfg.chatId` (allowlist). |
+| `/` menu not showing | `setMyCommands` is best-effort; runs once per bot per process — restart the worker or re-connect. |
+| No replies at all | The **worker** process isn't running — start `npm start` (web + worker) or `npm run dev:all`. |
+| Reply looks truncated | Bodies are length-capped by design (3800/3500 chars). |
+| Reject reason not recorded | A slash command supersedes the pending reject-reason wait; send the reason as plain text right after tapping ↩️ Reject. |
+
+## 15. Related links
+
+- [DM](./DM.md) · [TEAM_ROOM](./TEAM_ROOM.md) · [CHAT_COMMANDS](./CHAT_COMMANDS.md)
+- [WORKFLOW](./WORKFLOW.md) · [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)
+- [KB_RAG](./KB_RAG.md) · [KB_AGENT](./KB_AGENT.md)
+- [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) · [PLUGINS](./PLUGINS.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [SECURITY](./SECURITY.md)
+- [CONFIGURATION](./CONFIGURATION.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)