docs: a documentation site, and READMEs that match the code - #11
Merged
Conversation
The README carries the whole pitch and had grown to the point where the reference material and the argument were competing for the same page. This splits the reference out into eight pages under docs/: what the tool is, quickstart, the assertion API field by field, the CDP driver, the MCP server, the extension, CI recipes, and the limits. Plain HTML with the CSS inlined in each page. No build step, no CDN, no font fetch — what is committed is exactly what is served, and every page opens over file:// as readily as over https. The pages are duplicated rather than sharing a stylesheet on purpose: that is the trade that keeps the directory publishable as-is. pages.yml uploads docs/ unchanged, after grepping for any asset loaded from the network — a CDN link would break the self-contained promise quietly, since the page still renders for whoever has it cached. Pages itself is not enabled; that is a decision for a human, and until it is made the deploy step fails loudly rather than half-publishing. Everything documented here was read out of the source rather than recalled. Two things that were not written down anywhere: minAgeMs filters the reported allocation sites and not the verdict, and the message scanner descends only into arrays and plain object carriers, so a frame held on a class instance arrives uncounted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Each README now links the page that covers its own package, and keeps the GitHub link separately for source and issues. The correction is worth naming. Both the root and core READMEs offered `minAgeMs` as the way to ignore objects that may still legitimately be in flight, and the CI example passed `minAgeMs: 1000` as if it changed the outcome. It does not: checkLeaks applies it to report.sites only, while ok is computed from report.live, so raising it shortens the message without moving the verdict. `allow` is the option that does what the text described, so the examples now use that. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
What the project is, the one rule that matters, how to build and test, the lockstep release flow, and the two worktree traps — a worktree without its own node_modules type-checks mcp against the main checkout's declarations, and runs the tests against the main checkout's shim, because packages/cdp loads it by package name. Both fail by reporting a result about someone else's build, which is the expensive kind of wrong. CLAUDE.md is a symlink, matching the convention across these repositories. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An eight-page documentation site, a Pages workflow to deploy it, and the
README/AGENTS work that goes with it. Built by an agent against
main, thenrebased onto v0.3.1 and corrected where the code moved underneath it.
The site
docs/— overview, quickstart, API reference, CDP driver, MCP server,extension, CI recipes, honest limits. Plain HTML, CSS inlined per page, zero
network requests:
.github/workflows/pages.ymlgreps for externally-loadedassets and fails the build on a hit, so the no-network property is enforced
rather than hoped for.
Design follows the product: true-black ground, zinc neutrals, one accent, and
full three-state theming — bare
:root, aprefers-color-schemeblock guardedwith
:not([data-theme="light"]), an explicit[data-theme="dark"], and avisible System/Light/Dark toggle with a pre-paint script so a chosen theme does
not flash. Verified in a browser in both modes: no body-level horizontal scroll
at 375px, wide tables and
preblocks scroll inside their own containers, theheader goes non-sticky under 46rem so wrapped nav does not eat a phone screen.
Corrected on rebase
The branch was written when
minAgeMswas broken, so it documented the bug asbehaviour — accurately at the time, wrong as of v0.3.1. Rewritten to describe
what ships: the option decides the verdict,
liveAges/liveAgesCapare whatmake it exact, saturation reports a lower bound with the total beside it in
liveBounded, and a census with no ages setsminAgeMsApplied: falseratherthan filtering silently.
docs/limits.htmlnow describes the real limit — thecap — instead of the fixed defect.
LeakReportandContextCensustables gainthe v0.3.1 fields.
Also
AGENTS.md, withCLAUDE.mdsymlinked to it: the one rule that matters, thepackage map, build/test/typecheck with the Chrome path, the git-worktree trap,
and the lockstep release flow.
Verification
npm ciinside the worktree first, so the results are about this build and notthe main checkout's. Then
npm run build:all,npm test(49 pass, 0 fail,pinned Chrome 151.0.7922.71) and
npm run typecheck— all clean.Before this is useful
GitHub Pages needs switching on (Settings → Pages → Source: GitHub Actions), or
the README links to the site 404 on a public page.
🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is enabled.