epic: make vouch friendlier and more useful out of the box

[plind-junior]

Motivation

vouch is solid as a primitive, but it has rough edges when someone — human or agent — first picks it up. This epic tracks four parallel workstreams to lower friction. Each track can graduate into its own issue/PR.

---

Track 1 — First-run / onboarding UX

• vouch init writes a starter config.yaml, seeds an example source + claim, and prints "next steps"
• vouch doctor outputs suggested fixes, not just findings (e.g. run \vouch index` to rebuild`)
• Add a 30-second tour section to the README that runs end-to-end against the example KB

Track 2 — Friendlier CLI output

• Colorized output for vouch status, vouch lint, vouch search
• Progress indicator on long ops: rebuild_index, doctor, bundle import/export
• Human-readable summaries by default; --json for machine output
• Consistent error formatting with file/line context where applicable

Track 3 — Agent-facing ergonomics

• propose_* errors suggest the closest id ("did you mean src-acme-2025?") instead of just unknown source/evidence id
• New kb.help MCP method returning a short workflow guide (propose → review → crystallize)
• dry_run=true returns a rendered preview of the artifact, not just the proposal envelope
• Document the recommended agent loop in docs/

Track 4 — Real-world examples & templates

• templates/ directory with at least three ready-to-use workflows:
  • research-notes — papers → claims → synthesis page
  • codebase-audit — findings → claims → contradicted/superseded over time
  • meeting-decisions — transcripts as sources, decisions as claims
• vouch init --template <name> scaffolds from a template
• Tutorial page in docs/ walking through one template end-to-end

---

[sxxtony]

@plind-junior Can I pick this up?

[Tet-9]

@plind-junior Can I pick this up?

Nope🤦🙅