@hiai-gg/hiai-opencode 0.1.3 → 0.1.4

package/README.md

@@ -60,7 +60,7 @@ Minimum:
 
 Usually required:
 
-- `OPENROUTER_API_KEY` if you use the default model presets
+- at least one model provider connected in OpenCode for the model IDs you configure
 
 Optional, depending on which services you want:
 
@@ -73,19 +73,21 @@ Optional, depending on which services you want:
 
 ## Install
 
-Recommended native OpenCode install:
+### 1. Register the OpenCode plugin
 
 ```bash
 opencode plugin @hiai-gg/hiai-opencode@latest --global
 ```
 
-Optional DCP plugin:
+Optional Dynamic Context Pruning plugin:
 
 ```bash
 opencode plugin @tarquinen/opencode-dcp@latest --global
 ```
 
-Manual config alternative:
+Do not put MCP server packages such as `firecrawl-mcp`, `@playwright/mcp`, or `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. `hiai-opencode` only provides the OpenCode-side launch wiring for them through its `mcp` config and helper launchers.
+
+Manual OpenCode config equivalent:
 
 ```json
 {
@@ -94,107 +96,87 @@ Manual config alternative:
 }
 ```
 
-Then start OpenCode:
+The packaged minimal OpenCode example lives in [config/opencode.json](config/opencode.json).
 
-```bash
-opencode
-```
+### 2. Create project config
 
-Direct npm install is only needed for development or inspection:
+Create a project-level config file at `hiai-opencode.json` in the project root or at `.opencode/hiai-opencode.json`.
 
-```bash
-npm install @hiai-gg/hiai-opencode
-```
-
-For local development:
+Bash:
 
 ```bash
-git clone https://github.com/HiAi-gg/hiai-opencode.git
-cd hiai-opencode
-bun install
-bun run build
+mkdir -p .opencode
+cp hiai-opencode.json .opencode/hiai-opencode.json
 ```
 
-## Register The Plugin In OpenCode
-
-Use the OpenCode plugin CLI:
+PowerShell:
 
-```bash
-opencode plugin @hiai-gg/hiai-opencode@latest --global
+```powershell
+New-Item -ItemType Directory -Force .opencode
+Copy-Item .\hiai-opencode.json .\.opencode\hiai-opencode.json
 ```
 
-If you also want Dynamic Context Pruning, install its separate plugin next:
-
-```bash
-opencode plugin @tarquinen/opencode-dcp@latest --global
-```
-
-If you prefer manual config, add the plugin package to your OpenCode config. OpenCode installs npm plugins automatically at startup.
+If you installed only from npm/OpenCode and do not have this repository checked out, create `.opencode/hiai-opencode.json` with the service block below and adjust it later.
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@hiai-gg/hiai-opencode"]
+  "mcp": {
+    "playwright": { "enabled": true },
+    "sequential-thinking": { "enabled": true },
+    "firecrawl": { "enabled": true },
+    "mempalace": { "enabled": true },
+    "rag": { "enabled": false },
+    "stitch": { "enabled": false },
+    "context7": { "enabled": true }
+  }
 }
 ```
 
-The packaged minimal example lives in [config/opencode.json](config/opencode.json).
+By default, skill discovery is deterministic: `hiai-opencode` skills plus project-local `.opencode/skills` only. Global Claude/OpenCode/Agents skill folders are opt-in.
 
-The richer example config lives in [hiai-opencode.json](hiai-opencode.json).
+### 3. Connect models and add service keys
 
-Do not put MCP server packages such as `firecrawl-mcp`, `@playwright/mcp`, or `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. `hiai-opencode` only provides the OpenCode-side launch wiring for them through its `mcp` config and helper launchers.
+Model provider credentials belong to OpenCode Connect, not to `hiai-opencode`.
+This plugin only writes model IDs such as `openrouter/anthropic/claude-3.5-sonnet` into agent and category config.
 
-## Quick Start
+Use OpenCode Connect to authorize the providers behind your configured model IDs. Then add only the service keys for MCP or search integrations you actually use:
 
 ```bash
-git clone https://github.com/HiAi-gg/hiai-opencode.git
-cd hiai-opencode
-bun install
-bun run build
+export FIRECRAWL_API_KEY=...
+export STITCH_AI_API_KEY=...
+export CONTEXT7_API_KEY=...
 ```
 
-Register the plugin in OpenCode:
-
-```bash
-opencode plugin @hiai-gg/hiai-opencode@latest --global
-```
+See [Environment Variables And Keys](#environment-variables-and-keys) for the full list.
 
-Optional:
+### 4. Start and verify
 
 ```bash
-opencode plugin @tarquinen/opencode-dcp@latest --global
+opencode
+hiai-opencode mcp-status
+opencode debug config
+opencode mcp list --print-logs --log-level INFO
 ```
 
-Manual equivalent:
+`opencode mcp list` may not show plugin-provided MCP servers in every OpenCode version. If that happens, use `opencode debug config` and startup logs as the source of truth.
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@hiai-gg/hiai-opencode"]
-}
-```
+`hiai-opencode mcp-status` is the fastest visibility check. It does not change OpenCode config; it reports config location, enabled MCP services, missing keys, and basic local runtime availability.
 
-Project-level service config goes in `hiai-opencode.json` at the project root or under `.opencode/`:
+## Development Install
 
-```json
-{
-  "mcp": {
-    "playwright": { "enabled": true },
-    "sequential-thinking": { "enabled": true },
-    "firecrawl": { "enabled": true },
-    "mempalace": { "enabled": true },
-    "rag": { "enabled": false },
-    "stitch": { "enabled": false },
-    "context7": { "enabled": true }
-  }
-}
+Direct npm install is only needed for development or inspection:
+
+```bash
+npm install @hiai-gg/hiai-opencode
 ```
 
-Then verify:
+Local development:
 
 ```bash
-opencode debug config
-opencode mcp list --print-logs --log-level INFO
+git clone https://github.com/HiAi-gg/hiai-opencode.git
+cd hiai-opencode
+bun install
+bun run build
 ```
 
 ## Post-Install Bootstrap Prompt
@@ -210,6 +192,8 @@ Check that @hiai-gg/hiai-opencode is registered. If Dynamic Context Pruning is r
 
 Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp object as the single switchboard for enabling or disabling MCP services.
 
+Keep skill discovery deterministic unless I explicitly ask for external skills. Leave global_opencode, project_claude, global_claude, project_agents, and global_agents disabled by default.
+
 Enable only services that can run on this machine:
 - playwright: requires node/npx; optionally set HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1 before first run if browser binaries are needed.
 - sequential-thinking: requires node/npx.
@@ -232,21 +216,17 @@ If a dependency is missing, install only user-level or project-local dependencie
 
 ### Models
 
-Model presets and role guidance:
+Canonical runtime defaults for agents, categories, MCP, LSP, and model IDs:
 
-- [src/config/models.ts](src/config/models.ts)
+- [hiai-opencode.json](hiai-opencode.json)
 
-Runtime defaults for agents, categories, MCP, LSP:
+Runtime loader for the bundled canonical config:
 
 - [src/config/defaults.ts](src/config/defaults.ts)
 
-User-facing example config:
-
-- [hiai-opencode.json](hiai-opencode.json)
-
-If you want to change which model a specific agent uses by default, edit `src/config/defaults.ts`.
+If you want to change which model a specific agent or category uses by default, edit `hiai-opencode.json`.
 
-If you want to change the shared preset values like `fast`, `mid`, `high`, `vision`, or `reasoning`, edit `src/config/models.ts`.
+Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast`, `sonnet`, `fast`, or `high`.
 
 ### Prompting
 
@@ -281,6 +261,24 @@ Skill materialization logic:
 
 - [src/features/builtin-skills/materialize.ts](src/features/builtin-skills/materialize.ts)
 
+Skill discovery defaults:
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": true,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+This keeps clean installs reproducible and avoids accidentally mixing Codex, Claude, Antigravity, and global OpenCode skill collections. To opt into external skill folders, enable the specific source you want instead of turning everything on.
+
 ### MCP
 
 Default MCP registry:
@@ -304,21 +302,23 @@ LSP defaults are defined in:
 
 ## Environment Variables And Keys
 
-Important keys:
+Model provider keys are handled by OpenCode Connect. Do not add `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY` to `hiai-opencode` config for normal model usage.
+
+Important service variables:
 
-- `OPENROUTER_API_KEY`
-- `OPENAI_API_KEY`
-- `ANTHROPIC_API_KEY`
-- `DEEPSEEK_API_KEY`
-- `GLM_API_KEY`
-- `MINIMAX_API_KEY`
-- `QWEN_API_KEY`
 - `STITCH_AI_API_KEY`
 - `FIRECRAWL_API_KEY`
 - `CONTEXT7_API_KEY`
+- `GOOGLE_SEARCH_API_KEY`
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
 - `MEMPALACE_PYTHON`
+- `MEMPALACE_PALACE_PATH`
+- `OPENCODE_RAG_URL`
+- `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
+- `HIAI_MCP_AUTO_INSTALL`
+
+Optional headless or non-Connect fallback variables are documented in [.env.example](.env.example), but they are not required for normal OpenCode model auth.
 
 Use [.env.example](.env.example) as the reference template. Create a local `.env` in your OpenCode environment or export these variables in your shell before startup.
 
@@ -350,19 +350,40 @@ The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that
 - `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.
 - `firecrawl`: launches `firecrawl-mcp` through the helper npm runner and requires `FIRECRAWL_API_KEY`.
 
-### Needs upstream runtime or extra setup
+### Playwright On Minimal Linux Hosts
 
-- `mempalace`: prefers `uv`; otherwise uses Python. If `HIAI_MCP_AUTO_INSTALL` is not `0`, `false`, or `no`, the launcher can run `python -m pip install --user mempalace` on first start.
-- `rag`: requires your own running endpoint
+`hiai-opencode mcp-status` can confirm that the Playwright MCP launcher is available, but it cannot guarantee that Chromium can start on a minimal Linux image.
 
-### Additional OpenCode Plugin
+Playwright has two dependency layers:
 
-`opencode-dcp` is a separate OpenCode plugin, not an MCP server:
+- Browser binary: install with `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` before OpenCode starts, or run `npx playwright install chromium`.
+- System libraries: if Chromium errors with missing packages like `libnspr4`, `libnss3`, `libatk-bridge`, or `libgtk-3`, install them with admin rights, usually `sudo npx playwright install-deps chromium`.
 
-```bash
-opencode plugin @tarquinen/opencode-dcp@latest --global
+If sudo is not available:
+
+- Use an already installed system browser by editing the Playwright command in `.opencode/hiai-opencode.json`, for example:
+
+```json
+{
+  "mcp": {
+    "playwright": {
+      "enabled": true,
+      "command": ["node", "{pluginRoot}/assets/mcp/playwright.mjs", "--browser", "chrome"],
+      "timeout": 600000
+    }
+  }
+}
 ```
 
+- Try `--browser msedge` if Edge is installed.
+- Use a remote/CDP browser or the `agent-browser`/`playwright-cli` skill path if those tools are installed.
+- Use `curl` only as a degraded HTTP check. It does not replace browser interaction, screenshots, auth flows, or client-side app verification.
+
+### Needs upstream runtime or extra setup
+
+- `mempalace`: prefers `uv`; otherwise uses Python. If `HIAI_MCP_AUTO_INSTALL` is not `0`, `false`, or `no`, the launcher can run `python -m pip install --user mempalace` on first start.
+- `rag`: requires your own running endpoint
+
 ### Important Windows note
 
 On some Windows/OpenCode environments, local MCP process spawning can fail with `EPERM` for `cmd` or `node`. If you see that:
@@ -372,6 +393,68 @@ On some Windows/OpenCode environments, local MCP process spawning can fail with
 
 This most often affects `sequential-thinking` and `mempalace`, and sometimes local `npx`-backed tools.
 
+## Diagnostics
+
+The plugin now emits startup warnings for common misconfiguration, including:
+
+- `.opencode/opencode.json` containing `plugin: ["list"]`
+- enabled MCP integrations with missing required env vars such as `FIRECRAWL_API_KEY` or `STITCH_AI_API_KEY`
+
+Available CLI:
+
+```bash
+hiai-opencode mcp-status
+```
+
+Inside OpenCode, use the slash command:
+
+```text
+/mcp-status
+```
+
+Example output:
+
+```text
+MCP Servers:
+✅ playwright           - backend ok
+⚠️  rag                 - enabled, http://localhost:9002/tools/search not reachable
+✅ firecrawl            - backend ok
+❌ mempalace            - python not found
+⚠️  stitch              - enabled, API key missing (STITCH_AI_API_KEY)
+```
+
+Planned follow-up commands:
+
+- `hiai-opencode doctor`: report config location, MCP status, missing keys, and local dependency checks.
+- `hiai-opencode export-mcp`: generate a standard `.mcp.json` for hosts that do not expose plugin-provided MCP servers through `opencode mcp list`.
+
+Until those commands ship, use:
+
+```bash
+opencode debug config
+opencode mcp list --print-logs --log-level INFO
+```
+
+## Core Components And Upstream Projects
+
+`hiai-opencode` wires these projects and ideas into an OpenCode-friendly setup. Upstream projects remain independent; this table is attribution and orientation, not an ownership claim.
+
+| Component | Upstream | Notes |
+|---|---|---|
+| OpenCode host/runtime | [anomalyco/opencode](https://github.com/anomalyco/opencode) | plugin host and runtime target |
+| Core orchestration influences | [code-yeongyu/oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) | architectural influence |
+| Planning / workflow influences | [obra/superpowers](https://github.com/obra/superpowers) | planning, review, and debugging ideas |
+| Specialist / platform influences | [vtemian/micode](https://github.com/vtemian/micode) | platform-style specialist behavior |
+| Agent skill ecosystem | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | tactical workflow skill ideas |
+| Optional external plugin | [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) | installed separately |
+| MemPalace | [MemPalace/mempalace](https://github.com/MemPalace/mempalace) | external MCP/runtime |
+| Playwright MCP | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | external MCP |
+| Sequential Thinking | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | external MCP |
+| Firecrawl MCP | [firecrawl-ai/firecrawl-mcp-server](https://github.com/firecrawl-ai/firecrawl-mcp-server) | external MCP |
+| Context7 MCP | [upstash/context7-mcp](https://github.com/upstash/context7-mcp) | external MCP |
+| Websearch cited | [ghoulr/opencode-websearch-cited](https://github.com/ghoulr/opencode-websearch-cited) | search integration influence |
+| bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
+
 ## Build And Publish
 
 Build:

package/assets/cli/hiai-opencode.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import { parse } from "jsonc-parser"
+
+const DEFAULT_RAG_URL = "http://localhost:9002/tools/search"
+
+const MCP_REGISTRY = {
+  playwright: {
+    defaultEnabled: true,
+    requiredEnv: [],
+    check: checkNodeNpx,
+  },
+  rag: {
+    defaultEnabled: true,
+    requiredEnv: [],
+    check: checkRag,
+  },
+  firecrawl: {
+    defaultEnabled: true,
+    requiredEnv: ["FIRECRAWL_API_KEY"],
+    authFallback: "firecrawl",
+    check: checkNodeNpx,
+  },
+  mempalace: {
+    defaultEnabled: true,
+    requiredEnv: [],
+    check: checkMempalace,
+  },
+  stitch: {
+    defaultEnabled: true,
+    requiredEnv: ["STITCH_AI_API_KEY"],
+    authFallback: "stitch",
+    check: checkRemoteKeyOnly,
+  },
+  context7: {
+    defaultEnabled: true,
+    requiredEnv: [],
+    check: checkRemoteOptionalKey,
+  },
+  "sequential-thinking": {
+    defaultEnabled: true,
+    requiredEnv: [],
+    check: checkNodeNpx,
+  },
+}
+
+function usage() {
+  console.log(`hiai-opencode
+
+Usage:
+  hiai-opencode mcp-status
+
+Commands:
+  mcp-status   Check hiai-opencode MCP configuration, keys, and local runtimes.
+`)
+}
+
+function resolveEnvTemplate(value) {
+  if (typeof value !== "string") return value
+  return value.replace(/\{env:([^}]+)\}/g, (_match, expression) => {
+    const [name, fallback] = String(expression).split(":-", 2)
+    return process.env[name] || fallback || ""
+  })
+}
+
+function candidateConfigPaths() {
+  const cwd = process.cwd()
+  const paths = [
+    join(cwd, "hiai-opencode.json"),
+    join(cwd, "hiai-opencode.jsonc"),
+    join(cwd, ".opencode", "hiai-opencode.json"),
+    join(cwd, ".opencode", "hiai-opencode.jsonc"),
+    join(homedir(), ".config", "opencode", "hiai-opencode.json"),
+    join(homedir(), ".config", "opencode", "hiai-opencode.jsonc"),
+  ]
+
+  if (process.platform === "win32" && process.env.APPDATA) {
+    paths.push(join(process.env.APPDATA, "opencode", "hiai-opencode.json"))
+    paths.push(join(process.env.APPDATA, "opencode", "hiai-opencode.jsonc"))
+  }
+
+  return paths
+}
+
+function loadConfig() {
+  for (const path of candidateConfigPaths()) {
+    if (!existsSync(path)) continue
+    try {
+      return {
+        path,
+        config: parse(readFileSync(path, "utf-8")) ?? {},
+      }
+    } catch (error) {
+      return {
+        path,
+        config: {},
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  return { path: null, config: {} }
+}
+
+function hasCommand(command, args = ["--version"]) {
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+    timeout: 10000,
+    shell: process.platform === "win32",
+  })
+  return result.status === 0
+}
+
+function hasNode() {
+  return hasCommand(process.platform === "win32" ? "node.exe" : "node")
+}
+
+function hasNpx() {
+  return hasCommand(process.platform === "win32" ? "npx.cmd" : "npx")
+}
+
+function checkNodeNpx() {
+  const node = hasNode()
+  const npx = hasNpx()
+  if (node && npx) return { level: "ok", detail: "backend ok" }
+  return {
+    level: "error",
+    detail: `${node ? "node ok" : "node not found"}, ${npx ? "npx ok" : "npx not found"}`,
+  }
+}
+
+function pythonCandidates() {
+  const configured = process.env.MEMPALACE_PYTHON?.trim()
+  const candidates = []
+  if (configured) candidates.push(configured)
+  if (process.platform === "win32") {
+    candidates.push("py", "python", "python3")
+  } else {
+    candidates.push("python3", "python")
+  }
+  return [...new Set(candidates)]
+}
+
+function canImportMempalace(command) {
+  const args =
+    command === "py"
+      ? ["-3", "-c", "import mempalace.mcp_server"]
+      : ["-c", "import mempalace.mcp_server"]
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+    timeout: 10000,
+    shell: process.platform === "win32",
+  })
+  return result.status === 0
+}
+
+function checkMempalace() {
+  if (hasCommand(process.platform === "win32" ? "uv.exe" : "uv")) {
+    return { level: "ok", detail: "uv available" }
+  }
+
+  for (const candidate of pythonCandidates()) {
+    if (canImportMempalace(candidate)) {
+      return { level: "ok", detail: `${candidate} with mempalace available` }
+    }
+  }
+
+  const hasPython = pythonCandidates().some((candidate) =>
+    hasCommand(candidate, candidate === "py" ? ["-3", "--version"] : ["--version"]),
+  )
+
+  return {
+    level: "error",
+    detail: hasPython ? "mempalace Python package not found" : "python not found",
+  }
+}
+
+async function checkRag(config) {
+  const url =
+    process.env.OPENCODE_RAG_URL?.trim()
+    || resolveEnvTemplate(config?.mcp?.rag?.environment?.OPENCODE_RAG_URL)
+    || DEFAULT_RAG_URL
+
+  try {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 2500)
+    const response = await fetch(url, { method: "GET", signal: controller.signal })
+    clearTimeout(timeout)
+
+    if (response.status < 500) {
+      return { level: "ok", detail: `enabled, ${url} reachable` }
+    }
+    return { level: "warn", detail: `enabled, ${url} returned ${response.status}` }
+  } catch {
+    return { level: "warn", detail: `enabled, ${url} not reachable` }
+  }
+}
+
+function checkRemoteKeyOnly() {
+  return { level: "ok", detail: "remote endpoint configured" }
+}
+
+function checkRemoteOptionalKey(_config, name) {
+  if (name === "context7" && !process.env.CONTEXT7_API_KEY?.trim()) {
+    return { level: "ok", detail: "remote endpoint configured, API key optional/missing" }
+  }
+  return { level: "ok", detail: "remote endpoint configured" }
+}
+
+function hasEnvOrAuth(config, envName, authKey) {
+  if (process.env[envName]?.trim()) return true
+  if (authKey && config?.auth?.[authKey]?.trim()) return true
+  return false
+}
+
+function statusIcon(level) {
+  if (level === "ok") return "✅"
+  if (level === "warn") return "⚠️ "
+  return "❌"
+}
+
+async function mcpStatus() {
+  const { path, config, error } = loadConfig()
+  console.log("hiai-opencode mcp-status")
+  console.log(`Config: ${path ?? "not found; using defaults"}`)
+  if (error) console.log(`Config parse warning: ${error}`)
+  console.log("")
+  console.log("MCP Servers:")
+
+  for (const [name, entry] of Object.entries(MCP_REGISTRY)) {
+    const userEntry = config?.mcp?.[name]
+    const enabled = userEntry?.enabled ?? entry.defaultEnabled
+    if (!enabled) {
+      console.log(`⚪ ${name.padEnd(20)} - disabled`)
+      continue
+    }
+
+    const missingEnv = entry.requiredEnv.filter((envName) =>
+      !hasEnvOrAuth(config, envName, entry.authFallback),
+    )
+
+    if (missingEnv.length > 0) {
+      console.log(`⚠️  ${name.padEnd(20)} - enabled, API key missing (${missingEnv.join(", ")})`)
+      continue
+    }
+
+    const result = await entry.check(config, name)
+    console.log(`${statusIcon(result.level)} ${name.padEnd(20)} - ${result.detail}`)
+  }
+}
+
+async function main() {
+  const command = process.argv[2]
+  if (!command || command === "-h" || command === "--help") {
+    usage()
+    return
+  }
+
+  if (command === "mcp-status") {
+    await mcpStatus()
+    return
+  }
+
+  console.error(`Unknown command: ${command}`)
+  usage()
+  process.exit(1)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/assets/mcp/playwright.mjs

@@ -42,6 +42,13 @@ if (shouldInstallBrowsers()) {
   const result = runNpx(["-y", "playwright@latest", "install", "chromium"])
   if (result.status !== 0) {
     console.error("[hiai-opencode] playwright browser install failed")
+    console.error("[hiai-opencode] Try: npx playwright install chromium")
+  }
+
+  if (process.platform === "linux") {
+    console.error("[hiai-opencode] Playwright Chromium may also need Linux system libraries.")
+    console.error("[hiai-opencode] If browser launch fails with libnspr4/libnss3/libgtk errors, run: sudo npx playwright install-deps chromium")
+    console.error("[hiai-opencode] Without sudo, use an existing browser by adding args in hiai-opencode.json, e.g. --browser chrome")
   }
 }