docs: remove stale blog, complete config reference, sweep dead PRD refs - #276
Merged
Conversation
The launch-v0.6.md post is from a previous version of the project (current release is v0.0.11) and was the first chapter visitors saw in the sidebar. Owner has confirmed the project does not want a blog. Drop the post, the empty blog directory, and the SUMMARY entry.
The Release Prep chapter records release-engineering bookkeeping (Homebrew tap activation, npm token rotation, dist-workspace channel maintenance) that does not belong in user-facing docs. Drop the page and its SUMMARY entry; this content lives in repo-internal notes.
…rhythm, ignore Five active config sections were missing from configuration.md even though their consuming rules ship in the engine: - `[shadow]` is read by `shadow/scale-conformance`. - `[z_index]` is read by `z/scale-conformance`. - `[opacity]` is read by `opacity/scale-conformance`. - `[rhythm]` is read by `baseline/rhythm`. - `[[ignore]]` is the selector-scoped runtime suppression list. Mirror the existing field/type/default table format and update the top-level shape index so every section is listed.
The rule shipped with a registered docs page but was never listed in the overview's bullet catalog. Insert it in alphabetical-by-id order between `a11y/touch-target` and `color/contrast-aa`.
Every rule page's "See also" section linked to a `PRD §…` location. The PRD lives in `docs/local/` which is gitignored, so the references 404 for any external reader. A handful of inline-prose mentions (radius, spacing, sibling-height) referenced PRD section numbers that also do not resolve publicly. Drop the PRD bullets and reword the inline references so the prose stands on its own. The MCP-served rule docs and the mdBook source are the same files (book pages are symlinks into `crates/plumb-mcp/rule-docs/`), so the change covers both surfaces in one diff.
- introduction.md: drop the duplicate "Next" navigation list at the bottom; fold its targets into the single workflow-targeted list above so visitors see one curated path forward. - faq.md: replace the long "How do I integrate Plumb into GitHub Actions CI?" body with one sentence and a crosslink to the GitHub Code Scanning chapter, which already documents the full workflow. - ci/reviewdog.md: collapse the duplicated "copy contrib/reviewdog- plumb.yaml" instruction into a single mention near the top. - cli.md: replace the `<N>/<M>/<T>` placeholders in the `plumb watch` status line with concrete sample numbers. - cli/suggest-ignores.md: change the example `plumb_version` from `0.0.1` to `0.0.x` so the snippet doesn't pin a stale version.
This reverts commit e8a3625. The install-smoke validator (`tests/install-smoke-validate.sh`) hard-references this page to verify the #51 / #52 release-engineering checkpoints, so deleting it breaks `just validate`. Reinstate the page and its SUMMARY entry until the validator is migrated to a different source of truth.
Owner
Author
|
Wrong head branch — peer agent switched the working tree under me at PR-creation time. Recreating against the correct branch. |
aram-devdocs
changed the title
Contributor
|
I have all the information I need. Let me now write the full review. PR 276 — docs: remove stale blog, complete config reference, sweep dead PRD refsScope: docs-only. No Rust source changes. Determinism, layering, unsafe, and error-handling checklist items are N/A. 1. Determinism — N/A (no Rust changes)2. Layering — N/A (no Rust changes)3. Error handling — N/A (no Rust changes)4. Test coverage — N/A (docs only)5. DocumentationI cross-checked every new
All rule IDs cited in the "Consumed by" lines match the actual
Humanizer pass (required for any Specific items verified:
Punch listNothing blocks. No substantive issues found. Verdict: APPROVE |
6 tasks
3 tasks
aram-devdocs
added a commit
that referenced
this pull request
May 8, 2026
… strip) (#287) * chore: re-delete release-prep.md + drop its install-smoke-validate guard PR #276 had to revert the deletion of docs/src/ci/release-prep.md because tests/install-smoke-validate.sh greps the file for "Issue #51 verified" and "Issue #52 wired" sentinel strings. Those issues are now resolved (Homebrew tap and unscoped npm publish both ship as of 0.0.10/0.0.11), so the doc page is internal noise that doesn't belong in the public book. This commit removes both the page (already deleted via git rm in the same working tree) and the guard that referenced it. * fix(release): strip wrong-arch Windows ARM64 mapping from npm tarball cargo-dist 0.28.0 emits an aarch64-pc-windows-msvc entry in the npm package's supportedPlatforms that points to the x86_64 Windows zip. On Windows ARM that silently installs the wrong arch. The npm-publish job now extracts the tarball, removes the bad mapping from package.json via a node one-liner, repacks, and publishes. When cargo-dist ships a filter knob or we add a real Windows ARM64 target, the strip step can come out. Closes audit finding H7.
4 tasks
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.
Summary
Blogchapter inSUMMARY.md.configuration.md:[shadow],[z_index],[opacity],[rhythm],[[ignore]]. Each is consumed by an active rule but was previously undocumented.baseline/rhythmto the rules-overview index (the rule shipped with a docs page but was never listed).PRD §…references from all 16 rule pages (PRD lives indocs/local/which is gitignored, so the references 404 for external readers). Inline-prose mentions in radius / spacing / sibling-height pages are reworded so the prose stands on its own.Nextsection inintroduction.md, oversized FAQ item 12,reviewdog.mdduplicated copy-instruction,cli.mdwatch-mode placeholder example,cli/suggest-ignores.mdstaleplumb_version.Why
From the public-surface audit. Closes audit findings B3, H9, H10, H11, H12, H13, H14, AS1, AS2, AS3, AS4.
Deviations
docs/src/ci/release-prep.mdto be deleted as well, buttests/install-smoke-validate.shhard-references the page (it greps forIssue #51 is verified in this repo state.andIssue #52 is wired in this repo state.to assert the install-smoke feat(release): plumb-dev/homebrew-tap + cargo-dist wiring #51/feat(release): @plumb npm org + @plumb/cli wrapper package #52 checkpoints). The validator is out of scope for this PR (modifying it was rejected as scope escalation), so the deletion was reverted in-branch and the page is left in place. The history shows both the deletion and its revert as separate commits to keep the trail honest. Migrating the install-smoke validator to a different source of truth and re-deleting the page should be a follow-up PR.docs/site-truthfulness-passwas also used by a peer agent for PR 4 (npm README rewrite); this PR (docs: remove stale blog, complete config reference, sweep dead PRD refs #276) was originally opened with that peer's title and body. The branch is now this PR's content. The peer's PR 4 work is presumably tracked elsewhere.Test plan
mdbook buildsucceeds without warnings.grep -rn 'PRD §' docs/src/returns zero matches.cargo xtask sync-rules-indexreports16 built-in rule(s); all have docs pages.just validatepasses end-to-end (all gates).