| name | update-docs |
| description | Keep apps/docs in sync with merged product changes. On each run, audit recently merged PRs against docs content, update only drifted pages, verify with blume build, and open or update a docs/* PR — or report a clean no-op. |
Update docs — sync apps/docs with merged PRs
Upstream workflow: npx skills add haydenbleasel/blume --skill blume-update-docs. This local skill encodes it for scheduled agents in this repo.
When to use
- Scheduled — weekly (or similar) run to catch docs drift from merged PRs.
- On demand — after a batch of merged PRs that may have changed public API surfaces, seams, or Blume config.
Workflow
- Collect merged PRs in the lookback window (default 7 days):
git log --since="7 days ago" --merges --first-parent and gh pr list --state merged --search "merged:>$DATE". Done: every merged PR in the window listed with title, number, and surfaces touched.
- Drop feature-flagged work — skip PRs/commits touching flag-gated code; never document unreleased surfaces. Done: flag-gated PRs removed from the list.
- Map changed surfaces to docs pages — trace diffs in
src/core/, src/adapters/**, package.json exports, blume.config.ts / apps/docs/**, and TypeDoc-facing JSDoc to the pages that document them (content/reference/api/**, content/guides/**, content/recipes/**, content/concepts/**, content/adapters/**, plus homepage _home/** when behavior framing changed). Regenerate API MDX via bun run docs:api when public exports/JSDoc drifted. Done: every changed public surface mapped to zero or more docs pages.
- Edit only drifted facts — signatures, option tables, behavior descriptions, entry-point peers. Use
docs-voice; do not rewrite stable prose. Competitor framing stays store persist middlewares only. Done: every drifted fact updated; no stable prose touched.
- Verify —
bun run docs:validate -- --strict && bun run docs:check -- --isolated && bun run docs:build -- --isolated (or root filter equivalents); fix until green. Do not commit if any fail. Per verify-after-each-step. Done: all three green.
- Open or update a PR on branch
docs/sync-<date> with a summary of what drifted and the fixes. Label it docs so merge deploys /persist (docs-governance/LIFECYCLE.md § README surfaces). Follow commit/PR conventions; never --no-verify (no-bypass-hooks). Done: PR open with docs label and drift summary, or step 7 applies.
- Clean no-op — if nothing drifted, report the PRs checked and surfaces audited; do not open a PR. Done: report lists every PR checked and every surface audited.
Boundaries
- Only
apps/docs/ (+ root scripts/config that the docs app requires, e.g. typedoc.json when regenerating API) — never edit maintainer docs/ plans/research in a sync PR; never edit library src/ in a docs-sync PR.
- Minimal diffs — drifted facts only; no cosmetic rewrites, unrelated refactors, or removing source comments in touched files (
authoring-discipline).
- No PR on a clean no-op; no commit on a failing build.
Reference