feat: docs-sync skill for CC — TSDoc coverage check + README auto-update

[OneStepAt4time]

Feature Request — docs-sync Claude Code Skill

Context

Docs rot is the silent killer of open source projects. This skill gives Hep a tool to invoke CC to automatically check and fix TSDoc coverage + keep README in sync with the actual API — leveraging Aegis itself to develop Aegis.

Depends on: #370 (TypeDoc setup must exist first)

What to build

A new superpowers skill .claude/skills/docs-sync.md that when invoked by Hep via Aegis:

1. TSDoc audit — scans all src/**/*.ts public exports, identifies methods/classes with missing or incomplete TSDoc
2. Auto-fill TSDoc — for each gap, generates and inserts @param, @returns, @throws, @example from context
3. README sync — checks if endpoint list in README matches actual routes in src/server.ts — updates if stale
4. Coverage report — outputs summary: N/M methods documented (X%)

Acceptance criteria

• docs-sync skill file exists in .claude/skills/
• Hep can invoke it via: "Invoke the docs-sync skill" in a CC session
• After a run, TypeDoc coverage increases measurably
• README endpoint table matches actual server routes
• Hep's HEARTBEAT.md includes docs-sync in the release checklist

How to approach

⚠️ Use plan mode + brainstorming skill before writing any code.

1. Invoke brainstorming skill to explore: how to structure the skill file, TSDoc parsing strategies (AST via ts-morph vs regex), README sync approaches (structured comment anchors vs full rewrite), whether to use a separate CC session or inline script
2. Invoke writing-plans skill for the skill file structure + implementation plan
3. Implement via executing-plans — the skill itself is the output

Notes

• ts-morph is the cleanest way to parse/mutate TypeScript AST without regex hacks — worth evaluating in brainstorm
• Skill should be idempotent: running twice produces the same result
• Don't auto-commit — leave changes staged for Hep to review before committing

[OneStepAt4time]

🔧 Starting work on this. Approach: docs-sync skill using ts-morph for TSDoc audit + brainstorming skill for architecture. ETA: ~45 min.