update-docs

Update all project documentation to reflect recent changes.

Docs directory: docs/ within the current project root. Target files: all .md files in docs/ that already exist, plus README.md in the project root.

Procedure

UD-0. Read rules/docs.md. It is on-demand-only and never auto-injected, so this Read is mandatory. Read rules/coding.md here too — same on-demand-only status; its Public GitHub Rules govern every doc written in UD-4 and after. UD-1. Gather recent changes:

• Run git diff and git diff --cached to capture uncommitted and staged changes (current session's work, not yet in git log)
• Run git log --oneline -20 for committed history UD-2. Read current docs: Read all target docs files.
• README.md (repo root) is required for all repos. Create it first if missing — highest priority.
  • Goal: make the reader think "I want to use this" — crisp features, "what it does for you"
  • Initial install/setup instructions go here, not in ops.md
• CHANGELOG.md (repo root) for public repos. Create if missing (no manual seed needed — first run starts from here).
• When docs/glossary-user*.md or docs/glossary-internal*.md exists, Read rules/docs/glossary.md (on-demand-only) so its entry criteria drive the UD-3 glossary check. UD-3. Identify gaps: Compare git log against each document's content. Look for:
• Unrecorded commits or phases
• Architecture/design changes not yet documented
• New incidents or bug fixes
• Infrastructure or operational changes
• Progress updates
• README.md: Update when a user-visible feature is added or changed, install/usage steps shift, or an existing bullet no longer accurately reflects real behavior.
• Glossary promotion: list the user / internal rows of <INTENT_MD> ## Glossary (<INTENT_MD> = the output of node "$AGENTS_MAIN_ROOT/bin/plan-artifact-path" --stage intent) as promotion candidates in the UD-4 proposal; do not write yet.
• Glossary entries: never add one outside glossary promotion. UD-4. Propose updates: For each file that needs updating, present:
• Before drafting History/Changelog bullets: apply the language configured by DOCS_LANG_PUBLIC / DOCS_LANG_PRIVATE, routed by repo visibility — one policy covers both history and changelog
• Which sections need changes and why
• Specific additions or modifications UD-5. CONFIRM_DOCS gate: Gate check: apply skills/_shared/confirm-plan.md CPA-3 — run next-step --gate and follow GATE_ACTION.
• GATE_ACTION=ask: present the UD-4 proposal via AskUserQuestion and wait for approval before applying edits.
• GATE_ACTION=proceed: apply the edits and continue to UD-6 without waiting.
• When applying, run node "$AGENTS_MAIN_ROOT/bin/glossary-promote" "<INTENT_MD>" "<project-root>" first, then replace each promoted entry's Related: TODO with a link to the doc that owns the term. UD-6. Propagate to parent docs: If the project has a parent-level summary doc (e.g. an engineering hub), update it too. Skip for repo-local docs/.
• Skip infrastructure.md — delegate to /update-infrastructure instead. UD-7. Commit separately: If docs are in a separate repo, commit each repo independently