Maintenance WP3: Sphinx API reference omits sensory/, simulation/, recipes, and the tool layer

[kgdunn]

Work package 3 of 3 from the 2026-07-10 maintenance review

This issue is a complete, self-contained work prompt. Anyone (human or agent) should be able to execute it with no other context. Companion packages: WP1 (issue #448) and WP2 (issue #449) are separate and independent.

Background

docs/api/index.rst currently documents eight subpackages: multivariate, univariate, monitoring, experiments, regression, batch, bivariate, visualization. Missing from the API reference entirely:

• process_improve.sensory (has a user-guide page at docs/user_guide/sensory_panel.rst but no API page)
• process_improve.simulation (mentioned only in prose in docs/architecture.rst and docs/development/reproducibility.rst)
• process_improve.recipes, process_improve.tool_spec, process_improve.config, process_improve.tool_safety, process_improve.mcp_server (the analysis-recipe and MCP/tool layer; described narratively in docs/architecture.rst but with no reference pages)

The docs build is strict: docs.yml runs sphinx-build -W and nbsphinx_allow_errors = False, so every docstring warning in newly documented modules will fail the build and must be fixed.

Task A: add API pages

1. Read one or two existing pages first (for example docs/api/monitoring.rst and docs/api/bivariate.rst) and mirror their exact conventions: heading style, automodule/autosummary usage, :members: options, module ordering.
2. Create docs/api/sensory.rst covering the public surface of src/process_improve/sensory/ (modules: analysis, ingest, mam, panel, recipes, validation, and the subpackage __init__ exports; check __all__ or the __init__.py re-exports to decide what is public).
3. Create docs/api/simulation.rst covering src/process_improve/simulation/.
4. Create docs/api/tooling.rst (single page) covering, in this order: process_improve.recipes, process_improve.tool_spec, process_improve.config, process_improve.tool_safety, process_improve.mcp_server. Caveat: mcp_server imports the optional mcp package at module import time. The docs environment installs all extras (uv sync --dev --all-extras includes the mcp extra) so autodoc should import it fine in CI; verify locally with all extras installed. If it still cannot import, add mcp to autodoc_mock_imports in docs/conf.py rather than skipping the module.
5. Add the three new pages to the toctree in docs/api/index.rst, keeping the existing ordering scheme (append after the current entries unless the file orders alphabetically).

Task B: fix fallout

• Build the docs locally with the strict flags CI uses (see docs.yml; effectively sphinx-build -W -b html docs docs/_build/html or cd docs && make html if the Makefile passes -W). Fix every new warning. Expected fallout class: malformed NumPy-style docstrings in sensory/ and simulation/ (they have never been through autodoc). Fix docstring formatting only; do not change signatures or behavior in this PR.
• If a module exposes objects that produce unfixable warnings (for example pydantic-generated members), scope the directive down (:members: with an explicit list or :exclude-members:) instead of loosening the build.

Version bump and metadata (last commit of the PR)

• Bump PATCH in pyproject.toml relative to current main at execution time (after WP1 and WP2 this is likely 1.52.5; use whatever main says plus one).
• Set CITATION.cff version: identical and date-released: to the current date, same commit.
• No CHANGELOG entry and no heading roll (owner decision recorded 2026-07-10: internal-only batch).

Constraints

• Branch: claude/process-improve-maintenance-review-0lbiru-wp3; one ready-for-review PR, micro-committed (one commit per API page is a good grain).
• Never stage or push lock files.
• No em-dash characters in committed prose (including the new .rst files), commit messages, or the PR description (repo convention).

Verification

1. Local strict docs build passes: zero warnings.
2. Open the built HTML and confirm the three new pages render with populated member listings (not empty shells).
3. uv run pytest still passes (docstring-only changes must not break doctests if any are collected).
4. CI green on the PR, especially the docs workflow.