fix(cli): give every site command a description and structured help

[ankitranjan7]

The problem

Every leaf under webcmd site shipped with no description and no option help — site field-map --help printed literally add [options] <site> <key> and nothing else — and --help -f yaml was ignored across the whole namespace, so an agent had no way to learn the grammar. In a real eval that produced a cascade: site field-map quotes set (unknown command), note add quotes -m '...' (unknown option), endpoint set q landing --strategy PUBLIC (unknown option). The agent hit its step cap on site field-map --help still not knowing the shape.

What changed

1. Every site group and leaf now has a .description(), and every .argument() / .option() has a help string — 11 leaves, 6 groups.
2. The recurring mistake (site <thing> <site-name> <verb> instead of site <thing> <verb> <site-name>) is now stated on site --help as a Grammar block with a right/wrong pair, and each group's description repeats its own shape.
3. Every site command prints an Example: line and the Agent tip: use '--help -f yaml' footer, matching adapter command help.
4. installCommanderNamespaceStructuredHelp(siteCmd, ...) in src/cli.ts — site was the only built-in namespace missing from that list. It installs installStructuredHelp on the namespace, groups and leaves, so site <anything> --help -f yaml now returns structured YAML.
5. The footer is applied inside helpInformation rather than commander's addHelpText, because addHelpText also wraps structured output and would corrupt the YAML.

Not included: -f/--format flags for commands that lack them, owned by a separate change.

Before / After

$ webcmd site field-map --help                    # BEFORE
Usage: webcmd site field-map [options] [command]

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

Commands:
  add [options] <site> <key>
  help [command]              display help for command

$ webcmd site field-map --help                    # AFTER
Usage: webcmd site field-map add <site> <key> [options]

Explain what opaque response field names mean: webcmd site field-map add <site>
<key>

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

Commands:
  add [options] <site> <key>  Record what one response field means and where it
                              was observed
  help [command]              display help for command

Example: webcmd site field-map add example.com p --meaning "price in cents" --source /api/search
Agent tip: use '--help -f yaml' for structured args/options.

$ webcmd site endpoint set --help                 # BEFORE
Usage: webcmd site endpoint set [options] <site> <name>

Options:
  --url <url>
  --method <method>
  --params <json>
  --rows-path <path>
  --fields <fields>
  --notes <text>
  -h, --help          display help for command

$ webcmd site endpoint set --help                 # AFTER
Usage: webcmd site endpoint set [options] <site> <name>

Record or update one verified endpoint for a site

Arguments:
  site                Site key the memory belongs to, e.g. news.ycombinator.com
  name                Endpoint name to store it under, e.g. search

Options:
  --url <url>         Request URL of the endpoint
  --method <method>   HTTP method, e.g. GET or POST
  --params <json>     Query or body parameters as a JSON object
  --rows-path <path>  Dot path to the result rows inside the response, e.g.
                      data.items
  --fields <fields>   Comma-separated list of the response fields worth keeping
  --notes <text>      Freeform notes about auth, paging or quirks
  -h, --help          display help for command

Example: webcmd site endpoint set example.com search --url https://example.com/api/search --method GET --rows-path data.items
Agent tip: use '--help -f yaml' for structured args/options.

$ webcmd site --help                              # AFTER (tail)
Commands:
  memory          Inspect everything stored for a site: webcmd site memory
                  <show|list> <site>
  note            Read and write freeform site notes: webcmd site note
                  <add|list> <site>
  endpoint        Maintain the verified API endpoints found for a site: webcmd
                  site endpoint <set|stale|list> <site>
  field-map       Explain what opaque response field names mean: webcmd site
                  field-map add <site> <key>
  fixture         Read and write the verify fixtures used by webcmd browser
                  verify: webcmd site fixture <get|put> <site>/<command>
  sample          Keep raw response samples for a site command: webcmd site
                  sample add <site>/<command>
  help [command]  display help for command

Grammar: webcmd site <group> <verb> <site> [args] [options]
         The site name is a positional of the LEAF verb, never of the group.
         Right: webcmd site field-map add example.com price
         Wrong: webcmd site field-map example.com add price

Example: webcmd site note add news.ycombinator.com --text "front page is server-rendered"
Agent tip: use '--help -f yaml' for structured args/options.

$ webcmd site note add --help -f yaml             # BEFORE — flag ignored, plain text
Usage: webcmd site note add [options] <site>

Options:
  --text <markdown>
  --author <author>
  -h, --help         display help for command

$ webcmd site note add --help -f yaml             # AFTER
namespace: site
name: note add
command: webcmd site note add
usage: webcmd site note add <site> [options]
description: Append a markdown note to a site; the site name comes before --text
positionals:
  - name: site
    required: true
    help: Site key the memory belongs to, e.g. news.ycombinator.com
command_options:
  - name: text
    flags: '--text <markdown>'
    help: Note body, in markdown (required; there is no -m alias)
    takes_value: required
    required: true
  - name: author
    flags: '--author <author>'
    help: Who wrote the note
    takes_value: required
namespace_options: []
global_options: [...]
structured_help:
  formats:
    - yaml
    - json
  usage: webcmd site note add --help -f yaml

Tests

Three new cases in src/site-memory/commands.test.ts: no command in the site tree has an empty description; every site option and positional carries a help string; site note add --help names --text and the <site>-first usage. The existing site-help case now asserts the grammar block instead of the removed Authoring: list, and src/hosted/runner.test.ts follows the same rename.

npm run typecheck clean. npx vitest run --project unit: 154 files, 2706 passed, 1 skipped, 0 failed. npm run build clean; every terminal block above is copied from the built dist/src/main.js.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.