chore(docs): remove VitePress tooling

[flyingrobots]

Summary

• remove active VitePress docs-site scripts, Make targets, config, and browser-open helper
• drop VitePress, VitePress Mermaid plugin, and Mermaid dependencies from package.json / pnpm-lock.yaml
• update active docs and xtask dead-ref handling so docs root logic no longer depends on .vitepress config

Verification

• cargo fmt --all -- --check
• cargo check -p xtask
• cargo test -p xtask root_relative_link_resolves_against_docs_root
• pnpm run schema:runtime:check
• pnpm exec prettier --check package.json AGENTS.md CHANGELOG.md docs/workflows.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md docs/design/witnessed-suffix-admission-shell.md docs/design/witnessed-suffix-admission-evaluator.md docs/design/0018-echo-optics-api-design/design.md
• pnpm exec markdownlint-cli2 AGENTS.md CHANGELOG.md docs/workflows.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md docs/design/witnessed-suffix-admission-shell.md docs/design/witnessed-suffix-admission-evaluator.md docs/design/0018-echo-optics-api-design/design.md
• git diff --check
• ./scripts/check_spdx.sh

Note: pnpm run schema:runtime:check passed with the existing Node v26 engine warning.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 6 minutes. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: adf51ce2-7ac1-4caf-bbd5-0c3675659830

📥 Commits

Reviewing files that changed from the base of the PR and between cfb9f21 and e0f31d2.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (14)

• AGENTS.md
• CHANGELOG.md
• Makefile
• det-policy.yaml
• docs/.vitepress/config.ts
• docs/design/0018-echo-optics-api-design/design.md
• docs/design/wip-branch-policy.md
• docs/design/witnessed-suffix-admission-evaluator.md
• docs/design/witnessed-suffix-admission-shell.md
• docs/method/HANDOFF.md
• docs/workflows.md
• package.json
• scripts/docs-open.sh
• xtask/src/main.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch housekeeping/remove-vitepress-docs-site

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flyingrobots]

@codex self-review findings for confirmation.

Severity	File / line	Infraction	Evidence	Recommended mitigation prompt
Medium	docs/design/wip-branch-policy.md:373	Invalid documented verification gate	The branch updates this verification block to remove the retired docs-site build, but the remaining command cargo test -p xtask --lib hook cannot run because xtask has no library target. Local evidence: cargo test -p xtask --lib hook exits with error: no library targets found in package xtask. cargo test -p xtask hook is also not a safe replacement because it passes while running 0 tests.	Update the WIP branch-policy verification block to remove or replace cargo test -p xtask --lib hook. Use an existing nonzero binary-test filter such as a focused preflight test slice, or explicitly mark future hook tests as TBD until they exist. Rerun Prettier and markdownlint for the touched doc.
Medium	xtask/src/main.rs:5948; tests around xtask/src/main.rs:6741	Missing direct regression coverage for the new docs-root discovery rule	The implementation changed find_docs_root from .vitepress/config.* discovery to walking for an ancestor named docs, but the existing root-relative tests manually pass Path::new("docs") into build_candidates; they do not exercise find_docs_root itself. A regression in ancestor discovery would not be caught by root_relative_link_resolves_against_docs_root.	Add unit tests for find_docs_root: starting at docs, starting at a nested docs path such as docs/design, and a non-doc fallback path. Keep the existing build_candidates tests, then run cargo test -p xtask find_docs_root or the full cargo test -p xtask.
Low	CHANGELOG.md:593-595	Changelog overstates a committed repository change	The new entry says generated site residue was removed, but the committed diff deletes tracked config and dependencies; generated .vitepress output was local untracked residue, not a versioned artifact removed by the merge. Changelog should describe merge-visible repository behavior.	Tighten the changelog entry by removing generated site residue or rephrasing to only name committed removals: scripts, Make targets, tracked config, browser-open helper, and dependencies.
Low	Makefile:50	Section boundary collapsed after target deletion	Removing the docs targets leaves # Benchmarks and reports immediately after the dags-fetch recipe without a separating blank line. This is valid Make syntax but below the surrounding readability style.	Insert a blank line between the dags-fetch recipe and the # Benchmarks and reports section header.
Low	docs/method/HANDOFF.md:6	Overlong Markdown status paragraph	The branch appends the new docs-site retirement note to an already long status line. Markdownlint allows it here, but the line is hard to review and contradicts the repo's generally readable prose style.	Wrap the status into two or three short sentences across multiple lines while preserving the historical-handoff meaning.

No critical or high-severity issues found. The branch intent is otherwise satisfied: active VitePress scripts, Make targets, tracked config, dead helper, and dependencies are removed, and active scans only find the new changelog mention plus historical/archive references.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9d5652ce7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

@codex resolved the self-review findings in e0f31d2.

Changes:

• replaced the invalid cargo test -p xtask --lib hook recipe with a real cargo test -p xtask preflight slice
• added direct find_docs_root regression tests for docs root, nested docs path, and fallback behavior
• tightened the changelog wording to only describe committed removals
• restored the Makefile section spacing
• wrapped the historical handoff status paragraph

Verification after the fix:

• cargo fmt --all -- --check
• cargo test -p xtask find_docs_root
• cargo test -p xtask preflight
• cargo check -p xtask
• pnpm exec prettier --check CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• pnpm exec markdownlint-cli2 CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• git diff --check
• ./scripts/check_spdx.sh

[chatgpt-codex-connector]

Summary

• Confirmed the follow-up commit already resolves the invalid documented xtask gate by using cargo test -p xtask preflight instead of the invalid --lib hook command. docs/design/wip-branch-policy.mdL369-L377
• Confirmed find_docs_root still implements the intended ancestor walk and fallback behavior. xtask/src/main.rsL5944-L5960
• Confirmed direct regression coverage exists for docs-root discovery from docs, nested docs paths, and the non-docs fallback case. xtask/src/main.rsL6730-L6778
• Confirmed the changelog now describes only tracked repository removals. CHANGELOG.mdL591-L595
• Confirmed the Makefile section spacing is restored. MakefileL48-L52
• Confirmed the historical handoff status paragraph is wrapped into readable lines. docs/method/HANDOFF.mdL6-L10
• No additional edits were needed, so I did not create a new commit or PR.

Testing

• ✅ cargo fmt --all -- --check
• ✅ cargo test -p xtask find_docs_root
• ✅ cargo test -p xtask preflight
• ✅ cargo check -p xtask
• ✅ pnpm exec prettier --check CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• ✅ pnpm exec markdownlint-cli2 CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• ✅ git diff --check
• ✅ ./scripts/check_spdx.sh
• ✅ git status --short shows the working tree is clean.

View task →

[flyingrobots]

Activity Summary

@codex Code Lawyer closure pass completed for PR #553.

Item	Source	Severity	File / lines	Commit	Outcome
1	PR thread	P3 Medium	docs/design/wip-branch-policy.md:373	e0f31d22	Replaced invalid cargo test -p xtask --lib hook recipe with real nonzero cargo test -p xtask preflight; thread resolved.
2	PR thread	P3 Medium	xtask/src/main.rs:5948; tests near xtask/src/main.rs:6730-6778	e0f31d22	Added direct find_docs_root regression coverage for docs root, nested docs paths, and fallback behavior; thread resolved.
3	PR thread	P4 Low	CHANGELOG.md:593-595	e0f31d22	Removed the overclaim about generated site residue so the changelog only records tracked repository removals; thread resolved.
4	Self-review	P5 Nit	Makefile:50	e0f31d22	Restored blank line before the benchmarks section after docs target deletion.
5	Self-review	P5 Nit	docs/method/HANDOFF.md:6-10	e0f31d22	Wrapped the historical status paragraph into readable lines.

Review-thread closure:

• PRRT_kwDOQH8Wr86KhoPu: resolved
• PRRT_kwDOQH8Wr86KhoPy: resolved
• PRRT_kwDOQH8Wr86KhoP2: resolved

Verification:

• cargo fmt --all -- --check
• cargo test -p xtask find_docs_root
• cargo test -p xtask preflight
• cargo check -p xtask
• pnpm exec prettier --check CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• pnpm exec markdownlint-cli2 CHANGELOG.md docs/method/HANDOFF.md docs/design/wip-branch-policy.md
• git diff --check
• ./scripts/check_spdx.sh
• make verify-pr
• gh pr checks 553 reports all checks passing, including CodeRabbit.

Self-audit result: no new branch-diff issues found after e0f31d22.

[chatgpt-codex-connector]

Summary

• Confirmed PR chore(docs): remove VitePress tooling #553’s closure pass is already present in the checked-out branch: the invalid documented xtask --lib gate has been replaced with the real cargo test -p xtask preflight command. docs/design/wip-branch-policy.mdL369-L377
• Confirmed find_docs_root implements the intended ancestor walk to a docs directory and falls back to the start path when no docs ancestor exists. xtask/src/main.rsL5944-L5960
• Confirmed direct regression coverage exists for starting at docs, from a nested docs path, and from a non-doc fallback path. xtask/src/main.rsL6730-L6778
• Confirmed the changelog now describes only tracked repository removals for the VitePress tooling retirement. CHANGELOG.mdL591-L595
• Confirmed the Makefile section spacing is restored before the benchmarks section. MakefileL48-L52
• Confirmed the historical handoff status paragraph is wrapped into readable lines. docs/method/HANDOFF.mdL6-L10
• No additional file changes were needed. The working tree was clean, so I did not create a commit or call the PR creation tool.

Testing

• ✅ git status --short --branch
• ✅ git log -n 5 --oneline
• ✅ cargo test -p xtask find_docs_root
• ✅ git diff --check
• ⚠️ find backlog/asap -maxdepth 2 -type f -print | sort | head -50 — warning only because backlog/asap does not exist in this repository layout.

View task →