okengine 0.3.5 → 0.4.3

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

@@ -1,11 +1,24 @@
 ---
 title: Basic Usage
-description: Scaffold the standard starter, write a Flow, and inspect it in the Console.
+description: Scaffold the standard starter, call the health Flow, and inspect it in the Console.
 source: packages/create-oke/template
 icon: SquareTerminal
 ---
 
-## Scaffold an app
+Write your first Flow, call it from a typed client, and prove it with
+`bun:test` — using the same standard starter `create-oke` scaffolds.
+
+<Callout title="The one rule">
+  All reads, writes, emits, sends, and external calls belong behind `fx`. That is what makes effects
+  inspectable and tests deterministic.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Scaffold and run
 
 ```bash title="Terminal"
 bunx create-oke@latest my-app
@@ -13,26 +26,16 @@ cd my-app
 oke dev
 ```
 
-The app runs on `:6530`, the Console on `:6533`, and MCP on `:6535`.
+<Surfaces />
 
-## Mental model
+</Step>
 
-Every backend behavior has one shape:
+<Step>
+### Read the health Flow
 
-```text
-on(Trigger) → Effects
-```
+The standard starter already exports a health Flow:
 
-1. **Trigger** — how work starts (`http.post`, `every("10m")`, a signal, …)
-2. **Contracts** — `in`, `out`, and typed `errors`
-3. **`do`** — the body; world access goes only through `fx`
-4. **Effects** — inferred from the `fx` calls
-
-## Your first Flow
-
-The standard starter includes a health Flow:
-
-```typescript
+```typescript title="flows/main"
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
@@ -45,57 +48,65 @@ export const health = on(
 );
 ```
 
-Open `src/flows/main/index.ts`, change the route or output, and save. The app and
-Console update together from the same Manifest.
+Change the route or output and save. App and Console update together from the
+same Manifest.
 
-<Callout title="The invariant">
-  All reads, writes, emits, sends, and external calls belong behind `fx`. This is what makes effects
-  inspectable and tests deterministic.
-</Callout>
+</Step>
 
-## Wire the app
+<Step>
+### Call it from a typed client
 
-The starter adopts the module in `src/app.ts`:
+Adopted modules become namespaces on the client:
 
-```typescript
+```typescript title="app"
 import { oke } from "okengine";
 import * as main from "./flows/main";
 
-export const app = oke({ name: "my-app" }).adopt({ main });
+export const app = oke({ name: "standard" }).adopt({ main });
 export type App = typeof app;
 ```
 
-The namespace becomes the typed-client namespace and each exported Flow becomes
-a method.
-
-## Typed client
-
-```typescript
+```typescript title="client"
 import { createClient } from "okengine/client";
-import type { App } from "../src/app";
+import type { App } from "./app";
 
 const api = createClient<App>("http://localhost:6530");
 const { data, error } = await api.main.health({});
 ```
 
-`data` and `error` are inferred from the Flow contracts; no separate client
-schema or code-generation project is required.
+`data` and `error` are inferred from the Flow contracts — no separate client
+schema or codegen project.
+
+</Step>
+
+</Steps>
+
+## Mental model
+
+Every backend behavior has one shape:
+
+<FlowShape />
+
+## From Flow to client
+
+Export → adopt → call or test. Same App type — no separate codegen project.
+
+<ClientLoop />
 
 ## Test
 
-Use `createTestApp` to boot the same app with test drivers:
+Boot the same app with test drivers:
 
-```typescript
+```typescript title="tests/standard.test.ts"
 import { expect, test } from "bun:test";
 import { createTestApp } from "okengine/test";
 import { app } from "../src/app";
 
-test("health", async () => {
+test("boots — health flow", async () => {
   const t = await createTestApp(app);
   const { data, error } = await t.api.main.health({});
   expect(error).toBeNull();
   expect(data).toEqual({ ok: true });
-  await app.stop();
 });
 ```
 
@@ -103,6 +114,30 @@ test("health", async () => {
 bun test
 ```
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="api.main.health is not a function / type error">
+  Confirm the Flow is `export`ed from the module you `.adopt({main})`, and that `createClient` is
+  typed with your `App` type. Restart `oke dev` after renaming exports so the Manifest refreshes.
+</Accordion>
+
+<Accordion title="createTestApp fails to boot">
+  The starter patches test env and stores on the app options. Keep the template's side-imports
+  (vault, gates, channels, core db) — removing them can leave Vault or Store unresolved under test
+  drivers.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
+- [Store](/docs/elements/store) — SQL, KV, files, index
+- [fx](/docs/reference/fx) — the full effect surface
+- [Console · Overview](/docs/console/overview) — Manifest-derived panels
+
 ## Next
 
 <Cards>

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

@@ -5,31 +5,43 @@ source: README.md
 icon: Download
 ---
 
-This page gets you from zero to a running app. Prefer Bun throughout — the engine targets **Bun ≥ 1.3**.
+This page gets you from zero to a running app on Bun. The engine targets
+**Bun ≥ 1.3** — prefer it for install, scaffold, and `oke dev`.
+
+<Callout title="The one rule">
+  Prefer `bun add okengine` when you want the `oke` CLI on your PATH. JSR (`@omqkhafi/okengine`) is
+  the library API only.
+</Callout>
+
+## Quick start
 
 <Steps>
 
+<Step>
 ### Prerequisites
 
 - [Bun](https://bun.sh) ≥ 1.3 (`bun --version`)
 - A terminal and a code editor
 
-### Install the package
+</Step>
 
-Add the framework (ships the `oke` CLI):
+<Step>
+### Install the package
 
 ```bash title="Terminal"
 bun add okengine
 ```
 
-<Callout title="JSR">
-  Library API only: `bunx jsr add @omqkhafi/okengine`. Prefer npm / `bun add` when you want the
-  `oke` CLI on your PATH via the package.
-</Callout>
+Library-only via JSR:
 
-### Scaffold with create-oke
+```bash title="Terminal"
+bunx jsr add @omqkhafi/okengine
+```
+
+</Step>
 
-Create the standard recommended project layout:
+<Step>
+### Scaffold with create-oke
 
 ```bash title="Terminal"
 bunx create-oke@latest my-app
@@ -37,74 +49,114 @@ bunx create-oke@latest my-app --template standard
 bunx create-oke@latest my-app --sql postgres
 ```
 
-The standard template is the only starter. `--sql postgres` opts into a
-`pgTable` schema and pins local, Docker, and production to Postgres; the default
-keeps local SQLite with Docker and production on Postgres.
+`standard` is the only starter. Default: local SQLite, Docker/production
+Postgres. `--sql postgres` pins `store.sql` for **local, Docker, and
+production** — schema stays dialect-agnostic (`store.schema.table`).
+
+</Step>
 
-### Run the app
+<Step>
+### Run and verify
 
 ```bash title="Terminal"
 cd my-app
 oke dev
 ```
 
-Local mode watches domain schema paths (`schema.ts` / `schema.decl.ts` / `app.ts`)
-and auto-runs `oke db push` (drizzle-kit) so the database stays in sync. Opt out
-with `oke dev --no-db-push` or `db: { autoPush: false }` in `oke.config.ts`. For
-production, generate and apply migrations deliberately:
+Three ports come up together (mnemonic: **O·K·E = 6·5·3**):
+
+<Surfaces />
+
+Open `http://localhost:6533`. If the Console lists your flows, the install
+worked — **derived, not configured.**
+
+</Step>
+
+</Steps>
+
+## Local database sync
+
+Local mode watches schema paths and auto-runs `oke db push` so the database
+stays in sync. Opt out with `oke dev --no-db-push` or
+`db: { autoPush: false }` in `oke.config.ts`.
+
+For production, generate and apply migrations deliberately — never automatic on
+boot:
 
 ```bash title="Terminal"
 oke db generate   # write drizzle/*.sql
-oke db migrate    # apply — never automatic on boot
+oke db migrate    # apply
 ```
 
-Three ports come up together (mnemonic: **O·K·E = 6·5·3**):
-
-| Port    | Surface  |
-| ------- | -------- |
-| `:6530` | Your app |
-| `:6533` | Console  |
-| `:6535` | MCP      |
-
-Open the Console — flows, contracts, effects, and an architecture diagram are already there. **Derived, not configured.**
+## Docker mode
 
 Want Postgres/Redis like production while the app stays on host Bun?
 
+<DevModes />
+
 ```bash title="Terminal"
 oke dev --docker   # or: oke dev -d
 # or set the saved default: oke mode docker
 ```
 
-That uses the `docker` driver profile in `oke.config.ts` (filled from `prod` when omitted). Compose files and credentials land under `docker/` (`.env.docker` beside compose). Host ports — including Mailpit UI / RustFS console extras — are unique per project so multiple apps can run at once. Bare `oke dev` prompts once on a TTY (saved in `.oke/mode`); non-TTY defaults to `local`.
+Uses the `docker` driver profile in `oke.config.ts` (filled from `prod` when
+omitted). Compose and credentials land under `docker/` (`.env.docker` beside
+compose); host ports are unique per project.
 
-The generated env follows each protocol instead of forcing one generic credential shape:
+Bare `oke dev` prompts once on a TTY (saved in `.oke/mode`); non-TTY defaults
+to `local`.
 
-- Postgres: `DATABASE_URL` plus `OKE_STORE_SQL_*`
-- Redis: `REDIS_URL` plus `OKE_STORE_KV_PASSWORD`
-- S3-compatible files: `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET`, `S3_URL`, `S3_REGION`, and `S3_CONSOLE_URL`
-- SMTP email: `SMTP_URL`, `SMTP_HOST`, `SMTP_PORT`, and `MAILPIT_UI_URL` with optional `SMTP_USER` / `SMTP_PASSWORD`
+| Protocol            | Env shape (generated)                                                                                           |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Postgres            | `DATABASE_URL` plus `OKE_STORE_SQL_*`                                                                           |
+| Redis               | `REDIS_URL` plus `OKE_STORE_KV_PASSWORD`                                                                        |
+| S3-compatible files | `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET`, `S3_URL`, `S3_REGION`, `S3_CONSOLE_URL` |
+| SMTP email          | `SMTP_URL`, `SMTP_HOST`, `SMTP_PORT`, `MAILPIT_UI_URL`, optional `SMTP_USER` / `SMTP_PASSWORD`                  |
 
-Each section also includes commented controls (for example Redis memory policy,
-Postgres init options, Bun S3 session tokens, and Mailpit limits). Uncommented
-supported controls are preserved when `oke dev --docker` regenerates the file.
+Each section also includes commented controls (Redis memory policy, Postgres
+init options, Bun S3 session tokens, Mailpit limits). Uncommented supported
+controls are preserved when `oke dev --docker` regenerates the file.
 
-### Verify the install
+## Troubleshooting
 
-Hit the app (path depends on the template) or open `http://localhost:6533`. If the Console lists your flows, the install worked.
+<Accordions>
 
-</Steps>
+<Accordion title="oke: command not found after install">
+  Use `bun add okengine` (npm package), not JSR alone — the CLI ships with the npm distribution. Or
+  invoke via `bunx oke dev` from the project.
+</Accordion>
+
+<Accordion title="Console is empty / no flows listed">
+  Confirm `oke dev` is running and you opened `:6533`, not `:6530`. Flows appear only after the app
+  boots and the Manifest is extracted — fix TypeScript errors in the terminal first.
+</Accordion>
+
+<Accordion title="Database out of sync after editing schema">
+  Local `oke dev` auto-pushes by default. If you passed `--no-db-push` or set `db.autoPush: false`,
+  run `oke db push` yourself, or re-enable auto-push.
+</Accordion>
 
-## Next steps
+</Accordions>
 
-Continue to [Basic Usage](/docs/get-started/basic-usage) for your first Flow,
-typed client, and test.
+## Learn more
+
+- [CLI Reference](/docs/reference/cli) — `oke`, `create-oke`, mode, and db commands
+- [Environment variables](/docs/reference/environment-variables) — protocol-shaped env
+- [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and `db.autoPush`
+
+## Next
 
 <Cards>
   <Card
     title="Basic Usage"
-    description="First flows, client, and tests."
+    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"
+  />
   <Card
     title="CLI Reference"
     description="oke and create-oke commands."

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": ["introduction", "why", "installation", "basic-usage"]
 }