okengine 0.4.3 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./client/auth": "./src/client/auth.ts",
+    "./client-react": "./src/client-react/index.ts",
     "./test": "./src/test/index.ts",
     "./config": "./src/config/index.ts",
     "./auth": "./src/auth/index.ts",

package/site/content/docs/ai/index.mdx

@@ -0,0 +1,24 @@
+---
+title: "AI Resources"
+description: "Machine-facing surfaces — MCP on :6535/:6536, agent skills, and /llms.txt."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+Resources for AI agents that read or operate an OKE app — not the `ai` element itself.
+
+## Pages
+
+<Cards>
+  <Card title="MCP" description="Runtime MCP on :6535; docs MCP on :6536." href="/docs/ai/mcp" />
+  <Card
+    title="Skills"
+    description="AGENTS.md contract and installable skills."
+    href="/docs/ai/skills"
+  />
+  <Card
+    title="llms.txt"
+    description="Machine-readable docs index and pages."
+    href="/docs/ai/llms-txt"
+  />
+</Cards>

package/site/content/docs/ai/llms-txt.mdx

@@ -31,6 +31,9 @@ curl https://oke.omqkhafi.dev/llms.mdx/docs/elements/vault
   only when breadth matters more than tokens; per-page `/llms.mdx` is the precise instrument.
 </Callout>
 
+The homepage **Onboard AI** button copies a one-line prompt that points an agent at
+`/llms.txt` plus the repo-root `AGENTS.md` — project-wide context, not a single docs page.
+
 ## How it pairs with the docs MCP
 
 These endpoints serve the _published_ docs of the framework. During `oke dev`, the [docs MCP server](/docs/ai/mcp) also runs on :6536 (`oke.docs.search` / `oke.docs.get`), answering from the same content over the MCP protocol — pick the plain HTTP endpoints for one-shot context, the MCP tools when the agent is already connected as a client.

package/site/content/docs/ai/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "AI Resources",
   "icon": "Bot",
-  "pages": ["mcp", "skills", "llms-txt"]
+  "pages": ["index", "mcp", "skills", "llms-txt"]
 }

package/site/content/docs/console/gates.mdx

@@ -1,13 +1,15 @@
 ---
 title: "Gates"
-description: "Permission matrix, rate counters, MFA map."
+description: "Permission inquiry, rate counters, and continuous audit of unguarded vs explicitly public flows."
 icon: "Shield"
 source: "docs/spec/console.md"
 ---
 
-Answers: **permission matrix, rate counters, MFA map**
+The Gates panel answers **who may do what** without dumping a giant roles×permissions matrix as
+the home screen. Inquire from a principal or from a flow; the simulator shows the chain in
+evaluation order.
 
-<Callout title="Governing rule">
+<Callout title="The one rule">
   Refuse the giant roles×permissions matrix as the entry point — inquire from principal or from
   flow.
 </Callout>
@@ -15,10 +17,10 @@ Answers: **permission matrix, rate counters, MFA map**
 ## What this panel shows
 
 <Cards>
-  <Card title="Simulator" description="Gate chain in evaluation order — where a 403 stopped." />
+  <Card title="Simulator" description="Gate chain in evaluation order — where a denial stopped." />
   <Card
-    title="Unguarded flows"
-    description="Continuous audit: public user-plane flows after deploy."
+    title="Unguarded vs public"
+    description="Empty chain (missing posture) vs gate.public (intentional)."
   />
   <Card title="Deploy diff" description="Permission widening caught from Manifest Diff." />
   <Card
@@ -27,9 +29,45 @@ Answers: **permission matrix, rate counters, MFA map**
   />
 </Cards>
 
+## Unguarded vs explicit public
+
+| Flag            | Meaning                                                                      |
+| --------------- | ---------------------------------------------------------------------------- |
+| Unguarded       | User-plane flow with an **empty** gate chain — missing auth posture          |
+| Explicit public | Chain includes the reserved `public` sentinel (`gate.public` on the trigger) |
+
+App boot fails on unguarded HTTP triggers (`GateBootError`) unless `env === "test"` and
+`gate: { unguardedHttp: "allow" }`. Prefer fixing the flow: attach a policy, or attach
+`gate.public` when the surface is intentionally open.
+
+App authors configure Gate under `oke({ gate: { policies, auth, unguardedHttp } })` — see
+[Gate](/docs/elements/gate). Builtin `/auth/*` Flows from `gate.auth` are audited the same way.
+
 ## Catalog
 
+Policies, rates, and `/auth/*` Bindings from the Manifest — inquire and audit, not a live
+rate editor. Rate `overridable` is a catalog flag; schedule edits live under
+[Clock](/docs/console/clock).
+
 <Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="limits if `overridable`" />
+  <Card title="Dev" description="full catalog + simulator" />
+  <Card title="Prod" description="same inquire surface; no silent ungated HTTP" />
+</Cards>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — policies, rate limits, `gate.auth`, posture
+- [Plugins](/docs/plugins) — plugged sign-in method plugins
+- [Access](/docs/console/access) — roles and API keys
+
+## Next
+
+<Cards>
+  <Card title="Gate" description="Declare policies and auth." href="/docs/elements/gate" />
+  <Card title="Access" description="Roles and API keys." href="/docs/console/access" />
+  <Card
+    title="Overview"
+    description="Console panels from the Manifest."
+    href="/docs/console/overview"
+  />
 </Cards>

package/site/content/docs/console/index.mdx

@@ -0,0 +1,54 @@
+---
+title: "Console"
+description: "Manifest-derived operator panels on :6533 — health, elements, traces, access, and more."
+icon: "LayoutDashboard"
+source: "docs/spec/console.md"
+---
+
+The Console is derived from your Manifest. Each panel answers one operator question.
+
+## Pages
+
+<Cards>
+  <Card
+    title="Overview"
+    description="Is the system healthy right now?"
+    href="/docs/console/overview"
+  />
+  <Card
+    title="Flows"
+    description="What exists; call it; read its contract."
+    href="/docs/console/flows"
+  />
+  <Card title="Signals" description="Queue depth, in-flight, DLQ." href="/docs/console/signals" />
+  <Card title="Store" description="Browse sql/kv/files/index." href="/docs/console/store" />
+  <Card title="Clock" description="Crons, sleeps, journal." href="/docs/console/clock" />
+  <Card
+    title="Gates"
+    description="Permission matrix and rate counters."
+    href="/docs/console/gates"
+  />
+  <Card title="Vault" description="Secret contracts and rotation." href="/docs/console/vault" />
+  <Card
+    title="Channels"
+    description="Templates, receipts, opt-outs."
+    href="/docs/console/channels"
+  />
+  <Card title="AI" description="Prompts, evals, cost, agents." href="/docs/console/ai" />
+  <Card title="Architecture" description="How it all connects." href="/docs/console/architecture" />
+  <Card title="Traces" description="One timeline across effects." href="/docs/console/traces" />
+  <Card title="Runs" description="Wide events per execution." href="/docs/console/runs" />
+  <Card
+    title="Manifest Diff"
+    description="Blast radius of a deploy."
+    href="/docs/console/manifest-diff"
+  />
+  <Card title="Access" description="Identities, roles, API keys." href="/docs/console/access" />
+  <Card title="Plugins" description="Installed plugins and panels." href="/docs/console/plugins" />
+  <Card title="Privacy" description="Where PII lives (conditional)." href="/docs/console/privacy" />
+  <Card
+    title="Tenancy"
+    description="Per-tenant usage (conditional)."
+    href="/docs/console/tenancy"
+  />
+</Cards>

package/site/content/docs/console/meta.json

@@ -2,6 +2,7 @@
   "title": "Console",
   "icon": "LayoutDashboard",
   "pages": [
+    "index",
     "overview",
     "flows",
     "signals",

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

@@ -1,15 +1,17 @@
 ---
 title: "Gate"
-description: "Permission to act — auth policies and rate limits attached to the trigger, evaluated before any effect runs, denied as typed errors."
+description: "Permission to act — policies, rate limits, and built-in auth on the HTTP trigger, evaluated before any effect runs."
 icon: "ShieldCheck"
 source: "docs/spec/unified-theory.md"
 ---
 
-Gate is how your app answers **"may this happen?"** before it happens: is this request from a verified member? has this IP exhausted its minute quota? Gates attach to the trigger — the pipeline evaluates them before a single store write, emit, or channel send runs.
+Gate answers **"may this happen?"** before it happens: is this a verified member? has this IP
+burned its minute quota? Attach gates to the HTTP trigger — the pipeline checks them before a
+store write, emit, or channel send runs.
 
 <Callout title="The one rule">
-  Permission sits **at the trigger**, and denial is a typed error value — never a thrown exception,
-  never an effect that runs halfway and rolls back.
+  Every HTTP trigger declares posture: attach a real gate, or attach `gate.public`. Omitting both
+  fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
 </Callout>
 
 ## Quick start
@@ -17,50 +19,80 @@ Gate is how your app answers **"may this happen?"** before it happens: is this r
 <Steps>
 
 <Step>
-### Declare your gates
+### Declare policies and register the Gate bag
 
-Policies are named predicates; rate limits are declarative budgets. Both live once, app-wide:
+Policies are named predicates; rate limits are declarative budgets. Put the ones you reuse in
+`oke({ gate: { policies } })`:
 
 ```typescript title="src/gates.ts"
 import { gate } from "okengine";
 
-export const member = gate.policy("member", ({ auth }) => !!auth?.verified);
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+
+export const canBook = gate.scope("booking:create");
 
 export const fair = gate.rate({
-  strategy: "sliding-window-counter", // the default — near-exact, no boundary bursts
   max: 60,
   per: "1m",
   keyBy: "ip",
 });
 ```
 
+`gate.scope(name)` is sugar for
+`gate.policy(name, ({ auth }) => auth.scopes.has(name))` — one string is both the policy id and
+the scope checked.
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { member, canBook, fair } from "./gates";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { policies: [member, canBook, fair] },
+});
+```
+
 </Step>
 
 <Step>
 ### Attach them to triggers
 
-`.gate(...)` composes in registration order — evaluated left to right, first denial wins:
+`.gate(...)` composes left to right — first denial wins. Public routes must say so explicitly:
 
 ```typescript title="src/flows/links/shorten.ts"
+import { on, flow, http, gate } from "okengine";
+import { member, canBook, fair } from "../../gates";
+
+export const health = on(
+  http.get("/health").gate(gate.public),
+  flow({
+    out: HealthOut,
+    do: () => ({ ok: true as const }),
+  }),
+);
+
 export const shorten = on(
-  http.post("/links").gate(member, fair),
+  http.post("/links").gate(member, canBook, fair),
   flow({
     in: NewLink,
     out: LinkCode,
     errors: { Taken },
     do: async ({ url, code }, fx) => {
-      /* runs only if both gates passed */
+      /* runs only if every gate passed */
     },
   }),
 );
 ```
 
+Do **not** put `gate.public` in `gate.policies` — attach it on the trigger only.
+
 </Step>
 
 <Step>
-### Denials are typed failures
+### See typed denials
 
-A denied request never reaches `do`. It returns one of three typed failures, like any entry in `errors: { … }`:
+A denied request never reaches `do`. It returns one of three typed failures:
 
 | Gate result                      | Typed failure                         |
 | -------------------------------- | ------------------------------------- |
@@ -74,32 +106,38 @@ A denied request never reaches `do`. It returns one of three typed failures, lik
 
 <GatePipeline />
 
-## Two kinds of gates
+## `oke({ gate })` bag
+
+| Option          | Type                    | Default  | Meaning                                                         |
+| --------------- | ----------------------- | -------- | --------------------------------------------------------------- |
+| `policies`      | `GateDecl[]`            | `[]`     | Named policy / rate decls for the Gate runtime                  |
+| `auth`          | `GateAuthOptions`       | —        | Builtin hybrid sessions + `/auth/*` Flows (see below)           |
+| `rateLimit`     | `{ enabled?: boolean }` | see note | When auth is on, defaults `true` — stricter rates on auth paths |
+| `unguardedHttp` | `"deny"` \| `"allow"`   | `"deny"` | `"allow"` skips posture audit **only** when `env === "test"`    |
 
-| Declaration                           | Question it answers                    | Evaluated against                  |
-| ------------------------------------- | -------------------------------------- | ---------------------------------- |
-| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)      | auth / operator / request metadata |
-| `gate.rate(options)`                  | Is there budget left for this subject? | an atomic counter on the kv driver |
+## Declarations
 
-`gate.policy(name, check)` stays the terse form. Pass
-`{ check, description }` when you want a human title in the Console
-(falls back to the policy name).
+| Declaration                           | Question it answers                         | Evaluated against                  |
+| ------------------------------------- | ------------------------------------------- | ---------------------------------- |
+| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)           | auth / operator / request metadata |
+| `gate.scope(name)`                    | Does `auth.scopes` contain this exact name? | `auth.scopes`                      |
+| `gate.public`                         | Intentionally unauthenticated surface       | always allows                      |
+| `gate.rate(options)`                  | Is there budget left for this subject?      | an atomic counter on the kv driver |
 
-### The policy context
+Pass `{ check, description }` on `gate.policy` when you want a human title in the Console (falls
+back to the policy name). The name `"public"` is reserved — use `gate.public`, not
+`gate.policy("public", …)`.
 
-The predicate receives everything it may decide with — nothing else:
+### Policy context
 
 | Field      | Contents                                                 |
 | ---------- | -------------------------------------------------------- |
 | `auth`     | User principal: `userId`, `scopes` (a `Set`), `verified` |
 | `operator` | Operator principal (Console plane): `id`                 |
-| `meta`     | Request metadata for keying decisions: `ip`, `userId`, … |
-
-```typescript
-export const admin = gate.policy("admin", ({ auth }) => auth.scopes.has("admin"));
-```
+| `meta`     | Request metadata for keying: `ip`, `userId`, …           |
 
-A policy name containing `:` is also a `Module:Action` permission — the same declaration feeds role-based access reviews in the Console.
+A policy name containing `:` is also a `Module:Action` permission for Console role reviews.
+Fine-grained authorization (`gate.scope`, roles) stays opt-in — attach it only where you need it.
 
 ### Rate options
 
@@ -109,7 +147,7 @@ A policy name containing `:` is also a `Module:Action` permission — the same d
 | `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)              |
 | `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)                  |
 | `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                                        |
-| `overridable` | boolean      | `false`                    | Allow the Console to retune `max`/`per` live             |
+| `overridable` | boolean      | `false`                    | Catalog flag in Console (rate edit UI not shipped)       |
 | `description` | string       | —                          | Human title in the Console (falls back to the rate name) |
 
 | Strategy                 | Behavior                                               |
@@ -120,37 +158,139 @@ A policy name containing `:` is also a `Module:Action` permission — the same d
 | `token-bucket`           | Steady refill; permits saved-up bursts                 |
 | `leaky-bucket`           | Smooths output to a constant rate                      |
 
-All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory driver in tests.
+All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory
+driver in tests.
+
+## Auth posture at boot
+
+Every HTTP trigger must carry a gate or `gate.public`. Omitting both fails boot with
+`GateBootError` — message starts with `gate boot failed —` and lists every gap.
+
+```typescript
+on(http.get("/health").gate(gate.public), flow({/* … */}));
+on(http.post("/bookings").gate(member, canBook), flow({/* … */}));
+```
+
+**Consequence:** first `fetch` / `execute` auto-boots (`autoBoot` defaults to `true`).
+`oke({ autoBoot: false })` is a unit-test escape hatch only. A rate-only chain is declared
+posture but does **not** authenticate.
 
-## Identity comes from auth
+`gate: { unguardedHttp: "allow" }` skips the audit **only** when `env === "test"`.
+In `local` / `prod` / `docker` migrate with per-trigger `gate.public`.
 
-Gates don't log users in — they decide about principals that already exist. The built-in auth plugin (`okengine/auth`) provides the user plane: hybrid sessions, argon2id password hashing, roles, API keys, and invites, with zero-config defaults. Whatever it establishes lands on `fx.auth`, which is exactly what your policies read.
+## Built-in auth (`gate.auth`)
 
-## Every decision is recorded
+Enable hybrid sessions (Bearer access + revocable refresh). Auth HTTP surfaces are ordinary
+Bindings under `/auth` — same posture audit and pipeline as your app Flows:
 
-Pass **and** deny, every evaluation lands on the run's `gates` dimension in the telemetry trace. The Console (`:6533` → Gates) shows which gates fired on a request and their outcomes — an audit trail of permission decisions you never had to build. Rate gates declared `overridable: true` can also be retuned (`max`/`per`) from the Console without a redeploy; anything else rejects edits by design.
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { member, canBook } from "./gates";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: {
+    auth: {
+      emailAndPassword: { enabled: true },
+      session: { freshAgeMs: 24 * 60 * 60_000 },
+    },
+    policies: [member, canBook],
+  },
+});
+```
+
+| Surface                    | When                                   |
+| -------------------------- | -------------------------------------- |
+| `POST /auth/sign-up/email` | `emailAndPassword.enabled`             |
+| `POST /auth/sign-in/email` | `emailAndPassword.enabled`             |
+| `POST /auth/refresh`       | when `gate.auth` is set                |
+| `POST /auth/revoke`        | when `gate.auth` is set                |
+| `GET /auth/me`             | Bearer session (`auth.session` policy) |
+
+| Auth option                                 | Default   | Meaning                                                                        |
+| ------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
+| `secret`                                    | minted\*  | HMAC for access tokens (\*`prod` requires you set it)                          |
+| `basePath`                                  | `"/auth"` | HTTP prefix for auth Flows                                                     |
+| `http`                                      | `true`    | `false` = secret/tables only (no `/auth/*` Bindings)                           |
+| `audience`                                  | `oke-app` | Audience stamped on access tokens                                              |
+| `emailAndPassword.enabled`                  | `false`   | Sign-up / sign-in email Flows                                                  |
+| `emailAndPassword.requireEmailVerification` | `false`   | Block sign-in until email is verified                                          |
+| `passwordPolicy`                            | secure\*  | `\*` minLength 12, letter + number; sign-up → `AuthFailed` / `password_policy` |
+| `breachCheck`                               | unset     | `(password) => Promise<boolean>` — `true` rejects as `password_breached`       |
+| `session.freshAgeMs`                        | 24h       | Window for step-up `auth.fresh` policy                                         |
+| `session.accessTtlMs` / `refreshTtlMs`      | 14m / 30d | Access / refresh lifetimes                                                     |
+| `session.idleTtlMs`                         | unset     | Opt-in: reject refresh when idle too long                                      |
+| `session.absoluteTtlMs`                     | unset     | Opt-in: hard cap from session creation                                         |
+| `session.singleSessionPerUser`              | `false`   | Opt-in: issuing a session revokes other families for that user                 |
+| `cookies.enabled`                           | `false`   | Opt-in HttpOnly cookie mirror (Bearer stays default)                           |
+| `secondaryStorage.enabled`                  | `false`   | Hot auth data in `store.kv` when configured                                    |
+| `user` / `session` / …                      | defaults  | `modelName` / `fields` / `additionalFields`                                    |
+
+HIBP via `createHibpBreachCheck` from `okengine/auth` (k-anonymity range API; requires
+`userAgent`; `onError` defaults to `"reject"` — fail closed while the check is enabled):
+
+```typescript
+import { createHibpBreachCheck } from "okengine/auth";
+
+gate: {
+  auth: {
+    emailAndPassword: { enabled: true },
+    breachCheck: createHibpBreachCheck({ userAgent: "shop/1.0" }),
+  },
+}
+```
+
+Customize tables, then run `oke schema generate` (supports `--check` in CI). Extra sign-in
+shapes: [Plugins](/docs/plugins) (username, magic link, OTP, TOTP, passkeys). Call auth from
+[createClient](/docs/reference/client) — one client, helpers in `okengine/client/auth`.
+
+## Identity and decisions
+
+Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
+`fx.auth` (Console: `fx.operator`). Audit across `fx.call` uses read-only `fx.principal`
+(see [fx](/docs/reference/fx)).
+
+Pass **and** deny land on the run's `gates` dimension. Console (`:6533` → Gates) shows the
+chain. Rate `overridable` is a catalog flag only — Clock schedules are what the Console can
+edit live today.
 
 ## Troubleshooting
 
 <Accordions>
+<Accordion title="Boot: gate boot failed — N HTTP trigger(s) missing auth posture">
+
+Empty `.gate(...)` chain. Attach a policy/rate gate, or `.gate(gate.public)`. First `fetch`
+auto-boots — do not rely on `gate.unguardedHttp: "allow"` outside `env: "test"`.
+
+</Accordion>
 <Accordion title="Can a policy read the request body?">
 
-No — and that is deliberate. Gates run before the flow, so they see only the policy context (`auth`, `operator`, `meta`). Body-dependent decisions belong inside `do`, expressed as typed `errors`.
+No. Gates run before the flow, so they see only `auth`, `operator`, and `meta`. Body-dependent
+decisions belong inside `do` as typed `errors`.
 
 </Accordion>
 <Accordion title="Logged-in users still get Forbidden">
 
-`Forbidden` means the request _was_ authenticated but a policy said no. The failure includes the gate name and reason — check whether your predicate requires `verified` or a scope the user lacks.
+`Forbidden` means authenticated but a policy said no. Check `verified` or a missing scope —
+the failure includes the gate name and reason.
 
 </Accordion>
-<Accordion title="Which keyBy should I use?">
+<Accordion title="Prod boot: gate.auth: secret is required">
 
-`"ip"` for public unauthenticated surfaces (sign-up, password reset), `"user"` for authenticated quotas. Keying an authenticated endpoint by IP punishes users behind shared NAT; keying a public endpoint by user is impossible.
+Set `gate.auth.secret` (or provide it before boot). Non-prod may mint a development secret.
 
 </Accordion>
-<Accordion title="The Console won't retune my rate limit">
+<Accordion title="Sign-up returns AuthFailed password_policy">
 
-The gate was declared without `overridable: true`. Add it and redeploy — live retuning is opt-in per gate so a mistyped change cannot silently open a floodgate.
+Default policy requires length ≥ 12 plus a letter and a number. Short passwords like `"123"`
+are rejected — not accepted silently. Tighten or loosen via `gate.auth.passwordPolicy`.
+
+</Accordion>
+<Accordion title="Which keyBy should I use?">
+
+`"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
+Keying an authenticated endpoint by IP punishes shared NAT.
 
 </Accordion>
 </Accordions>
@@ -158,18 +298,17 @@ The gate was declared without `overridable: true`. Add it and redeploy — live
 ## Learn more
 
 - [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
-- [Console · Gates](/docs/console/gates) — decision audit and live retuning
-- [Vault](/docs/elements/vault) — the credentials your policies protect
+- [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`
+- [Client](/docs/reference/client) — Bearer `createClient` + `okengine/client/auth`
+- [Plugins](/docs/plugins) — username, magic link, OTP, TOTP, passkeys
+- [Console · Gates](/docs/console/gates) — decision audit and posture
+- [Vault](/docs/elements/vault) — credentials your policies protect
 
 ## Next
 
 <Cards>
   <Card title="Vault" description="Continue to Vault." href="/docs/elements/vault" />
-  <Card
-    title="Introduction"
-    description="Eight elements overview."
-    href="/docs/get-started/introduction"
-  />
+  <Card title="Plugins" description="Sign-in method plugins under /auth." href="/docs/plugins" />
   <Card
     title="Console"
     description="Panels derived from the Manifest."

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

@@ -0,0 +1,45 @@
+---
+title: "Elements"
+description: "The eight irreducible parts of an OKE backend — Flow through AI, one page each."
+icon: "Boxes"
+source: "docs/spec/unified-theory.md"
+---
+
+Every backend concern collapses to one of these eight. Pick the element you need.
+
+## Pages
+
+<Cards>
+  <Card title="Flow" description="Behavior — on(Trigger) → Effects." href="/docs/elements/flow" />
+  <Card
+    title="Signal"
+    description="Data in motion — queues, pub/sub, streams."
+    href="/docs/elements/signal"
+  />
+  <Card
+    title="Store"
+    description="Data at rest — sql, kv, files, index."
+    href="/docs/elements/store"
+  />
+  <Card
+    title="Clock"
+    description="Time — schedules, intervals, durable sleeps."
+    href="/docs/elements/clock"
+  />
+  <Card
+    title="Gate"
+    description="Permission to act — auth and rate limits."
+    href="/docs/elements/gate"
+  />
+  <Card
+    title="Vault"
+    description="Protected knowledge — secrets and keys."
+    href="/docs/elements/vault"
+  />
+  <Card
+    title="Channel"
+    description="Reaching humans — email, SMS, push."
+    href="/docs/elements/channel"
+  />
+  <Card title="AI" description="Reaching machine intelligence." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/elements/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Elements",
   "icon": "Boxes",
-  "pages": ["flow", "signal", "store", "clock", "gate", "vault", "channel", "ai"]
+  "pages": ["index", "flow", "signal", "store", "clock", "gate", "vault", "channel", "ai"]
 }

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

@@ -36,11 +36,11 @@ oke dev
 The standard starter already exports a health Flow:
 
 ```typescript title="flows/main"
-import { on, flow, http } from "okengine";
+import { on, flow, http, gate } from "okengine";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health"),
+  http.get("/health").gate(gate.public),
   flow({
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
@@ -75,7 +75,8 @@ const { data, error } = await api.main.health({});
 ```
 
 `data` and `error` are inferred from the Flow contracts — no separate client
-schema or codegen project.
+schema. Bearer: `auth: { getToken, refresh }` (`okengine/client/auth` helpers;
+`useSession` in `okengine/client-react`). Full options: [Client](/docs/reference/client).
 
 </Step>