[cscheid]

Summary

Adds q2 docs serve (visible alias q2 docs open). It starts a local web server for the Quarto 2 documentation site embedded in the binary, which is the documentation for exactly the running version. It opens the site in the browser and serves it until Ctrl-C. Nothing is fetched from the network and nothing is written to disk.

q2 docs serve                            # home page
q2 docs open guides/projects/preview     # deep link, same spellings as `q2 docs llms <href>`
q2 docs serve --no-browser --port 4321

An unknown page fails before the server starts, with the same near-miss suggestions as q2 docs llms.

One embed for both docs serve and docs llms

• Staging (cargo xtask build-agents-docs): clears and re-renders docs/_site (q2 render doesn't remove output for deleted pages), then stages the whole site under agents-docs-dist/site/ plus the llms ledger. It now fails if the site loads any remote subresource (new docs_offline_check: HTML subresource tags, <style> blocks, CSS @import/url()). The only allowlisted remote resource is the theme's Google Fonts import; offline, text falls back to the system sans-serif.
• Embedding (crates/quarto/build.rs): a deterministic tar.zst ordered llms-first (metadata, ledger-listed files, then the rest). The 73 MB / 1454-file site compresses to 3.6 MB.
• Runtime (commands/docs_embed.rs): docs llms stream-decodes only the llms prefix; docs serve decodes everything once. include_dir is gone from the quarto crate.
• Server (quarto_preview::static_mode::embedded_site): a small read-only router over in-memory files. It reuses the static server's path-decoding, 404, and redirect helpers but has no reload client, SSE, or pdf.js.

Measured (release build, M-series)

	before	after
q2 docs llms <page> (hyperfine)	3.7 ms	4.8 ms
q2 docs serve launch → first 200	—	~19 ms
docs embed in binary	~1.95 MB raw	3.6 MB tar.zst (≈ +1.6 MB)

Also

• docs/guides/embedded-docs.qmd: new "Reading the docs in a browser" section (retitled "Embedded documentation"); AGENTS.md § embedded docs updated.
• Release workflow: a smoke check that the release binary's docs serve serves the home page (non-Windows legs, since backgrounding and killing a native process from Git Bash is unreliable; the existing --embed-info gate still covers Windows).
• Rename of agents-docs-dist/ / build-agents-docs deferred to bd-7tkifpnh.

Plan with the design assessment and measurements: claude-notes/plans/2026-10-26-q2-docs-serve.md. Braid: bd-x248xpyh.

Test plan

• Unit tests: archive prefix and full decode, llms-first ordering invariant on the real embed, DocsEmbed ported to the decoded map (existing suite unchanged in behaviour; non-ledger site files invisible to docs llms), page → URL mapping, serve/open parse equivalence, router (index, dir redirect, MIME, percent-decoding, traversal 404, HEAD, 405), staging (whole site + ledger, dotfiles skipped, stale clearing), offline scanner fixtures
• Integration tests (docs_serve_cli.rs) pass in both embed states, real and placeholder (verified locally in each)
• cargo xtask verify green (all 14 steps; 17,346 Rust tests) before the rebase onto Rewire hub from samod access-policy fork to upstream samod 0.16.0 #917; after the rebase, the quarto docs tests and quarto-preview router tests were rerun green
• cargo xtask check-noop-rebuild green
• Windows cross-clippy clean for xtask; quarto/quarto-preview can't cross-check from macOS (ring), so they rely on the CI windows-latest clippy leg
• Manual browser check (Chrome): navigation, website search through the real UI, reveal.js example iframes; the only off-host requests are fonts.googleapis.com / fonts.gstatic.com
• Release smoke-check snippet run locally against a release build

🤖 Generated with Claude Code

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.