feat(readme): Docs Index — README links every doc in docs/

[derek-palmer]

Problem

Refresh generates user-facing docs (docs/api.md, docs/stack.md, docs/diagrams.md, docs/flows.md, docs/version-audit.md, docs/audit.md) but the generated README never links them. The readme task prompt has no documentation-index section — only a conditional "Architecture: link to docs/diagrams.md". Result: a fresh refresh leaves every generated doc orphaned and effectively invisible to readers.

Observed in practice: a full /forerunner-refresh run generated 5 docs in a target repo and the README linked none of them.

Design (grilled, decisions final)

Term: Docs Index (added to CONTEXT.md) — the ## Documentation README section listing every user-facing doc in docs/ with a one-line description. The readme task is its sole writer.

1. readme task — new conditional section

src/codeforerunner/prompts/tasks/readme.md:

• Add conditional section Documentation: present iff any top-level docs/*.md exists.
• Bullet list, one entry per doc: - [Title](docs/file.md) — one-line description.
• Covers all top-level docs/*.md present on disk — generated and hand-written alike.
• Respect scan excludes (e.g. docs/legacy/** from forerunner.config.yaml).
• Never link .forerunner/* (internal artifacts: scan, check-report, arch-review, review-summary).
• Replaces the existing conditional "Architecture: link to docs/diagrams.md if it exists" — subsumed by the index.

Example shape:

## Documentation

- [Getting started](docs/getting-started.md) — install and first run
- [Architecture diagrams](docs/diagrams.md) — system and data-flow diagrams
- [Stack guide](docs/stack.md) — env setup, modules, env vars
- [Version audit](docs/version-audit.md) — dependency EOL status

2. check task — new staleness rule

src/codeforerunner/prompts/tasks/check.md, add to "What to Check":

• Docs Index accuracy: does README link every top-level docs/*.md (excluding scan-excluded paths)? Unlinked doc → README STALE. README links a doc file that no longer exists → README STALE.

3. refresh task — readme runs last

src/codeforerunner/prompts/tasks/refresh.md: change generation order from

readme → api-docs → stack-docs → diagrams → flows → version-audit → audit

to

api-docs → stack-docs → diagrams → flows → version-audit → audit → readme

Rationale: docs generated in the same pass must exist on disk before the readme task builds the Docs Index; otherwise the index misses them and the README is stale the moment it is written. README links only files that actually exist — never "planned" docs from the check report.

Acceptance criteria

• readme task prompt emits ## Documentation when docs/*.md exists; omits it when docs/ is absent or empty.
• Index lists all top-level docs/*.md, each with a one-line description; no .forerunner/* entries; scan excludes respected.
• Old "Architecture: link to diagrams" conditional removed (subsumed).
• check classifies README STALE when an unlinked top-level docs/*.md exists, and when an index link points at a missing file.
• refresh generation order ends with readme.
• CONTEXT.md defines Docs Index (already committed alongside this issue).

Out of scope

• Recursive indexing of docs/ subdirectories (e.g. per-file docs/adr/ entries).
• Surgical README patching outside the readme task — check decides, readme writes, no second README write path.
• Changes to this repo's own README (it already has a ## Docs section; it will pick the new shape up on the next self-refresh).

[coderabbitai]

🔗 Related PRs

#8 - docs: add agent plugin distribution roadmap [merged]
#14 - docs: sync all markdown to v0.3.2 reality [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!