feat(cli): bernstein integrations list - enumerate wired-in adapters (#1496)

* adapters: add use-case metadata module for end-user copy

Per-adapter end-user copy (headline, binary, optional details, optional
docs path) lives in src/bernstein/adapters/use_cases.py alongside the
adapter implementations. Single source of truth in the adapters package
so a separate top-level docs/integrations.md is not needed.

Used by the upcoming bernstein integrations list command. Adapters
without an entry will fall back to the first line of the module
docstring.

* feat(cli): add bernstein integrations list command

Bernstein ships 40+ adapters under src/bernstein/adapters/ but the only
way for a user to enumerate them is to read the source tree. This adds
a top-level integrations group with a list subcommand that surfaces the
adapter registry directly.

Flags:
- (no flag) one-line summary per adapter (name + headline use case)
- --details per-adapter block with binary, config knob, docs link
- --json stable machine-readable payload for CI dashboards
- --installed filter to adapters whose binary is on $PATH

Per-adapter copy is pulled from bernstein.adapters.use_cases so the
description lives next to the adapter code, not in a parallel doc.
When an adapter has no curated entry the first line of its module
docstring is used so newcomers still appear with a sensible summary.

Tests under tests/unit/cli/test_integrations_list.py cover the default
table view, --details, --json, --installed filtering, unknown
subcommand handling, the synthetic generic adapter, and the no-em-dash
style check on curated copy.

* docs(adapters): add integrations index page and README pointer

New docs/adapters/index.md lists adapter categories with examples and
links to the source-of-truth metadata in
src/bernstein/adapters/use_cases.py. The page does not re-list every
adapter so it cannot drift; for the full enumeration it points at the
CLI.

README install section gains a one-liner so newcomers discover
bernstein integrations list --installed right after install.

* chore(ci): regenerate contract drift allow-lists

Auto-applied by contract-drift-autofix.yml on PR #1496.
Regenerated via scripts/regen_contract_drift.py. Refs #1273.

Source CI run: https://github.com/sipyourdrink-ltd/bernstein/actions/runs/26091497329

* docs(agents-md): sync use_cases.py entry across CLI hint files

Resolves AGENTS.md cross-CLI sync drift detected by repo-hygiene.

* ci: re-trigger after adding macos-needed label

---------

Co-authored-by: auto-heal-fixup <auto-heal-fixup@bernstein.local>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

.cursor/rules/module-map.mdc

@@ -132,6 +132,7 @@ alwaysApply: false
 | `report.py`                | Adapter conformance + capability report |
 | `rovo.py`                  | Atlassian Rovo Dev CLI adapter |
 | `skills_injector.py`       | Inject per-task Claude Code skills into the worktree before spawn |
+| `use_cases.py`             | Per-adapter metadata for the ``bernstein integrations list`` command |
 | `ci/`                      | CI system adapters for log parsing and failure extraction |
 
 ### `src/bernstein/agents/` — agent catalog & discovery

.goosehints

@@ -133,6 +133,7 @@ Bernstein is named after Leonard Bernstein, the American conductor and composer.
 | `report.py`                | Adapter conformance + capability report |
 | `rovo.py`                  | Atlassian Rovo Dev CLI adapter |
 | `skills_injector.py`       | Inject per-task Claude Code skills into the worktree before spawn |
+| `use_cases.py`             | Per-adapter metadata for the ``bernstein integrations list`` command |
 | `ci/`                      | CI system adapters for log parsing and failure extraction |
 
 ### `src/bernstein/agents/` — agent catalog & discovery

AGENTS.md

@@ -133,6 +133,7 @@ Bernstein is named after Leonard Bernstein, the American conductor and composer.
 | `report.py`                | Adapter conformance + capability report |
 | `rovo.py`                  | Atlassian Rovo Dev CLI adapter |
 | `skills_injector.py`       | Inject per-task Claude Code skills into the worktree before spawn |
+| `use_cases.py`             | Per-adapter metadata for the ``bernstein integrations list`` command |
 | `ci/`                      | CI system adapters for log parsing and failure extraction |
 
 ### `src/bernstein/agents/` — agent catalog & discovery

CLAUDE.md

@@ -133,6 +133,7 @@ Bernstein is named after Leonard Bernstein, the American conductor and composer.
 | `report.py`                | Adapter conformance + capability report |
 | `rovo.py`                  | Atlassian Rovo Dev CLI adapter |
 | `skills_injector.py`       | Inject per-task Claude Code skills into the worktree before spawn |
+| `use_cases.py`             | Per-adapter metadata for the ``bernstein integrations list`` command |
 | `ci/`                      | CI system adapters for log parsing and failure extraction |
 
 ### `src/bernstein/agents/` — agent catalog & discovery

CONVENTIONS.md

@@ -133,6 +133,7 @@ Bernstein is named after Leonard Bernstein, the American conductor and composer.
 | `report.py`                | Adapter conformance + capability report |
 | `rovo.py`                  | Atlassian Rovo Dev CLI adapter |
 | `skills_injector.py`       | Inject per-task Claude Code skills into the worktree before spawn |
+| `use_cases.py`             | Per-adapter metadata for the ``bernstein integrations list`` command |
 | `ci/`                      | CI system adapters for log parsing and failure extraction |
 
 ### `src/bernstein/agents/` — agent catalog & discovery

README.md

@@ -66,6 +66,8 @@ bernstein init
 bernstein run -g "fix the failing test in tests/test_foo.py"
 ```
 
+See installed integrations: `bernstein integrations list --installed`.
+
 ## sponsor
 
 if bernstein routed a model that saved you a claude bill, $25 covers a month of my coffee.

docs/adapters/index.md

@@ -0,0 +1,84 @@
+# Integrations index
+
+Bernstein ships ready-made adapters for the CLI coding agents under
+`src/bernstein/adapters/`. This page lists every wired-in integration
+with a one-line use case so you do not have to grep the source tree.
+
+The same data is available from the CLI:
+
+```bash
+bernstein integrations list                # one line per adapter
+bernstein integrations list --details      # per-adapter block with config knob
+bernstein integrations list --installed    # only adapters whose binary is on $PATH
+bernstein integrations list --json         # stable JSON for CI dashboards
+```
+
+Per-adapter copy lives in
+[`src/bernstein/adapters/use_cases.py`](../../src/bernstein/adapters/use_cases.py).
+That module is the single source of truth - this page links to it so we
+do not maintain two copies of the same list.
+
+## Selecting an adapter
+
+Set the active adapter through the `cli:` knob in `bernstein.yaml`:
+
+```yaml
+cli: claude            # or any other registry key listed below
+```
+
+Use `bernstein adapters check <name>` to verify conformance for a
+single adapter, and `bernstein adapters list` for a richer view that
+includes source paths and conformance verdicts.
+
+## Categories
+
+The current registry covers four broad categories. Names below match
+the registry keys you pass via `cli:`.
+
+### Mainstream coding agents
+
+These are the most exercised adapters in the test matrix.
+
+- `claude` - Anthropic Claude Code CLI.
+- `codex` - OpenAI Codex CLI.
+- `cursor` - Cursor Agent CLI.
+- `aider` - Aider pair-programming CLI.
+- `gemini` - Google Gemini CLI.
+- `copilot` - GitHub Copilot CLI.
+- `goose` - Block Goose.
+
+### Local and offline
+
+For air-gap or BYO-model scenarios.
+
+- `ollama` - drives Aider against an Ollama or OpenAI-compatible server.
+- `gptme` - local-first coding agent with shell tools.
+- `mock` - test stub, no API keys or network.
+- `generic` - wrap any coding agent CLI by command string.
+
+### Specialised adapters
+
+- `iac` - infrastructure-as-code (Terraform / Pulumi) with plan-before-apply.
+- `clm` - sovereign LLM gateway over mTLS for regulated deployments.
+- `cloudflare` - Cloudflare Agents SDK via wrangler.
+- `openai_agents` - in-process OpenAI Agents SDK v2 (requires the
+  `[openai]` extra).
+
+### Other supported CLIs
+
+See `bernstein integrations list` for the full enumerated set. The
+registry currently surfaces ~40 adapters; this page lists categories
+rather than re-listing each entry so the index does not drift.
+
+## Adding a new adapter
+
+1. Add a `<name>.py` module under `src/bernstein/adapters/` implementing
+   `CLIAdapter`.
+2. Register the class in `src/bernstein/adapters/registry.py`.
+3. Add an entry to `src/bernstein/adapters/use_cases.py` so the new
+   adapter shows up in `bernstein integrations list` with a meaningful
+   headline.
+4. Cover the adapter with a conformance test under `tests/contract/`.
+
+The contract for new adapters lives in
+[ADAPTER_GUIDE.md](./ADAPTER_GUIDE.md).