okengine 0.1.4 → 0.2.1

package/AGENTS.md

@@ -76,7 +76,7 @@ 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`; templates are the `examples/*` trees.
+- `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`).
 
 Engine: Bun `>=1.3`.
 

package/README.md

@@ -2,13 +2,21 @@
 
 *"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."*
 
+[![npm](https://img.shields.io/npm/v/okengine.svg)](https://www.npmjs.com/package/okengine)
+[![JSR](https://jsr.io/badges/@omqkhafi/okengine)](https://jsr.io/@omqkhafi/okengine)
+[![npm](https://img.shields.io/npm/v/create-oke.svg)](https://www.npmjs.com/package/create-oke)
 [![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)
 
-**Package:** `okengine` · **CLI:** `oke` · **License:** MIT
+**Framework:** [`okengine`](https://www.npmjs.com/package/okengine) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke) · **Docs:** [oke.dev](https://oke.dev) · **License:** MIT
 
-JSR (`@omqkhafi/okengine`) does not support npm-style `exports` wildcards — import deep drivers (`okengine/drivers/…`) from the npm package, not JSR. The `okengine/drivers` index is available on both.
+### Install
 
+```bash
+bun add okengine                 # npm (recommended — ships the `oke` CLI)
+bunx jsr add @omqkhafi/okengine  # JSR — library API only
+bunx create-oke@latest my-app --template hello   # scaffold from npm
+```
 ---
 
 ## Start here
@@ -27,14 +35,14 @@ Eight elements cover what a backend needs. Ten exports are the whole public voca
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Detail and comparisons live in [`docs/spec/unified-theory.md`](docs/spec/unified-theory.md).
+Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Handbook: [oke.dev/docs](https://oke.dev/docs). Spec depth: [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
 
 ---
 
 ## Run something in two minutes
 
 ```bash
-bunx create-oke@latest my-app
+bunx create-oke@latest my-app --template hello
 cd my-app
 oke dev
 ```
@@ -43,9 +51,13 @@ oke dev
 |---|---|
 | `:6530` | your app |
 | `:6533` | Console |
-| `:6535` | MCP |
+| `:6535` | MCP (your live Manifest, for agents) |
+
+Mnemonic: **O·K·E = 6·5·3**. Docs MCP for the handbook is a separate surface on `:6536` (search/fetch only — see [Documentation](#documentation)).
+
+That scaffolds the **hello** starter — one flow, no Store, the fastest true "it works" moment. Default without `--template` is **standard** (full recommended file layout, empty scaffolding). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
 
-That scaffolds the **Notes** app (same tree as [`examples/notes`](examples/notes)). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
+Prefer a worked teaching app (business logic + comments)? Use `--from-example notes|linkly|provisions|skyport` instead.
 
 ### The idea, in one file
 
@@ -119,7 +131,9 @@ The rest of the scaffold is small and ordinary: `oke.config.ts` (drivers by prot
 
 ## How to learn (read in order)
 
-Each app adds the smallest next set of ideas. Do not skip ahead.
+Start on the site if you want the handbook path: [Introduction](https://oke.dev/docs/get-started/introduction) → [Installation](https://oke.dev/docs/get-started/installation) → [Basic usage](https://oke.dev/docs/get-started/basic-usage).
+
+Each teaching app adds the smallest next set of ideas. Do not skip ahead.
 
 1. **Notes** — `oke`, `on`, `flow`, `http`, `store.sql`, `fx`, typed errors, typed client  
    → [`examples/notes`](examples/notes)
@@ -133,7 +147,17 @@ Each app adds the smallest next set of ideas. Do not skip ahead.
 4. **Skyport** — `ai`, multi-tenancy, SLOs, distributed topology, scaling axes  
    → [`examples/skyport`](examples/skyport)
 
-Spec that teaches the same path: [`docs/spec/four-applications.md`](docs/spec/four-applications.md).
+Same path in the spec: [`docs/spec/four-applications.md`](docs/spec/four-applications.md).
+
+---
+
+## Documentation
+
+- **Site** — [oke.dev](https://oke.dev) (landing) · [oke.dev/docs](https://oke.dev/docs) (handbook) · [changelog](https://oke.dev/changelog)
+- **Agents on the site** — [`/llms.txt`](https://oke.dev/llms.txt) index · [`/llms-full.txt`](https://oke.dev/llms-full.txt) full text · `/llms.mdx/docs/...` per-page markdown
+- **Docs MCP** — `:6536` · tools `oke.docs.search` / `oke.docs.get` (read-only; Host/Origin validated like the other surfaces)
+- **App MCP** — `:6535` · live Manifest, schemas, effects, traces, Console-safe actions (Bearer + confirmation for writes)
+- **Canonical specs in-repo** — [`docs/spec/`](docs/spec) (unified theory, four applications, Console)
 
 ---
 
@@ -180,7 +204,7 @@ flowchart TD
 
 Seventeen panels on `:6533` (app `:6530`, MCP `:6535`): Overview, Flows, Signals, Store, Clock, Gates, Vault, Channels, AI, Architecture, Traces, Runs, Manifest Diff, Access, Plugins — plus Privacy and Tenancy when those plugins are plugged.
 
-Operator and user planes stay separate. Every Console action is a real flow through `fx`, so the audit log is the trace. → [`docs/spec/console.md`](docs/spec/console.md)
+Operator and user planes stay separate. Every Console action is a real flow through `fx`, so the audit log is the trace. Spec: [`docs/spec/console.md`](docs/spec/console.md) · handbook: [oke.dev/docs/console](https://oke.dev/docs/console/overview).
 
 ---
 
@@ -302,7 +326,7 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 
 `.plug()` attaches a plugin. Scope is the attachment point: `app.plug()` app-wide, `unit.plug()` one unit, `flow.plug()` one flow. No `global: true`, no inheritance rule — [unified theory §14](docs/spec/unified-theory.md#14-plugins--the-extensibility-law).
 
-The Console is treated as internet-facing even on localhost. Host header validation, Origin validation, and authentication are mandatory on `:6530`, `:6533`, and `:6535` ([console.md §10](docs/spec/console.md#10-security-posture)): two-plane auth (operator vs user), capability-scoped tokens.
+The Console is treated as internet-facing even on localhost. Host header validation, Origin validation, and authentication are mandatory on `:6530`, `:6533`, and `:6535` ([console.md §10](docs/spec/console.md#10-security-posture)): two-plane auth (operator vs user), capability-scoped tokens. Docs MCP `:6536` uses the same Host/Origin checks and stays read-only (no Bearer writes).
 
 ---
 
@@ -316,12 +340,21 @@ The Console is treated as internet-facing even on localhost. Host header validat
 
 ---
 
+## Budgets
+
+Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with `bun run budgets`.
+
+---
+
 ## Status
 
-Pre-1.0. MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
+Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [oke.dev](https://oke.dev). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
 
-| Spec | Path |
+| Resource | Path |
 |---|---|
-| 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) |
+| Docs site | [oke.dev](https://oke.dev) · [handbook](https://oke.dev/docs) · [changelog](https://oke.dev/changelog) |
+| Unified theory | [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md) |
+| Four applications | [`docs/spec/four-applications.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/four-applications.md) |
+| Console | [`docs/spec/console.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/console.md) |
+| Scaffold | [`packages/create-oke`](https://github.com/omqkhafi/okengine/tree/main/packages/create-oke) |
+| Changelog source | [`docs/changelog.md`](docs/changelog.md) |

package/docs/spec/{complete-example.md → example.md}

@@ -1149,7 +1149,6 @@ oke images pin                   # tags → digests in oke.images.lock
 
 oke build --target edge          # < 15 kB kernel profile
 oke eval                         # run prompt eval sets; fails CI on regression
-oke ai cost --since 7d           # cost per flow, per tenant, per prompt version
 oke branch prod --at "yesterday" # fork journaled state into a sandbox
 oke privacy erase --subject <id> # crypto-shredding: deletes the key, not the terabytes
 oke upgrade                      # run codemods for a breaking change, print the diff

package/docs/spec/unified-theory.md

@@ -416,7 +416,7 @@ Plus `oke import express|hono|elysia` codemods for the mechanical parts. Migrati
 |---|---|
 | Kernel (edge profile) | < 15 kB |
 | Client runtime | < 3 kB |
-| Cold start on Bun | < 75 ms |
+| Cold start on Bun | < 75 ms in CI (GitHub Actions runners are less predictable than a dev machine); measured ~25–30 ms on real hardware |
 | p99 routing overhead | < 1 ms |
 
 A regression fails OKE's own build. Claims we cannot measure, we do not make.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,9 @@
     "url": "git+https://github.com/omqkhafi/okengine.git"
   },
   "workspaces": [
-    "examples/*"
+    "packages/*",
+    "examples/*",
+    "site"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -44,10 +46,13 @@
     "gate:errors": "bun test src/kernel/errors.registry.test.ts",
     "gate:codemods": "bun test src/upgrade/codemods.test.ts",
     "test:examples": "bun test examples/notes && bun test examples/linkly && bun test examples/provisions && bun test examples/skyport",
-    "test:create-oke": "bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
+    "test:create-oke": "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",
     "test:doc-drift": "bun src/cli/doc-drift.ts",
+    "site:sync": "bun run --cwd site sync",
+    "site:dev": "bun run --cwd site dev",
+    "site:build": "bun run --cwd site build",
     "test:skyport-docker": "bun test examples/skyport/tests/docker.test.ts",
-    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
+    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run site:build && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
     "gate:publish": "bun test scripts/publish.gate.test.ts",
     "bump": "bun run scripts/bump-version.ts",
     "publish:all": "bun run scripts/publish.ts",
@@ -60,13 +65,13 @@
   },
   "dependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",
-    "age-encryption": "^0.3.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "oxc-parser": "^0.141.0",
     "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",
@@ -103,11 +108,16 @@
     "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"
+    "drizzle-seed": ">=0.3.0",
+    "zod": ">=3.23.0"
   },
   "peerDependenciesMeta": {
+    "age-encryption": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },
@@ -116,13 +126,16 @@
     },
     "drizzle-seed": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {
     "bun": ">=1.3"
   },
   "bin": {
-    "oke": "./src/cli/index.ts"
+    "oke": "src/cli/index.ts"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -149,4 +162,4 @@
     "AGENTS.md",
     "docs/spec"
   ]
-}
+}

package/src/auth/index.ts

@@ -3,6 +3,7 @@
  * plus a provider seam. Subpath: `okengine/auth`.
  *
  * Two planes — `fx.operator` vs `fx.auth` — permanently separated.
+ * @module
  */
 
 export { auth, type AuthPluginOptions } from "./plugin.ts";

package/src/cli/dev.ts

@@ -500,7 +500,9 @@ async function startAppHot(
     if (stopped) return;
     stopped = true;
     try {
-      proc.kill();
+      // SIGKILL so `bun --hot` cannot linger and hold the project directory
+      // open (create-oke afterEach `rmSync` otherwise races the child exit).
+      proc.kill("SIGKILL");
     } catch {
       // already exited
     }

package/src/cli/doc-drift.ts

@@ -14,6 +14,10 @@
  * Usage:
  *   bun src/cli/doc-drift.ts
  *   bun src/cli/doc-drift.ts docs/spec/four-applications.md README.md
+ *   bun src/cli/doc-drift.ts site/content/docs/learn/notes.md
+ *
+ * Default paths: four-applications.md, README.md, and every markdown/MDX file
+ * under site/content/docs (claimed fences only — prose-only pages skip).
  */
 
 import { resolve } from "node:path";
@@ -21,8 +25,27 @@ import { Window } from "happy-dom";
 
 const ROOT = resolve(import.meta.dir, "../..");
 
-/** Default docs checked when no CLI paths are passed. */
-const DEFAULT_DOCS: readonly string[] = [
+/**
+ * Discover site content markdown that may contain claimed fences.
+ *
+ * @param root - Repo root
+ */
+async function discoverSiteDocs(root: string): Promise<string[]> {
+  const docsDir = resolve(root, "site/content/docs");
+  const out: string[] = [];
+  try {
+    const glob = new Bun.Glob("**/*.{md,mdx}");
+    for await (const rel of glob.scan({ cwd: docsDir, onlyFiles: true })) {
+      out.push(resolve(docsDir, rel));
+    }
+  } catch {
+    // site/ not present yet — skip
+  }
+  return out.sort();
+}
+
+/** Core docs that must contain claimed fences. */
+const REQUIRED_DOCS: readonly string[] = [
   resolve(ROOT, "docs/spec/four-applications.md"),
   resolve(ROOT, "README.md"),
 ];
@@ -315,6 +338,9 @@ export async function checkDocDrift(
 /**
  * Run doc-drift over one or more markdown files.
  *
+ * Site content under `site/` may have zero claimed fences (prose-only pages);
+ * only `docs/spec/four-applications.md` and `README.md` require at least one.
+ *
  * @param paths - Absolute or repo-relative markdown paths
  */
 export async function runDocDrift(
@@ -324,32 +350,36 @@ export async function runDocDrift(
   let ok = true;
   let total = 0;
   let mermaidTotal = 0;
+  let checkedFiles = 0;
 
   for (const path of paths) {
     const abs = resolve(ROOT, path);
     const label = abs.startsWith(ROOT + "/")
       ? abs.slice(ROOT.length + 1)
       : abs;
+    const requireClaimed = !label.startsWith("site/");
     const markdown = await Bun.file(abs).text();
     const fences = parseClaimedFences(markdown);
     if (fences.length === 0) {
-      messages.push(`doc-drift: no claimed fences found in ${label}`);
-      ok = false;
-      continue;
-    }
-
-    const result = await checkDocDrift(fences);
-    total += fences.length;
-    if (!result.ok) {
-      ok = false;
-      messages.push(
-        `doc-drift: ${result.failures.length} failure(s) in ${label}`,
-      );
-      for (const f of result.failures) messages.push(`  · ${f}`);
+      if (requireClaimed) {
+        messages.push(`doc-drift: no claimed fences found in ${label}`);
+        ok = false;
+      }
     } else {
-      messages.push(
-        `doc-drift: ok — ${fences.length} claimed fence(s) in ${label}`,
-      );
+      checkedFiles++;
+      const result = await checkDocDrift(fences);
+      total += fences.length;
+      if (!result.ok) {
+        ok = false;
+        messages.push(
+          `doc-drift: ${result.failures.length} failure(s) in ${label}`,
+        );
+        for (const f of result.failures) messages.push(`  · ${f}`);
+      } else {
+        messages.push(
+          `doc-drift: ok — ${fences.length} claimed fence(s) in ${label}`,
+        );
+      }
     }
 
     const mermaidFences = parseMermaidFences(markdown);
@@ -370,11 +400,11 @@ export async function runDocDrift(
     }
   }
 
-  if (ok && paths.length > 1) {
+  if (ok && checkedFiles > 1) {
     const mermaidNote =
       mermaidTotal > 0 ? ` · ${mermaidTotal} mermaid fence(s)` : "";
     messages.push(
-      `doc-drift: ok — ${total} claimed fence(s) across ${paths.length} file(s)${mermaidNote}`,
+      `doc-drift: ok — ${total} claimed fence(s) across ${checkedFiles} file(s)${mermaidNote}`,
     );
   }
 
@@ -383,7 +413,10 @@ export async function runDocDrift(
 
 async function main(): Promise<number> {
   const args = process.argv.slice(2);
-  const paths = args.length > 0 ? args : DEFAULT_DOCS;
+  const paths =
+    args.length > 0
+      ? args
+      : [...REQUIRED_DOCS, ...(await discoverSiteDocs(ROOT))];
   const { ok, messages } = await runDocDrift(paths);
   for (const m of messages) {
     if (ok) console.log(m);

package/src/client/index.ts

@@ -2,6 +2,7 @@
  * Typed client (+ live). Subpath: `okengine/client`.
  *
  * First Manifest derivation: `type App` → fully typed client, zero codegen.
+ * @module
  */
 
 export { createClient, flattenRoutes } from "./create.ts";

package/src/config/index.ts

@@ -2,6 +2,7 @@
  * `oke.config.ts` surface. Subpath: `okengine/config`.
  *
  * Driver maps are protocol-named; vendor/image choice lives in `images`.
+ * @module
  */
 
 /** Environment role keys used in driver maps. */

package/src/console/index.ts

@@ -3,28 +3,41 @@
  *
  * Built on `createClient<ConsoleApp>`. Every action is a real flow through `fx`;
  * the audit log is the trace (docs/spec/console.md).
+ *
+ * Imports leaf modules (not `server/index`) so unused panel projectors stay out
+ * of the `okengine/console` graph when tree-shaken.
+ *
+ * @module
  */
 
 export {
   bootConsoleApp,
+  createConsoleApp,
+  type ConsoleApp,
+  type ConsoleAppHandle,
+  type CreateConsoleAppOptions,
+} from "./server/app.ts";
+export {
   CLAIM_TTL_MS,
+  mintClaimCode,
+  printClaimCodeOnce,
+  verifyClaimCode,
+} from "./server/claim.ts";
+export { feedManifest } from "./server/live.ts";
+export { consolePlugin } from "./server/plugin.ts";
+export {
   CONSOLE_COOKIES,
   CONSOLE_CSP,
   PLUGIN_IFRAME_SANDBOX,
-  consolePlugin,
-  createConsoleApp,
-  createConsoleState,
-  feedManifest,
-  mintClaimCode,
-  printClaimCodeOnce,
+  withConsoleSecurityHeaders,
+} from "./server/security-headers.ts";
+export {
   serveConsole,
   startConsoleApp,
-  verifyClaimCode,
-  withConsoleSecurityHeaders,
-  type ConsoleApp,
-  type ConsoleAppHandle,
   type ConsoleServerHandle,
-  type ConsoleState,
-  type CreateConsoleAppOptions,
   type ServeConsoleOptions,
-} from "./server/index.ts";
+} from "./server/serve.ts";
+export {
+  createConsoleState,
+  type ConsoleState,
+} from "./server/state.ts";

package/src/console/server/app.ts

@@ -140,16 +140,53 @@ export async function bootConsoleApp(
     if (!runs) return [];
     return runs.all();
   };
-  await bindManifestSignalBus(handle.state);
-  await bindManifestStoreRuntime(handle.state);
-  await bindManifestVaultRuntime(handle.state);
-  await bindManifestGateRuntime(handle.state);
-  await bindManifestClockRuntime(handle.state);
-  bindManifestAiRuntime(handle.state);
-  bindManifestChannelRuntime(handle.state);
+  // Element runtimes bind lazily on first panel access (see ensure* below
+  // via list* methods / bindManifest* callers) — not all seventeen at boot.
   return handle.app;
 }
 
+/**
+ * Ensure Manifest-backed element runtimes for a panel are bound (idempotent).
+ *
+ * @param state - Console state
+ * @param panel - Panel id that was visited
+ */
+export async function ensureConsolePanelRuntimes(
+  state: ConsoleState,
+  panel:
+    | "signals"
+    | "store"
+    | "vault"
+    | "gates"
+    | "clock"
+    | "ai"
+    | "channels",
+): Promise<void> {
+  switch (panel) {
+    case "signals":
+      await bindManifestSignalBus(state);
+      break;
+    case "store":
+      await bindManifestStoreRuntime(state);
+      break;
+    case "vault":
+      await bindManifestVaultRuntime(state);
+      break;
+    case "gates":
+      await bindManifestGateRuntime(state);
+      break;
+    case "clock":
+      await bindManifestClockRuntime(state);
+      break;
+    case "ai":
+      bindManifestAiRuntime(state);
+      break;
+    case "channels":
+      bindManifestChannelRuntime(state);
+      break;
+  }
+}
+
 /**
  * Bind a ChannelRuntime + console inbox from the Manifest when no host
  * runtime is attached — Console surfaces real receipts / inbox, not mocks.

package/src/console/server/flows.ts

@@ -30,14 +30,10 @@ import {
 } from "./clock.ts";
 import { createFileDiff, emitStructuralDiff } from "./structural.ts";
 import type { ConsoleState } from "./state.ts";
+import { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 import { tenancyDeclared } from "./store.ts";
 
-/** Flows that may run without an operator session. */
-export const PUBLIC_CONSOLE_FLOWS = new Set([
-  "console.setup.status",
-  "console.setup.claim",
-  "console.session.login",
-]);
+export { PUBLIC_CONSOLE_FLOWS };
 
 const SetupStatusOut = z.object({
   setupClosed: z.boolean(),

package/src/console/server/index.ts

@@ -30,6 +30,7 @@ export {
   bindManifestVaultRuntime,
   bootConsoleApp,
   createConsoleApp,
+  ensureConsolePanelRuntimes,
   type ConsoleApp,
   type ConsoleAppHandle,
   type CreateConsoleAppOptions,
@@ -72,8 +73,8 @@ export {
 } from "./claim.ts";
 export {
   createConsoleBindings,
-  PUBLIC_CONSOLE_FLOWS,
 } from "./flows.ts";
+export { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 export {
   createLiveWebsocket,
   feedManifest,

package/src/console/server/lazy-panels.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Console per-panel backends construct lazily on first access.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createConsoleState } from "./state.ts";
+
+describe("console — lazy panel construction", () => {
+  test("createConsoleState constructs no panel backends", () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    expect([...state.constructedPanels]).toEqual([]);
+  });
+
+  test("only the visited panel is constructed", async () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    expect([...state.constructedPanels]).toEqual([]);
+
+    await state.listVault();
+    expect([...state.constructedPanels]).toEqual(["vault"]);
+
+    await state.listStores();
+    expect([...state.constructedPanels].sort()).toEqual(["store", "vault"]);
+
+    await state.listVault();
+    expect([...state.constructedPanels].sort()).toEqual(["store", "vault"]);
+  });
+});

package/src/console/server/panel-load.ts

@@ -0,0 +1,28 @@
+/**
+ * Lazy Console panel module loader — expression `new URL` keeps panel
+ * backends out of the createConsoleState / createConsoleApp graph until
+ * first access (mirrors kernel boot-bind).
+ */
+
+/** Panel ids that own server-side projection / mutation modules. */
+export type ConsolePanelId =
+  | "access"
+  | "gates"
+  | "signals"
+  | "store"
+  | "clock"
+  | "vault"
+  | "ai"
+  | "channels"
+  | "plugins"
+  | "diff";
+
+/**
+ * Load a Console panel module by id without bundling it into the parent.
+ *
+ * @param id - Panel module stem (`store`, `vault`, …)
+ */
+export async function loadConsolePanel<T>(id: ConsolePanelId): Promise<T> {
+  const url = new URL(`./${id}.ts`, import.meta.url);
+  return import(url.href) as Promise<T>;
+}

package/src/console/server/plugin.ts

@@ -10,7 +10,7 @@ import {
   type Fx,
   type PluginDef,
 } from "../../kernel/index.ts";
-import { PUBLIC_CONSOLE_FLOWS } from "./flows.ts";
+import { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 
 /**
  * Builtin Console plugin.