okengine 0.2.8 → 0.3.4

package/AGENTS.md

@@ -1,6 +1,6 @@
 # OKE — Agent Contract
 
-This file is loaded by every later session. It prevents drift. Specs live in `docs/spec/`. **If the spec is silent, stop and ask.**
+This file is loaded by every later session. It prevents drift. Product documentation lives in `site/content/docs/`. **If the documentation is silent, stop and ask.**
 
 ## The one law
 
@@ -53,11 +53,12 @@ A direct `node:` import (or any other side-channel I/O) in element or flow code
 
 ## Ports
 
-| Port     | Surface |
-| -------- | ------- |
-| **6530** | App     |
-| **6533** | Console |
-| **6535** | MCP     |
+| Port     | Surface              |
+| -------- | -------------------- |
+| **6530** | App                  |
+| **6533** | Console              |
+| **6535** | MCP                  |
+| **6536** | Docs MCP (read-only) |
 
 Mnemonic: O·K·E = 6·5·3.
 
@@ -76,17 +77,18 @@ A regression fails the build. Claims we cannot measure, we do not make.
 
 Published packages:
 
-- `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
-- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke`; clean starters are `templates/*`, teaching apps stay in `examples/*` (`--from-example`).
+- `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
+- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships one standard starter from `packages/create-oke/template`.
 
 Engine: Bun `>=1.3`.
 
-## Spec authority
+## Documentation authority
 
-| Spec              | Path                             |
-| ----------------- | -------------------------------- |
-| Unified theory    | `docs/spec/unified-theory.md`    |
-| Four applications | `docs/spec/four-applications.md` |
-| Console           | `docs/spec/console.md`           |
+| Surface  | Path                                 |
+| -------- | ------------------------------------ |
+| Theory   | `site/content/docs/elements/`        |
+| Console  | `site/content/docs/console/`         |
+| CLI      | `site/content/docs/reference/cli.md` |
+| Manifest | `manifest.v1.schema.json`            |
 
-**If the spec is silent, stop and ask.**
+**If the documentation is silent, stop and ask.**

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="site/public/OKE-W.svg" />
-    <img alt="OKE" src="site/public/OKE-B.svg" width="220" />
+    <source media="(prefers-color-scheme: dark)" srcset="site/public/logo/OKE-W.svg" />
+    <img alt="OKE" src="site/public/logo/OKE-B.svg" width="220" />
   </picture>
 </p>
 
@@ -15,7 +15,7 @@ _"Stop gluing APIs, jobs, and queues into one backend. One law collapses them
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bun >=1.3](https://img.shields.io/badge/Bun-%3E%3D1.3-black.svg)](https://bun.sh)
 
-**Docs:** [okengine.vercel.app](https://okengine.vercel.app) · **Handbook:** [/docs](https://okengine.vercel.app/docs) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke)
+**Docs:** [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · **Handbook:** [/docs](https://oke.omqkhafi.dev/docs) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke)
 
 > [!WARNING]
 > **Early development (`v0.x`) — not production-ready.**
@@ -51,42 +51,70 @@ Mnemonic: **O·K·E = 6·5·3**.
 Every backend behavior is a Flow: `on(Trigger) → Effects`. World access goes through `fx`.
 
 Store apps sync schema with `oke db push|generate|migrate` (local `oke dev`
-auto-pushes). Prefer `store.schema.table` + `field.*` (see Linkly) or keep a
+auto-pushes). Prefer `store.schema.table` + `field.*` or keep a
 hand-written Drizzle `schema.ts`.
 
-### `examples/notes/src/flows/notes/index.ts`
+### Resource Flow
 
 ```typescript
-export const create = on(
-  http.post("/notes"),
-  flow({
-    in: NewNote,
-    out: NoteId,
-    do: async (input, fx) => {
-      const [note] = await fx.store(db).insert(notes).values(input).returning();
-      return { id: note.id };
-    },
-  }),
-);
+import { on, http, store } from "okengine";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { db } from "../../core";
+import { notes as notesTable } from "../../schema";
+
+// Contracts derived from the schema — one source of truth.
+const NewNote = createInsertSchema(notesTable, { title: (s) => s.min(1).max(120) }).omit({
+  id: true,
+  createdAt: true,
+});
+const Note = createSelectSchema(notesTable);
+
+// One declarative resource: list (cursor + search + filters + order +
+// select), create (201), get / update / remove with typed NotFound.
+const notesR = store.resource(db, notesTable, {
+  in: NewNote,
+  out: Note,
+  update: NewNote.partial(),
+  list: {
+    cursor: [notesTable.createdAt, notesTable.id],
+    direction: "desc",
+    limit: 20,
+    maxLimit: 100,
+    search: [notesTable.title],
+    filter: "all",
+    order: "all",
+  },
+  unit: "notes",
+  breaking: true,
+});
+
+// Mount all five verbs: list/create on /notes, get/update/remove on /notes/:id.
+// `on(http.resource(...))` returns the ops bag; spread it into named exports
+// so `adopt({ notes })` registers each flow under the unit.
+const mounted = on(http.resource("/notes", notesR.all()));
+
+export const list = mounted.list;
+export const create = mounted.create;
+export const get = mounted.get;
+export const update = mounted.update;
+export const remove = mounted.remove;
 ```
 
-Full walkthrough: [Basic usage](https://okengine.vercel.app/docs/get-started/basic-usage) · teaching apps: [Learn](https://okengine.vercel.app/docs/learn/notes).
+Full walkthrough: [Basic usage](https://oke.omqkhafi.dev/docs/get-started/basic-usage).
 
 ## Documentation
 
-Everything beyond this page lives on the site and in-repo specs:
-
-| Resource          | Link                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| Docs site         | [okengine.vercel.app](https://okengine.vercel.app)                                         |
-| Handbook          | [/docs](https://okengine.vercel.app/docs)                                                  |
-| Changelog         | [/changelog](https://okengine.vercel.app/changelog)                                        |
-| Agents index      | [/llms.txt](https://okengine.vercel.app/llms.txt)                                          |
-| Unified theory    | [`docs/spec/unified-theory.md`](docs/spec/unified-theory.md)                               |
-| Four applications | [`docs/spec/four-applications.md`](docs/spec/four-applications.md)                         |
-| Console           | [`docs/spec/console.md`](docs/spec/console.md)                                             |
-| CLI reference     | [`docs/cli.md`](docs/cli.md) · [handbook](https://okengine.vercel.app/docs/cli)            |
-| Budgets           | [`BUDGETS.md`](BUDGETS.md)                                                                 |
-| Contributing      | [`CONTRIBUTING.md`](CONTRIBUTING.md) · [writing a driver](docs/guides/writing-a-driver.md) |
+Everything beyond this page lives in the site handbook:
+
+| Resource      | Link                                                               |
+| ------------- | ------------------------------------------------------------------ |
+| Docs site     | [oke.omqkhafi.dev](https://oke.omqkhafi.dev)                       |
+| Handbook      | [/docs](https://oke.omqkhafi.dev/docs)                             |
+| Changelog     | [/changelog](https://oke.omqkhafi.dev/changelog)                   |
+| Agents index  | [/llms.txt](https://oke.omqkhafi.dev/llms.txt)                     |
+| CLI reference | [/docs/reference/cli](https://oke.omqkhafi.dev/docs/reference/cli) |
+| Manifest      | [`manifest.v1.schema.json`](manifest.v1.schema.json)               |
+| Budgets       | [`BUDGETS.md`](BUDGETS.md)                                         |
+| Contributing  | [`CONTRIBUTING.md`](CONTRIBUTING.md)                               |
 
 Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine). MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.2.8",
+  "version": "0.3.4",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -12,14 +12,14 @@
   },
   "workspaces": [
     "packages/*",
-    "examples/*",
     "site"
   ],
   "files": [
     "src",
-    "spec",
+    "manifest.v1.schema.json",
     "AGENTS.md",
-    "docs/spec"
+    "README.md",
+    "site/content/docs"
   ],
   "type": "module",
   "sideEffects": false,
@@ -31,6 +31,7 @@
     "./auth": "./src/auth/index.ts",
     "./console": "./src/console/index.ts",
     "./mcp": "./src/mcp/index.ts",
+    "./plugins": "./src/plugins/index.ts",
     "./store": "./src/elements/store.ts",
     "./signal": "./src/elements/signal.ts",
     "./clock": "./src/elements/clock.ts",
@@ -44,8 +45,8 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit && bun run --cwd packages/create-oke typecheck",
-    "lint": "oxlint --type-aware --quiet",
-    "lint:fix": "oxlint --type-aware --fix",
+    "lint": "oxlint --quiet",
+    "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "test": "bun test --pass-with-no-tests",
@@ -55,12 +56,11 @@
     "prepack": "bun run build",
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate": "bun src/cli/doctor-diff-examples.ts && bun src/cli/doc-drift.ts",
-    "site:sync": "bun run --cwd site sync",
-    "site:dev": "bun run --cwd site dev",
+    "gate": "bun test src/cli/doc-staleness.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
+    "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
-    "ci": "bun run typecheck && bun run lint && bun run fmt:check && bun run test && bun run budgets -- --dry-run && bun run gate && bun run site:build",
-    "ci:integration": "CREATE_OKE_INTEGRATION=1 bun run ci",
+    "ci:workflow": "bun scripts/ci.ts --workflow",
+    "ci": "bun scripts/ci.ts",
     "bump": "bun run scripts/bump-version.ts",
     "release": "bun run scripts/publish.ts",
     "g": "gflows"
@@ -90,7 +90,6 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.4",
-    "age-encryption": "^0.3.0",
     "arktype": "^2.2.3",
     "axe-core": "^4.12.1",
     "clsx": "^2.1.1",
@@ -114,16 +113,12 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "age-encryption": "^0.3.0",
     "drizzle-kit": ">=1.0.0-rc.0",
     "drizzle-orm": ">=1.0.0-rc.0",
     "drizzle-seed": ">=0.3.0",
     "zod": ">=3.23.0"
   },
   "peerDependenciesMeta": {
-    "age-encryption": {
-      "optional": true
-    },
     "drizzle-kit": {
       "optional": true
     },

package/site/content/docs/ai/llms-txt.mdx

@@ -0,0 +1,54 @@
+---
+title: "llms.txt"
+description: "Machine-readable documentation — the index, the full concatenated text, and per-page markdown endpoints this site serves for agents."
+icon: "FileText"
+source: "docs/spec/unified-theory.md"
+---
+
+This documentation site serves machine-readable twins of every page, following the `llms.txt` convention — so an agent can pull exactly the docs it needs (or all of them) instead of scraping HTML. Three endpoints, three granularities:
+
+| Endpoint                | Contains                                            | Pull it when                                  |
+| ----------------------- | --------------------------------------------------- | --------------------------------------------- |
+| `/llms.txt`             | Index of every docs page (title, link, description) | The agent needs the map — what exists, where  |
+| `/llms-full.txt`        | All pages concatenated as one markdown document     | You want the whole docs in one context window |
+| `/llms.mdx/docs/⟨slug⟩` | One page as markdown                                | The agent needs just the Vault page, say      |
+
+## Use them
+
+```bash
+# the map
+curl https://oke.omqkhafi.dev/llms.txt
+
+# everything, for stuffing into context
+curl https://oke.omqkhafi.dev/llms-full.txt
+
+# one page — e.g. the Vault element
+curl https://oke.omqkhafi.dev/llms.mdx/docs/elements/vault
+```
+
+<Callout title="Which one first?">
+  Start with `/llms.txt` — it is small and tells the agent which slugs exist. Fetch `/llms-full.txt`
+  only when breadth matters more than tokens; per-page `/llms.mdx` is the precise instrument.
+</Callout>
+
+## How it pairs with the docs MCP
+
+These endpoints serve the _published_ docs of the framework. During `oke dev`, the [docs MCP server](/docs/ai/mcp) also runs on :6536 (`oke.docs.search` / `oke.docs.get`), answering from the same content over the MCP protocol — pick the plain HTTP endpoints for one-shot context, the MCP tools when the agent is already connected as a client.
+
+## Learn more
+
+- [MCP](/docs/ai/mcp) — runtime and docs MCP servers
+- [Agent contracts](/docs/ai/skills) — teaching agents the vocabulary these pages use
+- [Reference](/docs/reference/configuration) — the most-cited pages for config questions
+
+## Next
+
+<Cards>
+  <Card title="MCP" description="Runtime :6535 · docs :6536." href="/docs/ai/mcp" />
+  <Card
+    title="Skills"
+    description="AGENTS.md and the shipped agent skills."
+    href="/docs/ai/skills"
+  />
+  <Card title="AI element" description="Models inside your app." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/ai/mcp.mdx

@@ -0,0 +1,123 @@
+---
+title: "MCP"
+description: "The runtime MCP server on :6535 — read tools for Manifest, schemas, effects, and traces, write actions gated by per-call human confirmation — plus the read-only docs MCP on :6536."
+icon: "Plug"
+source: "docs/spec/unified-theory.md"
+---
+
+OKE serves an [MCP](https://modelcontextprotocol.io) endpoint on port **6535** so an AI agent can operate your running app: read its Manifest and traces, and take a small set of safe actions. It speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
+
+<Callout title="The one rule">
+  MCP inherits the operator's capability and can never exceed it. Server-level controls alone are
+  exactly where the confused-deputy problem lives, so access descends to the tool, the operation,
+  and each parameter.
+</Callout>
+
+## Read tools
+
+Default-safe — they return inert data envelopes, never live handles:
+
+| Tool               | Returns                                        | Scope (any of)                                |
+| ------------------ | ---------------------------------------------- | --------------------------------------------- |
+| `oke.manifest.get` | The current Manifest catalogue                 | `mcp:manifest:read` · `console:manifest:read` |
+| `oke.schema.get`   | In/out/error schemas for one flow (`flowId`)   | `mcp:schema:read` · `console:manifest:read`   |
+| `oke.effects.get`  | Declared effects for one flow (`flowId`)       | `mcp:effects:read` · `console:manifest:read`  |
+| `oke.traces.list`  | Recent runs (`limit` ≤ 200, optional `flowId`) | `mcp:traces:read` · `console:runs:read`       |
+| `oke.traces.get`   | One run/trace record (`runId`)                 | `mcp:traces:read` · `console:runs:read`       |
+
+## Write tools — confirmed, every single call
+
+Two actions are write-class, and each call needs a **fresh, single-use** confirmation — there is no session-level consent cache to leak:
+
+| Tool                            | Does                                                    | Scope (any of)                                         |
+| ------------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
+| `oke.action.invoke`             | Invoke a flow by id (sensitive)                         | `mcp:action:invoke` · `console:flows:invoke`           |
+| `oke.action.structural_propose` | Propose a structural diff — reviewable, **not applied** | `mcp:action:structural` · `console:structural:propose` |
+
+<Steps>
+
+<Step>
+### Request a confirmation token
+
+`oke.action.confirm` with the target `tool`, the exact `args`, and a human `reason` — it returns a single-use token.
+
+</Step>
+
+<Step>
+### Call the write tool
+
+Pass the token as `confirmToken` plus the phrase `CONFIRM` in `confirmation`. Token, phrase, args, and principal must all match what was confirmed.
+
+</Step>
+
+<Step>
+### The token dies
+
+Consumed tokens cannot be replayed; the next write needs a new confirmation. A mismatch fails with `write tool requires fresh human confirmation` and the `confirmVia` hint.
+
+</Step>
+
+</Steps>
+
+## Structural changes arrive as diffs
+
+`oke.action.structural_propose` is how an agent suggests a file change: it takes `title`, `relativePath`, and `contents`, and produces a **reviewable diff** for a human — it is never applied to the tree. This is the boundary that lets an agent propose boldly while a human stays the one who merges.
+
+## The security model
+
+| Layer               | Enforcement                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| Authentication      | Bearer session token required — even on `127.0.0.1`         |
+| Scope inheritance   | `console:*` / `mcp:*` expand to every declared tool scope   |
+| Per-tool ACL        | Each tool declares required scopes + read/write class       |
+| Per-parameter rules | `maxLength`, enum allow-lists, forbidden parameters         |
+| Token hygiene       | Caller token never forwarded — structured operator ids only |
+| Confirmation        | Single-use, per call, phrase + token + args bound           |
+
+## Docs MCP — a second, docs-only server
+
+`oke dev` also boots `okengine-docs-mcp` on port **6536** — the same protocol, but exposing the documentation itself instead of a live Manifest. It is how an agent answers "how do I … in OKE?" from the real pages rather than its training data.
+
+| Fact     | Value                                  |
+| -------- | -------------------------------------- |
+| Port     | `6536` (moves upward when busy)        |
+| Auth     | None — public documentation, read-only |
+| Endpoint | `POST http://127.0.0.1:6536/mcp`       |
+| Health   | `GET http://127.0.0.1:6536/health`     |
+| Tools    | `oke.docs.search` · `oke.docs.get`     |
+
+```json
+{
+  "mcpServers": {
+    "okengine-docs": { "url": "http://127.0.0.1:6536/mcp" }
+  }
+}
+```
+
+The docs content ships inside the `okengine` package, so the index your agent searches is exactly the version you have installed. If the surface cannot boot (missing content, busy port), `oke dev` prints `Docs MCP skipped — …` and continues — docs search never takes your dev session down.
+
+## Learn more
+
+- [Console · Access](/docs/console/access) — how operator tokens and grants work
+- [Agent contracts](/docs/ai/skills) — what agents are taught about the system they operate
+- [Flow](/docs/elements/flow) — the effects the MCP reads back
+
+## Next
+
+<Cards>
+  <Card
+    title="Skills"
+    description="AGENTS.md and the shipped agent skills."
+    href="/docs/ai/skills"
+  />
+  <Card
+    title="llms.txt"
+    description="Machine-readable documentation surfaces."
+    href="/docs/ai/llms-txt"
+  />
+  <Card
+    title="AI element"
+    description="Models inside your app — the other direction."
+    href="/docs/elements/ai"
+  />
+</Cards>

package/site/content/docs/ai/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "AI Resources",
+  "icon": "Bot",
+  "pages": ["mcp", "skills", "llms-txt"]
+}

package/site/content/docs/ai/skills.mdx

@@ -0,0 +1,53 @@
+---
+title: "Skills"
+description: "What OKE ships to teach AI agents the system — the repo-level AGENTS.md contract and the installable skills under .agents/skills/."
+icon: "GraduationCap"
+source: "docs/spec/unified-theory.md"
+---
+
+Tools alone don't make a good operator — an agent also needs to know the _vocabulary_: what a Flow is, why `fx` is the only door, which driver ids are legal. OKE ships that knowledge as contracts and skills that agents load automatically, so sessions start aligned instead of drifting and getting corrected.
+
+## The three layers
+
+| Layer              | Path                       | Loaded when                                       | Teaches                                                               |
+| ------------------ | -------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
+| **Agent contract** | `AGENTS.md` (repo root)    | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
+| **Element skill**  | `.agents/skills/oke/`      | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
+| **Docs skill**     | `.agents/skills/oke-docs/` | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
+
+## AGENTS.md — the root contract
+
+Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements and ten exports, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
+
+## Skills — installable know-how
+
+Skills are `SKILL.md` packages an agent loads when the work matches their description. The two OKE ships:
+
+| Skill      | Use it for                          | Inside                                                    |
+| ---------- | ----------------------------------- | --------------------------------------------------------- |
+| `oke`      | App work — flows, elements, drivers | The agent contract, element patterns, the fx invariants   |
+| `oke-docs` | Docs work — new pages, rewrites     | The page skeleton, verification sources, the density gate |
+
+Both live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe.
+
+## How contracts compose with MCP
+
+Contracts teach the _vocabulary_; [MCP](/docs/ai/mcp) grants the _hands_. An agent that knows the eight elements from `AGENTS.md` reads the Manifest through `oke.manifest.get` with the right mental model — and its write attempts still pass through [per-call human confirmation](/docs/ai/mcp), because knowing the system is not the same as being trusted by it.
+
+## Learn more
+
+- [MCP](/docs/ai/mcp) — the runtime surface these contracts pair with
+- [Introduction](/docs/get-started/introduction) — the eight elements in human terms
+- [llms.txt](/docs/ai/llms-txt) — feeding an agent the docs themselves
+
+## Next
+
+<Cards>
+  <Card
+    title="llms.txt"
+    description="Machine-readable documentation surfaces."
+    href="/docs/ai/llms-txt"
+  />
+  <Card title="MCP" description="Runtime server :6535." href="/docs/ai/mcp" />
+  <Card title="AI element" description="Models inside your app." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/console/access.mdx

@@ -0,0 +1,29 @@
+---
+title: "Access"
+description: "Identities, roles, API keys."
+icon: "Users"
+source: "docs/spec/console.md"
+---
+
+Answers: **identities, roles, API keys**
+
+<Callout title="Governing rule">
+  Granting an application scope to an operator is impossible in the UI — taught by absence, not
+  refusal.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Two planes" description="Operators and application users never mix." />
+  <Card title="Key creation" description="Value shown once; attenuation to creator scopes only." />
+  <Card title="Revocation" description="Blast radius plus honest JWT validity delay." />
+  <Card title="Hygiene" description="Unused keys, never-signed-in operators, expired invites." />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓ (admin)" />
+</Cards>

package/site/content/docs/console/ai.mdx

@@ -0,0 +1,35 @@
+---
+title: "AI"
+description: "Prompt versions, eval scores, cost, agent runs."
+icon: "Sparkles"
+source: "docs/spec/console.md"
+---
+
+Answers: **prompt versions, eval scores, cost, agent runs**
+
+<Callout title="Governing rule">
+  Everything else in the Console is deterministic; this panel is built on distributions, not single
+  values.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Prompt versions" description="A version bump is Manifest Diff blast radius." />
+  <Card title="Eval + shape" description="Schema-validation failure is its own class." />
+  <Card
+    title="Agent tools"
+    description="Tools are the app’s own flows — undeclared reach is denied and shown."
+  />
+  <Card
+    title="Budgets"
+    description="Cost, semantic cache, and `allowPii` as standing review surfaces."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="read + budgets" />
+</Cards>

package/site/content/docs/console/architecture.mdx

@@ -0,0 +1,35 @@
+---
+title: "Architecture"
+description: "How it all connects — the diagram that is the code."
+icon: "Network"
+source: "docs/spec/console.md"
+---
+
+Answers: **how it all connects — the diagram that _is_ the code**
+
+<Callout title="Governing rule">
+  Flows answers “which one”; Architecture answers “what shape”. Never shows the whole system by
+  default.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Unit clusters" description="Default aggregated edges; focus one or two hops." />
+  <Card title="Element layers" description="Toggle data, messaging, time, external edges." />
+  <Card
+    title="Live traffic"
+    description="Edge thickness from real traffic; dashed = never traversed."
+  />
+  <Card
+    title="Pathologies"
+    description="Cycles, god nodes, orphan signals, SPOFs — computed from the graph."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

package/site/content/docs/console/channels.mdx

@@ -0,0 +1,37 @@
+---
+title: "Channels"
+description: "Templates, delivery receipts, bounces, opt-outs."
+icon: "Mailbox"
+source: "docs/spec/console.md"
+---
+
+Answers: **templates, delivery receipts, bounces, opt-outs, deliverability (SPF/DKIM/DMARC)**
+
+<Callout title="Governing rule">
+  Suppression is not failure — the taxonomy of “did not arrive” has seven states with verdicts.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Dev inbox" description="`console` driver lands every medium locally." />
+  <Card
+    title="Deliverability"
+    description="SPF/DKIM/DMARC, bounces, complaints, suppression list."
+  />
+  <Card
+    title="Fallback chains"
+    description="Recorded as chains (e.g. WhatsApp → SMS), not single outcomes."
+  />
+  <Card
+    title="Locale previews"
+    description="Template data bound to schema; RTL-accurate previews."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full + console inbox" />
+  <Card title="Prod" description="send test, inspect delivery" />
+</Cards>