get-tbd 0.1.30 → 0.2.0

package/dist/docs/guidelines/cli-agent-skill-patterns.md

@@ -104,15 +104,15 @@ So:
 
 - **Prompt/instructions only** → ship a `SKILL.md`. (§3, §4)
 - **Project-wide conventions** (build/test/style) → add an `AGENTS.md`. (§2)
-- **You have a CLI** → `SKILL.md` + agent-friendly `--json` CLI. (§0.2, §6)
+- **You have a CLI** → `SKILL.md` and an agent-friendly `--json` CLI. (§0.2, §6)
 - **Many subcommands / a knowledge library** → CLI-as-skill meta-pattern.
   (§6)
 - **A service with no CLI, or you need OAuth / multi-tenant / audit** → MCP server.
   (§7)
-- **Maximum reach across many agents** → layer them: AGENTS.md + SKILL.md + CLI + MCP.
+- **Maximum reach across many agents** → layer them: AGENTS.md, SKILL.md, CLI, and MCP.
   (§1)
 - **Self-installs into agents & ships evolving skills?** → that is the advanced Tier 2
-  pattern (self-upgrade + format versioning); most tools are Tier 1: a pure skill run
+  pattern (self-upgrade and format versioning); most tools are Tier 1: a pure skill run
   via a **pinned** `npx`/`uvx`. (§6.0)
 
 Everything below is reference material.
@@ -136,7 +136,7 @@ or capability.
 | 5. Per-agent polish | `.cursor/rules/*.mdc`, plugin packaging, ACP, etc. | Glob-scoped activation, enterprise distribution, editor discovery | Per-agent |
 
 **Recommended default for a tool author who wants broad reach**: ship an `AGENTS.md`
-snippet (universal baseline) + a `SKILL.md` (portable capability) + an agent-friendly
+snippet (universal baseline), a `SKILL.md` (portable capability), and an agent-friendly
 CLI. Add an MCP server only when a CLI can’t serve the need.
 Add agent-specific files last, and only where they buy something.
 
@@ -204,8 +204,8 @@ current ones. Only the `format=fNN` value changes when the block’s shape chang
 
 ## 3. The Agent Skills Standard (SKILL.md)
 
-**What it is**: a folder with a `SKILL.md` file (YAML frontmatter + Markdown body), plus
-optional supporting files.
+**What it is**: a folder with a `SKILL.md` file (YAML frontmatter and a Markdown body),
+plus optional supporting files.
 Created by Anthropic (Dec 2025), published under Apache 2.0 at
 [agentskills.io](https://agentskills.io).
 280,000+ public skills exist as of early 2026.
@@ -318,8 +318,8 @@ Earlier guidance cited a flat ~15K-character budget.
 - The skill listing gets a budget of **~1% of the model’s context window** by default
   (`skillListingBudgetFraction`, default `0.01`). When it overflows, the
   least-recently-invoked skills lose their descriptions first.
-- Per-skill listing text (`description` + `when_to_use`) is truncated at **1,536 chars**
-  (`maxSkillDescriptionChars`).
+- Per-skill listing text (`description` and `when_to_use`) is truncated at **1,536
+  chars** (`maxSkillDescriptionChars`).
 - `SLASH_COMMAND_TOOL_CHAR_BUDGET` overrides the fraction with a fixed character count.
 - `skillOverrides` can set any skill to `on` / `name-only` / `user-invocable-only` /
   `off` without editing the file; `/doctor` reports overflow.
@@ -399,14 +399,14 @@ Verified against the Codex source (`codex-rs/core-skills/src/loader.rs`, tags
 `<dir>/.agents/skills/` from the project root down to cwd), `User`
 (`$HOME/.agents/skills/`), `Admin`, plus plugin roots and `$CODEX_HOME/skills`. So a
 **plain repo-root `.agents/skills/<name>/SKILL.md` is read directly**, no manifest
-required. (The repo path is built by joining `.agents` + `skills` at runtime, so it does
-*not* appear as a contiguous `.agents/skills` literal in the binary — a `strings`-based
-inspection will miss it and see only `.agents/plugins/marketplace.json`; confirm against
-the source, not binary strings.)
-**Plugins** are an *additional* distribution layer (installable units bundling skills +
-MCP servers — 90+ ship with Codex), declared in `.agents/plugins/marketplace.json` (also
-reads `.claude-plugin/marketplace.json`) — useful for *publishing a bundle*, but not
-needed to make a repo-local skill load.
+required. (The repo path is built by joining `.agents` and `skills` at runtime, so it
+does *not* appear as a contiguous `.agents/skills` literal in the binary — a
+`strings`-based inspection will miss it and see only `.agents/plugins/marketplace.json`;
+confirm against the source, not binary strings.)
+**Plugins** are an *additional* distribution layer (installable units bundling skills
+and MCP servers — 90+ ship with Codex), declared in `.agents/plugins/marketplace.json`
+(also reads `.claude-plugin/marketplace.json`) — useful for *publishing a bundle*, but
+not needed to make a repo-local skill load.
 Codex skills may carry a richer **`agents/openai.yaml`** companion (e.g.
 `interface.display_name`, icons, `dependencies.tools[]`,
 `policy.allow_implicit_invocation`); map the portable
@@ -431,7 +431,7 @@ sandboxed.
 This is the pattern for a richer tool: a CLI that is itself a skill, exposing many
 capabilities as subcommands while costing a single description slot.
 `tbd` is the reference implementation; **Beads/`bd`** (Steve Yegge), `tbd`’s lineage,
-follows the same shape (subcommands + `AGENTS.md` + `--json` + an optional MCP server).
+follows the same shape (subcommands, `AGENTS.md`, `--json`, and an optional MCP server).
 
 Use this when you have many capabilities, need cross-session state, or want a curated
 knowledge library the agent pulls from.
@@ -550,8 +550,8 @@ Rules: reference commands **explicitly** (`mycli command arg`, never “see the
 - **Actionable errors** that include the next command to run.
 - **Discoverable help**: an `IMPORTANT:` epilog pointing at a context-restore command
   (e.g., `mycli prime`), and a “Getting Started” one-liner.
-- **A `prime` command** (dashboard + status + rules) for session start and post-compact,
-  distinct from `skill` (pure documentation).
+- **A `prime` command** (dashboard, status, and rules) for session start and
+  post-compact, distinct from `skill` (pure documentation).
 
 ### 6.6 Distribution & multi-agent install
 
@@ -621,14 +621,14 @@ project needs both.
 - **Fully generated install artifacts** (`.agents/skills/<tool>/SKILL.md`,
   `.claude/skills/<tool>/SKILL.md`, generated hook scripts, and the like): CLI-owned;
   mark them “DO NOT EDIT.” Pick **one of two modes** and be consistent:
-  - **Commit + dogfood** (what `tbd` does): check the generated artifacts in, and add a
-    **drift test** that regenerates them and fails if they differ.
+  - **Commit and dogfood** (what `tbd` does): check the generated artifacts in, and add
+    a **drift test** that regenerates them and fails if they differ.
     Pros: browsable on GitHub / skills.sh, the repo demonstrates its own output,
     reviewers see changes.
     Con: a regeneration shows up as a diff to commit.
     Keep generated output deterministic and formatter-stable (below) or the drift
     test/commits will churn.
-  - **Gitignore + regenerate** (what `metaproc` does): add `.../skills/*/SKILL.md` to
+  - **Gitignore and regenerate** (what `metaproc` does): add `.../skills/*/SKILL.md` to
     `.gitignore` and let `setup`/`--install` (re)create them on demand.
     Pros: zero commit churn, no drift to guard.
     Con: not browsable in the repo, and no committed artifact to diff in review.
@@ -732,7 +732,7 @@ The clean implementation is the host language’s plugin mechanism:
 
 Keep each registered skill a **spec** (name, two-part description, `allowed-tools`, a
 baseline source, and an optional dynamic catalog function) and run them all through the
-**same** `compose` + `--install` path, so every skill — first-party or third-party —
+**same** `compose` and `--install` path, so every skill — first-party or third-party —
 gets identical frontmatter, the `DO NOT EDIT`/format marker, and deterministic output.
 This keeps the “one tool, many self-injecting commands” model open for extension without
 the core tool taking a dependency on every plugin.
@@ -810,8 +810,8 @@ See `tbd guidelines supply-chain-hardening` for the cross-ecosystem policy.
   `uv tool install` / `pipx install`. `uvx` reuses a persistent install if one exists.
 - **Go**: `go run <module>@<ver>` (compiles on the fly) or `go install`.
 - **Rust**: no first-class zero-install runner — ship **prebuilt binaries** (GitHub
-  releases + a `curl … | sh` installer) or `cargo binstall`; `cargo install` compiles.
-- **Cross-language**: a prebuilt binary + install script, or a container image (Docker
+  releases and a `curl … | sh` installer) or `cargo binstall`; `cargo install` compiles.
+- **Cross-language**: a prebuilt binary and install script, or a container image (Docker
   is emerging as the production-grade distribution for MCP servers).
 
 This mirrors how the ecosystem ships agent tooling today: **MCP servers** are most often
@@ -821,7 +821,7 @@ configs; **CLIs** like Beads offer `brew` / `npm -g` / `curl` installers, while
 
 **Recommendation**: default the skill to a **pinned zero-install invocation**
 (`uvx`/`npx <pkg>@<version>`) for maximum reach across ephemeral and cloud agents; offer
-**global install + a `SessionStart` bootstrap** as the optimization for persistent
+**global install and a `SessionStart` bootstrap** as the optimization for persistent
 environments where the project wants lockfile-managed versions and warm-start speed.
 
 ### 6.8 Publishing & discovery — make the skill installable
@@ -832,15 +832,15 @@ and the ecosystem finds it.
 The landscape worth targeting:
 
 - **`skills.sh` / `npx skills add <owner/repo>`** (Vercel) — the cross-agent “npm for
-  skills”: one command installs into `.agents/skills/` + symlinks per agent (Claude
+  skills”: one command installs into `.agents/skills/` and symlinks per agent (Claude
   Code, Codex, Cursor, Copilot, Gemini, …). No review; ranked by install telemetry.
   **This is the highest-leverage target** and needs zero extra infra.
 - **GitHub-scraping indexers** (SkillsMP ~800k skills, ClaudeSkills.info, LobeHub,
   claudemarketplaces.com) — auto-list public repos that contain a `SKILL.md` (often
-  gated on ≥2 stars). You get listed for free just by being public + discoverable.
+  gated on ≥2 stars). You get listed for free just by being public and discoverable.
 - **Plugin marketplaces** — `.claude-plugin/marketplace.json` (Claude Code, the official
   Anthropic channel) and `.agents/plugins/marketplace.json` (Codex; Codex reads both).
-  These are *plugin* channels: bundles of skills + MCP + hooks + commands.
+  These are *plugin* channels: bundles of skills, MCP servers, hooks, and commands.
   They are **only for publishing a bundle** — a repo-local skill already loads from
   `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex) **without any
   manifest**, so don’t add one just to be discovered.
@@ -873,10 +873,10 @@ itself. Generate this distribution `SKILL.md` from the same source as your in-re
 pushing.
 
 `tbd` does exactly this: `skills/tbd/SKILL.md` is generated at build time from the same
-baseline, carries `name: tbd` + a trigger-rich description, and opens with the
-`npm install -g get-tbd` + `tbd setup --auto` bootstrap — so `npx skills add jlevy/tbd`
-gives an agent a working landing page, and `tbd setup` then upgrades it to the full
-multi-agent install (§6.6).
+baseline, carries `name: tbd` and a trigger-rich description, and opens with the
+`npm install -g get-tbd` and `tbd setup --auto` bootstrap — so
+`npx skills add jlevy/tbd` gives an agent a working landing page, and `tbd setup` then
+upgrades it to the full multi-agent install (§6.6).
 
 * * *
 
@@ -1007,7 +1007,7 @@ going:
 - **Codex App-Server** — JSON-RPC (Thread/Turn/Item) decoupling Codex logic from client
   surfaces; relevant only for Codex-specific integration surfaces.
 - **Plugin marketplaces & `npx skills`** — distribution is consolidating: Claude Code
-  plugin marketplaces (official + community), Codex plugins, and Vercel’s
+  plugin marketplaces (official and community), Codex plugins, and Vercel’s
   `npx skills add` over the skills.sh directory (cross-agent symlinks).
 - **Routines / scheduled agents, background monitors, `/run` & `/verify` skills** —
   newer Claude Code capabilities for autonomous, event-triggered, and app-verifying
@@ -1174,3 +1174,7 @@ going:
 - Supply-chain / dependency currency: `tbd guidelines bun-monorepo-patterns` or
   `pnpm-monorepo-patterns`
 - Testing: `tbd guidelines general-testing-rules`
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/commit-conventions.md

@@ -77,3 +77,7 @@ ops: Update issue status for auth feature
 ops: Sync beads with remote
 process: Add TDD guidelines for agent workflows
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

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.
+-->