@hiai-gg/hiai-opencode 0.1.3 → 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
@@ -62,6 +55,9 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # 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 search tool endpoint

package/AGENTS.md

@@ -81,6 +81,8 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
 - 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.
 
@@ -96,16 +98,24 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
 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. Check environment variables without printing values:
-   - `OPENROUTER_API_KEY`
+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`
-6. Verify with:
+7. Verify with:
    - `opencode debug config`
    - `opencode mcp list --print-logs --log-level INFO`
 
@@ -121,6 +131,13 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
 | `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:
@@ -188,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
 
@@ -207,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 |
@@ -228,6 +241,8 @@ 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 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 |
@@ -328,22 +343,59 @@ 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`

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
@@ -196,6 +189,10 @@ 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
 
@@ -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 |