docs: make cofferdam context the entry point, document --only - #197
Open
TAJD wants to merge 11 commits into
Open
docs: make cofferdam context the entry point, document --only#197TAJD wants to merge 11 commits into
TAJD wants to merge 11 commits into
Conversation
CD-296: the landing page led with a prescriptive "two loops" framing. Replaced with cofferdam context as the single entry point to a repo, plus a description of the digest as an API — the fields an agent sorts and branches on to reach the next highest-priority problem. Schema block taken from real output, not invented. CD-298: the hero button read "The agent loop" and pointed at /agents, the `cofferdam agents` command reference. The link resolved; the label promised a concept and delivered a CLI page. Now "cofferdam context" -> /reference/context. CD-300: `--only` shipped under CD-74 and appeared in no docs page — only the CHANGELOG. Added ci-recipes §9 with the exit-code table and why it beats filtering `--format json` by check id: a filter cannot tell "no violations" from "the check never ran", so an unloadable plugin passes the gate silently. CD-295: README trimmed to value proposition, two workflow diagrams, a docs table and build-from-source instructions. Also replaced the landing page's quadrantChart with a table (CD-296 asks that diagrams read on mobile; quadrant charts do not) and dropped the second mermaid diagram that only restated the prose. CD-297 verified true and left as written: doctor.rs check 10 detects biome.json/biome.jsonc and ten eslint config filenames, and names six overlapping checks to disable. Verified: vitepress build clean (dead links fail the build by default); `cofferdam gen-docs --check` exits 0; hero and §9 anchors confirmed in the built HTML. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
Second pass over the pages, continuing CD-299. Four `check` flags shipped and appeared in no hand-written page — the generated reference/cli.md covered them, which is precisely why nobody noticed. Added to the universal-flags table with `--no-cache` given its own section: the findings cache is keyed on (content, config, engine_version), so re-running the same version against an already-scanned repo replays stale findings and makes a rule change look like a no-op. Cofferdam's own contributor guide requires --no-cache for real-repo validation; no public page said so. agents.md carried the same "two loops" framing CD-296 asked to drop from the landing page. Replaced with how the commands relate — start at context, and which of them gate — since that is what a reader needs and it does not prescribe a workflow. Mobile rendering (CD-296): the last quadrantChart, in output-formats.md, is now a table. Three `flowchart LR` diagrams in budgets.md and reference/advise.md are now TB so they reflow on a phone instead of scrolling sideways. No diagram in docs/ uses a fixed-aspect chart type any more. Verified: vitepress build clean, so every internal link and anchor resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
ignore.md promised a `[ignore]` section in cofferdam.toml "when it lands" and cited a retired beads id. `ProjectConfig` has no such table and no `exclude` key; exclusion is `.cofferdamignore`/`.gitignore` only. State that, and stop under-listing `--no-ignore`, which every tree-walking subcommand takes rather than three of them. mcp.md: the server exposes no `context` tool, so the entrypoint the docs now open with is unreachable over MCP alone (CD-302). Say so. type-aware-checks.md: replace the hand-wave about "your normal suppression flow" with the two concrete mechanisms, and record the asymmetry that `needs_type_oracle` keys on registered checks, so disabling the last type-aware check in config still spawns the host. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
languages.md covered TypeScript, HTML, Markdown and Rust but never mentioned `cofferdam typst`, an 11-check subcommand whose only trace in the docs was the clap-generated CLI reference — the same masking effect CD-301 turned up. Add the subcommand and tabulate the checks, and point at CD-303 for why they are absent from the check catalog. invariants.md documented three stubs by citing beads that no longer exist: `package.json:<key>` exports parse but resolve to nothing, `frozen = true` has no delta enforcement, and `transitively imports` walks direct edges only. All three are still stubs; retarget them at CD-304 and say plainly what each does today. The `package.json` pointer is the one that matters — it exempts nothing, silently. Drop the `--design` bead reference from dsl-grammar.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
plugin-sdk-e2e.md opened with "Status: design-only. The SDK epic has no
completed children" on a page in the published sidebar. The SDK shipped:
`@cofferdam/check-sdk` is on npm and the fixture it specifies runs in CI
at examples-plugins/brand-casing. Reframe it as the record of why the
surface is shaped this way, and drop the author's absolute Windows path
from the public site.
dsl-grammar.md printed a sample error carrying a line the binary never
emits ("reopen cd-9hp.10 to ship a SQL adapter"). Match the real text
from parser.rs, and stop telling readers to file against a retired
tracker.
canonical-graph.md claimed one built-in reads the canonical slot; two do
since Context.BlastRadius landed, and the check it named DeadExport is
under Refactor, not Design.
ci-recipes.md listed air-gapped installs as unwritten when install.md
documents the mechanism; point at it and narrow the gap to the recipe.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
… the TODO The Owner column listed retired bead ids where a reader wants a code path. The quoted rejection message named `cofferdam invariants migrate`, a subcommand that does not exist — fixed in the binary on the companion branch, so quote what it now says. And the page described the canonical graph and the DSL as unshipped; both shipped, they just carry no schema version of their own yet. Say plainly that nothing enforces the release-process bumps, rather than implying a gate exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
adapter-contract.md listed two Adapter impls; there are three — HtmlAdapter has shipped in cofferdam-html and backs `verify --dist`. Its arrival also weakens the page's own "not yet built" item, since all three adapters are file-and-span languages and none proves the trait shape holds for a domain that isn't. Say that instead. cross-file-checks.md opened with "added in this release" and "until recently", which stop being true the moment they are read. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
plugin-sdk-guide.md wrote `cofferdam --watch`; the CLI has a `watch` subcommand, not a flag. Strip the three cd-* references from headings and prose while there. seo-checking.md promised four surfaces and linked three. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
Prose only. The rewrite skips fenced blocks and inline code, so the `--analyze` flag on `advise`, Rust identifiers and mermaid's `color:` are all untouched — verified by grep after the pass. Covers three surfaces that have to agree or the site drifts back on the next regeneration: the docs pages, the check-catalogue bodies under crates/cofferdam-checks/docs/ that gen-docs copies into docs/checks/, and the clap doc comments that produce both `--help` and docs/reference/cli.md. Regenerated the catalogue, checks.json and the CLI reference so all three match. Left alone deliberately: identifiers, SPDX `license` fields, and the docs/superpowers/ and docs/decisions/ archives, which are records of what was written at the time. Verified: cargo test --workspace (1322 pass), clippy -D warnings, fmt, gen-docs --check, vitepress build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
The docs site is pnpm-managed (docs/pnpm-lock.yaml is tracked). This package-lock.json came from an `npm install` used to get a local vitepress build running and was swept in by a directory-wide `git add`. Two lockfiles for one package.json is worse than none. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
Criterion benchmark comparison (PR head vs base branch) |
Criterion benchmark comparison (PR head vs base branch) |
…I reference Three pages duplicated flag lists that `gen-docs` already emits from clap: `reference/advise.md`, `reference/context.md` and the ci-recipes cheat sheet. The generated page is strictly richer everywhere they overlap (it carries defaults, possible values and conflict rules), so the copies could only ever drift downward. Point at it instead, and keep only the prose the generator cannot produce: which flags change what a command *does*, and the caching caveat in ci-recipes. The one piece of wording worth saving — `--staged` conflicts with `--base` — moves into the clap doc comment, so it now reaches `--help` too. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v
Criterion benchmark comparison (PR head vs base branch) |
This was referenced Aug 9, 2026
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
1 participant
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.
Closes CD-295, CD-296, CD-298, CD-300. Verifies and closes CD-297.
CD-296 — landing page leads with
cofferdam contextThe page opened with a "two loops" section that told readers how to run their workflow. The ticket asks for the opposite: describe
cofferdam contextas the single entry point to a repo, then give the API for driving to the next problem. That section and its diagram are gone.In their place, the digest as an API — the JSON envelope with a table of the four fields an agent actually branches on (
score,check_id,pinned,explain,omitted), and where to go from a high-scoring item. The schema block is copied from realcofferdam context --format jsonoutput, not written from memory.CD-298 — the "agent loop" button
The link was not broken.
/cofferdam/agentsresolves, and the page builds and deploys.The defect is that the button promised a concept and delivered a command reference: it read "The agent loop" and landed on the
cofferdam agentsCLI page. Retargeted to "cofferdam context" →/reference/context, which also serves CD-296.CD-300 —
--onlywas undocumented--onlyshipped under CD-74 and appeared inCHANGELOG.mdand nowhere else. Newci-recipes§9 covers it, with the exit-code table:--fail-onExit 2 is the argument for the flag. A
jqfilter over--format jsoncannot distinguish "no violations" from "the check never ran", so an unbuilt plugin passes the gate silently. That happened in the projektor repo and is fixed in TAJD/projektor#242.Also added to the recipe selector and the universal-flags table.
CD-295 — README
Cut to value proposition, two workflow diagrams, a docs table and build-from-source instructions. The 17-item link list, the dogfood internals and the
advisewalkthrough moved out or went to the docs site.CD-297 — verified, no change needed
The claim that
cofferdam doctornames checks to disable against a Biome or ESLint config is true.doctor.rscheck 10 detectsbiome.json/biome.jsoncand ten eslint config filenames, and lists six overlapping checks. Kept, reworded to active voice.Mobile diagrams
CD-296 asks that diagrams read on phones. The
quadrantChartwas the worst offender — fixed aspect ratio, unreadable labels at narrow widths — and is now a two-by-two table. The remaining landing-page diagram isflowchart TB, which reflows. Net: three mermaid diagrams down to two.Verification
vitepress buildclean; dead links fail the build by default, so every internal link is checkedcofferdam gen-docs --checkexits 0Style
Economist style guide throughout, per CD-299: active voice, sentence-case headings, no serial comma, US spelling to match the existing pages.
🤖 Generated with Claude Code
https://claude.ai/code/session_019afugU2bTYCtXn6Vy9dn1v