@softspark/ai-toolkit 2.5.0 → 2.6.1

package/scripts/generate_opencode_commands.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate .opencode/commands/*.md files for opencode (https://opencode.ai).
+
+User-invocable skills become opencode slash commands. Knowledge skills
+(``user-invocable: false``) are excluded — they load automatically via
+AGENTS.md context instead of `/` invocation.
+
+Generated commands use the required ``template`` frontmatter field.
+Files are prefixed ``ai-toolkit-`` for clean uninstall.
+
+opencode commands: https://opencode.ai/docs/commands/
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import build_codex_skill_text, is_codex_adapted_skill
+from emission import skills_dir
+from frontmatter import frontmatter_field
+
+COMMAND_PREFIX = "ai-toolkit-"
+
+
+def _skill_body(skill_file: Path) -> str:
+    """Return the markdown body of a skill (content after frontmatter).
+
+    For skills that rely on Claude-only orchestration primitives, route
+    through the Codex adapter so `Agent`/`TeamCreate`/`TaskCreate` get
+    rewritten to opencode-compatible delegation guidance. The adapter's
+    output is compatible with opencode's subagent model (``spawn_agent``
+    conventions, plan tracking) because both lack Claude primitives.
+    """
+    if is_codex_adapted_skill(skill_file):
+        adapted = build_codex_skill_text(skill_file)
+        # Strip the adapted frontmatter — we emit our own below
+        parts = adapted.split("---", 2)
+        return parts[2].lstrip("\n") if len(parts) >= 3 else adapted
+
+    text = skill_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text
+    parts = text.split("---", 2)
+    return parts[2].lstrip("\n") if len(parts) >= 3 else text
+
+
+def _render_opencode_command(skill_file: Path) -> str:
+    """Render a single opencode command .md file from a user-invocable skill."""
+    name = frontmatter_field(skill_file, "name")
+    description = frontmatter_field(skill_file, "description")
+    agent_field = frontmatter_field(skill_file, "agent")
+    # opencode does NOT read "body" — the prompt is entirely in the `template`
+    # frontmatter field. We embed the SKILL.md body as the template using a
+    # YAML block scalar (``|``) which preserves newlines without escaping.
+    body = _skill_body(skill_file).rstrip()
+
+    lines: list[str] = ["---"]
+    if description:
+        safe_desc = description.replace('"', "'")
+        lines.append(f'description: "{safe_desc}"')
+    if agent_field:
+        # opencode accepts an `agent` frontmatter field pointing at a subagent
+        lines.append(f"agent: {_map_agent_name(agent_field)}")
+    lines.append("template: |")
+    for tpl_line in body.splitlines() or [""]:
+        lines.append(f"  {tpl_line}" if tpl_line else "  ")
+    lines.append("---")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _map_agent_name(value: str) -> str:
+    """Map ai-toolkit agent names to opencode subagent names.
+
+    Our opencode agents are installed with the ``ai-toolkit-`` prefix by
+    ``generate_opencode_agents.py``, so rewrite here for consistency.
+    """
+    value = value.strip()
+    if not value:
+        return value
+    if value.startswith(COMMAND_PREFIX):
+        return value
+    return f"{COMMAND_PREFIX}{value}"
+
+
+def _is_user_invocable(skill_file: Path) -> bool:
+    """Return True if the skill should be exposed as a `/` command."""
+    invocable = frontmatter_field(skill_file, "user-invocable")
+    if invocable:
+        return invocable.lower() not in ("false", "0", "no")
+    # Absence + `disable-model-invocation: true` = task skill (user-invocable)
+    disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+    if disable_model and disable_model.lower() in ("true", "1", "yes"):
+        return True
+    # Default: NOT invocable — avoids exposing knowledge skills as commands
+    return False
+
+
+def _cleanup_stale(commands_out: Path) -> int:
+    """Remove stale ai-toolkit-* command files whose source no longer exists or is no longer invocable."""
+    if not commands_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(commands_out.glob(f"{COMMAND_PREFIX}*.md")):
+        source_name = f.stem[len(COMMAND_PREFIX):]
+        source = skills_dir / source_name / "SKILL.md"
+        if not source.is_file() or not _is_user_invocable(source):
+            f.unlink()
+            removed += 1
+    return removed
+
+
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode command files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.opencode/commands/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``commands/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    commands_out = base / "commands"
+    commands_out.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        if not _is_user_invocable(skill_file):
+            continue
+        name = frontmatter_field(skill_file, "name")
+        if not name:
+            continue
+        out_path = commands_out / f"{COMMAND_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_command(skill_file), encoding="utf-8")
+        written += 1
+
+    removed = _cleanup_stale(commands_out)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_json.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Merge MCP servers from .mcp.json into opencode.json for opencode.
+
+opencode MCP config: https://opencode.ai/docs/mcp-servers/
+
+Schema per server:
+  Local:  {"type": "local",  "command": [...], "enabled": true, "environment": {...}}
+  Remote: {"type": "remote", "url": "...",      "enabled": true, "headers": {...}}
+
+Our canonical source is .mcp.json (Claude-style) with:
+  {"mcpServers": {"name": {"command": "...", "args": [...], "env": {...}}}}
+  or: {"name": {"url": "..."}} for remote.
+
+We translate into opencode's shape and merge under the ``mcp`` key.
+All non-``mcp`` keys are preserved verbatim — idempotent on re-run.
+
+Usage:
+  python3 scripts/generate_opencode_json.py [target-dir]
+"""
+from __future__ import annotations
+
+import copy
+import json
+import sys
+from pathlib import Path
+
+SCHEMA_URL = "https://opencode.ai/config.json"
+
+
+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+
+
+def _write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+
+def _translate_server(name: str, server: dict) -> dict:
+    """Translate a Claude-style server entry into opencode's shape."""
+    out: dict = {}
+    if "url" in server:
+        out["type"] = "remote"
+        out["url"] = server["url"]
+        if "headers" in server and isinstance(server["headers"], dict):
+            out["headers"] = copy.deepcopy(server["headers"])
+    elif "command" in server:
+        out["type"] = "local"
+        cmd = server["command"]
+        args = server.get("args") or []
+        if isinstance(cmd, list):
+            out["command"] = list(cmd) + list(args)
+        else:
+            out["command"] = [cmd, *args]
+        env = server.get("env") or server.get("environment")
+        if isinstance(env, dict) and env:
+            out["environment"] = copy.deepcopy(env)
+    else:
+        # Unknown shape — preserve as-is so opencode can report the error
+        out = copy.deepcopy(server)
+        out.setdefault("type", "local")
+
+    out.setdefault("enabled", True)
+    if "timeout" in server:
+        out["timeout"] = server["timeout"]
+    return out
+
+
+def _read_mcp_servers(project_dir: Path) -> dict:
+    """Read canonical .mcp.json and return the servers map.
+
+    Returns {} when no .mcp.json exists (non-fatal).
+    """
+    config = project_dir / ".mcp.json"
+    if not config.is_file():
+        return {}
+    data = _load_json(config)
+    servers = data.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        return {}
+    return servers
+
+
+def merge_into_opencode_json(
+    target_dir: Path, output_path: Path | None = None
+) -> tuple[Path, int]:
+    """Merge .mcp.json servers into an opencode.json file.
+
+    Reads ``target_dir/.mcp.json`` as the canonical source. By default
+    writes to ``target_dir/opencode.json`` (project-local). Pass
+    ``output_path=~/.config/opencode/opencode.json`` for the global layout.
+
+    Returns (path, server_count). If no .mcp.json exists, still ensures
+    the output has the $schema key set (creates a minimal file).
+    """
+    servers = _read_mcp_servers(target_dir)
+    path = output_path if output_path is not None else target_dir / "opencode.json"
+    data = _load_json(path)
+    data.setdefault("$schema", SCHEMA_URL)
+
+    if servers:
+        bucket = data.setdefault("mcp", {})
+        if not isinstance(bucket, dict):
+            raise ValueError(f"{path} has invalid 'mcp' data (expected object)")
+        for name, entry in servers.items():
+            if not isinstance(entry, dict):
+                continue
+            bucket[name] = _translate_server(name, entry)
+
+    _write_json(path, data)
+    return path, len(servers)
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path, count = merge_into_opencode_json(target)
+    rel = path.relative_to(target) if path.is_relative_to(target) else path
+    if count:
+        print(f"Generated: {rel} ({count} MCP server(s) merged)")
+    else:
+        print(f"Generated: {rel} (no MCP servers; .mcp.json not found)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_plugin.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Generate the ai-toolkit opencode plugin at ``.opencode/plugins/ai-toolkit-hooks.js``.
+
+opencode plugins are JS/TS modules with a NAMED export that receive a
+context (``$``, ``project``, ``client``, ``directory``, ``worktree``) and
+return a hooks object. Docs: https://opencode.ai/docs/plugins/
+
+This generator emits a single-file plugin that bridges ai-toolkit's
+shared Bash hooks (``$HOME/.softspark/ai-toolkit/hooks/*.sh``) to
+opencode lifecycle events. Coverage map:
+
+  opencode event              -> ai-toolkit Bash hook(s)
+  ---------------------------------------------------------------
+  session.created             -> session-start.sh + session-context.sh + mcp-health.sh
+  session.compacted           -> pre-compact.sh + pre-compact-save.sh
+  session.deleted             -> session-end.sh + save-session.sh
+  message.updated             -> user-prompt-submit.sh + track-usage.sh
+  message.part.updated        -> user-prompt-submit.sh + track-usage.sh
+  tool.execute.before (bash)  -> guard-destructive.sh + commit-quality.sh
+  tool.execute.after          -> post-tool-use.sh
+  permission.asked            -> guard-destructive.sh
+  command.executed            -> post-tool-use.sh
+
+Security: hooks are invoked via ``$`` with the script path bound to a
+JS constant (no opencode-payload interpolation into the command). Event
+payloads are passed on stdin as JSON. Non-zero exit codes are logged to
+stderr; ``exit 2`` is preserved as a block signal for PreToolUse guards.
+
+Usage:
+  python3 scripts/generate_opencode_plugin.py [target-dir] [--config-root PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+PLUGIN_BODY = r"""// ai-toolkit opencode plugin — bridges shared Bash hooks to opencode events.
+// Auto-generated by ai-toolkit. Do not edit by hand; re-run to update:
+//   ai-toolkit opencode-plugin
+// Docs: https://opencode.ai/docs/plugins/
+//
+// Hooks live at $HOME/.softspark/ai-toolkit/hooks/*.sh and are shared with
+// Claude Code and Codex CLI. This plugin invokes them via Bun's `$` shell
+// with the script path bound as a JS constant — no string interpolation of
+// opencode event payloads into the shell, so event data cannot inject
+// shell metacharacters. Payloads are passed on stdin as JSON.
+
+const HOOKS_DIR = `${process.env.HOME}/.softspark/ai-toolkit/hooks`;
+
+/** Invoke a Bash hook with a JSON payload on stdin. */
+async function runHook($, script, payload) {
+  const scriptPath = `${HOOKS_DIR}/${script}`;
+  try {
+    const input = JSON.stringify(payload ?? {});
+    const proc = $`bash ${scriptPath}`.env({
+      ...process.env,
+      AI_TOOLKIT_EVENT: payload?.event || "unknown",
+    });
+    proc.stdin.write(input);
+    proc.stdin.end();
+    const result = await proc.quiet().nothrow();
+    if (result.exitCode !== 0 && result.exitCode !== 2) {
+      // Exit 2 is the toolkit's "block" signal — pass through to opencode as a guard.
+      process.stderr.write(
+        `[ai-toolkit] ${script} exited ${result.exitCode}\n${result.stderr.toString()}`
+      );
+    }
+    return result.exitCode;
+  } catch (err) {
+    process.stderr.write(`[ai-toolkit] failed to run ${script}: ${err.message}\n`);
+    return 0;
+  }
+}
+
+export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
+  event: async ({ event }) => {
+    const payload = { event: event.type, project, directory, worktree };
+    switch (event.type) {
+      case "session.created":
+        await runHook($, "session-start.sh", payload);
+        await runHook($, "session-context.sh", payload);
+        await runHook($, "mcp-health.sh", payload);
+        break;
+      case "session.compacted":
+        await runHook($, "pre-compact.sh", payload);
+        await runHook($, "pre-compact-save.sh", payload);
+        break;
+      case "session.deleted":
+        await runHook($, "session-end.sh", payload);
+        await runHook($, "save-session.sh", payload);
+        break;
+      case "message.updated":
+      case "message.part.updated":
+        await runHook($, "user-prompt-submit.sh", payload);
+        await runHook($, "track-usage.sh", payload);
+        break;
+      case "permission.asked":
+        await runHook($, "guard-destructive.sh", payload);
+        break;
+      case "command.executed":
+        await runHook($, "post-tool-use.sh", payload);
+        break;
+    }
+  },
+
+  "tool.execute.before": async (input, output) => {
+    const payload = {
+      event: "tool.execute.before",
+      tool: input?.tool,
+      args: output?.args,
+      project,
+    };
+    if (input?.tool === "bash") {
+      await runHook($, "guard-destructive.sh", payload);
+      await runHook($, "commit-quality.sh", payload);
+    }
+  },
+
+  "tool.execute.after": async (input, output) => {
+    const payload = {
+      event: "tool.execute.after",
+      tool: input?.tool,
+      result: output,
+      project,
+    };
+    await runHook($, "post-tool-use.sh", payload);
+  },
+});
+"""
+
+
+def generate(target_dir: Path, config_root: Path | None = None) -> Path:
+    """Write the opencode plugin file and return its path.
+
+    ``config_root`` lets the caller override the default project-local
+    layout. When omitted, writes to ``target_dir/.opencode/plugins/``.
+    Pass ``config_root=~/.config/opencode`` to lay down the plugin
+    globally at ``~/.config/opencode/plugins/ai-toolkit-hooks.js``.
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    plugins_dir = base / "plugins"
+    plugins_dir.mkdir(parents=True, exist_ok=True)
+    path = plugins_dir / "ai-toolkit-hooks.js"
+    path.write_text(PLUGIN_BODY, encoding="utf-8")
+    return path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate opencode plugin")
+    parser.add_argument("target", nargs="?", default=".", help="Target directory")
+    parser.add_argument(
+        "--config-root",
+        type=Path,
+        default=None,
+        help="Override base (e.g. ~/.config/opencode for global install).",
+    )
+    args = parser.parse_args()
+    target = Path(args.target)
+    path = generate(target, config_root=args.config_root)
+    try:
+        rel = path.relative_to(target)
+    except ValueError:
+        rel = path
+    print(f"Generated: {rel}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install_steps/ai_tools.py

@@ -92,6 +92,14 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
             _install_codex_global(target_dir, rules_dir)
         installed.append("codex")
 
+    if "opencode" in eds:
+        if dry_run:
+            print("  Would inject: ~/.config/opencode/{AGENTS.md, agents/, "
+                  "commands/, plugins/ai-toolkit-hooks.js, opencode.json}")
+        else:
+            _install_opencode_global(target_dir, rules_dir)
+        installed.append("opencode")
+
     print()
     print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
     print("  Note: Copilot, Cline, Roo Code, Aider, Antigravity have no global config -- use 'ai-toolkit install --local' per project")
@@ -128,6 +136,51 @@ def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
     _install_codex_skills(target_dir)
 
 
+def _install_opencode_global(target_dir: Path, rules_dir: Path) -> None:
+    """Install opencode at the global level (~/.config/opencode/).
+
+    Creates:
+      - ~/.config/opencode/AGENTS.md (marker injection with rules)
+      - ~/.config/opencode/agents/ai-toolkit-*.md (subagents)
+      - ~/.config/opencode/commands/ai-toolkit-*.md (slash commands)
+      - ~/.config/opencode/plugins/ai-toolkit-hooks.js (hook bridge)
+      - ~/.config/opencode/opencode.json (MCP merge, preserves user keys)
+    """
+    opencode_home = target_dir / ".config" / "opencode"
+    inject_with_rules(
+        "generate_opencode.py",
+        opencode_home / "AGENTS.md",
+        rules_dir,
+    )
+
+    from generate_opencode_agents import generate as gen_opencode_agents
+    written, removed = gen_opencode_agents(target_dir, config_root=opencode_home)
+    msg = f"  Created: ~/.config/opencode/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+    from generate_opencode_commands import generate as gen_opencode_commands
+    written, removed = gen_opencode_commands(target_dir, config_root=opencode_home)
+    msg = f"  Created: ~/.config/opencode/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+    from generate_opencode_plugin import generate as gen_opencode_plugin
+    gen_opencode_plugin(target_dir, config_root=opencode_home)
+    print("  Created: ~/.config/opencode/plugins/ai-toolkit-hooks.js")
+
+    from generate_opencode_json import merge_into_opencode_json
+    _, count = merge_into_opencode_json(
+        target_dir, output_path=opencode_home / "opencode.json"
+    )
+    suffix = f" ({count} MCP server(s) merged)" if count else " (no MCP servers)"
+    print(f"  Created: ~/.config/opencode/opencode.json{suffix}")
+
+
 def inject_with_rules(
     generator_script: str,
     target_file: Path,
@@ -194,7 +247,7 @@ def run_script(script_name: str, *args: str, capture: bool = False) -> str:
 # All known editor identifiers for --editors flag
 ALL_EDITORS = [
     "copilot", "cursor", "windsurf", "cline", "roo",
-    "aider", "augment", "antigravity", "codex", "gemini",
+    "aider", "augment", "antigravity", "codex", "gemini", "opencode",
 ]
 
 # Map of project files/dirs → editor names for auto-detection
@@ -213,7 +266,15 @@ _EDITOR_MARKERS: dict[str, str] = {
     ".agent/rules": "antigravity",
     ".agents/skills": "codex",
     ".codex": "codex",
+    # NOTE: AGENTS.md alone is ambiguous (Codex + opencode both read it);
+    # prefer the dedicated .opencode/ and opencode.json markers when
+    # disambiguating. If only AGENTS.md is present, Codex takes precedence
+    # to preserve v2.4.x behavior.
     "AGENTS.md": "codex",
+    "opencode.json": "opencode",
+    ".opencode": "opencode",
+    ".opencode/agents": "opencode",
+    ".opencode/commands": "opencode",
 }
 
 
@@ -485,6 +546,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None) -> Non
         "aider":        "  Would generate: .aider.conf.yml + CONVENTIONS.md",
         "augment":      "  Would generate: .augment/rules/ai-toolkit-*.md",
         "antigravity":  "  Would generate: .agent/rules/ + .agent/workflows/",
+        "opencode":     "  Would generate: AGENTS.md + .opencode/{agents,commands,plugins}/ + opencode.json",
     }
     for ed, msg in _EDITOR_DRY_RUN.items():
         if ed in eds:
@@ -511,6 +573,24 @@ def _reset_local_configs(cwd: Path) -> None:
             p.unlink()
             print(f"  Removed: {rel}")
 
+    # opencode: remove only ai-toolkit-prefixed generated files so the
+    # user's own .opencode/agents/ or commands/ entries are preserved.
+    # opencode.json is left alone — it may contain user MCP servers and other
+    # project settings; reinstall re-merges our MCP entries idempotently.
+    opencode_plugin = cwd / ".opencode" / "plugins" / "ai-toolkit-hooks.js"
+    if opencode_plugin.is_file():
+        opencode_plugin.unlink()
+        print("  Removed: .opencode/plugins/ai-toolkit-hooks.js")
+    for sub in ("agents", "commands"):
+        sub_dir = cwd / ".opencode" / sub
+        if sub_dir.is_dir():
+            removed_any = False
+            for f in sorted(sub_dir.glob("ai-toolkit-*.md")):
+                f.unlink()
+                removed_any = True
+            if removed_any:
+                print(f"  Removed: .opencode/{sub}/ai-toolkit-*.md")
+
 
 def _create_local_claude_md(cwd: Path, reset: bool) -> None:
     claude_local = cwd / "CLAUDE.md"
@@ -699,6 +779,42 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         # .agents/skills/ — filtered symlinks (Codex-compatible skills only)
         _install_codex_skills(cwd)
 
+    if "opencode" in eds:
+        # AGENTS.md — shared with Codex via marker injection (opencode reads same file)
+        # Use a dedicated section tag so Codex and opencode don't clobber each other.
+        inject_with_rules(
+            "generate_opencode.py",
+            cwd / "AGENTS.md",
+            rules_dir,
+        )
+        # .opencode/agents/ — native subagents
+        from generate_opencode_agents import generate as gen_opencode_agents
+        written, removed = gen_opencode_agents(cwd)
+        msg = f"  Created: .opencode/agents/ ({written} agents"
+        if removed:
+            msg += f", {removed} stale removed"
+        msg += ")"
+        print(msg)
+        # .opencode/commands/ — native slash commands
+        from generate_opencode_commands import generate as gen_opencode_commands
+        written, removed = gen_opencode_commands(cwd)
+        msg = f"  Created: .opencode/commands/ ({written} commands"
+        if removed:
+            msg += f", {removed} stale removed"
+        msg += ")"
+        print(msg)
+        # .opencode/plugins/ai-toolkit-hooks.js — lifecycle hook bridge
+        from generate_opencode_plugin import generate as gen_opencode_plugin
+        gen_opencode_plugin(cwd)
+        print("  Created: .opencode/plugins/ai-toolkit-hooks.js")
+        # opencode.json — merge MCP servers from .mcp.json (preserves user keys)
+        from generate_opencode_json import merge_into_opencode_json
+        _, mcp_count = merge_into_opencode_json(cwd)
+        if mcp_count:
+            print(f"  Updated: opencode.json ({mcp_count} MCP server(s) from .mcp.json)")
+        else:
+            print("  Updated: opencode.json ($schema set)")
+
     synced_paths = sync_project_mcp_to_editors(cwd, sorted(eds))
     for path in synced_paths:
         rel = path.relative_to(cwd)

package/scripts/install_steps/install_state.py

@@ -89,7 +89,7 @@ def remove_mcp_template(name: str) -> None:
 DEFAULT_GLOBAL_EDITORS: list[str] = []
 
 # All editors that support global install (opt-in via --editors)
-GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "windsurf"]
+GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "opencode", "windsurf"]
 
 
 def get_global_editors() -> list[str]: