okengine 0.17.2 → 0.18.4

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

@@ -173,8 +173,8 @@ A value already in the vault / managed backend wins over a leftover env pin.
 If every layer misses a contract, boot **fails** before any request is served:
 
 ```text
-VaultBootError: 1 secret(s) missing:
-  STRIPE_KEY — Payments gateway key
+vault boot failed — 1 missing secret(s):
+  - STRIPE_KEY: Payments gateway key
 ```
 
 <Callout title="Good to know">
@@ -242,9 +242,9 @@ Backup stays on the CLI (`oke vault backup` / `restore`). The Console never
 accepts a master key in the HTTP body — unseal via `OKE_VAULT_MASTER_KEY`.
 
 <Callout title="Builtin concurrency (rotate / audit / backup)">
-  `rotate-master` uses SKIP LOCKED + lease TTL (one holder; crashed holders reclaim). Audit appends
-  under a transactional row lock. Backups use temp → fsync → rename with end marker + checksum —
-  restore rejects incomplete files before decrypt.
+  `rotate-master` holds a lease (`FOR UPDATE` + lease TTL) so exactly one batch runs at a time; a
+  busy audit append briefly waits rather than being misread as "lease held". Audit appends serialize
+  under a transactional write lock; backups use temp → fsync → rename with end marker + checksum.
 </Callout>
 
 <Callout title="Builtin master keys and expired rows">

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

@@ -146,7 +146,7 @@ Uncommented supported controls in the generated compose env are preserved when
 `oke dev` regenerates the file.
 
 Migrating from `local` / `docker` maps or `oke mode`?
-See [Migrating environments](/docs/reference/migrating-environments).
+Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
 
 ## Troubleshooting
 
@@ -198,7 +198,6 @@ See [Migrating environments](/docs/reference/migrating-environments).
 - [CLI Reference](/docs/reference/cli) — `oke`, `create-oke`, `oke test`, and db commands
 - [Environment variables](/docs/reference/environment-variables) — protocol-shaped env
 - [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and `db.autoPush`
-- [Migrating environments](/docs/reference/migrating-environments) — four-key maps → three
 
 ## Next
 
@@ -210,7 +209,7 @@ See [Migrating environments](/docs/reference/migrating-environments).
   />
   <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,82 +1,54 @@
 ---
 title: Introduction
-description: Learn the one idea behind okengine — then the eight elements and ten exports you will use everywhere.
+description: Learn the one idea behind okengine — then the eight elements and core programming vocabulary you will use everywhere.
 source: docs/spec/unified-theory.md
 icon: BookOpen
 ---
 
-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 Idea
 
-<Callout title="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>
+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.
 
-## Quick start
+> **The one rule**
+> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
 
-<Steps>
+## Quick Start
 
-<Step>
-### Write one Flow
+### Write One Flow
 
 Four contracts plus a `do`. This is the standard starter's health check:
 
-```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 }),
-  }),
-);
+```typescript
+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). Explicit `http.get("/health")` and `flow("main.health")` still win.
 
-</Step>
+### Change Only the Trigger
 
-<Step>
-### Change only the trigger
+Triggers define what starts the flow. Changing the trigger replaces the entire behavior while keeping the same structure:
 
 | Trigger                            | Starts when        | Replaces           |
 | ---------------------------------- | ------------------ | ------------------ |
-| `http.post("/bookings")`           | a request arrives  | endpoint · handler |
-| `every("10m")`                     | time passes        | cron job           |
-| `orderPlaced` (a signal)           | another flow emits | queue consumer     |
-| `db.table(users).changed("email")` | a row changes      | CDC pipeline       |
+| `http.post("/bookings")`           | A request arrives  | Endpoint · handler |
+| `every("10m")`                     | Time passes        | Cron job           |
+| `orderPlaced` (a signal)           | Another flow emits | Queue consumer     |
+| `db.table(users).changed("email")` | A row changes      | CDC pipeline       |
+
+```typescript
+import { on, flow, http } from "okengine";
 
-```typescript title="triggers"
 on(http.post("/bookings"), createBooking);
 on(every("10m"), expireStale);
 on(orderPlaced, sendReceipt);
 on(db.table(users).changed("email"), reverify);
 ```
 
-</Step>
-
-<Step>
-### See what was derived
-
-Run `oke dev`. Four surfaces come up together — nothing configured by hand in
-a separate dashboard.
-
-<Surfaces />
-
-</Step>
-
-</Steps>
-
 ## Anatomy
 
-One pipeline. Only the trigger changes between an endpoint, a job, a consumer,
-and a row hook.
-
-<FlowShape />
+One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook.
 
 | Piece         | Role                                                           |
 | ------------- | -------------------------------------------------------------- |
@@ -85,33 +57,25 @@ and a row hook.
 | **`do`**      | The body — every read, write, emit, and call goes through `fx` |
 | **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
 
-| Consequence                        | Follows from   |
-| ---------------------------------- | -------------- |
-| One documentation path             | One species    |
-| One trace shape                    | One Flow model |
-| One thing for an AI agent to learn | One law        |
-
-## The `fx` rule
+Consequence: One documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.
 
-**All world access goes through `fx`.** A Flow that imports `node:fs`, calls
-`fetch` directly, or uses `Date.now()` is a defect.
+## The `fx` Rule
 
-| Inferred from `fx` touches | Without hand annotations |
-| -------------------------- | ------------------------ |
-| Cache invalidation keys    | Yes                      |
-| Live queries               | Yes                      |
-| Least-privilege tokens     | Yes                      |
-| Deterministic tests        | Yes                      |
-| Manifest Diff              | Yes                      |
+**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect.
 
-## What the Manifest derives
+| Inferred From           | With `fx` |
+| ----------------------- | --------- |
+| Cache invalidation keys | Yes       |
+| Live queries            | Yes       |
+| Least-privilege tokens  | Yes       |
+| Deterministic tests     | Yes       |
+| Manifest Diff           | Yes       |
 
-At build time OKE extracts a **Manifest** — a machine-readable description of
-your system. You do not maintain a second source of truth.
+## What the Manifest Derives
 
-<ManifestPipeline />
+At build time OKE extracts a **Manifest** — a machine-readable description of your system. You do not maintain a second source of truth.
 
-| Surface                           | Port / place       | You maintain?                 |
+| Surface                           | Port / Place       | You Maintain?                 |
 | --------------------------------- | ------------------ | ----------------------------- |
 | Typed client (`okengine/client`)  | your app code      | No separate codegen           |
 | Console panels, traces, explorers | `:6533`            | No                            |
@@ -119,47 +83,38 @@ your system. You do not maintain a second source of truth.
 | Architecture diagram              | Console            | No — it _is_ the effect graph |
 | Capability matrix + cache keys    | compiler / runtime | No — from `fx`                |
 
-## Eight elements
+## 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**. New infrastructure becomes a new **driver** — never a ninth element.
 
-<Features />
-
-| Element     | Essence                       | Replaces the zoo of                                       |
+| 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         |
+| **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         |
 
-## Ten exports
+## Core Programming Vocabulary
 
-The entire public vocabulary fits in one import. Everything else in the docs is
-derived from these ten names:
+The core programming vocabulary fits in one import. Everything else in the docs is derived from these names:
 
-```ts title="okengine"
+```ts
 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
-router:
+For HTTP-only apps, prefer the slim entry so the cold graph stays on the edge:
 
-```ts title="okengine/http"
+```ts
 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`.
-
-<Vocabulary />
+Heavy surfaces (runs, journal factories, compiler extract, the legacy mega-barrel) live on `okengine/runs`, `okengine/journal`, `okengine/compiler`, and `okengine/full`.
 
-## Learn more
+## Learn More
 
 | Topic   | Page                                                                            |
 | ------- | ------------------------------------------------------------------------------- |
@@ -169,27 +124,9 @@ and `okengine/full`.
 | `fx`    | [fx](/docs/reference/fx)                                                        |
 | Agents  | [MCP](/docs/ai/mcp) · [Skills](/docs/ai/skills) · [llms.txt](/docs/ai/llms-txt) |
 
-## Next
-
-<Cards>
-  <Card
-    title="Why OKE"
-    description="Traditional backend pain — and what Manifest derivation closes."
-    href="/docs/get-started/why"
-  />
-  <Card
-    title="Installation"
-    description="Scaffold with create-oke and open the Console."
-    href="/docs/get-started/installation"
-  />
-  <Card
-    title="Basic Usage"
-    description="Health Flow, typed client, and bun:test."
-    href="/docs/get-started/basic-usage"
-  />
-  <Card
-    title="Project structure"
-    description="Folders are the URL; unit plus export is the name."
-    href="/docs/get-started/project-structure"
-  />
-</Cards>
+## 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)

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

@@ -1,5 +1,13 @@
 {
   "title": "Get Started",
   "icon": "Rocket",
-  "pages": ["index", "introduction", "why", "installation", "basic-usage", "project-structure"]
+  "pages": [
+    "index",
+    "why",
+    "introduction",
+    "installation",
+    "basic-usage",
+    "testing",
+    "project-structure"
+  ]
 }

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
 ```