okengine 0.10.2 → 0.11.0

package/src/cli/doctor.ts

@@ -3,17 +3,76 @@
  */
 
 import { resolve } from "node:path";
+import type {
+  ConfigEnv,
+  DriverRef,
+  DriversConfig,
+  EnvDriverMap,
+  VaultElementConfig,
+} from "../config/index.ts";
+import { resolveEffectiveDrivers, type EffectiveDriversConfig } from "../config/driver-defaults.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { APP_PORT, CONSOLE_PORT, MCP_PORT } from "../runtime/types.ts";
 import { hasFlag, wantsJson } from "./args.ts";
 import { checkManifestPiiAsks } from "./doctor-pii.ts";
 import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
-import { loadManifest } from "./load-config.ts";
+import { loadManifest, loadOkeConfig } from "./load-config.ts";
 import { isPortInUse } from "./ports.ts";
 import { schemaFingerprint, readSchemaFingerprint } from "./schema.ts";
 
 export { isPortInUse } from "./ports.ts";
 
+/**
+ * `label → merged EnvDriverMap` pairs, in the fixed order shown by
+ * {@link formatDriversSummary} / the `drivers` JSON key.
+ *
+ * @param drivers - Fully-resolved drivers config
+ */
+function flattenEffectiveDrivers(
+  drivers: EffectiveDriversConfig,
+): ReadonlyArray<readonly [string, EnvDriverMap]> {
+  return [
+    ["store.sql", drivers.store.sql],
+    ["store.kv", drivers.store.kv],
+    ["store.files", drivers.store.files],
+    ["signal", drivers.signal],
+    ["clock", drivers.clock],
+    ["journal", drivers.journal],
+    ["vault", drivers.vault],
+    ["channel.email", drivers.channel.email],
+    ["channel.sms", drivers.channel.sms],
+  ];
+}
+
+/**
+ * @param ref - Driver ref (string id, rich `{ driver }` object, or unset)
+ */
+function driverRefId(ref: DriverRef | undefined): string {
+  if (ref === undefined) return "—";
+  return typeof ref === "string" ? ref : ref.driver;
+}
+
+/**
+ * Render the fully-resolved drivers config as aligned text lines — every
+ * default plus every override, per env, for a developer whose own
+ * `oke.config.ts` only pins a handful of keys.
+ *
+ * @param drivers - Fully-resolved drivers config
+ * @param configEnv - Active env (marked in the active-driver column)
+ */
+function formatDriversSummary(drivers: EffectiveDriversConfig, configEnv: ConfigEnv): string {
+  const rows = flattenEffectiveDrivers(drivers);
+  const nameWidth = Math.max(...rows.map(([name]) => name.length));
+  const activeWidth = Math.max(...rows.map(([, map]) => driverRefId(map[configEnv]).length));
+  const lines = [`drivers (env=${configEnv}):`];
+  for (const [name, map] of rows) {
+    const active = driverRefId(map[configEnv]);
+    const full = `dev=${driverRefId(map.dev)} test=${driverRefId(map.test)} prod=${driverRefId(map.prod)}`;
+    lines.push(`  ${name.padEnd(nameWidth)}  ${active.padEnd(activeWidth)}  { ${full} }`);
+  }
+  return lines.join("\n");
+}
+
 /** One doctor finding. */
 export interface DoctorFinding {
   readonly code:
@@ -23,7 +82,8 @@ export interface DoctorFinding {
     | "db_drift"
     | "tenancy"
     | "driver"
-    | "pii_ask";
+    | "pii_ask"
+    | "vault_master_key";
   readonly severity: "error" | "warn";
   readonly message: string;
 }
@@ -55,6 +115,23 @@ export interface DoctorOptions {
   }>;
   /** Skip live DB drift probe (default false). */
   readonly skipDbDrift?: boolean;
+  /**
+   * Inject the `drivers` block directly (tests) — skips loading
+   * `oke.config.ts` from disk. When omitted, `oke doctor` best-effort loads
+   * `oke.config.ts` from {@link cwd}; a project without one just gets the
+   * real, untouched defaults in the drivers summary.
+   */
+  readonly driversConfig?: DriversConfig;
+  /**
+   * Inject the `vault` block directly (tests). When omitted, it is read
+   * from the same best-effort `oke.config.ts` load as {@link driversConfig}.
+   */
+  readonly vaultConfig?: VaultElementConfig;
+  /**
+   * Active {@link ConfigEnv} for the drivers summary. Default: `dev` when
+   * `OKE_DOCKER=1` (via {@link env}), else `test`.
+   */
+  readonly configEnv?: ConfigEnv;
   readonly write?: (text: string) => void;
   /** Write hints / progress (defaults to stderr). */
   readonly writeErr?: (text: string) => void;
@@ -92,6 +169,25 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   const env = options.env ?? ((k) => Bun.env[k] ?? process.env[k]);
   const secretNames = options.secrets ?? (manifest?.vault ? Object.keys(manifest.vault) : []);
 
+  // Fully-resolved `drivers.*` — real defaults + every override merged, so
+  // the picture is complete even when `oke.config.ts` only pins one key.
+  let driversConfig = options.driversConfig;
+  let vaultConfig = options.vaultConfig;
+  if (driversConfig === undefined || vaultConfig === undefined) {
+    try {
+      const loaded = (await loadOkeConfig(cwd)).config;
+      driversConfig ??= loaded.drivers;
+      vaultConfig ??= loaded.vault;
+    } catch {
+      // No oke.config.ts (or it failed to load) — show real defaults only.
+    }
+  }
+  // Match `bootApplication`: production NODE_ENV → prod; compose → dev; else test.
+  const configEnv: ConfigEnv =
+    options.configEnv ??
+    (env("NODE_ENV") === "production" ? "prod" : env("OKE_DOCKER") === "1" ? "dev" : "test");
+  const effectiveDrivers = resolveEffectiveDrivers(driversConfig);
+
   for (const name of secretNames) {
     const value = env(name);
     if (value === undefined || value.length === 0) {
@@ -104,6 +200,25 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
     }
   }
 
+  // An env-var master key is only as protected as the process environment:
+  // it lands in shell history, orchestrator manifests, and crash dumps.
+  const usesBuiltinVault =
+    vaultConfig !== undefined || driverRefId(effectiveDrivers.vault[configEnv]) === "vault";
+  if (
+    configEnv === "prod" &&
+    usesBuiltinVault &&
+    (vaultConfig?.encryption?.masterKey?.kind ?? "env") === "env"
+  ) {
+    findings.push({
+      code: "vault_master_key",
+      // Fail closed in prod: an env-sourced master key collapses envelope
+      // protection the moment DB + env are stolen together.
+      severity: "error",
+      message:
+        'vault master key comes from an environment variable in prod — set vault.encryption.masterKey = { kind: "kms", keyId } (or use managed aws-secrets-manager) so the key is never readable from the process environment',
+    });
+  }
+
   const ports = options.ports ?? [APP_PORT, CONSOLE_PORT, MCP_PORT];
   const probe = options.isPortInUse ?? isPortInUse;
   for (const port of ports) {
@@ -133,13 +248,13 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
         code: "schema_drift",
         severity: "error",
         message:
-          "core stub schema drift — run `oke schema generate` (schema/oke.ts; not domain migrations)",
+          "core stub schema drift — run `oke schema generate` (.oke/schema/oke.ts; not domain migrations)",
       });
     } else if (expected !== null && current === null) {
       findings.push({
         code: "schema_drift",
         severity: "error",
-        message: "schema/oke.ts missing — run `oke schema generate` (core/plugin stubs)",
+        message: ".oke/schema/oke.ts missing — run `oke schema generate` (core/plugin stubs)",
       });
     }
   }
@@ -157,7 +272,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
           severity: "error",
           message:
             drift.detail ??
-            "domain schema differs from the database — run `oke db generate` then `oke db migrate` (or `oke db push` in local)",
+            "domain schema differs from the database — run `oke db generate` then `oke db migrate` (or `oke db push` in dev)",
         });
       }
     }
@@ -177,7 +292,9 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   const code = ok ? EXIT_OK : EXIT_RUNTIME;
 
   if (json) {
-    write(`${JSON.stringify({ ok, findings }, null, 2)}\n`);
+    write(
+      `${JSON.stringify({ ok, findings, drivers: { env: configEnv, resolved: effectiveDrivers } }, null, 2)}\n`,
+    );
     if (!ok) {
       writeErr("Hint: fix error-severity findings, then re-run oke doctor.\n");
     }
@@ -186,6 +303,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
 
   if (findings.length === 0) {
     write("oke doctor: ok\n");
+    write(`${formatDriversSummary(effectiveDrivers, configEnv)}\n`);
     return { code: EXIT_OK, findings };
   }
 
@@ -193,6 +311,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   for (const f of findings) {
     write(`  [${f.severity}] ${f.code}: ${f.message}\n`);
   }
+  write(`${formatDriversSummary(effectiveDrivers, configEnv)}\n`);
   return { code, findings };
 }
 
@@ -208,16 +327,30 @@ export async function doctorCli(args: readonly string[]): Promise<number> {
   }
 
   let manifestPath: string | undefined;
+  let configEnv: ConfigEnv | undefined;
   const json = wantsJson(args);
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--manifest" || a === "-m") manifestPath = args[++i];
-    else if (a === "--help" || a === "-h") {
-      console.log(`oke doctor [--manifest|-m path] [--json|-j]
+    else if (a === "--env" || a === "-e") {
+      const value = args[++i];
+      if (value === "dev" || value === "test" || value === "prod") {
+        configEnv = value;
+      } else if (value === "local") {
+        configEnv = "test";
+      } else if (value === "docker") {
+        configEnv = "dev";
+      }
+    } else if (a === "--help" || a === "-h") {
+      console.log(`oke doctor [--manifest|-m path] [--env|-e dev|test|prod] [--json|-j]
 oke doctor --diff|-d [--before|-b <path> --after|-a <path>] [--base|-B <branch>]
 
 Verify secrets, ports, schema drift, and PII→model egress before serving.
+Also prints drivers.* fully resolved (every default + every override merged)
+for the active env, from oke.config.ts.
 
+--env   Env to resolve drivers for (default: prod when NODE_ENV=production,
+        dev when OKE_DOCKER=1 / \`oke dev\`, else test).
 --diff  CI gate: block undeclared contract breaks (Manifest Diff).
         Default baseline is git merge-base (main/master) vs the working
         tree; pass --before/--after for an explicit comparison.
@@ -227,6 +360,6 @@ Verify secrets, ports, schema drift, and PII→model egress before serving.
       return EXIT_OK;
     }
   }
-  const { code } = await runDoctor({ manifestPath, json });
+  const { code } = await runDoctor({ manifestPath, configEnv, json });
   return code;
 }

package/src/cli/drizzle-env.test.ts

@@ -24,22 +24,20 @@ async function tempDir(): Promise<string> {
 const dualConfig = {
   drivers: {
     store: {
-      sql: { local: "sqlite", docker: "postgres", prod: "postgres", test: "memory" },
+      sql: { dev: "postgres", test: "pglite", prod: "postgres" },
     },
   },
 } as unknown as OkeConfig;
 
 describe("resolveDrizzleKitEnv", () => {
-  test("local env → sqlite dialect + sqlite url", async () => {
+  test("test env → postgresql dialect (pglite)", async () => {
     const dir = await tempDir();
-    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "local");
-    expect(ctx.dialect).toBe("sqlite");
-    expect(ctx.overlay.OKE_DRIZZLE_DIALECT).toBe("sqlite");
-    expect(ctx.overlay.OKE_SQLITE_URL).toContain(".oke/app.sqlite");
-    expect(ctx.overlay.DATABASE_URL).toBeUndefined();
+    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "test");
+    expect(ctx.dialect).toBe("postgresql");
+    expect(ctx.overlay.OKE_DRIZZLE_DIALECT).toBe("postgresql");
   });
 
-  test("docker env → postgresql dialect + DATABASE_URL from compose env", async () => {
+  test("dev env → postgresql dialect + DATABASE_URL from compose env", async () => {
     const dir = await tempDir();
     await mkdir(join(dir, "docker"), { recursive: true });
     await writeFile(
@@ -49,7 +47,7 @@ describe("resolveDrizzleKitEnv", () => {
     const prevDb = process.env["DATABASE_URL"];
     delete process.env["DATABASE_URL"];
     try {
-      const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "docker");
+      const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "dev");
       expect(ctx.dialect).toBe("postgresql");
       expect(ctx.overlay.OKE_DRIZZLE_DIALECT).toBe("postgresql");
       expect(ctx.overlay.DATABASE_URL).toBe("postgres://u:p@127.0.0.1:5432/oke");
@@ -60,16 +58,16 @@ describe("resolveDrizzleKitEnv", () => {
     }
   });
 
-  test("docker dialect is postgresql even when DATABASE_URL unset (no URL guessing)", async () => {
+  test("dev dialect is postgresql even when DATABASE_URL unset (no URL guessing)", async () => {
     const dir = await tempDir();
-    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "docker");
+    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "dev");
     expect(ctx.dialect).toBe("postgresql");
   });
 
   test("unsupported driver id errors clearly", async () => {
     const dir = await tempDir();
-    const bad = { drivers: { store: { sql: { local: "memory" } } } } as unknown as OkeConfig;
-    await expect(resolveDrizzleKitEnv(dir, bad, "local")).rejects.toThrow(/not supported/);
+    const bad = { drivers: { store: { sql: { test: "memory" } } } } as unknown as OkeConfig;
+    await expect(resolveDrizzleKitEnv(dir, bad, "test")).rejects.toThrow(/not supported/);
   });
 });
 

package/src/cli/drizzle-env.ts

@@ -64,36 +64,43 @@ export async function applyComposeEnvToProcess(cwd: string): Promise<readonly st
  * Dialect comes from the configured driver via the exhaustive
  * `SQL_DRIVER_TO_DRIZZLE_DIALECT` map — a missing/unsupported driver id is a
  * compile-time gap there, and a clear runtime error here (never a silent
- * sqlite fallback).
+ * fallback).
  *
  * @param cwd - Project root
- * @param config - Loaded `oke.config.ts` (null → sqlite/local defaults)
- * @param env - Active env (`local` | `docker` for dev tooling)
+ * @param config - Loaded `oke.config.ts` (null → postgres/dev defaults)
+ * @param env - Active {@link ConfigEnv}
  */
 export async function resolveDrizzleKitEnv(
   cwd: string,
   config: OkeConfig | null | undefined,
   env: ConfigEnv,
 ): Promise<DrizzleKitEnvContext> {
-  const driverId = resolveDriverId(config?.drivers?.store?.sql, env) ?? "sqlite";
-  if (driverId !== "sqlite" && driverId !== "postgres") {
+  const driverId = resolveDriverId(config?.drivers?.store?.sql, env) ?? "postgres";
+  if (driverId !== "postgres" && driverId !== "pglite") {
     throw new Error(
-      `oke db: store.sql driver "${driverId}" is not supported by drizzle-kit (sqlite | postgres)`,
+      `oke db: store.sql driver "${driverId}" is not supported by drizzle-kit (postgres | pglite)`,
     );
   }
   const dialect = drizzleDialectFromSqlDriver(driverId);
 
-  const compose = env === "docker" ? await readComposeEnv(cwd) : new Map<string, string>();
+  const compose = env === "dev" ? await readComposeEnv(cwd) : new Map<string, string>();
 
   const overlay: Record<string, string> = { OKE_DRIZZLE_DIALECT: dialect };
-  if (dialect === "postgresql") {
+  if (driverId === "pglite") {
     const url =
+      process.env.OKE_PGLITE_URL ??
+      compose.get("OKE_PGLITE_URL") ??
+      (env === "test" ? "memory://" : ".oke/pgdata");
+    overlay.OKE_PGLITE_URL = url;
+    // drizzle-kit still wants a postgres-shaped URL for dialect postgresql when
+    // not using PGlite kit plugins — prefer DATABASE_URL from compose for push.
+    const pgUrl =
       process.env.DATABASE_URL ?? compose.get("DATABASE_URL") ?? compose.get("OKE_STORE_SQL_URL");
-    if (url !== undefined) overlay.DATABASE_URL = url;
+    if (pgUrl !== undefined) overlay.DATABASE_URL = pgUrl;
   } else {
     const url =
-      process.env.OKE_SQLITE_URL ?? compose.get("OKE_SQLITE_URL") ?? "file:.oke/app.sqlite";
-    overlay.OKE_SQLITE_URL = url;
+      process.env.DATABASE_URL ?? compose.get("DATABASE_URL") ?? compose.get("OKE_STORE_SQL_URL");
+    if (url !== undefined) overlay.DATABASE_URL = url;
   }
   return { env, dialect, overlay };
 }

package/src/cli/ensure-drizzle-config.ts

@@ -5,32 +5,29 @@
 
 import { resolve } from "node:path";
 
-/** Mode-aware template (matches create-oke templates' drizzle.config.ts). */
+/** PostgreSQL-only template (matches create-oke templates' drizzle.config.ts). */
 const DRIZZLE_CONFIG_TEMPLATE = `import { defineConfig } from "drizzle-kit";
 
 /**
  * Domain schema sync for \`oke db push|generate|migrate\`.
  *
- * Dialect comes from OKE's \`store.sql\` driver map (resolved by the CLI and
- * injected as \`OKE_DRIZZLE_DIALECT\`) — never inferred from \`DATABASE_URL\`
- * presence. \`src/db/schema.generated.ts\` is emitted from \`src/db/schema.decl.ts\`
- * for the active dialect as a pre-step of \`oke db\` / \`oke dev\`.
+ * SQL is PostgreSQL-only (postgres / pglite). Domain tables come from
+ * \`src/db/schema.decl.ts\` → \`src/db/schema.drizzle.ts\` (emitted as a
+ * pre-step of \`oke db\` / \`oke dev\`).
  *
- * Versioned prod migrations land in \`./src/db/migrations\` — never mix with \`.oke/\`.
+ * System / auth / plugin stubs are separate: \`oke schema generate\` →
+ * \`.oke/schema/oke.ts\` (gitignored with \`.oke/\`). Re-run after adding plugins.
+ *
+ * Versioned prod migrations land in \`./src/db/migrations\`.
  */
-const dialect = (process.env.OKE_DRIZZLE_DIALECT ?? "sqlite") as "sqlite" | "postgresql";
-
 export default defineConfig({
-  dialect,
-  schema: "./src/db/schema.generated.ts",
+  dialect: "postgresql",
+  schema: "./src/db/schema.drizzle.ts",
   out: "./src/db/migrations",
   // Core runtime tables (oke_crons, …) are created by drivers — not domain schema.
   tablesFilter: ["!oke_*"],
   dbCredentials: {
-    url:
-      dialect === "postgresql"
-        ? (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL!)
-        : (process.env.OKE_SQLITE_URL ?? "file:.oke/app.sqlite"),
+    url: process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL!,
   },
 });
 `;

package/src/cli/hero-meta.test.ts

@@ -15,23 +15,23 @@ import {
 const SAMPLE: OkeConfig = {
   drivers: {
     store: {
-      sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
-      kv: { local: "memory", docker: "redis", prod: "redis" },
+      sql: { dev: "postgres", test: "pglite", prod: "postgres" },
+      kv: { dev: "redis", test: "memory", prod: "redis" },
     },
-    signal: { local: "memory", docker: "redis", prod: "redis" },
-    clock: { local: "memory", docker: "file", prod: "file" },
-    vault: { local: "env", docker: "openbao", prod: "openbao" },
+    signal: { dev: "redis", test: "memory", prod: "redis" },
+    clock: { dev: "file", test: "memory", prod: "file" },
+    vault: { dev: "vault", test: "env", prod: "vault" },
     channel: {
-      email: { local: "console", docker: "smtp", prod: "smtp" },
+      email: { dev: "smtp", test: "console", prod: "smtp" },
     },
-    ai: { local: "mock", docker: "mock" },
+    ai: { dev: "mock", test: "mock" },
   },
 };
 
 describe("hero-meta", () => {
-  test("resolveDevProfile maps docker and NODE_ENV", () => {
-    expect(resolveDevProfile({ docker: false })).toBe("local");
-    expect(resolveDevProfile({ docker: true })).toBe("docker");
+  test("resolveDevProfile maps NODE_ENV (docker flag ignored)", () => {
+    expect(resolveDevProfile({ docker: false })).toBe("dev");
+    expect(resolveDevProfile({ docker: true })).toBe("dev");
     expect(resolveDevProfile({ docker: false, nodeEnv: "test" })).toBe("test");
     expect(resolveDevProfile({ docker: false, nodeEnv: "production" })).toBe("production");
   });
@@ -48,12 +48,12 @@ describe("hero-meta", () => {
       "channel",
       "ai",
     ]);
-    expect(rows.find((r) => r.element === "store")?.detail).toContain("sqlite");
+    expect(rows.find((r) => r.element === "store")?.detail).toContain("pglite");
     expect(rows.find((r) => r.element === "flow")?.detail).toBe("");
     expect(rows.find((r) => r.element === "flow")?.status).toBe("ready");
   });
 
-  test("docker profile applies to every element", () => {
+  test("dev (compose) profile applies to every element", () => {
     const rows = resolveHeroElements(SAMPLE, {
       docker: true,
       sqlDriver: "postgres",
@@ -62,7 +62,7 @@ describe("hero-meta", () => {
     const store = rows.find((r) => r.element === "store")?.detail ?? "";
     expect(store).toContain("postgres");
     expect(store).toContain("redis");
-    expect(store).not.toContain("sqlite");
+    expect(store).not.toContain("pglite");
     expect(rows.find((r) => r.element === "signal")?.detail).toBe("redis");
     expect(rows.find((r) => r.element === "clock")?.detail).toBe("file");
     expect(rows.find((r) => r.element === "gate")?.detail).toBe("redis");
@@ -78,8 +78,8 @@ describe("hero-meta", () => {
       version: "0.2.4",
       nodeEnv: "development",
     });
-    expect(snap.profile).toBe("docker");
-    expect(snap.runtimeEnv).toBe("local");
+    expect(snap.profile).toBe("dev");
+    expect(snap.runtimeEnv).toBe("dev");
     expect(decodeHeroSnapshot(encodeHeroSnapshot(snap))).toEqual(snap);
   });
 

package/src/cli/hero-meta.ts

@@ -11,11 +11,11 @@ import {
 } from "../config/index.ts";
 import type { DevStatus } from "../term.ts";
 
-/** How the process is running (local laptop → production). */
-export type DevRuntimeProfile = "local" | "docker" | "test" | "production";
+/** How the process is running (dev Compose → production). */
+export type DevRuntimeProfile = "dev" | "test" | "production";
 
-/** Data plane: still on a laptop vs real production. */
-export type DevRuntimeEnv = "local" | "production";
+/** Data plane: still on a laptop vs production deploy. */
+export type DevRuntimeEnv = "dev" | "production";
 
 /** One of the eight elements with its active driver summary. */
 export type HeroElementRow = {
@@ -69,16 +69,17 @@ export function resolveDevProfile(options: {
 }): DevRuntimeProfile {
   if (options.nodeEnv === "test") return "test";
   if (options.nodeEnv === "production") return "production";
-  return options.docker ? "docker" : "local";
+  void options.docker;
+  return "dev";
 }
 
 /**
- * Data-plane environment (local machine vs production deploy).
+ * Data-plane environment (dev machine vs production deploy).
  *
  * @param profile - Runtime profile
  */
 export function resolveDevRuntimeEnv(profile: DevRuntimeProfile): DevRuntimeEnv {
-  return profile === "production" ? "production" : "local";
+  return profile === "production" ? "production" : "dev";
 }
 
 /**
@@ -155,13 +156,13 @@ export function resolveHeroElements(
     readonly aiModel?: string;
     /** AI readiness when known (model loading / ready). */
     readonly aiStatus?: DevStatus;
-    /** Which driver map column to read (default `local`). */
+    /** Which driver map column to read (default `test` unless `docker`). */
     readonly configEnv?: ConfigEnv;
   },
 ): readonly HeroElementRow[] {
   const drivers = config?.drivers;
   // `-d` reads the `docker` profile for every element (not a store-only override).
-  const configEnv: ConfigEnv = options.configEnv ?? (options.docker ? "docker" : "local");
+  const configEnv: ConfigEnv = options.configEnv ?? (options.docker ? "dev" : "test");
 
   // Gate rates share `drivers.store.kv` (no separate drivers.gate).
   const gateKv =

package/src/cli/index.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
 /**
  * `oke` CLI entry.
+ *
+ * Bare `oke` (TTY) → interactive Ink TUI. `oke <command>` runs directly.
  */
 
 import { aiCli } from "./ai.ts";
@@ -23,11 +25,32 @@ import { replayCli } from "./replay.ts";
 import { schemaCli } from "./schema.ts";
 import { stackCli } from "./stack.ts";
 import { startCli } from "./start.ts";
+import { testCli } from "./test.ts";
 import { upgradeCli } from "./upgrade.ts";
 import { vaultCli } from "./vault-cmd.ts";
 
-const argv = process.argv.slice(2);
+const rawArgv = process.argv.slice(2);
+const wantTui = rawArgv.includes("--tui");
+const argv = rawArgv.filter((a) => a !== "--tui");
 const [cmd, sub, ...rest] = argv;
+/** Nested TUI / slash child — never re-enter the interactive shell. */
+const noTui = process.env["OKE_NO_TUI"] === "1";
+
+/**
+ * Launch interactive TUI when allowed; otherwise print help (non-TTY).
+ */
+async function maybeLaunchTui(): Promise<never> {
+  const { canRenderTui, launchTui } = await import("./tui/launch.ts");
+  if (noTui || !canRenderTui(process.stdout)) {
+    console.log(formatOkeHelp());
+    process.exit(EXIT_USAGE);
+  }
+  process.exit(await launchTui(process.cwd()));
+}
+
+if (wantTui && !noTui) {
+  await maybeLaunchTui();
+}
 
 if (cmd === "dev") {
   process.exit(await devCli(sub ? [sub, ...rest] : rest));
@@ -37,6 +60,10 @@ if (cmd === "mode") {
   process.exit(await modeCli(sub ? [sub, ...rest] : rest));
 }
 
+if (cmd === "test") {
+  process.exit(await testCli(sub ? [sub, ...rest] : rest));
+}
+
 if (cmd === "start") {
   process.exit(await startCli(sub ? [sub, ...rest] : rest));
 }
@@ -109,11 +136,14 @@ if (cmd === "completion") {
   process.exit(completionCli(sub ? [sub, ...rest] : rest));
 }
 
-if (cmd === undefined || cmd === "--help" || cmd === "-h" || cmd === "help") {
-  // Bare `oke` — commands only. Exit-code table only on explicit --help.
-  const help = cmd === undefined ? formatOkeHelp() : `${formatOkeHelp()}${EXIT_CODE_HELP}`;
-  console.log(help);
-  process.exit(cmd ? EXIT_OK : EXIT_USAGE);
+if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+  console.log(`${formatOkeHelp()}${EXIT_CODE_HELP}`);
+  process.exit(EXIT_OK);
+}
+
+if (cmd === undefined) {
+  // Bare `oke` — TUI on TTY; help + EXIT_USAGE when piped / CI / OKE_NO_TUI.
+  await maybeLaunchTui();
 }
 
 console.error(`Unknown command: ${cmd}${sub ? ` ${sub}` : ""}`);