docs: publish repo Markdown as an mdBook site

[oxfern]

Rebuilt on mdBook. The earlier Mintlify version is in the history of this branch; the review comment above explains why it was wrong.

What this does

Publishes the Markdown already tracked in this repo as a browsable book. The Markdown stays the source of truth — docs/book/ holds only book.toml and the script that assembles it.

74 pages, including all 16 NIPs.

Pages are discovered, not listed

Every tracked .md file is published unless it matches EXCLUDE, so a new document appears in the book by existing. An explicit include list fails silently — a file nobody remembered to add is indistinguishable from one that was never written.

That is not hypothetical. The first draft of this PR used a hardcoded manifest, published 45 of 105 tracked files, and consequently claimed "all 15 NIPs" in its description. There are 16: NIP-AB (Device Pairing) lives at crates/buzz-core/src/pairing/NIP-AB.md rather than under docs/nips/, so a manifest built by globbing one directory never saw it. Discovery finds it:

EXCLUDE covers machine-facing Markdown — agent instructions, prompt fragments, persona definitions, skill manifests, issue templates, test fixtures. Placement comes from SECTIONS, an ordered pattern list. Anything matching no rule is still published under Unsorted and named on stdout; --check makes that a build failure, which is what CI runs. Section ordering is derived from SECTIONS itself, so there is no second list to fall out of sync.

Files keep their repo paths

Documents are copied into src/ at their original paths, so relative links between them resolve unchanged and mdBook rewrites .md to .html at build time. No link rewriting, no route table.

Three cases still need handling, in resolve_links(): links to a README.md are rewritten to index.md because mdBook renders READMEs as index.html; links to excluded files are repointed at GitHub, where they do exist; anything else is already broken in the repo and is reported rather than rewritten.

That report currently lists 36 links, all the same class — bare-number references to the upstream nostr-protocol NIPs repo (01.md, 44.md, and similar), across NIP-AB, NIP-ER, NIP-RS and others. They do not resolve on GitHub either, so this is pre-existing and worth a separate PR. The build surfaces them without failing on them.

Publishing is no longer gated

The previous version needed an opt-in variable because Mintlify's export hardcodes root-absolute asset paths and cannot be served from block.github.io/buzz/. mdBook emits relative paths — a nested page references ../css/general.css — so it works from a subpath. mdBook's own docs are served that way, at rust-lang.github.io/mdBook/.

So the workflow writes the book into a /book/ subdirectory of the branch Pages already serves:

https://block.github.io/buzz/        legal pages, unchanged
https://block.github.io/buzz/book/   this book

No change to the Pages source, no custom domain, no DNS, and index/privacy/support/terms are untouched. It also drops the Node toolchain for a Rust binary, which suits the repo. cargo doc for API reference is a separate concern this PR does not touch — there is currently no rustdoc config or #![doc = include_str!] anywhere, so that is open ground.

Verification

Built locally and served from a subpath with a placeholder site at the root, to reproduce the block.github.io/buzz/ layout. Screenshots above are that build rendered in a browser, not checked by status code. Crawling rendered links across the home page, architecture, a NIP, a crate README and a nested README: 39 links, the only failures being the 5 pre-existing upstream-NIP references described above. build.py --check exits 0.

[oxfern]

Moving this to draft — two problems with the approach, both worth stating plainly.

The page list is hardcoded, and it silently drops things. PAGES in build.py is an explicit manifest, so anything not listed never appears and nothing warns. This repo tracks 105 Markdown files; the manifest publishes 45. Most of the gap is correctly excluded (skill files, issue templates, test fixtures), but not all of it — desktop/README.md, mobile/README.md, crates/buzz-persona/PERSONA_PACK_SPEC.md, crates/buzz-conformance/{LIMITS,TRACE_SCHEMA}.md, docs/formal/**, and examples/** are all real docs that fall through.

The clearest case: the description above says "all 15 NIPs", and that is wrong. There are 16. NIP-AB (Device Pairing) lives at crates/buzz-core/src/pairing/NIP-AB.md, not under docs/nips/, so a manifest built by globbing one directory never saw it. A hardcoded list turned a missing file into a confident false claim, which is the strongest argument against the design.

Mintlify is likely the wrong tool for a Rust monorepo. mdBook is the ecosystem norm for prose docs — the Rust Book, the Cargo Book and the rustc dev guide all use it — and it removes the constraint this PR was built around. mdBook emits relative asset paths, so it serves correctly from a subpath; its own docs live at rust-lang.github.io/mdBook/, which is a project Pages URL. Verified locally: a nested page references ../css/…, not /css/….

That changes the deployment story completely. Because mdBook tolerates a subpath, the book can be published into a subdirectory of the existing pages branch, leaving index/privacy/support/terms untouched at the root. No switch of the Pages source, no custom domain, and none of the opt-in gating this PR needed. It also drops the Node toolchain in favour of a Rust binary, which fits the repo, and cargo doc covers API reference separately.

I'd rather reopen this built on mdBook with a generated page list than have anyone review the current shape. Leaving it in draft meanwhile.