okengine 0.13.0 → 0.15.2

package/manifest.v1.schema.json

@@ -111,6 +111,11 @@
       "type": "string",
       "pattern": "^(sql|kv|files|index):.+$"
     },
+    "SignalResourceRef": {
+      "description": "Dead-letter read via fx.deadLetters — signal:<name>, not a store facet.",
+      "type": "string",
+      "pattern": "^signal:.+$"
+    },
     "SignalRef": {
       "type": "string",
       "minLength": 1
@@ -145,7 +150,8 @@
               {
                 "const": "runs",
                 "description": "Runs wide-event store via fx.runs (observability read)."
-              }
+              },
+              { "$ref": "#/$defs/SignalResourceRef" }
             ]
           },
           "uniqueItems": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.13.0",
+  "version": "0.15.2",
   "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",
@@ -271,6 +270,6 @@
     "react": "^19.2.8"
   },
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

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

@@ -1,11 +1,13 @@
 ---
 title: "MCP"
-description: "The runtime MCP server on :6535 — read tools for Manifest, schemas, effects, and traces, write actions gated by per-call human confirmation — plus the read-only docs MCP on :6536."
+description: "OKE serves MCP on :6535 so agents can operate a running app, and apps consume external MCP servers as allowlisted tools on the same fx.call path."
 icon: "Plug"
 source: "docs/spec/unified-theory.md"
 ---
 
-OKE serves an [MCP](https://modelcontextprotocol.io) endpoint on port **6535** so an AI agent can operate your running app: read its Manifest and traces, and take a small set of safe actions. It speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
+Two directions, same protocol. **Serve:** OKE exposes your running app on port **6535** so an agent can read the Manifest and take confirmed actions. **Consume:** your Flows call _external_ MCP servers as tools — declared on `ai.mcpServer`, dispatched through `fx.call`.
+
+The server on **6535** speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
 
 <Callout title="The one rule">
   MCP inherits the operator's capability and can never exceed it. Server-level controls alone are
@@ -96,6 +98,29 @@ Consumed tokens cannot be replayed; the next write needs a new confirmation. A m
 
 The docs content ships inside the `okengine` package, so the index your agent searches is exactly the version you have installed. If the surface cannot boot (missing content, busy port), `oke dev` prints `Docs MCP skipped — …` and continues — docs search never takes your dev session down.
 
+## Consume — `ai.mcpServer`
+
+Your app can _call_ other MCP servers. Those tools are not a second loop — they join `fx.ask` / `ai.agent` the same way a Flow tool does.
+
+```typescript
+export const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: githubToken },
+  tools: ["create_issue"], // required allowlist
+});
+
+await fx.ask(triage, input, { tools: [github.tool("create_issue")] });
+```
+
+| Rule       | Meaning                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| Allowlist  | `tools` is required. Extra names from `tools/list` are dropped.                                   |
+| Capability | `mcp:<server>/<tool>` on `effects.calls` — undeclared throws **OKE1007**.                         |
+| Transport  | `url` (Streamable HTTP) **or** `command` + `args` (stdio). Not both.                              |
+| Cancel     | HTTP aborts the fetch / SSE stream. stdio sends `notifications/cancelled` then kills the process. |
+
+Console draws each declared server as one **AI** node on the flow graph; Units chips read `Call github → create_issue`; traces label the effect **MCP call**. There is no separate MCP page or connect UI.
+
 ## Learn more
 
 - [Agent contracts](/docs/ai/skills) — what agents are taught about the system they operate

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

@@ -68,14 +68,15 @@ export const triage = smart.prompt("ticket-triage", {
 
 </Steps>
 
-## The four building blocks
+## The building blocks
 
-| Declaration                | Produces                                                           |
-| -------------------------- | ------------------------------------------------------------------ |
-| `ai.model(name, opts)`     | Logical model binding — provider / tier / concrete model id        |
-| `model.prompt(name, opts)` | Versioned prompt with typed in/out, evals, budget                  |
-| `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`) |
-| `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                   |
+| Declaration                | Produces                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `ai.model(name, opts)`     | Logical model binding — provider / tier / model id / optional `driverId`        |
+| `model.prompt(name, opts)` | Versioned prompt with typed in/out, evals, budget                               |
+| `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`)              |
+| `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                                |
+| `ai.mcpServer(name, opts)` | External MCP server — allowlisted tools join `fx.call` as `mcp:<server>/<tool>` |
 
 <AiBlocks />
 
@@ -105,9 +106,11 @@ const out = await fx.ask(summarizeNote, { title, body });
 // out.via is the logical model that answered
 ```
 
-Resolution: `fx.ask(…, { via })` overrides `prompt.via`, else the prompt’s bound model. On each model the runtime retries **once** for retryable failures (timeout / 429 / 5xx / network), then advances. Permanent failures (401 / other 4xx / schema invalid) stop the chain. When every eligible attempt fails, `fx.ask` throws — map that to a typed error in the flow (no silent text excerpt).
+Resolution: `fx.ask(…, { via })` overrides `prompt.via`, else the prompt’s bound model. On each model the runtime retries **once** for retryable failures (timeout / 429 / 5xx / network), then advances.
 
-`timeout` uses the same duration vocabulary as Clock (`"30s"`, `"2m"`, or a millisecond number). Ask-time `fx.ask(…, { timeout: "10s" })` overrides the prompt. Omit = no artificial cap. Cost caps stay on `budget`.
+Permanent failures (401 / other 4xx / schema invalid / client disconnect / `maxCostPerCall` exceeded) stop the chain. When every eligible attempt fails, `fx.ask` throws — map that to a typed error in the flow (no silent text excerpt).
+
+`timeout` uses the same duration vocabulary as Clock (`"30s"`, `"2m"`, or a millisecond number). Ask-time `fx.ask(…, { timeout: "10s" })` overrides the prompt. Omit = no artificial cap. `budget.maxCostPerCall` is enforced at runtime (not just observed). Set `driverId` on a model to open a different protocol than the app default.
 
 ## Declared guardrails
 
@@ -126,6 +129,22 @@ const result = await fx.ask(triage, input, {
 });
 ```
 
+External MCP tools take the same path. Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
+
+```typescript
+export const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: githubToken },
+  tools: ["create_issue"],
+});
+
+await fx.ask(triage, input, {
+  tools: [github.tool("create_issue")],
+});
+```
+
+Capability refs are `mcp:<server>/<tool>`. An undeclared call throws **OKE1007**. See [MCP](/docs/ai/mcp).
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:
@@ -139,7 +158,7 @@ export const support = ai.agent("support", {
 });
 ```
 
-`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
+`maxSteps` bounds the loop; `budget.maxCostPerRun` is enforced after the run. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
 
 ## Rate limits via Gate
 
@@ -157,7 +176,20 @@ Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/a
 
 ## Streaming
 
-`fx.stream(model, { prompt })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
+`fx.stream(model, { prompt, via? })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
+
+Return those chunks on HTTP with `fx.json.stream(...)`. The kernel answers `text/event-stream` (`data:` frames, then `data: [DONE]`). JSON flows stay buffered `{ data, error }`.
+
+```typescript
+on(
+  http.post("/complete").public(),
+  flow("chat.complete", {
+    do: (input, fx) => fx.json.stream(fx.stream(smart, { prompt: input.prompt })),
+  }),
+);
+```
+
+Disconnect cancels the provider call automatically (`request.signal` → ambient abort). An `AbortError` from hang-up does not retry or advance `via`. Console Traces stay empty until the stream closes — then the run is one completed row whose duration covers the open stream, not just time-to-first-byte.
 
 ## PII cannot leak by accident
 
@@ -305,6 +337,11 @@ Capability pins and Call API pass `name@version`. `fx.ask` resolves the bare
 prompt id. A pin that does not match `prompt.version` throws
 `ai: unknown prompt "name@version"`.
 
+</Accordion>
+<Accordion title="OKE1007 when the model calls an MCP tool">
+
+Add `mcp:<server>/<tool>` to that flow’s `effects.calls` — the same token as `fx.call`. The allowlist on `ai.mcpServer` is not a capability grant.
+
 </Accordion>
 <Accordion title="An agent looped and burned budget">
 
@@ -313,13 +350,24 @@ Bound it at declaration: `maxSteps` caps iterations, `budget.maxCostPerRun` caps
 `fx.ask` stamps `promptVersion` on the run. Cost is recorded only when the
 driver reports `usage.cost` — tokens land on the ask journal either way.
 
+</Accordion>
+<Accordion title="The client hung up but the model kept generating">
+
+HTTP flows install `request.signal` as the ambient abort. `fx.ask` / `fx.stream` /
+`fx.run` cancel the provider fetch. Return tokens with `fx.json.stream(fx.stream(...))`
+so disconnect is observable.
+
+A hang-up is `AbortError` — it does not retry or advance `via`.
+
 </Accordion>
 </Accordions>
 
 ## 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
 
 ## Next
 

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

@@ -28,7 +28,7 @@ export const purgeOld = on(
   every("1h"),
   flow("links.purgeOld", {
     do: async (_, fx) => {
-      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
+      const cutoff = fx.clock.ago("30d");
       await fx.store(db).delete(links).where(lt(links.createdAt, cutoff));
     },
   }),
@@ -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,
@@ -68,12 +70,15 @@ export const sendDaily = on(
 <Step>
 ### Ask for time inside flows
 
-`fx.clock` is the only clock a flow knows:
+`fx.clock` is the only clock a flow knows. Instants stay epoch-ms; spans use the same
+duration strings as `every()` and `sleep()`:
 
 ```typescript
 do: async (input, fx) => {
-  const now = fx.clock.now(); // epoch-ms, injectable
-  await fx.clock.sleep("wait-for-payment", "7d"); // durable — survives restarts on a shared journal
+  const cutoff = fx.clock.ago("30d");
+  const expiresAt = fx.clock.fromNow("14d");
+  const window = input.createdAt + fx.clock.duration("7d");
+  await fx.clock.sleep("wait-for-payment", "7d");
 };
 ```
 
@@ -90,13 +95,25 @@ difference.
 
 ### `clock()` options
 
-| Option        | Type    | Default | Meaning                                                        |
-| ------------- | ------- | ------- | -------------------------------------------------------------- |
-| `cron`        | string  | —       | Cron expression `m h dom mon dow` (this or `every` required)   |
-| `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`            |
-| `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                              |
-| `overridable` | boolean | `false` | Allow the Console to **edit** the schedule (pause is separate) |
-| `description` | string  | —       | Human title in the Console (falls back to the clock name)      |
+| Option        | Type    | Default | Meaning                                                                                                                  |
+| ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `cron`        | string  | —       | Five-field crontab (`m h dom mon dow`), plus steps, ranges, lists, names, `@hourly`, `@daily` (this or `every` required) |
+| `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`                                                                      |
+| `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                                                                                        |
+| `overridable` | boolean | `false` | Allow the Console to **edit** the schedule (pause is separate)                                                           |
+| `description` | string  | —       | Human title in the Console (falls back to the clock name)                                                                |
+
+### `fx.clock`
+
+| Call                 | Returns | Meaning                                          |
+| -------------------- | ------- | ------------------------------------------------ |
+| `now()`              | instant | Injected epoch-ms                                |
+| `ago("30d")`         | instant | now − duration                                   |
+| `fromNow("14d")`     | instant | now + duration                                   |
+| `duration("7d")`     | span ms | Offset a stored instant (`createdAt + duration`) |
+| `sleep(label, "7d")` | —       | Durable sleep                                    |
+
+Same duration strings as `every()`: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400_000 ms, not a calendar day. Unknown strings parse as `0`.
 
 ## Sleeping inside a flow
 
@@ -136,7 +153,7 @@ Simple daily crons (`M H * * *`) in a DST-observing zone can hit a **gap** (spri
 
 Detection attaches `dstAmbiguity` on the cron row and the Console shows it. `oke doctor` does not check DST. The scheduler does not rewrite the expression.
 
-**Consequence:** fall-back days can list two civil instants an hour apart. The default leader lease (30s) is shorter than that gap, so a lease alone is not a “fire once on overlap” policy. Prefer UTC, or a wall time outside the transition window, when double-fire would hurt.
+**Consequence:** firing follows crontab. A spring gap runs at the next valid instant (shifted). A fall overlap fires **once** (first occurrence). Prefer UTC when a shifted spring fire would hurt.
 
 ## Per-environment drivers
 
@@ -203,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

@@ -112,6 +112,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.
@@ -130,7 +132,9 @@ export const findOrder = on(
 
 ### signal — another flow emits
 
-The producer emits through `fx` (transactionally with its writes); the consumer is the same species — no `subscribe()`, no listener registration:
+The producer emits through `fx`. For `once` and `broadcast` the consumer is the same species —
+`on(signal, flow)`, no `subscribe()` registration. `live` replay is the exception: `bus.live()` on
+the server, not a Flow.
 
 ```typescript
 await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
@@ -154,7 +158,7 @@ on(
   every("1h"),
   flow("sessions.sweepExpired", {
     do: async (_, fx) => {
-      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000;
+      const cutoff = fx.clock.ago("30d");
       await fx.store(db).delete(sessions).where(lt(sessions.createdAt, cutoff));
     },
   }),
@@ -198,12 +202,13 @@ Everything a flow may touch, on one object:
 | ------------------------------------------- | --------------- | -------------------------------------------------- |
 | `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions                     |
 | `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes)       |
+| `fx.deadLetters(signal)`                    | read            | Dead-lettered messages for that signal             |
 | `fx.send(template, opts)`                   | send            | Reach a human (email · SMS · …)                    |
 | `fx.ask(prompt, input)`                     | ask             | Call a versioned AI prompt                         |
 | `fx.run(agent, input)`                      | ask             | Run a bounded agent                                |
 | `fx.call(flow, input)`                      | call            | Invoke another flow                                |
 | `fx.vault.get(contract)`                    | secret          | Read a secret (`Redacted`; logs masked)            |
-| `fx.clock.now()` / `.sleep(…)`              | —               | Injected time / durable sleep                      |
+| `fx.clock.now/ago/fromNow/duration/sleep`   | —               | Injected instants, spans, durable sleep            |
 | `fx.cache.get/set`                          | —               | Shared cache with effect-aware invalidation        |
 | `fx.step(name, fn, { undo? })`              | —               | Named durable step — optional LIFO undo on failure |
 | `fx.all` / `fx.race` / `fx.retry`           | —               | Structured concurrency + backoff retry             |
@@ -366,6 +371,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`)
 
@@ -270,12 +266,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>
@@ -313,6 +315,7 @@ Keying an authenticated endpoint by IP punishes shared NAT.
 
 ## 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`