Read Me Launcher

Core promise: a README that matches the repository.

Inspect first. Never invent stack facts. Choose the minimum honest proof for the audience. Lint for render breaks and secret-looking strings before finishing.

Step 0: classify

1. Run scripts/inspect-repo.sh.
2. Resolve INTERFACE × AUDIENCE × PRIMARY_PROOF (references/taxonomy.md).
3. Map to a mode shorthand if useful (references/audience.md).

Hard rules (errors)

• Claims about install/run/test match inspect output (✓ verified vs ? unknown)
• No invented features, scripts, or runtimes
• No code fences inside <div> / <section> / <center>
• Local images referenced by the README exist
• scripts/check-readme.sh README.md exits 0 (secret + render checks)
• Privacy rules in references/privacy.md

Strong defaults (not universal mandates)

• Libraries lead with working code, not marketing murals
• Internal repos optimize for runbooks, not launch theater
• Public GUIs usually need one real screenshot
• Add banner/preview/showcase only when each asset proves something
• Prefer PNG when embedding raster heroes (references/visuals.md)

Style preferences (warnings / prefs)

• Em dashes are a preference (PREF); use --strict-style only if the user wants hard fails
• Max ~3 badges above the fold by default
• Avoid emoji spam and badge walls

Workflow

1. Inspect - scripts/inspect-repo.sh
2. Classify - taxonomy + audience
3. Choose proof - minimum necessary evidence
4. Draft README - references/design.md, references/section-map.md
5. Generate assets only if needed - references/generation.md
6. Lint - scripts/check-readme.sh README.md
7. Consumer pass - would a stranger install from the first screen?

Claim markers (recommended in drafts / reviews)

Output rules

• Write the README (and assets only when justified)
• Prefer correcting an existing good README over destructive rewrites
• No “Generated by AI”
• Do not over-claim “secret-safe” beyond what check-readme.sh scans; call out residual risk

Bundled resources