docs: README landing page with a produce/verify demo GIF and a CI-verified quickstart - #55
Conversation
|
The This diff never touches Generated by Claude Code |
docs/assets/demo.tape drives context-report produce and verify against my-plugin, a two-file Claude Code plugin bundle, and renders docs/assets/demo.gif (VHS, Catppuccin Mocha, per the shared README-refresh recipe). Matches the README quickstart's own commands exactly. Signed-off-by: Claude <noreply@anthropic.com> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Centered header (name, one-line pitch, badges reordered CI/PyPI/Python/ License/Scorecard/PRs, no logo file exists so none is added), the demo GIF inserted after the badges, the quickstart replaced with a self-contained block whose JSON rows and verify output are real context-report output, "Who it's for" as a table, "Every model you can reach" folded into a provider table inside "Two models, not one", a new Supported agents table, and the family table replaced with the shared byte-identical version. The run/compare explanation and the "Every model you can reach" prose that used to sit inline move verbatim into docs/cli.md, linked from both places they used to live. Signed-off-by: Claude <noreply@anthropic.com> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
tools/quickstart_block.py extracts the first fenced bash block under the README's quickstart heading, stdlib only; a new quickstart CI job installs the package from this checkout and runs the extracted block in a fresh mktemp dir. tests/test_quickstart_block.py proves the extractor fails a broken block under bash -e. A dispatch-only render workflow reproduces docs/assets/demo.gif from its tape as an uploaded artifact, checksum- verifying the vhs binary download; main stays protected and never receives an automated commit. Signed-off-by: Claude <noreply@anthropic.com> Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
36a75d2 to
39d92ee
Compare
What
Refreshes the README's landing section per the shared README-refresh standard (org-plan #187,
epic #183): a centered header (name, one-line pitch, badges on one line), a rendered
context-report produce/verifydemo GIF (docs/assets/demo.tape→docs/assets/demo.gif,146 KB) inserted after the badges, the quickstart replaced with a self-contained block whose
JSON rows and
verifyoutput are realcontext-reportoutput (verified reproducible — runningthe extracted block in a fresh
mktemp -dyields byte-identicalinputHashvalues to what's inthe README), "Who it's for" reformatted as a table, "Every model you can reach" folded into a
provider table inside "Two models, not one", a new Supported agents table (reachability/cost
/fault per target, from
payloads-v0.1.jsonandfault.py's documented-oracle coverage), andthe family table replaced with the shared, byte-identical version. Word count excluding tables
and fenced code: 1,012.
Also adds:
tools/quickstart_block.py(stdlib) +tests/test_quickstart_block.py, and aquickstartCIjob that extracts the README's first fenced bash block and runs it in a fresh temp dir —
proving the README's own quick start actually works. The test suite proves the extractor fails
a broken block (
bash -eexits 1); I also confirmed this by hand against the real block (exit 0)and a deliberately broken one (exit 1).
.github/workflows/render-demo.yml, dispatch-only, to reproduce the GIF; it never commits tomain. The vhs binary download is checksum-verified (sha256sum -cagainst the release's ownchecksums.txt) rather than trusted blind.docs/cli.md: therun/compareexplanation (manifest schema,--dry-run/--n/--resume)and the "Every model you can reach" prose that the old quickstart carried inline, moved
verbatim rather than deleted, linked from both places in the README they used to live.
[Unreleased]→ Docs entry.Deviations
stays text-only rather than adding a placeholder image.
img.shields.io/pypi/v/context-report); no "Best Practices" badge existstoday so none was added ("where present" per the shared standard).
render-demo.ymluses the plain VHS binary (checksum-pinned) instead ofcharmbracelet/vhs-action: this session had no way to fetch or verify a real commit SHA forthat action (GitHub API access to repos outside this session's scope was unavailable), and
pinning an unverified SHA would violate the "verify before adding a dependency" rule.
actions/upload-artifactreuses the SHA already pinned elsewhere in this repo's own workflows.context-report produce's--kind plugin --subject ./my-pluginexample reportsreachability: FAILEDfor a real, honest reason (${CLAUDE_PLUGIN_ROOT}resolves relative to the cwd you runit from, so the hook is only reachable from the one cwd where that relative path still
resolves) — kept as-is rather than switched to an absolute path, since it's real, reproducible
output and echoes the README's own "Reachable is not the same as executable" finding. The tape
and the README quickstart now run the identical two commands (
producethenverify), so theGIF's punchline is a command a reader actually ran.
Definition of done
python -m ruff check .andpython -m ruff format --check .cleanpython -m pytest -qgreen (408 passed); new tests cover the extractor's ordinary andbroken-input cases
chock checkandchock sync --repo . --check: n/a,.agents/policies/untouchedClaims
re-derivableunless it actually recomputes from the subject plusits recorded configuration and carries an
inputHash. Every row shown in this PR's READMEchanges is real
context-reportoutput, not illustrative.