doctrina-cli 0.1.0 → 0.2.0

package/src/commands/decision.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, read, write } from "../lib/fs-ops.js";
+import { exists, read, relPath, write } from "../lib/fs-ops.js";
 import { walk } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
@@ -8,7 +8,7 @@ import { today, slugify, padNumber } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "supersede"];
+const SUBCOMMANDS = ["new", "supersede", "accept", "list"];
 
 export async function run(positional, _flags) {
   const sub = positional[0];
@@ -17,6 +17,10 @@ export async function run(positional, _flags) {
       return decisionNew(positional.slice(1));
     case "supersede":
       return decisionSupersede(positional.slice(1));
+    case "accept":
+      return decisionAccept(positional.slice(1));
+    case "list":
+      return decisionList();
     default:
       console.error(c.red("error:") + ` unknown decision subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -42,7 +46,7 @@ function decisionNew(args) {
   const filename = `${next}-${slug}.md`;
   const targetPath = path.join(projectRoot, ".doctrina", "decisions", filename);
   if (exists(targetPath)) {
-    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists`);
+    console.error(c.red("error:") + ` ${relPath(projectRoot, targetPath)} already exists`);
     return 1;
   }
 
@@ -55,7 +59,7 @@ function decisionNew(args) {
     DATE: date,
   });
   write(targetPath, body, { force: false });
-  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}`);
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}`);
 
   const index = idx.load(projectRoot);
   idx.addDecision(index, {
@@ -85,13 +89,13 @@ function decisionSupersede(args) {
   const files = walk(adrDir);
   const oldFile = files.find((f) => path.basename(f).startsWith(`${padded}-`));
   if (!oldFile) {
-    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${path.relative(projectRoot, adrDir)}`);
+    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${relPath(projectRoot, adrDir)}`);
     return 1;
   }
   const oldText = read(oldFile);
   const oldStatusMatch = oldText.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
   if (!oldStatusMatch) {
-    console.error(c.red("error:") + ` ADR at ${path.relative(projectRoot, oldFile)} has no Status: header`);
+    console.error(c.red("error:") + ` ADR at ${relPath(projectRoot, oldFile)} has no Status: header`);
     return 1;
   }
   const oldStatus = oldStatusMatch[1].trim();
@@ -124,14 +128,14 @@ function decisionSupersede(args) {
   // Inject Supersedes link
   body = body.replace(/(\*\*Supersedes:\*\*)\s+—/, `$1 ${padded}`);
   write(newPath, body, { force: false });
-  console.log(c.green("created") + ` ${path.relative(projectRoot, newPath)}`);
+  console.log(c.green("created") + ` ${relPath(projectRoot, newPath)}`);
 
   // Mutate ONLY the Status: and Superseded by: headers of the old ADR
   const updated = oldText
     .replace(/^(-\s+\*\*Status:\*\*)\s+.+$/m, `$1 superseded by ${next}`)
     .replace(/^(-\s+\*\*Superseded by:\*\*)\s+.+$/m, `$1 ${next}`);
   write(oldFile, updated, { force: true });
-  console.log(c.green("updated") + ` ${path.relative(projectRoot, oldFile)} status -> superseded by ${next}`);
+  console.log(c.green("updated") + ` ${relPath(projectRoot, oldFile)} status -> superseded by ${next}`);
 
   // Update index
   const index = idx.load(projectRoot);
@@ -153,6 +157,81 @@ function decisionSupersede(args) {
   return 0;
 }
 
+function decisionAccept(args) {
+  const target = args[0];
+  if (!target) {
+    console.error(c.red("error:") + " decision accept requires the target ADR number (e.g. 0003)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const padded = padNumber(parseInt(target, 10));
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = walk(adrDir).find((f) => path.basename(f).startsWith(`${padded}-`));
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${relPath(projectRoot, adrDir)}`);
+    return 1;
+  }
+  const text = read(file);
+  const statusMatch = text.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
+  if (!statusMatch) {
+    console.error(c.red("error:") + ` ADR at ${relPath(projectRoot, file)} has no Status: header`);
+    return 1;
+  }
+  const status = statusMatch[1].trim().toLowerCase();
+  if (status !== "proposed") {
+    console.error(c.red("error:") + ` ADR ${padded} is "${statusMatch[1].trim()}", not "proposed" — nothing to accept`);
+    return 1;
+  }
+
+  // Mutate ONLY the Status: header; the body stays immutable.
+  write(file, text.replace(/^(-\s+\*\*Status:\*\*)\s+.+$/m, "$1 accepted"), { force: true });
+  console.log(c.green("accepted") + ` ${relPath(projectRoot, file)}`);
+
+  const date = today();
+  const index = idx.load(projectRoot);
+  idx.updateDecision(index, padded, () => ({ status: "accepted" }));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` decision ${padded} -> accepted`);
+  return 0;
+}
+
+function decisionList() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const rows = [];
+  for (const f of walk(adrDir)) {
+    const m = path.basename(f).match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f);
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    const statusMatch = text.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
+    const dateMatch = text.match(/^-\s+\*\*Date:\*\*\s+(\S+)/m);
+    rows.push({
+      id: m[1],
+      status: statusMatch ? statusMatch[1].trim() : "?",
+      date: dateMatch ? dateMatch[1] : "—",
+      title: titleMatch ? titleMatch[1].trim() : path.basename(f),
+    });
+  }
+  if (rows.length === 0) {
+    console.log(c.gray("no ADRs found in .doctrina/decisions/"));
+    return 0;
+  }
+  console.log(c.bold("Decisions:"));
+  console.log("");
+  for (const r of rows) {
+    console.log(`  ${c.cyan(r.id)}  ${r.status.padEnd(20)} ${r.date}  ${r.title}`);
+  }
+  console.log("");
+  console.log(c.gray(`${rows.length} ADR${rows.length === 1 ? "" : "s"}`));
+  return 0;
+}
+
 function nextDecisionNumber(projectRoot) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
   const files = walk(adrDir);
@@ -178,6 +257,10 @@ Usage: doctrina decision <subcommand> [args]
 
 Subcommands:
   new "<title>"                        Create the next sequentially numbered ADR
+  accept <number>                      Flip a proposed ADR to accepted (rewrites
+                                       only the Status: header) and update the index
   supersede <number> "<new title>"     Create a new ADR that supersedes the target
                                        and rewrite the target's Status: header
+  list                                 One line per ADR: number, status, date,
+                                       title. Read-only.
 `;

package/src/commands/hooks.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import process from "node:process";
 import { chmodSync } from "node:fs";
-import { exists, mkdirp, read, write } from "../lib/fs-ops.js";
+import { exists, mkdirp, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir } from "../lib/templates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -33,7 +33,7 @@ export async function run(positional, flags) {
 
   const target = path.join(hooksDir, "pre-commit");
   if (exists(target) && !force) {
-    console.error(c.red("error:") + ` ${path.relative(projectRoot, target)} already exists (pass --force to overwrite)`);
+    console.error(c.red("error:") + ` ${relPath(projectRoot, target)} already exists (pass --force to overwrite)`);
     return 1;
   }
 
@@ -42,7 +42,7 @@ export async function run(positional, flags) {
   const body = read(tplPath);
   write(target, body, { force: true });
   chmodSync(target, 0o755);
-  console.log(c.green("installed") + ` ${path.relative(projectRoot, target)}`);
+  console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);
   console.log(`The hook runs ${c.cyan("doctrina validate")} before each commit.`);
   return 0;
 }

package/src/commands/index-rebuild.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["rebuild"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  if (sub !== "rebuild") {
+    console.error(c.red("error:") + ` unknown index subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina index ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  return rebuild(flags);
+}
+
+function rebuild(flags) {
+  const check = flagBool(flags, "check", false);
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  let current = null;
+  try {
+    current = idx.load(projectRoot);
+  } catch (err) {
+    if (check) {
+      console.error(c.red("error:") + ` ${err.message}`);
+      return 1;
+    }
+    console.log(c.yellow("warn:") + ` ${err.message} — rebuilding from scratch`);
+  }
+
+  const derived = deriveIndex(projectRoot, current);
+
+  if (indexesMatch(derived, current)) {
+    console.log(c.green("ok") + " index.json matches the tree (nothing to do)");
+    return 0;
+  }
+
+  const drift = describeDrift(current, derived);
+  for (const line of drift) console.log((check ? c.yellow("drift: ") : c.gray("sync:  ")) + line);
+
+  if (check) {
+    console.log("");
+    console.log(c.red("fail") + ` index.json has drifted from the tree (${drift.length} difference${drift.length === 1 ? "" : "s"})`);
+    console.log(c.gray("hint: ") + "run `doctrina index rebuild` to regenerate it");
+    return 1;
+  }
+
+  derived.last_updated = today();
+  idx.save(projectRoot, derived);
+  const a = derived.artifacts;
+  console.log("");
+  console.log(c.green("rebuilt") + ` .doctrina/index.json — ${a.specs.length} specs, ${a.decisions.length} decisions, ` +
+    `${a.changes.length} open changes, ${a.changes_archive.length} archived, ${a.skills.length} skills`);
+  return 0;
+}
+
+// Human-readable category-level drift between the on-disk index and the
+// derived one: added / removed / changed entry ids.
+function describeDrift(current, derived) {
+  const lines = [];
+  if (!current) return ["index.json missing or unreadable"];
+  const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
+  for (const cat of categories) {
+    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    for (const id of der.keys()) {
+      if (!cur.has(id)) lines.push(`${cat}: "${id}" on disk but not in index`);
+      else if (stableStringify(cur.get(id)) !== stableStringify(der.get(id))) {
+        lines.push(`${cat}: "${id}" metadata differs from the files`);
+      }
+    }
+    for (const id of cur.keys()) {
+      if (!der.has(id)) lines.push(`${cat}: "${id}" in index but not on disk`);
+    }
+  }
+  if (stableStringify(current.artifacts?.product ?? null) !== stableStringify(derived.artifacts.product)) {
+    lines.push("product: metadata differs");
+  }
+  if (lines.length === 0) lines.push("structural difference (key order or missing category)");
+  return lines;
+}
+
+export const help = `
+Usage: doctrina index <subcommand>
+
+Subcommands:
+  rebuild           Regenerate .doctrina/index.json from the artifacts on
+                    disk (spec headers, ADR headers, change proposals,
+                    archive folders, skill frontmatter). The files are the
+                    source of truth; the index is derived.
+  rebuild --check   Write nothing; exit 1 with a drift summary when the
+                    index no longer matches the tree. CI-friendly.
+
+Fields with no on-disk source (project name, framework_version, product
+metadata) are carried over from the existing index.
+`;

package/src/commands/init.js

@@ -1,11 +1,12 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, read, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { ask } from "../lib/prompt.js";
+import { writeIntakeFile, printBootstrapPlaybook } from "./intake.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -29,7 +30,27 @@ export async function run(_positional, flags) {
   const projectName = flagString(flags, "project-name") ?? path.basename(projectRoot);
   const date = flagString(flags, "date") ?? today();
 
+  // --intake hands over the FULL description up front (ADR 0005); the
+  // one-line summary is then derived instead of prompted for.
+  const intakeFile = flagString(flags, "intake");
+  let intakeBody = null;
+  if (intakeFile) {
+    const intakeAbs = path.resolve(projectRoot, intakeFile);
+    if (!isFile(intakeAbs)) {
+      console.error(c.red("error:") + ` --intake file not found: ${intakeFile}`);
+      return 1;
+    }
+    intakeBody = read(intakeAbs);
+    if (intakeBody.trim().length === 0) {
+      console.error(c.red("error:") + ` --intake file is empty: ${intakeFile}`);
+      return 1;
+    }
+  }
+
   let description = flagString(flags, "project-description") ?? "";
+  if (!description && intakeBody) {
+    description = firstLineSummary(intakeBody);
+  }
   if (!description && !nonInteractive) {
     description = await ask("One-sentence project description:");
   }
@@ -79,7 +100,7 @@ export async function run(_positional, flags) {
     ? fromAgentsContent.replace(/\n+$/, "") + "\n\n---\n\n## Project-specific\n\n" + projectAgents
     : projectAgents;
   write(agentsMdPath, finalAgents, { force });
-  console.log(c.green("created") + ` ${path.relative(projectRoot, agentsMdPath)}` + (fromAgentsContent ? " (with --from base)" : ""));
+  console.log(c.green("created") + ` ${relPath(projectRoot, agentsMdPath)}` + (fromAgentsContent ? " (with --from base)" : ""));
   const finalLines = finalAgents.split("\n").length;
   if (finalLines > 150) {
     console.log(c.yellow("warn:") + ` AGENTS.md is ${finalLines} lines (>150 soft cap); consider trimming the base`);
@@ -96,11 +117,11 @@ export async function run(_positional, flags) {
       const merged = `# ${projectName} — Product\n\n## Conventions base (from ${fromPath})\n\n${visionBlock}\n\n---\n\n${projectBody.replace(/^#[^\n]*\n+/, "")}`;
       const dest = path.join(doctrinaDir, "product.md");
       write(dest, merged, { force });
-      console.log(c.green("created") + ` ${path.relative(projectRoot, dest)} (with --from base)`);
+      console.log(c.green("created") + ` ${relPath(projectRoot, dest)} (with --from base)`);
       continue;
     }
     const written = materialiseEntry(entry, doctrinaDir, tokens, { force });
-    console.log(c.green("created") + ` ${path.relative(projectRoot, written)}`);
+    console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
   }
 
   // Adapters
@@ -115,12 +136,39 @@ export async function run(_positional, flags) {
     }
   }
 
+  if (intakeBody) {
+    const intakePath = writeIntakeFile(projectRoot, {
+      body: intakeBody,
+      source: relPath(projectRoot, path.resolve(projectRoot, intakeFile)),
+      projectName,
+      date,
+      force,
+    });
+    console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
+  }
+
   console.log("");
   console.log(c.bold("Doctrina initialised."));
-  console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+  if (intakeBody) {
+    console.log(`Next: execute the bootstrap playbook below — it converts the intake into`);
+    console.log(`${c.cyan(".doctrina/product.md")} and capability specs. Any AGENTS.md-aware agent`);
+    console.log(`runs it on its own; reprint anytime with ${c.cyan("doctrina intake")}.`);
+    console.log("");
+    printBootstrapPlaybook(projectRoot);
+  } else {
+    console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+  }
   return 0;
 }
 
+// First non-empty line of the intake, stripped of Markdown heading marks
+// and clipped, as the one-line description token for the templates.
+function firstLineSummary(text) {
+  const line = text.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
+  const cleaned = line.replace(/^#+\s*/, "").trim();
+  return cleaned.length > 120 ? cleaned.slice(0, 117).trimEnd() + "..." : cleaned;
+}
+
 function installAdapter(templatesDir, projectRoot, agent, tokens, opts) {
   const tree = loadTemplateTree(templatesDir, path.join("adapters", agent));
   for (const entry of tree) {
@@ -130,13 +178,13 @@ function installAdapter(templatesDir, projectRoot, agent, tokens, opts) {
       AGENTS_MD_PATH: adapterAgentsMdRelativePath(entry.relativePath),
     };
     const written = materialiseEntry(entry, projectRoot, adapterTokens, opts);
-    console.log(c.green(`adapter[${agent}]`) + ` ${path.relative(projectRoot, written)}`);
+    console.log(c.green(`adapter[${agent}]`) + ` ${relPath(projectRoot, written)}`);
   }
 }
 
 function adapterAgentsMdRelativePath(relativePath) {
   const cleaned = relativePath.replace(/\.template$/, "");
-  const depth = cleaned.split(path.sep).length - 1;
+  const depth = cleaned.split("/").length - 1;
   return depth === 0 ? "AGENTS.md" : "../".repeat(depth) + "AGENTS.md";
 }
 
@@ -150,6 +198,9 @@ Options:
   --project-description <text>   One-sentence description
   --agent <name>                 Install adapter for one agent
                                  (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|all)
+  --intake <file>                Full project description; stored verbatim at .doctrina/intake.md
+                                 and used to derive the one-line description when absent.
+                                 Follow up with \`doctrina intake\` for the bootstrap playbook
   --from <path>                  Local conventions directory; if it contains AGENTS.md and/or
                                  .doctrina/product.md, the content is folded into the new project
   --date <YYYY-MM-DD>            Override the system date

package/src/commands/intake.js

@@ -0,0 +1,166 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { listHeader } from "../lib/scan.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// `intake` is the first half of the no-ceremony path (ADR 0005): store the
+// user's FULL project description verbatim, then print the bootstrap
+// playbook the host agent executes to convert it into product.md content
+// and capability specs. The CLI does no interpretation — it scaffolds and
+// instructs; the agent thinks.
+
+export async function run(positional, flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const force = flagBool(flags, "force", false);
+  const inlineText = flagString(flags, "text");
+  const sourceFile = positional[0];
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+
+  // No source given: reprint the playbook for an existing intake.
+  if (!sourceFile && !inlineText) {
+    if (!isFile(intakePath)) {
+      console.error(c.red("error:") + " no intake found and no description given");
+      console.error(c.gray("hint: ") + "run `doctrina intake <file>` or `doctrina intake --text \"<description>\"`");
+      return 1;
+    }
+    const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
+    if (status === "converted") {
+      console.log(c.green("ok") + " intake already converted — specs are the source of truth.");
+      console.log(c.gray("hint: ") + "start implementation with `doctrina work \"<brief prompt>\"`");
+      return 0;
+    }
+    printBootstrapPlaybook(projectRoot);
+    return 0;
+  }
+
+  let body;
+  let source;
+  if (inlineText) {
+    body = inlineText;
+    source = "inline (--text)";
+  } else {
+    const abs = path.resolve(projectRoot, sourceFile);
+    if (!isFile(abs)) {
+      console.error(c.red("error:") + ` description file not found: ${sourceFile}`);
+      return 1;
+    }
+    body = read(abs);
+    source = relPath(projectRoot, abs);
+  }
+  if (body.trim().length === 0) {
+    console.error(c.red("error:") + " the description is empty");
+    return 1;
+  }
+
+  if (exists(intakePath) && !force) {
+    console.error(c.red("error:") + ` ${relPath(projectRoot, intakePath)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const projectName = idx.load(projectRoot).project ?? path.basename(projectRoot);
+  writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
+  console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
+  console.log("");
+  printBootstrapPlaybook(projectRoot);
+  return 0;
+}
+
+// Shared with `init --intake`. Writes the intake verbatim under a small
+// status header; the agent flips Status to converted at the end of the
+// playbook, which is how `next` knows the bootstrap is done.
+export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  const content = [
+    `# Intake — ${projectName}`,
+    "",
+    "- **Status:** pending",
+    `- **Date:** ${date}`,
+    `- **Source:** ${source}`,
+    "",
+    "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
+    "     (doctrina intake) converts it into product.md and capability",
+    "     specs, then flips Status to converted. After conversion the",
+    "     specs are the only source of truth; never edit this file to",
+    "     change requirements. -->",
+    "",
+    "---",
+    "",
+    body.replace(/\r\n/g, "\n").replace(/\n*$/, "\n"),
+  ].join("\n");
+  write(intakePath, content, { force });
+  return intakePath;
+}
+
+// Exported so `init --intake` can print the same playbook inline instead
+// of bouncing the user to a second command.
+export function printBootstrapPlaybook(projectRoot) {
+  const hasSpecs = exists(path.join(projectRoot, ".doctrina", "specs"));
+  console.log(c.bold("Bootstrap playbook") + c.gray(" — agent-executed (ADR 0005); the CLI does no interpretation."));
+  console.log("");
+  console.log("Execute in order, in a single linear pass:");
+  console.log("");
+  console.log(`1. Read ${c.cyan(".doctrina/intake.md")} (raw intent) and ${c.cyan(".doctrina/product.md")}.`);
+  console.log("");
+  console.log("2. Fill every product.md section from the intake: Vision, Problem,");
+  console.log("   Target users, Scope (in/out), Non-goals, Success criteria.");
+  console.log("   One fact, one home — product.md holds vision, never requirements.");
+  console.log("");
+  console.log("3. Derive the capability list: kebab-case, one per area of behaviour");
+  console.log("   (e.g. auth, billing, reports). For each capability:");
+  console.log(`       ${c.cyan("doctrina spec new <capability>")}`);
+  console.log("   then replace the template placeholders in");
+  console.log("   .doctrina/specs/<capability>/spec.md with EARS requirements derived");
+  console.log("   from the intake (Ubiquitous / Event-driven / State-driven /");
+  console.log("   Unwanted-behavior / Optional). Remove section stubs you do not use,");
+  console.log("   and write concrete Acceptance criteria.");
+  console.log("");
+  console.log("4. Record any architectural decision the intake forces:");
+  console.log(`       ${c.cyan("doctrina decision new \"<title>\"")} → edit → ${c.cyan("doctrina decision accept <num>")}`);
+  console.log("");
+  console.log("5. Quality gates — fix everything they report before moving on:");
+  console.log(`       ${c.cyan("doctrina clarify --all")}`);
+  console.log(`       ${c.cyan("doctrina validate")}`);
+  console.log("   If something in the intake is genuinely ambiguous, ask the user");
+  console.log("   before assuming.");
+  console.log("");
+  console.log("6. Mark the intake consumed: in .doctrina/intake.md flip");
+  console.log("   \"- **Status:** pending\" to \"- **Status:** converted\".");
+  console.log("");
+  console.log(`7. ${c.cyan("doctrina next")} — follow the recommendation. Implementation then`);
+  console.log(`   flows through ${c.cyan("doctrina work \"<brief prompt>\"")}, one change at a time.`);
+  if (!hasSpecs) {
+    console.log("");
+    console.log(c.yellow("warn:") + " .doctrina/specs/ is missing — re-run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina intake [<file>] [--text "<description>"] [--force]
+
+Store the full project description verbatim at .doctrina/intake.md and
+print the bootstrap playbook — the ordered instruction sequence the host
+AI agent executes to convert the intake into product.md content and
+capability specs (see ADR 0005). The CLI itself does no natural-language
+interpretation.
+
+Forms:
+  doctrina intake <file>              Ingest a description file
+  doctrina intake --text "<text>"     Ingest an inline description
+  doctrina intake                     Reprint the playbook for the
+                                      existing pending intake
+
+Options:
+  --text "<description>"   Inline description instead of a file
+  --force                  Overwrite an existing .doctrina/intake.md
+
+After conversion the agent flips the intake header to
+"- **Status:** converted"; specs become the only source of truth.
+`;