docs-refresh

# /docs-refresh Refresh this repo's top-level catalog docs so the stated plugin/skill/agent counts and the plugin set match what is actually on disk. The detector is `scripts/check-docs-index.sh`; this skill is the *fixer* that consumes its report. ## When to Use This Skill | Use this skill when... | Use something else when... | |------------------------|----------------------------| | Per-plugin counts in the README headline / PLUGIN-MAP / the d2 diagram drifted | A plugin needs adding/removing — follow `/plugin-authoring` § Plugin Lifecycle first, then run this | | `check-docs-index.sh` reports `doc_count_drift` / `diagram_count_drift` / `diagram_svg_stale` / `readme_row_dangling` | You need a generic project's docs synced — that's `documentation-plugin:docs-sync` (wrong layout for this repo) | | The PR gate `Check docs-index drift` failed in CI | Editing rule-index or marketplace set — the audit reports those, but fix them at their source | ## Context - Audit: !`bash scripts/check-docs-index.sh` - README last touched: !`git log --max-count=1 --format='%h %ci' -- README.md` ## Execution Execute this refresh: ### Step 1: Read the drift Run `bash scripts/check-docs-index.sh` (shown in Context). Each `ISSUES:` line names the exact file, line, and the disk-vs-stated count. `STATUS=OK` with `ISSUE_COUNT=0` means nothing to do — stop and report clean. ### Step 2: Apply count fixes For every `doc_count_drift` / `diagram_count_drift` issue, Edit the stated count to the disk count: - `docs/CATALOG.md` — never hand-edited; `just catalog` regenerates it from `marketplace.json` and the plugin dirs (CI: `Check catalog is current`). - `docs/PLUGIN-MAP.md` — the `| <plugin> | N | ... |` tier-table rows. - `docs/diagrams/plugin-relationships.d2` — the `label: "<name>\nN skills"` node labels. The `.svg` is generated and never hand-edited; re-render it in Step 4. ### Step 2b: Apply name-level fixes Two ERROR-severity issue types are *name* drift, not count drift — no `/docs-refresh` arithmetic repairs them: | Issue type | What it means | Fix | |---|---|---| | `diagram_svg_stale` / `diagram_svg_node_missing` | The committed `.svg` renders a per-plugin label the `.d2` no longer states | Re-render (Step 4). Never hand-edit the `.svg` to agree — Check 6 compares label text only and cannot tell a hand-patch from a render | | `readme_row_dangling` | A plugin README row advertises `/<ns>:<name>` with no matching skill directory | Delete the row if the skill never existed, or correct it to the real invocation path. Resolution is exact, so a row that is a *shorthand* for a longer directory is a real finding — fix the row, not the check | ### Step 3: Light content pass 1. `git log --oneline <README-last-touched-sha>..HEAD -- '*/.claude-plugin/plugin.json'` — if any **new** `*-plugin` directory landed, it must be added to PLUGIN-MAP, marketplace.json (which `just catalog` reads), and release config (see `/plugin-authoring` § Plugin Lifecycle). Surface this rather than guessing a category. 2. Update the rounded total in README's intro line (`NNN+ skills`) to the next round number at or below `TOTAL_SKILLS` from the audit. ### Step 4: Re-render the diagram If the d2 changed: `d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg`. Commit the `.d2` and `.svg` together — **always in the same commit**. Check 6 is ERROR severity, so a `.d2` edit pushed without its re-rendered `.svg` fails the always-on `Check docs-index drift` gate; that is deliberate (#2453, where the `.svg` sat stale behind `STATUS=OK`). If `d2` is not installed, install it rather than hand-editing the `.svg`: ```bash curl -fsSL https://d2lang.com/install.sh -o /tmp/d2-install.sh # read /tmp/d2-install.sh, then: sh /tmp/d2-install.sh ``` Download-review-run, not `curl … | sh` — the piped form is blocked by this repo's own `hooks-plugin/hooks/bash-antipatterns.sh` safety rule, so a skill that prescribed it would dead-end the agent it was guiding. Pin the version the committed `.svg` was rendered with — read it off the file's own `data-d2-version="..."` attribute — so the diff is the label change and not a whole-file renderer churn. ### Step 5: Verify and commit 1. `bash scripts/check-docs-index.sh --strict` must exit 0 (`STATUS=OK`). `DIAGRAM_SVG_NODES` should equal `DIAGRAM_NODES` — a smaller number means the `.svg` is missing nodes the `.d2` declares. 2. Commit as `docs: refresh plugin catalog counts` (the `docs:` type triggers no release bump). Stage only the catalog files you touched — never `git add -A`. ## Post-actions Report the before/after counts and confirm the audit is clean. The PR gate (`Check docs-index drift` in `plugin-pr-checks.yml`) will re-verify on push.