codebyplan 1.13.36 → 1.13.38

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.36";
+    VERSION = "1.13.38";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -698,7 +698,7 @@ function isRetryable(err) {
   return false;
 }
 function delay(ms) {
-  return new Promise((resolve11) => setTimeout(resolve11, ms));
+  return new Promise((resolve12) => setTimeout(resolve12, ms));
 }
 async function request(method, path10, options) {
   const url = buildUrl(path10, options?.params);
@@ -1056,7 +1056,7 @@ var init_device_flow = __esm({
         this.name = "OAuthInvalidClientError";
       }
     };
-    defaultSleep = (ms) => new Promise((resolve11) => setTimeout(resolve11, ms));
+    defaultSleep = (ms) => new Promise((resolve12) => setTimeout(resolve12, ms));
   }
 });
 
@@ -4670,7 +4670,7 @@ function setRetryDelayMs(ms) {
   RETRY_DELAY_MS = ms;
 }
 function sleep(ms) {
-  return new Promise((resolve11) => setTimeout(resolve11, ms));
+  return new Promise((resolve12) => setTimeout(resolve12, ms));
 }
 function isTransientMcpError(err) {
   if (!(err instanceof McpError)) return false;
@@ -8616,11 +8616,11 @@ async function ask(q, opts) {
   try {
     while (true) {
       const choices = q.choices.map((c) => `[${c.key}] ${c.label}`).join("  ");
-      const answer = await new Promise((resolve11) => {
+      const answer = await new Promise((resolve12) => {
         rl.question(`${q.message}
   ${choices}
 > `, (input) => {
-          resolve11(input.trim().toLowerCase());
+          resolve12(input.trim().toLowerCase());
         });
       });
       const match = q.choices.find(
@@ -9326,6 +9326,293 @@ var init_structure_generator = __esm({
   }
 });
 
+// src/lib/readme-generator.ts
+function managedStartMarker(section) {
+  return `${MANAGED_START_PREFIX}${section}${MANAGED_MARKER_SUFFIX}`;
+}
+function managedEndMarker(section) {
+  return `${MANAGED_END_PREFIX}${section}${MANAGED_MARKER_SUFFIX}`;
+}
+function hasManagedMarkers(content) {
+  return content.includes(MANAGED_START_PREFIX) || content.includes(MANAGED_END_PREFIX);
+}
+function validateManagedMarkers(content) {
+  const errors = [];
+  const startRe = /<!-- codebyplan:managed:start:([a-z0-9][a-z0-9-]*) -->/g;
+  const endRe = /<!-- codebyplan:managed:end:([a-z0-9][a-z0-9-]*) -->/g;
+  const starts = [...content.matchAll(startRe)].map((m) => m[1]);
+  const ends = [...content.matchAll(endRe)].map((m) => m[1]);
+  const seenStarts = /* @__PURE__ */ new Set();
+  for (const s of starts) {
+    if (seenStarts.has(s)) {
+      errors.push(`duplicate managed section '${s}'`);
+    }
+    seenStarts.add(s);
+    if (!ends.includes(s)) {
+      errors.push(`missing end marker for section '${s}'`);
+    }
+  }
+  for (const e of ends) {
+    if (!starts.includes(e)) {
+      errors.push(`end marker without start marker for section '${e}'`);
+    }
+  }
+  return errors;
+}
+function renderTechStackSection(techStack) {
+  const entries = Object.entries(techStack).filter(([, value]) => value.trim().length > 0).sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) return "";
+  const lines = entries.map(([cat, names]) => `- **${cat}**: ${names}`);
+  return `## Tech Stack
+
+${lines.join("\n")}
+`;
+}
+function renderStructureSection(packages) {
+  if (packages.length === 0) return "";
+  const sorted = [...packages].sort((a, b) => a.path.localeCompare(b.path));
+  const rows = sorted.map(
+    (p) => `| \`${p.path}\` | \`${p.name}\` | ${p.purpose ?? ""} |`
+  );
+  return `## Structure
+
+| Location | Package | Purpose |
+|----------|---------|----------|
+` + rows.join("\n") + "\n";
+}
+function renderScriptsSection(scripts, installCommand) {
+  const sortedEntries = Object.entries(scripts).filter(([, cmd]) => typeof cmd === "string" && cmd.trim().length > 0).sort(([a], [b]) => a.localeCompare(b));
+  const lines = [];
+  lines.push(`\`\`\`bash`);
+  lines.push(`# Install`);
+  lines.push(installCommand);
+  lines.push(``);
+  if (sortedEntries.length > 0) {
+    lines.push(`# Available scripts`);
+    for (const [name, cmd] of sortedEntries) {
+      lines.push(`# ${name}`);
+      lines.push(cmd);
+    }
+  }
+  lines.push(`\`\`\``);
+  return `## Scripts
+
+${lines.join("\n")}
+`;
+}
+function buildManagedSections(config) {
+  const sections = {};
+  if (config.techStack && Object.keys(config.techStack).length > 0) {
+    const rendered = renderTechStackSection(config.techStack);
+    if (rendered) {
+      sections["tech-stack"] = rendered;
+    }
+  }
+  if (config.packages && config.packages.length > 0) {
+    const rendered = renderStructureSection(config.packages);
+    if (rendered) {
+      sections["structure"] = rendered;
+    }
+  }
+  if (config.scripts && Object.keys(config.scripts).length > 0) {
+    const pm = config.packageManager ?? "pnpm";
+    const pmBase = pm.split("@")[0] ?? "pnpm";
+    const installCmd = config.installCommand ?? `${pmBase} install`;
+    const rendered = renderScriptsSection(config.scripts, installCmd);
+    if (rendered) {
+      sections["scripts"] = rendered;
+    }
+  }
+  return sections;
+}
+function hashManagedContent(sections) {
+  const sortedKeys = Object.keys(sections).sort();
+  const payload = {};
+  for (const k of sortedKeys) {
+    payload[k] = sections[k];
+  }
+  return sha256(JSON.stringify(payload));
+}
+function scaffoldReadme(config) {
+  const title = config.name ?? "Project";
+  const description = config.description ?? "";
+  const sections = buildManagedSections(config);
+  const hash = hashManagedContent(sections);
+  const lines = [];
+  lines.push(`# ${title}`);
+  lines.push(``);
+  if (description) {
+    lines.push(description);
+    lines.push(``);
+  }
+  const sectionKeys = Object.keys(sections).sort();
+  for (const key of sectionKeys) {
+    lines.push(managedStartMarker(key));
+    lines.push(sections[key].trimEnd());
+    lines.push(managedEndMarker(key));
+    lines.push(``);
+  }
+  lines.push(`${HASH_MARKER_PREFIX}${hash}${MANAGED_MARKER_SUFFIX}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function refreshManagedSections(existing, sections) {
+  let content = existing;
+  const startPattern = new RegExp(
+    `${escapeRegex(MANAGED_START_PREFIX)}([a-z0-9][a-z0-9-]*)${escapeRegex(MANAGED_MARKER_SUFFIX)}[\\s\\S]*?${escapeRegex(MANAGED_END_PREFIX)}\\1${escapeRegex(MANAGED_MARKER_SUFFIX)}`,
+    "g"
+  );
+  const seen = /* @__PURE__ */ new Set();
+  content = content.replace(startPattern, (_, sectionName) => {
+    const key = sectionName.trim();
+    seen.add(key);
+    if (Object.prototype.hasOwnProperty.call(sections, key)) {
+      const newBody = sections[key].trimEnd();
+      return managedStartMarker(key) + "\n" + newBody + "\n" + managedEndMarker(key);
+    } else {
+      return "";
+    }
+  });
+  content = content.replace(/\n{3,}/g, "\n\n");
+  const newSectionKeys = Object.keys(sections).sort().filter((k) => !seen.has(k));
+  if (newSectionKeys.length > 0) {
+    const hashCommentPattern = new RegExp(
+      `
+${escapeRegex(HASH_MARKER_PREFIX)}[^
+]*${escapeRegex(MANAGED_MARKER_SUFFIX)}(
+|$)`
+    );
+    content = content.replace(hashCommentPattern, "\n");
+    if (!content.endsWith("\n")) content += "\n";
+    for (const key of newSectionKeys) {
+      content += "\n" + managedStartMarker(key) + "\n" + sections[key].trimEnd() + "\n" + managedEndMarker(key) + "\n";
+    }
+  }
+  const newHash = hashManagedContent(sections);
+  const hashLine = `${HASH_MARKER_PREFIX}${newHash}${MANAGED_MARKER_SUFFIX}`;
+  const existingHashPattern = new RegExp(
+    `${escapeRegex(HASH_MARKER_PREFIX)}[^
+]*${escapeRegex(MANAGED_MARKER_SUFFIX)}`
+  );
+  if (existingHashPattern.test(content)) {
+    content = content.replace(existingHashPattern, hashLine);
+  } else {
+    if (!content.endsWith("\n")) content += "\n";
+    content += `${hashLine}
+`;
+  }
+  content = content.trimEnd() + "\n";
+  return content;
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractManagedHash(content) {
+  const hashPattern = new RegExp(
+    `${escapeRegex(HASH_MARKER_PREFIX)}(sha256:[0-9a-f]{64})${escapeRegex(MANAGED_MARKER_SUFFIX)}`
+  );
+  const m = hashPattern.exec(content);
+  return m?.[1] ?? null;
+}
+var MANAGED_START_PREFIX, MANAGED_END_PREFIX, MANAGED_MARKER_SUFFIX, HASH_MARKER_PREFIX;
+var init_readme_generator = __esm({
+  "src/lib/readme-generator.ts"() {
+    "use strict";
+    init_hash();
+    MANAGED_START_PREFIX = "<!-- codebyplan:managed:start:";
+    MANAGED_END_PREFIX = "<!-- codebyplan:managed:end:";
+    MANAGED_MARKER_SUFFIX = " -->";
+    HASH_MARKER_PREFIX = "<!-- codebyplan:hash:";
+  }
+});
+
+// src/lib/agents-generator.ts
+function stripStructureSentinels(structureContent) {
+  const lines = structureContent.split("\n");
+  const filtered = lines.filter((line) => {
+    const trimmed = line.trim();
+    return !trimmed.startsWith("<!-- @codebyplan-generated:");
+  });
+  let result = filtered.join("\n");
+  result = result.replace(/^\n+/, "").replace(/\n+$/, "");
+  return result;
+}
+function buildCuratedGuidance(cleanStructureContent) {
+  const lines = [];
+  lines.push(`## Project Context`);
+  lines.push(``);
+  lines.push(
+    `This file is auto-generated for cross-tool compatibility. The canonical source of truth for project instructions is \`.claude/CLAUDE.md\`. If your tool supports Claude Code's \`@\` import syntax, read \`.claude/CLAUDE.md\` directly.`
+  );
+  lines.push(``);
+  if (cleanStructureContent.trim().length > 0) {
+    lines.push(cleanStructureContent.trim());
+  } else {
+    lines.push(
+      `_Structure not yet generated. Run \`codebyplan claude generate\` to populate._`
+    );
+  }
+  lines.push(``);
+  lines.push(`## Source of Truth`);
+  lines.push(``);
+  lines.push(
+    `The database is the sole source of truth for all development data. No local markdown files for tracking \u2014 everything is in the DB, accessed via MCP tools or the Web UI.`
+  );
+  lines.push(``);
+  lines.push(`## \`.claude/\` Layout`);
+  lines.push(``);
+  lines.push(`| Directory | Purpose |`);
+  lines.push(`|-----------|---------|`);
+  lines.push(`| \`rules/\` | Auto-loaded behavioral constraints |`);
+  lines.push(`| \`skills/\` | User-invocable \`/cbp-*\` commands |`);
+  lines.push(`| \`agents/\` | Spawned sub-agents |`);
+  lines.push(`| \`context/\` | Agent/skill input data |`);
+  lines.push(
+    `| \`CLAUDE.md\` | Canonical project context (always loaded by Claude Code) |`
+  );
+  lines.push(``);
+  lines.push(`## Port Rule`);
+  lines.push(``);
+  lines.push(
+    `Never hardcode port numbers. Resolve from \`.codebyplan/server.json\` \`port_allocations[]\`. Each entry carries \`port\`, \`label\`, and \`server_type\`.`
+  );
+  lines.push(``);
+  lines.push(`## Git`);
+  lines.push(``);
+  lines.push(
+    `Do not include any mention of AI tools or code-assistant products in git commit messages.`
+  );
+  lines.push(``);
+  return lines.join("\n");
+}
+function generateAgentsMd(structureContent) {
+  const cleanStructure = stripStructureSentinels(structureContent);
+  const bodyContent = buildCuratedGuidance(cleanStructure);
+  const managedBody = [
+    managedStartMarker(AGENTS_SECTION_NAME),
+    bodyContent.trimEnd(),
+    managedEndMarker(AGENTS_SECTION_NAME)
+  ].join("\n");
+  const hash = hashManagedContent({ [AGENTS_SECTION_NAME]: bodyContent });
+  const hashLine = `${HASH_MARKER_PREFIX}${hash}${MANAGED_MARKER_SUFFIX}`;
+  const header = [
+    `<!-- GENERATED \u2014 do not hand-edit. Canonical source: .claude/CLAUDE.md -->`,
+    `<!-- Regenerate: codebyplan claude generate -->`
+  ].join("\n");
+  return [header, ``, managedBody, ``, hashLine, ``].join("\n");
+}
+function extractAgentsHash(content) {
+  return extractManagedHash(content);
+}
+var AGENTS_SECTION_NAME;
+var init_agents_generator = __esm({
+  "src/lib/agents-generator.ts"() {
+    "use strict";
+    init_readme_generator();
+    AGENTS_SECTION_NAME = "agents-context";
+  }
+});
+
 // src/cli/claude/generate.ts
 var generate_exports = {};
 __export(generate_exports, {
@@ -9353,6 +9640,7 @@ async function readPkgName(absPath) {
 async function runGenerate(opts) {
   const projectDir = opts.projectDir ?? opts["project-dir"] ?? process.cwd();
   const dryRun = opts.dryRun ?? opts["dryRun"] ?? false;
+  const check = opts.check ?? opts["check"] ?? false;
   const rootDir = resolve8(projectDir);
   let packageManager;
   try {
@@ -9454,28 +9742,362 @@ async function runGenerate(opts) {
     branchModel,
     shipmentSurfaces: shipmentSurfaces.length > 0 ? shipmentSurfaces : void 0
   };
-  const content = generateStructureMd(config);
+  const structureMdContent = generateStructureMd(config);
+  const agentsContent = generateAgentsMd(structureMdContent);
+  if (check) {
+    const agentsMdPath2 = join30(rootDir, "AGENTS.md");
+    let existingAgents = null;
+    try {
+      existingAgents = await readFile21(agentsMdPath2, "utf-8");
+    } catch {
+      existingAgents = null;
+    }
+    if (existingAgents === null) {
+      process.stdout.write(`AGENTS.md missing
+`);
+      process.exitCode = 1;
+    } else {
+      const existingHash = extractAgentsHash(existingAgents);
+      const freshEmbeddedHash = extractAgentsHash(agentsContent);
+      if (existingHash !== freshEmbeddedHash) {
+        process.stdout.write(`AGENTS.md drifted
+`);
+        process.exitCode = 1;
+      } else {
+        process.stdout.write(`AGENTS.md up to date
+`);
+      }
+    }
+    return;
+  }
   if (dryRun) {
     process.stdout.write(
       `[dry-run] Would write: .claude/generated/structure.md
 
 `
     );
-    process.stdout.write(content);
+    process.stdout.write(structureMdContent);
+    process.stdout.write(`
+[dry-run] Would write: AGENTS.md
+
+`);
+    process.stdout.write(agentsContent);
     return;
   }
   const outputDir = join30(rootDir, ".claude", "generated");
   await mkdir10(outputDir, { recursive: true });
   const outputPath = join30(outputDir, "structure.md");
-  await writeFile16(outputPath, content, "utf-8");
+  await writeFile16(outputPath, structureMdContent, "utf-8");
   process.stdout.write(`Wrote: .claude/generated/structure.md
 `);
+  const agentsMdPath = join30(rootDir, "AGENTS.md");
+  let existingAgentsContent = null;
+  try {
+    existingAgentsContent = await readFile21(agentsMdPath, "utf-8");
+  } catch {
+    existingAgentsContent = null;
+  }
+  if (existingAgentsContent !== null && existingAgentsContent === agentsContent) {
+    process.stdout.write(`Up to date: AGENTS.md
+`);
+  } else {
+    await writeFile16(agentsMdPath, agentsContent, "utf-8");
+    process.stdout.write(`Wrote: AGENTS.md
+`);
+  }
 }
 var init_generate = __esm({
   "src/cli/claude/generate.ts"() {
     "use strict";
     init_tech_detect();
     init_structure_generator();
+    init_agents_generator();
+  }
+});
+
+// src/cli/claude/readme.ts
+var readme_exports = {};
+__export(readme_exports, {
+  runReadme: () => runReadme,
+  runReadmeCommand: () => runReadmeCommand
+});
+import { readFile as readFile22, writeFile as writeFile17 } from "node:fs/promises";
+import { join as join31, resolve as resolve9, relative as relative8 } from "node:path";
+async function readJsonFile4(filePath) {
+  try {
+    const raw = await readFile22(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function buildConfig(absPath, isRoot, allPackages, rootPkgJson, pkgJson) {
+  let techStack;
+  try {
+    const techResult = await detectTechStack(absPath);
+    const CATEGORY_LABELS = {
+      "component-lib": "Component Library",
+      graphql: "GraphQL",
+      quality: "Code Quality"
+    };
+    const categoryMap = {};
+    for (const entry of techResult.flat) {
+      if (entry.name === SYNTHETIC_CARRIER_NAME) continue;
+      if (!categoryMap[entry.category]) {
+        categoryMap[entry.category] = [];
+      }
+      categoryMap[entry.category].push(entry.name);
+    }
+    if ((categoryMap["mobile"]?.length ?? 0) > 0) {
+      const frameworkEntries = categoryMap["framework"] ?? [];
+      const filtered = frameworkEntries.filter((n) => n !== "React");
+      if (filtered.length > 0) {
+        categoryMap["framework"] = filtered;
+      } else {
+        delete categoryMap["framework"];
+      }
+    }
+    if (Object.keys(categoryMap).length > 0) {
+      techStack = {};
+      for (const [cat, names] of Object.entries(categoryMap)) {
+        const label = CATEGORY_LABELS[cat] ?? cat.charAt(0).toUpperCase() + cat.slice(1);
+        techStack[label] = [...names].sort().join(" + ");
+      }
+    }
+  } catch {
+  }
+  const packages = isRoot ? allPackages : void 0;
+  const packageManager = typeof rootPkgJson?.packageManager === "string" ? rootPkgJson.packageManager : void 0;
+  const pmBase = packageManager?.split("@")[0] ?? "pnpm";
+  const installCommand = `${pmBase} install`;
+  return {
+    name: pkgJson?.name ?? void 0,
+    description: pkgJson?.description ?? void 0,
+    scripts: pkgJson?.scripts && Object.keys(pkgJson.scripts).length > 0 ? pkgJson.scripts : void 0,
+    packageManager,
+    techStack,
+    packages: packages && packages.length > 0 ? packages : void 0,
+    installCommand
+  };
+}
+async function discoverUnits(rootDir, rootPkgJson) {
+  const units = [];
+  const allPackages = [];
+  const pkgJsonByPath = /* @__PURE__ */ new Map();
+  units.push({
+    name: "root",
+    path: ".",
+    absPath: rootDir,
+    isRoot: true
+  });
+  pkgJsonByPath.set(rootDir, rootPkgJson);
+  const discovered = await discoverMonorepoApps(rootDir);
+  for (const app of discovered) {
+    const pkgJson = await readJsonFile4(
+      join31(app.absPath, "package.json")
+    );
+    pkgJsonByPath.set(app.absPath, pkgJson);
+    allPackages.push({
+      path: app.path,
+      name: pkgJson?.name ?? app.name,
+      purpose: pkgJson?.description ?? void 0
+    });
+    const isApp = app.path === "apps" || app.path.startsWith("apps/");
+    if (!isApp && pkgJson?.private === true) continue;
+    units.push({
+      name: app.name,
+      path: app.path,
+      absPath: app.absPath,
+      isRoot: false
+    });
+  }
+  return { units, allPackages, pkgJsonByPath };
+}
+async function runReadme(opts) {
+  const projectDir = opts.projectDir ?? opts["project-dir"] ?? process.cwd();
+  const dryRun = opts.dryRun ?? opts["dryRun"] ?? false;
+  const check = opts.check ?? opts["check"] ?? false;
+  const init = opts.init ?? opts["init"] ?? false;
+  const rootDir = resolve9(projectDir);
+  const rootPkgJson = await readJsonFile4(
+    join31(rootDir, "package.json")
+  );
+  const { units, allPackages, pkgJsonByPath } = await discoverUnits(
+    rootDir,
+    rootPkgJson
+  );
+  const driftUnits = [];
+  const missingUnits = [];
+  for (const unit of units) {
+    const readmePath = join31(unit.absPath, "README.md");
+    const relPath = unit.isRoot ? "README.md" : join31(relative8(rootDir, unit.absPath), "README.md");
+    let existingContent = null;
+    try {
+      existingContent = await readFile22(readmePath, "utf-8");
+    } catch {
+      existingContent = null;
+    }
+    let config;
+    try {
+      config = await buildConfig(
+        unit.absPath,
+        unit.isRoot,
+        allPackages,
+        rootPkgJson,
+        pkgJsonByPath.get(unit.absPath) ?? null
+      );
+    } catch (err) {
+      process.stderr.write(
+        `readme: error building config for ${relPath}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      continue;
+    }
+    const sections = buildManagedSections(config);
+    if (existingContent === null) {
+      if (check) {
+        missingUnits.push(relPath);
+        continue;
+      }
+      const newContent = scaffoldReadme(config);
+      if (dryRun) {
+        process.stdout.write(
+          `[dry-run] Would write (scaffold): ${relPath}
+
+${newContent}
+`
+        );
+      } else {
+        await writeFile17(readmePath, newContent, "utf-8");
+        process.stdout.write(`Wrote (scaffold): ${relPath}
+`);
+      }
+    } else if (hasManagedMarkers(existingContent)) {
+      const markerErrors = validateManagedMarkers(existingContent);
+      if (markerErrors.length > 0) {
+        process.stderr.write(
+          `readme: skipping ${relPath} \u2014 malformed managed markers: ${markerErrors.join("; ")}
+`
+        );
+        if (check) {
+          driftUnits.push(`${relPath} (malformed markers)`);
+        }
+        continue;
+      }
+      const existingHash = extractManagedHash(existingContent);
+      const newHash = hashManagedContent(sections);
+      if (existingHash === newHash) {
+        if (!check) {
+          process.stdout.write(`Up to date: ${relPath}
+`);
+        }
+        continue;
+      }
+      if (check) {
+        driftUnits.push(relPath);
+        continue;
+      }
+      const newContent = refreshManagedSections(existingContent, sections);
+      if (dryRun) {
+        process.stdout.write(
+          `[dry-run] Would write (refresh): ${relPath}
+
+${newContent}
+`
+        );
+      } else {
+        await writeFile17(readmePath, newContent, "utf-8");
+        process.stdout.write(`Wrote (refresh): ${relPath}
+`);
+      }
+    } else {
+      if (init) {
+        if (check) {
+          driftUnits.push(`${relPath} (no markers, needs --init)`);
+          continue;
+        }
+        const newContent = appendManagedBlock(existingContent, sections);
+        if (dryRun) {
+          process.stdout.write(
+            `[dry-run] Would write (init): ${relPath}
+
+${newContent}
+`
+          );
+        } else {
+          await writeFile17(readmePath, newContent, "utf-8");
+          process.stdout.write(`Wrote (init): ${relPath}
+`);
+        }
+      } else {
+        process.stdout.write(`Skipped (no markers, use --init): ${relPath}
+`);
+      }
+    }
+  }
+  if (check) {
+    if (driftUnits.length > 0 || missingUnits.length > 0) {
+      if (driftUnits.length > 0) {
+        process.stdout.write(
+          `
+README drift detected:
+${driftUnits.map((f) => `  - ${f}`).join("\n")}
+`
+        );
+      }
+      if (missingUnits.length > 0) {
+        process.stdout.write(
+          `
+README missing:
+${missingUnits.map((f) => `  - ${f}`).join("\n")}
+`
+        );
+      }
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(
+        `README check passed \u2014 all managed sections current.
+`
+      );
+    }
+  }
+}
+function appendManagedBlock(existing, sections) {
+  let content = existing.trimEnd();
+  const sectionKeys = Object.keys(sections).sort();
+  for (const key of sectionKeys) {
+    content += "\n\n" + managedStartMarker(key) + "\n" + sections[key].trimEnd() + "\n" + managedEndMarker(key);
+  }
+  const newHash = hashManagedContent(sections);
+  content += `
+
+${HASH_MARKER_PREFIX}${newHash}${MANAGED_MARKER_SUFFIX}`;
+  content += "\n";
+  return content;
+}
+async function runReadmeCommand(args) {
+  const dryRun = args.includes("--dry-run");
+  const check = args.includes("--check");
+  const init = args.includes("--init");
+  let projectDir;
+  const pdIdx = args.indexOf("--project-dir");
+  if (pdIdx !== -1) {
+    const pdVal = args[pdIdx + 1];
+    if (pdVal && !pdVal.startsWith("--")) {
+      projectDir = pdVal;
+    } else {
+      process.stderr.write("error: --project-dir requires a path argument.\n");
+      process.exitCode = 1;
+      return;
+    }
+  }
+  await runReadme({ dryRun, check, init, projectDir });
+}
+var init_readme = __esm({
+  "src/cli/claude/readme.ts"() {
+    "use strict";
+    init_tech_detect();
+    init_readme_generator();
   }
 });
 
@@ -9491,18 +10113,18 @@ __export(migrate_memory_exports, {
   runMigrateMemory: () => runMigrateMemory
 });
 import {
-  readFile as readFile22,
-  writeFile as writeFile17,
+  readFile as readFile23,
+  writeFile as writeFile18,
   mkdir as mkdir11,
   unlink as unlink4,
   rmdir,
   readdir as readdir4
 } from "node:fs/promises";
 import { existsSync as existsSync10 } from "node:fs";
-import { join as join31, resolve as resolve9, dirname as dirname11, sep as sep2 } from "node:path";
+import { join as join32, resolve as resolve10, dirname as dirname11, sep as sep2 } from "node:path";
 import { homedir as homedir8 } from "node:os";
 function encodeProjectPath(absPath) {
-  return resolve9(absPath).replace(/[/\\]/g, "-");
+  return resolve10(absPath).replace(/[/\\]/g, "-");
 }
 function resolveAutoMemoryDir(opts) {
   if (opts.autoMemoryDir) {
@@ -9510,7 +10132,7 @@ function resolveAutoMemoryDir(opts) {
   }
   const projectDir = opts.projectDir ?? process.cwd();
   const encoded = encodeProjectPath(projectDir);
-  return join31(homedir8(), ".claude", "projects", encoded, "memory");
+  return join32(homedir8(), ".claude", "projects", encoded, "memory");
 }
 function parseFrontmatter(content) {
   content = content.replace(/\r\n/g, "\n");
@@ -9576,10 +10198,10 @@ async function inventoryFiles(dir) {
   }
   const results = [];
   for (const filename of filenames) {
-    const sourcePath = join31(dir, filename);
+    const sourcePath = join32(dir, filename);
     let raw;
     try {
-      raw = await readFile22(sourcePath, "utf-8");
+      raw = await readFile23(sourcePath, "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       results.push({
@@ -9659,15 +10281,15 @@ function buildPlan(entries, opts) {
   return plan;
 }
 async function applyPlan(plan, opts) {
-  const projectDir = resolve9(opts.projectDir);
+  const projectDir = resolve10(opts.projectDir);
   const dryRun = opts.dryRun ?? false;
   for (const entry of plan.entries) {
     if (entry.suggested_action !== "keep") continue;
     if (!entry.suggested_target?.startsWith("nested:")) continue;
     const relPath = entry.suggested_target.slice("nested:".length);
-    const targetDir = resolve9(join31(projectDir, relPath));
-    const targetFile = join31(targetDir, "CLAUDE.md");
-    if (!targetDir.startsWith(resolve9(projectDir) + sep2)) {
+    const targetDir = resolve10(join32(projectDir, relPath));
+    const targetFile = join32(targetDir, "CLAUDE.md");
+    if (!targetDir.startsWith(resolve10(projectDir) + sep2)) {
       process.stderr.write(
         `migrate-memory: skipping unsafe suggested_target "${entry.suggested_target}" \u2014 resolves outside projectDir
 `
@@ -9685,8 +10307,8 @@ ${anchor}
     if (dryRun) {
       process.stdout.write(`[dry-run] Would create/append: ${targetFile}
 `);
-      if (resolve9(entry.source_path).startsWith(
-        resolve9(plan.auto_memory_dir) + sep2
+      if (resolve10(entry.source_path).startsWith(
+        resolve10(plan.auto_memory_dir) + sep2
       )) {
         process.stdout.write(
           `[dry-run] Would delete migrated keep source: ${entry.source_path}
@@ -9698,13 +10320,13 @@ ${anchor}
     await mkdir11(targetDir, { recursive: true });
     let existing = "";
     try {
-      existing = await readFile22(targetFile, "utf-8");
+      existing = await readFile23(targetFile, "utf-8");
     } catch {
     }
     if (!existing.includes(anchor)) {
-      await writeFile17(targetFile, existing + appendContent, "utf-8");
+      await writeFile18(targetFile, existing + appendContent, "utf-8");
     }
-    if (resolve9(entry.source_path).startsWith(resolve9(plan.auto_memory_dir) + sep2)) {
+    if (resolve10(entry.source_path).startsWith(resolve10(plan.auto_memory_dir) + sep2)) {
       try {
         await unlink4(entry.source_path);
       } catch {
@@ -9716,7 +10338,7 @@ ${anchor}
       );
     }
   }
-  const rootClaudeMd = join31(projectDir, ".claude", "CLAUDE.md");
+  const rootClaudeMd = join32(projectDir, ".claude", "CLAUDE.md");
   if (dryRun) {
     process.stdout.write(
       `[dry-run] Would ensure ${rootClaudeMd} contains: ${IMPORT_LINE}
@@ -9725,12 +10347,12 @@ ${anchor}
   } else {
     let claudeMdContent = "";
     try {
-      claudeMdContent = await readFile22(rootClaudeMd, "utf-8");
+      claudeMdContent = await readFile23(rootClaudeMd, "utf-8");
     } catch {
       await mkdir11(dirname11(rootClaudeMd), { recursive: true });
     }
     if (!claudeMdContent.includes(IMPORT_LINE)) {
-      await writeFile17(
+      await writeFile18(
         rootClaudeMd,
         claudeMdContent + `
 ${IMPORT_LINE}
@@ -9741,8 +10363,8 @@ ${IMPORT_LINE}
   }
   for (const entry of plan.entries) {
     if (entry.suggested_action !== "drop") continue;
-    if (!resolve9(entry.source_path).startsWith(
-      resolve9(plan.auto_memory_dir) + sep2
+    if (!resolve10(entry.source_path).startsWith(
+      resolve10(plan.auto_memory_dir) + sep2
     )) {
       process.stderr.write(
         `migrate-memory: skipping delete of "${entry.source_path}" \u2014 resolves outside auto_memory_dir
@@ -9760,13 +10382,13 @@ ${IMPORT_LINE}
     } catch {
     }
   }
-  const memoryMd = join31(plan.auto_memory_dir, "MEMORY.md");
-  const safeRmdirBase = join31(homedir8(), ".claude", "projects");
+  const memoryMd = join32(plan.auto_memory_dir, "MEMORY.md");
+  const safeRmdirBase = join32(homedir8(), ".claude", "projects");
   if (dryRun) {
     process.stdout.write(`[dry-run] Would delete MEMORY.md: ${memoryMd}
 `);
   } else {
-    if (resolve9(plan.auto_memory_dir).startsWith(safeRmdirBase + sep2)) {
+    if (resolve10(plan.auto_memory_dir).startsWith(safeRmdirBase + sep2)) {
       try {
         await unlink4(memoryMd);
       } catch {
@@ -9784,7 +10406,7 @@ ${IMPORT_LINE}
 `
     );
   } else {
-    if (!resolve9(plan.auto_memory_dir).startsWith(safeRmdirBase + sep2)) {
+    if (!resolve10(plan.auto_memory_dir).startsWith(safeRmdirBase + sep2)) {
       process.stderr.write(
         `migrate-memory: skipping rmdir of "${plan.auto_memory_dir}" \u2014 not under ~/.claude/projects
 `
@@ -9814,7 +10436,7 @@ async function runMigrateMemory(opts) {
   if (applyFile) {
     let planJson;
     try {
-      planJson = await readFile22(resolve9(applyFile), "utf-8");
+      planJson = await readFile23(resolve10(applyFile), "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(
@@ -9886,11 +10508,11 @@ var init_migrate_memory = __esm({
 // src/index.ts
 init_version();
 import { readFileSync as readFileSync10 } from "node:fs";
-import { resolve as resolve10 } from "node:path";
+import { resolve as resolve11 } from "node:path";
 void (async () => {
   if (!process.env.CODEBYPLAN_API_KEY) {
     try {
-      const envPath = resolve10(process.cwd(), ".env.local");
+      const envPath = resolve11(process.cwd(), ".env.local");
       const content = readFileSync10(envPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
@@ -10096,11 +10718,17 @@ void (async () => {
         process.exit(1);
       }
       const { runGenerate: runGenerate2 } = await Promise.resolve().then(() => (init_generate(), generate_exports));
+      const check = process.argv.slice(4).includes("--check");
       await runGenerate2(
-        parsed.projectDir != null ? { ...parsed.opts, projectDir: parsed.projectDir } : parsed.opts
+        parsed.projectDir != null ? { ...parsed.opts, check, projectDir: parsed.projectDir } : { ...parsed.opts, check }
       );
       process.exit(process.exitCode ?? 0);
     }
+    if (subcommand === "readme") {
+      const { runReadmeCommand: runReadmeCommand2 } = await Promise.resolve().then(() => (init_readme(), readme_exports));
+      await runReadmeCommand2(process.argv.slice(4));
+      process.exit(process.exitCode ?? 0);
+    }
     if (subcommand === "migrate-memory") {
       if (parsed === null) {
         process.exit(1);
@@ -10124,6 +10752,7 @@ void (async () => {
                                                --write-cache  Write result to .codebyplan/claude-status.local.json
                                                --quiet        Suppress stdout output
     codebyplan claude generate [flags]        Write .claude/generated/structure.md from local config
+    codebyplan claude readme   [flags]        Generate / refresh README.md for outward-facing units
     codebyplan claude migrate-memory [flags]  Inventory auto-memory files and emit migration plan
 
   Flags (apply to install/update/uninstall):
@@ -10142,6 +10771,13 @@ void (async () => {
   Flags (apply to generate):
     --project-dir <path>    Override the project root (default: cwd)
     --dry-run               Print what would be written, write nothing
+    --check                 Exit non-zero when AGENTS.md is missing or drifted
+
+  Flags (apply to readme):
+    --project-dir <path>    Override the project root (default: cwd)
+    --dry-run               Print what would be written, write nothing
+    --check                 Exit non-zero on drift or missing READMEs
+    --init                  Append managed block to marker-less existing READMEs
 `);
     process.exit(0);
   }
@@ -10206,6 +10842,7 @@ void (async () => {
     codebyplan claude update  [flags]         Update installed assets to latest versions
     codebyplan claude uninstall [flags]       Remove installed assets from ./.claude/
     codebyplan claude generate [flags]        Write .claude/generated/structure.md from local config
+    codebyplan claude readme   [flags]        Generate / refresh README.md for outward-facing units
     codebyplan claude migrate-memory [flags]  Inventory auto-memory files and emit migration plan
 
     Flags (install/update/uninstall):
@@ -10221,6 +10858,13 @@ void (async () => {
     Flags (generate):
       --project-dir <path>    Override the project root (default: cwd)
       --dry-run               Print what would be written, write nothing
+      --check                 Exit non-zero when AGENTS.md is missing or drifted
+
+    Flags (readme):
+      --project-dir <path>    Override the project root (default: cwd)
+      --dry-run               Print what would be written, write nothing
+      --check                 Exit non-zero on drift or missing READMEs
+      --init                  Append managed block to marker-less existing READMEs
 
     Flags (migrate-memory):
       --project-dir <path>    Override the project root (default: cwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.36",
+  "version": "1.13.38",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/context/mcp-docs.md

@@ -8,7 +8,7 @@ This file is the **consumer contract** for DocsByPlan: what the MCP tools are, w
 
 ## What DocsByPlan Is
 
-A DB-backed, version-aware library-doc retrieval service exposed via MCP at `codebyplan.com/mcp`. It replaces the retired `vendor/` filesystem mirror. Docs are ingested by the `apps/docs-ingest` worker, chunked and ranked by trust score, and served to agents on demand. The DB is the sole source of truth — there are no local files to read.
+A DB-backed, version-aware library-doc retrieval service exposed via MCP at `mcp.codebyplan.com/mcp`. It replaces the retired `vendor/` filesystem mirror. Docs are ingested by the `apps/docs-ingest` worker, chunked and ranked by trust score, and served to agents on demand. The DB is the sole source of truth — there are no local files to read.
 
 Purpose: Claude (planner + executor agents + the orchestrator) consults DocsByPlan **before** writing library-specific code, so that:
 
@@ -133,7 +133,7 @@ This file answers one question for one audience: **"As an agent (planner or exec
 |---------|-----------|
 | Ingest pipeline | `apps/docs-ingest` |
 | Register a new library | `/cbp-add-library {pkg}` |
-| MCP tool endpoint | `codebyplan.com/mcp` |
+| MCP tool endpoint | `mcp.codebyplan.com/mcp` |
 | Loading rule registration | `.claude/rules/context-file-loading.md` (Phase 2.6 / Step 3.4 mapping rows) |
 | Planner integration | `packages/codebyplan-package/templates/agents/task-planner.md` Phase 2.6 |
 | Executor integration | `packages/codebyplan-package/templates/agents/round-executor.md` Step 3.4 |