docs(spec): optional-connector catalog

[jordanrburger]

Design review only — no behavior change. Adds a design spec; implementation follows once the approach is agreed. Generalizes the one-off "Google Messages connector" into a reusable catalog. Companion to #149 (merged) and #150.

Context

Scout ships a fixed default connector set. Adding anything else (e.g. Google Messages for personal texts) means hand-editing three files (connectors.yaml, connector-probes.yaml, phases/connectors/*.md) and knowing how assembly gates on enabled_connectors. There's no way for a user to browse connectors Scout already knows how to drive but doesn't enable by default, and turn one on without that authoring.

The enable mechanism is largely already there — the gap is discovery, a turn-on flow, and a default-off marker.

Proposed design (Approach A — "the roster is the catalog")

1. Data model: extend connectors.yaml entries (+ the Connector loader) with optional: true (default-off; never auto-enabled by detection) and a catalog: block (summary / description / requirements / setup). Orthogonal to tier.
2. Browse: scoutctl connectors catalog [--json] lists optional connectors with enabled/available markers.
3. Enable/disable: enable <key> writes config, collects needs_user_input, prints setup steps, probe-verifies, and re-renders the brain files (additive cat-4 merge → clean) so it takes effect now; /scout-update is the fallback. disable reverts config.
4. Wizard: /scout-setup & /scout-update surface the catalog as an opt-in step (built on the CLI primitive).
5. Seed/proof: Google Messages as the first catalog entry, de-personalized — no contacts ship (vault-only state).

Alternatives B (connector package dirs — for community sharing, scoped out; sizeable refactor) and C (separate catalog manifest — drift) documented and rejected. B is left as a clean future path.

Asking reviewers

• Is "the roster is the catalog" the right call vs. a package format (B)?
• The enable → re-render coupling (enable invokes the cat-4 assembly path): the change is additive so the merge should be clean, with /scout-update as fallback — comfortable with that, or should enable always defer to /scout-update?
• Probe honesty for setup-gated connectors (Google Messages pairing is manual; the probe asserts the browser capability, not readiness).

Spec: docs/superpowers/specs/2026-06-21-optional-connector-catalog-design.md

🤖 Generated with Claude Code

[AdamVyborny]

make sense to me

[jordanrburger]

Folded #172 (email/gmail canonical-key mismatch) into this spec as a precondition of the catalog's key model:

• New §7 Canonical-key invariant — a connector must use one key across all namespaces (probe/detection, config enabled, phase requires:, roster); scoutctl connectors + CI enforce it. A mismatch makes a connector silently un-enableable (the enable <key> flow writes a key the phase gate never matches → sections never render), which is exactly the trap the catalog's turn-key promise must not inherit.
• Calls out the existing mail violation (probe/config gmail vs phase requires: email → the whole email phase is dropped from assembled SKILL.md; verified on a live vault) and recommends standardizing on the provider-neutral email with a gmail alias + idempotent gmail → email config normalization on /scout-update.
• Added a key-consistency test bullet (§8) and a legacy-config-migration risk note.

Commit: 8b8ffc2.

[jordanrburger]

Design review — optional-connector catalog

Verdict: 🟠 Needs revision (high-quality prose, but it rests on an outdated codebase model and a reversed premise)

The problem framing is real (adding a non-default connector today means hand-editing three files), the proposed CLI surface (catalog/enable/disable, --json) fits the existing scoutctl connectors sub-app, and the optional: true + catalog: schema additions are backward-compatible as described (_build_connector reads via raw.get(...)). And credit where due — §7 catches a genuine latent bug (below). But three load-bearing issues:

1. The flagship use-case has been reversed. The spec seeds the catalog with Google Messages as the proof-of-concept optional connector — but connectors.yaml shows it was promoted OPTIONAL→CRITICAL on 2026-04-25 (≈2 months before this spec), with a note that no work connector replaces it. There's also no phases/connectors/google-messages.md and no probe for it. The spec argues for opt-in defaults; the maintainers' revealed preference is the opposite. Re-justify the premise, or re-seed with a connector genuinely wanted default-off.

2. The key model is internally inconsistent. There are three non-reconciled namespaces: roster key (mcp:claude_ai_Gmail), probe/config key (gmail), and phase requires: (email). The enable flow's step-1 validation ("validate <key> exists in roster") operates on the mcp:… namespace, but connectors.enabled takes the probe key — the spec conflates them, so the turn-key promise can silently no-op. State which namespace each step uses, and make the proposed CI invariant assert agreement across all three (not two).

3. Missing scope items: the CI-verified connectors.snapshot.json artifact (snapshot --check) and the scout-app fixture will drift when the schema changes — not mentioned. And the seed connector's phase + probe don't exist and must be authored.

Real bug worth splitting out now (independent of this PR): §7 correctly identifies that probe/config key gmail ≠ phase requires: email, so select_sections silently drops all email phases whenever Gmail is enabled — masked in tests because the fixture (dummy-mixed.md) uses requires: gmail, not the real requires: email. Recommend a standalone fix PR, and fix the masking fixture at the same time.

The spec is well-written and the §7 catch is valuable — but don't merge it as a basis for implementation without addressing 1–3.

_{🤖 Claude Code-assisted design review.}