get-tbd 0.1.29 → 0.2.0

package/dist/docs/guidelines/common-doc-guidelines.md

@@ -0,0 +1,234 @@
+---
+title: Common Documentation Guidelines
+description: Common cross-project standards for writing and organizing docs, code comments, and text files — how to organize, structure, write, and format documents, plus the guideline footer convention. Downstream of github.com/jlevy/practical-prose. Use whenever writing or editing any documentation, README, guideline, or design doc.
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+# Common Documentation Guidelines
+
+Version: v0.1 (last update 2026-05-11)\
+Joshua Levy (github.com/jlevy)
+
+## Purpose
+
+Both agents and humans benefit from accurate, maintained documentation.
+These are brief and general guidelines for humans and agents when writing and organizing
+code, text files, and documentation.
+
+See the [Practical Prose](https://github.com/jlevy/practical-prose) repository for more
+extensive guidelines and context.
+
+## Organizing Documentation
+
+1. **Organize documents for rapid orientation**
+
+   - All context for understanding a project should be efficiently discoverable.
+   - Documents should reference other documents whenever relevant.
+   - A reader should be able to navigate from an obvious root document to all other
+     documents relevant to a given need by following references.
+
+2. **Use self-evident filenames and concise references**
+
+   - For file naming, always follow existing project conventions.
+     If conventions are unclear, use the conventions here.
+   - Repos and key file folders should have a concise `README.md` as a root document
+     that points to other documents.
+   - Within the top-level repo or within key folders, a `docs/` folder should be added
+     with other key docs and referenced in the `README.md`.
+   - Whenever possible give documents brief but unique names.
+   - Include a hint of the *topic* as well as *purpose*, such as
+     `python-structural-quality-guidelines.md`.
+   - Documents that are likely to become less relevant over time should have *dates or
+     versions* as well, such as `plan-2026-04-28-browser-realtime-streaming.md`.
+   - Unless other rules forbid it, references within documents should be *maximally
+     concise* so they are easy to maintain:
+     - For URLs, use simple link text with the URL in Markdown format.
+     - For other documents, use the simplest unique reference, such as a title or
+       filename, that makes the document easy to find.
+     - Do not include unnecessary metadata, local paths, or other details readily
+       determined from a search.
+
+3. **Divide documents by ownership, audience, and cadence**
+
+   - Documents owned and maintained by different people or teams should usually be
+     distinct.
+   - Documents meant for different audiences (such as internal versus external, or team
+     docs versus sensitive docs) should be kept separate.
+   - Documents updated on different cadences (such as ad hoc, every sprint, or yearly)
+     should be distinct.
+   - Documents with the same ownership, audience, and update cadence should be
+     consolidated.
+
+4. **Organize documents for maintainability**
+
+   - Reference or include relevant guidelines for updates.
+   - Documents should be organized in a way that is compatible with typical update
+     processes.
+
+## Structuring Documents
+
+1. **Explain motivations and background**
+
+   - Assume readers have low context.
+   - Highest-level documents or introductory sections should explain *why* as well as
+     *what*.
+   - A key part of the *why* is explaining why some approaches are taken and their
+     benefits compared to alternate approaches or alternate tools.
+   - Cite external sources for all content that is best covered externally.
+
+2. **Give context gradually and efficiently**
+
+   - Documents should be as brief as possible while still preserving all relevant
+     detail.
+   - Add detail incrementally: start with summaries, link to deeper docs.
+
+3. **Keep details close to where they apply**
+
+   - For example, docstrings in code or descriptions within YAML are preferred to
+     separate documentation when the content directly relates to code or content in
+     those files.
+
+4. **Avoid duplication**
+
+   - Do *not* repeat content in higher-level docs if the details are in referenced
+     lower-level docs.
+   - For example, if `docs/design.md` is an overview of the design, do not repeat the
+     design in `README.md`; reference it instead.
+
+5. **Describe the present state, not what it replaced**
+
+   - By default, write as if the current work or referenced system or design always
+     existed. Most readers need to understand what *is*, not what *was*; replacement
+     history pollutes their context with deprecated concepts they would otherwise never
+     have to learn. When version control like Git is used, its history is the
+     authoritative record of what was removed.
+   - Agents are especially prone to retaining history notations that are no longer
+     relevant ( “this design was changed because of X,” “this function was previously
+     named X”, “removed Z”). When in doubt, cut it.
+   - Exceptions are allowed when the document’s purpose *includes* history: migration
+     guides, postmortems, deprecation notices, decision records, changelogs,
+     governance/versioning sections in standards and schemas, and one-line pointers when
+     a future reader needs to find a predecessor (for example, “see commit `abc123` for
+     the prior shape”). The test is whether the history serves the reader’s task or
+     simply records the author’s path.
+
+## Writing Style
+
+Stylistically, emphasize **clarity**, **depth**, **rigor**, and **warmth**.
+
+1. **Be clear and concise**
+
+   - Use direct and simple language.
+   - Eliminate unnecessary or extraneous words.
+   - Avoid obvious statements.
+   - Remove duplication where a document says the same thing in different places.
+   - If removing a sentence loses no information about the subject, cut it.
+
+2. **Be detailed and specific**
+
+   - Use data or facts instead of generalizations or adjectives.
+   - Avoid vagueness or generalities.
+   - Use concrete examples.
+   - Cite sources whenever possible.
+
+3. **Be rigorous and logical**
+
+   - Use structure, such as headings, subheadings, and lists, effectively.
+   - Keep structure logical and consistent.
+   - Make headings specific; cleave to the true contours of the subject matter.
+
+4. **Be engaging and warm**
+
+   - Be friendly in tone, avoiding unnecessary formality unless required by the
+     situation (such as in legal documents).
+   - Be gracious in acknowledging previous work, even if correcting it.
+   - Avoid unnecessary coldness, blame, condescension, or opacity when writing for
+     humans. For agent-facing documents, the equivalent is directness, explicit context,
+     and absence of performative fluff.
+     `practical-prose-rubric.md` cites this as a Tone / Reader Respect contextual
+     modifier rather than a scored dimension.
+
+## Effective Communication
+
+1. **Respect the reader’s intelligence**
+
+   - Write for a reader that is *100% intelligent and 100% ignorant*. This respects the
+     reader yet provides enough context.
+   - Either explain concepts fully and from first principles or point them to where they
+     can learn the concept.
+   - Never dumb things down, be vague, or skip important technicalities or details.
+
+2. **Calibrate confidence**
+
+   - Never make a confident statement without citations or reasoning that justify the
+     confidence.
+   - Judgments are allowed but must be calibrated, considering evidence for and against.
+   - Do *not* aim to be agreeable; aim to be accurate when certain and explicit about
+     uncertainties.
+   - Do *not* make sweeping claims or use extravagant language.
+     Avoid words like “incontrovertibly,” “emphatically,” “definitively,”
+     “unequivocally,” “massive,” “monumental,” “profound,” “transformational,”
+     “seismic,” “paradigm-shifting,” “will revolutionize,” “structurally outmaneuvered,”
+     “successfully executing,” or “crushing it.”
+
+3. **Cut pompousness, meta-commentary, and unnecessary formality**
+
+   - Avoid “talking about talking,” such as narrating what a doc covers or instructing
+     readers on how to read a document.
+     Exception: standards, rubrics, runbooks, and other process documents may include
+     structural commentary (how dimensions map to rules, how to score, when to apply a
+     pass) when that commentary is what the document is *for*.
+   - Eliminate common but unnecessary phrases, such as “due to the fact” or “at this
+     point in time.” Avoid adverbs and general adjectives, such as “quickly respond” or
+     “very good.”
+   - Avoid pedantry, such as calling documents “canonical,” or giving justifications for
+     word choices. Jargon like “load-bearing” is acceptable when the audience uses it and
+     the term is genuinely descriptive (for example, a sentence-craft discussion citing
+     Gopen and Swan’s notion of *load-bearing constraints on sentence structure*); avoid
+     it as a filler intensifier in ordinary prose.
+   - Cut acronyms and jargon unless they serve a clear purpose.
+   - When technical terms or jargon are used, define them or reference their definition.
+
+## Formatting
+
+> Block quotes like this should be used for meta-instructions, quotes, and epigraphs.
+
+- **Boldface:** Use boldface for defining **key words** or concepts.
+- **Italics:** Use italics for *general emphasis*.
+- **Itemized lists:** Use bulleted lists whenever it aids with clarity.
+  Do not include full stops on each item for short lists and sentence fragments.
+  For lists with multiple sentences on each bullet (like this one), consistently use
+  full stops on all items.
+- **Inline headings:** Inline headings, where the heading is on the same line as a
+  paragraph of text, should be formatted like this, using a boldfaced colon.
+  Use this format consistently for inline headings within itemized lists.
+- **Em dashes:** Use em dashes *only* when they are the best punctuation for the
+  sentence. Prefer full stops, commas, colons, or semicolons as appropriate.
+  When you do use em dashes—like this—follow American style, without spaces around the
+  em dash.
+- **Conjunctions:** Write “and” rather than `+` or `&` in prose, list separators, and
+  cross-references. Reserve `+` and `&` for code, identifiers, and proper names where
+  they are part of the canonical form (for example, “Strunk & White”).
+- **Section headings:** Use Title Case (Chicago Manual of Style rules) for H1 `#` and H2
+  `##` headings (as in this document).
+  For H3 `###` and H4 `####`, title case is optional but should be applied consistently.
+
+### Auto-Formatting and Emojis
+
+> These two conventions are tbd extensions not yet in upstream practical-prose; see the
+> PR addendum proposing them upstream.
+
+- **Auto-formatting:** Always use auto-formatting on every file type that supports it.
+  Defer to the language- or format-specific rules for exact style.
+- **Emojis:** Do not use emojis gratuitously — only when they add clarity through a
+  consistent semantic vocabulary.
+  Use ✅ and ❌ for success and failure (or ✔︎ and ✘ if the codebase already uses them),
+  and ⚠️ and ‼️ for user-facing warnings and errors (or ∆ and ‼︎ to match an existing
+  codebase). You may use 📈 for reports and quantitative summaries, ⏰ for timings and
+  scheduling, and 🧪 for tests and experiments.
+  Apply whatever set you choose consistently.
+  Do not put emojis in code comments, where they add distraction without systematic
+  meaning.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/convex-limits-best-practices.md

@@ -2215,3 +2215,7 @@ constraints:
 | **10-50 KB** | Separate document or file storage | Use detail tables for on-demand fetch |
 | **50-900 KB** | **Must** use detail table or file storage | Approaching 1 MiB document limit |
 | **>900 KB** | **Must** use file storage with compression | Brotli compression for HTML/text (3:1 ratio) |
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/convex-rules.md

@@ -941,3 +941,7 @@ const mockAgentId = '12345;agents' as Id<'agents'>;  // OK - looks like real Con
    entirely
 
 3. **Test IDs should follow Convex format** - if test ids `'12345;tableName'` pattern
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/electron-app-development-patterns.md

@@ -835,3 +835,7 @@ Avoid `unsafe-eval` and `unsafe-inline`.
 
 - [Launchpad #1944468: Electron applications all crash upon launch](https://bugs.launchpad.net/bugs/1944468)
   — Ubuntu-specific Electron issues
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/error-handling-rules.md

@@ -561,3 +561,7 @@ grep -rn -A2 "} catch {" --include="*.ts" | grep -B1 "throw new"
 **Problematic patterns**:
 - `throw new CLIError('Failed to do X')` - Loses WHY it failed
 - `throw new Error('Operation failed')` - Generic message hides root cause
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-coding-rules.md

@@ -35,3 +35,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
   // Usage:
   const tradeCount = Math.min(trades.length, EXECUTION_STATS_LIMITS.maxTradeCount);
   ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-comment-rules.md

@@ -94,3 +94,7 @@ These are language-agnostic rules on comments:
   and at the top of files.
 
 - See language-specific comment rules for more details.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-eng-assistant-rules.md

@@ -53,3 +53,7 @@ Therefore:
   That is useless generalization.
   Instead, specifically say what you’ve done, e.g., “I’ve added types, including
   generics, to all the methods in `Foo` and fixed all linter errors.”
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-tdd-guidelines.md

@@ -145,3 +145,7 @@ Tests in the project are broken down into three types:
    Are not run on every commit as they can have costs or side effects or be slow.
    Requires all API keys.
    File names end with e2e.test.ts
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-testing-rules.md

@@ -25,3 +25,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 - Test edge cases and boundaries: Include tests for empty inputs, nulls, maximums,
   minimums, and error conditions—not just happy paths.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/golden-testing-guidelines.md

@@ -812,3 +812,7 @@ Golden session testing works well alongside other testing strategies:
 - ScalaTest Matchers: https://www.scalatest.org/user_guide/using_matchers
 
 - Concordion (Java): https://concordion.org/
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

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

@@ -90,9 +90,10 @@ The architecture prioritizes fast iteration during early development while maint
 clear path to split packages later without breaking changes.
 
 The recommended stack uses **pnpm workspaces** for dependency management, **tsdown** for
-building ESM/CJS dual outputs with TypeScript declarations, **Changesets** for
-versioning and release automation, **publint** for validating package publishability,
-and **lefthook** for fast local git hooks.
+building ESM/CJS dual outputs with TypeScript declarations, **Changesets**
+(multi-package monorepos) or **tag-triggered OIDC publishing** (single-package repos)
+for versioning and release automation, **publint** for validating package
+publishability, and **lefthook** for fast local git hooks.
 This approach supports private development via GitHub Packages or direct GitHub
 installs, with a seamless transition to public npm publishing when ready.
 
@@ -671,7 +672,8 @@ package. Essential for any published package.
 
 #### Changesets
 
-**Status**: Strongly Recommended
+**Status**: Recommended for multi-package monorepos (for a single published package,
+prefer the tag-triggered approach below)
 
 **Details**:
 
@@ -729,8 +731,10 @@ Changesets provides:
 
    - Publishes to npm when that PR is merged
 
-**Assessment**: Changesets is the de facto standard for monorepo versioning.
-It integrates seamlessly with pnpm and GitHub Actions.
+**Assessment**: Changesets is the de facto standard for *multi-package* monorepo
+versioning and integrates seamlessly with pnpm and GitHub Actions.
+For a repo that publishes a single package, its per-PR ceremony rarely pays off — prefer
+the tag-triggered approach below (see the LLM-era note).
 
 **References**:
 
@@ -759,6 +763,19 @@ No NPM_TOKEN needed, no “Version Packages” PR workflow.
 3. Commit, tag (e.g., `v1.2.3`), and push
 4. GitHub Action publishes automatically on tag push
 
+> **When to prefer this over Changesets (LLM-era note):** For a **single published
+> package**, Changesets’ main wins (multi-package coordination and per-PR changelog
+> accumulation) mostly evaporate, while its ceremony (a `.changeset/*.md` per PR, a
+> bump-type decision per PR, the `changeset version` step, a “Version Packages” PR)
+> stays. When releases are cut by an agent/maintainer who assembles notes from clean
+> conventional commits at release time (see a release-notes template), tag-triggered
+> publishing is simpler and has fewer moving parts: clean commits → bump + `## X.Y.Z`
+> CHANGELOG section → tag → auto-publish.
+> `tbd` itself uses this approach (project-local `docs/publishing.md` for the per-repo
+> playbook; the workflow itself is the GitHub Action triggered by the `v*` tag).
+> Keep Changesets when you publish several interdependent packages or want contributors
+> to declare intent in each PR.
+
 **One-time setup**:
 
 1. Publish package manually once: `npm publish --access public`
@@ -3554,3 +3571,7 @@ ncu --dep dev --format group
 # Upgrade with peer dependency handling
 ncu --target minor -u && pnpm install --force
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-cli-patterns.md

@@ -83,3 +83,7 @@ Use `uv-dynamic-versioning` for git-based versions:
 4. Separate handlers from command definitions for testability
 5. Use TypedDict or dataclasses for type-safe options
 6. Test with Typer’s CliRunner for isolated, fast tests
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-modern-guidelines.md

@@ -182,3 +182,33 @@ class MyThing:
 str(MyThing(file_path="/tmp/file.txt", title="Something " + "blah " * 50, url="https://www.example.com", body="..."))
 # -> "MyThing(title='Something blah blah blah blah blah blah blah blah blah blah blah…', file_path=/tmp/file.txt, url=https://www.example.com)"
 ```
+
+## Releasing (tag-triggered, no changesets)
+
+For publishing Python packages to PyPI, follow the
+[`simple-modern-uv`](https://github.com/jlevy/simple-modern-uv) template’s model — it is
+the standard for tbd’s Python projects.
+The same clean principles as the TypeScript guidance apply: no changesets, releases cut
+from clean conventional commits.
+
+- **Dynamic versioning from the git tag** via
+  [`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning) — the tag
+  *is* the version (no manual `version =` bump in `pyproject.toml`, no version commit).
+- **Release/tag-triggered publish**: a `publish.yml` workflow runs on
+  `on: release: types: [published]` (or a `v*` tag), builds with `uv build`, and
+  publishes with `uv publish --trusted-publishing always` — **PyPI Trusted Publishing
+  (OIDC), no API token**.
+- **Supply-chain cool-off in CI**: set `UV_EXCLUDE_NEWER` to a 14-days-ago cutoff so the
+  build never resolves a brand-new (potentially yanked/compromised) release.
+- **Release notes** are written per `release-notes-guidelines` from the commits since
+  the last tag — there is no per-PR changeset file.
+- Expose the version at runtime with `importlib.metadata.version("<pkg>")`.
+
+So a release is just: clean commits → create the GitHub release/tag `vX.Y.Z` → CI builds
+and publishes.
+See `template/docs/publishing.md` in `simple-modern-uv` for the first-time
+Trusted Publisher setup.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/python-rules.md

@@ -258,3 +258,7 @@ These are general rules that *must* be followed on this project for Python code.
 - Exported/public variables, functions, or methods SHOULD have concise docstrings.
   Internal/local variables, functions, and methods DO NOT need docstrings unless their
   purpose is not obvious.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/release-notes-guidelines.md

@@ -138,3 +138,7 @@ Before finalizing release notes:
 
 **Full commit history**: https://github.com/org/repo/compare/v0.1.12...v0.1.13
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/supply-chain-hardening.md

@@ -52,7 +52,7 @@ planned upgrade.
 | pnpm 11+ | `minimumReleaseAge: 20160` in `pnpm-workspace.yaml` (pnpm 11 ignores `NPM_CONFIG_*`; env prefix is `PNPM_CONFIG_*`) |
 | uv | `UV_EXCLUDE_NEWER="14 days"` |
 | pip 26.1+ | `PIP_UPLOADED_PRIOR_TO="P14D"` |
-| Cargo / Go | no native gate: commit the lockfile, pass `--locked` (Cargo) / keep `go.sum` + `-mod=readonly` (Go), and require human review before re-resolving; gate automated bumps with Renovate/Dependabot release-age policy |
+| Cargo / Go | no native gate: commit the lockfile, pass `--locked` (Cargo) / keep `go.sum` and `-mod=readonly` (Go), and require human review before re-resolving; gate automated bumps with Renovate/Dependabot release-age policy |
 
 At upgrade-decision time, `npm-check-updates --cooldown 14` (pin the `ncu` version)
 gates which upgrades are even offered.
@@ -75,8 +75,8 @@ To check one version’s age: `npm view <pkg> time.<ver>`.
 5. **Don’t update for its own sake.** The safest update is the one you skip — each bump
    is fresh attack surface.
    Bump only for a concrete reason ("show me the commit we need"); prefer fewer,
-   vendored/pinned dependencies; let audits + CVE monitoring tell you when a real update
-   is warranted.
+   vendored/pinned dependencies; let audits and CVE monitoring tell you when a real
+   update is warranted.
 6. **No unpinned zero-install runners.** Avoid `npx` / `pnpm dlx` / `bunx` / `uvx` /
    `go run <remote>` without an explicit `@version` pin and a review of the resolved
    `package@version` — they fetch and execute the latest code, bypassing the cool-off.
@@ -208,10 +208,10 @@ Reviewed <date>.`
 
 ## What This Does and Doesn’t Cover
 
-A cool-off + disabled scripts neutralizes the dominant **fast-yanked-incident** pattern.
-It does **not** stop: long-lived typosquats that survive past the window; a lockfile
-that already captured a bad version; payloads that fire on import/build rather than
-install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
+A cool-off plus disabled scripts neutralizes the dominant **fast-yanked-incident**
+pattern. It does **not** stop: long-lived typosquats that survive past the window; a
+lockfile that already captured a bad version; payloads that fire on import/build rather
+than install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
 legitimate CI with a forged “verified” provenance badge — a green badge is not proof).
 Those need lockfile review, typosquat checks, build-time controls, and — if you publish
 packages — the publish-side controls in the guidebook’s `hardening-ci-cd.md` (OIDC
@@ -235,3 +235,7 @@ provenance monitoring).
   StepSecurity, Socket, Unit 42).
 - Monorepo enforcement: `tbd guidelines pnpm-monorepo-patterns`,
   `tbd guidelines bun-monorepo-patterns`.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/tbd-sync-troubleshooting.md

@@ -163,7 +163,8 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 - Conflicting changes at field level
 
 **Solutions:**
-1. Check attic for conflict details: `ls .tbd/data-sync-worktree/.tbd/data-sync/attic/`
+1. Check attic for conflict details:
+   `ls "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree/.tbd/data-sync/attic/"`
 2. Review conflict files to understand what was lost
 3. Manually merge if needed
 4. Re-import with fresh workspace if appropriate
@@ -195,7 +196,7 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 1. Run `tbd doctor --fix` to auto-repair
 2. If that fails, manually repair:
    ```bash
-   rm -rf .tbd/data-sync-worktree
+   rm -rf "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree"
    git worktree prune
    tbd doctor --fix
    ```
@@ -204,7 +205,8 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 ### Worktree shows “detached HEAD”
 
 **Symptoms:**
-- `git -C .tbd/data-sync-worktree status` shows detached HEAD
+- `git -C "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree" status`
+  shows detached HEAD
 - Commits not going to tbd-sync branch
 
 **Solutions:**
@@ -224,7 +226,7 @@ tbd sync --status
 tbd workspace list
 
 # View worktree branch
-git -C .tbd/data-sync-worktree branch
+git -C "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree" branch
 
 # Compare local vs remote
 git log tbd-sync --oneline -5
@@ -258,3 +260,7 @@ tbd sync
 - `--no-outbox`: Skip automatic import from outbox on success
 
 See `tbd shortcut sync-failure-recovery` for the full workflow.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/typescript-cli-tool-rules.md

@@ -7,17 +7,17 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: Commander.js `^15.0.0` (ESM-only, requires Node v22.12.0+),
-picocolors `^1.1.1` (stable; no recent changes), Node.js 24 LTS / Node 26 Current.
+**Tracks**: Commander.js `^15.0.0` (ESM-only, requires Node v22.12.0+), picocolors
+`^1.1.1` (stable; no recent changes), Node.js 24 LTS / Node 26 Current.
 Commander 14 moves to security-only maintenance until May 2027.
 
 **Related**:
 
 - [TypeScript Rules](./typescript-rules.md)
 - [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  follow the 14-day package-age rule for every CLI dependency. Bundlers and
-  CLI dependencies that execute at install time (`postinstall` scripts) are a
-  primary attack surface.
+  follow the 14-day package-age rule for every CLI dependency.
+  Bundlers and CLI dependencies that execute at install time (`postinstall` scripts) are
+  a primary attack surface.
 
 These rules apply to all CLI tools, command-line scripts, and terminal utilities.
 Examples may be inspired by modern TypeScript repos, but guidance here is intentionally
@@ -107,9 +107,9 @@ generic and reusable across projects.
 ## Commander.js Patterns
 
 - **Use Commander.js for all CLI tools:** Import from `commander` and follow established
-  patterns for command registration and option handling. **Target Commander 15+
-  (ESM-only, requires Node v22.12.0+).** Commander 14 is security-maintenance
-  only until May 2027; do not start new projects on it.
+  patterns for command registration and option handling.
+  **Target Commander 15+ (ESM-only, requires Node v22.12.0+).** Commander 14 is
+  security-maintenance only until May 2027; do not start new projects on it.
 
 - **Apply colored help globally, not per-command:** Use Commander v14+ `configureHelp()`
   with style functions, applied recursively to all commands at program initialization.
@@ -565,30 +565,29 @@ When supporting environment variables, especially those used by SDK libraries (l
 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.), also support `.env` loading so CLIs work
 seamlessly in local dev and in remote environments.
 
-- **Prefer Node.js native `--env-file` for Node ≥20.6**: Production-ready on
-  Node 24 LTS. Pass `--env-file=.env.local --env-file=.env` on the CLI
-  invocation; later files do not override earlier ones, so list higher-priority
-  first. No dependency required:
+- **Prefer Node.js native `--env-file` for Node ≥20.6**: Production-ready on Node 24
+  LTS. Pass `--env-file=.env.local --env-file=.env` on the CLI invocation; later files
+  do not override earlier ones, so list higher-priority first.
+  No dependency required:
 
   ```bash
   node --env-file=.env.local --env-file=.env ./dist/bin.js
   ```
 
-  Make this the default for new projects. Reserve `dotenv` for advanced needs
-  (variable expansion, multiline values, custom precedence logic, or runtime
-  conditional loading from inside the CLI).
+  Make this the default for new projects.
+  Reserve `dotenv` for advanced needs (variable expansion, multiline values, custom
+  precedence logic, or runtime conditional loading from inside the CLI).
 
-- **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load
-  env files programmatically — e.g., it reads them after parsing command-line
-  flags, performs variable expansion, or supports custom file paths the user
-  cannot pre-bake into the `node` invocation.
+- **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load env files
+  programmatically — e.g., it reads them after parsing command-line flags, performs
+  variable expansion, or supports custom file paths the user cannot pre-bake into the
+  `node` invocation.
 
-- **Load `.env.local` and `.env` automatically (recommended):** Whichever
-  mechanism you use, support both `.env.local` (higher priority, gitignored)
-  and `.env` (lower priority, committed defaults only).
+- **Load `.env.local` and `.env` automatically (recommended):** Whichever mechanism you
+  use, support both `.env.local` (higher priority, gitignored) and `.env` (lower
+  priority, committed defaults only).
 
-- **Manual `dotenv` loading:** When you do need `dotenv`, load with explicit
-  precedence:
+- **Manual `dotenv` loading:** When you do need `dotenv`, load with explicit precedence:
 
   ```ts
   import dotenv from 'dotenv';
@@ -739,3 +738,7 @@ runtimes, Cloudflare Workers, etc.).
 
 - **Make scripts composable:** Design scripts to work well in pipelines and automation.
   Consider how they’ll be used in CI/CD and shell scripts.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->