okengine 0.3.6 → 0.5.0

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

@@ -1,123 +1,176 @@
 ---
 title: Introduction
-description: Learn the one idea behind okengine — then the eight elements and ten exports.
+description: Learn the one idea behind okengine — then the eight elements and ten exports you will use everywhere.
 source: docs/spec/unified-theory.md
 icon: BookOpen
 ---
 
-OKE is a Bun-first TypeScript backend. You do not learn a pile of unrelated tools (router + queue + cron + websockets). You learn **one sentence**, and everything else follows from it.
+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 law
+<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>
 
-> **Every backend behavior is a Flow:** `on(Trigger) → Effects`
+## Quick start
 
-There are no separate species called endpoints, handlers, consumers, jobs, subscribers, or workflows. There is one species — the **Flow** — and triggers are typed values:
+<Steps>
 
-```ts title="flows"
-on(http.post("/bookings"), createBooking); // "an API endpoint"
-on(every("10m"), expireStale); // "a cron job"
-on(orderPlaced, sendReceipt); // "a queue consumer"
-on(db.table(users).changed("email"), reverify); // "a CDC trigger"
-```
+<Step>
+### Write one Flow
 
-Same shape every time: a trigger, a flow body, and effects inferred from what that body touches through `fx`.
+Four contracts plus a `do`. This is the standard starter's health check:
 
-<Callout title="Why this lowers the learning curve">
-One law → one mental model → one documentation path → one trace shape → one thing for an AI agent to learn.
+```typescript title="health"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
 
-**Learning OKE is learning one sentence.**
+export const health = on(
+  http.get("/health"),
+  flow({
+    out: z.object({ ok: z.literal(true) }),
+    do: () => ({ ok: true as const }),
+  }),
+);
+```
 
-</Callout>
+</Step>
 
-## What you get
+<Step>
+### Change only the trigger
 
-You write TypeScript. At build time OKE extracts a **Manifest** — a machine-readable description of your system. From that Manifest the rest is **derived**, not configured by hand:
+| 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       |
 
-- Typed client (no separate codegen step to maintain)
-- OpenAPI / docs surfaces
-- Architecture diagram that _is_ the effect graph
-- Console panels, traces, and explorers
-- MCP surface for agents (`:6535`)
-- Least-privilege capability matrix and cache invalidation keys
+```typescript title="triggers"
+on(http.post("/bookings"), createBooking);
+on(every("10m"), expireStale);
+on(orderPlaced, sendReceipt);
+on(db.table(users).changed("email"), reverify);
+```
 
-## Ten exports
+</Step>
 
-The entire public vocabulary fits in one import:
+<Step>
+### See what was derived
 
-```ts title="okengine"
-import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
-```
+Run `oke dev`. Three surfaces come up together — nothing configured by hand in
+a separate dashboard.
 
-| Export    | Role                                            |
-| --------- | ----------------------------------------------- |
-| `on`      | Bind a trigger to a flow                        |
-| `flow`    | Define behavior + contracts                     |
-| `signal`  | Data in motion (queue / pub-sub / live)         |
-| `store`   | Data at rest (`sql` · `kv` · `files` · `index`) |
-| `clock`   | Time (cron, delay, sleep, TTL)                  |
-| `gate`    | Permission to act (auth, ABAC, limits)          |
-| `vault`   | Secrets and config                              |
-| `channel` | Reach humans (email, SMS, …)                    |
-| `ai`      | Reach models / agents                           |
-| `plugin`  | Extend the runtime without a ninth element      |
+<Surfaces />
 
-Everything else in the docs is derived from these ten names.
+</Step>
 
-## The eight elements
+</Steps>
 
-Everything a backend has ever needed reduces to eight typed elements. 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.
+## Anatomy
 
-<Features />
+One pipeline. Only the trigger changes between an endpoint, a job, a consumer,
+and a row hook.
 
-<details>
-<summary>What each element replaces</summary>
+<FlowShape />
 
-| Element     | Replaces the zoo of                                       |
-| ----------- | --------------------------------------------------------- |
-| **Flow**    | endpoint · handler · consumer · job · workflow · webhook  |
-| **Signal**  | queue · pub/sub · stream · websocket · SSE · event bus    |
-| **Store**   | database · cache · KV · file storage · search index       |
-| **Clock**   | cron · delay · timeout · durable sleep · TTL              |
-| **Gate**    | auth · session · ABAC · rate limit · quota · feature flag |
-| **Vault**   | secrets · config · environment                            |
-| **Channel** | email · SMS · WhatsApp · push                             |
-| **AI**      | model calls · prompts · embeddings · agents · RAG         |
+| 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            |
 
-</details>
+| 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
 
-**All world access goes through `fx`.** A Flow that imports `node:fs` (or any other side-channel I/O) is a defect.
+**All world access goes through `fx`.** A Flow that imports `node:fs`, calls
+`fetch` directly, or uses `Date.now()` is a defect.
+
+| Inferred from `fx` touches | Without hand annotations |
+| -------------------------- | ------------------------ |
+| Cache invalidation keys    | Yes                      |
+| Live queries               | Yes                      |
+| Least-privilege tokens     | Yes                      |
+| Deterministic tests        | Yes                      |
+| Manifest Diff              | Yes                      |
+
+## What the Manifest derives
 
-That single rule is why cache invalidation, live queries, least privilege, deterministic tests, and Manifest Diff can be **inferred** instead of annotated by hand. You will see `fx` in every example from here on.
+At build time OKE extracts a **Manifest** — a machine-readable description of
+your system. You do not maintain a second source of truth.
 
-## Where to go next
+<ManifestPipeline />
 
-Read in this order if you are new:
+| Surface                           | Port / place       | You maintain?                 |
+| --------------------------------- | ------------------ | ----------------------------- |
+| Typed client (`okengine/client`)  | your app code      | No separate codegen           |
+| Console panels, traces, explorers | `:6533`            | No                            |
+| MCP for agents                    | `:6535`            | No                            |
+| Architecture diagram              | Console            | No — it _is_ the effect graph |
+| Capability matrix + cache keys    | compiler / runtime | No — from `fx`                |
 
-1. [Comparison](/docs/get-started/comparison) — when OKE fits (and when it doesn't)
-2. [Installation](/docs/get-started/installation) — scaffold an app in minutes
-3. [Basic Usage](/docs/get-started/basic-usage) — first flows, client, and tests
-4. [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
+## Eight elements
+
+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                                       |
+| ----------- | ----------------------------- | --------------------------------------------------------- |
+| **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
+
+The entire public vocabulary fits in one import. Everything else in the docs is
+derived from these ten names:
+
+```ts title="okengine"
+import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+```
+
+<Vocabulary />
+
+## Learn more
+
+| Topic   | Page                                                                            |
+| ------- | ------------------------------------------------------------------------------- |
+| Why OKE | [Why OKE](/docs/get-started/why)                                                |
+| 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
 
 <Cards>
   <Card
-    title="Comparison"
-    description="Positioning matrix against Hono, Elysia, Encore.ts, and iii."
-    href="/docs/get-started/comparison"
+    title="Why OKE"
+    description="Traditional backend pain — and what Manifest derivation closes."
+    href="/docs/get-started/why"
   />
   <Card
     title="Installation"
-    description="Install okengine and scaffold with create-oke."
+    description="Scaffold with create-oke and open the Console."
     href="/docs/get-started/installation"
   />
   <Card
     title="Basic Usage"
-    description="Flows, typed client, and tests from the Notes example."
+    description="Health Flow, typed client, and bun:test."
     href="/docs/get-started/basic-usage"
   />
 </Cards>
-
-## AI resources
-
-`AGENTS.md` and MCP (`:6535`) expose the Manifest, schemas, effects, traces, and the Console's safe runtime actions. See [MCP](/docs/ai/mcp) for the runtime server, [Skills](/docs/ai/skills) for the agent contract, and [llms.txt](/docs/ai/llms-txt) for the machine-readable docs (`/llms.txt`, `/llms-full.txt`).

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

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

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

@@ -0,0 +1,141 @@
+---
+title: Why OKE
+description: The six seams every TypeScript backend maintains by hand — and what OKE derives from one Manifest instead.
+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.
+
+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.
+
+<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.
+</Callout>
+
+## The six seams
+
+### The 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.
+
+**OKE derives:** reads and writes are recorded through `fx`, so invalidation
+follows the Flow — there is no separate key to remember.
+
+### The secret that fails in prod
+
+`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.
+
+### 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.
+
+**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.
+
+**OKE derives:** the [Console](/docs/console/overview) reads the Manifest —
+flows, effects, traces, architecture — current on every save, in dev and prod
+(`:6533`).
+
+### The 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.
+
+**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.
+
+**OKE derives:** drivers are named after protocols (`postgres`, `redis`,
+`s3`), the vendor lives in `images`, and `oke dev --docker` runs the real
+stack locally.
+
+## The tax is drift
+
+Every seam above is the same shape: a hand-maintained copy of knowledge the
+code already has. Watch one change propagate both ways.
+
+<DriftBoard />
+
+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.
+
+## The answer's shape
+
+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.
+
+<CollapseBoard />
+
+New infrastructure becomes a **driver** for an existing element, never a
+ninth element — the set of eight is closed.
+
+## Traditional vs OKE
+
+| 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 — `securityHeaders`, `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 --docker`                        |
+| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                           |
+
+## 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                 |
+
+## Learn more
+
+- [Introduction](/docs/get-started/introduction) — the one law, eight elements, ten exports
+- [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
+- [Console · Overview](/docs/console/overview) — the Manifest-derived operator UI
+
+## Next
+
+<Cards>
+  <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="Introduction"
+    description="The one law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
+</Cards>

package/site/content/docs/index.mdx

@@ -23,41 +23,19 @@ on(orderPlaced, sendReceipt);
   <Card
     title="Get Started"
     description="One law → install → first flows."
-    href="/docs/get-started/introduction"
-  />
-  <Card
-    title="Basic Usage"
-    description="Build from the standard starter."
-    href="/docs/get-started/basic-usage"
-  />
-  <Card
-    title="Elements"
-    description="Flow → AI reference, one page each."
-    href="/docs/elements/flow"
-  />
-  <Card
-    title="Console"
-    description="Seventeen Manifest-derived panels."
-    href="/docs/console/overview"
+    href="/docs/get-started"
   />
+  <Card title="Elements" description="Flow → AI reference, one page each." href="/docs/elements" />
   <Card
     title="Plugins"
-    description="Official extensions — security headers, CORS, CSRF, compression, maintenance, IP rules."
-    href="/docs/plugins/security-headers"
-  />
-  <Card
-    title="CLI Reference"
-    description="`oke` and `create-oke` everyday commands."
-    href="/docs/reference/cli"
-  />
-  <Card
-    title="Security"
-    description="Console security posture — Host, Origin, MCP."
-    href="/docs/reference/security"
+    description="Official extensions — security, ops, performance."
+    href="/docs/plugins"
   />
+  <Card title="Console" description="Manifest-derived operator panels." href="/docs/console" />
   <Card
-    title="AI Resources"
-    description="AGENTS.md, MCP `:6535`, `/llms.txt`."
-    href="/docs/ai/mcp"
+    title="Reference"
+    description="Config, fx, env, errors, CLI, security."
+    href="/docs/reference"
   />
+  <Card title="AI Resources" description="MCP, skills, /llms.txt." href="/docs/ai" />
 </Cards>

package/site/content/docs/plugins/anonymous.mdx

@@ -0,0 +1,95 @@
+---
+title: "Anonymous"
+description: "Official plugin — issue a user-plane session with a random id and no password."
+icon: "UserRoundMinus"
+source: "docs/spec/unified-theory.md"
+---
+
+`anonymous()` creates a throwaway principal: one public Flow returns hybrid session tokens for a
+new random `userId`. Use it for guest carts or try-before-account flows.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(anonymous())`. Treat the session like any other Bearer principal —
+  gates still decide what it may do.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { anonymous } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(anonymous());
+```
+
+</Step>
+
+<Step>
+### Sign in anonymously
+
+```typescript
+const { data } = await api.auth.signInAnonymous();
+// data.userId is a fresh UUID; store tokens like any other session
+```
+
+`POST /auth/sign-in/anonymous` — no body.
+
+</Step>
+
+<Step>
+### Gate what guests can do
+
+Attach real policies to guest-capable Flows (`gate.scope`, custom policies). Anonymous only
+issues a session — it does not grant scopes.
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option        | Type           | Default    | Meaning                                                     |
+| ------------- | -------------- | ---------- | ----------------------------------------------------------- |
+| `secret`      | `string`       | active\*   | HMAC secret (\*from `gate.auth` when plugged after `oke()`) |
+| `sessions`    | `SessionStore` | active\*   | Session store shared with Gate auth                         |
+| `now`         | `() => number` | `Date.now` | Injectable clock                                            |
+| `emailDomain` | `string`       | —          | Reserved; unused in v1                                      |
+
+## Surfaces
+
+| Flow                   | Path                           | Gate                         |
+| ---------------------- | ------------------------------ | ---------------------------- |
+| `auth.signInAnonymous` | `POST /auth/sign-in/anonymous` | `gate.public` + sign-in rate |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="plugin boot failed — needs &quot;auth&quot;">
+
+Set `oke({ gate: { auth: { … } } })` before `.plug(anonymous())`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — policies on the new principal
+- [Username](/docs/plugins/username) — upgrade path to a real credential
+- [Plugins](/docs/plugins) — all auth method plugins
+
+## Next
+
+<Cards>
+  <Card title="Username" description="Username + password." href="/docs/plugins/username" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+</Cards>

package/site/content/docs/plugins/compression.mdx

@@ -47,9 +47,9 @@ Thresholds and matchers can follow the database like every other official plugin
 
 <Cards>
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card
     title="IP Allowlist"

package/site/content/docs/plugins/cors.mdx

@@ -86,9 +86,9 @@ See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configur
     href="/docs/plugins/csrf"
   />
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card
     title="Plugin API"

package/site/content/docs/plugins/csrf.mdx

@@ -89,8 +89,8 @@ See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configur
     href="/docs/elements/gate"
   />
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
 </Cards>