@hiai-gg/hiai-opencode 0.1.5 → 0.1.6

package/dist/shared/mcp-static-export.d.ts

@@ -0,0 +1,22 @@
+import type { HiaiOpencodeConfig } from "../config/types";
+type StaticMcpServer = {
+    type?: "http" | "stdio";
+    url?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    headers?: Record<string, string>;
+};
+export declare const MCP_EXPORT_MARKER = "hiai-opencode";
+type StaticMcpJsonPayload = {
+    mcpServers: Record<string, StaticMcpServer>;
+    _meta?: {
+        generatedBy: typeof MCP_EXPORT_MARKER;
+        version: 1;
+        generatedAt: string;
+    };
+};
+export declare function buildStaticMcpJson(config: HiaiOpencodeConfig): StaticMcpJsonPayload;
+export declare function isManagedStaticMcpFile(path: string): boolean;
+export declare function autoExportStaticMcpJson(directory: string, config: HiaiOpencodeConfig): void;
+export {};

package/dist/tools/ast-grep/constants.d.ts

@@ -1,5 +1,5 @@
 export type { EnvironmentCheckResult } from "./environment-check";
 export { checkEnvironment, formatEnvironmentCheck } from "./environment-check";
-export { CLI_LANGUAGES, NAPI_LANGUAGES, LANG_EXTENSIONS } from "./language-support";
+export { CLI_LANGUAGES, LANG_EXTENSIONS } from "./language-support";
 export { DEFAULT_TIMEOUT_MS, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_MAX_MATCHES } from "./language-support";
 export { findSgCliPathSync, getSgCliPath, setSgCliPath } from "./sg-cli-path";

package/dist/tools/ast-grep/environment-check.d.ts

@@ -4,13 +4,9 @@ export interface EnvironmentCheckResult {
         path: string;
         error?: string;
     };
-    napi: {
-        available: boolean;
-        error?: string;
-    };
 }
 /**
- * Check if ast-grep CLI and NAPI are available.
+ * Check if ast-grep CLI is available.
  * Call this at startup to provide early feedback about missing dependencies.
  */
 export declare function checkEnvironment(): EnvironmentCheckResult;

package/dist/tools/ast-grep/language-support.d.ts

@@ -1,5 +1,4 @@
 export declare const CLI_LANGUAGES: readonly ["bash", "c", "cpp", "csharp", "css", "elixir", "go", "haskell", "html", "java", "javascript", "json", "kotlin", "lua", "nix", "php", "python", "ruby", "rust", "scala", "solidity", "swift", "typescript", "tsx", "yaml"];
-export declare const NAPI_LANGUAGES: readonly ["html", "javascript", "tsx", "css", "typescript"];
 export declare const DEFAULT_TIMEOUT_MS = 300000;
 export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 export declare const DEFAULT_MAX_MATCHES = 500;

package/dist/tools/ast-grep/types.d.ts

@@ -1,6 +1,5 @@
-import type { CLI_LANGUAGES, NAPI_LANGUAGES } from "./constants";
+import type { CLI_LANGUAGES } from "./constants";
 export type CliLanguage = (typeof CLI_LANGUAGES)[number];
-export type NapiLanguage = (typeof NAPI_LANGUAGES)[number];
 export interface Position {
     line: number;
     column: number;

package/hiai-opencode.json

@@ -44,7 +44,6 @@
     }
   },
   "auth": {
-    "googleSearch": "{env:GOOGLE_SEARCH_API_KEY}",
     "stitch": "{env:STITCH_AI_API_KEY}",
     "firecrawl": "{env:FIRECRAWL_API_KEY}",
     "context7": "{env:CONTEXT7_API_KEY}"
@@ -55,7 +54,10 @@
     "sequential-thinking": { "enabled": true },
     "firecrawl": { "enabled": true },
     "rag": { "enabled": true },
-    "mempalace": { "enabled": true },
+    "mempalace": {
+      "enabled": true,
+      "pythonPath": "{env:MEMPALACE_PYTHON:-./.venv/bin/python}"
+    },
     "context7": { "enabled": true }
   },
   "lsp": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiai-gg/hiai-opencode",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Unified OpenCode plugin — canonical 12-agent model with bundled skills, MCP integrations, LSP, and permissions in one install.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,19 +50,21 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly",
+    "clean:dist": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "bun run clean:dist && bun build src/index.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly",
     "build:bundle": "bun build src/index.ts --outdir dist --target bun --format esm",
     "build:types": "tsc --emitDeclarationOnly",
     "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "pack:check": "npm pack --dry-run",
     "prepare": "bun run build",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run typecheck && bun run test && bun run build && bun run pack:check"
   },
   "dependencies": {
     "bun-pty": "^0.4.8",
     "@opencode-ai/plugin": "^1.4.0",
     "@opencode-ai/sdk": "^1.4.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@ast-grep/napi": "^0.37.0",
     "zod": "^4.3.0",
     "jsonc-parser": "^3.3.1",
     "js-yaml": "^4.1.0",

package/src/agents/bob/default.ts

@@ -36,7 +36,12 @@ export function buildDefaultBobPrompt(
   useTaskSystem = false,
 ): string {
   const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
-  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
+  const toolSelection = buildToolSelectionTable(
+    availableAgents,
+    availableTools,
+    availableSkills,
+    { includeIntegrationPrimer: true },
+  )
   const researcherSection = buildResearcherSection(availableAgents)
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(availableCategories, availableSkills)
   const delegationTable = buildDelegationTable(availableAgents)

package/src/agents/bob/gpt-pro.ts

@@ -88,6 +88,7 @@ export function buildGptProBobPrompt(
     availableAgents,
     availableTools,
     availableSkills,
+    { includeIntegrationPrimer: true },
   );
   const researcherSection = buildResearcherSection(availableAgents);
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(

package/src/agents/bob.ts

@@ -54,6 +54,7 @@ function buildDynamicBobPrompt(
     availableAgents,
     availableTools,
     availableSkills,
+    { includeIntegrationPrimer: true },
   );
   const researcherSection = buildResearcherSection(availableAgents);
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(

package/src/agents/coder/gpt-codex.ts

@@ -56,6 +56,7 @@ export function buildCoderPrompt(
     availableAgents,
     availableTools,
     availableSkills,
+    { includeIntegrationPrimer: true },
   );
   const researcherSection = buildResearcherSection(availableAgents);
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(

package/src/agents/coder/gpt-pro.ts

@@ -51,6 +51,7 @@ export function buildCoderPrompt(
     availableAgents,
     availableTools,
     availableSkills,
+    { includeIntegrationPrimer: true },
   );
   const researcherSection = buildResearcherSection(availableAgents);
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(

package/src/agents/coder/gpt.ts

@@ -32,6 +32,7 @@ export function buildCoderPrompt(
     availableAgents,
     availableTools,
     availableSkills,
+    { includeIntegrationPrimer: true },
   );
   const researcherSection = buildResearcherSection(availableAgents);
   const categorySkillsGuide = buildCategorySkillsDelegationGuide(

package/src/agents/dynamic-agent-core-sections.ts

@@ -45,6 +45,7 @@ export function buildToolSelectionTable(
   agents: AvailableAgent[],
   tools: AvailableTool[] = [],
   _skills: AvailableSkill[] = [],
+  options: { includeIntegrationPrimer?: boolean } = {},
 ): string {
   const rows: string[] = ["### Tool & Agent Selection:", ""]
 
@@ -72,10 +73,45 @@ export function buildToolSelectionTable(
   rows.push(
     "**Default flow**: researcher (background) + tools → strategist (if required) → critic (high-risk gate)",
   )
+  if (options.includeIntegrationPrimer) {
+    rows.push("")
+    rows.push(buildHiaiIntegrationPrimerSection())
+  }
 
   return rows.join("\n")
 }
 
+export function buildHiaiIntegrationPrimerSection(): string {
+  return `<hiai-opencode-integration-primer>
+## hiai-opencode Architecture And Integration Rules
+
+This workspace may use hiai-opencode, an OpenCode plugin that wires agents, skills, MCP launchers, LSP, diagnostics, and compatibility helpers around external upstream tools.
+
+Core rules:
+- OpenCode plugins are not MCP servers. Keep \`@hiai-gg/hiai-opencode\` and optional \`@tarquinen/opencode-dcp\` in the OpenCode plugin list; never add MCP packages such as \`firecrawl-mcp\`, \`@playwright/mcp\`, or \`@modelcontextprotocol/server-sequential-thinking\` to the plugin list.
+- User-facing config lives in \`hiai-opencode.json\` or \`.opencode/hiai-opencode.json\`: 10 model slots, MCP enable flags, LSP enable flags, service auth placeholders, and skill discovery switches.
+- Model provider credentials are configured through OpenCode Connect. Do not ask for \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, or \`ANTHROPIC_API_KEY\` for normal model usage.
+- Service keys are separate: \`FIRECRAWL_API_KEY\`, \`STITCH_AI_API_KEY\`, \`CONTEXT7_API_KEY\`, and \`OPENCODE_RAG_URL\` when those services are enabled.
+
+MCP usage:
+- Run \`hiai-opencode doctor\` or \`hiai-opencode mcp-status\` for effective runtime MCP status.
+- \`opencode mcp list\` often reads only static \`.mcp.json\`; plugin runtime MCP may work even when that list is empty.
+- The plugin auto-exports \`.mcp.json\` when missing. Run \`hiai-opencode export-mcp .mcp.json\` to refresh static visibility.
+- \`skill_mcp\` can call skill-embedded MCP and enabled hiai-opencode MCP. If an MCP is "not found", check whether the skill was loaded, whether \`hiai-opencode.json\` enables it, and whether static export is needed.
+
+Memory and retrieval:
+- MemPalace MCP is external. If enabled, use \`mempalace_status\` first, search before answering about remembered people/projects/past decisions, and write diary entries when appropriate. Never invent memories.
+- RAG MCP is external/local. Use it for project knowledge search when \`OPENCODE_RAG_URL\` is configured or the default \`http://localhost:9002/tools/search\` is reachable.
+- Sequential Thinking MCP is for complex planning/revision/branching, not for trivial edits.
+- Firecrawl/Stitch/Context7 are external web/docs/research services; missing service keys should be reported by env var name only.
+
+Installation/debugging:
+- Use \`/doctor\` or \`hiai-opencode doctor\` before changing config.
+- Prefer user-level or project-local installs. Do not use sudo/admin rights unless explicitly requested.
+- If DCP is requested, install it separately with \`opencode plugin @tarquinen/opencode-dcp@latest --global\`.
+</hiai-opencode-integration-primer>`
+}
+
 export function buildResearcherSection(agents: AvailableAgent[]): string {
   const researcherAgent = agents.find((agent) => agent.name === "researcher")
   if (!researcherAgent) {

package/src/agents/dynamic-agent-prompt-builder.ts

@@ -13,6 +13,7 @@ export {
   buildToolSelectionTable,
   buildResearcherSection,
   buildDelegationTable,
+  buildHiaiIntegrationPrimerSection,
   buildStrategistAndCriticSection,
   buildNonClaudePlannerSection,
   buildParallelDelegationSection,

package/src/config/defaults.ts

@@ -135,7 +135,20 @@ function deriveMcp(config: HiaiOpencodeConfig): HiaiOpencodeConfig["mcp"] {
   return Object.fromEntries(
     Object.entries(defaults).map(([name, entry]) => {
       const override = userMcp[name] ?? {}
-      return [name, { ...entry, ...override }]
+      const merged = { ...entry, ...override }
+
+      if (name === "mempalace" && typeof merged.pythonPath === "string" && merged.pythonPath.trim()) {
+        merged.environment = {
+          ...(entry.environment ?? {}),
+          ...(merged.environment ?? {}),
+          MEMPALACE_PYTHON: merged.pythonPath.trim(),
+        }
+      }
+
+      // Internal launcher hint; do not leak unknown keys into final OpenCode MCP server config.
+      delete merged.pythonPath
+
+      return [name, merged]
     }),
   )
 }

package/src/config/model-slots-and-export.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test"
+
+import { applyModelSlots } from "./defaults"
+import type { HiaiOpencodeConfig } from "./types"
+import { buildStaticMcpJson, MCP_EXPORT_MARKER } from "../shared/mcp-static-export"
+import { buildHiaiIntegrationPrimerSection } from "../agents/dynamic-agent-core-sections"
+
+const baseConfig: HiaiOpencodeConfig = {
+  models: {
+    bob: { model: "openrouter/test/bob", recommended: "xhigh" },
+    coder: { model: "openrouter/test/coder", recommended: "high" },
+    strategist: { model: "openrouter/test/strategist", recommended: "high" },
+    guard: { model: "openrouter/test/guard", recommended: "middle" },
+    critic: { model: "openrouter/test/critic", recommended: "high" },
+    designer: { model: "openrouter/test/designer", recommended: "design" },
+    researcher: { model: "openrouter/test/researcher", recommended: "fast" },
+    manager: { model: "openrouter/test/manager", recommended: "fast" },
+    brainstormer: { model: "openrouter/test/brainstormer", recommended: "writing" },
+    vision: { model: "openrouter/test/vision", recommended: "vision" },
+  },
+  mcp: {
+    mempalace: { enabled: true, pythonPath: "/opt/venv/bin/python" },
+  },
+}
+
+test("model slots derive canonical agents and categories", () => {
+  const resolved = applyModelSlots(baseConfig)
+  expect(resolved.agents?.bob?.model).toBe("openrouter/test/bob")
+  expect(resolved.agents?.coder?.model).toBe("openrouter/test/coder")
+  expect(resolved.agents?.["platform-manager"]?.model).toBe("openrouter/test/manager")
+  expect(resolved.agents?.sub?.model).toBe("openrouter/test/coder")
+  expect(resolved.categories?.artistry?.model).toBe("openrouter/test/designer")
+  expect(resolved.categories?.ultrabrain?.model).toBe("openrouter/test/strategist")
+  expect(resolved.categories?.writing?.model).toBe("openrouter/test/brainstormer")
+})
+
+test("compact MCP mempalace pythonPath is materialized into environment", () => {
+  const resolved = applyModelSlots(baseConfig)
+  expect(resolved.mcp?.mempalace?.environment?.MEMPALACE_PYTHON).toBe("/opt/venv/bin/python")
+})
+
+test("static MCP export includes marker metadata and servers", () => {
+  const resolved = applyModelSlots(baseConfig)
+  const exported = buildStaticMcpJson(resolved)
+
+  expect(exported._meta?.generatedBy).toBe(MCP_EXPORT_MARKER)
+  expect(exported._meta?.version).toBe(1)
+  expect(exported.mcpServers.playwright).toBeDefined()
+  expect(exported.mcpServers.mempalace).toBeDefined()
+})
+
+test("integration primer does not request model provider API keys", () => {
+  const primer = buildHiaiIntegrationPrimerSection()
+  expect(primer).toContain("Do not ask for `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`")
+})

package/src/config/platform-schema.ts

@@ -76,6 +76,7 @@ export const McpServerConfigSchema = z.object({
   command: z.array(z.string()).optional(),
   timeout: z.number().optional(),
   environment: z.record(z.string(), z.string()).optional(),
+  pythonPath: z.string().optional(),
 });
 
 export const LspServerConfigSchema = z.object({
@@ -129,9 +130,6 @@ export const PermissionsConfigSchema = z.object({
 });
 
 export const AuthKeysSchema = z.object({
-  googleSearch: z.string().optional(),
-  openai: z.string().optional(),
-  openrouter: z.string().optional(),
   stitch: z.string().optional(),
   firecrawl: z.string().optional(),
   context7: z.string().optional(),

package/src/config/schema/commands.ts

@@ -10,6 +10,7 @@ export const BuiltinCommandNameSchema = z.enum([
   "stop-continuation",
   "remove-ai-slops",
   "mcp-status",
+  "doctor",
 ])
 
 export type BuiltinCommandName = z.infer<typeof BuiltinCommandNameSchema>

package/src/config/schema/oh-my-opencode-config.ts

@@ -26,9 +26,6 @@ import { FastApplyConfigSchema } from "./fast-apply"
 import { WebsearchConfigSchema } from "./websearch"
 
 const AuthConfigSchema = z.object({
-  googleSearch: z.string().optional(),
-  openai: z.string().optional(),
-  openrouter: z.string().optional(),
   stitch: z.string().optional(),
   firecrawl: z.string().optional(),
   context7: z.string().optional(),

package/src/config/types.ts

@@ -150,6 +150,7 @@ export interface McpServerConfig {
   command?: string[];
   timeout?: number;
   environment?: Record<string, string>;
+  pythonPath?: string;
 }
 
 export interface LspServerConfig {
@@ -187,9 +188,6 @@ export interface PermissionsConfig {
 }
 
 export interface AuthKeys {
-  googleSearch?: string;
-  openai?: string;
-  openrouter?: string;
   stitch?: string;
   firecrawl?: string;
   context7?: string;

package/src/features/builtin-commands/commands.ts

@@ -9,6 +9,7 @@ import { START_WORK_TEMPLATE } from "./templates/start-work"
 import { HANDOFF_TEMPLATE } from "./templates/handoff"
 import { REMOVE_AI_SLOPS_TEMPLATE } from "./templates/remove-ai-slops"
 import { MCP_STATUS_TEMPLATE } from "./templates/mcp-status"
+import { DOCTOR_TEMPLATE } from "./templates/doctor"
 
 interface LoadBuiltinCommandsOptions {
   useRegisteredAgents?: boolean
@@ -126,6 +127,12 @@ $ARGUMENTS
       description: "(builtin) Show hiai-opencode MCP server status, missing keys, and local runtime availability",
       template: `<command-instruction>
 ${MCP_STATUS_TEMPLATE}
+</command-instruction>`,
+    },
+    doctor: {
+      description: "(builtin) Run hiai-opencode install/runtime diagnostics and explain setup issues",
+      template: `<command-instruction>
+${DOCTOR_TEMPLATE}
 </command-instruction>`,
     },
   }

package/src/features/builtin-commands/templates/doctor.ts

@@ -0,0 +1,43 @@
+export const DOCTOR_TEMPLATE = `# Hiai OpenCode Doctor Command
+
+## Purpose
+
+Use /doctor to run the hiai-opencode install/runtime diagnostic and report actionable setup issues.
+
+## Execute
+
+Run:
+
+\`\`\`bash
+hiai-opencode doctor
+\`\`\`
+
+If the binary is not on PATH, try the package-local fallback:
+
+\`\`\`bash
+node ./node_modules/@hiai-gg/hiai-opencode/assets/cli/hiai-opencode.mjs doctor
+\`\`\`
+
+## Report
+
+Summarize:
+
+- config path
+- enabled and disabled MCP servers
+- missing env vars by name only
+- static \`.mcp.json\` freshness and whether it is managed by hiai-opencode
+- OpenCode Connect visibility for configured model providers
+- OpenCode plugin registration sanity (including \`plugin: ["list"]\` misconfiguration warning)
+- skill materialization status from skill registry
+- agent count and naming summary
+- LSP runtime availability
+- MemPalace python source and selected interpreter (env/config/auto)
+- MCP tool probes (real connect + tools/list) for stdio and basic endpoint probes for remote MCP
+
+Rules:
+
+- Do not print API key values.
+- Do not ask for model provider env vars such as OPENROUTER_API_KEY or OPENAI_API_KEY; normal model auth belongs to OpenCode Connect.
+- If \`opencode mcp list\` is empty but doctor/mcp-status sees servers, explain the runtime-vs-static config distinction and run \`hiai-opencode export-mcp .mcp.json\` if the user wants static visibility.
+- Do not run package installs unless the user explicitly asks.
+`

package/src/features/builtin-commands/types.ts

@@ -1,6 +1,6 @@
 import type { CommandDefinition } from "../claude-code-command-loader"
 
-export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "remove-ai-slops" | "mcp-status"
+export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "remove-ai-slops" | "mcp-status" | "doctor"
 
 export interface BuiltinCommandConfig {
   disabled_commands?: BuiltinCommandName[]

package/src/features/builtin-skills/skills/hiai-opencode-setup.ts

@@ -0,0 +1,69 @@
+import type { BuiltinSkill } from "../types"
+
+export const hiaiOpencodeSetupSkill: BuiltinSkill = {
+  name: "hiai-opencode-setup",
+  description:
+    "Use when install/setup/onboarding or MCP debug mentions: install, setup, bootstrap, doctor, mcp-status, MCP not found, mcp list empty, MemPalace, RAG, firecrawl, stitch, sequential-thinking, playwright, DCP, agents, skills, or LSP.",
+  template: `# hiai-opencode Setup And Runtime Operations
+
+Use this skill for hiai-opencode installation, diagnostics, and integration repair.
+
+## Architecture
+
+- hiai-opencode is an OpenCode plugin, not a standalone app.
+- MCP servers are external upstream tools launched by hiai-opencode wiring.
+- The user-facing config is \`hiai-opencode.json\` or \`.opencode/hiai-opencode.json\`.
+- Model provider credentials belong to OpenCode Connect. Do not ask for \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, or \`ANTHROPIC_API_KEY\` for normal model usage.
+- Service credentials are separate: \`FIRECRAWL_API_KEY\`, \`STITCH_AI_API_KEY\`, \`CONTEXT7_API_KEY\`.
+
+## First Diagnostic Commands
+
+\`\`\`bash
+hiai-opencode doctor
+hiai-opencode mcp-status
+opencode debug config
+\`\`\`
+
+If \`opencode mcp list\` is empty but doctor/mcp-status sees servers, explain that OpenCode's list may read only static \`.mcp.json\`. Refresh static visibility:
+
+\`\`\`bash
+hiai-opencode export-mcp .mcp.json
+opencode mcp list --print-logs --log-level INFO
+\`\`\`
+
+## Plugin vs MCP
+
+Install OpenCode plugins with:
+
+\`\`\`bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+opencode plugin @tarquinen/opencode-dcp@latest --global
+\`\`\`
+
+Do not add MCP packages to the OpenCode plugin array. MCP packages are launched through \`hiai-opencode.json\` and helper scripts.
+
+## MCP Runtime Notes
+
+- \`playwright\`: node/npx; browser binaries may need \`HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1\`; Linux system deps may require admin rights.
+- \`sequential-thinking\`: node/npx; use for complex planning, revision, and branching.
+- \`firecrawl\`: requires \`FIRECRAWL_API_KEY\`.
+- \`mempalace\`: prefers \`uv\`; otherwise Python 3.9+ with \`mempalace\`. Use \`mempalace_status\` first, search before answering memory questions, and never invent memories.
+- \`rag\`: requires \`OPENCODE_RAG_URL\` or a reachable default \`http://localhost:9002/tools/search\`.
+- \`stitch\`: requires \`STITCH_AI_API_KEY\`.
+- \`context7\`: remote docs/search; key optional but recommended for limits.
+
+## Calling MCP
+
+- Use native MCP tools if OpenCode exposes them.
+- Use \`skill_mcp\` for skill-embedded MCP or enabled hiai-opencode MCP.
+- If \`skill_mcp\` says a server is not found, check whether the skill is loaded, whether the MCP is enabled in \`hiai-opencode.json\`, and whether \`.mcp.json\` needs export.
+
+## Safety Rules
+
+- Report missing keys by env var name only. Never print key values.
+- Prefer project-local or user-level installs. Do not use sudo/admin rights unless the user explicitly asks.
+- Do not edit unrelated OpenCode/Claude/Agents global skill folders unless the user opts in.
+- Keep DCP separate: it is an optional OpenCode plugin, not part of the hiai-opencode package.
+`,
+  allowedTools: ["Bash(*)", "Read(*)", "Edit(*)", "Glob(*)", "Grep(*)", "skill_mcp(*)"],
+}

package/src/features/builtin-skills/skills/index.ts

@@ -5,3 +5,4 @@ export { gitMasterSkill } from "./git-master"
 export { devBrowserSkill } from "./dev-browser"
 export { reviewWorkSkill } from "./review-work"
 export { aiSlopRemoverSkill } from "./ai-slop-remover"
+export { hiaiOpencodeSetupSkill } from "./hiai-opencode-setup"

package/src/features/builtin-skills/skills.ts

@@ -10,6 +10,7 @@ import {
   devBrowserSkill,
   reviewWorkSkill,
   aiSlopRemoverSkill,
+  hiaiOpencodeSetupSkill,
 } from "./skills/index"
 
 export interface CreateBuiltinSkillsOptions {
@@ -29,7 +30,15 @@ export function createBuiltinSkills(options: CreateBuiltinSkillsOptions = {}): B
     browserSkill = playwrightSkill
   }
 
-  const skills = [browserSkill, frontendUiUxSkill, gitMasterSkill, devBrowserSkill, reviewWorkSkill, aiSlopRemoverSkill]
+  const skills = [
+    browserSkill,
+    hiaiOpencodeSetupSkill,
+    frontendUiUxSkill,
+    gitMasterSkill,
+    devBrowserSkill,
+    reviewWorkSkill,
+    aiSlopRemoverSkill,
+  ]
 
   if (!disabledSkills) {
     return skills