docs(examples): call for real-world example kbs — screenshots and verifiable proof

[plind-junior]

everything under examples/ today is an authored fixture — real-shaped, but built for the docs (tiny/, decision-log/, the runnable flows). what's missing is evidence of vouch in the wild: a kb that grew inside an actual project, with real proposals, real review decisions, real supersessions and contradictions. this issue is a standing call for contributors to submit those.

what a submission looks like

one new subdirectory, examples/community/<slug>/, containing:

• a short README.md — what the project is, which host drives vouch (claude code, cursor, openclaw, plain cli), and what the kb is actually used for. one or two paragraphs, lowercase prose.
• a snapshot of the kb, following the existing snapshot convention: your .vouch/ tree copied to vouch/ (no leading dot, so it renders in the github ui) — claims/, pages/, decided/, audit.log.jsonl, sources/.
• screenshots (png or svg, stored in the example directory and embedded in its readme): at minimum vouch status, one vouch search <term> that hits, and vouch audit or vouch show <id> on a reviewed artifact. real terminal output against the submitted snapshot — unlike the shipped snapshots (which re-render byte-for-byte via make examples-screenshots), community screenshots just need to be honest, not machine-reproducible.

what counts as proof

the audit log is the proof. audit.log.jsonl and decided/ must be the genuine trail: every claim in the snapshot traceable to a propose → approve event, and vouch doctor clean on the tree. a kb hand-authored to look used will not reconcile — that's the point of the review gate, and it's the point of the example.

• vouch audit output must reconcile with what's in claims/ and decided/
• anyone who copies vouch/ into a fresh .vouch/ and runs the commands in your screenshots should see the same artifacts
• if the source project is public, link the repo where the kb lives; if it's private, say so in the readme — the snapshot itself is the evidence either way

privacy

scrub before you submit: no real customer names, internal urls, credentials, or pii in claims, pages, sources, screenshots, or the audit log. if redaction would gut the example, substitute placeholder names (alice-example, acme-example) and note that you did.

how to submit

one pr per example, branched as docs/example-<slug>. add a row for your example to a new "community examples" section in examples/README.md. keep the snapshot small — trim to the interesting subset (roughly 10–50 claims) rather than dumping the whole kb; supersession chains and rejected-then-reworked proposals are worth more than volume.

acceptance criteria (per submission)

• examples/community/<slug>/ with README.md, a vouch/ snapshot, and at least three screenshots embedded in the readme
• vouch doctor passes on the snapshot and vouch audit reconciles with the committed artifacts
• every claim traceable through audit.log.jsonl to a propose → approve decision — no hand-written approved artifacts
• no pii, customer names, or internal urls anywhere in the tree or the screenshots
• row added to examples/README.md
• lowercase prose throughout; no comparison to any other product or tool