Unify resource commands under singular nouns

[robzolkos]

Give each HEY resource one predictable noun-first command family so people and agents can discover list, view, and mutations the way they do in gh. Every existing plural listing and direct detail invocation remains executable; primary help, examples, breadcrumbs, and agent guidance promote only the canonical forms.

Review readiness: ✅ Yes
Risk: 🟡 Medium — routing and discovery change across six public command families, with explicit compatibility paths and parity coverage preserving existing scripts.
Decision: None

✅ Change — six split command pairs now read as single noun-first families

Before

boxes                    labels                    clips
└── list boxes            └── list labels           └── list clips
box <name|id>            label <id>                clip
└── read one box          ├── read one label        ├── create
                          └── mutations             └── delete

❌ Listing and management require remembering singular versus plural.

After

box                      label                     clip
├── list                 ├── list                  ├── list
└── view <name|id>       ├── view <id>             ├── create
                         └── mutations             └── delete

collection               workflow                  snippet
├── list                 ├── list                  ├── list
├── view <id>            ├── view <id>             └── mutations
└── mutations            └── mutations

✅ One noun leads to every operation.  ← CHANGED

The same operation factories create independent Cobra commands and flag state for canonical and compatibility routes. list/view stay leaf-local, so mutation commands do not inherit unrelated paging flags.

✅ Compatibility — old invocations remain executable and are identified, not promoted

• ✅ boxes, labels, collections, workflows, clips, and snippets still run and carry compatibility_for in hey commands --json.
• ✅ box <name|id>, label <id>, collection <id>, and workflow <id> still run and carry compatibility_usage on their canonical family.
• ✅ Root help and --agent --help show only canonical families; invoking a family without an action shows its complete canonical command help.
• ✅ hey commands --styled now lists the complete nested catalog and labels compatibility forms.
• ✅ box view list addresses a box named list; box -- list preserves the direct-form escape while box list remains the reserved action.
• ✅ .surface only adds commands and flags; it removes none.

✅ Evidence — focused parity, full checks, race coverage, and real Haystack verification pass

• ✅ GOWORK=off make check
• ✅ GOWORK=off make race-test
• ✅ GOWORK=off go test -race -count=1 ./internal/cmd after final review fixes
• ✅ GOWORK=off make coverage — 82.7%, above the 70.8% floor
• ✅ GOWORK=off make test-e2e — 177 checks
• ✅ Strict real-Haystack canonical/compatibility smoke matrix — list parity for all six families and view parity for box, label, collection, and workflow
• ✅ govulncheck ./... — no called vulnerabilities
• ✅ gitleaks detect --source . --verbose --redact — no leaks
• ✅ Command discovery recording — shows canonical-only root help, box list/box view, and compatibility metadata.

The full strict smoke suite also reached and passed the new matrix. Its unrelated shared-dev failures were attachment/contact/search 500s, cookie-only auth-token expectations, a missing seen-posting fixture, and dev-version detection; none touch the command routing changed here.

✅ Scope — CLI routing and guidance change; APIs, mutations, and the TUI remain unchanged

Included: command factories for six resources, root and agent help, complete command-catalog presentation and metadata, breadcrumbs/setup/watch guidance, README/API/Omarchy/agent-skill documentation, additive surface entries, unit parity tests, and real-server smoke parity.

Preserved: SDK calls, request and response shapes, output formats, account behavior, mutation semantics, existing scripts, plural/direct invocations, and TUI behavior.

Non-goals: removing compatibility forms, adding clip/snippet detail endpoints that the SDK does not expose, or changing unrelated command families.

➖ Delivery — no migration, configuration, deployment ordering, or cleanup

The additive command tree ships in the CLI binary. Rollback is a normal code revert; no data or external resources are involved.

✅ Review decision — no unresolved decision; focus on routing parity and discovery boundaries

Please confirm that the factory split keeps canonical and compatibility flag state independent, and that hey commands gives agents complete compatibility metadata without putting old forms back into primary help.

✅ Review path — command construction first, then compatibility proof and guidance

1. internal/cmd/label.go and internal/cmd/box.go — representative list/view factories and reserved-name routing.
2. internal/cmd/canonical_commands_test.go — API/envelope parity, independent flags, box-name escape, catalog, and agent-help assertions.
3. internal/cmd/commands.go and internal/cmd/help.go — canonical discovery and compatibility metadata.
4. tests/smoke/canonical_commands_test.go — real-Haystack canonical/compatibility parity.
5. README.md, skills/hey/SKILL.md, API-COVERAGE.md, and docs/omarchy.md — user, agent, API, and integration guidance.
6. The remaining command files update canonical breadcrumbs/agent notes; .surface records additive routes and internal/cmd/help_test.go pins canonical-only root presentation.

Origin and supporting links: Basecamp card

---

Summary by cubic

Unifies resource commands under singular, noun‑first families and promotes list/view, and now shows curated family help when no action is given. Previously, listings used plurals and details were invoked directly; now box, label, collection, workflow, clip, and snippet are canonical, and running a family with no args prints its list/view help instead of an error.

• Root and agent help show only canonical families; hey commands --json|--styled include compatibility metadata via compatibility_for and compatibility_usage, and help hides compatibility usage.
• box reserves list and view; address a box named “list” with hey box view list or escape via hey box -- list.
• Canonical and compatibility routes use separate factories and flags; list/view keep pagination flags leaf‑local so mutations do not inherit them.
• Tests assert canonical/compatibility parity, command‑catalog metadata, canonical‑only agent help, reserved‑name routing, and family‑help behavior.
• Docs and surfaces updated (README, skills, API coverage, .surface); APIs, mutations, output formats, and the TUI are unchanged; no migration required.

^{Written for commit df24dc8. Summary will update on new commits.}

[Copilot]

Pull request overview

Unifies six resource command families under canonical singular noun-first routes while preserving compatibility forms.

Changes:

• Adds canonical list and view subcommands with independent flag state.
• Updates help, catalog metadata, documentation, and breadcrumbs.
• Adds unit and smoke parity coverage for canonical and compatibility routes.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
.surface	Records additive command routes and flags.
AGENTS.md	Updates canonical box guidance.
API-COVERAGE.md	Maps endpoints to canonical commands.
README.md	Documents noun-first command families.
docs/omarchy.md	Updates plugin command examples.
skills/hey/SKILL.md	Updates agent triggers and guidance.
internal/cmd/box.go	Adds box list and box view.
internal/cmd/boxes.go	Builds canonical and compatibility listings.
internal/cmd/bulk_reply.go	Updates posting-ID guidance.
internal/cmd/canonical_commands_test.go	Tests routing, parity, metadata, and discovery.
internal/cmd/clip.go	Adds clip list.
internal/cmd/collection.go	Adds collection list and view.
internal/cmd/commands.go	Adds compatibility metadata and nested catalog output.
internal/cmd/help.go	Promotes canonical families in root help.
internal/cmd/help_test.go	Updates the root-help snapshot.
internal/cmd/ignore.go	Updates canonical box guidance.
internal/cmd/label.go	Adds label list and view.
internal/cmd/move.go	Updates canonical box guidance.
internal/cmd/postings_listing.go	Updates command references.
internal/cmd/root.go	Exposes compatibility metadata in agent help.
internal/cmd/seen.go	Updates seen/unseen guidance.
internal/cmd/setup.go	Promotes canonical setup examples.
internal/cmd/setup_test.go	Updates setup-output expectations.
internal/cmd/share.go	Updates topic-ID guidance.
internal/cmd/snippet.go	Adds snippet list.
internal/cmd/spam.go	Updates canonical box guidance.
internal/cmd/stop_ignoring.go	Updates canonical box guidance.
internal/cmd/trash.go	Updates canonical box guidance.
internal/cmd/watch.go	Updates recovery guidance.
internal/cmd/workflow.go	Adds workflow list and view.
tests/smoke/canonical_commands_test.go	Adds real-server parity coverage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.