feat(cli): unify the CLI as noun-verb commands (#96)

[V3RON]

Closes #96

What changed

Every CLI command is now appduct <noun> <verb> [selector] [args], the shape daemon run|start|stop|status already used:

• sessions ls|revoke|link replaces ls, revoke and link.
• tools ls|describe|call replaces tools, tools <name> and invoke.
• events tail|since <cursor> replaces events and events --since.

This is a clean break with no aliases, since we are pre-1.0. A removed top-level word, or a missing or unrecognized verb, is a usage error that names the fix. Every place that documented or hinted at an old form now uses only the new ones: the shipped skill, the READMEs, the website, docs/, and the CLI's own output hints.

Acceptance criteria

#	Criterion	Test	Tier
1	Each new verb produces the same stdout, exit code and --json as the command it replaces; SIGINT still cancels tools call; events since still prints the trailing cursor line	cli-v2.integration.test.ts, events.integration.test.ts, exit-codes.integration.test.ts, e2e/invoke-cancel.e2e.test.ts	integration, e2e
2	ls, revoke, link and invoke exit 64 naming their replacement	noun-verb-cli.integration.test.ts ("removed top-level commands...")	integration
3	A bare or unknown verb on sessions/tools/events exits 64 naming that noun's verbs, like daemon; --help on the noun itself names every verb (via .usage(...)), and so does the global --help	noun-verb-cli.integration.test.ts ("a bare noun with no verb...")	integration
4	events ls exits 64 naming tail and since until #95 lands	noun-verb-cli.integration.test.ts ("events ls is reserved for #95...")	integration
5	A boolean flag ahead of a positional (tools ls --full <selector>, sessions link --qr --open ios-sim) doesn't swallow it	create-cli.test.ts	unit
6	The shipped skill, the READMEs, website/, docs/ (including ARCHITECTURE.md §10) and the CLI's own hints (output.ts, commands/init.ts) use only the new forms; the CLI integration tests run against them	cli.integration.test.ts, output.test.ts (hint text), and each listed doc checked by hand with pnpm check:links	integration, docs
7	A Breaking changelog entry maps each old form to its new one	CHANGELOG.md under ## Unreleased	docs

E2E evidence

Not run; waived by the maintainer (decision on #96). The iOS row the e2e-device skill requires couldn't run in the cloud container, which has no Xcode, no simulator and no KVM.

The change is CLI routing, output hints and docs only. The RPC, the daemon and the app side are untouched. The CLI integration and e2e suites cover the new commands: 69 files in appduct, all green on the merged head.

Checklist

• CHANGELOG.md has an entry under Unreleased
• User-facing docs updated for every surface the change touches
• No new import past a module's index.ts; no new direct node:* I/O outside an adapter
• Simplification checklist from the architecture skill applied (see below)
• docs/ARCHITECTURE.md updated (§10, plus the §9 MCP cross-references)

Simplification notes:

• command-options.ts's splitOptionalSelectorAndTarget is deleted. It decided whether a single positional was a selector or a tool name with the selector omitted, and that can't happen once tools ls and tools describe are separate commands. commands/tools.ts's handleToolsCommand drops the branch that used to guess between them.
• tools/shared-options.ts parses the listing flags for both tools ls and tools describe, so it has the two callers the "simplest thing" rule asks for.

Out of scope

sessions describe, --name on events tail/since (#94), and a working events ls (#95) are all non-goals in the issue. Nothing else came up in passing.

Status

Implement: done (7/7 green) Review: round 4, approve (both nits fixed) E2E: waived (no macOS host; maintainer decision on #96) Ready: yes

🤖 Generated with Claude Code

https://claude.ai/code/session_014wk7yigkPHWoWLy9nvocyt

[V3RON]

Request changes (GitHub won't let this account request changes on its own PR, so this is posted as a comment): 2 blockers, 2 should-fix. The spec is issue #96's rewritten body; the first ## Design comment is superseded.
Fix first: the website landing page still shows appduct invoke, which now exits 64.

Two findings are in files this PR doesn't touch, so they have no inline comment:

• Blocker (criterion 6): website/src/pages/index.astro:21 (invokeCode = "appduct invoke seed_cart ...") and website/src/components/Hero.astro:65 (appduct invoke) still use the removed form. A visitor who copies the homepage example gets exit 64. Switch both to appduct tools call.
• Should-fix: .claude/skills/e2e-device/SKILL.md lines 46, 47, 60, 75-81 and 108 run pnpm playground:appduct -- link|ls|invoke. The pending E2E stage for this PR follows that skill, so its pairing loop and every smoke step will exit 64. Update it to sessions link, sessions ls and tools call.

---

Generated by Claude Code

[V3RON]

Verdict: request-changes (round 2). 1 blocker, 0 should-fix.
Spec: issue #96 body. All four round-1 findings are fixed; I checked the <noun> --help output against the built CLI.
Fix first: the website playground page, playground/README.md and the playground app's on-screen hints still use playground:appduct -- link/ls/tools/invoke/events --follow, and every one of those now exits 64 (criterion 6).

---

Generated by Claude Code

[V3RON]

Verdict: request changes. 2 blockers, 0 should-fix, 1 nit. The round-2 blocker is fixed.
Spec: issue #96 body; the first ## Design comment is superseded.
Fix first: the appduct events since cursor hint in output.ts:754 still says pass --since <cursor>, a removed flag.

---

Generated by Claude Code

[V3RON]

Verdict: approve. 0 blockers, 0 should-fix, 2 nits. Ready for the device test. The spec is issue #96's body.
All three round-3 fixes hold. On the built CLI, events since now prints run "appduct events since N". A repo-wide search, including commands split across line breaks, finds one removed form left: appduct link at docs/ARCHITECTURE.md:578-579. Fix that first, before merge.

---

Generated by Claude Code