v2 reset: design recipe catalog and tap support

[shpoont]

Problem

Users should be able to manage common apps out of the box, while advanced users should be able to add support for apps that are not in the official set. That requires a clear recipe catalog/tap model instead of only local ad-hoc recipes.

Scope

Design and implement recipe catalog support.

Required model

• The dotfiles-manager official catalog is preconfigured by default, but normal user output must not present it as baked into or included with the app.
• The official catalog can later be updated from its remote origin, and additional remote catalogs can be added, listed, updated, disabled, and removed.
• Catalogs are similar in spirit to Homebrew taps: a named source that provides recipes.
• Recipe origin is visible so users know whether a recipe is official or from another catalog.
• The trust/update story is explicit before recipes from remote sources can write app settings.

Acceptance criteria

• A catalog data model is specified, including name, source URL/path, enabled state, version/update metadata, and recipe origin.
• CLI UX is specified for listing catalogs, adding/removing catalogs, updating catalogs, and selecting recipes from catalogs.
• The default official catalog behavior is defined for first run and offline use.
• Security/trust rules are documented for remote catalogs before any write operation uses them.
• Tests cover official-catalog discovery and at least one additional remote catalog fixture.
• User docs explain catalogs only after the basic sync workflow, not as a prerequisite for common apps.

#219 audit follow-up: split sequence

Source: #219 audit merged in #220 (docs/internal/project/v2-reset-audit-issue-219.md).

This issue is now a parent delivery area. Use these split issues:

• v2 catalogs: specify catalog/tap trust and origin model #227 — specify catalog/tap trust and origin model.
• v2 catalogs: implement official catalog discovery baseline #228 — implement official-catalog discovery.
• v2 catalogs: implement official and remote catalog management with write gates #229 — implement official-catalog updates and additional remote catalog management with write gates.

Additional gate:

• v2 catalogs: specify catalog/tap trust and origin model #227 must be accepted before v2 catalogs: implement official catalog discovery baseline #228/v2 catalogs: implement official and remote catalog management with write gates #229 implementation work starts.
• Remote catalog recipes must not gain write authority until origin, trust, update behavior, disabling/removal, and recipe provenance are accepted.
• Treat any existing registry/catalog data as an implementation seed only after the v2 catalogs: implement official catalog discovery baseline #228/v2 catalogs: implement official and remote catalog management with write gates #229 contracts accept the relevant behavior.

Project Execution Standards alignment

Latest standard read for this update: /Users/shpoont/Work/shpoont/project-execution-standards/project-execution-standard.md, last-updated 2026-06-29.

Project record / source of truth: #209 plus docs/internal/project/v2-reset-execution-record.md; this issue is the catalog parent.

Role of this issue: parent delivery area for catalog work, not a direct implementation package.

Risk tier: parent mixed Tier 1/Tier 2. #228 official-catalog discovery is Tier 1 because it is public CLI UX but read-only. #229 catalog update/remote catalog management is Tier 2 because it introduces remote origin, trust, update/cache, and write-authority risk.

Current child sequence:

• v2 catalogs: specify catalog/tap trust and origin model #227 is complete and accepted as the catalog trust/origin model.
• v2 catalogs: implement official catalog discovery baseline #228 owns the read-only official-catalog discovery baseline and must not expose internal pseudo-app targets or unavailable catalog lifecycle commands in the normal path.
• v2 catalogs: implement official and remote catalog management with write gates #229 owns official-catalog update behavior and additional remote catalog lifecycle, including add/update/disable/remove and write gates.

Design/documentation-first rule:

• Any meaningful catalog CLI surface must have runnable/replayable UX evidence or an owner-recorded waiver before implementation.
• User-facing docs/examples for catalogs must explain that catalogs define app/tool support and do not store user settings.

Change rule:

• Changes to the child sequence, remote trust/write-authority model, catalog lifecycle scope, or official-catalog user wording are managed changes requiring Project Owner decision.

No-go actions:

• Do not reintroduce local catalog lifecycle into the normal v2 user path without a managed change.
• Do not present the official catalog as baked into or included with the app.
• Do not grant remote or updated catalog recipes live-write authority until v2 catalogs: implement official and remote catalog management with write gates #229 validation proves the accepted v2 catalogs: specify catalog/tap trust and origin model #227 trust/write-gate model.

Acceptance rule / closure rule:

• Project Owner acceptance is required before closing this parent.
• Keep this parent open until v2 catalogs: implement official catalog discovery baseline #228 and v2 catalogs: implement official and remote catalog management with write gates #229 are accepted or explicitly deferred, then record a project-level checkpoint in v2 reset: realign product plan around settings-folder sync #209 and docs/internal/project/v2-reset-execution-record.md.