feat: assemble the published site from declared content roots

[jackye1995]

Phase A1 of the documentation migration. Adds the assembler the site will be built from, and the harness that proves it changes nothing.

What this does

scripts/assemble.py resolves the content roots declared in assemble.yaml, validates them, and emits the published tree. There is one root today — this repo's docs/ — and the output is byte-identical to it, verified by diff -rq.

Six stages: resolve → validate → merge → nav → emit → check. The overlay merge and the version writer are stubs with their call sites and data shapes fixed. That is deliberate: later phases add a root by editing assemble.yaml, not by restructuring the script.

roots:
  - name: oss
    path: docs
    role: reference
  # later:  { name: lancedb, path: ..., role: reference }
  # later:  { name: sophon,  path: ..., role: overlay   }

The harness

CI checks one invariant on every pull request:

mint export (assembled tree)  ==  mint export (docs/ directly)

Both sides are exported from the same commit in the same run, so the check cannot go stale the way a stored baseline can. scripts/compare_exports.py normalizes the per-build UUIDs Mintlify regenerates each run, and quarantines only reference pages that failed to generate request examples at all — a quarantine that retires itself once those pages render.

On main, the assembled tree is force-pushed to the assembled branch. Nothing serves from it yet.

What green does and does not mean. With one root and no anchors, the assembler is close to a structured copy, so passing proves the plumbing, not the merge logic — which has nothing to exercise it until the overlay phase. Building the harness before the thing it must catch is the right order, but this is not the assembler proven.

The REST reference is fixed

The OpenAPI spec is now tracked at a release tag rather than committed by a bot, and make check-spec fails if the two drift.

Syncing to lance-format/lance-namespace@v0.12.0 fixes the endpoint pages. Today 43–48 of the 55 render "A valid request URL is required to generate request examples" instead of cURL/Python/JavaScript samples, and which ones fail varies per build. All 55 render after this change, with real URLs.

Validators

Each was negative-tested rather than assumed:

• duplicate anchors on a page → build fails
• navigation referencing a missing page → warning
• an overlay with no reference page → build fails
• two reference roots claiming one path → build fails, rather than last-writer-wins
• output paths escaping the output directory → build fails

Not in this change

Mintlify still serves the frozen deploy-freeze branch. Repointing it at assembled is the cutover, and it is deliberately a separate, deliberate step — it will be the first thing to reach users since the freeze, carrying every queued documentation pull request and the REST fix at once.