okengine 0.3.6 → 0.4.3

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"]
 }

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/plugins/ip-allowlist.mdx

@@ -46,8 +46,7 @@ A client whose IP is not on the list receives `403` with a typed denial:
 <Callout type="error">
   Standard reverse proxies **append** to `X-Forwarded-For` — left-side hops are attacker-controlled.
   The plugin trusts the hop `trustedProxyDepth` from the **right** (default `1` = last hop). Set
-  this to your real proxy count — wrong depth bypasses the allowlist (topology-dependent, not
-  drop-in).
+  this to your real proxy count — wrong depth bypasses the allowlist.
 </Callout>
 
 ## Notes

package/site/content/docs/plugins/security-headers.mdx

@@ -51,7 +51,7 @@ Every [helmet.js](https://helmet.js.org/) middleware maps to an option here —
 | `xPoweredBy`                    | `poweredBy`                                                                               | Yes — removed; a string sets a decoy value                                  |
 | `xXssProtection`                | `xssProtection`                                                                           | Yes — `0` (disables the legacy buggy auditor)                               |
 
-Beyond parity: headers land on **failures too** (helmet middleware ordering bugs are a classic Express footgun), app-set values win by default, and every option can be driven live from the database (below).
+Beyond parity: headers land on **failures too** (middleware that only wraps happy paths skips error responses), app-set values win by default, and every option can be driven live from the database (below).
 
 ## Options
 

package/site/content/docs/reference/configuration.mdx

@@ -39,7 +39,7 @@ drivers: {
 | `store.sql`        | env driver map | `sqlite` · `postgres` · `libsql` · `pglite` · `memory`                       |
 | `store.kv`         | env driver map | `memory` · `redis`                                                           |
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector` · `libsql`                                             |
+| `store.index`      | env driver map | `memory` · `pgvector` · `libsql` · `meilisearch`                             |
 | `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
 | `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
 | `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |

package/site/content/docs/reference/environment-variables.mdx

@@ -24,9 +24,11 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## Index store
 
-| Variable           | Used for                  | Default when unset |
-| ------------------ | ------------------------- | ------------------ |
-| `OKE_INDEX_DRIVER` | Force the index driver id | config map         |
+| Variable              | Used for                                            | Default when unset |
+| --------------------- | --------------------------------------------------- | ------------------ |
+| `OKE_INDEX_DRIVER`    | Force the index driver id                           | config map         |
+| `OKE_STORE_INDEX_URL` | Meilisearch base URL (`meilisearch` driver)         | —                  |
+| `OKE_STORE_INDEX_KEY` | Meilisearch API / master key (`meilisearch` driver) | `MEILI_MASTER_KEY` |
 
 ## KV store