v2 catalogs: implement official catalog discovery baseline

[shpoont]

Parent: #214
Project record: #209 and docs/internal/project/v2-reset-execution-record.md

Status

Recontracted on 2026-06-30 after Project Owner review of the normal list / discovery surface.

This replaces the previous #228 scope that mixed built-in/default-source wording with local catalog discovery. Draft PR #255 implemented the older local-catalog scope and is superseded for #228 acceptance purposes.

Purpose

Implement the safe official-catalog app/tool discovery baseline for v2.

A new user should be able to run read-only discovery commands, see real apps/tools supported by the preconfigured dotfiles-manager official catalog, understand what an app can manage, and see useful official-catalog state such as version and updated time. The user should not have to learn the recipe noun or see internal/generated pseudo-app targets or unavailable catalog lifecycle commands in the normal path, and the catalog should not be presented as included or baked into the app.

Risk tier

Tier 1.

This is public CLI UX and product vocabulary. It is read-only discovery behavior and must not introduce live-settings writes, stored-settings writes, network fetching, official-catalog updates, additional remote catalog management, or remote recipe write authority.

Scope

• Official-catalog app/tool support discovery from current official catalog metadata.
• catalog list identifies the official catalog as dotfiles-manager/official, defines catalogs as app/tool support sources rather than settings storage, and shows concise catalog state: version and updated time.
• Normal app-first commands:
  • dotfiles-manager list
  • dotfiles-manager search <query>
  • dotfiles-manager explain <app>
• Compact catalog name in explain <app>; catalog state details are reserved for catalog list or future verbose output.
• dotfiles-manager catalog list showing dotfiles-manager/official, version, and last-updated time.
• No public/mock dotfiles-manager catalog update or dotfiles-manager catalog add output in v2 catalogs: implement official catalog discovery baseline #228; catalog lifecycle behavior is omitted until implemented by v2 catalogs: implement official and remote catalog management with write gates #229.
• Tests and temp-home/fixture command evidence for deterministic official catalog metadata behavior.

Non-goals

• No user-facing "built-in catalog" model.
• No internal/generated pseudo-app targets in normal list or search.
• No public arbitrary-file management pseudo-app in this issue.
• No local catalog add/list/disable/enable/remove lifecycle.
• No local-only app candidates, local/official collision handling, or unavailable local-source states.
• No first-run download/update implementation for the official catalog, and no public catalog update placeholder/output in v2 catalogs: implement official catalog discovery baseline #228.
• No public catalog add placeholder/output in v2 catalogs: implement official catalog discovery baseline #228.
• No remote catalog add/update/disable/remove/sign/cache/integrity behavior. That belongs to v2 catalogs: implement official and remote catalog management with write gates #229.
• No remote write grants or live-write authority.
• No full manage/unmanage cleanup unless separately recontracted.
• No acceptance of PR Superseded: Implement built-in and local catalog discovery #255's local-catalog scope as v2 catalogs: implement official catalog discovery baseline #228 behavior.

Design evidence / pre-implementation model

Use and keep consistent with:

• docs/internal/ux/v2-catalog-discovery-storyboard.md
• docs/internal/ux/mocks/v2-catalog-discovery/README.md
• docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check

The runnable mock is design evidence only. It does not prove the runtime implementation works.

Acceptance criteria

• The implementation starts from current main after this recontract and a fresh implementation-start gate.
• Official-catalog discovery is deterministic in the accepted fixture/mock evidence, and catalog list shows version and updated time.
• list and search show real supported apps/tools from the current official catalog metadata only; internal/generated pseudo-app targets are not shown as normal apps/tools.
• Normal output uses official / official catalog wording, not user-facing built-in source wording.
• explain <official-app> explains what can be managed, what is intentionally excluded, and shows only the compact catalog name without printing live setting values; catalog state details belong in catalog list or future verbose output.
• Unsupported-app output points to future catalog capabilities without exposing unavailable update/add commands or promoting local catalog workarounds.
• catalog list shows dotfiles-manager/official, catalog version, and catalog updated time; catalog update and catalog add are omitted from v2 catalogs: implement official catalog discovery baseline #228 public/mock output until implemented by v2 catalogs: implement official and remote catalog management with write gates #229.
• Local catalog lifecycle is not implemented or promoted by v2 catalogs: implement official catalog discovery baseline #228.
• Real-result verification includes targeted tests, go test ./... where practical, and temp-home/fixture CLI transcripts for the accepted commands.
• Validation distinguishes design evidence, implementation verification, Project Owner acceptance, and closure.

Change rule

After this issue is frozen for implementation, changes to public commands, output shape, supported surfaces, evidence requirements, risk tier, or acceptance criteria are managed changes and must be recorded before implementation continues.

Acceptance / closure rule

Acceptor: Project Owner.

This issue may close only after implementation verification is available, validation is recorded against the recontracted criteria above, and the Project Owner explicitly accepts #228 closure or a predeclared auto-accept rule is added before validation.

[shpoont]

#228 work-item contract and freeze

Project Owner UX decision recorded on 2026-06-27: #228 should include a user-facing local catalog lifecycle, not only developer fixtures.

Type: delivery child of #214.
Risk tier: Tier 1.
Reason: this changes user-visible catalog discovery/listing/lifecycle behavior and recipe-origin output, but it must not implement remote fetching or remote write authority. Any live write behavior remains gated by existing sync/write confirmation and local trust mechanisms.

Outcome:

• Implement built-in and local catalog discovery against the accepted v2 catalogs: specify catalog/tap trust and origin model #227 catalog trust/origin model.
• Make catalogs an advanced Homebrew-tap-like expansion mechanism while keeping the normal product UX app-first.
• Provide a safe user-facing lifecycle for local catalogs before remote catalog work in v2 catalogs: implement official and remote catalog management with write gates #229.

Approved UX model:

• Normal users should not need to understand catalogs in the happy path.
• Primary UX remains app-first: users choose apps/tools to manage.
• Catalog/source/origin information is shown when useful: listing availability, explaining a recipe, resolving collisions, before writes, and diagnosing unavailable recipes.
• Advanced users may add local catalogs to provide additional app recipes.
• Built-in catalog is special: always available, deterministic/offline, and not removable by normal lifecycle commands.

Scope:

• Normalize the bundled/default recipes as a built-in catalog/source.
• Implement user-facing local catalog lifecycle commands or equivalent command surface:
  • add local catalog;
  • list catalogs;
  • disable local catalog;
  • enable local catalog;
  • remove local catalog.
• Show recipe/source origin for built-in and local recipes in relevant list/explain/planning output before writes.
• Preserve bundled-first/default precedence when built-in and local recipes collide.
• Show local recipes as additional candidates, not silent replacements for built-in recipes.
• Keep local write authority bound to existing local trust/write-surface evidence outside the settings storage folder.
• If a local catalog is disabled or removed, do not delete live app settings or stored settings; apps depending on that catalog become unavailable/orphaned until the user re-adds/enables the catalog, chooses another recipe, or stops managing that app.
• Mandatory machine validation for local catalog/recipe structure, schema, capabilities, path/write-surface constraints, and fail-closed unknown source kinds or enum values.
• Human recipe review must not be mandatory by default for regular users; default UX should show a plain-language summary before first use/write where needed.
• Tests/fixtures for built-in discovery, local catalog lifecycle, collision behavior, unavailable/orphaned source behavior, and offline first-run behavior.

Non-goals:

• Remote catalog fetching, update, signing, key rotation, revocation, cache/offline policy, or remote write authority.
• Trust-all-future-updates policy.
• Full strict-mode or security-policy UI, unless a minimal internal setting is needed only to preserve existing safety behavior.
• Deleting live settings or stored settings when a catalog is disabled or removed.
• Making Git mandatory for the settings storage folder.
• Rewriting production end-user docs for the whole product (v2 docs: rewrite end-user documentation after product reset #216).

Affected users/operators:

• Regular users listing/managing supported apps.
• Advanced users adding custom local catalogs.
• Implementers of v2 catalogs: implement official and remote catalog management with write gates #229, which will build remote catalog behavior on this foundation.

Dependencies and blockers:

• Depends on accepted v2 catalogs: specify catalog/tap trust and origin model #227 trust/origin model and PR Specify v2 catalog trust and origin model #250.
• Must not proceed into remote behavior from v2 catalogs: implement official and remote catalog management with write gates #229.
• If existing command surface cannot support the approved lifecycle without changing broader product UX, stop and recontract instead of silently inventing a larger command model.

Design evidence required before implementation:

• CLI transcript or equivalent UX examples covering:
  • built-in catalog first-run/offline listing;
  • adding a local catalog;
  • listing catalogs;
  • listing apps/recipes with built-in and local origin;
  • built-in + local collision with bundled-first default;
  • disabling/removing a local catalog with stored/live settings left untouched;
  • unavailable/orphaned managed app explanation;
  • before-write origin summary for local recipes.

Real-result verification required:

• go test ./... or justified targeted equivalent plus relevant package tests.
• Temp-home or fixture-storage CLI runs demonstrating the accepted UX examples.
• Offline/deterministic first-run evidence for built-in catalog loading.
• Fixture evidence for local catalog lifecycle and collision behavior.
• Verification that remote catalog/network behavior is not introduced by this issue.

Validation criteria:

• Built-in catalog behavior is deterministic and works offline.
• Local catalogs can be added, listed, disabled, enabled, and removed.
• Built-in/local recipe origin is visible before writes.
• Local catalogs do not enable remote writes or arbitrary command execution.
• Local recipes cannot silently override built-in recipes.
• Disabling/removing a local catalog leaves live settings and stored settings untouched and produces clear unavailable/orphaned status where relevant.
• Mandatory machine validation fails closed for unknown source kinds, unknown enum values, invalid schema, and unsafe declared behavior.

Acceptor and acceptance rule:

• Project Owner is acceptor.
• Acceptance requires merged implementation PR evidence, validation results, and explicit Project Owner acceptance before v2 catalogs: implement official catalog discovery baseline #228 is closed.

Privacy/authority/recovery considerations:

• Do not mutate live user settings during tests except in temp-home/fixture environments.
• Do not delete stored settings as part of catalog removal/disable.
• Do not load secrets or credentials from local catalogs.
• Do not introduce network access for catalogs in v2 catalogs: implement official catalog discovery baseline #228.

Closure requirements:

• PR merged with evidence.
• v2 catalogs: implement official catalog discovery baseline #228 closure comment records acceptance, evidence, limitations, and follow-ups.
• v2 reset: realign product plan around settings-folder sync #209 and docs/internal/project/v2-reset-execution-record.md updated if the next gate or project-level state changes.

[shpoont]

#228 design evidence draft: built-in and local catalog UX

Status: draft for Project Owner review. This is design evidence only, not implementation approval.

Purpose: define the user-facing CLI shape for #228 before implementation begins, using the frozen #228 contract and the accepted #227 trust/origin model.

UX principles

• Normal workflow stays app-first. Users manage apps/settings, not catalogs.
• Catalogs are an advanced expansion mechanism, similar to Homebrew taps.
• Built-in catalog is always available, deterministic/offline, and not removable.
• Local catalogs can be added, listed, disabled, enabled, and removed.
• Adding/disabling/removing a catalog never deletes live app settings or stored settings.
• Local recipes are discoverable after machine validation, but they do not silently override built-in recipes.
• Recipe origin is shown when useful: list/explain/planning/before-write/blocker output.
• Remote catalogs remain out of v2 catalogs: implement official catalog discovery baseline #228.

Proposed command surface for #228

dotfiles-manager catalog list
dotfiles-manager catalog add <name> <local-path>
dotfiles-manager catalog disable <name>
dotfiles-manager catalog enable <name>
dotfiles-manager catalog remove <name>

dotfiles-manager recipe list
dotfiles-manager recipe explain <target>

Notes:

• catalog add in v2 catalogs: implement official catalog discovery baseline #228 accepts local filesystem paths only.
• URL/remote sources should fail clearly and point to v2 catalogs: implement official and remote catalog management with write gates #229/future support.
• recipe list remains the app/recipe discovery surface; the output should say “app recipes” in human text, not force normal users to learn catalog internals.
• Exact JSON schema is not frozen by this draft; implementation must preserve JSON-only stdout for --json.

Transcript 1: first run / offline built-in catalog

Command:

dotfiles-manager catalog list

Expected default output:

Catalogs

  built-in  Built in  enabled
    Source: ships with dotfiles-manager
    Updates: with dotfiles-manager releases
    Network: not used
    Removable: no

Local catalogs: none
Remote catalogs: not supported yet

No live settings were read or changed.

Command:

dotfiles-manager recipe list

Expected default output:

Available app recipes

  custom.files  Built in
  git           Built in
  nvim          Built in
  ssh           Built in
  starship      Built in
  tmux          Built in
  zsh           Built in

Tip: add a local catalog when you want dotfiles-manager to discover custom app recipes.
     dotfiles-manager catalog add personal ~/dotfiles-manager-recipes

User takeaway: the app works offline and does not require catalog setup for built-in support.

Transcript 2: add a local catalog

Precondition: ~/dotfiles-manager-recipes is a local folder containing recipe directories, for example example-tool/recipe.yaml and git/recipe.yaml.

Command:

dotfiles-manager catalog add personal ~/dotfiles-manager-recipes

Expected default output:

Added local catalog: personal

Source:
  ~/dotfiles-manager-recipes

Validated recipes:
  example-tool  Local recipe
  git           Local candidate; built-in recipe remains the default

Not enabled for remote access: local catalogs never fetch from the network.
No live settings were read or changed.
No stored settings were changed.

If the path contains invalid recipe files:

Catalog not added: personal

Reason:
  1 recipe failed validation.

Invalid recipes:
  broken-tool
    - recipe.yaml has unknown field "dangerousCommand"

No live settings were read or changed.
No stored settings were changed.

User takeaway: adding a local catalog is safe, local-only, and machine-validated. Invalid catalogs fail before becoming active.

Transcript 3: list catalogs after adding local catalog

Command:

dotfiles-manager catalog list

Expected default output:

Catalogs

  built-in  Built in  enabled
    Source: ships with dotfiles-manager
    Updates: with dotfiles-manager releases
    Removable: no

  personal  Local  enabled
    Source: ~/dotfiles-manager-recipes
    Recipes: 2 valid, 0 blocked
    Writes: local recipe write trust still applies before live settings can be changed
    Network: not used

No live settings were read or changed.

Verbose output may include source IDs, catalog IDs, origin URIs, manifest/content digests where applicable, and local state paths. Default output should avoid those implementation terms unless needed for a next action.

Transcript 4: app/recipe list with built-in and local origins

Command:

dotfiles-manager recipe list

Expected default output:

Available app recipes

  custom.files  Built in
  example-tool  Local catalog: personal
  git           Built in
               Also found: local candidate from personal
  nvim          Built in
  ssh           Built in
  starship      Built in
  tmux          Built in
  zsh           Built in

Built-in recipes stay the default when a local recipe has the same app id.
Use recipe explain to see candidates for one app:
  dotfiles-manager recipe explain git

User takeaway: normal users see available apps first. Catalog origin is visible but secondary.

Transcript 5: explain a built-in/local collision

Command:

dotfiles-manager recipe explain git

Expected default output:

Git

Default recipe:
  Built in
  Recipe: recipe://bundled/git

Other candidates:
  Local catalog: personal
  Recipe: recipe://local/git
  Status: candidate only

Why built-in is used:
  Built-in recipes stay the default unless you explicitly choose another recipe.
  The local recipe cannot silently replace the built-in recipe.

Managed settings from the default recipe:
  git:user.email  Git user email
  git:user.name   Git user name

Not managed:
  credential.helper
  [credential] sections
  include/includeIf expansion

No live values were printed.

User takeaway: collision behavior is safe and understandable.

Transcript 6: explain a local-only recipe

Command:

dotfiles-manager recipe explain example-tool

Expected default output:

Example Tool

Recipe source:
  Local catalog: personal
  Recipe: recipe://local/example-tool
  Status: available after machine validation

This recipe can manage:
  example-tool:config  Config file
    Live location: $HOME/.config/example-tool/config.yaml

Before live settings can be changed:
  dotfiles-manager will show this source and the paths it wants to manage.
  Existing local recipe write-trust rules still apply.

No live values were printed.

User takeaway: the user sees a plain-language recipe summary, not YAML.

Transcript 7: before-write origin summary for a local recipe

Command:

dotfiles-manager sync --dry-run example-tool

Expected default output:

Preview sync for example-tool

Recipe source:
  Local catalog: personal
  Recipe: recipe://local/example-tool

This recipe wants to manage:
  example-tool:config
    Live location: $HOME/.config/example-tool/config.yaml
    Stored settings: desired/user/<user-id>/targets/example-tool/...

Result:
  No write will run yet.

Reason:
  Local recipe write trust must be satisfied before dotfiles-manager can change
  live settings for this recipe.

No live settings were changed.
No stored settings were changed.

If implementation can prove existing local write trust is already satisfied, the same output may proceed to the normal dry-run sync preview. It must still show the local recipe origin before any confirmed write.

Transcript 8: disable a local catalog

Command:

dotfiles-manager catalog disable personal

Expected default output:

Disabled local catalog: personal

Recipes no longer available from this catalog:
  example-tool
  git local candidate

Nothing was deleted.
Live app settings were not changed.
Stored settings were not changed.

If a selected app depends on this catalog, it will show as recipe unavailable
until you enable the catalog, add another recipe, or stop managing that app.

Command:

dotfiles-manager recipe list

Expected default output excerpt:

Available app recipes

  custom.files  Built in
  git           Built in
  nvim          Built in
  ssh           Built in
  starship      Built in
  tmux          Built in
  zsh           Built in

Disabled local catalogs:
  personal  2 recipes hidden

Transcript 9: unavailable/orphaned selected app after disable/remove

Precondition: example-tool was selected before the personal catalog was disabled or removed.

Command:

dotfiles-manager status example-tool

Expected default output:

example-tool: blocked

Reason:
  The selected app uses a recipe from local catalog "personal", but that catalog
  is disabled or removed.

Nothing was read or changed.
Live app settings were not changed.
Stored settings still exist, if they existed before.

To continue:
  Enable the catalog:
    dotfiles-manager catalog enable personal

  Or add another catalog/recipe that provides example-tool.

  Or stop managing this app if you no longer want dotfiles-manager to sync it.

User takeaway: disabling/removing a catalog is reversible and does not destroy data.

Transcript 10: enable a local catalog

Command:

dotfiles-manager catalog enable personal

Expected default output:

Enabled local catalog: personal

Validated recipes:
  example-tool  Local recipe
  git           Local candidate; built-in recipe remains the default

No live settings were read or changed.
No stored settings were changed.

Transcript 11: remove a local catalog

Command:

dotfiles-manager catalog remove personal

Expected default output:

Removed local catalog: personal

Removed from dotfiles-manager catalog list only:
  ~/dotfiles-manager-recipes

Nothing was deleted from that folder.
Live app settings were not changed.
Stored settings were not changed.

Apps that depended on this catalog are now recipe unavailable until you re-add
this catalog, choose another recipe, or stop managing those apps.

Important distinction:

• disable keeps the source record and can be re-enabled by name.
• remove forgets the source record but does not delete the catalog folder or settings data.

Transcript 12: remote catalog rejected in #228

Command:

dotfiles-manager catalog add community https://example.com/dotfiles-manager/catalog.yaml

Expected default output:

Catalog not added: community

Reason:
  Remote catalogs are not supported in this version of dotfiles-manager.

Use a local catalog path for now:
  dotfiles-manager catalog add personal ~/dotfiles-manager-recipes

Remote catalog trust, updates, and write gates are planned separately.
No live settings were read or changed.
No stored settings were changed.

Review questions for Project Owner

1. Is the proposed command surface acceptable for v2 catalogs: implement official catalog discovery baseline #228?
   • catalog add <name> <local-path>
   • catalog list
   • catalog disable|enable|remove <name>
2. Is it acceptable that recipe list remains the app/recipe discovery surface instead of adding a new apps command in v2 catalogs: implement official catalog discovery baseline #228?
3. Is the disable/remove behavior right?
   • disable/remove never delete live settings or stored settings;
   • selected apps become recipe unavailable/orphaned until resolved.
4. Is the before-write local recipe message strict enough, or should v2 catalogs: implement official catalog discovery baseline #228 define a concrete approval command too?

Until these are accepted, this is design evidence only and implementation should not begin.

[shpoont]

Managed change: flattened normal-user CLI model

Project Owner decision recorded on 2026-06-28 after Pro consultation and follow-up UX discussion.

This supersedes the earlier #228 design-evidence draft where recipe list remained the normal discovery surface. The updated user-facing model is:

• Normal users manage settings for apps/tools, not recipes.
• Normal user commands should be flattened around common actions:
  • dotfiles-manager list
  • dotfiles-manager search <query>
  • dotfiles-manager explain <app>
  • dotfiles-manager manage <app>
  • dotfiles-manager unmanage <app>
  • dotfiles-manager status [<app>...]
  • dotfiles-manager diff [<app>...]
  • dotfiles-manager sync [<app>...]
  • dotfiles-manager save [<app>...]
  • dotfiles-manager apply [<app>...]
• catalog ... remains an umbrella for support sources/catalog lifecycle.
• recipe ... remains an advanced umbrella for authoring/debugging support definitions.
• recipe should not be the normal-user discovery noun.

Definitions to preserve:

• list shows supported apps/tools and whether each is currently managed.
• search <query> finds supported apps/tools across enabled catalogs.
• explain <app> explains support/provenance/candidates without requiring recipe knowledge.
• manage <app> enrolls an app/tool so it participates in status/diff/sync/save/apply; it must not silently overwrite live settings.
• unmanage <app> stops tracking an app/tool; it must not uninstall the app, delete live settings, or delete stored settings.
• save remains directional sync from live settings to the settings storage folder.
• apply remains directional sync from the settings storage folder to live settings.
• sync remains the primary smart/bidirectional model.

#228 implementation guidance:

• v2 catalogs: implement official catalog discovery baseline #228 should implement the built-in/local catalog foundation using this vocabulary.
• Discovery UX in v2 catalogs: implement official catalog discovery baseline #228 should use list, search, and explain <app> rather than introducing apps or continuing to teach recipe list as the happy path.
• Catalog lifecycle remains in v2 catalogs: implement official catalog discovery baseline #228 for built-in/local only.
• Remote GitHub catalog syntax such as catalog add shpoont/custom-recipes remains reserved for v2 catalogs: implement official and remote catalog management with write gates #229 unless explicitly recontracted.
• Wider command cleanup/deprecation for existing app create/validate/test, add, or recipe list/explain compatibility should be tracked as follow-up work where it is outside v2 catalogs: implement official catalog discovery baseline #228’s built-in/local catalog discovery scope.

Design-evidence update required before implementation:

• Replace the previous recipe list happy-path transcripts with list, search, and explain transcripts.
• Include manage/unmanage semantics where relevant, but do not force v2 catalogs: implement official catalog discovery baseline #228 to implement full management lifecycle if that belongs to a focused follow-up issue.
• Keep before-write origin/provenance evidence for local catalog recipes.

Pro review used for this decision: https://chatgpt.com/c/6a4053f2-7ea4-83ed-b9eb-ad457ed2d7b7