okengine 0.2.6 → 0.3.2

package/package.json

@@ -1,39 +1,72 @@
 {
   "name": "okengine",
-  "version": "0.2.6",
+  "version": "0.3.2",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
-  "type": "module",
-  "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git+https://github.com/omqkhafi/okengine.git"
   },
+  "bin": {
+    "oke": "src/cli/index.ts"
+  },
   "workspaces": [
     "packages/*",
-    "examples/*",
     "site"
   ],
+  "files": [
+    "src",
+    "manifest.v1.schema.json",
+    "AGENTS.md",
+    "README.md",
+    "site/content/docs"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./test": "./src/test/index.ts",
+    "./config": "./src/config/index.ts",
+    "./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",
+    "./gate": "./src/elements/gate.ts",
+    "./vault": "./src/elements/vault.ts",
+    "./channel": "./src/elements/channel.ts",
+    "./ai": "./src/elements/ai.ts",
+    "./runs": "./src/runs/index.ts",
+    "./drivers": "./src/drivers/index.ts",
+    "./drivers/*": "./src/drivers/*"
+  },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && bun run --cwd packages/create-oke typecheck",
+    "lint": "oxlint --quiet",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
     "test": "bun test --pass-with-no-tests",
     "test:coverage": "bun test --coverage --pass-with-no-tests",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
-    "test:integration": "bun test examples/notes examples/linkly examples/provisions examples/skyport examples/skyport/tests/docker.test.ts && bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
     "build": "bunx vite build --config src/console/ui/vite.config.ts",
     "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 test src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.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 bench && bun run typecheck && bun run test && bun run budgets && bun run gate && bun run site:build && bun run test:integration",
+    "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"
   },
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "@duckdb/node-api": "^1.5.5-r.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -41,7 +74,6 @@
     "sently": "^0.8.0"
   },
   "devDependencies": {
-    "age-encryption": "^0.3.0",
     "@base-ui/react": "^1.6.0",
     "@codemirror/commands": "^6.10.4",
     "@codemirror/lang-json": "^6.0.2",
@@ -68,6 +100,9 @@
     "gflows": "^1.2.1",
     "happy-dom": "^20.11.1",
     "mermaid": "^11.16.0",
+    "oxfmt": "^0.61.0",
+    "oxlint": "^1.76.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "playwright": "^1.62.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -78,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
     },
@@ -103,33 +134,5 @@
   },
   "engines": {
     "bun": ">=1.3"
-  },
-  "bin": {
-    "oke": "src/cli/index.ts"
-  },
-  "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client/index.ts",
-    "./test": "./src/test/index.ts",
-    "./config": "./src/config/index.ts",
-    "./auth": "./src/auth/index.ts",
-    "./console": "./src/console/index.ts",
-    "./mcp": "./src/mcp/index.ts",
-    "./store": "./src/elements/store.ts",
-    "./signal": "./src/elements/signal.ts",
-    "./clock": "./src/elements/clock.ts",
-    "./gate": "./src/elements/gate.ts",
-    "./vault": "./src/elements/vault.ts",
-    "./channel": "./src/elements/channel.ts",
-    "./ai": "./src/elements/ai.ts",
-    "./runs": "./src/runs/index.ts",
-    "./drivers": "./src/drivers/index.ts",
-    "./drivers/*": "./src/drivers/*"
-  },
-  "files": [
-    "src",
-    "spec",
-    "AGENTS.md",
-    "docs/spec"
-  ]
+  }
 }

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>

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

@@ -0,0 +1,31 @@
+---
+title: "Clock"
+description: "Upcoming crons, sleeping durable flows, journal."
+icon: "Clock"
+source: "docs/spec/console.md"
+---
+
+Answers: **upcoming crons, sleeping durable flows, journal**
+
+<Callout title="Governing rule">
+  Looks like time — a forward timeline for schedules and pending wakes, not a flat grid.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Schedules"
+    description="Recurring crons with drift, overdue, catch-up, lease holder."
+  />
+  <Card title="Pending wakes" description="Every sleeping durable flow and when it wakes." />
+  <Card title="DST warnings" description="Only when the schedule falls in an ambiguous window." />
+  <Card title="Actions" description="Run now, wake early, pause, edit when overridable." />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="trigger/pause; edit if `overridable`" />
+</Cards>

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

@@ -0,0 +1,31 @@
+---
+title: "Flows"
+description: "What exists; call it; read its contract."
+icon: "GitBranch"
+source: "docs/spec/console.md"
+---
+
+Answers: **what exists; call it; read its contract**
+
+<Callout title="Governing rule">
+  Renders the one law as three columns: `Causes ← Flows → Effects` — not a tree.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Causes column" description="Triggers and callers — what runs this." />
+  <Card title="Flows column" description="Context-adaptive centre with contracts and invoke." />
+  <Card title="Effects column" description="What changes — store, signal, channel, AI, vault." />
+  <Card
+    title="Flow drawer"
+    description="Workshop peek/expand — save as bun:test from a real response."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full + source links" />
+  <Card title="Prod" description="read + invoke per gates" />
+</Cards>

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

@@ -0,0 +1,35 @@
+---
+title: "Gates"
+description: "Permission matrix, rate counters, MFA map."
+icon: "Shield"
+source: "docs/spec/console.md"
+---
+
+Answers: **permission matrix, rate counters, MFA map**
+
+<Callout title="Governing rule">
+  Refuse the giant roles×permissions matrix as the entry point — inquire from principal or from
+  flow.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Simulator" description="Gate chain in evaluation order — where a 403 stopped." />
+  <Card
+    title="Unguarded flows"
+    description="Continuous audit: public user-plane flows after deploy."
+  />
+  <Card title="Deploy diff" description="Permission widening caught from Manifest Diff." />
+  <Card
+    title="Plane separation"
+    description="Operator holding an application scope is a violation."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="limits if `overridable`" />
+</Cards>

package/site/content/docs/console/manifest-diff.mdx

@@ -0,0 +1,34 @@
+---
+title: "Manifest Diff"
+description: "Blast radius of a deploy: new effects, widened permissions."
+icon: "Diff"
+source: "docs/spec/console.md"
+---
+
+Answers: **blast radius of a deploy: new effects, widened permissions**
+
+<Callout title="Governing rule">
+  Compares meaning rather than lines — behaviour change, sorted by blast radius.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Contract breaking" description="Existing clients will fail." />
+  <Card
+    title="Permission widening"
+    description="Attack surface grew — gate removed or scope widened."
+  />
+  <Card title="Effect widening" description="New write, external effect, or secret read." />
+  <Card
+    title="CI gate"
+    description="Blocks undeclared breaks; intended breaks need `breaking: true`."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>