okengine 0.19.9 → 0.21.0

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

@@ -318,13 +318,12 @@ import { uploads } from "@/core";
 export const get = on(
   http.get({
     in: z.object({ id: z.string(), name: z.string() }),
-    errors: { NotFound: z.object({ key: z.string() }) },
   }),
   flow({
     do: async ({ id, name }, fx) => {
       const key = `notes/${id}/${name}`;
       const bytes = await fx.store(uploads).get(key);
-      if (!bytes) return fx.fail("NotFound", { key });
+      if (!bytes) return fx.fail.notFound({ key });
       return { key, size: bytes.byteLength };
     },
   }),
@@ -582,7 +581,7 @@ export default defineConfig({
   },
   images: {
     store: {
-      files: "rustfs/rustfs:1.0.0-rc.5",
+      files: "rustfs/rustfs:1.0.0",
     },
   },
 });
@@ -607,8 +606,14 @@ For `s3`, Compose / env typically supply `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`,
 </Accordion>
 
 <Accordion title="Invalid object key">
-  Cause: `Invalid object key: …` on the `fs` driver when the key starts with `/` or contains `..`.
-  Use relative, non-escaping keys.
+  The `fs` driver rejects keys that start with `/` or contain `..`. HTTP is `Forbidden` **403**
+  (`reason: invalid_key`) — the key is not copied. Use relative, non-escaping keys.
+</Accordion>
+
+<Accordion title="S3 AccessDenied / disk full is InternalError">
+  `AccessDenied` / `EACCES` map to `Forbidden` **403**. Missing `get` stays `null`. `SlowDown` stays
+  thrown until `flow.retry` exhausts, then **503**. `NoSuchBucket` / `ENOSPC` are **503** — see
+  [Errors · Files auto-map](/docs/reference/errors#files-auto-map).
 </Accordion>
 
 <Accordion title="ERR_IMAGE_TOO_MANY_PIXELS">
@@ -644,6 +649,7 @@ For `s3`, Compose / env typically supply `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`,
 - [HTTP](/docs/elements/flow/http) — routes that accept uploads
 - [Vault](/docs/elements/vault) — credentials for S3 when you configure bindings
 - [fx](/docs/reference/fx) — `fx.store(decl)`
+- [Errors](/docs/reference/errors) — Files auto-map
 - [Configuration](/docs/reference/configuration) — `drivers.store.files`
 
 ## Next

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

@@ -24,7 +24,7 @@ For developers persisting domain data on okengine — one handle shape, drivers
 <Step>
 ### Declare a SQL store
 
-```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", {
@@ -49,17 +49,20 @@ import { db, notes } from "@/schema";
 export const create = on(
   http.post({
     in: z.object({ title: z.string().min(1) }),
+    out: z.object({ id: z.string(), title: z.string() }),
   }),
   flow({
     do: async ({ title }, fx) => {
       const id = fx.id();
-      await fx.store(db).insert(notes).values({ id, title });
-      return fx.json.create({ id, title });
+      const [row] = await fx.store(db).insert(notes).values({ id, title }).returning();
+      return fx.json.create(row);
     },
   }),
 );
 ```
 
+`out` projects the insert row — `createdAt` strips; Date timestamps become ISO-8601.
+
 </Step>
 
 <Step>
@@ -84,6 +87,11 @@ Response:
 
 </Steps>
 
+<Callout title="Two declare layouts">
+  One file (`schema.ts`) or a folder (`schema/`, one table per file). Both import as `@/db/schema`.
+  Pick one — see [SQL](/docs/elements/store/sql#declaring-stores).
+</Callout>
+
 <Callout title="Effects are inferred">
   Every `fx.store` touch is recorded on the Flow as `reads` / `writes` (`sql:app`, `kv:sessions`,
   `files:uploads`, …). That powers the Manifest, Console, cache invalidation, and least privilege —
@@ -109,12 +117,11 @@ import { db, notes } from "@/schema";
 export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -220,7 +227,7 @@ export default defineConfig({
     store: {
       sql: "postgres:18-alpine",
       kv: "redis:8-alpine",
-      files: "rustfs/rustfs:1.0.0-rc.5",
+      files: "rustfs/rustfs:1.0.0",
     },
   },
 });

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

@@ -262,7 +262,7 @@ export const get = on(
     do: async ({ token }, fx) => {
       const userId = await fx.store(sessions).get(`session:${token}`);
       if (userId === undefined || userId === null) {
-        return fx.fail("NotFound", { token });
+        return fx.fail.notFound({ token });
       }
       return { userId };
     },
@@ -599,6 +599,12 @@ Gate rate strategies inherit `drivers.store.kv` (no separate `drivers.gate`).
   does). Prefer prefix filters in admin Flows.
 </Accordion>
 
+<Accordion title="Redis down returns InternalError">
+  Connection / `CLUSTERDOWN` / `READONLY` map to `ServiceUnavailable` **503**. `BUSY` / `TRYAGAIN`
+  stay thrown until `flow.retry` exhausts, then **503**. `WRONGTYPE` stays `InternalError` — see
+  [Errors · KV auto-map](/docs/reference/errors#kv-auto-map).
+</Accordion>
+
 <Accordion title="I expected incr / setNx / fx.store.kv">
   Those helpers are not on the public handle. Use `get` / `set` / `delete` / `list` / `ttlMs` via
   `fx.store(decl)`. Gate rates use Redis Lua internally.
@@ -614,7 +620,7 @@ Gate rate strategies inherit `drivers.store.kv` (no separate `drivers.gate`).
 - [Gate](/docs/elements/gate) — rate buckets use Redis internally
 - [fx](/docs/reference/fx) — `fx.store(decl)`
 - [Configuration](/docs/reference/configuration) — `drivers.store.kv`
-- [Errors](/docs/reference/errors) — OKE1810
+- [Errors](/docs/reference/errors) — OKE1810 · KV auto-map
 
 ## Next
 

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"]}>
+
+<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";
 
-**Module star** — starters re-export everything from the decl file:
+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.
 
@@ -294,19 +344,19 @@ export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), title: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
 );
 ```
 
-`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 +382,8 @@ export const create = on(
 );
 ```
 
+`out` projects the returned row — Date timestamps become ISO-8601; extra columns strip.
+
 </Tab>
 
 <Tab value="Update">
@@ -351,7 +403,6 @@ export const update = on(
       id: z.string(),
       title: z.string().min(1).optional(),
     }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id, title }, fx) => {
@@ -359,7 +410,7 @@ export const update = on(
         await fx.store(db).update(notes).set({ title }).where(eq(notes.id, id));
       }
       const row = await fx.store(db).findById(notes, id);
-      if (!row) return fx.fail("NotFound", { id });
+      if (!row) return fx.fail.notFound({ id });
       return row;
     },
   }),
@@ -538,7 +589,7 @@ The URL id segment is always `:id`. Update is **PATCH**, not PUT.
 | `out`      | Schema    | _(required)_                     | Item shape (get / list / update return)                                  |
 | `update`   | Schema    | `in`                             | Patch fields. Wire body is `{ id, …patch }`                              |
 | `idSchema` | Schema    | `update`/`in` + `{ id: string }` | Replaces the update Flow `in` when set (include the id key)              |
-| `errors`   | error map | `{ NotFound }`                   | Typed failures on get / update / remove                                  |
+| `errors`   | error map | —                                | Extra domain codes. Built-in `NotFound` is always on                     |
 | `id`       | column    | table PK                         | Column bound to `:id`                                                    |
 | `list`     | object    | see List Options                 | List query grammar (`GET /notes`)                                        |
 | `breaking` | `boolean` | `false`                          | Marks the five Flows `breaking: true` (handwritten → resource migration) |
@@ -671,7 +722,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 +768,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 +822,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(
@@ -864,6 +915,11 @@ export default defineConfig({
   `oke db migrate` in that environment.
 </Accordion>
 
+<Accordion title="Unique insert is 500 InternalError">
+  Unique / exclusion maps to `Conflict` **409**; missing FK to `ForeignKey` **409**. See [Errors ·
+  SQL auto-map](/docs/reference/errors#sql-auto-map).
+</Accordion>
+
 <Accordion title="update().set().where(): condition required">
   Updates and deletes without a `where` are rejected (`delete().where(): condition required`). Pass
   a Drizzle condition or equality map — or use `delete(table, id)` for PK deletes.
@@ -898,6 +954,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.
@@ -918,7 +979,7 @@ export default defineConfig({
 - [HTTP · Resources](/docs/elements/flow/http#resources) — mount, live SSE, verb table
 - [Consumers · CDC](/docs/elements/flow/consumers#cdc) — `db.table(…).changed()`
 - [fx](/docs/reference/fx) — `fx.store` session
-- [Errors](/docs/reference/errors) — OKE1110 · OKE1041
+- [Errors](/docs/reference/errors) — OKE1110 · OKE1041 · SQL auto-map
 
 ## Next
 

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

@@ -196,13 +196,16 @@ Order (Console labels match these source ids):
 3. **`.env.local`** — local overrides (gitignored)
 4. **dev-fallback** — `dev:` on the contract (dev boot only)
 
-Miss every layer → `VaultBootError` listing **all** gaps in one pass (including
-`vault.env.required` names):
+Miss every layer → `VaultBootError` (TTY title **OKE1510**) listing **all** gaps in one pass
+(including `vault.env.required` names):
 
 ```text
-vault boot failed — 2 missing secret(s):
-  - STRIPE_KEY: Payments gateway key
-  - DATABASE_URL: Primary SQL URL
+◇  OKE1510
+│  2 secrets have no value in any resolution layer.
+│  - STRIPE_KEY
+│  - DATABASE_URL
+│  → Set each name (`oke vault set <name>`, or `.env.local`).
+│  https://oke.omqkhafi.dev/e/1510
 ```
 
 **Consequence:** fix every listed name before traffic — boot does not take a half-configured app.
@@ -265,11 +268,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).
@@ -299,9 +300,9 @@ Managed provider ids: `aws-secrets-manager` · `azure-key-vault` · `gcp-secret-
 <Accordions>
 
 <Accordion title="VaultBootError — N missing secret(s)">
-  Cause: `vault boot failed — N missing secret(s):` with every gap listed. On a TTY, `oke dev`
-  prompts each into `.env.local`; otherwise use `oke vault set` / env / managed, or a `dev:`
-  fallback. `vault.env.required` joins the same list.
+  TTY title **OKE1510**. Cause: N secrets have no value in any resolution layer, with every gap
+  listed. On a TTY, `oke dev` prompts each into `.env.local`; otherwise use `oke vault set` / env /
+  managed, or a `dev:` fallback. `vault.env.required` joins the same list.
 </Accordion>
 
 <Accordion title='vault: secret "…" is not loaded'>

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

@@ -209,9 +209,12 @@ capability check.
 Missing non-tenant contracts fail boot with every hole listed once:
 
 ```text
-vault boot failed — 2 missing secret(s):
-  - STRIPE_KEY: Stripe secret API key
-  - APP_WEBHOOK_SECRET: HMAC secret for outbound webhooks
+◇  OKE1510
+│  2 secrets have no value in any resolution layer.
+│  - STRIPE_KEY
+│  - APP_WEBHOOK_SECRET
+│  → Set each name (`oke vault set <name>`, or `.env.local`).
+│  https://oke.omqkhafi.dev/e/1510
 ```
 
 Fill gaps with:

package/site/content/docs/index.mdx

@@ -29,7 +29,7 @@ Master the mental model before exploring features:
   />
   <Card
     title="Try It"
-    description="From an empty folder to a Flow running in the Console — one sitting, minimal detour."
+    description="Scaffold, see the files, add GET and POST /users, save a row — then email if you want."
     href="/docs/understand/try-it"
   />
 </Cards>

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/recipes/rustfs.mdx

@@ -27,7 +27,7 @@ drivers: {
   },
 },
 images: {
-  store: { files: "rustfs/rustfs:1.0.0-rc.5" },
+  store: { files: "rustfs/rustfs:1.0.0" },
 },
 ```