docs: redesign the README around the pipeline - #19
Conversation
Add a themed banner and pipeline diagram (light and dark, generated from one source), a demo poster, the manifest entry and registration from the proof fixture, and scannable install, command, coverage and guarantee tables. A test keeps the generated artwork in sync with its generator.
TueJon
added
documentation
TueJon
left a comment
TueJon
left a comment
There was a problem hiding this comment.
README.md:1 — The redesign removes the README's only semantic <h1>. GitHub renders this head with How it works as the first heading (<h2>); the <picture> image's SVG title and alt text do not create an HTML heading. This directly violates the repository's load-bearing rule in AGENTS.md:34-39 that the README <h1> retain the exact phrase "WebMCP agent skill", and drops the heading/search surface that rule exists to protect. The new artwork test checks asset references but does not guard this invariant.
Closure checklist:
- Restore a README
<h1>containing the exact phraseWebMCP agent skill(Markdown or literal HTML is fine). - Extend the README test coverage to fail if that phrase is absent from the semantic
<h1>again.
|
Fixed at 7c558b5: restored a semantic README h1 containing the exact WebMCP agent skill phrase and added a regression assertion. Verified with npm ci --ignore-scripts and npm run check (46/46). |
TueJon
left a comment
TueJon
left a comment
There was a problem hiding this comment.
No blocking findings remain.
The semantic h1 restores the exact discoverability phrase, its regression assertion covers the invariant, and the targeted README-art test passes.
TueJon
left a comment
TueJon
left a comment
There was a problem hiding this comment.
No blocking findings remain.
The merge from main leaves both closure items unchanged, and the targeted README-art test passes at this exact head (2/2).
…fresh-review # Conflicts: # README.md
TueJon
left a comment
TueJon
left a comment
There was a problem hiding this comment.
No blocking findings remain.
The main merge preserves both original closure items, carries the new v0.7 README guarantees through the conflict resolution, and npm run check passes at this exact head (71/71 tests).
1 participant
The README was a long wall of text with an ASCII pipeline. This redesign leads with what the skill does and shows it:
.webmcpify/manifest.json), in light and dark variants via<picture>. Both are SVGs, so they also render on directory sites that mirror the README.assets/readme/build.mjs);tests/readme-art.test.mjsfails when a committed SVG drifts from its generator.Wording stays within existing claims. Coverage is described as an explicit choice (the skill never defaults silently), and nothing new is promised about pinning, where #18 is still open.
Validation:
npm run checkpasses (46 tests including the new artwork test). The README was rendered through GitHub's Markdown API and inspected at 1012 px in light and dark.