Architecture

Webcmd is a local evidence-to-artifact pipeline. The CLI owns browser sessions and state, the runtime abstracts Playwright/Cloak/Camofox, packet builders give agents bounded planning inputs, and materializers apply strict Zod-validated plans into workspace-owned files.

flowchart LR; CLI["webcmd CLI"] --> Runtime["browser runtime"]; CLI --> State["workspace state"]; Runtime --> Providers["Cloak Playwright Camofox"]; State --> Evidence["sessions and evidence"]; Evidence --> Packets["agent packets"]; Packets --> Plans["validated plans"]; Plans --> Graph["capability graph"]; Graph --> Exports["runnable exports"];

Storage layout

Path	Contents
`.webcmd/sessions/<session>/`	Live/recorded session state.
`.webcmd/sessions/<session>/journal.jsonl`	Browser action timeline and recorder events.
`.webcmd/sessions/<session>/network.jsonl`	Redacted request/response evidence.
`.webcmd/sessions/<session>/network.marks.json`	Human/agent review marks for network records.
`.webcmd/sessions/<session>/snapshots/`	Semantic snapshot JSON files.
`.webcmd/sessions/<session>/distill.packet.json`	Distillation prompt context generated from a session.
`.webcmd/graphs/<app-id>/capabilities.json`	Typed capability graph.
`.webcmd/graphs/<app-id>/workflow.packet.json`	Workflow materialization context.
`.webcmd/graphs/<app-id>/cli.packet.json`	CLI materialization context.
`.webcmd/exports/workflows/<domain>/`	Runnable workflow `.mjs` files.
`.webcmd/exports/clis/<domain>/`	Generated CLI package, README, source, and `SKILL.md`.
`.webcmd/profiles/<name>/`	Persistent browser identity profiles.
`.webcmd/authoring/`	Create/update/heal authoring packets.

Runtime layer

createWorkflowRuntime() returns a public BrowserRuntime over one of these providers:

Provider	Notes
`cloak`	Default browser provider.
`chromium`, `firefox`, `webkit`	Playwright-backed browser engines.
`chromium --channel chrome`	Uses an installed Chrome channel; only valid with Chromium.
`camofox`	Remote Camofox service; requires `--camofox-url` and does not support Webcmd auth profiles.

Generated workflows should import only from webcmd/runtime and use the public methods: goto, click, fill, press, wait, snapshot, http, pageFetch, waitForResponse, and close. The runtime also accepts an injected options.runtime, which is how verification runs workflows without launching a real browser.

CLI command families

Family	Role
Session control	`open`, `snapshot`, `goto`, `click`, `fill`, `press`, `wait`, `close`, `handoff`, `resume`, `journal`.
Evidence review	`network list/show/summary/diff/mark/candidates`.
Auth	`auth doctor/login/bind`.
Planning	`author cli`, `author workflow`, `distill prepare`, `workflow <app-id> --task`, `cli <app-id> --task`.
Applying	`distill apply`, `workflow <app-id> --plan`, `cli <app-id> --plan`.
Exports	`workflow list`, `run`, `verify`, `apps index`, `apps match`.

Packet boundary

Packets are the main safety boundary between Webcmd and an agent. Webcmd gathers code-backed context, state paths, relevant evidence, response schema, required reading, and the exact apply command. The agent writes only the requested plan.

sequenceDiagram; participant W as Webcmd; participant A as Agent; participant F as Filesystem; W->>F: read graph sessions exports; W->>A: write packet with schema; A->>F: read required evidence; A->>F: write plan JSON; W->>F: validate and apply plan; W->>F: update graph or export;

Packet	Generated by	Applied by
Authoring packet	`webcmd author cli/workflow`	Not applied directly; it selects the next phase.
Distill packet	`webcmd distill prepare`	`webcmd distill apply <plan>`.
Workflow packet	`webcmd workflow <app-id> --task`	`webcmd workflow <app-id> --plan <plan.json>`.
CLI packet	`webcmd cli <app-id> --task`	`webcmd cli <app-id> --plan <plan.json>`.

Traceability Map

The boss-level thing Webcmd gives you is not just automation. It gives you an audit trail from a real browser demonstration to a verified command.

flowchart LR; Journal["journal event ids"] --> Evidence["snapshots and network records"]; Evidence --> Distill["distill packet"]; Distill --> Capability["capability evidence ids"]; Capability --> Auth["auth contract"]; Capability --> Materialization["workflow or CLI plan"]; Materialization --> Export["generated artifact"]; Export --> Verify["verification report"];

Trace point	Why it matters
Journal event ids	Shows which human/agent browser actions taught the system.
Snapshot and network ids	Separates visible UI evidence from request/API evidence.
Capability evidence ids	Keeps every reusable primitive tied to source observations.
Auth contract	Records replay strategy without storing secret values.
Materialization plan	Explains why a workflow or CLI command uses specific capabilities.
Verification report	Proves the generated artifact still satisfies the runtime contract.

This is the difference between “we scripted a website” and “we can explain, verify, and repair every generated command.”

Validation and path safety

Webcmd validates all core artifacts with Zod. App ids must be single path segments. Graph implementation paths must stay inside the graph directory. Generated CLI package paths must be relative package files, not absolute paths, not .., and not the package root. Workflow ids must be single path segments. Materializers assert that graph, workflow, and CLI writes stay under workspace-owned directories.

Why journals are not replayed

Journals intentionally capture exploration: duplicate clicks, failed selectors, redirects, incidental requests, and human handoffs. Replaying them would preserve mistakes. Distillation turns evidence into capabilities with typed inputs, outputs, effects, auth contracts, and provenance; materialization then writes the deterministic projection needed for a specific task.