feat: add readable session identifiers

README.md

@@ -38,17 +38,20 @@ For local, multi-step browser exploration, agents can send one sandboxed
 Playwright-style program to an explicit browser session:
 
 ```bash
-webcmd session create -f json
-webcmd --session session_abc browser run --file explore.js
+webcmd --profile work session create "Work Project" -f json
+# id: work-project-k7
+webcmd --profile work --session work-project-k7 browser tabs
+webcmd --profile work --session work-project-k7 browser run --file explore.js
 printf 'return await page.title();' \
-  | webcmd --session session_abc browser run --stdin
-webcmd session close session_abc
+  | webcmd --profile work --session work-project-k7 browser run --stdin
+webcmd --profile work session close work-project-k7
 ```
 
 Profiles are cookie jars; Sessions are independent browser windows within a
-profile, so parallel agents should create separate Sessions. Adapter commands
-use an adapter-default Session unless `--session` intentionally routes them to
-an explicit one.
+profile, so Session IDs are immutable, Profile-scoped, and safe to reuse for
+that Session's lifetime. Parallel agents should create separate Sessions.
+Adapter commands without `--session` reuse the Profile's `adapter-default`
+Session. Raw browser commands require an explicit readable Session ID.
 
 ## Demo
 

docs/agents/claude-code.md

@@ -88,7 +88,7 @@ Denying these tools does not affect the Bash tool, which is how `webcmd` is driv
 | Skill text looks out of date | `webcmd update` upgrades only the CLI. Run `claude plugin update webcmd@webcmd` to refresh plugin skills. |
 | Claude Code still uses `WebFetch` / `WebSearch` | Confirm `permissions.deny` lists both in the active settings file, then restart `claude`. |
 | `claude` requires permission prompts for `webcmd` | The Bash tool still asks before non-approved commands; run `claude --dangerously-skip-permissions` or allow the shell command if you accept the risk. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/codex-cli.md

@@ -84,7 +84,7 @@ disabled_tools = ["navigate", "screenshot"]
 | Search results look stale | `web_search` defaults to `"cached"`. Set `web_search = "live"` in `~/.codex/config.toml`, then restart `codex`. |
 | `web_search` was disabled and search stopped working | Expected. Set it back to `"live"` or `"cached"` — Webcmd does not replace search. |
 | `webcmd` not found in Codex shell | Confirm `webcmd` is on the PATH Codex uses; restart after installing the CLI. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/cursor.md

@@ -52,8 +52,8 @@ Use Webcmd for anything on the open web — fetching, authenticated
 third-party sites, multi-step automation, workflows worth making reusable:
 
 - Check `webcmd list -f json` for an adapter that covers the task; use it first.
-- Otherwise create a session, then drive it with `webcmd --session <session-id> browser ...` via the shell tool.
-- Run `webcmd doctor` first; use `webcmd session list` to inspect state and `webcmd session close <session-id>` when finished.
+- Otherwise run `webcmd --profile work session create "Work Project"`, then drive its returned readable ID with `webcmd --profile work --session work-project-k7 browser tabs` via the shell tool.
+- Run `webcmd doctor` first; use `webcmd --profile work session list` to inspect state and `webcmd --profile work session close work-project-k7` when finished.
 - For login walls, use Webcmd's human handoff; never type passwords, OTPs, cookies, or credentials.
 
 Use the native Browser tool only for the app being edited: localhost dev server,
@@ -77,7 +77,7 @@ Note that the rule is guidance, not a block. Cursor's Browser Automation has bee
 | Cursor uses its Browser tool for external sites | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`; for a hard block, set Browser Automation to Off. |
 | Browser Automation turns itself back on | Known behaviour — a prompt mentioning "browser" can re-enable it. Avoid the word, or turn it off in the agent window. |
 | `webcmd` not found in Cursor shell | Confirm `webcmd` is on the PATH the Cursor shell uses; restart Cursor after installing the CLI. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/hermes.md

@@ -52,7 +52,7 @@ Hermes' web surface spans three toolsets:
 
 **Hermes toggles toolsets, not individual tools.** There is no way to drop `web_extract` while keeping `web_search`, so leave the `web` toolset on and steer the agent with instructions instead. Add this to your Hermes system prompt or project instructions:
 
-> Use Webcmd (`webcmd list`, then `webcmd session create -f json` and `webcmd --session <session-id> browser ...` via the `terminal` toolset) for anything on the open web: fetching, authenticated third-party sites, multi-step automation. Prefer it over `web_extract`. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. Keep using `web_search` and `x_search` to find URLs.
+> Use Webcmd (`webcmd list`, then `webcmd --profile work session create "Work Project"` and `webcmd --profile work --session work-project-k7 browser tabs` via the `terminal` toolset) for anything on the open web: fetching, authenticated third-party sites, multi-step automation. Prefer it over `web_extract`. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. Keep using `web_search` and `x_search` to find URLs.
 
 Also check the `computer_use` toolset. It drives the whole desktop rather than a browser, so it overlaps with Webcmd whenever it is aimed at a website. Disable it if the user does not need desktop control.
 
@@ -85,7 +85,7 @@ Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`.
 | Search disappeared after disabling `web` | Expected: `web_search` and `web_extract` share one toolset. Re-enable `web` and steer the agent with instructions instead. |
 | `x_search` appeared on its own | Expected: it auto-registers when `XAI_API_KEY` or Grok OAuth is configured. Leave it — it is search. |
 | `webcmd` not found in Hermes terminal | Confirm `webcmd` is on the host PATH that Hermes' `terminal` toolset uses; non-interactive shells may skip shell init files. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/openclaw.md

@@ -82,7 +82,7 @@ Or remove it entirely — CLI, `browser.request` gateway method, and agent tool
 | OpenClaw uses `browser` for external sites | Remind it that Webcmd handles the open web; for a hard block, set `browser.enabled: false`. |
 | Search stopped working | Check whether `web_search` was denied. Webcmd does not replace search — remove it from `tools.deny`. |
 | `webcmd` not found in OpenClaw exec | Confirm `webcmd` is on the PATH the Gateway's `exec` tool uses; restart after installing the CLI. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/opencode.md

@@ -59,8 +59,8 @@ Deny `webfetch` so OpenCode cannot fall back to it while Webcmd is its browser s
 | Skills not loading in OpenCode | Run `webcmd skills add` with the `agents` provider, restart OpenCode, and check `/skills`. |
 | OpenCode still uses `webfetch` | Confirm `permission.webfetch` is `deny` in the active config, then restart OpenCode. |
 | `websearch` is missing entirely | It registers only with the OpenCode provider or `OPENCODE_ENABLE_EXA=1`. Not a Webcmd problem. |
-| `webcmd browser` errors | Read `webcmd-usage` and `webcmd-browser` skills; create a session and pass its ID as root `--session`. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| `webcmd browser` errors | Read `webcmd-usage` and `webcmd-browser`; create a named Session and pass its readable ID as root `--session`. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/agents/pi.md

@@ -66,7 +66,7 @@ To remove one outright, delete its folder — for example `~/.pi/agent/skills/pi
 | Pi still uses `browser-tools` or a web-fetch extension | Remove the skill folder or prompt Pi to prefer Webcmd, then restart Pi. |
 | Search stopped working after removing an extension | Some extensions bundle search with extraction. Reinstall it and steer Pi with instructions instead — Webcmd does not replace search. |
 | `webcmd` not found in Pi's shell | Confirm `webcmd` is on the PATH Pi's `bash` tool uses; restart Pi after installing the CLI. |
-| Browser Session idles or loses its window | Keep the same Session ID; the next `webcmd --session <session-id> browser ...` command reopens it. Use `webcmd session create -f json`, `webcmd session list`, and `webcmd session close <session-id>` for lifecycle. |
+| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. |
 
 ## See also
 

docs/cli-reference.mdx

@@ -52,44 +52,44 @@ webcmd web fetch --url "https://www.bing.com/search?q=agentic%20browser%20automa
 For either code, create one Session, navigate with `browser run`, inspect with a read snapshot, reuse the Session for allowed browser work, and close it:
 
 ```bash
-webcmd --profile work session create
-# Copy the returned full ID:
-# session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45
+webcmd --profile work session create "Work Project"
+# id: work-project-k7
+webcmd --profile work --session work-project-k7 browser tabs
 
 webcmd --profile work \
-  --session session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45 \
+  --session work-project-k7 \
   browser run --stdin <<'JS'
 await page.goto('https://example.com');
 return { url: page.url(), title: await page.title() };
 JS
 
 webcmd --profile work \
-  --session session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45 \
+  --session work-project-k7 \
   browser snapshot --snapshot-mode read
 
-webcmd --profile work session close \
-  session_7d8f2c10-4a11-4f3e-9c22-1b6de0a91f45
+webcmd --profile work session close work-project-k7
 ```
 
 Local browser commands use Cloak. Hosted browser commands use Webcmd Cloud and Browser Use; `web fetch` still runs locally.
 
 ## Browser Programs
 
-Create an opaque session before raw browser work. Profiles hold cookie/auth
-state; sessions are browser workspaces within that profile. Adapter commands
-may omit `--session` and use their profile's adapter-default session; pass
-`--session <session-id>` only when intentionally routing an adapter into an
-explicit session. Raw browser commands must always pass it. The retired
-positional session form is invalid:
+Create a named Session before raw browser work. The returned readable ID is
+immutable and Profile-scoped: keep using the same Profile and ID for that
+Session's lifetime. Adapter commands without `--session` reuse their Profile's
+`adapter-default` Session. Raw browser commands must always pass an explicit
+readable selector at the root:
 
 ```bash
-webcmd session create -f json
-webcmd --session session_abc browser snapshot --snapshot-mode act
-webcmd --session session_abc browser snapshot --snapshot-mode read
-webcmd --session session_abc browser run --stdin --timeout 45
-webcmd --session session_abc browser run --stdin --no-snapshot-diff
-webcmd session list
-webcmd session close session_abc
+webcmd --profile work session create "Work Project" -f json
+# id: work-project-k7
+webcmd --profile work --session work-project-k7 browser tabs
+webcmd --profile work --session work-project-k7 browser snapshot --snapshot-mode act
+webcmd --profile work --session work-project-k7 browser snapshot --snapshot-mode read
+webcmd --profile work --session work-project-k7 browser run --stdin --timeout 45
+webcmd --profile work --session work-project-k7 browser run --stdin --no-snapshot-diff
+webcmd --profile work session list
+webcmd --profile work session close work-project-k7
 ```
 
 `session create`, `session list`, and `session close` accept the universal output

docs/concepts.mdx

@@ -43,7 +43,7 @@ The agent chooses the strategy; the human describes the outcome and constraints.
 
 ## Profiles, Sessions, And Tabs
 
-A Profile is the browser identity and storage bucket, such as `default` or `work`. A Session is an opaque browser workspace inside a Profile; raw browser work creates one with `webcmd session create` and selects it at the root with `--session <session-id>`. A tab is one page inside that Session.
+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.
 

docs/skills.mdx

@@ -32,4 +32,4 @@ Do not also add the skills with `webcmd skills add` in Codex.
 ## Other Agents or Plugin-Free Setup
 
 Run `webcmd skills add` to install or refresh the bundled Webcmd skills for your agent. The agent can then start with `webcmd-usage` and load the specialized skill that matches the outcome.
-For raw browser work, agents should create a Session with `webcmd session create -f json` and pass it as a root selector: `webcmd --session <session-id> browser ...`.
+For raw browser work, agents should run `webcmd --profile work session create "Work Project"`, keep the returned immutable, Profile-scoped ID, and pass it at the root: `webcmd --profile work --session work-project-k7 browser tabs`. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector.

docs/troubleshooting.mdx

@@ -45,8 +45,8 @@ Common Session codes:
 
 | Code | Meaning | Next step |
 | --- | --- | --- |
-| `SESSION_REQUIRED` | A raw browser command needs a root Session selector. | Run `webcmd session create -f json`, then retry as `webcmd --session <session-id> browser ...`. |
-| `INVALID_SESSION_SELECTOR` | The selector is not an opaque Webcmd Session ID. | Use an ID returned by `webcmd session create` or `webcmd session list`. |
+| `SESSION_REQUIRED` | A raw browser command needs a root Session selector. | Run `webcmd --profile work session create "Work Project"`, then retry as `webcmd --profile work --session work-project-k7 browser tabs`. |
+| `INVALID_SESSION_SELECTOR` | The selector is not a readable Webcmd Session ID. | Use the immutable, Profile-scoped ID returned by `webcmd session create <name>` or `webcmd session list`. |
 | `SESSION_SELECTOR_POSITION` | `--session` was placed after the command name. | Move it before the command: `webcmd --session <session-id> browser ...`. |
 | `SESSION_NOT_FOUND` | The selected Session is missing for the current Profile. | When the ID belongs to another Profile the hint names it — retry with `webcmd --profile <owner> session close <session-id>`. Otherwise run `webcmd session list -f json`; create a new Session if needed. |
 | `INVALID_SESSION_LIMIT` | `session list --limit` is outside 1-100. | Retry with a limit from 1 to 100. |