@agentrhq/webcmd 0.2.4 → 0.3.0

package/skills/smart-search/SKILL.md

@@ -11,9 +11,19 @@ Route a query to the best webcmd search source based on the topic and context. T
 
 Before every use, do both of these steps:
 
-- Run `webcmd list -f yaml`
+- Run `webcmd list -f json`
 - Use the live registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
 
+If the user explicitly names a site/source and it is missing from `webcmd list` or when none of the sites cover the query, check installable plugins before marking it unavailable:
+
+```bash
+webcmd plugin search <site-or-source-or-capability> -f json
+```
+
+Derive a short plugin query from the missing site or capability. Preserve the user's term when practical: `find flights` becomes `flight`.
+
+If plugin search finds a match, tell the user it is available as a plugin and offer `webcmd plugin install <source>`. If plugin search fails because catalog sources cannot be fetched, report that catalog/search error separately from no plugin match.
+
 After choosing a site, do both of these steps:
 
 - Run `webcmd <site> -h` to see the site's subcommands
@@ -42,7 +52,7 @@ First create a site-call ledger. After each real search command, update it immed
 
 Counting rules:
 
-- `webcmd list -f yaml`, `webcmd <site> -h`, and `webcmd <site> <command> -h` are preflight/help commands and do not count as searches.
+- `webcmd list -f json`, `webcmd plugin search <query> -f json`, `webcmd <site> -h`, and `webcmd <site> <command> -h` are preflight/help commands and do not count as searches.
 - One real `webcmd <site> ...` search/query execution counts as 1 call for that site.
 - A failed call caused by an error, timeout, CAPTCHA, anti-bot check, or broken login state still counts as 1 call for that site. Do not retry indefinitely.
 
@@ -134,9 +144,10 @@ Keep a typical query to 1 AI source plus 1-2 specialized sources to avoid result
 When a site is unavailable:
 
 - Do not stop the whole search because one source failed
+- For a missing site or capability, run `webcmd plugin search <query> -f json` before recording unavailable
 - Record: `Skipped: <site> unavailable`
 - Fall back to another site of the same type, or to one AI source
-- Always trust the actual output of `webcmd list -f yaml` and `webcmd <site> -h`
+- Always trust the actual output of `webcmd list -f json`, `webcmd plugin search -f json`, and `webcmd <site> -h`
 
 Do not assume any site is always available. Even for public sites, trust live help and execution results in the current environment.
 

package/skills/webcmd-adapter-author/SKILL.md

@@ -28,7 +28,7 @@ Continue only when all three answers are yes.
 
 ## Top-Level Decision Tree
 
-**Choose the strategy before writing the adapter.** Every time you reach Step 3 or Step 4, and before writing code, produce a strategy note. Without that note, do not start `clis/<site>/<name>.js`.
+**Choose the strategy before writing the adapter.** Every time you reach Step 3 or Step 4, and before writing code, produce a strategy note. Without that note, do not start an adapter file.
 
 The core question is not whether an API is more elegant than DOM work. The core question is whether the data source has an external contract. Public or official interfaces are usually the most stable. UI/DOM semantics often have a user-visible contract too. Undocumented in-site XHR, GraphQL, or signature endpoints drift the most. Do not move a stable UI/DOM implementation to an uncontracted internal endpoint just to be "API-first."
 
@@ -253,7 +253,7 @@ Check these off step by step:
 - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults.
 - Throw the correct typed error for known failures according to [`references/typed-errors.md`](./references/typed-errors.md). **Do not** silently `return []`, **do not** silently `return [{sentinel}]`, and **do not** silently clamp external parameters with `Math.max/min`.
 - **Persistent sessions keep stale DOM between commands.** `siteSession: 'persistent'` shares one tab per site; leftover modals/drawers from the previous command leak into the next one. State-sensitive write commands (checkout flows) should add `freshPage: true` (new tab, same lease — cookies/login/location survive). Verify session-scoped context (login, selected city/date) *before* side effects, and embed such context in URLs/IDs your command emits for sibling commands. See `references/adapter-template.md` and "Persistent Sessions and State Hygiene" in `docs/authoring.mdx`.
-- For private adapters, write `~/.webcmd/clis/<site>/<name>.js` to avoid a build. Copy to `clis/<site>/<name>.js` only when preparing a PR.
+- For private iteration, write `~/.webcmd/clis/<site>/<name>.js` to avoid a build. When the user says to promote a CLI, create a main-repo plugin with `webcmd plugin create <site> --dir plugins/<site>`, copy the real command files into it, delete scaffold sample commands, register it in root `webcmd-plugin.json`, remove the local `~/.webcmd/clis/<site>` shadow, install the plugin, then run `webcmd validate <site>` and smoke commands. See `references/adapter-template.md` for details.
 - Write site memory every round: no memory -> use skill -> produce memory -> next time becomes a five-minute task.
 - **After a site's first command passes verify, stop and ask the user for their use cases before recommending next set of commands.** See Runbook Step 13.
 - **Raw dumps, packet captures, and HTML samples from debugging may only be written to `~/.webcmd/sites/<site>/fixtures/` or `/tmp/`. Never leave `.dbg-*.html`, `raw-*.json`, `sample.*`, or similar temporary files in the repo root, `clis/<site>/`, or the current working directory.**

package/skills/webcmd-adapter-author/references/adapter-template.md

@@ -16,10 +16,32 @@ Write the working file at:
 ~/.webcmd/clis/<site>/<name>.js
 ```
 
-Copy it to the repo only when preparing a PR:
+Promote a community CLI to the main repo as a plugin:
 
-```text
-clis/<site>/<name>.js
+```bash
+webcmd plugin create <site> --dir plugins/<site> --description "<site> commands for Webcmd"
+cp ~/.webcmd/clis/<site>/*.js plugins/<site>/
+rm plugins/<site>/hello.ts plugins/<site>/greet.ts 2>/dev/null || true
+```
+
+Then add `<site>` to the root `webcmd-plugin.json` `plugins` map:
+
+```json
+"<site>": {
+  "path": "plugins/<site>",
+  "version": "0.1.0",
+  "description": "<site> commands for Webcmd",
+  "webcmd": ">=0.2.0"
+}
+```
+
+Before handing off, remove the private shadow and prove the plugin path works:
+
+```bash
+rm -rf ~/.webcmd/clis/<site>
+webcmd plugin install file://$PWD/plugins/<site>
+webcmd validate <site>
+webcmd <site> <command> --help
 ```
 
 ## Minimal Registry Shape

package/skills/webcmd-autofix/SKILL.md

@@ -18,7 +18,7 @@ Hard stops before any code change:
 
 Scope constraint:
 
-- Modify only the file at `adapterSourcePath` in the trace `summary.md` front matter. That path is authoritative and may be `clis/<site>/...` in the repo or `~/.webcmd/clis/<site>/...` for user-local installs.
+- Modify only the file at `adapterSourcePath` in the trace `summary.md` front matter. That path is authoritative and may be `clis/<site>/...` in the repo or `plugins/<site>/...` in a plugin repo or `~/.webcmd/clis/<site>/...` for user-local installs.
 - Never modify `src/`, `extension/`, `tests/`, `package.json`, or `tsconfig.json` during autofix.
 
 Retry budget: maximum **3 repair rounds** per failure. A round is diagnose -> patch -> retry. If 3 rounds do not resolve it, stop and report what was tried.

package/skills/webcmd-usage/SKILL.md

@@ -10,7 +10,7 @@ Webcmd turns websites, Electron desktop apps, and external CLIs into a uniform `
 
 ## The Three Pillars
 
-- **Adapter commands:** `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`; user adapters live in `~/.webcmd/clis/`. Each command has a strategy such as `PUBLIC`, `COOKIE`, `INTERCEPT`, `UI`, or `LOCAL`.
+- **Adapter commands:** `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`; community adapters promoted to the main repo live as plugins under `plugins/`; private iteration adapters live in `~/.webcmd/clis/`. Each command has a strategy such as `PUBLIC`, `COOKIE`, `INTERCEPT`, `UI`, or `LOCAL`.
 - **Browser driving:** `webcmd browser *` subcommands (`open`, `state`, `click`, `type`, `select`, `find`, `extract`, `network`) for ad-hoc interaction when no adapter covers the task. See `webcmd-browser`.
 - **External CLI passthrough:** `webcmd gh`, `webcmd docker`, `webcmd vercel`, and similar wrappers. Manage them with `webcmd external install <name>` or `webcmd external register <name>`.
 
@@ -44,21 +44,25 @@ npx tsx src/main.ts <command>
 
 Electron desktop app adapters route through CDP against the running app. Make sure the app is open before invoking those commands.
 
-## Discover Installed Commands
+## Discover Commands
 
 Run commands instead of reading static docs:
 
 ```bash
-webcmd list
+webcmd
 webcmd list -f json
-webcmd list | grep -i github
 webcmd <site> --help
 webcmd <site> <command> --help
 ```
 
-Do not hard-code adapter lists. `webcmd list -f json` is the source of truth and emits one entry per command with fields such as `{site, name, aliases, description, strategy, browser, args, columns}`.
+Run `webcmd` with no arguments to see all available functions and installed site adapters. Do not hard-code adapter lists: `webcmd list -f json` is the source of truth for installed commands and emits one entry per command with fields such as `{site, name, aliases, description, strategy, browser, args, columns}`.
 
-Before falling back to raw `webcmd browser` on high-change authenticated sites, check whether a site adapter already exposes the workflow.
+Use this fallback order:
+
+1. Run `webcmd list -f json` once.
+2. Check that result against the whole requested workflow, not only a named site. If one installed command covers it, use that command and stop discovery.
+3. If none covers it, derive a short plugin query from the missing site or capability and run `webcmd plugin search <query> -f json`. Preserve the user's term when practical: `find flights` becomes `flight`.
+4. If plugin search returns a match, offer `webcmd plugin install <installSource>`. If it returns no match and no error, raw `webcmd browser` is allowed. If it errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
 
 ## Universal Flags
 
@@ -102,10 +106,13 @@ The error envelope includes a `trace` block pointing at `summary.md`. Patch only
 
 ## Writing An Adapter
 
-Two storage paths:
+Storage paths:
 
 - Private: `~/.webcmd/clis/<site>/<command>.js`
-- Public / PR: `clis/<site>/<command>.js`
+- Public (official bundle): `clis/<site>/<command>.js`
+- Public (community PRs): `plugins/<site>/` plus root `webcmd-plugin.json` registration
+
+The main Webcmd repo is itself a plugin monorepo: promoted community CLIs belong under `plugins/<site>/` and must be registered in the root `webcmd-plugin.json`.
 
 Scaffolding and checks:
 
@@ -126,9 +133,15 @@ webcmd plugin list [-f json]
 webcmd plugin update [name] | --all
 webcmd plugin uninstall <name>
 webcmd plugin create <name>
+webcmd plugin search [query] -f json
+webcmd plugin catalog list -f json
+webcmd plugin catalog add <source>
+webcmd plugin catalog remove <id>
 ```
 
-Plugins are third-party extensions pulled from git and separate from the main adapter registry.
+Plugins are installable extensions pulled from git or local paths. Use `plugin search` for marketplace discovery and `plugin list` for already-installed plugins. Main-repo community CLIs are exposed through the root plugin catalog manifest, not bundled into npm's `clis/` set.
+
+> **Note:** The repository's `plugins/` directory is not shipped in the npm package. Find the required plugin with `webcmd plugin search`, then install its `installSource` with `webcmd plugin install <installSource>`.
 
 ## External CLI Passthrough
 

package/clis/antigravity/SKILL.md

@@ -1,38 +0,0 @@
----
-description: How to automate Antigravity using Webcmd
----
-
-# Antigravity Automation Skill
-
-This skill allows AI agents to control the [Antigravity](https://github.com/chengazhen/Antigravity) desktop app (and any Electron app with CDP enabled) programmatically via Webcmd.
-
-## Requirements
-webcmd automatically detects, launches (with `--remote-debugging-port=9234`), and connects to Antigravity.
-If Antigravity is already running without CDP, webcmd will prompt to restart it.
-
-If the endpoint exposes multiple inspectable targets, set:
-\`\`\`bash
-export WEBCMD_CDP_TARGET="antigravity"
-\`\`\`
-
-## High-Level Capabilities
-1. **Send Messages (`webcmd antigravity send <message>`)**: Type and send a message directly into the chat UI.
-2. **Read History (`webcmd antigravity read`)**: Scrape the raw chat transcript from the main UI container.
-3. **Extract Code (`webcmd antigravity extract-code`)**: Automatically isolate and extract source code text blocks from the AI's recent answers.
-4. **Switch Models (`webcmd antigravity model <name>`)**: Instantly toggle the active LLM (e.g., \`gemini\`, \`claude\`).
-5. **Clear Context (`webcmd antigravity new`)**: Start a fresh conversation.
-
-## Examples for Automated Workflows
-
-### Generating and Saving Code
-\`\`\`bash
-webcmd antigravity send "Write a python script to fetch HN top stories"
-# wait ~10-15 seconds for output to render
-webcmd antigravity extract-code > hn_fetcher.py
-\`\`\`
-
-### Reading Real-time Logs
-Agents can run long-running streaming watch instances:
-\`\`\`bash
-webcmd antigravity watch
-\`\`\`