doc generator: flat doc/api output produces broken cross-directory and anchored links in generated HTML

[krukow]

_{Generated via Copilot on behalf of @krukow}

Problem

The bb docs generator emits all HTML into a flat doc/api/ directory but does naive, inconsistent .md→.html link rewriting on the rendered hub page (doc/api/index.html):

• Cross-directory links such as auth/index.md, mcp/overview.md, guides/custom-agents.md are rewritten to auth/index.html etc., but no doc/api/auth/, doc/api/mcp/, or doc/api/guides/ subdirectories exist — so they 404 in the generated HTML.
• Anchored links (reference/API.md#streaming, …) keep their .md extension in the generated HTML, even though the target renders to doc/api/API.html (flat).

This was surfaced by Copilot Code Review on #141 (threads on doc/api/index.html lines 16 and 34).

Why it is out of scope for PR #141

• The canonical source hub (doc/index.md) uses correct relative markdown links that resolve on GitHub and pass bb validate-docs (17 files, 0 warnings).
• The flat-output / link-rewriting behavior is pre-existing — the Guides links are byte-identical on main (predate the upstream-sync PR). PR feat: sync upstream copilot-sdk v1.0.4 (CLI schema 1.0.65) #141 only regenerated the HTML; it did not introduce the pattern.
• Generated doc/api/*.html are build artifacts; hand-editing them would be overwritten on the next bb docs run. The real fix belongs in the doc generator (bb docs), not in the artifact.

Suggested fix

Update the doc generator to either (a) preserve the source directory structure under doc/api/ so cross-directory links resolve, or (b) rewrite intra-doc links (including anchored ones) consistently to the flat *.html targets it actually produces. Then extend bb validate-docs to also check generated-HTML internal links, not just the markdown sources.