okengine 0.18.4 → 0.19.0

package/AGENTS.md

@@ -32,11 +32,13 @@ An element earns its place only if it has irreducible physics. New infrastructur
 ## Core programming vocabulary
 
 ```typescript
-import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+import { on, flow, call, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
 That is the core programming vocabulary. Everything else is derived.
 
+**Invoke contracts** (`in` / `out` / `errors`) are authored on the exposure — `http.*(path?, { … })`, `call(name, { … })`, or `mcp.tool(name, { … })` — not on `flow()`. **Emit schemas** live on Signal / Channel templates. Flow is behavior (`do` + runtime options) only.
+
 ## Governing rule
 
 > **Adopt, don't reinvent; bind natively; name drivers after protocols.**
@@ -68,13 +70,15 @@ Mnemonic: O·K·E = 6·5·3.
 
 | Budget                | Limit   |
 | --------------------- | ------- |
-| Kernel (edge profile) | < 15 kB |
-| Client runtime        | < 3 kB  |
+| Kernel (edge profile) | < 17 kB |
+| Client runtime        | < 5 kB  |
 | Cold start on Bun     | < 75 ms |
 | p99 routing overhead  | < 1 ms  |
 
 A regression fails the build. Claims we cannot measure, we do not make.
 
+After changing `src/kernel/`, `src/client/`, `src/compiler/`, `src/validation/`, or `src/release/limits.ts` / `measure.ts`, run `bun run budgets:core` (kernel edge + client gzip) before claiming done. Do not raise the published 17 kB / 5 kB caps without a measured before/after and an Unreleased changelog note; prefer lazy-loading off the edge graph.
+
 ## Package shape
 
 Published packages:
@@ -82,16 +86,18 @@ Published packages:
 - `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
 - `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships Notes starters from `packages/create-oke/templates/{standard,advanced}`.
 
-Engine: Bun `>=1.4.0`.
+Engine: Bun `>=1.4.2`.
 
 ## Documentation authority
 
-| Surface  | Path                                 |
-| -------- | ------------------------------------ |
-| Theory   | `site/content/docs/elements/`        |
-| Console  | `site/content/docs/console/`         |
-| CLI      | `site/content/docs/reference/cli.md` |
-| Manifest | `manifest.v1.schema.json`            |
+| Surface      | Path                            |
+| ------------ | ------------------------------- |
+| Understand   | `site/content/docs/understand/` |
+| Elements     | `site/content/docs/elements/`   |
+| Client       | `site/content/docs/client/`     |
+| Reference    | `site/content/docs/reference/`  |
+| AI Resources | `site/content/docs/ai/`         |
+| Manifest     | `manifest.v1.schema.json`       |
 
 **If the documentation is silent, stop and ask.**
 
@@ -99,4 +105,6 @@ Engine: Bun `>=1.4.0`.
 
 Before claiming work done: run [`.agents/skills/oke-ship`](.agents/skills/oke-ship/SKILL.md) — append notes to `changelog.md` under `## Unreleased` (never under a shipped `## v…` section), and update site docs via [`.agents/skills/oke-docs`](.agents/skills/oke-docs/SKILL.md) for any user-facing surface. Version bump is separate: `bun run bump` promotes Unreleased into the next `## vX.Y.Z`.
 
+Do **NOT** run `bun run ci` automatically after finishing an implementation. Only run `bun run ci` when the user explicitly requests it.
+
 Dependency bumps (one package, one `package.json`, or all): [`.agents/skills/oke-deps`](.agents/skills/oke-deps/SKILL.md).

package/README.md

@@ -16,7 +16,7 @@
   <a href="https://www.npmjs.com/package/okengine"><img alt="npm" src="https://shieldcn.dev/npm/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://jsr.io/@omqkhafi/okengine"><img alt="JSR" src="https://shieldcn.dev/jsr/@omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="MIT" src="https://shieldcn.dev/npm/license/okengine.svg?size=sm&variant=outline" /></a>
-  <a href="https://bun.sh"><img alt="Bun >=1.4.0" src="https://shieldcn.dev/badge/Bun-%3E%3D1.4.0.svg?logo=bun&size=sm&variant=outline" /></a>
+  <a href="https://bun.sh"><img alt="Bun >=1.4.2" src="https://shieldcn.dev/badge/Bun-%3E%3D1.4.2.svg?logo=bun&size=sm&variant=outline" /></a>
   <a href="https://github.com/omqkhafi/okengine/actions"><img alt="CI" src="https://shieldcn.dev/github/ci/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://github.com/omqkhafi/okengine/commits"><img alt="last commit" src="https://shieldcn.dev/github/last-commit/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
 </p>
@@ -39,7 +39,7 @@
 
 ## Install
 
-Requires [Bun](https://bun.sh) `>=1.4.0`.
+Requires [Bun](https://bun.sh) `>=1.4.2`.
 
 ```bash
 bunx create-oke@latest my-app                      # scaffold (recommended)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {
@@ -127,6 +127,7 @@
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts src/okid.bench.test.ts",
     "bench:load": "OKE_BENCH=1 bun test ./src/bench/*.bench.ts --timeout 600000 --pass-with-no-tests",
     "budgets": "bun src/release/publish.ts",
+    "budgets:core": "bun test src/kernel/budget.test.ts src/client/budget.test.ts",
     "gate": "PUBLISH_GATE=1 bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
@@ -138,39 +139,40 @@
     "postinstall": "bun run --cwd examples/keel prepare"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "@tanstack/react-virtual": "^3.14.9",
-    "intl-messageformat": "^11.2.13",
-    "sently": "1.2.1"
+    "@clack/prompts": "^1.8.0",
+    "@tanstack/react-virtual": "^3.14.11",
+    "intl-messageformat": "^11.2.14",
+    "oxc-parser": "^0.149.0",
+    "sently": "1.2.2"
   },
   "devDependencies": {
-    "@base-ui/react": "^1.6.0",
-    "@codemirror/commands": "^6.10.4",
+    "@base-ui/react": "^1.8.0",
+    "@codemirror/commands": "^6.11.0",
     "@codemirror/lang-json": "^6.0.2",
-    "@codemirror/state": "^6.7.1",
+    "@codemirror/state": "^6.7.4",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@codemirror/view": "^6.43.7",
+    "@codemirror/view": "^6.43.11",
     "@dagrejs/dagre": "^3.1.1",
-    "@duckdb/node-api": "^1.5.5-r.2",
-    "@electric-sql/pglite": "^0.5.4",
-    "@electric-sql/pglite-pgvector": "^0.0.5",
-    "@hugeicons/core-free-icons": "^4.2.3",
-    "@hugeicons/react": "^1.1.5",
+    "@duckdb/node-api": "^1.5.5-r.4",
+    "@electric-sql/pglite": "^0.5.8",
+    "@electric-sql/pglite-pgvector": "^0.0.9",
+    "@hugeicons/core-free-icons": "^4.3.2",
+    "@hugeicons/react": "^1.1.10",
     "@number-flow/react": "^0.6.2",
-    "@oxc-project/types": "^0.142.0",
-    "@playwright/test": "^1.62.1",
+    "@oxc-project/types": "^0.149.0",
+    "@playwright/test": "^1.63.0",
     "@sinclair/typebox": "^0.34.52",
     "@tailwindcss/vite": "^4.3.3",
-    "@tanstack/react-form": "^1.28.0",
+    "@tanstack/react-form": "^1.33.5",
     "@tanstack/react-hotkeys": "^0.10.0",
-    "@tanstack/react-query": "^5.101.4",
-    "@tanstack/react-router": "^1.170.18",
-    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-query": "^5.102.8",
+    "@tanstack/react-router": "^1.170.34",
+    "@tanstack/react-table": "^9.2.4",
     "@types/bun": "latest",
     "@types/d3-array": "^3.2.2",
-    "@types/d3-shape": "^3.1.8",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
+    "@types/d3-shape": "^3.2.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@visx/curve": "4.0.1-alpha.0",
     "@visx/event": "4.0.1-alpha.0",
     "@visx/gradient": "4.0.1-alpha.0",
@@ -178,43 +180,42 @@
     "@visx/responsive": "4.0.1-alpha.0",
     "@visx/scale": "4.0.1-alpha.0",
     "@visx/shape": "4.0.1-alpha.0",
-    "@vitejs/plugin-react": "^6.0.5",
-    "@xyflow/react": "^12.10.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@xyflow/react": "^12.11.6",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "arktype": "^2.2.3",
-    "axe-core": "^4.12.1",
+    "axe-core": "^4.13.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "d3-array": "^3.2.4",
     "d3-shape": "^3.2.0",
-    "date-fns": "^4.1.0",
+    "date-fns": "^4.4.0",
     "drizzle-kit": "1.0.0-rc.5-ab785fc",
     "drizzle-orm": "1.0.0-rc.5-169397b",
     "drizzle-seed": "^0.3.1",
     "gflows": "^1.2.1",
-    "happy-dom": "^20.11.1",
+    "happy-dom": "^20.14.3",
     "hast-util-to-jsx-runtime": "^2.3.6",
-    "mermaid": "^11.16.0",
-    "motion": "^13.1.0",
-    "nuqs": "^2.8.0",
-    "oxc-parser": "^0.142.0",
-    "oxfmt": "^0.61.0",
-    "oxlint": "^1.76.0",
+    "mermaid": "^11.17.2",
+    "motion": "^13.2.0",
+    "nuqs": "^2.10.1",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
     "oxlint-tsgolint": "^7.0.2001",
-    "playwright": "^1.62.1",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "react-resizable-panels": "^4.12.2",
-    "shadcn": "^3.8.0",
-    "shiki": "^3.22.0",
-    "tailwind-merge": "^3.5.0",
+    "playwright": "^1.63.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-resizable-panels": "^4.12.4",
+    "shadcn": "^4.21.0",
+    "shiki": "^4.4.3",
+    "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
     "typescript": "^7.0.2",
-    "valibot": "^1.4.2",
-    "vite": "^8.2.0",
-    "zod": "^4.4.3"
+    "valibot": "^1.5.0",
+    "vite": "^8.3.0",
+    "zod": "^4.6.1"
   },
   "peerDependencies": {
     "@aws-sdk/client-kms": ">=3.0.0",
@@ -230,7 +231,7 @@
     "drizzle-kit": ">=1.0.0-rc.0",
     "drizzle-orm": ">=1.0.0-rc.0",
     "drizzle-seed": ">=0.3.0",
-    "oxc-parser": ">=0.140.0",
+    "react": ">=18.0.0",
     "zod": ">=3.23.0"
   },
   "peerDependenciesMeta": {
@@ -264,6 +265,9 @@
     "ajv-formats": {
       "optional": true
     },
+    "react": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },
@@ -273,18 +277,15 @@
     "drizzle-seed": {
       "optional": true
     },
-    "oxc-parser": {
-      "optional": true
-    },
     "zod": {
       "optional": true
     }
   },
   "optionalDependencies": {
     "ink": "^6.0.0",
-    "react": "^19.2.8"
+    "react": "^19.3.0"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   }
 }

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

@@ -5,20 +5,39 @@ icon: "Bot"
 source: "docs/spec/unified-theory.md"
 ---
 
-Resources for AI agents that read or operate an OKE app — not the `ai` element itself. In OKE, **MCP is a surface of the model, not the model itself**. Gate governs agents calling in; the AI element governs apps calling out.
+Resources for AI agents that inspect, understand, or operate an OKEngine application.
 
-## Pages
+<Callout title="Two directions, one model">
+  **MCP is a surface of the model, not the model itself.** Gate governs agents calling in; the AI
+  element governs applications calling out to models.
+</Callout>
+
+```text
+External Agents → MCP (:6535) → Gate Check → Flow (inbound)
+Flow → fx.ask / fx.stream → AI Runtime → Models & External Tools (outbound)
+```
+
+## AI & Agent Surfaces
 
 <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."
+    title="MCP"
+    description="Runtime MCP on :6535 for running apps; Docs MCP on :6536 for handbook search."
+    href="/docs/ai/mcp"
+  />
+  <Card
+    title="Agent Skills"
+    description="AGENTS.md contract and autonomous maintenance skills."
     href="/docs/ai/skills"
   />
   <Card
     title="llms.txt"
-    description="Index, JSON catalogue, full dump, per-page markdown."
+    description="Standardized machine-readable feeds: /llms.txt, /llms.json, /llms-full.txt, and markdown twins."
     href="/docs/ai/llms-txt"
   />
+  <Card
+    title="AI Element"
+    description="Calling out: models, prompts, agents, and RAG inside your application."
+    href="/docs/elements/ai"
+  />
 </Cards>

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

@@ -40,7 +40,7 @@ The homepage **Onboard AI** button copies a one-line prompt that points an agent
 HTML docs pages advertise `rel="alternate"` `type="text/markdown"` to the twin.
 `Accept: text/markdown` on the same URL returns that twin and sets `Vary: Accept`.
 
-`/llms.txt` opens with **When to use this** — Introduction, Installation, AGENTS.md,
+`/llms.txt` opens with **When to use this** — The Problem, The Model, AGENTS.md,
 MCP, CLI, errors, npm, GitHub — then the curated map.
 
 Crawlers that honor `robots.txt` are allowed; `/sitemap.xml` lists the handbook and the machine entry points.

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

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

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

@@ -18,6 +18,9 @@ Tools alone don't make a good operator — an agent also needs to know the _voca
 | **Deps skill**     | `.agents/skills/oke-deps/`   | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)        |
 | **Images skill**   | `.agents/skills/oke-images/` | Updating Compose image pins                       | Registry probe, pin style, catalog + recipes + Keel + docs lockstep    |
 
+Contributor-only skills in the same tree (not required for app authors):
+`oke-ci`, `oke-docs-update`, `oke-docs-visuals`, `oke-console-style`.
+
 ## AGENTS.md — the root contract
 
 Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements bound to one contract, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
@@ -43,7 +46,7 @@ Contracts teach the _vocabulary_; [MCP](/docs/ai/mcp) grants the _hands_. An age
 ## Learn more
 
 - [MCP](/docs/ai/mcp) — the runtime surface these contracts pair with
-- [Introduction](/docs/get-started/introduction) — the eight elements in human terms
+- [The Model](/docs/understand/the-model) — the eight elements in human terms
 - [llms.txt](/docs/ai/llms-txt) — `/llms.txt`, `/llms.json`, `/llms/agents`, per-page markdown
 
 ## Next

package/site/content/docs/ai/try-it.mdx

@@ -0,0 +1,58 @@
+---
+title: "Try It"
+description: "From an empty folder to a Flow running in the Console — one sitting, minimal detour."
+icon: "Terminal"
+---
+
+## What you need
+
+Bun ≥ 1.4.2, and Docker running. `oke dev` starts everything else — Postgres, Redis, mail — for you.
+
+```bash
+bun --version
+docker info
+```
+
+## Scaffold and run
+
+```bash
+bunx create-oke@latest my-app
+cd my-app
+oke dev
+```
+
+Open the Console at the address printed in the terminal and claim it with the code shown there. The Flows listed weren't configured anywhere — they were derived from the code you just scaffolded.
+
+## Call it
+
+The starter ships a health Flow. Call it from a typed client, the same way your frontend would:
+
+```typescript
+import { createClient } from "okengine/client";
+import type { App } from "./app";
+
+const api = createClient<App>("http://localhost:6530");
+const { data, error } = await api.main.health({});
+```
+
+`data` and `error` are inferred straight from the Flow you just ran — not from a separate schema you maintain by hand.
+
+## Prove it, don't just believe it
+
+```typescript
+test("boots — health flow", async () => {
+  const t = await createTestApp(app);
+  const { data } = await t.api.main.health({});
+  expect(data).toEqual({ ok: true });
+});
+```
+
+```bash
+bun test
+```
+
+No mocked HTTP server, no real clock, no live mail provider. `createTestApp` swaps every driver behind `fx` for a deterministic one — because effects were never allowed to happen any other way.
+
+## Where this goes next
+
+If this went smoothly, the next page is the honest one: what's solid today, what's still moving, and who this is actually ready for right now.

package/site/content/docs/client/auth.mdx

@@ -0,0 +1,208 @@
+---
+title: "Auth"
+description: "createClient({ auth }) → api.auth — cookie-first, authorize/Can UI-only, Gate remains real authz."
+icon: "Lock"
+source: "docs/spec/unified-theory.md"
+---
+
+`createClient(url, { auth })` attaches `api.auth` — session orchestration over the same `/auth/*`
+Flows. Prefer that one call. `createAuthClient` + `bind` stays as a compose escape hatch.
+
+For storefronts and SPAs attaching identity to typed calls.
+
+<Callout title="The one rule">
+  Gate on Flows is real authorization. `authorize` / `hasScope` / `Can` are **UI-only**. Cookie mode
+  needs the `csrf` plugin (server soft-requires it when `gate.auth.cookies.enabled`); never persist
+  tokens to Storage when cookies own the session.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### One `createClient` with session auth
+
+```typescript title="web/src/api.ts"
+import { createClient } from "okengine/client";
+import { vault } from "okengine/vault";
+import { app } from "../../src/app";
+
+export const api = createClient(app, vault.env("PUBLIC_API_URL") ?? "", {
+  auth: { mode: "cookie", csrfConfigured: true },
+});
+```
+
+`api.auth` is an `AuthClient`. Unit Flows remain reachable (`api.auth.me`, …) under the same
+namespace.
+
+</Step>
+
+<Step>
+### Sign in and authorize chrome
+
+```typescript
+const result = await api.auth.signIn.email({ email: "alex@acme.co", password });
+if (!result.ok) {
+  if (result.twoFactor) {
+    await api.auth.completeChallenge({
+      challengeId: result.twoFactor.challengeId,
+      code: totp,
+    });
+  }
+  return;
+}
+
+const gate = api.auth.authorize({ all: ["orders:write"] });
+if (gate.status === "allowed") showFulfillment();
+await api.auth.signOut();
+```
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Authorize", "Cookie mode", "SSR", "Methods", "Escape hatch"]}>
+
+<Tab value="Authorize">
+
+```typescript
+const gate = api.auth.authorize({ all: ["orders:write"] });
+// or: api.auth.authorize({ any: ["orders:write", "admin"] })
+
+if (gate.status === "unauthenticated") redirectToSignIn();
+if (gate.status === "loading") return;
+if (gate.status === "denied") showMissing(gate.missing);
+// gate.status === "allowed"
+```
+
+React: `<Can auth={api.auth} all={["orders:write"]} fallback={<Denied />}>`. Prefer
+`authorize` / `Can` over bare `hasScope`. On server `Forbidden`, use `isForbidden` /
+`forbiddenScopes` and refresh `getSession()` if scopes look stale.
+
+</Tab>
+
+<Tab value="Cookie mode">
+
+When `gate.auth.cookies.enabled`, prefer HttpOnly cookies:
+
+```typescript
+export const api = createClient(app, base, {
+  auth: { mode: "cookie", csrfConfigured: true },
+});
+```
+
+Install `csrf({ allowNoHeader: false })`. Cross-origin also needs
+`cors({ origin: [...], credentials: true })`. Prod boots **refuse** without `csrf` when cookies
+are on; dev/test warn.
+
+</Tab>
+
+<Tab value="SSR">
+
+```typescript
+import { createClient } from "okengine/client";
+import { tokenFromRequestCookies, createServerClient } from "okengine/client/auth";
+
+// Explicit
+const api = createClient(base, {
+  credentials: "include",
+  auth: {
+    mode: "cookie",
+    getToken: () => tokenFromRequestCookies(req),
+  },
+});
+
+// Or the thin wrapper (same createClient)
+const api2 = createServerClient(req, base, { $routes });
+```
+
+</Tab>
+
+<Tab value="Methods">
+
+```typescript
+await api.auth.signIn.social({ provider: "google" });
+await api.auth.signIn.passkey({ email });
+await api.auth.signIn.magicLink.request({ email });
+await api.auth.signIn.otp.verify({ email, code });
+await api.auth.signIn.anonymous();
+await api.auth.signUp.email({ email, password, name });
+```
+
+Helpers call existing plugin Flows only — PKCE / WebAuthn UV stay server-side.
+
+</Tab>
+
+<Tab value="Escape hatch">
+
+```typescript
+import { createClient } from "okengine/client";
+import { createAuthClient } from "okengine/client/auth";
+
+const shell = createClient(app, base);
+const auth = createAuthClient(shell, { mode: "bearer", persist: "memory" });
+const api = createClient(app, base, { ...auth.clientOptions });
+auth.bind(api);
+```
+
+</Tab>
+
+</Tabs>
+
+## Helpers
+
+| Helper                                           | Package                 | Role                             |
+| ------------------------------------------------ | ----------------------- | -------------------------------- |
+| `createClient({ auth })`                         | `okengine/client`       | Happy path — attaches `api.auth` |
+| `createAuthClient`                               | `okengine/client/auth`  | Compose / bind escape hatch      |
+| `tokenFromRequestCookies` / `createServerClient` | same                    | SSR cookie → token               |
+| `authorize` / `hasScope` / `can`                 | on `AuthClient`         | UI-only chrome                   |
+| `isUnauthorized` / `isCsrf` / `forbiddenScopes`  | same                    | Envelope narrowers               |
+| `useSession` / `useAuthorize` / `Can`            | `okengine/client-react` | React session + chrome           |
+
+## Denial codes
+
+| Code           | HTTP | Typical fix                                    |
+| -------------- | ---- | ---------------------------------------------- |
+| `Unauthorized` | 401  | Sign in or refresh; re-login if still denied   |
+| `Forbidden`    | 403  | Wrong scopes / CSRF — read `error.data.reason` |
+| `RateLimited`  | 429  | Wait `retryAfterMs`                            |
+
+Also see [CORS](/docs/plugins/cors) and [CSRF](/docs/plugins/csrf). Advanced create-oke starter
+demos cookie + passkey + `<Can>`.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Cookie mode warns about CSRF / prod refuses boot">
+  Plug `csrf({ allowNoHeader: false })` when `gate.auth.cookies.enabled`. Set
+  `csrfConfigured: true` on the client only after the plugin is installed.
+</Accordion>
+
+<Accordion title="authorize allowed but Flow returns Forbidden">
+  Expected — client authorize is UI-only. Add `gate.scope` / `gate.policy` on the Flow.
+</Accordion>
+
+<Accordion title="localStorage warning">
+  Prefer cookie mode or memory / `sessionStorage`. XSS can read Storage until family revoke.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Calling](/docs/client/calling) — envelopes, binary `{ response: "blob" }`, REST
+- [React](/docs/client/react) — `useSession` / `Can` / `useAuthorize`
+- [Gate · Auth](/docs/elements/gate/auth) — server cookies and scopes
+
+## Next
+
+<Cards>
+  <Card title="Live" href="/docs/client/live" />
+  <Card title="React" href="/docs/client/react" />
+  <Card title="Gate Auth" href="/docs/elements/gate/auth" />
+</Cards>