okengine 0.13.0 → 0.15.2

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

@@ -71,7 +71,8 @@ export const sendConfirmation = on(
 
 </Steps>
 
-That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handles routing, retries, and dead-lettering.
+That's the loop for `once` and `broadcast`: declare → `fx.emit` → `on(signal, flow)`.
+`live` keeps the same emit; the listener is `bus.live()`, not a Flow.
 
 ## The three delivery physics
 
@@ -96,7 +97,7 @@ One placed order can need all three physics at once — pick a signal per job, n
 
 | Signal          | Mode        | Job                                                         |
 | --------------- | ----------- | ----------------------------------------------------------- |
-| `order-placed`  | `once`      | Fulfillment job — competing workers, retries, DLQ           |
+| `order-placed`  | `once`      | One job — competing workers, retries, DLQ                   |
 | `order-changed` | `broadcast` | Fan-out — cache invalidation **and** customer notification  |
 | `order-status`  | `live`      | Status feed — retained history a late subscriber can replay |
 
@@ -107,7 +108,7 @@ import { z } from "zod";
 export const orderPlaced = signal("order-placed", {
   schema: z.object({ orderId: z.string(), total: z.number() }),
   delivery: "once",
-  retries: 2,
+  retries: 3,
   deadLetter: true,
 });
 
@@ -126,25 +127,43 @@ export const orderStatus = signal("order-status", {
 });
 ```
 
-`once` — two fulfillment workers compete; **exactly one** claims each message (at-least-once; make the handler idempotent):
+A Flow **writes** all three tapes. `once` / `broadcast` **listen** with `on(signal, flow)`. `live` does not.
 
-```typescript title="src/flows/fulfillment/on-order.ts"
-on(
+```typescript title="src/flows/orders/place.ts"
+export const placeOrder = on(
+  http.post("/orders").public(),
+  flow("orders.place", {
+    in: z.object({ id: z.string(), total: z.number() }),
+    do: async (input, fx) => {
+      await fx.emit(orderPlaced, { orderId: input.id, total: input.total });
+      await fx.emit(orderChanged, { orderId: input.id, kind: "placed" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "placed" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "fulfilling" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "shipped" });
+    },
+  }),
+);
+```
+
+Stacked status emits are so replay is visible in one request. A real app emits as the order moves.
+
+`once` — the listener is `on(orderPlaced, flow)`. Two workers compete; **exactly one** claims each message (at-least-once; make the handler idempotent):
+
+```typescript title="src/flows/orders/send-confirmation.ts"
+export const sendConfirmation = on(
   orderPlaced,
-  flow("fulfillment.onOrder", {
-    do: async ({ orderId }, fx) => {
-      await fx.emit(orderChanged, { orderId, kind: "placed" });
-      await fx.emit(orderStatus, { orderId, status: "fulfilling" });
-      await fx.emit(orderStatus, { orderId, status: "shipped" });
+  flow("orders.sendConfirmation", {
+    do: async (input, fx) => {
+      await fx.send(orderConfirmed, { to: "user-1", data: input });
     },
   }),
 );
 ```
 
-`broadcast` — every subscriber gets its own copy of the same domain event:
+`broadcast` — every `on(orderChanged, flow)` gets its own copy. Neither Flow knows the other exists:
 
 ```typescript title="src/flows/orders/side-effects.ts"
-on(
+export const invalidateCache = on(
   orderChanged,
   flow("cache.onOrderChanged", {
     do: async ({ orderId }, fx) => {
@@ -153,7 +172,7 @@ on(
   }),
 );
 
-on(
+export const notifyCustomer = on(
   orderChanged,
   flow("notify.onOrderChanged", {
     do: async ({ orderId }, fx) => {
@@ -163,27 +182,38 @@ on(
 );
 ```
 
-`live` — retain status updates and replay the **full history** to a late `bus.live()` subscriber (tracking UI, ops feed).
+`live` — retain the tape. A late subscriber replays **full history** (`placed → fulfilling → shipped`), then keeps going.
 
-Today that subscription is a **server-side** bus API. `createClient` does not yet expose SSE / WebSocket / `client.live` — see [Client](/docs/reference/client#signal-and-live-queries).
+The listener is **`bus.live()`**, not `on(orderStatus, flow)`. `on(signal, flow)` does not replay retained live payloads. Today that API is server-side; `createClient` has no SSE / WebSocket / `client.live` yet — see [Client](/docs/reference/client#signal-and-live-queries).
 
 ```typescript
-await fx.emit(orderStatus, { orderId, status: "placed" });
+const bus = app.bootResult?.signal?.bus;
+if (!bus) throw new Error("signal runtime not booted");
 
-// Late subscriber (server / test harness) receives placed → fulfilling → shipped.
 const unsub = await bus.live("order-status", (payload) => {
-  /* push to UI */
+  /* placed → fulfilling → shipped */
 });
 ```
 
-**Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the client-visible timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
+**Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
 
 ## When delivery fails
 
 `once` signals retry automatically. Every attempt keeps a **typed failure reason**, and the full attempt history survives into the DLQ — so when a message lands there you see _why_ each attempt failed, not just that it did.
 
+Query that queue from a Flow with `fx.deadLetters(signal)` — same handle as `fx.emit`. The compiler stamps `reads: ["signal:<name>"]`; another signal throws **OKE1001**.
+
 The **Console** (`:6533` → `/overview`) shows emit and consume on the graph, and delivery attempts in Traces — no separate broker UI to run.
 
+```typescript
+on(
+  http.get("/notifications/failed"),
+  flow("notifications.failed", {
+    do: async (input, fx) => fx.json.withQuery(await fx.deadLetters(orderPlaced), input),
+  }),
+);
+```
+
 <Callout title="Orphan emits and schema fail loudly">
   Zero subscribers throws **OKE1042** unless `optional: true`. A payload that fails the signal's
   Standard Schema throws **OKE1043** before the message is staged — same `validate()` path as Flow
@@ -225,9 +255,9 @@ Committed `once` messages survive process death. A claim sets `lockedBy` and a v
 `live` retains every delivered message and replays the **full history** to a late `bus.live()` subscriber. There is no TTL or max-count window on that retention today (the Console payload monitor shows only the newest 50 for display).
 
 <Callout title="Client subscription is not shipped yet">
-  `delivery: "live"` means the **driver** retains and replays. `createClient` has no SSE / WebSocket
-  / `client.live` yet — poll an HTTP Flow or use `bus.live()` server-side. See [Client · Signal and
-  live queries](/docs/reference/client#signal-and-live-queries).
+  `delivery: "live"` means the **driver** retains and replays. Listen with `bus.live()` on the
+  server — not `on(signal, flow)`. `createClient` has no SSE yet — poll HTTP. See
+  [Client](/docs/reference/client#signal-and-live-queries).
 </Callout>
 
 ## Orphaned signal config
@@ -258,7 +288,10 @@ Pairing an arbitrary Store insert with emit inside **one** shared SQL transactio
 <Accordions>
 <Accordion title="Emit fails with OKE1042 (no subscriber)">
 
-You emitted a signal that nobody currently subscribes to. Wire a consumer with `on(signal, flow)` before emit, or set `optional: true` when zero-subscriber emits are intentional.
+You emitted a signal that nobody currently subscribes to. For `once` and `broadcast`, wire
+`on(signal, flow)` before emit.
+
+`live` listeners are `bus.live()`, not a Flow — set `optional: true` when they may connect later.
 
 </Accordion>
 <Accordion title="Emit fails with OKE1043 (schema)">
@@ -268,7 +301,18 @@ The payload failed the signal's Standard Schema at emit time — nothing was sta
 </Accordion>
 <Accordion title="A message keeps retrying and then disappears">
 
-When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`) — it is not lost. Open Console → Flows, inspect the typed failure on the trace, fix the consumer, then replay.
+When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`) — it is not lost. List it from a Flow with `fx.deadLetters(signal)`, or open Console → Flows, inspect the typed failure, fix the consumer, then replay.
+
+</Accordion>
+<Accordion title="fx.deadLetters throws OKE1001">
+
+The flow read a signal it did not declare. The compiler infers `reads: ["signal:<name>"]` from `fx.deadLetters(signal)`. A different handle needs its own read.
+
+</Accordion>
+<Accordion title="on(liveSignal, flow) never replays history">
+
+`on(signal, flow)` listens for `once` and `broadcast`. `live` replay is `bus.live()` on the Signal
+bus — a Flow trigger does not replay retained payloads.
 
 </Accordion>
 <Accordion title="once vs broadcast vs live — how do I choose?">
@@ -290,7 +334,9 @@ At-least-once: crash-after-claim reclaims when the lease expires, and a handler
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — signal files get a name, never a URL; `http.get("/…")` still wins
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and `fx.emit`
+- [fx](/docs/reference/fx) — `fx.emit` and `fx.deadLetters`
 - [Clock](/docs/elements/clock) — scheduled and delayed work
 
 ## Next

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

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

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

@@ -363,6 +363,7 @@ Schedule the live command with cron when you want automatic cleanup.
 
 ## Learn more
 
+- [Project structure](/docs/get-started/project-structure) — `flow({…})` names as `unit.export`; `flow("billing.charge")` still wins
 - [Flow](/docs/elements/flow) — how `fx.vault.get` reads secrets inside `do`
 - [CLI Reference](/docs/reference/cli) — `oke vault set` · `list` · `import`
 

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

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

package/site/content/docs/get-started/index.mdx

@@ -30,6 +30,11 @@ Learn the shape once, install on Bun, then write your first Flow from the standa
     description="Health Flow, typed client, Console proof."
     href="/docs/get-started/basic-usage"
   />
+  <Card
+    title="Project structure"
+    description="Folder and file conventions — URL, name, and the generated barrel."
+    href="/docs/get-started/project-structure"
+  />
   <Card
     title="Deployment"
     description="Compose, Swarm, Kubernetes, and reverse proxy."

package/site/content/docs/get-started/installation.mdx

@@ -6,7 +6,7 @@ icon: Download
 ---
 
 This page gets you from zero to a running app on Bun. The engine targets
-**Bun ≥ 1.3.14** — prefer it for install, scaffold, and `oke dev`.
+**Bun ≥ 1.4.0** — prefer it for install, scaffold, and `oke dev`.
 
 <Callout title="The one rule">
   The npm package is `okengine`; the CLI binary is `oke`. Use `bun add` in a project or `bun install
@@ -20,7 +20,7 @@ This page gets you from zero to a running app on Bun. The engine targets
 <Step>
 ### Prerequisites
 
-- [Bun](https://bun.sh) ≥ 1.3.14 (`bun --version`)
+- [Bun](https://bun.sh) ≥ 1.4.0 (`bun --version`)
 - [Docker](https://docs.docker.com/get-docker/) with a running daemon (`docker info`)
 - A terminal and a code editor
 

package/site/content/docs/get-started/introduction.mdx

@@ -23,19 +23,21 @@ shape. Learn the shape once; only the trigger changes.
 
 Four contracts plus a `do`. This is the standard starter's health check:
 
-```typescript title="health"
+```typescript title="flows/main/health.ts"
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health"),
-  flow("health.check", {
+  http.get().public(),
+  flow({
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),
 );
 ```
 
+`main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure). Explicit `http.get("/health")` and `flow("main.health")` still win.
+
 </Step>
 
 <Step>
@@ -162,6 +164,7 @@ and `okengine/full`.
 | Topic   | Page                                                                            |
 | ------- | ------------------------------------------------------------------------------- |
 | Why OKE | [Why OKE](/docs/get-started/why)                                                |
+| Folders | [Project structure](/docs/get-started/project-structure)                        |
 | Flow    | [Flow](/docs/elements/flow)                                                     |
 | `fx`    | [fx](/docs/reference/fx)                                                        |
 | Agents  | [MCP](/docs/ai/mcp) · [Skills](/docs/ai/skills) · [llms.txt](/docs/ai/llms-txt) |
@@ -184,4 +187,9 @@ and `okengine/full`.
     description="Health Flow, typed client, and bun:test."
     href="/docs/get-started/basic-usage"
   />
+  <Card
+    title="Project structure"
+    description="Folders are the URL; unit plus export is the name."
+    href="/docs/get-started/project-structure"
+  />
 </Cards>

package/site/content/docs/get-started/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Get Started",
   "icon": "Rocket",
-  "pages": ["index", "introduction", "why", "installation", "basic-usage"]
+  "pages": ["index", "introduction", "why", "installation", "basic-usage", "project-structure"]
 }