okengine 0.14.1 → 0.15.2

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

@@ -17,6 +17,7 @@ oke --help                       # command list (also what bare `oke` prints whe
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535 · docs MCP :6536
                                  #   → always Docker Compose under docker/ + host Bun
+                                 #   → regenerates flows/generated.ts when the flows tree changes
                                  #   → client types + domain schema push on save
                                  #   → Console UI hot-reloads from source (okengine checkout; no bun run build)
 oke dev --no-db-push             #     opt out of auto oke db push on schema input save
@@ -48,7 +49,7 @@ oke schema generate              # core + plugin stubs → .oke/schema/oke.ts (-
 oke db push                      # domain schema.ts → live DB (dev; drizzle-kit)
 oke db generate                  # versioned SQL under drizzle/ (review)
 oke db migrate                   # apply migrations (explicit; never auto in prod)
-oke db seed                      # this app's defineSeed (name + essential + env); never at boot
+oke db seed                      # this app's defineSeed (name + essential + env) — standard CLI path
 oke db seed --env prod --force   # CI: skip prod confirmation prompt
 oke db studio                    # drizzle-kit Studio (long-running)
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
@@ -112,24 +113,26 @@ not spawn a second stack. Non-TTY / CI keeps the classic help listing
 `oke dev` always starts Compose (requires a running Docker daemon). Boot chrome
 prints immediately (wordmark + Starting + profile), then streams background work
 (compose up, vault, per-service health, AI probe). Status ● is green ready ·
-yellow pending/loading · red error · dim idle. Compose health keeps polling
+yellow pending/loading · red error · dim idle. After bind, Backend · Console ·
+MCP · Docs MCP each get a box (URL + one-line purpose). Compose health keeps polling
 (`docker compose ps -a`); AI ● tracks model phase while the AI container is up.
 Boot does not wait for the model to become ready. A successful session writes
 `.oke/dev.json` (pid · ports · startedAt) and clears it on stop. Durable local
-markers live in `.oke/state.json` (`seededAt` + `seed` after the one-shot
-prompt for this app's `defineSeed({ name })`) — not in the session lock. Console session signing uses
+markers live in `.oke/state.json` — not in the session lock. Console session signing uses
 `.oke/console.secret` (or `OKE_CONSOLE_SECRET`); that is not a Vault secret.
 
 On a TTY, Ink keyboard controls stay active after boot (`useInput` — same
 shortcuts as before). Press `r` to clear the log pane and reprint the latest
 board.
 
-| Key       | Action                              |
-| --------- | ----------------------------------- |
-| `?`       | help                                |
-| `r`       | refresh — clear logs, show latest ● |
-| `q`       | quit `oke dev`                      |
-| `u` / `x` | compose up / stop (whole stack)     |
+| Key | Action                              |
+| --- | ----------------------------------- |
+| `?` | help                                |
+| `r` | refresh — clear logs, show latest ● |
+| `s` | `oke db seed`                       |
+| `q` | quit `oke dev`                      |
+| `u` | compose up (whole stack)            |
+| `x` | compose stop (whole stack)          |
 
 Compose stays quiet unless it fails. Process-local boot notices print once under
 the hero (not once per process).

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

@@ -5,7 +5,7 @@ icon: "MonitorSmartphone"
 source: "docs/spec/unified-theory.md"
 ---
 
-`okengine/client` is how a browser, CLI, or another service calls your app's flows. Adopt the unit, take `typeof app`, and `api.notes.get({ id })` is fully typed — same contracts the server already has, no separate schema project.
+`okengine/client` is how a browser, CLI, or another service calls your app's flows. Import the generated barrel, take `typeof app`, and `api.notes.get({ id })` is fully typed — same contracts the server already has, no separate schema project.
 
 <Callout title="The one rule">
   Treat every call as a result envelope: `{ data, error }`. Flow failures are values you switch on
@@ -21,19 +21,22 @@ source: "docs/spec/unified-theory.md"
 ### Adopt flows and export `App`
 
 ```typescript title="src/app.ts"
-import { oke } from "okengine";
-import * as main from "./flows/main";
+import "@/core";
+import "@/flows/generated";
+import { oke } from "okengine/http";
 
-export const app = oke({ name: "standard" }).adopt({ main });
+export const app = oke({ name: "notes" });
 export type App = typeof app;
 ```
 
+`.adopt({ notes })` is optional and additive.
+
 </Step>
 
 <Step>
 ### Create the client
 
-Same repo — pass the app value so HTTP triggers hit REST (method + path from adopt):
+Same repo — pass the app value so HTTP triggers hit REST (method + path from `$routes`):
 
 ```typescript title="client"
 import { createClient } from "okengine/client";
@@ -114,7 +117,7 @@ oke client add https://api.example.com --out ./types/oke-client.d.ts
 | Incomplete proxy path (`api.notes()` with no flow) | Result error: `Incomplete path: api.notes(…)`                                                                                                                  |
 
 ```typescript
-// REST — createClient(app, url) saw method/path from on(http.get("/notes/:id"), …)
+// REST — method/path from the bound HTTP trigger (file tree or explicit)
 await api.notes.get({ id: "n_1" }); // GET /notes/n_1
 
 // RPC — untriggered flow named notes.stats
@@ -210,16 +213,16 @@ core today: cookie jars or plugin `.client()` decorations. Browser apps: also se
   outcome by calling a Flow that uses it — or by handling a gate denial on that call.
 </Callout>
 
-| Element                           | On the client | How                                                                                     |
-| --------------------------------- | ------------- | --------------------------------------------------------------------------------------- |
-| [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                        |
-| [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`              |
-| [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows you adopt |
-| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                     |
-| [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                           |
-| [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                        |
-| [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                           |
-| [AI](/docs/elements/ai)           | Via Flows     | `fx.ask` / `fx.run` inside a Flow; the client gets that Flow’s `out`                    |
+| Element                           | On the client | How                                                                                        |
+| --------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                           |
+| [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`                 |
+| [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows on `$routes` |
+| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                        |
+| [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                              |
+| [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                           |
+| [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                              |
+| [AI](/docs/elements/ai)           | Via Flows     | `fx.ask` / `fx.run` inside a Flow; the client gets that Flow’s `out`                       |
 
 ### Store resources
 
@@ -227,7 +230,7 @@ Mount a resource, adopt the returned ops, then call the five Flows like any othe
 
 ```typescript
 const notesR = store.resource(db, notes, {/* in, out, list */});
-const mounted = on(http.resource("/notes", notesR.all()).gate.public.live());
+const mounted = on(http.resource("/notes", notesR.all()).public().live());
 // .adopt({ notes: mounted }) →
 const page = await api.notes.list({ limit: 20 });
 const more = await page.next();
@@ -280,9 +283,9 @@ Budget: the `./client` export stays under the measured client-runtime cap (hard
 
 <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 that `App` (or ambient `Register` after `oke-client.d.ts` regenerates). Restart
-`oke dev` after renaming exports.
+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 that `App` (or ambient `Register` after `oke-client.d.ts` regenerates). Restart `oke dev` after renaming exports.
 
 </Accordion>
 
@@ -321,7 +324,8 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 
 ## Learn more
 
-- [Basic usage](/docs/get-started/basic-usage) — adopt → client → test loop
+- [Project structure](/docs/get-started/project-structure) — folders are the URL; `$routes` without `.adopt()`
+- [Basic usage](/docs/get-started/basic-usage) — generated barrel → client → test loop
 - [Gate](/docs/elements/gate) — policies, `gate.public`, denials
 - [Store](/docs/elements/store) — `store.resource` and list query language
 - [Flow](/docs/elements/flow) — `in` / `out` / `errors` and `fx.fail`

package/site/content/docs/reference/security.md

@@ -41,7 +41,7 @@ Our path is concrete: a booking name containing "ignore previous instructions an
 #### 10.4 Remaining closures
 
 - **`invoke-as` is attenuated** exactly like an API key: an operator cannot assume a scope set they could not grant. Impersonating a real user is development-only. Console `POST /console/flows/invoke` runs the target flow on a bound host under the selected identity’s scopes (`trustedInvoke` is in-process only — never from public HTTP); when the host adapter is unbound, invoke fails closed.
-- **Store SQL browse** masks classified PII by default. `QUERY /console/store/query` with `revealPii: true` returns cleartext for the current page and writes an audited `console.store.query.reveal` log (operator, ref, child). The SQL query console (`POST /console/store/sql`) stays masked unless `revealPii: true`, which writes `console.store.sql.reveal` (operator, ref). Call API (`POST /console/flows/invoke`) masks the same classified field names on the handler response unless `revealPii: true`, which writes `console.flows.invoke.reveal` and opens the host store session with cleartext so columns the handler reads (for example `ownerEmail`) are not already `[redacted]`. `asGate` (a Manifest policy gate or `public`) sets `oke.gate` and `row_security` on postgres / pglite and writes `console.store.sql.asGate`; Operator (omit `asGate`) still bypasses RLS. Per-cell `POST /console/store/reveal` remains available. The Console auth schema (`sql:oke_console` — `oke_operators`, sessions, roles, keys) is hidden from Store browse unless `OKE_CONSOLE_AUTH_STORE=1`. When listed it is **read-only**; edit / delete / raw SQL are refused so operator-plane rows are never joined to `public`.
+- **Store SQL browse** masks classified PII by default. `QUERY /console/store/query` with `revealPii: true` returns cleartext for the current page and writes an audited `console.store.query.reveal` log (operator, ref, child). The SQL query console (`POST /console/store/sql`) stays masked unless `revealPii: true`, which writes `console.store.sql.reveal` (operator, ref). Call API (`POST /console/flows/invoke`) masks the same classified field names on the handler response unless `revealPii: true`, which writes `console.flows.invoke.reveal` and opens the host store session with cleartext so columns the handler reads (for example `ownerEmail`) are not already `[redacted]`. `{ asGate, asUserId }` on SQL, browse, row edit, and Call API stamps `oke.gate()` / `oke.user()` / `oke.has_scope()` on postgres / pglite (one identity bag; policy-only leaves `oke.user()` empty — never `gate:${name}`); Operator / omit / `bypassGates` still bypasses RLS. The response may include `rls: { gate, userId, applied }`. Catalog DDL stays Operator. Per-cell `POST /console/store/reveal` remains available. The Console auth schema (`sql:oke_console` — `oke_operators`, sessions, roles, keys) is hidden from Store browse unless `OKE_CONSOLE_AUTH_STORE=1`. When listed it is **read-only**; edit / delete / raw SQL are refused so operator-plane rows are never joined to `public`.
 - **Host WideEvent ingest** (`POST /console/runs/ingest`, `oke dev` only) is secret-gated and never echoes the event body. Operators read runs only through `projectRun` / `maskWideEventForConsole` on `GET /console/runs` and `/console/live` — the same PII boundary as Console-local runs.
 - **Store SQL performance** (`QUERY /console/store/sql/stats`, `/locks`, `POST /console/store/sql/advise`) is engine-native query text — not Store browse masking. Statements show `pg_stat_statements` fingerprints (`$n`). Live `pg_stat_activity.query` is collapsed until `revealPii: true`, which writes `console.store.sql.stats.reveal` (operator, ref). Named limitation `StoreSqlStatsQueryTextGap`. This surface does not terminate sessions or call `pg_stat_statements_reset`.
 - **Store KV performance** (`QUERY /console/store/kv/stats`) is Redis-wire `INFO` / `COMMANDSTATS` / `SLOWLOG` / `LATENCY` — not Store browse. INFO is instance-wide (`StoreKvStatsServerWideGap`). SLOWLOG args are keys and values — collapsed until `revealPii: true`, which writes `console.store.kv.stats.reveal` (operator, ref). Named limitation `StoreKvStatsSlowlogArgsGap`. `memory` returns `KvStatsUnsupported`. This surface does not run `MONITOR` and does not invent a hot-key table.

package/src/auth/bindings.ts

@@ -275,10 +275,13 @@ export function createAuthHttpBindings(
   } = { refresh, revoke, me };
   const bindings: Binding[] = [
     bindAuthHttp(
-      http.post(`${base}/refresh`).gate.public.gate(...(refreshRate ? [refreshRate] : [])),
+      http
+        .post(`${base}/refresh`)
+        .public()
+        .gate(...(refreshRate ? [refreshRate] : [])),
       refresh,
     ),
-    bindAuthHttp(http.post(`${base}/revoke`).gate.public, revoke),
+    bindAuthHttp(http.post(`${base}/revoke`).public(), revoke),
     bindAuthHttp(http.get(`${base}/me`).gate(AUTH_SESSION_GATE), me),
   ];
 
@@ -371,11 +374,17 @@ export function createAuthHttpBindings(
     flows.signUpEmail = signUpEmail;
     bindings.push(
       bindAuthHttp(
-        http.post(`${base}/sign-in/email`).gate.public.gate(...(signInRate ? [signInRate] : [])),
+        http
+          .post(`${base}/sign-in/email`)
+          .public()
+          .gate(...(signInRate ? [signInRate] : [])),
         signInEmail,
       ),
       bindAuthHttp(
-        http.post(`${base}/sign-up/email`).gate.public.gate(...(signUpRate ? [signUpRate] : [])),
+        http
+          .post(`${base}/sign-up/email`)
+          .public()
+          .gate(...(signUpRate ? [signUpRate] : [])),
         signUpEmail,
       ),
     );
@@ -406,7 +415,7 @@ export function isSessionFresh(
  * @param flowDef - Flow
  */
 export function bindAuthHttp(trigger: HttpTrigger, flowDef: AnyFlowDef): Binding {
-  const withPosture = trigger.gates.length > 0 ? trigger : trigger.gate.public;
+  const withPosture = trigger.gates.length > 0 ? trigger : trigger.public();
   const normalized = normalizeTrigger(withPosture);
   const list = flowDef.triggers as Trigger[];
   list.push(normalized);

package/src/auth/cross-plane.ts

@@ -86,9 +86,16 @@ export function assertCrossPlane(
 
 function inferFlowFromPath(path: string): string | undefined {
   // …/flows/bookings/create.ts → bookings.create
-  const m = /flows\/([^/]+)\/([^/]+)\.(ts|tsx|js)$/.exec(path.replace(/\\/g, "/"));
-  if (m) return `${m[1]}.${m[2]}`;
-  return undefined;
+  // …/flows/notes/[id]/get.ts → notes.get (never notes.id.get)
+  const posix = path.replace(/\\/g, "/");
+  const m = /(?:^|\/)flows\/([^/]+)\/(.+)\.(ts|tsx|js)$/.exec(posix);
+  if (!m) return undefined;
+  const unit = m[1]!;
+  const rest = m[2]!;
+  const leaf = rest.split("/").pop();
+  if (!leaf || leaf === "index" || leaf.startsWith("_")) return undefined;
+  if (leaf === "shapes" || leaf === "signals" || leaf.endsWith(".test")) return undefined;
+  return `${unit}.${leaf}`;
 }
 
 function inferPlaneFromSource(source: string): "user" | "operator" | undefined {

package/src/cli/ai-setup/ai-setup.test.ts

@@ -167,6 +167,68 @@ export default defineConfig({
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("applyAiSetup prefers an existing src/core/ai.ts over a thin core.ts barrel", () => {
+    const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-split-"));
+    try {
+      writeFileSync(
+        join(dir, "oke.config.ts"),
+        `import { defineConfig } from "okengine/config";
+export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        dev: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {
+    store: {
+      sql: "postgres:18-alpine",
+    },
+  },
+});
+`,
+        "utf8",
+      );
+      mkdirSync(join(dir, "src", "core"), { recursive: true });
+      writeFileSync(
+        join(dir, "src", "core.ts"),
+        `export * from "./core/store.ts";\nexport * from "./core/ai.ts";\n`,
+        "utf8",
+      );
+      writeFileSync(
+        join(dir, "src", "core", "store.ts"),
+        `import { store } from "okengine";\n\nexport const db = store.sql("app");\n`,
+        "utf8",
+      );
+      writeFileSync(join(dir, "src", "core", "ai.ts"), `import { ai } from "okengine";\n`, "utf8");
+      writeFileSync(
+        join(dir, "src", "app.ts"),
+        `import "@/core";\nexport const app = {};\n`,
+        "utf8",
+      );
+
+      applyAiSetup(dir, {
+        driver: "ollama",
+        baseUrl: "http://127.0.0.1:11434",
+        chatModel: "gemma4:e4b",
+        visionModel: "qwen3-vl:4b",
+        embedModel: "nomic-embed-text",
+      });
+
+      const barrel = readFileSync(join(dir, "src", "core.ts"), "utf8");
+      expect(barrel).not.toContain("ai.model");
+      expect(barrel).toContain('export * from "./core/ai.ts"');
+      const aiTs = readFileSync(join(dir, "src", "core", "ai.ts"), "utf8");
+      expect(aiTs).toContain("smart");
+      expect(aiTs).toContain('ai.model("vision"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("parseAiSetupArgs", () => {

package/src/cli/ai-setup/apply.ts

@@ -244,7 +244,9 @@ export function renderAiTs(input: AiSetupApplyInput): string {
 }
 
 /**
- * Write AI model declarations into `src/core.ts` (preferred) or legacy `src/core/ai.ts`.
+ * Write AI model declarations into `src/core/ai.ts` when that split exists
+ * (so a thin `src/core.ts` barrel stays a re-export), else `src/core.ts`,
+ * else legacy `src/core/index.ts` + sidecar.
  *
  * @param cwd - Project root
  * @param input - Setup choices
@@ -252,9 +254,25 @@ export function renderAiTs(input: AiSetupApplyInput): string {
  */
 function writeAiModels(cwd: string, input: AiSetupApplyInput): string {
   const rendered = renderAiTs(input);
+  const coreAiPath = join(cwd, "src", "core", "ai.ts");
   const coreTsPath = join(cwd, "src", "core.ts");
   const legacyIndex = join(cwd, "src", "core", "index.ts");
 
+  if (existsSync(coreAiPath)) {
+    const existing = readFileSync(coreAiPath, "utf8");
+    if (hasAiModels(existing)) {
+      const withPrompt = ensureSummarizeNotePrompt(existing);
+      if (withPrompt !== existing) {
+        writeFileSync(coreAiPath, withPrompt, "utf8");
+      }
+    } else {
+      writeFileSync(coreAiPath, mergeAiIntoCore(existing, rendered), "utf8");
+    }
+    ensureCoreBarrelExportsAi(cwd);
+    ensureCoreImported(cwd);
+    return coreAiPath;
+  }
+
   // Folder layout still in the wild — keep writing a sidecar.
   if (!existsSync(coreTsPath) && existsSync(legacyIndex)) {
     const aiTsPath = join(cwd, "src", "core", "ai.ts");
@@ -364,6 +382,19 @@ export function ensureNamedOkengineImport(source: string, name: string): string
   return source.replace(re, `import { ${sorted.join(", ")} } from "okengine";`);
 }
 
+/**
+ * Keep a `src/core.ts` barrel re-exporting `./core/ai.ts` after a split write.
+ *
+ * @param cwd - Project root
+ */
+function ensureCoreBarrelExportsAi(cwd: string): void {
+  const coreTsPath = join(cwd, "src", "core.ts");
+  if (!existsSync(coreTsPath)) return;
+  const src = readFileSync(coreTsPath, "utf8");
+  if (/from\s+["']\.\/core\/ai/.test(src)) return;
+  writeFileSync(coreTsPath, `${src.trimEnd()}\nexport * from "./core/ai.ts";\n`, "utf8");
+}
+
 /**
  * Ensure `src/app.ts` loads `@/core` / `./core` so merged AI registers.
  *

package/src/cli/attach-host-console.test.ts

@@ -28,7 +28,7 @@ describe("attachHostToConsole", () => {
 import { oke, on, flow, http, gate, store } from ${JSON.stringify(OKE)};
 const db = store.sql("db");
 export const ping = on(
-  http.get("/ping").gate.public,
+  http.get("/ping").public(),
   flow("main.ping", { do: () => ({ ok: true }) }),
 );
 export const app = oke({
@@ -69,6 +69,7 @@ export const app = oke({
     expect(ingested.some((row) => row.event?.flow === "main.ping")).toBe(true);
     await attached!.stop();
     expect(state.invokeUserFlow).toBeNull();
+    expect(state.storeRuntime).toBeNull();
   });
 
   test("binds host aiRuntime so Console projection sees a journaled ask", async () => {
@@ -81,7 +82,7 @@ import { oke, on, flow, http, gate, ai } from ${JSON.stringify(OKE)};
 const smart = ai.model("smart", { provider: "mock" });
 smart.prompt("ticket-triage", { version: 2 });
 export const ping = on(
-  http.get("/ping").gate.public,
+  http.get("/ping").public(),
   flow("main.ping", {
     effects: { asks: ["ticket-triage"] },
     do: (_input, fx) => fx.ask("ticket-triage", { subject: "hello" }),

package/src/cli/attach-host-console.ts

@@ -73,6 +73,9 @@ export async function attachHostToConsole(
   return {
     stop: async () => {
       options.state.invokeUserFlow = null;
+      options.state.storeRuntime = null;
+      options.state.vaultRuntime = null;
+      options.state.aiRuntime = null;
       await host.stop();
     },
   };

package/src/cli/build.test.ts

@@ -32,8 +32,10 @@ describe("oke build — .adopt() barrel regeneration", () => {
       expect(code).toBe(0);
 
       const after = await readFile(generatedPath, "utf8");
-      expect(after).toContain('export * as main from "./main/index.ts";');
-      expect(after).toContain('export * as notes from "./notes/index.ts";');
+      expect(after).toContain('import * as main from "./main/index.ts";');
+      expect(after).toContain('import * as notes from "./notes/index.ts";');
+      expect(after).toContain("export { main }");
+      expect(after).toContain("export { notes }");
     } finally {
       await rm(root, { recursive: true, force: true });
     }

package/src/cli/db-seed.ts

@@ -1,10 +1,10 @@
 /**
  * `oke db seed` — load `defineSeed`, boot the app store, run essential +
- * env-selected category (`dev` | `prod`).
+ * env-selected category (`dev` | `prod`). Tallies SQL upserts and `kv.set`.
  */
 
 import { resolve } from "node:path";
-import { isCancel, text } from "@clack/prompts";
+import { intro, isCancel, outro, text } from "@clack/prompts";
 import type { ConfigEnv, OkeConfig } from "../config/index.ts";
 import {
   normalizeSeedFns,
@@ -25,11 +25,13 @@ import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
 import { loadOkeConfig } from "./load-config.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
 
-/** Per-function upsert outcome counts. */
+/** Per-function upsert / KV-set outcome counts. */
 export interface SeedTally {
   upserted: number;
   changed: number;
   alreadyExisted: number;
+  /** `fx.store(kv).set` calls (cache or durable). */
+  keys: number;
 }
 
 /** Options for {@link runSeed}. */
@@ -56,6 +58,11 @@ export interface SeedOptions {
    */
   readonly confirmEnv?: (env: ConfigEnv, target: string) => Promise<boolean>;
   readonly stdinIsTTY?: boolean;
+  /**
+   * Clack `intro` / `outro` for the standalone `oke db seed` path.
+   * Default: on when stdin is a TTY.
+   */
+  readonly intro?: boolean;
 }
 
 /**
@@ -127,12 +134,13 @@ export async function runSeedFns(
 ): Promise<void> {
   for (let i = 0; i < fns.length; i++) {
     const fn = fns[i]!;
-    const tally: SeedTally = { upserted: 0, changed: 0, alreadyExisted: 0 };
+    const tally: SeedTally = { upserted: 0, changed: 0, alreadyExisted: 0, keys: 0 };
     const instrumented = instrumentFxUpserts(fx, tally);
     await fn(instrumented);
     const label = fn.name.length > 0 ? fn.name : String(i);
+    const kv = tally.keys > 0 ? ` · keys ${tally.keys}` : "";
     write(
-      `oke db seed: ${category} ${label} — upserted ${tally.upserted} · changed ${tally.changed} · already-existed ${tally.alreadyExisted}\n`,
+      `oke db seed: ${category} ${label} — upserted ${tally.upserted} · changed ${tally.changed} · already-existed ${tally.alreadyExisted}${kv}\n`,
     );
   }
 }
@@ -233,7 +241,13 @@ export async function bootSeedFx(
   if (!app) {
     throw new Error(`oke db seed: no oke() app export in ${entryAbs}`);
   }
-  await app.boot({ env, startScheduler: false, config: config ?? undefined, rootDir: cwd });
+  await app.boot({
+    env,
+    startScheduler: false,
+    config: config ?? undefined,
+    rootDir: cwd,
+    docker: process.env.OKE_DOCKER === "1",
+  });
   const storeRuntime = app.elements?.store ?? app.bootResult?.store;
   if (!storeRuntime) {
     throw new Error(
@@ -243,6 +257,7 @@ export async function bootSeedFx(
   const fx = createFx({
     flow: "oke.db.seed",
     storeRuntime,
+    rlsBypass: true,
   });
   return {
     fx,
@@ -262,6 +277,14 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
   const cwd = options.cwd ?? process.cwd();
   const loaded = await loadOkeConfig(cwd).catch(() => null);
   const env = options.env ?? (await resolveDevSqlEnv(cwd));
+  const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  const useIntro = options.intro !== false && tty;
+  if (useIntro) intro("oke db seed");
+
+  const finish = (code: number, message: string): number => {
+    if (useIntro) outro(message);
+    return code;
+  };
 
   let targetLabel = String(env);
   try {
@@ -274,7 +297,6 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
 
   if (env === "dev" || env === "prod") {
     if (options.force !== true) {
-      const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
       const confirm =
         options.confirmEnv ??
         (tty
@@ -288,7 +310,7 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
       const ok = await confirm(env, targetLabel);
       if (!ok) {
         write("oke db seed: cancelled\n");
-        return EXIT_USAGE;
+        return finish(EXIT_USAGE, "Cancelled.");
       }
     }
   }
@@ -308,10 +330,10 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
     stop = session.stop;
     await executeSeedDef(def, env, session.fx, write);
     write("oke db seed: ok\n");
-    return EXIT_OK;
+    return finish(EXIT_OK, "oke db seed: ok");
   } catch (err) {
     write(`oke db seed: ${err instanceof Error ? err.message : String(err)}\n`);
-    return EXIT_RUNTIME;
+    return finish(EXIT_RUNTIME, "oke db seed: failed");
   } finally {
     if (stop) await stop().catch(() => {});
   }
@@ -374,14 +396,18 @@ function instrumentFxUpserts(fx: Fx, tally: SeedTally): Fx {
 
 function instrumentUpsertHandle<T>(handle: T, tally: SeedTally): T {
   if (!handle || typeof handle !== "object") return handle;
-  const h = handle as { upsert?: (...args: unknown[]) => Promise<{ status: UpsertStatus }> };
-  if (typeof h.upsert !== "function") return handle;
-  const orig = h.upsert.bind(h);
+  const h = handle as {
+    upsert?: (...args: unknown[]) => Promise<{ status: UpsertStatus }>;
+    set?: (...args: unknown[]) => Promise<unknown>;
+  };
+  const origUpsert = typeof h.upsert === "function" ? h.upsert.bind(h) : undefined;
+  const origSet = typeof h.set === "function" ? h.set.bind(h) : undefined;
+  if (!origUpsert && !origSet) return handle;
   return new Proxy(handle as object, {
     get(target, prop, receiver) {
-      if (prop === "upsert") {
+      if (prop === "upsert" && origUpsert) {
         return async (...args: unknown[]) => {
-          const result = await orig(...args);
+          const result = await origUpsert(...args);
           const status =
             result && typeof result === "object" && "status" in result
               ? (result as { status: UpsertStatus }).status
@@ -392,6 +418,13 @@ function instrumentUpsertHandle<T>(handle: T, tally: SeedTally): T {
           return result;
         };
       }
+      if (prop === "set" && origSet) {
+        return async (...args: unknown[]) => {
+          const result = await origSet(...args);
+          tally.keys += 1;
+          return result;
+        };
+      }
       return Reflect.get(target, prop, receiver);
     },
   }) as T;