[aicayzer]

Summary

marfa docs now recovers when a search finds nothing, can print one section of a page, and shows a page safely on a terminal. An agent that searched for a word the docs do not use gets the nearest page titles and where every page is listed, and one that needs a single command's section no longer reads a whole page (the changelog alone is 11,854 words).

Closes #2312

Changes

• marfa docs search with no hit prints no docs page matches "<query>", up to five page titles with their paths whose title, path or description hold words of the query (read from the site's topics), and "marfa docs topics lists every page." If the topics cannot be read, the plain miss and that line still print. With --json the answer is the site's {"hits": []} and no topics request is sent.
• marfa docs <page> --section <heading> prints the part of the page under that heading, with the sections inside it. The heading is matched by its text in any case, or by its anchor (the site's [#anchor] or the one made from the text). Headings inside fenced code are not headings. With --json the record gains section.
• An unknown heading exits 1 with the new code docs_section_not_found, naming the page and listing its headings, indented by depth.
• When stdout is a terminal, control characters in a page are shown as \u{..}, as printable shows them for other text; line breaks and tabs stay. When stdout is a pipe, the bytes are exact.
• Contract: device/docs-search-miss, device/docs-search-miss-json, device/docs-section and device/docs-section-missing in conformance/spec/device.md, with one device fixture. The command reference (COMMANDS.md) is regenerated.

Testing

• cargo test -p marfa-cli, cargo clippy -p marfa-cli --all-targets -- -D warnings, cargo fmt --check and pnpm format:check pass.
• Unit tests (matching, sections, anchors, fenced code, terminal text) and four process tests in tests/docs.rs. The device fixture helps a docs search that finds nothing, and reads one section of a page fails with the marfa build from main and passes with this one.
• Tried by hand on a pseudo-terminal against a local page holding ESC[31m, a bell and a carriage return: the terminal shows \u{1b}[31m, \u{7} and \u{d}, and the pipe shows the exact bytes. marfa docs cli --section "Use another keychain file" on the real site printed that section only, and an unknown heading listed the page's headings.
• Not tested: the terminal rule has no conformance fixture, because the suite runs the binary without a terminal. The Rust unit test and the by-hand run hold it.

Notes for reviewers

• The docs page for marfa docs lives in the docs repository and is updated after this merges.
• The nearest titles are a word match, not a ranking model. Search ranking stays in the docs repository, as the issue says.
• Review depth: a read of the new section parser and the contract wording; no data or security path.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.