okengine 0.2.3 → 0.2.4

package/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="site/public/OKE-W.svg" />
+    <img alt="OKE" src="site/public/OKE-B.svg" width="220" />
+  </picture>
+</p>
+
 # okengine
 
 *"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."*
@@ -225,7 +232,7 @@ oke images list                  # recipe · image · tag · digest · size (wri
 3. **Derive Docker / compose**, then pin digests so tags cannot drift:
 
 ```bash
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # writes under docker/ (Dockerfile + compose.<role>.yml · …)
 oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 ```
@@ -251,8 +258,8 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
-oke dev -s store.sql,signal      #     partial: only these roles get real backends
+oke dev --stack                  # -s  infra only under docker/ (Postgres/Redis/…); app stays on host Bun
+oke dev -s store.sql,store.kv    #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
 oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
@@ -269,7 +276,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # artefacts under docker/ (Dockerfile + compose.<role>.yml · …)
 oke docker --prod                # -p  healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images list                  # recipe · image · tag · digest · size (--json|-j)
 oke images pin                   # tags → digests in oke.images.lock
@@ -346,6 +353,25 @@ Measured size and latency caps — see [`BUDGETS.md`](BUDGETS.md). Refresh with
 
 ---
 
+## Local framework link (try changes without publishing)
+
+To exercise a local `okengine` checkout inside an app (e.g. `oke-1`) without npm publish:
+
+```bash
+# in the okengine repo
+bun link
+# if you changed the Console SPA:
+bun run build
+
+# in the app repo
+bun link okengine
+# edit okengine → restart `bun dev` in the app
+```
+
+Alternatively set `"okengine": "file:../okengine"` in the app `package.json` and run `bun install`.
+
+---
+
 ## Status
 
 Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). Docs at [okengine.vercel.app](https://okengine.vercel.app). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.

package/docs/spec/example.md

@@ -43,7 +43,16 @@ import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" } },
+    // `stack` = `oke dev -s` (local server). Omitting it copies `prod`
+    // (defineConfig); vault `sops` becomes stack `dotenv` for `.env.stack`.
+    store: {
+      sql: {
+        dev: "sqlite",
+        stack: "postgres",
+        test: "memory",
+        prod: "postgres",
+      },
+    },
   },
 });
 ```
@@ -1132,7 +1141,7 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
+oke dev --stack                  # -s  infra compose under docker/ (no app container; host Bun)
 oke dev -s store.sql,signal      #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
@@ -1143,7 +1152,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
 oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 

package/docs/spec/four-applications.md

@@ -43,7 +43,14 @@ import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" } },
+    store: {
+      sql: {
+        dev: "sqlite",
+        stack: "postgres",
+        test: "memory",
+        prod: "postgres",
+      },
+    },
   },
 });
 ```
@@ -1132,7 +1139,7 @@ bun add okengine                 # ONE package
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535
                                  #   → also auto-syncs client types on every save
-oke dev --stack                  # -s  also boot the real infra stack (generated compose)
+oke dev --stack                  # -s  infra compose under docker/ (no app container; host Bun)
 oke dev -s store.sql,signal      #     partial: only these roles get real backends
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
@@ -1143,7 +1150,7 @@ oke schema generate              # core + plugin tables → schema/oke.ts   (--c
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # Dockerfile + compose.store.sql.yml · compose.store.kv.yml · …
+oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
 oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
 oke images pin                   # tags → digests in oke.images.lock
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",
@@ -17,51 +17,20 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test --pass-with-no-tests",
-    "test:manifest": "bun test --coverage src/manifest",
-    "test:runtime": "bun test src/runtime",
-    "test:compiler": "bun test src/validation src/compiler/aot src/compiler/differential src/compiler/extract",
-    "test:client": "bun test src/client src/cli/client-add.test.ts",
-    "test:store": "bun test src/elements/store src/drivers",
-    "test:signal": "bun test src/elements/signal",
-    "test:clock": "bun test src/elements/clock",
-    "test:gate": "bun test src/elements/gate",
-    "test:vault": "bun test src/elements/vault",
-    "test:channel": "bun test src/elements/channel",
-    "test:ai": "bun test src/elements/ai",
-    "test:auth": "bun test src/auth",
-    "test:runs": "bun test src/runs",
-    "test:cli": "bun test src/cli src/docker",
-    "test:console": "bun test src/console/server && bun test src/console/ui/flows && bun test src/console/ui/traces && bun test src/console/ui/runs && bun test src/console/ui/signals && bun test src/console/ui/architecture && bun test src/console/xss.gate.test.ts src/console/budget.test.ts",
-    "test:mcp": "bun test src/mcp",
+    "test:coverage": "bun test --coverage --pass-with-no-tests",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
-    "build:console": "bunx vite build --config src/console/ui/vite.config.ts",
-    "prepack": "bun run build:console",
-    "bench:cold-start": "bun test ./src/runtime/cold-start.bench.ts",
-    "bench:client": "bun test src/client/budget.test.ts",
-    "bench:console": "bun test src/console/budget.test.ts",
-    "bench:kernel": "bun test src/kernel/budget.test.ts",
-    "bench:routing": "bun test src/kernel/routing-budget.test.ts",
-    "bench:runs": "bun test src/runs/bench.test.ts",
+    "test:integration": "bun test examples/notes examples/linkly examples/provisions examples/skyport examples/skyport/tests/docker.test.ts && bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
+    "build": "bunx vite build --config src/console/ui/vite.config.ts",
+    "prepack": "bun run build",
+    "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate:doctor-diff": "bun src/cli/doctor-diff-examples.ts",
-    "gate:errors": "bun test src/kernel/errors.registry.test.ts",
-    "gate:codemods": "bun test src/upgrade/codemods.test.ts",
-    "test:examples": "bun test examples/notes && bun test examples/linkly && bun test examples/provisions && bun test examples/skyport",
-    "test:create-oke": "bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
-    "test:doc-drift": "bun src/cli/doc-drift.ts",
+    "gate": "bun src/cli/doctor-diff-examples.ts && bun test src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts && bun src/cli/doc-drift.ts",
     "site:sync": "bun run --cwd site sync",
     "site:dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
-    "test:skyport-docker": "bun test examples/skyport/tests/docker.test.ts",
-    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run site:build && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
-    "gate:publish": "bun test scripts/publish.gate.test.ts",
+    "ci": "bun run bench && bun run typecheck && bun run test && bun run budgets && bun run gate && bun run site:build && bun run test:integration",
     "bump": "bun run scripts/bump-version.ts",
-    "publish:all": "bun run scripts/publish.ts",
-    "publish:npm": "bun run scripts/publish.ts -- --npm-only",
-    "publish:jsr": "bun run scripts/publish.ts -- --jsr-only",
-    "publish:all:dry": "bun run scripts/publish.ts -- --dry-run",
-    "publish:npm:dry": "bun run scripts/publish.ts -- --dry-run --npm-only",
-    "publish:jsr:dry": "bun run scripts/publish.ts -- --dry-run --jsr-only",
+    "publish": "bun run scripts/publish.ts",
     "g": "gflows"
   },
   "dependencies": {

package/src/cli/dev-app-runner.ts

@@ -11,17 +11,29 @@
  * - `PORT` — listen port (`0` = ephemeral)
  * - `OKE_HOSTNAME` — listen hostname (default `127.0.0.1`)
  * - `OKE_READY_PATH` — when set, write bound port here once listening
+ * - `OKE_DEV_HERO_CONSOLE` / `OKE_DEV_HERO_MCP` — URL lines for soft-reload hero
+ * - `OKE_DEV_HERO_META` — JSON {@link import("./hero-meta.ts").DevHeroSnapshot}
  */
 
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
-import { formatAppReadyLine } from "../term.ts";
+import {
+  clearTerminalScreen,
+  formatAppReadyLine,
+  formatDevHero,
+} from "../term.ts";
+import { decodeHeroSnapshot } from "./hero-meta.ts";
 
 /** Stable Bun.serve id so `--hot` reuses the socket across soft reloads. */
 export const DEV_APP_SERVE_ID = "oke-dev-app";
 
+/** Survives `bun --hot` soft reload — marks second+ evaluation. */
+type DevRunnerGlobals = typeof globalThis & {
+  __okeDevSoftReload?: boolean;
+};
+
 /** App entry shape — FetchApp plus boot before serve. */
 type BootableApp = FetchApp & {
   boot(): Promise<unknown>;
@@ -36,6 +48,9 @@ if (entry === undefined || entry.length === 0) {
 const port = Number(Bun.env["PORT"] ?? APP_PORT);
 const hostname = Bun.env["OKE_HOSTNAME"] ?? "127.0.0.1";
 const readyPath = Bun.env["OKE_READY_PATH"];
+const consoleUrl = Bun.env["OKE_DEV_HERO_CONSOLE"];
+const mcpUrl = Bun.env["OKE_DEV_HERO_MCP"];
+const heroMeta = decodeHeroSnapshot(Bun.env["OKE_DEV_HERO_META"]);
 
 const absoluteEntry = resolve(entry);
 const mod = (await import(pathToFileURL(absoluteEntry).href)) as {
@@ -60,11 +75,35 @@ const handle = createBunRuntime().serve(mod.app, {
   id: DEV_APP_SERVE_ID,
 });
 
-process.stdout.write(
-  formatAppReadyLine(
-    `http://${formatHostForUrl(hostname)}:${handle.port}`,
-  ),
-);
+const appUrl = `http://${formatHostForUrl(hostname)}:${handle.port}`;
+const g = globalThis as DevRunnerGlobals;
+const isSoftReload = g.__okeDevSoftReload === true;
+g.__okeDevSoftReload = true;
+
+if (
+  isSoftReload &&
+  consoleUrl !== undefined &&
+  consoleUrl.length > 0 &&
+  mcpUrl !== undefined &&
+  mcpUrl.length > 0
+) {
+  // Drop request logs; keep the hero (Bun --no-clear-screen + our reprint).
+  process.stdout.write(clearTerminalScreen());
+  process.stdout.write(
+    formatDevHero({
+      appUrl,
+      consoleUrl,
+      mcpUrl,
+      profile: heroMeta?.profile,
+      runtimeEnv: heroMeta?.runtimeEnv,
+      system: heroMeta?.system,
+      elements: heroMeta?.elements,
+      version: heroMeta?.version,
+    }),
+  );
+} else {
+  process.stdout.write(formatAppReadyLine(appUrl));
+}
 
 if (readyPath !== undefined && readyPath.length > 0) {
   await Bun.write(readyPath, `${handle.port}\n`);

package/src/cli/dev.ts

@@ -1,6 +1,6 @@
 /**
  * `oke dev` — watch · hot reload · Console :6533 · MCP :6535 · client types on save.
- * `oke dev --stack` also boots generated compose.
+ * `oke dev --stack` boots infra compose and binds prod store drivers (Postgres/Redis).
  */
 
 import { watch } from "node:fs";
@@ -11,8 +11,12 @@ import type { SessionStore } from "../auth/sessions.ts";
 import type { ConsoleAppHandle } from "../console/server/app.ts";
 import type { ConsoleState } from "../console/server/state.ts";
 import {
+  DEFAULT_DOCKER_DIR,
   deriveInfrastructure,
   formatStackEnv,
+  loadExistingStackCredentials,
+  stackAppSlug,
+  stackInstanceId,
   writeDerivedFiles,
   type DeriveOptions,
 } from "../docker/index.ts";
@@ -25,11 +29,22 @@ import {
 } from "../runtime/types.ts";
 import {
   formatDevBanner,
+  formatDevLogSeparator,
   formatServiceLine,
+  formatStackSummary,
   formatStatusLine,
 } from "../term.ts";
 import { clientAdd } from "./client-add.ts";
-import { loadManifest, loadOkeConfig, resolveImages } from "./load-config.ts";
+import { resolveDriverId } from "../config/index.ts";
+import {
+  buildDevHeroSnapshot,
+  encodeHeroSnapshot,
+} from "./hero-meta.ts";
+import {
+  loadManifest,
+  loadOkeConfig,
+  resolveImages,
+} from "./load-config.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
 import { resolveDevPorts } from "./ports.ts";
 
@@ -224,16 +239,36 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   let stackRoles: string[] | null = null;
   let composeFiles: string[] | null = null;
   let stackEnv: Record<string, string> | null = null;
+  let stackSqlDriver = "postgres";
+  let stackKvDriver = "redis";
+  let loadedConfig: Awaited<ReturnType<typeof loadOkeConfig>>["config"] | null =
+    null;
+  try {
+    loadedConfig = (await loadOkeConfig(cwd)).config;
+  } catch {
+    loadedConfig = null;
+  }
 
   if (options.stack) {
     let images = options.images;
     if (!images) {
+      if (!loadedConfig) {
+        try {
+          const loaded = await loadOkeConfig(cwd);
+          loadedConfig = loaded.config;
+          images = resolveImages(loaded.config);
+        } catch (err) {
+          console.error(err instanceof Error ? err.message : String(err));
+          return { code: 1 };
+        }
+      } else {
+        images = resolveImages(loadedConfig);
+      }
+    } else if (!loadedConfig) {
       try {
-        const loaded = await loadOkeConfig(cwd);
-        images = resolveImages(loaded.config);
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return { code: 1 };
+        loadedConfig = (await loadOkeConfig(cwd)).config;
+      } catch {
+        loadedConfig = null;
       }
     }
     if (Array.isArray(options.stack)) {
@@ -246,16 +281,31 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       stackRoles = Object.keys(images);
     }
 
+    stackSqlDriver =
+      resolveDriverId(loadedConfig?.drivers?.store?.sql, "prod") ?? "postgres";
+    stackKvDriver =
+      resolveDriverId(loadedConfig?.drivers?.store?.kv, "prod") ?? "redis";
+
+    const composeDir = DEFAULT_DOCKER_DIR;
+    const dockerOut = resolve(cwd, composeDir);
+    const instanceId = stackInstanceId(cwd);
+    const appSlug = stackAppSlug(cwd);
+    const reusedCreds =
+      options.credentials ??
+      (await loadExistingStackCredentials(cwd, stackRoles));
     const derived = deriveInfrastructure({
       images,
-      app: "dev",
+      app: appSlug,
       prod: false,
-      ...(options.credentials ? { credentials: options.credentials } : {}),
+      includeApp: false,
+      composeDir,
+      instanceId,
+      ...(reusedCreds ? { credentials: reusedCreds } : {}),
       host: "127.0.0.1",
     });
     // Layer 4 is user-owned — include only if the file already exists.
     const existingOverride = await Bun.file(
-      resolve(cwd, "compose.override.yml"),
+      resolve(dockerOut, "compose.override.yml"),
     ).exists();
     composeFiles = derived.composeFiles.filter(
       (f) => f !== "compose.override.yml" || existingOverride,
@@ -263,8 +313,11 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv = { ...derived.stackEnv };
 
     if (!options.dryRun) {
-      await writeDerivedFiles(derived, cwd, { writeStackEnv: true });
-      // Ensure .env.stack is loaded for the app process
+      await writeDerivedFiles(derived, dockerOut, {
+        writeStackEnv: true,
+        stackEnvDir: cwd,
+      });
+      // Ensure .env.stack is at project root for the host Bun app / vault.
       await Bun.write(resolve(cwd, ".env.stack"), formatStackEnv(stackEnv));
       const up =
         options.composeUp ??
@@ -281,8 +334,27 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
             throw new Error(`oke dev --stack: docker compose exited ${code}`);
           }
         });
-      await up(composeFiles, cwd);
-      write(formatStatusLine(`stack up (${stackRoles.join(", ")})`));
+      // Compose files live under docker/; cwd for compose is that directory.
+      await up(composeFiles, dockerOut);
+      const roleLabel = (role: string): string => {
+        if (role === "store.sql") return "postgres";
+        if (role === "store.kv") return "redis";
+        return role;
+      };
+      const appDrivers = [
+        ...(stackRoles.includes("store.sql") ? [stackSqlDriver] : []),
+        ...(stackRoles.includes("store.kv") ? [stackKvDriver] : []),
+      ];
+      write(
+        formatStackSummary({
+          project: `oke-${appSlug}`,
+          services: derived.specs.map((spec) => ({
+            label: roleLabel(spec.role),
+            hostPort: spec.hostPort,
+          })),
+          appDrivers,
+        }),
+      );
     }
   }
 
@@ -296,7 +368,34 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv,
   };
 
-  write(formatDevBanner());
+  let okeVersion = "0.0.0";
+  try {
+    const pkg = (await Bun.file(
+      resolve(import.meta.dir, "../../package.json"),
+    ).json()) as { version?: string };
+    if (typeof pkg.version === "string") okeVersion = pkg.version;
+  } catch {
+    // shipped binary may not sit next to package.json
+  }
+
+  const heroSnapshot = buildDevHeroSnapshot({
+    config: loadedConfig,
+    stack: Boolean(options.stack),
+    sqlDriver: options.stack ? stackSqlDriver : undefined,
+    kvDriver: options.stack ? stackKvDriver : undefined,
+    version: okeVersion,
+    nodeEnv: "development",
+  });
+
+  write(
+    formatDevBanner({
+      profile: heroSnapshot.profile,
+      runtimeEnv: heroSnapshot.runtimeEnv,
+      system: heroSnapshot.system,
+      elements: heroSnapshot.elements,
+      version: okeVersion,
+    }),
+  );
 
   if (options.dryRun) return { code: 0, plan };
 
@@ -304,8 +403,21 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     ...(process.env as Record<string, string>),
     NODE_ENV: "development",
     PORT: String(appPort),
+    OKE_DEV_REQUEST_LOG: "1",
+    /** Soft-reload hero reprint (Console / MCP URLs + element snapshot). */
+    OKE_DEV_HERO_CONSOLE: `http://127.0.0.1:${consolePort}`,
+    OKE_DEV_HERO_MCP: `http://127.0.0.1:${mcpPort}`,
+    OKE_DEV_HERO_META: encodeHeroSnapshot(heroSnapshot),
     ...(stackEnv ?? {}),
+    ...(stackEnv
+      ? {
+          OKE_STACK: "1",
+          OKE_SQL_DRIVER: stackSqlDriver,
+          OKE_KV_DRIVER: stackKvDriver,
+        }
+      : {}),
   };
+  process.env.OKE_DEV_REQUEST_LOG = "1";
 
   const startApp =
     options.startApp ??
@@ -429,6 +541,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const appUrl =
     app.url?.origin ?? `http://127.0.0.1:${boundAppPort}`;
   await regen(appUrl);
+  write(formatDevLogSeparator());
 
   const watcher = watch(
     resolve(cwd, "src"),
@@ -555,9 +668,13 @@ async function startAppHot(
     OKE_ENTRY: absoluteEntry,
     OKE_HOSTNAME: hostname,
     OKE_READY_PATH: readyPath,
+    OKE_DEV_REQUEST_LOG: "1",
+    OKE_DEV_SURFACE: "App",
   };
 
-  const proc = Bun.spawn(["bun", "--hot", runner], {
+  // `--no-clear-screen`: Bun must not wipe the hero; the runner clears only
+  // request logs on soft reload and reprints App / Console / MCP URLs.
+  const proc = Bun.spawn(["bun", "--hot", "--no-clear-screen", runner], {
     cwd,
     env,
     stdout: "inherit",
@@ -652,7 +769,9 @@ export async function devCli(args: readonly string[]): Promise<number> {
 
 Watch · hot reload · Console :6533 · app :6530 · MCP :6535
 Regenerates client types on every save.
---stack boots generated compose (partial roles: -s store.sql,signal).
+--stack boots infra under docker/ and runs the app on host Bun with prod
+store drivers (Postgres/Redis) so local mimics the server.
+Partial roles: -s store.sql,store.kv.
 `);
       return 0;
     }

package/src/cli/docker-cli.test.ts

@@ -27,25 +27,25 @@ const credentials = {
 } as const;
 
 describe("oke docker CLI", () => {
-  test("writes Dockerfile and compose without credentials in YAML", async () => {
+  test("writes Dockerfile and compose under docker/ by default", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-cli-docker-"));
     const logs: string[] = [];
     const { code, result } = await runDockerDerive({
       cwd: dir,
-      outDir: dir,
       images,
       credentials,
       write: (t) => logs.push(t),
     });
     expect(code).toBe(0);
     expect(result).toBeDefined();
-    expect(await Bun.file(join(dir, "Dockerfile")).exists()).toBe(true);
-    expect(await Bun.file(join(dir, "compose.store.sql.yml")).exists()).toBe(
-      true,
-    );
-    const yml = await Bun.file(join(dir, "compose.store.sql.yml")).text();
+    expect(await Bun.file(join(dir, "docker/Dockerfile")).exists()).toBe(true);
+    expect(
+      await Bun.file(join(dir, "docker/compose.store.sql.yml")).exists(),
+    ).toBe(true);
+    const yml = await Bun.file(join(dir, "docker/compose.store.sql.yml")).text();
     expect(yml).not.toContain("test-password-not-in-yaml");
-    expect(logs.join("")).toContain("compose.override.yml");
+    expect(yml).toContain("../.env.stack");
+    expect(logs.join("")).toContain("docker/compose.override.yml");
   });
 });
 
@@ -164,8 +164,10 @@ describe("oke dev --stack", () => {
     expect(code).toBe(0);
     expect(plan?.stackRoles).toEqual(["store.sql"]);
     expect(plan?.composeFiles?.some((f) => f.includes("store.sql"))).toBe(true);
+    expect(plan?.composeFiles).toContain("compose.yml");
     expect(plan?.stackEnv?.DATABASE_URL).toContain("postgres://");
     expect(await Bun.file(join(dir, "compose.yml")).exists()).toBe(false);
+    expect(await Bun.file(join(dir, "docker/compose.yml")).exists()).toBe(false);
   });
 });
 

package/src/cli/docker.ts

@@ -4,6 +4,7 @@
 
 import { resolve } from "node:path";
 import {
+  DEFAULT_DOCKER_DIR,
   deriveInfrastructure,
   writeDerivedFiles,
   type DeriveOptions,
@@ -38,7 +39,15 @@ export async function runDockerDerive(
 ): Promise<{ readonly code: number; readonly result?: DeriveResult }> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
-  const outDir = resolve(cwd, options.outDir ?? ".");
+  const composeDirOpt = options.outDir ?? DEFAULT_DOCKER_DIR;
+  const outDir = resolve(cwd, composeDirOpt);
+  // Relative dir for env_file / build.context rewriting (`.` when out === cwd).
+  const composeDir =
+    outDir === cwd
+      ? "."
+      : outDir.startsWith(`${cwd}/`) || outDir.startsWith(`${cwd}\\`)
+        ? outDir.slice(cwd.length + 1)
+        : ".";
 
   let images = options.images;
   let app = "app";
@@ -70,6 +79,8 @@ export async function runDockerDerive(
       app,
       prod: options.prod ?? false,
       outDir,
+      composeDir,
+      includeApp: true,
       ...(options.credentials ? { credentials: options.credentials } : {}),
     });
 
@@ -77,13 +88,13 @@ export async function runDockerDerive(
       await writeDerivedFiles(result, outDir, { writeStackEnv: false });
     }
 
-    write(`oke docker: wrote ${result.files.length} file(s)\n`);
-    for (const f of result.files) write(`  ${f.path}\n`);
+    write(`oke docker: wrote ${result.files.length} file(s) → ${composeDir}/\n`);
+    for (const f of result.files) write(`  ${composeDir}/${f.path}\n`);
     write(
-      `compose merge order:\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
+      `compose merge order (cwd ${composeDir}/):\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
     );
     write(
-      "(compose.override.yml is layer 4 — user-owned, never written by oke)\n",
+      `(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`,
     );
     return { code: 0, result };
   } catch (err) {
@@ -109,9 +120,9 @@ export async function dockerCli(args: readonly string[]): Promise<number> {
     else if (a === "--config" || a === "-c") configPath = args[++i];
     else if (a === "--manifest" || a === "-m") manifestPath = args[++i];
     else if (a === "--help" || a === "-h") {
-      console.log(`oke docker [--prod|-p] [--out|-o .] [--config|-c oke.config.ts]
+      console.log(`oke docker [--prod|-p] [--out|-o docker] [--config|-c oke.config.ts]
 
-Derive Dockerfile + compose.<role>.yml files.
+Derive Dockerfile + compose.<role>.yml under docker/ (default).
 --prod is opt-in (never the default). Credentials are never written into YAML.
 `);
       return 0;