> ## Documentation Index
> Fetch the complete documentation index at: https://webcmd.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Webcmd Works

> How agents reuse commands, explore unfamiliar surfaces, retain useful knowledge, and create deterministic CLIs.

# How Webcmd Works

Webcmd gives an agent one rule: reuse what already exists before exploring.

## The Agent's Decision Flow

1. Load `webcmd-usage` and discover relevant existing adapters.
2. Use an existing command when it already satisfies the request.
3. Explore through a browser only when the surface is unfamiliar or broken.
4. Retain sitemap knowledge when it will help future browser work.
5. Create or repair an adapter when the workflow should become repeatable.

## From Exploration to a Command

Exploration is for understanding an unfamiliar surface. A verified, reusable workflow becomes an adapter command, so the next agent can use a stable CLI instead of repeating browser work.

## Adapters and Stable Output

An adapter turns a website, app, API, or local surface into one or more commands. Site adapters are installed as plugins; the core package bundles none. Legacy private adapters in `~/.webcmd/clis/` remain discoverable, and local tools can also be exposed as external CLIs.

Commands should have clear names, stable inputs, useful errors, and JSON-friendly output. Stable output is the contract that lets another agent reuse a successful workflow.

```text theme={null}
Return JSON rows with id, title, status, owner, updated_at, and url. Keep those fields stable across future updates.
```

## Execution Strategies

The agent chooses the strategy; the human describes the outcome and constraints.

| Strategy    | Meaning                                                              |
| ----------- | -------------------------------------------------------------------- |
| `PUBLIC`    | Uses public pages or APIs. No browser or login required.             |
| `COOKIE`    | Uses a logged-in browser profile for authenticated requests.         |
| `INTERCEPT` | Uses browser-derived request context, then replays a useful request. |
| `UI`        | Drives the live page UI.                                             |
| `LOCAL`     | Talks to a local app, service, or CLI.                               |

## Profiles, Sessions, And Tabs

A Profile is the browser identity and storage bucket, such as `default` or `work`. A Session is a named browser workspace inside a Profile. Create one with `webcmd --profile work session create "Work Project"`, then use its returned readable ID with `webcmd --profile work --session work-project-k7 browser tabs`. Session IDs are immutable and Profile-scoped. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. A tab is one page inside that Session.

Adapter browser commands can use `siteSession: 'ephemeral'` for an isolated tab or `siteSession: 'persistent'` for a longer same-site workflow. Those adapter site-session modes are separate from raw browser Sessions.

## What the Human Needs to Decide

Describe the outcome, required fields, constraints, and any approval boundaries. The agent decides whether an existing command, browser exploration, sitemap memory, or a reusable adapter is the right path.