---
name: read-me-launcher
description: >-
  Write audience-aware, repository-grounded GitHub README.md pages: inspect the
  real repo first, choose evidence (code/visual/behavioral), keep claims matched
  to manifests/scripts, render-safe Markdown, and scan for secret leaks. Use when
  writing or redesigning a README; when install docs drift from reality; when
  images fail on GitHub; or when the user wants trustworthy developer docs.
license: MIT
---

# 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](references/taxonomy.md)).
3. Map to a mode shorthand if useful
   ([references/audience.md](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](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](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/design.md),
   [references/section-map.md](references/section-map.md)
5. **Generate assets only if needed**  -  [references/generation.md](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)

| Marker | Meaning |
|--------|---------|
| ✓ verified | Confirmed from inspect/manifests |
| ~ inferred | Reasonable but not explicit in repo |
| ? unknown | Do not present as fact |
| ✗ unsupported | Remove or rewrite |

## 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

| Path | When |
|------|------|
| [scripts/inspect-repo.sh](scripts/inspect-repo.sh) | Always first |
| [scripts/check-readme.sh](scripts/check-readme.sh) | Always before finish |
| [references/taxonomy.md](references/taxonomy.md) | Classification |
| [references/audience.md](references/audience.md) | Evidence mode |
| [references/visuals.md](references/visuals.md) | Image formats |
| [references/generation.md](references/generation.md) | Asset prompts / bans |
| [references/design.md](references/design.md) | Structure |
| [references/privacy.md](references/privacy.md) | Public/private + deny-list |
| [references/section-map.md](references/section-map.md) | Sections by type |
| [tests/run-tests.sh](tests/run-tests.sh) | Local verification |