create-oke 0.2.3 → 0.2.8

package/src/cli.ts

@@ -36,6 +36,7 @@ import {
   type ExampleId,
   type TemplateId,
 } from "./templates.ts";
+import { DEFAULT_SQL_DRIVER, SQL_DRIVERS, isSqlDriverId, type SqlDriverId } from "./transform.ts";
 
 /** Parsed CLI arguments. */
 export type CliArgs = {
@@ -44,6 +45,10 @@ export type CliArgs = {
   readonly fromExample: ExampleId | undefined;
   /** True when `--template` / `-t` was present on the argv. */
   readonly templateExplicit: boolean;
+  /** Store SQL driver (`sqlite` default). */
+  readonly sqlDriver: SqlDriverId;
+  /** True when `--sql` was present on the argv. */
+  readonly sqlDriverExplicit: boolean;
   readonly help: boolean;
   /** Skip all prompts; use defaults. */
   readonly yes: boolean;
@@ -87,6 +92,7 @@ export type ScaffoldCallArgs = {
   readonly targetDir: string;
   readonly source: ScaffoldSource;
   readonly agentsMd: boolean;
+  readonly sqlDriver: SqlDriverId;
 };
 
 /**
@@ -99,6 +105,8 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   let template: TemplateId = DEFAULT_TEMPLATE;
   let fromExample: ExampleId | undefined;
   let templateExplicit = false;
+  let sqlDriver: SqlDriverId = DEFAULT_SQL_DRIVER;
+  let sqlDriverExplicit = false;
   let help = false;
   let yes = false;
   let install: boolean | undefined;
@@ -131,12 +139,28 @@ export function parseArgs(argv: readonly string[]): CliArgs {
       agentsMd = true;
       continue;
     }
+    if (a === "--sql") {
+      const next = argv[++i];
+      if (!next || !isSqlDriverId(next)) {
+        throw new Error(`create-oke: --sql must be one of ${SQL_DRIVERS.join("|")}`);
+      }
+      sqlDriver = next;
+      sqlDriverExplicit = true;
+      continue;
+    }
+    if (a.startsWith("--sql=")) {
+      const value = a.slice("--sql=".length);
+      if (!isSqlDriverId(value)) {
+        throw new Error(`create-oke: --sql must be one of ${SQL_DRIVERS.join("|")}`);
+      }
+      sqlDriver = value;
+      sqlDriverExplicit = true;
+      continue;
+    }
     if (a === "--template" || a === "-t") {
       const next = argv[++i];
       if (!next || !isTemplateId(next)) {
-        throw new Error(
-          `create-oke: --template must be one of ${TEMPLATES.join("|")}`,
-        );
+        throw new Error(`create-oke: --template must be one of ${TEMPLATES.join("|")}`);
       }
       template = next;
       templateExplicit = true;
@@ -145,9 +169,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     if (a.startsWith("--template=")) {
       const value = a.slice("--template=".length);
       if (!isTemplateId(value)) {
-        throw new Error(
-          `create-oke: --template must be one of ${TEMPLATES.join("|")}`,
-        );
+        throw new Error(`create-oke: --template must be one of ${TEMPLATES.join("|")}`);
       }
       template = value;
       templateExplicit = true;
@@ -156,9 +178,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     if (a === "--from-example") {
       const next = argv[++i];
       if (!next || !isExampleId(next)) {
-        throw new Error(
-          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
-        );
+        throw new Error(`create-oke: --from-example must be one of ${EXAMPLES.join("|")}`);
       }
       fromExample = next;
       continue;
@@ -166,9 +186,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     if (a.startsWith("--from-example=")) {
       const value = a.slice("--from-example=".length);
       if (!isExampleId(value)) {
-        throw new Error(
-          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
-        );
+        throw new Error(`create-oke: --from-example must be one of ${EXAMPLES.join("|")}`);
       }
       fromExample = value;
       continue;
@@ -184,9 +202,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   }
 
   if (templateExplicit && fromExample !== undefined) {
-    throw new Error(
-      "create-oke: use either --template or --from-example, not both",
-    );
+    throw new Error("create-oke: use either --template or --from-example, not both");
   }
 
   if (argv.includes("--install") && argv.includes("--no-install")) {
@@ -202,6 +218,8 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     template,
     fromExample,
     templateExplicit,
+    sqlDriver,
+    sqlDriverExplicit,
     help,
     yes,
     install,
@@ -248,9 +266,9 @@ export function helpText(): string {
     (id) =>
       `  ${id.padEnd(12)}${TEMPLATE_PURPOSES[id]}${id === DEFAULT_TEMPLATE ? "  (default)" : ""}`,
   ).join("\n");
-  const exampleLines = EXAMPLES.map(
-    (id) => `  ${id.padEnd(12)}${EXAMPLE_NEW_IDEAS[id]}`,
-  ).join("\n");
+  const exampleLines = EXAMPLES.map((id) => `  ${id.padEnd(12)}${EXAMPLE_NEW_IDEAS[id]}`).join(
+    "\n",
+  );
 
   return `create-oke — scaffold an okengine app
 
@@ -263,6 +281,10 @@ Usage:
 Options:
   -t, --template <id>   Clean starter (default: ${DEFAULT_TEMPLATE})
   --from-example <id>   Teaching example (non-interactive)
+  --sql <id>            Opt-in Store SQL dialect: ${SQL_DRIVERS.join("|")}
+                        Default keeps local sqlite · docker/prod postgres.
+                        --sql postgres rewrites src/schema.ts to pgTable and
+                        pins store.sql local/docker/prod to postgres.
   -y, --yes             No prompts; defaults + bun install (no oke dev)
   --install             Run bun install after scaffold
   --no-install          Skip bun install
@@ -292,10 +314,7 @@ No telemetry. Bun only. On a TTY, a project name alone still opens the wizard
  * @param args - Parsed args
  * @param stdinIsTTY - `process.stdin.isTTY`
  */
-export function shouldPrompt(
-  args: CliArgs,
-  stdinIsTTY: boolean | undefined,
-): boolean {
+export function shouldPrompt(args: CliArgs, stdinIsTTY: boolean | undefined): boolean {
   if (!stdinIsTTY) return false;
   if (args.help) return false;
   if (args.yes) return false;
@@ -332,6 +351,7 @@ export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
     targetDir: args.targetDir,
     source: sourceFromArgs(args),
     agentsMd: args.agentsMd,
+    sqlDriver: args.sqlDriver,
   };
 }
 
@@ -343,17 +363,18 @@ export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
  *
  * @param answers - Collected interactive answers
  */
-export function scaffoldArgsFromAnswers(
-  answers: InteractiveAnswers,
-): ScaffoldCallArgs {
+export function scaffoldArgsFromAnswers(answers: InteractiveAnswers): ScaffoldCallArgs {
   const targetDir = resolve(answers.name.trim());
   const name = basename(targetDir);
+  // Interactive always keeps the dual-mode default (local sqlite ·
+  // docker/prod postgres). Opt into postgres-everywhere with `--sql postgres`.
   if (answers.choice === FROM_EXAMPLE_CHOICE) {
     return {
       name,
       targetDir,
       source: { kind: "example", id: answers.example },
       agentsMd: answers.agentsMd,
+      sqlDriver: DEFAULT_SQL_DRIVER,
     };
   }
   return {
@@ -361,6 +382,7 @@ export function scaffoldArgsFromAnswers(
     targetDir,
     source: { kind: "template", id: answers.choice },
     agentsMd: answers.agentsMd,
+    sqlDriver: DEFAULT_SQL_DRIVER,
   };
 }
 
@@ -371,9 +393,10 @@ export function scaffoldArgsFromAnswers(
  *
  * @param partial - Name already known (pre-filled in the prompt)
  */
-export type AskInteractiveFn = (
-  partial: { readonly name?: string; readonly agentsMd?: boolean },
-) => Promise<InteractiveAnswers | null>;
+export type AskInteractiveFn = (partial: {
+  readonly name?: string;
+  readonly agentsMd?: boolean;
+}) => Promise<InteractiveAnswers | null>;
 
 /**
  * Collect interactive answers via `@clack/prompts`.
@@ -442,6 +465,8 @@ export async function askInteractiveAnswers(
     };
   }
 
+  const templateId = templateValue as TemplateId;
+
   const installAndRunValue = await confirm({
     message: "Install dependencies and start oke dev?",
     initialValue: true,
@@ -450,7 +475,7 @@ export async function askInteractiveAnswers(
 
   return {
     name,
-    choice: templateValue as TemplateId,
+    choice: templateId,
     installAndRun: Boolean(installAndRunValue),
     agentsMd,
   };
@@ -503,9 +528,7 @@ export async function run(
 
   if (args.name === undefined) {
     console.log(helpText());
-    console.error(
-      "create-oke: missing <name>. Pass a name, or run in a TTY for the wizard.",
-    );
+    console.error("create-oke: missing <name>. Pass a name, or run in a TTY for the wizard.");
     console.error("  Example: bunx create-oke@latest my-app --yes");
     return 1;
   }
@@ -513,7 +536,7 @@ export async function run(
   if (args.yes) {
     const source = sourceFromArgs(args);
     console.log(
-      `Using defaults: ${source.kind}=${source.id} agents-md=${args.agentsMd} install=${shouldInstall(args)}`,
+      `Using defaults: ${source.kind}=${source.id} sql=${args.sqlDriver} agents-md=${args.agentsMd} install=${shouldInstall(args)}`,
     );
   }
 
@@ -573,6 +596,7 @@ async function runScaffold(
     targetDir,
     source,
     agentsMd,
+    sqlDriver,
     interactive,
     install,
     startDev,
@@ -605,6 +629,7 @@ async function runScaffold(
       name,
       source,
       writeAgentsMd: agentsMd,
+      sqlDriver,
     });
     if (spun) spun.stop("Scaffolded.");
 

package/src/scaffold.ts

@@ -22,11 +22,15 @@ import {
 } from "./templates.ts";
 import { agentsMdContent } from "./agents-md.ts";
 import {
+  DEFAULT_SQL_DRIVER,
   sanitizeProjectName,
   shouldSkipTemplatePath,
+  transformConfigForSqlDriver,
   transformPackageJson,
+  transformSchemaForSqlDriver,
   resolveOkengineDependency,
   type ScaffoldPackageJson,
+  type SqlDriverId,
 } from "./transform.ts";
 
 /** Where the scaffold copies from. */
@@ -44,6 +48,12 @@ export type ScaffoldOptions = {
   readonly source: ScaffoldSource;
   /** Write root `AGENTS.md` (default true). */
   readonly writeAgentsMd?: boolean;
+  /**
+   * Store SQL driver — rewrites `src/schema.ts` dialect and pins
+   * `oke.config.ts` `store.sql` local/docker/prod when `postgres`.
+   * Default `sqlite`.
+   */
+  readonly sqlDriver?: SqlDriverId;
 };
 
 /** Result of a successful scaffold. */
@@ -54,6 +64,8 @@ export type ScaffoldResult = {
   /** Display label (`standard`, `notes`, …). */
   readonly label: string;
   readonly okengineDependency: string;
+  /** Store SQL driver applied to schema + config. */
+  readonly sqlDriver: SqlDriverId;
   /** Relative paths written (POSIX), sorted. */
   readonly files: readonly string[];
 };
@@ -71,22 +83,19 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
       ? resolveTemplateDir(options.source.id)
       : resolveExampleDir(options.source.id);
   const label = options.source.id;
+  const sqlDriver = options.sqlDriver ?? DEFAULT_SQL_DRIVER;
 
   if (existsSync(targetDir)) {
     const entries = readdirSync(targetDir);
     if (entries.length > 0) {
-      throw new Error(
-        `create-oke: target directory is not empty: ${targetDir}`,
-      );
+      throw new Error(`create-oke: target directory is not empty: ${targetDir}`);
     }
   } else {
     mkdirSync(targetDir, { recursive: true });
   }
 
   try {
-    const okengineDependency = resolveOkengineDependency(
-      resolveLocalOkengineRoot(),
-    );
+    const okengineDependency = resolveOkengineDependency(resolveLocalOkengineRoot());
     const written: string[] = [];
 
     copyTree(sourceDir, targetDir, "", written);
@@ -95,18 +104,25 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     if (!existsSync(pkgPath)) {
       throw new Error(`create-oke: source "${label}" has no package.json`);
     }
-    const sourcePkg = JSON.parse(
-      readFileSync(pkgPath, "utf8"),
-    ) as ScaffoldPackageJson;
+    const sourcePkg = JSON.parse(readFileSync(pkgPath, "utf8")) as ScaffoldPackageJson;
     const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
     writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
 
+    applySqlDriverTransforms(targetDir, sqlDriver);
+
     if (options.writeAgentsMd !== false) {
       const agentsPath = join(targetDir, "AGENTS.md");
       writeFileSync(agentsPath, agentsMdContent(name), "utf8");
       if (!written.includes("AGENTS.md")) written.push("AGENTS.md");
     }
 
+    const envExample = join(targetDir, ".env.example");
+    const envLocal = join(targetDir, ".env.local");
+    if (existsSync(envExample) && !existsSync(envLocal)) {
+      cpSync(envExample, envLocal);
+      if (!written.includes(".env.local")) written.push(".env.local");
+    }
+
     written.sort();
     return {
       targetDir,
@@ -114,6 +130,7 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
       source: options.source,
       label,
       okengineDependency,
+      sqlDriver,
       files: written,
     };
   } catch (e) {
@@ -122,6 +139,32 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   }
 }
 
+/**
+ * Rewrite schema dialect + (for postgres) `store.sql` pins.
+ *
+ * `sqlite` keeps the template dual-mode config (`local: sqlite` ·
+ * `docker`/`prod: postgres`) — only the Drizzle dialect is ensured.
+ * `postgres` writes `pgTable` and pins local/docker/prod to postgres.
+ *
+ * @param targetDir - Scaffolded project root
+ * @param sqlDriver - Chosen store.sql driver
+ */
+function applySqlDriverTransforms(targetDir: string, sqlDriver: SqlDriverId): void {
+  const schemaPath = join(targetDir, "src/schema.ts");
+  if (existsSync(schemaPath)) {
+    const next = transformSchemaForSqlDriver(readFileSync(schemaPath, "utf8"), sqlDriver);
+    writeFileSync(schemaPath, next, "utf8");
+  }
+
+  if (sqlDriver !== "postgres") return;
+
+  const configPath = join(targetDir, "oke.config.ts");
+  if (existsSync(configPath)) {
+    const next = transformConfigForSqlDriver(readFileSync(configPath, "utf8"), sqlDriver);
+    writeFileSync(configPath, next, "utf8");
+  }
+}
+
 /**
  * Recursively copy template files, applying {@link shouldSkipTemplatePath}.
  *
@@ -130,12 +173,7 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
  * @param rel - Relative path under the roots
  * @param written - Accumulator for relative paths written
  */
-function copyTree(
-  srcRoot: string,
-  dstRoot: string,
-  rel: string,
-  written: string[],
-): void {
+function copyTree(srcRoot: string, dstRoot: string, rel: string, written: string[]): void {
   const src = rel ? join(srcRoot, rel) : srcRoot;
   const st = statSync(src);
   if (st.isDirectory()) {

package/src/sync-templates.ts

@@ -7,14 +7,7 @@
  * monorepo-only docker.test.ts).
  */
 
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  rmSync,
-  statSync,
-} from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { EXAMPLES, packageRoot, TEMPLATES } from "./templates.ts";
 import { shouldSkipTemplatePath } from "./transform.ts";
@@ -26,9 +19,7 @@ const outTemplates = join(pkg, "templates");
 const outExamples = join(pkg, "examples");
 
 if (!existsSync(templatesRoot)) {
-  console.error(
-    `create-oke prepack: templates/ not found at ${templatesRoot}`,
-  );
+  console.error(`create-oke prepack: templates/ not found at ${templatesRoot}`);
   process.exit(1);
 }
 if (!existsSync(examplesRoot)) {

package/src/templates.ts

@@ -38,8 +38,7 @@ export type ExampleId = (typeof EXAMPLES)[number];
  * `--from-example` help and the interactive example select.
  */
 export const EXAMPLE_NEW_IDEAS: Readonly<Record<ExampleId, string>> = {
-  notes:
-    "`oke`, `on`, `flow`, `http`, `store.sql`, `fx`, typed errors, the typed client.",
+  notes: "`oke`, `on`, `flow`, `http`, `store.sql`, `fx`, typed errors, the typed client.",
   linkly:
     "`signal` and its three delivery physics · `clock` · `gate` · triggers beyond HTTP · transactional emit · cross-unit decoupling.",
   provisions:

package/src/transform.ts

@@ -8,12 +8,31 @@
  *    (absolute `file:<okengine-root>` in the monorepo; registry version otherwise)
  * 3. Drop monorepo-only files that import paths outside the source tree
  *    (today: `tests/docker.test.ts`)
+ * 4. Optional `--sql` / wizard choice → Drizzle dialect + `store.sql` pins
  */
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { packageRoot } from "./templates.ts";
 
+/** SQL store drivers selectable at scaffold time. */
+export const SQL_DRIVERS = ["sqlite", "postgres"] as const;
+
+/** A known store.sql driver id for create-oke. */
+export type SqlDriverId = (typeof SQL_DRIVERS)[number];
+
+/** Default when `--sql` / wizard choice is omitted (matches template sources). */
+export const DEFAULT_SQL_DRIVER: SqlDriverId = "sqlite";
+
+/**
+ * Whether `value` is a known {@link SqlDriverId}.
+ *
+ * @param value - Candidate string
+ */
+export function isSqlDriverId(value: string): value is SqlDriverId {
+  return (SQL_DRIVERS as readonly string[]).includes(value);
+}
+
 /** Shape of an example / scaffolded `package.json`. */
 export type ScaffoldPackageJson = {
   name?: string;
@@ -33,9 +52,7 @@ export type ScaffoldPackageJson = {
  *
  * @param localOkengineRoot - Absolute path when available
  */
-export function resolveOkengineDependency(
-  localOkengineRoot: string | null,
-): string {
+export function resolveOkengineDependency(localOkengineRoot: string | null): string {
   if (localOkengineRoot) return `file:${localOkengineRoot}`;
   const pkgPath = join(packageRoot(), "package.json");
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version: string };
@@ -94,6 +111,43 @@ export function shouldSkipTemplatePath(relativePath: string): boolean {
   return false;
 }
 
+/**
+ * Rewrite a Drizzle schema file to the dialect for `driver`.
+ *
+ * Templates ship as `sqliteTable` / `drizzle-orm/sqlite-core`. Choosing
+ * `postgres` swaps to `pgTable` / `pg-core` (and the reverse is idempotent).
+ *
+ * @param source - Schema TypeScript source
+ * @param driver - Target store.sql driver
+ */
+export function transformSchemaForSqlDriver(source: string, driver: SqlDriverId): string {
+  if (driver === "postgres") {
+    return source
+      .replaceAll("drizzle-orm/sqlite-core", "drizzle-orm/pg-core")
+      .replaceAll("sqliteTable", "pgTable");
+  }
+  return source
+    .replaceAll("drizzle-orm/pg-core", "drizzle-orm/sqlite-core")
+    .replaceAll("pgTable", "sqliteTable");
+}
+
+/**
+ * Pin `store.sql` `local` / `docker` / `prod` in `oke.config.ts` to `driver`.
+ *
+ * Leaves `test: "memory"` (and every other facet) untouched.
+ *
+ * @param source - Config TypeScript source
+ * @param driver - Target store.sql driver
+ */
+export function transformConfigForSqlDriver(source: string, driver: SqlDriverId): string {
+  return source.replace(/sql:\s*\{[\s\S]*?\n\s*\}/, (block) =>
+    block
+      .replace(/local:\s*"(?:sqlite|postgres)"/, `local: "${driver}"`)
+      .replace(/docker:\s*"(?:sqlite|postgres)"/, `docker: "${driver}"`)
+      .replace(/prod:\s*"(?:sqlite|postgres)"/, `prod: "${driver}"`),
+  );
+}
+
 /**
  * Sanitize a directory / package name for npm.
  *
@@ -106,13 +160,9 @@ export function sanitizeProjectName(raw: string): string {
   }
   // Allow scoped names; otherwise lowercase npm-safe slug.
   if (trimmed.startsWith("@")) {
-    const m = /^(@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*)$/.exec(
-      trimmed,
-    );
+    const m = /^(@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*)$/.exec(trimmed);
     if (!m) {
-      throw new Error(
-        `create-oke: invalid scoped package name "${trimmed}"`,
-      );
+      throw new Error(`create-oke: invalid scoped package name "${trimmed}"`);
     }
     return trimmed;
   }

package/templates/full/.env.example

@@ -0,0 +1,24 @@
+# Environment template — copy to `.env.local` for local overrides.
+# create-oke copies this file to `.env.local` when you scaffold a new project.
+#
+# Resolution order (first hit wins):
+#   process.env → .env.local → docker/.env.docker → vault driver → dev fallback
+#
+# --- Vault (app secrets) ---
+
+# APP_SECRET — signs sessions and internal tokens; generate with `openssl rand -hex 32`
+# Local scaffold default (also set as vault `dev:` fallback in src/vault.ts).
+APP_SECRET=dev-only-secret
+
+# --- Infrastructure (optional) ---
+# Commented — this app pins postgres, redis, and smtp (Mailpit) in oke.config.ts.
+# Run `oke dev --docker` to write role-accurate keys into `docker/.env.docker`.
+
+# DATABASE_URL — primary Postgres connection; from your host or `docker/.env.docker` after `oke dev --docker`
+# DATABASE_URL=postgres://user:password@127.0.0.1:5432/oke
+
+# REDIS_URL — Redis/Valkey connection for store.kv; from your host or `docker/.env.docker` after `oke dev --docker`
+# REDIS_URL=redis://:password@127.0.0.1:6379
+
+# SMTP_URL — outbound email (Mailpit in docker dev); from your provider or `docker/.env.docker` after `oke dev --docker`
+# SMTP_URL=smtp://127.0.0.1:1025

package/templates/full/README.md

@@ -8,19 +8,25 @@ complete surface ready to fill in.
 ```bash
 bun install
 oke dev          # app :6530 · Console :6533 · MCP :6535
+# or: oke mode docker && oke dev   # postgres · redis · Mailpit · RustFS · sops
 ```
 
-| Port | Try |
-|---|---|
-| `:6530` | `GET /` · `GET /health` |
-| `:6533` | Console |
-| `:6535` | MCP |
+Local `oke dev` auto-runs `oke db push` when `schema.ts` changes (opt out:
+`--no-db-push`). Docker/prod never auto-apply DDL — use `oke db migrate`.
+
+| Port    | Try                       |
+| ------- | ------------------------- |
+| `:6530` | `GET /` · `GET /health`   |
+| `:6533` | Console                   |
+| `:6535` | MCP                       |
 
 ## What’s in this template
 
 ```text
 full/
-├── oke.config.ts
+├── .env.example               # copied to .env.local by create-oke
+├── drizzle.config.ts          # oke db push|generate|migrate
+├── oke.config.ts              # local: sqlite · docker/prod: postgres
 ├── src/
 │   ├── app.ts                 # gates, secrets, signals, stores, channel, ai
 │   ├── core.ts / schema.ts    # Store
@@ -44,6 +50,16 @@ full/
 Replace stubs with real models, prompts, channels, and domain flows. Prefer
 `standard` if you do not need AI / clock / vault on day one.
 
+## Docker mode (`oke dev --docker`)
+
+Closest to production protocols: Postgres, Redis, SMTP (Mailpit), S3 (RustFS),
+vault `sops`/age. Compose credentials land in `docker/.env.docker`.
+
+| Surface        | URL                                              |
+| -------------- | ------------------------------------------------ |
+| Mailpit UI     | [http://127.0.0.1:8025](http://127.0.0.1:8025)   |
+| RustFS console | [http://127.0.0.1:9001](http://127.0.0.1:9001)   |
+
 ## Agent contract
 
 See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/full/drizzle.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "drizzle-kit";
+
+/**
+ * Domain schema sync for `oke db push|generate|migrate`.
+ * Versioned prod migrations land in `./drizzle` — never mix with `.oke/`.
+ */
+export default defineConfig({
+  dialect: "sqlite",
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dbCredentials: {
+    url: process.env.OKE_SQLITE_URL ?? "file:.oke/app.sqlite",
+  },
+});