@zenalexa/unicli 0.215.0 → 0.216.0

package/README.md

@@ -1,334 +1,310 @@
-<!-- AGENT: npm install -g @zenalexa/unicli && unicli search "your intent" — 1283 commands across 220 sites. Markdown envelope by default; use -f json for JSON. Self-repairing YAML adapters. Bilingual EN/ZH search. See AGENTS.md for live counts. -->
-
-<div align="center">
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
-  <img alt="Uni-CLI" src="assets/logo-light.svg" width="420">
-</picture>
-
-<br><br>
-
-**CLI is all agents need.**
-
-The execution layer for agent skills. Deterministic, editable, cross-vendor.
-
-<br>
-
-<a href="https://www.npmjs.com/package/@zenalexa/unicli"><img src="https://img.shields.io/npm/v/@zenalexa/unicli?style=flat-square&color=cb3837" alt="npm"></a>
-<a href="https://github.com/olo-dot-io/Uni-CLI/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/olo-dot-io/Uni-CLI/ci.yml?style=flat-square&label=CI" alt="CI"></a>
-<a href="./LICENSE"><img src="https://img.shields.io/github/license/olo-dot-io/Uni-CLI?style=flat-square" alt="license"></a>
-<img src="https://img.shields.io/badge/tests-<!-- STATS:test_count -->7145<!-- /STATS -->-44cc11?style=flat-square" alt="tests">
-<img src="https://img.shields.io/badge/agent--reach-ally-6a5acd?style=flat-square" alt="agent-reach ally">
-
-<br><br>
-
-```
-npm install -g @zenalexa/unicli
-```
-
-<br>
-
-<img src="docs/demo/demo.svg" alt="Uni-CLI in 30 seconds" width="720">
-
-</div>
-
----
+<p align="center">
+  <img src="assets/mascot-otter.png" alt="Uni-CLI otter mascot" width="180">
+</p>
 
-## What
+<h1 align="center">Uni-CLI</h1>
 
-Uni-CLI is a universal interface that compiles agent intent into deterministic CLI programs. One binary reaches <!-- STATS:site_count -->220<!-- /STATS --> sites, 30+ desktop apps, 35 CLI bridges, and the local OS — <!-- STATS:command_count -->1283<!-- /STATS --> commands in total. Every adapter is a 20-line YAML pipeline, so agents can read, edit, and re-run them without a compiler.
+<p align="center">
+  <strong>One CLI surface for agents to operate websites, desktop apps, local tools, and other CLIs.</strong>
+</p>
 
-Coverage is cross-cutting: web APIs and browser automation, desktop subprocesses (ffmpeg, Blender, LibreOffice), macOS system calls (screenshot, clipboard, Calendar), macOS AX, and a pluggable CUA contract with mock/provider stubs — all behind the same `unicli <site> <command>` surface. Output is a v2 AgentEnvelope in Markdown by default; use `-f json` for JSON, `-f yaml` for YAML, or legacy `csv` / `compact` when needed. Errors include the adapter path, the failing step, and a suggestion — enough directional feedback for an agent to fix the adapter and retry.
+<p align="center">
+  <a href="https://olo-dot-io.github.io/Uni-CLI/">Docs</a>
+  ·
+  <a href="https://olo-dot-io.github.io/Uni-CLI/reference/sites">Sites catalog</a>
+  ·
+  <a href="https://olo-dot-io.github.io/Uni-CLI/llms.txt">llms.txt</a>
+</p>
 
-Self-repair is a first-class capability. When a site changes its API, an agent reads the 20-line YAML, edits the selector or endpoint, saves to `~/.unicli/adapters/`, and retries. Fixes survive `npm update`. No human in the loop.
+<p align="center">
+  Search by intent, run a real command, get a structured envelope back. If a site changes, the error points to the adapter file and step to repair.
+</p>
 
-## Why
+<p align="center">
+  <a href="https://www.npmjs.com/package/@zenalexa/unicli"><img alt="npm" src="https://img.shields.io/npm/v/@zenalexa/unicli?style=flat-square"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
+  <img alt="Node 20+" src="https://img.shields.io/badge/node-20%2B-339933?style=flat-square&logo=node.js&logoColor=white">
+  <img alt="MCP" src="https://img.shields.io/badge/MCP-2025--11--25-6f42c1?style=flat-square">
+</p>
 
-MCP tool catalogs cost 4–35× more tokens per call than an equivalent CLI invocation, and 55K tokens of cold-start tax before the agent touches a tool (Firecrawl, Scalekit, Apideck benchmarks; see [`docs/BENCHMARK.md`](docs/BENCHMARK.md)). Agents perform better with executable programs than with catalogs of tool descriptions. Retrieval-over-catalog research in 2025–2026 (Semantic Tool Discovery, ITR Dynamic Tool Exposure, JSPLIT) reports 95–99% context reduction when tools are fetched on demand.
+<p align="center">
+  <sub><!-- STATS:site_count -->235<!-- /STATS --> sites · <!-- STATS:command_count -->1448<!-- /STATS --> commands · <!-- STATS:pipeline_step_count -->59<!-- /STATS --> pipeline steps · <!-- STATS:test_count -->7394<!-- /STATS --> tests</sub>
+</p>
 
-Uni-CLI is the execution half of that equation. The MCP server exposes 4 meta-tools (~200 tokens cold-start) — `unicli_run`, `unicli_list`, `unicli_search`, `unicli_explore` — and the agent pulls the exact tool it needs via BM25 bilingual search over a 50KB index. The CLI itself costs one subprocess per call.
+<p align="center">
+  <strong>Web / Social / Knowledge</strong><br>
+  <img src="https://img.shields.io/badge/X-000000?style=flat-square&logo=x&logoColor=white" alt="X">
+  <img src="https://img.shields.io/badge/Reddit-FF4500?style=flat-square&logo=reddit&logoColor=white" alt="Reddit">
+  <img src="https://img.shields.io/badge/Instagram-E4405F?style=flat-square&logo=instagram&logoColor=white" alt="Instagram">
+  <img src="https://img.shields.io/badge/TikTok-000000?style=flat-square&logo=tiktok&logoColor=white" alt="TikTok">
+  <img src="https://img.shields.io/badge/YouTube-FF0000?style=flat-square&logo=youtube&logoColor=white" alt="YouTube">
+  <img src="https://img.shields.io/badge/Bilibili-00A1D6?style=flat-square&logo=bilibili&logoColor=white" alt="Bilibili">
+  <img src="https://img.shields.io/badge/Zhihu-0084FF?style=flat-square&logo=zhihu&logoColor=white" alt="Zhihu">
+  <img src="https://img.shields.io/badge/Weibo-E6162D?style=flat-square&logo=sinaweibo&logoColor=white" alt="Weibo">
+  <img src="https://img.shields.io/badge/Xiaohongshu-FF2442?style=flat-square&logoColor=white" alt="Xiaohongshu">
+  <img src="https://img.shields.io/badge/Douyin-000000?style=flat-square&logo=tiktok&logoColor=white" alt="Douyin">
+  <img src="https://img.shields.io/badge/Hacker%20News-FF6600?style=flat-square&logo=ycombinator&logoColor=white" alt="Hacker News">
+  <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub">
+  <img src="https://img.shields.io/badge/Stack%20Overflow-F58025?style=flat-square&logo=stackoverflow&logoColor=white" alt="Stack Overflow">
+  <img src="https://img.shields.io/badge/Product%20Hunt-DA552F?style=flat-square&logo=producthunt&logoColor=white" alt="Product Hunt">
+  <img src="https://img.shields.io/badge/npm-CB3837?style=flat-square&logo=npm&logoColor=white" alt="npm">
+  <img src="https://img.shields.io/badge/PyPI-3775A9?style=flat-square&logo=pypi&logoColor=white" alt="PyPI">
+  <img src="https://img.shields.io/badge/Wikipedia-000000?style=flat-square&logo=wikipedia&logoColor=white" alt="Wikipedia">
+  <img src="https://img.shields.io/badge/Spotify-1DB954?style=flat-square&logo=spotify&logoColor=white" alt="Spotify">
+  <img src="https://img.shields.io/badge/IMDb-F5C518?style=flat-square&logo=imdb&logoColor=black" alt="IMDb">
+  <img src="https://img.shields.io/badge/Bloomberg-000000?style=flat-square&logoColor=white" alt="Bloomberg">
+  <img src="https://img.shields.io/badge/Reuters-FF8000?style=flat-square&logo=reuters&logoColor=white" alt="Reuters">
+  <img src="https://img.shields.io/badge/BBC-B80000?style=flat-square&logo=bbc&logoColor=white" alt="BBC">
+  <img src="https://img.shields.io/badge/Binance-F0B90B?style=flat-square&logo=binance&logoColor=black" alt="Binance">
+  <img src="https://img.shields.io/badge/Coinbase-0052FF?style=flat-square&logo=coinbase&logoColor=white" alt="Coinbase">
+  <img src="https://img.shields.io/badge/Yahoo%20Finance-6001D2?style=flat-square&logo=yahoo&logoColor=white" alt="Yahoo Finance">
+</p>
 
-## Quick start
+<p align="center">
+  <strong>Agent / IDE / Coding Surfaces</strong><br>
+  <img src="https://img.shields.io/badge/Claude%20Code-D97757?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code">
+  <img src="https://img.shields.io/badge/Codex-111111?style=flat-square&logo=openai&logoColor=white" alt="Codex">
+  <img src="https://img.shields.io/badge/OpenCode-101010?style=flat-square&logoColor=white" alt="OpenCode">
+  <img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logoColor=white" alt="Cursor">
+  <img src="https://img.shields.io/badge/Kiro-FF9900?style=flat-square&logo=amazon&logoColor=black" alt="Kiro">
+  <img src="https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=googlegemini&logoColor=white" alt="Gemini">
+  <img src="https://img.shields.io/badge/Qwen-1E88E5?style=flat-square&logoColor=white" alt="Qwen">
+  <img src="https://img.shields.io/badge/Kimi-6C5CE7?style=flat-square&logoColor=white" alt="Kimi">
+  <img src="https://img.shields.io/badge/MiniMax-00A6FB?style=flat-square&logoColor=white" alt="MiniMax">
+  <img src="https://img.shields.io/badge/Cline-6E56CF?style=flat-square&logoColor=white" alt="Cline">
+  <img src="https://img.shields.io/badge/Roo%20Code-2E7D32?style=flat-square&logoColor=white" alt="Roo Code">
+  <img src="https://img.shields.io/badge/Windsurf-00C2FF?style=flat-square&logoColor=white" alt="Windsurf">
+  <img src="https://img.shields.io/badge/Aider-6F42C1?style=flat-square&logo=python&logoColor=white" alt="Aider">
+  <img src="https://img.shields.io/badge/Goose-111827?style=flat-square&logoColor=white" alt="Goose">
+  <img src="https://img.shields.io/badge/OpenHands-FF6B00?style=flat-square&logoColor=white" alt="OpenHands">
+  <img src="https://img.shields.io/badge/SWE--agent-0F172A?style=flat-square&logoColor=white" alt="SWE-agent">
+  <img src="https://img.shields.io/badge/GitHub%20Copilot-181717?style=flat-square&logo=githubcopilot&logoColor=white" alt="GitHub Copilot">
+  <img src="https://img.shields.io/badge/AgentAPI-334155?style=flat-square&logoColor=white" alt="AgentAPI">
+  <img src="https://img.shields.io/badge/acpx-475569?style=flat-square&logoColor=white" alt="acpx">
+</p>
 
-Five minutes, top-to-bottom:
+<p align="center">
+  <strong>Desktop / Media / DevOps / Cloud</strong><br>
+  <img src="https://img.shields.io/badge/macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS">
+  <img src="https://img.shields.io/badge/Chrome-4285F4?style=flat-square&logo=googlechrome&logoColor=white" alt="Chrome">
+  <img src="https://img.shields.io/badge/Blender-F5792A?style=flat-square&logo=blender&logoColor=white" alt="Blender">
+  <img src="https://img.shields.io/badge/FFmpeg-007808?style=flat-square&logo=ffmpeg&logoColor=white" alt="FFmpeg">
+  <img src="https://img.shields.io/badge/ImageMagick-0074C1?style=flat-square&logoColor=white" alt="ImageMagick">
+  <img src="https://img.shields.io/badge/GIMP-5C5543?style=flat-square&logo=gimp&logoColor=white" alt="GIMP">
+  <img src="https://img.shields.io/badge/FreeCAD-729FCF?style=flat-square&logo=freecad&logoColor=white" alt="FreeCAD">
+  <img src="https://img.shields.io/badge/Audacity-0000CC?style=flat-square&logo=audacity&logoColor=white" alt="Audacity">
+  <img src="https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker">
+  <img src="https://img.shields.io/badge/GitHub%20CLI-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub CLI">
+  <img src="https://img.shields.io/badge/jq-C7254E?style=flat-square&logo=json&logoColor=white" alt="jq">
+  <img src="https://img.shields.io/badge/yt--dlp-4A5568?style=flat-square&logo=youtube&logoColor=white" alt="yt-dlp">
+  <img src="https://img.shields.io/badge/AWS-232F3E?style=flat-square&logo=amazonaws&logoColor=white" alt="AWS">
+  <img src="https://img.shields.io/badge/Vercel-000000?style=flat-square&logo=vercel&logoColor=white" alt="Vercel">
+  <img src="https://img.shields.io/badge/Supabase-3ECF8E?style=flat-square&logo=supabase&logoColor=black" alt="Supabase">
+  <img src="https://img.shields.io/badge/Cloudflare-F38020?style=flat-square&logo=cloudflare&logoColor=white" alt="Cloudflare">
+  <img src="https://img.shields.io/badge/Stripe-635BFF?style=flat-square&logo=stripe&logoColor=white" alt="Stripe">
+  <img src="https://img.shields.io/badge/Firebase-FFCA28?style=flat-square&logo=firebase&logoColor=black" alt="Firebase">
+  <img src="https://img.shields.io/badge/Netlify-00C7B7?style=flat-square&logo=netlify&logoColor=white" alt="Netlify">
+  <img src="https://img.shields.io/badge/Railway-0B0D0E?style=flat-square&logo=railway&logoColor=white" alt="Railway">
+  <img src="https://img.shields.io/badge/Azure-0078D4?style=flat-square&logo=microsoftazure&logoColor=white" alt="Azure">
+  <img src="https://img.shields.io/badge/Google%20Cloud-4285F4?style=flat-square&logo=googlecloud&logoColor=white" alt="Google Cloud">
+  <img src="https://img.shields.io/badge/Slack-4A154B?style=flat-square&logo=slack&logoColor=white" alt="Slack">
+  <img src="https://img.shields.io/badge/Notion-000000?style=flat-square&logo=notion&logoColor=white" alt="Notion">
+  <img src="https://img.shields.io/badge/Linear-5E6AD2?style=flat-square&logo=linear&logoColor=white" alt="Linear">
+  <img src="https://img.shields.io/badge/Figma-F24E1E?style=flat-square&logo=figma&logoColor=white" alt="Figma">
+</p>
 
 ```bash
-# 1. Install
 npm install -g @zenalexa/unicli
-
-# 2. Discover
-unicli list                                   # all sites + commands
-unicli search "推特热门"                       # → twitter trending (bilingual)
-
-# 3. Run
-unicli reddit hot --limit 3                   # zero-config web API
-unicli hackernews top -f json | jq '.data[].title' # pipe + transform
-
-# 4. Wire into an agent
-claude mcp add unicli -- npx @zenalexa/unicli mcp serve   # Claude Code (MCP stdio)
-unicli mcp serve --transport streamable --port 19826      # Any MCP client (HTTP)
-unicli acp                                                # avante.nvim / Zed (ACP)
+unicli search "hacker news frontpage"
+unicli hackernews top -f json
 ```
 
-Full walkthrough with 5 worked examples: [`docs/QUICKSTART.md`](docs/QUICKSTART.md).
+<!-- IF YOU ARE AN AI AGENT: Start here.
+Install: npm install -g @zenalexa/unicli
+Discover: unicli search "your intent"
+Run: unicli <site> <command> [args] [-f json|md|yaml|csv|compact]
+Repair: read the error envelope, edit the adapter_path, run unicli repair <site> <command>
+Prefer native CLI / JSON stream / MCP for agent runtimes. Use ACP as an editor compatibility gateway.
+-->
 
-## Architecture
+## What It Does
 
-```mermaid
-graph TB
-    CMD["unicli &lt;site&gt; &lt;command&gt;"]
+Uni-CLI turns software surfaces into commands that agents can discover, run, and fix.
 
-    CMD --> ADAPT["Adapter layer<br/><!-- STATS:adapter_count_yaml -->896<!-- /STATS --> YAML · <!-- STATS:adapter_count_ts -->77<!-- /STATS --> TS · 35 bridges"]
+| Surface            | What you get                                                                                       |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| Websites and APIs  | Declarative adapters for public, cookie, header, and browser-intercept workflows                   |
+| Browser automation | CDP steps for navigate, click, type, intercept, snapshot, extract, wait, and related browser work  |
+| Desktop and macOS  | System commands, app adapters, screenshots, clipboard, calendar, brightness, and local tools       |
+| External CLIs      | 58 registered pass-through bridges with install/status discovery                                   |
+| Agent backends     | Route matrix for native CLI, JSON stream, MCP, ACP, HTTP API, OpenAI-compatible, and bridge routes |
+| Output             | v2 `AgentEnvelope` in Markdown, JSON, YAML, CSV, or compact format                                 |
+| Repair             | Structured errors with `adapter_path`, failing `step`, retryability, suggestions, and alternatives |
 
-    ADAPT --> ENGINE["Pipeline engine — <!-- STATS:pipeline_step_count -->59<!-- /STATS -->+ steps<br/>fetch · navigate · exec · extract · each · if · parallel"]
+## For Agents
 
-    ENGINE --> T1["HTTP<br/>(web APIs)"]
-    ENGINE --> T2["CDP Browser<br/>(raw WebSocket)"]
-    ENGINE --> T3["Subprocess<br/>(ffmpeg, yt-dlp, gh)"]
-    ENGINE --> T4["Desktop-AX<br/>(macOS AppleScript)"]
-    ENGINE --> T5["Desktop-UIA<br/>(Windows declared stub)"]
-    ENGINE --> T6["Desktop-AT-SPI<br/>(Linux declared stub)"]
-    ENGINE --> T7["CUA<br/>(contract · mock · provider stubs)"]
+Use search first, then run the smallest matching command.
 
-    T1 --> OUT["Formatter<br/>md · json · yaml · csv · compact"]
-    T2 --> OUT
-    T3 --> OUT
-    T4 --> OUT
-    T5 --> OUT
-    T6 --> OUT
-    T7 --> OUT
+```bash
+unicli search "twitter trending" --limit 5
+unicli twitter search "coding agents" -f json
+unicli repair twitter search
 ```
 
-Seven TransportAdapters, one adapter layer, one formatter. Adapters are declarative YAML by default (Rice-decidable, no imports) and TypeScript when a site genuinely needs it. The full step reference lives in [`docs/ADAPTER-FORMAT.md`](docs/ADAPTER-FORMAT.md).
-
-## Self-repair
-
-When a command breaks:
-
-```
-unicli <site> <cmd> fails
-  → structured error envelope on stderr
-    { adapter_path, step, action, suggestion }
-  → agent opens the ~20-line YAML
-  → agent edits the selector / URL / auth
-  → unicli <site> <cmd> works
-  → fix persists in ~/.unicli/adapters/ (survives npm update)
-```
+Output defaults to structured Markdown for non-TTY and agent-user-agent runs. Force a machine format when you need one:
 
 ```bash
-unicli repair hackernews top      # Diagnose + suggest fix
-unicli test hackernews            # Validate adapter
-unicli repair --loop              # Autonomous fix loop
+UNICLI_OUTPUT=json unicli reddit hot --limit 10
+unicli hackernews top --limit 5 -f yaml
 ```
 
-Exit codes follow `sysexits.h`: `0` ok, `66` empty, `69` unavailable, `75` temporary, `77` auth, `78` config. Agents parse those directly — no regex over human error text.
-
-## Feature matrix
+Protocol entry points:
 
-| Capability               | What it means                                                                                                           |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| **CUA contract**         | Stable screenshot/action interface with mock backend and explicit provider stubs; not marketed as real computer-use yet |
-| **MCP transports**       | stdio · Streamable HTTP (spec 2025-11-25) · SSE · OAuth 2.1 PKCE                                                        |
-| **ACP ready**            | `unicli acp` speaks JSON-RPC 2.0 for avante.nvim, Zed, Gemini CLI                                                       |
-| **Cross-vendor skills**  | Skills in `skills/` work in Claude Code, OpenCode, Codex, Cursor, Cline                                                 |
-| **Self-repair envelope** | Every error ships `adapter_path` + `step` + `suggestion` (Banach-convergent)                                            |
-| **Bilingual search**     | BM25 + TF-IDF, 50KB index, <10ms queries, 200-entry ZH↔EN alias table                                                   |
-| **Browser operator**     | Extension-backed browser daemon with shared or isolated workspaces, background mode, bind/sessions                      |
+```bash
+npx @zenalexa/unicli mcp serve
+npx @zenalexa/unicli mcp serve --transport streamable --port 19826
+unicli acp
+unicli agents recommend codex
+unicli agents matrix
+```
 
-Detailed benchmarks (p50/p95 token cost per category, vs GitHub MCP cold-start): [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
+ACP is supported for editors and bridge tooling. The primary runtime path stays native CLI, JSON stream, or MCP when those routes are available.
 
-## Platform coverage
+## Coverage
 
-<!-- STATS:site_count -->220<!-- /STATS --> sites · <!-- STATS:command_count -->1283<!-- /STATS --> commands — the live list is auto-generated in [`AGENTS.md`](AGENTS.md) and split by domain:
+The catalog is intentionally broad, but the important point is not the count. The important point is that every command is discoverable, typed, and repairable.
 
-| Domain                | Highlights                                                              |
-| --------------------- | ----------------------------------------------------------------------- |
-| **Social (25)**       | twitter, reddit, instagram, tiktok, xiaohongshu, bilibili, zhihu, weibo |
-| **Tech (19)**         | hackernews, stackoverflow, producthunt, github-trending, npm, pypi      |
-| **News (11)**         | bbc, reuters, bloomberg, nytimes, techcrunch, 36kr                      |
-| **Finance (8)**       | xueqiu, yahoo-finance, eastmoney, binance, coinbase                     |
-| **AI / ML (14)**      | huggingface, ollama, replicate, perplexity, deepseek, doubao            |
-| **Desktop (30+)**     | blender, ffmpeg, imagemagick, gimp, freecad, musescore, kdenlive        |
-| **macOS system (58)** | screenshot, clipboard, Calendar, Mail, Reminders, Shortcuts, Safari     |
-| **CLI bridges (35)**  | gh, yt-dlp, jq, aws, vercel, supabase, wrangler, stripe                 |
+| Area                    | Examples                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Chinese platforms       | xiaohongshu, zhihu, bilibili, douyin, douban, v2ex, jike, linux-do                                          |
+| International platforms | twitter, reddit, instagram, tiktok, discord, slack, hackernews, lesswrong                                   |
+| AI and developer tools  | Claude, ChatGPT, Gemini, Codex, Cursor, VS Code, Docker Desktop, Postman                                    |
+| Finance and news        | xueqiu, eastmoney, yahoo-finance, bloomberg, reuters, bbc, 36kr                                             |
+| Desktop apps            | Blender, FreeCAD, GIMP, Audacity, Figma, Docker, ImageMagick, ffmpeg                                        |
+| Agent CLIs              | Claude Code, Codex, OpenCode, Gemini CLI, Qwen Code, Aider, Goose, Cursor Agent, Kiro, OpenHands, SWE-agent |
 
-Run `unicli list` for the live catalog, or `unicli list --category=<domain>` to filter.
+See the live catalog:
 
-## Agent integration
+```bash
+unicli list
+unicli list --site macos
+unicli ext list
+unicli ext list --tag agent
+```
 
-Every major agent platform works out of the box:
+Browse the same generated catalog on the docs site:
+<https://olo-dot-io.github.io/Uni-CLI/reference/sites>
 
-| Platform        | One-liner                                                  | Notes                                     |
-| --------------- | ---------------------------------------------------------- | ----------------------------------------- |
-| **Claude Code** | `claude mcp add unicli -- npx @zenalexa/unicli mcp serve`  | 4 meta-tools, stdio                       |
-| **Codex CLI**   | Add `[mcp_servers.unicli]` to `~/.codex/config.toml`       | First-class AGENTS.md citizen             |
-| **Cursor**      | MCP Settings → `unicli` → `npx @zenalexa/unicli mcp serve` | Bilingual search works inside Cursor chat |
-| **avante.nvim** | `type = "acp", command = "unicli", args = { "acp" }`       | See [`docs/AVANTE.md`](docs/AVANTE.md)    |
-| **OpenCode**    | MCP via `opencode.jsonc` — `command: "unicli mcp serve"`   | AGENTS.md auto-loaded                     |
-| **Cline**       | Add MCP server in settings — stdio transport               | Same 4 meta-tools, 200-token cold start   |
+## Output Contract
 
-Direct shell access (any agent with Bash or exec):
+Every normal command returns a v2 envelope. `mcp serve` and `acp` are protocol servers and keep their raw stdio protocol.
 
-```bash
-unicli twitter search "AI agents"
-unicli blender render scene.blend --output /tmp/frame.png
-unicli macos screenshot --region 0,0,1920,1080
+```yaml
+ok: true
+schema_version: "2"
+command: "twitter.search"
+meta:
+  duration_ms: 412
+  count: 20
+  surface: web
+data:
+  - { id: "...", text: "...", author: "..." }
+error: null
 ```
 
-## Authentication
-
-Five auth strategies, auto-probed in a cascade (`public → cookie → header`):
+Errors are meant to be acted on:
 
-| Strategy    | How                                                    |
-| ----------- | ------------------------------------------------------ |
-| `public`    | Direct HTTP, no credentials                            |
-| `cookie`    | `~/.unicli/cookies/<site>.json` injected into headers  |
-| `header`    | Cookie + auto-extracted CSRF (ct0, bili_jct, …)        |
-| `intercept` | Chrome navigates, Uni-CLI captures XHR/fetch responses |
-| `ui`        | Direct DOM interaction via CDP (click, type, submit)   |
-
-```bash
-unicli auth setup twitter    # Print required cookies + target path
-unicli auth check twitter    # Validate cookie file
-unicli auth list             # All configured sites
+```yaml
+ok: false
+schema_version: "2"
+command: "twitter.search"
+meta:
+  duration_ms: 91
+data: null
+error:
+  code: auth_required
+  message: "401 Unauthorized"
+  adapter_path: "src/adapters/twitter/search.yaml"
+  step: 1
+  suggestion: "Run: unicli auth setup twitter"
+  retryable: false
+  alternatives: ["twitter.timeline", "twitter.profile"]
 ```
 
-The browser operator has two layers:
+Exit codes: `0` ok, `66` empty, `69` unavailable, `75` temporary failure, `77` auth, `78` config.
 
-- `unicli browser start` manages a local Chrome/CDP launch path for cookie extraction and direct CDP use.
-- `unicli browser ...` / `unicli daemon ...` route through the local browser daemon plus Browser Bridge extension, with explicit workspace reuse, `--daemon-port` multi-profile routing, background/focus controls, and live session diagnostics.
+## Self-Repair
 
-For agent-style interactive browsing, prefer:
+Adapters are small YAML files by default. A failed command gives an agent enough context to patch the broken part without waiting for a package release.
 
-```bash
-unicli browser open https://example.com
-unicli browser state
-unicli browser find --css "button, a"
-unicli browser network --raw
-unicli browser extract
+```text
+1. Run the command.
+2. Read the error envelope.
+3. Open error.adapter_path.
+4. Patch the failing step.
+5. Save the override in ~/.unicli/adapters/<site>/<command>.yaml.
+6. Verify with unicli repair <site> <command>.
 ```
 
-## Write an adapter
+Local overrides survive npm updates.
 
-Most adapters are ~20 lines of YAML. No TypeScript, no build step, no imports:
+## Write An Adapter
 
 ```yaml
-site: hackernews
-name: top
-type: web-api
+site: example
+name: search
+description: "Search example.com"
+transport: http
 strategy: public
+capabilities: [fetch, select, map, limit]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
 pipeline:
   - fetch:
-      url: "https://hacker-news.firebaseio.com/v0/topstories.json"
-  - limit: { count: "${{ args.limit | default(30) }}" }
-  - each:
-      do:
-        - fetch:
-            url: "https://hacker-news.firebaseio.com/v0/item/${{ item }}.json"
+      url: "https://api.example.com/search?q=${{ args.query }}"
+  - select: data.results
   - map:
       title: "${{ item.title }}"
-      score: "${{ item.score }}"
       url: "${{ item.url }}"
-columns: [title, score, url]
-```
-
-Five adapter types: `web-api`, `desktop`, `browser`, `bridge`, `service`. 29 template filters (`join`, `urlencode`, `truncate`, `slugify`, `default`, `json`, …) run in a sandboxed VM.
-
-Scaffold, dev, test:
-
-```bash
-unicli init <site> <command>     # Scaffold new adapter
-unicli dev <path>                # Hot-reload during dev
-unicli test <site>               # Validate
-unicli record <url>              # Auto-generate adapter from traffic
-```
-
-Full reference: [`docs/ADAPTER-FORMAT.md`](docs/ADAPTER-FORMAT.md). Migrating from OpenCLI: [`docs/MIGRATING-FROM-OPENCLI.md`](docs/MIGRATING-FROM-OPENCLI.md) and the one-shot `unicli import opencli-yaml`.
-
-## Search
-
-Agents find commands by intent, bilingual:
-
-```bash
-unicli search "推特热门"            # → twitter trending
-unicli search "download video"      # → bilibili download, yt-dlp download, twitter download
-unicli search "股票行情"            # → binance ticker, xueqiu quote, barchart quote
-unicli search --category finance    # browse by category
+  - limit: "${{ args.limit }}"
+args:
+  - { name: query, type: string, required: true, positional: true }
+  - { name: limit, type: int, default: 20 }
+columns: [title, url]
 ```
 
-BM25 + TF-IDF scoring with a 200-entry ZH↔EN alias table. The index is 50KB, queries complete in under 10ms.
+Docs:
 
-## Theory + benchmarks
+- [Documentation site](https://olo-dot-io.github.io/Uni-CLI/)
+- [Getting started](docs/guide/getting-started.md)
+- [Integrations](docs/guide/integrations.md)
+- [Adapter format](docs/ADAPTER-FORMAT.md)
+- [Pipeline reference](docs/reference/pipeline.md)
+- [Exit codes](docs/reference/exit-codes.md)
 
-The design rests on five principles, each tied to a citation in [`docs/refs.bib`](docs/refs.bib):
+## Trust And Limits
 
-1. **Rice's restriction** — every adapter has decidable semantics (YAML pipeline, no Turing-complete logic).
-2. **Lehman's mandate** — no adapter is permanent; self-repair is first-class.
-3. **Shannon's compression** — CLI invocations are near-optimal compression of the underlying API call.
-4. **Agent tool trilemma (original)** — coverage × accuracy × performance, pick two. We choose accuracy × performance.
-5. **Banach convergence** — structured errors must provide directional feedback (`adapter_path` + `step` + `suggestion`) so repair iterations converge.
-
-Full treatment with 42 citations: [`docs/THEORY.md`](docs/THEORY.md). Reproducible benchmarks comparing Uni-CLI to GitHub MCP and Firecrawl MCP: [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
+- Auth-required sites use local cookie files under `~/.unicli/cookies/<site>.json`.
+- Browser adapters require a reachable Chrome/CDP session.
+- CUA routes require a configured real backend. Declared-but-unavailable providers fail closed with structured errors.
+- User adapters and repairs live in `~/.unicli/adapters/`; committed adapters remain the package baseline.
+- If a site blocks automation or changes a private API, the correct behavior is a clear failure envelope, not a fabricated success.
 
 ## Development
 
 ```bash
-git clone https://github.com/olo-dot-io/Uni-CLI.git && cd Uni-CLI
-npm install
-npm run verify     # typecheck + lint + test + build + stats check
+pnpm install
+pnpm typecheck
+pnpm lint
+npm run verify
 ```
 
-| Command                | Purpose                                                   |
-| ---------------------- | --------------------------------------------------------- |
-| `npm run dev`          | Run from source                                           |
-| `npm run build`        | Production build                                          |
-| `npm run typecheck`    | TypeScript strict                                         |
-| `npm run lint`         | Oxlint                                                    |
-| `npm run test`         | Unit tests (<!-- STATS:test_count -->7145<!-- /STATS -->) |
-| `npm run test:adapter` | Validate all adapters                                     |
-| `npm run verify`       | Full pipeline (7 gates)                                   |
-
-Eleven production dependencies: `ajv`, `ajv-formats`, `chalk`, `cli-table3`, `commander`, `js-yaml`, `jsonpath-plus`, `turndown`, `undici`, `ws`, `zod`.
-
-## Release cadence
-
-Patches ship every **Friday 09:00 HKT** when substantive commits have landed since the last tag. Quiet weeks are recorded and skipped — silence is success, not failure. Dependabot bumps are grouped into one PR per Monday so they ride along in the Friday cut without flooding the commit log.
-
-<a href="https://github.com/olo-dot-io/Uni-CLI/commits/main"><img src="https://img.shields.io/github/last-commit/olo-dot-io/Uni-CLI?style=flat-square&label=last-commit" alt="last commit"></a>
-
-Full policy — manual overrides, cancellation procedure, escalation rules: [`docs/RELEASE-CADENCE.md`](docs/RELEASE-CADENCE.md).
-
-## Contributing
-
-The fastest path to a merged PR: write a 20-line YAML adapter for a site you use every day. Per-domain guides live in [`contributing/`](contributing/):
-
-| Area             | Guide                                                    |
-| ---------------- | -------------------------------------------------------- |
-| New adapter      | [`contributing/adapter.md`](contributing/adapter.md)     |
-| New transport    | [`contributing/transport.md`](contributing/transport.md) |
-| CUA backend      | [`contributing/cua.md`](contributing/cua.md)             |
-| MCP server       | [`contributing/mcp.md`](contributing/mcp.md)             |
-| ACP integration  | [`contributing/acp.md`](contributing/acp.md)             |
-| Release process  | [`contributing/release.md`](contributing/release.md)     |
-| Schema migration | [`contributing/schema.md`](contributing/schema.md)       |
-
 ## License
 
 [Apache-2.0](./LICENSE)
 
-Repo: <https://github.com/olo-dot-io/Uni-CLI> · npm: [`@zenalexa/unicli`](https://www.npmjs.com/package/@zenalexa/unicli) · Issues welcome.
-
----
-
-<p align="center">
-  <a href="https://github.com/olo-dot-io/Uni-CLI/graphs/contributors">
-    <img src="https://contrib.rocks/image?repo=olo-dot-io/Uni-CLI" alt="Contributors">
-  </a>
-</p>
-
 <p align="center">
-  <sub>v0.215.0 — Closed Adapter Loop</sub><br>
-  <sub><!-- STATS:site_count -->220<!-- /STATS --> sites · <!-- STATS:command_count -->1283<!-- /STATS --> commands · <!-- STATS:pipeline_step_count -->59<!-- /STATS --> pipeline steps · BM25+TF-IDF bilingual search · MCP 2025-11-25 · <!-- STATS:test_count -->7145<!-- /STATS --> tests</sub>
+  <sub>0.216.0 — OpenCLI Parity Harness</sub>
 </p>