okengine 0.19.9 → 0.20.0

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

@@ -24,7 +24,7 @@ For developers ranking rows on okengine — mark columns, query with `fx.store(d
 <Step>
 ### Mark columns and bind a route
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { field, store } from "okengine";
 
 export const articles = store.schema.table("articles", {
@@ -98,7 +98,7 @@ From BM25-only ranking to hybrid LSH, fusion, and opt-in rerank:
 
 Title carries twice the BM25F field weight of body. No `ai` element, no `.embed()`:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { field, store } from "okengine";
 
 export const articles = store.schema.table("articles", {
@@ -283,7 +283,7 @@ Each searchable column binds with `field.text().searchable(…)` (optionally `.e
 
 Mark the text fields you want ranked. No AI, no shadow vector columns:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { field, store } from "okengine";
 
 export const articles = store.schema.table("articles", {
@@ -307,7 +307,7 @@ retrieval (`plainto_tsquery('english', …)`).
 Chain `.embed()` **after** `.searchable()`. Pass `{ model, dims }` on the field, or
 inherit the project default:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { field, store, ai } from "okengine";
 
 const embedder = ai.model("embedder", {
@@ -348,7 +348,7 @@ oke({
 });
 ```
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 body: field.text().searchable().embed(), // inherits model + dims
 caption: field.text().searchable().embed({ model: captionEmbedder }), // dims still inherit
 alt: field.text().searchable().embed({ model: captionEmbedder, dims: 384 }),

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

@@ -22,7 +22,7 @@ For developers modeling domain data on okengine — mark columns, push schema, q
 <Step>
 ### Define a table and bind the store
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { store, field } from "okengine";
 
 export const posts = store.schema.table("posts", {
@@ -81,9 +81,9 @@ Response:
 
 </Steps>
 
-<Callout title="Pathless declare">
-  Starters often pass the whole decl module: `store.sql("app", {schema})` where `schema` is `import
-  * as schema from "@/db/schema.decl"`. Named keys and the exported table handles are equivalent.
+<Callout title="Two declare layouts">
+  One file (`schema.ts`, blank) or a folder (`schema/`, one table per file — shorter). Both import
+  as `@/db/schema`. Do not keep the file and the folder in the same app.
 </Callout>
 
 ## Progressive Patterns
@@ -97,7 +97,7 @@ Explore SQL from a bare table to classified columns, CRUD factory, and RLS:
 `field.id()` is `text` + auto id on insert. Use `.okid()` on an existing text
 column when you want the same default without the sugar factory:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { store, field } from "okengine";
 
 export const notes = store.schema.table("notes", {
@@ -171,7 +171,7 @@ Pass extras as the **third argument array**. Helpers take SQL/JS column
 **names** (strings) and stamp `oke.gate()` / `oke.user()` / `oke.has_scope()`
 predicates:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 import { store, field } from "okengine";
 
 export const tasks = store.schema.table(
@@ -200,23 +200,23 @@ otherwise.
 
 Factories mirror Drizzle pg-core names. Chain modifiers after the factory:
 
-| Factory                                                  | Infers             | Notes                                                                                                                                                         |
-| -------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `field.id()`                                             | `string`           | `text` + auto id on insert (`≡ field.text().okid()`)                                                                                                          |
-| `field.okid()`                                           | `string`           | Pins OK ID on a text column                                                                                                                                   |
-| `field.text()` / `varchar` / `char`                      | `string`           | Optional `{ length?, enum? }`                                                                                                                                 |
-| `field.boolean()`                                        | `boolean`          |                                                                                                                                                               |
-| `field.smallint()` / `integer()`                         | `number`           |                                                                                                                                                               |
-| `field.bigint({ mode? })`                                | `number` (default) | `mode`: `"number"` · `"bigint"` · `"string"`                                                                                                                  |
-| `field.serial()` / `smallserial()` / `bigserial()`       | `number`           | NOT NULL by SQL physics                                                                                                                                       |
-| `field.numeric()` / `decimal()`                          | `string` (default) | Exact decimal; `{ precision?, scale?, mode? }`                                                                                                                |
-| `field.real()` / `doublePrecision()`                     | `number`           | Float4 / float8                                                                                                                                               |
-| `field.json()` / `jsonb()`                               | generic            | Narrow with `field.json<MyShape>()`                                                                                                                           |
-| `field.uuid()`                                           | `string`           |                                                                                                                                                               |
-| `field.time()` / `timestamp()` / `date()` / `interval()` | see type           | `timestamp` / `date` default to `Date`; `{ mode: "string" }` for ISO. On write, finite epoch-ms numbers (e.g. `fx.clock.now()`) coerce to `Date` for Postgres |
-| `field.point()` / `line()`                               | tuple              | `{ mode: "xy" }` / `"abc"` for objects                                                                                                                        |
-| `field.bytea()`                                          | `Buffer`           |                                                                                                                                                               |
-| `field.inet()` / `cidr()` / `macaddr()` / `macaddr8()`   | `string`           |                                                                                                                                                               |
+| Factory                                                  | Infers             | Notes                                                                                                                                                                                   |
+| -------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `field.id()`                                             | `string`           | `text` + auto id on insert (`≡ field.text().okid()`)                                                                                                                                    |
+| `field.okid()`                                           | `string`           | Pins OK ID on a text column                                                                                                                                                             |
+| `field.text()` / `varchar` / `char`                      | `string`           | Optional `{ length?, enum? }`                                                                                                                                                           |
+| `field.boolean()`                                        | `boolean`          |                                                                                                                                                                                         |
+| `field.smallint()` / `integer()`                         | `number`           |                                                                                                                                                                                         |
+| `field.bigint({ mode? })`                                | `number` (default) | `mode`: `"number"` · `"bigint"` · `"string"`                                                                                                                                            |
+| `field.serial()` / `smallserial()` / `bigserial()`       | `number`           | NOT NULL by SQL physics                                                                                                                                                                 |
+| `field.numeric()` / `decimal()`                          | `string` (default) | Exact decimal; `{ precision?, scale?, mode? }`                                                                                                                                          |
+| `field.real()` / `doublePrecision()`                     | `number`           | Float4 / float8                                                                                                                                                                         |
+| `field.json()` / `jsonb()`                               | generic            | Narrow with `field.json<MyShape>()`                                                                                                                                                     |
+| `field.uuid()`                                           | `string`           |                                                                                                                                                                                         |
+| `field.time()` / `timestamp()` / `date()` / `interval()` | see type           | `timestamp` / `date` default to `Date`; `{ mode: "string" }` for ISO. On write and in WHERE, finite epoch-ms (`fx.clock.now()`) and parseable ISO strings coerce to `Date` for Postgres |
+| `field.point()` / `line()`                               | tuple              | `{ mode: "xy" }` / `"abc"` for objects                                                                                                                                                  |
+| `field.bytea()`                                          | `Buffer`           |                                                                                                                                                                                         |
+| `field.inet()` / `cidr()` / `macaddr()` / `macaddr8()`   | `string`           |                                                                                                                                                                                         |
 
 | Chain                                                    | Meaning                                                                                         |
 | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -238,21 +238,71 @@ suffix (`sql:app`).
 | `classify`    | `table → column → tags` | `{}`       | Explicit tags; wins over schema-derived on conflict |
 | `description` | `string`                | store name | Console / docs label                                |
 
-**Named keys** — pass the tables you care about:
+Pick **one** layout. `oke db` discovers `schema.ts` first, else `schema/index.ts`.
+`schema.decl.ts` still resolves. `db.declare` overrides.
 
-```typescript
-export const db = store.sql("app", { schema: { posts, notes } });
-```
+<Tabs items={["Single file", "Folder"]}>
 
-**Module star** — starters re-export everything from the decl file:
+<Tab value="Single file">
+
+Blank starter. Add `store.schema.table` exports in one module. When it grows,
+split into the folder and **delete** `schema.ts`.
+
+```typescript title="src/db/schema.ts"
+import { store, field } from "okengine";
+
+export const posts = store.schema.table("posts", {
+  id: field.id().primaryKey(),
+  title: field.text().notNull(),
+});
+```
 
 ```typescript title="src/core.ts"
 import { store } from "okengine";
-import * as schema from "@/db/schema.decl";
+import * as schema from "@/db/schema";
+
+export const db = store.sql("app", { schema });
+```
+
+</Tab>
+
+<Tab value="Folder">
+
+Shorter and Keel. One file per table; the barrel is the declare module.
+
+```typescript title="src/db/schema/posts.ts"
+import { store, field } from "okengine";
+
+export const posts = store.schema.table("posts", {
+  id: field.id().primaryKey(),
+  title: field.text().notNull(),
+});
+```
+
+```typescript title="src/db/schema/index.ts"
+export * from "./posts.ts";
+```
+
+```typescript title="src/core/store.ts"
+import { store } from "okengine";
+import * as schema from "@/db/schema";
 
 export const db = store.sql("app", { schema });
 ```
 
+</Tab>
+
+</Tabs>
+
+**Named keys** — pass only the tables you care about:
+
+```typescript
+export const db = store.sql("app", { schema: { posts, notes } });
+```
+
+`oke db` / `oke dev` emit generated Drizzle under `src/db/drizzle/` (one file
+per table + `index.ts`). `oke dev` watches the declare path you picked.
+
 **Consequence:** every `fx.store(db)` touch stamps `reads` / `writes` as
 `sql:app` on the Flow — Manifest, Console, and least privilege follow from that.
 
@@ -306,7 +356,8 @@ export const get = on(
 );
 ```
 
-`findById(notes, id)` is the same PK path without a fluent chain.
+`findById(notes, id)` is the same PK path without a fluent chain. Declared `out` projects the
+row — return it as-is.
 
 </Tab>
 
@@ -332,6 +383,8 @@ export const create = on(
 );
 ```
 
+`out` projects the returned row — Date timestamps become ISO-8601; extra columns strip.
+
 </Tab>
 
 <Tab value="Update">
@@ -671,7 +724,7 @@ Pass extras after the column map:
 <Accordion title="Policy helpers">
   Helpers take **string** column / gate / scope names and stamp predicates:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 export const bookings = store.schema.table(
   "bookings",
   {
@@ -717,7 +770,7 @@ export const shared = store.schema.table(
   `store.schema.relations` records one/many links for Drizzle emit — it does
   **not** add `fx.store(db).query.…`:
 
-```typescript title="src/db/schema.decl.ts"
+```typescript title="src/db/schema.ts"
 export const links = store.schema.table("links", {
   id: field.id().primaryKey(),
   code: field.text().notNull().unique(),
@@ -771,7 +824,7 @@ recorded that identity yet. Categories:
 ```typescript title="src/db/seed/index.ts"
 import { defineSeed, type Fx } from "okengine";
 import { db } from "@/core";
-import { notes } from "@/db/schema.decl";
+import { notes } from "@/db/schema";
 
 async function welcomeNote(fx: Fx) {
   await fx.store(db).upsert(
@@ -898,6 +951,11 @@ export default defineConfig({
   columns on `store.resource(…, { list: { … } })` or your `liveQuery` options.
 </Accordion>
 
+<Accordion title="@/db/schema hits schema.ts, not my schema/ folder">
+  Cause: both `schema.ts` and `schema/` exist — the file wins for the import and for `oke db`
+  discovery. Delete `schema.ts` after you split, or set `db.declare` to `schema/index.ts`.
+</Accordion>
+
 <Accordion title="fx.store(db).query is undefined">
   There is no Relational Query Builder on the session handle. Use fluent `select` / `insert` /
   `update` / `page`, or `store.resource` for CRUD. `store.schema.relations` is emit metadata only.

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

@@ -265,11 +265,9 @@ export default defineConfig({
 | `memory`  | In-process map                   | Tests                                        |
 | `managed` | Remote provider bag              | AWS / Azure / GCP / Doppler / 1Password      |
 
-create-oke Notes starters pin `vault.dev: "vault"` and declare stack + app contracts in
-`src/vault.ts` (`vault.secret` / `vault.config`). Console Vault lists those contracts —
-values still resolve from `.env.local`, process env, `oke vault set`, or `dev:` /
-`vault.fromDocker` fallbacks. Pass `oke({ secrets: NOTES_VAULT })` so configs resolve
-(only `vault.secret` auto-registers).
+create-oke starters pin `vault.dev: "vault"` and declare contracts in `src/vault.ts` (blank) or `src/core/vault.ts` (shorter).
+Pass `oke({ secrets })` so configs resolve (only `vault.secret` auto-registers).
+Values still come from `.env.local`, process env, `oke vault set`, or `dev:` / `vault.fromDocker`.
 
 Managed provider ids: `aws-secrets-manager` · `azure-key-vault` · `gcp-secret-manager` ·
 `doppler` · `1password`. Env knobs: [Environment variables](/docs/reference/environment-variables).

package/site/content/docs/plugins/magic-link.mdx

@@ -89,8 +89,9 @@ const { data } = await api.auth.verifyMagicLink({ token });
 | `auth.requestMagicLink` | `POST /auth/magic-link/request` | `gate.public` + otp rate |
 | `auth.verifyMagicLink`  | `POST /auth/magic-link/verify`  | `gate.public` + otp rate |
 
-**Consequence:** the plugin contributes the `auth-magic-link` Channel template and EN/AR
-catalog bodies (`{{link}}`, `{{token}}`). Override copy by merging your own catalog at boot.
+**Consequence:** the plugin contributes `auth-magic-link` with EN/AR `catalog`
+on the template (`{{link}}`, `{{token}}`). Override copy with
+`oke({ channel.catalog })` or `.channelCatalog(…)` — later locale wins.
 
 ## Delivery drivers
 
@@ -155,7 +156,7 @@ unit tests without SMTP, set `exposeDevToken: true`.
 
 - [OTP](/docs/plugins/otp) — numeric code instead of a link
 - [Gate](/docs/elements/gate) — `gate.auth`
-- [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
+- [Channel](/docs/elements/channel) — `.template({ catalog })`, `fx.send`, Mailpit
 
 ## Next
 

package/site/content/docs/plugins/otp.mdx

@@ -148,8 +148,9 @@ app mode, or bind a Verify-capable driver (for example `taqnyat`).
 | Auto failover   | On real provider send errors, sently `FallbackTransport` walks remaining media; Taqnyat WhatsApp may use `sendWithFailover` |
 | User resend     | Explicit `resend` with `channel` — not automatic                                                                            |
 
-Templates: `auth-otp-email`, `auth-otp-sms`, `auth-otp-whatsapp` (EN/AR,
-`{{otp}}`). SMS here is a plain message — not Taqnyat Verify.
+Templates `auth-otp-email` / `auth-otp-sms` / `auth-otp-whatsapp` ship EN/AR
+`catalog` on the declare (`{{otp}}`). SMS is a plain message — not Taqnyat Verify.
+Override copy with `oke({ channel.catalog })` or `.channelCatalog(…)` (later locale wins).
 
 ## Options
 
@@ -209,7 +210,7 @@ In `local` / `test` the `console` driver captures messages. Use
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
 - [Two-factor](/docs/plugins/two-factor) — email OTP / TOTP as a **second** factor after password (distinct from this primary `/auth/otp` sign-in)
-- [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
+- [Channel](/docs/elements/channel) — `.template({ catalog })`, `fx.sendOtp`, Mailpit
 - [Gate](/docs/elements/gate) — `gate.auth`
 
 ## Next

package/site/content/docs/plugins/two-factor.mdx

@@ -127,6 +127,9 @@ Disable also requires step-up when 2FA is already enabled.
 `{ twoFactorRequired, challengeId, method, userId }` (no tokens) when the
 account has 2FA enabled. Complete login only via `twoFactorVerify`.
 
+Email OTP as second factor sends `auth-2fa-email` (`{{otp}}`, EN/AR `catalog` on
+the template). Overlay copy the same way as other Channel templates.
+
 ## Troubleshooting
 
 <Accordions>
@@ -160,6 +163,7 @@ challenge. A recovery code works once for TOTP, then is consumed.
 
 ## Learn more
 
+- [Channel](/docs/elements/channel) — `auth-2fa-email` catalog and Mailpit
 - [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against

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

@@ -8,7 +8,7 @@ source: "docs/spec/unified-theory.md"
 Every provider below speaks a protocol oke already drives — Postgres wire or Redis wire.
 Hand the connection string to that driver; no new driver id, no Flow code changes.
 
-These managed providers are real, working infrastructure choices behind the same two templates (`standard`, `advanced`) and the same eight elements — not alternative products or separate frameworks.
+These managed providers are real, working infrastructure choices behind the same templates (`blank`, `shorter`) and the same eight elements — not alternative products or separate frameworks.
 
 <Callout title="The one rule">
   Vendor choice lives in a connection URL (`DATABASE_URL` / `REDIS_URL`) — never in

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

@@ -8,7 +8,7 @@ source: "docs/spec/unified-theory.md"
 Every recipe below is already wired into `oke docker` — pin an image in `oke.config.ts`
 and get env, healthcheck, and a connection URL for free.
 
-These recipes are real, working infrastructure choices behind the same two templates (`standard`, `advanced`) and the same eight elements — not alternative products or separate frameworks.
+These recipes are real, working infrastructure choices behind the same templates (`blank`, `shorter`) and the same eight elements — not alternative products or separate frameworks.
 
 <Callout title="The one rule">
   Vendor choice lives in `images[…]` — never in `drivers.*`, which only ever say protocol ids

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

@@ -24,8 +24,8 @@ writes.
 ### Scaffold an app
 
 ```bash
-bunx create-oke@latest notes --yes
-cd notes
+bunx create-oke@latest my-app --yes
+cd my-app
 ```
 
 </Step>
@@ -98,7 +98,7 @@ oke start               # production entry (Docker CMD)
 
 ```bash
 bunx create-oke@latest my-app --yes
-bunx create-oke@latest my-app -t advanced --locales ar --proxy caddy
+bunx create-oke@latest my-app -t shorter --locales ar --proxy caddy
 bunx create-oke@latest          # interactive (TTY only)
 ```
 
@@ -164,7 +164,7 @@ oke db search-backfill notes --batch 500
 
 | Flag                             | Meaning                                                   |
 | -------------------------------- | --------------------------------------------------------- |
-| `-t, --template <id>`            | `standard` (default) or `advanced`                        |
+| `-t, --template <id>`            | `blank` (default) · `shorter`                             |
 | `--sql <id>`                     | Store SQL dialect — only `postgres` (test stays `pglite`) |
 | `-y, --yes`                      | No prompts; defaults + bun install (no `oke dev`)         |
 | `--install` / `--no-install`     | Run or skip `bun install` after scaffold                  |
@@ -175,6 +175,9 @@ oke db search-backfill notes --batch 500
 | `--proxy <id>` / `--no-proxy`    | `none` · `caddy` · `traefik` · `nginx`                    |
 | `-h, --help`                     | Show help                                                 |
 
+`blank` is an empty app (`main.health` + Store/Vault). `shorter` is a URL shortener
+(`POST /links`, public `GET /:code`).
+
 ## Troubleshooting
 
 <Accordions>

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

@@ -212,13 +212,13 @@ Runs retention and redaction — **not** the same key as `drivers.runs`.
 
 Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated to `oke schema generate`.
 
-| Option      | Default                      | Meaning                                                                   |
-| ----------- | ---------------------------- | ------------------------------------------------------------------------- |
-| `autoPush`  | `true`                       | Auto-run `db push` on schema change under `oke dev`; forced off in `prod` |
-| `config`    | `"drizzle.config.ts"`        | Path to the drizzle-kit config                                            |
-| `declare`   | `"src/db/schema.decl.ts"`    | Abstract schema module (`store.schema.table` exports)                     |
-| `generated` | `"src/db/schema.drizzle.ts"` | Where `oke db` emits dialect Drizzle                                      |
-| `entry`     | `src/app.ts`                 | App entry for collecting plugin table contributions                       |
+| Option      | Default               | Meaning                                                                          |
+| ----------- | --------------------- | -------------------------------------------------------------------------------- |
+| `autoPush`  | `true`                | Auto-run `db push` on schema change under `oke dev`; forced off in `prod`        |
+| `config`    | `"drizzle.config.ts"` | Path to the drizzle-kit config                                                   |
+| `declare`   | auto                  | `schema.ts` (file) if present, else `schema/index.ts` (folder). Set to override. |
+| `generated` | auto                  | `src/db/drizzle/index.ts`. Set to override.                                      |
+| `entry`     | `src/app.ts`          | App entry for collecting plugin table contributions                              |
 
 ## topology
 

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

@@ -78,35 +78,35 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 
 ## OKE numeric codes
 
-| Code   | Name                   | Cause                                                  | Fix                                                       |
-| ------ | ---------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
-| `1001` | undeclared read        | Flow reads a resource not in `effects.reads`           | Add it to the flow's `effects.reads`                      |
-| `1002` | undeclared write       | Flow writes a resource not in `effects.writes`         | Add it to the flow's `effects.writes`                     |
-| `1003` | undeclared emit        | Flow emits a signal not in `effects.emits`             | Add it to the flow's `effects.emits`                      |
-| `1004` | undeclared send        | Flow sends a template not in `effects.sends`           | Add it to the flow's `effects.sends`                      |
-| `1005` | undeclared ask         | Flow asks a prompt not in `effects.asks`               | Add it to the flow's `effects.asks`                       |
-| `1006` | undeclared secret      | Flow reads a secret not in `effects.secrets`           | Add it to the flow's `effects.secrets`                    |
-| `1007` | undeclared call        | Flow calls a flow not in `effects.calls`               | Add it to the flow's `effects.calls`                      |
-| `1008` | undeclared fetch       | Flow fetches a host not in `effects.fetches`           | Add the hostname to the flow's `effects.fetches`          |
-| `1009` | undeclared embed       | Flow embeds with a model not in `effects.embeds`       | Add it to the flow's `effects.embeds`                     |
-| `1020` | no effects declared    | Flow has no `effects` and no Manifest to infer from    | Run `oke build` / `oke dev`, or declare effects           |
-| `1030` | adopt barrel stale     | A `src/flows/<unit>` folder was not adopted            | Run `oke dev` or `oke build` to regenerate `generated.ts` |
-| `1040` | HTTP path unresolved   | Pathless `http.get()` never received a file-tree stamp | Import `@/flows/generated`, or pass `http.get("/…")`      |
-| `1041` | HTTP route clash       | Two HTTP flows share the same method + path            | Give each flow a unique method + path                     |
-| `1045` | HTTP flow unnamed      | Adopted HTTP flow still has no `unit.export`           | Export from `flows/<unit>/` or pass a named `flow`        |
-| `1050` | live exposure dup      | Same signal, gates, and match on two GET routes        | Change the gate or path-param filter                      |
-| `1060` | MCP tool duplicate     | Two MCP tool bindings share the same tool name         | Give each MCP tool exposure a unique name                 |
-| `1070` | flow name duplicate    | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export  |
-| `1071` | once-signal multi-flow | Two different Flows bound to the same `signal.once`    | Use `signal.broadcast`, or bind only one Flow             |
-| `1072` | flow unnamed           | Signal / Clock consumer still has no `unit.export`     | Export from `flows/<unit>/` or pass a named `flow`        |
-| `1110` | schema missing         | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment             |
-| `1210` | live resume gap        | `Last-Event-ID` is not on the retained tape            | Reconnect without the cursor; remaining tape replays      |
-| `1240` | orphan emit            | Emit with zero subscribers and `optional` false        | Add `on(signal, …)` or declare `optional: true`           |
-| `1250` | signal schema          | Emit payload failed the signal's `schema`              | Pass a payload that matches `schema`, or remove it        |
-| `1605` | channel schema         | Send payload failed the template's `schema`            | Fix template `data` payload or the template `schema`      |
-| `1810` | tenant required        | Tenant-scoped op with no `fx.tenant.id`                | `switchTenant`, signed `tid`, or tenant header            |
-| `1820` | tenant not member      | Client-supplied tenant id is not a membership          | Pick from `listTenants` or add the user as a member       |
-| `1830` | tenant unknown scope   | Tenant role used an invented or `console:*` scope      | Use a declared application scope                          |
+| Code   | Name                   | Cause                                                  | Fix                                                             |
+| ------ | ---------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
+| `1001` | undeclared read        | Flow reads a resource not in `effects.reads`           | Add it to the flow's `effects.reads`                            |
+| `1002` | undeclared write       | Flow writes a resource not in `effects.writes`         | Add it to the flow's `effects.writes`                           |
+| `1003` | undeclared emit        | Flow emits a signal not in `effects.emits`             | Add it to the flow's `effects.emits`                            |
+| `1004` | undeclared send        | Flow sends a template not in `effects.sends`           | Add it to the flow's `effects.sends`                            |
+| `1005` | undeclared ask         | Flow asks a prompt not in `effects.asks`               | Add it to the flow's `effects.asks`                             |
+| `1006` | undeclared secret      | Flow reads a secret not in `effects.secrets`           | Add it to the flow's `effects.secrets`                          |
+| `1007` | undeclared call        | Flow calls a flow not in `effects.calls`               | Add it to the flow's `effects.calls`                            |
+| `1008` | undeclared fetch       | Flow fetches a host not in `effects.fetches`           | Add the hostname to the flow's `effects.fetches`                |
+| `1009` | undeclared embed       | Flow embeds with a model not in `effects.embeds`       | Add it to the flow's `effects.embeds`                           |
+| `1020` | no effects declared    | Flow has no `effects` and no Manifest to infer from    | Run `oke build` / `oke dev`, or declare effects                 |
+| `1030` | adopt barrel stale     | A `src/flows/<unit>` folder was not adopted            | Run `oke dev` or `oke build` to regenerate `src/flows/index.ts` |
+| `1040` | HTTP path unresolved   | Pathless `http.get()` never received a file-tree stamp | Import `@/flows`, or pass `http.get("/…")`                      |
+| `1041` | HTTP route clash       | Two HTTP flows share the same method + path            | Give each flow a unique method + path                           |
+| `1045` | HTTP flow unnamed      | Adopted HTTP flow still has no `unit.export`           | Export from `flows/<unit>/` or pass a named `flow`              |
+| `1050` | live exposure dup      | Same signal, gates, and match on two GET routes        | Change the gate or path-param filter                            |
+| `1060` | MCP tool duplicate     | Two MCP tool bindings share the same tool name         | Give each MCP tool exposure a unique name                       |
+| `1070` | flow name duplicate    | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export        |
+| `1071` | once-signal multi-flow | Two different Flows bound to the same `signal.once`    | Use `signal.broadcast`, or bind only one Flow                   |
+| `1072` | flow unnamed           | Signal / Clock consumer still has no `unit.export`     | Export from `flows/<unit>/` or pass a named `flow`              |
+| `1110` | schema missing         | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment                   |
+| `1210` | live resume gap        | `Last-Event-ID` is not on the retained tape            | Reconnect without the cursor; remaining tape replays            |
+| `1240` | orphan emit            | Emit with zero subscribers and `optional` false        | Add `on(signal, …)` or declare `optional: true`                 |
+| `1250` | signal schema          | Emit payload failed the signal's `schema`              | Pass a payload that matches `schema`, or remove it              |
+| `1605` | channel schema         | Send payload failed the template's `schema`            | Fix template `data` payload or the template `schema`            |
+| `1810` | tenant required        | Tenant-scoped op with no `fx.tenant.id`                | `switchTenant`, signed `tid`, or tenant header                  |
+| `1820` | tenant not member      | Client-supplied tenant id is not a membership          | Pick from `listTenants` or add the user as a member             |
+| `1830` | tenant unknown scope   | Tenant role used an invented or `console:*` scope      | Use a declared application scope                                |
 
 <Callout title="Effects are usually inferred">
   The 1001–1007 · 1008 · 1009 family exists for flows that declare effects explicitly. Most apps
@@ -167,7 +167,7 @@ Thrown by specific subsystems — each names its own cause:
 </Accordion>
 
 <Accordion title="OKE1040 pathless HTTP never stamped">
-  Import `@/flows/generated`, or pass an explicit path: `http.get("/users/:id")`.
+  Import `@/flows`, or pass an explicit path: `http.get("/users/:id")`.
 </Accordion>
 
 <Accordion title="OKE1041 method + path bound twice">

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

@@ -211,7 +211,8 @@ const rows = await fx.using(
 | `fx.send(template, { to?, data?, via?, … })` | `send`  | `via` orders fallback; `locale` / `profileLocale` / `acceptLanguage` feed the locale chain |
 
 Omit locale opts and the send uses `fx.locale`. Dry runs record _would have fired_ and never
-contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Channel](/docs/elements/channel)).
+contact a provider. Bodies live on `.template({ catalog })` (`{{field}}`, not ICU — see
+[Channel](/docs/elements/channel)).
 
 ## Outbound HTTP
 
@@ -255,13 +256,13 @@ host tooltip).
 
 ## Clock
 
-| Signature                         | Notes                                                               |
-| --------------------------------- | ------------------------------------------------------------------- |
-| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"                         |
-| `fx.clock.ago(duration)`          | Instant before now (`"30d"` → now − 30 days)                        |
-| `fx.clock.fromNow(duration)`      | Instant after now (`"14d"` → now + 14 days)                         |
-| `fx.clock.duration(duration)`     | Span in ms — offset a stored instant (`createdAt + duration("7d")`) |
-| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise               |
+| Signature                         | Notes                                                                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"; pass into SQL timestamps as-is (store coerces numbers and ISO strings to `Date`) |
+| `fx.clock.ago(duration)`          | Instant before now (`"30d"` → now − 30 days)                                                                                  |
+| `fx.clock.fromNow(duration)`      | Instant after now (`"14d"` → now + 14 days)                                                                                   |
+| `fx.clock.duration(duration)`     | Span in ms — offset a stored instant (`createdAt + duration("7d")`)                                                           |
+| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise                                                                         |
 
 Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400_000 ms, not a calendar day. Unknown strings parse as `0`.
 
@@ -293,6 +294,8 @@ keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control. Pass `fx.stream(...)` into `fx.json.stream` to reach the HTTP client token-by-token.
 
+When `out` is set, success values are projected onto it (`fx.json.create(row)`, `return row`, `fx.json.withQuery(rows, input)`). Date timestamps and temporal epoch-ms (`*At` / `*_at` / `at`) become ISO-8601 and extra keys strip. A parse miss is not a client error.
+
 ## Logging, i18n, ids
 
 | Signature                                  | Notes                                                       |
@@ -355,6 +358,11 @@ to the key — see [Gate](/docs/elements/gate#api-keys).
   Type the parameter as `Fx` from `okengine`, not a hand-rolled structural type.
 </Accordion>
 
+<Accordion title="I mapped Date columns to ISO by hand">
+  Declared `out` projects success values. `fx.json.create(row)`, `return row`, and
+  `fx.json.withQuery(rows, input)` are enough — extra columns strip. A miss is not a client error.
+</Accordion>
+
 </Accordions>
 
 ## Learn more

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

@@ -257,8 +257,8 @@ until registered. Full tables: [Errors](/docs/reference/errors).
 
 ## Channel catalogs are separate
 
-`fx.send` templates use `{{field}}` bodies and their own `locales` list — not
-ICU. Omit `locale` / `profileLocale` / `acceptLanguage` on `fx.send` and the
+`fx.send` interpolates `{{field}}` from `.template({ catalog })` — not ICU, not
+`fx.t`. Omit `locale` / `profileLocale` / `acceptLanguage` on `fx.send` and the
 send uses `fx.locale`. Details: [Channel](/docs/elements/channel).
 
 ## Troubleshooting
@@ -280,8 +280,8 @@ the app (proxies sometimes strip it).
 </Accordion>
 <Accordion title="Email body is still English while fx.t is Arabic">
 
-Channel catalogs are separate `{{field}}` strings. Add an `ar` body on the
-template / plugin catalog; `fx.t` does not translate Channel templates.
+Channel catalogs are separate `{{field}}` strings. Add an `ar` key on
+`.template({ catalog })`; `fx.t` does not translate Channel templates.
 
 </Accordion>
 <Accordion title="TypeScript rejects a key that exists at runtime">

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

@@ -54,7 +54,7 @@ export const app = oke({ name: "shop", env: "dev" }).plug(audit);
 <Step>
 ### Everything derives as usual
 
-Plugin flows appear in the Manifest, plugin tables land in `schema.drizzle.ts` on the next `oke db push`, plugin panels show up in the Console. No extra wiring — a contribution is ordinary OKE, just authored elsewhere.
+Plugin flows appear in the Manifest, plugin tables land in `src/db/drizzle/` on the next `oke db push`, plugin panels show up in the Console. No extra wiring — a contribution is ordinary OKE, just authored elsewhere.
 
 </Step>
 
@@ -76,8 +76,8 @@ Every method below exists on both the fluent definition and the boot-time builde
 | `.clock(decl)`                   | A named clock schedule — merged into boot clocks                                              |
 | `.signal(decl)`                  | A signal declaration — merged into boot signals                                               |
 | `.gate(decl)`                    | A gate declaration — merged into boot gates                                                   |
-| `.channelTemplate(decl)`         | A channel template — merged into boot channel templates                                       |
-| `.channelCatalog(catalog)`       | Template body catalog entries — merged into boot channel catalog (`{{field}}` interpolation)  |
+| `.channelTemplate(decl)`         | `channel.<medium>().template(…)` — `catalog` on the decl drains into boot                     |
+| `.channelCatalog(catalog)`       | Overlay bodies after `.template({ catalog })` (`{{field}}`); later locale wins                |
 | `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
 | `.image(role, recipe)`           | An image recipe for a docker role                                                             |
 | `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
@@ -226,7 +226,7 @@ Extending an existing **app-owned** table with plugin columns is not supported i
     two configurations of one plugin would silently diverge. Pass identical config, or rename one
     instance.
   </Accordion>
-  <Accordion title="My plugin table is missing from schema.drizzle.ts">
+  <Accordion title="My plugin table is missing from drizzle/">
     The CLI reads table contributions from the live app entry. Make sure the plugin is actually
     `.plug()`ed in `src/app.ts` (or `db.entry` if overridden), then re-run `oke db push`.
   </Accordion>