@hiai-gg/hiai-opencode 0.1.4 → 0.1.6

package/.env.example

@@ -11,14 +11,7 @@
 # - anthropic/claude-3-5-sonnet-latest
 #
 # Do not put model provider keys here for normal OpenCode usage.
-# Optional fallback only for headless/non-Connect workflows:
-# OPENROUTER_API_KEY=your_openrouter_api_key_here
-# OPENAI_API_KEY=your_openai_api_key_here
-# ANTHROPIC_API_KEY=your_anthropic_api_key_here
-# DEEPSEEK_API_KEY=your_deepseek_api_key_here
-# GLM_API_KEY=your_glm_api_key_here
-# MINIMAX_API_KEY=your_minimax_api_key_here
-# QWEN_API_KEY=your_qwen_api_key_here
+# Connect model providers in OpenCode itself.
 
 # MCP Service Keys
 
@@ -58,6 +51,19 @@
 # Optional - if Linux system browser deps cannot be installed, edit hiai-opencode.json
 # and add Playwright MCP args such as "--browser", "chrome" to use an existing browser.
 
+# Static MCP export
+
+# Optional - controls automatic .mcp.json export when the plugin loads.
+# Values: if-missing (default), always (managed files only), force, 0/false/no/off.
+# HIAI_OPENCODE_AUTO_EXPORT_MCP=if-missing
+
+# Optional - override static MCP export path.
+# HIAI_OPENCODE_MCP_EXPORT_PATH=./.mcp.json
+
+# Optional - CLI export safety mode.
+# Values: safe (default), force
+# HIAI_OPENCODE_EXPORT_MCP_MODE=safe
+
 # RAG MCP
 
 # Optional - RAG search tool endpoint

package/AGENTS.md

@@ -66,9 +66,14 @@ Manual alternative:
 
 ```bash
 opencode debug config
+hiai-opencode doctor
+hiai-opencode mcp-status
+hiai-opencode export-mcp .mcp.json
 opencode mcp list --print-logs --log-level INFO
 ```
 
+`opencode mcp list` reads static `.mcp.json` files in many OpenCode versions. Runtime MCP servers launched by the plugin may work but not appear there until a static config exists. The plugin auto-exports `.mcp.json` on startup when missing. In `always` mode it overwrites only hiai-managed exports unless forced. `hiai-opencode export-mcp .mcp.json` can refresh it manually.
+
 ## Post-Install Bootstrap Instructions
 
 When a user asks OpenCode or another agent to finish installing this plugin, follow this procedure.
@@ -110,13 +115,15 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
    - `FIRECRAWL_API_KEY`
    - `STITCH_AI_API_KEY`
    - `CONTEXT7_API_KEY`
-   - `GOOGLE_SEARCH_API_KEY`
    - `MEMPALACE_PYTHON`
    - `OPENCODE_RAG_URL`
    - `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
    - `HIAI_MCP_AUTO_INSTALL`
 7. Verify with:
    - `opencode debug config`
+   - `hiai-opencode doctor`
+   - `hiai-opencode mcp-status`
+   - `hiai-opencode export-mcp .mcp.json` when static MCP visibility is needed
    - `opencode mcp list --print-logs --log-level INFO`
 
 ### MCP Setup Matrix
@@ -126,7 +133,7 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
 | `playwright` | Node and npx are available | Helper launcher runs `@playwright/mcp@latest`; set `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` to install Chromium on first start |
 | `sequential-thinking` | Node and npx are available | Helper launcher runs `@modelcontextprotocol/server-sequential-thinking` |
 | `firecrawl` | `FIRECRAWL_API_KEY` is set | Helper launcher runs `firecrawl-mcp` |
-| `mempalace` | `uv` is available, or Python 3.9+ with pip is available | Launcher prefers `uv`; otherwise uses Python and can run `python -m pip install --user mempalace` when `HIAI_MCP_AUTO_INSTALL` is not disabled |
+| `mempalace` | `uv` is available, or Python 3.9+ with pip is available | Launcher prefers `uv`; otherwise uses Python and can run `python -m pip install --user mempalace` when `HIAI_MCP_AUTO_INSTALL` is not disabled. Interpreter can be pinned via `mcp.mempalace.pythonPath` or `MEMPALACE_PYTHON` |
 | `rag` | User has a local or remote RAG endpoint | Uses `OPENCODE_RAG_URL`, defaulting to `http://localhost:9002/tools/search` |
 | `stitch` | `STITCH_AI_API_KEY` is set | Remote MCP endpoint |
 | `context7` | User wants Context7 docs/search | Remote MCP endpoint; use `CONTEXT7_API_KEY` if available |
@@ -155,14 +162,14 @@ Check which services can run here:
 - playwright: node/npx; optionally HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1.
 - sequential-thinking: node/npx.
 - firecrawl: FIRECRAWL_API_KEY.
-- mempalace: uv or Python 3.9+ with pip; MEMPALACE_PYTHON if needed; HIAI_MCP_AUTO_INSTALL controls first-run pip install.
+- mempalace: uv or Python 3.9+ with pip; set `mcp.mempalace.pythonPath` (or `MEMPALACE_PYTHON`) if needed; `HIAI_MCP_AUTO_INSTALL` controls first-run pip install.
 - rag: OPENCODE_RAG_URL or http://localhost:9002/tools/search.
 - stitch: STITCH_AI_API_KEY.
 - context7: optional CONTEXT7_API_KEY.
 
 Report missing keys without printing secret values. Never invent or hardcode API keys.
 
-Run opencode debug config and opencode mcp list --print-logs --log-level INFO if available. If something is missing, propose or run only user-level/project-local install commands.
+Run hiai-opencode mcp-status and opencode debug config. If the user wants opencode mcp list visibility, run hiai-opencode export-mcp .mcp.json before opencode mcp list --print-logs --log-level INFO. If something is missing, propose or run only user-level/project-local install commands.
 ```
 
 ## Expected Agent State
@@ -213,6 +220,8 @@ The runtime loader is:
 
 - [src/config/defaults.ts](src/config/defaults.ts)
 
+Users configure only the 10 primary agent model slots under `models`: `bob`, `coder`, `strategist`, `guard`, `critic`, `designer`, `researcher`, `manager`, `brainstormer`, and `vision`.
+Hidden agents and task categories are derived internally in `src/config/defaults.ts`.
 Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast`, `sonnet`, `fast`, or `high`.
 
 ## Change Map
@@ -221,9 +230,9 @@ Use this table when you need to change something and want the right file immedia
 
 | Goal | Edit this first | Why |
 |---|---|---|
-| Change which default model an agent uses | [hiai-opencode.json](hiai-opencode.json) | This is the canonical model source |
-| Change which default model a category uses | [hiai-opencode.json](hiai-opencode.json) | Categories are assigned there |
-| Change MCP/LSP/user-facing defaults | [hiai-opencode.json](hiai-opencode.json) | The runtime loader reads this file |
+| Change a user-facing default model slot | [hiai-opencode.json](hiai-opencode.json) | This is the canonical model source |
+| Change how categories inherit the 10 model slots | [src/config/defaults.ts](src/config/defaults.ts) | Category routing is internal |
+| Change MCP/LSP user-facing switches | [hiai-opencode.json](hiai-opencode.json) | Users only toggle enabled state there |
 | Change Bob behavior or prompt text | [src/agents/bob.ts](src/agents/bob.ts), `src/agents/bob/*` | Bob prompt authoring lives there |
 | Change Coder behavior or prompt text | `src/agents/coder/*` | Coder prompt authoring lives there |
 | Change Strategist behavior or prompt text | `src/agents/strategist/*` | Strategist prompt authoring lives there |
@@ -395,7 +404,6 @@ Common service keys:
 - `STITCH_AI_API_KEY`
 - `FIRECRAWL_API_KEY`
 - `CONTEXT7_API_KEY`
-- `GOOGLE_SEARCH_API_KEY`
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
 - `MEMPALACE_PYTHON`
@@ -403,6 +411,9 @@ Common service keys:
 - `OPENCODE_RAG_URL`
 - `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
 - `HIAI_MCP_AUTO_INSTALL`
+- `HIAI_OPENCODE_AUTO_EXPORT_MCP`
+- `HIAI_OPENCODE_MCP_EXPORT_PATH`
+- `HIAI_OPENCODE_EXPORT_MCP_MODE`
 
 ## Known Runtime Caveats
 

package/ARCHITECTURE.md

@@ -62,20 +62,20 @@ Runtime naming, visibility, and compatibility are normalized through:
 
 ### Presets
 
-Agent and category model IDs live in one place:
+User-facing model IDs live in one place:
 
 - [hiai-opencode.json](hiai-opencode.json)
 
 ### Runtime Defaults
 
-The TypeScript defaults loader only reads the bundled canonical config:
+The TypeScript defaults loader derives hidden agents and categories from the 10 user-facing model slots:
 
 - [src/config/defaults.ts](src/config/defaults.ts)
 
-This is the runtime source of truth for:
+This is the internal routing source for:
 
-- agent models
-- category models
+- hidden agent model inheritance
+- category model inheritance
 - MCP defaults
 - LSP defaults
 - permissions
@@ -158,7 +158,8 @@ If a prompt change looks correct in source but does not show up correctly in Ope
 
 Use these rules when editing the prompt layer:
 
-- change `hiai-opencode.json` when any default model assignment should change
+- change `hiai-opencode.json` when any primary agent model slot should change
+- change `src/config/defaults.ts` when internal category-to-agent-slot routing should change
 - change `src/agents/*` when the prompt content or behavior should change
 - change shared prompt/injection files when the prompt is being appended or normalized after agent construction
 - change `src/plugin-handlers/agent-config-handler.ts` when runtime name, visibility, mode, or final description should change

package/LICENSE.md

@@ -31,7 +31,6 @@ Some are:
 | 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 |
 
 ## What Is Bundled vs External

package/README.md

@@ -31,7 +31,7 @@ Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages
 
 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.
+Then run `hiai-opencode doctor`, `hiai-opencode mcp-status`, and `opencode debug config`.
 ```
 
 For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖
@@ -116,15 +116,27 @@ 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.
+If you installed only from npm/OpenCode and do not have this repository checked out, create `.opencode/hiai-opencode.json` with the shape below and adjust it later.
 
 ```json
 {
+  "models": {
+    "bob": { "model": "openrouter/moonshotai/kimi-k2.6", "recommended": "xhigh" },
+    "coder": { "model": "openrouter/minimax/minimax-m2.7", "recommended": "high" },
+    "strategist": { "model": "openrouter/anthropic/claude-opus-latest", "recommended": "high" },
+    "guard": { "model": "openrouter/qwen/qwen3.6-plus", "recommended": "middle" },
+    "critic": { "model": "openrouter/xiaomi/mimo-v2.5-pro", "recommended": "high" },
+    "designer": { "model": "openrouter/google/gemini-3.1-pro-preview", "recommended": "design" },
+    "researcher": { "model": "openrouter/deepseek/deepseek-v4-flash", "recommended": "fast" },
+    "manager": { "model": "openrouter/qwen/qwen3.5-9b", "recommended": "fast" },
+    "brainstormer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
+    "vision": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
+  },
   "mcp": {
     "playwright": { "enabled": true },
     "sequential-thinking": { "enabled": true },
     "firecrawl": { "enabled": true },
-    "mempalace": { "enabled": true },
+    "mempalace": { "enabled": true, "pythonPath": "{env:MEMPALACE_PYTHON:-./.venv/bin/python}" },
     "rag": { "enabled": false },
     "stitch": { "enabled": false },
     "context7": { "enabled": true }
@@ -137,7 +149,7 @@ By default, skill discovery is deterministic: `hiai-opencode` skills plus projec
 ### 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.
+This plugin only reads the 10 model IDs in `models`. Internal routing derives hidden agents and task categories from those 10 choices.
 
 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:
 
@@ -153,15 +165,19 @@ See [Environment Variables And Keys](#environment-variables-and-keys) for the fu
 
 ```bash
 opencode
+hiai-opencode doctor
 hiai-opencode mcp-status
+hiai-opencode export-mcp .mcp.json
 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.
+`opencode mcp list` reads static `.mcp.json` files in many OpenCode versions. Runtime MCP servers launched by plugins may work but not appear there. If you want `opencode mcp list` visibility, run `hiai-opencode export-mcp .mcp.json` first.
 
 `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.
 
+`hiai-opencode doctor` is the broader install/runtime diagnostic. It includes MCP status, static `.mcp.json` freshness, OpenCode Connect visibility, skill materialization, agent naming/count checks, LSP runtime checks, MemPalace Python source selection, and real MCP tool probes.
+
 ## Development Install
 
 Direct npm install is only needed for development or inspection:
@@ -198,7 +214,7 @@ 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.
+- mempalace: requires uv or Python 3.9+ with pip; set `mcp.mempalace.pythonPath` (or `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.
@@ -207,6 +223,8 @@ Check .env.example, report missing keys without printing secret values, and neve
 
 Run verification commands where available:
 - opencode debug config
+- hiai-opencode mcp-status
+- hiai-opencode export-mcp .mcp.json
 - 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.
@@ -216,7 +234,7 @@ If a dependency is missing, install only user-level or project-local dependencie
 
 ### Models
 
-Canonical runtime defaults for agents, categories, MCP, LSP, and model IDs:
+Canonical user-facing config for 10 primary agent models, MCP/LSP switches, service auth placeholders, and skill discovery:
 
 - [hiai-opencode.json](hiai-opencode.json)
 
@@ -224,7 +242,7 @@ Runtime loader for the bundled canonical config:
 
 - [src/config/defaults.ts](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 model selection, edit the 10 entries in `models`. Do not add category-specific model choices unless you are intentionally developing the plugin internals.
 
 Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast`, `sonnet`, `fast`, or `high`.
 
@@ -309,7 +327,6 @@ Important service variables:
 - `STITCH_AI_API_KEY`
 - `FIRECRAWL_API_KEY`
 - `CONTEXT7_API_KEY`
-- `GOOGLE_SEARCH_API_KEY`
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
 - `MEMPALACE_PYTHON`
@@ -317,6 +334,8 @@ Important service variables:
 - `OPENCODE_RAG_URL`
 - `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
 - `HIAI_MCP_AUTO_INSTALL`
+- `HIAI_OPENCODE_AUTO_EXPORT_MCP`
+- `HIAI_OPENCODE_MCP_EXPORT_PATH`
 
 Optional headless or non-Connect fallback variables are documented in [.env.example](.env.example), but they are not required for normal OpenCode model auth.
 
@@ -381,7 +400,7 @@ If sudo is not available:
 
 ### 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.
+- `mempalace`: prefers `uv`; otherwise uses Python. You can force interpreter selection via `mcp.mempalace.pythonPath` or `MEMPALACE_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
@@ -403,12 +422,26 @@ The plugin now emits startup warnings for common misconfiguration, including:
 Available CLI:
 
 ```bash
+hiai-opencode doctor
 hiai-opencode mcp-status
+hiai-opencode export-mcp .mcp.json
+```
+
+By default, the plugin auto-exports `.mcp.json` at workspace startup when the file is missing. This closes the visibility gap where runtime plugin MCP works but `opencode mcp list` only reads static files. Control it with:
+
+```bash
+export HIAI_OPENCODE_AUTO_EXPORT_MCP=if-missing  # default
+export HIAI_OPENCODE_AUTO_EXPORT_MCP=always      # overwrite only managed hiai-opencode exports
+export HIAI_OPENCODE_AUTO_EXPORT_MCP=force       # force overwrite even non-managed files
+export HIAI_OPENCODE_AUTO_EXPORT_MCP=0           # disable auto-export
+export HIAI_OPENCODE_MCP_EXPORT_PATH=.mcp.json   # override path
+export HIAI_OPENCODE_EXPORT_MCP_MODE=safe        # export-mcp command mode: safe|force
 ```
 
 Inside OpenCode, use the slash command:
 
 ```text
+/doctor
 /mcp-status
 ```
 
@@ -423,14 +456,13 @@ MCP Servers:
 ⚠️  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`.
+`hiai-opencode export-mcp` writes a standard `.mcp.json` so hosts whose `mcp list` ignores plugin runtime MCP can still show the same servers statically. Exports are marker-tagged as hiai-managed; by default, the command avoids overwriting non-managed files unless `HIAI_OPENCODE_EXPORT_MCP_MODE=force` is set.
 
-Until those commands ship, use:
+Use:
 
 ```bash
+hiai-opencode mcp-status
+hiai-opencode export-mcp .mcp.json
 opencode debug config
 opencode mcp list --print-logs --log-level INFO
 ```
@@ -452,7 +484,6 @@ opencode mcp list --print-logs --log-level INFO
 | 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
@@ -480,7 +511,7 @@ Before publishing:
 1. run `bun run build`
 2. run `npm pack --dry-run`
 3. verify `debug config`
-4. verify `mcp list`
+4. run `hiai-opencode export-mcp .mcp.json` if you need static `mcp list` visibility
 
 Publish: