@hiai-gg/hiai-opencode 0.1.2 → 0.1.4

package/README.md

@@ -1,14 +1,40 @@
 # hiai-opencode
 
-`hiai-opencode` is an OpenCode plugin that bundles:
+`hiai-opencode` is an OpenCode plugin that wires together:
 
 - a curated multi-agent runtime
-- project and built-in skills
+- project and OpenCode skills
 - MCP integrations
 - LSP defaults
 - migration and compatibility wiring
 
 This repository is intended to be usable by someone who clones it from GitHub without any internal context.
+The external MCP servers, skills, model providers, and auxiliary OpenCode plugins remain their own upstream projects; this plugin only provides OpenCode wiring, defaults, prompts, launchers, and documentation around them.
+
+## Why This Exists
+
+I wanted the "one install, give me the whole cockpit" setup. More agents, more MCP servers, more skills, better defaults, fewer tiny config islands. 🚀
+
+The problem: all those great tools do not magically become friends just because you installed them. Some are npm packages, some are Python tools, some need API keys, some need a local service, and some only wake up after the first run. Meanwhile your main agent can waste half the context window just reading everything you bolted on. Not chill. 😅
+
+So `hiai-opencode` is my attempt to wire the best pieces I use into one OpenCode-friendly shape: agents, prompts, skills, MCP launchers, LSP defaults, and a clean config surface. It does not claim ownership of the upstream tools. It just tries to make them cooperate.
+
+After the first install, a few MCP services may still need local dependencies or keys. You have two options:
+
+- Follow the setup sections below: [Install](#install), [Environment](#environment), and [MCP Service Notes](#mcp-service-notes).
+- Or ask OpenCode to do the boring part for you. Paste this after installing:
+
+```text
+Read AGENTS.md and finish hiai-opencode setup for this workspace.
+
+Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages to the OpenCode plugin list.
+
+Check which MCP services can run on this machine, update hiai-opencode.json, install only missing user-level or project-local dependencies, and report missing API keys without printing secret values.
+
+Then run opencode debug config and opencode mcp list --print-logs --log-level INFO if available.
+```
+
+For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖
 
 ## What You Get
 
@@ -20,7 +46,7 @@ This repository is intended to be usable by someone who clones it from GitHub wi
   - `deep`, `ultrabrain`, `visual-engineering`, `artistry`, and `unspecified-high` are the deep Coder contour
   - `Critic` and `Researcher` are selected explicitly
   - `Designer`, `Brainstormer`, `Manager`, and `Vision` are direct callable specialists
-- Built-in skill materialization into OpenCode's `skills/` view
+- Skill materialization into OpenCode's `skills/` view
 - MCP wiring for `playwright`, `stitch`, `sequential-thinking`, `firecrawl`, `rag`, `mempalace`, `context7`, plus remote `websearch` and `grep_app`
 - LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint
 
@@ -34,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:
 
@@ -47,9 +73,21 @@ Optional, depending on which services you want:
 
 ## Install
 
-Recommended native OpenCode install, once published:
+### 1. Register the OpenCode plugin
 
-Add the npm package to your OpenCode config. OpenCode installs npm plugins automatically at startup.
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Optional Dynamic Context Pruning plugin:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
+
+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
 {
@@ -58,19 +96,81 @@ Add the npm package to your OpenCode config. OpenCode installs npm plugins autom
 }
 ```
 
-Then start OpenCode:
+The packaged minimal OpenCode example lives in [config/opencode.json](config/opencode.json).
+
+### 2. Create project config
+
+Create a project-level config file at `hiai-opencode.json` in the project root or at `.opencode/hiai-opencode.json`.
+
+Bash:
+
+```bash
+mkdir -p .opencode
+cp hiai-opencode.json .opencode/hiai-opencode.json
+```
+
+PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force .opencode
+Copy-Item .\hiai-opencode.json .\.opencode\hiai-opencode.json
+```
+
+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
+{
+  "mcp": {
+    "playwright": { "enabled": true },
+    "sequential-thinking": { "enabled": true },
+    "firecrawl": { "enabled": true },
+    "mempalace": { "enabled": true },
+    "rag": { "enabled": false },
+    "stitch": { "enabled": false },
+    "context7": { "enabled": true }
+  }
+}
+```
+
+By default, skill discovery is deterministic: `hiai-opencode` skills plus project-local `.opencode/skills` only. Global Claude/OpenCode/Agents skill folders are opt-in.
+
+### 3. Connect models and add service keys
+
+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.
+
+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
+export FIRECRAWL_API_KEY=...
+export STITCH_AI_API_KEY=...
+export CONTEXT7_API_KEY=...
+```
+
+See [Environment Variables And Keys](#environment-variables-and-keys) for the full list.
+
+### 4. Start and verify
 
 ```bash
 opencode
+hiai-opencode mcp-status
+opencode debug config
+opencode mcp list --print-logs --log-level INFO
 ```
 
+`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.
+
+`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.
+
+## Development Install
+
 Direct npm install is only needed for development or inspection:
 
 ```bash
 npm install @hiai-gg/hiai-opencode
 ```
 
-For local development:
+Local development:
 
 ```bash
 git clone https://github.com/HiAi-gg/hiai-opencode.git
@@ -79,65 +179,54 @@ bun install
 bun run build
 ```
 
-## Register The Plugin In OpenCode
+## Post-Install Bootstrap Prompt
 
-Add this to your OpenCode config:
+After installing the plugin, you can ask OpenCode to finish local setup with this prompt:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@hiai-gg/hiai-opencode"]
-}
-```
+```text
+Inspect this OpenCode workspace and finish hiai-opencode setup.
 
-The packaged minimal example lives in [config/opencode.json](config/opencode.json).
+Do not add MCP server packages to the OpenCode plugin list. Keep OpenCode plugins separate from MCP servers.
 
-The richer example config lives in [hiai-opencode.json](hiai-opencode.json).
+Check that @hiai-gg/hiai-opencode is registered. If Dynamic Context Pruning is requested, install @tarquinen/opencode-dcp as a separate OpenCode plugin.
 
-## Quick Start
+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.
 
-```bash
-git clone https://github.com/HiAi-gg/hiai-opencode.git
-cd hiai-opencode
-bun install
-bun run build
-```
+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.
 
-Register the plugin in OpenCode:
+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.
+- firecrawl: requires FIRECRAWL_API_KEY.
+- mempalace: requires uv or Python 3.9+ with pip; set MEMPALACE_PYTHON if needed. Leave HIAI_MCP_AUTO_INSTALL enabled unless the user forbids package installation.
+- rag: requires OPENCODE_RAG_URL or a running local endpoint at http://localhost:9002/tools/search.
+- stitch: requires STITCH_AI_API_KEY.
+- context7: works without a key but use CONTEXT7_API_KEY if available.
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@hiai-gg/hiai-opencode"]
-}
-```
+Check .env.example, report missing keys without printing secret values, and never invent or hardcode API keys.
 
-Then verify:
+Run verification commands where available:
+- opencode debug config
+- opencode mcp list --print-logs --log-level INFO
 
-```bash
-opencode debug config
-opencode mcp list --print-logs --log-level INFO
+If a dependency is missing, install only user-level or project-local dependencies, explain every command before running it, and do not use sudo/admin rights unless the user explicitly asks.
 ```
 
 ## Where To Change Things
 
 ### 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:
+If you want to change which model a specific agent or category uses by default, edit `hiai-opencode.json`.
 
-- [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 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
 
@@ -164,21 +253,39 @@ Name mapping and visibility:
 
 ### Skills
 
-Packaged project skills live under:
+Project skill definitions live under:
 
 - [skills](skills)
 
-Built-in skill materialization logic:
+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 definitions:
+Default MCP registry:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback MCP assembly:
+OpenCode MCP config assembly:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 
@@ -195,26 +302,41 @@ 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.
 
 ## MCP Service Notes
 
+The user-facing MCP switchboard is the `mcp` object in `hiai-opencode.json`:
+
+```json
+{
+  "mcp": {
+    "playwright": { "enabled": true },
+    "mempalace": { "enabled": false }
+  }
+}
+```
+
+The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that file when adding a new MCP integration or changing its launch command, required env vars, or install strategy.
+
 ### Works well as remote MCP
 
 - `stitch`
@@ -224,14 +346,43 @@ Use [.env.example](.env.example) as the reference template. Create a local `.env
 
 ### Works with local helper bootstrap
 
-- `playwright`
+- `playwright`: launches `@playwright/mcp@latest` through the helper npm runner. Set `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` if you want the launcher to install Chromium on first start.
+- `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`.
+
+### Playwright On Minimal Linux Hosts
+
+`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.
+
+Playwright has two dependency layers:
+
+- 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`.
+
+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`: requires `uv` or Python with `mempalace` installed
-- `firecrawl`: requires `FIRECRAWL_API_KEY`
+- `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
-- `sequential-thinking`: uses upstream stdio launch
 
 ### Important Windows note
 
@@ -242,16 +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.
 
-## Optional External Plugin
+## Diagnostics
+
+The plugin now emits startup warnings for common misconfiguration, including:
 
-`opencode-dcp` is intentionally not bundled.
+- `.opencode/opencode.json` containing `plugin: ["list"]`
+- enabled MCP integrations with missing required env vars such as `FIRECRAWL_API_KEY` or `STITCH_AI_API_KEY`
 
-Install it separately if you want it:
+Available CLI:
 
 ```bash
-opencode plugin @tarquinen/opencode-dcp@latest --global
+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: