codebyplan 1.13.37 → 1.13.39

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.37";
+    VERSION = "1.13.39";
     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));
   }
 });
 
@@ -3134,6 +3134,11 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
     JSON.stringify({}, null, 2) + "\n",
     "utf-8"
   );
+  await writeFile7(
+    join12(codebyplanDir, "architecture.json"),
+    JSON.stringify({ version: 1, modules: [] }, null, 2) + "\n",
+    "utf-8"
+  );
   const statuslinePath = join12(codebyplanDir, "statusline.json");
   let statuslineExists = false;
   try {
@@ -3151,7 +3156,7 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
   await writeLocalConfig(projectPath, { device_id: deviceId });
   console.log(`  Created ${codebyplanDir}/`);
   console.log(
-    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, statusline.json`
+    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, architecture.json, statusline.json`
   );
   console.log(`    device.local.json (gitignored)`);
   const gitignoreAction = await ensureManagedGitignoreBlock(projectPath);
@@ -4670,7 +4675,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;
@@ -7142,6 +7147,425 @@ var init_upload_e2e_images = __esm({
   }
 });
 
+// src/cli/arch-map.ts
+var arch_map_exports = {};
+__export(arch_map_exports, {
+  mapFileSlug: () => mapFileSlug,
+  runArchMapCommand: () => runArchMapCommand,
+  updateFrontmatterFields: () => updateFrontmatterFields
+});
+import { readFile as readFile17, writeFile as writeFile13 } from "node:fs/promises";
+import { existsSync as existsSync5, readdirSync as readdirSync2 } from "node:fs";
+import { join as join23 } from "node:path";
+import { spawnSync as spawnSync7 } from "node:child_process";
+function normalizeModulePath(modulePath) {
+  return modulePath.replace(/\/+$/, "");
+}
+function repoRootFromCodebyplanDir(codebyplanDir) {
+  return codebyplanDir.endsWith("/.codebyplan") ? codebyplanDir.slice(0, codebyplanDir.lastIndexOf("/")) : codebyplanDir;
+}
+function mapFileSlug(modulePath) {
+  const slug = modulePath.replace(/\//g, "-").replace(/^\./, "dot-");
+  return `${slug}.md`;
+}
+async function resolveCodebyplanDir(startDir) {
+  try {
+    const found = await findCodebyplanConfig(startDir);
+    if (!found) return null;
+    if (found.path.endsWith("/repo.json")) {
+      return found.path.slice(0, found.path.lastIndexOf("/"));
+    }
+    return found.path.slice(0, found.path.lastIndexOf("/"));
+  } catch {
+    return null;
+  }
+}
+async function readArchitectureConfig(codebyplanDir) {
+  const filePath = join23(codebyplanDir, "architecture.json");
+  try {
+    const raw = await readFile17(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.modules)) {
+      return { version: 1, modules: [] };
+    }
+    return parsed;
+  } catch {
+    return { version: 1, modules: [] };
+  }
+}
+async function writeArchitectureConfig(codebyplanDir, config) {
+  const filePath = join23(codebyplanDir, "architecture.json");
+  await writeFile13(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function resolveGitSha(modulePath, cwd) {
+  try {
+    const result = spawnSync7(
+      "git",
+      ["log", "--format=%H", "-1", "--", modulePath],
+      { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    );
+    if (result.status !== 0 || result.error) return null;
+    const sha = (result.stdout ?? "").trim();
+    return sha.length > 0 ? sha : null;
+  } catch {
+    return null;
+  }
+}
+async function discoverModulePaths(projectRoot) {
+  const paths = [];
+  const workspacePath = join23(projectRoot, "pnpm-workspace.yaml");
+  let patterns = [];
+  try {
+    const raw = await readFile17(workspacePath, "utf-8");
+    const lines = raw.split("\n");
+    let inPackages = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.split("#")[0].trim() === "packages:") {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        if (trimmed.startsWith("-")) {
+          const pat = trimmed.slice(1).trim().replace(/['"]/g, "");
+          patterns.push(pat);
+        } else if (trimmed && !trimmed.startsWith("#")) {
+          break;
+        }
+      }
+    }
+  } catch {
+    patterns = ["apps/*", "packages/*"];
+  }
+  for (const pattern of patterns) {
+    if (pattern.endsWith("/*")) {
+      const dir = pattern.slice(0, -2);
+      const absDir = join23(projectRoot, dir);
+      try {
+        if (existsSync5(absDir)) {
+          const entries = readdirSync2(absDir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.isDirectory()) {
+              paths.push(`${dir}/${entry.name}`);
+            }
+          }
+        }
+      } catch {
+      }
+    } else if (!pattern.includes("*")) {
+      const absPath = join23(projectRoot, pattern);
+      if (existsSync5(absPath)) {
+        paths.push(pattern);
+      }
+    }
+  }
+  const crossCutting = ["supabase", ".github", "scripts"];
+  for (const dir of crossCutting) {
+    const absPath = join23(projectRoot, dir);
+    try {
+      if (existsSync5(absPath)) {
+        paths.push(dir);
+      }
+    } catch {
+    }
+  }
+  return paths;
+}
+async function runStatus(projectRoot) {
+  console.log("\n  CodeByPlan arch-map status\n");
+  try {
+    const codebyplanDir = await resolveCodebyplanDir(projectRoot);
+    const repoRoot = codebyplanDir ? repoRootFromCodebyplanDir(codebyplanDir) : projectRoot;
+    const config = codebyplanDir ? await readArchitectureConfig(codebyplanDir) : { version: 1, modules: [] };
+    const manifestByPath = /* @__PURE__ */ new Map();
+    for (const entry of config.modules) {
+      manifestByPath.set(normalizeModulePath(entry.path), entry);
+    }
+    let modulePaths = [];
+    try {
+      modulePaths = await discoverModulePaths(repoRoot);
+    } catch {
+      console.warn("  Warning: could not discover modules from workspace");
+    }
+    if (modulePaths.length === 0 && config.modules.length === 0) {
+      console.log("  No modules found.\n");
+      return;
+    }
+    const allPaths = /* @__PURE__ */ new Set([
+      ...modulePaths.map(normalizeModulePath),
+      ...config.modules.map((e) => normalizeModulePath(e.path))
+    ]);
+    console.log(
+      "  Module".padEnd(40) + "Map".padEnd(8) + "Stamped".padEnd(12) + "Status"
+    );
+    console.log("  " + "-".repeat(70));
+    for (const modPath of allPaths) {
+      const entry = manifestByPath.get(modPath);
+      const hasMap = !!entry;
+      const stamped = entry?.generated_from_sha != null;
+      let freshness = "-";
+      if (stamped && entry) {
+        const currentSha = resolveGitSha(modPath, repoRoot);
+        if (currentSha == null) {
+          freshness = "unknown";
+        } else if (currentSha === entry.generated_from_sha) {
+          freshness = "fresh";
+        } else {
+          freshness = "stale";
+        }
+      }
+      console.log(
+        "  " + modPath.padEnd(38) + (hasMap ? "yes" : "no").padEnd(8) + (stamped ? "yes" : "no").padEnd(12) + freshness
+      );
+    }
+    console.log();
+  } catch (err) {
+    console.warn(
+      `  Warning: arch-map status error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function runDrift(projectRoot) {
+  console.log("\n  CodeByPlan arch-map drift\n");
+  try {
+    const codebyplanDir = await resolveCodebyplanDir(projectRoot);
+    if (!codebyplanDir) {
+      console.log("  No .codebyplan/ directory found \u2014 no manifest to check.");
+      console.log();
+      return;
+    }
+    const repoRoot = repoRootFromCodebyplanDir(codebyplanDir);
+    const config = await readArchitectureConfig(codebyplanDir);
+    const stamped = config.modules.filter((e) => e.generated_from_sha != null);
+    if (stamped.length === 0) {
+      console.log("  No stamped modules found \u2014 run arch-map stamp first.");
+      console.log();
+      return;
+    }
+    let driftCount = 0;
+    for (const entry of stamped) {
+      const currentSha = resolveGitSha(entry.path, repoRoot);
+      if (currentSha == null) {
+        console.log(
+          `  ? ${entry.path} \u2014 could not resolve current SHA (git unavailable or path not tracked)`
+        );
+        continue;
+      }
+      if (currentSha !== entry.generated_from_sha) {
+        console.log(`  DRIFTED  ${entry.path}`);
+        console.log(`           stamped: ${entry.generated_from_sha}`);
+        console.log(`           current: ${currentSha}`);
+        driftCount++;
+      }
+    }
+    if (driftCount === 0) {
+      console.log("  All stamped modules are fresh.");
+    } else {
+      console.log(`
+  ${driftCount} module(s) have drifted since last stamp.`);
+    }
+    console.log();
+  } catch (err) {
+    console.warn(
+      `  Warning: arch-map drift error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function updateFrontmatterFields(content, fields) {
+  const lines = content.split("\n");
+  if (lines.length === 0 || lines[0] !== "---") {
+    return null;
+  }
+  let closeIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      closeIndex = i;
+      break;
+    }
+  }
+  if (closeIndex === -1) {
+    return null;
+  }
+  const result = lines.map((line, idx) => {
+    if (idx === 0 || idx >= closeIndex) {
+      return line;
+    }
+    if (/^generated_from_sha:\s*/.test(line)) {
+      return `generated_from_sha: ${fields.generated_from_sha}`;
+    }
+    if (/^generated_at:\s*/.test(line)) {
+      return `generated_at: ${fields.generated_at}`;
+    }
+    if (fields.depth !== void 0 && /^depth:\s*/.test(line)) {
+      return `depth: ${fields.depth}`;
+    }
+    return line;
+  });
+  return result.join("\n");
+}
+async function runStamp(modulePath, sha, depthArg, projectRoot) {
+  const codebyplanDir = await resolveCodebyplanDir(projectRoot);
+  if (!codebyplanDir) {
+    process.stderr.write(
+      "  Error: no .codebyplan/ directory found. Run `codebyplan setup` first.\n"
+    );
+    process.exit(1);
+  }
+  const repoRoot = repoRootFromCodebyplanDir(codebyplanDir);
+  let resolvedSha = sha;
+  if (!resolvedSha) {
+    resolvedSha = resolveGitSha(modulePath, repoRoot);
+    if (!resolvedSha) {
+      process.stderr.write(
+        `  Error: could not resolve SHA for ${modulePath}. Provide --sha <value>.
+`
+      );
+      process.exit(1);
+    }
+  }
+  const config = await readArchitectureConfig(codebyplanDir);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const mapFile = mapFileSlug(modulePath);
+  const mapFilePath = `.claude/architecture/${mapFile}`;
+  const existingIndex = config.modules.findIndex((e) => e.path === modulePath);
+  if (existingIndex >= 0) {
+    config.modules[existingIndex] = {
+      ...config.modules[existingIndex],
+      map_file: mapFilePath,
+      generated_from_sha: resolvedSha,
+      generated_at: now,
+      ...depthArg !== null ? { depth: depthArg } : {}
+    };
+  } else {
+    config.modules.push({
+      path: modulePath,
+      map_file: mapFilePath,
+      generated_from_sha: resolvedSha,
+      depth: depthArg ?? "skeleton",
+      generated_at: now
+    });
+  }
+  await writeArchitectureConfig(codebyplanDir, config);
+  const stampedEntry = existingIndex >= 0 ? config.modules[existingIndex] : config.modules[config.modules.length - 1];
+  const mapAbsPath = join23(repoRoot, stampedEntry.map_file);
+  let mapContent = null;
+  try {
+    mapContent = await readFile17(mapAbsPath, "utf-8");
+  } catch {
+    console.warn(
+      "  Warning: map file " + stampedEntry.map_file + " not found \u2014 stamped manifest only"
+    );
+  }
+  if (mapContent !== null) {
+    const updated = updateFrontmatterFields(mapContent, {
+      generated_from_sha: resolvedSha,
+      generated_at: now,
+      ...depthArg !== null ? { depth: depthArg } : {}
+    });
+    if (updated === null) {
+      console.warn(
+        "  Warning: no frontmatter block in " + stampedEntry.map_file + " \u2014 stamped manifest only"
+      );
+    } else if (!updated.includes(`generated_from_sha: ${resolvedSha}`) || !updated.includes(`generated_at: ${now}`)) {
+      console.warn(
+        "  Warning: " + stampedEntry.map_file + " frontmatter missing generated_from_sha/generated_at \u2014 not mirrored (manifest stamped)"
+      );
+    } else {
+      try {
+        await writeFile13(mapAbsPath, updated, "utf-8");
+      } catch (writeErr) {
+        console.warn(
+          "  Warning: could not write map file " + stampedEntry.map_file + " \u2014 " + (writeErr instanceof Error ? writeErr.message : String(writeErr)) + " \u2014 stamped manifest only"
+        );
+      }
+    }
+  }
+  console.log(`  Stamped ${modulePath} @ ${resolvedSha.slice(0, 8)} (${now})`);
+}
+async function runArchMapCommand(rest) {
+  const subcommand = rest[0];
+  const projectRoot = process.cwd();
+  if (subcommand === "status") {
+    await runStatus(projectRoot);
+    return;
+  }
+  if (subcommand === "drift") {
+    await runDrift(projectRoot);
+    return;
+  }
+  if (subcommand === "stamp") {
+    const rawModulePath = rest[1];
+    if (!rawModulePath) {
+      process.stderr.write(
+        "  Usage: codebyplan arch-map stamp <module> [--sha <value>]\n"
+      );
+      process.exit(1);
+    }
+    if (rawModulePath.startsWith("/")) {
+      process.stderr.write(
+        "  Error: module path must be relative to the repo root (e.g. apps/web), not absolute.\n"
+      );
+      process.exit(1);
+    }
+    const modulePath = normalizeModulePath(rawModulePath);
+    if (modulePath.split("/").length > 2) {
+      console.warn(
+        `  Warning: ${modulePath} has more than 2 path segments; expected a top-level module path (e.g. apps/web).`
+      );
+    }
+    let sha = null;
+    const shaIdx = rest.indexOf("--sha");
+    if (shaIdx !== -1) {
+      const shaVal = rest[shaIdx + 1];
+      if (!shaVal || shaVal.startsWith("--")) {
+        process.stderr.write("  Error: --sha requires a value.\n");
+        process.exit(1);
+      }
+      if (!/^[0-9a-f]{40}$/i.test(shaVal)) {
+        process.stderr.write(
+          "  Error: --sha value does not look like a git SHA (expected 40 hex chars).\n"
+        );
+        process.exit(1);
+      }
+      sha = shaVal;
+    }
+    let depthArg = null;
+    const depthIdx = rest.indexOf("--depth");
+    if (depthIdx !== -1) {
+      const depthVal = rest[depthIdx + 1];
+      if (!depthVal || depthVal.startsWith("--")) {
+        process.stderr.write("  Error: --depth requires a value.\n");
+        process.exit(1);
+      }
+      if (depthVal !== "skeleton" && depthVal !== "deep") {
+        process.stderr.write("  Error: --depth must be skeleton or deep.\n");
+        process.exit(1);
+      }
+      depthArg = depthVal;
+    }
+    await runStamp(modulePath, sha, depthArg, projectRoot);
+    return;
+  }
+  console.log(`
+  codebyplan arch-map \u2014 Architecture map pipeline
+
+  Note: arch-map commands are intended to run from the repo root.
+
+  Usage:
+    codebyplan arch-map status              List all modules and map freshness
+    codebyplan arch-map drift               Report modules drifted since last stamp
+    codebyplan arch-map stamp <module>      Stamp a module with its current git SHA
+    codebyplan arch-map stamp <module> --sha <sha>  Stamp with an explicit SHA
+    codebyplan arch-map stamp <module> --depth <skeleton|deep>  Stamp with an explicit depth
+`);
+}
+var init_arch_map = __esm({
+  "src/cli/arch-map.ts"() {
+    "use strict";
+    init_flags();
+  }
+});
+
 // src/lib/worktree-port-resolver.ts
 async function resolveWorktreePortAllocations(repoId, projectPath) {
   let resolvedWorktreeId;
@@ -7231,19 +7655,19 @@ var init_worktree_port_resolver = __esm({
 });
 
 // src/lib/migrate-local-config.ts
-import { mkdir as mkdir7, readFile as readFile17, unlink as unlink3, writeFile as writeFile13 } from "node:fs/promises";
-import { join as join23 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile18, unlink as unlink3, writeFile as writeFile14 } from "node:fs/promises";
+import { join as join24 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join23(projectPath, ".codebyplan.json");
+  return join24(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join23(projectPath, ".codebyplan.local.json");
+  return join24(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join23(projectPath, ".codebyplan");
+  return join24(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join23(projectPath, ".codebyplan", "repo.json");
+  return join24(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -7282,7 +7706,7 @@ async function runLocalMigration(projectPath) {
   }
   let legacyRaw;
   try {
-    legacyRaw = await readFile17(legacySharedPath(projectPath), "utf-8");
+    legacyRaw = await readFile18(legacySharedPath(projectPath), "utf-8");
   } catch {
     return {
       migrated: true,
@@ -7309,7 +7733,7 @@ async function runLocalMigration(projectPath) {
   let deviceId;
   let deviceWrittenByHelper = false;
   try {
-    const localRaw = await readFile17(legacyLocalPath(projectPath), "utf-8");
+    const localRaw = await readFile18(legacyLocalPath(projectPath), "utf-8");
     const localParsed = JSON.parse(localRaw);
     if (typeof localParsed.device_id === "string") {
       deviceId = localParsed.device_id;
@@ -7336,8 +7760,8 @@ async function runLocalMigration(projectPath) {
   if ("repo_id" in cfg) repoJson.repo_id = cfg.repo_id;
   if ("organization_id" in cfg) repoJson.organization_id = cfg.organization_id;
   if ("project_id" in cfg) repoJson.project_id = cfg.project_id;
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "repo.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -7349,8 +7773,8 @@ async function runLocalMigration(projectPath) {
     serverJson.auto_push_enabled = cfg.auto_push_enabled;
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "server.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -7358,44 +7782,44 @@ async function runLocalMigration(projectPath) {
   const gitJson = {};
   if ("git_branch" in cfg) gitJson.git_branch = cfg.git_branch;
   if ("branch_config" in cfg) gitJson.branch_config = cfg.branch_config;
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "git.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/git.json");
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "shipment.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "shipment.json"),
     JSON.stringify(shipmentJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/shipment.json");
   const vendorJson = {};
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "vendor.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "vendor.json"),
     JSON.stringify(vendorJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/vendor.json");
   const e2eJson = {};
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "e2e.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "e2e.json"),
     JSON.stringify(e2eJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/e2e.json");
   const eslintJson = {};
-  await writeFile13(
-    join23(projectPath, ".codebyplan", "eslint.json"),
+  await writeFile14(
+    join24(projectPath, ".codebyplan", "eslint.json"),
     JSON.stringify(eslintJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/eslint.json");
   if (!deviceWrittenByHelper) {
-    await writeFile13(
-      join23(projectPath, ".codebyplan", "device.local.json"),
+    await writeFile14(
+      join24(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -7407,9 +7831,9 @@ async function runLocalMigration(projectPath) {
       "Migration write incomplete: .codebyplan/repo.json was not persisted. Re-run migration to retry from a clean state."
     );
   }
-  const gitignorePath = join23(projectPath, ".gitignore");
+  const gitignorePath = join24(projectPath, ".gitignore");
   try {
-    const gitignoreContent = await readFile17(gitignorePath, "utf-8");
+    const gitignoreContent = await readFile18(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
     const newLine = ".codebyplan/device.local.json";
     const hasLegacy = gitignoreContent.split("\n").some((l) => l.trimEnd() === legacyLine);
@@ -7428,7 +7852,7 @@ async function runLocalMigration(projectPath) {
       updated = gitignoreContent;
     }
     if (updated !== gitignoreContent) {
-      await writeFile13(gitignorePath, updated, "utf-8");
+      await writeFile14(gitignorePath, updated, "utf-8");
       filesChanged.push(".gitignore");
     }
   } catch {
@@ -7469,8 +7893,8 @@ __export(config_exports, {
   readVendorConfig: () => readVendorConfig,
   runConfig: () => runConfig
 });
-import { mkdir as mkdir8, readFile as readFile18, writeFile as writeFile14 } from "node:fs/promises";
-import { join as join24 } from "node:path";
+import { mkdir as mkdir8, readFile as readFile19, writeFile as writeFile15 } from "node:fs/promises";
+import { join as join25 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -7503,7 +7927,7 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join24(projectPath, ".codebyplan");
+  const codebyplanDir = join25(projectPath, ".codebyplan");
   const {
     resolvedWorktreeId,
     portAllocations,
@@ -7571,6 +7995,10 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   const vendorPayload = {};
   const e2ePayload = {};
   const eslintPayload = {};
+  const architecturePayload = {
+    version: 1,
+    modules: []
+  };
   if (dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
@@ -7583,20 +8011,25 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     { name: "shipment.json", payload: shipmentPayload },
     { name: "vendor.json", payload: vendorPayload },
     { name: "e2e.json", payload: e2ePayload, createOnly: true },
-    { name: "eslint.json", payload: eslintPayload, createOnly: true }
+    { name: "eslint.json", payload: eslintPayload, createOnly: true },
+    {
+      name: "architecture.json",
+      payload: architecturePayload,
+      createOnly: true
+    }
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
-    const filePath = join24(codebyplanDir, name);
+    const filePath = join25(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
-      currentJson = await readFile18(filePath, "utf-8");
+      currentJson = await readFile19(filePath, "utf-8");
     } catch {
     }
     if (createOnly && currentJson !== "") continue;
     if (currentJson === newJson) continue;
-    await writeFile14(filePath, newJson, "utf-8");
+    await writeFile15(filePath, newJson, "utf-8");
     console.log(`  Updated .codebyplan/${name}`);
     anyUpdated = true;
   }
@@ -7606,8 +8039,8 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 }
 async function readRepoConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "repo.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7617,8 +8050,8 @@ async function readRepoConfig(projectPath) {
 }
 async function readServerConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "server.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7628,8 +8061,8 @@ async function readServerConfig(projectPath) {
 }
 async function readGitConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "git.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7639,8 +8072,8 @@ async function readGitConfig(projectPath) {
 }
 async function readShipmentConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "shipment.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7650,8 +8083,8 @@ async function readShipmentConfig(projectPath) {
 }
 async function readVendorConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "vendor.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7661,8 +8094,8 @@ async function readVendorConfig(projectPath) {
 }
 async function readE2eConfig2(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "e2e.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "e2e.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7672,8 +8105,8 @@ async function readE2eConfig2(projectPath) {
 }
 async function readServerLocalConfig(projectPath) {
   try {
-    const raw = await readFile18(
-      join24(projectPath, ".codebyplan", "server.local.json"),
+    const raw = await readFile19(
+      join25(projectPath, ".codebyplan", "server.local.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7728,14 +8161,14 @@ var init_server_detect = __esm({
 });
 
 // src/lib/port-verify.ts
-import { readFile as readFile19 } from "node:fs/promises";
+import { readFile as readFile20 } from "node:fs/promises";
 async function verifyPorts(projectPath, portAllocations) {
   const mismatches = [];
   const allocatedPorts = new Set(portAllocations.map((a) => a.port));
   const packageJsonPaths = await findPackageJsonFiles(projectPath, projectPath);
   for (const pkgPath of packageJsonPaths) {
     try {
-      const raw = await readFile19(pkgPath, "utf-8");
+      const raw = await readFile20(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       const scriptPort = detectPortFromScripts(pkg);
       if (scriptPort !== null && !allocatedPorts.has(scriptPort)) {
@@ -7798,7 +8231,7 @@ async function findUnallocatedApps(projectPath, portAllocations) {
     }
     let pkg;
     try {
-      const raw = await readFile19(`${app.absPath}/package.json`, "utf-8");
+      const raw = await readFile20(`${app.absPath}/package.json`, "utf-8");
       pkg = JSON.parse(raw);
     } catch {
       continue;
@@ -7848,8 +8281,8 @@ __export(ports_exports, {
   parseEnvFile: () => parseEnvFile,
   runPorts: () => runPorts
 });
-import { mkdir as mkdir9, readFile as readFile20, writeFile as writeFile15 } from "node:fs/promises";
-import { join as join25 } from "node:path";
+import { mkdir as mkdir9, readFile as readFile21, writeFile as writeFile16 } from "node:fs/promises";
+import { join as join26 } from "node:path";
 async function runPorts() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -7970,12 +8403,12 @@ async function writeServerLocalConfig(repoId, projectPath, dryRun) {
     // and ServerLocalConfig.port_allocations is typed the same — honest end-to-end.
     port_allocations: portAllocations
   };
-  const codebyplanDir = join25(projectPath, ".codebyplan");
-  const filePath = join25(codebyplanDir, "server.local.json");
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "server.local.json");
   const newJson = JSON.stringify(payload, null, 2) + "\n";
   let currentJson = "";
   try {
-    currentJson = await readFile20(filePath, "utf-8");
+    currentJson = await readFile21(filePath, "utf-8");
   } catch {
   }
   if (currentJson === newJson) {
@@ -7987,17 +8420,17 @@ async function writeServerLocalConfig(repoId, projectPath, dryRun) {
     return;
   }
   await mkdir9(codebyplanDir, { recursive: true });
-  await writeFile15(filePath, newJson, "utf-8");
+  await writeFile16(filePath, newJson, "utf-8");
   console.log(
     `  Updated .codebyplan/server.local.json (worktree ${resolvedWorktreeId ?? "\u2014"}, ${portAllocations.length} allocation${portAllocations.length === 1 ? "" : "s"}).`
   );
 }
 async function provisionE2eEnv(projectPath, dryRun) {
-  const relSource = join25("apps", "web", ".env.local");
-  const sourcePath = join25(projectPath, relSource);
+  const relSource = join26("apps", "web", ".env.local");
+  const sourcePath = join26(projectPath, relSource);
   let sourceRaw;
   try {
-    sourceRaw = await readFile20(sourcePath, "utf-8");
+    sourceRaw = await readFile21(sourcePath, "utf-8");
   } catch {
     console.warn(
       `  Skipped .codebyplan/e2e.env \u2014 source ${relSource} not found.`
@@ -8026,12 +8459,12 @@ async function provisionE2eEnv(projectPath, dryRun) {
     );
     return;
   }
-  const codebyplanDir = join25(projectPath, ".codebyplan");
-  const filePath = join25(codebyplanDir, "e2e.env");
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "e2e.env");
   const newContent = lines.join("\n") + "\n";
   let currentContent = "";
   try {
-    currentContent = await readFile20(filePath, "utf-8");
+    currentContent = await readFile21(filePath, "utf-8");
   } catch {
   }
   if (currentContent === newContent) {
@@ -8043,7 +8476,7 @@ async function provisionE2eEnv(projectPath, dryRun) {
     return;
   }
   await mkdir9(codebyplanDir, { recursive: true });
-  await writeFile15(filePath, newContent, "utf-8");
+  await writeFile16(filePath, newContent, "utf-8");
   console.log(
     `  Provisioned .codebyplan/e2e.env (${lines.length} var${lines.length === 1 ? "" : "s"}).`
   );
@@ -8093,7 +8526,7 @@ __export(tech_stack_exports, {
   runFullTechStack: () => runFullTechStack,
   runTechStack: () => runTechStack
 });
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 async function runTechStack() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -8266,7 +8699,7 @@ async function runFullTechStack(dryRun) {
       continue;
     }
     const localWorktrees = worktrees.filter(
-      (wt) => wt.path ? existsSync5(wt.path) : false
+      (wt) => wt.path ? existsSync6(wt.path) : false
     );
     if (localWorktrees.length === 0) {
       console.log(`  skipping ${repo.name} \u2014 no local worktree on this device`);
@@ -8366,7 +8799,7 @@ var init_claude_plan = __esm({
 // src/cli/claude/status.ts
 var status_exports = {};
 __export(status_exports, {
-  runStatus: () => runStatus
+  runStatus: () => runStatus2
 });
 import * as fs6 from "node:fs";
 import * as path7 from "node:path";
@@ -8433,7 +8866,7 @@ function resolveCurrentBranch2() {
     }
   }
 }
-async function runStatus(argv) {
+async function runStatus2(argv) {
   const checked_at = (/* @__PURE__ */ new Date()).toISOString();
   const writeCache = argv.includes("--write-cache");
   const quiet = argv.includes("--quiet");
@@ -8616,11 +9049,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,16 +9759,303 @@ 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, {
   runGenerate: () => runGenerate
 });
-import { readFile as readFile21, mkdir as mkdir10, writeFile as writeFile16 } from "node:fs/promises";
-import { join as join30, resolve as resolve8 } from "node:path";
+import { readFile as readFile22, mkdir as mkdir10, writeFile as writeFile17 } from "node:fs/promises";
+import { join as join31, resolve as resolve8 } from "node:path";
 async function readJsonFile3(filePath) {
   try {
-    const raw = await readFile21(filePath, "utf-8");
+    const raw = await readFile22(filePath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -9343,7 +10063,7 @@ async function readJsonFile3(filePath) {
 }
 async function readPkgName(absPath) {
   try {
-    const raw = await readFile21(join30(absPath, "package.json"), "utf-8");
+    const raw = await readFile22(join31(absPath, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     return typeof pkg.name === "string" ? pkg.name : null;
   } catch {
@@ -9353,10 +10073,11 @@ 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 {
-    const raw = await readFile21(join30(rootDir, "package.json"), "utf-8");
+    const raw = await readFile22(join31(rootDir, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     if (typeof pkg.packageManager === "string") {
       packageManager = pkg.packageManager;
@@ -9364,7 +10085,7 @@ async function runGenerate(opts) {
   } catch {
   }
   const serverJson = await readJsonFile3(
-    join30(rootDir, ".codebyplan", "server.json")
+    join31(rootDir, ".codebyplan", "server.json")
   );
   const ports = [];
   for (const alloc of serverJson?.port_allocations ?? []) {
@@ -9377,7 +10098,7 @@ async function runGenerate(opts) {
     }
   }
   const gitJson = await readJsonFile3(
-    join30(rootDir, ".codebyplan", "git.json")
+    join31(rootDir, ".codebyplan", "git.json")
   );
   const branchModel = gitJson?.branch_config?.production ? {
     production: gitJson.branch_config.production,
@@ -9386,7 +10107,7 @@ async function runGenerate(opts) {
     )
   } : void 0;
   const shipmentJson = await readJsonFile3(
-    join30(rootDir, ".codebyplan", "shipment.json")
+    join31(rootDir, ".codebyplan", "shipment.json")
   );
   const shipmentSurfaces = [];
   const rawSurfaces = shipmentJson?.shipment?.surfaces ?? shipmentJson?.surfaces ?? {};
@@ -9454,28 +10175,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 = join31(rootDir, "AGENTS.md");
+    let existingAgents = null;
+    try {
+      existingAgents = await readFile22(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");
+  const outputDir = join31(rootDir, ".claude", "generated");
   await mkdir10(outputDir, { recursive: true });
-  const outputPath = join30(outputDir, "structure.md");
-  await writeFile16(outputPath, content, "utf-8");
+  const outputPath = join31(outputDir, "structure.md");
+  await writeFile17(outputPath, structureMdContent, "utf-8");
   process.stdout.write(`Wrote: .claude/generated/structure.md
 `);
+  const agentsMdPath = join31(rootDir, "AGENTS.md");
+  let existingAgentsContent = null;
+  try {
+    existingAgentsContent = await readFile22(agentsMdPath, "utf-8");
+  } catch {
+    existingAgentsContent = null;
+  }
+  if (existingAgentsContent !== null && existingAgentsContent === agentsContent) {
+    process.stdout.write(`Up to date: AGENTS.md
+`);
+  } else {
+    await writeFile17(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 readFile23, writeFile as writeFile18 } from "node:fs/promises";
+import { join as join32, resolve as resolve9, relative as relative8 } from "node:path";
+async function readJsonFile4(filePath) {
+  try {
+    const raw = await readFile23(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(
+      join32(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(
+    join32(rootDir, "package.json")
+  );
+  const { units, allPackages, pkgJsonByPath } = await discoverUnits(
+    rootDir,
+    rootPkgJson
+  );
+  const driftUnits = [];
+  const missingUnits = [];
+  for (const unit of units) {
+    const readmePath = join32(unit.absPath, "README.md");
+    const relPath = unit.isRoot ? "README.md" : join32(relative8(rootDir, unit.absPath), "README.md");
+    let existingContent = null;
+    try {
+      existingContent = await readFile23(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 writeFile18(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 writeFile18(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 writeFile18(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 +10546,18 @@ __export(migrate_memory_exports, {
   runMigrateMemory: () => runMigrateMemory
 });
 import {
-  readFile as readFile22,
-  writeFile as writeFile17,
+  readFile as readFile24,
+  writeFile as writeFile19,
   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 { existsSync as existsSync11 } from "node:fs";
+import { join as join33, 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 +10565,7 @@ function resolveAutoMemoryDir(opts) {
   }
   const projectDir = opts.projectDir ?? process.cwd();
   const encoded = encodeProjectPath(projectDir);
-  return join31(homedir8(), ".claude", "projects", encoded, "memory");
+  return join33(homedir8(), ".claude", "projects", encoded, "memory");
 }
 function parseFrontmatter(content) {
   content = content.replace(/\r\n/g, "\n");
@@ -9576,10 +10631,10 @@ async function inventoryFiles(dir) {
   }
   const results = [];
   for (const filename of filenames) {
-    const sourcePath = join31(dir, filename);
+    const sourcePath = join33(dir, filename);
     let raw;
     try {
-      raw = await readFile22(sourcePath, "utf-8");
+      raw = await readFile24(sourcePath, "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       results.push({
@@ -9659,15 +10714,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(join33(projectDir, relPath));
+    const targetFile = join33(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 +10740,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 +10753,13 @@ ${anchor}
     await mkdir11(targetDir, { recursive: true });
     let existing = "";
     try {
-      existing = await readFile22(targetFile, "utf-8");
+      existing = await readFile24(targetFile, "utf-8");
     } catch {
     }
     if (!existing.includes(anchor)) {
-      await writeFile17(targetFile, existing + appendContent, "utf-8");
+      await writeFile19(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 +10771,7 @@ ${anchor}
       );
     }
   }
-  const rootClaudeMd = join31(projectDir, ".claude", "CLAUDE.md");
+  const rootClaudeMd = join33(projectDir, ".claude", "CLAUDE.md");
   if (dryRun) {
     process.stdout.write(
       `[dry-run] Would ensure ${rootClaudeMd} contains: ${IMPORT_LINE}
@@ -9725,12 +10780,12 @@ ${anchor}
   } else {
     let claudeMdContent = "";
     try {
-      claudeMdContent = await readFile22(rootClaudeMd, "utf-8");
+      claudeMdContent = await readFile24(rootClaudeMd, "utf-8");
     } catch {
       await mkdir11(dirname11(rootClaudeMd), { recursive: true });
     }
     if (!claudeMdContent.includes(IMPORT_LINE)) {
-      await writeFile17(
+      await writeFile19(
         rootClaudeMd,
         claudeMdContent + `
 ${IMPORT_LINE}
@@ -9741,8 +10796,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 +10815,13 @@ ${IMPORT_LINE}
     } catch {
     }
   }
-  const memoryMd = join31(plan.auto_memory_dir, "MEMORY.md");
-  const safeRmdirBase = join31(homedir8(), ".claude", "projects");
+  const memoryMd = join33(plan.auto_memory_dir, "MEMORY.md");
+  const safeRmdirBase = join33(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 +10839,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 +10869,7 @@ async function runMigrateMemory(opts) {
   if (applyFile) {
     let planJson;
     try {
-      planJson = await readFile22(resolve9(applyFile), "utf-8");
+      planJson = await readFile24(resolve10(applyFile), "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(
@@ -9842,7 +10897,7 @@ async function runMigrateMemory(opts) {
     );
     return;
   }
-  if (!existsSync10(autoMemoryDir)) {
+  if (!existsSync11(autoMemoryDir)) {
     process.stdout.write(
       JSON.stringify(
         {
@@ -9886,11 +10941,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();
@@ -10029,6 +11084,12 @@ void (async () => {
     await runUploadE2eImagesCommand2(rest);
     process.exit(0);
   }
+  if (arg === "arch-map") {
+    const { runArchMapCommand: runArchMapCommand2 } = await Promise.resolve().then(() => (init_arch_map(), arch_map_exports));
+    const rest = process.argv.slice(3);
+    await runArchMapCommand2(rest);
+    process.exit(0);
+  }
   if (arg === "config") {
     const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
     await runConfig2();
@@ -10054,8 +11115,8 @@ void (async () => {
     const flagArgs = process.argv.slice(3);
     const parsed = parseClaudeFlags(flagArgs);
     if (subcommand === "status") {
-      const { runStatus: runStatus2 } = await Promise.resolve().then(() => (init_status(), status_exports));
-      await runStatus2(process.argv.slice(4));
+      const { runStatus: runStatus3 } = await Promise.resolve().then(() => (init_status(), status_exports));
+      await runStatus3(process.argv.slice(4));
       return;
     }
     if (subcommand === "install") {
@@ -10096,11 +11157,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 +11191,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 +11210,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);
   }
@@ -10159,6 +11234,7 @@ void (async () => {
     codebyplan create-project        Create a new project within an organization (interactive prompt)
     codebyplan create-repo           Create a new repository within a project (interactive prompt)
     codebyplan config                Sync repo config from DB to .codebyplan/ files
+    codebyplan arch-map              Map architecture modules (status/drift/stamp)
     codebyplan ports                 Verify port allocations against local package.json scripts
     codebyplan tech-stack            Detect and sync tech stack dependencies
                                      (--full-tech-stack: sync every local worktree on this device)
@@ -10206,6 +11282,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 +11298,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)