codebyplan 1.13.53 → 1.13.54

package/dist/cli.js

@@ -39,7 +39,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.53";
+    VERSION = "1.13.54";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1105,14 +1105,16 @@ async function validateAuth() {
   await getAuthHeaders();
 }
 async function getAuthHeaders() {
+  const key = legacyApiKey();
+  if (key) {
+    return { headers: { "x-api-key": key }, via: "api_key" };
+  }
   try {
     const token = await getAccessToken();
     return { headers: { Authorization: `Bearer ${token}` }, via: "bearer" };
   } catch (err) {
     if (!(err instanceof NoTokenError)) throw err;
-    const key = legacyApiKey();
-    if (!key) throw new Error(noAuthHint());
-    return { headers: { "x-api-key": key }, via: "api_key" };
+    throw new Error(noAuthHint());
   }
 }
 async function validateConnectivity() {
@@ -1757,7 +1759,18 @@ var init_template_walker = __esm({
       // SessionStart scope + sibling-parity sweep — fires ONLY in the templates source
       // repo (self-guards on templates/ presence). A no-op for consumers, so it ships
       // neither in hooks.json nor as a copied file.
-      "hooks/verify-parity.sh"
+      "hooks/verify-parity.sh",
+      // Monorepo-internal skill helpers — these qa-regression checklists hardcode
+      // absolute /Users/... home paths and CBP worktree UUIDs that are meaningless
+      // (and misleading) in any other consumer repo, so they ship neither as copied
+      // files nor in the install manifest.
+      "skills/cbp-todo/qa-regression.md",
+      "skills/cbp-session-start/qa-regression.md",
+      // task-routing-recommendation.md carries `scope: repo-only:codebyplan` and is
+      // installed only in codebyplan-family repos (see templates/rules/README.md).
+      // Excluding it here fixes a latent scope violation — it previously shipped to
+      // every consumer despite the repo-only marker.
+      "rules/task-routing-recommendation.md"
     ]);
   }
 });
@@ -4744,6 +4757,7 @@ __export(state_store_exports, {
   readEntityFile: () => readEntityFile,
   roundPath: () => roundPath,
   sessionLogPath: () => sessionLogPath,
+  standaloneTaskPath: () => standaloneTaskPath,
   taskPath: () => taskPath,
   todosPath: () => todosPath,
   worktreesPath: () => worktreesPath,
@@ -4790,6 +4804,9 @@ function roundPath(repoRoot, checkpointId, taskId, roundId) {
     `${roundId}.json`
   );
 }
+function standaloneTaskPath(repoRoot, taskId) {
+  return join18(stateDir(repoRoot), "standalone_tasks", `${taskId}.json`);
+}
 function sessionLogPath(repoRoot) {
   return join18(stateDir(repoRoot), "session", "current.json");
 }
@@ -14280,8 +14297,8 @@ var require_RealtimeChannel = __commonJS({
       }
       /** @internal */
       _notThisChannelEvent(event, ref) {
-        const { close, error, leave, join: join53 } = constants_1.CHANNEL_EVENTS;
-        const events = [close, error, leave, join53];
+        const { close, error, leave, join: join54 } = constants_1.CHANNEL_EVENTS;
+        const events = [close, error, leave, join54];
         return ref && events.includes(event) && ref !== this.joinPush.ref;
       }
       /** @internal */
@@ -28253,244 +28270,6 @@ var init_task = __esm({
   }
 });
 
-// src/cli/session.ts
-var session_exports = {};
-__export(session_exports, {
-  runSessionCommand: () => runSessionCommand
-});
-async function resolveRepoRoot3() {
-  const found = await findCodebyplanConfig(process.cwd());
-  if (!found?.contents.repo_id) return null;
-  const repoRoot = deriveRepoRoot(found.path);
-  return { repoRoot, repoId: found.contents.repo_id };
-}
-async function updateCursorHash3(repoRoot, entityId, row) {
-  const cursor = await readCursor(repoRoot);
-  if (!cursor) return;
-  const hash = hashEntity(row);
-  cursor.entity_hashes[entityId] = hash;
-  await writeCursor(repoRoot, cursor);
-}
-async function runSessionCreateLog(args) {
-  const { flags } = parseFlagsFromArgs(args);
-  const repoInfo = await resolveRepoRoot3();
-  if (!repoInfo) {
-    process.stderr.write(
-      "session create-log: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
-    );
-    process.exit(1);
-  }
-  const { repoRoot, repoId } = repoInfo;
-  const snakeFlags = coerceFieldValues(kebabToSnakeKeys(flags));
-  const body = {
-    repo_id: repoId,
-    ...snakeFlags
-  };
-  try {
-    const created = await apiBackendPost(new URL(backendSessionLogsEndpoint()).pathname, body);
-    const sessionLog = created.session_log ?? created;
-    const filePath = sessionLogPath(repoRoot);
-    await writeEntityFile(filePath, sessionLog);
-    const sessionLogId = sessionLog.id;
-    if (sessionLogId) {
-      await updateCursorHash3(repoRoot, sessionLogId, sessionLog);
-    }
-    process.stdout.write(JSON.stringify(created) + "\n");
-  } catch (err) {
-    if (err instanceof BackendError) {
-      process.stderr.write(
-        `session create-log: backend error ${err.status}: ${err.message}
-`
-      );
-    } else {
-      process.stderr.write(
-        `session create-log: ${err instanceof Error ? err.message : String(err)}
-`
-      );
-    }
-    process.exit(1);
-  }
-  process.exit(0);
-}
-async function runSessionUpdateLog(args) {
-  const { flags } = parseFlagsFromArgs(args);
-  const id = flags.id ?? flags["log-id"];
-  if (!id) {
-    process.stderr.write("session update-log: --id <log-id> is required\n");
-    process.exit(1);
-  }
-  const repoInfo = await resolveRepoRoot3();
-  if (!repoInfo) {
-    process.stderr.write(
-      "session update-log: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
-    );
-    process.exit(1);
-  }
-  const { repoRoot } = repoInfo;
-  const filePath = sessionLogPath(repoRoot);
-  const { id: _omit, ...patchBody } = flags;
-  void _omit;
-  const snakePatch = coerceFieldValues(kebabToSnakeKeys(patchBody));
-  const snapshot = await readEntityFile(filePath);
-  const optimistic = { ...snapshot ?? {}, ...snakePatch, id };
-  await writeEntityFile(filePath, optimistic);
-  try {
-    const updated = await apiBackendPatch(
-      `${new URL(backendSessionLogsEndpoint()).pathname}/${id}`,
-      snakePatch
-    );
-    await writeEntityFile(filePath, updated);
-    await updateCursorHash3(repoRoot, id, updated);
-    process.stdout.write(JSON.stringify(updated) + "\n");
-  } catch (err) {
-    if (err instanceof BackendError && err.status < 500) {
-      if (snapshot !== null) {
-        await writeEntityFile(filePath, snapshot);
-      } else {
-        await deleteEntityFile(filePath);
-      }
-      process.stderr.write(
-        `session update-log: backend rejected (${err.status}): ${err.message}
-`
-      );
-    } else {
-      await writeEntityFile(pendingMarkerPath(repoRoot, id), {
-        entity: "session_log",
-        id,
-        operation: "update-log",
-        attempted_at: (/* @__PURE__ */ new Date()).toISOString(),
-        error: err instanceof Error ? err.message : String(err)
-      });
-      process.stderr.write(
-        `session update-log: backend unavailable \u2014 local write kept, pending marker written. Error: ${err instanceof Error ? err.message : String(err)}
-`
-      );
-    }
-    process.exit(1);
-  }
-  process.exit(0);
-}
-async function runSessionUpdateState(args) {
-  const { flags, booleans } = parseFlagsFromArgs(args);
-  if (booleans.has("action") && !flags["action"]) {
-    process.stderr.write(
-      "session update-state: --action requires a value \u2014 use --action <activate|deactivate>\n"
-    );
-    process.exit(1);
-  }
-  if (!flags["action"]) {
-    process.stderr.write(
-      "session update-state: --action <activate|deactivate> is required\n"
-    );
-    process.exit(1);
-  }
-  const VALID_ACTIONS = /* @__PURE__ */ new Set(["activate", "deactivate"]);
-  if (!VALID_ACTIONS.has(flags["action"])) {
-    process.stderr.write(
-      `session update-state: --action must be 'activate' or 'deactivate', got '${flags["action"]}'
-`
-    );
-    process.exit(1);
-  }
-  const repoInfo = await resolveRepoRoot3();
-  if (!repoInfo) {
-    process.stderr.write(
-      "session update-state: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
-    );
-    process.exit(1);
-  }
-  const { repoRoot, repoId } = repoInfo;
-  const { ...patchBody } = flags;
-  const snakePatch = coerceFieldValues(kebabToSnakeKeys(patchBody));
-  const stateFilePath = sessionLogPath(repoRoot).replace(
-    "current.json",
-    "state.json"
-  );
-  const snapshot = await readEntityFile(stateFilePath);
-  const optimistic = { ...snapshot ?? {}, ...snakePatch, repo_id: repoId };
-  await writeEntityFile(stateFilePath, optimistic);
-  try {
-    const updated = await apiBackendPatch(
-      new URL(backendSessionStateEndpoint(repoId)).pathname,
-      snakePatch
-    );
-    await writeEntityFile(stateFilePath, updated);
-    process.stdout.write(JSON.stringify(updated) + "\n");
-  } catch (err) {
-    if (err instanceof BackendError && err.status < 500) {
-      if (snapshot !== null) {
-        await writeEntityFile(stateFilePath, snapshot);
-      } else {
-        await deleteEntityFile(stateFilePath);
-      }
-      process.stderr.write(
-        `session update-state: backend rejected (${err.status}): ${err.message}
-`
-      );
-    } else {
-      await writeEntityFile(
-        pendingMarkerPath(repoRoot, `session-state-${repoId}`),
-        {
-          entity: "session_state",
-          repo_id: repoId,
-          operation: "update-state",
-          attempted_at: (/* @__PURE__ */ new Date()).toISOString(),
-          error: err instanceof Error ? err.message : String(err)
-        }
-      );
-      process.stderr.write(
-        `session update-state: backend unavailable \u2014 local write kept, pending marker written. Error: ${err instanceof Error ? err.message : String(err)}
-`
-      );
-    }
-    process.exit(1);
-  }
-  process.exit(0);
-}
-function printSessionHelp() {
-  process.stdout.write(
-    "\n  codebyplan session <subcommand>\n\n  Subcommands:\n    create-log     Create a session log (fields as --key value pairs)\n    update-log     Update a session log (--id <uuid> required, then --key value pairs)\n    update-state   Update session state for the current repo (--key value pairs)\n\n"
-  );
-}
-async function runSessionCommand(args) {
-  const subcommand = args[0];
-  if (subcommand === "create-log") {
-    await runSessionCreateLog(args.slice(1));
-    return;
-  }
-  if (subcommand === "update-log") {
-    await runSessionUpdateLog(args.slice(1));
-    return;
-  }
-  if (subcommand === "update-state") {
-    await runSessionUpdateState(args.slice(1));
-    return;
-  }
-  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
-    printSessionHelp();
-    process.exit(0);
-  }
-  if (subcommand) {
-    process.stderr.write(
-      `Unknown session subcommand: ${subcommand}
-Run 'codebyplan session help' for usage.
-`
-    );
-  } else {
-    printSessionHelp();
-  }
-  process.exit(1);
-}
-var init_session = __esm({
-  "src/cli/session.ts"() {
-    "use strict";
-    init_flags();
-    init_state_store();
-    init_state_client();
-    init_urls();
-  }
-});
-
 // src/lib/mcp-client.ts
 async function mcpCall(toolName, args) {
   let accessToken;
@@ -29126,7 +28905,7 @@ async function runRoundSyncApprovals(args) {
       );
       if (!dryRun && !callerWorktreeId) {
         throw new Error(
-          "could not resolve caller_worktree_id for this worktree.\n  Run: codebyplan resolve-worktree --cache\n  If this worktree is not registered, run: npx codebyplan setup\n  Then re-run /cbp-round-update (sync-approvals)."
+          "could not resolve caller_worktree_id for this worktree.\n  Run: codebyplan resolve-worktree --cache\n  If this worktree is not registered, run: npx codebyplan setup\n  Then re-run codebyplan round sync-approvals."
         );
       }
       let gitStatusOutput = "";
@@ -29205,7 +28984,7 @@ async function runRoundSyncApprovals(args) {
   }
   if (skipReason !== null) {
     process.stderr.write(
-      `sync-approvals: MCP temporarily unavailable (${skipReason}); skipping approval sync. Re-run /cbp-round-update when the service recovers.
+      `sync-approvals: MCP temporarily unavailable (${skipReason}); skipping approval sync. Re-run codebyplan round sync-approvals when the service recovers.
 `
     );
     process.exit(0);
@@ -29237,6 +29016,577 @@ var init_round = __esm({
   }
 });
 
+// src/cli/standalone-task.ts
+var standalone_task_exports = {};
+__export(standalone_task_exports, {
+  runStandaloneTaskCommand: () => runStandaloneTaskCommand
+});
+async function resolveRepoRoot3() {
+  const found = await findCodebyplanConfig(process.cwd());
+  if (!found?.contents.repo_id) return null;
+  const repoRoot = deriveRepoRoot(found.path);
+  return { repoRoot, repoId: found.contents.repo_id };
+}
+async function updateCursorHash3(repoRoot, entityId, row) {
+  const cursor = await readCursor(repoRoot);
+  if (!cursor) return;
+  const hash = hashEntity(row);
+  cursor.entity_hashes[entityId] = hash;
+  await writeCursor(repoRoot, cursor);
+}
+async function resolveCallerWorktreeId2(repoRoot, currentBranch, repoId, overrideId) {
+  if (overrideId) {
+    return overrideId;
+  }
+  const cached = await readCachedWorktreeId(repoRoot, currentBranch);
+  if (cached) {
+    return cached;
+  }
+  if (!repoId || !currentBranch) {
+    return null;
+  }
+  const deviceId = await getOrCreateDeviceId(repoRoot);
+  const wid = await resolveWorktreeId({
+    repoId,
+    repoPath: repoRoot,
+    branch: currentBranch,
+    deviceId
+  });
+  if (wid) {
+    await writeWorktreeCache(repoRoot, {
+      worktree_id: wid,
+      branch: currentBranch,
+      device_id: deviceId
+    });
+    return wid;
+  }
+  return null;
+}
+function currentBranchSafe(repoRoot) {
+  try {
+    return getCurrentBranch(repoRoot);
+  } catch {
+    return "";
+  }
+}
+async function revertLocalWrite(filePath, snapshot) {
+  if (snapshot !== null) {
+    await writeEntityFile(filePath, snapshot);
+  } else {
+    await deleteEntityFile(filePath);
+  }
+}
+async function handleMcpWriteError(opts) {
+  const { verb, err, filePath, snapshot, repoRoot, id, operation } = opts;
+  const msg = err instanceof Error ? err.message : String(err);
+  const status = err instanceof McpError ? err.status : void 0;
+  if (status === 401) {
+    await revertLocalWrite(filePath, snapshot);
+    process.stderr.write(
+      `${verb}: authentication failed (401): ${msg}
+  Run: codebyplan login
+`
+    );
+    return;
+  }
+  if (isTransientMcpError(err)) {
+    await writeEntityFile(pendingMarkerPath(repoRoot, id), {
+      entity: "standalone_task",
+      id,
+      operation,
+      attempted_at: (/* @__PURE__ */ new Date()).toISOString(),
+      error: msg
+    });
+    process.stderr.write(
+      `${verb}: MCP unavailable \u2014 local write kept, pending marker written. Error: ${msg}
+`
+    );
+    return;
+  }
+  await revertLocalWrite(filePath, snapshot);
+  process.stderr.write(`${verb}: rejected: ${msg}
+`);
+}
+async function runStandaloneTaskCreate(args) {
+  const { flags } = parseFlagsFromArgs(args);
+  if (!flags.title) {
+    process.stderr.write(
+      "standalone-task create: --title <title> is required\nUsage: codebyplan standalone-task create --title <title> [--key value ...]\n"
+    );
+    process.exit(1);
+  }
+  const found = await findCodebyplanConfig(process.cwd());
+  const repoId = flags["repo-id"] ?? found?.contents.repo_id;
+  if (!repoId) {
+    process.stderr.write(
+      "standalone-task create: could not determine repo_id.\n  Pass --repo-id <uuid> or run `codebyplan setup` so .codebyplan/repo.json exists.\n"
+    );
+    process.exit(1);
+  }
+  const repoRoot = found ? deriveRepoRoot(found.path) : process.cwd();
+  const snakeFlags = coerceFieldValues(kebabToSnakeKeys(flags));
+  const currentBranch = currentBranchSafe(repoRoot);
+  const callerWorktreeId = await resolveCallerWorktreeId2(
+    repoRoot,
+    currentBranch,
+    repoId,
+    flags["caller-worktree-id"]
+  );
+  const mcpArgs = {};
+  for (const key of CREATE_KEYS) {
+    if (snakeFlags[key] !== void 0) mcpArgs[key] = snakeFlags[key];
+  }
+  mcpArgs.repo_id = repoId;
+  if (flags.number !== void 0) mcpArgs.number = Number(flags.number);
+  if (callerWorktreeId) mcpArgs.caller_worktree_id = callerWorktreeId;
+  try {
+    const created = await mcpCall(
+      "create_standalone_task",
+      mcpArgs
+    );
+    const filePath = standaloneTaskPath(repoRoot, created.id);
+    await writeEntityFile(filePath, created);
+    await updateCursorHash3(repoRoot, created.id, created);
+    process.stdout.write(JSON.stringify(created) + "\n");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`standalone-task create: ${msg}
+`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+async function runStandaloneTaskUpdate(args) {
+  const { flags } = parseFlagsFromArgs(args);
+  const id = flags.id ?? flags["standalone-task-id"];
+  if (!id) {
+    process.stderr.write(
+      "standalone-task update: --id <standalone-task-id> is required\n"
+    );
+    process.exit(1);
+  }
+  const repoInfo = await resolveRepoRoot3();
+  if (!repoInfo) {
+    process.stderr.write(
+      "standalone-task update: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
+    );
+    process.exit(1);
+  }
+  const { repoRoot, repoId } = repoInfo;
+  const filePath = standaloneTaskPath(repoRoot, id);
+  const snapshot = await readEntityFile(filePath);
+  const {
+    id: _omit,
+    "standalone-task-id": _omit2,
+    "caller-worktree-id": _omit3,
+    ...patchBody
+  } = flags;
+  void _omit;
+  void _omit2;
+  void _omit3;
+  const snakePatch = coerceFieldValues(kebabToSnakeKeys(patchBody));
+  if (typeof snakePatch.app_file_approval_by_user === "string") {
+    const v = snakePatch.app_file_approval_by_user;
+    if (v === "true") snakePatch.app_file_approval_by_user = true;
+    else if (v === "false") snakePatch.app_file_approval_by_user = false;
+  }
+  const currentBranch = currentBranchSafe(repoRoot);
+  const callerWorktreeId = await resolveCallerWorktreeId2(
+    repoRoot,
+    currentBranch,
+    repoId,
+    flags["caller-worktree-id"]
+  );
+  const optimistic = { ...snapshot ?? {}, ...snakePatch, id };
+  await writeEntityFile(filePath, optimistic);
+  const mcpArgs = {
+    standalone_task_id: id,
+    ...snakePatch
+  };
+  if (callerWorktreeId) mcpArgs.caller_worktree_id = callerWorktreeId;
+  try {
+    const updated = await mcpCall(
+      "update_standalone_task",
+      mcpArgs
+    );
+    await writeEntityFile(filePath, updated);
+    await updateCursorHash3(repoRoot, id, updated);
+    process.stdout.write(JSON.stringify(updated) + "\n");
+  } catch (err) {
+    await handleMcpWriteError({
+      verb: "standalone-task update",
+      err,
+      filePath,
+      snapshot,
+      repoRoot,
+      id,
+      operation: "update"
+    });
+    process.exit(1);
+  }
+  process.exit(0);
+}
+async function runStandaloneTaskComplete(args) {
+  const { flags } = parseFlagsFromArgs(args);
+  const id = flags.id ?? flags["standalone-task-id"];
+  if (!id) {
+    process.stderr.write(
+      "standalone-task complete: --id <standalone-task-id> is required\n"
+    );
+    process.exit(1);
+  }
+  const repoInfo = await resolveRepoRoot3();
+  if (!repoInfo) {
+    process.stderr.write(
+      "standalone-task complete: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
+    );
+    process.exit(1);
+  }
+  const { repoRoot, repoId } = repoInfo;
+  const currentBranch = currentBranchSafe(repoRoot);
+  const callerWorktreeId = await resolveCallerWorktreeId2(
+    repoRoot,
+    currentBranch,
+    repoId,
+    flags["caller-worktree-id"]
+  );
+  if (!callerWorktreeId) {
+    process.stderr.write(
+      "standalone-task complete: could not resolve caller_worktree_id for this worktree.\n  Run: codebyplan resolve-worktree --cache\n  If this worktree is not registered, run: npx codebyplan setup\n  Then re-run /cbp-standalone-task-complete.\n"
+    );
+    process.exit(1);
+  }
+  const filePath = standaloneTaskPath(repoRoot, id);
+  const snapshot = await readEntityFile(filePath);
+  const optimistic = { ...snapshot ?? {}, id, status: "completed" };
+  await writeEntityFile(filePath, optimistic);
+  try {
+    const completed = await mcpCall(
+      "complete_standalone_task",
+      { standalone_task_id: id, caller_worktree_id: callerWorktreeId }
+    );
+    await writeEntityFile(filePath, completed);
+    await updateCursorHash3(repoRoot, id, completed);
+    process.stdout.write(JSON.stringify(completed) + "\n");
+  } catch (err) {
+    await handleMcpWriteError({
+      verb: "standalone-task complete",
+      err,
+      filePath,
+      snapshot,
+      repoRoot,
+      id,
+      operation: "complete"
+    });
+    process.exit(1);
+  }
+  process.exit(0);
+}
+function printStandaloneTaskHelp() {
+  process.stdout.write(
+    "\n  codebyplan standalone-task <subcommand>\n\n  Standalone tasks are independent work items (no checkpoint parent).\n  Writes go through the standalone MCP tools \u2014 no --checkpoint-id flag.\n\n  Subcommands:\n    create    Create a standalone task (--title required, pass extra fields as --key value)\n    update    Update a standalone task (--id required, then --key value pairs)\n    complete  Complete a standalone task (--id required; caller worktree must resolve)\n\n"
+  );
+}
+async function runStandaloneTaskCommand(args) {
+  const subcommand = args[0];
+  if (subcommand === "create") {
+    await runStandaloneTaskCreate(args.slice(1));
+    return;
+  }
+  if (subcommand === "update") {
+    await runStandaloneTaskUpdate(args.slice(1));
+    return;
+  }
+  if (subcommand === "complete") {
+    await runStandaloneTaskComplete(args.slice(1));
+    return;
+  }
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    printStandaloneTaskHelp();
+    process.exit(0);
+  }
+  if (subcommand) {
+    process.stderr.write(
+      `Unknown standalone-task subcommand: ${subcommand}
+Run 'codebyplan standalone-task help' for usage.
+`
+    );
+  } else {
+    printStandaloneTaskHelp();
+  }
+  process.exit(1);
+}
+var CREATE_KEYS;
+var init_standalone_task = __esm({
+  "src/cli/standalone-task.ts"() {
+    "use strict";
+    init_mcp_client();
+    init_round();
+    init_flags();
+    init_git_utils();
+    init_worktree_cache();
+    init_resolve_worktree();
+    init_local_config();
+    init_state_store();
+    CREATE_KEYS = [
+      "repo_id",
+      "title",
+      "number",
+      "requirements",
+      "status",
+      "context",
+      "qa",
+      "research",
+      "context_development",
+      "resources",
+      "user_context",
+      "is_claude_written",
+      "deadline",
+      "branch_name",
+      "assigned_worktree_id",
+      "caller_worktree_id"
+    ];
+  }
+});
+
+// src/cli/session.ts
+var session_exports = {};
+__export(session_exports, {
+  runSessionCommand: () => runSessionCommand
+});
+async function resolveRepoRoot4() {
+  const found = await findCodebyplanConfig(process.cwd());
+  if (!found?.contents.repo_id) return null;
+  const repoRoot = deriveRepoRoot(found.path);
+  return { repoRoot, repoId: found.contents.repo_id };
+}
+async function updateCursorHash4(repoRoot, entityId, row) {
+  const cursor = await readCursor(repoRoot);
+  if (!cursor) return;
+  const hash = hashEntity(row);
+  cursor.entity_hashes[entityId] = hash;
+  await writeCursor(repoRoot, cursor);
+}
+async function runSessionCreateLog(args) {
+  const { flags } = parseFlagsFromArgs(args);
+  const repoInfo = await resolveRepoRoot4();
+  if (!repoInfo) {
+    process.stderr.write(
+      "session create-log: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
+    );
+    process.exit(1);
+  }
+  const { repoRoot, repoId } = repoInfo;
+  const snakeFlags = coerceFieldValues(kebabToSnakeKeys(flags));
+  const body = {
+    repo_id: repoId,
+    ...snakeFlags
+  };
+  try {
+    const created = await apiBackendPost(new URL(backendSessionLogsEndpoint()).pathname, body);
+    const sessionLog = created.session_log ?? created;
+    const filePath = sessionLogPath(repoRoot);
+    await writeEntityFile(filePath, sessionLog);
+    const sessionLogId = sessionLog.id;
+    if (sessionLogId) {
+      await updateCursorHash4(repoRoot, sessionLogId, sessionLog);
+    }
+    process.stdout.write(JSON.stringify(created) + "\n");
+  } catch (err) {
+    if (err instanceof BackendError) {
+      process.stderr.write(
+        `session create-log: backend error ${err.status}: ${err.message}
+`
+      );
+    } else {
+      process.stderr.write(
+        `session create-log: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}
+async function runSessionUpdateLog(args) {
+  const { flags } = parseFlagsFromArgs(args);
+  const id = flags.id ?? flags["log-id"];
+  if (!id) {
+    process.stderr.write("session update-log: --id <log-id> is required\n");
+    process.exit(1);
+  }
+  const repoInfo = await resolveRepoRoot4();
+  if (!repoInfo) {
+    process.stderr.write(
+      "session update-log: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
+    );
+    process.exit(1);
+  }
+  const { repoRoot } = repoInfo;
+  const filePath = sessionLogPath(repoRoot);
+  const { id: _omit, ...patchBody } = flags;
+  void _omit;
+  const snakePatch = coerceFieldValues(kebabToSnakeKeys(patchBody));
+  const snapshot = await readEntityFile(filePath);
+  const optimistic = { ...snapshot ?? {}, ...snakePatch, id };
+  await writeEntityFile(filePath, optimistic);
+  try {
+    const updated = await apiBackendPatch(
+      `${new URL(backendSessionLogsEndpoint()).pathname}/${id}`,
+      snakePatch
+    );
+    await writeEntityFile(filePath, updated);
+    await updateCursorHash4(repoRoot, id, updated);
+    process.stdout.write(JSON.stringify(updated) + "\n");
+  } catch (err) {
+    if (err instanceof BackendError && err.status < 500) {
+      if (snapshot !== null) {
+        await writeEntityFile(filePath, snapshot);
+      } else {
+        await deleteEntityFile(filePath);
+      }
+      process.stderr.write(
+        `session update-log: backend rejected (${err.status}): ${err.message}
+`
+      );
+    } else {
+      await writeEntityFile(pendingMarkerPath(repoRoot, id), {
+        entity: "session_log",
+        id,
+        operation: "update-log",
+        attempted_at: (/* @__PURE__ */ new Date()).toISOString(),
+        error: err instanceof Error ? err.message : String(err)
+      });
+      process.stderr.write(
+        `session update-log: backend unavailable \u2014 local write kept, pending marker written. Error: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}
+async function runSessionUpdateState(args) {
+  const { flags, booleans } = parseFlagsFromArgs(args);
+  if (booleans.has("action") && !flags["action"]) {
+    process.stderr.write(
+      "session update-state: --action requires a value \u2014 use --action <activate|deactivate>\n"
+    );
+    process.exit(1);
+  }
+  if (!flags["action"]) {
+    process.stderr.write(
+      "session update-state: --action <activate|deactivate> is required\n"
+    );
+    process.exit(1);
+  }
+  const VALID_ACTIONS = /* @__PURE__ */ new Set(["activate", "deactivate"]);
+  if (!VALID_ACTIONS.has(flags["action"])) {
+    process.stderr.write(
+      `session update-state: --action must be 'activate' or 'deactivate', got '${flags["action"]}'
+`
+    );
+    process.exit(1);
+  }
+  const repoInfo = await resolveRepoRoot4();
+  if (!repoInfo) {
+    process.stderr.write(
+      "session update-state: no .codebyplan/repo.json found. Run `codebyplan setup`.\n"
+    );
+    process.exit(1);
+  }
+  const { repoRoot, repoId } = repoInfo;
+  const { ...patchBody } = flags;
+  const snakePatch = coerceFieldValues(kebabToSnakeKeys(patchBody));
+  const stateFilePath = sessionLogPath(repoRoot).replace(
+    "current.json",
+    "state.json"
+  );
+  const snapshot = await readEntityFile(stateFilePath);
+  const optimistic = { ...snapshot ?? {}, ...snakePatch, repo_id: repoId };
+  await writeEntityFile(stateFilePath, optimistic);
+  try {
+    const updated = await apiBackendPatch(
+      new URL(backendSessionStateEndpoint(repoId)).pathname,
+      snakePatch
+    );
+    await writeEntityFile(stateFilePath, updated);
+    process.stdout.write(JSON.stringify(updated) + "\n");
+  } catch (err) {
+    if (err instanceof BackendError && err.status < 500) {
+      if (snapshot !== null) {
+        await writeEntityFile(stateFilePath, snapshot);
+      } else {
+        await deleteEntityFile(stateFilePath);
+      }
+      process.stderr.write(
+        `session update-state: backend rejected (${err.status}): ${err.message}
+`
+      );
+    } else {
+      await writeEntityFile(
+        pendingMarkerPath(repoRoot, `session-state-${repoId}`),
+        {
+          entity: "session_state",
+          repo_id: repoId,
+          operation: "update-state",
+          attempted_at: (/* @__PURE__ */ new Date()).toISOString(),
+          error: err instanceof Error ? err.message : String(err)
+        }
+      );
+      process.stderr.write(
+        `session update-state: backend unavailable \u2014 local write kept, pending marker written. Error: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}
+function printSessionHelp() {
+  process.stdout.write(
+    "\n  codebyplan session <subcommand>\n\n  Subcommands:\n    create-log     Create a session log (fields as --key value pairs)\n    update-log     Update a session log (--id <uuid> required, then --key value pairs)\n    update-state   Update session state for the current repo (--key value pairs)\n\n"
+  );
+}
+async function runSessionCommand(args) {
+  const subcommand = args[0];
+  if (subcommand === "create-log") {
+    await runSessionCreateLog(args.slice(1));
+    return;
+  }
+  if (subcommand === "update-log") {
+    await runSessionUpdateLog(args.slice(1));
+    return;
+  }
+  if (subcommand === "update-state") {
+    await runSessionUpdateState(args.slice(1));
+    return;
+  }
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    printSessionHelp();
+    process.exit(0);
+  }
+  if (subcommand) {
+    process.stderr.write(
+      `Unknown session subcommand: ${subcommand}
+Run 'codebyplan session help' for usage.
+`
+    );
+  } else {
+    printSessionHelp();
+  }
+  process.exit(1);
+}
+var init_session = __esm({
+  "src/cli/session.ts"() {
+    "use strict";
+    init_flags();
+    init_state_store();
+    init_state_client();
+    init_urls();
+  }
+});
+
 // src/lib/migrate-branch-model.ts
 import { readFile as readFile17, writeFile as writeFile14 } from "node:fs/promises";
 import { join as join21 } from "node:path";
@@ -34905,9 +35255,600 @@ var init_tech_stack = __esm({
   }
 });
 
+// src/cli/docs.ts
+var docs_exports = {};
+__export(docs_exports, {
+  libDirName: () => libDirName,
+  runDocs: () => runDocs,
+  sanitizeDocPath: () => sanitizeDocPath,
+  selectDependencies: () => selectDependencies,
+  stripRangePrefix: () => stripRangePrefix
+});
+import { existsSync as existsSync13 } from "node:fs";
+import { mkdir as mkdir12, readFile as readFile26, readdir as readdir6, rm as rm2, writeFile as writeFile20 } from "node:fs/promises";
+import { dirname as dirname13, isAbsolute, join as join37, relative as relative7, sep as sep2 } from "node:path";
+function selectDependencies(deps) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const dep of deps) {
+    const name = dep.name?.trim() ?? "";
+    if (name === "") continue;
+    if (name.startsWith("@types/")) continue;
+    const declared = dep.version?.trim() ?? "";
+    if (SKIP_VERSION_RE.test(declared)) continue;
+    const candidate = {
+      name,
+      declared,
+      isDev: dep.is_dev === true,
+      sourcePath: dep.source_path ?? "package.json"
+    };
+    const existing = byName.get(name);
+    if (!existing || existing.isDev && !candidate.isDev) {
+      byName.set(name, candidate);
+    }
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function stripRangePrefix(range) {
+  return range.replace(/^(>=|\^|~)\s*/, "").trim();
+}
+function sanitizeDocPath(docPath) {
+  const trimmed = docPath.trim();
+  if (trimmed === "") return null;
+  if (trimmed.includes("\0")) return null;
+  if (trimmed.includes("..")) return null;
+  if (trimmed.startsWith("/")) return null;
+  return trimmed.endsWith(".md") ? trimmed : `${trimmed}.md`;
+}
+function libDirName(name) {
+  return name.replace(/\//g, "__");
+}
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from(
+    { length: Math.min(limit, items.length) },
+    async () => {
+      for (; ; ) {
+        const i = next++;
+        if (i >= items.length) return;
+        results[i] = await fn(items[i]);
+      }
+    }
+  );
+  await Promise.all(workers);
+  return results;
+}
+async function resolveExactVersion(projectPath, dep) {
+  const candidateDirs = [projectPath];
+  const sourceDir = join37(projectPath, dirname13(dep.sourcePath));
+  if (sourceDir !== projectPath) candidateDirs.push(sourceDir);
+  for (const base of candidateDirs) {
+    try {
+      const raw = await readFile26(
+        join37(base, "node_modules", dep.name, "package.json"),
+        "utf-8"
+      );
+      const pkg = JSON.parse(raw);
+      if (typeof pkg.version === "string" && pkg.version.length > 0) {
+        return pkg.version;
+      }
+    } catch {
+    }
+  }
+  return stripRangePrefix(dep.declared);
+}
+async function readVendorDocsPath(projectPath) {
+  try {
+    const raw = await readFile26(
+      join37(projectPath, ".codebyplan", "vendor.json"),
+      "utf-8"
+    );
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.vendor_docs_path === "string" && parsed.vendor_docs_path.trim() !== "") {
+      return parsed.vendor_docs_path.trim();
+    }
+  } catch {
+  }
+  return null;
+}
+async function resolveDocsDir(projectPath, flags) {
+  const configured = flags["dir"] ?? await readVendorDocsPath(projectPath) ?? DEFAULT_DOCS_DIR;
+  const absDir = isAbsolute(configured) ? configured : join37(projectPath, configured);
+  const rel = relative7(projectPath, absDir);
+  const relDir = rel === "" || rel.startsWith("..") ? null : rel.split(sep2).join("/");
+  return { absDir, relDir };
+}
+async function readDocsLock(absDir) {
+  const empty = { generated_at: "", libraries: {} };
+  let raw;
+  try {
+    raw = await readFile26(join37(absDir, LOCK_FILE), "utf-8");
+  } catch {
+    return empty;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && parsed.libraries !== null && typeof parsed.libraries === "object") {
+      return {
+        generated_at: typeof parsed.generated_at === "string" ? parsed.generated_at : "",
+        libraries: parsed.libraries
+      };
+    }
+  } catch {
+  }
+  console.warn(`  Warning: corrupt ${LOCK_FILE} \u2014 treating as empty.`);
+  return empty;
+}
+function manifestMatchesLock(manifest, entry) {
+  if (!entry) return false;
+  if (entry.resolved_version !== manifest.resolved_version) return false;
+  if (Object.keys(entry.files).length !== manifest.files.length) return false;
+  return manifest.files.every((f) => entry.files[f.path] === f.content_hash);
+}
+function chunkTotal(manifest) {
+  return manifest.files.reduce((sum, f) => sum + (f.chunk_count ?? 0), 0);
+}
+function isThin(manifest) {
+  return chunkTotal(manifest) < THIN_MIN_CHUNKS || manifest.files.length < THIN_MIN_FILES;
+}
+async function fetchAllFiles(versionId) {
+  const collected = [];
+  let cursor = null;
+  for (; ; ) {
+    const res = await apiGet("/library-docs/export/files", {
+      version_id: versionId,
+      limit: String(FILES_PAGE_LIMIT),
+      ...cursor !== null ? { cursor } : {}
+    });
+    const page = res.data;
+    collected.push(...page.files);
+    if (page.next_cursor === null || page.files.length === 0) break;
+    cursor = page.next_cursor;
+  }
+  return collected;
+}
+function buildLibIndex(name, manifest) {
+  const sorted = [...manifest.files].sort(
+    (a, b) => a.path.localeCompare(b.path)
+  );
+  return [
+    `# ${name}`,
+    "",
+    `- Version: ${manifest.resolved_version}`,
+    `- Resolution: ${manifest.resolution}`,
+    `- Files: ${sorted.length}`,
+    `- Chunks: ${chunkTotal(manifest)}`,
+    "",
+    "## Files",
+    "",
+    ...sorted.map((f) => `- ${sanitizeDocPath(f.path) ?? f.path}`),
+    ""
+  ].join("\n");
+}
+function buildTopIndex(outcomes) {
+  const covered = outcomes.filter(
+    (o) => o.kind === "synced" || o.kind === "unchanged"
+  ).sort((a, b) => a.dep.name.localeCompare(b.dep.name));
+  const uncovered = outcomes.filter((o) => o.kind === "uncovered").sort((a, b) => a.dep.name.localeCompare(b.dep.name));
+  const lines = [
+    "# Dependency Docs Mirror",
+    "",
+    "Generated by `codebyplan docs sync`.",
+    "",
+    "## Libraries",
+    ""
+  ];
+  if (covered.length === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const o of covered) {
+      lines.push(
+        `- ${o.dep.name}@${o.manifest.resolved_version} \u2014 ${o.manifest.files.length} files${isThin(o.manifest) ? " (thin)" : ""}`
+      );
+    }
+  }
+  if (uncovered.length > 0) {
+    lines.push("", "## Uncovered", "");
+    for (const o of uncovered) {
+      lines.push(`- ${o.dep.name}@${o.exactVersion || "?"}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function ensureDocsGitignoreEntry(projectPath, relDir, dryRun) {
+  const entry = `/${relDir}/`;
+  const gitignorePath = join37(projectPath, ".gitignore");
+  let existing = "";
+  try {
+    existing = await readFile26(gitignorePath, "utf-8");
+  } catch {
+  }
+  const lines = existing.split(/\r?\n/).map((l) => l.trim());
+  const variants = /* @__PURE__ */ new Set([entry, entry.slice(1), entry.slice(0, -1), relDir]);
+  if (lines.some((l) => variants.has(l))) return "unchanged";
+  if (!dryRun) {
+    let content = existing;
+    if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+    content += `${GITIGNORE_COMMENT}
+${entry}
+`;
+    await writeFile20(gitignorePath, content, "utf-8");
+  }
+  return "added";
+}
+async function syncOneLibrary(dep, ctx) {
+  const exactVersion = await resolveExactVersion(ctx.projectPath, dep);
+  let manifest;
+  try {
+    const res = await apiGet(
+      "/library-docs/export/manifest",
+      {
+        slug: dep.name,
+        ...exactVersion !== "" ? { version: exactVersion } : {}
+      }
+    );
+    manifest = res.data;
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) {
+      console.log(
+        `  uncovered ${dep.name}@${exactVersion || "?"} \u2014 no docs in the library mirror`
+      );
+      return { kind: "uncovered", dep, exactVersion };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `  Warning: docs sync failed for ${dep.name}@${exactVersion || "?"}: ${message}`
+    );
+    return { kind: "failed", dep, exactVersion, message };
+  }
+  if (!manifest || !Array.isArray(manifest.files) || manifest.files.length === 0) {
+    console.log(
+      `  uncovered ${dep.name}@${exactVersion || "?"} \u2014 no docs in the library mirror`
+    );
+    return { kind: "uncovered", dep, exactVersion };
+  }
+  const unsafeCount = manifest.files.filter(
+    (f) => sanitizeDocPath(f.path) === null
+  ).length;
+  if (unsafeCount > 0) {
+    const sample = manifest.files.find((f) => sanitizeDocPath(f.path) === null);
+    console.warn(
+      `  Warning: ${dep.name}: dropping ${unsafeCount} unsafe doc path(s) from manifest (e.g. ${JSON.stringify(sample?.path)})`
+    );
+    manifest = {
+      ...manifest,
+      files: manifest.files.filter((f) => sanitizeDocPath(f.path) !== null)
+    };
+    if (manifest.files.length === 0) {
+      console.log(
+        `  uncovered ${dep.name}@${exactVersion || "?"} \u2014 no docs in the library mirror`
+      );
+      return { kind: "uncovered", dep, exactVersion };
+    }
+  }
+  const lockEntry = ctx.lock.libraries[dep.name];
+  const libPath = join37(ctx.absDir, libDirName(dep.name));
+  const versionPath = join37(libPath, manifest.resolved_version);
+  if (manifestMatchesLock(manifest, lockEntry)) {
+    console.log(`  unchanged ${dep.name}@${manifest.resolved_version}`);
+    if (!ctx.dryRun && !existsSync13(join37(libPath, "INDEX.md"))) {
+      await mkdir12(libPath, { recursive: true });
+      await writeFile20(
+        join37(libPath, "INDEX.md"),
+        buildLibIndex(dep.name, manifest),
+        "utf-8"
+      );
+    }
+    return { kind: "unchanged", dep, exactVersion, manifest };
+  }
+  const fetched = await fetchAllFiles(manifest.version_id);
+  const sameVersionLockFiles = lockEntry && lockEntry.resolved_version === manifest.resolved_version ? lockEntry.files : {};
+  let written = 0;
+  for (const file of fetched) {
+    const rel = sanitizeDocPath(file.path);
+    if (rel === null) {
+      console.warn(
+        `  Warning: skipping unsafe doc path from ${dep.name}: ${JSON.stringify(file.path)}`
+      );
+      continue;
+    }
+    const target = join37(versionPath, rel);
+    if (sameVersionLockFiles[file.path] === file.content_hash && existsSync13(target)) {
+      continue;
+    }
+    written++;
+    if (!ctx.dryRun) {
+      await mkdir12(dirname13(target), { recursive: true });
+      await writeFile20(target, file.content, "utf-8");
+    }
+  }
+  let removedFiles = 0;
+  if (lockEntry && lockEntry.resolved_version === manifest.resolved_version) {
+    const manifestPaths = new Set(manifest.files.map((f) => f.path));
+    for (const lockedPath of Object.keys(lockEntry.files)) {
+      if (manifestPaths.has(lockedPath)) continue;
+      const rel = sanitizeDocPath(lockedPath);
+      if (rel === null) continue;
+      removedFiles++;
+      if (!ctx.dryRun) await rm2(join37(versionPath, rel), { force: true });
+    }
+  }
+  let removedVersionDirs = 0;
+  let libEntries = [];
+  try {
+    libEntries = await readdir6(libPath, { withFileTypes: true });
+  } catch {
+  }
+  for (const entry of libEntries) {
+    if (!entry.isDirectory() || entry.name === manifest.resolved_version) {
+      continue;
+    }
+    removedVersionDirs++;
+    if (!ctx.dryRun) {
+      await rm2(join37(libPath, entry.name), { recursive: true, force: true });
+    }
+  }
+  if (!ctx.dryRun) {
+    await mkdir12(libPath, { recursive: true });
+    await writeFile20(
+      join37(libPath, "INDEX.md"),
+      buildLibIndex(dep.name, manifest),
+      "utf-8"
+    );
+  }
+  const removals = removedFiles + removedVersionDirs;
+  console.log(
+    ctx.dryRun ? `  would sync ${dep.name}@${manifest.resolved_version} \u2014 ${written} file(s), ${removals} removal(s)` : `  synced ${dep.name}@${manifest.resolved_version} \u2014 ${written} file(s) written${removals > 0 ? `, ${removals} removed` : ""}${isThin(manifest) ? " (thin)" : ""}`
+  );
+  return {
+    kind: "synced",
+    dep,
+    exactVersion,
+    manifest,
+    written,
+    removedFiles,
+    removedVersionDirs
+  };
+}
+async function runDocsSync() {
+  const flags = parseFlags(4);
+  const dryRun = hasFlag("dry-run", 4);
+  await validateAuth();
+  const config = await resolveConfig(flags);
+  const { repoId, projectPath } = config;
+  const { absDir, relDir } = await resolveDocsDir(projectPath, flags);
+  console.log(`
+  CodeByPlan Docs Sync`);
+  console.log(`  Repo: ${repoId}`);
+  console.log(`  Path: ${projectPath}`);
+  console.log(`  Dir:  ${absDir}`);
+  if (dryRun) console.log(`  Mode: dry-run`);
+  if (hasFlag("include-dev", 4)) {
+    console.log(`  Dev dependencies: included (already the default)`);
+  }
+  console.log();
+  const started = Date.now();
+  const { dependencies } = await scanAllDependencies(projectPath);
+  const selected = selectDependencies(dependencies);
+  if (selected.length === 0) {
+    console.log("  No dependencies eligible for docs sync.\n");
+    return;
+  }
+  console.log(`  ${selected.length} dependencies after skip rules + dedup
+`);
+  const lock = await readDocsLock(absDir);
+  const ctx = { projectPath, absDir, lock, dryRun };
+  const outcomes = await mapWithConcurrency(
+    selected,
+    SYNC_CONCURRENCY,
+    (dep) => syncOneLibrary(dep, ctx)
+  );
+  if (!dryRun) {
+    await mkdir12(absDir, { recursive: true });
+    await writeFile20(join37(absDir, "INDEX.md"), buildTopIndex(outcomes), "utf-8");
+    const libraries = {};
+    for (const o of outcomes) {
+      if (o.kind === "synced" || o.kind === "unchanged") {
+        libraries[o.dep.name] = {
+          version: o.exactVersion,
+          resolved_version: o.manifest.resolved_version,
+          resolution: o.manifest.resolution,
+          files: Object.fromEntries(
+            o.manifest.files.map((f) => [f.path, f.content_hash])
+          )
+        };
+      } else if (o.kind === "failed") {
+        const previous = lock.libraries[o.dep.name];
+        if (previous) libraries[o.dep.name] = previous;
+      }
+    }
+    const sortedLibraries = {};
+    for (const name of Object.keys(libraries).sort()) {
+      sortedLibraries[name] = libraries[name];
+    }
+    const newLock = {
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      libraries: sortedLibraries
+    };
+    await writeFile20(
+      join37(absDir, LOCK_FILE),
+      JSON.stringify(newLock, null, 2) + "\n",
+      "utf-8"
+    );
+  }
+  if (relDir !== null) {
+    const action = await ensureDocsGitignoreEntry(projectPath, relDir, dryRun);
+    if (action === "added") {
+      console.log(
+        dryRun ? `
+  would add /${relDir}/ to .gitignore` : `
+  Added /${relDir}/ to .gitignore`
+      );
+    }
+  }
+  const synced = outcomes.filter((o) => o.kind === "synced").length;
+  const unchanged = outcomes.filter((o) => o.kind === "unchanged").length;
+  const uncovered = outcomes.filter((o) => o.kind === "uncovered").length;
+  const failed = outcomes.filter((o) => o.kind === "failed").length;
+  const thin = outcomes.filter(
+    (o) => (o.kind === "synced" || o.kind === "unchanged") && isThin(o.manifest)
+  ).length;
+  const durationS = ((Date.now() - started) / 1e3).toFixed(1);
+  if (failed > 0) {
+    console.warn(`  Warning: ${failed} libraries failed to sync (see above).`);
+  }
+  console.log(
+    `
+  Docs sync ${dryRun ? "plan " : ""}complete: ${synced} synced, ${unchanged} unchanged, ${uncovered} uncovered, ${thin} thin (${durationS}s).
+`
+  );
+}
+async function countFilesRecursively(dirPath) {
+  let entries;
+  try {
+    entries = await readdir6(dirPath, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let count = 0;
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      count += await countFilesRecursively(join37(dirPath, entry.name));
+    } else if (entry.isFile()) {
+      count++;
+    }
+  }
+  return count;
+}
+async function runDocsStatus() {
+  const flags = parseFlags(4);
+  const projectPath = flags["path"] ?? process.cwd();
+  const { absDir } = await resolveDocsDir(projectPath, flags);
+  console.log(`
+  CodeByPlan Docs Status`);
+  console.log(`  Dir: ${absDir}
+`);
+  let raw;
+  try {
+    raw = await readFile26(join37(absDir, LOCK_FILE), "utf-8");
+  } catch {
+    console.log(
+      `  No ${LOCK_FILE} found \u2014 run \`codebyplan docs sync\` first.
+`
+    );
+    return;
+  }
+  let lock;
+  try {
+    lock = JSON.parse(raw);
+    if (lock === null || typeof lock.libraries !== "object") {
+      throw new Error("malformed lock");
+    }
+  } catch {
+    console.warn(
+      `  Warning: corrupt ${LOCK_FILE} \u2014 run \`codebyplan docs sync\` to regenerate.
+`
+    );
+    return;
+  }
+  const names = Object.keys(lock.libraries).sort();
+  if (names.length === 0) {
+    console.log("  Lock contains no libraries.\n");
+    return;
+  }
+  let outOfSync = 0;
+  for (const name of names) {
+    const entry = lock.libraries[name];
+    const versionPath = join37(absDir, libDirName(name), entry.resolved_version);
+    const expected = Object.keys(entry.files).length;
+    if (!existsSync13(versionPath)) {
+      outOfSync++;
+      console.log(
+        `  ${name}@${entry.resolved_version} \u2014 MISSING dir (${expected} files in lock)`
+      );
+      continue;
+    }
+    const onDisk = await countFilesRecursively(versionPath);
+    if (onDisk === expected) {
+      console.log(`  ${name}@${entry.resolved_version} \u2014 ok (${onDisk} files)`);
+    } else {
+      outOfSync++;
+      console.log(
+        `  ${name}@${entry.resolved_version} \u2014 MISMATCH (${onDisk} files on disk / ${expected} in lock)`
+      );
+    }
+  }
+  console.log(
+    outOfSync === 0 ? `
+  ${names.length} libraries in sync.
+` : `
+  ${outOfSync} of ${names.length} libraries out of sync \u2014 run \`codebyplan docs sync\`.
+`
+  );
+}
+function printUsage() {
+  console.log(`
+  codebyplan docs
+
+  Local dependency docs mirror \u2014 sync covered library docs from CodeByPlan.
+
+  Subcommands:
+    sync      Fetch doc files for installed dependencies into the local mirror
+    status    Offline report of lock vs on-disk mirror state (no network)
+
+  Flags (sync):
+    --path <dir>     Project root directory (default: cwd)
+    --dir <dir>      Mirror directory (default: .codebyplan/vendor.json
+                     vendor_docs_path, else ${DEFAULT_DOCS_DIR})
+    --include-dev    Explicitly include dev dependencies (already the default)
+    --dry-run        Print the full sync plan without writing any files
+
+  Flags (status):
+    --path <dir>     Project root directory (default: cwd)
+    --dir <dir>      Mirror directory (same resolution as sync)
+`);
+}
+async function runDocs() {
+  const subcommand = process.argv[3];
+  if (subcommand === "sync") {
+    await runDocsSync();
+    return;
+  }
+  if (subcommand === "status") {
+    await runDocsStatus();
+    return;
+  }
+  if (subcommand === void 0 || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    printUsage();
+    return;
+  }
+  console.error(
+    `  docs: unknown subcommand '${subcommand}'. Run 'codebyplan docs help' for usage.`
+  );
+  process.exitCode = 1;
+}
+var DEFAULT_DOCS_DIR, LOCK_FILE, SYNC_CONCURRENCY, FILES_PAGE_LIMIT, THIN_MIN_CHUNKS, THIN_MIN_FILES, GITIGNORE_COMMENT, SKIP_VERSION_RE;
+var init_docs = __esm({
+  "src/cli/docs.ts"() {
+    "use strict";
+    init_flags();
+    init_api();
+    init_tech_detect();
+    DEFAULT_DOCS_DIR = "docs/dependencies";
+    LOCK_FILE = "docs.lock.json";
+    SYNC_CONCURRENCY = 5;
+    FILES_PAGE_LIMIT = 200;
+    THIN_MIN_CHUNKS = 25;
+    THIN_MIN_FILES = 5;
+    GITIGNORE_COMMENT = "# DocsByPlan local mirror";
+    SKIP_VERSION_RE = /^(workspace:|file:|link:|git\+|https?:)/;
+  }
+});
+
 // src/lib/check-baseline.ts
 import { readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join37 } from "node:path";
+import { join as join38 } from "node:path";
 function emptyBaseline() {
   return {
     lint: { known_failing: [] },
@@ -34917,7 +35858,7 @@ function emptyBaseline() {
   };
 }
 function loadBaseline(projectRoot) {
-  const filePath = join37(projectRoot, BASELINE_FILENAME);
+  const filePath = join38(projectRoot, BASELINE_FILENAME);
   try {
     const raw = readFileSync12(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -34941,7 +35882,7 @@ function loadBaseline(projectRoot) {
   }
 }
 function saveBaseline(projectRoot, baseline) {
-  const filePath = join37(projectRoot, BASELINE_FILENAME);
+  const filePath = join38(projectRoot, BASELINE_FILENAME);
   writeFileSync7(filePath, JSON.stringify(baseline, null, 2) + "\n", "utf-8");
 }
 function diffBaseline(check, currentFailingPackages, baseline) {
@@ -34990,8 +35931,8 @@ var init_check_baseline = __esm({
 });
 
 // src/lib/check.ts
-import { readFileSync as readFileSync13, existsSync as existsSync13 } from "node:fs";
-import { join as join38 } from "node:path";
+import { readFileSync as readFileSync13, existsSync as existsSync14 } from "node:fs";
+import { join as join39 } from "node:path";
 import { spawnSync as spawnSync10 } from "node:child_process";
 function hasSentinelValue(arrays) {
   const SENTINELS = /* @__PURE__ */ new Set([
@@ -35001,6 +35942,11 @@ function hasSentinelValue(arrays) {
   ]);
   return arrays.some((arr) => arr.some((v) => SENTINELS.has(v)));
 }
+function resolveNewFailures(check, failingPackages, baseline, updateBaseline, noBaseline) {
+  if (updateBaseline) return [];
+  if (noBaseline) return failingPackages;
+  return diffBaseline(check, failingPackages, baseline);
+}
 function defaultSpawnFn(command, opts) {
   const result = spawnSync10(command, {
     shell: true,
@@ -35054,9 +36000,9 @@ function parseFailingPackagesFromSummary(summaryPath) {
   return Array.from(failing).sort();
 }
 function resolveTurboBin(projectRoot) {
-  const localBin = join38(projectRoot, "node_modules", ".bin", "turbo");
-  if (existsSync13(localBin)) return localBin;
-  const workspaceRootBin = join38(
+  const localBin = join39(projectRoot, "node_modules", ".bin", "turbo");
+  if (existsSync14(localBin)) return localBin;
+  const workspaceRootBin = join39(
     projectRoot,
     "..",
     "..",
@@ -35064,7 +36010,7 @@ function resolveTurboBin(projectRoot) {
     ".bin",
     "turbo"
   );
-  if (existsSync13(workspaceRootBin)) return workspaceRootBin;
+  if (existsSync14(workspaceRootBin)) return workspaceRootBin;
   return TURBO_NOT_FOUND_SENTINEL;
 }
 function runTurboWithSummary(task, projectRoot, spawnFn) {
@@ -35101,13 +36047,20 @@ function runCheck(opts) {
     projectRoot = process.cwd(),
     changedFiles,
     spawnFn = defaultSpawnFn,
-    updateBaseline = false,
+    updateBaseline: updateBaselineOpt = false,
+    noBaseline = false,
     loadBaselineFn = loadBaseline,
     saveBaselineFn = saveBaseline
   } = opts;
   if (changedFiles !== void 0) {
     process.stderr.write("check: --files is ignored in whole-repo mode\n");
   }
+  if (noBaseline && updateBaselineOpt) {
+    process.stderr.write(
+      "check: --no-baseline and --update-baseline are mutually exclusive \u2014 ignoring --update-baseline (strict mode never writes the baseline)\n"
+    );
+  }
+  const updateBaseline = noBaseline ? false : updateBaselineOpt;
   const baseline = loadBaselineFn(projectRoot);
   const results = [];
   {
@@ -35146,7 +36099,13 @@ function runCheck(opts) {
       command: lintCommand
     } = runTurboWithSummary("lint", projectRoot, spawnFn);
     currentFailing.lint = failingPackages;
-    const newFailures = updateBaseline ? [] : diffBaseline("lint", failingPackages, baseline);
+    const newFailures = resolveNewFailures(
+      "lint",
+      failingPackages,
+      baseline,
+      updateBaseline,
+      noBaseline
+    );
     results.push({
       check: "lint",
       status: newFailures.length > 0 ? "fail" : "pass",
@@ -35165,7 +36124,13 @@ function runCheck(opts) {
       command: typecheckCommand
     } = runTurboWithSummary("typecheck", projectRoot, spawnFn);
     currentFailing.typecheck = failingPackages;
-    const newFailures = updateBaseline ? [] : diffBaseline("typecheck", failingPackages, baseline);
+    const newFailures = resolveNewFailures(
+      "typecheck",
+      failingPackages,
+      baseline,
+      updateBaseline,
+      noBaseline
+    );
     results.push({
       check: "typecheck",
       status: newFailures.length > 0 ? "fail" : "pass",
@@ -35184,7 +36149,13 @@ function runCheck(opts) {
       command: testsCommand
     } = runTurboWithSummary("test", projectRoot, spawnFn);
     currentFailing.tests = failingPackages;
-    const newFailures = updateBaseline ? [] : diffBaseline("tests", failingPackages, baseline);
+    const newFailures = resolveNewFailures(
+      "tests",
+      failingPackages,
+      baseline,
+      updateBaseline,
+      noBaseline
+    );
     results.push({
       check: "tests",
       status: newFailures.length > 0 ? "fail" : "pass",
@@ -35210,7 +36181,14 @@ function runCheck(opts) {
         };
       }
       const currentGhsaIds = parseAuditJson(result.stdout);
-      const newAdvisories = updateBaseline ? [] : diffAudit(currentGhsaIds, baseline.audit.ghsa_ids);
+      let newAdvisories;
+      if (updateBaseline) {
+        newAdvisories = [];
+      } else if (noBaseline) {
+        newAdvisories = currentGhsaIds;
+      } else {
+        newAdvisories = diffAudit(currentGhsaIds, baseline.audit.ghsa_ids);
+      }
       results.push({
         check: "audit",
         status: newAdvisories.length > 0 ? "fail" : "pass",
@@ -35346,7 +36324,7 @@ function runCheck(opts) {
   }
   const hard_fail_checks = results.filter((r) => r.status === "fail").map((r) => r.check);
   const any_failed = hard_fail_checks.length > 0;
-  return { results, any_failed, hard_fail_checks };
+  return { results, any_failed, hard_fail_checks, no_baseline: noBaseline };
 }
 var SUMMARY_UNREADABLE, SPAWN_KILLED, TURBO_NOT_FOUND_SENTINEL;
 var init_check = __esm({
@@ -35369,6 +36347,7 @@ function parseCheckArgs(args) {
   let json = false;
   let files;
   let updateBaseline = false;
+  let noBaseline = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--scope") {
@@ -35388,6 +36367,8 @@ function parseCheckArgs(args) {
       json = true;
     } else if (arg === "--update-baseline") {
       updateBaseline = true;
+    } else if (arg === "--no-baseline") {
+      noBaseline = true;
     } else if (arg === "--files") {
       const val = args[i + 1];
       if (val !== void 0 && !val.startsWith("--")) {
@@ -35401,15 +36382,16 @@ function parseCheckArgs(args) {
       }
     }
   }
-  return { scope, json, files, updateBaseline };
+  return { scope, json, files, updateBaseline, noBaseline };
 }
 function emitTable(result) {
+  const strict = result.no_baseline === true;
   const headers = ["check", "status", "exit_code", "new_failures", "command"];
   const rows = result.results.map((r) => {
     let newFailuresCell = "";
     if (r.new_failures !== void 0) {
       if (r.new_failures.length === 0 && r.executed) {
-        newFailuresCell = r.exit_code !== null && r.exit_code !== 0 ? "(baselined)" : "";
+        newFailuresCell = !strict && r.exit_code !== null && r.exit_code !== 0 ? "(baselined)" : "";
       } else {
         newFailuresCell = r.new_failures.join(", ");
       }
@@ -35436,6 +36418,11 @@ function emitTable(result) {
     );
   }
   lines.push("");
+  if (strict) {
+    lines.push(
+      "MODE: strict (--no-baseline) \u2014 baseline ignored; every failure counts"
+    );
+  }
   if (result.any_failed) {
     lines.push(
       `FAILED: ${result.hard_fail_checks.join(", ")} (${result.hard_fail_checks.length} check(s) failed)`
@@ -35468,12 +36455,13 @@ function runCheckCommand(args) {
   if (parsed === null) {
     return;
   }
-  const { scope, json, files, updateBaseline } = parsed;
+  const { scope, json, files, updateBaseline, noBaseline } = parsed;
   const result = runCheck({
     scope,
     changedFiles: files,
     // NO-OP in whole-repo mode; notice emitted by runCheck
-    updateBaseline
+    updateBaseline,
+    noBaseline
   });
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
@@ -37116,11 +38104,11 @@ var generate_exports = {};
 __export(generate_exports, {
   runGenerate: () => runGenerate
 });
-import { readFile as readFile26, mkdir as mkdir12, writeFile as writeFile20 } from "node:fs/promises";
-import { join as join45, resolve as resolve11 } from "node:path";
+import { readFile as readFile27, mkdir as mkdir13, writeFile as writeFile21 } from "node:fs/promises";
+import { join as join46, resolve as resolve11 } from "node:path";
 async function readJsonFile4(filePath) {
   try {
-    const raw = await readFile26(filePath, "utf-8");
+    const raw = await readFile27(filePath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -37128,7 +38116,7 @@ async function readJsonFile4(filePath) {
 }
 async function readPkgName(absPath) {
   try {
-    const raw = await readFile26(join45(absPath, "package.json"), "utf-8");
+    const raw = await readFile27(join46(absPath, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     return typeof pkg.name === "string" ? pkg.name : null;
   } catch {
@@ -37142,7 +38130,7 @@ async function runGenerate(opts) {
   const rootDir = resolve11(projectDir);
   let packageManager;
   try {
-    const raw = await readFile26(join45(rootDir, "package.json"), "utf-8");
+    const raw = await readFile27(join46(rootDir, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     if (typeof pkg.packageManager === "string") {
       packageManager = pkg.packageManager;
@@ -37150,7 +38138,7 @@ async function runGenerate(opts) {
   } catch {
   }
   const serverJson = await readJsonFile4(
-    join45(rootDir, ".codebyplan", "server.json")
+    join46(rootDir, ".codebyplan", "server.json")
   );
   const ports = [];
   for (const alloc of serverJson?.port_allocations ?? []) {
@@ -37163,7 +38151,7 @@ async function runGenerate(opts) {
     }
   }
   const gitJson = await readJsonFile4(
-    join45(rootDir, ".codebyplan", "git.json")
+    join46(rootDir, ".codebyplan", "git.json")
   );
   const branchModel = gitJson?.branch_config?.production ? {
     production: gitJson.branch_config.production,
@@ -37172,7 +38160,7 @@ async function runGenerate(opts) {
     )
   } : void 0;
   const shipmentJson = await readJsonFile4(
-    join45(rootDir, ".codebyplan", "shipment.json")
+    join46(rootDir, ".codebyplan", "shipment.json")
   );
   const shipmentSurfaces = [];
   const rawSurfaces = shipmentJson?.shipment?.surfaces ?? shipmentJson?.surfaces ?? {};
@@ -37243,10 +38231,10 @@ async function runGenerate(opts) {
   const structureMdContent = generateStructureMd(config);
   const agentsContent = generateAgentsMd(structureMdContent);
   if (check) {
-    const agentsMdPath2 = join45(rootDir, "AGENTS.md");
+    const agentsMdPath2 = join46(rootDir, "AGENTS.md");
     let existingAgents = null;
     try {
-      existingAgents = await readFile26(agentsMdPath2, "utf-8");
+      existingAgents = await readFile27(agentsMdPath2, "utf-8");
     } catch {
       existingAgents = null;
     }
@@ -37282,16 +38270,16 @@ async function runGenerate(opts) {
     process.stdout.write(agentsContent);
     return;
   }
-  const outputDir = join45(rootDir, ".claude", "generated");
-  await mkdir12(outputDir, { recursive: true });
-  const outputPath = join45(outputDir, "structure.md");
-  await writeFile20(outputPath, structureMdContent, "utf-8");
+  const outputDir = join46(rootDir, ".claude", "generated");
+  await mkdir13(outputDir, { recursive: true });
+  const outputPath = join46(outputDir, "structure.md");
+  await writeFile21(outputPath, structureMdContent, "utf-8");
   process.stdout.write(`Wrote: .claude/generated/structure.md
 `);
-  const agentsMdPath = join45(rootDir, "AGENTS.md");
+  const agentsMdPath = join46(rootDir, "AGENTS.md");
   let existingAgentsContent = null;
   try {
-    existingAgentsContent = await readFile26(agentsMdPath, "utf-8");
+    existingAgentsContent = await readFile27(agentsMdPath, "utf-8");
   } catch {
     existingAgentsContent = null;
   }
@@ -37299,7 +38287,7 @@ async function runGenerate(opts) {
     process.stdout.write(`Up to date: AGENTS.md
 `);
   } else {
-    await writeFile20(agentsMdPath, agentsContent, "utf-8");
+    await writeFile21(agentsMdPath, agentsContent, "utf-8");
     process.stdout.write(`Wrote: AGENTS.md
 `);
   }
@@ -37319,11 +38307,11 @@ __export(readme_exports, {
   runReadme: () => runReadme,
   runReadmeCommand: () => runReadmeCommand
 });
-import { readFile as readFile27, writeFile as writeFile21 } from "node:fs/promises";
-import { join as join46, resolve as resolve12, relative as relative8 } from "node:path";
+import { readFile as readFile28, writeFile as writeFile22 } from "node:fs/promises";
+import { join as join47, resolve as resolve12, relative as relative9 } from "node:path";
 async function readJsonFile5(filePath) {
   try {
-    const raw = await readFile27(filePath, "utf-8");
+    const raw = await readFile28(filePath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -37392,7 +38380,7 @@ async function discoverUnits(rootDir, rootPkgJson) {
   const discovered = await discoverMonorepoApps(rootDir);
   for (const app of discovered) {
     const pkgJson = await readJsonFile5(
-      join46(app.absPath, "package.json")
+      join47(app.absPath, "package.json")
     );
     pkgJsonByPath.set(app.absPath, pkgJson);
     allPackages.push({
@@ -37418,7 +38406,7 @@ async function runReadme(opts) {
   const init = opts.init ?? opts["init"] ?? false;
   const rootDir = resolve12(projectDir);
   const rootPkgJson = await readJsonFile5(
-    join46(rootDir, "package.json")
+    join47(rootDir, "package.json")
   );
   const { units, allPackages, pkgJsonByPath } = await discoverUnits(
     rootDir,
@@ -37427,11 +38415,11 @@ async function runReadme(opts) {
   const driftUnits = [];
   const missingUnits = [];
   for (const unit of units) {
-    const readmePath = join46(unit.absPath, "README.md");
-    const relPath = unit.isRoot ? "README.md" : join46(relative8(rootDir, unit.absPath), "README.md");
+    const readmePath = join47(unit.absPath, "README.md");
+    const relPath = unit.isRoot ? "README.md" : join47(relative9(rootDir, unit.absPath), "README.md");
     let existingContent = null;
     try {
-      existingContent = await readFile27(readmePath, "utf-8");
+      existingContent = await readFile28(readmePath, "utf-8");
     } catch {
       existingContent = null;
     }
@@ -37466,7 +38454,7 @@ ${newContent}
 `
         );
       } else {
-        await writeFile21(readmePath, newContent, "utf-8");
+        await writeFile22(readmePath, newContent, "utf-8");
         process.stdout.write(`Wrote (scaffold): ${relPath}
 `);
       }
@@ -37504,7 +38492,7 @@ ${newContent}
 `
         );
       } else {
-        await writeFile21(readmePath, newContent, "utf-8");
+        await writeFile22(readmePath, newContent, "utf-8");
         process.stdout.write(`Wrote (refresh): ${relPath}
 `);
       }
@@ -37523,7 +38511,7 @@ ${newContent}
 `
           );
         } else {
-          await writeFile21(readmePath, newContent, "utf-8");
+          await writeFile22(readmePath, newContent, "utf-8");
           process.stdout.write(`Wrote (init): ${relPath}
 `);
         }
@@ -37611,15 +38599,15 @@ __export(migrate_memory_exports, {
   runMigrateMemory: () => runMigrateMemory
 });
 import {
-  readFile as readFile28,
-  writeFile as writeFile22,
-  mkdir as mkdir13,
+  readFile as readFile29,
+  writeFile as writeFile23,
+  mkdir as mkdir14,
   unlink as unlink6,
   rmdir,
-  readdir as readdir6
+  readdir as readdir7
 } from "node:fs/promises";
-import { existsSync as existsSync20 } from "node:fs";
-import { join as join47, resolve as resolve13, dirname as dirname14, sep as sep3 } from "node:path";
+import { existsSync as existsSync21 } from "node:fs";
+import { join as join48, resolve as resolve13, dirname as dirname15, sep as sep4 } from "node:path";
 import { homedir as homedir8 } from "node:os";
 function encodeProjectPath(absPath) {
   return resolve13(absPath).replace(/[/\\]/g, "-");
@@ -37630,7 +38618,7 @@ function resolveAutoMemoryDir(opts) {
   }
   const projectDir = opts.projectDir ?? process.cwd();
   const encoded = encodeProjectPath(projectDir);
-  return join47(homedir8(), ".claude", "projects", encoded, "memory");
+  return join48(homedir8(), ".claude", "projects", encoded, "memory");
 }
 function parseFrontmatter(content) {
   content = content.replace(/\r\n/g, "\n");
@@ -37689,17 +38677,17 @@ function parseFrontmatter(content) {
 async function inventoryFiles(dir) {
   let filenames;
   try {
-    const entries = await readdir6(dir);
+    const entries = await readdir7(dir);
     filenames = entries.filter((f) => f.endsWith(".md") && f !== "MEMORY.md").sort();
   } catch {
     return [];
   }
   const results = [];
   for (const filename of filenames) {
-    const sourcePath = join47(dir, filename);
+    const sourcePath = join48(dir, filename);
     let raw;
     try {
-      raw = await readFile28(sourcePath, "utf-8");
+      raw = await readFile29(sourcePath, "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       results.push({
@@ -37785,9 +38773,9 @@ async function applyPlan(plan, opts) {
     if (entry.suggested_action !== "keep") continue;
     if (!entry.suggested_target?.startsWith("nested:")) continue;
     const relPath = entry.suggested_target.slice("nested:".length);
-    const targetDir = resolve13(join47(projectDir, relPath));
-    const targetFile = join47(targetDir, "CLAUDE.md");
-    if (!targetDir.startsWith(resolve13(projectDir) + sep3)) {
+    const targetDir = resolve13(join48(projectDir, relPath));
+    const targetFile = join48(targetDir, "CLAUDE.md");
+    if (!targetDir.startsWith(resolve13(projectDir) + sep4)) {
       process.stderr.write(
         `migrate-memory: skipping unsafe suggested_target "${entry.suggested_target}" \u2014 resolves outside projectDir
 `
@@ -37806,7 +38794,7 @@ ${anchor}
       process.stdout.write(`[dry-run] Would create/append: ${targetFile}
 `);
       if (resolve13(entry.source_path).startsWith(
-        resolve13(plan.auto_memory_dir) + sep3
+        resolve13(plan.auto_memory_dir) + sep4
       )) {
         process.stdout.write(
           `[dry-run] Would delete migrated keep source: ${entry.source_path}
@@ -37815,16 +38803,16 @@ ${anchor}
       }
       continue;
     }
-    await mkdir13(targetDir, { recursive: true });
+    await mkdir14(targetDir, { recursive: true });
     let existing = "";
     try {
-      existing = await readFile28(targetFile, "utf-8");
+      existing = await readFile29(targetFile, "utf-8");
     } catch {
     }
     if (!existing.includes(anchor)) {
-      await writeFile22(targetFile, existing + appendContent, "utf-8");
+      await writeFile23(targetFile, existing + appendContent, "utf-8");
     }
-    if (resolve13(entry.source_path).startsWith(resolve13(plan.auto_memory_dir) + sep3)) {
+    if (resolve13(entry.source_path).startsWith(resolve13(plan.auto_memory_dir) + sep4)) {
       try {
         await unlink6(entry.source_path);
       } catch {
@@ -37836,7 +38824,7 @@ ${anchor}
       );
     }
   }
-  const rootClaudeMd = join47(projectDir, ".claude", "CLAUDE.md");
+  const rootClaudeMd = join48(projectDir, ".claude", "CLAUDE.md");
   if (dryRun) {
     process.stdout.write(
       `[dry-run] Would ensure ${rootClaudeMd} contains: ${IMPORT_LINE}
@@ -37845,12 +38833,12 @@ ${anchor}
   } else {
     let claudeMdContent = "";
     try {
-      claudeMdContent = await readFile28(rootClaudeMd, "utf-8");
+      claudeMdContent = await readFile29(rootClaudeMd, "utf-8");
     } catch {
-      await mkdir13(dirname14(rootClaudeMd), { recursive: true });
+      await mkdir14(dirname15(rootClaudeMd), { recursive: true });
     }
     if (!claudeMdContent.includes(IMPORT_LINE)) {
-      await writeFile22(
+      await writeFile23(
         rootClaudeMd,
         claudeMdContent + `
 ${IMPORT_LINE}
@@ -37862,7 +38850,7 @@ ${IMPORT_LINE}
   for (const entry of plan.entries) {
     if (entry.suggested_action !== "drop") continue;
     if (!resolve13(entry.source_path).startsWith(
-      resolve13(plan.auto_memory_dir) + sep3
+      resolve13(plan.auto_memory_dir) + sep4
     )) {
       process.stderr.write(
         `migrate-memory: skipping delete of "${entry.source_path}" \u2014 resolves outside auto_memory_dir
@@ -37880,13 +38868,13 @@ ${IMPORT_LINE}
     } catch {
     }
   }
-  const memoryMd = join47(plan.auto_memory_dir, "MEMORY.md");
-  const safeRmdirBase = join47(homedir8(), ".claude", "projects");
+  const memoryMd = join48(plan.auto_memory_dir, "MEMORY.md");
+  const safeRmdirBase = join48(homedir8(), ".claude", "projects");
   if (dryRun) {
     process.stdout.write(`[dry-run] Would delete MEMORY.md: ${memoryMd}
 `);
   } else {
-    if (resolve13(plan.auto_memory_dir).startsWith(safeRmdirBase + sep3)) {
+    if (resolve13(plan.auto_memory_dir).startsWith(safeRmdirBase + sep4)) {
       try {
         await unlink6(memoryMd);
       } catch {
@@ -37904,14 +38892,14 @@ ${IMPORT_LINE}
 `
     );
   } else {
-    if (!resolve13(plan.auto_memory_dir).startsWith(safeRmdirBase + sep3)) {
+    if (!resolve13(plan.auto_memory_dir).startsWith(safeRmdirBase + sep4)) {
       process.stderr.write(
         `migrate-memory: skipping rmdir of "${plan.auto_memory_dir}" \u2014 not under ~/.claude/projects
 `
       );
     } else {
       try {
-        const remaining = await readdir6(plan.auto_memory_dir);
+        const remaining = await readdir7(plan.auto_memory_dir);
         if (remaining.length === 0) {
           await rmdir(plan.auto_memory_dir);
         }
@@ -37934,7 +38922,7 @@ async function runMigrateMemory(opts) {
   if (applyFile) {
     let planJson;
     try {
-      planJson = await readFile28(resolve13(applyFile), "utf-8");
+      planJson = await readFile29(resolve13(applyFile), "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(
@@ -37962,7 +38950,7 @@ async function runMigrateMemory(opts) {
     );
     return;
   }
-  if (!existsSync20(autoMemoryDir)) {
+  if (!existsSync21(autoMemoryDir)) {
     process.stdout.write(
       JSON.stringify(
         {
@@ -38004,8 +38992,8 @@ var init_migrate_memory = __esm({
 });
 
 // src/lib/claude-mode-audit.ts
-import { readdirSync as readdirSync7, readFileSync as readFileSync19, existsSync as existsSync21 } from "node:fs";
-import { join as join48, basename as basename2 } from "node:path";
+import { readdirSync as readdirSync7, readFileSync as readFileSync19, existsSync as existsSync22 } from "node:fs";
+import { join as join49, basename as basename2 } from "node:path";
 function parseFrontmatter2(content) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (!match) return {};
@@ -38082,20 +39070,20 @@ function auditSkill(filePath) {
 }
 function auditMode(templatesDir) {
   const entries = [];
-  const agentsDir = join48(templatesDir, "agents");
-  if (existsSync21(agentsDir)) {
+  const agentsDir = join49(templatesDir, "agents");
+  if (existsSync22(agentsDir)) {
     const agentFiles = readdirSync7(agentsDir).filter((f) => f.endsWith(".md")).sort();
     for (const f of agentFiles) {
-      entries.push(auditAgent(join48(agentsDir, f)));
+      entries.push(auditAgent(join49(agentsDir, f)));
     }
   }
-  const skillsDir = join48(templatesDir, "skills");
-  if (existsSync21(skillsDir)) {
+  const skillsDir = join49(templatesDir, "skills");
+  if (existsSync22(skillsDir)) {
     const skillDirs = readdirSync7(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
     for (const dir of skillDirs) {
-      if (existsSync21(join48(skillsDir, dir, "PROVENANCE.md"))) continue;
-      const skillMd = join48(skillsDir, dir, "SKILL.md");
-      if (existsSync21(skillMd)) {
+      if (existsSync22(join49(skillsDir, dir, "PROVENANCE.md"))) continue;
+      const skillMd = join49(skillsDir, dir, "SKILL.md");
+      if (existsSync22(skillMd)) {
         entries.push(auditSkill(skillMd));
       }
     }
@@ -39149,7 +40137,7 @@ var validate_waves_exports = {};
 __export(validate_waves_exports, {
   runValidateWavesCommand: () => runValidateWavesCommand
 });
-import { readFile as readFile29 } from "node:fs/promises";
+import { readFile as readFile30 } from "node:fs/promises";
 async function readStdin() {
   return new Promise((resolve16, reject) => {
     const chunks = [];
@@ -39168,7 +40156,7 @@ async function runValidateWavesCommand(args) {
   let raw;
   if (filePath) {
     try {
-      raw = await readFile29(filePath, "utf-8");
+      raw = await readFile30(filePath, "utf-8");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(
@@ -39248,12 +40236,12 @@ var init_validate_waves2 = __esm({
 });
 
 // src/cli/worktree/path.ts
-import { dirname as dirname15, basename as basename4, join as join50 } from "node:path";
+import { dirname as dirname16, basename as basename4, join as join51 } from "node:path";
 function computeWorktreePath(cwd, checkpointNumber) {
-  const parent = dirname15(cwd);
+  const parent = dirname16(cwd);
   const base = basename4(cwd);
   const nnn = String(checkpointNumber).padStart(3, "0");
-  return join50(parent, `${base}-CHK-${nnn}`);
+  return join51(parent, `${base}-CHK-${nnn}`);
 }
 var init_path = __esm({
   "src/cli/worktree/path.ts"() {
@@ -39262,8 +40250,8 @@ var init_path = __esm({
 });
 
 // src/cli/worktree/add.ts
-import { join as join51, basename as basename5 } from "node:path";
-import { mkdir as mkdir14, readFile as readFile30, writeFile as writeFile23 } from "node:fs/promises";
+import { join as join52, basename as basename5 } from "node:path";
+import { mkdir as mkdir15, readFile as readFile31, writeFile as writeFile24 } from "node:fs/promises";
 import { spawnSync as spawnSync16 } from "node:child_process";
 async function defaultGetRepoId(cwd) {
   const found = await findCodebyplanConfig(cwd);
@@ -39306,22 +40294,22 @@ function defaultGitRun(args, cwd) {
   };
 }
 async function defaultCopyConfigStubs(srcCwd, destPath) {
-  await mkdir14(join51(destPath, ".codebyplan"), { recursive: true });
+  await mkdir15(join52(destPath, ".codebyplan"), { recursive: true });
   const topLevelStubs = [".mcp.json", ".env.local"];
   for (const stub of topLevelStubs) {
     try {
-      const content = await readFile30(join51(srcCwd, stub), "utf-8");
-      await writeFile23(join51(destPath, stub), content, "utf-8");
+      const content = await readFile31(join52(srcCwd, stub), "utf-8");
+      await writeFile24(join52(destPath, stub), content, "utf-8");
     } catch {
     }
   }
   try {
-    const content = await readFile30(
-      join51(srcCwd, ".codebyplan", "repo.json"),
+    const content = await readFile31(
+      join52(srcCwd, ".codebyplan", "repo.json"),
       "utf-8"
     );
-    await writeFile23(
-      join51(destPath, ".codebyplan", "repo.json"),
+    await writeFile24(
+      join52(destPath, ".codebyplan", "repo.json"),
       content,
       "utf-8"
     );
@@ -39482,7 +40470,7 @@ var init_add = __esm({
 });
 
 // src/cli/worktree/create.ts
-import { join as join52 } from "node:path";
+import { join as join53 } from "node:path";
 async function defaultGetRepoIdentity(cwd) {
   const found = await findCodebyplanConfig(cwd);
   const contents = found?.contents ?? null;
@@ -39537,7 +40525,7 @@ async function runWorktreeCreate(args, deps = {}) {
     );
     return 1;
   }
-  const worktreePath = explicitPath ?? join52(cwd, "..", name);
+  const worktreePath = explicitPath ?? join53(cwd, "..", name);
   const deviceId = await getDeviceId(cwd);
   let filesWritten = false;
   try {
@@ -40022,7 +41010,7 @@ var init_e2e = __esm({
 });
 
 // src/cli/e2e/verify-round.ts
-import { readFile as readFile31 } from "node:fs/promises";
+import { readFile as readFile32 } from "node:fs/promises";
 import { resolve as resolve14 } from "node:path";
 async function defaultFetchRounds(taskId) {
   return mcpCall("get_rounds", { task_id: taskId });
@@ -40030,7 +41018,7 @@ async function defaultFetchRounds(taskId) {
 async function defaultReadE2eConfig(cwd) {
   try {
     const p = resolve14(cwd, ".codebyplan", "e2e.json");
-    const raw = await readFile31(p, "utf-8");
+    const raw = await readFile32(p, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -40436,6 +41424,12 @@ void (async () => {
     await runTaskCommand2(rest);
     process.exit(0);
   }
+  if (arg === "standalone-task") {
+    const { runStandaloneTaskCommand: runStandaloneTaskCommand2 } = await Promise.resolve().then(() => (init_standalone_task(), standalone_task_exports));
+    const rest = process.argv.slice(3);
+    await runStandaloneTaskCommand2(rest);
+    process.exit(0);
+  }
   if (arg === "session") {
     const { runSessionCommand: runSessionCommand2 } = await Promise.resolve().then(() => (init_session(), session_exports));
     const rest = process.argv.slice(3);
@@ -40540,6 +41534,11 @@ void (async () => {
     await runTechStack2();
     process.exit(0);
   }
+  if (arg === "docs") {
+    const { runDocs: runDocs2 } = await Promise.resolve().then(() => (init_docs(), docs_exports));
+    await runDocs2();
+    process.exit(process.exitCode ?? 0);
+  }
   if (arg === "check") {
     const { runCheckCommand: runCheckCommand2 } = await Promise.resolve().then(() => (init_check2(), check_exports));
     const rest = process.argv.slice(3);
@@ -40798,6 +41797,7 @@ void (async () => {
     codebyplan doctor                Run diagnostics: auth, version, worktree (always exits 0)
     codebyplan tech-stack            Detect and sync tech stack dependencies
                                      (--full-tech-stack: sync every local worktree on this device)
+    codebyplan docs                  Local dependency docs mirror (sync / status)
     codebyplan eslint                ESLint config management (init)
     codebyplan ci                    CI configuration management (init / scaffold-workflow / enforce-check)
     codebyplan cd                    CD configuration management (init / scaffold-workflow)
@@ -40809,6 +41809,8 @@ void (async () => {
     codebyplan watch status           Show daemon status (--json for machine-readable)
     codebyplan watch run              Run daemon in foreground (used internally by start)
     codebyplan round sync-approvals   Sync git diff and approvals with round/task state
+    codebyplan standalone-task        Standalone task writes via MCP (create/update/complete)
+                                     (create --title; update --id; complete --id \u2014 no --checkpoint-id)
     codebyplan bump [--prerelease <id>]  Detect changed packages and patch-bump versions
     codebyplan ship                  Ship current feat branch to production via PR
     codebyplan upload-e2e-images     Upload new/changed committed e2e PNGs for a checkpoint