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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.

[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]

🟠 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.