v2 catalogs: implement official and remote catalog management with write gates

[shpoont]

Parent: #214
Project record: #209 and docs/internal/project/v2-reset-execution-record.md
Depends on: #227 catalog trust/origin model and #228 official-catalog discovery baseline.

Purpose

Implement official-catalog download/update behavior and remote catalog lifecycle only after trust and origin rules are accepted and after #228 establishes the official-catalog discovery baseline.

This issue owns the normal extension path beyond the current official catalog metadata:

• updating the preconfigured official catalog from its remote origin;
• adding additional remote catalogs using Homebrew-like syntax such as catalog add <owner>/<repo>;
• listing, updating, disabling, and removing additional remote catalogs;
• enforcing write-authority gates before recipes from updated or additional remote catalog data can write live app settings.

Risk tier

Tier 2.

This work introduces remote origin/trust/update behavior and can affect which recipes are visible before write-capable workflows. Remote or updated catalog data must not gain live-write authority without explicit gates.

Scope

• Update the preconfigured official catalog from its remote origin, with identity/integrity/cache rules.
• Add, list, update, disable, and remove additional remote catalogs.
• Surface recipe origin, catalog identity, update metadata, and whether data comes from current or updated catalog data.
• Enforce write-authority gates before updated official recipes or additional remote recipes can write live app settings.
• Show affected managed apps/settings when a catalog is disabled, removed, blocked, or updated.

Non-goals

• No local catalog lifecycle in the normal v2 user path.
• No internal/generated public pseudo-app path.
• No live settings writes merely because a catalog is added, updated, or enabled.
• No accepting remote recipe command execution beyond the catalog trust/command-boundary model.

Acceptance criteria

• Depends on accepted catalog/tap trust and origin model, updated for the official catalog metadata model.
• Official-catalog download/update behavior is explicit, cache/offline behavior is safe, and failure leaves the last successful local catalog version usable.
• Users can add, list, update, disable, and remove additional remote catalogs.
• Users can see affected recipes/apps when a catalog changes state.
• Remote or updated catalog writes are blocked until origin/trust/write authority is explicit.
• Tests cover official-catalog update fixtures, additional remote catalog fixtures, disable/remove behavior, and write gating.

Evidence

Split from #214 by the #219 audit: docs/internal/project/v2-reset-audit-issue-219.md.
#228 recontract moved the default support model to a preconfigured official catalog with concise version/last-updated state; #229 is the download/update/add/remove/write-gate follow-up.

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.

Delivery type: Tier 2 delivery work after #228 discovery baseline is accepted.

Documentation/design-first requirements before implementation:

• Draft user-facing docs or equivalent usage guide for official-catalog update and remote catalog lifecycle.
• Runnable/replayable CLI mock or fixture transcript covering catalog list, update behavior, add/remove/disable flows, affected-app reporting, offline/cache failure paths, and write-gate messaging.
• Internal model/control review for origin identity, integrity/cache, stale data, disable/remove orphan behavior, and write-authority transitions.

Implementation-start gate requirements:

• Current main and current v2 catalogs: implement official catalog discovery baseline #228/v2 catalogs: specify catalog/tap trust and origin model #227 state refreshed.
• Frozen command/output contract and failure paths.
• Explicit no-go that adding/updating/enabling a catalog does not write live settings by itself.
• Explicit write-authority gate for recipes from updated official data and additional remote catalogs.

Real-result verification required:

• Targeted catalog lifecycle tests, fixture remote catalogs, offline/cache failure tests, and write-gate tests.
• go test ./... unless a narrower set is justified in the PR evidence.
• Temp-home/fixture CLI transcripts proving real output matches accepted docs/mock.

Change rule:

• Changes to remote syntax, trust model, cache/integrity behavior, write authority, or remove/disable/orphan behavior are managed changes requiring Project Owner decision before implementation continues.

Acceptance / closure rule:

• Project Owner acceptance is required before closing.
• Closure must distinguish design evidence from real-result verification and must update v2 reset: design recipe catalog and tap support #214/v2 reset: realign product plan around settings-folder sync #209 and the execution record if catalog sequencing or risk changes.

[shpoont]

Context update from #228 recontract

#228 is being recontracted to be the built-in-only discovery baseline. Local catalog lifecycle was removed from the normal #228 user path, and custom.files was removed from normal discovery.

That makes this issue (#229) the intended normal extension path for adding more app support beyond built-ins, using Homebrew-like remote catalog syntax such as:

dotfiles-manager catalog add <owner>/<repo>

This does not start #229 implementation yet. #229 still needs its own Tier 2 contract/freeze around remote origin, trust, update, disabling/removal effects, and write-authority gates before runtime work begins.