okengine 0.11.2 → 0.12.0

package/manifest.v1.schema.json

@@ -189,7 +189,7 @@
       "properties": {
         "method": {
           "type": "string",
-          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]
         },
         "path": { "type": "string", "minLength": 1 }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,7 @@
   },
   "workspaces": [
     "packages/*",
+    "examples/*",
     "site"
   ],
   "files": [
@@ -88,7 +89,7 @@
     "./drivers/*": "./src/drivers/*"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && bun run --cwd packages/create-oke typecheck",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/console/tsconfig.ui-next.json && tsc --noEmit -p src/console/ui-next && bun run --cwd packages/create-oke typecheck && bun run --cwd examples/keel typecheck",
     "lint": "oxlint --quiet",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",
@@ -97,7 +98,18 @@
     "test": "bun test --pass-with-no-tests",
     "test:coverage": "bun test --coverage --pass-with-no-tests",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
-    "build": "bunx vite build --config src/console/ui/vite.config.ts",
+    "test:console:setup": "bunx playwright test --config playwright.ui-next.config.ts",
+    "test:console:setup:report": "bunx playwright show-report playwright-report/ui-next",
+    "build": "bunx --bun vite build --config src/console/ui-next/vite.config.ts",
+    "dev:console": "bunx --bun vite --config src/console/ui-next/vite.config.ts",
+    "dev:console:seed": "OKE_CONSOLE_SEEDED=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
+    "dev:console:fresh": "OKE_CONSOLE_FRESH=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
+    "dev:console:fresh:seed": "OKE_CONSOLE_FRESH=1 OKE_CONSOLE_SEEDED=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
+    "dev:keel": "bun run --cwd examples/keel dev",
+    "dev:keel:seed": "bun run --cwd examples/keel seed",
+    "dev:keel:reset": "bun run --cwd examples/keel reset",
+    "test:keel": "bun run --cwd examples/keel test",
+    "test:keel:docker": "OKE_TEST_DOCKER=1 bun run --cwd examples/keel test",
     "build:lib": "bun src/release/build-lib.ts",
     "prepack": "bun run build && bun run build:lib",
     "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",
@@ -112,6 +124,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@tanstack/react-virtual": "^3.14.9",
     "intl-messageformat": "^11.2.13",
     "sently": "1.2.1"
   },
@@ -122,31 +135,55 @@
     "@codemirror/state": "^6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.43.7",
+    "@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",
+    "@number-flow/react": "^0.6.2",
     "@oxc-project/types": "^0.142.0",
     "@playwright/test": "^1.62.1",
     "@sinclair/typebox": "^0.34.52",
     "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-form": "^1.28.0",
+    "@tanstack/react-hotkeys": "^0.10.0",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-router": "^1.170.18",
+    "@tanstack/react-table": "^8.21.3",
     "@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",
+    "@visx/curve": "4.0.1-alpha.0",
+    "@visx/event": "4.0.1-alpha.0",
+    "@visx/gradient": "4.0.1-alpha.0",
+    "@visx/grid": "4.0.1-alpha.0",
+    "@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",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "arktype": "^2.2.3",
     "axe-core": "^4.12.1",
+    "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",
     "drizzle-kit": "1.0.0-rc.4",
     "drizzle-orm": "1.0.0-rc.4",
     "drizzle-seed": "^0.3.1",
     "drizzle-zod": "^0.8.3",
     "gflows": "^1.2.1",
     "happy-dom": "^20.11.1",
+    "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",
@@ -154,7 +191,12 @@
     "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",
     "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
     "typescript": "^7.0.2",
     "valibot": "^1.4.2",
     "vite": "^8.2.0",
@@ -163,9 +205,12 @@
   "peerDependencies": {
     "@aws-sdk/client-kms": ">=3.0.0",
     "@aws-sdk/client-secrets-manager": ">=3.0.0",
+    "@azure/identity": ">=4.0.0",
+    "@azure/keyvault-secrets": ">=4.0.0",
     "@duckdb/node-api": ">=1.5.0",
     "@electric-sql/pglite": ">=0.5.0",
     "@electric-sql/pglite-pgvector": ">=0.0.5",
+    "@google-cloud/secret-manager": ">=5.0.0",
     "ajv": ">=8.0.0",
     "ajv-formats": ">=3.0.0",
     "drizzle-kit": ">=1.0.0-rc.0",
@@ -181,6 +226,15 @@
     "@aws-sdk/client-secrets-manager": {
       "optional": true
     },
+    "@azure/identity": {
+      "optional": true
+    },
+    "@azure/keyvault-secrets": {
+      "optional": true
+    },
+    "@google-cloud/secret-manager": {
+      "optional": true
+    },
     "@duckdb/node-api": {
       "optional": true
     },

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

@@ -1,6 +1,6 @@
 ---
 title: "AI Resources"
-description: "Machine-facing surfaces — MCP on :6535/:6536, agent skills, and /llms.txt."
+description: "Machine-facing surfaces — MCP on :6535/:6536, agent skills, /llms.txt, /llms.json, and /llms/agents."
 icon: "Bot"
 source: "docs/spec/unified-theory.md"
 ---
@@ -18,7 +18,7 @@ Resources for AI agents that read or operate an OKE app — not the `ai` element
   />
   <Card
     title="llms.txt"
-    description="Machine-readable docs index and pages."
+    description="Index, JSON catalogue, full dump, per-page markdown."
     href="/docs/ai/llms-txt"
   />
 </Cards>

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

@@ -1,38 +1,43 @@
 ---
 title: "llms.txt"
-description: "Machine-readable documentation — the index, the full concatenated text, and per-page markdown endpoints this site serves for agents."
+description: "Machine-readable documentation — the index, the JSON catalogue, the full dump, per-page markdown, and the agent contract this site serves."
 icon: "FileText"
 source: "docs/spec/unified-theory.md"
 ---
 
-This documentation site serves machine-readable twins of every page, following the `llms.txt` convention — so an agent can pull exactly the docs it needs (or all of them) instead of scraping HTML. Three endpoints, three granularities:
+This documentation site serves machine-readable twins of every page, following the `llms.txt` convention — so an agent can pull exactly the docs it needs (or all of them) instead of scraping HTML.
 
-| Endpoint                | Contains                                            | Pull it when                                  |
-| ----------------------- | --------------------------------------------------- | --------------------------------------------- |
-| `/llms.txt`             | Index of every docs page (title, link, description) | The agent needs the map — what exists, where  |
-| `/llms-full.txt`        | All pages concatenated as one markdown document     | You want the whole docs in one context window |
-| `/llms.mdx/docs/⟨slug⟩` | One page as markdown                                | The agent needs just the Vault page, say      |
+| Endpoint                   | Contains                                                | Pull it when            |
+| -------------------------- | ------------------------------------------------------- | ----------------------- |
+| `/llms.txt`                | Spec map — H1, summary, curated links, Optional rest    | The agent needs the map |
+| `/llms.json`               | Same catalogue as JSON (`slug`, `html`, `markdown`)     | Structured clients      |
+| `/llms-full.txt`           | All pages concatenated; teaching figures as blockquotes | Whole-docs context      |
+| `/llms.mdx/docs/⟨slug⟩.md` | One page as source markdown                             | One page — e.g. Vault   |
+| `/llms/agents`             | The `AGENTS.md` contract                                | Session bootstrap       |
+| `/robots.txt`              | Allow-all, including named AI crawlers                  | Crawler policy          |
+| `/sitemap.xml`             | HTML pages plus the machine endpoints                   | Crawler map             |
 
 ## Use them
 
 ```bash
-# the map
 curl https://oke.omqkhafi.dev/llms.txt
-
-# everything, for stuffing into context
+curl https://oke.omqkhafi.dev/llms.json
 curl https://oke.omqkhafi.dev/llms-full.txt
-
-# one page — e.g. the Vault element
-curl https://oke.omqkhafi.dev/llms.mdx/docs/elements/vault
+curl https://oke.omqkhafi.dev/llms.mdx/docs/elements/vault.md
+curl https://oke.omqkhafi.dev/llms/agents
 ```
 
 <Callout title="Which one first?">
-  Start with `/llms.txt` — it is small and tells the agent which slugs exist. Fetch `/llms-full.txt`
-  only when breadth matters more than tokens; per-page `/llms.mdx` is the precise instrument.
+  Start with `/llms.txt`. Fetch `/llms-full.txt` only when breadth matters more than tokens.
+  Per-page `/llms.mdx` is the precise instrument. `/llms.mdx/docs/⟨slug⟩/content.md` still works.
 </Callout>
 
 The homepage **Onboard AI** button copies a one-line prompt that points an agent at
-`/llms.txt` plus the repo-root `AGENTS.md` — project-wide context, not a single docs page.
+`/llms.txt` plus `/llms/agents` on this origin — project-wide context, not a single docs page.
+
+HTML docs pages advertise `rel="alternate"` `type="text/markdown"` to the twin. Crawlers
+that honor `robots.txt` are allowed; `/sitemap.xml` lists the handbook and the machine
+entry points.
 
 ## How it pairs with the docs MCP
 

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

@@ -111,7 +111,7 @@ The docs content ships inside the `okengine` package, so the index your agent se
   />
   <Card
     title="llms.txt"
-    description="Machine-readable documentation surfaces."
+    description="llms.txt, llms.json, per-page markdown, /llms/agents."
     href="/docs/ai/llms-txt"
   />
   <Card

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

@@ -9,13 +9,14 @@ Tools alone don't make a good operator — an agent also needs to know the _voca
 
 ## The layers
 
-| Layer              | Path                       | Loaded when                                       | Teaches                                                               |
-| ------------------ | -------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
-| **Agent contract** | `AGENTS.md` (repo root)    | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
-| **Element skill**  | `.agents/skills/oke/`      | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
-| **Docs skill**     | `.agents/skills/oke-docs/` | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
-| **Ship skill**     | `.agents/skills/oke-ship/` | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
-| **Deps skill**     | `.agents/skills/oke-deps/` | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)       |
+| Layer              | Path                         | Loaded when                                       | Teaches                                                               |
+| ------------------ | ---------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
+| **Agent contract** | `AGENTS.md` (repo root)      | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
+| **Element skill**  | `.agents/skills/oke/`        | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
+| **Docs skill**     | `.agents/skills/oke-docs/`   | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
+| **Ship skill**     | `.agents/skills/oke-ship/`   | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
+| **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   |
 
 ## AGENTS.md — the root contract
 
@@ -25,12 +26,13 @@ Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, an
 
 Skills are `SKILL.md` packages an agent loads when the work matches their description. OKE ships:
 
-| Skill      | Use it for                                   | Inside                                                                    |
-| ---------- | -------------------------------------------- | ------------------------------------------------------------------------- |
-| `oke`      | App work — flows, elements, drivers          | The agent contract, element patterns, the fx invariants                   |
-| `oke-docs` | Docs work — new pages, rewrites              | The page skeleton, verification sources, the density gate                 |
-| `oke-ship` | Closing an implementation — changelog + docs | Append under `## Unreleased`; `bun run bump` promotes it into `## vX.Y.Z` |
-| `oke-deps` | Dependency updates — one package or all      | Scope map, `ncu` + Bun, reject downgrades / protect RC and aliases        |
+| Skill        | Use it for                                   | Inside                                                                    |
+| ------------ | -------------------------------------------- | ------------------------------------------------------------------------- |
+| `oke`        | App work — flows, elements, drivers          | The agent contract, element patterns, the fx invariants                   |
+| `oke-docs`   | Docs work — new pages, rewrites              | The page skeleton, verification sources, the density gate                 |
+| `oke-ship`   | Closing an implementation — changelog + docs | Append under `## Unreleased`; `bun run bump` promotes it into `## vX.Y.Z` |
+| `oke-deps`   | Dependency updates — one package or all      | Scope map, `ncu` + Bun, reject downgrades / protect RC and aliases        |
+| `oke-images` | Compose image pins — one image or all        | Registry probe, keep pin style, never `:latest`, sync catalog → docs      |
 
 All live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe.
 
@@ -42,7 +44,7 @@ Contracts teach the _vocabulary_; [MCP](/docs/ai/mcp) grants the _hands_. An age
 
 - [MCP](/docs/ai/mcp) — the runtime surface these contracts pair with
 - [Introduction](/docs/get-started/introduction) — the eight elements in human terms
-- [llms.txt](/docs/ai/llms-txt) — feeding an agent the docs themselves
+- [llms.txt](/docs/ai/llms-txt) — `/llms.txt`, `/llms.json`, `/llms/agents`, per-page markdown
 
 ## Next
 

package/site/content/docs/deployment/docker-swarm.mdx

@@ -1,6 +1,6 @@
 ---
 title: Docker Swarm
-description: Deploy with docker stack deploy — docker-stack.yml, PgDog, HEALTHCHECK readiness, graceful SIGTERM, known multi-instance limits, and optional Caddy or Traefik.
+description: Deploy with docker stack deploy — docker-stack.yml, PgDog, HEALTHCHECK readiness, graceful SIGTERM, known multi-instance limits, and optional Caddy, Traefik, or nginx.
 icon: Ship
 source: README.md
 ---
@@ -48,7 +48,7 @@ docker stack deploy -c docker-stack.yml myapp
 ```
 
 Create `secrets:` names via `docker secret create` when you use secret refs,
-or keep credentials in `.env.docker` for single-node labs.
+or keep credentials in `.env.local` for single-node labs.
 
 </Step>
 
@@ -83,10 +83,9 @@ Pin `dev`/`prod` drivers to shared stores:
 Bun.SQL defaults to **10** connections per process — fine for one replica.
 Scale the Swarm service and `N × pool` can exceed Postgres `max_connections`.
 
-When both `store.sql` and `pgdog` are pinned (`dev`/`prod` default in templates),
-`DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
-transparent to Bun.SQL / Drizzle. No app code changes. Configs:
-`docker/pgdog/pgdog.toml` + `docker/pgdog/users.toml`.
+When both `store.sql` and `pgdog` are pinned (`dev`/`prod` template default),
+`DATABASE_URL` points at PgDog `:6432` — transaction pooling, wire-transparent.
+Configs: `docker/pgdog/pgdog.toml` + `docker/pgdog/users.toml`.
 
 **Why PgDog.** Transaction pooling fixes the connection math. Naive poolers can
 leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients; PgDog
@@ -116,7 +115,7 @@ visibility TTL on survivors.
 
 ## Reverse proxy
 
-Same opt-in `images.proxy` pins as plain Compose — Caddy or Traefik. Re-run
+Same opt-in `images.proxy` pins as plain Compose — Caddy, Traefik, or nginx. Re-run
 `oke docker --stack` after pinning. Details:
 [Reverse proxy](/docs/deployment/reverse-proxy).
 
@@ -152,7 +151,7 @@ volumes for durable state across nodes.
 ## Learn more
 
 - [Docker](/docs/deployment/docker) — plain compose default
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx
 - [Kubernetes](/docs/deployment/kubernetes) — Deployment, probes, Ingress
 - [CLI](/docs/reference/cli) — `oke docker --stack`
 

package/site/content/docs/deployment/docker.mdx

@@ -1,6 +1,6 @@
 ---
 title: Docker
-description: Deploy with plain docker compose — single production-grade docker-compose.yml, shared drivers, PgDog, readiness, graceful SIGTERM, and opt-in Caddy or Traefik when you need TLS without an orchestrator.
+description: Deploy with plain docker compose — single production-grade docker-compose.yml, shared drivers, PgDog, readiness, graceful SIGTERM, and opt-in Caddy, Traefik, or nginx when you need an edge without an orchestrator.
 icon: Package
 source: README.md
 ---
@@ -55,6 +55,12 @@ same protocols locally via `oke dev` and in production):
 | Files                         | `s3`                         | S3-compatible object store                     |
 | Signal                        | see known limits below       | —                                              |
 
+<Callout>
+  The monorepo `examples/keel` app is the work-management Compose fixture — `bun run dev:keel`, then
+  `oke db seed` (Harbor GA story + ~500 tasks). Wipe with `bun run dev:keel:reset` (stops leftover
+  ports, fresh `.env.local`).
+</Callout>
+
 </Step>
 
 <Step>
@@ -77,10 +83,9 @@ that file). With `--split`, pass every `-f` file `oke docker` prints.
 Bun.SQL defaults to **10** connections per process — fine for one instance.
 Scale out and `N × pool` can exceed Postgres `max_connections`.
 
-When both `store.sql` and `pgdog` are pinned (dev/prod default in templates),
-`DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
-transparent to Bun.SQL / Drizzle. No app code changes. Configs land in
-`docker/pgdog/pgdog.toml` and `docker/pgdog/users.toml`.
+When both `store.sql` and `pgdog` are pinned (templates' `dev`/`prod` default),
+`DATABASE_URL` points at PgDog `:6432` — transaction pooling, wire-transparent.
+Configs: `docker/pgdog/pgdog.toml` + `docker/pgdog/users.toml`.
 
 **Why PgDog.** Transaction pooling fixes the connection math. Naive poolers can
 leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients; PgDog
@@ -127,19 +132,22 @@ so the release path can finish (≥ typical Clock / Journal / Signal lease TTL).
 Omit `images.proxy` until you need HTTPS or horizontal scale without fighting a
 host port bind. Then pick one:
 
-| Choice                       | Best for                                  | How routing works                                                  |
-| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
-| **Caddy** (`caddy:2-alpine`) | Single instance, simplest automatic HTTPS | Generated `Caddyfile` → `reverse_proxy app:6530`                   |
-| **Traefik** (`traefik:v3.3`) | `docker compose up --scale app=N`         | Docker labels on `app`; replicas auto-discovered and load-balanced |
+| Choice                          | Best for                                  | How routing works                                                  |
+| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| **Caddy** (`caddy:2-alpine`)    | Single instance, simplest automatic HTTPS | Generated `Caddyfile` → `reverse_proxy app:6530`                   |
+| **Traefik** (`traefik:v3.7`)    | `docker compose up --scale app=N`         | Docker labels on `app`; replicas auto-discovered and load-balanced |
+| **nginx** (`nginx:1.31-alpine`) | Static HTTP edge; TLS elsewhere           | Generated `nginx.conf` → `proxy_pass` to `app:6530` on `:80`       |
 
 ```typescript title="oke.config.ts"
 images: {
   // …
-  proxy: "caddy:2-alpine", // or "traefik:v3.3"
+  proxy: "caddy:2-alpine", // or "traefik:v3.7" / "nginx:1.31-alpine"
 },
 ```
 
-```bash title="docker/.env.docker"
+`create-oke` asks **Add a reverse proxy…?** (or `--proxy caddy|traefik|nginx|none`).
+
+```bash title=".env.local"
 OKE_PROXY_HOST=app.example.com
 OKE_PROXY_ACME_EMAIL=admin@example.com
 ```
@@ -203,7 +211,7 @@ Serve validates `Host`. Add your public hostname to `allowedHosts`
 ## Learn more
 
 - [Deployment](/docs/deployment) — choose compose, Swarm, or Kubernetes
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik in full
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx in full
 - [Docker Swarm](/docs/deployment/docker-swarm) — `docker stack deploy`
 - [Kubernetes](/docs/deployment/kubernetes) — Deployment, probes, Ingress
 - [CLI](/docs/reference/cli) — `oke docker`, layouts, budget flags

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

@@ -36,7 +36,7 @@ These already ship. Each path page explains them in full in that page's words:
 | **Graceful SIGTERM**              | `installGracefulShutdown` releases Clock + Journal leases, then drains                  | Path pages                                       |
 | **Readiness vs liveness**         | `GET /_/ready` (kernel) vs app `GET /health`                                            | Path pages                                       |
 | **Horizontal proof**              | Two-process integration test against live Postgres + Redis                              | Changelog / CI (`OKE_TEST_POSTGRES_URL` + Redis) |
-| **Reverse proxy (compose/Swarm)** | Opt-in Caddy or Traefik (`images.proxy`)                                                | [Reverse proxy](/docs/deployment/reverse-proxy)  |
+| **Reverse proxy (compose/Swarm)** | Opt-in Caddy, Traefik, or nginx (`images.proxy`)                                        | [Reverse proxy](/docs/deployment/reverse-proxy)  |
 | **Ingress (Kubernetes)**          | Cluster-native Ingress / Gateway API                                                    | [Kubernetes](/docs/deployment/kubernetes)        |
 
 Honesty notes (Signal consume / Channel suppression still process-local) live
@@ -62,7 +62,7 @@ on each path page — not papered over here.
   />
   <Card
     title="Reverse proxy"
-    description="Caddy vs Traefik — TLS, domains, socket-proxy why."
+    description="Caddy / Traefik / nginx — TLS, domains, socket-proxy why."
     href="/docs/deployment/reverse-proxy"
   />
 </Cards>

package/site/content/docs/deployment/kubernetes.mdx

@@ -103,7 +103,7 @@ longest lease TTL (typically ≥ 30s) so release finishes before kubelet SIGKILL
 ## Ingress (TLS / routing)
 
 Use cluster-native **Ingress** or Gateway API for HTTPS.
-Compose `images.proxy` recipes (Caddy / Traefik) target plain Docker and Swarm —
+Compose `images.proxy` recipes (Caddy / Traefik / nginx) target plain Docker and Swarm —
 see [Reverse proxy](/docs/deployment/reverse-proxy) when you are not on Kubernetes.
 
 Still set serve `allowedHosts` to the public hostname
@@ -159,7 +159,7 @@ on `/_/ready` so the pod stays Alive while Waiting for Ready.
 - [Deployment](/docs/deployment) — choose compose, Swarm, or Kubernetes
 - [Docker](/docs/deployment/docker) — plain compose
 - [Docker Swarm](/docs/deployment/docker-swarm) — `docker stack deploy`
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik (non-K8s)
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx (non-K8s)
 - [Store](/docs/elements/store) — PgDog and facets
 - [Clock](/docs/elements/clock) — shared CronStore / leader election
 - [Flow](/docs/elements/flow) — durable journal

package/site/content/docs/deployment/reverse-proxy.mdx

@@ -1,18 +1,18 @@
 ---
 title: Reverse proxy
-description: 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.
+description: Opt-in Caddy, Traefik, or nginx for edge routing on plain Docker and Swarm — custom domains, Let's Encrypt, and the socket-proxy security model.
 icon: Globe
 source: README.md
 ---
 
-Pin `images.proxy` when you need HTTPS at the edge on plain `docker compose` or
+Pin `images.proxy` when you need an edge in front of the app on plain `docker compose` or
 Docker Swarm. Kubernetes uses cluster Ingress / Gateway API instead — this page
 is for the compose recipes.
 
 <Callout title="The one rule">
-  Leave the no-proxy default until you need TLS or horizontal scale on compose. Then pick **Caddy**
-  (simplest automatic HTTPS) or **Traefik** (label auto-discovery for `--scale app=N`). Never mount
-  the raw Docker socket into Traefik.
+  Leave the no-proxy default until you need an edge on compose. Then pick **Caddy** (automatic
+  HTTPS), **Traefik** (`--scale app=N`), or **nginx** (HTTP; TLS elsewhere). Never mount raw
+  `docker.sock` into Traefik.
 </Callout>
 
 ## Quick start
@@ -26,23 +26,24 @@ is for the compose recipes.
 images: {
   "store.sql": "postgres:18-alpine",
   // …
-  proxy: "caddy:2-alpine", // or "traefik:v3.3"
+  proxy: "caddy:2-alpine", // or "traefik:v3.7" / "nginx:1.31-alpine"
 },
 ```
 
-Pin **either** Caddy or Traefik — never both. Re-run `oke docker --prod`.
+Pin **one** proxy image — never two. `create-oke` asks **Add a reverse proxy…?** (or
+`--proxy`). Re-run `oke docker --prod`.
 
 </Step>
 
 <Step>
 ### Set the public host and ACME email
 
-```bash title="docker/.env.docker"
+```bash title=".env.local"
 OKE_PROXY_HOST=app.example.com
 OKE_PROXY_ACME_EMAIL=admin@example.com
 ```
 
-`.env.docker` is preserved across regeneration. Point DNS `A`/`AAAA` at the host.
+`.env.local` is preserved across regeneration. Point DNS `A`/`AAAA` at the host.
 
 </Step>
 
@@ -67,14 +68,16 @@ Add your public hostname to serve `allowedHosts`
 
 ## Which proxy?
 
-| Choice                       | Best for                                                   | How routing works                                                  |
-| ---------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Caddy** (`caddy:2-alpine`) | hello / minimal / standard — single instance, simplest TLS | Generated `Caddyfile` → `reverse_proxy app:6530`; automatic HTTPS  |
-| **Traefik** (`traefik:v3.3`) | Horizontally scaled plain compose                          | Docker labels on `app`; replicas auto-discovered and load-balanced |
-| _(omit `images.proxy`)_      | Local / private networks                                   | App publishes `6530` — **default, unchanged**                      |
+| Choice                          | Best for                                                   | How routing works                                                  |
+| ------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Caddy** (`caddy:2-alpine`)    | hello / minimal / standard — single instance, simplest TLS | Generated `Caddyfile` → `reverse_proxy app:6530`; automatic HTTPS  |
+| **Traefik** (`traefik:v3.7`)    | Horizontally scaled plain compose                          | Docker labels on `app`; replicas auto-discovered and load-balanced |
+| **nginx** (`nginx:1.31-alpine`) | Static HTTP edge; TLS elsewhere                            | Generated `nginx.conf` → `proxy_pass` to `app:6530` on `:80`       |
+| _(omit `images.proxy`)_         | Local / private networks                                   | App publishes `6530` — **default, unchanged**                      |
 
 **Consequence:** Caddy is the recommended default when you just need a certificate.
 Choose Traefik when `docker compose up --scale app=N` is the deployment shape.
+Choose nginx when another edge already terminates TLS.
 
 ## Caddy
 
@@ -86,15 +89,15 @@ Emits `docker/Caddyfile`:
 }
 ```
 
-| Setting                | What it does                                                                                                                                  |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OKE_PROXY_HOST`       | Site address. `localhost` → local TLS; a public DNS name → Let's Encrypt HTTP-01                                                              |
-| `OKE_PROXY_ACME_EMAIL` | Written into `.env.docker` for the proxy role. Traefik consumes it; for Caddy, add a global `email` block if you want a specific ACME contact |
+| Setting                | What it does                                                                                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OKE_PROXY_HOST`       | Site address. `localhost` → local TLS; a public DNS name → Let's Encrypt HTTP-01                                                             |
+| `OKE_PROXY_ACME_EMAIL` | Written into `.env.local` for the proxy role. Traefik consumes it; for Caddy, add a global `email` block if you want a specific ACME contact |
 
 Custom domain:
 
 1. DNS for `app.example.com` → this host
-2. `OKE_PROXY_HOST=app.example.com` in `docker/.env.docker`
+2. `OKE_PROXY_HOST=app.example.com` in `.env.local`
 3. Ports `80`/`443` reachable from the public internet
 4. `allowedHosts` includes `app.example.com`
 
@@ -119,6 +122,14 @@ HTTP (`:80`) redirects to HTTPS. ACME email comes from
 Scaled replicas need no label edits — `docker compose up --scale app=N` registers
 every replica through the Docker provider.
 
+## nginx
+
+| Piece          | Meaning                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| Generated file | `docker/nginx.conf` — `proxy_pass` to `app:6530` on `:80`               |
+| TLS            | None in-container — put Cloudflare / an ALB in front, or switch recipes |
+| Full recipe    | [nginx](/docs/recipes/nginx)                                            |
+
 ## Why docker-socket-proxy (Traefik)
 
 Traefik's Docker provider watches the Engine API for containers and labels.
@@ -158,7 +169,7 @@ the full Docker control plane.
 
 | Surface                                       | Edge / ingress                                           |
 | --------------------------------------------- | -------------------------------------------------------- |
-| [Docker](/docs/deployment/docker)             | Opt-in Caddy or Traefik (`images.proxy`)                 |
+| [Docker](/docs/deployment/docker)             | Opt-in Caddy / Traefik / nginx (`images.proxy`)          |
 | [Docker Swarm](/docs/deployment/docker-swarm) | Same proxy recipes + Swarm routing mesh                  |
 | [Kubernetes](/docs/deployment/kubernetes)     | Ingress / Gateway API (cluster-native — not this recipe) |
 
@@ -183,6 +194,13 @@ Confirm app labels are present (`traefik.enable=true`) in `compose.proxy.yml`,
 containers share the `oke` network, and `socket-proxy` is healthy. Traefik must
 not mount `docker.sock` itself.
 
+</Accordion>
+<Accordion title="oke dev: service app has neither an image nor a build context">
+
+`oke dev` starts infra only; the app stays on the host at `:6530`.
+Proxy recipes route to a Compose `app` service — use `oke docker` for that.
+Re-run `oke dev` after upgrading so compose drops the label-only `app`.
+
 </Accordion>
 <Accordion title="Host header rejected (403)">
 
@@ -193,7 +211,7 @@ Serve validates `Host`. Add your public hostname to `allowedHosts`
 <Accordion title="Caddy serves localhost certs on my public host">
 
 `OKE_PROXY_HOST` is still `localhost` (or unset). Set the public DNS name in
-`docker/.env.docker` and recreate the proxy container so it reloads the Caddyfile.
+`.env.local` and recreate the proxy container so it reloads the Caddyfile.
 
 </Accordion>
 </Accordions>