@zenalexa/unicli 0.210.0 → 0.212.1

package/README.md

@@ -1,61 +1,120 @@
-<!-- AGENT: npm install -g @zenalexa/unicli && unicli list | 957 commands across 195 sites. JSON when piped. Self-repairing YAML adapters. unicli repair --loop for autonomous fix. See AGENTS.md -->
+<!-- AGENT: npm install -g @zenalexa/unicli && unicli search "your intent" — hundreds of commands across ~200 sites. JSON when piped. Self-repairing YAML adapters. Bilingual EN/ZH search. See AGENTS.md for live counts. -->
 
-<h1 align="center">Uni-CLI</h1>
+<div align="center">
 
-<p align="center">
-  <strong>CLI is all agents need.</strong><br>
-  <sub>One command to control any website, desktop app, or local tool — with structured JSON output and self-repairing adapters.</sub>
-</p>
+<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>
 
-<p align="center">
-  <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="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://www.npmjs.com/package/@zenalexa/unicli"><img src="https://img.shields.io/npm/dm/@zenalexa/unicli?style=flat-square" alt="downloads"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@zenalexa/unicli?style=flat-square&color=339933" alt="node"></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/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
-</p>
+<br><br>
 
-<p align="center">
-  <code>npm install -g @zenalexa/unicli</code>
-</p>
+**CLI is all agents need.**
 
----
+The execution layer for agent skills. Deterministic, editable, cross-vendor.
 
-```bash
-unicli hackernews top --limit 5          # Hacker News front page
-unicli twitter search "AI agents"        # Twitter (authenticated)
-unicli bilibili hot                      # Bilibili trending
-unicli blender render scene.blend        # Render a 3D scene
-unicli cursor ask "explain this code"    # Talk to Cursor IDE
-unicli notion search "meeting notes"     # Search Notion
-unicli obs scene set "Camera 2"          # Switch OBS scene
-unicli ffmpeg compress video.mp4         # Compress video
+<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 -->1146<!-- /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
 ```
 
-Every command outputs **structured JSON when piped** — zero flags needed. Every error emits structured JSON to stderr with the adapter path, the failing step, and a fix suggestion. **~80 tokens per call.**
+<br>
+
+<img src="docs/demo/demo.svg" alt="Uni-CLI in 30 seconds" width="720">
+
+</div>
+
+---
+
+## What
+
+Uni-CLI is a universal interface that compiles agent intent into deterministic CLI programs. One binary reaches <!-- STATS:site_count -->200<!-- /STATS --> sites, 30+ desktop apps, 35 CLI bridges, and the local OS — <!-- STATS:command_count -->968<!-- /STATS --> commands in total. Every adapter is a 20-line YAML pipeline, so agents can read, edit, and re-run them without a compiler.
+
+Coverage is cross-cutting: web APIs and browser automation, desktop subprocesses (ffmpeg, Blender, LibreOffice), macOS system calls (screenshot, clipboard, Calendar), and Computer Use Agents (Anthropic, OpenAI, Google) — all behind the same `unicli <site> <command>` surface. Output is a table in a terminal and JSON when piped. Errors are structured JSON on stderr with the adapter path, the failing step, and a suggestion — enough directional feedback for an agent to fix the adapter and retry.
 
-## Key Ideas
+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.
 
-**Universal** — 195 sites, 30+ desktop apps, 8 Electron apps, 35 CLI bridges, 30 macOS system commands. One interface: `unicli <site> <command>`.
+## Why
 
-**Self-repairing** — When a site changes its API, the agent reads the ~20 line YAML adapter, fixes it, retries. No human in the loop. Fixes persist across updates.
+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.
 
-**Agent-native** — Piped output auto-switches to JSON. Errors are machine-parseable. Exit codes follow `sysexits.h`. The agent doesn't need flags or special handling.
+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.
 
-**Cheap** — ~80 tokens per CLI invocation vs 550–1,400 tokens for an MCP tool definition. Two orders of magnitude cheaper in context window cost.
+## Quick start
 
-## Self-Repair
+Five minutes, top-to-bottom:
 
-The core differentiator. When a command breaks, agents fix it themselves:
+```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 --json | jq '.[].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)
+```
+
+Full walkthrough with 5 worked examples: [`docs/QUICKSTART.md`](docs/QUICKSTART.md).
+
+## Architecture
 
 ```mermaid
-flowchart LR
-    A["unicli site cmd\n❌ fails"] --> B["Structured error\n{adapter_path, step, suggestion}"]
-    B --> C["Agent reads\n20-line YAML"]
-    C --> D["Agent edits\nthe adapter"]
-    D --> E["unicli site cmd\n✅ works"]
-    E --> F["Fix persists in\n~/.unicli/adapters/"]
+graph TB
+    CMD["unicli &lt;site&gt; &lt;command&gt;"]
+
+    CMD --> ADAPT["Adapter layer<br/>887 YAML · 72 TS · 35 bridges"]
+
+    ADAPT --> ENGINE["Pipeline engine — <!-- STATS:pipeline_step_count -->54<!-- /STATS -->+ steps<br/>fetch · navigate · exec · extract · each · if · parallel"]
+
+    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 UIAutomation)"]
+    ENGINE --> T6["Desktop-AT-SPI<br/>(Linux accessibility)"]
+    ENGINE --> T7["CUA<br/>(Anthropic · OpenAI · Google)"]
+
+    T1 --> OUT["Formatter<br/>table · json · yaml · csv · md"]
+    T2 --> OUT
+    T3 --> OUT
+    T4 --> OUT
+    T5 --> OUT
+    T6 --> OUT
+    T7 --> OUT
+```
+
+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 JSON error 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)
 ```
 
 ```bash
@@ -64,125 +123,83 @@ unicli test hackernews            # Validate adapter
 unicli repair --loop              # Autonomous fix loop
 ```
 
-Fixes are saved to `~/.unicli/adapters/` and survive `npm update`.
-
-## Coverage
-
-<details open>
-<summary><strong>Web Platforms — 95 sites</strong></summary>
-
-| Category           | Sites                                                                                                                                                                           |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Tech / Dev**     | hackernews, stackoverflow, devto, lobsters, producthunt, hf, github-trending, substack, lesswrong, npm, pypi, crates-io, cocoapods, homebrew, gitlab, gitee, npm-trends, ollama |
-| **Social**         | twitter (35 cmds), reddit (20), instagram (24), tiktok (15), facebook (10), bluesky (12), medium, threads                                                                       |
-| **Chinese Social** | bilibili (18), weibo, zhihu (20), xiaohongshu (24), douyin (13), jike, douban, weread, tieba, v2ex, linux-do, zsxq, xiaoyuzhou, baidu, toutiao                                  |
-| **Video / Media**  | youtube (5), bilibili, douyin, tiktok, kuaishou, douyu, wechat-channels, twitch                                                                                                 |
-| **Finance**        | xueqiu, sinafinance, barchart, yahoo-finance, binance, futu, coinbase, eastmoney                                                                                                |
-| **News**           | bbc, bloomberg (10), reuters, 36kr, google news, cnn, nytimes, techcrunch, theverge, infoq, ithome                                                                              |
-| **Shopping**       | amazon (8), xianyu, coupang, smzdm, jd, maoyan, ele, dianping, dangdang, pinduoduo, meituan                                                                                     |
-| **Jobs**           | boss (14), linkedin                                                                                                                                                             |
-| **AI Platforms**   | gemini (5), grok, doubao-web (9), notebooklm (15), yollomi (12), jimeng, yuanbao, deepseek, perplexity                                                                          |
-| **Education**      | chaoxing, arxiv, wikipedia                                                                                                                                                      |
-| **Other**          | ones (11), band, xiaoe, pixiv (6), hupu (7), ctrip, sinablog, steam                                                                                                             |
-
-</details>
-
-<details>
-<summary><strong>Desktop Software — 32 apps</strong></summary>
-
-| Category          | Apps                                                                |
-| ----------------- | ------------------------------------------------------------------- |
-| **3D / CAD**      | blender (13 cmds), freecad (15), cloudcompare (4), openscad         |
-| **Image**         | gimp (12), inkscape, imagemagick (6), krita (4)                     |
-| **Video / Audio** | ffmpeg (11), kdenlive (3), shotcut (3), audacity (8), musescore (5) |
-| **Diagram**       | drawio, mermaid                                                     |
-| **Document**      | libreoffice, pandoc                                                 |
-| **Streaming**     | obs (8, WebSocket)                                                  |
-| **Productivity**  | zotero (8), vscode (3), obsidian (3)                                |
-| **Dev Services**  | wiremock (5), adguardhome (5), novita (3)                           |
-| **Browser**       | chrome (2), zoom (2)                                                |
-| **Other**         | slay-the-spire-ii (6), sketch (3)                                   |
-
-</details>
-
-<details>
-<summary><strong>Electron Apps — 8 apps, 70 commands</strong></summary>
-
-All via Chrome DevTools Protocol — no extensions, no hacks.
-
-| App             | Commands                                                                                       | Port |
-| --------------- | ---------------------------------------------------------------------------------------------- | ---- |
-| **Cursor**      | ask, send, read, model, composer, extract-code, new, status, screenshot, dump, history, export | 9226 |
-| **Codex**       | ask, send, read, model, extract-diff, new, status, screenshot, dump, history, export           | 9222 |
-| **ChatGPT**     | ask, send, read, model, new, status, screenshot, dump                                          | 9236 |
-| **Notion**      | search, read, write, new, status, sidebar, favorites, export, screenshot                       | 9230 |
-| **Discord**     | servers, channels, read, send, search, members, status, delete                                 | 9232 |
-| **ChatWise**    | ask, send, read, model, new, status, screenshot, dump                                          | 9228 |
-| **Doubao**      | ask, send, read, new, status, screenshot, dump                                                 | 9225 |
-| **Antigravity** | ask, send, read, model, new, status, screenshot, dump                                          | 9234 |
-
-</details>
-
-<details>
-<summary><strong>CLI Bridges — 35 tools</strong></summary>
-
-Passthrough wrappers that normalize output to JSON:
-
-docker, gh, jq, yt-dlp, vercel, supabase, wrangler, lark, dingtalk, hf, claude-code, codex-cli, opencode, aws, gcloud, az, doctl, netlify, railway, flyctl, pscale, neonctl, slack, kimi-cli, gws, deepagents, stripe, firebase, mmx-cli, wecom, mem0, dws, hermes, openclaw, opencode-cli
-
-</details>
-
-<details>
-<summary><strong>macOS System — 30 commands</strong></summary>
-
-| Category          | Commands                                                                                                                                                     |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Audio/Display** | volume, dark-mode, brightness, say                                                                                                                           |
-| **Power/System**  | battery, lock-screen, caffeinate, sleep, uptime, system-info                                                                                                 |
-| **Files/Search**  | spotlight, disk-info, trash, empty-trash, open, finder-tags, finder-recent, finder-selection                                                                 |
-| **Network**       | wifi, wifi-info, bluetooth                                                                                                                                   |
-| **Notifications** | notify, notification, do-not-disturb                                                                                                                         |
-| **Apps**          | apps, apps-list, active-app, open-app, safari-tabs, shortcuts-list, shortcuts-run                                                                            |
-| **PIM**           | calendar-list, calendar-create, calendar-today, contacts-search, mail-status, mail-send, messages-send, reminders-list, reminders-create, reminders-complete |
-| **Media**         | music-now, music-control, photos-search, notes-list, notes-search, screenshot, clipboard, processes                                                          |
-
-</details>
+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.
 
-## Architecture
+## Feature matrix
 
-```mermaid
-graph TB
-    CMD["unicli &lt;site&gt; &lt;command&gt; [args]"]
-
-    CMD --> YAML["YAML Adapter<br/><i>~20 lines, agent-editable</i>"]
-    CMD --> TS["TS Adapter<br/><i>complex logic</i>"]
-    CMD --> BRIDGE["Bridge<br/><i>passthrough to CLI</i>"]
-
-    YAML --> ENGINE
-    TS --> ENGINE
-    BRIDGE --> ENGINE
-
-    subgraph ENGINE ["Pipeline Engine — 35 steps"]
-        direction LR
-        API["fetch  fetch_text<br/>parse_rss  html_to_md"]
-        TRANSFORM["select  map  filter<br/>sort  limit"]
-        BROWSER["navigate  evaluate<br/>click  type  press<br/>scroll  intercept<br/>snapshot  tap  extract"]
-        CONTROL["set  if  each<br/>parallel  append<br/>rate_limit  assert  retry"]
-        OTHER["exec  write_temp<br/>download  websocket"]
-    end
-
-    ENGINE --> CDP["Direct CDP"]
-    ENGINE --> DAEMON["Browser Daemon<br/><i>reuses Chrome logins</i>"]
-
-    CDP --> OUT["Output Formatter<br/><i>table · json · yaml · csv · md</i>"]
-    DAEMON --> OUT
+| Capability               | What it means                                                                                        |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| **CUA backends**         | Anthropic `computer-use`, OpenAI Operator, Google CUA, and direct CDP — 4 transports behind one flag |
+| **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 daemon**       | Persistent Chrome via CDP, reuses your login sessions, 13-layer stealth                              |
+
+Detailed benchmarks (p50/p95 token cost per category, vs GitHub MCP cold-start): [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
+
+## Platform coverage
+
+<!-- STATS:site_count -->200<!-- /STATS --> sites · <!-- STATS:command_count -->968<!-- /STATS --> commands — the live list is auto-generated in [`AGENTS.md`](AGENTS.md) and split by domain:
+
+| 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                 |
+
+Run `unicli list` for the live catalog, or `unicli list --category=<domain>` to filter.
+
+## Agent integration
+
+Every major agent platform works out of the box:
+
+| 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   |
+
+Direct shell access (any agent with Bash or exec):
+
+```bash
+unicli twitter search "AI agents"
+unicli blender render scene.blend --output /tmp/frame.png
+unicli macos screenshot --region 0,0,1920,1080
 ```
 
-Remote browser support via `UNICLI_CDP_ENDPOINT` — connect to any CDP WebSocket (Cloudflare Browser Rendering, Browserless, or self-hosted).
+## Authentication
+
+Five auth strategies, auto-probed in a cascade (`public → cookie → header`):
 
-## Write an Adapter
+| 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)   |
 
-Most adapters are ~20 lines of YAML:
+```bash
+unicli auth setup twitter    # Print required cookies + target path
+unicli auth check twitter    # Validate cookie file
+unicli auth list             # All configured sites
+```
+
+The browser daemon (`unicli browser start`) reuses your signed-in Chrome session via CDP — no cookie export, no extension install. Auto-exits after 4h idle.
+
+## Write an adapter
+
+Most adapters are ~20 lines of YAML. No TypeScript, no build step, no imports:
 
 ```yaml
 site: hackernews
@@ -197,95 +214,91 @@ pipeline:
       do:
         - fetch:
             url: "https://hacker-news.firebaseio.com/v0/item/${{ item }}.json"
-      max: "${{ args.limit | default(30) }}"
   - map:
       title: "${{ item.title }}"
       score: "${{ item.score }}"
       url: "${{ item.url }}"
-      by: "${{ item.by }}"
-columns: [title, score, by, url]
+columns: [title, score, url]
 ```
 
-Five adapter types: `web-api`, `desktop`, `browser`, `bridge`, `service`.
-
-29 template filters in a sandboxed VM: `join`, `urlencode`, `truncate`, `slugify`, `sanitize`, `basename`, `strip_html`, `default`, `split`, `first`, `last`, `length`, `keys`, `json`, `replace`, `lowercase`, `uppercase`, `trim`, `slice`, `reverse`, `unique`, `abs`, `round`, `ceil`, `floor`, `int`, `float`, `str`, `ext`.
+Five adapter types: `web-api`, `desktop`, `browser`, `bridge`, `service`. 29 template filters (`join`, `urlencode`, `truncate`, `slugify`, `default`, `json`, …) run in a sandboxed VM.
 
-## Authentication
-
-Five strategies, auto-detected via cascade (`PUBLIC → COOKIE → HEADER`):
-
-| Strategy    | How                                                      |
-| ----------- | -------------------------------------------------------- |
-| `public`    | Direct HTTP — no credentials                             |
-| `cookie`    | Injects cookies from `~/.unicli/cookies/<site>.json`     |
-| `header`    | Cookie + auto-extracted CSRF token (ct0, bili_jct, etc.) |
-| `intercept` | Navigates page in Chrome, captures XHR/fetch responses   |
-| `ui`        | Direct DOM interaction (click, type, submit)             |
+Scaffold, dev, test:
 
 ```bash
-unicli auth setup twitter    # Show required cookies + template
-unicli auth check twitter    # Validate cookie file
-unicli auth list             # List configured sites
+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
 ```
 
-## Browser Daemon
+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`.
 
-Persistent background process that reuses your Chrome login sessions — no cookie export, no extension install:
+## Search
+
+Agents find commands by intent, bilingual:
 
 ```bash
-unicli daemon status             # Check daemon
-unicli operate open <url>        # Navigate
-unicli operate state             # DOM accessibility snapshot
-unicli operate click <ref>       # Click by ref
-unicli operate type <ref> <text> # Type into element
-unicli operate eval <js>         # Execute JavaScript
-unicli operate screenshot        # Capture page
-unicli record <url>              # Auto-generate adapter from traffic
+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
 ```
 
-13-layer anti-detection stealth: webdriver removal, `chrome.runtime` mock, CDP marker cleanup, `Error.stack` filtering, iframe consistency, and more. Auto-exits after 4h idle.
+BM25 + TF-IDF scoring with a 200-entry ZH↔EN alias table. The index is 50KB, queries complete in under 10ms.
 
-## MCP Server
+## Theory + benchmarks
 
-For MCP-only environments:
+The design rests on five principles, each tied to a citation in [`docs/refs.bib`](docs/refs.bib):
 
-```bash
-unicli mcp serve    # All 957 commands become MCP tools
-```
+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).
 
 ## Development
 
 ```bash
 git clone https://github.com/olo-dot-io/Uni-CLI.git && cd Uni-CLI
-npm install && npm run verify
+npm install
+npm run verify     # typecheck + lint + test + build + stats check
 ```
 
-| Command                | Purpose                   |
-| ---------------------- | ------------------------- |
-| `npm run dev`          | Dev run                   |
-| `npm run build`        | Production build          |
-| `npm run typecheck`    | TypeScript strict         |
-| `npm run lint`         | Oxlint                    |
-| `npm run test`         | Unit tests (788)          |
-| `npm run test:adapter` | Validate all 601 adapters |
-| `npm run verify`       | Full pipeline             |
+| 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 -->1146<!-- /STATS -->) |
+| `npm run test:adapter` | Validate all adapters                                     |
+| `npm run verify`       | Full pipeline (7 gates)                                   |
 
-7 production dependencies: `chalk`, `cli-table3`, `commander`, `js-yaml`, `turndown`, `undici`, `ws`.
+Seven production dependencies: `chalk`, `cli-table3`, `commander`, `js-yaml`, `turndown`, `undici`, `ws`.
 
 ## Contributing
 
-The fastest way to contribute: write a [20-line YAML adapter](./CONTRIBUTING.md) for a site you use.
+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/):
 
-```bash
-unicli init <site> <command>     # Scaffold new adapter
-unicli dev <path>                # Hot-reload during dev
-unicli test <site>               # Validate
-```
+| 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">
@@ -295,6 +308,6 @@ unicli test <site>               # Validate
 </p>
 
 <p align="center">
-  <sub>v0.210.0 — Vostok · Komarov</sub><br>
-  <sub>195 sites · 957 commands · 35 pipeline steps · 29 filters · 788 tests</sub>
+  <sub>v0.211.2 — Vostok · Volynov</sub><br>
+  <sub><!-- STATS:site_count -->200<!-- /STATS --> sites · <!-- STATS:command_count -->968<!-- /STATS --> commands · <!-- STATS:pipeline_step_count -->54<!-- /STATS --> pipeline steps · BM25+TF-IDF bilingual search · MCP 2025-11-25 · <!-- STATS:test_count -->1146<!-- /STATS --> tests</sub>
 </p>

package/dist/cli.d.ts

@@ -2,5 +2,13 @@
  * CLI entry point — Commander-based routing with dynamic adapter commands.
  */
 import { Command } from "commander";
+/**
+ * Apply the `--json` deprecation alias.
+ *
+ * Exported so unit tests can exercise the alias logic without booting the
+ * full Commander program. Walks up to the root `Command` so nested
+ * subcommands still read `format: "json"` from `program.opts()`.
+ */
+export declare function applyJsonAlias(cmd: Command): void;
 export declare function createCli(): Promise<Command>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CpC,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAkmBlD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkDpC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAajD;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAgsBlD"}