okengine 0.18.4 → 0.19.0

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

@@ -0,0 +1,231 @@
+---
+title: "CLI"
+description: "oke and create-oke commands — scaffold, develop, ship, and operate an okengine app."
+icon: "Terminal"
+source: "docs/spec/unified-theory.md"
+---
+
+The CLI is how you scaffold, run, and operate an app. `create-oke` writes the project;
+`oke` is the day-to-day binary (dev loop, schema, vault, docker, doctor).
+
+For developers who already know the model — look up a command, its flags, and what it
+writes.
+
+<Callout title="The one rule">
+  Prefer the CLI for environment wiring (`oke dev`, `oke db`, `oke docker`). Put behavior in Flows
+  and `oke.config.ts` — never invent a ninth element or hand-edit the Manifest.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Scaffold an app
+
+```bash
+bunx create-oke@latest notes --yes
+cd notes
+```
+
+</Step>
+
+<Step>
+### Run the dev loop
+
+```bash
+oke dev
+```
+
+Compose comes up (pull / create / start progress streams into the boot status
+lines), the backend listens on **6530**, Console on **6533**, app MCP on **6535**,
+docs MCP on **6536**. Open `http://localhost:6533`. Quit with **Ctrl+C**.
+
+On a TTY, after schema push, `oke dev` also:
+
+1. Prompts one-by-one for any Vault boot gaps (writes `.env.local`) — e.g.
+   `OPENROUTER_API_KEY` when create-oke / `oke ai setup` / Keel declared the
+   OpenRouter contract without a value.
+2. Asks to run `oke db seed` when a seed module exists and `.oke/state.json` has
+   not recorded that seed identity yet. Run `oke db seed` anytime later.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Daily", "Schema", "Ship", "Scaffold"]}>
+
+<Tab value="Daily">
+
+```bash
+oke dev                 # watch · Console · client types · Docker Compose
+oke test                # bun test with PGLite posture
+oke doctor              # secrets · ports · schema drift
+oke doctor --diff       # CI gate: undeclared contract breaks
+```
+
+</Tab>
+
+<Tab value="Schema">
+
+```bash
+oke db push             # sync domain schema (dev; auto under oke dev)
+oke db generate         # versioned SQL under drizzle/
+oke db migrate          # apply migrations (prod)
+oke schema generate     # core + plugin stub → .oke/schema/oke.ts
+```
+
+**Consequence:** `oke schema generate` is not `oke db generate`. The first writes the
+framework stub; the second emits your app's Drizzle migrations.
+
+</Tab>
+
+<Tab value="Ship">
+
+```bash
+oke docker --prod       # derive production Compose
+oke build --target bun  # tree-shaken bundle
+oke start               # production entry (Docker CMD)
+```
+
+</Tab>
+
+<Tab value="Scaffold">
+
+```bash
+bunx create-oke@latest my-app --yes
+bunx create-oke@latest my-app -t advanced --locales ar --proxy caddy
+bunx create-oke@latest          # interactive (TTY only)
+```
+
+</Tab>
+
+</Tabs>
+
+## Port Map
+
+| Port     | Surface              | Who starts it           |
+| -------- | -------------------- | ----------------------- |
+| **6530** | Backend API          | `oke dev` / `oke start` |
+| **6533** | Developer Console    | `oke dev`               |
+| **6535** | App MCP              | `oke dev`               |
+| **6536** | Docs MCP (read-only) | `oke dev`               |
+
+Override app / console / mcp listen ports in `oke.config.ts` `ports` — see
+[Configuration](/docs/reference/configuration#ports).
+
+## `oke` Commands
+
+| Command      | Purpose                                                      | Key flags / subs                                                                                                                                          |
+| ------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dev`        | Watch · hot reload · Console · client types (Docker Compose) | `--docker\|-d [roles]`, `--no-db-push`, `--entry\|-e`                                                                                                     |
+| `test`       | Run bun test with PGLite test posture                        |                                                                                                                                                           |
+| `start`      | Production entry (Docker CMD)                                | `--entry\|-e`, `--port\|-p`                                                                                                                               |
+| `doctor`     | Secrets · ports · stub/domain schema drift                   | `--manifest`, `--diff`, `--before`, `--after`, `--base`, `--json`                                                                                         |
+| `stack`      | Preview images / tags / ports (writes nothing)               | `--config`, `--json`                                                                                                                                      |
+| `schema`     | Core + plugin tables → `.oke/schema/oke.ts`                  | `generate` (`--check`, `--manifest`, `--out`)                                                                                                             |
+| `db`         | Domain schema                                                | `push` · `generate` · `migrate` · `seed` · `studio` · `search-backfill`                                                                                   |
+| `client`     | Ambient types for a separate frontend repo                   | `add <url>` (`--out`)                                                                                                                                     |
+| `vault`      | Secrets                                                      | `set` · `list` · `import` · `key` · `init` · `status` · `seal` · `unseal` · `rotate` · `rotate-master` · `audit` · `purge-expired` · `backup` · `restore` |
+| `docker`     | Derive compose · clean leftover stacks                       | `--prod\|-p`, `--out`, `--config`, `--manifest`; sub `clean`                                                                                              |
+| `images`     | List / pin digests                                           | `list` · `pin`                                                                                                                                            |
+| `build`      | Tree-shaken bundle                                           | `--target\|-t bun\|node\|edge`, `--entry`, `--outdir`                                                                                                     |
+| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`                                                                                                                                              |
+| `ai`         | Configure AI driver + models                                 | `setup` (`--provider`, `--chat`, `--vision`, `--embed`, `--yes`)                                                                                          |
+| `branch`     | Fork journaled state                                         | `<name>`, `--at\|-a`                                                                                                                                      |
+| `replay`     | Re-invoke a past Flow from Runs                              | `--request-id\|-r`, `--entry`, `--dry-run`, `--live`                                                                                                      |
+| `privacy`    | Crypto-shred subject data                                    | `erase` (`--subject\|-s`)                                                                                                                                 |
+| `upgrade`    | Breaking-change codemods + diff                              | `--apply\|-a`                                                                                                                                             |
+| `console`    | Console helpers                                              | `claim-code` (`--json`)                                                                                                                                   |
+| `gates`      | Gate catalogue from Manifest                                 | `list` (`--manifest`, `--json`)                                                                                                                           |
+| `completion` | Shell completion script                                      | `bash` · `zsh` · `fish`                                                                                                                                   |
+| `mode`       | **Deprecated** — `oke dev` always uses Docker Compose        | `--help`                                                                                                                                                  |
+
+Bare `oke` (TTY) opens the interactive board; `oke --help` prints the catalogue.
+
+### `oke db` detail
+
+Shared flags on push / generate / migrate / studio: `--config\|-c`, `--env name`
+(`dev` · `test` · `prod`). Seed adds `--force`, `--entry`. Search-backfill adds
+`--batch n` and a `<table>` positional.
+
+```bash
+oke db push --env dev
+oke db migrate --env prod
+oke db seed --force
+oke db search-backfill notes --batch 500
+```
+
+## `create-oke`
+
+| Flag                             | Meaning                                                   |
+| -------------------------------- | --------------------------------------------------------- |
+| `-t, --template <id>`            | `standard` (default) or `advanced`                        |
+| `--sql <id>`                     | Store SQL dialect — only `postgres` (test stays `pglite`) |
+| `-y, --yes`                      | No prompts; defaults + bun install (no `oke dev`)         |
+| `--install` / `--no-install`     | Run or skip `bun install` after scaffold                  |
+| `--agents-md` / `--no-agents-md` | Write `AGENTS.md` (default on)                            |
+| `--ai` / `--no-ai` / `--ai skip` | Configure or skip AI setup                                |
+| `--locales <tags>`               | Extra languages beyond English (e.g. `ar` or `ar,fr`)     |
+| `--pgdog` / `--no-pgdog`         | Pin PgDog in front of Postgres                            |
+| `--proxy <id>` / `--no-proxy`    | `none` · `caddy` · `traefik` · `nginx`                    |
+| `-h, --help`                     | Show help                                                 |
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="oke start: no entry found">
+  Set `package.json` `okengine.entry` or `main`, pass `--entry`, or keep a conventional
+  `src/app.ts`. Production imports that module; the app must call `createBunRuntime().serve` itself.
+</Accordion>
+
+<Accordion title="Confusion: oke schema generate vs oke db generate">
+  `oke schema generate` emits framework / plugin stub tables under `.oke/schema/`. `oke db generate`
+  emits versioned domain SQL via Drizzle. Use `db` for your app tables; use `schema` when the stub
+  drifted after a plugin change.
+</Accordion>
+
+<Accordion title="oke mode still in muscle memory">
+  `oke mode` is deprecated. `oke dev` always starts Docker Compose. There is no soft-compat for old
+  `local` / `docker` env map keys — rename to `dev` / `test` / `prod` in
+  [Configuration](/docs/reference/configuration).
+</Accordion>
+
+<Accordion title="OKE1110 after deploy">
+  Domain tables are missing in prod (no auto-DDL). Run `oke db migrate` against that environment —
+  see [Errors](/docs/reference/errors).
+</Accordion>
+
+<Accordion title="Claim code missing for first Console operator">
+  The setup claim code prints on the `oke dev` TTY board and is mirrored to gitignored
+  `.oke/claim-code`. Run `oke console claim-code` while setup is open.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and ports
+- [Environment Variables](/docs/reference/environment-variables) — what Compose writes
+- [Security](/docs/reference/security) — Host / Origin / `allowedHosts`
+- [The Model](/docs/understand/the-model) — one contract; `oke doctor --diff` reviews it
+- [Vault](/docs/elements/vault) — `oke vault` rotate / unseal
+
+## Next
+
+<Cards>
+  <Card
+    title="Configuration"
+    description="Every option in oke.config.ts."
+    href="/docs/reference/configuration"
+  />
+  <Card
+    title="Security"
+    description="Host, Origin, planes, and MCP posture."
+    href="/docs/reference/security"
+  />
+  <Card title="Client" description="Typed createClient for your flows." href="/docs/client" />
+</Cards>

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

@@ -2,6 +2,7 @@
 title: "Configuration"
 description: "Every option in oke.config.ts — three environments (dev · test · prod), drivers, images, i18n, tenancy, privacy, db sync, topology, ports, and console."
 icon: "Settings2"
+source: "docs/spec/unified-theory.md"
 ---
 
 Complete reference for `oke.config.ts`. Options below match `defineConfig`. Driver maps use three keys: **dev** · **test** · **prod**.
@@ -14,9 +15,9 @@ export default defineConfig({
 });
 ```
 
-<Callout title="Philosophy">
-  We test on what we deploy. Local development runs the same stack as production via Docker. Tests
-  use PGLite for speed without sacrificing Postgres correctness.
+<Callout title="The one rule">
+  Pin drivers and images in `oke.config.ts` for `dev` · `test` · `prod`. We test on what we deploy:
+  Docker-first local stack, PGLite for tests, same protocol ids in production.
 </Callout>
 
 ## Environments
@@ -116,7 +117,7 @@ Built-in defaults (`DRIVER_DEFAULTS`) when a key is omitted:
 | `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                    |
 | `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                           |
 | `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                    |
-| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`     |
+| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex`                |
 | `runs`             | env driver map | `memory` · `files` (Parquet + DuckDB at `.oke/runs`) · `postgres` · `clickhouse` |
 | `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred                  |
 
@@ -150,11 +151,10 @@ images: {
   store: {
     sql: "postgres:18-alpine",
     kv: "redis:8-alpine",
-    files: "rustfs/rustfs:1.0.0-rc.2",
+    files: "rustfs/rustfs:1.0.0-rc.5",
   },
-  channel: { email: "axllent/mailpit:v1.30.7" },
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53",
-  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10450",
+  channel: { email: "axllent/mailpit:v1.31.1" },
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
   // proxy: "caddy:2-alpine",
 },
 ```
@@ -163,7 +163,10 @@ Omitted image keys mean no container for that role. When both `store.sql` and `p
 
 For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
 `{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
-For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
+
+Compose does not manage AI inference — [OpenRouter](/docs/recipes/openrouter) or BYO
+`OKE_AI_URL` ([Models](/docs/elements/ai/models)). For `proxy`, see [Caddy](/docs/recipes/caddy),
+[Traefik](/docs/recipes/traefik), or [nginx](/docs/recipes/nginx).
 
 ## i18n
 
@@ -267,6 +270,23 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 ## Learn more
 
-- [CLI Reference](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
+- [CLI](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
 - [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
 - [Store](/docs/elements/store) — what the store drivers back
+- [i18n](/docs/reference/i18n) — locale catalogs beyond the config block
+
+## Next
+
+<Cards>
+  <Card
+    title="Environment Variables"
+    description="URLs and secrets Compose writes."
+    href="/docs/reference/environment-variables"
+  />
+  <Card title="CLI" description="Commands that honor this config." href="/docs/reference/cli" />
+  <Card
+    title="Security"
+    description="Host, Origin, planes, and MCP ports."
+    href="/docs/reference/security"
+  />
+</Cards>

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

@@ -1,12 +1,51 @@
 ---
 title: "Environment Variables"
-description: "Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags, grouped by what they configure."
-icon: "Terminal"
+description: "Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags."
+icon: "Variable"
+source: "docs/spec/unified-theory.md"
 ---
 
-OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `.env.local`; this page is the full map.
+OKE reads environment variables at boot for connection detail and secrets — never for
+behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these
+into `.env.local`; this page is the full map.
 
-<Callout title="Precedence">
+<Callout title="The one rule">
+  Put drivers, images, and locale lists in `oke.config.ts`. Use env vars for URLs, credentials, and
+  runtime posture the host injects — not for inventing new behavior.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Let Compose write the map
+
+```bash
+oke dev
+```
+
+Compose fills `.env.local` with `DATABASE_URL`, Redis, S3, and vault keys for the
+pinned images.
+
+</Step>
+
+<Step>
+### Override one URL when needed
+
+```bash
+export DATABASE_URL=postgres://user:pass@db:5432/oke
+```
+
+Conventional names win over `OKE_*` aliases, then built-in defaults.
+
+</Step>
+
+</Steps>
+
+## Precedence
+
+<Callout title="Resolution order">
   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>
@@ -101,10 +140,11 @@ Read when `drivers.channel.sms` resolves to that driver id (`console` opens noth
 WhatsApp (`wa-cloud`) and push (`webpush` / `fcm`) are not opened from env at
 boot — pass them on `BootOptions.channel.drivers` with their open options.
 
-## Live test gates (opt-in)
+## Live test gates (opt-in, contributors)
 
-Provider-quota-burning live suites are double-gated: the medium flag **plus** that
-provider's real credentials — credentials alone never send.
+Provider-quota-burning live suites in the okengine repo are double-gated: the
+medium flag **plus** that provider's real credentials — credentials alone never
+send. App projects can ignore these.
 
 | Variable         | Used for                                                  |
 | ---------------- | --------------------------------------------------------- |
@@ -113,18 +153,17 @@ provider's real credentials — credentials alone never send.
 
 ## AI providers
 
-| Variable              | Used for                                                                                                | Default when unset                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                           | —                                                                          |
-| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                 | —                                                                          |
-| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                   | —                                                                          |
-| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                            | OpenAI cloud                                                               |
-| `OKE_AI_DRIVER`       | Force the AI driver id (honoured under Compose / `oke dev`)                                             | config map                                                                 |
-| `OKE_AI_URL`          | Local / openai-compatible base URL                                                                      | `http://127.0.0.1:8080/v1` (llama.cpp) · `http://127.0.0.1:11434` (ollama) |
-| `OKE_AI_MODEL`        | Default model id — Docker Hub `ai/` for llama.cpp; Ollama library tag for ollama; HF id for vLLM/SGLang | `granite3.3:2b` (llama.cpp) / `qwen3.5:9b` (ollama)                        |
-| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                | —                                                                          |
-| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                            | —                                                                          |
-| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                   | —                                                                          |
+| Variable              | Used for                                                                                | Default when unset |
+| --------------------- | --------------------------------------------------------------------------------------- | ------------------ |
+| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                           | —                  |
+| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                 | —                  |
+| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                   | —                  |
+| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                            | OpenAI cloud       |
+| `OKE_AI_DRIVER`       | Force the AI driver id (honoured under Compose / `oke dev`)                             | config map         |
+| `OKE_AI_URL`          | openai-compatible base URL (must end in `/v1`) — BYO; Compose does not manage inference | —                  |
+| `OKE_AI_MODEL`        | Default model id for openai-compatible / setup bindings                                 | —                  |
+| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                | —                  |
+| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                            | —                  |
 
 ## Framework behavior
 
@@ -145,8 +184,42 @@ Console operator rows are **not** stored in `.oke/console.sqlite`. With `DATABAS
 `OKE_STORE_SQL_URL`) they live in Postgres schema `oke_console`. Without a Postgres URL,
 Console uses PGlite under `.oke/console-pg` for local reopen durability.
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Compose did not write .env.local">
+  Run `oke dev` (not a bare `bun` entry) so Compose posture sets `OKE_DOCKER=1` and writes
+  connection URLs. Confirm `images` pins exist in [Configuration](/docs/reference/configuration).
+</Accordion>
+
+<Accordion title="Vault sealed / missing master key">
+  Built-in vault needs `OKE_VAULT_MASTER_KEY` (or `oke vault unseal`). See
+  [Vault](/docs/elements/vault).
+</Accordion>
+
+<Accordion title="Console operator store missing">
+  Operator rows need `DATABASE_URL` or `OKE_STORE_SQL_URL` (schema `oke_console`). Without Postgres,
+  Console uses PGlite under `.oke/console-pg`.
+</Accordion>
+
+</Accordions>
+
 ## 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
+- [CLI](/docs/reference/cli) — which commands write these for you
+- [Security](/docs/reference/security) — `OKE_CONSOLE_SECRET`
+
+## Next
+
+<Cards>
+  <Card
+    title="Configuration"
+    description="Drivers and images in oke.config.ts."
+    href="/docs/reference/configuration"
+  />
+  <Card title="CLI" description="oke dev writes the env map." href="/docs/reference/cli" />
+  <Card title="Vault" description="Master key and managed providers." href="/docs/elements/vault" />
+</Cards>