get-tbd 0.2.3 → 0.3.0

package/dist/docs/references/docref-format.md

@@ -0,0 +1,71 @@
+---
+title: Docref Format
+description: A single-string, URI-like address for any document, the one source-address grammar used across tbd
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+category: general
+---
+# Docref Format (v0.1)
+
+A **docref** is a single-string, URI-like address for a document.
+It is the one address syntax used everywhere tbd names where a doc comes from or lives:
+`docs_cache.files` values, the fork manifest’s `source` field, and future `tbd docs add`
+arguments. The grammar is tool-agnostic: any application can adopt it, and the reference
+implementation (`src/docref/` in tbd) is standalone and dependency-free.
+
+## Forms
+
+| Form | Example | Meaning |
+| --- | --- | --- |
+| internal | `internal:guidelines/python-rules.md` | A doc bundled inside the consuming tool. App-relative: each tool resolves it against its own bundled collection. |
+| local | `./docs/general/`, `../shared/rules.md`, `/abs/f.md`, `C:/docs/f.md` | A filesystem path. Must be **anchored**: `./`, `../`, `/`, or a Windows drive letter. |
+| url | `https://example.com/style.md` | A plain URL, kept verbatim. |
+| git | `github:owner/repo@ref//path/to/file.md` | A file in a git host’s repo. `gitlab:` likewise. `@ref` is optional; `//` separates repo from path. |
+| git + fragment | `github:o/r@main//f.md#naming` | Optional in-document anchor, preserved verbatim. |
+
+The `//` separator makes refs with slashes unambiguous:
+`github:o/r@feature/x//docs/f.md` pins ref `feature/x`. Unlike GitHub blob URLs, where
+ref and path cannot be split reliably.
+
+## Strictness
+
+The grammar is deliberately strict; consumers may be lenient at their own boundary:
+
+- **Bare relative strings are not docrefs** (`guidelines/x.md` is invalid).
+  A consumer that wants to accept them may prepend `./` before parsing.
+  A strict grammar plus lenient consumers composes; the reverse can never be tightened.
+- **Home-relative paths (`~/…`) are rejected** in v0.1 (no portable expansion
+  semantics).
+- **Unknown schemes are rejected** (`mailto:…`, `git:…`). Additional protocols, for
+  example a host-bearing git scheme for forges beyond GitHub/GitLab, may be added in
+  future versions.
+
+## Normalization
+
+Web URLs that point at a known git host’s file view normalize to the canonical scheme,
+so one file has one address:
+
+- `https://github.com/o/r/blob/main/f.md` → `github:o/r@main//f.md`
+- `https://raw.githubusercontent.com/o/r/main/f.md` → `github:o/r@main//f.md`
+- `https://gitlab.com/o/r/-/blob/main/f.md` → `gitlab:o/r@main//f.md`
+
+URL fragments are preserved through normalization; a normalizer must never silently drop
+data.
+
+## Equality
+
+Two docrefs are equal when their canonical forms are identical, except that local paths
+compare with a single leading `./` ignored.
+Equality is purely syntactic: hosts and owners are not case-normalized, and no network
+or filesystem is consulted.
+
+## Prior Art
+
+[purl](https://github.com/package-url/purl-spec) addresses *packages*
+(`pkg:type/namespace/name@version`); its identity is the package, with file paths as an
+awkward suffix. docref’s identity is the *document*, with in-repo paths and anchored
+local files as first-class forms, which is why a separate small grammar exists rather
+than a purl profile.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/shortcuts/standard/checkout-third-party-repo.md

@@ -28,12 +28,24 @@ need.
 3. **Identify the version in use**: Check `package.json`, `requirements.txt`,
    `Cargo.toml`, etc. for the exact version of the dependency you’re investigating.
 
-4. **Clone the repo**:
+4. **Reuse an existing checkout**: If `attic/<repo-name>` already exists—common when a
+   repo is consulted across sessions—use it instead of re-cloning.
+   Confirm it is clean; attic clones are read-only, so it should be, and if it is dirty,
+   stop and flag it rather than discarding changes.
+   Then update to the version you need and skip the clone step below.
+   ```bash
+   git -C attic/<repo-name> status         # Should be clean; if dirty, stop and flag
+   git -C attic/<repo-name> pull           # Update the clone...
+   # ...or, if it is pinned to a tag (detached HEAD, where plain pull fails):
+   git -C attic/<repo-name> fetch --tags && git -C attic/<repo-name> checkout <tag>
+   ```
+
+5. **Clone the repo** (if not already in `attic/`):
    ```bash
    git clone <repo-url> attic/<repo-name>
    ```
 
-5. **Checkout the matching version**: Find the tag or branch matching your project’s
+6. **Checkout the matching version**: Find the tag or branch matching your project’s
    version:
    ```bash
    cd attic/<repo-name>
@@ -41,13 +53,14 @@ need.
    git checkout <tag-or-branch>
    ```
 
-6. **Explore**: Now use standard tools (Grep, Read, Glob) to investigate the source.
+7. **Explore**: Now use standard tools (Grep, Read, Glob) to investigate the source.
 
 ## Notes
 
 - The `attic/` directory is gitignored—cloned repos won’t pollute your project
 - You can clone multiple repos into attic/ as needed
-- Delete cloned repos when done to save disk space
+- Delete cloned repos to save disk space when you no longer need them—but keep a clone
+  if you expect to consult the same repo again (reuse it via the step above)
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.

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

@@ -56,13 +56,13 @@ Examples: `code-review-and-commit`, `new-plan-spec`, `review-code-typescript`
 ## Referencing Other Shortcuts
 
 Refer to other shortcuts, guidelines, and templates by **name**, using the command that
-surfaces them — never by file path:
+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
+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.
@@ -80,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/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/skill-baseline.md

@@ -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.
@@ -82,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` |
@@ -96,7 +103,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
@@ -171,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

@@ -71,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)
@@ -119,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)
@@ -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)
@@ -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