Agent Guide

Webcmd is built for coding agents. The CLI gives agents durable evidence packets and strict apply commands so they can create, update, and repair browser automations without replaying raw exploration forever.

flowchart TD; Request["user request"] --> Packet["authoring packet"]; Packet --> Phase{"packet phase"}; Phase --> Discovery["discovery"]; Phase --> Distill["distill"]; Phase --> Build["build"]; Phase --> Repair["repair"]; Discovery --> Packet; Distill --> Build; Build --> Verify["verify"]; Repair --> Verify;

Install the skills

webcmd setup
webcmd setup --scope local
webcmd setup --skills-root /path/to/.agents/skills

Global setup installs to ~/.agents/skills/. Local setup installs to .agents/skills/. Generated app CLIs can also install their own skill when materialized:

webcmd cli <app-id> --plan <plan.json> --install-skill
webcmd cli <app-id> --plan <plan.json> --install-skill /path/to/skills

Generated CLIs get SKILL.md; workflows do not. A generated CLI skill carries app metadata, command contracts, provenance, and safe smoke tests.

Agent decision loop

User asks	First command
Create a new CLI	`webcmd author cli --operation create --task "..." --app-id <id> --url <url>`
Add/change a CLI command	`webcmd author cli --operation update --task "..." --app-id <id> --target <cli-dir>`
Repair a CLI	`webcmd author cli --operation heal --task "..." --app-id <id> --target <cli-dir>`
Create a workflow	`webcmd author workflow --operation create --task "..." --app-id <id> --url <url>`
Repair a workflow	`webcmd author workflow --operation heal --task "..." --app-id <id> --target <workflow.mjs>`

Read the packet before planning. Its phase decides the next move:

Phase	Agent action
`discovery`	Open/drive a browser, capture snapshots and network, respect the budget.
`distill`	Run `webcmd distill prepare`, inspect evidence, write a distill plan, apply it.
`build`	Prepare workflow/CLI materialization packet and write the requested plan.
`repair`	Reproduce or classify the failure, then update graph/artifact as needed.

Discovery discipline

webcmd open "<url>" --session <id> --headed
webcmd snapshot --session <id>
webcmd click --session <id> --role button --name "Continue"
webcmd fill "value" --session <id> --label "Search"
webcmd network summary --session <id>
webcmd network candidates --session <id>
webcmd close --session <id>

Prefer accessible selectors (role/name, label, placeholder, test-id) before CSS/XPath. Mark network evidence when it affects safety:

webcmd network mark n12 --session <id> --mark important
webcmd network mark n13 --session <id> --mark side-effect
webcmd network mark n14 --session <id> --mark ignore

Handoff and resume

Use handoff when the human must login, approve, solve 2FA, or demonstrate a step:

webcmd handoff --session <id>
# user acts in the headed browser
webcmd resume --session <id>
webcmd journal --session <id>

Resume prints the compact journal so the agent can continue with the new evidence.

Distillation rules

A distill plan should only write graph knowledge: discarded events, reusable inputs, capabilities, scenarios, and auth contracts. It should use evidence ids from the packet. It should not store credentials or copy secret values from network records.

webcmd distill prepare --session <id> \
  --sample-task "Search jobs by keyword" \
  --sample keyword=engineer \
  --sample location=Remote

webcmd distill apply .webcmd/sessions/<id>/distill.plan.json

Capabilities should be small, typed, and reusable. Put app-level reusable code under graph-local implementation paths such as atoms/search.mjs; put workflow-specific filtering or presentation in the workflow/CLI materialization instead.

Materialization rules

For workflows:

webcmd workflow <app-id> --task "Search jobs by keyword"
webcmd workflow <app-id> --plan .webcmd/graphs/<app-id>/workflow.plan.json
webcmd verify .webcmd/exports/workflows/<domain>/<workflow-id>.mjs

For CLIs:

webcmd cli <app-id> --task "Create a jobs CLI"
webcmd cli <app-id> --plan .webcmd/graphs/<app-id>/cli.plan.json --install-skill
webcmd verify .webcmd/exports/clis/<domain>

Never invent missing capabilities during materialization. If the graph does not contain the needed app behavior, collect/distill more evidence first.

Generated CLI smoke tests

CLI command contracts may include smoke tests, but they must be safe validation invocations. The accepted safe flags are --help, --dry-run, and --validate. A generated skill should never tell an agent to run a mutating smoke test.