okengine 0.17.2 → 0.18.4

package/site/content/docs/get-started/testing.mdx

@@ -0,0 +1,328 @@
+---
+title: Testing
+description: Write deterministic tests for your Flows with createTestApp — freeze the clock, mock AI, drain signals, and prove side effects.
+icon: FlaskConical
+---
+
+`createTestApp` boots the **same app** you deploy, but with memory drivers and a
+frozen clock. You drive it through `t.api`, `t.auth`, `t.signals`, `t.clock`,
+and `t.channels` — every assertion is deterministic.
+
+<Callout title="The one rule">
+  Boot the same `app` your server boots. Assert only through the harness surfaces (`t.api`,
+  `t.auth`, `t.signals`, `t.clock`, `t.channels`, `t.ai`, `t.effects`) — never reach into internal
+  runtimes.
+</Callout>
+
+## Import
+
+The harness ships as a separate subpath so production bundles stay small:
+
+```typescript title="tests/orders.test.ts"
+import { describe, expect, test } from "bun:test";
+import { createTestApp } from "okengine/testing"; // or "okengine/test"
+import { app } from "../src/app";
+
+test("orders flow", async () => {
+  const t = await createTestApp(app);
+  // ...
+  await t.close();
+});
+```
+
+Both `okengine/testing` and `okengine/test` are aliases. Use `okengine/testing`
+(→ `dist/testing.js`) for published packages and hoisted monorepos; `okengine/test`
+is the source-only path older starters use.
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Adopt your Flows
+
+Every behavior on the app is reachable. No separate test database or server.
+
+```typescript title="src/flows/orders/index.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+
+export const create = on(
+  http.post("/orders").gate(member),
+  flow("orders.create", {
+    in: z.object({ sku: z.string(), qty: z.number() }),
+    out: z.object({ id: z.string() }),
+    do: async (input, fx) => {
+      const id = fx.id();
+      await fx.emit(orderPlaced, { orderId: id, ...input });
+      return { id };
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Boot the harness
+
+```typescript title="tests/orders.test.ts"
+const t = await createTestApp(app, { gates: [member] });
+```
+
+</Step>
+
+<Step>
+### Login and call
+
+```typescript
+const u = await t.auth.loginAs({ scopes: ["order:create"] });
+const { data, error } = await t.api.orders.create({ sku: "COFFEE", qty: 2 }, { as: u });
+expect(error).toBeNull();
+expect(data).toEqual({ id: expect.any(String) });
+```
+
+</Step>
+
+<Step>
+### Advance time and drain signals
+
+Signal handlers and Clocks are processed deterministically:
+
+```typescript
+await t.signals.drain(); // run queued signal work
+await t.clock.advance("2m"); // tick scheduled Clocks forward
+expect(t.channels.sent()).toContainEqual(expect.objectContaining({ template: "order-confirmed" }));
+```
+
+</Step>
+
+</Steps>
+
+## Harness surface
+
+| Property                                    | What it does                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `t.api.<unit>.<flow>(input, opts?)`         | Invoke an adopted Flow directly with a `{ as }` principal and optional `{ tenant }`    |
+| `t.auth.loginAs(options)`                   | Returns a verified `TestUser` with `id`, `scopes`, `verified`, and optional `tenantId` |
+| `t.clock.advance(by)` / `t.clock.now()`     | Freeze and move the harness clock (used by durable sleeps and Clocks)                  |
+| `t.cron.run(name)`                          | Run a named Clock / `every()` interval now, still leader-elected                       |
+| `t.signals.drain()`                         | Drain the signal bus until idle (deterministic queued work)                            |
+| `t.signals.subscribeLive(signal, handlers)` | Subscribe to a `delivery: "live"` signal's event stream (deterministic)                |
+| `t.signals.waitForLive(signal, predicate)`  | Resolve once a live event matching `predicate` arrives                                 |
+| `t.channels.sent()`                         | Receipts / inbox entries sent during the test                                          |
+| `t.ai.mock(prompt, output)`                 | Register a canned mock response for a Prompt                                           |
+| `t.ai.cost()`                               | Accumulated AI cost across `fx.ask` calls                                              |
+| `t.effects.of(runId)`                       | Effect ledger for a recorded run (reads / writes / emits / sends)                      |
+| `t.runs()`                                  | All wide events recorded during the test                                               |
+| `t.close()`                                 | Close booted element runtimes                                                          |
+
+## Multi-tenancy & RLS
+
+With `gate.auth: { tenant: true }` you can test tenant isolation with real
+row-level security.
+
+```typescript title="src/db/documents.ts"
+import { store, field } from "okengine";
+
+export const documents = store.schema.table(
+  "documents",
+  {
+    id: field.text().primaryKey(),
+    tenant_id: field.text().notNull(),
+    title: field.text().notNull(),
+  },
+  [store.schema.policy.tenant("tenant_id", { for: "all" })],
+);
+```
+
+Give each test user a tenant, and drive distinct tenants against the same
+
+Flow:
+
+```typescript title="tests/tenant.test.ts"
+const t = await createTestApp(app, {
+  gates: [member],
+  boot: { config: { drivers: { store: { sql: { test: "pglite" } } } } },
+});
+
+const alice = await t.auth.loginAs({ id: "alice", tenantId: "acme" });
+const bob = await t.auth.loginAs({ id: "bob", tenantId: "globex" });
+
+await t.api.docs.create({ title: "Acme Roadmap" }, { as: alice });
+await t.api.docs.create({ title: "Globex Secrets" }, { as: bob });
+
+const acmeDocs = await t.api.docs.list(undefined, { as: alice });
+expect(acmeDocs.data).toHaveLength(1); // only Acme Roadmap
+```
+
+Re-scope a single call to another tenant with `{ tenant }`, independent of the
+principal's own tenant:
+
+```typescript
+const carol = await t.auth.loginAs({ id: "carol", tenantId: "acme" });
+const { data } = await t.api.docs.create(
+  { title: "Globex Carol" },
+  { as: carol, tenant: "globex" },
+);
+expect(data.tenantId).toBe("globex");
+```
+
+RLS policies are row-level: tenant-scoped tables need `store.schema.policy.tenant`
+(or `store.schema.unscoped()` for genuinely global tables). Harness boots do not
+run migrations — in a real app `oke db push` installs those policies.
+
+## Deterministic live signals
+
+Signals with `delivery: "live"` back client feeds and SSE streams. The harness
+exposes the retained event stream so you can assert both sides deterministically:
+
+```typescript title="tests/live.test.ts"
+const orderStatus = signal("order-status", {
+  delivery: "live",
+  retention: { maxCount: 10 },
+});
+
+on(
+  http.post("/orders/status").public(),
+  flow("orders.updateStatus", {
+    in: z.object({ orderId: z.string(), status: z.string() }),
+    effects: { emits: ["order-status"] },
+    do: async (input, fx) => {
+      await fx.emit(orderStatus, input);
+      return { ok: true };
+    },
+  }),
+);
+```
+
+```typescript
+const seen: Array<{ orderId: string; status: string }> = [];
+
+const unsubscribe = t.signals.subscribeLive(orderStatus, {
+  onEvent: (event) => seen.push(event),
+});
+
+await t.api.orders.updateStatus({ orderId: "o1", status: "placed" });
+await t.signals.drain();
+expect(seen.map((e) => e.status)).toEqual(["placed"]);
+
+// Resolve a promise the moment a matching event arrives.
+const deliveredPromise = t.signals.waitForLive(
+  orderStatus,
+  (event) => event.status === "delivered",
+);
+await t.api.orders.updateStatus({ orderId: "o1", status: "delivered" });
+await t.signals.drain();
+const delivered = await deliveredPromise;
+expect(delivered.status).toBe("delivered");
+
+unsubscribe(); // no further events observed
+```
+
+Call `t.signals.drain()` after each emit — live events are staged until the bus
+drains. `retention` caps the replayed tape (`maxCount` / `maxAge`); it is only
+valid on `delivery: "live"` signals.
+
+## Time travel
+
+`t.clock` freezes time. `t.clock.advance("2m")` moves the clock forward and
+resumes any durable sleeps that become due. `t.cron.run("expire-stale")` runs a
+named Clock now:
+
+```typescript
+await t.clock.advance("30s"); // durable sleeps resume
+await t.cron.run("expire-stale"); // named Clock fires
+expect(t.channels.sent()).toHaveLength(1); // side effect observed
+```
+
+## AI & channels
+
+`fx.ask` routes to a mock driver. Register canned outputs and read accumulated
+cost:
+
+```typescript
+t.ai.mock(summarizePrompt, { title: "Mock summary" });
+const { data } = await t.api.posts.summarize({ postId: "p_1" }, { as: u });
+expect(data).toEqual({ title: "Mock summary" });
+expect(t.ai.cost()).toBe(0);
+```
+
+Channels write to an inbox instead of a transport:
+
+```typescript
+expect(t.channels.sent()).toContainEqual(
+  expect.objectContaining({ template: "order-confirmed", to: u.id }),
+);
+```
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="createTestApp fails to boot — missing secrets or stores">
+  The starter patches test drivers and fallback secrets on the app options. If
+  your `oke({ ... })` references a Vault secret or Store that the template does
+  not define, pass them explicitly:
+
+```typescript
+await createTestApp(app, {
+  secrets: [openAiKey],
+  vaultSecrets: { OPENAI_KEY: "sk-test" },
+});
+```
+
+</Accordion>
+
+<Accordion title="My live subscription never receives events">
+  - Live events are staged until `t.signals.drain()` — await `drain()` after
+    every emitting call.
+  - Register `subscribeLive` / `waitForLive` **before** you emit.
+  - A signal with a schema drops violating emits — assert `res.error`.
+
+</Accordion>
+
+<Accordion title="Cross-tenant reads return a stale cached row">
+  Tier-1 read caching keys by flow, input, and user id — tenant is a row-level
+  RLS scope, not a cache dimension. For reads under a `{ tenant }` override, use
+  a distinct call principal (or write first) so the cache key differs.
+
+</Accordion>
+
+<Accordion title="PGlite RLS policies aren't applied in the harness">
+  Test boots never run migrations — `oke db push` installs DDL and
+  `store.schema.policy.tenant` policies in real apps.
+
+Assert real RLS by installing the policy + `oke.*` helpers on the booted
+primary connection (as the repo's `sql-rls-isolation.test.ts` does).
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
+- [Store](/docs/elements/store) — SQL, KV, files, index, and RLS policies
+- [Signal](/docs/elements/signal) — delivery physics, retention, and live feeds
+- [Client](/docs/reference/client) — the typed client for real HTTP calls
+
+## Next
+
+<Cards>
+  <Card
+    title="Project structure"
+    description="Folders are the URL; unit plus export is the name."
+    href="/docs/get-started/project-structure"
+  />
+  <Card
+    title="Flow"
+    description="Triggers, contracts, effects, and composition."
+    href="/docs/elements/flow"
+  />
+  <Card
+    title="Signal"
+    description="Delivery physics, retention, and deterministic live feeds."
+    href="/docs/elements/signal"
+  />
+</Cards>

package/site/content/docs/get-started/why.mdx

@@ -1,120 +1,142 @@
 ---
 title: Why OKE
-description: The six seams every TypeScript backend maintains by hand — and what OKE derives from one Manifest instead.
+description: From forty tools to one species — the Manifest, the `fx` rule, and the eight closed elements.
 source: docs/spec/unified-theory.md
 icon: Compass
 ---
 
-Every TypeScript backend works on day one. The bill arrives later: the cache
-that serves last month's schema, the secret that only exists on your laptop,
-the dashboard that has never heard of your new Flow.
+## From forty tools to one species
 
-None of these are router problems. They are **seams** — copies of your code's
-knowledge, kept in places the compiler cannot check, updated by memory.
+A booking API, a nightly cleanup job, a receipt email, a row-change hook — in most stacks these are **four frameworks**. In OKE they are **one species** with one shape. Learn the shape once; only the trigger changes.
 
-<Callout title="The one rule">
-  **All world access goes through `fx`.** What a Flow reads, writes, emits, and reveals is recorded
-  — so the seams below are derived from one Manifest, not re-typed per project.
+> **The one rule**
+> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
+
+<Callout title="A note on the count">
+  'Forty' is a representative illustration of the number of backend concerns developers commonly
+  assemble across modern stacks, not a literal count of backend technologies.
 </Callout>
 
-## The six seams
+## The pain we solve
+
+Every TypeScript backend works on day one. The bill arrives later. None of these are router problems — they are **gaps** between what your code knows and what your tooling knows.
 
-### The cache that lies
+### Cache that lies
 
-You add a column to `orders` and update three writers. The hand-bumped cache
-key in `checkout` is not one of them. A customer finds it a week later.
+You add a column to `orders` and update three writers. The cache key in `checkout` is not one of them. A customer finds it a week later.
 
-**OKE derives:** reads and writes are recorded through `fx`, so invalidation
-follows the Flow — there is no separate key to remember.
+OKE derives: reads and writes are recorded through `fx`, so cache invalidation follows the Flow — there is no separate key to remember.
 
-### The secret that fails in prod
+### Secret that fails at 2am
 
-`STRIPE_KEY` lives in your laptop's `.env`, a README, and a teammate's shell
-history. The deploy boots fine — the first charge request dies at 2am.
+`STRIPE_KEY` lives in your laptop's `.env`, a README, and a teammate's shell history. The deploy boots fine — the first charge request dies at 2am.
 
-**OKE derives:** [Vault](/docs/elements/vault) contracts declare the need in
-code; boot resolves every contract and fails loud with every gap listed —
-never halfway.
+OKE derives: [Vault](/docs/elements/vault) contracts declare the need in code; boot resolves every contract and **fails loud** with every gap listed — never halfway.
 
 ### The glue you rewrite
 
-CORS rules, security headers, CSRF tokens, compression — copied from the last
-repo, tweaked, and already drifting from whatever that repo does today.
+CORS rules, security headers, CSRF tokens, compression — copied from the last repo, tweaked, and already drifting from whatever that repo does today.
 
-**OKE derives:** the official `okengine/plugins` set ships this glue once —
-shared lifecycle, optional live DB config, nothing to re-copy.
+OKE derives: the official `okengine/plugins` set ships this glue once — shared lifecycle, optional live DB config, nothing to re-copy.
 
 ### The dashboard that doesn't know you
 
-Your observability stack learned your routes from sampled traffic. The Flow
-you deployed an hour ago is invisible until someone wires it by hand.
+Your observability stack learned your routes from sampled traffic. The Flow you deployed an hour ago is invisible until someone wires it by hand.
 
-**OKE derives:** its operator interface reads the Manifest —
-flows, effects, traces, architecture — current on every save, in dev and prod
-(`:6533`).
+OKE derives: its operator interface reads the Manifest — flows, effects, traces, architecture — current on every save, in dev and prod (`:6533`).
 
-### The permission check in the wrong place
+### Permission check in the wrong place
 
-`if (!user.isAdmin)` sits in handler forty-one of sixty. Which Flows touch
-`payments`? grep answers slowly; review answers never.
+`if (!user.isAdmin)` sits in handler forty-one of sixty. Which Flows touch `payments`? grep answers slowly; review answers never.
 
-**OKE derives:** declared effects produce a least-privilege matrix — widening
-access appears in Manifest Diff, not in a diff nobody reads.
+OKE derives: declared effects produce a **least-privilege matrix** — widening access appears in Manifest Diff, not in a diff nobody reads.
 
 ### Local works, prod doesn't
 
-Local runs one vendor client, CI another, prod a third — three glue stories
-for the same database. "Works on my machine" is a driver mismatch.
+Local runs one vendor client, CI another, prod a third — three glue stories for the same database.
+
+OKE derives: drivers are named after protocols (`postgres`, `redis`, `s3`), the vendor lives in `images`, and `oke dev` runs the real stack locally.
+
+---
+
+Every gap above is the same shape: knowledge the code already has, duplicated somewhere the compiler cannot check. **The tax is drift.** One change costs fifteen seams to update by hand; in OKE it always costs one.
+
+## One Manifest feeds every surface
+
+At build time OKE extracts a **Manifest** — the compiled, versioned contract between your backend model and everything derived from it. The source of truth is your model expressed in code (`on(Trigger) → Flow → fx → Effects`); the Manifest freezes that model into a machine-readable, diffable contract. You do not write or hand-maintain the Manifest:
+
+| Surface                           | Port               | You maintain?                 |
+| --------------------------------- | ------------------ | ----------------------------- |
+| Typed client (`okengine/client`)  | your app code      | No — derived from `Manifest`  |
+| Console panels, traces, explorers | `:6533`            | No — reads the Manifest       |
+| MCP for agents                    | `:6535`            | No — reads the Manifest       |
+| Architecture diagram              | Console            | No — it _is_ the effect graph |
+| Capability matrix + cache keys    | compiler / runtime | No — inferred from `fx`       |
+
+Because every surface reads the same Manifest contract, they **cannot disagree** — there is only one source of truth.
+
+## The `fx` rule — one door to the world
+
+**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect. Effects are **inferred from what a Flow touches through `fx`**, and that inference powers the Manifest, the Console, caching, and durability.
+
+<Callout title="What `fx` records">
+  Every read, write, emit, send, ask, secret, and call is captured — so the Manifest knows exactly
+  which flows touch `orders` or send PII to a model, without you declaring it.
+</Callout>
 
-**OKE derives:** drivers are named after protocols (`postgres`, `redis`,
-`s3`), the vendor lives in `images`, and `oke dev` runs the real
-stack locally.
+| Inferred from `fx`      | What it gives you                    |
+| ----------------------- | ------------------------------------ |
+| Cache invalidation keys | Automatic — follows the Flow         |
+| Live queries            | Built-in subscription model          |
+| Least-privilege tokens  | Capability matrix from effects       |
+| Deterministic tests     | Time, clock, and randomness injected |
+| Manifest Diff           | Exact change surface on every save   |
 
-## The tax is drift
+## Eight elements — a closed set
 
-Every seam above is the same shape: a hand-maintained copy of knowledge the
-code already has. Watch one change propagate both ways.
+Forty infrastructure concerns collapse into eight elements — each kept only because it has **irreducible physics**. New infrastructure becomes a **driver** for an existing element, never a ninth.
 
-<DriftBoard />
+| Element     | Essence                       | Replaces the zoo                                          |
+| ----------- | ----------------------------- | --------------------------------------------------------- |
+| **Flow**    | Behavior                      | endpoint · handler · consumer · job · workflow · webhook  |
+| **Signal**  | Data in motion                | queue · pub/sub · stream · websocket · SSE · event bus    |
+| **Store**   | Data at rest                  | database · cache · KV · file storage · search index       |
+| **Clock**   | Time                          | cron · delay · timeout · durable sleep · TTL              |
+| **Gate**    | Permission to act             | auth · session · ABAC · rate limit · quota · feature flag |
+| **Vault**   | Protected knowledge           | secrets · config · environment                            |
+| **Channel** | Reaching humans               | email · SMS · WhatsApp · push                             |
+| **AI**      | Reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
 
-On the left, versions scatter and stay scattered. On the right, one Manifest
-feeds five surfaces — they cannot disagree, because none of them is a copy.
+Drivers are named after **protocols** (`postgres`, `redis`, `s3`) — never vendors. The vendor lives in `images`, and `oke dev` runs the real stack locally.
 
-## The answer's shape
+## The shape of a Flow
 
-Forty infrastructure concerns collapse into eight elements — each kept only
-because it has irreducible physics. One change costs up to fifteen seams in
-the zoo; here it always costs two.
+One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook:
 
-<CollapseBoard />
+```ts
+import { on, flow, http } from "okengine/http";
 
-New infrastructure becomes a **driver** for an existing element, never a
-ninth element — the set of eight is closed.
+export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
+```
 
-## Traditional vs OKE
+| Piece         | Role                                                           |
+| ------------- | -------------------------------------------------------------- |
+| **Trigger**   | How work starts — `http`, a signal, `every`, a row change      |
+| **Contracts** | `in`, `out`, typed `errors` — validated before and after `do`  |
+| **`do`**      | The body — every read, write, emit, and call goes through `fx` |
+| **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
 
-| Seam               | Maintained by hand                                        | Derived by OKE                                                          |
-| ------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
-| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                             |
-| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                              |
-| HTTP glue          | Middleware copied per repo                                | Official plugins — `headers`, `cors`, `csrf`, compression, IP allowlist |
-| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                               |
-| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                       |
-| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                            |
-| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev`                         |
-| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                   |
+Consequence: **one documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.**
 
 ## Ambition, stated plainly
 
-|                 | Statement                                                                                        |
-| --------------- | ------------------------------------------------------------------------------------------------ |
-| **Ambition**    | The default, most capable TypeScript backend — Bun-first, Web-Standards portable, contract-first |
-| **Grounded in** | Eight elements, effect inference through `fx`, Gate and Vault, the official plugin set           |
-| **Maturity**    | **pre-1.0** — published and usable; not independently battle-tested at scale yet                 |
+> **Ambition**: The default, most capable TypeScript backend — Bun-first, Web-Standards portable, contract-first  
+> **Grounded in**: Eight elements, effect inference through `fx`, Gate and Vault, the official plugin set  
+> **Maturity**: **pre-1.0** — published and usable; not independently battle-tested at scale yet
 
 ## Learn more
 
-- [Introduction](/docs/get-started/introduction) — the one law, eight elements, ten exports
+- [Introduction](/docs/get-started/introduction) — the one law, eight elements, one contract
 - [Flow](/docs/elements/flow) — how effects are recorded and inferred
 - [Vault](/docs/elements/vault) — fail-loud secret contracts
 - [Plugins](/docs/reference/plugins) — the official HTTP glue set
@@ -134,7 +156,7 @@ ninth element — the set of eight is closed.
   />
   <Card
     title="Introduction"
-    description="The one law, eight elements, ten exports."
+    description="The one law, eight elements, one contract."
     href="/docs/get-started/introduction"
   />
 </Cards>

package/site/content/docs/index.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Documentation"
-description: "One law. Eight elements. Ten exports."
+description: "A new programming model for backends. One law. Eight elements. One contract."
 icon: "BookOpen"
 source: "docs/spec/unified-theory.md"
 ---
 
-Welcome to the okengine handbook. Pick a section below — or start with Get Started if you are new.
+Welcome to the okengine handbook. The backend model stays small; operational surfaces are derived from it instead of maintained separately.
 
 <Callout title="The one law">
   Every backend behavior is a Flow: `on(Trigger) → Effects`. One species; triggers are typed values.
@@ -17,29 +17,62 @@ on(every("10m"), expireStale);
 on(orderPlaced, sendReceipt);
 ```
 
-## Browse by section
+## Understand OKE (Core Model)
+
+<Cards>
+  <Card
+    title="Why OKE"
+    description="From forty tools to one species — the problem, the law, and the Manifest contract."
+    href="/docs/get-started/why"
+  />
+  <Card
+    title="Elements"
+    description="The eight closed core elements: Flow, Signal, Store, Clock, Gate, Vault, Channel, AI."
+    href="/docs/elements"
+  />
+  <Card
+    title="Introduction"
+    description="The one law, eight elements, and one contract."
+    href="/docs/get-started/introduction"
+  />
+</Cards>
+
+## Build with OKE (Surfaces & Infrastructure)
 
 <Cards>
   <Card
     title="Get Started"
-    description="One law → install → first flows."
+    description="Installation, basic usage, project structure, and testing."
     href="/docs/get-started"
   />
-  <Card title="Elements" description="Flow → AI reference, one page each." href="/docs/elements" />
   <Card
     title="Plugins"
-    description="Official extensions — security, ops, performance."
+    description="22 official extensions — authentication, OAuth, security, ops, performance."
     href="/docs/plugins"
   />
   <Card
-    title="Deployment"
-    description="Compose, Swarm, Kubernetes, reverse proxy."
-    href="/docs/deployment"
+    title="Providers"
+    description="12 managed cloud infrastructure options behind protocol-named drivers."
+    href="/docs/providers"
+  />
+  <Card
+    title="Recipes"
+    description="20 self-hosted infrastructure recipes via Docker compose."
+    href="/docs/recipes"
   />
   <Card
     title="Reference"
-    description="Config, fx, env, errors, CLI, security."
+    description="Configuration, fx ledger, environment variables, errors, client, and security."
     href="/docs/reference"
   />
-  <Card title="AI Resources" description="MCP, skills, /llms.txt." href="/docs/ai" />
+  <Card
+    title="AI Resources & MCP"
+    description="Runtime MCP (:6535), docs MCP (:6536), skills, and /llms.txt."
+    href="/docs/ai"
+  />
+  <Card
+    title="Deployment"
+    description="Docker, Swarm, Kubernetes, and reverse proxy deployment."
+    href="/docs/deployment"
+  />
 </Cards>

package/site/content/docs/meta.json

@@ -3,13 +3,16 @@
   "icon": "BookOpen",
   "pages": [
     "index",
-    "get-started",
+    "---Understand OKE---",
     "elements",
-    "plugins",
+    "---Build with OKE---",
+    "get-started",
+    "ai",
     "deployment",
-    "recipes",
-    "providers",
     "reference",
-    "ai"
+    "plugins",
+    "---Drivers---",
+    "providers",
+    "recipes"
   ]
 }