Add audience tag in claude.md

Author: kdeldycke

.claude/agents/grunt-qa.md

@@ -25,9 +25,9 @@ Work beyond the local repository: check issues, PRs, and CI runs on GitHub. Fix
 
 1. **`CLAUDE.md` compliance** — Read it, then grep the codebase for violations. Fix all of: typos, grammar, stale references, ordering violations, style issues, documentation sync issues. Remove discoverable content per `CLAUDE.md` § Keeping `claude.md` lean.
 2. **CLI health** — Run every subcommand's `--help`; fix docs if output diverges
-3. **Documentation sync** — Per `CLAUDE.md` § Documentation sync
+3. **Documentation sync** — Inside `kdeldycke/repomatic` only, per `CLAUDE.md` § Documentation sync (upstream maintainers). Skip it elsewhere: the section is upstream-only and never reaches a downstream `claude.md`.
 4. **Quality checks** — Per `CLAUDE.md` § Testing guidelines and § Linting and formatting; fix simple issues, escalate complex ones
-5. **Release alignment** — Per `CLAUDE.md` § Release checklist
+5. **Release alignment** — Inside `kdeldycke/repomatic` only, per `CLAUDE.md` § Release checklist (upstream maintainers). Downstream repos follow their own release process.
 6. **CI/CD failures** — Review recent failed runs, distinguish systematic from one-off
 7. **Workflow CLI references** — Verify all `repomatic` invocations in workflows use valid subcommands and flags
 

.claude/agents/sphinx-docs.md

@@ -527,7 +527,7 @@ Hand-written, but with a strict structure that downstream projects should mirror
 
 3. **Try it** tab-set with three tabs: `Latest release`, `Specific version`, `Development version`. The Latest release tab pairs the `uvx` command with a `{click:run}` block rendering live `--help` so visitors can preview the CLI without opening a terminal. The other two tabs stay as `shell-session` because they're about how to invoke `uvx`, not what the help looks like. An optional fourth `Local version` tab (`uvx --from file:///path/to/checkout -- <cli>`) helps maintainers exercise a working tree; it stays `shell-session` too.
 
-4. **Install methods** tab-set with one tab per package manager that actually distributes the package. Order: `uv`, `pip`, `pipx`, then everything else alphabetized (Arch Linux, Homebrew, Nix, etc.). Each tab leads with a one-sentence pointer to the upstream installer's docs and shows a single install command. Per `CLAUDE.md` § Prefer `uv` over `pip`, `uv tool install` (or `uv pip install`) is the primary command; alternative installers may appear as secondary options but never replace `uv` as the default. If a project ships extras, render them as a `{list-table}` only when there are 3 or more — for 1-2 extras, an inline `uv pip install pkg[extra]` line is clearer.
+4. **Install methods** tab-set with one tab per package manager that actually distributes the package. Order: `uv`, `pip`, `pipx`, then everything else alphabetized (Arch Linux, Homebrew, Nix, etc.). Each tab leads with a one-sentence pointer to the upstream installer's docs and shows a single install command. Per `CLAUDE.md` § Prefer `uv` over `pip` in documentation, `uv tool install` (or `uv pip install`) is the primary command; alternative installers may appear as secondary options but never replace `uv` as the default. If a project ships extras, render them as a `{list-table}` only when there are 3 or more — for 1-2 extras, an inline `uv pip install pkg[extra]` line is clearer.
 
    **Repology is the source of truth for which tabs exist.** Before adding, removing, or refreshing tabs:
 

.claude/skills/repomatic-ship/SKILL.md

@@ -70,7 +70,7 @@ The three substance passes own disjoint lanes (code owns Python including docstr
 2. **Docs**: an `Agent` that verifies prose docs against current behavior, not the journey (version references, CLI output, removed or renamed features go stale every cycle). Its constraints:
 
    - Manually-maintained version examples (install commands, binary download URLs, `uses:` refs) track the latest *released* tag, never the version being prepared, because the docs site deploys on every push to `main`. "Manually-maintained" is the load-bearing word and it is not a synonym for "under `docs/`": the freeze reaches into that tree in at least one repo (the canonical one rewrites `docs/install.md`), so decide file by file from the freeze's actual scope per the next bullet, never from the path. The tracking runs both ways: advance a sample that *lags* the released tag (still at N-1 after release N published) up to it, applying the bump directly rather than deferring it as a version advisory; only bumping a sample forward to the not-yet-released version is off-limits. A stale sample hides in plain sight, so grep every version string in `docs/` and `readme.md` rather than trusting a sub-agent's list.
-   - What the freeze rewrites varies by repo (the canonical repo pins workflow refs and CLI invocations; a downstream freeze may touch only `changelog.md`, `citation.cff`, `__init__.py`, and `pyproject.toml`). Read the last freeze commit's file list (`git show <last-freeze-sha> --stat`) and treat every version sample outside it, `readme.md` quick-start output included, as hand-maintained tracking the released tag: samples presumed freeze-managed have shipped stale through a release. On a cycle that migrated the release tooling itself, the historical freeze under-predicts the new one (a pre-repomatic freeze touching only `changelog.md` says nothing about the repomatic freeze, which also rewrites `citation.cff`, `__init__.py`, and `pyproject.toml`): treat every version sample as hand-maintained until the regenerated release PR's diff shows the new freeze's actual scope.
+   - What the freeze rewrites varies by repo (the canonical repo pins workflow refs and CLI invocations; a downstream freeze may touch only `changelog.md`, `citation.cff`, `__init__.py`, and `pyproject.toml`). Read the last freeze commit's actual diff (`git show <last-freeze-sha>`, never just `--stat`) and treat every version sample it does not rewrite, `readme.md` quick-start output included, as hand-maintained tracking the released tag: samples presumed freeze-managed have shipped stale through a release. **Freeze-management is per line, not per file**, and a file list is exactly the wrong granularity to decide it: a file the freeze touches can still carry hand-maintained samples it never rewrites, so `--stat` clears the whole file and the stale ones survive. The archetype: `docs/install.md` sits in the freeze commit, which rewrites precisely one line of it (the `uvx <cli>@X.Y.Z` pin), while the `>>> <pkg>.__version__` REPL capture further down the same page is hand-maintained and had been a full release behind since the previous cycle. Settle each sample individually with `git log -S '<the literal string>' -- <file>`, which shows whether a freeze commit or a human last moved it. On a cycle that migrated the release tooling itself, the historical freeze under-predicts the new one (a pre-repomatic freeze touching only `changelog.md` says nothing about the repomatic freeze, which also rewrites `citation.cff`, `__init__.py`, and `pyproject.toml`): treat every version sample as hand-maintained until the regenerated release PR's diff shows the new freeze's actual scope.
    - The mirror of the hand-maintained rule: a freeze-managed field legitimately shows the *dev* version between releases, so never flag one as stale against the released tag or as a dead link. `pyproject.toml`'s `urls.Download` reading `.../releases/tag/vX.Y.Z.devN` (a tag that has no GitHub release yet) is the expected post-bump state that the freeze rewrites to the release tag at cut. Hand-maintained samples track the *released* tag while freeze-managed fields track the *dev* version, so classify a version string by which mechanism owns it before judging it stale.
    - A third owner sits beside hand-maintained and freeze-managed: artifacts regenerated by `_release-engine.yaml`'s `update-dep-graph` job, whose `if:` gates on `release_commits_matrix`, so it fires **only on release commits** (never on ordinary pushes, to avoid noise from transitive dependency churn). It sits in the release engine rather than `autofix.yaml` because a release push is its only firing moment, and that is exactly the push `autofix.yaml` now skips wholesale, so do not go looking for it there. `docs/assets/dependencies.mmd` therefore lags `pyproject.toml` for the whole cycle: a runtime dependency added since the last release is *expected* to be missing from it, and the graph catches up through its own PR once the release lands. Never hand-forge the file, and never run `<cmd> update-dep-graph` to "fix" it mid-sweep: a local run uses whatever repomatic version the sweep resolved rather than the version the job pins, so it produces churn the next regeneration reverts. Classify a stale-looking generated artifact by the job that owns it before reporting it as drift.
    - Executable doc blocks fail open: a `{click:run}` invocation that no longer parses renders the usage error into the published page instead of failing the build (`docs.yaml` stayed green while a stale option printed `No such option`; only `click:tree` and `click:config` hard-error). Verify each `{click:run}` invocation against the current CLI, or grep the built HTML for `Error: No such option`-class output.
@@ -196,7 +196,7 @@ Spawn `Agent`, named so it stays addressable, on the `sonnet` model to run `/bab
 
 - When binaries are enabled, babysit's "every stable job passes" never covers them: its early exit declares success once the fast platforms are green, while macOS and the entire `release.yaml` matrix still build. Independently confirm the `release.yaml` run reached a terminal green state (`gh run watch <release-run-id>`, then read its `conclusion`); never infer the Nuitka result from babysit's summary. If a binary build fails, re-spawn babysit or fix inline.
 
-- A green `conclusion` also proves nothing on a HEAD that touched no Python source: `release.yaml` skips the entire `compile-binaries` matrix on such pushes (workflow-only, docs-only). Read the run's *jobs* and confirm the per-platform build and test jobs ran rather than skipped; when they skipped, the authoritative binary signal is the last run that actually compiled, valid only while its source tree matches the release tree. When no compiled run matches the release tree (a binary-relevant commit's run cancelled by supersession, then the reconciliation HEAD content-skipped the matrix), you *may* dispatch one: `gh workflow run release.yaml --ref main`. A dispatch carries no push diff for the skip heuristic to read, so it compiles and self-tests the full per-platform matrix on the current tree, with no commit and no PR churn.
+- A green `conclusion` also proves nothing on a HEAD that touched no Python source: `release.yaml` skips the entire `compile-binaries` matrix on such pushes (workflow-only, docs-only). Read the run's *jobs* and confirm the per-platform build and test jobs ran rather than skipped; when they skipped, the authoritative binary signal is the last run that actually compiled, valid only while its source tree matches the release tree. **Tell a wholesale skip from individually-filtered cells by whether the job name expanded.** The two are indistinguishable in any status count — both read as "N success, M skipped" — and they mean opposite things: filtered cells are the expected `nuitka.dev-targets` canary behavior, while an unevaluated matrix means *zero* binaries were built. The tell is the job name itself. A matrix that expanded yields named cells (`✅ ubuntu-26.04, abc1234 build`); a matrix that never evaluated leaves the raw template verbatim (`${{ (((matrix.state == 'stable') && '✅') || '⁉️') }} ${{ matrix.os }}, ${{ matrix.short_sha }} build`). Unexpanded `${{ }}` in a job name always means the stage never ran. This misreads silently and expensively: a sub-agent reported a content-skipped matrix as "dev-canary subset built, rest correctly skipped" twice in one run, which would have shipped a release whose binaries no CI job ever compiled. When no compiled run matches the release tree (a binary-relevant commit's run cancelled by supersession, then the reconciliation HEAD content-skipped the matrix), you *may* dispatch one: `gh workflow run release.yaml --ref main`. A dispatch carries no push diff for the skip heuristic to read, so it compiles and self-tests the full per-platform matrix on the current tree, with no commit and no PR churn.
 
   **That dispatch is information, never a gate, and on a busy pool it is often the wrong call.** `claude.md` § A published release freezes what is missing from it is explicit that shipping short is intended behavior and that you never hold a release or sit on a draft waiting for a build cell, so a missing binary signal must not delay a merge that is otherwise green. Three things make the wait even less attractive than that rule alone suggests: a skipped matrix is the *normal* steady state here rather than a new gap, since ordinary pushes routinely fall outside `binary_affecting_paths` and supersession cancels the rest; the wheel and sdist that PyPI actually ships are built by `📦 Build package`, which involves no Nuitka at all, so package distribution is already verified without it; and merging triggers the release commit's own full-fleet build, which a pre-merge dispatch then **competes with for runners**, slowing the build that produces the real assets. So weigh the dispatch against the source delta since the last compile: a new dataclass field or a bumped version literal does not earn a 40-90-minute fleet build, while a dependency swap, a packaging change or a new native import does. **When you dispatch and then decide to merge anyway, cancel the dispatch first** so it stops taxing the release it was meant to protect.