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.