okengine 0.13.0 → 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/fx.mdx

@@ -33,9 +33,10 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 ## Signals
 
-| Signature                             | Records | Notes                                                                                                                                                                                                     |
-| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fx.emit(signal, payload?, { key? })` | `emit`  | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
+| Signature                             | Records                | Notes                                                                                                                                                                                                     |
+| ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
+| `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                               |
 
 ## Runs (observability read)
 
@@ -145,12 +146,12 @@ contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Ch
 
 ## AI
 
-| Signature                                             | Records                   | Returns                                                                       |
-| ----------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
-| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                   |
-| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                  |
-| `fx.stream(model, { prompt?, data? })`                | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` |
-| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                  |
+| Signature                                             | Records                   | Returns                                                                                                  |
+| ----------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                                              |
+| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                                             |
+| `fx.stream(model, { prompt?, data?, via? })`          | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` (HTTP disconnect included) |
+| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                                             |
 
 AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 
@@ -169,12 +170,15 @@ AI calls are nondeterministic: journaling is forced on and auto-cache disabled a
 
 ## Clock
 
-| Signature                         | Notes                                                 |
-| --------------------------------- | ----------------------------------------------------- |
-| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"           |
-| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise |
+| Signature                         | Notes                                                               |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"                         |
+| `fx.clock.ago(duration)`          | Instant before now (`"30d"` → now − 30 days)                        |
+| `fx.clock.fromNow(duration)`      | Instant after now (`"14d"` → now + 14 days)                         |
+| `fx.clock.duration(duration)`     | Span in ms — offset a stored instant (`createdAt + duration("7d")`) |
+| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise               |
 
-Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`.
+Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400_000 ms, not a calendar day. Unknown strings parse as `0`.
 
 ## Cache
 
@@ -192,15 +196,16 @@ keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
 
 ## Responses
 
-| Helper                                    | Status | Body                                                        |
-| ----------------------------------------- | ------ | ----------------------------------------------------------- |
-| `fx.json.ok(value, { meta? })`            | 200    | `{ data, meta?, error: null }`                              |
-| `fx.json.create(value)`                   | 201    | `{ data, error: null }`                                     |
-| `fx.json.empty()`                         | 204    | no body                                                     |
-| `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager         |
-| `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST |
+| Helper                                    | Status | Body                                                           |
+| ----------------------------------------- | ------ | -------------------------------------------------------------- |
+| `fx.json.ok(value, { meta? })`            | 200    | `{ data, meta?, error: null }`                                 |
+| `fx.json.create(value)`                   | 201    | `{ data, error: null }`                                        |
+| `fx.json.empty()`                         | 204    | no body                                                        |
+| `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager            |
+| `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST    |
+| `fx.json.stream(chunks)`                  | 200    | `text/event-stream` — JSON `data:` frames, then `data: [DONE]` |
 
-Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control.
+Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control. Pass `fx.stream(...)` into `fx.json.stream` to reach the HTTP client token-by-token.
 
 ## Logging, i18n, ids
 

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/ai-setup/recommend.test.ts

@@ -197,4 +197,29 @@ describe("formatModelRow", () => {
     expect(row).toContain("text · code");
     expect(row).not.toContain("  ·  ≈");
   });
+
+  test("Arabic and CJK labels keep Caps aligned", () => {
+    const header = formatModelTableHeader();
+    const capsWidth = Bun.stringWidth(header.slice(0, header.indexOf("Caps")));
+    const ar = formatModelRow({
+      id: "ar",
+      label: "مرحبا بالعالم",
+      hint: "",
+      role: "chat",
+      ramGb: 8,
+      tier: "fast",
+      modalities: ["text"],
+    });
+    const cjk = formatModelRow({
+      id: "cjk",
+      label: "你好世界模型",
+      hint: "",
+      role: "chat",
+      ramGb: 8,
+      tier: "fast",
+      modalities: ["text"],
+    });
+    expect(Bun.stringWidth(ar.slice(0, ar.indexOf("text")))).toBe(capsWidth);
+    expect(Bun.stringWidth(cjk.slice(0, cjk.indexOf("text")))).toBe(capsWidth);
+  });
 });

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

@@ -195,9 +195,14 @@ const MODEL_COL_RAM = 7;
  * @param width - Fixed width
  */
 function clipPad(value: string, width: number): string {
-  if (value.length === width) return value;
-  if (value.length < width) return value.padEnd(width);
-  return `${value.slice(0, Math.max(0, width - 1))}…`;
+  const bunAnsi = Bun as typeof Bun & {
+    stringWidth(text: string): number;
+    sliceAnsi(text: string, start: number, end: number, omission?: string): string;
+  };
+  const display = bunAnsi.stringWidth(value);
+  if (display === width) return value;
+  if (display < width) return value + " ".repeat(width - display);
+  return bunAnsi.sliceAnsi(value, 0, width, "…");
 }
 
 /**

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 });
     }