Concepts

Webcmd separates messy discovery from reusable execution. Raw browser sessions are evidence; capability graphs are the durable model; workflows and generated CLIs are runnable projections of that model.

flowchart LR; Demo["demonstrate task"] --> Record["record session"]; Record --> Evidence["collect evidence"]; Evidence --> Distill["distill graph"]; Distill --> Graph["capability graph"]; Graph --> Workflow["workflow"]; Graph --> CLI["generated CLI"]; Workflow --> Run["verify and run"]; CLI --> Run;

Lifecycle

Record: webcmd open creates a browser session and, by default, records journal events, snapshots, and redacted network evidence.
Inspect: webcmd journal, webcmd snapshot, and webcmd network * expose enough evidence to classify actions, selectors, auth, API candidates, and side effects.
Distill: webcmd distill prepare packages evidence; an agent writes a distill plan; webcmd distill apply updates the graph.
Materialize: webcmd workflow or webcmd cli creates an agent-readable packet, then applies a plan to write runnable artifacts.
Verify and run: webcmd verify checks generated structure/runtime contracts; webcmd run executes exported workflows.

Vocabulary

Term	Meaning
Session	A named browser runtime, usually controlled by `--session <id>`.
Journal	Append-only event log at `.webcmd/sessions/<session>/journal.jsonl`.
Snapshot	Semantic page state captured before/after actions or by `webcmd snapshot`.
Network record	Redacted HTTP evidence at `.webcmd/sessions/<session>/network.jsonl`.
Network mark	Reviewer classification in `network.marks.json`: `important`, `ignore`, or `side-effect`.
Distill packet	Evidence bundle that tells an agent how to write graph changes.
Capability graph	Strict JSON model at `.webcmd/graphs/<app-id>/capabilities.json`.
Capability	Reusable app primitive with inputs, output, auth contract, effects, and evidence ids.
Scenario	Ordered capability usage sample from a recorded task.
Command mapping	Graph-level description of how a generated CLI command maps flags to capabilities.
Workflow	Executable `.mjs` script exported under `.webcmd/exports/workflows/<domain>/`.
Generated CLI	Standalone package exported under `.webcmd/exports/clis/<domain>/` with a `SKILL.md`.
Authoring packet	Meta-planning artifact used for create/update/heal requests.
Profile	Persistent browser identity under `.webcmd/profiles/<name>`.

Capability graph shape

{
  "version": 1,
  "app": {
    "id": "hacker-news",
    "name": "Hacker News",
    "baseUrls": ["https://news.ycombinator.com"],
    "auth": { "requiresAuth": false, "provider": "none" }
  },
  "capabilities": [],
  "scenarios": [],
  "commands": [],
  "provenance": { "distillations": [] }
}

Capabilities are intentionally small and remixable. They carry:

Field	Purpose
`id`, `description`, `visibility`	Stable identity and human summary.
`evidence`	Journal, network, and snapshot ids that justify the capability.
`inputs`	Typed params: `string`, `number`, `boolean`, or `json`.
`output`	Output type plus optional item name or JSON schema.
`auth`	Replay strategy and validation hints; never credential values.
`implementation`	Optional graph-local implementation path/export, often `atoms/<name>.mjs`.
`networkNotes`	Useful request observations that should not become secrets.
`preconditions`, `effects`	Runtime requirements and visible or backend side effects.

Auth strategies

Every distilled capability must classify auth:

Strategy	Use when
`public`	No identity material is required.
`browser-cookie`	Browser cookies are sufficient for replay.
`browser-request`	Browser-context HTTP can replay a stable request.
`page-fetch`	Auth/signing depends on page runtime, storage, service workers, or app JS.
`intercept`	The workflow should trigger UI and observe the app’s own response.
`ui`	Visible UI behavior is the stable primitive.
`local`	Named env/config credentials are required.
`manual`	Login, SSO, 2FA, device approval, or human checkpoints are required.

Auth contracts describe required, profileRequired, origins, replaySurface, sources, validation probes, refresh hints, and evidence ids. They must not store cookies, tokens, passwords, CSRF values, or other credential material.