@hiai-gg/hiai-opencode 0.2.0 → 0.2.2

package/.env.example

@@ -22,6 +22,7 @@
 # FIRECRAWL_API_KEY=your_firecrawl_api_key_here
 
 # Optional - Context7 code search MCP
+# CONTEXT7_API_KEY=your_context7_api_key_here
 
 # Local Model Helpers
 
@@ -46,6 +47,9 @@
 
 # Optional - controls automatic .mcp.json export when the plugin loads.
 # Values: if-missing (default), always (managed files only), force, 0/false/no/off.
+# Optional - log level for hiai-opencode (debug, info, warn, error)
+# HIAI_OPENCODE_LOG_LEVEL=info
+
 # HIAI_OPENCODE_AUTO_EXPORT_MCP=if-missing
 
 # Optional - override static MCP export path.

package/AGENTS.md

@@ -68,11 +68,11 @@ Manual alternative:
 opencode debug config
 hiai-opencode doctor
 hiai-opencode mcp-status
-hiai-opencode export-mcp .mcp.json
+hiai-opencode export-mcp .opencode/.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.
+`opencode mcp list` reads static `.opencode/.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 `.opencode/.mcp.json` on startup when missing. In `always` mode it overwrites only hiai-managed exports unless forced. `hiai-opencode export-mcp .opencode/.mcp.json` can refresh it manually.
 
 ## Post-Install Bootstrap Instructions
 
@@ -122,7 +122,7 @@ When a user asks OpenCode or another agent to finish installing this plugin, fol
    - `opencode debug config`
    - `hiai-opencode doctor`
    - `hiai-opencode mcp-status`
-   - `hiai-opencode export-mcp .mcp.json` when static MCP visibility is needed
+   - `hiai-opencode export-mcp .opencode/.mcp.json` when static MCP visibility is needed
    - `opencode mcp list --print-logs --log-level INFO`
 
 ### MCP Setup Matrix
@@ -158,7 +158,7 @@ Check which services can run here:
 
 Report missing keys without printing secret values. Never invent or hardcode API keys.
 
-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.
+Run hiai-opencode mcp-status and opencode debug config. If the user wants opencode mcp list visibility, run hiai-opencode export-mcp .opencode/.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
@@ -223,13 +223,13 @@ Use this table when you need to change something and want the right file immedia
 | 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 Bob behavior or prompt text | `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 |
 | Change Manager behavior or prompt text | `src/agents/manager/*` | Manager prompt authoring lives there |
 | Change Critic prompt text | `src/agents/critic/*` | Critic prompt authoring lives there |
 | Change Vision prompt text | [src/agents/ui.ts](src/agents/ui.ts) | Vision lives there |
-| Change Manager prompt text | [src/agents/platform-manager.ts](src/agents/platform-manager.ts) | Manager lives there |
+| Change Manager prompt text | `src/agents/manager/*` | Manager lives there |
 | Change reusable policy blocks used by several agents | `src/agents/prompt-library/*` | Shared prompt sections live there |
 | Change dynamic prompt sections assembled from agent/tool/category context | `src/agents/dynamic-agent-*` | Dynamic sections are built there |
 | Change runtime display names | [src/shared/agent-display-names.ts](src/shared/agent-display-names.ts) | Final display-name mapping lives there |
@@ -256,21 +256,20 @@ Prompting is layered.
 
 These decide the high-level config object for each agent:
 
-- Bob: [src/agents/bob.ts](src/agents/bob.ts)
+- Bob: `src/agents/bob/*`
 - Coder: `src/agents/coder/*`
 - Strategist: `src/agents/strategist/*`
 - Manager: `src/agents/manager/*`
 - Critic: `src/agents/critic/*`
 - Vision: [src/agents/ui.ts](src/agents/ui.ts)
-- Manager: [src/agents/platform-manager.ts](src/agents/platform-manager.ts)
 - Researcher: [src/agents/researcher.ts](src/agents/researcher.ts)
 
 ### Layer 2: Model-Specific Prompt Variants
 
 Examples:
 
-- Bob: `src/agents/bob.ts` (single file — variants are merged via factory logic)
-- Coder: `src/agents/coder/agent.ts`, `src/agents/coder/gpt.ts` (model routing via index.ts)
+- Bob: `src/agents/bob/claude.ts`, `src/agents/bob/gpt.ts` (model routing via index.ts)
+- Coder: `src/agents/coder/agent.ts`, `src/agents/coder/core.ts` (model routing via index.ts)
 - Strategist: `src/agents/strategist/index.ts` (mode variants via sub-directory files)
 - Manager: `src/agents/manager/agent.ts`, `src/agents/manager/default.ts`, `src/agents/manager/default-prompt-sections.ts`
 
@@ -422,13 +421,13 @@ Model provider credentials are configured through OpenCode Connect. Do not ask u
 
 Common service keys:
 
-- `STITCH_AI_API_KEY`
-- `FIRECRAWL_API_KEY`
-- `CONTEXT7_API_KEY`
+- `STITCH_AI_API_KEY` (MCP)
+- `FIRECRAWL_API_KEY` (CLI skill, not MCP)
+- `CONTEXT7_API_KEY` (MCP)
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
-- `MEMPALACE_PYTHON`
-- `MEMPALACE_PALACE_PATH`
+- `MEMPALACE_PYTHON` (MCP)
+- `MEMPALACE_PALACE_PATH` (MCP)
 
 - `HIAI_MCP_AUTO_INSTALL`
 - `HIAI_OPENCODE_AUTO_EXPORT_MCP`
@@ -455,12 +454,14 @@ AGENTS:
   agent-skills      — skill registry, discovery
 
 MCP INTEGRATIONS (who uses what):
-  Stitch              -> designer (UI generation)
-  Firecrawl           -> researcher (CLI skill)
-  Context7            -> researcher, coder (lib docs)
-  grep_app            -> researcher (OSS code patterns)
-  MemPalace           -> manager (primary), all agents (search before answer)
-  Sequential-Thinking -> strategist, critic (deep reasoning)
+  Stitch              -> designer (UI generation) [MCP]
+  Context7            -> researcher, coder (lib docs) [MCP]
+  grep_app            -> researcher (OSS code patterns) [MCP]
+  MemPalace           -> manager (primary), all agents (search before answer) [MCP]
+  Sequential-Thinking -> strategist, critic (deep reasoning) [MCP]
+
+CLI SKILLS (not MCP):
+  Firecrawl           -> researcher (web scraping, crawl, extract, search)
 
 LSP:
   typescript, svelte, eslint, bash, pyright
@@ -498,20 +499,20 @@ All agents MUST wrap their final response in a structured `<CLOSURE>` block. Thi
 
 ### Readiness Values
 
-| Value | Meaning |
-|-------|---------|
-| `done` | Task completed successfully |
-| `accept` | Reviewer approved the proposed changes |
-| `reject` | Reviewer denied the changes with feedback |
+| Value | Meaning | Used By |
+|-------|---------|---------|
+| `done` | Task completed successfully | All agents |
+| `accept` | Reviewer approved the proposed changes | Critic, Quality Guardian |
+| `reject` | Reviewer denied the changes with feedback | Critic, Quality Guardian |
 
 **WARNING**: Responses without a valid `<CLOSURE>` block will be automatically REJECTED by the system.
 
 ### Relationship to `<promise>DONE</promise>`
 
-The ralph-loop continuation system uses `<promise>DONE</promise>` as its signal to stop iterating. This is separate from `<CLOSURE>`:
+The ralph-loop and ULW loop continuation systems use `<promise>DONE</promise>` as their signal to stop iterating. This is separate from `<CLOSURE>`:
 
 - `<CLOSURE>` — task completion marker, required on every agent response
-- `<promise>DONE</promise>` — ralph-loop continuation signal, stops the loop when emitted
+- `<promise>DONE</promise>` — ralph-loop/ULW loop continuation signal, stops the loop when emitted
 
 Both can appear together; they do not conflict. The closure validator lives in [src/shared/closure-protocol.ts](src/shared/closure-protocol.ts).
 
@@ -540,26 +541,19 @@ If an agent response is missing `<CLOSURE>` at runtime but the source prompts lo
 
 ### `opencode mcp list` does not show hiai-opencode MCP servers
 
-- `opencode mcp list` reads static `.mcp.json` files, not runtime plugin MCP
-- Run `hiai-opencode export-mcp .mcp.json` to write a static export
+- `opencode mcp list` reads static `.opencode/.mcp.json` files, not runtime plugin MCP
+- Run `hiai-opencode export-mcp .opencode/.mcp.json` to write a static export
 - The plugin auto-exports on startup when `HIAI_OPENCODE_AUTO_EXPORT_MCP` is not disabled
 
 ### Firecrawl tools return "FIRECRAWL_API_KEY missing" despite having the key set
 
-The `skill_mcp` env scrubber strips secret-shaped env vars before launching stdio MCP servers. If your key only lives in `process.env`, move it into the explicit `environment` block in `hiai-opencode.json`:
+Firecrawl is a CLI skill (not an MCP server). The `FIRECRAWL_API_KEY` env var must be available in the shell environment where the CLI skill runs. If your key only lives in `process.env`, export it before starting OpenCode:
 
-```json
-{
-  "mcp": {
-    "firecrawl-cli": {
-      "enabled": true,
-      "environment": { "FIRECRAWL_API_KEY": "fc-..." }
-    }
-  }
-}
+```bash
+export FIRECRAWL_API_KEY=fc-...
 ```
 
-This bypasses the filter because explicit `environment` entries are an allowlist.
+Or set it in `.env` in your project root. Firecrawl is NOT configured via `hiai-opencode.json` MCP section.
 
 ### Browser Automation (agent-browser)
 
@@ -623,7 +617,7 @@ Inspect layer 6 first when runtime output diverges from source.
 
 ### Installing MCP server packages as OpenCode plugins
 
-MCP servers (`firecrawl-mcp`, `@modelcontextprotocol/server-sequential-thinking`) are NOT OpenCode plugins. Adding them to the `plugin` array in `opencode.json` will not work.
+MCP servers (`@modelcontextprotocol/server-sequential-thinking`, `@upstash/context7-mcp`) are NOT OpenCode plugins. Adding them to the `plugin` array in `opencode.json` will not work. Note: Firecrawl is a CLI skill, not an MCP server.
 
 Register only `@hiai-gg/hiai-opencode` as a plugin. MCP wiring is handled through the `mcp` object in `hiai-opencode.json`.
 
@@ -638,14 +632,16 @@ Never put actual API key values in `hiai-opencode.json`. Use `{env:VARIABLE_NAME
 ```json
 {
   "mcp": {
-    "firecrawl-cli": {
+    "stitch": {
       "enabled": true,
-      "environment": { "FIRECRAWL_API_KEY": "{env:FIRECRAWL_API_KEY}" }
+      "environment": { "STITCH_AI_API_KEY": "{env:STITCH_AI_API_KEY}" }
     }
   }
 }
 ```
 
+Note: Firecrawl is a CLI skill, not an MCP server. Its `FIRECRAWL_API_KEY` is set via shell env or `.env`, not in the `mcp` config block.
+
 Check with: `grep -E '(AQ\.|fc-|ctx7sk-|sk-|key-)' hiai-opencode.json` — should return 0 matches.
 
 ### Enabling all skill sources

package/ARCHITECTURE.md

@@ -259,12 +259,13 @@ Current MCP set:
 
 - `stitch`
 - `sequential-thinking`
-- `firecrawl` (CLI skill, not MCP)
 - `mempalace`
 - `context7`
-- `websearch`
 - `grep_app`
-- `agent-browser` (CLI skill, not MCP)
+
+CLI skills (not MCP):
+- `firecrawl` — web scraping, crawl, extract, search
+- `agent-browser` — browser automation via Chrome CDP
 
 ## LSP
 

package/LICENSE.md

@@ -33,6 +33,7 @@ Some are:
 | Firecrawl CLI skill | [firecrawl/firecrawl](https://github.com/firecrawl/firecrawl) | CLI-based web scraping, crawl, extract, search |
 | Context7 MCP | [upstash/context7](https://github.com/upstash/context7) | external MCP |
 | bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
+| Design skills, design systems, craft guidelines, prompt templates | [nexu-io/open-design](https://github.com/nexu-io/open-design) | Apache 2.0 — bundled skill definitions, 150+ brand DESIGN.md files, craft typography/color/UX guidelines, image/video prompt templates |
 
 ## What Is Bundled vs External
 
@@ -58,3 +59,16 @@ If you publish this package publicly:
 - keep upstream links accurate
 - do not imply ownership of upstream MCP servers or external plugins
 - document clearly when a dependency is external rather than bundled
+
+## Third-party: open-design
+
+This project includes content from [nexu-io/open-design](https://github.com/nexu-io/open-design).
+Copyright (c) nexu-io.
+Licensed under the Apache License, Version 2.0.
+Full license: https://github.com/nexu-io/open-design/blob/main/LICENSE
+
+Included content:
+- `skills/` — 130+ skill definitions with SKILL.md prompts and checklists
+- `design-systems/` — 150+ brand DESIGN.md files with tokens.css and components.html
+- `prompt-templates/` — image and video prompt templates
+- `craft/` — typography, color, accessibility, animation, and UX guidelines

package/README.md

@@ -1,7 +1,7 @@
 # hiai-opencode
 
 [![CI](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml?query=branch%3Amain)
-[![npm version](https://img.shields.io/npm/v/@hiai-gg/hiai-opencode/0.2.0?style=flat-square)](https://www.npmjs.com/package/@hiai-gg/hiai-opencode)
+[![npm](https://img.shields.io/npm/v/@hiai-gg/hiai-opencode?style=flat-square&logo=npm)](https://www.npmjs.com/package/@hiai-gg/hiai-opencode)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE.md)
 
 `hiai-opencode` is an OpenCode plugin that turns vanilla OpenCode into an opinionated multi-agent cockpit.
@@ -10,7 +10,7 @@
 
 - **14-agent canonical model (9 visible + 5 hidden)** with peer-aware prompts — Bob orchestrates, Coder/Sub implement, Strategist plans, Critic gates, Researcher discovers via Context7/Firecrawl/grep_app/MemPalace, Designer drives Stitch UI generation, Writer owns copy/SEO, Vision extracts PDFs/images, Manager keeps memory, Quality Guardian reviews, Sandbox sandboxes bash.
 - **Mode → agent routing** for `task()` delegation — `quick`/`bounded`/`unspecified-low` → Sub, `deep`/`cross-module` → Coder, `ultrabrain` → Strategist, `visual-engineering`/`artistry` → Designer, `writing` → Writer, `git-ops` → Manager. No more "everything routes to coder".
-- **MCP wiring out of the box** — Stitch, Firecrawl, Context7, grep_app, MemPalace, Sequential-Thinking. Each agent's prompt knows which MCP servers it owns.
+- **MCP wiring out of the box** — Stitch, Context7, grep_app, MemPalace, Sequential-Thinking. Each agent's prompt knows which MCP servers it owns. Firecrawl is available as a CLI skill (not MCP).
 - **LSP defaults** for TypeScript, Svelte, ESLint, Bash, Pyright. Coder must run `lsp_diagnostics` after every edit.
 - **Permission discipline** — read-only agents cannot delegate; write-capable agents have explicit file-scope limits.
 
@@ -54,7 +54,7 @@ For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖
 | `Manager` | Delegation orchestrator, TODO tracker | Coordinates specialists, maintains session continuity |
 | `Critic` | Review gate, high-accuracy verification | Plan review, code review, regression catch |
 | `Designer` | UI/visual direction via Stitch MCP | Visual problems, design systems, screen generation |
-| `Researcher` | Local + external search | Codebase exploration, documentation discovery |
+| `Researcher` | Local + external search | Codebase exploration, documentation discovery via Context7/grep_app/Firecrawl CLI/MemPalace |
 | `Writer` | Content, copy, positioning, SEO | Website copy, product messaging, naming |
 | `Vision` | PDF/image/diagram extraction, browser UI verification | Multimodal analysis, live browser verification |
 
@@ -97,12 +97,40 @@ MCP integrations and which agents use them:
 | MemPalace | MEMPALACE_PYTHON (optional) | Manager (primary), all agents | Project memory and past decisions |
 | Sequential-Thinking | — | Strategist, Critic | Deep reasoning for planning/review |
 
+## Design System
+
+The plugin bundles a comprehensive design library sourced from [nexu-io/open-design](https://github.com/nexu-io/open-design) (Apache 2.0).
+
+**150+ brand design systems** in `design-systems/` — each contains:
+- `DESIGN.md` — brand voice, typography, color palette, component patterns, layout principles
+- `tokens.css` — CSS custom properties for colors, spacing, typography, shadows
+- `components.html` — reference HTML for key UI components
+
+Brands include: Apple, Linear, Stripe, Vercel, Airbnb, BMW, Spotify, Notion, Figma, Supabase, and 140+ more.
+
+**48 design skills** in `skills/` — covering:
+- Visual storytelling, editorial layouts, motion design
+- Figma integration (create, generate, implement, export)
+- Canvas design, poster/hero layouts, slide decks
+- Accessibility baselines, animation discipline, color theory
+
+**Craft guidelines** in `craft/` — deep references on:
+- Typography hierarchy (editorial + standard)
+- Color systems and accessibility
+- Form validation UX, state coverage patterns
+- Laws of UX, RTL/bidirectional layout
+- Anti-AI-slop patterns (preventing generic output)
+
+**Prompt templates** in `prompt-templates/` — ready-made prompts for image generation and video production.
+
+The Designer agent uses these assets to ground its output in real brand systems instead of generic AI aesthetics. When the Designer agent works on a task, it can reference brand-specific tokens, typography scales, and component patterns from the design-systems library.
+
 ## What You Get
 
 - **9 visible primary agents** + **5 hidden system agents** (Agent Skills, Sub, build, plan, Quality Guardian)
 - **Mode-based task routing** via `task(category=..., ...)` or `task(mode=..., ...)`
 - Skill materialization into OpenCode's `skills/` view
-- MCP wiring for `stitch`, `sequential-thinking`, `firecrawl-cli`, `mempalace`, `context7`, and `grep_app`
+- MCP wiring for `stitch`, `sequential-thinking`, `mempalace`, `context7`, and `grep_app` (Firecrawl is CLI skill only, not MCP)
 - LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint
 
 ## Continuation, Ralph-Loop, And Auto-Start
@@ -134,7 +162,7 @@ Minimum:
 
 - OpenCode installed
 - Node.js 18+
-- Bun 1.1+
+- Bun 1.3.14+
 
 Usually required:
 
@@ -142,10 +170,10 @@ Usually required:
 
 Optional, depending on which services you want:
 
-- `FIRECRAWL_API_KEY` for Firecrawl
-- `STITCH_AI_API_KEY` for Stitch
-- `CONTEXT7_API_KEY` for Context7
-- Python 3.9+ or `uv` for MemPalace
+- `FIRECRAWL_API_KEY` for Firecrawl (CLI skill, not MCP)
+- `STITCH_AI_API_KEY` for Stitch (MCP)
+- `CONTEXT7_API_KEY` for Context7 (MCP)
+- Python 3.9+ or `uv` for MemPalace (MCP)
 - local language servers if you want LSP beyond the npm-bootstrapped helpers
 
 ## Install
@@ -162,7 +190,7 @@ Optional Dynamic Context Pruning plugin:
 opencode plugin @tarquinen/opencode-dcp@latest --global
 ```
 
-Do not put MCP server packages such as `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. Install the CLI skill separately using `opencode plugin` or `npm install -g @mendableai/firecrawl`.
+Do not put MCP server packages such as `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. Firecrawl is available as a CLI skill at `skills/firecrawl-cli/`, not as an MCP server.
 
 Manual OpenCode config equivalent:
 
@@ -247,12 +275,12 @@ See [Environment Variables And Keys](#environment-variables-and-keys) for the fu
 opencode
 hiai-opencode doctor
 hiai-opencode mcp-status
-hiai-opencode export-mcp .mcp.json
+hiai-opencode export-mcp .opencode/.mcp.json
 opencode debug config
 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 plugins may work but not appear there. If you want `opencode mcp list` visibility, run `hiai-opencode export-mcp .mcp.json` first.
+`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 .opencode/.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.
 
@@ -292,17 +320,18 @@ Keep skill discovery deterministic unless I explicitly ask for external skills.
 
 Enable only services that can run on this machine:
 - sequential-thinking: requires node/npx.
-- firecrawl-cli: uses CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks.
 - 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.
 - stitch: requires STITCH_AI_API_KEY.
 - context7: works without a key but use CONTEXT7_API_KEY if available.
+- grep_app: no key required.
+- firecrawl-cli: CLI skill (not MCP) at `skills/firecrawl-cli/`; requires FIRECRAWL_API_KEY.
 
 Check .env.example, report missing keys without printing secret values, and never invent or hardcode API keys.
 
 Run verification commands where available:
 - opencode debug config
 - hiai-opencode mcp-status
-- hiai-opencode export-mcp .mcp.json
+- hiai-opencode export-mcp .opencode/.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.
@@ -334,15 +363,14 @@ Prompting has two main layers:
 
 Important prompt entrypoints:
 
-- `Bob`: [src/agents/bob.ts](src/agents/bob.ts) and `src/agents/bob/*`
+- `Bob`: `src/agents/bob/*`
 - `Coder`: `src/agents/coder/*`
 - `Strategist`: `src/agents/strategist/*`
 - `Manager`: `src/agents/manager/*`
 - `Critic`: `src/agents/critic/*`
 - `Vision`: [src/agents/ui.ts](src/agents/ui.ts)
-- `Manager`: [src/agents/platform-manager.ts](src/agents/platform-manager.ts)
 - `Researcher`: [src/agents/researcher.ts](src/agents/researcher.ts)
-- `Writer` / `Writer`: [src/agents/writer.ts](src/agents/writer.ts)
+- `Writer`: [src/agents/writer.ts](src/agents/writer.ts)
 
 Name mapping and visibility:
 
@@ -419,13 +447,13 @@ Model provider keys are handled by OpenCode Connect. Do not add `OPENROUTER_API_
 
 Important service variables:
 
-- `STITCH_AI_API_KEY`
-- `FIRECRAWL_API_KEY`
-- `CONTEXT7_API_KEY`
+- `STITCH_AI_API_KEY` (MCP)
+- `FIRECRAWL_API_KEY` (CLI skill, not MCP)
+- `CONTEXT7_API_KEY` (MCP)
 - `OLLAMA_BASE_URL`
 - `OLLAMA_MODEL`
-- `MEMPALACE_PYTHON`
-- `MEMPALACE_PALACE_PATH`
+- `MEMPALACE_PYTHON` (MCP)
+- `MEMPALACE_PALACE_PATH` (MCP)
 
 - `HIAI_MCP_AUTO_INSTALL`
 - `HIAI_OPENCODE_AUTO_EXPORT_MCP`
@@ -459,7 +487,10 @@ The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that
 ### Works with local helper bootstrap
 
 - `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.
-- `firecrawl`: uses the CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks.
+
+### CLI skills (not MCP)
+
+- `firecrawl`: uses the CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks. No MCP server needed.
 
 ### Browser Automation
 
@@ -508,24 +539,24 @@ This most often affects `sequential-thinking` and `mempalace`, and sometimes loc
 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`
+- enabled MCP integrations with missing required env vars such as `STITCH_AI_API_KEY`
 
 Available CLI:
 
 ```bash
 hiai-opencode doctor
 hiai-opencode mcp-status
-hiai-opencode export-mcp .mcp.json
+hiai-opencode export-mcp .opencode/.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:
+By default, the plugin auto-exports `.opencode/.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_MCP_EXPORT_PATH=.opencode/.mcp.json   # override path
 export HIAI_OPENCODE_EXPORT_MCP_MODE=safe        # export-mcp command mode: safe|force
 ```
 
@@ -542,7 +573,7 @@ Use:
 
 ```bash
 hiai-opencode mcp-status
-hiai-opencode export-mcp .mcp.json
+hiai-opencode export-mcp .opencode/.mcp.json
 opencode debug config
 opencode mcp list --print-logs --log-level INFO
 ```
@@ -563,7 +594,7 @@ opencode mcp list --print-logs --log-level INFO
 | 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 |
 | Sequential Thinking | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | external MCP |
-| Firecrawl CLI skill | [firecrawl/firecrawl](https://github.com/firecrawl/firecrawl) | CLI-based web scraping, crawl, extract, search |
+| Firecrawl CLI skill | [firecrawl/firecrawl](https://github.com/firecrawl/firecrawl) | CLI-based web scraping, crawl, extract, search (NOT an MCP server) |
 | Context7 MCP | [upstash/context7](https://github.com/upstash/context7) | external MCP |
 | bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
 
@@ -592,7 +623,7 @@ Before publishing:
 1. run `bun run build`
 2. run `npm pack --dry-run`
 3. verify `debug config`
-4. run `hiai-opencode export-mcp .mcp.json` if you need static `mcp list` visibility
+4. run `hiai-opencode export-mcp .opencode/.mcp.json` if you need static `mcp list` visibility
 
 Publish:
 

package/assets/cli/hiai-opencode.mjs

@@ -343,7 +343,7 @@ function checkStaticMcpFreshness(outputPath, config) {
   }
 }
 
-function exportMcp(outputPath = join(process.cwd(), ".mcp.json")) {
+function exportMcp(outputPath = join(process.cwd(), ".opencode", ".mcp.json")) {
   const { path, config, error } = loadConfig()
   if (error) {
     console.error(`Config parse warning: ${error}`)
@@ -793,7 +793,7 @@ function statusIcon(level) {
 
 async function mcpStatus(options = {}) {
   const { path, config, error } = loadConfig()
-  const staticMcpPath = join(process.cwd(), ".mcp.json")
+  const staticMcpPath = join(process.cwd(), ".opencode", ".mcp.json")
   console.log(options.doctor ? "hiai-opencode doctor" : "hiai-opencode mcp-status")
   console.log(`Config: ${path ?? "not found; using defaults"}`)
   if (error) console.log(`Config parse warning: ${error}`)
@@ -873,7 +873,7 @@ async function mcpStatus(options = {}) {
 
     console.log("")
     console.log("Recommended follow-ups:")
-    console.log("  - hiai-opencode export-mcp .mcp.json")
+    console.log("  - hiai-opencode export-mcp .opencode/.mcp.json")
     console.log("  - opencode debug config")
     console.log("  - opencode mcp list --print-logs --log-level INFO")
   }
@@ -937,7 +937,7 @@ async function runDiagnose(outputPath) {
   sections.push(`  CWD: ${process.cwd()}`)
   sections.push(`  Package root: ${PACKAGE_ROOT}`)
   sections.push(`  Config: ${configPath ?? "(none)"}`)
-  sections.push(`  Static MCP: ${join(process.cwd(), ".mcp.json")}`)
+  sections.push(`  Static MCP: ${join(process.cwd(), ".opencode", ".mcp.json")}`)
   sections.push("")
 
   sections.push("=".repeat(60))

package/config/hiai-opencode.schema.json

@@ -26,7 +26,7 @@
         "strategist": {
           "$ref": "#/definitions/modelSlot"
         },
-        "guard": {
+        "manager": {
           "$ref": "#/definitions/modelSlot"
         },
         "critic": {
@@ -38,10 +38,7 @@
         "researcher": {
           "$ref": "#/definitions/modelSlot"
         },
-        "manager": {
-          "$ref": "#/definitions/modelSlot"
-        },
-        "brainstormer": {
+        "writer": {
           "$ref": "#/definitions/modelSlot"
         },
         "vision": {
@@ -55,18 +52,18 @@
         "bob",
         "coder",
         "strategist",
-        "guard",
+        "manager",
         "critic",
         "designer",
         "researcher",
-        "manager",
-        "brainstormer",
-        "vision"
+        "writer",
+        "vision",
+        "sub"
       ]
     },
     "auth": {
       "type": "object",
-      "description": "Service auth placeholders. Keys: stitch, context7. Others are not valid.",
+      "description": "Service auth placeholders. Keys: stitch, context7, firecrawl.",
       "additionalProperties": false,
       "properties": {
         "stitch": {
@@ -76,6 +73,10 @@
         "context7": {
           "type": "string",
           "description": "Context7 API key placeholder, e.g. {env:HIAI_CONTEXT7_AUTH}"
+        },
+        "firecrawl": {
+          "type": "string",
+          "description": "Firecrawl API key placeholder, e.g. {env:FIRECRAWL_API_KEY}"
         }
       }
     },
@@ -83,9 +84,6 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "playwright": {
-          "$ref": "#/definitions/toggle"
-        },
         "stitch": {
           "$ref": "#/definitions/toggle"
         },

package/dist/agents/{bob.d.ts → bob/claude.d.ts}

@@ -1,7 +1,11 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
-import type { AgentPromptMetadata } from "./types";
+import type { AgentPromptMetadata } from "../types";
+import type { AvailableAgent, AvailableSkill, AvailableCategory } from "../dynamic-agent-prompt-builder";
 export declare const BOB_PROMPT_METADATA: AgentPromptMetadata;
-import type { AvailableAgent, AvailableSkill, AvailableCategory } from "./dynamic-agent-prompt-builder";
+/**
+ * Default Bob agent (Claude models).
+ * Thinking config enabled, no reasoningEffort.
+ */
 export declare function createBobAgent(model: string, availableAgents?: AvailableAgent[], availableToolNames?: string[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[], useTaskSystem?: boolean): AgentConfig;
 export declare namespace createBobAgent {
     var mode: "primary";

package/dist/agents/bob/core.d.ts

@@ -0,0 +1,6 @@
+import type { AvailableAgent, AvailableTool, AvailableSkill, AvailableCategory } from "../dynamic-agent-prompt-builder";
+/**
+ * Build Bob's full prompt. Model-agnostic — all model-specific
+ * config (thinking vs reasoningEffort) lives in the overlay files.
+ */
+export declare function buildDynamicBobPrompt(model: string, availableAgents: AvailableAgent[], availableTools?: AvailableTool[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[], useTaskSystem?: boolean): string;

package/dist/agents/bob/gpt.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AvailableAgent, AvailableSkill, AvailableCategory } from "../dynamic-agent-prompt-builder";
+/**
+ * GPT-specific Bob overlay.
+ * Uses reasoningEffort instead of thinking config.
+ * Includes apply-patch permission for GPT models.
+ */
+export declare function createGptBobAgent(model: string, availableAgents?: AvailableAgent[], availableToolNames?: string[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[], useTaskSystem?: boolean): AgentConfig;
+export declare namespace createGptBobAgent {
+    var mode: "primary";
+}

package/dist/agents/bob/index.d.ts

@@ -0,0 +1,3 @@
+export { createBobAgent, BOB_PROMPT_METADATA } from "./claude";
+export { createGptBobAgent } from "./gpt";
+export { buildDynamicBobPrompt } from "./core";

package/dist/agents/coder/core.d.ts

@@ -0,0 +1,4 @@
+/** PROMPT_VERSION: 2026-04-26
+ * Generic GPT Coder prompt - fallback for GPT models without a model-specific variant */
+import type { AvailableAgent, AvailableTool, AvailableSkill, AvailableCategory } from "../dynamic-agent-prompt-builder";
+export declare function buildCoderPrompt(availableAgents?: AvailableAgent[], availableTools?: AvailableTool[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[], useTaskSystem?: boolean): string;