okengine 0.2.6 → 0.3.2

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

@@ -0,0 +1,136 @@
+---
+title: "Security Headers"
+description: "Official plugin — the complete secure-headers set on every HTTP response, failures included. Full helmet.js parity with API-first defaults, a CSP builder with report-only mode, and live DB-driven config."
+icon: "ShieldCheck"
+source: "src/plugins/security-headers.ts"
+---
+
+`securityHeaders()` stamps security headers on **every** HTTP flow response — successes, failures, and short-circuits alike, because it runs at `onResponse`, the last pipeline stage. An explicit value your app already set is never overridden unless you ask for it.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { securityHeaders } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders());
+```
+
+Every HTTP response now carries:
+
+| Header                              | Value         |
+| ----------------------------------- | ------------- |
+| `X-Content-Type-Options`            | `nosniff`     |
+| `X-Frame-Options`                   | `DENY`        |
+| `Referrer-Policy`                   | `no-referrer` |
+| `Origin-Agent-Cluster`              | `?1`          |
+| `X-DNS-Prefetch-Control`            | `off`         |
+| `X-Download-Options`                | `noopen`      |
+| `X-Permitted-Cross-Domain-Policies` | `none`        |
+| `X-XSS-Protection`                  | `0`           |
+| `X-Powered-By`                      | removed       |
+
+## Helmet parity
+
+Every [helmet.js](https://helmet.js.org/) middleware maps to an option here — same defaults wherever helmet's default is safe for an API, plus three deliberate deviations marked `opt-in`:
+
+| Helmet middleware               | This plugin                                                                               | Default match?                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `contentSecurityPolicy`         | `contentSecurityPolicy` — string **or** `{ directives, useDefaults, reportOnly }` builder | Same default directives; ours is opt-in like helmet's structure suggests    |
+| `crossOriginEmbedderPolicy`     | `crossOriginEmbedderPolicy`                                                               | Yes — off unless set                                                        |
+| `crossOriginOpenerPolicy`       | `crossOriginOpenerPolicy`                                                                 | **opt-in** — helmet's `same-origin` default breaks cross-origin API clients |
+| `crossOriginResourcePolicy`     | `crossOriginResourcePolicy`                                                               | **opt-in** — same API rationale                                             |
+| `originAgentCluster`            | `originAgentCluster`                                                                      | Yes — `?1`                                                                  |
+| `referrerPolicy`                | `referrerPolicy`                                                                          | Yes — `no-referrer`                                                         |
+| `strictTransportSecurity`       | `hsts`                                                                                    | **opt-in** — HSTS is sticky; never on plain-HTTP local dev                  |
+| `xContentTypeOptions`           | always on                                                                                 | Yes — `nosniff`                                                             |
+| `xDnsPrefetchControl`           | `dnsPrefetchControl`                                                                      | Yes — `off`; `{ allow: true }` → `on`                                       |
+| `xDownloadOptions`              | `downloadOptions`                                                                         | Yes — `noopen`                                                              |
+| `xFrameOptions`                 | `frameOptions`                                                                            | Yes — stricter: `DENY` over helmet's `SAMEORIGIN`                           |
+| `xPermittedCrossDomainPolicies` | `permittedCrossDomainPolicies`                                                            | Yes — `none`                                                                |
+| `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).
+
+## Options
+
+| Option                         | Type                                                             | Default         | Does                                                                                     |
+| ------------------------------ | ---------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------- |
+| `contentSecurityPolicy`        | `string` · `{ directives, useDefaults?, reportOnly? }`           | — (omitted)     | CSP header; object form merges over helmet's default directives, camelCase or kebab keys |
+| `frameOptions`                 | `"DENY"` · `"SAMEORIGIN"`                                        | `"DENY"`        | `X-Frame-Options` value                                                                  |
+| `referrerPolicy`               | `string`                                                         | `"no-referrer"` | `Referrer-Policy` value                                                                  |
+| `hsts`                         | `boolean` · `{ maxAge?, includeSubDomains?, preload? }`          | `false`         | `Strict-Transport-Security` — `true` = one year                                          |
+| `permissionsPolicy`            | `string`                                                         | — (omitted)     | `Permissions-Policy` value                                                               |
+| `crossOriginOpenerPolicy`      | `"same-origin"` · `"same-origin-allow-popups"` · `"unsafe-none"` | — (omitted)     | `Cross-Origin-Opener-Policy` value                                                       |
+| `crossOriginResourcePolicy`    | `"same-origin"` · `"same-site"` · `"cross-origin"`               | — (omitted)     | `Cross-Origin-Resource-Policy` value                                                     |
+| `crossOriginEmbedderPolicy`    | `"require-corp"` · `"credentialless"`                            | — (omitted)     | `Cross-Origin-Embedder-Policy` value                                                     |
+| `originAgentCluster`           | `boolean`                                                        | `true`          | `Origin-Agent-Cluster: ?1` — `false` omits                                               |
+| `dnsPrefetchControl`           | `boolean` · `{ allow: boolean }`                                 | `true` → `off`  | `X-DNS-Prefetch-Control`; `false` omits                                                  |
+| `downloadOptions`              | `boolean`                                                        | `true`          | `X-Download-Options: noopen` — `false` omits                                             |
+| `permittedCrossDomainPolicies` | `"none"` · `"master-only"` · `"by-content-type"` · `"all"`       | `"none"`        | `X-Permitted-Cross-Domain-Policies` value                                                |
+| `poweredBy`                    | `boolean` · `string`                                             | `true`          | `true` removes `X-Powered-By`, a string sets a decoy, `false` keeps the app's            |
+| `xssProtection`                | `boolean`                                                        | `true`          | `X-XSS-Protection: 0` — `false` omits                                                    |
+| `override`                     | `boolean`                                                        | `false`         | Replace values the app set explicitly                                                    |
+
+```typescript
+.plug(
+  securityHeaders({
+    contentSecurityPolicy: {
+      directives: { scriptSrc: ["'self'", "https://cdn.example.com"] }, // merged over the defaults
+      reportOnly: true, // Content-Security-Policy-Report-Only while you tune
+    },
+    hsts: { maxAge: 63072000, includeSubDomains: true },
+    permissionsPolicy: "camera=(), microphone=()",
+  }),
+)
+```
+
+<Callout type="warn">
+  HSTS is off by default because it is **sticky** — once a browser sees it, it insists on HTTPS for
+  the whole `max-age`. Enable it only on deployments that already serve HTTPS (never on plain-HTTP
+  local dev). The same caution applies to `upgrade-insecure-requests` in the default CSP.
+</Callout>
+
+## Runtime configuration
+
+Header policy is exactly the config you want to flip without a redeploy — enable HSTS the day HTTPS lands, tighten the CSP after an audit. Pass a `configSource()` and options follow the database within one sync interval:
+
+```typescript
+const headers = configSource({
+  plugin: "security-headers",
+  code: { hsts: false }, // safe floor for local dev
+  db: { store: db },
+  kv: cache,
+});
+on(every("30s"), headers.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders(headers));
+```
+
+```sql
+INSERT INTO security_headers_config ("key", "value")
+VALUES ('config', '{"hsts": true}');
+```
+
+See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Notes
+
+| Behavior          | Detail                                                                |
+| ----------------- | --------------------------------------------------------------------- |
+| Failures included | `onResponse` runs after `onError` — denials get the same headers      |
+| App wins          | A header set earlier (app hook, flow) is kept unless `override: true` |
+| Non-HTTP triggers | No-op — nothing to stamp outside HTTP                                 |
+| Scope             | Flow responses — infra routes (`/_oke/*`, 404s) bypass the pipeline   |
+
+## Next
+
+<Cards>
+  <Card title="CORS" description="Cross-origin rules at the edge." href="/docs/plugins/cors" />
+  <Card title="CSRF" description="Block cross-site state changes." href="/docs/plugins/csrf" />
+  <Card
+    title="Plugin API"
+    description="Runtime configuration contract."
+    href="/docs/reference/plugins"
+  />
+</Cards>

package/site/content/docs/reference/cli.md

@@ -0,0 +1,101 @@
+---
+title: "CLI Reference"
+description: "oke and create-oke — everyday commands and flags."
+icon: "Terminal"
+source: "docs/cli.md"
+---
+
+### Commands
+
+```bash
+bun add okengine                 # ONE package
+
+oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535 · docs MCP :6536
+                                 #   → client types + domain schema push on save (local)
+oke dev --local                  # -l  session-only local (in-memory; never writes .oke/mode)
+oke dev --no-db-push             #     opt out of auto oke db push on schema change
+oke dev --docker                 # -d  infra compose under docker/ (no app container; host Bun)
+oke dev -d store.sql,signal      #     partial: only these roles get real backends
+oke mode local|docker            # get/set default oke dev mode (saved in .oke/mode)
+
+oke start                        # runs exactly what production runs (this is the Docker CMD)
+oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
+oke stack                        # preview resolved images/tags/ports — writes nothing
+
+oke schema generate              # core + plugin stubs → schema/oke.ts   (--check in CI)
+oke db push                      # domain schema.ts → live local DB (dev; drizzle-kit)
+oke db generate                  # versioned SQL under drizzle/ (review)
+oke db migrate                   # apply migrations (explicit; never auto in prod)
+oke vault set STRIPE_KEY         # also: list · import .env · key rotate
+oke client add <url>             # types for a separate frontend repo
+
+oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
+oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
+oke images pin                   # tags → digests in oke.images.lock
+
+oke build --target edge          # < 15 kB kernel profile
+oke eval                         # run prompt eval sets; fails CI on regression
+oke branch prod --at "yesterday" # fork journaled state into a sandbox
+oke privacy erase --subject <id> # crypto-shredding: deletes the key, not the terabytes
+oke upgrade                      # run codemods for a breaking change, print the diff
+```
+
+In development, app, Console, MCP, and docs MCP prefer the canonical ports and move upward
+when occupied. Docker infrastructure uses stable per-project offsets in disjoint ranges for
+each built-in service, preventing one service's offset port from overlapping another's.
+
+### Additional commands
+
+```bash
+oke doctor --diff                # CI gate: undeclared Manifest contract breaks
+oke doctor --json                # -j  JSON on stdout; hints on stderr (agents / MCP)
+oke stack --json                 # -j
+oke images list                  # recipe · image · tag · digest · size (--json|-j)
+oke gates list                   # Module:Action catalogue (--json|-j)
+```
+
+### Shell completion
+
+Generated from the command registry — not a hand-maintained script:
+
+```bash
+eval "$(oke completion bash)"
+eval "$(oke completion zsh)"
+oke completion fish | source
+```
+
+### Short flags
+
+Long form is canonical in docs; short form is convenience only. Shared letters follow git’s pattern (different meanings on different subcommands — e.g. `-c` is `--check` on `schema generate`, `--config` on `stack` / `docker` / `images`).
+
+| Long                 | Short | Where                                          |
+| -------------------- | ----- | ---------------------------------------------- |
+| `--local`            | `-l`  | `dev`                                          |
+| `--docker`           | `-d`  | `dev`                                          |
+| `--no-db-push`       |       | `dev`                                          |
+| `--prod`             | `-p`  | `docker`                                       |
+| `--port`             | `-p`  | `start`                                        |
+| `--check`            | `-c`  | `schema generate`                              |
+| `--config`           | `-c`  | `stack`, `docker`, `images`, `db *` (drizzle)  |
+| `--apply`            | `-a`  | `upgrade`                                      |
+| `--at`               | `-a`  | `branch`                                       |
+| `--after`            | `-a`  | `doctor --diff`                                |
+| `--target`           | `-t`  | `build`                                        |
+| `--diff`             |       | `doctor`                                       |
+| `--json`             | `-j`  | `doctor`, `stack`, `images list`, `gates list` |
+| `--manifest`         | `-m`  | most Manifest readers                          |
+| `--entry`            | `-e`  | `dev`, `start`, `build`                        |
+| `--out` / `--outdir` | `-o`  | writers                                        |
+| `--subject`          | `-s`  | `privacy erase`                                |
+| `--before`           | `-b`  | `doctor --diff`                                |
+| `--base`             | `-B`  | `doctor --diff`                                |
+
+### Exit codes
+
+| Exit  | Meaning                               |
+| ----- | ------------------------------------- |
+| **0** | success                               |
+| **1** | usage / validation                    |
+| **2** | runtime / environment / check failure |
+
+`oke help` prints the same flag and exit-code tables.

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

@@ -0,0 +1,159 @@
+---
+title: "Configuration"
+description: "Every option in oke.config.ts — drivers per environment, images, i18n, tenancy, privacy, db sync, topology, ports, and console."
+icon: "Settings2"
+---
+
+Complete reference for `oke.config.ts`. Every option below is verified against `defineConfig`; the four environment keys everywhere are `local` · `docker` · `test` · `prod`.
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  // options below
+});
+```
+
+## drivers
+
+Which backend each element talks to, per environment. A value is either a driver id string or a rich object:
+
+```typescript
+drivers: {
+  store: {
+    sql: { local: "sqlite", docker: "postgres", test: "memory", prod: "postgres" },
+    kv: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
+    files: { local: "fs", docker: "s3", test: "memory", prod: "s3" },
+  },
+  signal: { local: "memory", docker: "postgres", test: "memory", prod: "postgres" },
+  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
+  vault: { local: "dotenv", docker: "openbao", test: "memory", prod: "openbao" },
+  channel: {
+    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+  },
+},
+```
+
+| Key                | Shape          | Driver ids (verified)                                                        |
+| ------------------ | -------------- | ---------------------------------------------------------------------------- |
+| `store.sql`        | env driver map | `sqlite` · `postgres` · `memory`                                             |
+| `store.kv`         | env driver map | `memory` · `redis`                                                           |
+| `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
+| `store.index`      | env driver map | `memory` · `pgvector`                                                        |
+| `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
+| `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
+| `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |
+| `channel.email`    | env driver map | `console` · `smtp` · `resend`                                                |
+| `channel.sms`      | env driver map | `console` · `unifonic`                                                       |
+| `channel.whatsapp` | env driver map | medium declared; drivers added per provider                                  |
+| `channel.push`     | env driver map | medium declared; drivers added per provider                                  |
+| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama` |
+| `runs`             | env driver map | runs-store driver (distinct from top-level `runs`)                           |
+| `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred              |
+
+When `docker` is omitted it inherits the `prod` driver. The rich object form adds connection detail:
+
+```typescript
+sql: {
+  prod: { driver: "postgres", pool: { max: 20 }, replicas: ["postgres://ro-1/db"] },
+},
+```
+
+| Field      | Type              | Meaning                                     |
+| ---------- | ----------------- | ------------------------------------------- |
+| `url`      | connection string | Overrides the env-var resolution            |
+| `pool`     | `{ max?, min? }`  | SQL pool sizing                             |
+| `replicas` | `string[]`        | Read-only routing targets (read flows only) |
+
+## images
+
+Container image pins keyed by element role — vendor choice lives here, never in driver ids:
+
+```typescript
+images: {
+  "store.sql": "postgres:18",
+  "store.kv": "redis:8",
+  "store.files": "rustfs/rustfs:1.0.0-beta.11",
+  "channel.email": "axllent/mailpit:v1.22.3",
+  vault: "openbao/openbao:2.6.1",
+},
+```
+
+## i18n
+
+| Option    | Type       | Default | Meaning                                     |
+| --------- | ---------- | ------- | ------------------------------------------- |
+| `locales` | `string[]` | —       | Supported locales                           |
+| `default` | string     | —       | Fallback locale (channel templates, `fx.t`) |
+| `dir`     | record     | —       | Per-locale direction: `"ltr"` \| `"rtl"`    |
+
+```typescript
+i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
+```
+
+## tenancy
+
+Multi-tenant isolation policy.
+
+| Option      | Type                              | Meaning                                  |
+| ----------- | --------------------------------- | ---------------------------------------- |
+| `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store   |
+| `resolve`   | string \| function                | Tenant resolver — reads `ctx.auth.orgId` |
+
+## privacy
+
+Presence of this block turns the CORE privacy tooling on in the Console — masking, classification surfaces. It is not a `.plug()` call.
+
+```typescript
+privacy: {},
+```
+
+## runs
+
+Runs retention and redaction at the config surface — **not** the same key as `drivers.runs`.
+
+| Option   | Type                     | Meaning                                               |
+| -------- | ------------------------ | ----------------------------------------------------- |
+| `redact` | `Record<string, string>` | Field → retention duration; presence turns privacy on |
+
+## db
+
+Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated to `oke schema generate`.
+
+| Option      | Default                     | Meaning                                                                     |
+| ----------- | --------------------------- | --------------------------------------------------------------------------- |
+| `autoPush`  | `true` (local only)         | Auto-run `db push` on schema change in `oke dev`; forced off in docker/prod |
+| `config`    | `"drizzle.config.ts"`       | Path to the drizzle-kit config                                              |
+| `declare`   | `"src/schema.decl.ts"`      | Abstract schema module (`store.schema.table` exports)                       |
+| `generated` | `"src/schema.generated.ts"` | Where `oke db` emits dialect Drizzle                                        |
+| `entry`     | `src/app.ts`                | App entry for collecting plugin table contributions                         |
+
+## topology
+
+| Value        | Meaning                                          |
+| ------------ | ------------------------------------------------ |
+| `"monolith"` | One process serves everything (default posture)  |
+| `"services"` | Split deployment units derived from the Manifest |
+
+## ports
+
+| Option    | Default | Surface |
+| --------- | ------- | ------- |
+| `app`     | `6530`  | App     |
+| `console` | `6533`  | Console |
+| `mcp`     | `6535`  | MCP     |
+
+## console
+
+Production Console exposure.
+
+| Option         | Type                                 | Default | Meaning                   |
+| -------------- | ------------------------------------ | ------- | ------------------------- |
+| `prod.enabled` | boolean                              | —       | Serve the Console in prod |
+| `prod.auth`    | `"required" \| "optional" \| "none"` | —       | Access requirement        |
+
+## Learn more
+
+- [CLI Reference](/docs/reference/cli) — `oke dev` · `oke db` · `oke docker`
+- [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
+- [Store](/docs/elements/store) — what the store drivers back

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

@@ -0,0 +1,87 @@
+---
+title: "Environment Variables"
+description: "Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags, grouped by what they configure."
+icon: "Terminal"
+---
+
+OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. In docker mode these are written for you into `docker/.env.docker`; this page is the full map.
+
+<Callout title="Precedence">
+  For anything with both an `OKE_*` variable and a conventional one (like `DATABASE_URL`), the
+  conventional variable wins first, then the `OKE_*` form, then the built-in default.
+</Callout>
+
+## SQL store
+
+| Variable            | Used for                                             | Default when unset              |
+| ------------------- | ---------------------------------------------------- | ------------------------------- |
+| `DATABASE_URL`      | Postgres connection (`postgres` driver, drizzle-kit) | `postgres://localhost:5432/oke` |
+| `OKE_STORE_SQL_URL` | Explicit SQL URL override                            | —                               |
+| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                   | `.oke/app.sqlite`               |
+| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                      | config map                      |
+
+## KV store
+
+| Variable           | Used for                 | Default when unset |
+| ------------------ | ------------------------ | ------------------ |
+| `REDIS_URL`        | Redis connection         | driver default     |
+| `OKE_STORE_KV_URL` | Explicit KV URL override | —                  |
+| `OKE_KV_DRIVER`    | Force the kv driver id   | config map         |
+
+## Files store
+
+| Variable               | Used for                         | Default when unset |
+| ---------------------- | -------------------------------- | ------------------ |
+| `S3_BUCKET`            | Bucket name (`s3` driver)        | —                  |
+| `S3_ENDPOINT`          | S3-compatible endpoint (RustFS)  | —                  |
+| `S3_ACCESS_KEY_ID`     | Access key                       | —                  |
+| `S3_SECRET_ACCESS_KEY` | Secret key                       | —                  |
+| `S3_REGION`            | Region                           | —                  |
+| `S3_SESSION_TOKEN`     | Session token (temporary creds)  | —                  |
+| `OKE_STORE_FILES_DB`   | Explicit files location override | —                  |
+| `OKE_FILES_DRIVER`     | Force the files driver id        | config map         |
+
+## Vault (OpenBao)
+
+Written by the first-boot bootstrap; you normally only set these when pointing at an external vault.
+
+| Variable          | Used for                    | Default when unset |
+| ----------------- | --------------------------- | ------------------ |
+| `OKE_VAULT_URL`   | OpenBao base URL            | —                  |
+| `OKE_VAULT_TOKEN` | App token (least-privilege) | —                  |
+| `OKE_VAULT_MOUNT` | KV v2 mount path            | `"secret"`         |
+
+## Channel (email)
+
+| Variable                | Used for                                  |
+| ----------------------- | ----------------------------------------- |
+| `SMTP_URL`              | Full SMTP connection string (`smtp://…`)  |
+| `SMTP_USER`             | Overrides the user embedded in `SMTP_URL` |
+| `SMTP_PASSWORD`         | Overrides the password in `SMTP_URL`      |
+| `OKE_CHANNEL_EMAIL_URL` | OKE-specific alternative to `SMTP_URL`    |
+
+## AI providers
+
+| Variable            | Used for                                |
+| ------------------- | --------------------------------------- |
+| `ANTHROPIC_API_KEY` | `anthropic` driver credential           |
+| `ANTHROPIC_MODEL`   | Model override for the anthropic driver |
+| `OPENAI_API_KEY`    | `openai-compatible` driver credential   |
+
+## Framework behavior
+
+| Variable              | Used for                                                      |
+| --------------------- | ------------------------------------------------------------- |
+| `OKE_DOCKER`          | `"1"` marks docker mode (set by the CLI, not by you)          |
+| `OKE_DB_AUTO_PUSH`    | Overrides `db.autoPush` at boot                               |
+| `OKE_DRIZZLE_DIALECT` | `"sqlite"` \| `"postgresql"` for generated drizzle config     |
+| `OKE_DEV_REQUEST_LOG` | `"1"` logs requests during `oke dev` (set by the CLI)         |
+| `OKE_CONSOLE_SECRET`  | Console session secret — set explicitly in production         |
+| `PORT`                | App port in production containers (default `6530`)            |
+| `NODE_ENV`            | `"production"` switches the Console to its production posture |
+
+## Learn more
+
+- [Configuration](/docs/reference/configuration) — the declarative side of the same knobs
+- [Vault](/docs/elements/vault) — how `OKE_VAULT_*` gets minted on first boot
+- [CLI Reference](/docs/reference/cli) — which commands write these for you

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

@@ -0,0 +1,80 @@
+---
+title: "Errors"
+description: "Every error OKE produces — permanent OKE codes with fixes, gate denials, and subsystem errors, with what to do about each."
+icon: "OctagonAlert"
+---
+
+OKE has two error families, and confusing them is the most common mistake: **failures are values** a flow returns (`{ data: null, error: { code, data } }` — clients switch on `error.code`), while **framework errors are thrown** for invariant violations and carry a permanent numeric code, a cause, and a fix.
+
+```text
+OKE1101  domain table not found — migrations have not been applied.
+         → run `oke db migrate` against this environment.
+         https://oke.omqkhafi.dev/e/1101
+```
+
+Codes are permanent once published — you can match on them safely across upgrades.
+
+## OKE numeric codes
+
+| Code   | Name              | Cause                                            | Fix                                             |
+| ------ | ----------------- | ------------------------------------------------ | ----------------------------------------------- |
+| `1001` | undeclared read   | Flow reads a resource not in `effects.reads`     | Add it to the flow's `effects.reads`            |
+| `1002` | undeclared write  | Flow writes a resource not in `effects.writes`   | Add it to the flow's `effects.writes`           |
+| `1003` | undeclared emit   | Flow emits a signal not in `effects.emits`       | Add it to the flow's `effects.emits`            |
+| `1004` | undeclared send   | Flow sends a template not in `effects.sends`     | Add it to the flow's `effects.sends`            |
+| `1005` | undeclared ask    | Flow asks a prompt not in `effects.asks`         | Add it to the flow's `effects.asks`             |
+| `1006` | undeclared secret | Flow reads a secret not in `effects.secrets`     | Add it to the flow's `effects.secrets`          |
+| `1007` | undeclared call   | Flow calls a flow not in `effects.calls`         | Add it to the flow's `effects.calls`            |
+| `1042` | orphan emit       | Emitted signal has no subscriber                 | Add `on(signal, …)` or declare `optional: true` |
+| `1101` | schema missing    | Domain table absent in docker/prod — no auto-DDL | Run `oke db migrate` against this environment   |
+
+<Callout title="Effects are usually inferred">
+  The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an
+  `effects` block — inference covers them — so seeing one of these means an explicit declaration
+  drifted from the code.
+</Callout>
+
+## Gate denials (typed failures)
+
+Returned, not thrown — the request never reached `do`:
+
+| Code           | When                                         | Payload          |
+| -------------- | -------------------------------------------- | ---------------- |
+| `Unauthorized` | Policy denied, request not authenticated     | —                |
+| `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` |
+| `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`   |
+
+## Framework validation failures
+
+| Code              | When                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `ValidationError` | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`) |
+| `NotFound`        | A `store.resource` get/update/remove hit a missing row                                     |
+
+## Subsystem errors
+
+Thrown by specific subsystems — each names its own cause:
+
+| Error                         | Thrown when                                                        | What to do                                              |
+| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
+| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap       |
+| `OpenBaoUnavailableError`     | Vault driver can't reach OpenBao, or it's sealed, in docker/prod   | Restore the vault or unseal it — never silently skipped |
+| `OpenBaoBootstrapError`       | First-boot init/unseal failed, or key material is missing/unsafe   | Read the message — it names the exact failing step      |
+| `AiPiiBuildError`             | Build: a flow sends PII fields to a third-party model              | Drop the fields or add `allowPii: true` — fields named  |
+| `AiSchemaValidationError`     | A model response failed the prompt's `out` schema                  | Fix the prompt or the schema — response didn't conform  |
+| `ScheduleNotOverridableError` | Console tried to edit a clock declared without `overridable: true` | Declare it overridable and redeploy                     |
+| `ClockResourceNotFoundError`  | Console action targeted an unknown clock name                      | Check the name against your `clock()` declarations      |
+| `DryRunWriteIsolationError`   | A write attempted inside a dry run                                 | Dry runs never write — use a real run                   |
+| `ManifestValidationError`     | The compiled Manifest failed schema validation                     | Re-run the build; the error names the offending entry   |
+| `CrossPlaneError`             | A user-plane token was used on the operator plane (or vice versa)  | Use the correct principal for the plane                 |
+| `AttenuationError`            | A token was used beyond its attenuated scope                       | Re-issue with the needed scope                          |
+| `SessionError`                | Session token invalid, expired, or malformed                       | Re-authenticate                                         |
+| `OperatorError`               | Operator-plane operation failed its checks                         | Error message names the failed check                    |
+| `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                    |
+| `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                               |
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — `fx.fail` and the response envelope
+- [Gate](/docs/elements/gate) — where the three denials come from
+- [CLI Reference](/docs/reference/cli) — `oke db migrate` and friends