fix(cli): group the browser command surface and drop help-list noise

[Agnik47]

Fixes #317.

Problem

webcmd browser --help printed one flat list mixing two unrelated surfaces, plus Commander's auto help [command] a line below the -h, --help option that does the same thing:

Usage: webcmd browser [options] [command]

bind, close, fork, init, run, snapshot, tabs, verify

Options:
  -h, --help               display help for command

Commands:
  init <name>              Generate adapter scaffold in ~/.webcmd/clis/
  fork <name>              Fork an installed plugin command into a private copy
  verify [options] <name>  Execute an adapter and validate output; uses fixture
                           at ~/.webcmd/sites/<site>/verify/<cmd>.json when
                           present
  tabs                     List pages in the existing browser session
  bind [options]           Bind this session to an existing page
  run [options]            Run JavaScript with Playwright
  snapshot [options]       Inspect the current page with a compact accessibility
                           snapshot
  close                    Close or detach this browser session
  help [command]           display help for command

docs/cli-reference.mdx already states that "the public raw-browser surface is tabs, bind, run, and snapshot", but the help output gave init/fork/verify equal billing with no indication they are adapter-authoring commands.

After

Usage: webcmd browser [options] [command]

bind, close, init, run, snapshot, tabs, verify

Options:
  -h, --help               display help for command

Browser session commands:
  tabs                     List pages in the existing browser session
  bind [options]           Bind this session to an existing page
  run [options]            Run JavaScript with Playwright
  snapshot [options]       Inspect the current page with a compact accessibility
                           snapshot
  close                    Close or detach this browser session

Adapter authoring commands:
  init <name>              Generate adapter scaffold in ~/.webcmd/clis/
  verify [options] <name>  Execute an adapter and validate output; uses fixture
                           at ~/.webcmd/sites/<site>/verify/<cmd>.json when
                           present

Changes

• Grouping. Browser subcommands are grouped under Browser session commands: / Adapter authoring commands:. The mapping lives next to browserCommandCatalog and is consumed by both cli.ts and hosted/browser-args.ts, so local and hosted browser --help present the same shape. The catalog entries and hosted-contract.json are untouched.
• Ordering. init/fork/verify are now attached after the session commands (via new Command(...) + addCommand, matching how tabs/bind/run/snapshot/close were already registered), so the group the namespace is named for comes first. Leaf help and error text for these commands is byte-identical to before.
• fork. It copies a plugin command into ~/.webcmd/clis and never touches a Session — exactly what webcmd adapter override does. adapter override gains a fork alias, so webcmd adapter fork <site>/<command> is the local spelling, and browser fork is hidden from local help while staying registered and dispatchable. Hosted help still lists it, since hosted mode has no adapter fork.
• help [command]. Namespace help no longer advertises Commander's auto help command; the root presentation already omitted it. webcmd <namespace> help <command> still works — it is only dropped from the listed commands. This applies to every namespace (browser, adapter, plugin, profile, daemon, auth, session, ...).

Not included

init and verify are grouped, not relocated. Moving them to webcmd adapter init|verify would be a breaking surface change: they are the documented cloud authoring flow (hosted/runner.ts prints webcmd browser init / webcmd browser verify after plugin create), they are referenced throughout the bundled skills (webcmd-adapter-author, webcmd-usage, webcmd-autofix), and they are part of the hosted browser contract. Happy to do that relocation in a follow-up if you'd like it — it needs a call on hosted routing and a skills/docs sweep.

Verification

• npx tsc --noEmit clean.
• npx vitest run --project unit: no new failures. The 20 remaining failures on this branch are pre-existing on main in this environment (Windows EPERM on symlink in plugin/discovery/site-memory/docs-sync-review tests, plus one hosted file-upload test).
• New coverage in src/browser/command-catalog.test.ts (group mapping, group order, fork hidden but registered, adapter override|fork alias) and src/help.test.ts (visibleChildCommands / hideAutoHelpCommands, including that help <command> still dispatches).
• src/hosted/runner.test.ts "matches the exact local text help for every raw-session browser leaf" still passes, so local and hosted leaf help remain byte-identical.
• npm run check:typed-error-lint and npm run check:silent-column-drop report no new violations.

[github-actions]

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.