@hiai-gg/hiai-opencode 0.1.2 → 0.1.4

package/.env.example

@@ -2,29 +2,22 @@
 # Copy this file to .env and fill in your values.
 # All keys are optional unless noted.
 
-# Core Model Provider (REQUIRED for default presets)
-
-# Required if using OpenRouter (the default provider for most agents)
-OPENROUTER_API_KEY=your_openrouter_api_key_here
-
-# Alternative Direct Provider Keys
-
-# Optional - needed only if using OpenAI models directly (not via OpenRouter)
+# Model Provider Credentials
+#
+# Configure model provider credentials with OpenCode Connect.
+# hiai-opencode only stores model IDs such as:
+# - openrouter/anthropic/claude-3.5-sonnet
+# - openai/gpt-4.1
+# - 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
-
-# Optional - needed only if using Anthropic models directly (not via OpenRouter)
 # ANTHROPIC_API_KEY=your_anthropic_api_key_here
-
-# Optional - DeepSeek models
 # DEEPSEEK_API_KEY=your_deepseek_api_key_here
-
-# Optional - GLM models via OpenRouter
 # GLM_API_KEY=your_glm_api_key_here
-
-# Optional - MiniMax models via OpenRouter
 # MINIMAX_API_KEY=your_minimax_api_key_here
-
-# Optional - Qwen models via OpenRouter
 # QWEN_API_KEY=your_qwen_api_key_here
 
 # MCP Service Keys
@@ -32,7 +25,7 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # Optional - Stitch AI remote MCP service
 # STITCH_AI_API_KEY=your_stitch_api_key_here
 
-# Optional - Firecrawl web scraping MCP (npx -y firecrawl-mcp)
+# Optional - Firecrawl web scraping MCP
 # FIRECRAWL_API_KEY=your_firecrawl_api_key_here
 
 # Optional - Context7 code search MCP
@@ -51,7 +44,21 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # Optional - Python command for MemPalace MCP (python3, python, or full path)
 # MEMPALACE_PYTHON=python3
 
+# Optional - custom MemPalace data directory
+# MEMPALACE_PALACE_PATH=./.opencode/palace
+
+# Optional - set to 0, false, or no to prevent first-run Python package install
+# HIAI_MCP_AUTO_INSTALL=1
+
+# Playwright MCP
+
+# Optional - set to 1, true, or yes to install Chromium during launcher startup
+# HIAI_PLAYWRIGHT_INSTALL_BROWSERS=0
+
+# 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.
+
 # RAG MCP
 
-# Optional - RAG endpoint URL (default: http://localhost:9002)
-# RAG_ENDPOINT=http://localhost:9002
+# Optional - RAG search tool endpoint
+# OPENCODE_RAG_URL=http://localhost:9002/tools/search

package/AGENTS.md

@@ -4,7 +4,9 @@ This file is for autonomous agents or tooling that need to install, configure, v
 
 ## Purpose
 
-`hiai-opencode` is an OpenCode plugin repository published as `@hiai-gg/hiai-opencode`. It is not a standalone app. The normal workflow is:
+`hiai-opencode` is an OpenCode plugin repository published as `@hiai-gg/hiai-opencode`. It is not a standalone app. It wires OpenCode agents, prompts, skills, MCP server launch commands, LSP defaults, and compatibility behavior around external upstream tools. Do not describe MCP servers, skills, model providers, or auxiliary OpenCode plugins as owned by this repository.
+
+The normal workflow is:
 
 1. install it through OpenCode or build it locally
 2. register `@hiai-gg/hiai-opencode` in OpenCode
@@ -15,7 +17,19 @@ This file is for autonomous agents or tooling that need to install, configure, v
 
 ### Native OpenCode Install
 
-Add the package name to OpenCode config. OpenCode installs npm plugins automatically at startup.
+Use the OpenCode plugin CLI:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Optional Dynamic Context Pruning plugin:
+
+```bash
+opencode plugin @tarquinen/opencode-dcp@latest --global
+```
+
+Manual alternative:
 
 ```json
 {
@@ -33,7 +47,13 @@ bun run build
 
 ### Register In OpenCode
 
-Add this to OpenCode config:
+Use the plugin CLI:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+```
+
+Manual alternative:
 
 ```json
 {
@@ -49,6 +69,102 @@ opencode debug config
 opencode mcp list --print-logs --log-level INFO
 ```
 
+## Post-Install Bootstrap Instructions
+
+When a user asks OpenCode or another agent to finish installing this plugin, follow this procedure.
+
+### Operating Rules
+
+- Keep OpenCode plugins separate from MCP servers.
+- Register `@hiai-gg/hiai-opencode` as an OpenCode plugin.
+- Register `@tarquinen/opencode-dcp` only when the user wants Dynamic Context Pruning; it is a separate OpenCode plugin.
+- Do not add MCP server npm packages to the OpenCode `plugin` array.
+- Use `hiai-opencode.json` as the project-level service switchboard.
+- Use `src/mcp/registry.ts` as the source of truth for default MCP launch wiring.
+- Keep skill discovery deterministic by default: packaged plugin skills, generated builtin skills, explicit config sources, and project `.opencode/skills`.
+- Do not enable global OpenCode, Claude, or Agents skill folders unless the user explicitly asks.
+- Use `.env.example` as the key template, but never print, invent, commit, or hardcode secret values.
+- Prefer user-level or project-local installs. Do not use sudo/admin rights unless the user explicitly asks.
+
+### Bootstrap Checklist
+
+1. Check tool availability:
+   - `opencode --version`
+   - `node --version`
+   - `npx --version`
+   - `bun --version`
+   - `python --version` or `python3 --version`
+   - `uv --version` when available
+2. Check plugin registration with `opencode debug config`.
+3. Find or create `hiai-opencode.json` in the project root or `.opencode/`.
+4. Configure the `mcp` object there. Disable services that cannot run on the host.
+5. Keep `skill_discovery` clean unless the user opts into external folders:
+   - `config_sources: true`
+   - `project_opencode: true`
+   - `global_opencode: false`
+   - `project_claude: false`
+   - `global_claude: false`
+   - `project_agents: false`
+   - `global_agents: false`
+6. Check environment variables without printing values:
+   - `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`
+   - `opencode mcp list --print-logs --log-level INFO`
+
+### MCP Setup Matrix
+
+| Service | Enable when | Dependency behavior |
+|---|---|---|
+| `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 |
+| `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 |
+
+Playwright troubleshooting rules:
+
+- If `skill_mcp` says `MCP server "playwright" not found`, first load the `playwright` skill and check `hiai-opencode mcp-status`; do not report this as a browser dependency failure.
+- If Chromium reports missing Linux libraries (`libnspr4`, `libnss3`, `libatk-bridge`, `libgtk-3`, etc.), explain that MCP is present but the host lacks browser system dependencies.
+- Without sudo, try a system browser override in `hiai-opencode.json`, such as `--browser chrome` or `--browser msedge`.
+- If no browser path works, use `curl` only as degraded HTTP verification and explicitly say it is not a replacement for browser testing.
+
+### Prompt For OpenCode Users
+
+Users can paste this into OpenCode after installing the plugin:
+
+```text
+Finish hiai-opencode setup in this workspace.
+
+Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages to the OpenCode plugin list.
+
+Verify @hiai-gg/hiai-opencode is registered. If I ask for Dynamic Context Pruning, install @tarquinen/opencode-dcp as a separate OpenCode plugin.
+
+Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp object as the only switchboard for MCP enable/disable.
+
+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.
+- 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.
+```
+
 ## Expected Agent State
 
 Visible primary agents:
@@ -89,18 +205,15 @@ If runtime output differs from that set, inspect:
 
 ## Model Configuration
 
-There are two sources of truth:
+There is one source of truth for model IDs:
 
-1. shared presets and guidance:
-   - [src/config/models.ts](src/config/models.ts)
-2. actual runtime defaults:
-   - [src/config/defaults.ts](src/config/defaults.ts)
+- [hiai-opencode.json](hiai-opencode.json)
 
-The example override file is:
+The runtime loader is:
 
-- [hiai-opencode.json](hiai-opencode.json)
+- [src/config/defaults.ts](src/config/defaults.ts)
 
-Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast` or `sonnet`.
+Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast`, `sonnet`, `fast`, or `high`.
 
 ## Change Map
 
@@ -108,10 +221,9 @@ Use this table when you need to change something and want the right file immedia
 
 | Goal | Edit this first | Why |
 |---|---|---|
-| Change shared preset values like `fast`, `mid`, `high`, `vision`, `reasoning` | [src/config/models.ts](src/config/models.ts) | This is the shared preset map |
-| Change which default model an agent uses | [src/config/defaults.ts](src/config/defaults.ts) | This is the runtime default assignment layer |
-| Change which default model a category uses | [src/config/defaults.ts](src/config/defaults.ts) | Categories are assigned there |
-| Change provider/model guidance shown to maintainers | [src/config/models.ts](src/config/models.ts) | That file holds provider rules and role guidance |
+| 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 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 |
@@ -129,8 +241,10 @@ Use this table when you need to change something and want the right file immedia
 | Change closure protocol appended to prompts | [src/shared/closure-protocol.ts](src/shared/closure-protocol.ts) | It is injected after prompt construction |
 | Change prompt override / prompt_append behavior | `src/agents/builtin-agents/agent-overrides.ts` | Override merge logic lives there |
 | Change environment context appended to prompts | `src/agents/builtin-agents/environment-context.ts` | Runtime environment prompt injection lives there |
-| Change MCP defaults | [src/config/defaults.ts](src/config/defaults.ts) | Default MCP definitions live there |
-| Change fallback packaged MCP behavior | [src/mcp/index.ts](src/mcp/index.ts) | Packaged MCP assembly lives there |
+| Change skill discovery source defaults | [src/config/schema/skill-discovery.ts](src/config/schema/skill-discovery.ts), [src/plugin/skill-discovery-config.ts](src/plugin/skill-discovery-config.ts) | Controls opt-in external skill folders |
+| Change skill source loading behavior | [src/plugin/skill-context.ts](src/plugin/skill-context.ts), [src/plugin-handlers/command-config-handler.ts](src/plugin-handlers/command-config-handler.ts) | Skills and skill-backed commands must stay aligned |
+| Change MCP defaults | [src/mcp/registry.ts](src/mcp/registry.ts) | Default MCP wiring lives there |
+| Change OpenCode MCP assembly | [src/mcp/index.ts](src/mcp/index.ts) | Final MCP config assembly lives there |
 | Change local MCP helper launcher logic | `assets/mcp/*` | Runtime launcher scripts live there |
 | Change npm bootstrap behavior for MCP/LSP tools | [assets/runtime/npm-package-runner.mjs](assets/runtime/npm-package-runner.mjs) | Shared npm bootstrap logic lives there |
 | Change LSP defaults | [src/config/defaults.ts](src/config/defaults.ts) | LSP defaults live there |
@@ -204,11 +318,11 @@ So:
 
 ## MCP Rules
 
-Default MCP definitions live in:
+Default MCP wiring lives in:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback/packaged MCP assembly lives in:
+OpenCode MCP config assembly lives in:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 
@@ -229,25 +343,66 @@ Current MCP set:
 - `websearch`
 - `grep_app`
 
+## Skill Discovery Rules
+
+Default behavior is intentionally deterministic.
+
+Enabled by default:
+
+- packaged `hiai-opencode` skill definitions mirrored into OpenCode's skill view
+- generated builtin helper skills
+- explicit `skills.sources` entries
+- project-local `.opencode/skills` and `.opencode/skill`
+
+Disabled by default:
+
+- global OpenCode skills
+- project and global Claude skills
+- project and global Agents skills
+
+Opt-in example:
+
+```json
+{
+  "skill_discovery": {
+    "global_opencode": true,
+    "project_claude": true,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+Use `skills.disable` for noisy individual skills:
+
+```json
+{
+  "skills": {
+    "disable": ["claude-md-management"]
+  }
+}
+```
+
 ## Environment Variables
 
 Use [.env.example](.env.example) as the canonical key template for local setup and release checks.
 
-Common keys:
+Model provider credentials are configured through OpenCode Connect. Do not ask users to put `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY` into `hiai-opencode.json` for normal model usage. The plugin stores model IDs only.
+
+Common service keys:
 
-- `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`
 
 ## Known Runtime Caveats
 

package/ARCHITECTURE.md

@@ -14,7 +14,7 @@ The plugin has five main layers:
 
 ## Repository Layout
 
-- [src/config](src/config): schemas, types, model presets, default wiring
+- [src/config](src/config): schemas, types, and bundled config loading
 - [src/agents](src/agents): agent factories, prompts, and prompt helpers
 - [src/plugin-handlers](src/plugin-handlers): runtime config assembly into OpenCode shape
 - [src/features](src/features): loaders, materializers, bridges, and supporting runtime features
@@ -62,19 +62,13 @@ Runtime naming, visibility, and compatibility are normalized through:
 
 ### Presets
 
-Shared presets and provider guidance live in:
+Agent and category model IDs live in one place:
 
-- [src/config/models.ts](src/config/models.ts)
-
-This file defines:
-
-- `MODEL_PRESETS`
-- `MODEL_ROLE_GUIDE`
-- `PROVIDER_MODEL_RULES`
+- [hiai-opencode.json](hiai-opencode.json)
 
 ### Runtime Defaults
 
-Actual default agent/category assignments live in:
+The TypeScript defaults loader only reads the bundled canonical config:
 
 - [src/config/defaults.ts](src/config/defaults.ts)
 
@@ -164,8 +158,7 @@ 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 `src/config/models.ts` when the preset map itself should change
-- change `src/config/defaults.ts` when default model assignment should change
+- change `hiai-opencode.json` when any default model assignment 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
@@ -187,25 +180,29 @@ The final runtime prompt can also be affected by:
 
 ## Skills
 
-Two skill sources are combined:
+Two skill sources are wired into OpenCode:
 
-- project skills shipped in [skills](skills)
-- built-in skills materialized into the OpenCode-visible skill tree
+- project skill definitions in [skills](skills)
+- skill materialization into the OpenCode-visible skill tree
 
 Relevant files:
 
 - [src/features/builtin-skills/materialize.ts](src/features/builtin-skills/materialize.ts)
 - [src/features/opencode-skill-loader](src/features/opencode-skill-loader)
+- [src/config/schema/skill-discovery.ts](src/config/schema/skill-discovery.ts)
+- [src/plugin/skill-discovery-config.ts](src/plugin/skill-discovery-config.ts)
+
+Default discovery is deterministic: packaged plugin skills, generated builtin skills, explicit config sources, and project `.opencode/skills`. Global OpenCode, Claude, and Agents skill folders are opt-in.
 
 ## MCP
 
 ### Definitions
 
-Default MCP definitions are in:
+Default MCP wiring is in:
 
-- [src/config/defaults.ts](src/config/defaults.ts)
+- [src/mcp/registry.ts](src/mcp/registry.ts)
 
-Fallback assembly for packaged MCP support is in:
+OpenCode MCP config assembly is in:
 
 - [src/mcp/index.ts](src/mcp/index.ts)
 
@@ -273,8 +270,8 @@ Avoid adding more root docs unless they serve a genuinely new role.
 
 When changing the plugin, keep these invariants:
 
-- `src/config/defaults.ts` is the runtime source of truth for defaults
-- `src/config/models.ts` is the source of truth for shared model presets and provider guidance
+- `hiai-opencode.json` is the source of truth for user-facing runtime defaults and model IDs
+- `src/config/defaults.ts` must remain a loader, not a second model map
 - root docs should use canonical runtime names, not stale internal aliases
 - user-facing docs should describe visible agents first and hidden/system agents second
 - third-party MCPs should follow upstream install/launch conventions whenever possible

package/LICENSE.md

@@ -20,6 +20,7 @@ Some are:
 
 | 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) | important 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 |