@cursor/bdk 0.2.1

package/src/internal/init-project.ts

@@ -0,0 +1,711 @@
+/**
+ * Scaffold a minimal BDK project (`bdk init`).
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { runfiles } from "@bazel/runfiles";
+import type { ModelSetting } from "../types.js";
+import {
+  canonicalTemplateName,
+  isTemplateName,
+  readCursorAgentTemplate,
+  type TemplateName,
+} from "./cursor-agent-template.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME, packageRootDir, packageVersion } from "./distribution.js";
+import {
+  applyInitReplacements,
+  isTemplateMetaPath,
+  loadTemplateInitSpec,
+  posixRel,
+  type TemplateInitSpec,
+  templateFileHasReplacements,
+} from "./init-interview.js";
+import { agentsMd, GITIGNORE, writeDefaultScaffold } from "./init-scaffold.js";
+import {
+  type ProjectRoot,
+  remapCanonicalProjectContents,
+  remapCanonicalProjectPath,
+  resolveProjectRoot,
+} from "./project-layout.js";
+import { makePalette, stdoutPalette, type TerminalPalette } from "./terminal-style.js";
+
+export interface InitProjectOptions {
+  /** Directory to create (created if missing). */
+  dir: string;
+  /** Agent display name; defaults to the directory basename. */
+  name?: string;
+  /** Model id override written into agent.ts. */
+  model?: string;
+  templateDir?: string;
+  overlayDir?: string;
+  templateName?: string;
+  /** Answers collected from `init.json` / `--var`. */
+  answers?: Record<string, string>;
+  initSpec?: TemplateInitSpec;
+}
+
+export type InitFileAction = "create" | "exist";
+
+export interface InitFileEntry {
+  path: string;
+  action: InitFileAction;
+}
+
+export interface InitProjectResult {
+  rootDir: string;
+  /** Scaffold files in write order, with create/exist for each. */
+  files: InitFileEntry[];
+  /** Paths newly written. */
+  created: string[];
+  /** Paths left alone because they already existed. */
+  skipped: string[];
+}
+
+type TemplateEntry = {
+  dir: string;
+  overlay?: string;
+};
+
+const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
+  "agentic-owners": { dir: "agentic-owners" },
+  "agents-md": { dir: "agents-md" },
+  "code-wiki": { dir: "code-wiki" },
+  demo: { dir: "demo" },
+  "grokbot-agents": { dir: "grokbot-agents" },
+  "pr-autofixer": { dir: "pr-autofixer" },
+  "security-help": { dir: "security-help" },
+  "security-reviewer": { dir: "security-reviewer" },
+  "thermo-quality-review": { dir: "thermo-quality-review" },
+  "thermo-review": { dir: "thermo-review" },
+  "triage-linear": { dir: "triage", overlay: "linear" },
+  "triage-jira": { dir: "triage", overlay: "jira" },
+};
+
+export function availableTemplates(): string[] {
+  return Object.keys(TEMPLATES).sort();
+}
+
+export type TemplateResolution =
+  | { ok: true; name: string; dir: string; overlayDir?: string }
+  | { ok: false; message: string };
+
+export function resolveTemplate(name: string): TemplateResolution {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    return {
+      ok: false,
+      message: "template name must match /^[a-z][a-z0-9-]*$/",
+    };
+  }
+  const resolved = canonicalTemplateName(name);
+  if (!isTemplateName(resolved)) {
+    return {
+      ok: false,
+      message: `unknown template "${name}" (available: ${availableTemplates().join(", ")})`,
+    };
+  }
+  const entry = TEMPLATES[resolved];
+  const dir = resolvePackagePath("templates", entry.dir);
+  return {
+    ok: true,
+    name: resolved,
+    dir,
+    overlayDir: entry.overlay === undefined ? undefined : join(dir, "overlays", entry.overlay),
+  };
+}
+
+function resolvePackagePath(...segments: string[]): string {
+  if (runfiles.workspace !== undefined) {
+    return runfiles.resolveWorkspaceRelative(["packages", "agent-serve", ...segments].join("/"));
+  }
+  return join(packageRootDir(), ...segments);
+}
+
+export type InitTargetCheck = { ok: true } | { ok: false; message: string };
+
+/**
+ * Re-init must keep the mode the project was scaffolded with: template
+ * scaffolds stamp `cursorAgentTemplate` into package.json, and a mismatch
+ * here would silently mix default-scaffold files into a template project
+ * (or the reverse).
+ */
+export function checkInitTarget(rootDir: string, template: string | undefined): InitTargetCheck {
+  const pkgPath = join(rootDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { ok: true };
+  }
+  const marker = readCursorAgentTemplate(rootDir);
+  if (marker === template) {
+    return { ok: true };
+  }
+  if (
+    marker !== undefined &&
+    template !== undefined &&
+    canonicalTemplateName(marker) === canonicalTemplateName(template)
+  ) {
+    return { ok: true };
+  }
+  if (template === undefined) {
+    return {
+      ok: false,
+      message: `${rootDir} was scaffolded from the "${marker}" template; re-run with --template ${marker}`,
+    };
+  }
+  if (marker === undefined) {
+    return {
+      ok: false,
+      message: `${rootDir} already has a package.json without template provenance; re-run init without --template, or scaffold into a fresh directory`,
+    };
+  }
+  return {
+    ok: false,
+    message: `${rootDir} was scaffolded from the "${marker}" template, not "${template}"`,
+  };
+}
+
+const DEFAULT_MODEL: ModelSetting = {
+  id: "grok-4.5",
+  params: [
+    { id: "effort", value: "high" },
+    { id: "fast", value: "true" },
+  ],
+};
+
+export async function initProject(options: InitProjectOptions): Promise<InitProjectResult> {
+  const rootDir = resolve(options.dir);
+  const projectName = basename(rootDir);
+  const name = options.name ?? projectName;
+  const model = formatModelLiteral(options.model ?? DEFAULT_MODEL);
+  const projectRoot = resolveProjectRoot(rootDir);
+
+  const files: InitFileEntry[] = [];
+  const write = async (rel: string, contents: string | Uint8Array): Promise<void> => {
+    const abs = join(rootDir, rel);
+    await mkdir(dirname(abs), { recursive: true });
+    try {
+      await writeFile(abs, contents, { flag: "wx" });
+      files.push({ path: rel, action: "create" });
+    } catch (error) {
+      if (isEexist(error)) {
+        files.push({ path: rel, action: "exist" });
+        return;
+      }
+      throw error;
+    }
+  };
+
+  if (options.templateDir !== undefined) {
+    const templateDir = options.templateDir;
+    const overlayDir = options.overlayDir;
+    const overlayPaths = overlayDir ? await listTemplateFiles(overlayDir) : [];
+    const overlaySet = new Set(overlayPaths);
+    const corePaths = (await listTemplateFiles(templateDir)).filter(rel => !overlaySet.has(rel));
+    const templateName = options.templateName ?? basename(templateDir);
+    const initSpec = options.initSpec ?? (await loadTemplateInitSpec(templateDir));
+    const answers = options.answers ?? {};
+    for (const rel of corePaths) {
+      await writeTemplateFile({
+        write,
+        sourceDir: templateDir,
+        rel,
+        destinationRel: remapCanonicalProjectPath(rel, projectRoot),
+        projectRoot,
+        projectName,
+        templateName,
+        initSpec,
+        answers,
+      });
+    }
+    if (overlayDir !== undefined) {
+      for (const rel of overlayPaths) {
+        await writeTemplateFile({
+          write,
+          sourceDir: overlayDir,
+          rel,
+          destinationRel: remapCanonicalProjectPath(rel, projectRoot),
+          projectRoot,
+          projectName,
+          templateName,
+          initSpec,
+          answers,
+        });
+      }
+    }
+  } else {
+    await writeDefaultScaffold(write, name, model, projectRoot);
+  }
+
+  await write("AGENTS.md", agentsMd(name, projectRoot));
+  await write(".gitignore", GITIGNORE);
+  return {
+    rootDir,
+    files,
+    created: files.filter(entry => entry.action === "create").map(entry => entry.path),
+    skipped: files.filter(entry => entry.action === "exist").map(entry => entry.path),
+  };
+}
+
+async function listTemplateFiles(root: string): Promise<string[]> {
+  const entries = await readdir(root, {
+    recursive: true,
+    withFileTypes: true,
+  });
+  return entries
+    .filter(entry => entry.isFile())
+    .map(entry => posixRel(relative(root, join(entry.parentPath, entry.name))))
+    .filter(rel => !isTemplateMetaPath(rel))
+    .sort();
+}
+
+async function writeTemplateFile(input: {
+  write: (rel: string, contents: string | Uint8Array) => Promise<void>;
+  sourceDir: string;
+  rel: string;
+  destinationRel: string;
+  projectRoot: ProjectRoot;
+  projectName: string;
+  templateName: string;
+  initSpec?: TemplateInitSpec;
+  answers: Record<string, string>;
+}): Promise<void> {
+  const source = join(input.sourceDir, input.rel);
+  if (input.rel === "package.json") {
+    const packageJson: {
+      name: string;
+      dependencies: Record<string, string>;
+      [key: string]: unknown;
+    } = JSON.parse(await readFile(source, "utf8"));
+    packageJson.name = input.projectName;
+    packageJson.dependencies[PACKAGE_NAME] = `^${packageVersion()}`;
+    packageJson.cursorAgentTemplate = input.templateName;
+    await input.write(input.destinationRel, `${JSON.stringify(packageJson, null, 2)}\n`);
+    return;
+  }
+  if (input.initSpec !== undefined && templateFileHasReplacements(input.initSpec, input.rel)) {
+    const contents = applyInitReplacements(
+      await readFile(source, "utf8"),
+      input.rel,
+      input.initSpec,
+      input.answers,
+    );
+    await input.write(
+      input.destinationRel,
+      remapCanonicalProjectContents(contents, input.projectRoot),
+    );
+    return;
+  }
+  const contents = await readFile(source, "utf8");
+  await input.write(
+    input.destinationRel,
+    remapCanonicalProjectContents(contents, input.projectRoot),
+  );
+}
+
+export function isEexist(error: unknown): boolean {
+  return hasErrorCode(error, "EEXIST");
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return error !== null && typeof error === "object" && "code" in error && error.code === code;
+}
+
+export interface InstallScaffoldDependenciesOptions {
+  /**
+   * `inherit` streams npm output to the terminal (human `init`);
+   * `pipe` captures it ( `--json` / tests).
+   */
+  stdio?: "inherit" | "pipe";
+  /** Test seam — replaces the real `npm install` spawn. */
+  runner?: (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdio: "inherit" | "pipe";
+  }) => Promise<{ exitCode: number; stderr: string }>;
+}
+
+export interface InstallScaffoldDependenciesResult {
+  ok: boolean;
+  exitCode: number;
+  stderr: string;
+}
+
+/**
+ * Install the scaffold's npm dependencies so `dev` / `run` can resolve
+ * `@cursor/bdk` immediately after `init`.
+ */
+export async function installScaffoldDependencies(
+  rootDir: string,
+  options: InstallScaffoldDependenciesOptions = {},
+): Promise<InstallScaffoldDependenciesResult> {
+  const stdio = options.stdio ?? "inherit";
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const args = ["install", "--no-fund", "--no-audit"];
+  const runner = options.runner ?? defaultNpmInstallRunner;
+  const result = await runner({ command, args, cwd: rootDir, stdio });
+  return {
+    ok: result.exitCode === 0,
+    exitCode: result.exitCode,
+    stderr: result.stderr,
+  };
+}
+
+export interface LinkCliOntoPathOptions {
+  stdio?: "inherit" | "pipe";
+  runner?: (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdio: "inherit" | "pipe";
+  }) => Promise<{ exitCode: number; stderr: string }>;
+  /** Test seam — absolute path of the linked CLI when present. */
+  whichImpl?: (command: string) => string | undefined | Promise<string | undefined>;
+}
+
+export interface LinkCliOntoPathResult {
+  ok: boolean;
+  exitCode: number;
+  stderr: string;
+  /** Absolute path to the linked `bdk` when it resolves on PATH. */
+  resolvedPath?: string;
+}
+
+/**
+ * Put `bdk` on the user PATH by installing the already-downloaded project
+ * copy into the npm global prefix. `npx @cursor/bdk init` only runs the
+ * package; this is the install that makes bare `bdk …`
+ * work afterward.
+ */
+export async function linkCliOntoPath(
+  rootDir: string,
+  options: LinkCliOntoPathOptions = {},
+): Promise<LinkCliOntoPathResult> {
+  const packageDir = join(rootDir, "node_modules", PACKAGE_NAME);
+  if (!existsSync(packageDir)) {
+    return {
+      ok: false,
+      exitCode: 1,
+      stderr: `missing ${PACKAGE_NAME} under ${packageDir} (run npm install first)`,
+    };
+  }
+  const stdio = options.stdio ?? "inherit";
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const args = ["install", "--global", "--no-fund", "--no-audit", packageDir];
+  const runner = options.runner ?? defaultNpmInstallRunner;
+  const result = await runner({ command, args, cwd: rootDir, stdio });
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      exitCode: result.exitCode,
+      stderr: result.stderr,
+    };
+  }
+  const whichImpl = options.whichImpl ?? resolveLinkedCli;
+  const resolvedPath = await whichImpl(CLI_COMMAND_NAME);
+  return {
+    ok: resolvedPath !== undefined,
+    exitCode: 0,
+    stderr:
+      resolvedPath === undefined
+        ? `${CLI_COMMAND_NAME} linked into the npm global prefix but is not on PATH; open a new shell or add that bin directory to PATH`
+        : "",
+    resolvedPath,
+  };
+}
+
+/** Prefer the npm-global bin; ignore an older `bdk` earlier on PATH. */
+async function resolveLinkedCli(commandName: string): Promise<string | undefined> {
+  const prefix = await npmGlobalPrefix();
+  if (prefix === undefined) {
+    return whichOnPath(commandName);
+  }
+  const binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+      : [""];
+  for (const ext of exts) {
+    const candidate = join(binDir, `${commandName}${ext}`);
+    if (!existsSync(candidate)) {
+      continue;
+    }
+    // Only claim PATH success when this linked bin is the first hit.
+    const onPath = whichOnPath(commandName);
+    return onPath === candidate ? candidate : undefined;
+  }
+  return undefined;
+}
+
+async function npmGlobalPrefix(): Promise<string | undefined> {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  return await new Promise(resolvePromise => {
+    const child = spawn(command, ["prefix", "-g"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: process.env,
+    });
+    let out = "";
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      out += chunk;
+    });
+    child.on("error", () => resolvePromise(undefined));
+    child.on("close", code => {
+      if (code !== 0) {
+        resolvePromise(undefined);
+        return;
+      }
+      const prefix = out.trim();
+      resolvePromise(prefix === "" ? undefined : prefix);
+    });
+  });
+}
+
+function whichOnPath(commandName: string): string | undefined {
+  const pathEnv = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+      : [""];
+  for (const dir of pathEnv.split(sep)) {
+    if (dir === "") {
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = join(dir, `${commandName}${ext}`);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
+async function defaultNpmInstallRunner(args: {
+  command: string;
+  args: string[];
+  cwd: string;
+  stdio: "inherit" | "pipe";
+}): Promise<{ exitCode: number; stderr: string }> {
+  return await new Promise((resolvePromise, reject) => {
+    const child = spawn(args.command, args.args, {
+      cwd: args.cwd,
+      stdio: args.stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stderr = "";
+    if (args.stdio === "pipe") {
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk: string) => {
+        stderr += chunk;
+      });
+      child.stdout?.resume();
+    }
+    child.on("error", reject);
+    child.on("close", code => {
+      resolvePromise({ exitCode: code ?? 1, stderr });
+    });
+  });
+}
+
+function formatModelLiteral(model: string | ModelSetting): string {
+  if (typeof model === "string") {
+    return JSON.stringify(model);
+  }
+  const params =
+    model.params === undefined
+      ? ""
+      : `,
+    params: [
+${model.params
+  .map(param => `      { id: ${JSON.stringify(param.id)}, value: ${JSON.stringify(param.value)} },`)
+  .join("\n")}
+    ]`;
+  return `{
+    id: ${JSON.stringify(model.id)}${params},
+  }`;
+}
+
+export interface InitScaffoldSummaryOptions {
+  /** Scaffolded project root (absolute). */
+  rootDir: string;
+  /** Scaffold files in write order (`create` / `exist`). */
+  files: InitFileEntry[];
+  /** Override TTY color detection (tests / `--json` callers). */
+  color?: boolean;
+}
+
+export interface InitNextStepsOptions {
+  /** Scaffolded project root (absolute). */
+  rootDir: string;
+  /** Directory the command ran from. */
+  cwd: string;
+  /**
+   * True when a Cursor credential resolves. When false, next steps include
+   * `login` (used for `--json` and when an interactive login attempt failed).
+   */
+  signedIn: boolean;
+  /**
+   * True when `bdk` resolves on PATH after init linked the CLI.
+   * When false, next steps include a PATH export for `node_modules/.bin`.
+   */
+  cliOnPath: boolean;
+  /** Override TTY color detection (tests / `--json` callers). */
+  color?: boolean;
+}
+
+export type InitSummaryOptions = InitScaffoldSummaryOptions & InitNextStepsOptions;
+
+function initPalette(color?: boolean): TerminalPalette {
+  return color === undefined ? stdoutPalette() : makePalette(color);
+}
+
+/**
+ * Created/skipped files plus the project path. Printed before an interactive
+ * login so the scaffold is visible while the browser flow runs.
+ */
+export function formatInitScaffoldSummary(options: InitScaffoldSummaryOptions): string {
+  const c = initPalette(options.color);
+  const name = basename(options.rootDir);
+  const lines: string[] = [];
+  lines.push(`Initialized agent ${name}`);
+  lines.push("");
+  for (const file of options.files) {
+    // Empty-dir placeholders stay on disk but clutter the summary.
+    if (file.path.endsWith("/.gitkeep") || file.path === ".gitkeep") {
+      continue;
+    }
+    // Thor/Rails status column is 12 chars, right-aligned.
+    lines.push(c.dim(`${file.action.padStart(12)}  ${file.path}`));
+  }
+  lines.push("");
+  lines.push(c.dim(`Project: ${options.rootDir}`));
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Numbered next steps after scaffold (and after login when init ran it).
+ * Includes `cd` when init did not already run inside the project.
+ */
+export function formatInitNextSteps(options: InitNextStepsOptions): string {
+  const c = initPalette(options.color);
+  const lines: string[] = [];
+  lines.push("Next steps:");
+  lines.push("");
+
+  const steps = initNextStepEntries(options);
+  const width = Math.max(...steps.map(step => step.command.length));
+  for (const [index, step] of steps.entries()) {
+    const command =
+      step.note === undefined
+        ? step.command
+        : `${step.command.padEnd(width)}   ${c.dim(`# ${step.note}`)}`;
+    lines.push(`  ${index + 1}. ${command}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Full human-readable scaffold summary (scaffold + next steps).
+ */
+export function formatInitSummary(options: InitSummaryOptions): string {
+  return formatInitScaffoldSummary(options) + formatInitNextSteps(options);
+}
+
+/**
+ * `cd` into the scaffold when init did not already run inside it. Relative
+ * when the target sits under the invoking directory, absolute otherwise.
+ */
+export function formatCdCommand(cwd: string, rootDir: string): string | undefined {
+  const rel = relative(cwd, rootDir);
+  if (rel === "") {
+    return undefined;
+  }
+  const path = rel.startsWith("..") ? rootDir : rel;
+  const quoted = /\s/.test(path) ? JSON.stringify(path) : path;
+  return `cd ${quoted}`;
+}
+
+function initNextStepEntries(options: InitNextStepsOptions): Array<{
+  command: string;
+  note?: string;
+}> {
+  const steps: Array<{ command: string; note?: string }> = [];
+  const cd = formatCdCommand(options.cwd, options.rootDir);
+  if (cd !== undefined) {
+    steps.push({ command: cd });
+  }
+  if (!options.signedIn) {
+    const login = options.cliOnPath ? `${CLI_COMMAND_NAME} login` : `npx ${PACKAGE_NAME} login`;
+    steps.push({
+      command: login,
+      note: "connect your Cursor account (powers model turns)",
+    });
+  }
+  const dev = options.cliOnPath ? `${CLI_COMMAND_NAME} dev` : `npx ${PACKAGE_NAME} dev`;
+  steps.push({
+    command: dev,
+    note: "start the local playground",
+  });
+  return steps;
+}
+
+/**
+ * Next-step commands for the `--json` scaffold summary (login omitted when
+ * the host already has a Cursor credential).
+ */
+export function initNextCommands(options: {
+  rootDir: string;
+  cwd: string;
+  signedIn: boolean;
+  cliOnPath: boolean;
+}): string[] {
+  return initNextStepEntries(options).map(step => step.command);
+}
+
+/**
+ * Coding-agent setup guide printed by `bdk init`
+ * with no target directory (does not scaffold).
+ */
+export function printInitGuide(): void {
+  process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
+
+Scaffold a project, then open the playground:
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links bdk onto PATH
+  npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
+  npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
+  npx ${PACKAGE_NAME} init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
+  npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
+  npx ${PACKAGE_NAME} init ./thermo-review --template thermo-review       # review PRs for bugs and breakage
+  npx ${PACKAGE_NAME} init ./thermo-quality --template thermo-quality-review # review PRs for code quality
+  npx ${PACKAGE_NAME} init ./security-help --template security-help   # answer security questions in Slack
+  npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues
+  npx ${PACKAGE_NAME} init ./my-triage --template triage-jira     # comment on Jira issues
+  npx ${PACKAGE_NAME} init ./my-owners --template agentic-owners  # review PRs via owners policies
+  # TTY asks the template's questions. Scripts pass --var:
+  #   --var repos=acme/widgets,acme/api
+  #   --var agents="Plan Keeper, Chief of Staff"
+  cd ./my-agent && ${CLI_COMMAND_NAME} dev        # or: npx ${PACKAGE_NAME} dev
+
+Recommended loop once the project exists (from the project directory):
+  1. Edit bot/ + tools under bot/tools/
+  2. ${CLI_COMMAND_NAME} info --dir . --json
+  3. ${CLI_COMMAND_NAME} run --dir . --message "..."
+  4. ${CLI_COMMAND_NAME} eval --dir .
+
+Evals:
+  Create evals/**/*.eval.ts using defineEval from ${PACKAGE_NAME}/evals
+  Case id is the path: evals/weather/nyc.eval.ts → weather/nyc
+  Required: evals/evals.config.ts with defineEvalConfig({ maxConcurrency })
+    (hard-capped at 200 due to model provider request limits)
+  Run: ${CLI_COMMAND_NAME} eval [--json] [evalId...]
+    (pass --prod to run against the hosted deployment)
+
+The scaffold writes AGENTS.md (coding-agent loop for this project).
+See AGENTS.md in the ${PACKAGE_NAME} package for the framework loop.
+`);
+}