@zenalexa/unicli 0.218.0 → 0.218.1

package/AGENTS.md

@@ -52,4 +52,22 @@ project ships at high cadence, written counts go stale fast.
 
 ## Version
 
-0.218.0 — Apollo · Cernan
+0.218.1 — Apollo · Cernan Patch
+
+## MCP one-liner (Claude Desktop / Cursor / Continue)
+
+```json
+{
+  "mcpServers": {
+    "unicli": {
+      "command": "npx",
+      "args": ["-y", "@zenalexa/unicli-mcp"]
+    }
+  }
+}
+```
+
+Equivalent: `npx -y @zenalexa/unicli mcp serve`. Default profile exposes 4
+meta-tools (~200 tokens); `--expanded` exposes one tool per command (3,319
+tools, ~160K tokens). The registry manifest is shipped at `server.json` for
+the official MCP registry.

package/README.md

@@ -354,5 +354,5 @@ npm run verify
 [Apache-2.0](./LICENSE)
 
 <p align="center">
-  <sub>v0.218.0 — Apollo · Cernan</sub>
+  <sub>v0.218.1 — Apollo · Cernan Patch</sub>
 </p>

package/README.zh-CN.md

@@ -334,5 +334,5 @@ npm run verify
 [Apache-2.0](./LICENSE)
 
 <p align="center">
-  <sub>v0.218.0 — Apollo · Cernan</sub>
+  <sub>v0.218.1 — Apollo · Cernan Patch</sub>
 </p>

package/dist/bin/unicli-mcp.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @owner   src/bin/unicli-mcp.ts
+ * @does    One-liner npm bin that boots the Uni-CLI MCP server (stdio).
+ * @needs   ../mcp/server.js
+ * @feeds   npm bin -> `npx -y @zenalexa/unicli-mcp` (Claude Desktop, Cursor, etc.)
+ * @breaks  Server start failure propagates as exit 1; no fallback transport.
+ */
+import "../mcp/server.js";
+//# sourceMappingURL=unicli-mcp.d.ts.map

package/dist/bin/unicli-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unicli-mcp.d.ts","sourceRoot":"","sources":["../../src/bin/unicli-mcp.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,kBAAkB,CAAC"}

package/dist/bin/unicli-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @owner   src/bin/unicli-mcp.ts
+ * @does    One-liner npm bin that boots the Uni-CLI MCP server (stdio).
+ * @needs   ../mcp/server.js
+ * @feeds   npm bin -> `npx -y @zenalexa/unicli-mcp` (Claude Desktop, Cursor, etc.)
+ * @breaks  Server start failure propagates as exit 1; no fallback transport.
+ */
+import "../mcp/server.js";
+//# sourceMappingURL=unicli-mcp.js.map

package/dist/bin/unicli-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unicli-mcp.js","sourceRoot":"","sources":["../../src/bin/unicli-mcp.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,kBAAkB,CAAC"}

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.218.0",
+  "version": "0.218.1",
   "sites": {
     "1688": {
       "commands": [

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@zenalexa/unicli",
-  "version": "0.218.0",
-  "description": "Agent execution substrate for web, apps, local tools, and system capabilities",
+  "version": "0.218.1",
+  "description": "Agent execution substrate for web, apps, local tools, and system capabilities. Self-repairing CLI catalog for 237+ websites and apps. Stdio + Streamable HTTP MCP server.",
   "type": "module",
   "main": "dist/main.js",
   "bin": {
-    "unicli": "dist/main.js"
+    "unicli": "dist/main.js",
+    "unicli-mcp": "dist/bin/unicli-mcp.js"
   },
   "files": [
     "dist/",
@@ -14,6 +15,19 @@
     "docs/mcp/clients/",
     "src/adapters/",
     "src/hub/",
+    "skills/unicli/",
+    "skills/unicli-browser/",
+    "skills/unicli-claude-code/",
+    "skills/unicli-explorer/",
+    "skills/unicli-hermes/",
+    "skills/unicli-oneshot/",
+    "skills/unicli-operate/",
+    "skills/unicli-repair/",
+    "skills/unicli-smart-search/",
+    "skills/unicli-usage/",
+    "skills/talk-normal/",
+    "skills/README.md",
+    "server.json",
     "AGENTS.md"
   ],
   "publishConfig": {
@@ -124,7 +138,7 @@
   "scripts": {
     "dev": "tsx src/main.ts",
     "build": "tsc && tsx scripts/build-manifest.js && tsx scripts/count-stats.ts && tsx scripts/build-readme.ts && tsx scripts/build-agents.ts && prettier --write AGENTS.md",
-    "postbuild": "node -e \"require('fs').chmodSync('dist/main.js', 0o755)\"",
+    "postbuild": "node -e \"const fs=require('fs'); fs.chmodSync('dist/main.js', 0o755); fs.chmodSync('dist/bin/unicli-mcp.js', 0o755);\"",
     "stats": "tsx scripts/build-manifest.js && tsx scripts/count-stats.ts && tsx scripts/build-readme.ts && tsx scripts/build-agents.ts",
     "stats:check": "tsx scripts/count-consistency.ts",
     "build:agents": "tsx scripts/build-agents.ts",
@@ -219,10 +233,10 @@
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "@zenalexa/unicli-atspi-linux-arm64": "0.218.0",
-    "@zenalexa/unicli-atspi-linux-x64": "0.218.0",
-    "@zenalexa/unicli-uia-win32-arm64": "0.218.0",
-    "@zenalexa/unicli-uia-win32-x64": "0.218.0"
+    "@zenalexa/unicli-atspi-linux-arm64": "0.218.1",
+    "@zenalexa/unicli-atspi-linux-x64": "0.218.1",
+    "@zenalexa/unicli-uia-win32-arm64": "0.218.1",
+    "@zenalexa/unicli-uia-win32-x64": "0.218.1"
   },
   "devDependencies": {
     "@ai-sdk/openai-compatible": "^2.0.41",

package/server.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.olo-dot-io/Uni-CLI",
+  "description": "Self-repairing CLI catalog that exposes 237+ websites, desktop apps, and external CLIs as one MCP server. 920 declarative YAML adapters; structured error envelopes let agents fix failing adapters at runtime and retry.",
+  "version": "0.218.1",
+  "repository": {
+    "url": "https://github.com/olo-dot-io/Uni-CLI",
+    "source": "github"
+  },
+  "websiteUrl": "https://olo-dot-io.github.io/Uni-CLI/",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@zenalexa/unicli",
+      "version": "0.218.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "mcp",
+          "valueHint": "subcommand",
+          "isRequired": true
+        },
+        {
+          "type": "positional",
+          "value": "serve",
+          "valueHint": "subcommand",
+          "isRequired": true
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "UNICLI_MCP_PROFILE",
+          "description": "Tool profile: default (4 meta-tools), expanded (one tool per command), or computer-use",
+          "isRequired": false,
+          "default": "default"
+        }
+      ]
+    }
+  ]
+}

package/skills/README.md

@@ -0,0 +1,39 @@
+# Uni-CLI Skills
+
+Cross-vendor agent skills shipped with the repo. Each `<name>/SKILL.md`
+follows the [Agent Skill Protocol v2.0](https://github.com/anthropics/skills)
+with `name`, `description`, `triggers` frontmatter, and a progressive
+loading layout (L0 index → L1 main → L2 references → L3 external).
+
+These skills are consumable by any agent platform that speaks the
+SKILL.md standard: Claude Code, Codex, Hermes, Cline, OpenCode, etc.
+
+## Skills
+
+| Skill                 | Purpose                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `talk-normal`         | Always-on concise writing rules for docs and UI copy                                |
+| `unicli`              | Comprehensive agent guide — discover, run, read output, auth, errors, skill routing |
+| `bgclick-rev`         | IDA-backed research workflow for macOS background clicks                            |
+| `unicli-browser`      | Control Chrome via daemon bridge                                                    |
+| `unicli-claude`       | Claude.ai-specific commands and integration                                         |
+| `unicli-claude-code`  | Claude Code CLI integration                                                         |
+| `unicli-explorer`     | Create new adapters by exploring sites/APIs                                         |
+| `unicli-hermes`       | Hermes-platform integration                                                         |
+| `unicli-oneshot`      | One-shot adapter generation from a URL + goal                                       |
+| `unicli-operate`      | Direct browser automation via `operate` subcommands                                 |
+| `unicli-repair`       | Self-repair workflow for broken adapters (envelope-driven)                          |
+| `unicli-smart-search` | Route search queries to the best platform                                           |
+| `unicli-usage`        | Command reference and usage guide                                                   |
+
+## Adding a skill
+
+1. Create `skills/<name>/SKILL.md` with v2.0 frontmatter.
+2. Keep the protocol section lean (decision trees, not prose).
+3. Push large references into `skills/<name>/references/`.
+4. Add a row above.
+5. `npm run lint:context` scores it against the agent-lint rubric;
+   threshold is 60/100.
+
+See `docs/guide/integrations.md`, `contributing/mcp.md`, and the global
+skills protocol guide for structure details.

package/skills/talk-normal/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: talk-normal
+slug: talk-normal
+description: Always-on writing rules for concise, normal, bilingual documentation and user-facing text.
+version: 0.6.2
+tags: [prompt, writing, concise, anti-slop, chinese, bilingual, always-on]
+homepage: https://github.com/hexiecs/talk-normal
+license: MIT
+---
+
+# talk-normal
+
+Use this skill before drafting or editing public docs, UI copy, README text,
+agent-facing instructions, release notes, and other user-facing prose.
+
+The full writing rules live in [prompt.md](prompt.md). The operating summary:
+
+- Lead with the answer or concrete point.
+- Keep useful detail; remove filler, throat-clearing, and corporate polish.
+- Prefer direct positive claims.
+- Use bullets only when the content is naturally parallel.
+- End with the concrete recommendation or next action when one is needed.
+- Avoid hypothetical follow-up offers.
+
+Upstream: https://github.com/hexiecs/talk-normal

package/skills/talk-normal/prompt.md

@@ -0,0 +1,35 @@
+<!-- talk-normal 0.6.2 -->
+
+Be direct and informative. No filler, no fluff, but give enough to be useful.
+
+Your single hardest constraint: prefer direct positive claims. Do not use negation-based contrastive phrasing in any language or position — neither "reject then correct" (不是X，而是Y) nor "correct then reject" (X，而不是Y). If you catch yourself writing a sentence where a negative adverb sets up or follows a positive claim, restructure and state only the positive.
+
+Examples:
+
+BAD: 真正的创新者不是"有创意的人"，而是五种特质同时拉满的人
+GOOD: 真正的创新者是五种特质同时拉满的人
+
+BAD: 真正的创新者是五种特质同时拉满的人，而不是单纯"聪明"的人
+GOOD: 真正的创新者是五种特质同时拉满的人
+
+BAD: 这更像创始人筛选框架，不是交易信号
+GOOD: 这是一个创始人筛选框架
+
+BAD: It's not about intelligence, it's about taste
+GOOD: Taste is what matters
+
+Rules:
+
+- Lead with the answer, then add context only if it genuinely helps.
+- Do not use negation-based contrastive phrasing in any position. This covers any sentence structure where a negative adverb rejects an alternative to set up or append to a positive claim: in any order, chained, symmetric, or with or without an explicit conjunction. State the positive claim directly. If a genuine distinction needs both sides, name them as parallel positive clauses. Narrow exception: technical statements about necessary or sufficient conditions in logic, math, or formal proofs.
+- End with a concrete recommendation or next step when relevant. Do not use summary-stamp closings such as "In conclusion", "In summary", "Hope this helps", "一句话总结", "总结一下", "简而言之", or any structural variant that labels a summary before delivering it.
+- Kill filler: "I'd be happy to", "Great question", "It's worth noting", "Certainly", "Of course", "Let me break this down", "首先我们需要", "值得注意的是", "综上所述", "让我们一起来看看".
+- Never restate the question.
+- Yes/no questions: answer first, one sentence of reasoning.
+- Comparisons: give your recommendation with brief reasoning.
+- Code: give the code and usage example if non-trivial.
+- Explanations: match depth to complexity. Simple question = short answer. Complex question = structured but tight.
+- Use structure only when the content has natural sequential or parallel structure.
+- Do not end with hypothetical follow-up offers or conditional next-step menus.
+- Do not restate the same point in a "plain language" or "in human terms" block after already explaining it.
+- When listing pros/cons or comparing options, cap each side at 3-4 important points.

package/skills/unicli/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: unicli
+description: >
+  Comprehensive guide to using Uni-CLI — the universal CLI for AI agents.
+  Trigger when the user needs to fetch data from websites (Twitter, Bilibili,
+  HackerNews, GitHub, Reddit, Bloomberg, Zhihu, WeChat, and 230+ more);
+  interact with news, finance, social, academic, shopping, or video platforms;
+  control macOS desktop apps (Blender, GIMP, Figma, VS Code, Cursor, Terminal,
+  Discord, Slack, etc.) via AppleScript or Accessibility API; automate browser
+  actions on login-gated pages; extract trending/hot/search/top lists from any
+  major platform; run desktop workflows or system tasks; or when the user says
+  "unicli", "scrape", "fetch from", "get trending", "check [site]", "find on
+  [platform]", "获取", "查询", "抓取".
+version: 0.218.0
+category: core
+depends-on:
+  - talk-normal
+allowed-tools: [Bash, Read]
+protocol: 2.0
+triggers:
+  - "unicli"
+  - "fetch from"
+  - "get from"
+  - "check twitter"
+  - "bilibili"
+  - "hackernews"
+  - "scrape"
+  - "trending"
+  - "hot topics"
+  - "desktop app"
+  - "macOS app"
+  - "browser automation"
+  - "search web"
+  - "social media"
+  - "获取"
+  - "查询"
+  - "抓取"
+---
+
+# Uni-CLI — Agent Usage Guide
+
+unicli converts 237 websites, 2,000+ desktop apps, and macOS system tools into
+deterministic CLI commands. Each command is a ≤20-line YAML pipeline: fetch data,
+transform it, emit a v2 AgentEnvelope. When a command breaks, read the structured
+error, edit the YAML adapter, and it stays fixed for all future calls.
+
+**Install** (once): `npm install -g @zenalexa/unicli`
+
+---
+
+## Five-Command Quick Start
+
+```bash
+unicli list                              # browse all 3,319 commands
+unicli list --site hackernews            # commands for one site
+unicli hackernews top --limit 5          # run a command
+unicli hackernews top --limit 5 -f json  # machine-readable JSON envelope
+unicli describe hackernews top           # full schema + example payload
+```
+
+---
+
+## Step 1 — Discover the Right Command
+
+### Find by site
+
+```bash
+unicli list --site <site>          # all commands for a site
+unicli describe <site> <command>   # args, output columns, example
+```
+
+### Search by keyword
+
+```bash
+unicli search "trending"           # semantic search across all commands
+unicli search "hot stock"          # natural language
+```
+
+### Browse by type
+
+```bash
+unicli list --type web-api         # REST API adapters (1,138 commands)
+unicli list --type desktop         # desktop app control (2,068 commands)
+unicli list --type browser         # browser automation (23 commands)
+unicli list --type service         # local/remote services (43 commands)
+unicli list --type bridge          # passthrough CLI bridges (47 commands)
+```
+
+### Check if a site exists
+
+```bash
+unicli list --site github-trending  # returns commands or empty
+unicli health                        # adapter index summary
+```
+
+---
+
+## Step 2 — Run Commands
+
+### Basic syntax
+
+```bash
+unicli <site> <command> [<positional-arg>] [--flag value] [-f json|md|yaml|csv]
+```
+
+### Key flags (universal)
+
+| Flag                 | Effect                                                     |
+| -------------------- | ---------------------------------------------------------- |
+| `--limit N`          | Cap output rows (default varies, max 100)                  |
+| `-f json`            | Machine-readable v2 AgentEnvelope JSON to stdout           |
+| `-f md`              | Agent-native Markdown (default, frontmatter + sections)    |
+| `-f yaml`            | YAML envelope                                              |
+| `-f csv`             | Flat CSV (array data only)                                 |
+| `-f compact`         | One row per line, `\|` separator                           |
+| `--args-file <path>` | Read args from a JSON file (avoids shell-quote issues)     |
+| `--cursor <token>`   | Pagination cursor from previous envelope `meta.pagination` |
+
+### Common patterns
+
+```bash
+# Search
+unicli hackernews search "AI agents" --limit 10
+
+# Trending
+unicli weibo hot
+unicli bilibili hot --limit 20
+
+# Finance
+unicli xueqiu hot-stock --limit 10 -f json
+
+# Desktop control
+unicli blender render scene.blend output.png
+unicli ffmpeg compress video.mp4 -o compressed.mp4
+
+# macOS system
+unicli macos volume 60
+unicli macos screenshot ~/Desktop/capture.png
+```
+
+### Pagination
+
+```bash
+# First page
+unicli reddit hot --limit 25 -f json | jq '.meta.pagination.next_cursor'
+
+# Next page (use cursor from previous response)
+unicli reddit hot --limit 25 --cursor <token> -f json
+```
+
+---
+
+## Step 3 — Read the Output
+
+Every command emits a **v2 AgentEnvelope**. Learn the shape once; it applies to
+all 3,319 commands.
+
+### JSON structure
+
+```json
+{
+  "ok": true,
+  "schema_version": "2",
+  "command": "hackernews.top",
+  "meta": {
+    "duration_ms": 2805,
+    "count": 5,
+    "surface": "web",
+    "pagination": { "next_cursor": "...", "has_more": true }
+  },
+  "data": [{ "rank": 1, "title": "...", "score": 80, "url": "..." }],
+  "error": null,
+  "next_actions": [
+    { "command": "unicli describe hackernews top", "description": "..." }
+  ]
+}
+```
+
+### Key fields
+
+| Field             | Meaning                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `ok`              | `true` = success, `false` = failure — **always check first** |
+| `schema_version`  | Always `"2"` — confirms v2 envelope                          |
+| `meta.count`      | Rows returned                                                |
+| `meta.pagination` | Non-null when more pages exist; use `.next_cursor`           |
+| `data`            | Payload array or object                                      |
+| `error`           | `null` on success; structured on failure (see Step 5)        |
+| `next_actions`    | HATEOAS hints — valid commands to run next, trust these      |
+
+### Markdown format (default)
+
+When piped or called by an agent, the default format is `md` — YAML frontmatter
+followed by formatted sections. Use `-f json` for programmatic parsing.
+
+### Parse with jq
+
+```bash
+unicli hackernews top -f json | jq '.[].title'           # WRONG: data is nested
+unicli hackernews top -f json | jq '.data[].title'       # correct
+unicli hackernews top -f json | jq '.data[] | {title, url}'
+unicli xueqiu hot -f json | jq '.data[] | select(.change | tonumber > 5)'
+```
+
+---
+
+## Step 4 — Authentication
+
+unicli uses a **strategy cascade** that auto-probes on first run. Most sites need
+no manual setup — the cascade promotes from `public` → `cookie` → `header`
+automatically.
+
+### Strategy ladder
+
+| Strategy    | Auth needed           | How to set up                                          |
+| ----------- | --------------------- | ------------------------------------------------------ |
+| `public`    | None                  | Works out of the box                                   |
+| `cookie`    | Browser login         | `unicli auth setup <site>` → log in once in browser    |
+| `header`    | Cookie + CSRF         | Same as `cookie`; auto-extracted per request           |
+| `intercept` | Browser session       | `unicli browser start` then `unicli auth setup <site>` |
+| `ui`        | Browser + interaction | Same; unicli clicks through login flow                 |
+
+### Auth setup workflow
+
+```bash
+# First time — unicli guides you through browser login
+unicli auth setup twitter
+
+# Verify credentials are stored
+unicli auth status twitter
+
+# List all authenticated sites
+unicli auth list
+
+# Re-authenticate when cookies expire (exit code 77)
+unicli auth setup <site>
+```
+
+Cookie files live at `~/.unicli/cookies/<site>.json` — never read or edit these
+directly; use `unicli auth`.
+
+---
+
+## Step 5 — Handle Errors
+
+### Exit code → action (primary decision tree)
+
+| Code | Meaning                | Action                                             |
+| ---- | ---------------------- | -------------------------------------------------- |
+| 0    | Success                | Read `data`                                        |
+| 1    | Generic error          | Read `error.reason` + `error.suggestion`           |
+| 2    | Usage error            | Fix arg syntax; run `unicli describe <site> <cmd>` |
+| 66   | Empty result           | Try different query terms or `--limit`             |
+| 69   | Service unavailable    | `unicli browser start` then retry                  |
+| 75   | Temp failure / timeout | Retry once; if persists → load `unicli-repair`     |
+| 77   | Auth required          | `unicli auth setup <site>` then retry              |
+| 78   | Config error           | Read `error.suggestion`; check `~/.unicli/` config |
+
+### Failure envelope fields
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "auth_required",
+    "exit_code": 77,
+    "message": "No cookie file found for twitter",
+    "adapter_path": "adapters/twitter/search.yaml",
+    "step": 1,
+    "retryable": true,
+    "suggestion": "Run `unicli auth setup twitter` to authenticate",
+    "remedy": {
+      "command": "unicli auth setup twitter",
+      "message": "Open browser to complete login"
+    }
+  }
+}
+```
+
+### Hard rules
+
+- **ALWAYS check `ok` first** before reading `data`.
+- **NEVER retry on exit 2** (usage error — fix the args, not the adapter).
+- **Follow `error.remedy.command`** exactly — it is generated from the adapter schema.
+- **Load `unicli-repair` skill** when the same command fails twice after following
+  `remedy` — the adapter likely needs structural repair, not just a retry.
+
+---
+
+## Browser Mode (Escalation Path)
+
+Use browser mode when: a site requires JavaScript rendering, login-gated access,
+interaction (click/type/scroll), or the API adapter returns exit 69.
+
+```bash
+unicli browser start             # launch Chrome with CDP (required first)
+unicli browser status            # confirm CDP is alive + session state
+unicli browser open <url>        # navigate to page
+unicli browser state             # DOM accessibility tree with [ref] IDs
+unicli browser find --css h2     # query specific elements
+unicli browser click <ref>       # interact
+unicli browser type <ref> "text" # fill input
+unicli browser extract           # extract full page text
+unicli browser screenshot        # capture to file
+```
+
+For a guided browser automation workflow, load skill `unicli-browser`.
+
+---
+
+## Composition Patterns
+
+### Multi-source research
+
+```bash
+# Tech trends: query 3 sources
+unicli hackernews top --limit 10 -f json | jq '.data[].title'
+unicli reddit hot --limit 10 -f json | jq '.data[].title'
+unicli github-trending daily --limit 10 -f json | jq '.data[].name'
+```
+
+### Cross-platform topic search
+
+```bash
+for site in hackernews reddit twitter; do
+  echo "=== $site ===" && unicli $site search "AI agents" --limit 5
+done
+```
+
+### Data pipeline (pipe to jq)
+
+```bash
+unicli bilibili hot -f json \
+  | jq '.data[] | select(.view | tonumber > 1000000) | {title, view, up}'
+```
+
+### Budget rule: 1–2 primary sources + 1 supplementary per user question. Never
+
+query the same site twice in one turn.
+
+---
+
+## Skill Routing
+
+| Scenario                                     | Load skill            |
+| -------------------------------------------- | --------------------- |
+| Adapter fails with structured error envelope | `unicli-repair`       |
+| Search queries across platforms              | `unicli-smart-search` |
+| Browser automation, CDP sessions             | `unicli-browser`      |
+| Creating a new adapter from scratch          | `unicli-explorer`     |
+| One-shot URL → adapter generation            | `unicli-oneshot`      |
+| Claude / Claude.ai commands                  | `unicli-claude`       |
+| Claude Code commands                         | `unicli-claude-code`  |
+| Hermes integration                           | `unicli-hermes`       |
+| Detailed command reference                   | `unicli-usage`        |
+
+---
+
+## Efficiency Rules
+
+1. Default output is `md` (Markdown). Use `-f json` for programmatic parsing.
+2. Always set `--limit` — default varies per command (5–50); unset = potentially 100+.
+3. MCP server (`unicli mcp serve`) wraps all commands as tools; 4 default tools,
+   `--expanded` adds all 3,319 (costs tokens: use only in MCP-only environments).
+4. Adapter user overlay: fixes go to `~/.unicli/adapters/<site>/<cmd>.yaml`
+   and survive `npm update`.
+5. `unicli doctor` checks runtime health (Node version, Chrome, auth files,
+   adapter index). Run it when unexplained failures occur.
+6. `UNICLI_OUTPUT=json unicli <cmd>` sets JSON globally without `-f json` per call.
+
+---
+
+## Reference Index
+
+| Reference                                      | Load when                                |
+| ---------------------------------------------- | ---------------------------------------- |
+| [`references/sites.md`](references/sites.md)   | Browsing the site catalog by category    |
+| [`references/output.md`](references/output.md) | Parsing AgentEnvelope v2 fields in depth |
+| [`references/auth.md`](references/auth.md)     | Auth setup per site, cookie management   |
+
+---
+
+## MCP Server
+
+```bash
+unicli mcp serve                    # 4 tools: run, list, search, explore
+unicli mcp serve --expanded         # all 3,319 commands as individual tools
+unicli mcp serve --profile browser  # browser + CDP tools only
+```