Skip to content

docs: a documentation site, and READMEs that match the code - #11

Merged
unfoundbox merged 3 commits into
mainfrom
docs/site
Aug 17, 2026
Merged

docs: a documentation site, and READMEs that match the code#11
unfoundbox merged 3 commits into
mainfrom
docs/site

Conversation

@unfoundbox

@unfoundbox unfoundbox commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator

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, then
rebased 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.yml greps for externally-loaded
assets 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, a prefers-color-scheme block guarded
with :not([data-theme="light"]), an explicit [data-theme="dark"], and a
visible 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 pre blocks scroll inside their own containers, the
header goes non-sticky under 46rem so wrapped nav does not eat a phone screen.

Corrected on rebase

The branch was written when minAgeMs was broken, so it documented the bug as
behaviour — accurately at the time, wrong as of v0.3.1. Rewritten to describe
what ships: the option decides the verdict, liveAges/liveAgesCap are what
make it exact, saturation reports a lower bound with the total beside it in
liveBounded, and a census with no ages sets minAgeMsApplied: false rather
than filtering silently. docs/limits.html now describes the real limit — the
cap — instead of the fixed defect. LeakReport and ContextCensus tables gain
the v0.3.1 fields.

Also

  • Root README keeps its voice; gains a docs link and a Documentation section.
  • Per-package READMEs link their own page.
  • AGENTS.md, with CLAUDE.md symlinked to it: the one rule that matters, the
    package map, build/test/typecheck with the Chrome path, the git-worktree trap,
    and the lockstep release flow.

Verification

npm ci inside the worktree first, so the results are about this build and not
the 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


View with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.

unfoundbox and others added 3 commits August 17, 2026 15:34
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>
@unfoundbox
unfoundbox merged commit a40a040 into main Aug 17, 2026
4 checks passed
@unfoundbox
unfoundbox deleted the docs/site branch August 17, 2026 10:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant