README create/update

Replaces the former doc-readme-create / doc-readme-create-sub / doc-readme-update trio: $mode picks the verb, $target picks the directory (project root when empty). If $mode is empty, infer it from a three-way state check, not a create/update binary:

• (a) No README at the target → create.
• (b) Placeholder/auto-generated README → treated as create, free to fully regenerate against the template. Detected by: a <!-- doc-readme: generated ... --> marker (see Mode: create below; this skill leaves one on everything it writes from now on), OR a recognisable scaffold-tool stub (a framework's default "Welcome to Create React App" / npm init boilerplate / near-empty single-paragraph file with no real project detail).
• (c) Hand-authored README, no marker, doesn't match a placeholder shape → update, the cautious path.

Say which state you detected and why (marker found, boilerplate pattern matched or genuinely hand-authored) before proceeding.

Mode: create

1. Confirm the target directory exists; stop and report if not.
2. Analyse it: purpose, contents, structure, key modules, build system, existing docs. For a sub-directory, read the surrounding context too (parent README, siblings, project docs) to place it in the codebase.
3. Fill the matching skeleton: ~/.claude/library/templates/readme-root.md for the project root, readme-sub.md for a sub-directory. Each {{ slot }} describes its content; drop sections that do not apply, never invent content to fill one.
4. Include actual paths and commands, not placeholders. Match the style of existing project READMEs. Keep it proportional: a README is an overview, not full docs.
5. Badge row, only for what's real. Detect what's actually present (a real .github/workflows/*.yml → CI badge; a real published version (package manifest, svu current) → version badge; a real LICENSE/LICENSE.md → license badge) and emit a shields.io row from those only. Never a badge for something that isn't in the repo; a badge for CI that doesn't run is a lie the honesty rule in artefact-conventions.md exists to prevent, and that value applies here too even though this is Markdown, not HTML.
6. Collapsibility for secondary sections. Past roughly 4-5 major sections, wrap the less-critical ones (Contributing, full config reference, detailed dev setup) in GFM's native <details><summary>: no custom styling needed, GitHub renders the disclosure triangle itself. Keep What-it-is, Quickstart/Install, and core usage always visible.
7. Provenance footer. A short, visible closing line: Generated by doc-readme against \{commit-sha}` on {date}.` Terse, at the very bottom, doesn't compete with the real content.
8. Marker comment, placed as the very first line of the file: <!-- doc-readme: generated {date}. Delete this line once you hand-edit this file. -->, which is what lets a future run detect state (b) instead of treating a since-regenerated README as hand-authored.
9. Scan the draft before showing it: ~/.claude/library/scripts/slop-scan.py --strict - <<'SLOP_EOF' … SLOP_EOF. Non-zero exit: rewrite to clear every L<n> <rule>: <excerpt> line and rescan, at most twice. If hits remain, list them under the draft in step 10 so the reviewer decides.
10. Show the draft and stop for approval before writing. Git is the backup; never leave .bak files in the tree.

Mode: update

Reached only for state (c), a genuinely hand-authored README with no marker and no placeholder shape. Stay conservative here; this is the one path that must never treat someone's real prose as raw material to restructure.

1. Resolve the README ($target/README.md, default ./README.md). If it does not exist, say so and offer create mode instead.

2. Read it for structure and style, then gather what changed in one command:

   "$HOME"/.claude/library/scripts/git-doc-history.sh $target/README.md $target
   

   It prints the commits, file changes and diff stat since the README was last touched; analyse that dump rather than running exploratory git calls.

3. Identify what needs updating: outdated descriptions, undocumented additions, removed content to clean up, structural changes.

4. Generate targeted updates preserving the existing structure and style. Scan the changed passages (~/.claude/library/scripts/slop-scan.py --strict - on a heredoc of the new text) and clear every hit, at most two rewrites; then show a diff (any remaining hits listed under it) and apply on approval.

5. If the changes are minor, say so; don't invent updates for the sake of it. Prefer surgical edits over rewrites; don't remove content unless genuinely obsolete.