superacli 1.1.5 → 1.1.7

package/docs/features/skills.md

@@ -1,12 +1,16 @@
-# AI Skills Support
+# Skill Documents (SKILL.md)
 
-SUPERCLI natively integrates a teaching mechanism to empower local LLMs/agents with context about the application's CLI interface.
+SUPERCLI includes a SKILL.md teaching/catalog system for local LLMs and agents.
+
+Terminology:
+- **Capability**: executable command endpoint (commands, MCP tool bindings, OpenAPI-backed operations, workflows).
+- **Skill document**: instruction artifact returned by `supercli skills ...` commands.
 
 ## Key Features
 
-- **Bootstrapping Skills (`teach`)**: Emits a meta-skill document (in Markdown format compatible with Anthropic/OpenAI instructions) detailing the core architectural design of SUPERCLI and dynamically listing the namespaces and resources available.
-- **Micro-Skills Extraction (`get <cmd>`)**: Automatically pulls a specific SUPERCLI command's capabilities and formats it into a self-contained AI-actionable tool instruction (e.g., Markdown schema).
-- **Embedded DAG Planning**: Optionally injects execution plan information (`--show-dag`) into a skill's document to teach agents how to handle dry-runs for risky operations before execution.
+- **Bootstrapping Skill Docs (`teach`)**: Emits a meta-skill document (Markdown compatible with Anthropic/OpenAI instructions) describing SuperCLI and available namespaces/resources.
+- **Capability Doc Extraction (`get <cmd>`)**: Pulls one command capability and formats it as a self-contained agent instruction document.
+- **Embedded DAG Planning**: Optionally injects execution plan information (`--show-dag`) into the generated skill document to teach dry-run-first workflows.
 
 ## Usage
 

package/docs/{supported-harnesses.md → plugins-available.md}

@@ -1,10 +1,10 @@
 # Supported Harnesses
 
-A comprehensive guide to all currently supported harnesses in dcli, including bundled harnesses, built-in adapters, and popular community harnesses available via the plugin system.
+A comprehensive guide to all currently supported harnesses in supercli, including bundled harnesses, built-in adapters, and popular community harnesses available via the plugin system.
 
 ## Bundled Harnesses
 
-These harnesses are included with dcli and require only the underlying CLI tool to be installed.
+These harnesses are included with supercli and require only the underlying CLI tool to be installed.
 
 ### beads (Task/Issue Management)
 
@@ -258,6 +258,7 @@ These harnesses are in active development and will be available as plugins. Stat
 
 | Harness | CLI | Status | Purpose |
 |---------|-----|--------|---------|
+| **cocoindex-code** | cocoindex-code | Available via plugin | Semantic code search via local MCP with bound `cocoindex.code.search` capability |
 | **huggingface** | huggingface-cli | Planned | Hugging Face model management |
 | **langchain** | langchain CLI | Planned | LangChain utilities |
 | **ollama** | ollama | Planned | Local LLM management |
@@ -289,7 +290,7 @@ For detailed instructions, see [plugin-harness-guide.md](plugin-harness-guide.md
 
 ## Request a Harness
 
-Missing a CLI you'd like to use with dcli? [Open an issue](https://github.com/anomalyco/dcli/issues) with:
+Missing a CLI you'd like to use with supercli? [Open an issue](https://github.com/anomalyco/supercli/issues) with:
 - CLI name and link
 - Use cases in your workflow
 - Relevant commands/operations

package/docs/{plugin-harness-guide.md → plugins-how-to.md}

@@ -8,7 +8,7 @@ A **plugin harness** bridges dcli to an external CLI tool. It allows dcli to:
 - Discover and route commands to the external CLI
 - Expose the CLI's functionality through dcli's unified interface
 - Provide consistent output formatting and error handling
-- Integrate AI-driven skill discovery across all harnesses
+- Integrate AI-driven capability discovery across all harnesses
 
 ## Anatomy of a Plugin Harness
 

package/docs/plugins.md

@@ -1,6 +1,6 @@
 # Plugins
 
-DCLI supports plugin discovery through the registry file at `plugins/plugins.json`.
+supercli supports plugin discovery through `plugins/plugins.json` plus auto-discovery of bundled manifests at `plugins/*/plugin.json`.
 
 Plugin owners can submit PRs that add or update metadata in this registry:
 
@@ -8,30 +8,31 @@ Plugin owners can submit PRs that add or update metadata in this registry:
 - `description`
 - `tags`
 - `source` (`bundled` path or remote `git` repo + manifest path)
+- `install_guidance` (optional plugin-specific dependency/setup hints)
 
 ## Plugin Commands
 
 ```bash
-dcli plugins list
-dcli plugins explore
-dcli plugins explore --name commiat
-dcli plugins explore --tags git,ai
-dcli plugins explore --has-learn true --installed false --source bundled --limit 10 --json
-dcli plugins learn <plugin-name>
-dcli plugins install <plugin-name>
-dcli plugins install --git https://github.com/org/repo.git --manifest-path plugins/supercli/plugin.json --ref main
-dcli plugins show <plugin-name>
-dcli plugins doctor
-dcli plugins doctor <plugin-name>
-dcli plugins remove <plugin-name>
+supercli plugins list
+supercli plugins explore
+supercli plugins explore --name commiat
+supercli plugins explore --tags git,ai
+supercli plugins explore --has-learn true --installed false --source bundled --limit 10 --json
+supercli plugins learn <plugin-name>
+supercli plugins install <plugin-name>
+supercli plugins install --git https://github.com/org/repo.git --manifest-path plugins/supercli/plugin.json --ref main
+supercli plugins show <plugin-name>
+supercli plugins doctor
+supercli plugins doctor <plugin-name>
+supercli plugins remove <plugin-name>
 ```
 
 Install conflict policy:
 
 ```bash
-dcli plugins install <plugin-name> --on-conflict fail
-dcli plugins install <plugin-name> --on-conflict skip
-dcli plugins install <plugin-name> --on-conflict replace
+supercli plugins install <plugin-name> --on-conflict fail
+supercli plugins install <plugin-name> --on-conflict skip
+supercli plugins install <plugin-name> --on-conflict replace
 ```
 
 Default is `fail`.
@@ -39,13 +40,18 @@ Default is `fail`.
 ## Notes
 
 - `plugins list` shows installed plugins.
-- `plugins explore` shows discoverable plugins from `plugins/plugins.json`.
+- `plugins explore` shows discoverable plugins from merged sources: curated registry entries plus bundled manifest auto-discovery.
 - `plugins explore` supports filters: `--name`, `--tags`, `--has-learn true|false`, `--installed true|false`, `--source bundled|git`, `--limit <n>`.
 - `plugins explore --json` includes `has_learn`, `installed`, and `filters` metadata so agents can prioritize plugins with learning content.
 - `plugins learn <name>` prints plugin-provided learning content before or after install.
 - `plugins install` supports local path, registry name, and direct remote git manifest installs.
 - Plugin manifests can define `learn` content via `learn.text` or `learn.file` (path inside plugin folder).
 - Plugin manifests can define `post_install` hooks (`script`, optional `runtime`, optional `timeout_ms`) that execute from the plugin folder after install.
-- `agency-agents` is a bundled zero-command plugin. Installing it adds a remote skills provider named `agency-agents` and refreshes the local skills catalog.
-- `visual-explainer` is a bundled zero-command plugin. Installing it adds a remote skills provider named `visual-explainer` sourced from normalized markdown skills in `javimosch/visual-explainer` and refreshes the local skills catalog.
-- `browser-use` is a bundled hybrid plugin. Installing it auto-registers a `browser-use` MCP server, discovers and binds Browser Use MCP tools into direct `browseruse.tool.*` commands, and installs local Browser Use skills from the plugin folder.
+- Plugin manifests can define `install_guidance` so plugin-specific setup guidance does not require core edits in `cli/plugin-install-guidance.js`.
+- `agency-agents` is a bundled zero-command plugin. Installing it adds a remote skill-document provider named `agency-agents` and refreshes the local skill-doc catalog.
+- `visual-explainer` is a bundled zero-command plugin. Installing it adds a remote skill-document provider named `visual-explainer` sourced from normalized markdown skill documents in `javimosch/visual-explainer` and refreshes the local skill-doc catalog.
+- `browser-use` is a bundled hybrid plugin. Installing it auto-registers a `browser-use` MCP server, discovers and binds Browser Use MCP tools into direct `browseruse.tool.*` commands, and installs local Browser Use skill documents from the plugin folder.
+- `cocoindex-code` is a bundled hybrid plugin. Installing it auto-registers a local `cocoindex-code` MCP server, exposes fast direct search via `cocoindex.code.search`, keeps `cocoindex.mcp.search` for MCP-native flows, and installs local quickstart skill documents.
+- `squirrelscan` is a bundled Docker-backed plugin with broad CLI coverage (`audit`, `crawl`, `analyze`, `report`, `auth`, `config`, `init`, `feedback`, `self`, `skills`) plus passthrough. It lazily builds a pinned local image on first use, then reuses it for fast repeat scans (example: `supercli squirrel audit https://example.com -C quick`).
+- `openhands` is a bundled plugin for OpenHands headless workflows (`task run`, `task file`, `task json`) plus passthrough for full CLI coverage.
+- `uipathcli` is a bundled plugin for UiPath automation lifecycle wrappers (`project pack`, `project analyze`, `project deploy`) plus passthrough.

package/docs/server-plugins-usage-guide.md

@@ -0,0 +1,182 @@
+# Server Plugins Usage Guide
+
+This guide covers manual testing of server plugins in SUPERCLI, including JSON and ZIP plugin flows.
+
+## Prerequisites
+
+- A running server instance (example: `PORT=3001 sc --server`)
+- CLI shell with:
+
+```bash
+export SUPERCLI_SERVER=http://localhost:3001
+```
+
+## 1) Verify Server Plugin Endpoints
+
+```bash
+curl -s "$SUPERCLI_SERVER/api/plugins?format=json" | jq
+curl -s "$SUPERCLI_SERVER/api/plugins/settings" | jq
+```
+
+Expected: JSON response with `plugins` and `settings`.
+
+## 2) Create a JSON Server Plugin
+
+Create a simple shell command plugin:
+
+```bash
+curl -s -X POST "$SUPERCLI_SERVER/api/plugins" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source_type": "json",
+    "name": "server-demo-json",
+    "version": "0.1.0",
+    "description": "Server JSON plugin demo",
+    "enabled": true,
+    "hooks_policy": "inherit",
+    "manifest": {
+      "name": "server-demo-json",
+      "version": "0.1.0",
+      "commands": [
+        {
+          "namespace": "demo",
+          "resource": "fs",
+          "action": "list",
+          "description": "List files via server plugin",
+          "adapter": "shell",
+          "adapterConfig": {
+            "unsafe": true,
+            "script": "ls -lrt",
+            "parseJson": false,
+            "timeout_ms": 5000
+          },
+          "args": []
+        }
+      ]
+    }
+  }' | jq
+```
+
+## 3) Sync and Execute JSON Plugin Command
+
+```bash
+sc sync --json | jq
+sc commands --namespace demo --json | jq
+sc demo fs list --json | jq
+```
+
+Expected:
+
+- `sync` includes `server_plugins` diagnostics.
+- `demo fs list` appears in commands.
+- execution returns shell output in `data.raw`.
+
+## 4) Test Enable/Disable Server Plugin
+
+Disable:
+
+```bash
+curl -s -X PATCH "$SUPERCLI_SERVER/api/plugins/server-demo-json" \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled": false}' | jq
+```
+
+Re-sync and verify command removal:
+
+```bash
+sc sync --json | jq
+sc commands --namespace demo --json | jq
+```
+
+Re-enable:
+
+```bash
+curl -s -X PATCH "$SUPERCLI_SERVER/api/plugins/server-demo-json" \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled": true}' | jq
+sc sync --json | jq
+```
+
+## 5) Upload a ZIP Server Plugin (multipart)
+
+Create a minimal ZIP payload:
+
+```bash
+mkdir -p /tmp/server-demo-zip
+cat > /tmp/server-demo-zip/plugin.json <<'EOF'
+{
+  "name": "server-demo-zip",
+  "version": "0.1.0",
+  "commands": [
+    {
+      "namespace": "zipdemo",
+      "resource": "tool",
+      "action": "ping",
+      "description": "ZIP plugin ping",
+      "adapter": "shell",
+      "adapterConfig": {
+        "unsafe": true,
+        "script": "printf ping",
+        "parseJson": false,
+        "timeout_ms": 3000
+      },
+      "args": []
+    }
+  ]
+}
+EOF
+(cd /tmp/server-demo-zip && zip -r /tmp/server-demo-zip.zip .)
+```
+
+Upload as multipart form:
+
+```bash
+curl -s -X POST "$SUPERCLI_SERVER/api/plugins/upload" \
+  -F "name=server-demo-zip" \
+  -F "version=0.1.0" \
+  -F "description=ZIP plugin demo" \
+  -F "enabled=true" \
+  -F "hooks_policy=inherit" \
+  -F "manifest={\"name\":\"server-demo-zip\",\"version\":\"0.1.0\",\"commands\":[]}" \
+  -F "archive=@/tmp/server-demo-zip.zip;type=application/zip" | jq
+```
+
+Then sync and verify:
+
+```bash
+sc sync --json | jq
+sc commands --namespace zipdemo --json | jq
+```
+
+## 6) Validate Local-Over-Server Precedence
+
+Install/create a local plugin with the same plugin name as a server plugin.
+After `sc sync`, verify server plugin is shadowed:
+
+```bash
+sc sync --json | jq '.server_plugins.shadowed_by_local'
+```
+
+Expected: plugin name appears in `shadowed_by_local`, and local plugin commands remain active.
+
+## 7) Update Server Plugin Settings
+
+```bash
+curl -s -X PUT "$SUPERCLI_SERVER/api/plugins/settings" \
+  -H 'Content-Type: application/json' \
+  -d '{"max_zip_mb": 10, "default_hooks_policy": "deny"}' | jq
+```
+
+## 8) Cleanup
+
+```bash
+curl -s -X DELETE "$SUPERCLI_SERVER/api/plugins/server-demo-json" | jq
+curl -s -X DELETE "$SUPERCLI_SERVER/api/plugins/server-demo-zip" | jq
+sc sync --json | jq
+```
+
+## Troubleshooting
+
+- If ZIP upload fails with size errors, check `max_zip_mb` in `/api/plugins/settings`.
+- If ZIP sync fails on client extraction, ensure `unzip` is installed.
+- If commands do not appear after server updates, run `sc sync` again and inspect `server_plugins` diagnostics.

package/docs/skills-catalog.md

@@ -1,7 +1,9 @@
-# Skills Catalog
+# Skill Documents Catalog
 
 SuperCLI can discover SKILL.md files from multiple local providers and expose them with stable `provider:id` identifiers.
 
+This catalog is for **skill documents** (agent instructions), not executable command capabilities. Executable capabilities are still discovered/executed via normal command routing (`supercli <namespace> <resource> <action>` and `supercli inspect ...`).
+
 ## Provider Commands
 
 ```bash
@@ -19,7 +21,7 @@ supercli skills sync --json
 
 This scans enabled provider roots for `SKILL.md` files and rebuilds the local index.
 
-## Query Catalog Skills
+## Query Catalog Skill Documents
 
 ```bash
 supercli skills list --catalog --json
@@ -27,13 +29,13 @@ supercli skills search --query "planning" --json
 supercli skills get opencode:plan-changes
 ```
 
-## Built-in MCP Usage Skill (Agent-Friendly)
+## Built-in MCP Usage Skill Document (Agent-Friendly)
 
 ```bash
 supercli skills get mcp.servers.usage
 ```
 
-This built-in skill teaches non-human agents how to register, verify, and use MCP servers
+This built-in skill document teaches non-human agents how to register, verify, and use MCP servers
 through SuperCLI, including a browser-use style `mcp-remote` SSE bridge pattern with
 runtime API-key passing.
 
@@ -41,7 +43,7 @@ runtime API-key passing.
 
 - IDs are always provider-qualified (`provider:id`) for future-proof disambiguation.
 - Current provider types include `local_fs`, `repo_fs`, and `remote_static`.
-- Existing command-skill flow remains available (`skills list`, `skills get <ns.res.act>`, `skills teach`).
+- Existing capability-doc flow remains available (`skills list`, `skills get <ns.res.act>`, `skills teach`).
 
 ## Remote Provider Example: agency-agents
 
@@ -51,9 +53,9 @@ supercli skills list --catalog --provider agency-agents --json
 supercli skills get agency-agents:engineering.engineering-frontend-developer
 ```
 
-`agency-agents` maps skills one-to-one to upstream `.md` files in
+`agency-agents` maps skill documents one-to-one to upstream `.md` files in
 `msitarzewski/agency-agents`. If upstream paths change or files are removed,
-individual skills may stop resolving until reinstalled/refreshed.
+individual skill documents may stop resolving until reinstalled/refreshed.
 
 ## Remote Provider Example: visual-explainer
 
@@ -63,7 +65,7 @@ supercli skills list --catalog --provider visual-explainer --json
 supercli skills get visual-explainer:visual-explainer.skill
 ```
 
-`visual-explainer` maps skills to normalized markdown files under
+`visual-explainer` maps skill documents to normalized markdown files under
 `plugins/visual-explainer-normalized` in `javimosch/visual-explainer`.
 
 ## Remote Provider Example: nullclaw
@@ -119,7 +121,7 @@ supercli skills get clix:root.readme
 so agents can learn safe cookie-auth X workflows, JSON usage, and agent-mode guidance.
 It also exposes curated read-only wrappers for the local `clix` binary.
 
-## Local Repo Skill Example: cline-non-interactive
+## Local Repo Skill Document Example: cline-non-interactive
 
 ```bash
 supercli skills sync --json
@@ -127,5 +129,5 @@ supercli skills list --catalog --provider repo --json
 supercli skills get repo:cline-non-interactive
 ```
 
-`cline-non-interactive` is a repository-local skill that teaches agents to prefer the wrapped
+`cline-non-interactive` is a repository-local skill document that teaches agents to prefer the wrapped
 `supercli cline task run` and `supercli cline task plan` commands for unattended Cline usage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superacli",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "license": "MIT",
   "main": "server/app.js",

package/plugins/agent-browser/README.md

@@ -0,0 +1,69 @@
+# agent-browser Plugin Harness
+
+This plugin integrates `agent-browser` into supercli with a few human-friendly wrappers and full passthrough for the entire upstream CLI.
+
+## What You Get
+
+- quick wrappers for common setup and workflow steps
+- full passthrough for every upstream `agent-browser` command
+- learn content via `supercli plugins learn agent-browser`
+
+## Prerequisites
+
+Install the upstream CLI globally (recommended for speed):
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+## Install Plugin
+
+```bash
+supercli plugins learn agent-browser
+supercli plugins install agent-browser --json
+```
+
+## Wrapper Commands
+
+```bash
+supercli agent-browser cli version
+supercli agent-browser browser install
+supercli agent-browser browser open --url https://example.com
+supercli agent-browser browser snapshot
+supercli agent-browser browser close
+```
+
+## Full Passthrough Examples
+
+```bash
+supercli agent-browser open example.com
+supercli agent-browser snapshot -i --json
+supercli agent-browser click @e1
+supercli agent-browser fill @e2 "test@example.com"
+supercli agent-browser screenshot --annotate
+supercli agent-browser close
+```
+
+## Recommended Human Workflow
+
+1. Open page: `supercli agent-browser open <url>` or `supercli agent-browser browser open --url <url>`
+2. Capture refs: `supercli agent-browser snapshot -i`
+3. Interact with refs: `click @eN`, `fill @eN "..."`
+4. Re-snapshot after page changes
+5. Close when done: `supercli agent-browser close`
+
+## Important Caveats
+
+- `browser open` wrapper requires `--url` (named argument). Check schema with `supercli inspect agent-browser browser open --json`.
+- Wrappers are intentionally minimal. Use passthrough (`supercli agent-browser <upstream args...>`) for full upstream options.
+- Ref ids (`@e1`, `@e2`, etc.) are snapshot-scoped and can change after navigation or refresh. Run a fresh `snapshot -i` before using refs.
+- `browser snapshot` returns a full accessibility tree; `snapshot -i` returns a compact refs map and is better for click/fill automation loops.
+- Real pages may expose noisy or translated link labels (social embeds, widgets). Prefer ref-based actions over brittle text matching.
+- After `browser close`, `browser snapshot` may return a minimal empty document. Re-open a URL before continuing automation.
+
+## Notes
+
+- The plugin uses long timeouts (`180000ms`) because browser tasks can take longer than standard CLI commands.
+- Use `--json` on passthrough commands when you need machine-readable output.
+- If you see missing dependency errors, ensure `agent-browser` is on your `PATH` and rerun `agent-browser install`.

package/plugins/agent-browser/plugin.json

@@ -0,0 +1,111 @@
+{
+  "name": "agent-browser",
+  "version": "0.1.0",
+  "description": "agent-browser CLI plugin with quick wrappers and passthrough",
+  "source": "https://github.com/vercel-labs/agent-browser",
+  "checks": [
+    { "type": "binary", "name": "agent-browser" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "commands": [
+    {
+      "namespace": "agent-browser",
+      "resource": "cli",
+      "action": "version",
+      "description": "Show installed agent-browser version",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["--version"],
+        "parseJson": false,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "install",
+      "description": "Install browser runtime dependencies for agent-browser",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["install"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "open",
+      "description": "Open a URL in agent-browser",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["open"],
+        "positionalArgs": ["url"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": [
+        {
+          "name": "url",
+          "type": "string",
+          "required": true,
+          "description": "URL to open"
+        }
+      ]
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "snapshot",
+      "description": "Capture accessibility snapshot for ref-based automation",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["snapshot"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "browser",
+      "action": "close",
+      "description": "Close active agent-browser session",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "baseArgs": ["close"],
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    },
+    {
+      "namespace": "agent-browser",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough command to execute any agent-browser CLI command",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "agent-browser",
+        "passthrough": true,
+        "parseJson": true,
+        "timeout_ms": 180000,
+        "missingDependencyHelp": "Install with: npm install -g agent-browser && agent-browser install"
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/agent-browser/skills/quickstart/SKILL.md

@@ -0,0 +1,66 @@
+---
+skill_name: agent-browser.quickstart
+description: Agent workflow to install and run agent-browser through supercli with snapshot-ref automation.
+tags: agent-browser,browser,automation,playwright,agents
+---
+
+# agent-browser Quickstart
+
+Use this when you need deterministic browser automation for agent tasks.
+
+## 1) Install plugin and dependency
+
+```bash
+supercli plugins learn agent-browser
+supercli plugins install agent-browser --json
+supercli agent-browser browser install
+```
+
+If the binary is missing, install globally first:
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+## 2) Validate setup
+
+```bash
+supercli agent-browser cli version
+```
+
+## 3) Recommended agent workflow
+
+```bash
+supercli agent-browser browser open --url https://example.com
+supercli agent-browser browser snapshot
+supercli agent-browser click @e1
+supercli agent-browser fill @e2 "test@example.com"
+supercli agent-browser wait --load networkidle
+supercli agent-browser screenshot --annotate
+supercli agent-browser browser close
+```
+
+## 4) Use passthrough for full command coverage
+
+```bash
+supercli agent-browser find role button click --name "Submit"
+supercli agent-browser get url
+supercli agent-browser diff snapshot
+```
+
+## 5) Structured output for tool chains
+
+```bash
+supercli agent-browser snapshot --json
+supercli agent-browser get text @e1 --json
+```
+
+## 6) Important caveats
+
+- `browser open` wrapper requires `--url` (named arg). Use `supercli inspect agent-browser browser open --json` to confirm the active schema.
+- Wrapper commands are intentionally minimal. For advanced flags and full upstream coverage, use passthrough commands like `supercli agent-browser <upstream args...>`.
+- Ref ids (`@e1`, `@e2`, etc.) are snapshot-scoped and can change after navigation or refresh. Run a new `snapshot -i` before acting on refs.
+- `browser snapshot` returns the full accessibility tree text; `snapshot -i` returns a compact refs map that is easier for reliable click/fill automation.
+- Link labels may be verbose, translated, or indirect on real sites (for example social widgets). Prefer refs over brittle text matching.
+- After `browser close`, a snapshot may still return a minimal empty document. Always `open` a target URL again before continuing task steps.