okengine 0.18.3 → 0.18.5

package/AGENTS.md

@@ -1,5 +1,7 @@
 # OKE — Agent Contract
 
+One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.
+
 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
@@ -27,13 +29,13 @@ There are no separate species called endpoints, handlers, consumers, jobs, subsc
 
 An element earns its place only if it has irreducible physics. New infrastructure becomes a new **driver** for an existing element — never a ninth element.
 
-## The ten exports
+## Core programming vocabulary
 
 ```typescript
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-That is the entire public vocabulary. Everything else is derived.
+That is the core programming vocabulary. Everything else is derived.
 
 ## Governing rule
 
@@ -80,7 +82,7 @@ Published packages:
 - `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 Notes starters from `packages/create-oke/templates/{standard,advanced}`.
 
-Engine: Bun `>=1.3.14`.
+Engine: Bun `>=1.4.0`.
 
 ## Documentation authority
 

package/README.md

@@ -2,11 +2,11 @@
   <picture>
     <source
       media="(prefers-color-scheme: dark)"
-      srcset="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-W.svg&theme=zinc&size=banner&mode=dark&font=geist&align=left"
+      srcset="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+One+contract.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-W.svg&theme=zinc&size=banner&mode=dark&font=geist&align=left"
     />
     <img
-      alt="okengine — One law. Eight elements. Ten exports."
-      src="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-B.svg&theme=zinc&size=banner&mode=light&font=geist&align=left"
+      alt="okengine — One law. Eight elements. One contract."
+      src="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+One+contract.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-B.svg&theme=zinc&size=banner&mode=light&font=geist&align=left"
       width="750"
     />
   </picture>
@@ -22,7 +22,7 @@
 </p>
 
 <p align="center">
-  <em>Stop gluing APIs, jobs, and queues into one backend. One law collapses them — client, Console, and infra come free. Yours to host.</em>
+  <em>Modern backends became a pile of disconnected systems. One law collapses them — client, Console, and infra derived from one contract. Yours to host.</em>
 </p>
 
 <p align="center">
@@ -104,7 +104,7 @@ Every backend behavior is a Flow: `on(Trigger) → Effects`. Endpoints, jobs, co
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-That is the entire public vocabulary. World access goes through `fx` — effects are inferred, so the Manifest can derive the typed client, Console, and MCP without a second source of truth.
+That is the core programming vocabulary. World access goes through `fx` — effects are inferred, so the Manifest can derive the typed client, Console, and MCP without a second source of truth.
 
 | Element     | Essence                       |
 | ----------- | ----------------------------- |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "okengine",
-  "version": "0.18.3",
-  "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
+  "version": "0.18.5",
+  "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -5,20 +5,39 @@ icon: "Bot"
 source: "docs/spec/unified-theory.md"
 ---
 
-Resources for AI agents that read or operate an OKE app — not the `ai` element itself.
+Resources for AI agents that inspect, understand, or operate an OKEngine application.
 
-## Pages
+<Callout title="Two directions, one model">
+  **MCP is a surface of the model, not the model itself.** Gate governs agents calling in; the AI
+  element governs applications calling out to models.
+</Callout>
+
+```text
+External Agents → MCP (:6535) → Gate Check → Flow (inbound)
+Flow → fx.ask / fx.stream → AI Runtime → Models & External Tools (outbound)
+```
+
+## AI & Agent Surfaces
 
 <Cards>
-  <Card title="MCP" description="Runtime MCP on :6535; docs MCP on :6536." href="/docs/ai/mcp" />
   <Card
-    title="Skills"
-    description="AGENTS.md contract and installable skills."
+    title="MCP"
+    description="Runtime MCP on :6535 for running apps; Docs MCP on :6536 for handbook search."
+    href="/docs/ai/mcp"
+  />
+  <Card
+    title="Agent Skills"
+    description="AGENTS.md contract and autonomous maintenance skills."
     href="/docs/ai/skills"
   />
   <Card
     title="llms.txt"
-    description="Index, JSON catalogue, full dump, per-page markdown."
+    description="Standardized machine-readable feeds: /llms.txt, /llms.json, /llms-full.txt, and markdown twins."
     href="/docs/ai/llms-txt"
   />
+  <Card
+    title="AI Element"
+    description="Calling out: models, prompts, agents, and RAG inside your application."
+    href="/docs/elements/ai"
+  />
 </Cards>

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

@@ -5,7 +5,16 @@ icon: "Plug"
 source: "docs/spec/unified-theory.md"
 ---
 
-Two directions, same protocol. **Serve:** OKE exposes your running app on port **6535** so an agent can read the Manifest and take confirmed actions. **Consume:** your Flows call _external_ MCP servers as tools — declared on `ai.mcpServer`, dispatched through `fx.call`.
+## Two directions, same execution model
+
+> **MCP is a surface of the model, not the model itself.**
+
+Two genuinely distinct things share the protocol in OKE:
+
+1. **Gate Element (MCP Provider role):** Your app exposes Flows as MCP tools on port **6535** (or via `mcp.tool()` + OAuth 2.1 Authorization Server) so external AI agents (Claude, ChatGPT) can read the Manifest and call declared Flows.
+2. **AI Element (MCP Client role):** Your app consumes _external_ MCP tool servers via `ai.mcpServer(...)`, routing tool calls through `fx.call` inside prompts and agents.
+
+OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes.
 
 The server on **6535** 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.
 

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

@@ -9,18 +9,18 @@ Tools alone don't make a good operator — an agent also needs to know the _voca
 
 ## The 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     |
-| **Ship skill**     | `.agents/skills/oke-ship/`   | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
-| **Deps skill**     | `.agents/skills/oke-deps/`   | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)       |
-| **Images skill**   | `.agents/skills/oke-images/` | Updating Compose image pins                       | Registry probe, pin style, catalog + recipes + Keel + docs lockstep   |
+| Layer              | Path                         | Loaded when                                       | Teaches                                                                |
+| ------------------ | ---------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Agent contract** | `AGENTS.md` (repo root)      | Every agent session, automatically                | The one law, eight elements, one contract, 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      |
+| **Ship skill**     | `.agents/skills/oke-ship/`   | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`             |
+| **Deps skill**     | `.agents/skills/oke-deps/`   | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)        |
+| **Images skill**   | `.agents/skills/oke-images/` | Updating Compose image pins                       | Registry probe, pin style, catalog + recipes + Keel + docs lockstep    |
 
 ## 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.
+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 bound to one contract, 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
 

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

@@ -129,7 +129,7 @@ const result = await fx.ask(triage, input, {
 });
 ```
 
-External MCP tools take the same path. Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
+External MCP tools take the same path. In OKE, **MCP is a surface of the model, not the model itself** — `ai.mcpServer` models the client role (consuming external tools), while `mcp.tool()` + Gate models the provider role (exposing your flows to agents). Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
 
 ```typescript
 export const github = ai.mcpServer("github", {

package/site/content/docs/elements/gate.mdx

@@ -9,6 +9,8 @@ Gate answers **"may this happen?"** before it happens: is this a verified member
 burned its minute quota? Attach gates to the HTTP trigger — the pipeline checks them before a
 store write, emit, or channel send runs.
 
+> **Same Semantics Across Planes:** OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes: users via sessions, operators via Console policies, and agents via `mcp.tool()` + OAuth 2.1 AS.
+
 <Callout title="The one rule">
   Every HTTP trigger declares posture: attach a real gate, or attach `.public()`. Omitting both
   fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
@@ -63,8 +65,7 @@ import { member, canBook, fair } from "../../gates";
 export const health = on(
   http.get("/health").public(),
   flow("health.check", {
-    out: HealthOut,
-    do: () => ({ ok: true as const }),
+    do: () => ({ ok: true }),
   }),
 );
 

package/site/content/docs/elements/index.mdx

@@ -1,45 +1,76 @@
 ---
 title: "Elements"
-description: "The eight irreducible parts of an OKE backend — Flow through AI, one page each."
+description: "The eight closed semantic primitives of the OKEngine backend model."
 icon: "Boxes"
 source: "docs/spec/unified-theory.md"
 ---
 
-Every backend concern collapses to one of these eight. Pick the element you need.
+Forty backend concerns collapse into eight semantic primitives. An element earns its place only with **irreducible physics**.
 
-## Pages
+<Callout title="Closed primitive set">
+  There is no ninth element. New infrastructure creates a protocol driver or plugin, preserving a
+  small mental model.
+</Callout>
+
+```text
+Elements define the model.
+Plugins extend the model's capabilities.
+Drivers connect the model to infrastructure.
+Providers and Recipes choose where that infrastructure runs.
+```
+
+## The Eight Primitives
 
 <Cards>
-  <Card title="Flow" description="Behavior — on(Trigger) → Effects." href="/docs/elements/flow" />
+  <Card
+    title="Flow"
+    description="Behavior — on(Trigger) → Effects via fx."
+    href="/docs/elements/flow"
+  />
   <Card
     title="Signal"
-    description="Data in motion — queues, pub/sub, streams."
+    description="Data in motion — delivery physics as a property (once, broadcast, live)."
     href="/docs/elements/signal"
   />
   <Card
     title="Store"
-    description="Data at rest — sql, kv, files, index."
+    description="Data at rest — SQL, KV, files with image transforms, and search."
     href="/docs/elements/store"
   />
   <Card
     title="Clock"
-    description="Time — schedules, intervals, durable sleeps."
+    description="Time — schedules, intervals, durable sleeps, and time travel."
     href="/docs/elements/clock"
   />
   <Card
     title="Gate"
-    description="Permission to act — auth and rate limits."
+    description="Permission to act — auth, tenancy, ABAC, and rate limits at the trigger."
     href="/docs/elements/gate"
   />
   <Card
     title="Vault"
-    description="Protected knowledge — secrets and keys."
+    description="Protected knowledge — fail-loud secret contracts and redacted values."
     href="/docs/elements/vault"
   />
   <Card
     title="Channel"
-    description="Reaching humans — email, SMS, push."
+    description="Reaching humans — email, SMS, WhatsApp, and push with built-in consent."
     href="/docs/elements/channel"
   />
-  <Card title="AI" description="Reaching machine intelligence." href="/docs/elements/ai" />
+  <Card
+    title="AI"
+    description="Reaching machine intelligence — models, prompts, agents, and RAG."
+    href="/docs/elements/ai"
+  />
 </Cards>
+
+## See How They Compose
+
+The closed elements compose into full backend capabilities:
+
+| Composition Target | Formula                                         | How It Works                                              |
+| ------------------ | ----------------------------------------------- | --------------------------------------------------------- |
+| **Realtime**       | Store + Gate + Signal + Flow → Live Query       | CDC changes re-checked against Gate RLS, streamed as SSE  |
+| **Security**       | Gate + Store/RLS + Tenant + fx → Secure runtime | Tenant-isolated queries with least-privilege capability   |
+| **Agents**         | MCP + Gate + OAuth + Flow → Agent-ready backend | Declared Flows exposed on :6535 behind auth confirmation  |
+| **Operations**     | Manifest + Effects + Runs → Inspectable backend | Inferred effects feed Console (:6533) and wide-event logs |

package/site/content/docs/elements/store.mdx

@@ -129,6 +129,8 @@ A request that filters on a forbidden column — `?secret=eq.x` — fails with *
 
 ### Live queries — `live: true` and `.live(table)`
 
+> **Realtime did not introduce a new subsystem. It composed existing Store, Signal, Gate/RLS, Flow, and Manifest semantics.**
+
 Pass `live: true` to also mount `GET <path>/live` — an SSE feed of per-subscriber classified events (`upsert` / `revoked` / `delete`), gated the same way as the CRUD verbs:
 
 ```typescript

package/site/content/docs/get-started/basic-usage.mdx

@@ -46,16 +46,9 @@ lists HTTP routes — static GET paths are links. `curl` still gets `{ data, err
 The standard starter already exports a named health Flow:
 
 ```typescript title="flows/main/health.ts"
-import { on, flow, http } from "okengine";
-import { z } from "zod";
-
-export const health = on(
-  http.get().public(),
-  flow({
-    out: z.object({ ok: z.literal(true) }),
-    do: () => ({ ok: true as const }),
-  }),
-);
+import { on, flow, http } from "okengine/http";
+
+export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
 ```
 
 `main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure).

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

@@ -12,7 +12,7 @@ Learn the shape once, install on Bun, then write your first Flow from the standa
 <Cards>
   <Card
     title="Introduction"
-    description="One law, eight elements, ten exports."
+    description="One law, eight elements, one contract."
     href="/docs/get-started/introduction"
   />
   <Card

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

@@ -209,7 +209,7 @@ Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
   />
   <Card
     title="Introduction"
-    description="The one law, eight elements, ten exports."
+    description="The one law, eight elements, one contract."
     href="/docs/get-started/introduction"
   />
   <Card

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

@@ -1,41 +1,25 @@
 ---
 title: Introduction
-description: Learn the one idea behind okengine — then the eight elements and ten exports you will use everywhere.
+description: The Law, the eight elements, the fx rule, and the compiled Manifest contract.
 source: docs/spec/unified-theory.md
 icon: BookOpen
 ---
 
-## The One Idea
+## The One Law
 
-A booking API, a nightly cleanup job, a receipt email, a row-change hook — in most stacks those are four frameworks. In OKE they are **one species** with one shape. Learn the shape once; only the trigger changes.
-
-> **The one rule**
-> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
-
-## Quick Start
-
-### Write One Flow
-
-Four contracts plus a `do`. This is the standard starter's health check:
+Every backend behavior is a Flow: `on(Trigger) → Effects`.
 
 ```typescript
-import { on, flow, http } from "okengine";
-import { z } from "zod";
+import { on, flow, http } from "okengine/http";
 
-export const health = on(
-  http.get().public(),
-  flow({
-    out: z.object({ ok: z.literal(true) }),
-    do: () => ({ ok: true as const }),
-  }),
-);
+export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
 ```
 
-`main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure). Explicit `http.get("/health")` and `flow("main.health")` still win.
+An endpoint, a nightly cleanup cron, a queue consumer, a row-change CDC hook — these are not four frameworks. They are **one species** with one shape. Only the trigger changes.
 
-### Change Only the Trigger
+## Changing Only the Trigger
 
-Triggers define what starts the flow. Changing the trigger replaces the entire behavior while keeping the same structure:
+Triggers determine what starts the flow while preserving identical anatomy and effect tracking:
 
 | Trigger                            | Starts when        | Replaces           |
 | ---------------------------------- | ------------------ | ------------------ |
@@ -53,9 +37,9 @@ on(orderPlaced, sendReceipt);
 on(db.table(users).changed("email"), reverify);
 ```
 
-## Anatomy
+## Anatomy of a Flow
 
-One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook.
+Every Flow consists of four clear sections:
 
 | Piece         | Role                                                           |
 | ------------- | -------------------------------------------------------------- |
@@ -64,35 +48,53 @@ One pipeline. Only the trigger changes between an endpoint, a job, a consumer, a
 | **`do`**      | The body — every read, write, emit, and call goes through `fx` |
 | **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
 
-Consequence: One documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.
+```typescript
+export const createOrder = on(
+  http.post("/orders"),
+  flow("orders.create", {
+    in: OrderInput,
+    out: OrderResult,
+    do: async (input, fx) => {
+      const order = await fx.store(db).insert(orders).values(input);
+      await fx.emit(orderPlaced, { orderId: order.id });
+      return order;
+    },
+  }),
+);
+```
 
 ## The `fx` Rule
 
-**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect.
+**All world access goes through `fx`.**
+
+<Callout title="Single door to the world">
+  Nothing in user flows imports `node:fs`, calls global `fetch`, or calls `Date.now()`. Every effect
+  is recorded on the effect ledger.
+</Callout>
 
-| Inferred From           | With `fx` |
-| ----------------------- | --------- |
-| Cache invalidation keys | Yes       |
-| Live queries            | Yes       |
-| Least-privilege tokens  | Yes       |
-| Deterministic tests     | Yes       |
-| Manifest Diff           | Yes       |
+| Inferred from `fx`      | What it powers                       |
+| ----------------------- | ------------------------------------ |
+| Cache invalidation keys | Invalidation follows the flow writes |
+| Live queries            | Realtime CDC subscriptions           |
+| Least-privilege tokens  | Compiler-derived capability matrix   |
+| Deterministic tests     | Injected time, clock, and stores     |
+| Manifest Diff           | Blast-radius checks on every save    |
 
-## What the Manifest Derives
+## The Compiled Manifest
 
-At build time OKE extracts a **Manifest** — a machine-readable description of your system. You do not maintain a second source of truth.
+The source of truth is the backend model expressed in code. The **Manifest** is the compiled, versioned contract representing that model.
 
-| Surface                           | Port / Place       | You Maintain?                 |
+| Surface                           | Port               | You Maintain?                 |
 | --------------------------------- | ------------------ | ----------------------------- |
-| Typed client (`okengine/client`)  | your app code      | No separate codegen           |
-| Console panels, traces, explorers | `:6533`            | No                            |
-| MCP for agents                    | `:6535`            | No                            |
+| 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 — from `fx`                |
+| Capability matrix + cache keys    | compiler / runtime | No — inferred from `fx`       |
 
 ## The Eight Elements
 
-An element earns its place only if it has **irreducible physics**. New infrastructure becomes a new **driver** — never a ninth element.
+An element earns its place only if it has **irreducible physics**.
 
 | Element     | Essence                       | Replaces the Zoo                                          |
 | ----------- | ----------------------------- | --------------------------------------------------------- |
@@ -105,35 +107,38 @@ An element earns its place only if it has **irreducible physics**. New infrastru
 | **Channel** | Reaching humans               | email · SMS · WhatsApp · push                             |
 | **AI**      | Reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
 
-## Ten Exports
+New infrastructure becomes a **driver** for an existing element, never a ninth.
 
-The entire public vocabulary fits in one import. Everything else in the docs is derived from these ten names:
+## Core Programming Vocabulary
 
-```ts
+The core programming vocabulary is ten exported names:
+
+```typescript
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-For HTTP-only apps, prefer the slim entry so the cold graph stays on the edge:
+For HTTP runtime essentials, use the slim entry `okengine/http`:
 
-```ts
+```typescript
 import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
 ```
 
-Heavy surfaces (runs, journal factories, compiler extract, the legacy mega-barrel) live on `okengine/runs`, `okengine/journal`, `okengine/compiler`, and `okengine/full`.
-
-## Learn More
-
-| Topic   | Page                                                                            |
-| ------- | ------------------------------------------------------------------------------- |
-| Why OKE | [Why OKE](/docs/get-started/why)                                                |
-| Folders | [Project structure](/docs/get-started/project-structure)                        |
-| Flow    | [Flow](/docs/elements/flow)                                                     |
-| `fx`    | [fx](/docs/reference/fx)                                                        |
-| Agents  | [MCP](/docs/ai/mcp) · [Skills](/docs/ai/skills) · [llms.txt](/docs/ai/llms-txt) |
-
 ## Next Steps
 
-- [Why OKE](/docs/get-started/why)
-- [Installation](/docs/get-started/installation)
-- [Basic Usage](/docs/get-started/basic-usage)
-- [Project Structure](/docs/get-started/project-structure)
+<Cards>
+  <Card
+    title="Why OKE"
+    description="Explore the problem of seams and the smaller model."
+    href="/docs/get-started/why"
+  />
+  <Card
+    title="Installation"
+    description="Scaffold a new OKEngine project with create-oke."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Basic Usage"
+    description="Write your first flow and verify it with bun test."
+    href="/docs/get-started/basic-usage"
+  />
+</Cards>

package/site/content/docs/get-started/meta.json

@@ -3,8 +3,8 @@
   "icon": "Rocket",
   "pages": [
     "index",
-    "introduction",
     "why",
+    "introduction",
     "installation",
     "basic-usage",
     "testing",

package/site/content/docs/get-started/project-structure.mdx

@@ -561,10 +561,7 @@ export const archive = on(
 <Tab value="(public)">
 
 ```typescript title="flows/main/(public)/health.ts"
-export const health = on(
-  http.get().public(),
-  flow({ out: z.object({ ok: z.literal(true) }), do: () => ({ ok: true as const }) }),
-);
+export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
 // still GET /health named main.health
 ```
 
@@ -635,13 +632,9 @@ Do not put `index.ts` next to `health.ts` — that mix is a generate error. Use
 <Tab value="health.ts">
 
 ```typescript title="flows/main/health.ts"
-export const health = on(
-  http.get().public(),
-  flow({
-    out: z.object({ ok: z.literal(true) }),
-    do: () => ({ ok: true as const }),
-  }),
-);
+import { on, flow, http } from "okengine/http";
+
+export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
 // GET /health   name main.health
 ```