create-oke 0.2.1 → 0.2.3

package/README.md

@@ -3,11 +3,15 @@
 Scaffold an [okengine](https://www.npmjs.com/package/okengine) app.
 
 ```bash
-bunx create-oke@latest my-app --template hello
+bunx create-oke@latest my-app
 cd my-app
 oke dev
 ```
 
+On a TTY, create-oke opens a Clack wizard: confirm name, pick a template, and
+optionally install + start `oke dev`. Pass `--yes` or `--template` /
+`--from-example` for non-interactive (CI / agents).
+
 | Port | What |
 |---|---|
 | `:6530` | your app |
@@ -21,6 +25,7 @@ Pick another with `--template`, or start from a teaching example with `--from-ex
 bunx create-oke@latest my-app --template hello
 bunx create-oke@latest my-app --template minimal
 bunx create-oke@latest my-app --template full
+bunx create-oke@latest my-app --yes
 bunx create-oke@latest my-notes --from-example notes
 ```
 
@@ -31,6 +36,9 @@ bunx create-oke@latest my-notes --from-example notes
 | `standard` | Full recommended file layout, empty scaffolding (default) |
 | `full` | Every element present and wired, no business logic |
 
+Every scaffold writes an `AGENTS.md` so coding agents know the OKE contract
+(`--no-agents-md` to skip).
+
 `--from-example` copies a teaching example (including its business logic and
 comments) — most new projects want `--template` instead.
 
@@ -41,10 +49,6 @@ comments) — most new projects want `--template` instead.
 | `provisions` | durable flows · `vault` · `channel` · plugins |
 | `skyport` | `ai` · multi-tenancy · distributed topology |
 
-With no arguments in a real terminal, create-oke asks for a project name and
-template interactively. Non-TTY / CI / any explicit flag stays fully scriptable
-— zero prompts.
-
 ## Registries
 
 | Registry | Package |
@@ -52,4 +56,4 @@ template interactively. Non-TTY / CI / any explicit flag stays fully scriptable
 | npm (CLI) | [`create-oke`](https://www.npmjs.com/package/create-oke) — use this with `bunx` |
 | JSR | [`@omqkhafi/create-oke`](https://jsr.io/@omqkhafi/create-oke) — same sources; prefer npm for the binary |
 
-Requires **Bun ≥ 1.3**. Framework docs: [okengine README](https://github.com/omqkhafi/okengine#readme) · [unified theory](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
+Requires **Bun ≥ 1.3**. Docs: [okengine.vercel.app](https://okengine.vercel.app) · [handbook](https://okengine.vercel.app/docs) · [unified theory](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).

package/examples/linkly/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-linkly",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/examples/notes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-notes",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/examples/provisions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-provisions",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/examples/skyport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-skyport",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-oke",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Scaffold an okengine app — bunx create-oke@latest <name>",
   "license": "MIT",
   "type": "module",

package/src/agents-md.ts

@@ -0,0 +1,99 @@
+/**
+ * Slim `AGENTS.md` written into every scaffolded app for coding agents.
+ */
+
+import { docsUrl } from "./docs-origin.ts";
+
+/**
+ * Render the app-facing agent contract for a new project.
+ *
+ * @param projectName - Sanitized package / folder name
+ */
+export function agentsMdContent(projectName: string): string {
+  const handbook = docsUrl("/docs");
+  return `# ${projectName} — OKE Agent Contract
+
+This file is for coding agents (Cursor, Claude Code, Codex, …). Read it before
+changing backend code. Handbook: ${handbook}
+
+**If the docs are silent, stop and ask.**
+
+## The one law
+
+Every backend behavior is a Flow:
+
+\`\`\`text
+on(Trigger) → Effects
+\`\`\`
+
+There are no separate species called endpoints, handlers, consumers, jobs,
+subscribers, or workflows. There is one species — the **Flow** — and triggers
+are typed values.
+
+## The eight elements
+
+| Element | Essence |
+|---|---|
+| **Flow** | behavior |
+| **Signal** | data in motion |
+| **Store** | data at rest (\`sql\` · \`kv\` · \`files\` · \`index\`) |
+| **Clock** | time |
+| **Gate** | permission to act |
+| **Vault** | protected knowledge |
+| **Channel** | reaching humans |
+| **AI** | reaching machine intelligence |
+
+An element earns its place only if it has irreducible physics. New
+infrastructure becomes a new **driver** for an existing element — never a
+ninth element.
+
+## The ten exports
+
+\`\`\`typescript
+import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+\`\`\`
+
+That is the entire public vocabulary. Everything else is derived.
+
+## The fx rule
+
+**All world access goes through \`fx\`. No exceptions.**
+
+A direct \`node:\` import (or any other side-channel I/O) in element or flow
+code is a **defect**. \`fx\` is the single door to the outside world; effects
+are inferred from what a Flow touches through it.
+
+## Ports
+
+| Port | Surface |
+|---|---|
+| **6530** | App |
+| **6533** | Console |
+| **6535** | MCP |
+
+Mnemonic: O·K·E = 6·5·3.
+
+## How to run
+
+\`\`\`bash
+bun install
+oke dev          # or: bun run dev
+\`\`\`
+
+App \`:6530\` · Console \`:6533\` · MCP \`:6535\`.
+
+## Common mistakes
+
+- ❌ I/O outside \`fx\` (raw \`fetch\`, \`node:fs\`, vendor SDKs in flow bodies)
+- ✅ \`fx.store\` / \`fx.emit\` / \`fx.ask\` / channel sends through \`fx\`
+- ❌ Inventing a ninth “element” or a parallel handler stack beside Flows
+- ✅ New capability = new **driver** on an existing element, or a new Flow
+- ❌ Untyped HTTP handlers that skip \`on\` / \`flow\` / contracts
+- ✅ \`on(http.get("/…"), flow({ in, out, do }))\`
+
+## Learn more
+
+- Handbook: ${handbook}
+- Get started: ${docsUrl("/docs/get-started/introduction")}
+`;
+}

package/src/cli.test.ts

@@ -3,7 +3,13 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -72,9 +78,17 @@ describe("shouldPrompt", () => {
     expect(shouldPrompt(parseArgs([]), true)).toBe(true);
   });
 
-  test("non-TTY or any explicit input → no prompts", () => {
+  test("TTY + name alone → still interactive (confirm name / template)", () => {
+    expect(shouldPrompt(parseArgs(["my-app"]), true)).toBe(true);
+  });
+
+  test("non-TTY, --yes, or config flags → no prompts", () => {
     expect(shouldPrompt(parseArgs([]), false)).toBe(false);
-    expect(shouldPrompt(parseArgs(["my-app"]), true)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app"]), false)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app", "--yes"]), true)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app", "--template", "hello"]), true)).toBe(
+      false,
+    );
     expect(shouldPrompt(parseArgs(["--template", "hello"]), true)).toBe(false);
     expect(shouldPrompt(parseArgs(["--from-example", "notes"]), true)).toBe(
       false,
@@ -83,6 +97,23 @@ describe("shouldPrompt", () => {
   });
 });
 
+describe("parseArgs flags", () => {
+  test("accepts --yes / --install / --no-install / --no-agents-md", () => {
+    expect(parseArgs(["x", "--yes"]).yes).toBe(true);
+    expect(parseArgs(["x", "-y"]).yes).toBe(true);
+    expect(parseArgs(["x", "--install"]).install).toBe(true);
+    expect(parseArgs(["x", "--no-install"]).install).toBe(false);
+    expect(parseArgs(["x", "--no-agents-md"]).agentsMd).toBe(false);
+    expect(parseArgs(["x"]).agentsMd).toBe(true);
+  });
+
+  test("rejects --install with --no-install", () => {
+    expect(() => parseArgs(["x", "--install", "--no-install"])).toThrow(
+      /install/,
+    );
+  });
+});
+
 describe("sourceFromArgs", () => {
   test("prefers example when set", () => {
     expect(sourceFromArgs(parseArgs(["x", "--from-example", "linkly"]))).toEqual(
@@ -98,7 +129,12 @@ describe("sourceFromArgs", () => {
 describe("scaffoldArgsFromAnswers ≡ flag-driven", () => {
   test("each --template path matches interactive choice", () => {
     for (const id of TEMPLATES) {
-      const answers: InteractiveAnswers = { name: "x", choice: id };
+      const answers: InteractiveAnswers = {
+        name: "x",
+        choice: id,
+        installAndRun: false,
+        agentsMd: true,
+      };
       const fromAnswers = scaffoldArgsFromAnswers(answers);
       const fromFlags = scaffoldArgsFromCli(
         parseArgs(["x", "--template", id]),
@@ -114,6 +150,8 @@ describe("scaffoldArgsFromAnswers ≡ flag-driven", () => {
         name: "x",
         choice: FROM_EXAMPLE_CHOICE,
         example: id,
+        installAndRun: false,
+        agentsMd: true,
       };
       const fromAnswers = scaffoldArgsFromAnswers(answers);
       const fromFlags = scaffoldArgsFromCli(
@@ -144,6 +182,7 @@ describe("transformPackageJson", () => {
       "0.0.26",
     );
     expect(next.name).toBe("my-app");
+    expect(next.version).toBe("0.0.1");
     expect(next.dependencies?.["okengine"]).toBe("0.0.26");
     expect(next.dependencies?.["okengine"]).not.toBe("file:../..");
     expect(next.dependencies?.["zod"]).toBe("^4.4.3");
@@ -186,7 +225,20 @@ describe("scaffold structure", () => {
           name: `app-${id}`,
           source: { kind: "template", id },
         });
-        expect([...result.files].sort()).toEqual(expected);
+        expect([...result.files].sort()).toEqual(
+          [...expected, "AGENTS.md"].sort(),
+        );
+        expect(result.files).toContain(".gitignore");
+        expect(result.files).toContain("README.md");
+        expect(
+          readFileSync(join(result.targetDir, "AGENTS.md"), "utf8"),
+        ).toMatch(/one law|on\(Trigger\)/i);
+        const readme = readFileSync(join(result.targetDir, "README.md"), "utf8");
+        expect(readme).toMatch(/oke dev/);
+        expect(readme).toMatch(new RegExp(`^# ${id}`, "m"));
+        expect(
+          readFileSync(join(result.targetDir, ".gitignore"), "utf8"),
+        ).toMatch(/node_modules/);
         const pkg = JSON.parse(
           readFileSync(join(result.targetDir, "package.json"), "utf8"),
         ) as { name: string; dependencies: { okengine: string } };
@@ -271,17 +323,34 @@ describe("scaffold structure", () => {
         name: "from-notes",
         source: { kind: "example", id: "notes" },
       });
-      expect([...result.files].sort()).toEqual(expected);
+      expect([...result.files].sort()).toEqual(
+        [...expected, "AGENTS.md"].sort(),
+      );
       expect(result.files).toContain("src/flows/notes/index.ts");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("--no-agents-md skips AGENTS.md", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-no-agents-"));
+    try {
+      const result = scaffold({
+        targetDir: join(dir, "hello"),
+        name: "no-agents",
+        source: { kind: "template", id: "hello" },
+        writeAgentsMd: false,
+      });
+      expect(result.files).not.toContain("AGENTS.md");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("non-TTY CLI", () => {
   test("no args + non-TTY → zero prompts, exit 1", async () => {
-    const code = await run([], { stdinIsTTY: false });
+    const code = await run([], { stdinIsTTY: false, runPostScaffold: false });
     expect(code).toBe(1);
   });
 
@@ -308,11 +377,12 @@ describe("non-TTY CLI", () => {
     const target = join(root, "flag-app");
     try {
       const code = await run(
-        [target, "--template", "hello"],
-        { stdinIsTTY: false },
+        [target, "--template", "hello", "--no-install"],
+        { stdinIsTTY: false, runPostScaffold: false },
       );
       expect(code).toBe(0);
       expect(readdirSync(target).length).toBeGreaterThan(0);
+      expect(existsSync(join(target, "AGENTS.md"))).toBe(true);
       const result = {
         targetDir: target,
         name: "flag-app",
@@ -323,6 +393,7 @@ describe("non-TTY CLI", () => {
       };
       expect(nextStepsText(result)).toContain("oke dev");
       expect(nextStepsText(result)).toContain("bun install");
+      expect(nextStepsText(result)).toContain("okengine.vercel.app");
     } finally {
       rmSync(root, { recursive: true, force: true });
     }

package/src/cli.ts

@@ -4,14 +4,17 @@
  * ```bash
  * bunx create-oke@latest <name> [--template hello|minimal|standard|full]
  * bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+ * bunx create-oke@latest <name> --yes
  * bunx create-oke@latest   # interactive when stdin is a TTY
  * ```
  */
 
 import {
   cancel,
+  confirm,
   intro,
   isCancel,
+  note,
   outro,
   select,
   spinner,
@@ -19,6 +22,8 @@ import {
 } from "@clack/prompts";
 import { basename, relative, resolve } from "node:path";
 import { existsSync, rmSync } from "node:fs";
+import { agentsMdContent } from "./agents-md.ts";
+import { docsUrl } from "./docs-origin.ts";
 import { scaffold, type ScaffoldResult, type ScaffoldSource } from "./scaffold.ts";
 import {
   DEFAULT_TEMPLATE,
@@ -40,6 +45,15 @@ export type CliArgs = {
   /** True when `--template` / `-t` was present on the argv. */
   readonly templateExplicit: boolean;
   readonly help: boolean;
+  /** Skip all prompts; use defaults. */
+  readonly yes: boolean;
+  /**
+   * Install after scaffold.
+   * `undefined` = default (interactive asks; `--yes` installs; else skip).
+   */
+  readonly install: boolean | undefined;
+  /** Write `AGENTS.md` (default true). */
+  readonly agentsMd: boolean;
   readonly targetDir: string | undefined;
 };
 
@@ -54,11 +68,15 @@ export type InteractiveAnswers =
   | {
       readonly name: string;
       readonly choice: TemplateId;
+      readonly installAndRun: boolean;
+      readonly agentsMd: boolean;
     }
   | {
       readonly name: string;
       readonly choice: typeof FROM_EXAMPLE_CHOICE;
       readonly example: ExampleId;
+      readonly installAndRun: boolean;
+      readonly agentsMd: boolean;
     };
 
 /**
@@ -68,6 +86,7 @@ export type ScaffoldCallArgs = {
   readonly name: string;
   readonly targetDir: string;
   readonly source: ScaffoldSource;
+  readonly agentsMd: boolean;
 };
 
 /**
@@ -81,6 +100,9 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   let fromExample: ExampleId | undefined;
   let templateExplicit = false;
   let help = false;
+  let yes = false;
+  let install: boolean | undefined;
+  let agentsMd = true;
   let targetDir: string | undefined;
 
   for (let i = 0; i < argv.length; i++) {
@@ -89,6 +111,26 @@ export function parseArgs(argv: readonly string[]): CliArgs {
       help = true;
       continue;
     }
+    if (a === "--yes" || a === "-y") {
+      yes = true;
+      continue;
+    }
+    if (a === "--install") {
+      install = true;
+      continue;
+    }
+    if (a === "--no-install") {
+      install = false;
+      continue;
+    }
+    if (a === "--no-agents-md") {
+      agentsMd = false;
+      continue;
+    }
+    if (a === "--agents-md") {
+      agentsMd = true;
+      continue;
+    }
     if (a === "--template" || a === "-t") {
       const next = argv[++i];
       if (!next || !isTemplateId(next)) {
@@ -147,11 +189,25 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     );
   }
 
+  if (argv.includes("--install") && argv.includes("--no-install")) {
+    throw new Error("create-oke: use either --install or --no-install, not both");
+  }
+
   if (name !== undefined) {
     targetDir = resolve(name);
   }
 
-  return { name, template, fromExample, templateExplicit, help, targetDir };
+  return {
+    name,
+    template,
+    fromExample,
+    templateExplicit,
+    help,
+    yes,
+    install,
+    agentsMd,
+    targetDir,
+  };
 }
 
 /**
@@ -179,6 +235,8 @@ Next steps:
   cd ${formatCdPath(result.targetDir)}
   bun install
   oke dev          # app :6530 · Console :6533 · MCP :6535
+
+Docs: ${docsUrl("/docs")}
 `;
 }
 
@@ -199,8 +257,19 @@ export function helpText(): string {
 Usage:
   bunx create-oke@latest <name> [--template hello|minimal|standard|full]
   bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+  bunx create-oke@latest <name> --yes
   bunx create-oke@latest          # interactive (TTY only)
 
+Options:
+  -t, --template <id>   Clean starter (default: ${DEFAULT_TEMPLATE})
+  --from-example <id>   Teaching example (non-interactive)
+  -y, --yes             No prompts; defaults + bun install (no oke dev)
+  --install             Run bun install after scaffold
+  --no-install          Skip bun install
+  --agents-md           Write AGENTS.md (default)
+  --no-agents-md        Skip AGENTS.md
+  -h, --help            Show this help
+
 Templates (clean starters from templates/):
 ${templateLines}
 
@@ -208,16 +277,17 @@ ${templateLines}
 comments — most new projects want --template instead):
 ${exampleLines}
 
-No telemetry. Bun only. Interactive prompts only when stdin is a TTY and no
-name / --template / --from-example is given.
+No telemetry. Bun only. On a TTY, a project name alone still opens the wizard
+(confirm name, template, install). Non-TTY / --yes / --template /
+--from-example stay fully scriptable.
 `;
 }
 
 /**
- * Whether the CLI should open the two-question interactive flow.
+ * Whether the CLI should open the interactive Clack flow.
  *
- * Mirrors oke / gflows: bare invocation is interactive only in a real terminal;
- * any explicit flag or positional name stays fully scriptable.
+ * TTY humans get the wizard even when a name is pre-filled. Config flags
+ * (`--template`, `--from-example`) or `--yes` skip prompts for CI/agents.
  *
  * @param args - Parsed args
  * @param stdinIsTTY - `process.stdin.isTTY`
@@ -228,7 +298,7 @@ export function shouldPrompt(
 ): boolean {
   if (!stdinIsTTY) return false;
   if (args.help) return false;
-  if (args.name !== undefined) return false;
+  if (args.yes) return false;
   if (args.templateExplicit) return false;
   if (args.fromExample !== undefined) return false;
   return true;
@@ -261,6 +331,7 @@ export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
     name: basename(resolve(args.name)),
     targetDir: args.targetDir,
     source: sourceFromArgs(args),
+    agentsMd: args.agentsMd,
   };
 }
 
@@ -282,12 +353,14 @@ export function scaffoldArgsFromAnswers(
       name,
       targetDir,
       source: { kind: "example", id: answers.example },
+      agentsMd: answers.agentsMd,
     };
   }
   return {
     name,
     targetDir,
     source: { kind: "template", id: answers.choice },
+    agentsMd: answers.agentsMd,
   };
 }
 
@@ -296,34 +369,32 @@ export function scaffoldArgsFromAnswers(
  *
  * Injectable for tests; production uses {@link askInteractiveAnswers}.
  *
- * @param partial - Name already known (skipped in the prompt)
+ * @param partial - Name already known (pre-filled in the prompt)
  */
 export type AskInteractiveFn = (
-  partial: { readonly name?: string },
+  partial: { readonly name?: string; readonly agentsMd?: boolean },
 ) => Promise<InteractiveAnswers | null>;
 
 /**
  * Collect interactive answers via `@clack/prompts`.
  *
- * @param partial - Optional pre-filled project name
+ * @param partial - Optional pre-filled project name / agents-md default
  * @returns Answers, or `null` if the user cancelled
  */
 export async function askInteractiveAnswers(
-  partial: { readonly name?: string } = {},
+  partial: { readonly name?: string; readonly agentsMd?: boolean } = {},
 ): Promise<InteractiveAnswers | null> {
-  let name = partial.name;
-  if (name === undefined) {
-    const nameValue = await text({
-      message: "Project name",
-      placeholder: "my-app",
-      validate: (value) => {
-        if (!value?.trim()) return "Project name is required";
-        return undefined;
-      },
-    });
-    if (isCancel(nameValue)) return null;
-    name = String(nameValue).trim();
-  }
+  const nameValue = await text({
+    message: "Project name",
+    placeholder: "my-app",
+    initialValue: partial.name ?? "my-app",
+    validate: (value) => {
+      if (!value?.trim()) return "Project name is required";
+      return undefined;
+    },
+  });
+  if (isCancel(nameValue)) return null;
+  const name = String(nameValue).trim();
 
   const templateValue = await select({
     message: "Template",
@@ -343,6 +414,8 @@ export async function askInteractiveAnswers(
   });
   if (isCancel(templateValue)) return null;
 
+  const agentsMd = partial.agentsMd ?? true;
+
   if (templateValue === "__example__") {
     const exampleValue = await select({
       message: "Example",
@@ -353,21 +426,52 @@ export async function askInteractiveAnswers(
       })),
     });
     if (isCancel(exampleValue)) return null;
+
+    const installAndRunValue = await confirm({
+      message: "Install dependencies and start oke dev?",
+      initialValue: true,
+    });
+    if (isCancel(installAndRunValue)) return null;
+
     return {
       name,
       choice: FROM_EXAMPLE_CHOICE,
       example: exampleValue as ExampleId,
+      installAndRun: Boolean(installAndRunValue),
+      agentsMd,
     };
   }
 
-  return { name, choice: templateValue as TemplateId };
+  const installAndRunValue = await confirm({
+    message: "Install dependencies and start oke dev?",
+    initialValue: true,
+  });
+  if (isCancel(installAndRunValue)) return null;
+
+  return {
+    name,
+    choice: templateValue as TemplateId,
+    installAndRun: Boolean(installAndRunValue),
+    agentsMd,
+  };
+}
+
+/**
+ * Resolve whether to run `bun install` after scaffold (non-interactive).
+ *
+ * @param args - Parsed args
+ */
+export function shouldInstall(args: CliArgs): boolean {
+  if (args.install === true) return true;
+  if (args.install === false) return false;
+  return args.yes;
 }
 
 /**
  * Run the CLI.
  *
  * @param argv - Args after the binary
- * @param options - Test seams (stdin TTY, ask injection)
+ * @param options - Test seams (stdin TTY, ask injection, skip real install/dev)
  * @returns Exit code
  */
 export async function run(
@@ -375,6 +479,8 @@ export async function run(
   options: {
     readonly stdinIsTTY?: boolean | undefined;
     readonly ask?: AskInteractiveFn;
+    /** When false, skip spawning bun install / oke dev (tests). Default true. */
+    readonly runPostScaffold?: boolean;
   } = {},
 ): Promise<number> {
   let args: CliArgs;
@@ -392,34 +498,49 @@ export async function run(
 
   const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY;
   if (shouldPrompt(args, stdinIsTTY)) {
-    return runInteractive(args, options.ask ?? askInteractiveAnswers);
+    return runInteractive(args, options.ask ?? askInteractiveAnswers, options);
   }
 
   if (args.name === undefined) {
     console.log(helpText());
-    console.error("create-oke: missing <name>");
+    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;
   }
 
+  if (args.yes) {
+    const source = sourceFromArgs(args);
+    console.log(
+      `Using defaults: ${source.kind}=${source.id} agents-md=${args.agentsMd} install=${shouldInstall(args)}`,
+    );
+  }
+
   return runScaffold({
     ...scaffoldArgsFromCli(args),
     interactive: false,
+    install: shouldInstall(args),
+    startDev: false,
+    runPostScaffold: options.runPostScaffold ?? true,
   });
 }
 
 /**
  * Interactive TTY flow — ask → map answers → scaffold.
  *
- * @param args - Parsed args (name may already be set if ever called that way)
+ * @param args - Parsed args (name may already be set)
  * @param ask - Injectable ask step
+ * @param options - Post-scaffold seams
  */
 async function runInteractive(
   args: CliArgs,
   ask: AskInteractiveFn,
+  options: { readonly runPostScaffold?: boolean },
 ): Promise<number> {
   intro("create-oke");
 
-  const answers = await ask({ name: args.name });
+  const answers = await ask({ name: args.name, agentsMd: args.agentsMd });
   if (answers === null) {
     cancel("Cancelled.");
     return 1;
@@ -428,18 +549,35 @@ async function runInteractive(
   return runScaffold({
     ...scaffoldArgsFromAnswers(answers),
     interactive: true,
+    install: answers.installAndRun,
+    startDev: answers.installAndRun,
+    runPostScaffold: options.runPostScaffold ?? true,
   });
 }
 
 /**
  * Scaffold with optional spinner / outro, cleaning up on failure or cancel.
  *
- * @param options - Scaffold inputs + interactive flag
+ * @param options - Scaffold inputs + interactive / install flags
  */
 async function runScaffold(
-  options: ScaffoldCallArgs & { readonly interactive: boolean },
+  options: ScaffoldCallArgs & {
+    readonly interactive: boolean;
+    readonly install: boolean;
+    readonly startDev: boolean;
+    readonly runPostScaffold: boolean;
+  },
 ): Promise<number> {
-  const { name, targetDir, source, interactive } = options;
+  const {
+    name,
+    targetDir,
+    source,
+    agentsMd,
+    interactive,
+    install,
+    startDev,
+    runPostScaffold,
+  } = options;
   const existed = existsSync(targetDir);
   let spun: ReturnType<typeof spinner> | undefined;
 
@@ -462,14 +600,53 @@ async function runScaffold(
       spun = spinner();
       spun.start("Scaffolding…");
     }
-    const result = scaffold({ targetDir, name, source });
+    const result = scaffold({
+      targetDir,
+      name,
+      source,
+      writeAgentsMd: agentsMd,
+    });
     if (spun) spun.stop("Scaffolded.");
+
+    if (runPostScaffold && install) {
+      const installSpun = interactive ? spinner() : undefined;
+      installSpun?.start("Installing dependencies…");
+      const installOk = await runCommand(["bun", "install"], targetDir);
+      if (!installOk) {
+        installSpun?.stop("Install failed.");
+        cleanup();
+        console.error("create-oke: bun install failed");
+        return 1;
+      }
+      installSpun?.stop("Installed.");
+    }
+
     const message = nextStepsText(result);
     if (interactive) {
+      note(
+        [
+          `App      http://127.0.0.1:6530`,
+          `Console  http://127.0.0.1:6533`,
+          `MCP      http://127.0.0.1:6535`,
+          `Docs     ${docsUrl("/docs")}`,
+          agentsMd ? `Agents   AGENTS.md` : undefined,
+        ]
+          .filter(Boolean)
+          .join("\n"),
+        "Ports",
+      );
       outro(message.trim());
     } else {
       console.log(message);
     }
+
+    if (runPostScaffold && startDev) {
+      const ok = await runCommand(["bun", "run", "dev"], targetDir, {
+        inherit: true,
+      });
+      return ok ? 0 : 1;
+    }
+
     return 0;
   } catch (e) {
     spun?.stop("Failed.");
@@ -480,3 +657,32 @@ async function runScaffold(
     process.off("SIGINT", onSigInt);
   }
 }
+
+/**
+ * Spawn a command in `cwd`.
+ *
+ * @param cmd - Argv
+ * @param cwd - Working directory
+ * @param options - Inherit stdio for long-running processes
+ */
+async function runCommand(
+  cmd: readonly string[],
+  cwd: string,
+  options: { readonly inherit?: boolean } = {},
+): Promise<boolean> {
+  const proc = Bun.spawn([...cmd], {
+    cwd,
+    stdout: options.inherit ? "inherit" : "pipe",
+    stderr: options.inherit ? "inherit" : "pipe",
+    stdin: options.inherit ? "inherit" : undefined,
+  });
+  const code = await proc.exited;
+  if (code !== 0 && !options.inherit) {
+    const err = await new Response(proc.stderr).text();
+    if (err.trim()) console.error(err);
+  }
+  return code === 0;
+}
+
+/** Re-export for tests that assert agents content shape. */
+export { agentsMdContent };

package/src/docs-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical public docs origin for scaffolded AGENTS.md and next-steps.
+ *
+ * Keep in lockstep with `src/docs-origin.ts` in the okengine package.
+ * Flip both when the custom domain is attached: `https://oke.omqkhafi.dev`.
+ */
+
+/** Live docs site (Vercel). Planned cutover: `https://oke.omqkhafi.dev`. */
+export const DOCS_ORIGIN = "https://okengine.vercel.app" as const;
+
+/**
+ * Absolute docs URL for a path under the handbook / site.
+ *
+ * @param path - Path beginning with `/` (e.g. `/docs`)
+ */
+export function docsUrl(path: string): string {
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  return `${DOCS_ORIGIN}${normalized}`;
+}

package/src/index.ts

@@ -4,6 +4,7 @@
  *
  * ```bash
  * bunx create-oke@latest my-app
+ * bunx create-oke@latest my-app --yes
  * bunx create-oke@latest my-app --template hello
  * bunx create-oke@latest my-app --from-example notes
  * ```

package/src/scaffold.ts

@@ -20,6 +20,7 @@ import {
   type ExampleId,
   type TemplateId,
 } from "./templates.ts";
+import { agentsMdContent } from "./agents-md.ts";
 import {
   sanitizeProjectName,
   shouldSkipTemplatePath,
@@ -41,6 +42,8 @@ export type ScaffoldOptions = {
   readonly name: string;
   /** Template or teaching-example source. */
   readonly source: ScaffoldSource;
+  /** Write root `AGENTS.md` (default true). */
+  readonly writeAgentsMd?: boolean;
 };
 
 /** Result of a successful scaffold. */
@@ -98,6 +101,12 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
     writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
 
+    if (options.writeAgentsMd !== false) {
+      const agentsPath = join(targetDir, "AGENTS.md");
+      writeFileSync(agentsPath, agentsMdContent(name), "utf8");
+      if (!written.includes("AGENTS.md")) written.push("AGENTS.md");
+    }
+
     written.sort();
     return {
       targetDir,

package/src/transform.ts

@@ -62,6 +62,8 @@ export function transformPackageJson(
   return {
     ...source,
     name: projectName,
+    // Starter apps always begin at 0.0.1 — never the framework lockstep version.
+    version: "0.0.1",
     dependencies,
   };
 }

package/templates/full/README.md

@@ -0,0 +1,49 @@
+# full
+
+**Every element present and wired** — no business logic. Use when you want the
+complete surface ready to fill in.
+
+## Run
+
+```bash
+bun install
+oke dev          # app :6530 · Console :6533 · MCP :6535
+```
+
+| Port | Try |
+|---|---|
+| `:6530` | `GET /` · `GET /health` |
+| `:6533` | Console |
+| `:6535` | MCP |
+
+## What’s in this template
+
+```text
+full/
+├── oke.config.ts
+├── src/
+│   ├── app.ts                 # gates, secrets, signals, stores, channel, ai
+│   ├── core.ts / schema.ts    # Store
+│   ├── gates.ts               # open gate (used on HTTP)
+│   ├── vault.ts               # appSecret
+│   ├── channels.ts            # welcome template
+│   ├── ai.ts                  # stub model + echo prompt
+│   ├── locales/en.ts · ar.ts
+│   └── flows/main/
+│       ├── index.ts           # GET / · GET /health · every("1d")
+│       ├── shapes.ts
+│       └── signals.ts         # pinged
+└── tests/full.test.ts
+```
+
+- **Elements wired:** Flow · Store · Signal · Clock (`every`) · Gate · Vault · Channel · AI
+- **Unit:** `main`
+- **App `$options`:** `gates`, `secrets`, `signals`, `stores`, `channel`, `ai`
+- **Flows:** `root`, `health` (emits `pinged`), plus a trivial daily cron
+
+Replace stubs with real models, prompts, channels, and domain flows. Prefer
+`standard` if you do not need AI / clock / vault on day one.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/full/oke.config.ts

@@ -19,5 +19,9 @@ export default defineConfig({
       test: "mock",
     },
   },
+  images: {
+    "store.sql": "postgres:18-alpine",
+    "store.kv": "redis:8-alpine",
+  },
   i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
 });

package/templates/full/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/template-full",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/templates/full/src/flows/main/index.ts

@@ -1,8 +1,26 @@
 import { on, flow, http, every } from "okengine";
+import { z } from "zod";
 import { open } from "../../gates";
 import { Health } from "./shapes";
 import { pinged } from "./signals";
 
+/** First-run welcome — visit :6530/ after `oke dev`. */
+export const root = on(
+  http.get("/").gate(open),
+  flow({
+    out: z.object({
+      ok: z.literal(true),
+      console: z.string(),
+      try: z.string(),
+    }),
+    do: () => ({
+      ok: true as const,
+      console: "http://127.0.0.1:6533",
+      try: "/health",
+    }),
+  }),
+);
+
 export const health = on(
   http.get("/health").gate(open),
   flow({

package/templates/hello/README.md

@@ -1,13 +1,38 @@
 # hello
 
-Fastest possible okengine scaffold — one flow, no Store. This is an "it works"
-starting point, not a lesson.
+Fastest possible “it works” — one unit, two HTTP flows, **no Store**.
+
+## Run
 
 ```bash
 bun install
 oke dev          # app :6530 · Console :6533 · MCP :6535
 ```
 
-Try `GET /hello`. For the teaching path (comment-heavy apps with real domains),
-see the `examples/` apps and `docs/spec/four-applications.md` in the okengine
-repo — or scaffold with `bunx create-oke@latest <name> --from-example notes`.
+| Port | Try |
+|---|---|
+| `:6530` | `GET /` · `GET /hello` |
+| `:6533` | Console |
+| `:6535` | MCP |
+
+## What’s in this template
+
+```text
+hello/
+├── oke.config.ts
+├── src/
+│   ├── app.ts                 # oke({ name: "hello" }).adopt({ hello })
+│   └── flows/hello/index.ts   # GET / · GET /hello
+└── tests/hello.test.ts
+```
+
+- **Elements:** Flow only (no `store`, `gate`, `vault`, `channel`, or `ai`)
+- **Unit:** `hello`
+- **Flows:** `root` (`GET /`), `hello` (`GET /hello` → `{ message: "ok" }`)
+
+Replace `/hello` with your first real route. When you need persistence, move up to
+`minimal` or `standard` — or keep growing this tree.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/hello/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/template-hello",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/templates/hello/src/flows/hello/index.ts

@@ -1,6 +1,23 @@
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
+/** First-run welcome — visit :6530/ after `oke dev`. */
+export const root = on(
+  http.get("/"),
+  flow({
+    out: z.object({
+      ok: z.literal(true),
+      console: z.string(),
+      try: z.string(),
+    }),
+    do: () => ({
+      ok: true as const,
+      console: "http://127.0.0.1:6533",
+      try: "/hello",
+    }),
+  }),
+);
+
 export const hello = on(
   http.get("/hello"),
   flow({

package/templates/minimal/README.md

@@ -0,0 +1,41 @@
+# minimal
+
+Smallest shape you’d actually ship — **Store + HTTP flows** over a single table.
+
+## Run
+
+```bash
+bun install
+oke dev          # app :6530 · Console :6533 · MCP :6535
+```
+
+| Port | Try |
+|---|---|
+| `:6530` | `GET /` · `GET /entries` · `POST /entries` |
+| `:6533` | Console |
+| `:6535` | MCP |
+
+## What’s in this template
+
+```text
+minimal/
+├── oke.config.ts
+├── src/
+│   ├── app.ts                 # adopt({ main }), stores: [db]
+│   ├── core.ts                # store.sql("…")
+│   ├── schema.ts              # entries table (Drizzle)
+│   └── flows/main/index.ts    # GET / · GET|POST /entries
+└── tests/minimal.test.ts
+```
+
+- **Elements:** Flow · Store (`sql`)
+- **Unit:** `main`
+- **Flows:** `root`, `list` (`GET /entries`), `create` (`POST /entries` with `{ body }`)
+- **Schema:** `entries` — `id`, `body`, `createdAt`
+
+Swap `entries` for your domain table and grow flows beside it. Need gates,
+channels, or locales? Use `standard`.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/minimal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/template-minimal",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/templates/minimal/src/flows/main/index.ts

@@ -11,6 +11,23 @@ const Entry = z.object({
   createdAt: z.number(),
 });
 
+/** First-run welcome — visit :6530/ after `oke dev`. */
+export const root = on(
+  http.get("/"),
+  flow({
+    out: z.object({
+      ok: z.literal(true),
+      console: z.string(),
+      try: z.string(),
+    }),
+    do: () => ({
+      ok: true as const,
+      console: "http://127.0.0.1:6533",
+      try: "GET /entries",
+    }),
+  }),
+);
+
 export const create = on(
   http.post("/entries"),
   flow({

package/templates/standard/README.md

@@ -0,0 +1,47 @@
+# standard
+
+Full recommended file layout with **empty scaffolding** — structure without
+business logic. Default `create-oke` template.
+
+## Run
+
+```bash
+bun install
+oke dev          # app :6530 · Console :6533 · MCP :6535
+```
+
+| Port | Try |
+|---|---|
+| `:6530` | `GET /` · `GET /health` |
+| `:6533` | Console |
+| `:6535` | MCP |
+
+## What’s in this template
+
+```text
+standard/
+├── oke.config.ts
+├── src/
+│   ├── app.ts                 # adopt({ main }); wires stores + side modules
+│   ├── core.ts / schema.ts    # Store (replace the placeholder table)
+│   ├── gates.ts               # Gate stubs
+│   ├── vault.ts               # Vault stubs
+│   ├── channels.ts            # Channel stubs
+│   ├── locales/en.ts · ar.ts  # i18n stubs
+│   └── flows/main/
+│       ├── index.ts           # GET / · GET /health
+│       ├── shapes.ts          # contracts live next to flows
+│       └── signals.ts         # Signal stubs
+└── tests/standard.test.ts
+```
+
+- **Elements stubbed:** Flow · Store · Signal · Gate · Vault · Channel (+ locales)
+- **Unit:** `main`
+- **Flows to replace:** `root`, `health` — delete or rename once your domain exists
+
+Fill `schema.ts`, then add real flows under `src/flows/<unit>/`. Prefer this
+layout for new products; use `hello` / `minimal` only when you want less surface.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/standard/oke.config.ts

@@ -15,5 +15,9 @@ export default defineConfig({
       whatsapp: { dev: "console", test: "console", prod: "wa-cloud" },
     },
   },
+  images: {
+    "store.sql": "postgres:18-alpine",
+    "store.kv": "redis:8-alpine",
+  },
   i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
 });

package/templates/standard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/template-standard",
-  "version": "0.2.1",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/templates/standard/src/flows/main/index.ts

@@ -4,6 +4,23 @@ import { z } from "zod";
 import "./shapes";
 import "./signals";
 
+/** First-run welcome — visit :6530/ after `oke dev`. */
+export const root = on(
+  http.get("/"),
+  flow({
+    out: z.object({
+      ok: z.literal(true),
+      console: z.string(),
+      try: z.string(),
+    }),
+    do: () => ({
+      ok: true as const,
+      console: "http://127.0.0.1:6533",
+      try: "/health",
+    }),
+  }),
+);
+
 /** Replace with your unit's flows. */
 export const health = on(
   http.get("/health"),