@jackwener/opencli 0.7.4 → 0.7.6

package/README.md

@@ -48,7 +48,7 @@ OpenCLI connects to your browser through the Playwright MCP Bridge extension.
 ### Playwright MCP Bridge Extension Setup
 
 1. Install **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension in Chrome.
-2. Run `opencli setup` — it auto-discovers your token and lets you choose which tools to configure:
+2. Run `opencli setup` — discovers the token, distributes it to your tools, and verifies connectivity:
 
 ```bash
 opencli setup
@@ -58,6 +58,15 @@ The interactive TUI will:
 - 🔍 Auto-discover `PLAYWRIGHT_MCP_EXTENSION_TOKEN` from Chrome (no manual copy needed)
 - ☑️ Show all detected tools (Codex, Cursor, Claude Code, Gemini CLI, etc.)
 - ✏️ Update only the files you select (Space to toggle, Enter to confirm)
+- 🔌 Auto-verify browser connectivity after writing configs
+
+> **Tip**: Use `opencli doctor` for ongoing diagnosis and maintenance:
+> ```bash
+> opencli doctor            # Read-only token & config diagnosis
+> opencli doctor --live     # Also test live browser connectivity
+> opencli doctor --fix      # Fix mismatched configs (interactive)
+> opencli doctor --fix -y   # Fix all configs non-interactively
+> ```
 
 <details>
 <summary>Manual setup (alternative)</summary>
@@ -86,14 +95,6 @@ export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<your-token-here>"
 
 </details>
 
-Verify with `opencli doctor` — shows colored status for extension install, token consistency, and all config locations:
-
-```bash
-opencli doctor            # Token & config diagnosis
-opencli doctor --live     # Also test live browser connectivity
-opencli doctor --fix -y   # Auto-fix all mismatched configs
-```
-
 ## Quick Start
 
 ### Install via npm (recommended)

package/README.zh-CN.md

@@ -1,7 +1,7 @@
 # OpenCLI
 
 > **把任何网站变成你的命令行工具。**  
-> 零风控 · 复用 Chrome 登录 · AI 自动发现接口
+> 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 80+ 命令 · 19 站点
 
 [English](./README.md)
 
@@ -9,7 +9,7 @@
 [![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-OpenCLI 将任何网站变成命令行工具 — B站、知乎、小红书、Twitter、Reddit 等众多站点 — 复用浏览器登录态，AI 驱动探索。
+OpenCLI 将任何网站变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube 等 [19 个站点](#内置命令) — 复用浏览器登录态，AI 驱动探索。
 
 ---
 
@@ -29,8 +29,9 @@ OpenCLI 将任何网站变成命令行工具 — B站、知乎、小红书、Twi
 
 ## 亮点
 
-- **多站点覆盖** — B站、知乎、小红书、Twitter、Reddit 等众多站点
+- **多站点覆盖** — B站、知乎、小红书、Twitter、Reddit 等 19 个站点，80+ 命令
 - **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- **自修复配置** — `opencli setup` 自动发现 Token；`opencli doctor` 诊断 10+ 工具配置；`--fix` 一键修复
 - **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
 - **动态加载引擎** — 声明式的 `.yaml` 或者底层定制的 `.ts` 适配器，放入 `clis/` 文件夹即可自动注册生效
 
@@ -46,7 +47,7 @@ OpenCLI 通过 Playwright MCP Bridge 扩展与你的浏览器通信。
 ### Playwright MCP Bridge 扩展配置
 
 1. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
-2. 运行 `opencli setup` — 自动发现 Token 并让你选择要配置哪些工具：
+2. 运行 `opencli setup` — 自动发现 Token、分发到各工具、验证连通性：
 
 ```bash
 opencli setup
@@ -56,6 +57,15 @@ opencli setup
 - 🔍 从 Chrome 自动发现 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`（无需手动复制）
 - ☑️ 显示所有支持的工具（Codex、Cursor、Claude Code、Gemini CLI 等）
 - ✏️ 只更新你选中的文件（空格切换，回车确认）
+- 🔌 完成后自动验证浏览器连通性
+
+> **Tip**：后续诊断和维护用 `opencli doctor`：
+> ```bash
+> opencli doctor            # 只读 Token 与配置诊断
+> opencli doctor --live     # 额外测试浏览器连通性
+> opencli doctor --fix      # 修复不一致的配置（交互确认）
+> opencli doctor --fix -y   # 无交互直接修复所有配置
+> ```
 
 <details>
 <summary>手动配置（备选方案）</summary>
@@ -84,12 +94,6 @@ export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<你的-token>"
 
 </details>
 
-配置后运行 `opencli doctor` 检查所有位置的 Token 状态：
-
-```bash
-opencli doctor
-```
-
 ## 快速开始
 
 ### npm 全局安装（推荐）
@@ -129,27 +133,29 @@ npm install -g @jackwener/opencli@latest
 
 ## 内置命令
 
-| 站点 | 命令 | 模式 |
-|------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` | 🔐 浏览器 |
-| **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
-| **xiaohongshu** | `search` `notifications` `feed` `user` | 🔐 浏览器 |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` | 🔐 浏览器 |
-| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 🔐 浏览器 |
-| **weibo** | `hot` | 🔐 浏览器 |
-| **boss** | `search` `detail` | 🔐 浏览器 |
-| **coupang** | `search` `add-to-cart` | 🔐 浏览器 |
-| **youtube** | `search` | 🔐 浏览器 |
-| **linkedin** | `search` | 🔐 浏览器 |
-| **yahoo-finance** | `quote` | 🔐 浏览器 |
-| **reuters** | `search` | 🔐 浏览器 |
-| **smzdm** | `search` | 🔐 浏览器 |
-| **ctrip** | `search` | 🔐 浏览器 |
-| **github** | `search` | 🌐 公共 API |
-| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 公共 API / 🔐 浏览器 |
-| **hackernews** | `top` | 🌐 公共 API |
-| **bbc** | `news` | 🌐 公共 API |
+**19 个站点 · 80+ 命令** — 运行 `opencli list` 查看完整注册表。
+
+| 站点 | 命令 | 数量 | 模式 |
+|------|------|:----:|------|
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` | 18 | 🔐 浏览器 |
+| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 15 | 🔐 浏览器 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` | 11 | 🔐 浏览器 |
+| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 6 | 🌐 / 🔐 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 6 | 🔐 浏览器 |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 5 | 🔐 浏览器 |
+| **youtube** | `search` `video` `transcript` | 3 | 🔐 浏览器 |
+| **zhihu** | `hot` `search` `question` | 3 | 🔐 浏览器 |
+| **boss** | `search` `detail` | 2 | 🔐 浏览器 |
+| **coupang** | `search` `add-to-cart` | 2 | 🔐 浏览器 |
+| **bbc** | `news` | 1 | 🌐 公共 API |
+| **ctrip** | `search` | 1 | 🔐 浏览器 |
+| **github** | `search` | 1 | 🌐 公共 API |
+| **hackernews** | `top` | 1 | 🌐 公共 API |
+| **linkedin** | `search` | 1 | 🔐 浏览器 |
+| **reuters** | `search` | 1 | 🔐 浏览器 |
+| **smzdm** | `search` | 1 | 🔐 浏览器 |
+| **weibo** | `hot` | 1 | 🔐 浏览器 |
+| **yahoo-finance** | `quote` | 1 | 🔐 浏览器 |
 
 ## 输出格式
 
@@ -201,6 +207,7 @@ opencli cascade https://api.example.com/data
   - 确保 Node.js 版本 `>= 18`。旧版不支持我们使用的现代核心库 API。
 - **Token 问题**
   - 运行 `opencli doctor` 诊断所有工具的 Token 配置状态。
+  - 使用 `opencli doctor --live` 测试浏览器连通性。
 
 ## 版本发布
 

package/SKILL.md

@@ -164,7 +164,8 @@ opencli validate bilibili   # Validate specific site
 opencli setup               # Interactive token setup (auto-discover + TUI checkbox)
 opencli doctor              # Diagnose token & extension config across all tools
 opencli doctor --live       # Also test live browser connectivity
-opencli doctor --fix -y     # Auto-fix all config files (non-interactive)
+opencli doctor --fix        # Fix mismatched configs (interactive confirmation)
+opencli doctor --fix -y     # Fix all configs non-interactively
 ```
 
 ### AI Agent Workflow

package/dist/completion.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shell tab-completion support for opencli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'opencli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export declare function getCompletions(words: string[], cursor: number): string[];
+export declare function bashCompletionScript(): string;
+export declare function zshCompletionScript(): string;
+export declare function fishCompletionScript(): string;
+/**
+ * Print the completion script for the requested shell.
+ */
+export declare function printCompletionScript(shell: string): void;

package/dist/completion.js

@@ -0,0 +1,116 @@
+/**
+ * Shell tab-completion support for opencli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+import { getRegistry } from './registry.js';
+// ── Dynamic completion logic ───────────────────────────────────────────────
+/**
+ * Built-in (non-dynamic) top-level commands.
+ */
+const BUILTIN_COMMANDS = [
+    'list',
+    'validate',
+    'verify',
+    'explore',
+    'probe', // alias for explore
+    'synthesize',
+    'generate',
+    'cascade',
+    'doctor',
+    'setup',
+    'completion',
+];
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'opencli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export function getCompletions(words, cursor) {
+    // cursor === 1 → completing the first argument (site name or built-in command)
+    if (cursor <= 1) {
+        const sites = new Set();
+        for (const [, cmd] of getRegistry()) {
+            sites.add(cmd.site);
+        }
+        return [...BUILTIN_COMMANDS, ...sites].sort();
+    }
+    const site = words[0];
+    // If the first word is a built-in command, no further completion
+    if (BUILTIN_COMMANDS.includes(site)) {
+        return [];
+    }
+    // cursor === 2 → completing the sub-command name under a site
+    if (cursor === 2) {
+        const subcommands = [];
+        for (const [, cmd] of getRegistry()) {
+            if (cmd.site === site) {
+                subcommands.push(cmd.name);
+            }
+        }
+        return subcommands.sort();
+    }
+    // cursor >= 3 → no further completion
+    return [];
+}
+// ── Shell script generators ────────────────────────────────────────────────
+export function bashCompletionScript() {
+    return `# Bash completion for opencli
+# Add to ~/.bashrc:  eval "$(opencli completion bash)"
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`;
+}
+export function zshCompletionScript() {
+    return `# Zsh completion for opencli
+# Add to ~/.zshrc:  eval "$(opencli completion zsh)"
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+compdef _opencli opencli
+`;
+}
+export function fishCompletionScript() {
+    return `# Fish completion for opencli
+# Add to ~/.config/fish/config.fish:  opencli completion fish | source
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+}
+/**
+ * Print the completion script for the requested shell.
+ */
+export function printCompletionScript(shell) {
+    switch (shell) {
+        case 'bash':
+            process.stdout.write(bashCompletionScript());
+            break;
+        case 'zsh':
+            process.stdout.write(zshCompletionScript());
+            break;
+        case 'fish':
+            process.stdout.write(fishCompletionScript());
+            break;
+        default:
+            console.error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
+            process.exitCode = 1;
+    }
+}

package/dist/doctor.d.ts

@@ -50,8 +50,8 @@ export declare function toolName(p: string): string;
 export declare function getDefaultShellRcPath(): string;
 export declare function getDefaultMcpConfigPaths(cwd?: string): string[];
 export declare function readTokenFromShellContent(content: string): string | null;
-export declare function upsertShellToken(content: string, token: string): string;
-export declare function upsertJsonConfigToken(content: string, token: string): string;
+export declare function upsertShellToken(content: string, token: string, filePath?: string): string;
+export declare function upsertJsonConfigToken(content: string, token: string, filePath?: string): string;
 export declare function readTomlConfigToken(content: string): string | null;
 export declare function upsertTomlConfigToken(content: string, token: string): string;
 export declare function fileExists(filePath: string): boolean;

package/dist/doctor.js

@@ -60,6 +60,13 @@ export function getDefaultShellRcPath() {
         return path.join(os.homedir(), '.config', 'fish', 'config.fish');
     return path.join(os.homedir(), '.zshrc');
 }
+function isFishConfig(filePath) {
+    return filePath.endsWith('config.fish') || filePath.includes('/fish/');
+}
+/** Detect if a JSON config file uses OpenCode's `mcp` format vs standard `mcpServers` */
+function isOpenCodeConfig(filePath) {
+    return filePath.includes('opencode');
+}
 export function getDefaultMcpConfigPaths(cwd = process.cwd()) {
     const home = os.homedir();
     const candidates = [
@@ -83,7 +90,17 @@ export function readTokenFromShellContent(content) {
     const m = content.match(TOKEN_LINE_RE);
     return m?.[3] ?? null;
 }
-export function upsertShellToken(content, token) {
+export function upsertShellToken(content, token, filePath) {
+    if (filePath && isFishConfig(filePath)) {
+        // Fish shell uses `set -gx` instead of `export`
+        const fishLine = `set -gx ${PLAYWRIGHT_TOKEN_ENV} "${token}"`;
+        const fishRe = /^\s*set\s+(-gx\s+)?PLAYWRIGHT_MCP_EXTENSION_TOKEN\s+.*/m;
+        if (!content.trim())
+            return `${fishLine}\n`;
+        if (fishRe.test(content))
+            return content.replace(fishRe, fishLine);
+        return `${content.replace(/\s*$/, '')}\n${fishLine}\n`;
+    }
     const nextLine = `export ${PLAYWRIGHT_TOKEN_ENV}="${token}"`;
     if (!content.trim())
         return `${nextLine}\n`;
@@ -109,17 +126,14 @@ function readTokenFromJsonObject(parsed) {
         return opencode;
     return null;
 }
-export function upsertJsonConfigToken(content, token) {
+export function upsertJsonConfigToken(content, token, filePath) {
     const parsed = content.trim() ? JSON.parse(content) : {};
-    if (parsed?.mcpServers) {
-        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] ?? {
-            command: 'npx',
-            args: ['-y', '@playwright/mcp@latest', '--extension'],
-        };
-        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env ?? {};
-        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
-    }
-    else {
+    // Determine format: use OpenCode format only if explicitly an opencode config,
+    // or if the existing content already uses `mcp` key (not `mcpServers`)
+    const useOpenCodeFormat = filePath
+        ? isOpenCodeConfig(filePath)
+        : (!parsed.mcpServers && parsed.mcp);
+    if (useOpenCodeFormat) {
         parsed.mcp = parsed.mcp ?? {};
         parsed.mcp[PLAYWRIGHT_SERVER_NAME] = parsed.mcp[PLAYWRIGHT_SERVER_NAME] ?? {
             command: ['npx', '-y', '@playwright/mcp@latest', '--extension'],
@@ -129,6 +143,15 @@ export function upsertJsonConfigToken(content, token) {
         parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment = parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment ?? {};
         parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment[PLAYWRIGHT_TOKEN_ENV] = token;
     }
+    else {
+        parsed.mcpServers = parsed.mcpServers ?? {};
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] ?? {
+            command: 'npx',
+            args: ['-y', '@playwright/mcp@latest', '--extension'],
+        };
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env ?? {};
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
+    }
     return `${JSON.stringify(parsed, null, 2)}\n`;
 }
 export function readTomlConfigToken(content) {
@@ -206,6 +229,28 @@ function readConfigStatus(filePath) {
         };
     }
 }
+/**
+ * Dynamically enumerate Chrome profiles by scanning for 'Default' and 'Profile *'
+ * directories across all browser base paths. Falls back to ['Default'] if none found.
+ */
+function enumerateProfiles(baseDirs) {
+    const profiles = new Set();
+    for (const base of baseDirs) {
+        if (!fileExists(base))
+            continue;
+        try {
+            for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                if (entry.name === 'Default' || /^Profile \d+$/.test(entry.name)) {
+                    profiles.add(entry.name);
+                }
+            }
+        }
+        catch { /* permission denied, etc. */ }
+    }
+    return profiles.size > 0 ? [...profiles].sort() : ['Default'];
+}
 /**
  * Discover the auth token stored by the Playwright MCP Bridge extension
  * by scanning Chrome's LevelDB localStorage files directly.
@@ -230,7 +275,7 @@ export function discoverExtensionToken() {
         const appData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
         bases.push(path.join(appData, 'Google', 'Chrome', 'User Data'), path.join(appData, 'Microsoft', 'Edge', 'User Data'));
     }
-    const profiles = ['Default', 'Profile 1', 'Profile 2', 'Profile 3'];
+    const profiles = enumerateProfiles(bases);
     const tokenRe = /([A-Za-z0-9_-]{40,50})/;
     for (const base of bases) {
         for (const profile of profiles) {
@@ -352,7 +397,7 @@ export function checkExtensionInstalled() {
         const appData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
         browserDirs.push({ name: 'Chrome', base: path.join(appData, 'Google', 'Chrome', 'User Data') }, { name: 'Edge', base: path.join(appData, 'Microsoft', 'Edge', 'User Data') });
     }
-    const profiles = ['Default', 'Profile 1', 'Profile 2', 'Profile 3'];
+    const profiles = enumerateProfiles(browserDirs.map(d => d.base));
     const foundBrowsers = [];
     for (const { name, base } of browserDirs) {
         for (const profile of profiles) {
@@ -564,7 +609,7 @@ export async function applyBrowserDoctorFix(report, opts = {}) {
     const written = [];
     if (plannedWrites.includes(shellPath)) {
         const shellBefore = fileExists(shellPath) ? fs.readFileSync(shellPath, 'utf-8') : '';
-        writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token));
+        writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token, shellPath));
         written.push(shellPath);
     }
     for (const config of report.configs) {
@@ -573,7 +618,9 @@ export async function applyBrowserDoctorFix(report, opts = {}) {
         if (config.parseError)
             continue;
         const before = fileExists(config.path) ? fs.readFileSync(config.path, 'utf-8') : '';
-        const next = config.format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+        const next = config.format === 'toml'
+            ? upsertTomlConfigToken(before, token)
+            : upsertJsonConfigToken(before, token, config.path);
         writeFileWithMkdir(config.path, next);
         written.push(config.path);
     }

package/dist/doctor.test.js

@@ -68,6 +68,47 @@ describe('json token helpers', () => {
         const parsed = JSON.parse(next);
         expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
     });
+    it('creates standard mcpServers format for empty file (not OpenCode)', () => {
+        const next = upsertJsonConfigToken('', 'abc123');
+        const parsed = JSON.parse(next);
+        expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+        expect(parsed.mcp).toBeUndefined();
+    });
+    it('creates OpenCode format when filePath contains opencode', () => {
+        const next = upsertJsonConfigToken('', 'abc123', '/home/user/.config/opencode/opencode.json');
+        const parsed = JSON.parse(next);
+        expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+        expect(parsed.mcpServers).toBeUndefined();
+    });
+    it('creates standard format when filePath is claude.json', () => {
+        const next = upsertJsonConfigToken('', 'abc123', '/home/user/.claude.json');
+        const parsed = JSON.parse(next);
+        expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    });
+});
+describe('fish shell support', () => {
+    it('generates fish set -gx syntax for fish config path', () => {
+        const next = upsertShellToken('', 'abc123', '/home/user/.config/fish/config.fish');
+        expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+        expect(next).not.toContain('export');
+    });
+    it('replaces existing fish set line', () => {
+        const content = 'set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "old"\n';
+        const next = upsertShellToken(content, 'new', '/home/user/.config/fish/config.fish');
+        expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "new"');
+        expect(next).not.toContain('"old"');
+    });
+    it('appends fish syntax to existing fish config', () => {
+        const content = 'set -gx PATH /usr/bin\n';
+        const next = upsertShellToken(content, 'abc123', '/home/user/.config/fish/config.fish');
+        expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+        expect(next).toContain('set -gx PATH /usr/bin');
+    });
+    it('uses export syntax for zshrc even with filePath', () => {
+        const next = upsertShellToken('', 'abc123', '/home/user/.zshrc');
+        expect(next).toContain('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="abc123"');
+        expect(next).not.toContain('set -gx');
+    });
 });
 describe('doctor report rendering', () => {
     const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');

package/dist/main.js

@@ -13,11 +13,34 @@ import { render as renderOutput } from './output.js';
 import { PlaywrightMCP } from './browser.js';
 import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
 import { PKG_VERSION } from './version.js';
+import { getCompletions, printCompletionScript } from './completion.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
+// ── Fast-path: handle --get-completions before commander parses ─────────
+// Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
+const getCompIdx = process.argv.indexOf('--get-completions');
+if (getCompIdx !== -1) {
+    const rest = process.argv.slice(getCompIdx + 1);
+    let cursor;
+    const words = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--cursor' && i + 1 < rest.length) {
+            cursor = parseInt(rest[i + 1], 10);
+            i++; // skip the value
+        }
+        else {
+            words.push(rest[i]);
+        }
+    }
+    if (cursor === undefined)
+        cursor = words.length;
+    const candidates = getCompletions(words, cursor);
+    process.stdout.write(candidates.join('\n') + '\n');
+    process.exit(0);
+}
 const program = new Command();
 program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);
 // ── Built-in commands ──────────────────────────────────────────────────────
@@ -130,6 +153,12 @@ program.command('setup')
     const { runSetup } = await import('./setup.js');
     await runSetup({ cliVersion: PKG_VERSION, token: opts.token });
 });
+program.command('completion')
+    .description('Output shell completion script')
+    .argument('<shell>', 'Shell type: bash, zsh, or fish')
+    .action((shell) => {
+    printCompletionScript(shell);
+});
 // ── Dynamic site commands ──────────────────────────────────────────────────
 const registry = getRegistry();
 const siteGroups = new Map();

package/dist/setup.js

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import chalk from 'chalk';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { PLAYWRIGHT_TOKEN_ENV, discoverExtensionToken, fileExists, getDefaultShellRcPath, runBrowserDoctor, shortenPath, toolName, upsertJsonConfigToken, upsertShellToken, upsertTomlConfigToken, writeFileWithMkdir, } from './doctor.js';
+import { PLAYWRIGHT_TOKEN_ENV, checkExtensionInstalled, checkTokenConnectivity, discoverExtensionToken, fileExists, getDefaultShellRcPath, runBrowserDoctor, shortenPath, toolName, upsertJsonConfigToken, upsertShellToken, upsertTomlConfigToken, writeFileWithMkdir, } from './doctor.js';
 import { getTokenFingerprint } from './browser.js';
 import { checkboxPrompt } from './tui.js';
 export async function runSetup(opts = {}) {
@@ -45,11 +45,24 @@ export async function runSetup(opts = {}) {
             chalk.dim(`(${getTokenFingerprint(token)})`));
     }
     if (!token) {
-        console.log(`  ${chalk.yellow('!')} No token found. Please enter it manually.`);
-        console.log(chalk.dim('    (Find it in the Playwright MCP Bridge extension → Status page)'));
+        // Give precise diagnosis of why token scan failed
+        const extInstall = checkExtensionInstalled();
+        console.log(`  ${chalk.red('✗')} Browser token scan failed\n`);
+        if (!extInstall.installed) {
+            console.log(chalk.dim('  Cause: Playwright MCP Bridge extension is not installed'));
+            console.log(chalk.dim('  Fix:   Install from https://chromewebstore.google.com/detail/'));
+            console.log(chalk.dim('         playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm'));
+        }
+        else {
+            console.log(chalk.dim(`  Cause: Extension is installed (${extInstall.browsers.join(', ')}) but token not found in LevelDB`));
+            console.log(chalk.dim('  Fix:   1) Open the extension popup and verify the token is generated'));
+            console.log(chalk.dim('         2) Close Chrome completely, then re-run setup'));
+        }
+        console.log();
+        console.log(`  You can enter the token manually, or fix the above and re-run ${chalk.bold('opencli setup')}.`);
         console.log();
         const rl = createInterface({ input, output });
-        const answer = await rl.question('  Token: ');
+        const answer = await rl.question('  Token (press Enter to abort): ');
         rl.close();
         token = answer.trim();
         if (!token) {
@@ -105,7 +118,7 @@ export async function runSetup(opts = {}) {
         if (sel.startsWith('shell:')) {
             const p = sel.slice('shell:'.length);
             const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
-            writeFileWithMkdir(p, upsertShellToken(before, token));
+            writeFileWithMkdir(p, upsertShellToken(before, token, p));
             written.push(p);
             wroteShell = true;
         }
@@ -116,7 +129,7 @@ export async function runSetup(opts = {}) {
                 continue;
             const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
             const format = config?.format ?? (p.endsWith('.toml') ? 'toml' : 'json');
-            const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+            const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token, p);
             writeFileWithMkdir(p, next);
             written.push(p);
         }
@@ -138,6 +151,22 @@ export async function runSetup(opts = {}) {
         console.log(chalk.yellow('  No files were changed.'));
     }
     console.log();
+    // Step 7: Auto-verify browser connectivity
+    console.log(chalk.dim('  Verifying browser connectivity...'));
+    try {
+        const result = await checkTokenConnectivity({ timeout: 5 });
+        if (result.ok) {
+            console.log(`  ${chalk.green('✓')} Browser connected in ${(result.durationMs / 1000).toFixed(1)}s`);
+        }
+        else {
+            console.log(`  ${chalk.yellow('!')} Browser connectivity test failed: ${result.error ?? 'unknown'}`);
+            console.log(chalk.dim('    Make sure Chrome is running with the extension enabled.'));
+        }
+    }
+    catch {
+        console.log(`  ${chalk.yellow('!')} Could not verify connectivity (Chrome may not be running)`);
+    }
+    console.log();
 }
 function padRight(s, n) {
     const visible = s.replace(/\x1b\[[0-9;]*m/g, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,7 @@
     "clean-yaml": "node -e \"const{readdirSync:r,rmSync:d,existsSync:e,statSync:s}=require('fs'),p=require('path');function w(dir){if(!e(dir))return;for(const f of r(dir)){const fp=p.join(dir,f);s(fp).isDirectory()?w(fp):/\\.ya?ml$/.test(f)&&d(fp)}}w('dist/clis')\"",
     "copy-yaml": "node -e \"const{readdirSync:r,copyFileSync:c,mkdirSync:m,existsSync:e,statSync:s}=require('fs'),p=require('path');function w(src,dst){if(!e(src))return;for(const f of r(src)){const sp=p.join(src,f),dp=p.join(dst,f);s(sp).isDirectory()?w(sp,dp):/\\.ya?ml$/.test(f)&&(m(p.dirname(dp),{recursive:!0}),c(sp,dp))}}w('src/clis','dist/clis')\"",
     "start": "node dist/main.js",
+    "postinstall": "node scripts/postinstall.js || true",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",

package/scripts/postinstall.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * postinstall script — automatically install shell completion files.
+ *
+ * Detects the user's default shell and writes the completion script to the
+ * standard system completion directory so that tab-completion works immediately
+ * after `npm install -g`.
+ *
+ * Supported shells: bash, zsh, fish.
+ *
+ * This script is intentionally plain Node.js (no TypeScript, no imports from
+ * the main source tree) so that it can run without a build step.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+
+// ── Completion script content ──────────────────────────────────────────────
+
+const BASH_COMPLETION = `# Bash completion for opencli (auto-installed)
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`;
+
+const ZSH_COMPLETION = `#compdef opencli
+# Zsh completion for opencli (auto-installed)
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+_opencli
+`;
+
+const FISH_COMPLETION = `# Fish completion for opencli (auto-installed)
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function detectShell() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('bash')) return 'bash';
+  if (shell.includes('fish')) return 'fish';
+  return null;
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Ensure fpath contains the custom completions directory in .zshrc
+ */
+function ensureZshFpath(completionsDir, zshrcPath) {
+  const fpathLine = `fpath=(${completionsDir} $fpath)`;
+  const autoloadLine = `autoload -Uz compinit && compinit`;
+
+  if (!existsSync(zshrcPath)) {
+    writeFileSync(zshrcPath, `${fpathLine}\n${autoloadLine}\n`, 'utf8');
+    return;
+  }
+
+  const content = readFileSync(zshrcPath, 'utf8');
+
+  // Check if completions dir is already in fpath
+  if (content.includes(completionsDir)) {
+    return; // already configured
+  }
+
+  // Append fpath configuration
+  let addition = `\n# opencli completion\n${fpathLine}\n`;
+  if (!content.includes('compinit')) {
+    addition += `${autoloadLine}\n`;
+  }
+  appendFileSync(zshrcPath, addition, 'utf8');
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  // Skip in CI environments
+  if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) {
+    return;
+  }
+
+  // Only install completion for global installs and npm link
+  const isGlobal = process.env.npm_config_global === 'true';
+  if (!isGlobal) {
+    return;
+  }
+
+  const shell = detectShell();
+  if (!shell) {
+    // Cannot determine shell; silently skip
+    return;
+  }
+
+  const home = homedir();
+
+  try {
+    switch (shell) {
+      case 'zsh': {
+        const completionsDir = join(home, '.zsh', 'completions');
+        const completionFile = join(completionsDir, '_opencli');
+        ensureDir(completionsDir);
+        writeFileSync(completionFile, ZSH_COMPLETION, 'utf8');
+
+        // Ensure fpath is set up in .zshrc
+        const zshrcPath = join(home, '.zshrc');
+        ensureZshFpath(completionsDir, zshrcPath);
+
+        console.log(`✓ Zsh completion installed to ${completionFile}`);
+        console.log(`  Restart your shell or run: source ~/.zshrc`);
+        break;
+      }
+      case 'bash': {
+        // Try system-level first, fall back to user-level
+        const userCompDir = join(home, '.bash_completion.d');
+        const completionFile = join(userCompDir, 'opencli');
+        ensureDir(userCompDir);
+        writeFileSync(completionFile, BASH_COMPLETION, 'utf8');
+
+        // Ensure .bashrc sources the completion directory
+        const bashrcPath = join(home, '.bashrc');
+        if (existsSync(bashrcPath)) {
+          const content = readFileSync(bashrcPath, 'utf8');
+          if (!content.includes('.bash_completion.d/opencli')) {
+            appendFileSync(bashrcPath,
+              `\n# opencli completion\n[ -f "${completionFile}" ] && source "${completionFile}"\n`,
+              'utf8'
+            );
+          }
+        }
+
+        console.log(`✓ Bash completion installed to ${completionFile}`);
+        console.log(`  Restart your shell or run: source ~/.bashrc`);
+        break;
+      }
+      case 'fish': {
+        const completionsDir = join(home, '.config', 'fish', 'completions');
+        const completionFile = join(completionsDir, 'opencli.fish');
+        ensureDir(completionsDir);
+        writeFileSync(completionFile, FISH_COMPLETION, 'utf8');
+
+        console.log(`✓ Fish completion installed to ${completionFile}`);
+        console.log(`  Restart your shell to activate.`);
+        break;
+      }
+    }
+  } catch (err) {
+    // Completion install is best-effort; never fail the package install
+    if (process.env.OPENCLI_VERBOSE) {
+      console.error(`Warning: Could not install shell completion: ${err.message}`);
+    }
+  }
+}
+
+main();

package/src/completion.ts

@@ -0,0 +1,129 @@
+/**
+ * Shell tab-completion support for opencli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+
+import { getRegistry } from './registry.js';
+
+// ── Dynamic completion logic ───────────────────────────────────────────────
+
+/**
+ * Built-in (non-dynamic) top-level commands.
+ */
+const BUILTIN_COMMANDS = [
+  'list',
+  'validate',
+  'verify',
+  'explore',
+  'probe',        // alias for explore
+  'synthesize',
+  'generate',
+  'cascade',
+  'doctor',
+  'setup',
+  'completion',
+];
+
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'opencli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export function getCompletions(words: string[], cursor: number): string[] {
+  // cursor === 1 → completing the first argument (site name or built-in command)
+  if (cursor <= 1) {
+    const sites = new Set<string>();
+    for (const [, cmd] of getRegistry()) {
+      sites.add(cmd.site);
+    }
+    return [...BUILTIN_COMMANDS, ...sites].sort();
+  }
+
+  const site = words[0];
+
+  // If the first word is a built-in command, no further completion
+  if (BUILTIN_COMMANDS.includes(site)) {
+    return [];
+  }
+
+  // cursor === 2 → completing the sub-command name under a site
+  if (cursor === 2) {
+    const subcommands: string[] = [];
+    for (const [, cmd] of getRegistry()) {
+      if (cmd.site === site) {
+        subcommands.push(cmd.name);
+      }
+    }
+    return subcommands.sort();
+  }
+
+  // cursor >= 3 → no further completion
+  return [];
+}
+
+// ── Shell script generators ────────────────────────────────────────────────
+
+export function bashCompletionScript(): string {
+  return `# Bash completion for opencli
+# Add to ~/.bashrc:  eval "$(opencli completion bash)"
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`;
+}
+
+export function zshCompletionScript(): string {
+  return `# Zsh completion for opencli
+# Add to ~/.zshrc:  eval "$(opencli completion zsh)"
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+compdef _opencli opencli
+`;
+}
+
+export function fishCompletionScript(): string {
+  return `# Fish completion for opencli
+# Add to ~/.config/fish/config.fish:  opencli completion fish | source
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+}
+
+/**
+ * Print the completion script for the requested shell.
+ */
+export function printCompletionScript(shell: string): void {
+  switch (shell) {
+    case 'bash':
+      process.stdout.write(bashCompletionScript());
+      break;
+    case 'zsh':
+      process.stdout.write(zshCompletionScript());
+      break;
+    case 'fish':
+      process.stdout.write(fishCompletionScript());
+      break;
+    default:
+      console.error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
+      process.exitCode = 1;
+  }
+}

package/src/doctor.test.ts

@@ -83,6 +83,54 @@ describe('json token helpers', () => {
     const parsed = JSON.parse(next);
     expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
   });
+
+  it('creates standard mcpServers format for empty file (not OpenCode)', () => {
+    const next = upsertJsonConfigToken('', 'abc123');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    expect(parsed.mcp).toBeUndefined();
+  });
+
+  it('creates OpenCode format when filePath contains opencode', () => {
+    const next = upsertJsonConfigToken('', 'abc123', '/home/user/.config/opencode/opencode.json');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    expect(parsed.mcpServers).toBeUndefined();
+  });
+
+  it('creates standard format when filePath is claude.json', () => {
+    const next = upsertJsonConfigToken('', 'abc123', '/home/user/.claude.json');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+  });
+});
+
+describe('fish shell support', () => {
+  it('generates fish set -gx syntax for fish config path', () => {
+    const next = upsertShellToken('', 'abc123', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+    expect(next).not.toContain('export');
+  });
+
+  it('replaces existing fish set line', () => {
+    const content = 'set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "old"\n';
+    const next = upsertShellToken(content, 'new', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "new"');
+    expect(next).not.toContain('"old"');
+  });
+
+  it('appends fish syntax to existing fish config', () => {
+    const content = 'set -gx PATH /usr/bin\n';
+    const next = upsertShellToken(content, 'abc123', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+    expect(next).toContain('set -gx PATH /usr/bin');
+  });
+
+  it('uses export syntax for zshrc even with filePath', () => {
+    const next = upsertShellToken('', 'abc123', '/home/user/.zshrc');
+    expect(next).toContain('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="abc123"');
+    expect(next).not.toContain('set -gx');
+  });
 });
 
 describe('doctor report rendering', () => {

package/src/doctor.ts

@@ -111,6 +111,15 @@ export function getDefaultShellRcPath(): string {
   return path.join(os.homedir(), '.zshrc');
 }
 
+function isFishConfig(filePath: string): boolean {
+  return filePath.endsWith('config.fish') || filePath.includes('/fish/');
+}
+
+/** Detect if a JSON config file uses OpenCode's `mcp` format vs standard `mcpServers` */
+function isOpenCodeConfig(filePath: string): boolean {
+  return filePath.includes('opencode');
+}
+
 export function getDefaultMcpConfigPaths(cwd: string = process.cwd()): string[] {
   const home = os.homedir();
   const candidates = [
@@ -136,7 +145,15 @@ export function readTokenFromShellContent(content: string): string | null {
   return m?.[3] ?? null;
 }
 
-export function upsertShellToken(content: string, token: string): string {
+export function upsertShellToken(content: string, token: string, filePath?: string): string {
+  if (filePath && isFishConfig(filePath)) {
+    // Fish shell uses `set -gx` instead of `export`
+    const fishLine = `set -gx ${PLAYWRIGHT_TOKEN_ENV} "${token}"`;
+    const fishRe = /^\s*set\s+(-gx\s+)?PLAYWRIGHT_MCP_EXTENSION_TOKEN\s+.*/m;
+    if (!content.trim()) return `${fishLine}\n`;
+    if (fishRe.test(content)) return content.replace(fishRe, fishLine);
+    return `${content.replace(/\s*$/, '')}\n${fishLine}\n`;
+  }
   const nextLine = `export ${PLAYWRIGHT_TOKEN_ENV}="${token}"`;
   if (!content.trim()) return `${nextLine}\n`;
   if (TOKEN_LINE_RE.test(content)) return content.replace(TOKEN_LINE_RE, `$1"${
@@ -162,16 +179,16 @@ function readTokenFromJsonObject(parsed: any): string | null {
   return null;
 }
 
-export function upsertJsonConfigToken(content: string, token: string): string {
+export function upsertJsonConfigToken(content: string, token: string, filePath?: string): string {
   const parsed = content.trim() ? JSON.parse(content) : {};
-  if (parsed?.mcpServers) {
-    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] ?? {
-      command: 'npx',
-      args: ['-y', '@playwright/mcp@latest', '--extension'],
-    };
-    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env ?? {};
-    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
-  } else {
+
+  // Determine format: use OpenCode format only if explicitly an opencode config,
+  // or if the existing content already uses `mcp` key (not `mcpServers`)
+  const useOpenCodeFormat = filePath
+    ? isOpenCodeConfig(filePath)
+    : (!parsed.mcpServers && parsed.mcp);
+
+  if (useOpenCodeFormat) {
     parsed.mcp = parsed.mcp ?? {};
     parsed.mcp[PLAYWRIGHT_SERVER_NAME] = parsed.mcp[PLAYWRIGHT_SERVER_NAME] ?? {
       command: ['npx', '-y', '@playwright/mcp@latest', '--extension'],
@@ -180,6 +197,14 @@ export function upsertJsonConfigToken(content: string, token: string): string {
     };
     parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment = parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment ?? {};
     parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment[PLAYWRIGHT_TOKEN_ENV] = token;
+  } else {
+    parsed.mcpServers = parsed.mcpServers ?? {};
+    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] ?? {
+      command: 'npx',
+      args: ['-y', '@playwright/mcp@latest', '--extension'],
+    };
+    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env ?? {};
+    parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
   }
   return `${JSON.stringify(parsed, null, 2)}\n`;
 }
@@ -262,6 +287,26 @@ function readConfigStatus(filePath: string): McpConfigStatus {
   }
 }
 
+/**
+ * Dynamically enumerate Chrome profiles by scanning for 'Default' and 'Profile *'
+ * directories across all browser base paths. Falls back to ['Default'] if none found.
+ */
+function enumerateProfiles(baseDirs: string[]): string[] {
+  const profiles = new Set<string>();
+  for (const base of baseDirs) {
+    if (!fileExists(base)) continue;
+    try {
+      for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === 'Default' || /^Profile \d+$/.test(entry.name)) {
+          profiles.add(entry.name);
+        }
+      }
+    } catch { /* permission denied, etc. */ }
+  }
+  return profiles.size > 0 ? [...profiles].sort() : ['Default'];
+}
+
 /**
  * Discover the auth token stored by the Playwright MCP Bridge extension
  * by scanning Chrome's LevelDB localStorage files directly.
@@ -298,7 +343,7 @@ export function discoverExtensionToken(): string | null {
     );
   }
 
-  const profiles = ['Default', 'Profile 1', 'Profile 2', 'Profile 3'];
+  const profiles = enumerateProfiles(bases);
   const tokenRe = /([A-Za-z0-9_-]{40,50})/;
 
   for (const base of bases) {
@@ -424,7 +469,7 @@ export function checkExtensionInstalled(): { installed: boolean; browsers: strin
     );
   }
 
-  const profiles = ['Default', 'Profile 1', 'Profile 2', 'Profile 3'];
+  const profiles = enumerateProfiles(browserDirs.map(d => d.base));
   const foundBrowsers: string[] = [];
 
   for (const { name, base } of browserDirs) {
@@ -643,7 +688,7 @@ export async function applyBrowserDoctorFix(report: DoctorReport, opts: DoctorOp
   const written: string[] = [];
   if (plannedWrites.includes(shellPath)) {
     const shellBefore = fileExists(shellPath) ? fs.readFileSync(shellPath, 'utf-8') : '';
-    writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token));
+    writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token, shellPath));
     written.push(shellPath);
   }
 
@@ -651,7 +696,9 @@ export async function applyBrowserDoctorFix(report: DoctorReport, opts: DoctorOp
     if (!plannedWrites.includes(config.path)) continue;
     if (config.parseError) continue;
     const before = fileExists(config.path) ? fs.readFileSync(config.path, 'utf-8') : '';
-    const next = config.format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+    const next = config.format === 'toml'
+      ? upsertTomlConfigToken(before, token)
+      : upsertJsonConfigToken(before, token, config.path);
     writeFileWithMkdir(config.path, next);
     written.push(config.path);
   }

package/src/main.ts

@@ -14,6 +14,7 @@ import { render as renderOutput } from './output.js';
 import { PlaywrightMCP } from './browser.js';
 import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
 import { PKG_VERSION } from './version.js';
+import { getCompletions, printCompletionScript } from './completion.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -22,6 +23,27 @@ const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 
+// ── Fast-path: handle --get-completions before commander parses ─────────
+// Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
+const getCompIdx = process.argv.indexOf('--get-completions');
+if (getCompIdx !== -1) {
+  const rest = process.argv.slice(getCompIdx + 1);
+  let cursor: number | undefined;
+  const words: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--cursor' && i + 1 < rest.length) {
+      cursor = parseInt(rest[i + 1], 10);
+      i++; // skip the value
+    } else {
+      words.push(rest[i]);
+    }
+  }
+  if (cursor === undefined) cursor = words.length;
+  const candidates = getCompletions(words, cursor);
+  process.stdout.write(candidates.join('\n') + '\n');
+  process.exit(0);
+}
+
 const program = new Command();
 program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);
 
@@ -128,6 +150,13 @@ program.command('setup')
     await runSetup({ cliVersion: PKG_VERSION, token: opts.token });
   });
 
+program.command('completion')
+  .description('Output shell completion script')
+  .argument('<shell>', 'Shell type: bash, zsh, or fish')
+  .action((shell) => {
+    printCompletionScript(shell);
+  });
+
 // ── Dynamic site commands ──────────────────────────────────────────────────
 
 const registry = getRegistry();

package/src/setup.ts

@@ -11,6 +11,8 @@ import { stdin as input, stdout as output } from 'node:process';
 import {
   type DoctorReport,
   PLAYWRIGHT_TOKEN_ENV,
+  checkExtensionInstalled,
+  checkTokenConnectivity,
   discoverExtensionToken,
   fileExists,
   getDefaultShellRcPath,
@@ -60,11 +62,24 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
   }
 
   if (!token) {
-    console.log(`  ${chalk.yellow('!')} No token found. Please enter it manually.`);
-    console.log(chalk.dim('    (Find it in the Playwright MCP Bridge extension → Status page)'));
+    // Give precise diagnosis of why token scan failed
+    const extInstall = checkExtensionInstalled();
+
+    console.log(`  ${chalk.red('✗')} Browser token scan failed\n`);
+    if (!extInstall.installed) {
+      console.log(chalk.dim('  Cause: Playwright MCP Bridge extension is not installed'));
+      console.log(chalk.dim('  Fix:   Install from https://chromewebstore.google.com/detail/'));
+      console.log(chalk.dim('         playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm'));
+    } else {
+      console.log(chalk.dim(`  Cause: Extension is installed (${extInstall.browsers.join(', ')}) but token not found in LevelDB`));
+      console.log(chalk.dim('  Fix:   1) Open the extension popup and verify the token is generated'));
+      console.log(chalk.dim('         2) Close Chrome completely, then re-run setup'));
+    }
+    console.log();
+    console.log(`  You can enter the token manually, or fix the above and re-run ${chalk.bold('opencli setup')}.`);
     console.log();
     const rl = createInterface({ input, output });
-    const answer = await rl.question('  Token: ');
+    const answer = await rl.question('  Token (press Enter to abort): ');
     rl.close();
     token = answer.trim();
     if (!token) {
@@ -129,7 +144,7 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
     if (sel.startsWith('shell:')) {
       const p = sel.slice('shell:'.length);
       const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
-      writeFileWithMkdir(p, upsertShellToken(before, token));
+      writeFileWithMkdir(p, upsertShellToken(before, token, p));
       written.push(p);
       wroteShell = true;
     } else if (sel.startsWith('config:')) {
@@ -138,7 +153,7 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
       if (config && config.parseError) continue;
       const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
       const format = config?.format ?? (p.endsWith('.toml') ? 'toml' : 'json');
-      const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+      const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token, p);
       writeFileWithMkdir(p, next);
       written.push(p);
     }
@@ -161,6 +176,21 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
     console.log(chalk.yellow('  No files were changed.'));
   }
   console.log();
+
+  // Step 7: Auto-verify browser connectivity
+  console.log(chalk.dim('  Verifying browser connectivity...'));
+  try {
+    const result = await checkTokenConnectivity({ timeout: 5 });
+    if (result.ok) {
+      console.log(`  ${chalk.green('✓')} Browser connected in ${(result.durationMs / 1000).toFixed(1)}s`);
+    } else {
+      console.log(`  ${chalk.yellow('!')} Browser connectivity test failed: ${result.error ?? 'unknown'}`);
+      console.log(chalk.dim('    Make sure Chrome is running with the extension enabled.'));
+    }
+  } catch {
+    console.log(`  ${chalk.yellow('!')} Could not verify connectivity (Chrome may not be running)`);
+  }
+  console.log();
 }
 
 function padRight(s: string, n: number): string {