okengine 0.9.1 → 0.10.1

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

@@ -45,14 +45,44 @@ oke build --target edge          # < 15 kB kernel profile
 oke eval                         # run prompt eval sets; fails CI on regression
 oke ai setup                     # configure AI driver + models (TTY wizard or flags)
 oke branch prod --at "yesterday" # fork journaled state into a sandbox
+oke replay --request-id <id>     # re-invoke a past Flow from a Runs WideEvent (dry-run if send/ask)
 oke privacy erase --subject <id> # crypto-shredding: deletes the key, not the terabytes
 oke upgrade                      # run codemods for a breaking change, print the diff
 ```
 
+`oke replay` loads a Runs WideEvent by id and re-enters the Flow with stored
+input. Defaults to dry-run when the ledger has `send` / `ask` (pass `--live`
+to override). Needs a build that persisted `WideEvent.input`.
+
 In development, app, Console, MCP, and docs MCP prefer the canonical ports and move upward
 when occupied. Docker infrastructure uses stable per-project offsets in disjoint ranges for
 each built-in service, preventing one service's offset port from overlapping another's.
 
+`oke dev` boot chrome prints immediately (wordmark + Starting + profile), then
+streams background work (compose up, vault, per-service health, AI probe) in a
+live progress pane — no blank multi-second wait. That pane clears before the
+elements + Docker board. Status ● is green ready · yellow pending/loading ·
+red error · dim idle. Compose health keeps polling (`docker compose ps -a`)
+so ● updates live if you stop a container; AI ● tracks model phase while the
+AI container is up. Boot does not wait for the model to become ready.
+
+On a TTY with `-d`, keyboard controls stay active under Logs. Status ● for
+compose/AI live on the board **above** Logs (not as log lines). Press `c` to
+clear the log pane and reprint the latest board. `l` / `?` also refresh first
+so the services/help panel is not mixed into request logs.
+
+| Key                          | Action                              |
+| ---------------------------- | ----------------------------------- |
+| `?`                          | help                                |
+| `c`                          | refresh — clear logs, show latest ● |
+| `q`                          | quit `oke dev`                      |
+| `l`                          | list docker services                |
+| `u` / `x`                    | compose up / stop (whole stack)     |
+| `1`–`9` then `u` / `x` / `r` | start / stop / restart one service  |
+
+Compose stays quiet unless it fails. Process-local boot notices print once under
+the hero (not once per process).
+
 ### create-oke
 
 ```bash
@@ -66,9 +96,11 @@ bunx create-oke@latest my-app --no-ai
 
 On a TTY: pick **standard** or **advanced**, then recommended defaults or
 customize. Customize asks **local** or **docker** first, walks facets for that
-side only, then whether to customize the other (defaults if no). Writes
-user-global `~/.oke/create-defaults.json` (reuse only when `template` matches).
-Scaffold writes `.oke/mode` from the primary side. Non-TTY / `--yes` / explicit
+side only (including `store.index` with a `none` opt-out — no separate enable
+prompt), then whether to customize the other (defaults if no). **AI setup**
+offers Recommended (llama.cpp) · Customize · Off. Writes user-global
+`~/.oke/create-defaults.json` (reuse only when `template` matches). Scaffold
+writes `.oke/mode` from the primary side. Non-TTY / `--yes` / explicit
 `--template` never prompt.
 
 ### Additional commands
@@ -79,8 +111,9 @@ oke doctor --json                # -j  JSON on stdout; hints on stderr (agents /
 oke stack --json                 # -j
 oke images list                  # recipe · image · tag · digest · size (--json|-j)
 oke gates list                   # Module:Action catalogue (--json|-j)
-oke ai setup --provider ollama --yes   # non-interactive AI config
-# TTY Ollama: needs quiz → RAM-tier panel → recommend / installed / manual (+ ← Back)
+oke ai setup --provider llama-cpp --yes  # default local AI
+oke ai setup --provider ollama --yes     # fully supported alternative
+# TTY: llama.cpp / Ollama → banner · tiers · manual; vLLM / SGLang / cloud → model
 ```
 
 ### Shell completion
@@ -115,7 +148,10 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 | `--diff`             |       | `doctor`                                       |
 | `--json`             | `-j`  | `doctor`, `stack`, `images list`, `gates list` |
 | `--manifest`         | `-m`  | most Manifest readers                          |
-| `--entry`            | `-e`  | `dev`, `start`, `build`                        |
+| `--entry`            | `-e`  | `dev`, `start`, `build`, `replay`              |
+| `--request-id`       | `-r`  | `replay`                                       |
+| `--dry-run`          |       | `replay`                                       |
+| `--live`             |       | `replay`                                       |
 | `--out` / `--outdir` | `-o`  | writers                                        |
 | `--subject`          | `-s`  | `privacy erase`                                |
 | `--before`           | `-b`  | `doctor --diff`                                |

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

@@ -82,7 +82,7 @@ images: {
   "store.files": "rustfs/rustfs:1.0.0-beta.11",
   "channel.email": "axllent/mailpit:v1.22.3",
   vault: "openbao/openbao:2.6.1",
-  ai: "ollama/ollama:latest",
+  ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // default; or ollama/ollama:0.32.6
   // opt-in TLS edge — omit for the default (app publishes 6530):
   // proxy: "caddy:2-alpine",   // simplest automatic HTTPS
   // proxy: "traefik:v3.3",     // label auto-discovery for --scale app=N
@@ -96,7 +96,9 @@ When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog
 For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays
 `redis`, same `REDIS_URL`. Image table + licenses: [Store · KV](/docs/elements/store#kv).
 
-For `ai`, the Ollama recipe pulls `OKE_AI_MODEL` (default `qwen3.5:9b` — a balanced local-dev starting point; override freely; on Apple Silicon prefer `qwen3.5:9b-mlx`) and writes `OKE_AI_URL`.
+For `ai`, default is [llama.cpp](/docs/recipes/llama-cpp) (`OKE_AI_URL` →
+`/v1`, curated Docker Hub `ai/` model). Ollama / vLLM / SGLang are explicit
+alternatives — see [Recipes · AI](/docs/recipes#ai-local--self-hosted).
 
 For `proxy`, pin **either** Caddy or Traefik — never both. Opt-in only; see
 [Reverse proxy](/docs/deployment/reverse-proxy).
@@ -165,7 +167,7 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 | Option    | Default | Surface |
 | --------- | ------- | ------- |
-| `app`     | `6530`  | App     |
+| `app`     | `6530`  | Backend |
 | `console` | `6533`  | Console |
 | `mcp`     | `6535`  | MCP     |
 

package/site/content/docs/reference/environment-variables.mdx

@@ -109,18 +109,18 @@ provider's real credentials — credentials alone never send.
 
 ## AI providers
 
-| Variable              | Used for                                                                                                                                  | Default when unset                |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                                                             | —                                 |
-| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                                                   | —                                 |
-| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                                                     | —                                 |
-| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                                                              | OpenAI cloud                      |
-| `OKE_AI_DRIVER`       | Force the AI driver id (honoured in docker mode)                                                                                          | config map                        |
-| `OKE_AI_URL`          | Ollama (or openai-compatible) base URL                                                                                                    | `http://127.0.0.1:11434` (ollama) |
-| `OKE_AI_MODEL`        | Default model for `ollama` (any pulled model; `qwen3.5:9b` is a balanced local-dev starting point; on Apple Silicon try `qwen3.5:9b-mlx`) | `qwen3.5:9b`                      |
-| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                                                  | —                                 |
-| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                                                              | —                                 |
-| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                                                     | —                                 |
+| Variable              | Used for                                                                                                | Default when unset                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                           | —                                                                          |
+| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                 | —                                                                          |
+| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                   | —                                                                          |
+| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                            | OpenAI cloud                                                               |
+| `OKE_AI_DRIVER`       | Force the AI driver id (honoured in docker mode)                                                        | config map                                                                 |
+| `OKE_AI_URL`          | Local / openai-compatible base URL                                                                      | `http://127.0.0.1:8080/v1` (llama.cpp) · `http://127.0.0.1:11434` (ollama) |
+| `OKE_AI_MODEL`        | Default model id — Docker Hub `ai/` for llama.cpp; Ollama library tag for ollama; HF id for vLLM/SGLang | `smollm2` (llama.cpp) / `qwen3.5:9b` (ollama)                              |
+| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                | —                                                                          |
+| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                            | —                                                                          |
+| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                   | —                                                                          |
 
 ## Framework behavior
 

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

@@ -33,9 +33,42 @@ 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; 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) |
+
+## Runs (observability read)
+
+Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Channel) without a parallel metrics API.
+
+| Signature                                | Records       | Returns                                       |
+| ---------------------------------------- | ------------- | --------------------------------------------- |
+| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory)        |
+| `fx.runs.all()`                          | `read` `runs` | All wide events                               |
+| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m) |
+| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches               |
+
+```typescript
+on(
+  every("5m"),
+  flow({
+    name: "ops.slo-check",
+    effects: { reads: ["runs"], sends: ["slo-alert"] },
+    do: async (_, fx) => {
+      const breaches = await fx.runs.checkSlo(
+        "checkout.create",
+        { availability: "99.9%", latency: { p95: "200ms" } },
+        5 * 60_000,
+      );
+      if (breaches.length === 0) return;
+      await fx.send(sloAlert, {
+        to: "oncall@example.com",
+        data: { flow: "checkout.create", count: breaches.length },
+      });
+    },
+  }),
+);
+```
 
 ## Flows
 
@@ -228,7 +261,8 @@ must log who started the call chain.
 
 <Callout title="No fx.metric">
   Investigated and declined. [Runs](/docs/console/runs) already own per-invocation observability as
-  wide events; a parallel counter/gauge API would be a second instrumentation path without a sink.
+  wide events. Native alerting is `fx.runs` + Clock + Channel — not a second counter/gauge API.
+  Optional OTLP export for existing Grafana/Datadog stacks is additive and never required.
 </Callout>
 
 ## Learn more

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

@@ -13,13 +13,14 @@ import { parseAiSetupArgs } from "./index.ts";
 
 describe("catalog", () => {
   test("recommendChatModel respects RAM tiers", () => {
-    expect(recommendChatModel(8).id).toBe("gemma4:e4b");
+    expect(recommendChatModel(8).ramGb).toBeLessThanOrEqual(8);
     expect(recommendChatModel(16).ramGb).toBeLessThanOrEqual(16);
     expect(recommendChatModel(null).recommended).toBe(true);
   });
 
   test("cloud providers ship short curated chat lists + recommended", () => {
     expect(cloudChatModels("openai").length).toBeGreaterThan(0);
+    expect(cloudChatModels("openai").length).toBeLessThanOrEqual(10);
     expect(cloudChatModels("anthropic").some((m) => m.recommended)).toBe(true);
     expect(recommendCloudChat("openai")).toBe("gpt-4o-mini");
     expect(recommendCloudChat("anthropic")).toContain("claude");
@@ -58,11 +59,15 @@ describe("apply", () => {
 });
 `;
     const next = upsertAiDrivers(src, "ollama");
-    expect(next).toMatch(/^ {4}ai:\s*\{/m);
-    expect(next).toContain('local: "ollama"');
-    const channel = next.match(/^ {4}channel:\s*\{[\s\S]*?\n {4}\},?\n/m)?.[0] ?? "";
-    expect(channel).toContain("email:");
-    expect(channel).not.toContain("ai:");
+    const body = next
+      .replace(/^import\s+[\s\S]*?from\s+["'][^"']+["'];?\s*/m, "")
+      .replace(/export\s+default\s+/, "return ");
+    const config = new Function("defineConfig", body)(<T>(c: T): T => c) as {
+      drivers?: { ai?: unknown; channel?: { ai?: unknown; email?: unknown } };
+    };
+    expect(config.drivers?.ai).toMatchObject({ local: "ollama", docker: "ollama" });
+    expect(config.drivers?.channel?.ai).toBeUndefined();
+    expect(config.drivers?.channel?.email).toBeDefined();
   });
 
   test("upsertEnv uncomment / set", () => {
@@ -70,6 +75,18 @@ describe("apply", () => {
     expect(upsertEnv(env, "OKE_AI_DRIVER", "ollama")).toContain("OKE_AI_DRIVER=ollama");
   });
 
+  test("upsertEnv comment keeps stack keys as overrides", () => {
+    const env = `# OKE_AI_DRIVER=mock\nOKE_AI_URL=http://x\n`;
+    const next = upsertEnv(env, "OKE_AI_URL", "http://127.0.0.1:8080/v1", { comment: true });
+    expect(next).toContain("# OKE_AI_URL=http://127.0.0.1:8080/v1");
+    expect(next).not.toMatch(/^OKE_AI_URL=/m);
+  });
+
+  test("upsertEnv writes API token when provided", () => {
+    const env = `# OKE_AI_DRIVER=mock\n`;
+    expect(upsertEnv(env, "OPENAI_API_KEY", "sk-test")).toContain("OPENAI_API_KEY=sk-test");
+  });
+
   test("renderAiTs includes vision + embed", () => {
     const ts = renderAiTs({
       driver: "ollama",
@@ -82,7 +99,7 @@ describe("apply", () => {
     expect(ts).toContain("docsEmbed");
   });
 
-  test("applyAiSetup writes config, env, ai.ts", () => {
+  test("applyAiSetup writes config, env, core/ai.ts", () => {
     const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-"));
     try {
       writeFileSync(
@@ -119,14 +136,17 @@ export default defineConfig({
 
       const config = readFileSync(join(dir, "oke.config.ts"), "utf8");
       expect(config).toContain('local: "ollama"');
-      expect(config).toContain('ai: "ollama/ollama:latest"');
+      expect(config).toContain('ai: "ollama/ollama:0.32.6"');
       const env = readFileSync(join(dir, ".env.local"), "utf8");
-      expect(env).toContain("OKE_AI_DRIVER=ollama");
-      expect(env).toContain("OKE_AI_MODEL=gemma4:e4b");
-      const aiTs = readFileSync(join(dir, "src", "ai.ts"), "utf8");
+      expect(env).toContain("# OKE_AI_DRIVER=ollama");
+      expect(env).toMatch(/^OKE_AI_MODEL=gemma4:e4b$/m);
+      expect(env).not.toMatch(/^#\s*OKE_AI_MODEL=gemma4:e4b$/m);
+      expect(env).toContain("# OKE_AI_URL=http://127.0.0.1:11434");
+      expect(env).not.toMatch(/^OKE_AI_URL=/m);
+      const aiTs = readFileSync(join(dir, "src", "core", "ai.ts"), "utf8");
       expect(aiTs).toContain("smart");
       const app = readFileSync(join(dir, "src", "app.ts"), "utf8");
-      expect(app).toContain('import "./ai"');
+      expect(app).toContain('import "./core/ai"');
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

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

@@ -1,9 +1,10 @@
 /**
- * Write AI driver config, env, and `src/ai.ts` for `oke ai setup`.
+ * Write AI driver config, env, and `src/core/ai.ts` for `oke ai setup`.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { OLLAMA_IMAGE } from "../../docker/recipes/index.ts";
 
 /** Choices applied to the project. */
 export type AiSetupApplyInput = {
@@ -13,6 +14,10 @@ export type AiSetupApplyInput = {
   readonly visionModel?: string | null;
   readonly embedModel?: string | null;
   readonly apiKeyEnv?: string;
+  /** When set with {@link apiKeyEnv}, writes the token into `.env.local`. */
+  readonly apiKey?: string;
+  /** Optional `images.ai` pin (llama.cpp / Ollama / vLLM / SGLang). */
+  readonly image?: string;
 };
 
 /** Options for {@link applyAiSetup}. */
@@ -49,8 +54,10 @@ export function applyAiSetup(
   if (updateDrivers) {
     let config = readFileSync(configPath, "utf8");
     config = upsertAiDrivers(config, input.driver);
-    if (input.driver === "ollama") {
-      config = upsertImage(config, "ai", "ollama/ollama:latest");
+    if (input.image) {
+      config = upsertImage(config, "ai", input.image);
+    } else if (input.driver === "ollama") {
+      config = upsertImage(config, "ai", OLLAMA_IMAGE);
     }
     writeFileSync(configPath, config, "utf8");
   }
@@ -62,20 +69,29 @@ export function applyAiSetup(
     : existsSync(envExample)
       ? readFileSync(envExample, "utf8")
       : "";
-  env = upsertEnv(env, "OKE_AI_DRIVER", input.driver);
-  if (input.baseUrl) env = upsertEnv(env, "OKE_AI_URL", input.baseUrl);
+  // Driver / URL stay commented so docker mode can hydrate `OKE_AI_URL` from
+  // `docker/.env.docker` without being shadowed. The selected chat model is
+  // written active — `oke dev` seeds it into stack controls / `LLAMA_ARG_DOCKER_REPO`
+  // (commented-only left the compose default `smollm2` forever).
+  env = upsertEnv(env, "OKE_AI_DRIVER", input.driver, { comment: true });
+  if (input.baseUrl) env = upsertEnv(env, "OKE_AI_URL", input.baseUrl, { comment: true });
   if (input.chatModel) env = upsertEnv(env, "OKE_AI_MODEL", input.chatModel);
-  if (input.visionModel) env = upsertEnv(env, "OKE_AI_VISION_MODEL", input.visionModel);
-  if (input.embedModel) env = upsertEnv(env, "OKE_AI_EMBED_MODEL", input.embedModel);
+  if (input.visionModel) {
+    env = upsertEnv(env, "OKE_AI_VISION_MODEL", input.visionModel, { comment: true });
+  }
+  if (input.embedModel) {
+    env = upsertEnv(env, "OKE_AI_EMBED_MODEL", input.embedModel, { comment: true });
+  }
   if (input.apiKeyEnv) {
-    // Ensure the key name is present (value left blank for the user)
-    if (!new RegExp(`^${input.apiKeyEnv}=`, "m").test(env)) {
-      env = `${env.trimEnd()}\n${input.apiKeyEnv}=\n`;
+    if (input.apiKey !== undefined && input.apiKey.length > 0) {
+      env = upsertEnv(env, input.apiKeyEnv, input.apiKey);
+    } else if (!new RegExp(`^#?\\s*${input.apiKeyEnv}=`, "m").test(env)) {
+      env = `${env.trimEnd()}\n# ${input.apiKeyEnv}=\n`;
     }
   }
   writeFileSync(envPath, env.endsWith("\n") ? env : `${env}\n`, "utf8");
 
-  const aiTsPath = join(cwd, "src", "ai.ts");
+  const aiTsPath = join(cwd, "src", "core", "ai.ts");
   mkdirSync(dirname(aiTsPath), { recursive: true });
   writeFileSync(aiTsPath, renderAiTs(input), "utf8");
   ensureAiImported(cwd);
@@ -89,11 +105,11 @@ export function applyAiSetup(
  */
 export function upsertAiDrivers(source: string, driver: string): string {
   const block = `{
-    local: "${driver}",
-    docker: "${driver === "mock" ? "mock" : driver}",
-    test: "mock",
-    prod: "${driver === "mock" ? "mock" : driver}",
-  }`;
+      local: "${driver}",
+      docker: "${driver === "mock" ? "mock" : driver}",
+      test: "mock",
+      prod: "${driver === "mock" ? "mock" : driver}",
+    }`;
   // Top-level drivers.ai only (4-space indent) — never nest under channel.email.
   const aiRe = /^( {4})ai:\s*\{[\s\S]*?\n\1\}/m;
   if (aiRe.test(source)) {
@@ -131,13 +147,30 @@ export function upsertImage(source: string, key: string, image: string): string
   return source.replace(imagesRe, `images: {${body}\n${line}\n  }`);
 }
 
+/** Options for {@link upsertEnv}. */
+export type UpsertEnvOptions = {
+  /**
+   * When true, write `# KEY=value` (opt-in override). Used for AI stack keys
+   * so they do not shadow `docker/.env.docker`.
+   */
+  readonly comment?: boolean;
+};
+
 /**
+ * Insert or replace a dotenv assignment (optionally commented).
+ *
  * @param env - dotenv text
  * @param key - Variable name
  * @param value - Value
+ * @param options - Comment vs active line
  */
-export function upsertEnv(env: string, key: string, value: string): string {
-  const line = `${key}=${value}`;
+export function upsertEnv(
+  env: string,
+  key: string,
+  value: string,
+  options: UpsertEnvOptions = {},
+): string {
+  const line = options.comment ? `# ${key}=${value}` : `${key}=${value}`;
   const re = new RegExp(`^#?\\s*${key}=.*$`, "m");
   if (re.test(env)) return env.replace(re, line);
   const aiSection = /(# ── AI[^\n]*\n)/;
@@ -197,18 +230,27 @@ export function renderAiTs(input: AiSetupApplyInput): string {
 }
 
 /**
- * Ensure `src/app.ts` (or `src/core.ts`) imports `./ai`.
+ * Ensure `src/app.ts` or `src/core/index.ts` imports AI wiring.
  *
  * @param cwd - Project root
  */
 function ensureAiImported(cwd: string): void {
-  for (const rel of ["src/app.ts", "src/core.ts"]) {
+  const candidates: ReadonlyArray<{ readonly rel: string; readonly importLine: string }> = [
+    { rel: "src/app.ts", importLine: `import "./core/ai";\n` },
+    { rel: "src/core/index.ts", importLine: `import "./ai";\n` },
+    { rel: "src/core.ts", importLine: `import "./ai";\n` },
+  ];
+  for (const { rel, importLine } of candidates) {
     const path = join(cwd, rel);
     if (!existsSync(path)) continue;
     const src = readFileSync(path, "utf8");
-    if (/from\s+["']\.\/ai["']/.test(src) || /import\s+["']\.\/ai["']/.test(src)) return;
-    const next = `import "./ai";\n${src}`;
-    writeFileSync(path, next, "utf8");
+    if (
+      /from\s+["']\.\/(?:core\/)?ai["']/.test(src) ||
+      /import\s+["']\.\/(?:core\/)?ai["']/.test(src)
+    ) {
+      return;
+    }
+    writeFileSync(path, `${importLine}${src}`, "utf8");
     return;
   }
 }