okengine 0.14.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -174,10 +174,9 @@
     "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-kit": "1.0.0-rc.5-ab785fc",
+    "drizzle-orm": "1.0.0-rc.5-169397b",
     "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",

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

@@ -182,7 +182,7 @@ Return those chunks on HTTP with `fx.json.stream(...)`. The kernel answers `text
 
 ```typescript
 on(
-  http.post("/complete").gate.public,
+  http.post("/complete").public(),
   flow("chat.complete", {
     do: (input, fx) => fx.json.stream(fx.stream(smart, { prompt: input.prompt })),
   }),
@@ -364,6 +364,7 @@ A hang-up is `AbortError` — it does not retry or advance `via`.
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — agent `tools` are Flow names (`notes.get`), not URLs
 - [Flow](/docs/elements/flow) — `fx.ask` and `fx.search` inside `do`
 - [Store](/docs/elements/store) — `store.index`, the home of embeddings
 - [MCP](/docs/ai/mcp) — serve the app to agents, or consume external servers as tools

package/site/content/docs/elements/channel.mdx

@@ -327,6 +327,7 @@ Confirm a visible OS notification titled `okengine webpush interop`.
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — `flow({…})` names as `unit.export`; explicit `flow("unit.action")` still wins
 - [Flow](/docs/elements/flow) — `fx.send` inside `do`
 - [Environment Variables](/docs/reference/environment-variables) — Channel boot credentials
 - [Configuration](/docs/reference/configuration) — `drivers.channel.*` maps

package/site/content/docs/elements/clock.mdx

@@ -52,6 +52,8 @@ export const dailyReport = clock("daily-report", {
 });
 ```
 
+Import the module before `oke()` — named clocks auto-register. No `oke({ clocks })` list.
+
 ```typescript title="src/flows/reports/daily.ts"
 export const sendDaily = on(
   dailyReport,
@@ -218,6 +220,7 @@ The registry is off in `test` and when there is no shared SQL URL. `dev`/`prod`
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — clock flows in the tree get a name, never a URL
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and the `fx` surface
 - [fx · Runs](/docs/reference/fx#runs-observability-read) — native SLO checkers via `on(every(…))` + `fx.runs`
 - [Signal](/docs/elements/signal) — reacting to events instead of time

package/site/content/docs/elements/flow.mdx

@@ -104,6 +104,12 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
   [Store](/docs/elements/store#handwritten-http-lists).
 </Callout>
 
+<Callout title="Helpers take the real Fx">
+  Type a helper's `fx` as the exported `Fx` (`import type { Fx } from
+  "okengine"`). A narrower `{ store: … }` will not match `store()` overloads
+  — that is the `as never` trap. See [fx](/docs/reference/fx).
+</Callout>
+
 ## The five triggers
 
 <FlowTriggers />
@@ -112,6 +118,8 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
 
 `http.get` · `http.post` · `http.put` · `http.patch` · `http.delete` · `http.head` · `http.options` · `http.query`. QUERY (RFC 10008) is a safe, idempotent read with a JSON body.
 
+`http.get()` with no path is filled from the file tree (`flows/notes/[id]/get.ts` → `/notes/:id`). `flow({ do })` is named `unit.export`. Explicit `http.get("/me/tasks")` and `flow("notes.get")` still win. Folder conventions live on [Project structure](/docs/get-started/project-structure).
+
 `Content-Type: application/json` is required — missing → **400** `InvalidQuery`, anything else → **415** `UnsupportedMediaType` with `Accept-Query: "application/json"`. Invalid JSON is **400** (no sniffing). Responses advertise `Accept-Query`. okengine does not assign `Location` / `Content-Location` result URIs.
 
 A browser `GET` (`Accept` prefers `text/html`) paints the `{ data, error }` envelope in traces chrome — status, latency, and cache, Routes rail (static GET links), copy, line numbers, Pretty / Raw, Console on **6533**. `curl`, `Accept: application/json`, and `?format=json` stay JSON.
@@ -369,6 +377,7 @@ a **hit**. A matching write turns the next read into a miss.
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — folders are the URL; `unit.export` is the name
 - [fx](/docs/reference/fx) — full `fx` surface, including ICU `fx.t` / `fx.locale`
 - [Signal](/docs/elements/signal) — delivery physics (`once` · `broadcast` · `live`)
 - [Clock](/docs/elements/clock) — schedules and durable sleep

package/site/content/docs/elements/gate.mdx

@@ -10,7 +10,7 @@ burned its minute quota? Attach gates to the HTTP trigger — the pipeline check
 store write, emit, or channel send runs.
 
 <Callout title="The one rule">
-  Every HTTP trigger declares posture: attach a real gate, or attach `.gate.public`. Omitting both
+  Every HTTP trigger declares posture: attach a real gate, or attach `.public()`. Omitting both
   fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
 </Callout>
 
@@ -19,10 +19,10 @@ store write, emit, or channel send runs.
 <Steps>
 
 <Step>
-### Declare policies and register the Gate bag
+### Declare policies
 
-Policies are named predicates; rate limits are declarative budgets. Put the ones you reuse in
-`oke({ gate: { policies } })`:
+Policies are named predicates; rate limits are declarative budgets. Import the module before
+`oke()` — they auto-register. `oke({ gate: { policies } })` is still valid and additive.
 
 ```typescript title="src/gates.ts"
 import { gate } from "okengine";
@@ -43,14 +43,10 @@ export const fair = gate.rate({
 the scope checked.
 
 ```typescript title="src/app.ts"
+import "./gates";
 import { oke } from "okengine";
-import { member, canBook, fair } from "./gates";
 
-export const app = oke({
-  name: "shop",
-  env: "dev",
-  gate: { policies: [member, canBook, fair] },
-});
+export const app = oke({ name: "shop", env: "dev" });
 ```
 
 </Step>
@@ -58,14 +54,14 @@ export const app = oke({
 <Step>
 ### Attach them to triggers
 
-`.gate(...)` composes left to right — first denial wins. Public routes must say so explicitly:
+`.gate(...)` composes left to right — first denial wins. Public routes must say so explicitly. Path and name can come from the file tree — see [Project structure](/docs/get-started/project-structure).
 
 ```typescript title="src/flows/links/shorten.ts"
 import { on, flow, http, gate } from "okengine";
 import { member, canBook, fair } from "../../gates";
 
 export const health = on(
-  http.get("/health").gate.public,
+  http.get("/health").public(),
   flow("health.check", {
     out: HealthOut,
     do: () => ({ ok: true as const }),
@@ -88,8 +84,8 @@ export const shorten = on(
 ```
 
 A single gate stays `.gate(member)`. Reuse two or more with `gate.all` — `.gate(write)`
-flattens. `http.resource(path, ops).gate(...)` stamps every verb. Do **not** put
-`gate.public` in `gate.policies` — attach it on the trigger only.
+flattens. `http.resource(path, ops).gate(...)` stamps every verb. Public routes use
+`.public()` — do **not** put `gate.public` in `gate.policies`.
 
 </Step>
 
@@ -131,16 +127,16 @@ gates are skipped. `do` runs only when every gate passed.
 | ------------------------------------- | ------------------------------------------- | ---------------------------------- |
 | `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)           | auth / operator / request metadata |
 | `gate.scope(name)`                    | Does `auth.scopes` contain this exact name? | `auth.scopes`                      |
-| `gate.public` / `.gate.public`        | Intentionally unauthenticated surface       | always allows                      |
+| `gate.public` / `.public()`           | Intentionally unauthenticated surface       | always allows                      |
 | `gate.rate(options)`                  | Is there budget left for this subject?      | an atomic counter on the kv driver |
 | `gate.all(...members)`                | Reuse this chain on many triggers           | flattens; each member is evaluated |
 
 Pass `{ check, description }` on `gate.policy` when you want a human title in the Console (falls
-back to the policy name). The name `"public"` is reserved — use `gate.public`, not
-`gate.policy("public", …)`.
+back to the policy name). The name `"public"` is reserved — mark the trigger with
+`.public()`, not `gate.policy("public", …)`.
 
 `gate.all()` with no members throws. Nested `all` handles flatten.
-`oke({ gate: { policies: [write] } })` registers the members.
+Members auto-register when declared; `oke({ gate: { policies: [write] } })` is additive.
 
 ### Policy context
 
@@ -178,11 +174,11 @@ driver in tests. Boot opens a dedicated `oke:gates` namespace on **`drivers.stor
 
 ## Auth posture at boot
 
-Every HTTP trigger must carry a gate or `.gate.public`. Omitting both fails boot with
+Every HTTP trigger must carry a gate or `.public()`. Omitting both fails boot with
 `GateBootError` — message starts with `gate boot failed —` and lists every gap.
 
 ```typescript
-on(http.get("/health").gate.public, flow("health.check", {/* … */}));
+on(http.get("/health").public(), flow("health.check", {/* … */}));
 on(http.post("/bookings").gate(member, canBook), flow("bookings.create", {/* … */}));
 ```
 
@@ -191,7 +187,7 @@ on(http.post("/bookings").gate(member, canBook), flow("bookings.create", {/* …
 posture but does **not** authenticate.
 
 `gate: { unguardedHttp: "allow" }` skips the audit **only** when `env === "test"`.
-In `dev` / `prod` migrate with per-trigger `.gate.public`.
+In `dev` / `prod` migrate with per-trigger `.public()`.
 
 ## Built-in auth (`gate.auth`)
 
@@ -260,6 +256,38 @@ Customize tables, then `oke schema generate` (`.oke/schema/oke.ts`; `--check` in
 sign-in shapes: [Plugins](/docs/plugins). Call auth from
 [createClient](/docs/reference/client) — helpers in `okengine/client/auth`.
 
+## API keys
+
+A key is the **issuer with fewer gates** — not a second permission system.
+Bearer secrets authenticate as the creator; `fx.auth.scopes` shrink to the key.
+
+| Field                               | Session        | API key                 |
+| ----------------------------------- | -------------- | ----------------------- |
+| `fx.auth.userId` / `fx.operator.id` | subject        | creator (`creatorId`)   |
+| `fx.auth.scopes`                    | session scopes | key scopes (attenuated) |
+| `fx.auth.apiKeyId`                  | `null`         | key id                  |
+| WideEvent `principal`               | subject        | issuer                  |
+| `dimensions.api_key`                | absent         | key id                  |
+
+`gate.auth` always creates a shared key store (HMAC-SHA-256 with `gate.auth.secret`).
+Do not pass `apiKeyStore` unless you are injecting a test Map.
+
+<Callout title="Keys live on the app database">
+  With `store.sql()`, boot hydrates public `oke_api_keys` on that connection (`DATABASE_URL`) and
+  write-through persists create / rotate / revoke. Console **Access** attaches this host store — it
+  does not keep a second key database.
+</Callout>
+
+Session Flows manage keys via [fx](/docs/reference/fx) (`createApiKey`, `listApiKeys`,
+`revokeApiKey`, `rotateApiKey`, `updateApiKey`). A key-authenticated caller cannot.
+
+Declare `effects.reads: ["auth:api-keys"]` / `effects.writes: ["auth:api-keys"]` — never
+`sql:oke_api_keys`. Console **Access** (`:6533` → `/access`) mints operator keys as the
+operator, and user-plane keys only as a picked issuer (`creatorUserId`).
+
+Verify rejects expired, revoked, allowlist-miss, and over-rate secrets with `401`
+and no `api_key` dimension.
+
 ## Identity and decisions
 
 Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
@@ -270,12 +298,18 @@ Pass **and** deny land on the run's `gates` dimension. Console (`:6533` → `/fl
 chain on the flow contract. Rate `overridable` is a catalog flag only — Clock schedules are what the Console can
 edit live today.
 
+<Callout title="RLS reads the stamped principal">
+  After HTTP Gate passes, user-plane `fx.store` stamps `oke.gate()`, `oke.user()`, and
+  `oke.has_scope()`. Rate, cron, CDC, and signal stay unstamped. Helpers:
+  [Store](/docs/elements/store).
+</Callout>
+
 ## Troubleshooting
 
 <Accordions>
 <Accordion title="Boot: gate boot failed — N HTTP trigger(s) missing auth posture">
 
-Empty `.gate(...)` chain. Attach a policy/rate gate, or `.gate.public`. First `fetch`
+Empty `.gate(...)` chain. Attach a policy/rate gate, or `.public()`. First `fetch`
 auto-boots — do not rely on `gate.unguardedHttp: "allow"` outside `env: "test"`.
 
 </Accordion>
@@ -308,11 +342,35 @@ character classes.
 `"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
 Keying an authenticated endpoint by IP punishes shared NAT.
 
+</Accordion>
+<Accordion title="API key Bearer returns 401">
+
+Expired, revoked, allowlist miss, or over the key's `rateLimit`. Check
+`ipAllowlist` against the same X-Forwarded-For hop as `ip-allowlist`.
+Entries are IPs or hostnames — a host resolves at verify time and must
+include the client IP (lookup failure is closed). Rotate if the secret
+was shown once and then lost.
+
+</Accordion>
+<Accordion title="Keys vanish after an app restart">
+
+No SQL store, or a new `gate.auth.secret`. Declare `store.sql()`, keep
+`DATABASE_URL` (or the same PGlite datadir) and the auth secret stable.
+Console does not persist keys in `oke_console`.
+
+</Accordion>
+<Accordion title="Key can call a route the issuer cannot">
+
+That is a bug in the mint. `createApiKey` / `fx.auth.createApiKey` re-run
+`assertAttenuated` against the issuer's live scopes. Custom `gate.policy`
+predicates that ignore scopes still see `verified: true`.
+
 </Accordion>
 </Accordions>
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — `http.get()` and `flow({…})` fill path and name from the file tree
 - [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
 - [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`
 - [Client](/docs/reference/client) — Bearer `createClient` + `okengine/client/auth`

package/site/content/docs/elements/signal.mdx

@@ -131,7 +131,7 @@ A Flow **writes** all three tapes. `once` / `broadcast` **listen** with `on(sign
 
 ```typescript title="src/flows/orders/place.ts"
 export const placeOrder = on(
-  http.post("/orders").gate.public,
+  http.post("/orders").public(),
   flow("orders.place", {
     in: z.object({ id: z.string(), total: z.number() }),
     do: async (input, fx) => {
@@ -256,9 +256,8 @@ Committed `once` messages survive process death. A claim sets `lockedBy` and a v
 
 <Callout title="Client subscription is not shipped yet">
   `delivery: "live"` means the **driver** retains and replays. Listen with `bus.live()` on the
-  server — not `on(signal, flow)`. `createClient` has no SSE / WebSocket / `client.live` yet — poll
-  an HTTP Flow. See [Client · Signal and live
-  queries](/docs/reference/client#signal-and-live-queries).
+  server — not `on(signal, flow)`. `createClient` has no SSE yet — poll HTTP. See
+  [Client](/docs/reference/client#signal-and-live-queries).
 </Callout>
 
 ## Orphaned signal config
@@ -335,6 +334,7 @@ At-least-once: crash-after-claim reclaims when the lease expires, and a handler
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — signal files get a name, never a URL; `http.get("/…")` still wins
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and `fx.emit`
 - [fx](/docs/reference/fx) — `fx.emit` and `fx.deadLetters`
 - [Clock](/docs/elements/clock) — scheduled and delayed work

package/site/content/docs/elements/store.mdx

@@ -19,6 +19,9 @@ only the driver changes.
 Every facet accepts optional `description` — a human title in the Console (falls back to the store
 name).
 
+`store.sql` / `kv` / `files` / `index` auto-register when the declaring module is imported before
+`oke()`. `oke({ stores })` is still valid and additive.
+
 ## SQL
 
 <StoreFacetMark facet="sql" />
@@ -39,9 +42,9 @@ Manifest tables, columns, and keywords.
 Classified PII stays masked unless the toolbar **PII** control is on
 (`revealPii: true`, audited).
 
-**Gate** views the result as Operator (default, bypasses RLS), public, a
-selected user (via their matching policy), or a Manifest policy gate.
-`asGate` sets `oke.gate` on postgres / pglite for `current_setting('oke.gate', true)`.
+**Gate** views as Operator (bypass), public, a user, or a policy. SQL,
+browse, and grid edit send `{ asGate, asUserId }`. postgres / pglite stamp
+`oke.gate()` / `oke.user()` / `oke.has_scope()`; memory is catalog-only.
 
 The SQL band **Schema** control opens a visualizer of Manifest tables and
 relations — declared `.references()` plus inferred `*_id` columns — not the
@@ -88,17 +91,21 @@ Install reviews the `CREATE EXTENSION` SQL; **Advanced** can set `SCHEMA`,
 When a newer packaged version exists, the name chip shows **Upgrade**
 (`ALTER EXTENSION … UPDATE`). Names link to the project or Postgres docs.
 
-Each SQL table row shows whether Postgres RLS is on (emerald shield)
-or off (muted shield). KV, files, and index have no badge. Enabling
-RLS on create flips that shield.
+SQL table rows and the resource header show RLS (emerald / muted shield;
+**N RLS** when policies exist) before **PII**. KV, files, and index have
+no badge — enabling RLS on create flips the shield.
+
+**RLS Policies** lists `pg_policies` plus Manifest `declared` / `live`.
+Two-finger click a row for its sheet, or empty grid to create. Create
+pins SQL | Code (`store.schema.policy` + `pgPolicy`); drag to resize.
 
-**RLS Policies** lists `pg_policies`. Create policy pins the SQL preview;
-**Templates** slides a flush library beside it (every `FOR` command, owner,
-`oke.gate`). Or edit `roles` / `USING` / `WITH CHECK` in the grid (`ALTER POLICY`).
+**Templates** use `oke.user()` / `oke.gate()` / `oke.has_scope()`.
+Owner cards pick a **Column** (guess `creator_email` / `owner_email`)
+with PK / FK marks. Create stays blocked until a column is picked.
 
 Create policy picks a Gate posture (Read / Write / Both), or **Policy &
-scope** for `gate.public`, `gate.policy`, and `gate.scope`. `TO public`
-stays on the SQL — those picks are not Postgres roles.
+scope**. Those picks fill `USING` / `WITH CHECK`. `TO` stays `public` —
+Gate names are not Postgres roles.
 
 ### Quick start
 
@@ -192,7 +199,7 @@ const notesR = store.resource(db, notes, {
   },
 });
 
-const mounted = on(http.resource("/notes", notesR.all()).gate.public.live());
+const mounted = on(http.resource("/notes", notesR.all()).public().live());
 ```
 
 `.gate(...)` / `.live()` chain like `http.get` — gates on every verb, live on list and get.
@@ -240,7 +247,7 @@ list: { mode: "offset", filter: "none", limit: 20 },
 
 ```typescript
 export const list = on(
-  http.get("/notes").gate.public,
+  http.get("/notes").public(),
   flow("notes.list", {
     out: z.array(Note),
     do: async (input, fx) => {
@@ -251,6 +258,8 @@ export const list = on(
 );
 ```
 
+`list.ts` + `http.get()` fills `GET /notes` named `notes.list` — explicit strings still win. See [Project structure](/docs/get-started/project-structure).
+
 Zero-config: `?q=` searches every string field, extra keys auto-eq except path `id`, and PostgREST `?col=op.value` / `?order=` / `?select=` are open. Nested lists filter the parent in the load — `input.id` is not a column eq.
 
 <Callout title="Preferred, not required">
@@ -282,6 +291,9 @@ await fx.store(db).update(notes).set({ title: input.title }).where(eq(notes.id,
 await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 ```
 
+`select().from(notes)` infers the declared row (`string` / `number` / `null` from
+`field.*`). A `select({ title: notes.title })` projection stays untyped.
+
 <Callout title="One table per call — no relational with:">
   `fx.store` is deliberately **single-table**: Drizzle's relational `findMany({ with: … })` is not
   available through `fx`. Compose joins as separate single-table reads (or `fx.call`) so every
@@ -292,15 +304,44 @@ await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 
 The recommended path: declare tables ORM-agnostically, then let `oke db` emit real Drizzle (`pgTable` for Postgres / PGLite) into `src/db/schema.drizzle.ts`.
 
-| Field API                                    | Meaning                                         |
-| -------------------------------------------- | ----------------------------------------------- |
-| `field.text()` / `field.integer()`           | v1 column primitives                            |
-| `.primaryKey()` · `.notNull()` · `.unique()` | constraints                                     |
-| `.default(v)` · `.defaultFn(id \| now)`      | defaults                                        |
-| `.pii()` · `.sensitive()` · `.retain("30d")` | privacy classification                          |
-| `.as("sql_name")`                            | override the automatic `camelCase → snake_case` |
-| `.describe("…")`                             | human title in the Console (falls back to key)  |
-| `.references(() => col, { onDelete })`       | foreign key                                     |
+| Field API                                    | Meaning                                                          |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| `field.text()` / `field.integer()`           | v1 column primitives                                             |
+| `.primaryKey()` · `.notNull()` · `.unique()` | constraints                                                      |
+| `.default(v)` · `.defaultFn(id \| now)`      | defaults                                                         |
+| `.pii()` · `.sensitive()` · `.retain("30d")` | privacy classification                                           |
+| `.as("sql_name")`                            | override the automatic `camelCase → snake_case`                  |
+| `.describe("…")`                             | human title in the Console (falls back to key)                   |
+| `.references(() => col, { onDelete })`       | foreign key                                                      |
+| `store.schema.rls()`                         | `pgTable.withRLS` when there are no policies                     |
+| `store.schema.policy.gate/owner/scope`       | happy-path RLS (`oke.gate()` / `oke.user()` / `oke.has_scope()`) |
+
+Third argument on `store.schema.table` is Drizzle-shaped extras:
+
+```typescript
+export const bookings = store.schema.table(
+  "bookings",
+  {
+    id: field.text().primaryKey(),
+    owner: field.text().notNull(),
+  },
+  [
+    store.schema.policy.gate("member", { for: "select" }),
+    store.schema.policy.owner("owner", { for: "all" }),
+    store.schema.policy.scope("booking:create", { for: "insert" }),
+  ],
+);
+```
+
+Helpers emit stable names (`gate_member_select`). Raw
+`store.schema.policy("name", { as, to, for, using, withCheck })` is the
+escape hatch — predicates use `oke.*`, never `current_setting`.
+
+<Callout title="User-plane fx.store applies RLS">
+  HTTP / resource flows stamp Gate identity onto every postgres / pglite statement (`SET LOCAL ROLE
+  oke_app` + `set_config` in one pinned transaction). Table-owner bypass ends there; operator / cron
+  / CDC / signal / catalog stay unstamped.
+</Callout>
 
 #### Foreign keys and relations
 
@@ -356,9 +397,9 @@ Staging/prod accumulate versioned SQL under `drizzle/` (`oke db generate`).
 | Staging / prod | `oke db generate` → review files → `oke db migrate` on that DB |
 
 <Callout title="Connection pooling is infrastructure, not app code" type="info">
-  Bun.SQL defaults to **10** connections per process — fine per instance. Scale out and `N × pool`
-  can exceed Postgres `max_connections`. `dev`/`prod` put **PgDog** in front; `DATABASE_URL` → port
-  `6432`. No app code changes.
+  One shared Bun.SQL pool (**8** connections) per URL. `dev`/`prod` put **PgDog** in front
+  (`DATABASE_URL` → port `6432`, `pool_size` 20). RLS stamps `reserve` one slot, then `SET LOCAL` in
+  that transaction — a leaked `BEGIN` exhausts checkout.
 </Callout>
 
 **Why PgDog (not PgBouncer as the default).** Transaction pooling fixes the
@@ -371,8 +412,9 @@ Not wired this round — readiness only.
 
 #### Seeding
 
-`oke db seed` loads `defineSeed` from `src/db/seed/index.ts` — **never at boot**.
-`name` is this app's seed (template or example). The prompt and `.oke/state.json` key off it.
+`oke db seed` loads `defineSeed` from `src/db/seed/index.ts` — a separate
+command, never at boot. Not every project has a seed. In `oke dev`, `s` runs
+the same command. `name` is this app's seed (template or example).
 
 <StoreSeeding />
 
@@ -642,8 +684,12 @@ Default `store.kv("sessions")` is cache-shaped — a Redis recreate drops keys.
 ```typescript
 export const sessions = store.kv("sessions", { description: "Session cache" });
 export const ledger = store.kv("ledger", { durable: true, description: "Idempotency keys" });
+export const drafts = store.kv("drafts", { durable: true, description: "Compose drafts" });
 ```
 
+**Consequence:** `oke db seed` into cache Redis looks fine until compose recreates the
+container — Console Store then shows **No rows.** Seeded namespaces need `{ durable: true }`.
+
 Gate rates and Signal stay on `REDIS_URL`. Missing `DATABASE_URL` with the postgres driver
 fails boot: `oke boot: durable store.kv needs DATABASE_URL`.
 
@@ -1014,6 +1060,11 @@ Inserts and selects now resolve it from the declaration. Keep the `name` column.
 
 Schema DDL never runs automatically in `prod`. Under `oke dev`, `db.autoPush` (default `true`) runs `oke db push`. For production use `oke db generate` + `oke db migrate`.
 
+</Accordion>
+<Accordion title="oke db push: missing_hints">
+
+New tables are created automatically. Push only manages `public` — it will not drop schema `oke` (RLS helpers) or `oke_console`. Remaining `missing_hints` are destructive (drop a non-empty public table, type change). Review with `oke db generate`.
+
 </Accordion>
 <Accordion title="I need a join — with: is not supported">
 
@@ -1064,11 +1115,17 @@ Unlike KV/Files, unset `drivers.store.index` does **not** promote to `pgvector`
 
 `.oke/state.json` stores `seededAt` plus this app's `defineSeed({ name })` — notes vs keel are different ids. A new name re-asks. Clear those keys to prompt again.
 
+</Accordion>
+<Accordion title="Console KV shows No rows after oke db seed">
+
+Default `store.kv` is cache Redis with no AOF — a recreate drops keys. SQL seed still looks full. Mark seeded namespaces `{ durable: true }` so they live in `oke_kv`, then restart and seed again.
+
 </Accordion>
 </Accordions>
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — `list.ts` + `http.get()` is `GET /notes` named `notes.list`
 - [Flow](/docs/elements/flow) — the `fx.store` session inside `do`
 - [AI](/docs/elements/ai) — `ai.embed` into a vector `store.index`, searched via `fx.search`
 - [Gate](/docs/elements/gate) — `pii:reveal` and other permissions on flows

package/site/content/docs/elements/vault.mdx

@@ -201,6 +201,9 @@ The **Console** (`:6533`) **Vault** page (`/vault`) groups **Secrets** and
 **Config**. Secrets are write-only: a salted fingerprint (`sha256:…`), never
 the cleartext. Config rows show the value — that is `vault.config()`.
 
+API keys are principals — mint them on **Access** (`/access`), not Vault.
+See [Gate](/docs/elements/gate#api-keys).
+
 Add (`+`) creates a contract from Console as well as from source. Those rows
 show `console` until you declare the same name in the Manifest.
 
@@ -363,6 +366,7 @@ Schedule the live command with cron when you want automatic cleanup.
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — `flow({…})` names as `unit.export`; `flow("billing.charge")` still wins
 - [Flow](/docs/elements/flow) — how `fx.vault.get` reads secrets inside `do`
 - [CLI Reference](/docs/reference/cli) — `oke vault set` · `list` · `import`
 

package/site/content/docs/get-started/basic-usage.mdx

@@ -45,19 +45,21 @@ lists HTTP routes — static GET paths are links. `curl` still gets `{ data, err
 
 The standard starter already exports a named health Flow:
 
-```typescript title="flows/main"
-import { on, flow, http, gate } from "okengine/http";
+```typescript title="flows/main/health.ts"
+import { on, flow, http } from "okengine";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health").gate.public,
-  flow("main.health", {
+  http.get().public(),
+  flow({
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),
 );
 ```
 
+`main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure).
+
 Named flows show up as `main.health` (not `flow_1`) in `oke dev` logs, with the run id after the timestamp.
 Change the route or output and save — App and Console update together from the
 same Manifest.
@@ -67,20 +69,19 @@ same Manifest.
 <Step>
 ### Call it from a typed client
 
-Adopted modules become namespaces on the client:
+Generated units become namespaces on the client:
 
 ```typescript title="app"
 import "@/core";
-
+import "@/flows/generated";
 import { oke } from "okengine/http";
-import * as routes from "@/flows/generated";
 
-export const app = oke({ name: "notes" }).adopt(routes);
+export const app = oke({ name: "notes" });
 export type App = typeof app;
 ```
 
-`import "@/core"` loads stores, secrets, channels, and message catalogs
-(via `locales/index.ts`) so they auto-register before `oke()`.
+`import "@/core"` loads stores, secrets, gates, clocks, channels, and
+message catalogs (via `locales/index.ts`) so they auto-register before `oke()`.
 
 ```typescript title="client"
 import { createClient } from "okengine/client";
@@ -107,7 +108,7 @@ Every backend behavior has one shape:
 
 ## From Flow to client
 
-Export → adopt → call or test. Same App type — no separate codegen project.
+Export → generated barrel → call or test. Same App type — no separate codegen project.
 
 <ClientLoop />
 
@@ -137,8 +138,10 @@ bun test
 <Accordions>
 
 <Accordion title="api.main.health is not a function / type error">
-  Confirm the Flow is `export`ed from the module you `.adopt({main})`, and that `createClient` is
-  typed with your `App` type. Restart `oke dev` after renaming exports so the Manifest refreshes.
+  Confirm the Flow is `export`ed from a generated unit (`import "@/flows/generated"` then `oke({ name })`), or from a module you still `.adopt({ main })`.
+
+Type `createClient` with your `App` type. Restart `oke dev` after renaming exports so the Manifest refreshes.
+
 </Accordion>
 
 <Accordion title="createTestApp fails to boot">
@@ -151,6 +154,7 @@ bun test
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — folders are the URL
 - [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
 - [Store](/docs/elements/store) — SQL, KV, files, index, and the preferred list envelope
 - [fx](/docs/reference/fx) — the full effect surface
@@ -158,6 +162,11 @@ bun test
 ## Next
 
 <Cards>
+  <Card
+    title="Project structure"
+    description="Folders are the URL; unit plus export is the name."
+    href="/docs/get-started/project-structure"
+  />
   <Card
     title="Flow"
     description="Triggers, contracts, effects, and composition."