Recontract #228 discovery around the official catalog

[shpoont]

Related work

• Recontract/design-evidence update for v2 catalogs: implement official catalog discovery baseline #228
• Parent/catalog context: v2 reset: design recipe catalog and tap support #214
• Project context: v2 reset: realign product plan around settings-folder sync #209
• Official-catalog update / additional remote-catalog follow-up: v2 catalogs: implement official and remote catalog management with write gates #229
• Supersedes PR Superseded: Implement built-in and local catalog discovery #255 for v2 catalogs: implement official catalog discovery baseline #228 acceptance purposes

This PR does not close #228. It records the recontracted #228 target and design evidence so a fresh implementation-start gate can happen from current main.

Risk tier

Tier 1: this changes public CLI UX design evidence, tracker records, and process state for a user-facing discovery surface. It does not change runtime behavior, live settings, stored settings, remote fetching, or write authority.

Recontracted #228 decision

The Project Owner decided on 2026-06-30 that normal discovery should:

• show real supported apps/tools only;
• remove internal/generated pseudo-app targets from normal list/search;
• remove catalog lifecycle command placeholders from v2 catalogs: implement official catalog discovery baseline #228 and the normal user path;
• replace user-facing built-in catalog wording with the preconfigured official catalog;
• require catalog list to identify dotfiles-manager/official, define catalogs as app/tool support sources rather than settings storage, and show catalog version/updated time;
• omit catalog update and catalog add from v2 catalogs: implement official catalog discovery baseline #228 public/mock output until v2 catalogs: implement official and remote catalog management with write gates #229 implements those behaviors;
• treat official-catalog update and additional remote catalogs as the intended extension path, implemented separately by v2 catalogs: implement official and remote catalog management with write gates #229;
• stop treating PR Superseded: Implement built-in and local catalog discovery #255 as the active v2 catalogs: implement official catalog discovery baseline #228 implementation target.

What changed

• Replaced docs/internal/ux/v2-catalog-discovery-storyboard.md with the official-catalog discovery target.
• Added runnable/replayable UX mock evidence under docs/internal/ux/mocks/v2-catalog-discovery/.
• Updated the v2 CLI: normalize flattened normal-user command vocabulary #252 discovery-normalization storyboard so examples no longer imply old internal pseudo-app list entries.
• Removed repetitive No live settings were read or changed / No stored settings were changed footers from normal read-only discovery output after Project Owner UX feedback.
• Updated the UX index and v2 execution record so future agents see v2 catalogs: implement official catalog discovery baseline #228 as official-catalog discovery, v2 catalogs: implement official and remote catalog management with write gates #229 as the update/additional-catalog follow-up, and PR Superseded: Implement built-in and local catalog discovery #255 as superseded.

Design evidence

• docs/internal/ux/v2-catalog-discovery-storyboard.md
• docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check
• Subagent review after initial fixes found no blockers for the recontract package or live tracker state.
• 2026-07-02 UX role reviews found the app-first direction sound and requested cleanup: remove the leftover internal pseudo-app transcript, remove catalog add from v2 catalogs: implement official catalog discovery baseline #228 public/mock output, avoid the normal-user recipe noun, and clarify catalog meaning/active-for-discovery wording.

Validation performed

git diff origin/main...HEAD --check
PYTHON="$HOME/.asdf/shims/python" docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check

Both passed.

Live tracker updates performed

• v2 catalogs: implement official catalog discovery baseline #228 body updated to the official-catalog discovery contract and the 2026-07-02 managed change that omits catalog update and catalog add from v2 catalogs: implement official catalog discovery baseline #228 public/mock output.
• v2 catalogs: implement official catalog discovery baseline #228 managed-change comment recorded.
• Superseded: Implement built-in and local catalog discovery #255 title/body/comment marked superseded.
• v2 catalogs: implement official and remote catalog management with write gates #229 title/body updated for official-catalog updates and additional remote catalog management.
• v2 reset: realign product plan around settings-folder sync #209 and v2 reset: design recipe catalog and tap support #214 source-of-truth bodies updated to remove stale built-in/local wording.

Docs impact

Internal design/process docs only. Production end-user documentation remains #216.

Known out-of-scope item

The unrelated untracked local file under docs/presentations/ was left untouched and is not part of this PR.

[shpoont]

Update: official-catalog snapshot model applied

This PR has been updated after Project Owner approval to replace user-facing built-in catalog wording with the dotfiles-manager official catalog model:

• the official catalog is preconfigured by the app;
• v2 catalogs: implement official catalog discovery baseline #228 uses the bundled official-catalog snapshot for offline/first-run discovery;
• v2 catalogs: implement official and remote catalog management with write gates #229 owns official-catalog updates and additional remote catalogs;
• catalog update / catalog add <owner>/<repo> are v2 catalogs: implement official catalog discovery baseline #228 placeholder errors only;
• active design docs and live issues v2 reset: design recipe catalog and tap support #214/v2 catalogs: implement official catalog discovery baseline #228/v2 catalogs: implement official and remote catalog management with write gates #229/v2 reset: realign product plan around settings-folder sync #209 are reconciled.

Local validation and subagent blocker review passed before the force-push.

[shpoont]

UX wording refinement after Project Owner feedback on dotfiles-manager explain git clarity:\n\n- Replaced default-output "Why this source is used" with "Where this support comes from".\n- Replaced user-facing "bundled snapshot" / "Catalog data" wording with "official catalog" and "Available offline: yes (included with this app)".\n- Kept #228 constraints unchanged: official catalog is preconfigured, discovery works offline, no network update/add behavior, no local catalog lifecycle, and no custom.files in normal discovery.\n\nValidation:\n\n- docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check\n- git diff --check\n- Subagent blocker-only review: no blockers.

[shpoont]

Managed UX simplification after Project Owner approval:\n\n- Shortened default dotfiles-manager explain git output.\n- Removed the separate source-origin paragraph from default explain output.\n- Kept only a compact signal: Catalog: official (included with this app; works offline).\n- Updated #228 contract to state that longer source/origin detail belongs in catalog list or future verbose output.\n\nValidation:\n\n- docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check\n- git diff --check\n- Subagent blocker-only review: no blockers.

[shpoont]

Managed UX correction after Project Owner feedback:\n\n- Removed offline/cache/download semantics from default dotfiles-manager explain git.\n- Default explain output now shows only Catalog: official.\n- Kept offline/source/cache details reserved for catalog list or future verbose output.\n- Updated #228 contract accordingly.\n\nValidation:\n\n- docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check\n- git diff --check\n- Subagent blocker-only review: no blockers.

[shpoont]

Managed catalog-model correction after Project Owner feedback:\n\n- Removed wording that presented the official catalog as included/baked into the app.\n- Simplified dotfiles-manager catalog list to useful state only: version and last-updated time.\n- Kept default explain <app> to Catalog: official only.\n- Updated #209/#228/#229 and the project execution record so #228 is catalog metadata/discovery evidence, while first-run download/update behavior remains #229 or later implementation.\n\nCurrent mock output:\n\ntext\nCatalogs\n\n official dotfiles-manager official catalog active\n Version: 9f2c7a1\n Last updated: 2026-06-30 18:00\n\n\nValidation:\n\n- docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check\n- git diff --check\n- Subagent review after fixes: no blockers.

[shpoont]

Managed catalog-list UX tweak:\n\n- Changed the catalog row from duplicated label text to the catalog identifier:\n\ntext\nCatalogs\n\n dotfiles-manager/official active\n Version: 9f2c7a1\n Last updated: 2026-06-30 18:00\n\n\n- Updated #228 and the project execution record to reference dotfiles-manager/official for catalog-list output.\n\nValidation:\n\n- docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check\n- git diff --check\n- Subagent blocker-only review: no blockers.

[shpoont]

Managed #228 catalog update omission after Project Owner selected hide/omit until implemented:

• Removed dotfiles-manager catalog update from the v2 catalogs: implement official catalog discovery baseline #228 runnable mock/demo and storyboard.
• Removed the catalog update placeholder output.
• Updated v2 catalogs: implement official catalog discovery baseline #228 so update behavior is omitted from public output until implemented.
• No-match output no longer prints unavailable update/add commands.
• Kept catalog list as dotfiles-manager/official with version and last-updated state.

Current relevant mock output:

$ dotfiles-manager catalog list
Catalogs

  dotfiles-manager/official  active
    Version: 9f2c7a1
    Last updated: 2026-06-30 18:00

Validation:

• docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check
• git diff --check
• Subagent blocker-only review: no blockers.

[shpoont]

Managed #228 UX cleanup after Project Owner decision and UX role re-review:

• Removed the leftover internal pseudo-app transcript from the runnable mock/storyboard; normal users no longer see custom.files in v2 catalogs: implement official catalog discovery baseline #228 design evidence.
• Removed catalog add from the v2 catalogs: implement official catalog discovery baseline #228 public/mock demo, matching the earlier decision to omit catalog update until catalog lifecycle behavior is implemented by v2 catalogs: implement official and remote catalog management with write gates #229.
• Removed the normal-user recipe noun leak from the public/mock flow.
• Clarified catalog list: catalogs define app/tool support and do not store settings; dotfiles-manager/official is now shown as active for discovery with catalog version/updated metadata.
• Updated v2 catalogs: implement official catalog discovery baseline #228 and PR text so the contract says unavailable catalog lifecycle commands are omitted from v2 catalogs: implement official catalog discovery baseline #228 public/mock output, not demonstrated as placeholders.

Validation:

• docs/internal/ux/mocks/v2-catalog-discovery/run-demo.sh --check
• git diff --check
• focused grep scan confirmed no custom.files, catalog add, catalog update, Future command, or normal-user app/tool recipe appears in the runnable expected demo / v2 catalogs: implement official catalog discovery baseline #228 UX package public transcript.
• Subagent UX re-review: no blockers.

Commit: c4c5013