okengine 0.6.1 → 0.8.0

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

@@ -13,14 +13,14 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## SQL store
 
-| Variable            | Used for                                             | Default when unset              |
-| ------------------- | ---------------------------------------------------- | ------------------------------- |
-| `DATABASE_URL`      | Postgres connection (`postgres` driver, drizzle-kit) | `postgres://localhost:5432/oke` |
-| `OKE_STORE_SQL_URL` | Explicit SQL URL override                            | —                               |
-| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                   | `.oke/app.sqlite`               |
-| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)            | `.oke/app.libsql`               |
-| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)     | `.oke/pgdata`                   |
-| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                      | config map                      |
+| Variable            | Used for                                                                      | Default when unset              |
+| ------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
+| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal drivers, drizzle-kit) | `postgres://localhost:5432/oke` |
+| `OKE_STORE_SQL_URL` | Explicit SQL URL override                                                     | —                               |
+| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                                            | `.oke/app.sqlite`               |
+| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)                                     | `.oke/app.libsql`               |
+| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)                              | `.oke/pgdata`                   |
+| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                               | config map                      |
 
 ## Index store
 
@@ -74,6 +74,8 @@ Read when `drivers.channel.email` resolves to that driver id.
 | `RESEND_API_KEY`        | `resend` API key                                 |
 | `SNDR_API_KEY`          | `sndr` API key                                   |
 | `SNDR_BASE_URL`         | Optional SNDR API origin (default `api.sndr.sh`) |
+| `TAQNYAT_MAIL_TOKEN`    | `taqnyat-mail` bearer token (Email-enabled)      |
+| `TAQNYAT_CAMPAIGN`      | `taqnyat-mail` campaign name                     |
 
 ## Channel (SMS) — boot binder
 
@@ -94,18 +96,30 @@ Read when `drivers.channel.sms` resolves to that driver id (`console` opens noth
 WhatsApp (`wa-cloud`) and push (`webpush` / `fcm`) are not opened from env at
 boot — pass them on `BootOptions.channel.drivers` with their open options.
 
+## Live test gates (opt-in)
+
+Provider-quota-burning live suites are double-gated: the medium flag **plus** that
+provider's real credentials — credentials alone never send.
+
+| Variable         | Used for                                                  |
+| ---------------- | --------------------------------------------------------- |
+| `OKE_SMS_LIVE`   | `=1` allows live SMS provider tests (e.g. Taqnyat OTP)    |
+| `OKE_EMAIL_LIVE` | `=1` allows live email provider tests (e.g. Taqnyat Mail) |
+
 ## 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`                      |
-| `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`          | 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                                                                     | —                                 |
 
 ## Framework behavior
 

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

@@ -29,17 +29,18 @@ string. Custom app codes stay message-less until registered.
 
 ## OKE numeric codes
 
-| Code   | Name              | Cause                                            | Fix                                             |
-| ------ | ----------------- | ------------------------------------------------ | ----------------------------------------------- |
-| `1001` | undeclared read   | Flow reads a resource not in `effects.reads`     | Add it to the flow's `effects.reads`            |
-| `1002` | undeclared write  | Flow writes a resource not in `effects.writes`   | Add it to the flow's `effects.writes`           |
-| `1003` | undeclared emit   | Flow emits a signal not in `effects.emits`       | Add it to the flow's `effects.emits`            |
-| `1004` | undeclared send   | Flow sends a template not in `effects.sends`     | Add it to the flow's `effects.sends`            |
-| `1005` | undeclared ask    | Flow asks a prompt not in `effects.asks`         | Add it to the flow's `effects.asks`             |
-| `1006` | undeclared secret | Flow reads a secret not in `effects.secrets`     | Add it to the flow's `effects.secrets`          |
-| `1007` | undeclared call   | Flow calls a flow not in `effects.calls`         | Add it to the flow's `effects.calls`            |
-| `1042` | orphan emit       | Emitted signal has no subscriber                 | Add `on(signal, …)` or declare `optional: true` |
-| `1101` | schema missing    | Domain table absent in docker/prod — no auto-DDL | Run `oke db migrate` against this environment   |
+| Code   | Name              | Cause                                            | Fix                                                |
+| ------ | ----------------- | ------------------------------------------------ | -------------------------------------------------- |
+| `1001` | undeclared read   | Flow reads a resource not in `effects.reads`     | Add it to the flow's `effects.reads`               |
+| `1002` | undeclared write  | Flow writes a resource not in `effects.writes`   | Add it to the flow's `effects.writes`              |
+| `1003` | undeclared emit   | Flow emits a signal not in `effects.emits`       | Add it to the flow's `effects.emits`               |
+| `1004` | undeclared send   | Flow sends a template not in `effects.sends`     | Add it to the flow's `effects.sends`               |
+| `1005` | undeclared ask    | Flow asks a prompt not in `effects.asks`         | Add it to the flow's `effects.asks`                |
+| `1006` | undeclared secret | Flow reads a secret not in `effects.secrets`     | Add it to the flow's `effects.secrets`             |
+| `1007` | undeclared call   | Flow calls a flow not in `effects.calls`         | Add it to the flow's `effects.calls`               |
+| `1042` | orphan emit       | Emit with zero subscribers and `optional` false  | Add `on(signal, …)` or declare `optional: true`    |
+| `1043` | signal schema     | Emit payload failed the signal's `schema`        | Pass a payload that matches `schema`, or remove it |
+| `1101` | schema missing    | Domain table absent in docker/prod — no auto-DDL | Run `oke db migrate` against this environment      |
 
 <Callout title="Effects are usually inferred">
   The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an

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

@@ -16,24 +16,26 @@ flow({
 
 ## Stores
 
-| Signature                                                           | Records      | Returns                                                   |
-| ------------------------------------------------------------------- | ------------ | --------------------------------------------------------- |
-| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | rows (`where` · `orderBy` · `limit` · `offset` chainable) |
-| `fx.store(sqlDecl).insert(t).values(v)`                             | `write`      | `Promise<void>`                                           |
-| `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`      | `Promise<void>`                                           |
-| `fx.store(sqlDecl).delete(t).where(…)`                              | `write`      | `Promise<void>`                                           |
-| `fx.store(sqlDecl).findById(t, id)`                                 | `read`       | row \| undefined                                          |
-| `fx.store(kv).get / set(key, value, ttl?) / delete / list(prefix?)` | read / write | per op                                                    |
-| `fx.store(files).put / get / delete / list(prefix?)`                | read / write | per op                                                    |
-| `fx.store(index).upsert / search(vector, topK?) / delete`           | read / write | per op                                                    |
+| Signature                                                           | Records      | Returns                                                                                     |
+| ------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | rows (`where` · `orderBy` · `limit` · `offset` chainable)                                   |
+| `fx.store(sqlDecl).insert(t).values(v)`                             | `write`      | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`      | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).delete(t).where(…)`                              | `write`      | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).findById(t, id)`                                 | `read`       | row \| undefined                                                                            |
+| `fx.store(kv).get / set(key, value, ttl?) / delete / list(prefix?)` | read / write | per op                                                                                      |
+| `fx.store(files).put / get / delete / list(prefix?)`                | read / write | per op                                                                                      |
+| `fx.store(files).image(key\|bytes).…`                               | read / write | Bun.Image chain; terminals gate (see [Store](/docs/elements/store#images--image--putimage)) |
+| `fx.store(files).putImage(key, data, opts?)`                        | `write`      | original + variants (+ optional LQIP)                                                       |
+| `fx.store(index).upsert / search(vector, topK?) / delete`           | read / write | per op                                                                                      |
 
 See [Store](/docs/elements/store) for the query-builder surface.
 
 ## Signals
 
-| Signature                   | Records | Notes                                            |
-| --------------------------- | ------- | ------------------------------------------------ |
-| `fx.emit(signal, payload?)` | `emit`  | With the postgres driver, joins your transaction |
+| 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) |
 
 ## Flows
 

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

@@ -45,7 +45,9 @@ Our path is concrete: a booking name containing "ignore previous instructions an
 - **Plugin panels** run in a sandboxed iframe without `allow-same-origin`, communicating only over a `postMessage` bridge with their own CSP, no access to the operator session token, and exposure limited to that plugin's declared flows.
 - **Session and framing:** `frame-ancestors 'none'`, `SameSite=Strict`, step-up authentication before destructive actions.
 - **Secret write path:** TLS required, no autocomplete, never echoed, never logged, not retained in browser memory after submission.
-- **The setup claim code** is rate-limited and compared in constant time.
+- **The setup claim code** is rate-limited and compared in constant time. The first-operator password
+  uses the same policy as Gate auth (minLength 12, letter + number); weak passwords return
+  `ClaimFailed` / `password_policy`, not an opaque 500.
 
 #### 10.5 Reversibility governs the confirmation pattern
 

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

@@ -0,0 +1,144 @@
+/**
+ * Unit tests for `oke ai setup` catalog, detect, and apply.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyAiSetup, renderAiTs, upsertAiDrivers, upsertEnv } from "./apply.ts";
+import { cloudChatModels, recommendChatModel, recommendCloudChat } from "./catalog.ts";
+import { isInstalled, parseOllamaList } from "./detect-ollama.ts";
+import { parseAiSetupArgs } from "./index.ts";
+
+describe("catalog", () => {
+  test("recommendChatModel respects RAM tiers", () => {
+    expect(recommendChatModel(8).id).toBe("gemma4:e4b");
+    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("anthropic").some((m) => m.recommended)).toBe(true);
+    expect(recommendCloudChat("openai")).toBe("gpt-4o-mini");
+    expect(recommendCloudChat("anthropic")).toContain("claude");
+  });
+});
+
+describe("detect-ollama", () => {
+  test("parseOllamaList skips header", () => {
+    const out = parseOllamaList(`NAME           ID      SIZE
+qwen3.5:9b     abc     5.0 GB
+nomic-embed-text  def  274 MB
+`);
+    expect(out).toEqual(["qwen3.5:9b", "nomic-embed-text"]);
+  });
+
+  test("isInstalled matches mlx suffixes", () => {
+    expect(isInstalled("qwen3.5:9b", ["qwen3.5:9b-mlx"])).toBe(true);
+    expect(isInstalled("gemma4:e4b", ["qwen3.5:9b"])).toBe(false);
+  });
+});
+
+describe("apply", () => {
+  test("upsertAiDrivers inserts after channel (sibling, not nested)", () => {
+    const src = `export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        local: "console",
+        docker: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {},
+});
+`;
+    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:");
+  });
+
+  test("upsertEnv uncomment / set", () => {
+    const env = `# OKE_AI_DRIVER=mock\nOKE_AI_URL=http://x\n`;
+    expect(upsertEnv(env, "OKE_AI_DRIVER", "ollama")).toContain("OKE_AI_DRIVER=ollama");
+  });
+
+  test("renderAiTs includes vision + embed", () => {
+    const ts = renderAiTs({
+      driver: "ollama",
+      chatModel: "gemma4:e4b",
+      visionModel: "qwen3-vl:4b",
+      embedModel: "nomic-embed-text",
+    });
+    expect(ts).toContain('ai.model("smart"');
+    expect(ts).toContain('ai.model("vision"');
+    expect(ts).toContain("docsEmbed");
+  });
+
+  test("applyAiSetup writes config, env, ai.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-"));
+    try {
+      writeFileSync(
+        join(dir, "oke.config.ts"),
+        `import { defineConfig } from "okengine/config";
+export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        local: "console",
+        docker: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {
+    "store.sql": "postgres:18-alpine",
+  },
+});
+`,
+        "utf8",
+      );
+      mkdirSync(join(dir, "src"), { recursive: true });
+      writeFileSync(join(dir, "src", "app.ts"), `export 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 config = readFileSync(join(dir, "oke.config.ts"), "utf8");
+      expect(config).toContain('local: "ollama"');
+      expect(config).toContain('ai: "ollama/ollama:latest"');
+      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(aiTs).toContain("smart");
+      const app = readFileSync(join(dir, "src", "app.ts"), "utf8");
+      expect(app).toContain('import "./ai"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("parseAiSetupArgs", () => {
+  test("parses provider and models", () => {
+    const a = parseAiSetupArgs(["--provider", "ollama", "--chat=qwen3.5:9b", "--no-pull", "--yes"]);
+    expect(a.provider).toBe("ollama");
+    expect(a.chat).toBe("qwen3.5:9b");
+    expect(a.pull).toBe(false);
+    expect(a.yes).toBe(true);
+  });
+});

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

@@ -0,0 +1,214 @@
+/**
+ * Write AI driver config, env, and `src/ai.ts` for `oke ai setup`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Choices applied to the project. */
+export type AiSetupApplyInput = {
+  readonly driver: "ollama" | "anthropic" | "openai-compatible" | "mock";
+  readonly baseUrl?: string;
+  readonly chatModel?: string;
+  readonly visionModel?: string | null;
+  readonly embedModel?: string | null;
+  readonly apiKeyEnv?: string;
+};
+
+/** Options for {@link applyAiSetup}. */
+export type AiSetupApplyOptions = {
+  /**
+   * When false, leave `drivers.ai` / `images.ai` alone (create-oke already
+   * wrote per-env pins). Default true for standalone `oke ai setup`.
+   */
+  readonly updateDrivers?: boolean;
+};
+
+/**
+ * Apply AI setup to a project root.
+ *
+ * @param cwd - Project root
+ * @param input - Selected provider / models
+ * @param options - Pin-preserving knobs for create-oke
+ */
+export function applyAiSetup(
+  cwd: string,
+  input: AiSetupApplyInput,
+  options: AiSetupApplyOptions = {},
+): {
+  readonly configPath: string;
+  readonly envPath: string;
+  readonly aiTsPath: string;
+} {
+  const updateDrivers = options.updateDrivers !== false;
+  const configPath = join(cwd, "oke.config.ts");
+  if (!existsSync(configPath)) {
+    throw new Error("oke ai setup: no oke.config.ts in the current directory");
+  }
+
+  if (updateDrivers) {
+    let config = readFileSync(configPath, "utf8");
+    config = upsertAiDrivers(config, input.driver);
+    if (input.driver === "ollama") {
+      config = upsertImage(config, "ai", "ollama/ollama:latest");
+    }
+    writeFileSync(configPath, config, "utf8");
+  }
+
+  const envPath = join(cwd, ".env.local");
+  const envExample = join(cwd, ".env.example");
+  let env = existsSync(envPath)
+    ? readFileSync(envPath, "utf8")
+    : existsSync(envExample)
+      ? readFileSync(envExample, "utf8")
+      : "";
+  env = upsertEnv(env, "OKE_AI_DRIVER", input.driver);
+  if (input.baseUrl) env = upsertEnv(env, "OKE_AI_URL", input.baseUrl);
+  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.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`;
+    }
+  }
+  writeFileSync(envPath, env.endsWith("\n") ? env : `${env}\n`, "utf8");
+
+  const aiTsPath = join(cwd, "src", "ai.ts");
+  mkdirSync(dirname(aiTsPath), { recursive: true });
+  writeFileSync(aiTsPath, renderAiTs(input), "utf8");
+  ensureAiImported(cwd);
+
+  return { configPath, envPath, aiTsPath };
+}
+
+/**
+ * @param source - oke.config.ts
+ * @param driver - AI driver id
+ */
+export function upsertAiDrivers(source: string, driver: string): string {
+  const block = `{
+    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)) {
+    return source.replace(aiRe, `$1ai: ${block}`);
+  }
+  const channelRe = /^( {4})channel:\s*\{[\s\S]*?\n\1\},?\n/m;
+  if (channelRe.test(source)) {
+    return source.replace(channelRe, (match) => `${match}    ai: ${block},\n`);
+  }
+  const driversClose = /(drivers:\s*\{[\s\S]*?)(\n\s*\},)/;
+  if (!driversClose.test(source)) {
+    throw new Error("oke ai setup: could not find drivers block in oke.config.ts");
+  }
+  return source.replace(driversClose, `$1\n    ai: ${block},$2`);
+}
+
+/**
+ * @param source - Config source
+ * @param key - Image role
+ * @param image - Image ref
+ */
+export function upsertImage(source: string, key: string, image: string): string {
+  const keyLit = key.includes(".") ? `"${key}"` : key;
+  const line = `    ${keyLit}: "${image}",`;
+  const imagesRe = /images:\s*\{([\s\S]*?)\n\s*\}/;
+  const m = imagesRe.exec(source);
+  if (!m) return source;
+  const body = m[1]!;
+  if (new RegExp(`${keyLit}\\s*:`).test(body) || new RegExp(`"${key}"\\s*:`).test(body)) {
+    return source.replace(
+      new RegExp(`(["']?${key.replace(".", "\\.")}["']?\\s*:\\s*)"[^"]*"`),
+      `$1"${image}"`,
+    );
+  }
+  return source.replace(imagesRe, `images: {${body}\n${line}\n  }`);
+}
+
+/**
+ * @param env - dotenv text
+ * @param key - Variable name
+ * @param value - Value
+ */
+export function upsertEnv(env: string, key: string, value: string): string {
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^#?\\s*${key}=.*$`, "m");
+  if (re.test(env)) return env.replace(re, line);
+  const aiSection = /(# ── AI[^\n]*\n)/;
+  if (aiSection.test(env)) {
+    return env.replace(aiSection, `$1${line}\n`);
+  }
+  return `${env.trimEnd()}\n\n# ── AI ──────────────────────────────────────────────────────\n${line}\n`;
+}
+
+/**
+ * @param input - Setup choices
+ */
+export function renderAiTs(input: AiSetupApplyInput): string {
+  const chat = input.chatModel ?? "default";
+  const provider =
+    input.driver === "ollama"
+      ? "ollama"
+      : input.driver === "anthropic"
+        ? "anthropic"
+        : input.driver === "mock"
+          ? "mock"
+          : "openai-compatible";
+
+  const lines = [
+    `import { ai } from "okengine";`,
+    ``,
+    `export const smart = ai.model("smart", {`,
+    `  provider: "${provider}",`,
+    `  model: process.env.OKE_AI_MODEL ?? "${chat}",`,
+    `});`,
+  ];
+
+  if (input.visionModel) {
+    lines.push(
+      ``,
+      `export const vision = ai.model("vision", {`,
+      `  provider: "${provider}",`,
+      `  model: process.env.OKE_AI_VISION_MODEL ?? "${input.visionModel}",`,
+      `});`,
+    );
+  }
+
+  if (input.embedModel) {
+    lines.push(
+      ``,
+      `export const embedModel = ai.model("embed", {`,
+      `  provider: "${provider}",`,
+      `  model: process.env.OKE_AI_EMBED_MODEL ?? "${input.embedModel}",`,
+      `});`,
+      ``,
+      `export const docsEmbed = ai.embed("docs", { model: embedModel });`,
+    );
+  }
+
+  lines.push(``);
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Ensure `src/app.ts` (or `src/core.ts`) imports `./ai`.
+ *
+ * @param cwd - Project root
+ */
+function ensureAiImported(cwd: string): void {
+  for (const rel of ["src/app.ts", "src/core.ts"]) {
+    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");
+    return;
+  }
+}