docs: validate landing-page demo asset and CTAs

[aram-devdocs]

Spec

Fixes #63

Summary

• rebase PR docs: validate landing-page demo asset and CTAs #185 onto main after docs: add landing demo asset and CTA verification #184 landed the public landing-page demo and CTA copy
• keep docs: validate landing-page demo asset and CTAs #185 focused on a deterministic cargo xtask validate-landing-page gate for the merged landing page
• validate the checked-in demo asset on main, reject remote embeds, verify the local HTML demo source, and verify the install CTA anchors resolve to local docs targets
• leave book.toml, domain, and CNAME unchanged; do not treat deployed-root acceptance as complete while https://plumb.dev/ still returns HTTP 403

Test plan

• cargo xtask validate-landing-page
• cargo test -p xtask
• cargo fmt --check
• cargo clippy -p xtask --all-targets -- -D warnings
• cargo clippy --workspace --all-targets -- -D warnings
• git diff --check
• CTA verification covered by the validator
• No final diff under docs/src/**, so no humanizer/banned-phrase rerun was needed

Notes for reviewers

• main already contains the public-facing landing-page asset and CTA copy from docs: add landing demo asset and CTA verification #184; this PR now changes only xtask/src/main.rs.
• The validator targets the merged landing page as it exists on main today, including docs/src/demo-terminal.svg and the current install CTA anchors.
• https://plumb.dev/ still returns HTTP 403, so this PR does not claim deployed-root acceptance.

Breaking change?

• No
• Yes — describe the migration path

[github-actions]

All checks complete. Here is the review.

---

Review: commit 02840fc — test: cover local markdown link validation

Files changed: Cargo.lock, xtask/AGENTS.md, xtask/Cargo.toml, xtask/src/main.rs

All changes are confined to the xtask dev-tool crate. This is a CLI binary, not a library, so the library-level hard rules (thiserror, no-anyhow, etc.) do not apply here.

---

1. Determinism

No violations. The new functions are pure functions of file content. Output messages include demo_size (file metadata) and links.len() (count) — both are derived deterministically from checked-in assets. No HashMap/HashSet, no wall-clock, no randomness introduced.

2. Workspace layering

• xtask/src/main.rs:10 — #![forbid(unsafe_code)] is present and unchanged. ✓
• writeln!(std::io::stdout(), …) is the pre-existing xtask idiom that sidesteps clippy::print_stdout (which only flags print!/println!). Consistent with every other xtask output site. ✓
• tempfile correctly placed under [dev-dependencies] in xtask/Cargo.toml. ✓
• No new internal crate dependencies. ✓

3. Error handling

• xtask/src/main.rs:333 — unwrap_or_else(|| Path::new(".")) provides a sensible fallback; not a bare unwrap. ✓
• All .expect(…) calls are inside #[test] functions. ✓
• anyhow::bail! and .with_context(…) used consistently throughout. ✓

4. Test coverage

All helpers have direct unit tests:

Helper	Test
markdown_anchor_slug	heading_slug_matches_install_anchor_shape
extract_markdown_links	extracts_markdown_links_outside_code_fences
extract_html_sources	extracts_html_sources, ignores_html_sources_inside_code_fences
collect_markdown_anchors	collects_heading_anchors_outside_code_fences
validate_no_remote_embeds	rejects_remote_embeds, ignores_remote_embeds_inside_code_fences
validate_local_markdown_link	validates_local_markdown_link_when_file_and_anchor_exist, rejects_local_markdown_link_when_anchor_does_not_match

Confirmed that ~~~ fence style does not appear anywhere in docs/src/, so the ```-only toggle is not a gap in practice.

5. Documentation

All added items are private functions or clap enum variants; no new pub items requiring rustdoc. Cmd::ValidateLandingPage carries the required clap doc comment. xtask/AGENTS.md updated accurately.

---

Punch list

Nothing blocking. One advisory item:

• xtask/src/main.rs:~290 — validate_no_remote_embeds(path: &Path, src: &str): the second parameter holds file content, not a source URL. The name src is ambiguous alongside the function body's use of src for embed src= attributes. Not a correctness issue; rename to content would improve readability, but this is an xtask private fn and the scope is small.

---

Verdict: APPROVE