fix(docs): make the documentation build reach a page, then pass strict

[livingstaccato]

docs.yml has failed every time it has run, most recently 2026-04-21, and never reached a page. Two failures stacked; the third piece is in provide-foundry.

1. The build died at config load

mkdocs.yml:2 is INHERIT: .provide/foundry/base-mkdocs.yml, and .gitignore:408 excludes .provide/foundry/ because it is an extract of provide-foundry, not source of ours. Nothing in a checkout creates it:

Error: Inherited config file '.provide/foundry/base-mkdocs.yml' does not exist

It exists on a developer machine, which is exactly why this looked like a link problem locally and was nothing of the kind. Reproduced by building from git archive HEAD into a clean tree, which fails with that line verbatim — the same line in the CI log for this PR's parent.

extract_base_mkdocs() in provide-foundry already writes it: the base config, the theme custom_dir points at, the shared partials, the helper scripts, and gen_ref_pages.py. It is now a docs dependency, and scripts/extract_docs_scaffolding.py runs before mkdocs.

The two mkdocs steps became uv run one-liners rather than activate-and-run blocks, per the no-inline-scripts rule. The extraction lives in scripts/ beside sbom_from_wheel.sh, which release.yml already invokes the same way.

2. The nine warnings underneath

Unreachable until now — the reference generator never ran, so mkdocs never rendered a page that could raise them.

Five are Google-style Raises: entries written as prose, which griffe cannot parse into an ExceptionType: description pair. Four name the exception they re-raise; the fifth (scoped_cache.py:84) documented the absence of exceptions, which is not what a Raises: section is for, and is removed rather than reworded.

hub/decorators.py:118 documented force_options as a parameter of register_command, which has no such parameter. It is not stale documentation: cli/click/commands.py:65 reads it out of info.metadata, so it arrives through **metadata and works. Moved to where it actually lives.

docs/reference/index.md linked hub/container/index.md, but container is a module rather than a package, so the generator emits container.md. Its "Full Module Index" link pointed at the built URL SUMMARY/; mkdocs validates against source filenames, and SUMMARY.md resolves to the same page.

Also gitignores the generated reference tree — mkdocs-gen-files keeps it in a temp overlay during a build, but running gen_ref_pages.py directly writes 351 files into docs/ for real.

Verified end to end

From git archive HEAD into a clean tree, running CI's exact sequence:

$ python scripts/extract_docs_scaffolding.py
✅ Docs scaffolding extracted to .../.provide/foundry
$ mkdocs build --clean --strict
EXIT=0   warnings: 0   reference pages: 353

Before: config-load failure. With scaffolding but the old generator: 1 page, 91 warnings.

⚠️ This does not turn the workflow green by itself

The extracted gen_ref_pages.py never invokes itself — provide-foundry#3. No provide-foundry release carries that fix yet (0.4.0 is the only published version), so CI here will still extract the broken generator and fail on the 91 warnings.

Order: merge provide-foundry#3 → release provide-foundry 0.4.1 → this goes green. The verification above used the fixed generator to prove that.