update-docs

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

1. 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.
2. Drop feature-flagged work — skip PRs/commits touching flag-gated code; never document unreleased surfaces. Done: flag-gated PRs removed from the list.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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

• Verify loop: verify-after-each-step · harden-pr (lite before commit, full before merge)
• Authoring: authoring-discipline
• Voice/tone/format for the public site: docs-voice
• Docs site scope: docs-governance (governs docs/; this skill governs apps/docs/ sync only)