get-tbd 0.2.2 → 0.3.0

package/dist/docs/shortcuts/standard/new-shortcut.md

@@ -53,6 +53,20 @@ Examples: `code-review-and-commit`, `new-plan-spec`, `review-code-typescript`
 - **Reference, don’t duplicate**: Point to `tbd shortcut/guidelines/template` commands
 - **Trust the agent**: They’ll adapt to context
 
+## Referencing Other Shortcuts
+
+Refer to other shortcuts, guidelines, and templates by **name**, using the command that
+surfaces them, never by file path:
+
+- Another shortcut: `tbd shortcut <name>` (e.g. `tbd shortcut precommit-process`)
+- A guideline: `tbd guidelines <name>` (e.g. `tbd guidelines typescript-rules`)
+- A template: `tbd template <name>` (e.g. `tbd template plan-spec`)
+
+The name stays valid wherever the file ends up: read directly, served via
+`tbd shortcut`, or embedded in another tool.
+File paths and relative markdown links break when shortcuts are flattened into the
+`.tbd` cache or relocated, so don’t use them to point at other shortcuts.
+
 ## Testing
 
 ```bash
@@ -66,10 +80,10 @@ For official shortcuts: `pnpm build` in packages/tbd/
 
 For official shortcuts added to `packages/tbd/docs/shortcuts/standard/`:
 
-1. **Update root README.md** — Add to the “Available shortcuts” table (grouped by
+1. **Update root README.md:** Add to the “Available shortcuts” table (grouped by
    category: Planning, Documentation, Review, Git, Cleanup, Session, Meta)
-2. **Sync docs cache** — Run `tbd setup --auto` to update `.tbd/docs/`
-3. **Rebuild** — `pnpm build` in packages/tbd/ (also copies README to package)
+2. **Sync docs cache:** Run `tbd setup --auto` to update `.tbd/docs/`
+3. **Rebuild:** `pnpm build` in packages/tbd/ (also copies README to package)
 
 ## Shortcuts vs Guidelines
 

package/dist/docs/shortcuts/standard/plan-implementation-with-beads.md

@@ -48,7 +48,7 @@ If unclear, ask the user if they want you to create a spec first using
 
 - **Parent/Child** (`--parent`): Hierarchical grouping.
   All implementation beads should be children of the epic.
-  Children inherit context from their parent — `tbd show` auto-displays the parent’s
+  Children inherit context from their parent; `tbd show` auto-displays the parent’s
   details, so child descriptions don’t need to duplicate the parent’s context.
 
 - **Blocker** (`tbd dep add`): Sequential ordering.

package/dist/docs/shortcuts/standard/setup-github-cli.md

@@ -64,7 +64,10 @@ If this fails for any reason, follow the steps below.
 
 Set `GH_TOKEN` environment variable with a GitHub personal access token **before**
 starting the session.
-See `docs/general/agent-setup/github-cli-setup.md` for token creation instructions.
+Create a [Personal Access Token](https://github.com/settings/tokens?type=beta)
+(fine-grained recommended) with **Contents** and **Pull requests** read/write
+permissions, then export it (e.g. add `export GH_TOKEN=...` to your shell profile or set
+it in your agent environment).
 
 ## Quick Reference
 

package/dist/docs/shortcuts/standard/suggest-upstream-improvements.md

@@ -0,0 +1,69 @@
+---
+title: Suggest Upstream Improvements
+description: Review local doc-fork customizations and contribute the generally useful changes back upstream
+category: meta
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+This shortcut reviews the docs this project has forked and customized (in `docs/tbd/`),
+decides which changes generalize beyond this project, and proposes them upstream, to the
+tbd repo for tbd’s bundled docs, or to your org’s docs repo for docs added by URL.
+
+## When to Use
+
+- Forked guidelines or shortcuts have accumulated edits that would help other projects.
+- Before unforking: upstream the good parts first, so nothing is lost when the fork goes
+  away.
+- After `tbd docs update` keeps producing the same conflict because upstream lacks an
+  improvement you made locally.
+
+## Instructions
+
+Create a to-do list with the following items then perform all of them:
+
+1. **Collect customizations**: Run `tbd docs status --json` and collect every doc in
+   `customized` state (including customized docs that also have upstream updates
+   pending).
+
+2. **Review each diff**: For each doc, run `tbd docs diff <name> --base` (your file vs
+   its recorded base, exactly what this project changed).
+   Classify each hunk:
+   - **Generally applicable**: fixes, clarifications, better examples, rules any project
+     would benefit from. Candidates for upstreaming.
+   - **Project-specific**: team conventions, internal links, stack-specific overrides.
+     These stay in the fork; do not propose them.
+
+3. **Identify the upstream target** for each doc with generalizable hunks:
+   - Bundled docs (manifest `source` starts with `internal:`): the tbd repo
+     (`jlevy/tbd`), where doc sources live under `packages/tbd/docs/`.
+   - URL-added docs: the repo their docref points at (for example, your org’s shared
+     docs repo).
+
+4. **Draft the proposal**: For each doc, draft an issue or PR body containing:
+   - Which doc (name and kind) and why the change is generally useful.
+   - Only the generalizable diff hunks, in fenced code blocks.
+   - Brief project context: what prompted the change here.
+
+5. **Confirm, then file**: Show the draft to the user and get confirmation.
+   Then:
+   - Issue: `gh issue create -R jlevy/tbd` (or the org’s repo) with the drafted body.
+   - PR (preferred when the change is small and ready): apply the generalizable hunks to
+     the upstream source file on a branch and open a PR with `gh pr create`.
+
+6. **Close the loop (after upstream merges)**: Once the change ships upstream and tbd is
+   upgraded, run `tbd docs update`. If upstream adopted the customization, the merge
+   converges and the doc returns to unmodified `forked` state, then a plain
+   `tbd docs unfork <name>` (no `--force` needed) completes the cleanup, or keep the
+   fork for future edits.
+
+## Notes
+
+- Only propose hunks you would accept as a maintainer: each should stand alone, with
+  rationale.
+- Never file an issue or PR without showing the user the draft first.
+- Diff views: `tbd docs diff <name>` (no flag) compares your copy against current
+  upstream; `--base` is the right view for “what did we change”; `--upstream` shows
+  incoming upstream changes.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/sync-failure-recovery.md

@@ -31,7 +31,7 @@ git commit -m "tbd: save outbox"
 git push
 ```
 
-**Note:** Do not gitignore `.tbd/workspaces/` — it must be committed to your working
+**Note:** Do not gitignore `.tbd/workspaces/`; it must be committed to your working
 branch.
 
 ## Later, When Sync Works

package/dist/docs/shortcuts/standard/welcome-user.md

@@ -13,6 +13,33 @@ project.
 First, run `tbd status` to check the current state.
 Give a brief summary of the status (repository, sync status, integrations).
 
+Then make the two-axis guidelines offer, one short question per axis:
+
+1. **Scope:** keep **all** standard guidelines active (recommended), or just a subset
+   for this project’s languages and stack?
+   Give a few examples of what the standard set covers, such as Python guidelines,
+   TypeScript guidelines, documentation guidelines, testing guidelines, and commit
+   conventions. Note that `tbd guidelines --list` shows the full set.
+2. **Visibility:** leave them in tbd’s hidden cache (the default, which just works), or
+   fork them into `docs/tbd/` so they are visible on GitHub, reviewable in PRs, and
+   editable (checked into git)?
+
+When explaining visibility, give this guidance: for small repos or quick work, you
+usually don’t want to fork.
+Leaving the docs in tbd’s hidden cache is the simplest start and just works.
+For larger projects with a lot of customization, forking can make sense: it gives you
+maximum control to adapt, improve, and customize every guideline.
+Either way the choice is reversible: you can tell tbd you want to fork the docs later,
+so starting with the hidden cache loses nothing.
+
+Explain that forking changes nothing about how guidelines work.
+Both paths serve the same guidelines; forking only makes them visible and customizable.
+If the user wants visible docs, the recommendation is to fork the general guidelines
+plus the categories for the project’s languages and frameworks:
+`tbd docs fork --category=general --category=<language>` (e.g. `--category=typescript`).
+Use `tbd docs fork --all` for everything, or `tbd docs fork <name> [<name>...]` to fork
+individual docs by name (preview with `--dry-run` first).
+
 Then show the welcome message:
 
 * * *
@@ -50,6 +77,7 @@ Here are examples of things you can say and what happens:
 | “I’m building a TypeScript CLI” | Applies TypeScript CLI guidelines |
 | “Help me set up better testing” | Applies testing guidelines |
 | “What are the Python best practices?” | Applies Python guidelines |
+| “Make the guidelines visible in my repo” | Forks them into `docs/tbd/` (`tbd docs fork --category=general --category=<lang>`, or `tbd docs fork --all`) |
 
 **Tips:**
 

package/dist/docs/shortcuts/system/shortcut-explanation.md

@@ -24,6 +24,20 @@ These may include:
 - File operations and git workflows
 - Prompts for gathering information from the user
 
+## Referencing Other Shortcuts, Guidelines, and Templates
+
+Shortcuts refer to each other by **name**, using the command that surfaces them:
+
+- Another shortcut: `tbd shortcut <name>` (e.g. `tbd shortcut precommit-process`)
+- A guideline: `tbd guidelines <name>` (e.g. `tbd guidelines typescript-rules`)
+- A template: `tbd template <name>` (e.g. `tbd template plan-spec`)
+
+Always reference by name, never by file path.
+The name is stable wherever the shortcut lives, so the reference stays valid whether the
+file is read directly, served via `tbd shortcut`, or embedded in another tool.
+File paths (and relative markdown links) break when shortcuts are flattened into the
+`.tbd` cache or relocated, so avoid them inside shortcut bodies.
+
 ## Example Workflow
 
 User: “I want to create a new research brief”
@@ -37,7 +51,8 @@ Agent:
 
 Shortcuts are loaded from directories in the doc path (searched in order):
 
-- `.tbd/docs/shortcuts/system/` - Core system docs (skill.md, etc.)
+- `.tbd/docs/shortcuts/system/` - Core system docs (skill-baseline,
+  shortcut-explanation, etc.)
 - `.tbd/docs/shortcuts/standard/` - Standard workflow shortcuts
 
 Directories earlier in the doc path take precedence.

package/dist/docs/shortcuts/system/skill-baseline.md

@@ -9,7 +9,7 @@ description: Full tbd workflow guide for agents
    Drop-in replacement for `bd`.
 2. **Spec-Driven Workflows**: Plan features → break into beads → implement
    systematically.
-3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+3. **Knowledge Injection**: 25+ engineering guidelines (TypeScript, Python, TDD,
    testing, Convex, monorepos) available on demand.
 4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
    commits, PRs, cleanup, handoffs).
@@ -17,12 +17,15 @@ description: Full tbd workflow guide for agents
 ## 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
@@ -34,7 +37,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.
@@ -71,6 +74,7 @@ or want help → run `tbd shortcut welcome-user`
 | “Create a PR” / “File a PR” | `tbd shortcut create-or-update-pr-simple` |
 | “Merge main into my branch” | `tbd shortcut merge-upstream` |
 | **Guidelines & Knowledge** |  |
+| *(any engineering work)* | Load the **General engineering** group first (see below) |
 | “Use TypeScript best practices” | `tbd guidelines typescript-rules` |
 | “Use Python best practices” | `tbd guidelines python-rules` |
 | “Build a TypeScript CLI” | `tbd guidelines typescript-cli-tool-rules` |
@@ -81,6 +85,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` |
@@ -89,7 +97,13 @@ or want help → run `tbd shortcut welcome-user`
 | “Check out this library’s source” | `tbd shortcut checkout-third-party-repo` |
 | *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
 
-**Note:** Never gitignore `.tbd/workspaces/` — the outbox must be committed to your
+**Loading guidelines for engineering work:** Before writing or reviewing code, load the
+**General engineering** group—the `general-*` rules plus `error-handling-rules`—since
+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
 working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 
 ## CRITICAL: Session Closing Protocol
@@ -164,6 +178,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/tbd-design.md

@@ -18,8 +18,7 @@ agents.
   - [1. Introduction](#1-introduction)
     - [1.1 What is tbd?](#11-what-is-tbd)
     - [1.2 When to Use tbd vs Beads](#12-when-to-use-tbd-vs-beads)
-    - [1.3 Why Replace Beads?
-      (Architecture Comparison)](#13-why-replace-beads-architecture-comparison)
+    - [1.3 Why Replace Beads? (Architecture Comparison)](#13-why-replace-beads-architecture-comparison)
     - [1.4 Design Goals](#14-design-goals)
     - [1.5 Design Principles](#15-design-principles)
     - [1.6 Non-Goals](#16-non-goals)
@@ -72,6 +71,7 @@ agents.
       - [2.8.5 Comparison with Beads](#285-comparison-with-beads)
       - [2.8.6 Future Dependency Types](#286-future-dependency-types)
       - [2.8.7 Future: Transitive Blocking Option](#287-future-transitive-blocking-option)
+    - [2.9 Managed Docs: Copies, Forks, and Synchronization](#29-managed-docs-copies-forks-and-synchronization)
   - [3. Git Layer](#3-git-layer)
     - [3.1 Overview](#31-overview)
     - [3.2 Sync Branch Architecture](#32-sync-branch-architecture)
@@ -120,6 +120,7 @@ agents.
     - [4.10 Global Options](#410-global-options)
     - [4.11 Attic Commands](#411-attic-commands)
     - [4.12 Output Formats](#412-output-formats)
+    - [4.13 Docs Commands](#413-docs-commands)
   - [5. Beads Compatibility](#5-beads-compatibility)
     - [5.1 Import Strategy](#51-import-strategy)
       - [5.1.1 Import Command](#511-import-command)
@@ -659,6 +660,7 @@ serialization:
 > directory.
 
 > **Why canonical format?** Deterministic serialization ensures:
+> 
 > 1. Git diffs show only actual content changes (no spurious whitespace/ordering noise)
 > 2. Testing is reliable (same input produces same output)
 > 3. Future caching/deduplication can use content hashes if needed
@@ -1968,6 +1970,107 @@ Add transitive blocking as an opt-in feature if users request it after real-worl
 
 * * *
 
+### 2.9 Managed Docs: Copies, Forks, and Synchronization
+
+tbd manages documentation (guidelines, shortcuts, templates) alongside issues.
+With forkable docs (format f05, `plan-2026-06-11-forkable-docs.md`), a doc can exist as
+up to **four copies plus a manifest**, each with a distinct owner and lifecycle.
+This section is the canonical statement of that model and the invariants that make every
+combination of user actions safe.
+
+#### The copies
+
+| Copy | Location | In git? | Written by | Role |
+| --- | --- | --- | --- | --- |
+| Bundled | npm package (`dist/docs/`) | n/a (per tbd version) | tbd releases | The upstream for `internal:` docs; immutable per installed version |
+| Cache | `.tbd/docs/` | gitignored | doc sync only | Complete, pristine, machine-local mirror of all upstream docs (bundled + URL sources); disposable |
+| Fork | `docs/tbd/<kind>/<name>.md` | tracked | `tbd docs fork/update` + the user/agent | The editable copy that tbd serves; optional, per-doc |
+| Base | `.tbd/doc-forks/base/<kind>/<name>.md` | tracked | `tbd docs fork/update` | Verbatim upstream snapshot at the fork point; the three-way merge base |
+| Manifest | `.tbd/doc-forks/forks.yml` | tracked | `tbd docs fork/unfork/update` | Provenance per fork: source docref, `base_hash` (LF-normalized sha256), `tbd_version` at fork point, `conflicted` flag |
+
+A doc’s identity is **kind + name**; paths follow fixed conventions
+(`<kind-dir>/<name>.md`, flat; nested folders are not scanned).
+
+The model follows one principle: **resolve by convention; track only what cannot be
+derived; publish the inventory as a generated view.** Lookup is a fixed search path over
+conventional locations; no registry that can drift from disk.
+The only stored tracking is the fork manifest, which records the one fact that cannot be
+recomputed from the files: each fork’s upstream source and base snapshot.
+The docmap that doc commands emit is a generated view of this state, never an input to
+resolution. (A copy-all-and-gitignore variant of the fork dir was considered and
+rejected: gitignored mirrors are invisible on GitHub and in PRs, and edits to them
+diverge silently with no team-visible artifact; `tbd docs fork --all` provides the
+all-visible posture in tracked form.
+See the spec’s Alternatives.)
+
+#### Invariants
+
+1. **Serving precedence**: the fork dir is prepended to every kind’s lookup path, so a
+   forked (or hand-authored local) file shadows the cache copy by name.
+   With nothing forked, lookup paths reduce to the cache and behavior is byte-identical
+   to pre-f05.
+2. **Cache completeness**: doc sync always installs *all* upstream docs into the cache,
+   including forked ones.
+   The cache copy is the pristine reference: the staleness comparator, the “theirs” side
+   of every update merge, and the fallback after unfork.
+3. **The cache is never authored**: only doc sync writes it, nothing else reads from
+   anywhere else for upstream content, and deleting it is always safe (auto-sync
+   regenerates it on the next doc access, including on fresh clones).
+4. **Tracked files mutate only via explicit `tbd docs` verbs** (fork/unfork/update).
+   Setup, `tbd sync`, and background auto-sync refresh the cache and *report* drift but
+   never write the fork dir, bases, or manifest.
+5. **Tracking is derived, not stored**: every doc state
+   (`upstream/forked/customized/stale/conflicted/local/missing/orphaned`) is a pure
+   function of (manifest entry present?, file hash, base hash, cache hash, conflicted
+   flag, markers present).
+   There is no hidden database, so no sequence of git operations (commit, pull, merge,
+   revert, partial commits) can desynchronize tbd from the files: collaborators
+   recompute identical states from identical content.
+6. **The base is the fork point**: advanced only by fork (refresh) and update; with the
+   stored snapshot, `customized` (file ≠ base), `stale` (cache ≠ base), and three-way
+   merging are exact, offline operations for every collaborator regardless of which tbd
+   version created the fork.
+7. **The format gate**: forking bumps nothing at runtime, but the f05 `tbd_format` in
+   `config.yml` (mirrored into the machine-local common-dir `layout.yml`) makes pre-f05
+   clients refuse the repo; they would otherwise serve upstream copies of docs the team
+   has customized. Within the f05 era, the manifest’s per-entry `tbd_version` guards the
+   remaining skew: `tbd docs update` refuses to touch a doc whose fork point was
+   advanced by a newer tbd than the one running, since that client’s bundled “upstream”
+   is older than the fork point and updating would silently downgrade the doc.
+
+#### Who writes what (synchronization flows)
+
+| Flow | Reads | Writes | Tracked files touched |
+| --- | --- | --- | --- |
+| npm upgrade | — | bundle | none |
+| Doc sync (`tbd sync --docs`, auto-sync, setup) | bundle + URL sources | cache | none |
+| `tbd docs fork` | cache | fork file, base, manifest, fork-dir README | yes (explicit) |
+| `tbd docs update` | cache, base, fork file | fork file and/or base, manifest, README | yes (explicit) |
+| `tbd docs unfork` | base, fork file | removes fork artifacts, README | yes (explicit) |
+| User/agent edits | — | fork dir (any way they like) | yes (theirs) |
+| git operations | — | any tracked artifact | yes (theirs) |
+
+Staleness appears exactly when doc sync moves the cache past a fork’s base; awareness
+surfaces (`tbd docs status`, the one-line `tbd sync` drift notice) report it, and only
+the explicit `tbd docs update` acts on it.
+
+#### Drift and degraded modes
+
+Because of invariant 5, arbitrary user actions in the fork dir resolve to defined
+states: edits → `customized`; deletion → `missing` (serving falls back to the cache);
+rename → `missing` + `local`; new files → `local` (served, no upstream); deleting the
+manifest → everything `local` (serving unaffected); moving into subfolders → not scanned
+(documented). Degraded modes fail soft: an unreachable URL source keeps serving the
+last-good cache copy; an empty cache self-heals via auto-sync; a deleted base blocks
+merging only for that doc (repairable via `update --keep-ours`); the upgrade abort path
+is specified in `tbd-docs.md` §Troubleshooting.
+The drift matrix with resolutions is user-facing in `tbd-docs.md` §“Forked Docs in Your
+Repo”; the state matrix, update decision table, and drift scenarios are pinned by
+`fork-manifest`/`fork-update`/`doc-fork` unit tests and the `cli-docs-fork`/
+`cli-docs-update` golden tryscripts.
+
+* * *
+
 ## 3. Git Layer
 
 ### 3.1 Overview
@@ -2034,6 +2137,8 @@ main branch:                    tbd-sync branch:
 .tbd/.gitignore       # Controls what's gitignored below
 .tbd/.gitattributes   # Merge strategies (merge=union for ids.yml)
 .tbd/workspaces/      # Persistent state (outbox, named workspaces)
+.tbd/doc-forks/       # Fork manifest + base snapshots (see §2.9; f05+)
+docs/tbd/             # Forked docs, outside .tbd/ (see §2.9; only when fork is used)
 ```
 
 #### Files Gitignored (local only)
@@ -2290,7 +2395,7 @@ const issueMergeRules: MergeRules<Issue> = {
   created_by: { strategy: 'preserve_oldest' },
   closed_at: { strategy: 'lww' }, // See status/closed_at rules below
   close_reason: { strategy: 'lww' },
-  child_order_hints: { strategy: 'lww' }, // Soft ordering, LWW on concurrent edits
+  child_order_hints: { strategy: 'union' }, // Append-only set of child IDs; union (dedupe)
 };
 ```
 
@@ -3660,6 +3765,42 @@ tbd attic restore proj-a1b2 2025-01-07T10-30-00Z
 
 * * *
 
+### 4.13 Docs Commands
+
+Operations on managed docs (see §2.9 for the data model) live under the noun-scoped
+`tbd docs` group, alongside the existing per-kind readers (`tbd guidelines`,
+`tbd shortcut`, `tbd template`, which serve forked copies transparently via lookup
+precedence):
+
+```bash
+tbd docs fork [names...] [--kind] [--all] [--force] [--dry-run]   # copy into docs/tbd/
+tbd docs unfork [names...] [--all] [--force]   # back to upstream; refuses to drop edits
+tbd docs status [--json]                       # per-doc states + missing/local hints
+tbd docs update [names...] [--merge|--keep-ours] [--dry-run]      # reconcile with upstream
+tbd docs diff <name> [--base|--upstream]       # net fork / your changes / incoming
+tbd docs list [--kind] [--json]                # cross-kind list with state markers
+```
+
+tbd has three deliberately separate update surfaces; they differ in scope, risk, and
+failure mode, and doc updates are the only one that can merge and mutate tracked files:
+
+| Command | Scope | Touches | Modifies tracked files? |
+| --- | --- | --- | --- |
+| `tbd sync` | project data (issues) | sync worktree + `tbd-sync` branch; refreshes the doc cache and *reports* fork drift | never |
+| `tbd setup --auto` | installation + integrations | skills, hooks, settings, `AGENTS.md`; invokes a docs-cache sync | only generated integration files |
+| `tbd docs update` | forked docs | fork dir + bases + manifest (offline, against the cache) | **yes, the only doc command that does** |
+
+Update semantics (the full decision table is unit-tested row by row): an unmodified
+stale fork is replaced; a customized stale fork gets a `git merge-file` three-way merge
+that applies automatically when clean; conflicts are skipped by default and listed with
+the two explicit strategies: `--merge` (combine, standard conflict markers, sets the
+`conflicted` flag until markers are resolved) and `--keep-ours` (keep the local content,
+advance the fork point).
+Forked files are git-tracked, so every applied update is reviewable in `git diff` and
+revertible; git is the undo.
+
+* * *
+
 ## 5. Beads Compatibility
 
 ### 5.1 Import Strategy