# Documentation

- [Documentation](/docs): One law. Eight elements. Ten exports.
- Get Started
  - [Get Started](/docs/get-started): From the one law to a running app — introduction, why OKE, install, and first flows.
  - [Introduction](/docs/get-started/introduction): Learn the one idea behind okengine — then the eight elements and ten exports you will use everywhere.
  - [Why OKE](/docs/get-started/why): The six seams every TypeScript backend maintains by hand — and what OKE derives from one Manifest instead.
  - [Installation](/docs/get-started/installation): Install okengine, scaffold an app with create-oke, and open the Console.
  - [Basic Usage](/docs/get-started/basic-usage): Scaffold the standard Notes starter, call health and notes Flows, and inspect them in the Console.
- Elements
  - [Elements](/docs/elements): The eight irreducible parts of an OKE backend — Flow through AI, one page each.
  - [Flow](/docs/elements/flow): Behavior — endpoints, jobs, consumers, and workflows as one species: a typed trigger, declared contracts, and a do that touches the world only through fx.
  - [Signal](/docs/elements/signal): Data in motion — queues, pub/sub, and streams as one declaration whose delivery physics you choose explicitly.
  - [Store](/docs/elements/store): Data at rest behind one handle and four independent facets — sql · kv · files · index — swapped per environment by driver.
  - [Clock](/docs/elements/clock): Time — recurring schedules, intervals, and durable sleeps as first-class declarations, not a bolted-on cron library.
  - [Gate](/docs/elements/gate): Permission to act — policies, rate limits, and built-in auth on the HTTP trigger, evaluated before any effect runs.
  - [Vault](/docs/elements/vault): Secrets, API keys, and config — declared once as typed contracts, resolved from a real vault in production, never leaked into logs.
  - [Channel](/docs/elements/channel): Reaching humans — email, SMS, WhatsApp, and push with consent, locale, receipts, and fallback chains built in.
  - [AI](/docs/elements/ai): Reaching machine intelligence — models, versioned prompts, embeddings, and bounded agents, with cost and PII egress as first-class constraints.
- Plugins
  - [Plugins](/docs/plugins): Official okengine/plugins extensions — authentication, security, operations, and performance.

  - **Authentication**
  - [Username](/docs/plugins/username): Official plugin — username + password sign-up and sign-in under /auth, plugged onto gate.auth.
  - [Anonymous](/docs/plugins/anonymous): Official plugin — issue a user-plane session with a random id and no password.
  - [Magic link](/docs/plugins/magic-link): Official plugin — request and verify a one-time email link to sign in under /auth.
  - [OTP](/docs/plugins/otp): Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit provider or app mode.
  - [Two-factor](/docs/plugins/two-factor): Official plugin — TOTP enable, verify, and disable for an authenticated session.
  - [Passkey](/docs/plugins/passkey): Official plugin — WebAuthn register and authenticate under /auth with signature and origin checks.

  - **Security**
  - [Headers](/docs/plugins/headers): 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.
  - [CORS](/docs/plugins/cors): Official plugin — cross-origin rules at the edge: preflight OPTIONS answered even for paths bound to other methods, plus CORS headers on matched responses. Closed by default.
  - [CSRF](/docs/plugins/csrf): Official plugin — cross-site request forgery defense using fetch metadata (Sec-Fetch-Site) with an Origin fallback. Stateless: no tokens, no cookies, no session reads.
  - [IP Allowlist](/docs/plugins/ip-allowlist): Official plugin — allow/deny rules by client IP at the edge of the pipeline, with the same typed Forbidden denial the gate element produces.

  - **Operations**
  - [Maintenance Mode](/docs/plugins/maintenance-mode): Official plugin — drain HTTP traffic with one flag: every flow returns a 503 ServiceUnavailable envelope with an optional Retry-After, while allow-listed paths and an operator bypass header stay alive.

  - **Performance**
  - [Compression](/docs/plugins/compression): Official plugin — gzip response bodies for clients that send Accept-Encoding: gzip, with a size threshold and content-type matcher. Bun.serve does not compress on its own.
- Console
  - [Console](/docs/console): Manifest-derived operator panels on :6533 — health, elements, traces, access, and more.
  - [Overview](/docs/console/overview): Is the system healthy right now?
  - [Flows](/docs/console/flows): What exists; call it; read its contract.
  - [Signals](/docs/console/signals): Queue depth, in-flight, DLQ, live monitors, orphaned config.
  - [Store](/docs/console/store): Browse sql/kv/files/index; cache keys; replica lag.
  - [Clock](/docs/console/clock): Upcoming crons, sleeping durable flows, journal.
  - [Gates](/docs/console/gates): Permission inquiry, rate counters, and continuous audit of unguarded vs explicitly public flows.
  - [Vault](/docs/console/vault): Secret contracts, who can read each, rotation due.
  - [Channels](/docs/console/channels): Templates, delivery receipts, bounces, opt-outs.
  - [AI](/docs/console/ai): Prompt versions, eval scores, cost, agent runs.
  - [Architecture](/docs/console/architecture): How it all connects — the diagram that is the code.
  - [Traces](/docs/console/traces): One timeline across http → store → signal → durable steps.
  - [Runs](/docs/console/runs): Wide events — one record per flow execution.
  - [Manifest Diff](/docs/console/manifest-diff): Blast radius of a deploy: new effects, widened permissions.
  - [Access](/docs/console/access): Identities, roles, API keys.
  - [Plugins](/docs/console/plugins): Installed plugins and their contributed panels.
  - [Privacy](/docs/console/privacy): Where PII lives, who touches it, export/erase (conditional).
  - [Tenancy](/docs/console/tenancy): Per-tenant usage, limits, isolation checks (conditional).
- Deployment
  - [Deployment](/docs/deployment): Choose plain docker compose, Docker Swarm, or Kubernetes — then follow that path's complete page for PgDog, probes, graceful shutdown, and TLS.
  - [Docker](/docs/deployment/docker): Deploy with plain docker compose — shared drivers, PgDog, readiness, graceful SIGTERM, and opt-in Caddy or Traefik when you need TLS without an orchestrator.
  - [Docker Swarm](/docs/deployment/docker-swarm): Deploy the generated compose stack with docker stack deploy — PgDog, HEALTHCHECK readiness, graceful SIGTERM, known multi-instance limits, and optional Caddy or Traefik.
  - [Kubernetes](/docs/deployment/kubernetes): Run an OKE app as a plain Deployment — PgDog, readiness vs liveness probes, graceful SIGTERM, shared drivers, and honest multi-instance limits.
  - [Reverse proxy](/docs/deployment/reverse-proxy): Opt-in Caddy or Traefik for TLS termination and routing on plain Docker and Swarm — custom domains, Let's Encrypt, and the socket-proxy security model.
- Reference
  - [Reference](/docs/reference): Lookup pages — config, fx, i18n, client, env vars, errors, plugins API, CLI, and Console security.
  - [Configuration](/docs/reference/configuration): Every option in oke.config.ts — drivers per environment, images, i18n, tenancy, privacy, db sync, topology, ports, and console.
  - [fx](/docs/reference/fx): The complete fx surface — every call a flow can make, its signature, and the effect it records.
  - [i18n](/docs/reference/i18n): ICU message catalogs for fx.t, typed keys, request locale, and how failures and channels pick a language.
  - [Client](/docs/reference/client): Typed caller for your flows — createClient from okengine/client, zero codegen, errors as values.
  - [Environment Variables](/docs/reference/environment-variables): Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags, grouped by what they configure.
  - [Errors](/docs/reference/errors): Every error OKE produces — permanent OKE codes with fixes, gate denials, and subsystem errors, with what to do about each.
  - [Plugins](/docs/reference/plugins): The plugin API reference — what a plugin may contribute, hook stages, whole-table schema contributions, and identity rules. First-party plugins live in the Plugins section.
  - [CLI Reference](/docs/reference/cli): oke and create-oke — everyday commands and flags.
  - [Security](/docs/reference/security): Console security posture — DNS rebinding, XSS, MCP.
- AI Resources
  - [AI Resources](/docs/ai): Machine-facing surfaces — MCP on :6535/:6536, agent skills, and /llms.txt.
  - [MCP](/docs/ai/mcp): The runtime MCP server on :6535 — read tools for Manifest, schemas, effects, and traces, write actions gated by per-call human confirmation — plus the read-only docs MCP on :6536.
  - [Skills](/docs/ai/skills): What OKE ships to teach AI agents the system — the repo-level AGENTS.md contract and the installable skills under .agents/skills/.
  - [llms.txt](/docs/ai/llms-txt): Machine-readable documentation — the index, the full concatenated text, and per-page markdown endpoints this site serves for agents.