Generate and publish API reference documentation pages from the configured mkdocstrings handler

[dgenio]

Summary

Add API-reference pages to the MkDocs navigation that render the public symbols via the already-configured mkdocstrings[python] handler, so the hosted docs site includes generated reference for FlowExecutor, Flow, FlowBuilder, the exception hierarchy, and the persistence protocols.

Why this matters

mkdocstrings is installed and configured in mkdocs.yml, but the reference/ nav contains only a hand-written error table — none of the public API is rendered. Users currently read source or scattered guides to learn method signatures. Generated reference is table-stakes for a typed library approaching v1 and directly supports the API-tiering work in open issue #349.

Current evidence

• mkdocs.yml: mkdocstrings plugin is configured (line ~53) but the Reference nav lists only reference/error-table.md.
• chainweaver/py.typed ships and the package is fully type-annotated, so docstring/signature rendering will be high quality.
• Open Tier the public API surface ahead of v1.0 #349 (tier the public API ahead of v1) defines the surface; this issue renders it.

External context

Generated API reference via mkdocstrings/Sphinx autodoc is the standard expectation for typed Python libraries; it pairs with a documented public-API tier.

Proposed implementation

1. Add docs/reference/api/ pages with ::: chainweaver.<symbol> directives for the public surface (executor, flow types, builder, decorators, exceptions, storage/cache/checkpoint protocols, export adapters).
2. Organize by the tier that Tier the public API surface ahead of v1.0 #349 establishes (coordinate; if Tier the public API surface ahead of v1.0 #349 not yet landed, group by module and note the dependency).
3. Wire the pages into mkdocs.yml nav; ensure the docs CI lane (.github/workflows/docs.yml) builds without warnings (consider --strict).
4. Cross-link from the error-table page to the generated exception reference.

AI-agent execution notes

Inspect mkdocs.yml (plugin config + nav), docs/reference/, .github/workflows/docs.yml, chainweaver/__init__.py __all__ (source of truth for the public surface), docs/v1-release-criteria.md. Coordinate with #349 to avoid documenting symbols slated for de-listing. Do not document chainweaver.testing internals beyond the public harness. Keep docstrings as the single source — fix any that render poorly rather than duplicating prose.

Acceptance criteria

• The hosted docs include generated reference for the public API surface, navigable from the nav.
• The docs build passes (ideally --strict) with no missing-reference warnings.
• The exception reference cross-links to the error table.

Test plan

Docs build in CI (mkdocs build --strict); link-check; spot-check rendered signatures for key classes.

Documentation plan

mkdocs.yml nav, new docs/reference/api/* pages, CHANGELOG (docs note); README docs link if appropriate.

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

--strict may surface pre-existing docstring issues (fix incrementally); generated reference must track the public-API tier to avoid documenting internals — sequence with #349.

Suggested labels

documentation, developer-experience