v2 CLI: normalize flattened normal-user command vocabulary

[shpoont]

Parent: #209
Related: #228, #214

Purpose

Normalize the v2 normal-user CLI around flattened action commands while keeping catalog ... and recipe ... as focused umbrella namespaces.

This issue exists because the #228 catalog-discovery UX decision clarified the desired command model, but some of the broader command cleanup is cross-cutting and should not be silently folded into #228 if it exceeds official-catalog discovery.

Product decision

Normal users manage settings for apps/tools, not recipes. The normal command surface should be action-first:

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>...]

Specialized namespaces remain:

dotfiles-manager catalog ...   # support sources/catalog lifecycle
dotfiles-manager recipe ...    # advanced recipe authoring/debugging

recipe must not be the normal-user discovery noun.

Draft work-item contract

Type: delivery/design cleanup.
Risk tier: Tier 1.
Reason: this changes user-facing CLI vocabulary, help output, examples, and compatibility behavior, but should not introduce new live-setting write authority.

Scope

• Define and implement the canonical flattened command vocabulary for normal users.
• Ensure list, search, and explain <app> are the normal discovery/explanation path.
• Define manage as enrolling an app/tool into dotfiles-manager control without silently overwriting live settings.
• Define unmanage as removing an app/tool from the default managed set without uninstalling the app, deleting live settings, or deleting stored settings.
• Keep status, diff, sync, save, and apply top-level and app-filterable.
• Decide compatibility behavior for existing command names such as add, recipe list, recipe explain, and app create/validate/test.
• Keep catalog ... and recipe ... as umbrella commands for their specialized audiences.
• Update CLI help, docs examples, and tests/fixtures affected by the vocabulary decision.

Non-goals

• Remote catalog fetching/update/write authority (v2 catalogs: implement official and remote catalog management with write gates #229).
• Production end-user documentation rewrite for the entire product (v2 docs: rewrite end-user documentation after product reset #216), except local examples needed to validate this issue.
• App installation management.
• Deleting live app settings or stored settings.
• Reintroducing v1 migration or backup/restore concepts.

Design evidence required before implementation

• CLI transcript or docs-first examples covering:
  • list with supported/managed state;
  • search <query> across enabled catalogs;
  • explain <app> with source/provenance/candidate information;
  • manage <app> safe enrollment and next steps;
  • unmanage <app> safe unenrollment with data left untouched;
  • app-filtered status, diff, sync, save, and apply;
  • compatibility/deprecation behavior for replaced commands.

Real-result verification required

• Targeted CLI tests plus go test ./... unless a narrower test set is justified.
• Temp-home/fixture command output proving the normal-user command flow.
• Verification that command renames/aliases do not create new write authority or mutate real user settings.

Validation criteria

• Normal help surfaces the flattened normal-user commands and does not teach recipe as the happy-path discovery noun.
• manage and unmanage semantics are safe and clear.
• status, diff, sync, save, and apply remain top-level and app-filterable.
• Existing compatibility commands either keep working with clear advanced/legacy wording or are explicitly deprecated according to the accepted contract.
• Tests and docs examples align with the accepted vocabulary.

Acceptance rule

Project Owner acceptance required before closing.

Notes

Created from the #228 managed change recorded at:
#228 (comment)

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 a future CLI vocabulary work-item contract and does not override the active #228/#229/#230/#231 gates.

Current gate / no-go actions:

• v2 CLI: normalize flattened normal-user command vocabulary #252 may proceed only after its own documentation/mock-first evidence and implementation-start gate are current.
• Do not silently fold broad command-vocabulary implementation into v2 catalogs: implement official catalog discovery baseline #228, v2 catalogs: implement official and remote catalog management with write gates #229, v2 bootstrap: specify new-computer UX and output #230, or v2 bootstrap: implement apply-from-storage flow after sync model #231.
• Do not introduce new live-settings write authority, backup/restore, v1 migration, mandatory Git, or remote catalog behavior through this issue.
• Do not treat compatibility/deprecation choices as executor discretion after the contract is frozen; record them as managed changes or Project Owner decisions.

Closure rule:

• Project Owner acceptance is required before closing.
• Closure must record real-result verification against the accepted command vocabulary, including help/output examples, compatibility/deprecation behavior, and proof that no new write authority was introduced.
• Any unresolved command vocabulary cleanup must become explicit follow-up work rather than being hidden inside v2 catalogs: implement official catalog discovery baseline #228, v2 catalogs: implement official and remote catalog management with write gates #229, v2 bootstrap: specify new-computer UX and output #230, or v2 bootstrap: implement apply-from-storage flow after sync model #231.

[shpoont]

#252 focused implementation slice freeze: flattened discovery surface

Project Owner instruction: proceed after the #228 command-model conflict was identified.

This freezes the first #252 implementation slice. #252 remains the umbrella issue for broader command normalization, but this slice is intentionally limited so it can be implemented and verified safely before returning to #228 catalog lifecycle work.

Type: delivery/design cleanup slice.
Risk tier: Tier 1.
Reason: this changes user-facing CLI vocabulary/help/output and compatibility behavior, but must not introduce new live-setting write authority.

Outcome for this slice:

• Make the normal discovery/explanation path app/tool-oriented and flattened:
  • dotfiles-manager list
  • dotfiles-manager search <query>
  • dotfiles-manager explain <app>
• Keep recipe ... as the advanced authoring/debugging namespace, not the happy-path discovery noun.
• Preserve access to the previous managed-settings list behavior through an explicit compatibility path rather than silently deleting it.
• Keep this slice small enough to unblock v2 catalogs: implement official catalog discovery baseline #228 implementation, where built-in/local catalog discovery needs the accepted normal-user discovery surface.

Frozen scope:

• Add/update design evidence before runtime changes for:
  • default list as supported apps/tools with managed/not-managed state;
  • search <query> over supported apps/tools;
  • top-level explain <app> as user-facing support/provenance explanation;
  • compatibility path for the previous selected-settings list output.
• Implement list default output as supported apps/tools, using existing bundled support first.
• Preserve the old selected-settings list output behind an explicit flag or subcommand, with tests documenting compatibility.
• Implement search <query> as read-only app/tool discovery.
• Implement top-level explain <app> as read-only app/tool support explanation, reusing existing recipe metadata internally where practical.
• Update CLI help/tests so normal help no longer teaches recipe list as the happy-path discovery noun.
• Keep JSON output stable enough for tests, while allowing a new schema/command for the new discovery output if needed.

Non-goals for this slice:

• Implementing manage or unmanage runtime behavior.
• Changing status, diff, sync, save, or apply semantics beyond any documentation/examples needed for this slice.
• Implementing catalog lifecycle commands from v2 catalogs: implement official catalog discovery baseline #228.
• Implementing local/remote catalog discovery beyond existing bundled/local recipe metadata already available.
• Remote catalog fetching/update/write authority (v2 catalogs: implement official and remote catalog management with write gates #229).
• Production end-user docs rewrite (v2 docs: rewrite end-user documentation after product reset #216).
• Deleting or mutating live app settings or stored settings.

Design evidence required before implementation:

• A checked-in internal UX/storyboard artifact for this slice.
• A review pass, by subagent if available, before runtime implementation.

Real-result verification required:

• Targeted CLI tests for list, list compatibility path, search, explain, and help output.
• go test ./... unless a narrower run is justified by a blocker.
• Temp-home/fixture CLI output showing read-only behavior and no live-setting mutation.

Acceptance rule:

• PR must pass validation and subagent PR review.
• Project Owner acceptance is required before closing v2 CLI: normalize flattened normal-user command vocabulary #252. If this PR completes only the frozen slice, v2 CLI: normalize flattened normal-user command vocabulary #252 remains open with the remaining command-normalization work explicitly recorded.

[shpoont]

Focused implementation slice merged in PR #254

Merged PR: #254
Squash merge commit: f18290c1670d774f97a0a926ae19bbbe4da1e720

What this completed for the frozen #252 slice:

• dotfiles-manager list is now the normal app/tool discovery surface.
• dotfiles-manager search <query> is available as read-only app/tool discovery.
• dotfiles-manager explain <app> is available as app-oriented support/provenance explanation.
• The prior selected-settings list remains available through list --settings, including the previous dotfiles-manager.v2.list JSON schema.
• Normal root help now surfaces flattened discovery before the advanced recipe namespace.
• Design evidence and directly affected docs/specs were updated for this slice.

Validation/evidence:

• Subagent design review before implementation: initially requested JSON/error/help/no-mutation specificity; re-review approved after fixes.
• Subagent PR review after implementation: approved, no blocking findings.
• Subagent review of the coverage fix: approved, no blocking findings.
• GitHub Actions for PR Add flattened app discovery commands #254 head 9cd34dd passed:
  • static-checks
  • linux-unit
  • linux-integration
  • linux-contract
  • linux-performance
  • macos-integration
  • coverage-aggregation
  • final-required-check
• Local coverage reproduction after adding direct appdiscovery tests passed the unchanged gate:
  • line: 90.1% / threshold 90%
  • branch: 90.1% / threshold 85%
  • logging-critical branch: 100.0% / threshold 100%

Important limits:

• This PR intentionally did not implement manage / unmanage.
• This PR intentionally did not implement catalog lifecycle or remote catalog behavior.
• v2 CLI: normalize flattened normal-user command vocabulary #252 remains open for the remaining broader command-normalization scope unless the Project Owner chooses to split or close the remaining scope separately.