Add top-level `adcs` Typer aggregator CLI (deferred from WP1)

[mzargham]

Context

WP1 of the active roadmap (planning file /Users/z/.claude/plans/i-want-to-continue-atomic-lobster.md) introduces Typer as the demo's CLI framework and migrates every existing argparse entry point (pipeline.runner, interrogate.explain, interrogate.reproduce) plus the new interrogate.rerun to Typer apps.

During WP1 planning we considered also adding a top-level adcs Typer aggregator — a single console-script entry point that exposes the per-module commands as subcommands (e.g. adcs pipeline run, adcs interrogate rerun). This was deferred. This issue tracks the deferred work so it doesn't quietly disappear.

Why it was deferred

1. WP1 scope is already substantial. WP1 ships nine commits across pipeline refactor, query helper, URI builders, a discipline-driven rename pass, Typer migration of four modules, the new rerun.py + tests, openCAESAR prose cleanup, and docs. Adding the aggregator stretches scope without unblocking downstream work.
2. The aggregator's subcommand shape is sensitive to entry points that don't exist yet. WP4 (three-remote architecture) will add Flexo materialization commands; WP3 may surface an evidence-by-image query CLI. Designing the subcommand hierarchy now would lock in a shape we'd likely revisit. Designing it once after WP4 is more honest.
3. Per-module Typer apps already deliver the value WP1 promised. uv run python -m pipeline.runner, uv run python -m interrogate.rerun, etc. work fine after WP1 with rich Typer-generated help. The aggregator is ergonomic sugar (adcs pipeline run vs python -m pipeline.runner), not capability — and the no-aggregator surface is the one stakeholders see at the OpenMBEE talk and the 2026-06-12 JAXA workshop.
4. No external blocker. WP3 and WP4 can be planned and shipped without the aggregator; the roadmap's sequencing does not depend on it.
5. Aggregator design has real decisions to make (see acceptance criteria below) — naming, console-script entry-point packaging, whether uv tool install exposes `adcs` globally, backwards-compat with per-module invocations. These deserve their own design pass rather than being squeezed into WP1.

When to revisit

• After WP4 lands (three-remote architecture) — the full canonical CLI surface is visible only after Flexo materialization commands exist.
• Or sooner if WP5 (storyboard integration) or user feedback during the 2026-06-12 JAXA workshop surfaces a strong need for a single-entry-point surface.

Acceptance criteria for the eventual implementation

• New module (e.g. adcs/cli.py or pipeline/cli.py) containing a typer.Typer() aggregator app.
• Subcommand tree decided and documented. Tentative shape:
  • `adcs pipeline run` → existing `python -m pipeline.runner`
  • `adcs interrogate explain` → existing `python -m interrogate.explain`
  • `adcs interrogate reproduce` → existing `python -m interrogate.reproduce`
  • `adcs interrogate rerun` → existing `python -m interrogate.rerun`
  • Plus any commands WP3 / WP4 add (e.g. `adcs compute reproduce`, `adcs flexo materialize`).
• [project.scripts] entry added to pyproject.toml: adcs = "<module>:app".
• `uv run adcs --help` and `uv tool install` paths both work.
• Backwards compatibility preserved — every `uv run python -m ` invocation continues to work unchanged so prior docs / scripts / training material still run.
• README and CLAUDE.md updated to document the new top-level entry point; per-module entry points kept as documented alternatives.
• Tests under tests/test_cli.py extended with typer.testing.CliRunner smoke tests for the aggregator (top-level `--help`, each subcommand routes correctly, subcommand `--help` text matches per-module help).
• Validation/verification discipline respected throughout (no "validate" labels for automated checks).

Out of scope

• Replacing the per-module entry points (would break existing docs and the principle that per-module CLIs stay independently runnable).
• Building a separate Click-based or argparse-based aggregator (Typer is the standard per the repo's CLI convention).
• Changing flag semantics on any existing CLI.

References

• Roadmap section: "WP1 — Pipeline cleanup + rerun surfacing", §4.6 "Typer adoption + argparse migration" — the per-module migration that makes this aggregator a small follow-up rather than a from-scratch design.
• WP1 subplan §10 "Known follow-ups" — points at this issue.
• Related: any future WP4 issue that proposes Flexo materialization commands should reference this issue so its commands land into the aggregator's subcommand tree.