get-tbd 0.2.3 → 0.3.0

package/dist/cli.mjs

@@ -1,25 +1,29 @@
-import { C as IssueSchema, S as IssueKind, T as IssueTitle, c as DATA_SYNC_SCHEMA_VERSION, i as COMMON_DIR_LAYOUT_FIELD_ORDER, n as AtticEntrySchema, o as CommonDirLayoutSchema, t as ATTIC_ENTRY_FIELD_ORDER, w as IssueStatus, y as ISSUE_TITLE_MAX_LENGTH } from "./schemas-f0EcuAVu.mjs";
-import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-DTyyuaG_.mjs";
+import { C as IssueSchema, S as IssueKind, T as IssueTitle, c as DATA_SYNC_SCHEMA_VERSION, i as COMMON_DIR_LAYOUT_FIELD_ORDER, n as AtticEntrySchema, o as CommonDirLayoutSchema, t as ATTIC_ENTRY_FIELD_ORDER, w as IssueStatus, y as ISSUE_TITLE_MAX_LENGTH } from "./schemas-lCwRk30L.mjs";
+import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-CxKOynr1.mjs";
 import { a as parseYamlWithConflictDetection, d as PAGINATION_LINE_THRESHOLD, f as PARENT_CONTEXT_MAX_LINES, l as comparisonChain, n as detectDuplicateYamlKeys, o as sortKeys, s as stringifyYaml, u as ordering } from "./yaml-utils-BPy991by.mjs";
-import { A as WORKSPACES_DIR, C as SYNC_BRANCH, D as TBD_SHORTCUTS_STANDARD, E as TBD_GUIDELINES_DIR, F as resolveAtticDir, I as resolveDataSyncDir, L as resolveSharedTbdPaths, M as getWorkspaceDir, N as isCommonDirOutsideProject, O as TBD_SHORTCUTS_SYSTEM, P as isValidWorkspaceName, S as LEGACY_WORKTREE_DIR, T as TBD_DOCS_DIR, _ as DATA_SYNC_DIR, a as isInitialized, b as DEFAULT_SHORTCUT_PATHS, c as readConfigWithMigration, d as writeConfig, g as CHARS_PER_TOKEN, h as isCompatibleFormat, i as initConfig, j as WORKTREE_DIR_NAME, k as TBD_TEMPLATES_DIR, l as readLocalState, m as formatUpgradeMessage, n as findTbdRoot, o as markWelcomeSeen, p as CURRENT_FORMAT, r as hasSeenWelcome, s as readConfig, t as IncompatibleFormatError, u as updateLocalState, v as DATA_SYNC_DIR_NAME, w as TBD_DIR, x as DEFAULT_TEMPLATE_PATHS, y as DEFAULT_GUIDELINES_PATHS } from "./config-1ouUTKQr.mjs";
-import { C as withLockfile, S as DATA_SYNC_LOCK_OPTIONS, _ as formatDisplayId, a as hasShortId, b as normalizeIssueId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, g as formatDebugId, h as extractUlidFromInternalId, i as generateUniqueShortId, l as reconcileMappings, m as extractShortId, o as loadIdMapping, p as extractPrefix, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts, v as generateInternalId, x as validateIssueId, y as makeInternalId } from "./id-mapping-687_UEsy.mjs";
+import { C as parseDate, S as nowFilenameTimestamp, _ as isCompatibleFormat, a as isInitialized, b as now, c as readConfigWithMigration, d as updateLocalState, f as writeConfig, g as formatUpgradeMessage, h as FORMAT_HISTORY, i as initConfig, l as readLocalState, m as CURRENT_FORMAT, n as findTbdRoot, o as markWelcomeSeen, r as hasSeenWelcome, s as readConfig, t as IncompatibleFormatError, u as stampSetupVersion, v as isFormatCompatibleWithSupported, x as nowDate, y as normalizeTimestamp } from "./config-B1w3pAkY.mjs";
+import { A as isCommonDirOutsideProject, C as TBD_GUIDELINES_DIR, D as WORKSPACES_DIR, E as TBD_TEMPLATES_DIR, F as gitSafeEnv, M as resolveAtticDir, N as resolveDataSyncDir, O as WORKTREE_DIR_NAME, P as resolveSharedTbdPaths, S as TBD_DOCS_DIR, T as TBD_SHORTCUTS_SYSTEM, _ as FORK_TEMPLATES_DIR, b as SYNC_BRANCH, c as DATA_SYNC_DIR_NAME, d as DEFAULT_SHORTCUT_PATHS, f as DEFAULT_TEMPLATE_PATHS, g as FORK_SHORTCUTS_DIR, h as FORK_REFERENCES_DIR, i as CACHE_TEMPLATE_PATHS, j as isValidWorkspaceName, k as getWorkspaceDir, l as DEFAULT_GUIDELINES_PATHS, m as FORK_GUIDELINES_DIR, n as CACHE_REFERENCE_PATHS, p as FORK_DIR, r as CACHE_SHORTCUT_PATHS, s as DATA_SYNC_DIR, t as CACHE_GUIDELINES_PATHS, u as DEFAULT_REFERENCE_PATHS, v as LEGACY_WORKTREE_DIR, w as TBD_SHORTCUTS_STANDARD, x as TBD_DIR } from "./paths-C1DpnZJW.mjs";
+import { n as withLockfile, t as DATA_SYNC_LOCK_OPTIONS } from "./lockfile-BR0laSDy.mjs";
+import { _ as formatDisplayId, a as hasShortId, b as normalizeIssueId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, g as formatDebugId, h as extractUlidFromInternalId, i as generateUniqueShortId, l as reconcileMappings, m as extractShortId, o as loadIdMapping, p as extractPrefix, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts, v as generateInternalId, x as validateIssueId, y as makeInternalId } from "./id-mapping-DAIeLKzm.mjs";
+import { a as tryParseDocRef, i as parseDocRef, r as normalizeDocRef, t as DocRefError } from "./docref-C7g0sjvL.mjs";
+import { C as withForkManifestLock, S as upsertFork, T as writeForkManifest, _ as normalizeLineEndings, c as compareVersionsLoose, d as findFork, h as hashContent, m as hasUnresolvedConflict, n as CONFLICT_LABELS, w as writeBaseContent, y as readForkManifest } from "./fork-manifest-ByU7U2do.mjs";
+import { c as formatDocSize, d as fetchWithGhFallback, f as gitDocRefToRawUrl, l as formatTimestampAgo, o as SCORE_PREFIX_MATCH, s as generateShortcutDirectory, t as DocCache, u as syncDocsWithDefaults } from "./doc-cache-CamtXfi4.mjs";
+import { a as forkFilePath, c as listLocalForkFiles, d as regenerateForkDirReadme, f as unforkDoc, i as forkDoc, l as readForkBase, n as KIND_DIR, r as computeForkDriftSummary, s as forkStatusFor, t as ForkConflictError, u as readForkFile } from "./doc-fork-CoPi1G1N.mjs";
 import { createRequire } from "node:module";
-import { ZodError } from "zod";
-import matter from "gray-matter";
+import { ZodError, z } from "zod";
 import { parse } from "yaml";
 import { Command } from "commander";
 import pc from "picocolors";
 import { marked } from "marked";
 import { markedTerminal } from "marked-terminal";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
-import { access, chmod, cp, mkdir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink } from "node:fs/promises";
+import { access, chmod, cp, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { writeFile } from "atomically";
+import { tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import prettyBytes from "pretty-bytes";
-import prettyMs from "pretty-ms";
 import GithubSlugger from "github-slugger";
 
 //#region src/cli/lib/version.ts
@@ -49,12 +53,12 @@ function getVersion() {
 /**
 * Clean published npm version for pinned `get-tbd@<version>` fallbacks (the
 * session script and any other generated install hint). Always the package.json
-* semver — NOT the git-describe display version, which for a local/dirty build
+* semver, NOT the git-describe display version, which for a local/dirty build
 * is an unpublished string like `0.2.3-dev.2.abc1234-dirty` that npm cannot
 * install and that would churn generated files on every build.
 */
 function getPinnedNpmVersion() {
-	return "0.2.3";
+	return "0.3.0";
 }
 /**
 * CLI version - use this instead of importing VERSION directly from index.ts
@@ -214,7 +218,7 @@ function createHelpEpilog(colorOption = "auto") {
 		"",
 		"  This initializes tbd and configures your coding agents automatically.",
 		`  To refresh setup (idempotent, safe anytime): ${colors.green("`tbd setup --auto`")}`,
-		`  For interactive setup: ${colors.dim("`tbd setup --interactive`")}`,
+		`  For managed docs: ${colors.dim("`tbd docs`")}`,
 		"",
 		colors.blue("For more on tbd, see: https://github.com/jlevy/tbd")
 	].join("\n");
@@ -647,7 +651,7 @@ var SyncError = class extends CLIError {
 */
 var UnrelatedHistoriesError = class extends SyncError {
 	constructor(remote = "origin", syncBranch = "tbd-sync") {
-		super(`${remote}/${syncBranch} has an unrelated history (no common ancestor) — push cannot fast-forward and a merge would refuse.\nRun \`tbd doctor --fix\` to reconcile the unrelated histories (non-destructive; a backup branch is created first).`);
+		super(`${remote}/${syncBranch} has an unrelated history (no common ancestor); push cannot fast-forward and a merge would refuse.\nRun \`tbd doctor --fix\` to reconcile the unrelated histories (non-destructive; a backup branch is created first).`);
 		this.name = "UnrelatedHistoriesError";
 	}
 };
@@ -897,58 +901,6 @@ async function getBeadsPrefix(cwd) {
 	}
 }
 
-//#endregion
-//#region src/utils/time-utils.ts
-/**
-* Time utilities for tbd.
-*
-* All timestamps should be ISO 8601 UTC format with Z suffix.
-* Use these functions instead of raw Date calls for consistency.
-*/
-/**
-* Get current time as ISO 8601 UTC string.
-* Use this when recording timestamps for new/updated issues.
-*/
-function now() {
-	return (/* @__PURE__ */ new Date()).toISOString();
-}
-/**
-* Get current time as Date object.
-* Use this when you need date arithmetic or comparisons.
-*/
-function nowDate() {
-	return /* @__PURE__ */ new Date();
-}
-/**
-* Parse a timestamp string to Date object.
-* Returns null if the timestamp is invalid.
-*/
-function parseDate(timestamp) {
-	if (!timestamp) return null;
-	try {
-		const date = new Date(timestamp);
-		if (isNaN(date.getTime())) return null;
-		return date;
-	} catch {
-		return null;
-	}
-}
-/**
-* Normalize any timestamp to ISO 8601 UTC format with Z suffix.
-* Handles various formats including timezone offsets like -08:00.
-* Returns null if the timestamp is invalid or missing.
-*/
-function normalizeTimestamp(timestamp) {
-	return parseDate(timestamp)?.toISOString() ?? null;
-}
-/**
-* Get current time as a filename-safe timestamp.
-* Replaces colons with dashes and removes milliseconds for filesystem compatibility.
-*/
-function nowFilenameTimestamp() {
-	return (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "Z");
-}
-
 //#endregion
 //#region src/utils/zod-error-utils.ts
 /**
@@ -1079,7 +1031,7 @@ function reportInvalidIssueFile(invalidIssue, warnOnInvalid, onInvalidIssue) {
 *
 * See: tbd-design.md §3.3 Sync Operations
 */
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync = promisify(execFile);
 /**
 * Error thrown by {@link git} when a git command exits non-zero.
 *
@@ -1145,7 +1097,10 @@ const GIT_MAX_BUFFER = 50 * 1024 * 1024;
 */
 async function git(...args) {
 	try {
-		const { stdout } = await execFileAsync$1("git", args, { maxBuffer: GIT_MAX_BUFFER });
+		const { stdout } = await execFileAsync("git", args, {
+			maxBuffer: GIT_MAX_BUFFER,
+			env: gitSafeEnv()
+		});
 		return stdout.trim();
 	} catch (err) {
 		throw GitError.from(err, args);
@@ -1158,12 +1113,9 @@ async function git(...args) {
 */
 async function gitNoPrompt(...args) {
 	try {
-		const { stdout } = await execFileAsync$1("git", args, {
+		const { stdout } = await execFileAsync("git", args, {
 			maxBuffer: GIT_MAX_BUFFER,
-			env: {
-				...process.env,
-				GIT_TERMINAL_PROMPT: "0"
-			}
+			env: gitSafeEnv({ GIT_TERMINAL_PROMPT: "0" })
 		});
 		return stdout.trim();
 	} catch (err) {
@@ -1569,7 +1521,7 @@ async function branchExists(branch, baseDir) {
 * `git ls-remote --exit-code` exits 2 when the connection succeeded but no ref
 * matched; any other failure (auth/network/transient, or git not found) is a
 * check failure. Orphan-creating callers MUST branch on all three states and
-* never treat `check-failed` as `absent` — doing so risks creating a divergent
+* never treat `check-failed` as `absent`; doing so risks creating a divergent
 * local branch when the remote is merely unreachable.
 */
 async function probeRemoteBranch(remote, branch, baseDir) {
@@ -1861,7 +1813,7 @@ async function pushFreshOrphan(baseDir, worktreePath, remote, syncBranch, dataSy
 * Initialize the hidden worktree for the tbd-sync branch.
 * Follows the decision tree from tbd-design.md §2.3.
 *
-* MUST be called while holding `withSharedDataSyncLock` — it migrates legacy
+* MUST be called while holding `withSharedDataSyncLock`; it migrates legacy
 * per-checkout worktrees and creates the shared attached worktree on tbd-sync,
 * so concurrent callers can otherwise race branch ownership and migration.
 *
@@ -2081,7 +2033,7 @@ async function readBranchMapping(baseDir, ref) {
 * both sides instead of one side winning.
 *
 * Returns `null` when the bead does not exist on the `theirsRef` side (nothing to
-* merge — keep ours). Used by sync's conflict paths in place of git's line-based
+* merge, keep ours). Used by sync's conflict paths in place of git's line-based
 * text merge. See issue #155.
 *
 * @param repoDir - Directory to run git in (the data-sync worktree). `oursRef` and
@@ -2133,7 +2085,7 @@ async function preserveLosingVersion(dataSyncPath, loser) {
 * the rescue is restartable.
 *
 * MUST be called while holding `withSharedDataSyncLock`. A merge in progress
-* aborts the rescue; a merely-dirty worktree does not — its uncommitted
+* aborts the rescue; a merely-dirty worktree does not; its uncommitted
 * tbd-owned data-sync changes are committed first (so the backup branch captures
 * them), while any dirty path outside the data-sync tree aborts. See issue #158.
 */
@@ -2208,7 +2160,7 @@ async function countRemoteIssues(remote = "origin", syncBranch = SYNC_BRANCH, ba
 * - CORRUPTED: backup to .tbd/backups/, remove, then recreate
 * - MISSING: just create
 *
-* MUST be called while holding `withSharedDataSyncLock` — repair mutates
+* MUST be called while holding `withSharedDataSyncLock`; repair mutates
 * shared worktree and branch state and shares the same locking contract as
 * `initWorktree`.
 *
@@ -2371,6 +2323,17 @@ async function readCommonDirLayout(layoutPath) {
 	}
 }
 /**
+* Whether an existing layout is simply from an older format than the checkout
+* config and can be re-stamped in place. This is the normal mid-migration state
+* (e.g. an f04 layout next to a config that just migrated to f05): the format
+* bump's only effect on the layout is the stamp, so rewriting it from the config
+* IS the layout migration. Anything else (future formats, storage mismatches)
+* stays a hard validation error.
+*/
+function isLayoutUpgradeable(layout, config) {
+	return layout.tbd_format !== config.tbd_format && layout.tbd_format in FORMAT_HISTORY && config.tbd_format in FORMAT_HISTORY && isFormatCompatibleWithSupported(layout.tbd_format, config.tbd_format) && layout.sync_storage === config.sync.storage;
+}
+/**
 * Validate that common-dir layout metadata matches the checkout config.
 */
 function validateCommonDirLayout(layout, config) {
@@ -2407,6 +2370,7 @@ async function writeCommonDirLayout(paths, config, existing) {
 async function ensureCommonDirLayout(paths, config) {
 	const existing = await readCommonDirLayout(paths.sharedLayoutPath);
 	if (existing) {
+		if (isLayoutUpgradeable(existing, config)) return writeCommonDirLayout(paths, config, existing);
 		validateCommonDirLayout(existing, config);
 		return existing;
 	}
@@ -2417,8 +2381,8 @@ async function ensureCommonDirLayout(paths, config) {
 * path is not writable by this process (EPERM/EACCES).
 *
 * The common trigger is an agent sandbox (e.g. Codex) where the *checkout* is
-* writable but `$GIT_COMMON_DIR/tbd` — which holds the shared sync worktree and
-* the lock — lives in the user's original repo directory, outside the sandbox's
+* writable but `$GIT_COMMON_DIR/tbd`, which holds the shared sync worktree and
+* the lock, lives in the user's original repo directory, outside the sandbox's
 * writable boundary. Read-only commands work, but any write needs the lock and
 * fails here. This is fatal for the command: without the lock we cannot safely
 * mutate shared state. See issue #164.
@@ -2427,7 +2391,7 @@ var SharedLockUnwritableError = class extends Error {
 	constructor(code, paths, projectRoot) {
 		const outside = isCommonDirOutsideProject(paths.gitCommonDir, projectRoot);
 		const cause = outside ? `The checkout is writable, but the shared tbd state under ${paths.sharedTbdDir} is outside this process's writable area (a common agent-sandbox shape, e.g. Codex worktrees), so write commands cannot proceed.` : `The shared tbd state under ${paths.sharedTbdDir} is not writable by this process, so write commands cannot proceed.`;
-		const fix = outside ? `Fix: grant write access to ${paths.sharedTbdDir} — in an agent sandbox such as Codex add it to the writable roots, or re-run with sandbox escalation.` : `Fix: ensure ${paths.sharedTbdDir} is writable by this user (check filesystem permissions).`;
+		const fix = outside ? `Fix: grant write access to ${paths.sharedTbdDir}; in an agent sandbox such as Codex add it to the writable roots, or re-run with sandbox escalation.` : `Fix: ensure ${paths.sharedTbdDir} is writable by this user (check filesystem permissions).`;
 		super(`Cannot acquire the shared tbd data-sync lock (${code}): ${paths.sharedLockPath}\n${cause}\n${fix} Run \`tbd doctor\` to confirm the diagnosis.`);
 		this.code = code;
 		this.name = "SharedLockUnwritableError";
@@ -2787,7 +2751,8 @@ async function probeDataSyncReadiness(tbdRoot) {
 	const { config, migrated, fromFormat } = await readConfigWithMigration(tbdRoot);
 	const sharedPaths = await resolveSharedTbdPaths(tbdRoot);
 	const layout = await readCommonDirLayout(sharedPaths.sharedLayoutPath);
-	if (layout) validateCommonDirLayout(layout, config);
+	const layoutNeedsUpgrade = layout !== null && isLayoutUpgradeable(layout, config);
+	if (layout && !layoutNeedsUpgrade) validateCommonDirLayout(layout, config);
 	const health = await checkWorktreeHealth(tbdRoot, config.sync.branch);
 	return {
 		config,
@@ -2796,7 +2761,7 @@ async function probeDataSyncReadiness(tbdRoot) {
 		sharedPaths,
 		layout,
 		health,
-		ready: !migrated && layout !== null && health.valid
+		ready: !migrated && layout !== null && !layoutNeedsUpgrade && health.valid
 	};
 }
 /**
@@ -2840,12 +2805,12 @@ function notifyConfigMigrated(fromFormat, toFormat) {
 * The shared worktree can be absent in a fresh/ephemeral clone (or if it was
 * deleted). `withDataSyncContext` heals it transparently, but a silent heal on a
 * read/write command looks indistinguishable from "the tracker is empty" or "my
-* issue was saved normally" — the exact confusion reported in #135. A terse
+* issue was saved normally", the exact confusion reported in #135. A terse
 * stderr note keeps stdout (and JSON) clean while making the heal visible.
 */
 function notifyWorktreeRepaired(status) {
 	if (status !== "missing" && status !== "prunable") return;
-	process.stderr.write(`• tbd-sync worktree was ${status} — auto-materialized it (fresh clone, or the worktree was removed).\n`);
+	process.stderr.write(`• tbd-sync worktree was ${status}; auto-materialized it (fresh clone, or the worktree was removed).\n`);
 }
 async function assembleDataContext(tbdRoot, probe, repairedWorktreeStatus) {
 	const dataSyncDir = await resolveDataSyncDir(tbdRoot, { allowFallback: false });
@@ -4570,6 +4535,53 @@ const listDepsCommand = new Command("list").description("List dependencies for a
 });
 const depCommand = new Command("dep").description("Manage issue dependencies").addCommand(addCommand).addCommand(removeCommand).addCommand(listDepsCommand);
 
+//#endregion
+//#region src/cli/lib/docs-sync-output.ts
+/** Print the result of a docs-cache sync (writes applied). */
+function printDocSyncResult(output, result) {
+	if (!(result.added.length > 0 || result.updated.length > 0 || result.removed.length > 0 || result.pruned.length > 0)) {
+		output.success("Docs up to date");
+		return;
+	}
+	const parts = [];
+	if (result.added.length > 0) parts.push(`+${result.added.length}`);
+	if (result.updated.length > 0) parts.push(`~${result.updated.length}`);
+	if (result.removed.length > 0) parts.push(`-${result.removed.length}`);
+	if (parts.length > 0) output.success(`Synced docs: ${parts.join(" ")} doc(s)`);
+	if (result.pruned.length > 0) output.info(`Removed ${result.pruned.length} stale config entry/entries`);
+	for (const err of result.errors) output.warn(`Doc sync error: ${err.path}: ${err.error}`);
+}
+/** Print what a docs-cache sync would change (dry-run / status view). */
+function printDocSyncStatus(output, result) {
+	const colors = output.getColors();
+	if (!(result.added.length > 0 || result.updated.length > 0 || result.removed.length > 0 || result.pruned.length > 0)) {
+		output.success("Docs up to date");
+		return;
+	}
+	console.log(colors.bold("Docs:"));
+	if (result.added.length > 0) console.log(`  ${colors.success(`+${result.added.length}`)} new doc(s) available`);
+	if (result.updated.length > 0) console.log(`  ${colors.warn(`~${result.updated.length}`)} doc(s) to update`);
+	if (result.removed.length > 0) console.log(`  ${colors.error(`-${result.removed.length}`)} doc(s) to remove`);
+	if (result.pruned.length > 0) console.log(`  ${colors.dim(`${result.pruned.length}`)} stale config entry/entries`);
+}
+/**
+* One-line awareness notice for forked docs: a cache refresh is exactly when
+* forks become stale, so drift is surfaced here, but never acted on (only the
+* explicit `tbd docs update` mutates tracked files). Best-effort: never fails
+* the surrounding sync.
+*/
+async function printForkDriftNotice(output, tbdRoot) {
+	try {
+		const drift = await computeForkDriftSummary(tbdRoot, FORK_DIR, await readForkManifest(tbdRoot));
+		if (drift.forks === 0) return;
+		const parts = [];
+		if (drift.stale > 0) parts.push(`${drift.stale} forked doc(s) have upstream updates; run 'tbd docs update'`);
+		if (drift.conflicted > 0) parts.push(`${drift.conflicted} with unresolved conflict markers`);
+		if (drift.missing > 0) parts.push(`${drift.missing} missing (deleted/renamed); see 'tbd docs status'`);
+		if (parts.length > 0) output.notice(`Docs: ${parts.join("; ")}`);
+	} catch {}
+}
+
 //#endregion
 //#region src/lib/sync-summary.ts
 /**
@@ -4682,511 +4694,6 @@ function parseGitDiff(diffOutput) {
 	return tallies;
 }
 
-//#endregion
-//#region src/file/github-fetch.ts
-/**
-* GitHub URL utilities and content fetching with `gh` CLI fallback.
-*
-* Consolidates all GitHub-specific URL handling and fetching logic:
-* - GitHub blob URL → raw URL conversion
-* - Direct HTTP fetch with timeout
-* - Fallback to `gh api` on 403 errors (common in restricted environments)
-*
-* This module is reusable across doc-sync, doc-add, and any future code
-* that needs to fetch content from GitHub.
-*/
-const execFileAsync = promisify(execFile);
-/**
-* Regular expression to match GitHub blob URLs.
-*
-* Matches patterns like:
-*   https://github.com/{owner}/{repo}/blob/{ref}/{path}
-*/
-const GITHUB_BLOB_RE = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
-/**
-* Regular expression to match raw.githubusercontent.com URLs.
-*
-* Matches patterns like:
-*   https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}
-*/
-const RAW_GITHUB_RE = /^https?:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/;
-/**
-* Convert a GitHub blob URL to a raw.githubusercontent.com URL.
-*
-* If the URL is already a raw URL or not a GitHub blob URL, returns it unchanged.
-*
-* @example
-* githubBlobToRawUrl('https://github.com/org/repo/blob/main/docs/file.md')
-* // => 'https://raw.githubusercontent.com/org/repo/main/docs/file.md'
-*
-* @example
-* githubBlobToRawUrl('https://raw.githubusercontent.com/org/repo/main/docs/file.md')
-* // => 'https://raw.githubusercontent.com/org/repo/main/docs/file.md' (unchanged)
-*/
-function githubBlobToRawUrl(url) {
-	const match = GITHUB_BLOB_RE.exec(url);
-	if (!match) return url;
-	const [, owner, repo, ref, path] = match;
-	return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path}`;
-}
-/**
-* Parse a raw.githubusercontent.com URL into its components.
-*
-* @returns The parsed components, or null if not a raw GitHub URL
-*/
-function parseRawGitHubUrl(url) {
-	const match = RAW_GITHUB_RE.exec(url);
-	if (!match) return null;
-	return {
-		owner: match[1],
-		repo: match[2],
-		ref: match[3],
-		path: match[4]
-	};
-}
-/** Default timeout for URL fetches in milliseconds */
-const DEFAULT_FETCH_TIMEOUT = 3e4;
-/**
-* Fetch content from a URL via direct HTTP.
-*
-* @throws If the request fails or returns a non-OK status
-*/
-async function directFetch(url, options) {
-	const timeout = options?.timeout ?? DEFAULT_FETCH_TIMEOUT;
-	const controller = new AbortController();
-	const timer = setTimeout(() => {
-		controller.abort();
-	}, timeout);
-	try {
-		const response = await fetch(url, {
-			signal: controller.signal,
-			headers: {
-				"User-Agent": "get-tbd/1.0",
-				Accept: "text/plain, text/markdown, */*"
-			}
-		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-		return await response.text();
-	} finally {
-		clearTimeout(timer);
-	}
-}
-/**
-* Fetch content from a GitHub raw URL using `gh api`.
-*
-* Converts raw.githubusercontent.com URLs to GitHub API content endpoints
-* and decodes the base64-encoded response.
-*
-* @throws If the URL is not a GitHub URL or gh CLI fails
-*/
-async function ghCliFetch(rawUrl) {
-	const parsed = parseRawGitHubUrl(rawUrl);
-	if (parsed) try {
-		const { stdout } = await execFileAsync("gh", [
-			"api",
-			`/repos/${parsed.owner}/${parsed.repo}/contents/${parsed.path}?ref=${parsed.ref}`,
-			"--jq",
-			".content",
-			"-H",
-			"Accept: application/vnd.github.v3+json"
-		]);
-		const base64Content = stdout.trim();
-		return Buffer.from(base64Content, "base64").toString("utf-8");
-	} catch (error) {
-		throw new Error(`Failed to fetch via gh CLI: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	try {
-		const { stdout } = await execFileAsync("gh", ["api", rawUrl]);
-		return stdout;
-	} catch (error) {
-		throw new Error(`Failed to fetch via gh CLI: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-/**
-* Fetch content from a URL, falling back to `gh` CLI on 403 errors.
-*
-* GitHub.com and raw.githubusercontent.com may block requests from
-* certain environments (e.g., CI runners, corporate proxies). When
-* a 403 is received, we retry using `gh api` which authenticates
-* via the user's GitHub CLI token.
-*
-* This function also auto-converts GitHub blob URLs to raw URLs.
-*
-* @returns The fetched content and whether gh CLI was used
-* @throws If both direct fetch and gh CLI fallback fail
-*/
-async function fetchWithGhFallback(url, options) {
-	const rawUrl = githubBlobToRawUrl(url);
-	try {
-		return {
-			content: await directFetch(rawUrl, options),
-			usedGhCli: false
-		};
-	} catch (error) {
-		if (!(error instanceof Error && error.message.includes("HTTP 403"))) throw error;
-	}
-	return {
-		content: await ghCliFetch(rawUrl),
-		usedGhCli: true
-	};
-}
-
-//#endregion
-//#region src/file/doc-sync.ts
-/**
-* DocSync - Sync documentation files from configured sources.
-*
-* Syncs docs from internal bundled sources and external URLs to .tbd/docs/.
-*
-* See: docs/project/specs/active/plan-2026-01-26-configurable-doc-cache-sync.md
-*/
-/** Prefix for internal bundled doc sources */
-const INTERNAL_SOURCE_PREFIX = "internal:";
-/**
-* Syncs documentation files from configured sources.
-*
-* Supports:
-* - Internal bundled docs (using internal: prefix)
-* - External URLs (raw.githubusercontent.com, etc.)
-*/
-var DocSync = class {
-	docsDir;
-	/**
-	* Create a new DocSync instance.
-	*
-	* @param tbdRoot - The tbd project root directory (parent of .tbd/)
-	* @param config - The doc_cache configuration mapping dest paths to sources
-	*/
-	constructor(tbdRoot, config) {
-		this.tbdRoot = tbdRoot;
-		this.config = config;
-		this.docsDir = join(tbdRoot, TBD_DOCS_DIR);
-	}
-	/**
-	* Parse a source string into a DocSource.
-	*
-	* @example
-	* parseSource('internal:shortcuts/standard/code-review-and-commit.md')
-	* // => { type: 'internal', location: 'shortcuts/standard/code-review-and-commit.md' }
-	*
-	* @example
-	* parseSource('https://raw.githubusercontent.com/org/repo/main/file.md')
-	* // => { type: 'url', location: 'https://...' }
-	*/
-	parseSource(source) {
-		if (source.startsWith(INTERNAL_SOURCE_PREFIX)) return {
-			type: "internal",
-			location: source.slice(9)
-		};
-		return {
-			type: "url",
-			location: source
-		};
-	}
-	/**
-	* Fetch content from a source.
-	*
-	* @throws If the source cannot be fetched
-	*/
-	async fetchContent(source) {
-		if (source.type === "internal") return this.fetchInternalContent(source.location);
-		return this.fetchUrlContent(source.location);
-	}
-	/**
-	* Fetch content from an internal bundled doc.
-	*/
-	async fetchInternalContent(location) {
-		const basePaths = getDocsBasePath();
-		for (const basePath of basePaths) {
-			const fullPath = join(basePath, location);
-			try {
-				await access(fullPath);
-				return await readFile(fullPath, "utf-8");
-			} catch {}
-		}
-		throw new Error(`Internal doc not found: ${location}`);
-	}
-	/**
-	* Fetch content from a URL (with gh CLI fallback on 403).
-	*/
-	async fetchUrlContent(url) {
-		const { content } = await fetchWithGhFallback(url);
-		return content;
-	}
-	/**
-	* Get the current state of the docs directory.
-	* Returns a set of relative paths that exist in .tbd/docs/.
-	*/
-	async getCurrentState() {
-		const paths = /* @__PURE__ */ new Set();
-		try {
-			await access(this.docsDir);
-		} catch {
-			return paths;
-		}
-		await this.scanDirectory(this.docsDir, "", paths);
-		return paths;
-	}
-	/**
-	* Recursively scan a directory and add all .md file paths to the set.
-	*/
-	async scanDirectory(baseDir, prefix, paths) {
-		try {
-			const dirEntries = await readdir(baseDir, { withFileTypes: true });
-			for (const entry of dirEntries) {
-				const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
-				if (entry.isDirectory()) await this.scanDirectory(join(baseDir, entry.name), relativePath, paths);
-				else if (entry.isFile() && entry.name.endsWith(".md")) paths.add(relativePath);
-			}
-		} catch {}
-	}
-	/**
-	* Sync all docs from config to .tbd/docs/.
-	*
-	* - Downloads/copies new docs
-	* - Updates docs whose source has changed
-	* - Removes docs no longer in config
-	*
-	* @param options - Sync options (dryRun, silent)
-	*/
-	async sync(options = {}) {
-		const result = {
-			added: [],
-			updated: [],
-			removed: [],
-			errors: [],
-			success: true
-		};
-		const currentPaths = await this.getCurrentState();
-		const configPaths = new Set(Object.keys(this.config));
-		for (const [destPath, sourceStr] of Object.entries(this.config)) try {
-			const source = this.parseSource(sourceStr);
-			const content = await this.fetchContent(source);
-			const fullPath = join(this.docsDir, destPath);
-			let exists = false;
-			let existingContent = "";
-			try {
-				existingContent = await readFile(fullPath, "utf-8");
-				exists = true;
-			} catch {}
-			if (!exists) {
-				if (!options.dryRun) {
-					await mkdir(dirname(fullPath), { recursive: true });
-					await writeFile(fullPath, content);
-				}
-				result.added.push(destPath);
-			} else if (existingContent !== content) {
-				if (!options.dryRun) await writeFile(fullPath, content);
-				result.updated.push(destPath);
-			}
-		} catch (err) {
-			result.errors.push({
-				path: destPath,
-				error: err.message
-			});
-			result.success = false;
-		}
-		for (const existingPath of currentPaths) if (!configPaths.has(existingPath)) try {
-			if (!options.dryRun) await rm(join(this.docsDir, existingPath));
-			result.removed.push(existingPath);
-		} catch (err) {
-			result.errors.push({
-				path: existingPath,
-				error: `Failed to remove: ${err.message}`
-			});
-		}
-		return result;
-	}
-	/**
-	* Get a status of what would change without actually making changes.
-	*/
-	async status() {
-		return this.sync({ dryRun: true });
-	}
-};
-/**
-* Get base docs paths (with fallbacks for development).
-* Matches the logic in setup.ts.
-*/
-function getDocsBasePath() {
-	const __dirname = dirname(fileURLToPath(import.meta.url));
-	return [join(__dirname, "docs"), join(__dirname, "..", "..", "docs")];
-}
-/**
-* Generate default doc_cache config by scanning bundled docs.
-*
-* This creates a config entry for each .md file found in the bundled
-* docs directories (shortcuts, guidelines, templates).
-*
-* @returns A doc_cache config mapping destination paths to internal: sources
-*/
-async function generateDefaultDocCacheConfig() {
-	const config = {};
-	const basePaths = getDocsBasePath();
-	let docsDir = null;
-	for (const path of basePaths) try {
-		await access(path);
-		docsDir = path;
-		break;
-	} catch {}
-	if (!docsDir) return config;
-	for (const { subdir, prefix } of [
-		{
-			subdir: "shortcuts/system",
-			prefix: "shortcuts/system"
-		},
-		{
-			subdir: "shortcuts/standard",
-			prefix: "shortcuts/standard"
-		},
-		{
-			subdir: "guidelines",
-			prefix: "guidelines"
-		},
-		{
-			subdir: "templates",
-			prefix: "templates"
-		}
-	]) {
-		const fullDir = join(docsDir, subdir);
-		try {
-			const entries = await readdir(fullDir, { withFileTypes: true });
-			for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".md")) {
-				const relativePath = `${prefix}/${entry.name}`;
-				config[relativePath] = `${INTERNAL_SOURCE_PREFIX}${relativePath}`;
-			}
-		} catch {}
-	}
-	return config;
-}
-/**
-* Merge user's doc_cache config with default bundled docs.
-*
-* This ensures:
-* - New bundled docs from tbd updates are added to existing configs
-* - User's custom sources (URLs, etc.) are preserved
-* - User's overrides of bundled docs are respected
-*
-* @param userConfig - The user's existing doc_cache config (may be undefined/empty)
-* @param defaults - The default config from generateDefaultDocCacheConfig()
-* @returns Merged config with defaults as base, user config overlaid
-*/
-function mergeDocCacheConfig(userConfig, defaults) {
-	return {
-		...defaults,
-		...userConfig
-	};
-}
-/**
-* Check if docs are stale based on last sync time and configured hours.
-*
-* @param lastSyncAt - ISO timestamp of last sync (or undefined if never synced)
-* @param autoSyncHours - Hours between auto-syncs (0 = disabled)
-* @returns true if docs should be synced
-*/
-function isDocsStale(lastSyncAt, autoSyncHours) {
-	if (autoSyncHours <= 0) return false;
-	if (!lastSyncAt) return true;
-	const lastSync = new Date(lastSyncAt).getTime();
-	return (Date.now() - lastSync) / (1e3 * 60 * 60) >= autoSyncHours;
-}
-/**
-* Check if an internal bundled doc exists.
-*
-* @param location - The internal doc path (without 'internal:' prefix)
-* @returns true if the doc exists in any of the bundled doc paths
-*/
-async function internalDocExists(location) {
-	const basePaths = getDocsBasePath();
-	for (const basePath of basePaths) {
-		const fullPath = join(basePath, location);
-		try {
-			await access(fullPath);
-			return true;
-		} catch {}
-	}
-	return false;
-}
-/**
-* Prune entries from config that point to non-existent internal sources.
-*
-* This handles the case where a bundled doc is removed in a tbd update -
-* the stale config entry is automatically cleaned up.
-*
-* @param config - The doc_cache config to prune
-* @returns Object with pruned config and list of removed entries
-*/
-async function pruneStaleInternals(config) {
-	const result = {};
-	const pruned = [];
-	for (const [dest, source] of Object.entries(config)) {
-		if (source.startsWith(INTERNAL_SOURCE_PREFIX)) {
-			if (!await internalDocExists(source.slice(9))) {
-				pruned.push(dest);
-				continue;
-			}
-		}
-		result[dest] = source;
-	}
-	return {
-		config: result,
-		pruned
-	};
-}
-/**
-* Deep equality check for config objects.
-*/
-function configsEqual(a, b) {
-	const keysA = Object.keys(a).sort();
-	const keysB = Object.keys(b).sort();
-	if (keysA.length !== keysB.length) return false;
-	for (const key of keysA) if (!Object.hasOwn(b, key) || a[key] !== b[key]) return false;
-	return true;
-}
-/**
-* Sync docs with merged defaults and auto-pruning.
-*
-* This is the single entry point for all doc sync operations that need
-* to pick up new bundled docs from tbd upgrades.
-*
-* Steps:
-* 1. Read current config
-* 2. Generate defaults from bundled docs
-* 3. Merge: defaults as base, user config overlays
-* 4. Prune entries with missing internal sources
-* 5. Sync files to .tbd/docs/
-* 6. Write config if changed
-* 7. Update last_doc_sync_at in state
-*
-* @param tbdRoot - The tbd project root directory
-* @param options - Sync options (quiet, dryRun)
-* @returns Sync result with added/updated/removed/pruned counts
-*/
-async function syncDocsWithDefaults(tbdRoot, options = {}) {
-	const config = await readConfig(tbdRoot);
-	const originalFiles = config.docs_cache?.files ?? {};
-	const { config: prunedConfig, pruned } = await pruneStaleInternals(mergeDocCacheConfig(originalFiles, await generateDefaultDocCacheConfig()));
-	const syncResult = await new DocSync(tbdRoot, prunedConfig).sync({ dryRun: options.dryRun });
-	const configChanged = !configsEqual(prunedConfig, originalFiles);
-	if (configChanged && !options.dryRun) {
-		config.docs_cache = {
-			lookup_path: config.docs_cache?.lookup_path ?? [".tbd/docs/shortcuts/system", ".tbd/docs/shortcuts/standard"],
-			files: prunedConfig
-		};
-		await writeConfig(tbdRoot, config);
-	}
-	if (!options.dryRun) await updateLocalState(tbdRoot, { last_doc_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
-	return {
-		added: syncResult.added,
-		updated: syncResult.updated,
-		removed: syncResult.removed,
-		pruned,
-		configChanged,
-		errors: syncResult.errors,
-		success: syncResult.success
-	};
-}
-
 //#endregion
 //#region src/file/workspace.ts
 /**
@@ -5631,31 +5138,17 @@ var SyncHandler = class extends BaseCommand {
 	async syncDocs(statusOnly) {
 		if (statusOnly) {
 			const result = await syncDocsWithDefaults(this.tbdRoot, { dryRun: true });
-			this.showDocStatus(result);
+			printDocSyncStatus(this.output, result);
 			return result;
 		}
 		const spinner = this.output.spinner("Syncing docs...");
 		const result = await syncDocsWithDefaults(this.tbdRoot);
 		spinner.stop();
-		this.showDocSyncResult(result);
+		printDocSyncResult(this.output, result);
+		await printForkDriftNotice(this.output, this.tbdRoot);
 		return result;
 	}
 	/**
-	* Show doc sync status (what would change).
-	*/
-	showDocStatus(result) {
-		const colors = this.output.getColors();
-		if (!(result.added.length > 0 || result.updated.length > 0 || result.removed.length > 0 || result.pruned.length > 0)) {
-			this.output.success("Docs up to date");
-			return;
-		}
-		console.log(colors.bold("Docs:"));
-		if (result.added.length > 0) console.log(`  ${colors.success(`+${result.added.length}`)} new doc(s) available`);
-		if (result.updated.length > 0) console.log(`  ${colors.warn(`~${result.updated.length}`)} doc(s) to update`);
-		if (result.removed.length > 0) console.log(`  ${colors.error(`-${result.removed.length}`)} doc(s) to remove`);
-		if (result.pruned.length > 0) console.log(`  ${colors.dim(`${result.pruned.length}`)} stale config entry/entries`);
-	}
-	/**
 	* Show doc sync result after sync.
 	*/
 	showDocSyncResult(result) {
@@ -5846,7 +5339,7 @@ var SyncHandler = class extends BaseCommand {
 	* result, and asserting no bead was left corrupt.
 	*
 	* Shared by the pull/full-sync path and the push-retry path so both integrate
-	* the remote identically — and so a rejected push actually advances local
+	* the remote identically, and so a rejected push actually advances local
 	* `tbd-sync` to include the remote before retrying, instead of looping on the
 	* same non-fast-forward commit. See issue #155.
 	*
@@ -6193,61 +5686,11 @@ const syncCommand = new Command("sync").description("Synchronize issues and docs
 });
 
 //#endregion
-//#region src/lib/format-utils.ts
+//#region src/cli/commands/search.ts
 /**
-* Human-readable formatting utilities for tbd CLI.
+* `tbd search` - Search issues.
 *
-* Uses sindresorhus libraries for consistent, well-tested formatting:
-* - pretty-bytes: Byte sizes (1337 -> "1.34 kB")
-* - pretty-ms: Durations (3600000 -> "1h")
-*/
-/**
-* Estimate token count from text content.
-* Uses CHARS_PER_TOKEN (~3.5) for markdown/code content.
-*/
-function estimateTokens(text) {
-	return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-/**
-* Format token count: "~1.2k tok" or "~450 tok"
-*/
-function formatTokens(tokens) {
-	if (tokens >= 1e3) return `~${(tokens / 1e3).toFixed(1)}k tok`;
-	return `~${tokens} tok`;
-}
-/**
-* Format doc size for list display: "(1.8 kB, ~450 tok)"
-*/
-function formatDocSize(sizeBytes, approxTokens) {
-	return `(${prettyBytes(sizeBytes)}, ${formatTokens(approxTokens)})`;
-}
-/**
-* Format relative time from Date: "2d ago", "3h ago", "5m ago"
-* Uses compact format for concise display.
-*/
-function formatTimeAgo(date) {
-	const ms = Date.now() - date.getTime();
-	if (ms < 0) return "just now";
-	if (ms < 6e4) return "just now";
-	return `${prettyMs(ms, { compact: true })} ago`;
-}
-/**
-* Format relative time from ISO timestamp string.
-* Returns null if timestamp is invalid.
-*/
-function formatTimestampAgo(timestamp) {
-	if (!timestamp) return null;
-	const date = new Date(timestamp);
-	if (isNaN(date.getTime())) return null;
-	return formatTimeAgo(date);
-}
-
-//#endregion
-//#region src/cli/commands/search.ts
-/**
-* `tbd search` - Search issues.
-*
-* See: tbd-design.md §4.8 Search Commands
+* See: tbd-design.md §4.8 Search Commands
 */
 const STALE_THRESHOLD_MS = 300 * 1e3;
 var SearchHandler = class extends BaseCommand {
@@ -6556,8 +5999,8 @@ function renderFooter(suggestions, colors) {
 *
 * UNIFIED with the `.tbd/` directory format (`tbd_format`): there is one format
 * code for all tbd-managed surfaces, sourced from `tbd-format.ts` (the single
-* source of truth). Bump `CURRENT_FORMAT` there when any managed surface — config
-* schema OR a generated agent surface — changes shape. A marked AGENTS.md block
+* source of truth). Bump `CURRENT_FORMAT` there when any managed surface (config
+* schema OR a generated agent surface) changes shape. A marked AGENTS.md block
 * with no `format=` field predates this and is treated as `f01`; a running tbd
 * that finds a HIGHER format than it knows refuses to overwrite it and tells the
 * user to upgrade tbd.
@@ -6728,6 +6171,7 @@ var StatusHandler = class extends BaseCommand {
 			worktree_healthy: null,
 			worktree_status: null,
 			workspaces: [],
+			docs_drift: null,
 			integrations: {
 				portable_skill: false,
 				portable_skill_path: AGENTS_SKILL_DISPLAY,
@@ -6751,7 +6195,12 @@ var StatusHandler = class extends BaseCommand {
 		statusData.beads_detected = beadsInfo.detected;
 		statusData.beads_issue_count = beadsInfo.issueCount;
 		statusData.integrations = await this.checkIntegrations(projectRoot);
-		if (statusData.initialized && tbdRoot) await this.loadPostInitInfo(tbdRoot, statusData);
+		if (statusData.initialized && tbdRoot) {
+			await this.loadPostInitInfo(tbdRoot, statusData);
+			try {
+				statusData.docs_drift = await computeForkDriftSummary(tbdRoot, FORK_DIR, await readForkManifest(tbdRoot));
+			} catch {}
+		}
 		this.output.data(statusData, () => {
 			this.renderText(statusData);
 		});
@@ -6896,6 +6345,15 @@ var StatusHandler = class extends BaseCommand {
 			console.log(`Run ${colors.bold("tbd setup auto")} to configure detected agents`);
 		}
 		if (data.worktree_status !== null && data.worktree_path) renderWorktreeStatus(data.worktree_path, data.worktree_status, colors);
+		if (data.docs_drift && data.docs_drift.forks > 0) {
+			const d = data.docs_drift;
+			const parts = [`${d.customized} customized`];
+			if (d.stale > 0) parts.push(`${d.stale} with upstream updates; run 'tbd docs update'`);
+			if (d.conflicted > 0) parts.push(`${d.conflicted} conflict pending`);
+			if (d.missing > 0) parts.push(`${d.missing} missing; see 'tbd docs status'`);
+			console.log("");
+			console.log(`${colors.bold("Docs:")} ${d.forks} forked (${parts.join(", ")})`);
+		}
 		if (data.workspaces.length > 0) {
 			console.log("");
 			console.log(colors.bold("WORKSPACES"));
@@ -7182,7 +6640,7 @@ function renderDiagnostics(results, colors) {
 *
 * Returns null when the remote branch does not exist (the caller then falls
 * through to local-branch / new-repo handling). Unrelated histories are a hard
-* ✗ finding routed to `tbd doctor --fix` (the rescue), NOT `tbd sync` — push
+* ✗ finding routed to `tbd doctor --fix` (the rescue), NOT `tbd sync`; push
 * can never fast-forward and a plain merge refuses, so `tbd sync` cannot help.
 */
 function classifyRemoteSyncHealth(health, remote, syncBranch) {
@@ -7191,7 +6649,7 @@ function classifyRemoteSyncHealth(health, remote, syncBranch) {
 		name: "Remote sync branch",
 		status: "error",
 		fixable: true,
-		message: `${remote}/${syncBranch} histories are unrelated (no common ancestor) — push cannot succeed`,
+		message: `${remote}/${syncBranch} histories are unrelated (no common ancestor); push cannot succeed`,
 		suggestion: "Run: tbd doctor --fix to reconcile the unrelated histories"
 	};
 	if (health.diverged) return {
@@ -7210,7 +6668,7 @@ function classifyRemoteSyncHealth(health, remote, syncBranch) {
 * The "Sync consistency" finding for a branch that is both ahead and behind.
 *
 * When the histories are unrelated, the remediation is the rescue
-* (`tbd doctor --fix`), NOT `tbd sync` — otherwise the unrelated-history error
+* (`tbd doctor --fix`), NOT `tbd sync`; otherwise the unrelated-history error
 * (which says "run doctor --fix") and this warning (which would say "run sync")
 * point at each other in a loop with no terminating instruction. See #158.
 */
@@ -7218,7 +6676,7 @@ function divergenceFinding(ahead, behind, unrelated) {
 	if (unrelated) return {
 		name: "Sync consistency",
 		status: "warn",
-		message: `diverged (${ahead} ahead, ${behind} behind) — unrelated histories`,
+		message: `diverged (${ahead} ahead, ${behind} behind): unrelated histories`,
 		suggestion: "Run: tbd doctor --fix to reconcile the unrelated histories"
 	};
 	return {
@@ -7234,7 +6692,7 @@ function divergenceFinding(ahead, behind, unrelated) {
 * `code` is the errno from attempting to create a directory under the shared
 * locks dir, or undefined on success. EPERM/EACCES is a hard error: every write
 * command must acquire this lock, so an unwritable lock path breaks all writes
-* (the #164 Codex-sandbox case) — and a lock tbd needs but cannot take is a
+* (the #164 Codex-sandbox case), and a lock tbd needs but cannot take is a
 * fatal condition, not a soft warning. Any other probe failure is reported as a
 * warning since it cannot be positively interpreted. Never `fixable`: tbd cannot
 * widen a sandbox or change filesystem permissions itself.
@@ -7327,6 +6785,15 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.safeCheck("Sync status", () => this.checkLocalVsRemoteData()));
 		healthChecks.push(await this.safeCheck("Clone status", () => this.checkCloneScenarios()));
 		healthChecks.push(await this.safeCheck("Sync consistency", () => this.checkSyncConsistency()));
+		try {
+			healthChecks.push(...await this.checkForkedDocs(options.fix));
+		} catch (error) {
+			healthChecks.push({
+				name: "Forked docs",
+				status: "error",
+				message: `check could not complete: ${error instanceof Error ? error.message : String(error)}`
+			});
+		}
 		const integrationChecks = [];
 		integrationChecks.push(await this.safeCheck("Portable Agent Skill", () => this.checkPortableSkill()));
 		integrationChecks.push(await this.safeCheck("Claude Code skill", () => this.checkClaudeSkill()));
@@ -7558,7 +7025,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Resolve merge conflicts in ids.yml")) try {
-			const { resolveIdMappingConflicts, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
+			const { resolveIdMappingConflicts, saveIdMapping } = await import("./id-mapping-D0iitY-F.mjs");
 			const resolved = resolveIdMappingConflicts(content);
 			await saveIdMapping(this.dataSyncDir, resolved);
 			return {
@@ -7607,7 +7074,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Fix duplicate ID mapping keys")) try {
-			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
+			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-D0iitY-F.mjs");
 			const mapping = await loadIdMapping(this.dataSyncDir);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			return {
@@ -7746,7 +7213,7 @@ var DoctorHandler = class extends BaseCommand {
 			name: "ID mapping coverage",
 			status: "ok"
 		};
-		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-mtoSP9Qt.mjs");
+		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-D0iitY-F.mjs");
 		const mapping = await loadIdMapping(this.dataSyncDir);
 		const missingIds = [];
 		for (const issue of this.issues) {
@@ -7758,10 +7225,10 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Create missing ID mappings")) {
-			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-mtoSP9Qt.mjs");
+			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-D0iitY-F.mjs");
 			let historicalMapping;
 			try {
-				const syncBranch = (await import("./config-YRRW9l89.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
+				const syncBranch = (await import("./config-DXhifxOw.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
 				const logArgs = ["log", "--format=%H"];
 				if (maxHistory > 0) logArgs.push(`-${maxHistory}`);
 				logArgs.push(syncBranch, "--", `${DATA_SYNC_DIR}/mappings/ids.yml`);
@@ -7999,11 +7466,23 @@ var DoctorHandler = class extends BaseCommand {
 		try {
 			layout = await readCommonDirLayout(layoutPath);
 		} catch (error) {
+			if (fix && !this.checkDryRun("Rewrite corrupt common-dir layout from config")) {
+				const configRef = this.config;
+				await withSharedDataSyncLock(this.cwd, async () => writeCommonDirLayout(sharedPaths, configRef));
+				return {
+					name: "Common-dir layout",
+					status: "ok",
+					message: "rewritten from config (was unreadable)",
+					path: layoutPath
+				};
+			}
 			return {
 				name: "Common-dir layout",
 				status: "error",
-				message: error instanceof Error ? error.message : String(error),
-				path: layoutPath
+				message: `${error instanceof Error ? error.message : String(error)}`,
+				path: layoutPath,
+				fixable: true,
+				suggestion: `Run: tbd doctor --fix (rewrites it from config), or delete ${layoutPath}`
 			};
 		}
 		if (!layout) return {
@@ -8019,6 +7498,25 @@ var DoctorHandler = class extends BaseCommand {
 			path: layoutPath,
 			suggestion: "Upgrade: npm install -g get-tbd@latest"
 		};
+		if (isLayoutUpgradeable(layout, this.config)) {
+			if (fix && !this.checkDryRun("Apply pending format migration")) {
+				await prepareDataSyncContext(this.cwd);
+				return {
+					name: "Common-dir layout",
+					status: "ok",
+					message: `format migration applied (${layout.tbd_format} → ${this.config.tbd_format})`,
+					path: layoutPath
+				};
+			}
+			return {
+				name: "Common-dir layout",
+				status: "warn",
+				message: `format migration pending (${layout.tbd_format} → ${this.config.tbd_format}); applies on next write or 'tbd doctor --fix'`,
+				path: layoutPath,
+				fixable: true,
+				suggestion: "Run: tbd doctor --fix (or any write command) to apply"
+			};
+		}
 		try {
 			validateCommonDirLayout(layout, this.config);
 			return {
@@ -8355,12 +7853,12 @@ var DoctorHandler = class extends BaseCommand {
 			if (consistency.localAhead > 0) return {
 				name: "Sync consistency",
 				status: "ok",
-				message: `${consistency.localAhead} local commit(s) not yet pushed — run \`tbd sync\` to push`
+				message: `${consistency.localAhead} local commit(s) not yet pushed; run \`tbd sync\` to push`
 			};
 			if (consistency.localBehind > 0) return {
 				name: "Sync consistency",
 				status: "ok",
-				message: `${consistency.localBehind} remote commit(s) not yet pulled — run \`tbd sync\` to pull`
+				message: `${consistency.localBehind} remote commit(s) not yet pulled; run \`tbd sync\` to pull`
 			};
 			return {
 				name: "Sync consistency",
@@ -8380,6 +7878,198 @@ var DoctorHandler = class extends BaseCommand {
 			};
 		}
 	}
+	/**
+	* Check 16 group: Forked docs (`.tbd/doc-forks/` ↔ base snapshots ↔ fork dir).
+	*
+	* Validates the forkable-docs state per the f05 spec (Phase 2 doctor checks):
+	* manifest readability, missing forked files (--fix finalizes the unfork),
+	* orphaned entries whose upstream doc is gone (--fix removes the entry),
+	* base snapshot presence/hash integrity (no auto-fix; re-fork vs unfork is
+	* the user's call), unresolved tbd conflict markers, user docs claiming the
+	* reserved `tbd-` name prefix, and a gitignored fork dir.
+	*
+	* Returns zero findings when nothing is forked and no fork dir exists, so
+	* doctor output is byte-identical for repos that never touched forking.
+	* See: docs/project/specs/done/plan-2026-06-11-forkable-docs.md §`tbd doctor`.
+	*/
+	async checkForkedDocs(fix) {
+		const name = "Forked docs";
+		const { DOC_FORKS_DIR, FORKS_FILE, findFork, hashContent, hasUnresolvedConflict, readForkManifest, removeBaseContent, removeFork, withForkManifestLock, writeForkManifest } = await import("./fork-manifest-C7lGRq-6.mjs");
+		const manifestPath = `${DOC_FORKS_DIR}/${FORKS_FILE}`;
+		let manifest;
+		try {
+			manifest = await readForkManifest(this.cwd);
+		} catch (error) {
+			return [{
+				name,
+				status: "warn",
+				message: `fork manifest unreadable: ${(error instanceof Error ? error.message : String(error)).split("\n")[0]}`,
+				path: manifestPath,
+				suggestion: `Fix or delete ${manifestPath} (forked files stay in place), then re-run tbd doctor`
+			}];
+		}
+		let forkDirExists = true;
+		try {
+			await access(join(this.cwd, FORK_DIR));
+		} catch {
+			forkDirExists = false;
+		}
+		if (manifest.forks.length === 0 && !forkDirExists) return [];
+		const { forkStatusFor, listLocalForkFiles, readForkBase, readForkFile, regenerateForkDirReadme, unforkDoc } = await import("./doc-fork-BMjqzfAs.mjs");
+		const { DocCache } = await import("./doc-cache-CiBwpDTf.mjs");
+		const kindCachePaths = {
+			guideline: CACHE_GUIDELINES_PATHS,
+			shortcut: CACHE_SHORTCUT_PATHS,
+			template: CACHE_TEMPLATE_PATHS,
+			reference: CACHE_REFERENCE_PATHS
+		};
+		const caches = /* @__PURE__ */ new Map();
+		const missing = [];
+		const orphaned = [];
+		const baseProblems = [];
+		const conflicted = [];
+		for (const entry of manifest.forks) {
+			let cache = caches.get(entry.kind);
+			if (!cache) {
+				cache = new DocCache(kindCachePaths[entry.kind] ?? [], this.cwd);
+				await cache.load({ quiet: true });
+				caches.set(entry.kind, cache);
+			}
+			const cacheContent = cache.get(entry.name)?.doc.content ?? null;
+			const status = await forkStatusFor(this.cwd, FORK_DIR, entry, cacheContent);
+			if (status.state === "missing") {
+				missing.push(entry);
+				continue;
+			}
+			if (status.orphaned) {
+				orphaned.push(entry);
+				continue;
+			}
+			const base = await readForkBase(this.cwd, entry);
+			if (base === null) baseProblems.push(`${entry.name}: missing`);
+			else if (hashContent(base) !== entry.base_hash) baseProblems.push(`${entry.name}: hash mismatch`);
+			const content = await readForkFile(this.cwd, FORK_DIR, entry);
+			if (content !== null && hasUnresolvedConflict(content)) conflicted.push(entry.name);
+		}
+		const results = [];
+		if (missing.length > 0) {
+			const message = `${missing.length} missing (${missing.map((e) => e.name).join(", ")}: forked file deleted)`;
+			if (fix && !this.checkDryRun("Finalize unfork of deleted forked docs")) try {
+				await withForkManifestLock(this.cwd, async () => {
+					let current = await readForkManifest(this.cwd);
+					for (const entry of missing) {
+						if (!findFork(current, entry.name, entry.kind)) continue;
+						current = (await unforkDoc({
+							tbdRoot: this.cwd,
+							forkDir: FORK_DIR,
+							manifest: current,
+							name: entry.name,
+							kind: entry.kind
+						})).manifest;
+					}
+					await writeForkManifest(this.cwd, current);
+					await regenerateForkDirReadme(this.cwd, FORK_DIR, current);
+				});
+				results.push({
+					name,
+					status: "warn",
+					message,
+					details: ["Fixed: finalized unfork (removed manifest entry + base); now served from upstream"]
+				});
+			} catch (error) {
+				results.push({
+					name,
+					status: "error",
+					message: `failed to finalize unfork: ${error instanceof Error ? error.message : String(error)}`
+				});
+			}
+			else results.push({
+				name,
+				status: "warn",
+				message,
+				fixable: true,
+				suggestion: "Run: tbd doctor --fix to finalize the unfork, or tbd docs fork <name> --force to restore"
+			});
+		}
+		if (orphaned.length > 0) {
+			const message = `${orphaned.length} orphaned (${orphaned.map((e) => e.name).join(", ")}: upstream doc no longer exists)`;
+			if (fix && !this.checkDryRun("Remove orphaned fork manifest entries")) try {
+				await withForkManifestLock(this.cwd, async () => {
+					let current = await readForkManifest(this.cwd);
+					for (const entry of orphaned) {
+						current = removeFork(current, entry.name, entry.kind);
+						await removeBaseContent(this.cwd, entry.kind, entry.name);
+					}
+					await writeForkManifest(this.cwd, current);
+					await regenerateForkDirReadme(this.cwd, FORK_DIR, current);
+				});
+				results.push({
+					name,
+					status: "warn",
+					message,
+					details: [`Fixed: removed orphaned manifest entr${orphaned.length === 1 ? "y" : "ies"} + base; file kept as a local doc`]
+				});
+			} catch (error) {
+				results.push({
+					name,
+					status: "error",
+					message: `failed to remove orphaned entries: ${error instanceof Error ? error.message : String(error)}`
+				});
+			}
+			else results.push({
+				name,
+				status: "warn",
+				message,
+				fixable: true,
+				suggestion: "Run: tbd doctor --fix to remove the entry (your file is kept as a local doc)"
+			});
+		}
+		if (baseProblems.length > 0) results.push({
+			name,
+			status: "warn",
+			message: `${baseProblems.length} base snapshot problem${baseProblems.length === 1 ? "" : "s"} (${baseProblems.join(", ")})`,
+			suggestion: "Run: tbd docs fork <name> --force to re-fork, or tbd docs unfork <name>"
+		});
+		if (conflicted.length > 0) results.push({
+			name,
+			status: "warn",
+			message: `${conflicted.length} unresolved merge conflict${conflicted.length === 1 ? "" : "s"} (${conflicted.join(", ")})`,
+			suggestion: "Run: resolve the conflict markers, then re-run tbd docs update"
+		});
+		if (manifest.forks.length > 0 && results.length === 0) results.push({
+			name,
+			status: "ok",
+			message: `${manifest.forks.length} forked, base snapshots intact`
+		});
+		const reserved = (await listLocalForkFiles(this.cwd, FORK_DIR, manifest)).filter((l) => l.name.startsWith("tbd-"));
+		if (reserved.length > 0) results.push({
+			name: "Reserved tbd- names",
+			status: "warn",
+			message: `${reserved.length} user doc${reserved.length === 1 ? " claims" : "s claim"} the reserved tbd- prefix`,
+			details: reserved.map((l) => l.relPath),
+			suggestion: "Rename the file(s): the tbd- prefix is reserved for tbd self-docs"
+		});
+		if (manifest.forks.length > 0) {
+			let ignored = false;
+			try {
+				await git("-C", this.cwd, "check-ignore", "-q", FORK_DIR);
+				ignored = true;
+			} catch {
+				ignored = false;
+			}
+			results.push(ignored ? {
+				name: "Fork dir",
+				status: "warn",
+				message: `${FORK_DIR}/ is gitignored; forked docs will not be committed`,
+				suggestion: `Remove the .gitignore rule covering ${FORK_DIR}/ so forks are tracked in git`
+			} : {
+				name: "Fork dir",
+				status: "ok",
+				message: `${FORK_DIR}/ tracked in git (not gitignored)`
+			});
+		}
+		return results;
+	}
 };
 const doctorCommand = new Command("doctor").description("Diagnose and repair repository").option("--fix", "Attempt to fix issues").option("--max-history <n>", "Max git commits to scan for ID mapping recovery (0 = full history)", "50").action(async (options, command) => {
 	await new DoctorHandler(command).run(options);
@@ -8404,6 +8094,13 @@ var ConfigShowHandler = class extends BaseCommand {
 		this.output.data(config, () => {
 			const colors = this.output.getColors();
 			console.log(`${colors.dim("tbd_version:")} ${config.tbd_version}`);
+			if (config.tbd_upgrades && config.tbd_upgrades.length > 0) {
+				console.log(`${colors.dim("tbd_upgrades:")}`);
+				for (const entry of config.tbd_upgrades) {
+					const when = entry.at ? ` ${colors.dim(`(${entry.at})`)}` : "";
+					console.log(`  ${colors.dim("-")} ${entry.version}${when}`);
+				}
+			}
 			console.log(`${colors.dim("sync:")}`);
 			console.log(`  ${colors.dim("branch:")} ${config.sync.branch}`);
 			console.log(`  ${colors.dim("remote:")} ${config.sync.remote}`);
@@ -9079,157 +8776,1355 @@ const importCommand = new Command("import").description("Import issues from JSON
 });
 
 //#endregion
-//#region src/cli/commands/docs.ts
+//#region src/file/fork-update.ts
 /**
-* `tbd docs` - Display CLI documentation.
-*
-* Shows the bundled documentation for tbd CLI.
-* Documentation can be filtered by section.
+* Updating forked docs after upstream moves: three-way merge plus the per-state
+* decision logic from the spec's update table.
 *
-* Note: Doc cache sync functionality has moved to `tbd sync --docs`.
-* See: docs/project/specs/active/plan-2026-01-29-unified-sync-command.md
+* The merge itself is outsourced to git (`git merge-file`), which works on plain
+* files, reports the conflict count via exit code, and uses standard conflict
+* markers. Nothing in the git repo state is touched.
 */
+const MERGE_MAX_BUFFER = 16 * 1024 * 1024;
 /**
-* Get the path to the bundled docs file.
-* The docs file is copied to dist/docs/ during build.
+* Three-way merge of `current` and `other` against their common `base`, via
+* `git merge-file -p`. Returns the merged text (with standard conflict markers
+* when conflicts arise) and the conflict count. Pure with respect to repo state:
+* it only uses temporary files.
 */
-function getDocsPath() {
-	return join(dirname(fileURLToPath(import.meta.url)), "docs", "tbd-docs.md");
-}
-var DocsHandler = class extends BaseCommand {
-	async run(topic, options) {
-		let content;
-		try {
-			content = await readFile(getDocsPath(), "utf-8");
-		} catch {
-			try {
-				content = await readFile(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "docs", "tbd-docs.md"), "utf-8");
-			} catch {
-				throw new CLIError("Documentation file not found. Please rebuild the CLI.");
-			}
-		}
-		const sections = this.extractSections(content);
-		if (options.all) {
-			await this.showComprehensiveListing();
-			return;
-		}
-		if (options.list) {
-			this.output.data(sections, () => {
-				const colors = this.output.getColors();
-				console.log(colors.bold("Available documentation sections:"));
-				console.log("");
-				const maxSlugLen = Math.max(...sections.map((s) => s.slug.length));
-				for (const section of sections) {
-					const paddedSlug = section.slug.padEnd(maxSlugLen);
-					console.log(`  ${colors.id(paddedSlug)}  ${section.title}`);
+async function mergeContents(current, base, other, labels = {}) {
+	const dir = await mkdtemp(join(tmpdir(), "tbd-merge-"));
+	const currentPath = join(dir, "current");
+	const basePath = join(dir, "base");
+	const otherPath = join(dir, "other");
+	try {
+		await Promise.all([
+			writeFile(currentPath, normalizeLineEndings(current)),
+			writeFile(basePath, normalizeLineEndings(base)),
+			writeFile(otherPath, normalizeLineEndings(other))
+		]);
+		const args = [
+			"merge-file",
+			"-p",
+			"-L",
+			labels.current ?? CONFLICT_LABELS.ours,
+			"-L",
+			labels.base ?? CONFLICT_LABELS.base,
+			"-L",
+			labels.other ?? CONFLICT_LABELS.theirs,
+			currentPath,
+			basePath,
+			otherPath
+		];
+		return await new Promise((resolve, reject) => {
+			execFile("git", args, {
+				maxBuffer: MERGE_MAX_BUFFER,
+				env: gitSafeEnv()
+			}, (error, stdout, stderr) => {
+				if (error) {
+					const code = error.code;
+					if (typeof code === "number" && code > 0 && code <= 127) {
+						resolve({
+							merged: stdout,
+							conflicts: code
+						});
+						return;
+					}
+					const detail = String(stderr ?? "").trim();
+					reject(new Error(`git merge-file failed${detail ? `: ${detail}` : ""}`, { cause: error }));
+					return;
 				}
-				console.log("");
-				console.log(`Use ${colors.dim("tbd docs <topic>")} to view a specific section.`);
+				resolve({
+					merged: stdout,
+					conflicts: 0
+				});
 			});
-			return;
-		}
-		const sectionQuery = topic ?? options.section;
-		if (sectionQuery) {
-			const sectionContent = this.extractSection(content, sections, sectionQuery);
-			if (!sectionContent) throw new NotFoundError("Section", `"${sectionQuery}" (use --list to see available sections)`);
-			content = sectionContent;
-		}
-		if (shouldUseInteractiveOutput(this.ctx)) await paginateOutput(renderMarkdown(content, this.ctx.color), true);
-		else console.log(content);
+		});
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
 	}
-	/**
-	* Extract section metadata from the documentation.
-	* Sections are top-level headers (## ).
-	* Returns title and slugified ID for each section.
-	*/
-	extractSections(content) {
-		const sections = [];
-		const lines = content.split("\n");
-		const slugger = new GithubSlugger();
-		for (const line of lines) if (line.startsWith("## ")) {
-			const title = line.slice(3).trim();
-			const slug = slugger.slug(title);
-			sections.push({
-				title,
-				slug
+}
+/**
+* Unified diff of two contents via `git diff --no-index`. Returns the diff text
+* (empty string when identical). Uses temporary files and touches no repo state.
+*/
+async function diffContents(left, right, labels = {}) {
+	const dir = await mkdtemp(join(tmpdir(), "tbd-diff-"));
+	const leftName = labels.left ?? "a";
+	const rightName = labels.right ?? "b";
+	try {
+		await Promise.all([writeFile(join(dir, leftName), left), writeFile(join(dir, rightName), right)]);
+		return await new Promise((resolve, reject) => {
+			execFile("git", [
+				"diff",
+				"--no-index",
+				"--no-color",
+				"--no-prefix",
+				leftName,
+				rightName
+			], {
+				cwd: dir,
+				maxBuffer: MERGE_MAX_BUFFER,
+				env: gitSafeEnv()
+			}, (error, stdout) => {
+				if (error) {
+					if (error.code === 1) {
+						resolve(stdout);
+						return;
+					}
+					reject(error instanceof Error ? error : /* @__PURE__ */ new Error("git diff failed"));
+					return;
+				}
+				resolve(stdout);
 			});
-		}
-		return sections;
+		});
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
 	}
-	/**
-	* Extract a specific section from the documentation.
-	* Matches by slug or partial title match.
-	* Returns content from the section header to the next section header.
-	*/
-	extractSection(content, sections, query) {
-		const lowerQuery = query.toLowerCase();
-		const matchedSection = sections.find((s) => s.slug === lowerQuery) ?? sections.find((s) => s.title.toLowerCase().includes(lowerQuery));
-		if (!matchedSection) return null;
-		const lines = content.split("\n");
-		let inSection = false;
-		const sectionLines = [];
-		for (const line of lines) if (line.startsWith("## ")) {
-			if (inSection) break;
-			if (line.slice(3).trim() === matchedSection.title) {
-				inSection = true;
-				sectionLines.push(line);
-			}
-		} else if (inSection) sectionLines.push(line);
-		if (sectionLines.length === 0) return null;
-		while (sectionLines.length > 0) if (sectionLines[sectionLines.length - 1]?.trim() === "") sectionLines.pop();
-		else break;
-		return sectionLines.join("\n");
+}
+/**
+* Decide and (when needed) perform the three-way merge for a single forked doc,
+* implementing the spec's update decision table across the default / --merge /
+* --keep-ours strategies. Pure aside from the git merge-file call.
+*/
+async function updateOne(input) {
+	const { entry, forkContent, baseContent, upstreamContent, strategy } = input;
+	const name = entry.name;
+	if (forkContent === null) return {
+		action: "skip-missing",
+		message: `${name}: forked file is missing (doctor's job)`
+	};
+	if (upstreamContent === null) return {
+		action: "skip-orphaned",
+		message: `${name}: upstream removed this doc; keep your copy or 'tbd docs unfork ${name}'`
+	};
+	if (entry.conflicted && hasUnresolvedConflict(forkContent)) return {
+		action: "skip-unresolved",
+		message: `${name}: unresolved conflict markers; resolve them first`
+	};
+	if (input.runningVersion !== void 0 && entry.tbd_version !== void 0 && compareVersionsLoose(input.runningVersion, entry.tbd_version) === -1) return {
+		action: "skip-newer-base",
+		message: `${name}: fork point was set by tbd ${entry.tbd_version} (you have ${input.runningVersion}); upgrade tbd before updating this doc`
+	};
+	if (baseContent === null) {
+		if (strategy === "keep-ours") return {
+			action: "repaired",
+			newBaseContent: upstreamContent,
+			message: `${name}: re-established missing base from upstream (file kept)`
+		};
+		return {
+			action: "skip-no-base",
+			needsDecision: true,
+			message: `${name}: base snapshot missing: cannot merge; re-run with --keep-ours to repair`
+		};
 	}
-	/**
-	* Show a comprehensive listing of all documentation resources organized by purpose.
-	*/
-	async showComprehensiveListing() {
-		const colors = this.output.getColors();
-		console.log(colors.bold("=== tbd Documentation Resources ==="));
-		console.log("");
-		console.log(colors.bold("Getting Started:"));
-		console.log("  tbd                          Full orientation and project status");
-		console.log("  tbd prime                    Workflow context and guidance");
-		console.log("  tbd prime --brief            Quick reference (~35 lines)");
-		console.log("  tbd --help                   CLI command reference");
-		console.log("");
-		console.log(colors.bold("Workflows (Shortcuts):"));
-		console.log("  tbd shortcut --list          List all available shortcuts");
-		console.log("  tbd shortcut new-plan-spec   Plan a new feature");
-		console.log("  tbd shortcut code-review-and-commit     Commit code properly");
-		console.log("  tbd shortcut create-or-update-pr-simple  Create a pull request");
-		console.log("");
-		console.log(colors.bold("Guidelines (Coding Standards):"));
-		console.log("  tbd guidelines --list        List all available guidelines");
-		console.log("  tbd guidelines typescript-rules      TypeScript best practices");
-		console.log("  tbd guidelines general-tdd-guidelines  Test-driven development");
-		console.log("  tbd guidelines golden-testing-guidelines  Snapshot/golden testing");
-		console.log("");
-		console.log(colors.bold("Templates:"));
-		console.log("  tbd template --list          List all available templates");
-		console.log("  tbd template plan-spec       Feature planning template");
-		console.log("  tbd template architecture-doc    Architecture document template");
-		console.log("");
-		console.log(colors.bold("Design & Reference:"));
-		console.log("  tbd docs --list              List documentation sections");
-		console.log("  tbd design                   tbd design document");
-		console.log("  tbd closing                  Session closing protocol");
-		console.log("");
-		console.log(colors.bold("Quick Tips:"));
-		console.log("  - Run tbd ready to see what issues are available to work on");
-		console.log("  - Run tbd shortcut <name> to get step-by-step instructions");
-		console.log("  - Run tbd guidelines <name> to get coding standards");
-		console.log("  - Always run tbd sync at the end of a session");
+	const customized = hashContent(forkContent) !== hashContent(baseContent);
+	if (!(hashContent(upstreamContent) !== hashContent(baseContent))) return {
+		action: "skip-not-stale",
+		message: `${name}: already up to date`
+	};
+	if (!customized) {
+		if (strategy === "keep-ours") return {
+			action: "kept",
+			newBaseContent: upstreamContent,
+			message: `${name}: kept your version; fork point advanced`
+		};
+		return {
+			action: "replaced",
+			newFileContent: upstreamContent,
+			newBaseContent: upstreamContent,
+			message: `${name}: refreshed to upstream (was unmodified)`
+		};
 	}
-};
-const docsCommand = new Command("docs").description("Display CLI documentation (use tbd sync --docs for doc cache sync)").argument("[topic]", "Topic to display (e.g., \"commands\", \"id-system\")").option("--section <name>", "Show specific section (e.g., \"commands\", \"workflows\")").option("--list", "List available sections").option("--all", "Show comprehensive listing of all documentation resources").action(async (topic, options, command) => {
-	await new DocsHandler(command).run(topic, options);
-});
+	if (strategy === "keep-ours") return {
+		action: "kept",
+		newBaseContent: upstreamContent,
+		message: `${name}: kept your version; fork point advanced`
+	};
+	const merge = await mergeContents(forkContent, baseContent, upstreamContent);
+	if (merge.conflicts === 0) return {
+		action: "merged-clean",
+		newFileContent: merge.merged,
+		newBaseContent: upstreamContent,
+		message: `${name}: merged upstream cleanly (review with: git diff)`
+	};
+	if (strategy === "merge") return {
+		action: "merged-conflict",
+		newFileContent: merge.merged,
+		newBaseContent: upstreamContent,
+		setConflicted: true,
+		message: `${name}: wrote merged content with conflict markers; resolve them, then it returns to 'customized'`
+	};
+	return {
+		action: "skip-conflict-listed",
+		needsDecision: true,
+		message: `${name}: your changes conflict with upstream`
+	};
+}
 
 //#endregion
-//#region src/cli/commands/closing.ts
-/**
-* `tbd closing` - Display the session closing protocol reminder.
+//#region src/docmap/docmap.ts
+/**
+* docmap: a minimal, machine-readable inventory of a collection of documents.
+*
+* A docmap is a "sitemap for docs": one entry per document, each with an identity
+* (`type` + `name`, unique within the map), a location (`path` and/or a provenance
+* `source` docref; at least one is required), and presentation metadata (`title`,
+* `description`). It describes a collection; it says nothing about how the
+* collection is assembled, fetched, or kept fresh; a docmap is a generated VIEW
+* of a collection, never an input to resolution.
+*
+* Path convention: for a docmap committed as a file, `path` is relative to the
+* docmap file's own directory (the sitemap convention); generated docmaps state
+* their collection root out of band.
+*
+* This is the docmap/0.1 format. The module is standalone and dependency-free (no
+* tbd-internal imports) so it can move to its own package later. Consumers MUST
+* ignore unknown fields, so producers (such as tbd) may attach extension fields:
+* for example tbd's `state`/`stale`, or size metrics like `word_count` /
+* `size_bytes`, without breaking other readers; core fields stay minimal.
+*/
+/** Current docmap format version tag. */
+const DOCMAP_VERSION = "docmap/0.1";
+/**
+* One document in a docmap. Unknown fields are preserved (extension fields).
+* Every entry must carry a location: `path` and/or `source`; an inventory whose
+* entries cannot be located is not an inventory.
+*/
+const DocMapEntrySchema = z.object({
+	name: z.string().min(1),
+	type: z.string().min(1),
+	path: z.string().optional(),
+	source: z.string().optional(),
+	title: z.string().optional(),
+	description: z.string().optional()
+}).passthrough().refine((entry) => entry.path !== void 0 || entry.source !== void 0, { message: "docmap entry must have a location: path and/or source" });
+/**
+* A document inventory. `documents` entries are unique by (`type`, `name`).
+*/
+const DocMapSchema = z.object({
+	docmap: z.string(),
+	name: z.string().optional(),
+	documents: z.array(DocMapEntrySchema)
+}).passthrough();
+/** Error thrown when an object is not a valid docmap. */
+var DocMapError = class extends Error {
+	constructor(detail) {
+		super(`Invalid docmap: ${detail}`);
+		this.name = "DocMapError";
+	}
+};
+/** Stable key for an entry's identity. */
+function entryKey(entry) {
+	return `${entry.type}:${entry.name}`;
+}
+/** Assert that entries are unique by (type, name); throws {@link DocMapError}. */
+function assertUniqueIdentities(documents) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of documents) {
+		const key = entryKey(entry);
+		if (seen.has(key)) throw new DocMapError(`duplicate entry identity ${JSON.stringify(key)}`);
+		seen.add(key);
+	}
+}
+/**
+* Build a docmap from entries. Validates each entry and identity uniqueness.
+*/
+function createDocMap(documents, options = {}) {
+	const parsed = documents.map((d) => DocMapEntrySchema.parse(d));
+	assertUniqueIdentities(parsed);
+	const map = {
+		docmap: DOCMAP_VERSION,
+		documents: parsed
+	};
+	if (options.name !== void 0) map.name = options.name;
+	return map;
+}
+
+//#endregion
+//#region src/cli/lib/doc-serve.ts
+/**
+* Shared construction of docmap entries for served docs: the one-model,
+* one-renderer contract (spec Decisions 21/22): `tbd docs list`/`show`, the
+* bare overview, and the per-kind readers all build entries here, so their
+* JSON output cannot drift.
+*/
+const KIND_FORK_DIRS = {
+	guideline: FORK_GUIDELINES_DIR,
+	shortcut: FORK_SHORTCUTS_DIR,
+	template: FORK_TEMPLATES_DIR,
+	reference: FORK_REFERENCES_DIR
+};
+const KIND_CACHE_DIRS = {
+	guideline: CACHE_GUIDELINES_PATHS,
+	shortcut: CACHE_SHORTCUT_PATHS,
+	template: CACHE_TEMPLATE_PATHS,
+	reference: CACHE_REFERENCE_PATHS
+};
+/**
+* Validated repo-relative dirs from docs_cache.local_dirs (./-prefixed local
+* docrefs). Invalid entries are skipped; doctor surfaces them.
+*/
+function sanitizeLocalDirs(localDirs) {
+	const out = [];
+	for (const dir of localDirs ?? []) {
+		const parsed = tryParseDocRef(dir);
+		if (parsed?.kind === "local" && dir.startsWith("./")) out.push(parsed.path.replace(/^\.\//, "").replace(/\/+$/, ""));
+	}
+	return out;
+}
+/**
+* Effective lookup order for serving one kind: fork dir → local_dirs → cache
+* (the resolution precedence the design fixes). local_dirs entries serve for
+* every kind so reads find them by name; inventory surfaces dedupe so each
+* local doc appears once.
+*/
+function effectiveServePaths(kind, localDirs) {
+	return [
+		KIND_FORK_DIRS[kind],
+		...localDirs,
+		...KIND_CACHE_DIRS[kind]
+	];
+}
+/**
+* Build the docmap entry (+ state marker) for one served doc. Single point of
+* construction for every docs inventory and read surface (Decision 21/22).
+* Every entry carries a location: forked docs have path+source, local files a
+* path, upstream docs their provenance docref.
+*/
+function servedEntryFor(tbdRoot, kind, doc, manifest, files, localDirs = []) {
+	const fork = findFork(manifest, doc.name, kind);
+	const isLocalDir = !fork && localDirs.some((d) => doc.sourceDir === d);
+	const isLocal = !fork && (doc.sourceDir.startsWith(FORK_DIR) || isLocalDir);
+	let state = "upstream";
+	let marker = "";
+	if (fork) {
+		const customized = hashContent(doc.content) !== fork.base_hash;
+		state = customized ? "customized" : "forked";
+		marker = customized ? "[forked, customized]" : "[forked]";
+	} else if (isLocal) {
+		state = "local";
+		marker = "[local]";
+	}
+	const localPath = isLocalDir ? `${doc.sourceDir}/${doc.name}.md` : `${FORK_DIR}/${KIND_DIR[kind]}/${doc.name}.md`;
+	return {
+		entry: {
+			name: doc.name,
+			type: kind,
+			...fork ? {
+				path: fork.path,
+				source: fork.source
+			} : isLocal ? { path: localPath } : { source: sourceDocRefFor(tbdRoot, files, doc.path) },
+			title: doc.frontmatter?.title,
+			description: doc.frontmatter?.description,
+			state
+		},
+		state,
+		marker
+	};
+}
+/** Load the shared context servedEntryFor needs (manifest + config maps). */
+async function loadServeContext(tbdRoot) {
+	const manifest = await readForkManifest(tbdRoot);
+	const config = await readConfig(tbdRoot);
+	return {
+		manifest,
+		files: config.docs_cache?.files,
+		localDirs: sanitizeLocalDirs(config.docs_cache?.local_dirs)
+	};
+}
+/** Derive the provenance docref for a cached doc from config, defaulting to internal:. */
+function sourceDocRefFor(tbdRoot, files, docPath) {
+	const rel = relative(join(tbdRoot, TBD_DOCS_DIR), docPath).split(sep).join("/");
+	return files?.[rel] ?? `internal:${rel}`;
+}
+
+//#endregion
+//#region src/lib/doc-categories.ts
+/**
+* The fixed category vocabulary for bundled docs. Every bundled guideline
+* declares exactly one in frontmatter (enforced by doc-categories.test.ts);
+* the old name-based inference is retired in favor of the declared field.
+*/
+const DOC_CATEGORIES = [
+	"general",
+	"typescript",
+	"python",
+	"convex",
+	"electron"
+];
+/**
+* A doc's declared category, or `undefined` if it does not declare one of the
+* known categories. Categories are guideline-oriented; non-guideline docs
+* (shortcuts, templates, references) generally declare other categories or none,
+* so they return `undefined` and are not matched by `--category` selection.
+* (Previously this defaulted unknown/undeclared categories to `general`, which
+* made `--category=general` a catch-all that over-forked every such doc.)
+*/
+function docCategory(frontmatter) {
+	const declared = frontmatter?.category;
+	return DOC_CATEGORIES.includes(declared ?? "") ? declared : void 0;
+}
+/** Validate a user-supplied --category value. */
+function parseCategoryOption(value) {
+	if (!DOC_CATEGORIES.includes(value)) throw new Error(`Unknown category "${value}". Valid categories: ${DOC_CATEGORIES.join(", ")}.`);
+	return value;
+}
+
+//#endregion
+//#region src/cli/commands/docs-fork.ts
+/** Kinds that can be resolved from the cache and forked today. */
+const RESOLVABLE_KINDS = [
+	"guideline",
+	"shortcut",
+	"template",
+	"reference"
+];
+/**
+* Validate a user-supplied --kind value. Without this, an unknown kind silently
+* produces an empty cache and misleading "no docs" output.
+*/
+function parseKindOption(kind) {
+	if (kind === void 0) return void 0;
+	if (!RESOLVABLE_KINDS.includes(kind)) throw new CLIError(`Unknown kind "${kind}". Valid kinds: ${RESOLVABLE_KINDS.join(", ")}.`);
+	return kind;
+}
+const KIND_CACHE_PATHS = {
+	guideline: CACHE_GUIDELINES_PATHS,
+	shortcut: CACHE_SHORTCUT_PATHS,
+	template: CACHE_TEMPLATE_PATHS,
+	reference: CACHE_REFERENCE_PATHS
+};
+/** Build a cache over a kind's cache-only paths (pristine upstream). */
+async function buildKindCache(kind, tbdRoot) {
+	const cache = new DocCache(KIND_CACHE_PATHS[kind] ?? [], tbdRoot);
+	await cache.load({ quiet: true });
+	return cache;
+}
+/** Derive the provenance docref for a cached doc from config, defaulting to internal:. */
+function sourceDocRef(tbdRoot, files, docPath) {
+	const rel = relative(join(tbdRoot, TBD_DOCS_DIR), docPath).split(sep).join("/");
+	return files?.[rel] ?? `internal:${rel}`;
+}
+var DocsForkHandler = class extends BaseCommand {
+	async run(names, options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const files = (await readConfig(tbdRoot)).docs_cache?.files;
+			const targets = await this.resolveTargets(tbdRoot, files, names, options);
+			if (targets.length === 0) throw new CLIError("No matching docs to fork. Run `tbd docs status` or `tbd guidelines --list`.");
+			if (options.dryRun) {
+				const catSuffix = options.category && options.category.length > 0 ? ` (categories: ${options.category.join(", ")})` : "";
+				this.output.dryRun(`Would fork ${targets.length} doc(s) into ${FORK_DIR}/${catSuffix}`, { docs: targets.map((t) => `${t.kind}/${t.name}`) });
+				if (!this.ctx.json) {
+					for (const t of targets) console.log(`  ${t.kind.padEnd(11)} ${t.name}`);
+					console.log("No files written. Re-run without --dry-run to apply.");
+				}
+				return;
+			}
+			const forked = [];
+			await withForkManifestLock(tbdRoot, async () => {
+				let manifest = await readForkManifest(tbdRoot);
+				for (const t of targets) {
+					let result;
+					try {
+						result = await forkDoc({
+							tbdRoot,
+							forkDir: FORK_DIR,
+							manifest,
+							kind: t.kind,
+							name: t.name,
+							source: t.source,
+							content: t.content,
+							tbdVersion: VERSION,
+							force: options.force
+						});
+					} catch (err) {
+						if (err instanceof ForkConflictError && err.code === "overwrite") throw new CLIError(`${err.message}. Refusing to overwrite it. Options:\n  tbd docs diff ${t.name}           # see how it differs\n  tbd docs fork ${t.name} --force   # overwrite with upstream`);
+						throw err;
+					}
+					manifest = result.manifest;
+					forked.push(result.relPath);
+					if (!this.ctx.json) this.output.success(`Forked ${t.name} → ${result.relPath}`);
+				}
+				await writeForkManifest(tbdRoot, manifest);
+				await regenerateForkDirReadme(tbdRoot, FORK_DIR, manifest);
+			});
+			if (this.ctx.json) this.output.data({ forked });
+			else {
+				const colors = this.output.getColors();
+				console.log(colors.dim(`  Regenerated ${FORK_DIR}/README.md`));
+				console.log("");
+				console.log("Edit in place; tbd now serves your copy wherever it served upstream.");
+			}
+		}, "Failed to fork");
+	}
+	async resolveTargets(tbdRoot, files, names, options) {
+		const parsedKind = parseKindOption(options.kind);
+		const kinds = parsedKind ? [parsedKind] : RESOLVABLE_KINDS;
+		const categories = (options.category ?? []).map(parseCategoryOption);
+		const byCategory = categories.length > 0;
+		if (options.all || byCategory) {
+			const targets = [];
+			for (const kind of kinds) {
+				if (byCategory && kind !== "guideline") continue;
+				const cache = await buildKindCache(kind, tbdRoot);
+				for (const doc of cache.list()) {
+					if (kind === "shortcut" && doc.sourceDir.endsWith("system")) continue;
+					if (byCategory) {
+						const cat = docCategory(doc.frontmatter);
+						if (cat === void 0 || !categories.includes(cat)) continue;
+					}
+					targets.push({
+						kind,
+						name: doc.name,
+						source: sourceDocRef(tbdRoot, files, doc.path),
+						content: doc.content
+					});
+				}
+			}
+			return targets;
+		}
+		const caches = /* @__PURE__ */ new Map();
+		for (const kind of kinds) caches.set(kind, await buildKindCache(kind, tbdRoot));
+		const targets = [];
+		for (const name of names) {
+			const matches = [];
+			for (const kind of kinds) {
+				const hit = caches.get(kind).get(name);
+				if (hit) matches.push({
+					kind,
+					name: hit.doc.name,
+					source: sourceDocRef(tbdRoot, files, hit.doc.path),
+					content: hit.doc.content
+				});
+			}
+			if (matches.length === 0) throw new CLIError(`No doc found named "${name}". Run \`tbd guidelines --list\` to see names.`);
+			if (matches.length > 1) throw new CLIError(`"${name}" exists in multiple kinds (${matches.map((m) => m.kind).join(", ")}). Use --kind to disambiguate.`);
+			targets.push(matches[0]);
+		}
+		return targets;
+	}
+};
+var DocsUnforkHandler = class extends BaseCommand {
+	async run(names, options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const removed = [];
+			await withForkManifestLock(tbdRoot, async () => {
+				let manifest = await readForkManifest(tbdRoot);
+				const targetNames = options.all ? manifest.forks.map((f) => f.name) : names;
+				if (targetNames.length === 0) throw new CLIError("Specify a doc name to unfork, or use --all.");
+				for (const name of targetNames) try {
+					manifest = (await unforkDoc({
+						tbdRoot,
+						forkDir: FORK_DIR,
+						manifest,
+						name,
+						kind: parseKindOption(options.kind),
+						force: options.force
+					})).manifest;
+					removed.push(name);
+					if (!this.ctx.json) this.output.success(`Unforked ${name}, served from upstream again.`);
+				} catch (err) {
+					if (err instanceof ForkConflictError && err.code === "customized") throw new CLIError(`${name} has local customizations (differs from its base). Refusing to discard them. Options:\n  tbd docs diff ${name}             # review your changes\n  tbd docs unfork ${name} --force   # discard and fall back to upstream`);
+					throw err;
+				}
+				await writeForkManifest(tbdRoot, manifest);
+				await regenerateForkDirReadme(tbdRoot, FORK_DIR, manifest);
+			});
+			if (this.ctx.json) this.output.data({ unforked: removed });
+		}, "Failed to unfork");
+	}
+};
+/** Compose the display label for a doc's state, combining customized + stale. */
+function stateLabel(state, stale) {
+	if ((state === "customized" || state === "orphaned" || state === "conflicted") && stale) return `${state}, stale`;
+	return state;
+}
+var DocsStatusHandler = class extends BaseCommand {
+	async run(options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const manifest = await readForkManifest(tbdRoot);
+			const colors = this.output.getColors();
+			const caches = /* @__PURE__ */ new Map();
+			const rows = [];
+			for (const entry of manifest.forks) {
+				const kind = entry.kind;
+				if (!caches.has(kind)) caches.set(kind, await buildKindCache(kind, tbdRoot));
+				const status = await forkStatusFor(tbdRoot, FORK_DIR, entry, caches.get(kind).get(entry.name)?.doc.content ?? null);
+				rows.push({
+					name: entry.name,
+					kind: entry.kind,
+					label: stateLabel(status.state, status.stale),
+					path: entry.path,
+					source: entry.source,
+					customized: status.customized,
+					stale: status.stale,
+					conflicted: status.conflicted,
+					missing: status.state === "missing"
+				});
+			}
+			const locals = await listLocalForkFiles(tbdRoot, FORK_DIR, manifest);
+			for (const l of locals) rows.push({
+				name: l.name,
+				kind: l.kind,
+				label: "local",
+				path: l.relPath,
+				source: "—",
+				customized: false,
+				stale: false,
+				conflicted: false,
+				missing: false
+			});
+			rows.sort((a, b) => a.name.localeCompare(b.name));
+			if (this.ctx.json) {
+				const docs = rows.map((r) => ({
+					name: r.name,
+					type: r.kind,
+					path: r.path,
+					...r.source !== "—" ? { source: r.source } : {},
+					state: r.label,
+					stale: r.stale
+				}));
+				this.output.data(createDocMap(docs, { name: "tbd-forks" }));
+				return;
+			}
+			if (rows.length === 0) {
+				console.log("No docs forked into the repo.");
+				console.log(`Make some visible: ${colors.bold("tbd docs fork <name>")} or ${colors.bold("tbd docs fork --all")}`);
+				return;
+			}
+			const nameW = Math.max(4, ...rows.map((r) => r.name.length));
+			const kindW = Math.max(4, ...rows.map((r) => r.kind.length));
+			const stateW = Math.max(5, ...rows.map((r) => r.label.length));
+			const header = `${"NAME".padEnd(nameW)}  ${"KIND".padEnd(kindW)}  ${"STATE".padEnd(stateW)}  SOURCE`;
+			console.log(colors.dim(header));
+			for (const r of rows) {
+				const line = `${r.name.padEnd(nameW)}  ${r.kind.padEnd(kindW)}  ${r.label.padEnd(stateW)}  ${r.source}`;
+				console.log(r.label === "local" ? colors.dim(line) : line);
+			}
+			const forkedRows = rows.filter((r) => r.label !== "local");
+			const customizedCount = forkedRows.filter((r) => r.customized).length;
+			const staleCount = forkedRows.filter((r) => r.stale).length;
+			const conflictCount = forkedRows.filter((r) => r.conflicted).length;
+			const missingRows = forkedRows.filter((r) => r.missing);
+			const parts = [`${customizedCount} customized`];
+			if (staleCount > 0) parts.push(`${staleCount} with upstream updates; run 'tbd docs update'`);
+			if (conflictCount > 0) parts.push(`${conflictCount} conflict pending`);
+			if (locals.length > 0) parts.push(`${locals.length} local`);
+			console.log("");
+			console.log(`${forkedRows.length} forked: ${parts.join(", ")}`);
+			if (missingRows.length > 0) {
+				console.log("");
+				console.log(`${missingRows.length} doc(s) missing (forked file deleted or renamed):`);
+				for (const r of missingRows) console.log(`  ${r.name}   restore with 'tbd docs fork ${r.name} --force', or finalize with 'tbd docs unfork ${r.name}'`);
+			}
+		}, "Failed to read docs status");
+	}
+};
+var DocsUpdateHandler = class extends BaseCommand {
+	async run(names, options) {
+		await this.execute(async () => {
+			if (options.merge && options.keepOurs) throw new CLIError("--merge and --keep-ours are mutually exclusive.");
+			const strategy = options.merge ? "merge" : options.keepOurs ? "keep-ours" : "default";
+			const tbdRoot = await requireInit();
+			const applied = [];
+			const decisions = [];
+			const skipped = [];
+			await withForkManifestLock(tbdRoot, async () => {
+				let manifest = await readForkManifest(tbdRoot);
+				if (names.length > 0) {
+					const known = new Set(manifest.forks.map((f) => f.name));
+					const unknown = names.filter((n) => !known.has(n));
+					if (unknown.length > 0) throw new CLIError(`Not forked: ${unknown.join(", ")}. Run \`tbd docs status\` to see forked docs.`);
+				}
+				const selected = names.length > 0 ? manifest.forks.filter((f) => names.includes(f.name)) : manifest.forks;
+				const caches = /* @__PURE__ */ new Map();
+				const upstreamFor = async (entry) => {
+					const kind = entry.kind;
+					if (!caches.has(kind)) caches.set(kind, await buildKindCache(kind, tbdRoot));
+					return caches.get(kind).get(entry.name)?.doc.content ?? null;
+				};
+				for (const entry of selected) {
+					const forkContent = await readForkFile(tbdRoot, FORK_DIR, entry);
+					const result = await updateOne({
+						entry,
+						forkContent,
+						baseContent: await readForkBase(tbdRoot, entry),
+						upstreamContent: await upstreamFor(entry),
+						strategy,
+						runningVersion: VERSION
+					});
+					const { newFileContent, newBaseContent } = result;
+					if (newFileContent === void 0 && newBaseContent === void 0) {
+						if (!options.dryRun && entry.conflicted && forkContent !== null && !hasUnresolvedConflict(forkContent)) {
+							const cleared = { ...entry };
+							delete cleared.conflicted;
+							manifest = upsertFork(manifest, cleared);
+						}
+						if (result.needsDecision) decisions.push({
+							name: entry.name,
+							message: result.message
+						});
+						else if (result.action !== "skip-not-stale") skipped.push({
+							name: entry.name,
+							message: result.message
+						});
+						continue;
+					}
+					if (!options.dryRun) {
+						if (newFileContent !== void 0) {
+							const abs = forkFilePath(tbdRoot, FORK_DIR, entry.kind, entry.name);
+							await mkdir(dirname(abs), { recursive: true });
+							await writeFile(abs, newFileContent);
+						}
+						const updated = { ...entry };
+						if (newBaseContent !== void 0) {
+							await writeBaseContent(tbdRoot, entry.kind, entry.name, newBaseContent);
+							updated.base_hash = hashContent(newBaseContent);
+							updated.tbd_version = VERSION;
+						}
+						if (result.setConflicted) updated.conflicted = true;
+						else delete updated.conflicted;
+						manifest = upsertFork(manifest, updated);
+					}
+					applied.push({
+						entry,
+						message: result.message
+					});
+				}
+				if (!options.dryRun) {
+					await writeForkManifest(tbdRoot, manifest);
+					await regenerateForkDirReadme(tbdRoot, FORK_DIR, manifest);
+				}
+			});
+			if (this.ctx.json) {
+				this.output.data({
+					dryRun: Boolean(options.dryRun),
+					updated: applied.map((a) => a.entry.name),
+					needsDecision: decisions,
+					skipped
+				});
+				return;
+			}
+			const colors = this.output.getColors();
+			if (applied.length === 0 && decisions.length === 0 && skipped.length === 0) {
+				console.log("All forked docs are up to date.");
+				return;
+			}
+			if (applied.length > 0) {
+				const verb = options.dryRun ? "Would update" : "Updated";
+				console.log(`${verb} ${applied.length} forked doc(s):`);
+				for (const a of applied) console.log(`  ${colors.success("✓")} ${a.message}`);
+			}
+			if (skipped.length > 0) {
+				console.log("");
+				console.log(`${skipped.length} doc(s) skipped:`);
+				for (const sk of skipped) console.log(`  ${colors.warn("⚠")} ${sk.message}`);
+			}
+			if (decisions.length > 0) {
+				console.log("");
+				console.log(`${decisions.length} doc(s) need a decision:`);
+				for (const d of decisions) console.log(`  ${colors.warn("⚠")} ${d.message}`);
+				console.log("  re-run with one of:");
+				console.log("    tbd docs update <name> --merge      # combine, then resolve conflict markers");
+				console.log("    tbd docs update <name> --keep-ours  # keep your version, advance the fork point");
+			}
+		}, "Failed to update forked docs");
+	}
+};
+var DocsListHandler = class extends BaseCommand {
+	async run(options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const { manifest, files, localDirs } = await loadServeContext(tbdRoot);
+			const parsedKind = parseKindOption(options.kind);
+			const kinds = parsedKind ? [parsedKind] : RESOLVABLE_KINDS;
+			const colors = this.output.getColors();
+			const seenLocal = /* @__PURE__ */ new Set();
+			const grouped = [];
+			const docmapEntries = [];
+			for (const kind of kinds) {
+				const cache = new DocCache(effectiveServePaths(kind, localDirs), tbdRoot);
+				await cache.load({ quiet: true });
+				const rows = [];
+				for (const doc of cache.list()) {
+					if (localDirs.includes(doc.sourceDir)) {
+						if (seenLocal.has(doc.path)) continue;
+						seenLocal.add(doc.path);
+					}
+					const { entry, state, marker } = servedEntryFor(tbdRoot, kind, doc, manifest, files, localDirs);
+					rows.push({
+						name: doc.name,
+						title: doc.frontmatter?.title,
+						description: doc.frontmatter?.description,
+						sizeInfo: formatDocSize(doc.sizeBytes, doc.approxTokens),
+						marker,
+						state,
+						path: entry.path ?? doc.sourceDir + "/" + doc.name + ".md"
+					});
+					docmapEntries.push(entry);
+				}
+				grouped.push({
+					kind,
+					rows
+				});
+			}
+			if (this.ctx.json) {
+				this.output.data(createDocMap(docmapEntries, { name: "tbd-docs" }));
+				return;
+			}
+			for (const { kind, rows } of grouped) {
+				if (rows.length === 0) continue;
+				if (!options.kind) console.log(colors.bold(kind));
+				for (const r of rows) {
+					const indent = options.kind ? "" : "  ";
+					const markerStr = r.marker ? ` ${colors.dim(r.marker)}` : "";
+					console.log(`${indent}${colors.bold(r.name)} ${colors.dim(r.sizeInfo)}${markerStr}`);
+					const desc = r.title && r.description ? `${r.title}: ${r.description}` : r.title ?? r.description;
+					if (desc) console.log(`${indent}   ${desc}`);
+				}
+			}
+		}, "Failed to list docs");
+	}
+};
+var DocsDiffHandler = class extends BaseCommand {
+	async run(name, options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const entry = findFork(await readForkManifest(tbdRoot), name, parseKindOption(options.kind));
+			if (!entry) throw new CLIError(`${name} is not a forked doc. Run \`tbd docs status\` to see forks.`);
+			const forkContent = await readForkFile(tbdRoot, FORK_DIR, entry);
+			const baseContent = await readForkBase(tbdRoot, entry);
+			const upstreamContent = (await buildKindCache(entry.kind, tbdRoot)).get(entry.name)?.doc.content ?? null;
+			let left = upstreamContent;
+			let right = forkContent;
+			let labels = {
+				left: "upstream",
+				right: "ours"
+			};
+			if (options.base) {
+				left = baseContent;
+				right = forkContent;
+				labels = {
+					left: "base",
+					right: "ours"
+				};
+			} else if (options.upstream) {
+				left = baseContent;
+				right = upstreamContent;
+				labels = {
+					left: "base",
+					right: "upstream"
+				};
+			}
+			if (left === null || right === null) throw new CLIError(`Cannot diff ${name}: one side is unavailable (forked file missing, base missing, or upstream gone).`);
+			const diff = await diffContents(left, right, labels);
+			if (this.ctx.json) {
+				this.output.data({
+					name: entry.name,
+					kind: entry.kind,
+					diff
+				});
+				return;
+			}
+			if (!diff.trim()) {
+				console.log(`No differences (${labels.left} vs ${labels.right}).`);
+				return;
+			}
+			console.log(diff.trimEnd());
+		}, "Failed to diff");
+	}
+};
+/**
+* Merge a subcommand's local options with globals/ancestors (e.g. the global
+* --dry-run and --json), preferring the subcommand's own values.
+*/
+function mergedForkOptions(local, command) {
+	const g = command.optsWithGlobals();
+	return {
+		all: local.all ?? g.all,
+		category: local.category,
+		kind: local.kind ?? g.kind,
+		force: local.force ?? g.force,
+		dryRun: local.dryRun ?? g.dryRun,
+		json: g.json
+	};
+}
+/** Register fork/unfork/status subcommands onto the `docs` command. */
+function registerForkSubcommands(docs) {
+	docs.command("fork").description("Fork managed docs into the repo (default docs/tbd/) so they are visible and editable").argument("[names...]", "doc name(s) to fork").option("--kind <kind>", "restrict to a kind (guideline|shortcut|template|reference)").option("--all", "fork all available docs").option("--category <name>", "fork all docs in a category (repeatable: general|typescript|python|convex|electron)", (value, previous = []) => [...previous, value]).option("--force", "overwrite an existing non-fork file").action(async (names, options, command) => {
+		await new DocsForkHandler(command).run(names, mergedForkOptions(options, command));
+	});
+	docs.command("unfork").description("Remove a fork and fall back to upstream (refuses to discard edits without --force)").argument("[names...]", "doc name(s) to unfork").option("--kind <kind>", "restrict to a kind").option("--all", "unfork all forked docs").option("--force", "discard local customizations").action(async (names, options, command) => {
+		const m = mergedForkOptions(options, command);
+		await new DocsUnforkHandler(command).run(names, {
+			all: m.all,
+			kind: m.kind,
+			force: m.force,
+			json: m.json
+		});
+	});
+	docs.command("list").description("List all docs across kinds, with [forked]/[customized]/[local] markers").option("--kind <kind>", "restrict to a kind (guideline|shortcut|template)").action(async (options, command) => {
+		await new DocsListHandler(command).run({
+			kind: options.kind,
+			json: command.optsWithGlobals().json === true
+		});
+	});
+	docs.command("status").description("Show forked docs and their states").action(async (_options, command) => {
+		await new DocsStatusHandler(command).run({ json: command.optsWithGlobals().json === true });
+	});
+	docs.command("update").description("Reconcile forked docs with upstream after an upgrade (--merge / --keep-ours)").argument("[names...]", "doc name(s) to update (default: all)").option("--merge", "on conflict: combine and write conflict markers to resolve").option("--keep-ours", "on conflict: keep your version and advance the fork point").action(async (names, options, command) => {
+		const g = command.optsWithGlobals();
+		await new DocsUpdateHandler(command).run(names, {
+			merge: options.merge,
+			keepOurs: options.keepOurs,
+			dryRun: g.dryRun === true,
+			json: g.json === true
+		});
+	});
+	docs.command("diff").description("Diff a forked doc against upstream (default), its base (--base), or incoming (--upstream)").argument("<name>", "forked doc name").option("--base", "diff your file against its base (what you changed)").option("--upstream", "diff the base against current upstream (incoming changes)").option("--kind <kind>", "restrict to a kind").action(async (name, options, command) => {
+		await new DocsDiffHandler(command).run(name, options);
+	});
+}
+
+//#endregion
+//#region src/file/doc-add.ts
+/**
+* Add external documentation to the tbd doc cache.
+*
+* Uses the shared github-fetch utility for URL conversion and fetching.
+* Handles doc-specific concerns: content validation, file writing, and
+* atomic config updates.
+*/
+/**
+* Validate that fetched content looks like a reasonable markdown document.
+*
+* @throws If content fails sanity checks
+*/
+function validateDocContent(content, name) {
+	if (!content || content.trim().length === 0) throw new Error(`Fetched content for "${name}" is empty`);
+	if (content.length < 10) throw new Error(`Fetched content for "${name}" is too short (${content.length} chars)`);
+	if (content.trimStart().startsWith("<!DOCTYPE") || content.trimStart().startsWith("<html")) throw new Error(`Fetched content for "${name}" appears to be an HTML page, not a markdown document`);
+	if (content.split("").filter((c) => {
+		const code = c.charCodeAt(0);
+		return code < 32 && code !== 9 && code !== 10 && code !== 13;
+	}).length / content.length > .1) throw new Error(`Fetched content for "${name}" appears to be binary, not a text document`);
+}
+/**
+* Get the destination subdirectory for a doc type.
+*/
+function getDocTypeSubdir(docType) {
+	switch (docType) {
+		case "guideline": return "guidelines";
+		case "shortcut": return "shortcuts/custom";
+		case "template": return "templates";
+		case "reference": return "references";
+	}
+}
+/**
+* Add an external document to the tbd doc cache.
+*
+* This function:
+* 1. Converts GitHub blob URLs to raw URLs
+* 2. Fetches the content (with gh CLI fallback on 403)
+* 3. Validates the content looks like markdown
+* 4. Writes the file to .tbd/docs/{type}/{name}.md
+* 5. Atomically updates the config to include the new source
+*
+* @throws If fetching, validation, or config update fails
+*/
+async function addDoc(tbdRoot, options) {
+	const { url, name, docType } = options;
+	const cleanName = name.endsWith(".md") ? name.slice(0, -3) : name;
+	const filename = `${cleanName}.md`;
+	const subdir = getDocTypeSubdir(docType);
+	const destPath = `${subdir}/${filename}`;
+	const source = normalizeDocRef(url);
+	const parsed = parseDocRef(source);
+	if (parsed.kind === "internal") throw new DocRefError(url, "bundled internal: sources cannot be added");
+	if (parsed.kind === "git" && !parsed.ref) throw new DocRefError(url, `git docrefs need an explicit ref for deterministic sync; use ${parsed.host}:${parsed.owner}/${parsed.repo}@<ref>//${parsed.path}`);
+	let content;
+	let usedGhCli = false;
+	let rawUrl = source;
+	if (parsed.kind === "local") {
+		rawUrl = parsed.path;
+		content = await readFile(join(tbdRoot, parsed.path), "utf-8");
+	} else {
+		rawUrl = parsed.kind === "git" ? gitDocRefToRawUrl(parsed) : parsed.url;
+		const fetched = await fetchWithGhFallback(rawUrl);
+		content = fetched.content;
+		usedGhCli = fetched.usedGhCli;
+	}
+	validateDocContent(content, cleanName);
+	const fullPath = join(tbdRoot, TBD_DOCS_DIR, destPath);
+	await mkdir(dirname(fullPath), { recursive: true });
+	await writeFile(fullPath, content);
+	const config = await readConfig(tbdRoot);
+	config.docs_cache ??= {
+		files: {},
+		lookup_path: []
+	};
+	config.docs_cache.files ??= {};
+	config.docs_cache.files[destPath] = source;
+	const lookupDir = `.tbd/docs/${subdir}`;
+	if (!config.docs_cache.lookup_path.includes(lookupDir)) config.docs_cache.lookup_path.push(lookupDir);
+	await writeConfig(tbdRoot, config);
+	return {
+		destPath,
+		source,
+		rawUrl,
+		usedGhCli
+	};
+}
+
+//#endregion
+//#region src/cli/lib/docs-menu.ts
+/**
+* Shared docs-posture menu for the zero-forks state.
+*
+* The same "three postures" menu is shown by `tbd setup --auto` (the Docs
+* summary) and by the bare `tbd docs` overview, so the wording lives in one
+* place and the two surfaces cannot drift. Lines are returned unindented and
+* uncolored; callers add their own indentation and formatting.
+*
+* Contract note (forkable-docs spec): the menu must only name selectors that
+* exist; `--category` appears here because the flag ships with it.
+*/
+/**
+* Menu body lines for the zero-forks state: the three serving postures plus
+* the browse/read pointer. Shown under a lead line reporting the count of
+* docs available in the cache.
+*/
+function docsPostureMenuLines() {
+	return [
+		"Guidelines are active from the cache. Three postures, all serving the same docs:",
+		"Hidden (default):  keep the cache as-is; zero repo footprint",
+		`Curated:           tbd docs fork <name> [...]  fork chosen docs into ${FORK_DIR}/`,
+		`                   tbd docs fork --category=<name>  (${DOC_CATEGORIES.join(", ")})`,
+		"Everything:        tbd docs fork --all         all docs, visible and editable",
+		"Browse / read: tbd docs list / tbd docs show <name>"
+	];
+}
+
+//#endregion
+//#region src/cli/commands/docs.ts
+/**
+* `tbd docs`, manage tbd-served docs: browse, fork into the repo, sync the
+* cache, and pull upstream updates into forks.
+*
+* Surface (the f05 reorganization of the old manual viewer):
+*   tbd docs                     status overview of managed docs (landing page)
+*   tbd docs show <name>         read any doc by name (kind-agnostic; --section)
+*   tbd docs show tbd-docs       the CLI manual (old bare `tbd docs`)
+*   tbd docs manual [topic]      alias for `tbd docs show tbd-docs`
+*   tbd docs sync                refresh the gitignored cache (canonical form of
+*                                the deprecated `tbd sync --docs` alias)
+*   tbd docs list/status/fork/unfork/update/diff   (see docs-fork.ts)
+*/
+/** Reserved name that serves the CLI manual (`tbd-docs.md`). */
+const MANUAL_DOC_NAME = "tbd-docs";
+/**
+* Self-docs: served as `reference` docs from the cache like everything else
+* (so forks shadow them), but with a bundled fallback so they stay readable
+* before init or before the first cache sync.
+*/
+const BUNDLED_ROOT_DOCS = {
+	[MANUAL_DOC_NAME]: "tbd-docs.md",
+	"tbd-design": "tbd-design.md"
+};
+/**
+* Read a doc bundled at the docs root. Copied to dist/docs/ during build; in
+* development read from the package docs/ directory.
+*/
+async function readBundledRootDoc(filename) {
+	const __dirname = dirname(fileURLToPath(import.meta.url));
+	try {
+		return await readFile(join(__dirname, "docs", filename), "utf-8");
+	} catch {
+		try {
+			return await readFile(join(__dirname, "..", "..", "..", "docs", filename), "utf-8");
+		} catch {
+			throw new CLIError("Documentation file not found. Please rebuild the CLI.");
+		}
+	}
+}
+/** Extract `## ` section metadata (title + GitHub slug) from a markdown doc. */
+function extractSections(content) {
+	const sections = [];
+	const slugger = new GithubSlugger();
+	for (const line of content.split("\n")) if (line.startsWith("## ")) {
+		const title = line.slice(3).trim();
+		sections.push({
+			title,
+			slug: slugger.slug(title)
+		});
+	}
+	return sections;
+}
+/**
+* Extract one `## ` section (header through the next header), matching by slug
+* or partial title. Returns null when no section matches.
+*/
+function extractSection(content, sections, query) {
+	const lowerQuery = query.toLowerCase();
+	const matched = sections.find((s) => s.slug === lowerQuery) ?? sections.find((s) => s.title.toLowerCase().includes(lowerQuery));
+	if (!matched) return null;
+	const lines = content.split("\n");
+	let inSection = false;
+	const sectionLines = [];
+	for (const line of lines) if (line.startsWith("## ")) {
+		if (inSection) break;
+		if (line.slice(3).trim() === matched.title) {
+			inSection = true;
+			sectionLines.push(line);
+		}
+	} else if (inSection) sectionLines.push(line);
+	while (sectionLines.length > 0 && sectionLines[sectionLines.length - 1]?.trim() === "") sectionLines.pop();
+	return sectionLines.length > 0 ? sectionLines.join("\n") : null;
+}
+/**
+* Bare `tbd docs`: the status overview / landing page for managed docs.
+* Mirrors `tbd status`: a summary plus pointers, never the full table.
+*/
+var DocsOverviewHandler = class extends BaseCommand {
+	async run() {
+		await this.execute(async () => {
+			let tbdRoot;
+			try {
+				tbdRoot = await requireInit();
+			} catch (err) {
+				if (!(err instanceof NotInitializedError)) throw err;
+				const colors = this.output.getColors();
+				console.log(`${colors.bold("tbd docs")}: managed documentation`);
+				console.log("");
+				console.log("  tbd is not initialized in this repo (run: tbd setup --auto).");
+				console.log("  The CLI manual is bundled and always available:");
+				console.log("");
+				console.log("  Learn more: tbd docs show tbd-docs   (alias: tbd docs manual)");
+				return;
+			}
+			const manifest = await readForkManifest(tbdRoot);
+			const drift = await computeForkDriftSummary(tbdRoot, FORK_DIR, manifest);
+			const { files, localDirs } = await loadServeContext(tbdRoot);
+			let total = 0;
+			const entries = [];
+			const seenLocal = /* @__PURE__ */ new Set();
+			for (const kind of RESOLVABLE_KINDS) {
+				const cache = new DocCache(effectiveServePaths(kind, localDirs), tbdRoot);
+				await cache.load({ quiet: true });
+				for (const doc of cache.list()) {
+					if (localDirs.includes(doc.sourceDir)) {
+						if (seenLocal.has(doc.path)) continue;
+						seenLocal.add(doc.path);
+					}
+					total += 1;
+					if (this.ctx.json) entries.push(servedEntryFor(tbdRoot, kind, doc, manifest, files, localDirs).entry);
+				}
+			}
+			if (this.ctx.json) {
+				this.output.data(createDocMap(entries, { name: "tbd-docs" }));
+				return;
+			}
+			const colors = this.output.getColors();
+			console.log(`${colors.bold("tbd docs")}: managed documentation`);
+			console.log("");
+			if (drift.forks === 0) {
+				console.log(`  ${total} docs available in the cache (.tbd/docs/, gitignored); none forked into the repo.`);
+				const [intro, ...postures] = docsPostureMenuLines();
+				console.log(`  ${intro}`);
+				console.log("");
+				for (const line of postures.slice(0, -1)) console.log(`  ${line}`);
+				console.log("");
+				console.log(`  ${postures[postures.length - 1]}`);
+				console.log(`  Learn more:    tbd docs show tbd-docs   (the manual; alias: tbd docs manual)`);
+				return;
+			}
+			const upstream = total - drift.forks;
+			console.log(`  ${total} available  (${upstream} upstream, ${drift.forks} forked into ${FORK_DIR}/)`);
+			const parts = [`${drift.customized} customized`];
+			if (drift.stale > 0) parts.push(`${drift.stale} with upstream updates; run 'tbd docs update'`);
+			if (drift.conflicted > 0) parts.push(`${drift.conflicted} conflict pending`);
+			if (drift.missing > 0) parts.push(`${drift.missing} missing; see 'tbd docs status'`);
+			if (drift.local > 0) parts.push(`${drift.local} local`);
+			console.log(`  ${drift.forks} forked: ${parts.join(", ")}`);
+			console.log("");
+			console.log("  Inspect:    tbd docs status");
+			console.log("  Browse:     tbd docs list");
+			console.log("  Update:     tbd docs update");
+			console.log("  Learn more: tbd docs show tbd-docs");
+		}, "Failed to read docs overview");
+	}
+};
+/**
+* `tbd docs show <name>`: kind-agnostic read of any managed doc. The reserved
+* `tbd-docs` name serves the bundled CLI manual (with `--section` navigation,
+* relocated here from the old bare `tbd docs` viewer).
+*/
+var DocsShowHandler = class extends BaseCommand {
+	async run(name, options) {
+		await this.execute(async () => {
+			let content;
+			let provenance = null;
+			const bundledFallback = BUNDLED_ROOT_DOCS[name];
+			let tbdRoot = null;
+			if (bundledFallback) try {
+				tbdRoot = await requireInit();
+			} catch (err) {
+				if (!(err instanceof NotInitializedError)) throw err;
+			}
+			else tbdRoot = await requireInit();
+			if (tbdRoot === null) content = await readBundledRootDoc(bundledFallback);
+			else {
+				const requestedKind = parseKindOption(options.kind);
+				const kinds = requestedKind ? [requestedKind] : RESOLVABLE_KINDS;
+				const { manifest: showManifest, files: showFiles, localDirs } = await loadServeContext(tbdRoot);
+				const matches = [];
+				for (const kind of kinds) {
+					const cache = new DocCache(effectiveServePaths(kind, localDirs), tbdRoot);
+					await cache.load({ quiet: true });
+					const hit = cache.get(name);
+					if (hit) matches.push({
+						kind,
+						content: hit.doc.content,
+						sourceDir: hit.doc.sourceDir,
+						path: hit.doc.path
+					});
+				}
+				if (new Set(matches.map((m) => m.path)).size === 1 && matches.length > 1) matches.length = 1;
+				if (matches.length === 0) if (bundledFallback) content = await readBundledRootDoc(bundledFallback);
+				else throw new NotFoundError("Doc", `"${name}" (run \`tbd docs list\` to see names)`);
+				else if (matches.length > 1) throw new CLIError(`"${name}" exists in multiple kinds (${matches.map((m) => m.kind).join(", ")}). Use --kind to disambiguate.`);
+				else {
+					const match = matches[0];
+					content = match.content;
+					if (this.ctx.json && !options.sections) {
+						const { entry } = servedEntryFor(tbdRoot, match.kind, {
+							name,
+							content,
+							sourceDir: match.sourceDir,
+							path: match.path
+						}, showManifest, showFiles, localDirs);
+						this.output.data({
+							...entry,
+							content
+						});
+						return;
+					}
+					if (match.sourceDir.startsWith(FORK_DIR)) provenance = `(serving forked copy: ${relative(tbdRoot, match.path).split("\\").join("/")})`;
+					else if (localDirs.includes(match.sourceDir)) provenance = `(serving local doc: ${relative(tbdRoot, match.path).split("\\").join("/")})`;
+				}
+			}
+			const sections = extractSections(content);
+			if (options.sections) {
+				this.output.data(sections, () => {
+					const colors = this.output.getColors();
+					console.log(colors.bold(`Sections in ${name}:`));
+					console.log("");
+					const maxSlugLen = Math.max(...sections.map((s) => s.slug.length));
+					for (const section of sections) console.log(`  ${colors.id(section.slug.padEnd(maxSlugLen))}  ${section.title}`);
+					console.log("");
+					console.log(`Use ${colors.dim(`tbd docs show ${name} --section <name>`)} to view a section.`);
+				});
+				return;
+			}
+			if (options.section) {
+				const sectionContent = extractSection(content, sections, options.section);
+				if (!sectionContent) throw new NotFoundError("Section", `"${options.section}" (use --sections to see available sections)`);
+				content = sectionContent;
+			}
+			if (provenance && !this.ctx.quiet && !this.ctx.json) process.stderr.write(`${provenance}\n`);
+			if (shouldUseInteractiveOutput(this.ctx)) await paginateOutput(renderMarkdown(content, this.ctx.color), true);
+			else console.log(content);
+		}, "Failed to show doc");
+	}
+};
+/**
+* `tbd docs add <docref>`: register an external doc in the cache. The unified
+* form of the per-kind --add flags (which remain as aliases); the canonical
+* docref is what config records.
+*/
+var DocsAddHandler = class extends BaseCommand {
+	async run(docref, options) {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			const kind = parseKindOption(options.kind);
+			if (!kind) throw new CLIError("--kind is required (guideline|shortcut|template|reference)");
+			const inferredName = (() => {
+				const parsed = parseDocRef(docref);
+				const base = (parsed.kind === "url" ? new URL(parsed.url).pathname : "path" in parsed ? parsed.path : "").split("/").filter(Boolean).pop() ?? "";
+				return base.endsWith(".md") ? base.slice(0, -3) : base;
+			})();
+			const finalName = options.name ?? inferredName;
+			if (!finalName) throw new CLIError("--name is required when it cannot be inferred from the docref");
+			console.log(`Adding ${kind}: ${finalName}`);
+			const result = await addDoc(tbdRoot, {
+				url: docref,
+				name: finalName,
+				docType: kind
+			});
+			console.log(`  Source: ${result.source}`);
+			if (result.usedGhCli) {
+				const colors = this.output.getColors();
+				console.log(colors.dim("  (fetched via gh CLI due to direct access restriction)"));
+			}
+			this.output.success(`Added to .tbd/docs/${result.destPath}`);
+			console.log(`  Config updated (docs_cache.files): ${result.source}`);
+			console.log("");
+			console.log(`Run 'tbd docs list' to verify, or 'tbd docs fork ${finalName}' to make it visible.`);
+		}, "Failed to add doc");
+	}
+};
+/** `tbd docs sync`: refresh the gitignored docs cache (canonical command). */
+var DocsSyncHandler = class extends BaseCommand {
+	async run() {
+		await this.execute(async () => {
+			const tbdRoot = await requireInit();
+			if (this.ctx.dryRun) {
+				const result = await syncDocsWithDefaults(tbdRoot, { dryRun: true });
+				printDocSyncStatus(this.output, result);
+				return;
+			}
+			const spinner = this.output.spinner("Syncing docs...");
+			const result = await syncDocsWithDefaults(tbdRoot);
+			spinner.stop();
+			printDocSyncResult(this.output, result);
+			await printForkDriftNotice(this.output, tbdRoot);
+		}, "Failed to sync docs");
+	}
+};
+const docsCommand = new Command("docs").description("Manage tbd-served docs: browse, fork into your repo, and pull upstream updates").action(async (_options, command) => {
+	await new DocsOverviewHandler(command).run();
+});
+docsCommand.command("show").description("Read any managed doc by name (tbd-docs is the CLI manual)").argument("<name>", "doc name (e.g. python-rules, tbd-docs)").option("--section <name>", "show one section of the doc").option("--sections", "list the doc’s sections").option("--kind <kind>", "restrict to a kind (guideline|shortcut|template)").action(async (name, options, command) => {
+	await new DocsShowHandler(command).run(name, options);
+});
+docsCommand.command("manual").description("Show the tbd CLI manual (alias for: tbd docs show tbd-docs)").argument("[topic]", "section to display (e.g. \"commands\", \"id-system\")").option("--section <name>", "show one section of the manual").option("--sections", "list the manual’s sections").action(async (topic, options, command) => {
+	await new DocsShowHandler(command).run(MANUAL_DOC_NAME, {
+		...options,
+		section: options.section ?? topic
+	});
+});
+docsCommand.command("add").description("Register an external doc in the cache by docref (URL, github:o/r@ref//path, ./local)").argument("<docref>", "source docref").option("--kind <kind>", "doc kind (guideline|shortcut|template|reference)").option("--name <name>", "doc name (defaults to the source filename)").action(async (docref, options, command) => {
+	await new DocsAddHandler(command).run(docref, options);
+});
+docsCommand.command("sync").description("Refresh the gitignored docs cache (.tbd/docs/) from bundled and URL sources").action(async (_options, command) => {
+	await new DocsSyncHandler(command).run();
+});
+registerForkSubcommands(docsCommand);
+
+//#endregion
+//#region src/cli/commands/closing.ts
+/**
+* `tbd closing` - Display the session closing protocol reminder.
 *
 * Shows the close protocol checklist for completing work.
 * Used by the Claude Code PostToolUse hook after git push.
@@ -9447,6 +10342,7 @@ var UninstallHandler = class extends BaseCommand {
 		let localBranchExists = false;
 		try {
 			execSync(`git rev-parse --verify ${syncBranch}`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9460,6 +10356,7 @@ var UninstallHandler = class extends BaseCommand {
 		let remoteBranchExists = false;
 		if (options.removeRemote) try {
 			execSync(`git rev-parse --verify ${remote}/${syncBranch}`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9488,6 +10385,7 @@ var UninstallHandler = class extends BaseCommand {
 		this.output.info("Uninstalling tbd...");
 		if (worktreeExists) try {
 			execSync(`git worktree remove --force "${worktreePath}"`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9509,6 +10407,7 @@ var UninstallHandler = class extends BaseCommand {
 		}
 		if (legacyWorktreeExists) try {
 			execSync(`git worktree remove --force "${legacyWorktreePath}"`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9526,6 +10425,7 @@ var UninstallHandler = class extends BaseCommand {
 		}
 		if (localBranchExists && !options.keepBranch) try {
 			execSync(`git branch -D ${syncBranch}`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9539,6 +10439,7 @@ var UninstallHandler = class extends BaseCommand {
 		}
 		if (remoteBranchExists && options.removeRemote) try {
 			execSync(`git push ${remote} --delete ${syncBranch}`, {
+				env: gitSafeEnv(),
 				encoding: "utf-8",
 				stdio: [
 					"ignore",
@@ -9624,361 +10525,6 @@ const uninstallCommand = new Command("uninstall").description("Remove tbd from t
 	await new UninstallHandler(command).run(options);
 });
 
-//#endregion
-//#region src/file/doc-cache.ts
-/**
-* DocCache - Path-ordered markdown document cache with lookup.
-*
-* Provides document lookups for the `tbd shortcut` command, supporting
-* both exact matching by filename and fuzzy matching against metadata.
-*
-* Also provides auto-sync functionality when docs are stale (per spec).
-*
-* See: docs/project/specs/active/plan-2026-01-22-doc-cache-abstraction.md
-* See: docs/project/specs/active/plan-2026-01-26-configurable-doc-cache-sync.md
-*/
-/** Score for exact filename match (with or without .md extension) */
-const SCORE_EXACT_MATCH = 1;
-/** Score when query is a prefix of the filename */
-const SCORE_PREFIX_MATCH = .9;
-/** Score when filename contains all query words */
-const SCORE_CONTAINS_ALL = .8;
-/** Base score for partial word matches (multiplied by matched/total ratio) */
-const SCORE_PARTIAL_BASE = .7;
-/** Minimum score threshold to return a fuzzy match result */
-const SCORE_MIN_THRESHOLD = .5;
-/**
-* Path-ordered markdown document cache.
-*
-* Loads all .md files from configured paths in order, with earlier paths
-* taking precedence (like shell $PATH). Supports exact lookup by filename
-* and fuzzy search across filename + frontmatter metadata.
-*/
-var DocCache = class {
-	/** Active docs (first occurrence of each name) */
-	docs = [];
-	/** All docs including shadowed ones */
-	allDocs = [];
-	/** Track names we've seen for shadow detection */
-	seenNames = /* @__PURE__ */ new Set();
-	/** Whether the cache has been loaded */
-	loaded = false;
-	/**
-	* Create a new DocCache.
-	*
-	* @param paths - Ordered array of directory paths to search (relative to baseDir)
-	* @param baseDir - Base directory for resolving relative paths (default: cwd)
-	*/
-	constructor(paths, baseDir = process.cwd()) {
-		this.paths = paths;
-		this.baseDir = baseDir;
-	}
-	/**
-	* Load all documents from configured paths.
-	*
-	* Reads all .md files from each path in order. Documents with the same
-	* name in later paths are shadowed (tracked but not returned by default).
-	*
-	* If auto-sync is enabled and docs are stale, triggers a sync first.
-	*
-	* @param options - Load options (quiet: suppress auto-sync output)
-	*/
-	async load(options) {
-		if (this.loaded) return;
-		await this.checkAutoSync(options?.quiet ?? false);
-		for (const relativePath of this.paths) {
-			const dirPath = join(this.baseDir, relativePath);
-			await this.loadDirectory(dirPath, relativePath);
-		}
-		this.loaded = true;
-	}
-	/**
-	* Check if docs are stale and auto-sync if needed.
-	* Respects the quiet option - only silent when explicitly requested.
-	*
-	* Uses syncDocsWithDefaults() to ensure auto-sync also picks up new bundled
-	* docs from tbd upgrades, not just existing config entries.
-	*
-	* @param quiet - If true, suppress sync output
-	*/
-	async checkAutoSync(quiet) {
-		try {
-			const tbdRoot = await findTbdRoot(this.baseDir);
-			if (!tbdRoot) return;
-			const config = await readConfig(tbdRoot);
-			const state = await readLocalState(tbdRoot);
-			const autoSyncHours = config.settings?.doc_auto_sync_hours ?? 24;
-			if (!isDocsStale(state.last_doc_sync_at, autoSyncHours)) return;
-			await syncDocsWithDefaults(tbdRoot, { quiet });
-		} catch {}
-	}
-	/**
-	* Load documents from a single directory.
-	*/
-	async loadDirectory(dirPath, sourceDir) {
-		let entries;
-		try {
-			entries = await readdir(dirPath);
-		} catch {
-			return;
-		}
-		for (const entry of entries) {
-			if (!entry.endsWith(".md")) continue;
-			const filePath = join(dirPath, entry);
-			const name = basename(entry, ".md");
-			try {
-				const content = await readFile(filePath, "utf-8");
-				const doc = {
-					path: filePath,
-					name,
-					frontmatter: this.parseFrontmatterData(content),
-					content,
-					sourceDir,
-					sizeBytes: Buffer.byteLength(content, "utf-8"),
-					approxTokens: estimateTokens(content)
-				};
-				this.allDocs.push(doc);
-				if (!this.seenNames.has(name)) {
-					this.docs.push(doc);
-					this.seenNames.add(name);
-				}
-			} catch (error) {
-				console.warn(`Failed to load shortcut ${filePath}: ${error.message}`);
-			}
-		}
-	}
-	/**
-	* Parse YAML frontmatter from content and return typed data.
-	* Uses gray-matter for consistent frontmatter parsing.
-	*/
-	parseFrontmatterData(content) {
-		if (!matter.test(content)) return;
-		try {
-			const parsed = matter(content).data;
-			return {
-				title: typeof parsed.title === "string" ? parsed.title : void 0,
-				description: typeof parsed.description === "string" ? parsed.description : void 0,
-				category: typeof parsed.category === "string" ? parsed.category : void 0,
-				tags: Array.isArray(parsed.tags) ? parsed.tags.filter((t) => typeof t === "string") : void 0
-			};
-		} catch {
-			return;
-		}
-	}
-	/**
-	* Get a document by exact name match.
-	*
-	* @param name - Filename to match (with or without .md extension)
-	* @returns Match with score SCORE_EXACT_MATCH, or null if not found
-	*/
-	get(name) {
-		const lookupName = name.endsWith(".md") ? name.slice(0, -3) : name;
-		const doc = this.docs.find((d) => d.name === lookupName);
-		if (!doc) return null;
-		return {
-			doc,
-			score: SCORE_EXACT_MATCH
-		};
-	}
-	/**
-	* Search for documents matching a query.
-	*
-	* Performs fuzzy matching against filename, title, and description.
-	* Returns matches sorted by score descending.
-	*
-	* @param query - Search query string
-	* @param limit - Maximum number of results (default: 10)
-	* @returns Array of matches sorted by score descending
-	*/
-	search(query, limit = 10) {
-		const matches = [];
-		for (const doc of this.docs) {
-			const score = this.calculateScore(doc, query);
-			if (score >= SCORE_MIN_THRESHOLD) matches.push({
-				doc,
-				score
-			});
-		}
-		matches.sort((a, b) => {
-			if (b.score !== a.score) return b.score - a.score;
-			return a.doc.name.localeCompare(b.doc.name);
-		});
-		return matches.slice(0, limit);
-	}
-	/**
-	* Calculate relevance score for a document against a query.
-	*/
-	calculateScore(doc, query) {
-		const queryLower = query.toLowerCase().trim();
-		if (queryLower.length === 0) return 0;
-		const nameLower = doc.name.toLowerCase();
-		const titleLower = doc.frontmatter?.title?.toLowerCase() ?? "";
-		const descLower = doc.frontmatter?.description?.toLowerCase() ?? "";
-		if (nameLower === queryLower) return SCORE_EXACT_MATCH;
-		if (nameLower.startsWith(queryLower)) return SCORE_PREFIX_MATCH;
-		const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 0);
-		const searchableText = `${nameLower} ${titleLower} ${descLower}`;
-		if (queryWords.every((word) => searchableText.includes(word)) && queryWords.length > 0) return SCORE_CONTAINS_ALL;
-		const matchedWords = queryWords.filter((word) => searchableText.includes(word));
-		if (matchedWords.length > 0) return SCORE_PARTIAL_BASE * (matchedWords.length / queryWords.length);
-		return 0;
-	}
-	/**
-	* List all documents.
-	*
-	* @param includeAll - If true, include shadowed documents
-	* @returns Array of cached documents
-	*/
-	list(includeAll = false) {
-		return includeAll ? this.allDocs : this.docs;
-	}
-	/**
-	* Check if a document is shadowed by an earlier path.
-	*
-	* @param doc - Document to check
-	* @returns True if this doc is shadowed (not the first with this name)
-	*/
-	isShadowed(doc) {
-		return this.docs.find((d) => d.name === doc.name) !== doc;
-	}
-	/**
-	* Check if the cache has been loaded.
-	*/
-	isLoaded() {
-		return this.loaded;
-	}
-};
-/**
-* Marker comments for shortcut directory section in skill files.
-* Used for incremental updates without overwriting user content.
-*/
-const SHORTCUT_DIRECTORY_BEGIN = "<!-- BEGIN SHORTCUT DIRECTORY -->";
-const SHORTCUT_DIRECTORY_END = "<!-- END SHORTCUT DIRECTORY -->";
-const GUIDELINE_GROUPS = [
-	{
-		heading: "General engineering",
-		note: "Read all of these for any engineering work (writing or reviewing code).",
-		match: (n) => n.startsWith("general-") || n === "error-handling-rules" || n === "backward-compatibility-rules" || n === "commit-conventions" || n.includes("tdd") || n.includes("testing") || n.includes("golden")
-	},
-	{
-		heading: "TypeScript & JS ecosystem",
-		note: "Also load these when working in TypeScript or JavaScript.",
-		match: (n) => n.startsWith("typescript-") || n.endsWith("monorepo-patterns") || n.startsWith("electron-")
-	},
-	{
-		heading: "Python",
-		note: "Also load these when working in Python.",
-		match: (n) => n.startsWith("python-")
-	},
-	{
-		heading: "Convex",
-		note: "Also load these when working with Convex.",
-		match: (n) => n.startsWith("convex-")
-	},
-	{
-		heading: "Docs, process & tooling",
-		match: () => true
-	}
-];
-/**
-* Build table rows from docs (shared helper for shortcuts and guidelines).
-*/
-function buildTableRows(docs, skipNames = []) {
-	const sortedDocs = [...docs].sort((a, b) => a.name.localeCompare(b.name));
-	const rows = [];
-	for (const doc of sortedDocs) {
-		if (skipNames.includes(doc.name)) continue;
-		const name = doc.name;
-		const escapedDescription = (doc.frontmatter?.description ?? "").replace(/\|/g, "\\|");
-		rows.push(`| ${name} | ${escapedDescription} |`);
-	}
-	return rows;
-}
-/**
-* Generate a formatted markdown directory of shortcuts and guidelines.
-*
-* The output includes:
-* 1. Marker comments for incremental updates
-* 2. Available Shortcuts section with name and description
-* 3. Available Guidelines section, grouped by area (General engineering first, then
-*    language/framework groups), with name and description (if provided)
-*
-* @param shortcuts - Array of shortcut CachedDoc objects
-* @param guidelines - Optional array of guideline CachedDoc objects
-* @returns Formatted markdown string with shortcuts and guidelines directory
-*
-* @example
-* const directory = generateShortcutDirectory(shortcutDocs, guidelineDocs);
-* // Returns:
-* // <!-- BEGIN SHORTCUT DIRECTORY -->
-* // ## Available Shortcuts
-* // | Name | Description |
-* // | --- | --- |
-* // | code-review-and-commit | Run pre-commit checks, review changes, and commit code |
-* // ...
-* // ## Available Guidelines
-* // ### General engineering
-* // | Name | Description |
-* // | --- | --- |
-* // | error-handling-rules | Rules for handling errors... |
-* // ...
-* // ### TypeScript & JS ecosystem
-* // | typescript-rules | TypeScript coding rules and best practices |
-* // ...
-* // <!-- END SHORTCUT DIRECTORY -->
-*/
-function generateShortcutDirectory(shortcuts, guidelines = []) {
-	const lines = [SHORTCUT_DIRECTORY_BEGIN];
-	const shortcutRows = buildTableRows(shortcuts, [
-		"skill-baseline",
-		"skill-brief",
-		"skill-minimal",
-		"shortcut-explanation"
-	]);
-	lines.push("## Available Shortcuts");
-	lines.push("");
-	lines.push("Run `tbd shortcut <name>` to use any of these shortcuts:");
-	lines.push("");
-	if (shortcutRows.length === 0) lines.push("No shortcuts available. Create shortcuts in `.tbd/docs/shortcuts/standard/`.");
-	else {
-		lines.push("| Name | Description |");
-		lines.push("| --- | --- |");
-		lines.push(...shortcutRows);
-	}
-	if (guidelines.length > 0) {
-		const grouped = GUIDELINE_GROUPS.map((group) => ({
-			group,
-			docs: []
-		}));
-		const catchAll = grouped[grouped.length - 1];
-		for (const doc of guidelines) (grouped.find((g) => g.group.match(doc.name)) ?? catchAll)?.docs.push(doc);
-		if (grouped.some((g) => g.docs.length > 0)) {
-			lines.push("");
-			lines.push("## Available Guidelines");
-			lines.push("");
-			lines.push("Run `tbd guidelines <name>` to apply any of these guidelines.");
-			lines.push("Load the **General engineering** group first, then the language or framework group.");
-			for (const { group, docs } of grouped) {
-				const rows = buildTableRows(docs);
-				if (rows.length === 0) continue;
-				lines.push("");
-				lines.push(`### ${group.heading}`);
-				if (group.note) {
-					lines.push("");
-					lines.push(`*${group.note}*`);
-				}
-				lines.push("");
-				lines.push("| Name | Description |");
-				lines.push("| --- | --- |");
-				lines.push(...rows);
-			}
-		}
-	}
-	lines.push("");
-	lines.push(SHORTCUT_DIRECTORY_END);
-	return lines.join("\n");
-}
-
 //#endregion
 //#region src/cli/commands/prime.ts
 /**
@@ -10067,7 +10613,7 @@ tbd is not yet initialized. To set it up, run:
   tbd setup --auto                   # If .tbd/ already exists (prefix already set)
 
 CRITICAL: Never guess a prefix. Always ask the user what prefix they want.
-Do NOT tell the user to run these commands — run them yourself on their behalf.
+Do NOT tell the user to run these commands; run them yourself on their behalf.
 
 After setup, run 'tbd' again to get project status and workflow guidance.`;
 var PrimeHandler = class extends BaseCommand {
@@ -10135,7 +10681,7 @@ var PrimeHandler = class extends BaseCommand {
 		const shortcutDir = await this.getShortcutDirectory(tbdRoot);
 		let markdownContent = primeContent;
 		if (shortcutDir) markdownContent += "\n\n" + shortcutDir;
-		markdownContent += "\n\nIMPORTANT: Use tbd to help the user — do NOT tell the user to run tbd commands.\nWhen the user asks for help or orientation, run `tbd shortcut welcome-user`.";
+		markdownContent += "\n\nIMPORTANT: Use tbd to help the user; do NOT tell the user to run tbd commands.\nWhen the user asks for help or orientation, run `tbd shortcut welcome-user`.";
 		if (shouldUseInteractiveOutput(this.ctx)) await paginateOutput(renderMarkdown(markdownContent, this.ctx.color), true);
 		else console.log(markdownContent);
 	}
@@ -10172,7 +10718,7 @@ var PrimeHandler = class extends BaseCommand {
 		console.log("1. Welcome the user! Run `tbd shortcut welcome-user` and follow its");
 		console.log("   instructions to give the user a warm orientation.");
 		console.log("2. Show the user examples of what THEY can say (e.g. \"there's a bug\",");
-		console.log("   \"let's plan a feature\") — do NOT show them tbd CLI commands.");
+		console.log("   \"let's plan a feature\"); do NOT show them tbd CLI commands.");
 		console.log("3. You use tbd on the user's behalf. The user talks to you naturally;");
 		console.log("   you translate their requests into tbd actions.");
 		console.log("");
@@ -10335,80 +10881,6 @@ const SHORTCUT_AGENT_HEADER = "Agent instructions: You have activated a shortcut
 */
 const GUIDELINES_AGENT_HEADER = "Agent instructions: You have activated a guidelines document. If a user has asked you to apply these rules, read them carefully and apply them. Use beads to track each step.";
 
-//#endregion
-//#region src/file/doc-add.ts
-/**
-* Add external documentation to the tbd doc cache.
-*
-* Uses the shared github-fetch utility for URL conversion and fetching.
-* Handles doc-specific concerns: content validation, file writing, and
-* atomic config updates.
-*/
-/**
-* Validate that fetched content looks like a reasonable markdown document.
-*
-* @throws If content fails sanity checks
-*/
-function validateDocContent(content, name) {
-	if (!content || content.trim().length === 0) throw new Error(`Fetched content for "${name}" is empty`);
-	if (content.length < 10) throw new Error(`Fetched content for "${name}" is too short (${content.length} chars)`);
-	if (content.trimStart().startsWith("<!DOCTYPE") || content.trimStart().startsWith("<html")) throw new Error(`Fetched content for "${name}" appears to be an HTML page, not a markdown document`);
-	if (content.split("").filter((c) => {
-		const code = c.charCodeAt(0);
-		return code < 32 && code !== 9 && code !== 10 && code !== 13;
-	}).length / content.length > .1) throw new Error(`Fetched content for "${name}" appears to be binary, not a text document`);
-}
-/**
-* Get the destination subdirectory for a doc type.
-*/
-function getDocTypeSubdir(docType) {
-	switch (docType) {
-		case "guideline": return "guidelines";
-		case "shortcut": return "shortcuts/custom";
-		case "template": return "templates";
-	}
-}
-/**
-* Add an external document to the tbd doc cache.
-*
-* This function:
-* 1. Converts GitHub blob URLs to raw URLs
-* 2. Fetches the content (with gh CLI fallback on 403)
-* 3. Validates the content looks like markdown
-* 4. Writes the file to .tbd/docs/{type}/{name}.md
-* 5. Atomically updates the config to include the new source
-*
-* @throws If fetching, validation, or config update fails
-*/
-async function addDoc(tbdRoot, options) {
-	const { url, name, docType } = options;
-	const cleanName = name.endsWith(".md") ? name.slice(0, -3) : name;
-	const filename = `${cleanName}.md`;
-	const subdir = getDocTypeSubdir(docType);
-	const destPath = `${subdir}/${filename}`;
-	const rawUrl = githubBlobToRawUrl(url);
-	const { content, usedGhCli } = await fetchWithGhFallback(url);
-	validateDocContent(content, cleanName);
-	const fullPath = join(tbdRoot, TBD_DOCS_DIR, destPath);
-	await mkdir(dirname(fullPath), { recursive: true });
-	await writeFile(fullPath, content);
-	const config = await readConfig(tbdRoot);
-	config.docs_cache ??= {
-		files: {},
-		lookup_path: []
-	};
-	config.docs_cache.files ??= {};
-	config.docs_cache.files[destPath] = rawUrl;
-	const lookupDir = `.tbd/docs/${subdir}`;
-	if (!config.docs_cache.lookup_path.includes(lookupDir)) config.docs_cache.lookup_path.push(lookupDir);
-	await writeConfig(tbdRoot, config);
-	return {
-		destPath,
-		rawUrl,
-		usedGhCli
-	};
-}
-
 //#endregion
 //#region src/cli/commands/shortcut.ts
 /**
@@ -10440,7 +10912,7 @@ var ShortcutHandler = class extends BaseCommand {
 				return;
 			}
 			const tbdRoot = await requireInit();
-			const cache = new DocCache((await readConfig(tbdRoot)).docs_cache?.lookup_path ?? DEFAULT_SHORTCUT_PATHS, tbdRoot);
+			const cache = new DocCache([FORK_SHORTCUTS_DIR, ...((await readConfig(tbdRoot)).docs_cache?.lookup_path ?? CACHE_SHORTCUT_PATHS).filter((p) => p !== FORK_SHORTCUTS_DIR)], tbdRoot);
 			await cache.load({ quiet: this.ctx.quiet });
 			if (options.refresh) {
 				await this.handleRefresh(cache, tbdRoot, options.quiet);
@@ -10664,7 +11136,8 @@ var DocCommandHandler = class extends BaseCommand {
 	*/
 	async initCache() {
 		this.tbdRoot = await requireInit();
-		this.cache = new DocCache(this.config.paths, this.tbdRoot);
+		const { localDirs } = await loadServeContext(this.tbdRoot);
+		this.cache = new DocCache(localDirs.length > 0 ? effectiveServePaths(this.config.docType, localDirs) : this.config.paths, this.tbdRoot);
 		await this.cache.load({ quiet: this.ctx.quiet });
 	}
 	/**
@@ -10674,16 +11147,7 @@ var DocCommandHandler = class extends BaseCommand {
 		if (!this.cache) throw new Error("Cache not initialized");
 		const docs = this.cache.list(includeAll);
 		if (this.ctx.json) {
-			this.output.data(docs.map((d) => ({
-				name: d.name,
-				title: d.frontmatter?.title,
-				description: d.frontmatter?.description,
-				path: d.path,
-				sourceDir: d.sourceDir,
-				sizeBytes: d.sizeBytes,
-				approxTokens: d.approxTokens,
-				shadowed: this.cache.isShadowed(d)
-			})));
+			this.output.data(createDocMap(await this.docMapEntries(docs), { name: "tbd-docs" }));
 			return;
 		}
 		if (docs.length === 0) {
@@ -10710,6 +11174,45 @@ var DocCommandHandler = class extends BaseCommand {
 		}
 	}
 	/**
+	* Build docmap entries for this kind's docs through the shared constructor,
+	* with per-kind extensions (size metrics; shadowed flag when applicable).
+	*/
+	async docMapEntries(docs) {
+		const { manifest, files, localDirs } = await loadServeContext(this.tbdRoot);
+		return docs.map((d) => {
+			const { entry } = servedEntryFor(this.tbdRoot, this.config.docType, d, manifest, files, localDirs);
+			return {
+				...entry,
+				sizeBytes: d.sizeBytes,
+				approxTokens: d.approxTokens,
+				...this.cache.isShadowed(d) ? { shadowed: true } : {}
+			};
+		});
+	}
+	/**
+	* Emit one doc: docmap entry + content in JSON mode (the one-entry read
+	* shape, spec Decision 22); in text mode, a forked-copy provenance note on
+	* stderr (Decision 18) before the content.
+	*/
+	async emitDoc(doc, score) {
+		if (this.ctx.json) {
+			const [entry] = await this.docMapEntries([doc]);
+			this.output.data({
+				...entry,
+				...score !== void 0 ? { score } : {},
+				content: doc.content
+			});
+			return;
+		}
+		const { localDirs } = await loadServeContext(this.tbdRoot);
+		if (!this.ctx.quiet) {
+			const rel = relative(this.tbdRoot, doc.path).split("\\").join("/");
+			if (doc.sourceDir.startsWith(FORK_DIR)) process.stderr.write(`(serving forked copy: ${rel})\n`);
+			else if (localDirs.includes(doc.sourceDir)) process.stderr.write(`(serving local doc: ${rel})\n`);
+		}
+		await this.outputDocContent(doc.content);
+	}
+	/**
 	* Handle no query: show explanation + help.
 	*/
 	async handleNoQuery() {
@@ -10746,13 +11249,7 @@ var DocCommandHandler = class extends BaseCommand {
 		if (!this.cache) throw new Error("Cache not initialized");
 		const exactMatch = this.cache.get(query);
 		if (exactMatch) {
-			if (this.ctx.json) this.output.data({
-				name: exactMatch.doc.name,
-				title: exactMatch.doc.frontmatter?.title,
-				score: exactMatch.score,
-				content: exactMatch.doc.content
-			});
-			else await this.outputDocContent(exactMatch.doc.content);
+			await this.emitDoc(exactMatch.doc, exactMatch.score);
 			return;
 		}
 		const matches = this.cache.search(query, 5);
@@ -10770,13 +11267,7 @@ var DocCommandHandler = class extends BaseCommand {
 			}
 			return;
 		}
-		if (this.ctx.json) this.output.data({
-			name: best.doc.name,
-			title: best.doc.frontmatter?.title,
-			score: best.score,
-			content: best.doc.content
-		});
-		else await this.outputDocContent(best.doc.content);
+		await this.emitDoc(best.doc, best.score);
 	}
 	/**
 	* Output document content with interactive formatting (colors, pagination) when appropriate.
@@ -10811,7 +11302,7 @@ var DocCommandHandler = class extends BaseCommand {
 		});
 		if (result.usedGhCli) console.log(pc.dim("  (fetched via gh CLI due to direct access restriction)"));
 		console.log(pc.green(`  Added to ${result.destPath}`));
-		console.log(pc.green(`  Config updated with source: ${result.rawUrl}`));
+		console.log(pc.green(`  Config updated with source: ${result.source}`));
 		console.log("");
 		console.log(`Run \`tbd ${this.config.typeNamePlural} --list\` to verify.`);
 	}
@@ -10880,15 +11371,6 @@ var DocCommandHandler = class extends BaseCommand {
 * Guidelines are reusable coding rules and best practices documents.
 * Give a name or description and tbd will find the matching guideline.
 */
-/**
-* Infer category from guideline name.
-*/
-function inferGuidelineCategory(name) {
-	if (name.startsWith("typescript-")) return "typescript";
-	if (name.startsWith("python-")) return "python";
-	if (name.includes("tdd") || name.includes("testing") || name.includes("golden")) return "testing";
-	if (name.startsWith("general-") || name.includes("rules") || name.includes("patterns") || name.startsWith("backward-") || name.startsWith("convex-") || name.startsWith("release-") || name.startsWith("writing-")) return "general";
-}
 var GuidelinesHandler = class extends DocCommandHandler {
 	constructor(command) {
 		super(command, {
@@ -10923,27 +11405,24 @@ var GuidelinesHandler = class extends DocCommandHandler {
 	async handleListWithCategory(includeAll, category) {
 		if (!this.cache) throw new Error("Cache not initialized");
 		let docs = this.cache.list(includeAll);
-		if (category) docs = docs.filter((d) => {
-			return inferGuidelineCategory(d.name) === category;
-		});
+		if (category) {
+			const wanted = parseCategoryOption(category);
+			docs = docs.filter((d) => docCategory(d.frontmatter) === wanted);
+		}
 		if (this.ctx.json) {
-			this.output.data(docs.map((d) => ({
-				name: d.name,
-				title: d.frontmatter?.title,
-				description: d.frontmatter?.description,
-				category: inferGuidelineCategory(d.name),
-				path: d.path,
-				sourceDir: d.sourceDir,
-				sizeBytes: d.sizeBytes,
-				approxTokens: d.approxTokens,
-				shadowed: this.cache.isShadowed(d)
-			})));
+			const entries = await this.docMapEntries(docs);
+			const docByName = new Map(docs.map((d) => [d.name, d]));
+			const withCategory = entries.map((e) => ({
+				...e,
+				category: docCategory(docByName.get(e.name)?.frontmatter)
+			}));
+			this.output.data(createDocMap(withCategory, { name: "tbd-docs" }));
 			return;
 		}
 		if (docs.length === 0) {
 			if (category) {
 				console.log(`No guidelines found in category: ${category}`);
-				console.log("Valid categories: typescript, python, testing, general");
+				console.log(`Valid categories: ${DOC_CATEGORIES.join(", ")}`);
 			} else {
 				console.log("No guidelines found.");
 				console.log("Run `tbd setup --auto` to install built-in guidelines.");
@@ -11020,12 +11499,11 @@ const templateCommand = new Command("template").description("Find and output doc
 * `tbd setup` - Configure tbd integration with editors and tools.
 *
 * Requires a git repository. All setup artifacts (.tbd/, .claude/) are placed
-* at the git root, adjacent to .git/. Installation is always project-local —
+* at the git root, adjacent to .git/. Installation is always project-local;
 * there is no global/user-level install.
 *
 * Options:
 * - `tbd setup --auto` - Non-interactive setup (for agents/scripts)
-* - `tbd setup --interactive` - Interactive setup with prompts (for humans)
 * - `tbd setup --from-beads` - Migrate from Beads to tbd
 *
 * See: tbd-design.md §6.4.2 Claude Code Integration
@@ -11090,7 +11568,7 @@ async function writeSkillFile(targetPath, payload) {
 }
 /**
 * AGENTS.md managed-block markers. `CODEX_BEGIN_MARKER` is the stable PREFIX of
-* the begin line — the metadata (`format=fNN surface=agents-md`) follows it on the
+* the begin line; the metadata (`format=fNN surface=agents-md`) follows it on the
 * same line, e.g. `<!-- BEGIN TBD INTEGRATION format=f02 surface=agents-md -->`.
 * Cleanup/upgrade code matches on this prefix so it finds both legacy
 * (`<!-- BEGIN TBD INTEGRATION -->`) and current marked blocks.
@@ -11116,7 +11594,7 @@ function parseIntegrationFormat(content) {
 /**
 * Forward-compatibility guard. If a generated artifact was written by a NEWER
 * tbd than this one understands, refuse to rewrite it and tell the user to
-* upgrade tbd — overwriting would downgrade a newer managed format. This is what
+* upgrade tbd; overwriting would downgrade a newer managed format. This is what
 * makes pinning safe on a team: an older tbd fails loudly instead of clobbering.
 */
 function assertNotNewerFormat(content, artifact) {
@@ -11137,7 +11615,7 @@ function getCodexTbdSection() {
 
 This repository uses **tbd** for git-native issue tracking (beads), spec-driven
 planning, and on-demand engineering guidelines.
-As the agent, you operate tbd on the user’s behalf — translate their requests into tbd
+As the agent, you operate tbd on the user’s behalf: translate their requests into tbd
 actions rather than telling them to run commands.
 
 - Run \`tbd prime\` to load current project state and the full tbd workflow.
@@ -11866,11 +12344,10 @@ var SetupCodexHandler = class extends BaseCommand {
 	}
 };
 /**
-* Default handler for `tbd setup` with --auto or --interactive flags.
+* Default handler for `tbd setup --auto`.
 *
 * This implements the unified onboarding flow:
 * - `tbd setup --auto`: Non-interactive setup with smart defaults (for agents)
-* - `tbd setup --interactive`: Interactive setup with prompts (for humans)
 *
 * Decision tree:
 * 1. Not in git repo → Error (git init first)
@@ -11908,14 +12385,16 @@ var SetupDefaultHandler = class extends BaseCommand {
 				config.settings.use_gh_cli = false;
 				ghCliChanged = true;
 			}
+			const stamped = stampSetupVersion(config, VERSION);
+			const versionStamped = stamped !== config;
 			if (migrated) {
 				await withDataSyncContext(projectDir, { lock: true }, async () => void 0);
 				console.log(`  ${colors.success("✓")} Config migrated to latest format`);
 				for (const change of changes) console.log(`      ${colors.dim(change)}`);
 			}
-			if (ghCliChanged) {
-				await writeConfig(projectDir, config);
-				console.log(`  ${colors.success("✓")} Disabled gh CLI auto-setup`);
+			if (versionStamped || ghCliChanged) {
+				await writeConfig(projectDir, stamped);
+				if (ghCliChanged) console.log(`  ${colors.success("✓")} Disabled gh CLI auto-setup`);
 			}
 			console.log("");
 			await this.handleAlreadyInitialized(projectDir, isAutoMode);
@@ -12124,7 +12603,7 @@ Example:
 * Agent integration surfaces that `tbd setup` can install, in install/report
 * order. Each is selectable via `--surfaces=<comma-list>`; with the flag omitted,
 * all are installed. Adding an agent is one entry here plus a case in
-* `installSurface` — there is no per-agent flag to add.
+* `installSurface`; there is no per-agent flag to add.
 */
 const SETUP_SURFACE_IDS = [
 	"portable",
@@ -12257,6 +12736,44 @@ var SetupAutoHandler = class extends BaseCommand {
 			for (const name of skippedSurfaces) console.log(`  ${colors.dim("-")} ${name}`);
 		}
 		if (failed.length > 0) for (const r of failed) console.log(colors.warn(`  ! ${r.name}: ${r.error}`));
+		await this.printDocsSummary(cwd);
+	}
+	/**
+	* Print the Docs summary after the integration sections: how many docs tbd
+	* serves from the gitignored cache, or, when docs are forked into the repo,
+	* the fork count plus any pending upstream updates. Reporting only: setup
+	* never writes the fork dir (only `tbd docs update` modifies forked docs).
+	*
+	* Zero-fork wording is shared with the bare `tbd docs` overview via
+	* {@link docsPostureMenuLines} so the two menus cannot drift.
+	*/
+	async printDocsSummary(cwd) {
+		if (this.ctx.quiet || this.ctx.json) return;
+		let lines;
+		try {
+			const drift = await computeForkDriftSummary(cwd, FORK_DIR, await readForkManifest(cwd));
+			if (drift.forks > 0) {
+				const updates = drift.stale > 0 ? ` ${drift.stale} have upstream updates; run 'tbd docs update'.` : "";
+				lines = [`Docs: ${drift.forks} forked into ${FORK_DIR}/.${updates}`];
+			} else {
+				let total = 0;
+				for (const paths of [
+					DEFAULT_GUIDELINES_PATHS,
+					DEFAULT_SHORTCUT_PATHS,
+					DEFAULT_TEMPLATE_PATHS,
+					DEFAULT_REFERENCE_PATHS
+				]) {
+					const cache = new DocCache(paths, cwd);
+					await cache.load({ quiet: true });
+					total += cache.list().length;
+				}
+				lines = [`Docs: ${total} docs available in the cache (.tbd/docs/, gitignored); none forked into the repo.`, ...docsPostureMenuLines().map((line) => `  ${line}`)];
+			}
+		} catch {
+			return;
+		}
+		console.log("");
+		for (const line of lines) console.log(line);
 	}
 	/**
 	* Sync docs using syncDocsWithDefaults.
@@ -12407,8 +12924,8 @@ var SetupAutoHandler = class extends BaseCommand {
 		return result;
 	}
 };
-const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").option("--surfaces <list>", "Comma-separated agent surfaces to install: portable, agents-md, claude, codex (or \"all\"). Default: all").action(async (options, command) => {
-	if (options.auto || options.interactive) {
+const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").option("--surfaces <list>", "Comma-separated agent surfaces to install: portable, agents-md, claude, codex (or \"all\"). Default: all").action(async (options, command) => {
+	if (options.auto) {
 		await new SetupDefaultHandler(command).run(options);
 		return;
 	}
@@ -12427,7 +12944,6 @@ const setupCommand = new Command("setup").description("Configure tbd integration
 	console.log("");
 	console.log("Modes (one required):");
 	console.log("  --auto              Non-interactive mode with smart defaults (for agents/scripts)");
-	console.log("  --interactive       Interactive mode with prompts (for humans)");
 	console.log("  --from-beads        Migrate from Beads to tbd (implies --auto)");
 	console.log("");
 	console.log("Options:");
@@ -12439,7 +12955,6 @@ const setupCommand = new Command("setup").description("Configure tbd integration
 	console.log("Examples:");
 	console.log("  tbd setup --auto --prefix=tbd   # Full automatic setup with prefix");
 	console.log("  tbd setup --from-beads          # Migrate from Beads (uses beads prefix)");
-	console.log("  tbd setup --interactive         # Interactive setup with prompts");
 	console.log("");
 	console.log("For surgical initialization without integrations, see: tbd init --help");
 });