get-tbd 0.2.3 → 0.3.0

package/dist/docref-C7g0sjvL.mjs

@@ -0,0 +1,167 @@
+//#region src/docref/docref.ts
+/** Error thrown when a string is not a valid docref. */
+var DocRefError = class extends Error {
+	constructor(input, detail) {
+		super(`Invalid docref ${JSON.stringify(input)}: ${detail}`);
+		this.input = input;
+		this.name = "DocRefError";
+	}
+};
+const GIT_SCHEMES = ["github", "gitlab"];
+/**
+* True for strings that address a local filesystem path: anchored relative
+* (`./`, `../`), absolute (`/`), or a Windows drive-letter path (`C:/`, `C:\`).
+*/
+function looksLocal(input) {
+	return input.startsWith("./") || input.startsWith("../") || input.startsWith("/") || /^[A-Za-z]:[\\/]/.test(input);
+}
+/**
+* Parse a `host:owner/repo[@ref]//path[#fragment]` body (everything after the scheme).
+*/
+function parseGitBody(host, body, input) {
+	const sep = body.indexOf("//");
+	if (sep === -1) throw new DocRefError(input, `git docref must contain "//" separating repo from path`);
+	const repoPart = body.slice(0, sep);
+	const pathPart = body.slice(sep + 2);
+	const hashIndex = pathPart.indexOf("#");
+	const path = hashIndex === -1 ? pathPart : pathPart.slice(0, hashIndex);
+	const fragment = hashIndex === -1 ? void 0 : pathPart.slice(hashIndex + 1) || void 0;
+	if (!path) throw new DocRefError(input, "git docref has an empty path");
+	const atIndex = repoPart.indexOf("@");
+	const ownerRepo = atIndex === -1 ? repoPart : repoPart.slice(0, atIndex);
+	const ref = atIndex === -1 ? void 0 : repoPart.slice(atIndex + 1) || void 0;
+	const slash = ownerRepo.indexOf("/");
+	if (slash === -1) throw new DocRefError(input, "git docref must be \"owner/repo\"");
+	const owner = ownerRepo.slice(0, slash);
+	const repo = ownerRepo.slice(slash + 1);
+	if (!owner || !repo) throw new DocRefError(input, "git docref must be \"owner/repo\"");
+	return {
+		kind: "git",
+		host,
+		owner,
+		repo,
+		path,
+		...ref !== void 0 ? { ref } : {},
+		...fragment !== void 0 ? { fragment } : {}
+	};
+}
+/**
+* If `url` points at a known git host's file view, return the equivalent git
+* docref; otherwise return null (caller keeps it as a plain URL).
+* URL fragments are preserved; normalization must never silently drop data.
+*/
+function gitRefFromUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return null;
+	}
+	const segments = parsed.pathname.split("/").filter(Boolean);
+	const fragment = parsed.hash ? parsed.hash.slice(1) || void 0 : void 0;
+	const frag = fragment !== void 0 ? { fragment } : {};
+	if (parsed.hostname === "github.com" && segments[2] === "blob" && segments.length >= 5) {
+		const [owner, repo, , ref, ...rest] = segments;
+		return {
+			kind: "git",
+			host: "github",
+			owner,
+			repo,
+			ref,
+			path: rest.join("/"),
+			...frag
+		};
+	}
+	if (parsed.hostname === "raw.githubusercontent.com" && segments.length >= 4) {
+		const [owner, repo, ref, ...rest] = segments;
+		return {
+			kind: "git",
+			host: "github",
+			owner,
+			repo,
+			ref,
+			path: rest.join("/"),
+			...frag
+		};
+	}
+	if (parsed.hostname === "gitlab.com" && segments[2] === "-" && segments[3] === "blob") {
+		const [owner, repo, , , ref, ...rest] = segments;
+		if (owner && repo && ref && rest.length > 0) return {
+			kind: "git",
+			host: "gitlab",
+			owner,
+			repo,
+			ref,
+			path: rest.join("/"),
+			...frag
+		};
+	}
+	return null;
+}
+/**
+* Parse a docref string into a structured {@link DocRef}.
+* Throws {@link DocRefError} if the string is not a valid docref.
+*/
+function parseDocRef(input) {
+	const raw = input.trim();
+	if (!raw) throw new DocRefError(input, "empty");
+	if (raw.startsWith("internal:")) {
+		const path = raw.slice(9);
+		if (!path) throw new DocRefError(input, "internal docref has an empty path");
+		return {
+			kind: "internal",
+			path
+		};
+	}
+	for (const host of GIT_SCHEMES) {
+		const prefix = `${host}:`;
+		if (raw.startsWith(prefix)) return parseGitBody(host, raw.slice(prefix.length), input);
+	}
+	if (raw.startsWith("http://") || raw.startsWith("https://")) return gitRefFromUrl(raw) ?? {
+		kind: "url",
+		url: raw
+	};
+	if (looksLocal(raw)) return {
+		kind: "local",
+		path: raw
+	};
+	if (raw.startsWith("~")) throw new DocRefError(input, "home-relative (~) paths are not supported; use an absolute or ./-relative path");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) throw new DocRefError(input, "unknown scheme");
+	throw new DocRefError(input, "local paths must start with \"./\", \"../\", or \"/\" (bare relative paths are not valid docrefs)");
+}
+/** Parse a docref, returning null instead of throwing on invalid input. */
+function tryParseDocRef(input) {
+	try {
+		return parseDocRef(input);
+	} catch {
+		return null;
+	}
+}
+/** Serialize a {@link DocRef} back to its canonical string form. */
+function formatDocRef(ref) {
+	switch (ref.kind) {
+		case "internal": return `internal:${ref.path}`;
+		case "local": return ref.path;
+		case "url": return ref.url;
+		case "git": {
+			const refPart = ref.ref ? `@${ref.ref}` : "";
+			const fragPart = ref.fragment ? `#${ref.fragment}` : "";
+			return `${ref.host}:${ref.owner}/${ref.repo}${refPart}//${ref.path}${fragPart}`;
+		}
+	}
+}
+/**
+* Normalize a docref string to its canonical form (parse + re-format).
+* Rationalizes git web URLs into the `github:`/`gitlab:` scheme.
+*/
+function normalizeDocRef(input) {
+	return formatDocRef(parseDocRef(input));
+}
+/** True if `input` parses as a valid docref. */
+function isDocRef(input) {
+	return tryParseDocRef(input) !== null;
+}
+
+//#endregion
+export { tryParseDocRef as a, parseDocRef as i, isDocRef as n, normalizeDocRef as r, DocRefError as t };
+//# sourceMappingURL=docref-C7g0sjvL.mjs.map

package/dist/docref-C7g0sjvL.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"docref-C7g0sjvL.mjs","names":[],"sources":["../src/docref/docref.ts"],"sourcesContent":["/**\n * docref: a single-string, URI-like address for any document.\n *\n * This module is intentionally standalone and dependency-free (no tbd-internal\n * imports) so it can move to its own package later. It is the one address syntax\n * used everywhere a doc's source or location is named: config source strings, the\n * fork manifest's `source` field, `tbd docs add` arguments, and `local_dirs` entries.\n *\n * Supported forms (docref v0.1):\n *   internal:guidelines/python-rules.md       bundled doc shipped inside the consuming\n *                                             tool (app-relative, not tbd-specific)\n *   ./docs/general/   ../shared/   /abs/f.md  local paths; must be anchored with\n *                                             \"./\", \"../\", \"/\", or a Windows drive\n *                                             letter (C:/ or C:\\)\n *   https://example.com/style.md              plain URL\n *   github:owner/repo@ref//path/to/file.md    git-hosted (also gitlab:)\n *   github:owner/repo@ref//file.md#section    optional fragment, preserved\n *\n * The grammar is deliberately strict: bare relative strings (\"guidelines/x.md\") and\n * home-relative paths (\"~/x.md\") are NOT valid docrefs. Consumers that want lenient\n * input may coerce at their own boundary (e.g. prepend \"./\") before parsing; a\n * strict grammar plus lenient consumers composes; the reverse cannot be tightened.\n *\n * Additional protocols (for example a host-bearing git scheme for forges beyond\n * GitHub/GitLab) may be added in future versions.\n *\n * Web URLs that point at a known git host are normalized to the `github:`/`gitlab:`\n * form so there is one canonical address for a given file:\n *   https://github.com/o/r/blob/main/f.md   -> github:o/r@main//f.md\n *   https://raw.githubusercontent.com/o/r/main/f.md -> github:o/r@main//f.md\n */\n\n/** Scheme of a git-hosted docref. */\nexport type GitHost = 'github' | 'gitlab';\n\n/** A parsed document reference. */\nexport type DocRef =\n  | { readonly kind: 'internal'; readonly path: string }\n  | { readonly kind: 'local'; readonly path: string }\n  | { readonly kind: 'url'; readonly url: string }\n  | {\n      readonly kind: 'git';\n      readonly host: GitHost;\n      readonly owner: string;\n      readonly repo: string;\n      readonly ref?: string;\n      readonly path: string;\n      /** Optional in-document anchor (e.g. a heading slug), preserved verbatim. */\n      readonly fragment?: string;\n    };\n\n/** Error thrown when a string is not a valid docref. */\nexport class DocRefError extends Error {\n  constructor(\n    public readonly input: string,\n    detail: string,\n  ) {\n    super(`Invalid docref ${JSON.stringify(input)}: ${detail}`);\n    this.name = 'DocRefError';\n  }\n}\n\nconst GIT_SCHEMES: readonly GitHost[] = ['github', 'gitlab'];\n\n/**\n * True for strings that address a local filesystem path: anchored relative\n * (`./`, `../`), absolute (`/`), or a Windows drive-letter path (`C:/`, `C:\\`).\n */\nfunction looksLocal(input: string): boolean {\n  return (\n    input.startsWith('./') ||\n    input.startsWith('../') ||\n    input.startsWith('/') ||\n    /^[A-Za-z]:[\\\\/]/.test(input)\n  );\n}\n\n/** Strip a single leading `./` for tidy comparison; other forms are left as-is. */\nfunction tidyLocal(path: string): string {\n  return path.startsWith('./') ? path.slice(2) : path;\n}\n\n/**\n * Parse a `host:owner/repo[@ref]//path[#fragment]` body (everything after the scheme).\n */\nfunction parseGitBody(host: GitHost, body: string, input: string): DocRef {\n  const sep = body.indexOf('//');\n  if (sep === -1) {\n    throw new DocRefError(input, `git docref must contain \"//\" separating repo from path`);\n  }\n  const repoPart = body.slice(0, sep);\n  const pathPart = body.slice(sep + 2);\n\n  const hashIndex = pathPart.indexOf('#');\n  const path = hashIndex === -1 ? pathPart : pathPart.slice(0, hashIndex);\n  const fragment = hashIndex === -1 ? undefined : pathPart.slice(hashIndex + 1) || undefined;\n  if (!path) {\n    throw new DocRefError(input, 'git docref has an empty path');\n  }\n\n  const atIndex = repoPart.indexOf('@');\n  const ownerRepo = atIndex === -1 ? repoPart : repoPart.slice(0, atIndex);\n  const ref = atIndex === -1 ? undefined : repoPart.slice(atIndex + 1) || undefined;\n\n  const slash = ownerRepo.indexOf('/');\n  if (slash === -1) {\n    throw new DocRefError(input, 'git docref must be \"owner/repo\"');\n  }\n  const owner = ownerRepo.slice(0, slash);\n  const repo = ownerRepo.slice(slash + 1);\n  if (!owner || !repo) {\n    throw new DocRefError(input, 'git docref must be \"owner/repo\"');\n  }\n\n  return {\n    kind: 'git',\n    host,\n    owner,\n    repo,\n    path,\n    ...(ref !== undefined ? { ref } : {}),\n    ...(fragment !== undefined ? { fragment } : {}),\n  };\n}\n\n/**\n * If `url` points at a known git host's file view, return the equivalent git\n * docref; otherwise return null (caller keeps it as a plain URL).\n * URL fragments are preserved; normalization must never silently drop data.\n */\nfunction gitRefFromUrl(url: string): DocRef | null {\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return null;\n  }\n  const segments = parsed.pathname.split('/').filter(Boolean);\n  const fragment = parsed.hash ? parsed.hash.slice(1) || undefined : undefined;\n  const frag = fragment !== undefined ? { fragment } : {};\n\n  // https://github.com/{owner}/{repo}/blob/{ref}/{path...}\n  if (parsed.hostname === 'github.com' && segments[2] === 'blob' && segments.length >= 5) {\n    const [owner, repo, , ref, ...rest] = segments;\n    return {\n      kind: 'git',\n      host: 'github',\n      owner: owner!,\n      repo: repo!,\n      ref,\n      path: rest.join('/'),\n      ...frag,\n    };\n  }\n  // https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path...}\n  if (parsed.hostname === 'raw.githubusercontent.com' && segments.length >= 4) {\n    const [owner, repo, ref, ...rest] = segments;\n    return {\n      kind: 'git',\n      host: 'github',\n      owner: owner!,\n      repo: repo!,\n      ref,\n      path: rest.join('/'),\n      ...frag,\n    };\n  }\n  // https://gitlab.com/{owner}/{repo}/-/blob/{ref}/{path...}\n  if (parsed.hostname === 'gitlab.com' && segments[2] === '-' && segments[3] === 'blob') {\n    const [owner, repo, , , ref, ...rest] = segments;\n    if (owner && repo && ref && rest.length > 0) {\n      return { kind: 'git', host: 'gitlab', owner, repo, ref, path: rest.join('/'), ...frag };\n    }\n  }\n  return null;\n}\n\n/**\n * Parse a docref string into a structured {@link DocRef}.\n * Throws {@link DocRefError} if the string is not a valid docref.\n */\nexport function parseDocRef(input: string): DocRef {\n  const raw = input.trim();\n  if (!raw) {\n    throw new DocRefError(input, 'empty');\n  }\n\n  // Internal bundled docs.\n  if (raw.startsWith('internal:')) {\n    const path = raw.slice('internal:'.length);\n    if (!path) {\n      throw new DocRefError(input, 'internal docref has an empty path');\n    }\n    return { kind: 'internal', path };\n  }\n\n  // Git-hosted schemes.\n  for (const host of GIT_SCHEMES) {\n    const prefix = `${host}:`;\n    if (raw.startsWith(prefix)) {\n      return parseGitBody(host, raw.slice(prefix.length), input);\n    }\n  }\n\n  // Web URLs: normalize known git hosts, otherwise keep as a plain URL.\n  if (raw.startsWith('http://') || raw.startsWith('https://')) {\n    return gitRefFromUrl(raw) ?? { kind: 'url', url: raw };\n  }\n\n  // Local filesystem paths (anchored; includes Windows drive letters).\n  if (looksLocal(raw)) {\n    return { kind: 'local', path: raw };\n  }\n\n  if (raw.startsWith('~')) {\n    throw new DocRefError(\n      input,\n      'home-relative (~) paths are not supported; use an absolute or ./-relative path',\n    );\n  }\n  if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) {\n    throw new DocRefError(input, 'unknown scheme');\n  }\n  throw new DocRefError(\n    input,\n    'local paths must start with \"./\", \"../\", or \"/\" (bare relative paths are not valid docrefs)',\n  );\n}\n\n/** Parse a docref, returning null instead of throwing on invalid input. */\nexport function tryParseDocRef(input: string): DocRef | null {\n  try {\n    return parseDocRef(input);\n  } catch {\n    return null;\n  }\n}\n\n/** Serialize a {@link DocRef} back to its canonical string form. */\nexport function formatDocRef(ref: DocRef): string {\n  switch (ref.kind) {\n    case 'internal':\n      return `internal:${ref.path}`;\n    case 'local':\n      return ref.path;\n    case 'url':\n      return ref.url;\n    case 'git': {\n      const refPart = ref.ref ? `@${ref.ref}` : '';\n      const fragPart = ref.fragment ? `#${ref.fragment}` : '';\n      return `${ref.host}:${ref.owner}/${ref.repo}${refPart}//${ref.path}${fragPart}`;\n    }\n  }\n}\n\n/**\n * Normalize a docref string to its canonical form (parse + re-format).\n * Rationalizes git web URLs into the `github:`/`gitlab:` scheme.\n */\nexport function normalizeDocRef(input: string): string {\n  return formatDocRef(parseDocRef(input));\n}\n\n/** True if `input` parses as a valid docref. */\nexport function isDocRef(input: string): boolean {\n  return tryParseDocRef(input) !== null;\n}\n\n/**\n * Whether two docrefs address the same document, ignoring a leading `./` on\n * local paths. Comparison is purely syntactic; no case normalization of hosts\n * or owners. Useful for de-duping config entries.\n */\nexport function docRefsEqual(a: DocRef, b: DocRef): boolean {\n  if (a.kind !== b.kind) return false;\n  if (a.kind === 'local' && b.kind === 'local') {\n    return tidyLocal(a.path) === tidyLocal(b.path);\n  }\n  return formatDocRef(a) === formatDocRef(b);\n}\n"],"mappings":"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"}

package/dist/docs/README.md

@@ -37,7 +37,6 @@ will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
 ## Quick Start
 
 > [!TIP]
-> 
 > If running on your own machine, install the `tbd` CLI yourself:
 > 
 > **`npm install -g get-tbd@latest`**
@@ -50,6 +49,11 @@ will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
 > 
 > ***“install tbd (npm install -g get-tbd@latest) and run tbd prime for instructions to
 > set up this project”***
+> 
+> If tbd is already set up in the repo and you want the latest version, tell the agent:
+> 
+> ***“upgrade tbd (npm install -g get-tbd@latest), run tbd setup --auto, and commit the
+> changes”***
 
 That’s it.
 Running `tbd prime` gives agents full workflow context on how to use `tbd` and
@@ -122,7 +126,6 @@ agents handling different aspects that I manage) is slower, because it forces yo
 design, but it gives higher quality results.
 
 > [!NOTE]
-> 
 > We use *Beads* (capitalized) to refer to Steve Yegge’s original
 > [`bd` tool](https://github.com/steveyegge/beads).
 > Lowercase “beads” refers generically to the issues stored in `tbd` or `bd`.
@@ -160,8 +163,8 @@ You just talk naturally.
 
 > [!NOTE]
 > For full technical details, see the [reference docs](packages/tbd/docs/tbd-docs.md)
-> (run `tbd docs`) or the full [design doc](packages/tbd/docs/tbd-design.md)
-> (`tbd design`).
+> (run `tbd docs show tbd-docs`) or the full
+> [design doc](packages/tbd/docs/tbd-design.md) (`tbd design`).
 
 - **Git-native:** Beads live in your repo, synced to a separate, dedicated `tbd-sync`
   branch. Your code history stays clean—no bead churn polluting your logs.
@@ -225,7 +228,6 @@ practices. These aren’t generic tips; they’re mostly my own detailed and som
 opinionated rules with concrete examples, built from months of heavy agentic coding.
 
 > [!TIP]
-> 
 > An example: I *strongly* believe there are much better ways to do testing
 > proliferating hundreds of unit and integration tests.
 > So (with help from some Opus 4.5 and GPT-5 Pro) I wrote a multi-page brief about
@@ -292,6 +294,25 @@ tbd setup --from-beads
 > **Tip:** Run `tbd setup --auto` anytime to refresh skill files, hooks, and configs
 > with the latest shortcuts, guidelines, and templates.
 
+### Upgrading
+
+Upgrading an existing installation is the same two commands, run by you or your agent:
+
+```bash
+npm install -g get-tbd@latest   # Upgrade the CLI
+tbd setup --auto                # Refresh skills/hooks and apply any format migration
+```
+
+If the new version bumps the repository format (`tbd_format` in `.tbd/config.yml`),
+setup migrates it automatically and prints a notice; **commit the resulting diff** to
+publish the upgrade to your team.
+Teammates still on an older tbd then see “This repository requires a newer version of
+tbd” until they run the same two commands.
+Issue data is never touched by an upgrade, and the migration is revertible: see
+“Aborting a Format Upgrade” under Troubleshooting in the CLI manual (`tbd docs manual`).
+If you have forked docs in `docs/tbd/`, `tbd sync` prints a notice when their upstream
+versions moved; run `tbd docs update` to merge the changes in.
+
 ### Team Setup
 
 `tbd` is designed for teams where one person sets up the project and others join later.
@@ -394,11 +415,21 @@ tbd template --list              # List all templates
 tbd template plan-spec           # Get a plan spec template
 
 # Add your own from any URL
+# (per-kind aliases for `tbd docs add <docref>`)
 tbd guidelines --add=<url> --name=<name>
 tbd shortcut --add=<url> --name=<name>
 tbd template --add=<url> --name=<name>
 ```
 
+**Forkable: see them in your repo.** By default these docs are served from a hidden,
+gitignored cache. Fork any of them into `docs/tbd/` and they become visible on GitHub,
+reviewable in PRs, and editable in place—tbd serves your copy instead, and
+`tbd docs update` merges upstream improvements into it after an upgrade:
+
+```bash
+tbd docs fork --all              # Or fork by name: tbd docs fork <name> [<name>...]
+```
+
 **Available shortcuts:**
 
 | Category | Shortcut | Purpose |
@@ -480,7 +511,8 @@ Every command supports these flags for automation:
 ```bash
 tbd                          # Full orientation and workflow guidance
 tbd readme                   # This file
-tbd docs                     # Full CLI reference
+tbd docs                     # Managed-docs overview (cached, forked, and local docs)
+tbd docs show tbd-docs       # Full CLI reference (the manual; alias: tbd docs manual)
 ```
 
 Or read online:

package/dist/docs/SKILL.md

@@ -31,12 +31,15 @@ allowed-tools: Bash(tbd:*), Read, Write
 ## Installation
 
 ```bash
-npm install -g get-tbd@latest
+npm install -g get-tbd@latest      # Install or upgrade the CLI (same command for both)
 tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
-tbd setup --auto                   # Existing tbd project (prefix already set)
+tbd setup --auto                   # Existing tbd project — also the upgrade step (applies any format migration; commit the diff it reports)
 tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
 ```
 
+If tbd refuses with “This repository requires a newer version of tbd”, run the two
+install/upgrade commands above.
+
 ## Routine Commands
 
 ```bash
@@ -48,7 +51,7 @@ tbd setup --auto   # Run any time to refresh setup
 tbd prime      # Restore full context on tbd after compaction
 ```
 
-## CRITICAL: You Operate tbd — The User Doesn’t
+## CRITICAL: You Operate tbd, the User Doesn’t
 
 **You are the tbd operator:** Users talk naturally; you translate their requests to tbd
 actions. DO NOT tell users to run tbd commands.
@@ -96,6 +99,10 @@ or want help → run `tbd shortcut welcome-user`
 | **Documentation** |  |
 | “Research this topic” | `tbd shortcut new-research-brief` |
 | “Document architecture” | `tbd shortcut new-architecture-doc` |
+| “What guidelines/docs are there?” | `tbd docs list` |
+| “Make the guidelines visible / customize doc X” | `tbd docs fork --category=general --category=<lang>` (recommended: general + the repo’s languages), or `tbd docs fork <name>` / `--all`; then edit in `docs/tbd/` |
+| “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` |
+| “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork <name> --force` or finalize with `tbd docs unfork <name>` |
 | **Cleanup & Maintenance** |  |
 | “Clean up this code” / “Remove dead code” | `tbd shortcut code-cleanup-all` |
 | “Fix repository problems” | `tbd doctor --fix` |
@@ -110,7 +117,7 @@ these apply to all code regardless of language.
 Then load the group for the language or framework in use (TypeScript, Python, Convex,
 etc.). Run `tbd guidelines --list` to see all available guidelines.
 
-**Note:** Never gitignore `.tbd/workspaces/` — the outbox must be committed to your
+**Note:** Never gitignore `.tbd/workspaces/`; the outbox must be committed to your
 working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 
 ## CRITICAL: Session Closing Protocol
@@ -185,6 +192,8 @@ working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 | `tbd guidelines <name>` | Load coding guidelines |
 | `tbd guidelines --list` | List guidelines |
 | `tbd template <name>` | Output a template |
+| `tbd docs` / `tbd docs list` | Managed-docs overview / cross-kind list with state markers |
+| `tbd docs fork/unfork/update <name>` | Fork docs into `docs/tbd/`, return to upstream, pull upstream updates |
 
 ## Quick Reference
 

package/dist/docs/guidelines/backward-compatibility-rules.md

@@ -2,6 +2,7 @@
 title: Backward Compatibility Rules
 description: Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
 ---
 ## Backward Compatibility Guidelines
 

package/dist/docs/guidelines/bun-monorepo-patterns.md

@@ -2,6 +2,7 @@
 title: Bun Monorepo Patterns
 description: Modern patterns for Bun-based TypeScript monorepo architecture
 author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: typescript
 ---
 # Bun Monorepo Patterns