What you're trying to do
the example KBs under examples/ (tiny/, decision-log/) are
self-contained vouch/ trees, but they're text-only. the READMEs tell a
reader to cp -r examples/tiny/vouch ./.vouch then run vouch status,
vouch search auth, vouch pending — without ever showing what those
commands return. someone evaluating vouch on GitHub has to install it and
load a fixture before they can see what the tool looks like.
screenshots of the shipped examples in use would let the examples carry
their own weight: see the output, then decide whether to set it up.
Suggested shape
capture each surface against the example fixtures (no bespoke data — use
exactly what's in examples/tiny/vouch and examples/decision-log/vouch
so the shots stay reproducible):
- cli —
vouch status, vouch search auth, and vouch show auth-uses-jwt against tiny/; vouch log / supersession view against
decision-log/ (it's the example that demonstrates supersession + audit
trail).
- web review-ui — the read view over
decision-log/, if src/vouch/web/
is available.
- desktop gui — the same KB loaded in the Electron app, if in scope.
store images under docs/img/examples/ (or alongside the demo assets in
docs/), then embed them in examples/README.md and each subdir README so
the table rows gain a thumbnail. keep them small — these are learning
material, not the 200k-claim anti-example the README already rules out.
prefer deterministic capture (a .tape like docs/demo.tape, re-renderable
with vhs) over hand-grabbed screenshots where the surface is a tty, so the
images can be regenerated when output format drifts.
Compatibility considerations
additive and docs-only — no KB-format or surface change, no VEP. the example
fixtures themselves don't change; only READMEs gain image embeds.
Alternatives
- a single animated gif per example instead of stills (heavier, but matches
the existing docs/demo.gif convention).
- leave examples text-only and lean on
docs/example-session.md for the
visual walkthrough (status quo — but that walkthrough isn't tied to the
shipped fixtures).
What you're trying to do
the example KBs under
examples/(tiny/,decision-log/) areself-contained
vouch/trees, but they're text-only. the READMEs tell areader to
cp -r examples/tiny/vouch ./.vouchthen runvouch status,vouch search auth,vouch pending— without ever showing what thosecommands return. someone evaluating vouch on GitHub has to install it and
load a fixture before they can see what the tool looks like.
screenshots of the shipped examples in use would let the examples carry
their own weight: see the output, then decide whether to set it up.
Suggested shape
capture each surface against the example fixtures (no bespoke data — use
exactly what's in
examples/tiny/vouchandexamples/decision-log/vouchso the shots stay reproducible):
vouch status,vouch search auth, andvouch show auth-uses-jwtagainsttiny/;vouch log/ supersession view againstdecision-log/(it's the example that demonstrates supersession + audittrail).
decision-log/, ifsrc/vouch/web/is available.
store images under
docs/img/examples/(or alongside the demo assets indocs/), then embed them inexamples/README.mdand each subdir README sothe table rows gain a thumbnail. keep them small — these are learning
material, not the 200k-claim anti-example the README already rules out.
prefer deterministic capture (a
.tapelikedocs/demo.tape, re-renderablewith
vhs) over hand-grabbed screenshots where the surface is a tty, so theimages can be regenerated when output format drifts.
Compatibility considerations
additive and docs-only — no KB-format or surface change, no VEP. the example
fixtures themselves don't change; only READMEs gain image embeds.
Alternatives
the existing
docs/demo.gifconvention).docs/example-session.mdfor thevisual walkthrough (status quo — but that walkthrough isn't tied to the
shipped fixtures).