Consistent sub-item command pattern (subcommands vs hyphenated)

[andybergon]

Problem

Sub-item operations use two different patterns inconsistently across domains:

Pattern	Example	UX
Subcommand (nested)	docs comments add, gmail labels create	resource sub-resource action
Hyphenated (flat)	sheets add-tab, forms add-question	resource action-subresource

Both patterns exist, sometimes within the same domain doing the same kind of CRUD on sub-resources.

Audit

Mixed-pattern domains (the problem)

Domain	Hyphenated sub-items	Nested sub-items
forms	questions (add-question, delete-question, move-question)	responses (responses list/get), watches (watch create/list/delete/renew)
docs	tabs (list-tabs)	comments (comments list/get/add/reply/resolve/delete)
gmail	mark-read	labels, messages, threads, drafts — all nested

Forms is the worst offender — questions and responses are both sub-resources of a form with multiple CRUD ops, yet they use opposite patterns.

Internally consistent domains (for reference)

Domain	Pattern	Sub-items
sheets	all hyphenated	tabs (add-tab, rename-tab, delete-tab), notes (update-note)
slides	all hyphenated	slides (add-slide, list-slides, delete-slide, read-slide, update-notes, replace-slide)
chat	all nested	spaces, messages, threads, dm
classroom	all nested	courses, students, teachers, coursework, submissions, ...
calendar	all hyphenated	special actions only (focus-time, out-of-office, working-location) — arguably fine since these aren't sub-resource CRUD

Proposed rule

• Subcommand when the sub-item is a distinct noun with CRUD operations → resource sub-resource action
• Hyphenated only for special one-off actions that aren't CRUD on a sub-resource (e.g. calendar focus-time, docs find-replace, gmail mark-read)

Scope

This is likely a large refactor in terms of lines touched — every renamed command needs its struct, aliases, help text, and tests updated. Probably best to tackle after clearing some of the open PRs, and in the meantime use this as a guideline for new commands: new sub-resource CRUD should use the subcommand pattern.

[andybergon]

cc @steipete — I think this is important for keeping the CLI consistent as it grows, but since the refactor would touch a lot of commands it'll likely conflict with open PRs. Probably best driven by a maintainer who can time it right (e.g. after a batch of PRs lands).