okengine 0.2.6 → 0.3.2

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

@@ -0,0 +1,263 @@
+---
+title: "Vault"
+description: "Secrets, API keys, and config — declared once as typed contracts, resolved from a real vault in production, never leaked into logs."
+icon: "KeyRound"
+source: "docs/spec/unified-theory.md"
+---
+
+Vault is where your app's **protected knowledge** lives: API keys, database URLs, tokens — plus non-secret config like a public app URL. This page shows how to declare a secret, give it a value, and read it in a Flow, then how OKE keeps it safe in production.
+
+<Callout title="The one rule">
+  You declare **contracts**, never values, in code. Values come from the environment at boot — a
+  secret that has no value anywhere fails the boot loudly, with every gap listed at once.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare the contract
+
+In `src/vault.ts`, declare what your app needs. This says "a secret named `STRIPE_KEY` exists" — it does **not** contain the key itself:
+
+```typescript title="src/vault.ts"
+import { vault } from "okengine";
+import { z } from "zod";
+
+export const stripeKey = vault.secret("STRIPE_KEY", {
+  description: "Payments gateway key",
+  rotate: "90d",
+  schema: z.string().startsWith("sk_"),
+  dev: "sk_test_local", // used only by `oke dev` (local) when nothing else provides a value
+});
+```
+
+</Step>
+
+<Step>
+### Give it a value
+
+For local development, put the real value in `.env.local` (gitignored):
+
+```bash title=".env.local"
+STRIPE_KEY=sk_test_your_key_here
+```
+
+Or set it from the CLI — it writes to the right place for the active mode:
+
+```bash
+oke vault set STRIPE_KEY sk_test_your_key_here
+```
+
+</Step>
+
+<Step>
+### Read it in a Flow
+
+Flows read secrets through `fx.vault` — never through `process.env`:
+
+```typescript title="src/flows/billing/charge.ts"
+export const charge = on(
+  http.post("/charge"),
+  flow({
+    in: ChargeInput,
+    out: z.object({ id: z.string() }),
+    do: async (input, fx) => {
+      const key = fx.vault(stripeKey); // cleartext, inside this flow only
+      const intent = await stripe(key).create(input);
+      return { id: intent.id };
+    },
+  }),
+);
+```
+
+</Step>
+
+</Steps>
+
+That's the whole loop: declare → set → read. Everything below is what OKE guarantees on top of it.
+
+## Two kinds of contracts
+
+| Declaration                         | Sensitive? | Console shows    | Use for                     |
+| ----------------------------------- | ---------- | ---------------- | --------------------------- |
+| `vault.secret("STRIPE_KEY", …)`     | yes        | fingerprint only | API keys, tokens, passwords |
+| `vault.config("PUBLIC_APP_URL", …)` | no         | cleartext value  | Public URLs, feature flags  |
+
+`vault(name, …)` is shorthand for `vault.secret(name, …)`.
+
+### Contract options
+
+| Option        | Type                  | Meaning                                                                  |
+| ------------- | --------------------- | ------------------------------------------------------------------------ |
+| `description` | string                | Shown in boot-gap listings and the Console                               |
+| `rotate`      | string                | Rotation hint (`"90d"`) — drives the rotation-due signal in the Console  |
+| `schema`      | zod / Standard Schema | Validated at boot; a bad value fails boot like a missing one             |
+| `dev`         | string                | Local-only fallback when no source provides a value (never used in prod) |
+| `sensitive`   | boolean               | Override the default (`true` for secrets, `false` for config)            |
+
+### Zero-setup local fallback
+
+`dev: vault.fromDocker("store.sql")` resolves the connection URL that `oke dev --docker` generated for that role — no manual copying of Postgres URLs:
+
+```typescript
+export const dbUrl = vault.secret("DATABASE_URL", {
+  dev: vault.fromDocker("store.sql"),
+});
+```
+
+## Where values come from
+
+At boot, each contract is resolved through this chain — **first hit wins**:
+
+| #   | Source               | Typical content                                   |
+| --- | -------------------- | ------------------------------------------------- |
+| 1   | `process.env`        | Real environment (CI, hosting platform)           |
+| 2   | `.env.local`         | Your machine's local overrides (gitignored)       |
+| 3   | `docker/.env.docker` | Generated compose stack credentials               |
+| 4   | vault driver         | OpenBao in docker/prod mode                       |
+| 5   | `dev` fallback       | The `dev:` option on the contract (never in prod) |
+
+If every layer misses a contract, boot **fails** before any request is served:
+
+```text
+VaultBootError: 1 secret(s) missing:
+  STRIPE_KEY — Payments gateway key
+```
+
+<Callout title="Good to know">
+  This is the fail-loud contract: an app with a missing secret **never** boots halfway and fails
+  later at request time. All gaps are listed in one error, not one at a time.
+</Callout>
+
+## Setting and rotating values
+
+| Command                    | What it does                                                     |
+| -------------------------- | ---------------------------------------------------------------- |
+| `oke vault set NAME value` | Write a value (OpenBao API in docker mode, `.env.local` locally) |
+| `oke vault list`           | List names present in the active store                           |
+| `oke vault import <file>`  | Bulk-import names from a dotenv file                             |
+
+In docker mode, `oke vault set` writes straight to the running OpenBao — no git commit, no rebuild, no restart of the vault.
+
+The **Console** (`:6533`) can also set and rotate values, but it is **write-only**: it shows a salted fingerprint (`sha256:…`) per secret, never the cleartext. When you rotate a key there, the panel shows the **blast radius** — which in-flight durable runs will wake up with the new value.
+
+<Callout title="Secrets never reach logs">
+  Every loaded secret is registered with the redactor at boot. Even if you accidentally pass one to
+  `fx.log`, the log line shows `***` — the value, never. Traces and the Console get fingerprints.
+</Callout>
+
+## Per-environment drivers
+
+Which backend holds your values depends on the mode — configured once in `oke.config.ts`:
+
+```typescript title="oke.config.ts"
+vault: {
+  local: "dotenv",   // .env.local — zero ceremony
+  docker: "openbao", // real vault in the compose stack
+  test: "memory",    // seeded map — deterministic tests
+  prod: "openbao",   // real vault in production
+},
+```
+
+| Driver    | Backend         | Best for                                   |
+| --------- | --------------- | ------------------------------------------ |
+| `dotenv`  | `.env.local`    | Local loop — no infra at all               |
+| `openbao` | OpenBao (KV v2) | Docker + prod — durable, access-controlled |
+| `memory`  | in-process map  | Tests                                      |
+
+Other drivers (`infisical`, `managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
+
+## OpenBao in docker and prod
+
+When you run `oke dev --docker` (or bring up a `--prod` stack), OKE runs a real OpenBao container with durable Raft storage — not an in-memory dev server.
+
+<Steps>
+
+<Step>
+### First boot is automatic
+
+OKE initializes OpenBao (Shamir 1-of-1), unseals it, writes a least-privilege policy that covers **only your declared secrets**, and mints an app token bound to that policy. You never run raw `bao` commands.
+
+</Step>
+
+<Step>
+### Keys stay on the host
+
+The unseal key and root token are written to `.oke/openbao/` (mode `0600`, gitignored) — never into `docker/.env.docker`, never into YAML. Only the least-privilege app token lands in `.env.docker` as `OKE_VAULT_TOKEN`.
+
+</Step>
+
+<Step>
+### Restarts just work
+
+On every later start OKE detects the sealed vault and unseals it with the host key. Secrets set before a container restart are still there after it — proven by an integration test, not assumed.
+
+</Step>
+
+</Steps>
+
+| File                      | Holds                     | Used by                          |
+| ------------------------- | ------------------------- | -------------------------------- |
+| `.oke/openbao/unseal.key` | The single unseal share   | `oke` (every start)              |
+| `.oke/openbao/root.token` | Root token                | `oke` (policy sync / token mint) |
+| `.oke/openbao/app.token`  | Least-privilege app token | the app + Console                |
+
+<Callout title="Single point of failure — read this once" type="warn">
+  Back up `.oke/openbao/unseal.key` to a separate safe location. Losing it means losing every secret
+  permanently, with no recovery.
+</Callout>
+
+This is by design: self-hosted single-node, Shamir 1-of-1, no cloud KMS. If OpenBao is initialized but the key is gone, boot fails with an explicit permanent-loss error — it never silently starts empty.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Boot fails with VaultBootError listing missing secrets">
+
+A contract has no value in any layer of the chain. Fix by providing it in exactly one place:
+
+- locally: add `NAME=value` to `.env.local` (or run `oke vault set NAME value`)
+- docker mode: `oke vault set NAME value` writes to OpenBao directly
+- CI / hosting: set a real environment variable
+
+</Accordion>
+<Accordion title="OpenBao is sealed or unreachable in docker mode">
+
+Re-run `oke dev --docker` — the bootstrap unseals with the host key on every start. If it reports the vault is initialized but `.oke/openbao/unseal.key` is missing, restore the key from your backup; the error is explicit because starting empty would look like "no secrets" instead of data loss.
+
+</Accordion>
+<Accordion title="Where is the root token?">
+
+`.oke/openbao/root.token`, mode `0600`, gitignored. It exists only for `oke` to sync policies and mint app tokens — the running app never sees it.
+
+</Accordion>
+<Accordion title="How do I rotate a key safely?">
+
+Set the new value (`oke vault set` or the Console). The Console's rotation view shows the blast radius — in-flight durable runs that will resume with the new value — before you commit. The `rotate: "90d"` hint on the contract drives the rotation-due signal.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Console · Vault](/docs/console/vault) — fingerprints, resolution chain, rotation blast radius
+- [Flow](/docs/elements/flow) — how `fx.vault` reads secrets inside `do`
+- [CLI Reference](/docs/reference/cli) — `oke vault set` · `list` · `import`
+
+## Next
+
+<Cards>
+  <Card title="Channel" description="Continue to Channel." href="/docs/elements/channel" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>

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

@@ -0,0 +1,124 @@
+---
+title: Basic Usage
+description: Scaffold the standard starter, write a Flow, and inspect it in the Console.
+source: packages/create-oke/template
+icon: SquareTerminal
+---
+
+## Scaffold an app
+
+```bash title="Terminal"
+bunx create-oke@latest my-app
+cd my-app
+oke dev
+```
+
+The app runs on `:6530`, the Console on `:6533`, and MCP on `:6535`.
+
+## Mental model
+
+Every backend behavior has one shape:
+
+```text
+on(Trigger) → Effects
+```
+
+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
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+
+export const health = on(
+  http.get("/health"),
+  flow({
+    out: z.object({ ok: z.literal(true) }),
+    do: () => ({ ok: true as const }),
+  }),
+);
+```
+
+Open `src/flows/main/index.ts`, change the route or output, and save. The 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>
+
+## Wire the app
+
+The starter adopts the module in `src/app.ts`:
+
+```typescript
+import { oke } from "okengine";
+import * as main from "./flows/main";
+
+export const app = oke({ name: "my-app" }).adopt({ main });
+export type App = typeof app;
+```
+
+The namespace becomes the typed-client namespace and each exported Flow becomes
+a method.
+
+## Typed client
+
+```typescript
+import { createClient } from "okengine/client";
+import type { App } from "../src/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.
+
+## Test
+
+Use `createTestApp` to boot the same app with test drivers:
+
+```typescript
+import { expect, test } from "bun:test";
+import { createTestApp } from "okengine/test";
+import { app } from "../src/app";
+
+test("health", 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();
+});
+```
+
+```bash title="Terminal"
+bun test
+```
+
+## Next
+
+<Cards>
+  <Card
+    title="Flow"
+    description="Triggers, contracts, effects, and composition."
+    href="/docs/elements/flow"
+  />
+  <Card
+    title="Store"
+    description="SQL, KV, files, index, and declarative resources."
+    href="/docs/elements/store"
+  />
+  <Card
+    title="Console"
+    description="Manifest-derived flows, effects, traces, and architecture."
+    href="/docs/console/overview"
+  />
+</Cards>

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

@@ -0,0 +1,65 @@
+---
+title: Comparison
+description: How OKE compares to Hono, Elysia, Encore.ts, and iii — and when to pick it.
+source: docs/spec/unified-theory.md
+icon: Scale
+---
+
+> **OKE is the batteries-included TypeScript backend for the Bun era:** contract-first APIs with end-to-end type safety, declarative infrastructure primitives, an OpenTelemetry-native Console, secure-by-default auth and ABAC — pure TypeScript, Web-Standards portable, MIT-licensed, self-hostable with zero cloud lock-in.
+
+_"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."_
+
+## When to pick OKE
+
+Choose OKE if you want:
+
+- **One mental model** for HTTP, jobs, consumers, and durable work (`on(Trigger) → Effects`)
+- **Batteries included** — store, signals, clock, gates, vault, channels, and AI as first-class elements
+- **A local Console** derived from your code (not a separate SaaS product you must adopt)
+- **MIT + self-host** with drivers named after protocols (`postgres`, `redis`, `s3`), not vendors
+- Effects that power cache invalidation, live queries, and least privilege **without hand annotations**
+
+Prefer a thinner router (Hono / Elysia alone) if you only need HTTP and will assemble queues, cron, and auth yourself.
+
+## Matrix
+
+|                                                 | Hono            | Elysia      | Encore.ts           | iii                   | **OKE**                           |
+| ----------------------------------------------- | --------------- | ----------- | ------------------- | --------------------- | --------------------------------- |
+| Primary runtime                                 | Multi (Web Std) | Bun-first   | Node + Rust core    | Rust engine, polyglot | **Bun-first, Web-Std portable**   |
+| License                                         | MIT             | MIT         | MPL-2.0             | ELv2 engine           | **MIT**                           |
+| Typed client                                    | hc RPC          | Eden Treaty | generated           | SDK                   | **contract-first + live queries** |
+| DB · queue · cron · storage                     | ❌              | ❌          | ✅                  | ✅                    | **✅ (7 elements)**               |
+| Durable workflows                               | ❌              | ❌          | ❌                  | partial               | **✅ (a flag)**                   |
+| Local Console                                   | ❌              | ❌          | ✅                  | ✅                    | **✅ (dev + prod)**               |
+| Auto cache invalidation                         | ❌              | ❌          | ❌                  | ❌                    | **✅ (from effects)**             |
+| Least-privilege by compiler                     | ❌              | ❌          | ❌                  | ❌                    | **✅**                            |
+| Human channels (email/SMS/WA)                   | ❌              | ❌          | ❌                  | ❌                    | **✅ (7th element)**              |
+| AI in the application (models, prompts, agents) | ❌              | ❌          | ❌                  | ❌                    | **✅ (8th element)**              |
+| Self-host, no lock-in                           | ✅              | ✅          | ✅ (Cloud optional) | ⚠️                    | **✅ first-class**                |
+
+## vs Collections of libraries
+
+Frameworks that ship a router plus a queue library plus a cron library plus websockets share one flaw: the concepts do not derive from one another. Documentation sprawls; each new fashion adds a concept that never gets removed.
+
+OKE starts from one law so docs, traces, hooks, and agent surfaces stay **one shape**.
+
+## vs Cloud-gravity platforms
+
+OKE is MIT, self-hostable, and names drivers after **protocols** — not vendors. Vendor choice lives in images keyed by role. There is no separate “deploy to our cloud” product you must adopt to get the Console.
+
+## vs Rolling your own effect system
+
+Effects are inferred from what a Flow touches through `fx`. Cache invalidation, live queries, least privilege, deterministic tests, and Manifest Diff fall out of that one decision — without hand-written annotations for each capability.
+
+<Cards>
+  <Card
+    title="Installation"
+    description="Install and scaffold in minutes."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Introduction"
+    description="The one law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
+</Cards>

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

@@ -0,0 +1,113 @@
+---
+title: Installation
+description: Install okengine, scaffold an app with create-oke, and open the Console.
+source: README.md
+icon: Download
+---
+
+This page gets you from zero to a running app. Prefer Bun throughout — the engine targets **Bun ≥ 1.3**.
+
+<Steps>
+
+### Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.3 (`bun --version`)
+- A terminal and a code editor
+
+### Install the package
+
+Add the framework (ships the `oke` CLI):
+
+```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>
+
+### Scaffold with create-oke
+
+Create the standard recommended project layout:
+
+```bash title="Terminal"
+bunx create-oke@latest my-app
+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.
+
+### Run the app
+
+```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:
+
+```bash title="Terminal"
+oke db generate   # write drizzle/*.sql
+oke db migrate    # apply — never automatic on boot
+```
+
+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.**
+
+Want Postgres/Redis like production while the app stays on host Bun?
+
+```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`.
+
+The generated env follows each protocol instead of forcing one generic credential shape:
+
+- 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`
+
+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.
+
+### Verify the install
+
+Hit the app (path depends on the template) or open `http://localhost:6533`. If the Console lists your flows, the install worked.
+
+</Steps>
+
+## Next steps
+
+Continue to [Basic Usage](/docs/get-started/basic-usage) for your first Flow,
+typed client, and test.
+
+<Cards>
+  <Card
+    title="Basic Usage"
+    description="First flows, client, and tests."
+    href="/docs/get-started/basic-usage"
+  />
+  <Card
+    title="CLI Reference"
+    description="oke and create-oke commands."
+    href="/docs/reference/cli"
+  />
+</Cards>

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

@@ -0,0 +1,123 @@
+---
+title: Introduction
+description: Learn the one idea behind okengine — then the eight elements and ten exports.
+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.
+
+## The one law
+
+> **Every backend behavior is a Flow:** `on(Trigger) → Effects`
+
+There are no separate species called endpoints, handlers, consumers, jobs, subscribers, or workflows. There is one species — the **Flow** — and triggers are typed values:
+
+```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"
+```
+
+Same shape every time: a trigger, a flow body, and effects inferred from what that body touches through `fx`.
+
+<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.
+
+**Learning OKE is learning one sentence.**
+
+</Callout>
+
+## What you get
+
+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:
+
+- 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
+
+## Ten exports
+
+The entire public vocabulary fits in one import:
+
+```ts title="okengine"
+import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+```
+
+| 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      |
+
+Everything else in the docs is derived from these ten names.
+
+## The eight elements
+
+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.
+
+<Features />
+
+<details>
+<summary>What each element replaces</summary>
+
+| 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         |
+
+</details>
+
+## 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.
+
+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.
+
+## Where to go next
+
+Read in this order if you are new:
+
+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
+
+<Cards>
+  <Card
+    title="Comparison"
+    description="Positioning matrix against Hono, Elysia, Encore.ts, and iii."
+    href="/docs/get-started/comparison"
+  />
+  <Card
+    title="Installation"
+    description="Install okengine and scaffold with create-oke."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Basic Usage"
+    description="Flows, typed client, and tests from the Notes example."
+    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`).