constella 0.1.0

package/docs/en/START_MODE.md

@@ -0,0 +1,340 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/START_MODE.md) · [✦ Constella](../../README.md)
+
+# Start Mode ✦ — the launch pad
+
+> The default ignition for a single-pilot ship: Constella boots on `127.0.0.1`, auto-provisions a local operator, signs you in with no login screen, and lets the agent constellation run with full local permissions.
+
+Start Mode is the run mode you get when you launch Constella with no mode flag (or with `--start`). It optimizes for a single operator on their own machine: zero friction, no passwords, full agent autonomy.
+
+---
+
+## 🛰️ When to use
+
+| Use Start Mode when… | Prefer another mode when… |
+| --- | --- |
+| You run Constella **on your own laptop / workstation** | You expose it on a network → [AUTH_MODE](./AUTH_MODE.md) / [VPS_MODE](./VPS_MODE.md) |
+| You want **no login screen**, always signed in | Multiple humans need accounts / 2FA → [AUTH_MODE](./AUTH_MODE.md) |
+| You want agents that can **install deps + run tests** (full shell) | You want agents jailed to edits-only → [AUTH_MODE](./AUTH_MODE.md) |
+| You're developing, demoing, or running a personal agent-company | You boot from a USB drive across machines → [PORTABLE_MODE](./PORTABLE_MODE.md) |
+
+Start Mode is **local-only by design**. It binds the loopback interface and uses a predictable operator credential — both safe on one machine, both unsafe on a network. The code refuses to provision that credential in any other mode.
+
+---
+
+## 🌌 How it works
+
+Start Mode is one of four values of `RunMode` (`src/lib/run-mode.ts`):
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+```
+
+The launcher (`bin/constella.mjs`) selects the mode from the launch flag and exports it as `CONSTELLA_RUN_MODE`. The whole server reads it back through `getRunMode()`, which **defaults to `start`** when the env var is missing or unknown:
+
+```ts
+// src/lib/run-mode.ts
+export function getRunMode(): RunMode {
+  const m = process.env.CONSTELLA_RUN_MODE as RunMode | undefined;
+  return m && m in RUN_MODES ? m : "start";
+}
+```
+
+The `RUN_MODES` registry marks `start` as the only mode that does **not** require a login:
+
+```ts
+start: { label: "Start", requiresLogin: false, note: "Local auto-created account · always signed in." },
+```
+
+Three behaviours flow from that single fact:
+
+1. **No login screen.** The workspace guard sends unauthenticated requests to the silent auto-login route instead of `/login`.
+2. **Auto-provisioned operator.** A real local user + a real better-auth password hash are created idempotently, and signed in.
+3. **Full-access agents.** The CLI adapter runs agents with `--permission-mode bypassPermissions` (install deps, run tests, full shell) because you're on your own machine.
+
+The chosen mode is also **persisted on the organization** at onboarding time (`organization.runMode`), so the org record remembers it was born in Start Mode.
+
+---
+
+## 🚀 Main flow
+
+```mermaid
+flowchart TD
+  A["constella  (no flag)  or  constella --start"] --> B["bin/constella.mjs"]
+  B --> C["CONSTELLA_RUN_MODE=start<br/>host=127.0.0.1  port=3000"]
+  C --> D["Persist secrets to &lt;HOME&gt;/.env (chmod 600)<br/>BETTER_AUTH_SECRET · VAULT_KEY · WORKER_SECRET"]
+  D --> E["drizzle-kit migrate (fresh DB gets its tables)"]
+  E --> F["next start + worker (supervised)"]
+  F --> G["Browser hits any (app) page"]
+  G --> H{"requireWorkspace():<br/>session cookie?"}
+  H -- "yes" --> Z["Render the app"]
+  H -- "no (start mode)" --> I["redirect /api/dev-login"]
+  I --> J["ensureLocalOperator()"]
+  J --> K["auth.signInEmail(operator@constella.dev)"]
+  K --> L["Set-Cookie + redirect /"]
+  L --> Z
+```
+
+### Auto-login flow (the heart of Start Mode) 🌠
+
+```mermaid
+sequenceDiagram
+  participant U as Browser
+  participant W as requireWorkspace()
+  participant R as /api/dev-login
+  participant D as dev-auth.ts
+  participant A as better-auth
+
+  U->>W: GET /(app)/...
+  W->>W: getSession()
+  Note over W: no session cookie
+  W-->>U: 307 → /api/dev-login
+  U->>R: GET /api/dev-login
+  R->>R: getRunMode() === "start" ?
+  alt not start mode
+    R-->>U: 307 → /login
+  else start mode
+    R->>D: ensureLocalOperator()
+    D->>D: upsert user_operator + credential hash
+    R->>A: signInEmail(operator@constella.dev / operator123)
+    A-->>R: session cookie (nextCookies plugin)
+    R-->>U: 307 → /  (now authenticated)
+  end
+```
+
+---
+
+## 🪐 Key concepts
+
+### The local operator
+
+`src/server/dev-auth.ts` defines the predictable account:
+
+```ts
+export const DEV_OPERATOR = {
+  id: "user_operator",
+  email: "operator@constella.dev",
+  password: "operator123",
+  name: "Operator",
+};
+```
+
+`ensureLocalOperator()` is **idempotent** and safe to call on every request:
+
+- It looks up the user by email; if absent, inserts `user_operator` (with `emailVerified: true`).
+- It looks up the `credential` account; if absent, hashes `operator123` through better-auth's own `ctx.password.hash` and inserts a real credential row.
+- It returns the user id.
+
+Because the id is fixed (`user_operator`) and matches the seed owner, a seeded demo org is owned by the auto-provisioned operator — so a **from-scratch DB wipe self-heals**: the next page load re-creates the operator and signs in, no manual step.
+
+> 🕳️ **Defense-in-depth gate:** `ensureLocalOperator()` throws `"ensureLocalOperator is start-mode only"` if `getRunMode() !== "start"`. The predictable `operator/operator123` credential can therefore **never** exist in a network-exposed mode where the default password would be a remote login.
+
+### The auto-login route
+
+`src/app/api/dev-login/route.ts` is a `GET` handler:
+
+- Outside Start Mode → `redirect("/login")` (the normal screen).
+- In Start Mode → `ensureLocalOperator()` → `auth.api.signInEmail({ email, password })` (the cookie is set by the `nextCookies()` better-auth plugin) → `redirect("/")`.
+- On any failure → `redirect("/login?autologin=failed")` so the guard never loops.
+
+### The workspace guard
+
+`src/lib/workspace.ts` `requireWorkspace()` is the gate every `(app)` page and server action passes through. The Start-Mode branch:
+
+```ts
+if (!session) redirect(getRunMode() === "start" ? "/api/dev-login" : "/login");
+```
+
+That single line is what turns "no session" into "auto sign-in" in Start Mode, and "show the login screen" everywhere else.
+
+### Full-access agents (`bypassPermissions`)
+
+`src/server/adapters/cli.ts` decides how much shell power agents get:
+
+```ts
+const RUN_MODE = process.env.CONSTELLA_RUN_MODE ?? "start";
+const AGENT_FULL_ACCESS = process.env.CONSTELLA_AGENT_FULL_ACCESS != null
+  ? process.env.CONSTELLA_AGENT_FULL_ACCESS !== "0"
+  : RUN_MODE === "start";
+
+function claudePermArgs(): string[] {
+  return AGENT_FULL_ACCESS
+    ? ["--permission-mode", "bypassPermissions"]   // start → full: install + test
+    : ["--permission-mode", "acceptEdits"];        // network modes → jailed: edits only
+}
+```
+
+So in Start Mode the `claude` / `codex` CLIs run with `bypassPermissions` — they can install dependencies and run tests in the workspace — because you're on your own machine. Network modes (`auth` / `vps` / `portable`) default to `acceptEdits` (edits-only, jailed). Override either way with `CONSTELLA_AGENT_FULL_ACCESS=1|0`. Agents still always run **vanilla** (a temp settings overlay sets `disableAllHooks: true`) so the operator's personal `~/.claude` hooks/plugins never bleed into agent runs. See [AGENTS](./AGENTS.md) and [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+### The auth secret in Start Mode
+
+`next start` runs under `NODE_ENV=production`, where better-auth **throws on its default secret**. So even local Start Mode needs a real `BETTER_AUTH_SECRET` — the launcher generates and persists one to `<HOME>/.env` (`chmod 600`). The only relaxation: `assertAuthSecret()` accepts a missing secret **only** when `RUN_MODE === "start"`; every network mode hard-fails closed without one (`src/lib/auth.ts`). Session cookies stay non-`Secure` in Start Mode because it's local `http` only.
+
+---
+
+## Tables 📊
+
+### Start Mode vs the other run modes
+
+| Property | **start** | auth | vps | portable |
+| --- | --- | --- | --- | --- |
+| `requiresLogin` | **false** | true | true | true |
+| Login screen | none (auto) | email + password | email + password | email + password |
+| Bind host | `127.0.0.1` | `127.0.0.1` | `0.0.0.0` | `0.0.0.0` |
+| Operator | auto `operator@constella.dev` | you create it | you create it | you create it |
+| Agent permission | `bypassPermissions` | `acceptEdits` | `acceptEdits` | `acceptEdits` |
+| `BETTER_AUTH_SECRET` required | persisted, not enforced | enforced | enforced | enforced |
+| Secure cookies | no (local http) | if behind https | yes | if behind https |
+| Typical use | own machine / dev | shared box, local net | server over Tailscale | USB across machines |
+
+### Launch commands → Start Mode
+
+| Command | Result |
+| --- | --- |
+| `constella` | Start Mode (default `cmd === "start"`) |
+| `constella --start` | Start Mode (explicit) |
+| `constella --bind local` | Start Mode (legacy `--bind` back-compat) |
+| `CONSTELLA_RUN_MODE=start` | Forces Start Mode for the server process |
+
+### Env vars that shape Start Mode
+
+| Variable | Default in Start Mode | Effect |
+| --- | --- | --- |
+| `CONSTELLA_RUN_MODE` | `start` | The run mode the server reads |
+| `CONSTELLA_HOME` | `~/.constella` | Runtime root (DB, secrets, orgs) |
+| `--host` / host | `127.0.0.1` | Loopback bind |
+| `--port` / `PORT` | `3000` | Web port |
+| `CONSTELLA_AGENT_FULL_ACCESS` | `1` (implied by start) | `0` re-jails agents to edits-only |
+| `CONSTELLA_WEB_RESEARCH` | on | `0` disables agent WebSearch/WebFetch |
+| `BETTER_AUTH_SECRET` | generated → `<HOME>/.env` | Session signing key |
+
+### Key files
+
+| File | Role |
+| --- | --- |
+| `src/lib/run-mode.ts` | `RunMode` type, `RUN_MODES`, `getRunMode()`, `requiresLogin()` |
+| `bin/constella.mjs` | Launcher: picks mode, sets host/port, persists secrets, boots web + worker |
+| `src/lib/workspace.ts` | `requireWorkspace()` — redirects to `/api/dev-login` in Start Mode |
+| `src/app/api/dev-login/route.ts` | Silent auto sign-in route |
+| `src/server/dev-auth.ts` | `DEV_OPERATOR`, `ensureLocalOperator()` |
+| `src/lib/auth.ts` | better-auth config; `assertAuthSecret()` relaxes only for `start` |
+| `src/server/adapters/cli.ts` | `claudePermArgs()` → `bypassPermissions` in Start Mode |
+| `src/lib/run-context.ts` | `detectRunContext()` for the Update path |
+
+---
+
+## Step-by-step 🧭
+
+### Start a fresh ship in Start Mode
+
+1. **Launch** with no flag (or `--start`):
+   ```bash
+   npx constella
+   # or, installed globally:
+   constella --start
+   ```
+2. The launcher prints the runtime root and `Mode : start · 127.0.0.1:3000`, persists secrets to `<HOME>/.env`, applies migrations, and boots `next start` + the worker.
+3. **Open** `http://127.0.0.1:3000`.
+4. `requireWorkspace()` finds no session → redirects to `/api/dev-login`.
+5. The route provisions `operator@constella.dev`, signs it in, sets the cookie, and bounces to `/`.
+6. If no org exists yet, you land in [ONBOARDING](./ONBOARDING.md); otherwise you're in the app, already signed in.
+
+### Wipe and self-heal
+
+```bash
+# stop Constella, then:
+rm ~/.constella/constella.db
+constella
+```
+The next page load re-runs `ensureLocalOperator()` and re-creates the operator — no manual account step.
+
+### Re-jail agents in Start Mode (extra caution)
+
+```bash
+CONSTELLA_AGENT_FULL_ACCESS=0 constella --start
+```
+Agents now run `acceptEdits` (edits-only, no arbitrary shell), while you keep the no-login convenience.
+
+---
+
+## Examples 🌟
+
+**Default launch (Start Mode):**
+```bash
+$ constella
+Constella runtime root : /home/you/.constella
+Mode                   : start  ·  127.0.0.1:3000
+• Secrets ready (stored in /home/you/.constella/.env, never printed).
+• Starting: next start -H 127.0.0.1 -p 3000  (…)  +  worker
+```
+
+**Custom port, still Start Mode:**
+```bash
+$ constella --start --port 4000
+# → http://127.0.0.1:4000, auto-login, full-access agents
+```
+
+**Pin a different runtime root:**
+```bash
+$ CONSTELLA_HOME=/data/constella constella --start
+# DB at /data/constella/constella.db; secrets at /data/constella/.env
+```
+
+---
+
+## Possible states 🛰️
+
+| Situation | Behaviour |
+| --- | --- |
+| No session cookie, Start Mode | Redirect `/api/dev-login` → auto sign-in → `/` |
+| No session cookie, **not** Start Mode | Redirect `/login` |
+| Auto sign-in succeeds | Cookie set, land on `/` (or `/onboarding` if no org) |
+| Auto sign-in **fails** | Redirect `/login?autologin=failed` (no loop) |
+| `CONSTELLA_FORCE_ONBOARDING=1` | After session, redirect `/onboarding` (one-shot, cleared by `completeOnboarding`) |
+| Org missing / workspace missing | Redirect `/onboarding` |
+| `ensureLocalOperator()` called outside start | Throws `"ensureLocalOperator is start-mode only"` |
+| Agent run, Start Mode | `claude --permission-mode bypassPermissions` (full shell) |
+| Agent run, `CONSTELLA_AGENT_FULL_ACCESS=0` | `claude --permission-mode acceptEdits` (jailed) |
+
+---
+
+## Related integrations 🪐
+
+- **Onboarding** persists the active mode onto `organization.runMode` (`src/server/onboarding.ts`). See [ONBOARDING](./ONBOARDING.md).
+- **Worker** (`bin/worker.mjs`) connects back over `127.0.0.1` regardless of bind host; in Start Mode that's also the web bind. See [ARCHITECTURE](./ARCHITECTURE.md).
+- **Vault** still needs `CONSTELLA_VAULT_KEY` even in Start Mode (provider keys are encrypted). See [SECURITY](./SECURITY.md).
+- **Update** path is mode-aware via `detectRunContext()`. See [UPDATE](./UPDATE.md).
+
+---
+
+## Security 🕳️
+
+Start Mode trades network hardening for local convenience — safe precisely because it is local:
+
+- **Loopback only.** Host binds `127.0.0.1`; nothing is reachable off-box.
+- **Predictable credential is gated.** `operator@constella.dev / operator123` is provisioned **only** when `getRunMode() === "start"`; `ensureLocalOperator()` throws otherwise. The dev-login route also returns `/login` outside Start Mode.
+- **Real auth secret persisted.** A real `BETTER_AUTH_SECRET` is generated to `<HOME>/.env` (`chmod 600`) so sessions aren't forgeable; cookies are non-`Secure` only because the local transport is plain `http`.
+- **Full-access agents are local-only.** `bypassPermissions` lets agents run shell, but the workspace is still an FS jail (`safe()` lexical + symlink checks), and the guard/lock hooks still apply. Set `CONSTELLA_AGENT_FULL_ACCESS=0` to re-jail.
+- **Do not port-forward Start Mode.** If you need remote access, switch to [VPS_MODE](./VPS_MODE.md) (Tailscale + Docker) or [AUTH_MODE](./AUTH_MODE.md) — never expose the loopback Start Mode to a network, where the default password becomes a remote login.
+
+---
+
+## Troubleshooting 🧰
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Stuck on `/login` despite `--start` | `CONSTELLA_RUN_MODE` not `start` for the server | Verify launch flag; check the `Mode : start` line at boot |
+| `/login?autologin=failed` | Auto sign-in threw (DB locked, schema not migrated) | Check console `[dev-login] auto sign-in failed`; ensure migrations ran |
+| Login loop | Guard ↔ dev-login bouncing | The route falls back to `/login?autologin=failed` by design; inspect the logged error |
+| Agents can't install deps / run tests | `CONSTELLA_AGENT_FULL_ACCESS=0` set, or not Start Mode | Unset the override, or relaunch with `--start` |
+| Reachable from another machine | You overrode `--host` to `0.0.0.0` | Drop `--host`; Start Mode binds `127.0.0.1` |
+| better-auth secret error at boot | Forced a network mode without a secret | Network modes require `BETTER_AUTH_SECRET`; the launcher persists one — let it run, or set it |
+| Operator vanished after DB reset | Expected | Reload any page — `ensureLocalOperator()` re-creates it |
+
+---
+
+## Related links 🌌
+
+- [INSTALLATION](./INSTALLATION.md) · [ONBOARDING](./ONBOARDING.md) · [CONFIGURATION](./CONFIGURATION.md)
+- [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md)
+- [SECURITY](./SECURITY.md) · [UPDATE](./UPDATE.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)

package/docs/en/SYNCED_BLOCKS.md

@@ -0,0 +1,320 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/SYNCED_BLOCKS.md) · [✦ Constella](../../README.md)
+
+# 🌌 Synced Blocks — the canonical memory nebula
+
+![](../assets/divider-orbit.svg)
+
+Synced blocks are the **single source of truth** for durable project knowledge: one named unit (`slug` + Markdown `body`) edited in exactly one place and surfaced by reference everywhere — agent prompts, the welcome home, and transcluded into reports. Edit a block once and every surface reflects the latest, with no copy-paste drift. They are distinct from auto-captured `kb_entry` knowledge: a synced block is **curated, canonical, and versioned**; agents can only *propose* edits to it.
+
+Source of truth in code: `src/server/blocks.ts`, schema `src/db/schema.ts` (`synced_block`, `block_proposal`).
+
+---
+
+## 1. When to use 🪐
+
+Use synced blocks for facts that:
+
+- are **durable** and **reused** across many runs and surfaces (the official stack, business rules, security patterns, the architecture every agent must treat as canonical);
+- must stay **consistent** everywhere they appear (no drift between the persona file, a report, and a chat answer);
+- benefit from **operator/KB-agent review** before changing the shared truth.
+
+Do **not** use them for transient, run-specific learnings. Those flow into the auto-captured KB via the `[[REMEMBER type=<t>: <fact>]]` token (no approval) — see [KB_RAG.md](./KB_RAG.md) and [MEMORY_RAG.md](./MEMORY_RAG.md).
+
+| Knowledge kind | Mechanism | Approval | Versioned | Doc |
+|---|---|---|---|---|
+| Canonical, curated fact | Synced block (`synced_block`) | Operator / KB agent merges proposals | Yes (`version`) | this doc |
+| Auto-captured learning | `kb_entry` via `[[REMEMBER …]]` | None (ingested directly) | No (status lifecycle) | [KB_RAG.md](./KB_RAG.md) |
+
+---
+
+## 2. How it works 🛰️
+
+A synced block lives in the `synced_block` table, keyed by `(workspaceId, slug)`. Its `body` is canonical Markdown. Two things happen whenever a block is written via `upsertBlock`:
+
+1. The row is **upserted** — on create `version = 1`; on update `version` is incremented (`cur.version + 1`), `updatedBy` and `updatedAt` are refreshed.
+2. The body is **re-embedded** into `rag_chunk` at path `block/<slug>` (`embedBlock`), so agents also *retrieve* the current block through RAG, not just receive it injected. The old chunks at that path are deleted first, so embeddings never go stale.
+
+The block then reaches agents through **three** distinct surfaces:
+
+- **Injected** — `canonicalFactsSection(wsId)` builds a compact "Canonical project facts" section (up to 20 most-recently-updated blocks, each title + kind + first 800 chars, capped at 5000 chars total) that the context manager injects near the top of every agent prompt.
+- **Transcluded** — `resolveBlocks(orgId, text)` replaces `{{kb:slug}}` markers anywhere in text (persona files, instructions, report bodies) with the block's current `body`. A missing slug renders a LOUD visible marker `[[missing block: <slug>]]` rather than silently vanishing.
+- **Retrieved** — the RAG chunks at `block/<slug>` are returned by ordinary `kbQuery` retrieval, so a block can surface even when it isn't in the always-injected window.
+
+### Slug rules
+
+Slugs are normalized (`normSlug`): lowercased, trimmed, non-`[a-z0-9-]` collapsed to `-`, leading/trailing dashes stripped, truncated to 60 chars, and validated against `/^[a-z0-9][a-z0-9-]{0,60}$/`. An invalid slug fails the upsert (`{ ok: false }`).
+
+### Field bounds (enforced in `upsertBlock`)
+
+| Field | Bound |
+|---|---|
+| `title` | sliced to 200 chars |
+| `body` | sliced to 20000 chars |
+| `kind` | sliced to 40 chars (default `note`) |
+| `updatedBy` | sliced to 60 chars (default `operator`) |
+
+---
+
+## 3. Main flow 🌠
+
+```mermaid
+flowchart TD
+  subgraph Authoring
+    OP["Operator edits in Knowledge UI"] -->|saveBlockAction| UP["upsertBlock()"]
+    SEED["Boot / KB card seeding"] -->|seedDefaultBlocks · seedCanonicalBlocks| UP
+    AG["Agent proposes [[KB-BLOCK]]"] -->|proposeBlockEdit| PQ["block_proposal (pending)"]
+    PQ -->|mergeProposal| UP
+  end
+  UP -->|version++| TBL["synced_block (workspaceId, slug)"]
+  UP -->|re-embed| RC["rag_chunk path=block/&lt;slug&gt;"]
+  TBL -->|canonicalFactsSection| PROMPT["Agent prompt: Canonical project facts"]
+  TBL -->|"resolveBlocks {{kb:slug}}"| SURF["Reports · persona · instructions"]
+  RC -->|kbQuery retrieval| PROMPT
+```
+
+---
+
+## 4. Key concepts ✦
+
+| Concept | What it is |
+|---|---|
+| **Block** | `typeof syncedBlock.$inferSelect` — one canonical knowledge unit `(slug, kind, title, body, version, updatedBy)`. |
+| **Proposal** | `typeof blockProposal.$inferSelect` — an agent's *suggested* edit awaiting merge/reject. |
+| **`{{kb:slug}}` marker** | A transclusion token resolved at read time to the block's current body. |
+| **`[[KB-BLOCK slug]]…[[/KB-BLOCK]]`** | The token an agent emits in its run output to *propose* a block edit. |
+| **Canonical facts section** | The bounded block digest injected into every agent prompt as the authoritative source of truth. |
+| **Re-embedding** | Each save refreshes `rag_chunk` at `block/<slug>` so RAG retrieval stays current. |
+| **Versioning** | `version` starts at 1, increments on every update; the UI shows `v<n>` and `updatedBy`. |
+
+---
+
+## 5. Tables 🗄️
+
+### `synced_block` (PK `(workspaceId, slug)`)
+
+| Column | Type | Notes |
+|---|---|---|
+| `workspace_id` | text | FK → `workspace.id`, `onDelete: cascade` |
+| `slug` | text | stable handle, e.g. `official-stack` |
+| `kind` | text | default `note`; see kinds below |
+| `title` | text | default `""` |
+| `body` | text | canonical Markdown — the single source of truth |
+| `version` | integer | default `1`, bumped on every update |
+| `updated_by` | text | agent handle or `operator` (or `system` for seeded) |
+| `created_at` | timestamp | `unixepoch()` |
+| `updated_at` | timestamp | `unixepoch()`; blocks are listed/digested in `desc(updatedAt)` |
+
+**`kind` values** (from the schema comment): `mission`, `objective`, `stack`, `architecture`, `business-rule`, `ui-pattern`, `security`, `commands`, `deploy-checklist`, `review-checklist`, `glossary`, `policy`, `note`. `kind` is free text (sliced to 40 chars), so these are conventions, not a DB enum.
+
+### `block_proposal` (PK `id`, index `block_prop_ws_idx` on `(workspaceId, status)`)
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | text | `randomUUID()` |
+| `workspace_id` | text | FK → `workspace.id`, `onDelete: cascade` |
+| `slug` | text | target block slug (normalized) |
+| `kind` | text | default `note` |
+| `title` | text | default `""` |
+| `body` | text | proposed Markdown body |
+| `by_agent_handle` | text | who proposed it |
+| `status` | text enum | `pending` \| `merged` \| `rejected` (default `pending`) |
+| `created_at` | timestamp | `unixepoch()` |
+| `decided_at` | timestamp | set on merge/reject |
+| `decided_by` | text | default `""`; `operator` from the action |
+
+---
+
+## 6. The canonical block set 🚀
+
+`seedCanonicalBlocks(orgId)` (wired to the KB card and the Welcome Home "Create central blocks" button via `seedDefaultBlocksAction`) ensures the full curated set exists. `mission`, `objective`, and `official-stack` are filled from the workspace's own fields; the rest are created as **editable starter placeholders** so they show up to be filled in. It is **idempotent** — it never overwrites an existing block, and returns how many were newly created.
+
+| slug | kind | source of body |
+|---|---|---|
+| `mission` | `mission` | `workspace.mission` |
+| `objective` | `objective` | `workspace.objective` |
+| `official-stack` | `stack` | rendered from `workspace.stack` (`- **key:** value`, skips `None`) |
+| `current-architecture` | `architecture` | starter placeholder |
+| `business-rules` | `business-rule` | starter placeholder |
+| `ui-patterns` | `ui-pattern` | starter placeholder |
+| `security-patterns` | `security` | starter placeholder |
+| `deploy-checklist` | `deploy-checklist` | starter placeholder |
+| `code-review-checklist` | `review-checklist` | starter placeholder |
+| `glossary` | `glossary` | starter placeholder |
+| `technical-decisions` | `note` | starter placeholder |
+
+A lighter `seedDefaultBlocks(orgId)` seeds only `mission` / `objective` / `official-stack` and only if absent **and** non-empty. It runs at boot for every workspace via `seedDefaultBlocksForExistingWorkspaces()` (called from `src/server/boot.ts`).
+
+---
+
+## 7. Agent proposals: propose → review → merge ✦
+
+Agents never write blocks directly. The runner instruction tells them:
+
+> If you discover a DURABLE canonical fact that belongs in the shared knowledge … you MAY propose a synced-block edit by emitting on their own lines: `[[KB-BLOCK <kebab-slug>]]` then the new Markdown body then `[[/KB-BLOCK]]` — the operator / Knowledge agent reviews and merges it. Use sparingly, only for reusable facts (e.g. `official-stack`, `security-patterns`).
+
+After a successful run, `src/server/runner.ts` scans the output for `[[KB-BLOCK slug]]…[[/KB-BLOCK]]` blocks, calls `proposeBlockEdit` for each (queuing a `block_proposal` with `status = pending`), records the touched slugs (→ room chips), and **strips the tokens** from the visible text. Each proposal also:
+
+- pushes an **Inbox** item (`kind: review`, `refType: validation`, `refId = proposalId`) titled `Block edit proposed — <slug>`;
+- fires an operator notification via `notifyOps`.
+
+The operator (or the Knowledge agent, Vannevar) then **merges** or **rejects** from the Knowledge module's `BlocksPanel`.
+
+```mermaid
+sequenceDiagram
+  participant A as Agent
+  participant R as runner.ts
+  participant P as block_proposal
+  participant I as Inbox / notifyOps
+  participant OP as Operator / KB agent
+  participant B as synced_block
+
+  A->>R: run output with [[KB-BLOCK slug]]…[[/KB-BLOCK]]
+  R->>P: proposeBlockEdit() → status=pending
+  R->>I: pushInbox(review/validation) + notifyOps
+  Note over OP: reviews in Knowledge → BlocksPanel
+  alt merge
+    OP->>P: mergeProposalAction(id)
+    P->>B: upsertBlock(body, updatedBy=byAgentHandle) → version++
+    B->>B: re-embed rag_chunk block/<slug>
+    P->>P: status=merged, decidedAt, decidedBy
+    P->>I: resolveInboxFor(validation, id)
+  else reject
+    OP->>P: rejectProposalAction(id)
+    P->>P: status=rejected, decidedAt, decidedBy
+    P->>I: resolveInboxFor(validation, id)
+  end
+```
+
+On **merge**, `mergeProposal(wsId, id, by)` only proceeds if the proposal is still `pending`; it then runs `upsertBlock` with `updatedBy` set to the proposing agent's handle (so authorship is preserved), marks the proposal `merged`, and resolves the Inbox item. On **reject**, `rejectProposal` marks it `rejected` and resolves the Inbox item without touching the block.
+
+---
+
+## 8. Step-by-step 🛠️
+
+**Seed the canonical set**
+
+1. Open the **Knowledge** module (or the Welcome Home / dashboard KB card).
+2. Click **Create central blocks** → `seedDefaultBlocksAction` → `seedCanonicalBlocks`.
+3. `mission` / `objective` / `official-stack` come pre-filled from the workspace; the rest appear as starter placeholders to edit.
+
+**Edit a block as operator**
+
+1. In `BlocksPanel`, click **Edit** on a block (or **New**).
+2. Set `slug`, `title`, `kind`, `body` (Markdown).
+3. Save → `saveBlockAction` → `upsertBlock(…, updatedBy: "operator")` → `version++` + re-embed.
+
+**Transclude a block into a report or persona**
+
+1. Write `{{kb:official-stack}}` anywhere in the text.
+2. At read time, `resolveBlocks` swaps it for the block's current body (reports resolve in `src/app/(app)/reports/[id]/page.tsx`; prompts resolve at the end of context assembly).
+
+**Let an agent propose a change**
+
+1. The agent emits `[[KB-BLOCK security-patterns]] …new body… [[/KB-BLOCK]]` in its run output.
+2. The proposal lands in the Knowledge module's pending list + the Inbox.
+3. You **Merge** (applies + bumps version) or **Reject**.
+
+---
+
+## 9. Examples 📡
+
+**Transclusion marker** (in a report or `.claude/agents/<handle>/Agent.md`):
+
+```markdown
+## Stack you must use
+{{kb:official-stack}}
+
+## Rules you must never break
+{{kb:business-rules}}
+```
+
+A missing slug stays loudly visible:
+
+```markdown
+{{kb:does-not-exist}}   →   [[missing block: does-not-exist]]
+```
+
+**Agent proposal token** (emitted by the agent, stripped from chat after capture):
+
+```text
+[[KB-BLOCK official-stack]]
+- **language:** TypeScript
+- **framework:** Next.js 16
+- **db:** SQLite via drizzle-orm
+[[/KB-BLOCK]]
+```
+
+**Injected digest** (what `canonicalFactsSection` produces, abbreviated):
+
+```text
+### Official stack (stack)
+- **framework:** Next.js 16
+- **db:** SQLite
+
+### Business rules (business-rule)
+...first 800 chars...
+```
+
+---
+
+## 10. Possible states 🕳️
+
+**Block** — has no status column; its lifecycle is the `version` counter. A block exists, is edited (version bumps), or is deleted (`deleteBlock` removes the row **and** its `rag_chunk` entries at `block/<slug>`).
+
+**Proposal** (`block_proposal.status`):
+
+| State | Meaning | Set by |
+|---|---|---|
+| `pending` | awaiting operator/KB-agent decision; appears in `listProposals` + Inbox | `proposeBlockEdit` (default) |
+| `merged` | applied to the block (version bumped), Inbox resolved | `mergeProposal` |
+| `rejected` | discarded, block untouched, Inbox resolved | `rejectProposal` |
+
+`listProposals(wsId)` returns only `pending` proposals, newest first.
+
+---
+
+## 11. Related integrations 🔗
+
+- **RAG** ([KB_RAG.md](./KB_RAG.md), [MEMORY_RAG.md](./MEMORY_RAG.md)) — every save re-embeds the block into `rag_chunk` (`embed` + `chunksOf`) at path `block/<slug>`, so blocks participate in ordinary retrieval. A keyword fallback applies if the embed server is down.
+- **Context manager** ([AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md)) — `canonicalFactsSection` is injected as the top-priority "Canonical project facts" section; `resolveBlocks` runs last over the assembled prompt.
+- **Inbox** ([INBOX.md](./INBOX.md)) — proposals raise and resolve `validation` review items.
+- **Agents / Knowledge agent** ([AGENTS.md](./AGENTS.md), [KB_AGENT.md](./KB_AGENT.md)) — agents propose; Vannevar / the operator merge.
+- **Reports & specs** ([GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md)) — report bodies transclude `{{kb:slug}}` at read time.
+- **Knowledge tokens** ([CHAT_COMMANDS.md](./CHAT_COMMANDS.md)) — `[[KB-BLOCK …]]` sits alongside `[[REMEMBER …]]` / `[[CONSULT …]]` in the agent token vocabulary.
+
+---
+
+## 12. Security 🛡️
+
+- **No direct agent writes.** Agents can only *propose*; the canonical body changes only through `mergeProposal` / `saveBlockAction` (operator or KB agent). This keeps the shared source of truth under human/curator control.
+- **Workspace isolation.** Every query is scoped by `workspaceId`; the PK is `(workspaceId, slug)` and FKs cascade on workspace delete.
+- **Bounded input.** `title`/`body`/`kind`/`updatedBy` are length-capped; slugs are normalized and regex-validated before any write.
+- **Secret hygiene.** Blocks are curated knowledge, but treat bodies like any shared surface — do not paste secrets; the platform scrubs secrets on KB ingest, Telegram and logs (`scrubSecrets`, see [SECURITY.md](./SECURITY.md)).
+- **Resilience.** All block functions wrap their DB work in `try/catch` and degrade gracefully (`listBlocks` → `[]`, `resolveBlocks` → original text), so a transient failure never breaks prompt assembly.
+
+---
+
+## 13. Troubleshooting 🔧
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `[[missing block: <slug>]]` in a report/prompt | the referenced block does not exist (or slug typo) | create the block, or fix the `{{kb:slug}}` marker; slugs are lowercase kebab |
+| Block save silently fails (`{ ok: false }`) | invalid slug (fails `SLUG_RE`) or empty after normalization | use `[a-z0-9-]`, start with alphanumeric, ≤ 60 chars |
+| Agent's proposal never appears | the agent didn't wrap it correctly, or the body was empty | tokens must be exactly `[[KB-BLOCK <slug>]]` … `[[/KB-BLOCK]]` with a non-empty body |
+| Merge button does nothing | the proposal is no longer `pending` (already decided) | refresh; `mergeProposal` ignores non-pending proposals |
+| Edited block doesn't show in agent answers | RAG retrieval cold / embed server down | the block is still injected via `canonicalFactsSection`; check the embed server (see [MODELS.md](./MODELS.md)) |
+| No blocks at all after onboarding | workspace `mission`/`objective`/`stack` were empty (nothing to seed) | click **Create central blocks** to seed the full set with starters |
+
+---
+
+## 14. Related links ✦
+
+- [KB_RAG.md](./KB_RAG.md) — the knowledge base, ingestion, and `kbQuery`
+- [MEMORY_RAG.md](./MEMORY_RAG.md) — embeddings, the memory nebula
+- [KB_AGENT.md](./KB_AGENT.md) — Vannevar, the Knowledge agent
+- [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — how context is assembled for agents
+- [AGENTS.md](./AGENTS.md) — the agent roster and how they run
+- [INBOX.md](./INBOX.md) — review items and resolution
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — specs, reports, transclusion targets
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — agent token vocabulary
+- [SECURITY.md](./SECURITY.md) — isolation, scrubbing, vault