@kuznai/inception-engine 0.19.0 → 0.20.0

package/README.md

@@ -8,7 +8,7 @@ GitHub Copilot is no longer treated as a separate instruction or skill target in
 
 The broader portability layer is the roadmap direction, but this README focuses on what is working now.
 
-`init` is available as a bootstrap command. It scans for directories containing `SKILL.md`, discovers agent-rules Markdown files using the Claude-first portability conventions, and reads `mcp-servers.json` from the repo root to populate `mcpServers`. `files` and `configs` remain empty — `init` emits guidance when it detects a `files/` or `configs/` directory.
+`init` is available as a bootstrap command. It scans for directories containing `SKILL.md`, discovers agent-rules Markdown files using the Claude-first portability conventions, and reads `mcp-servers.json` from the repo root to populate `mcpServers`. Shared surfaces now default to the primary deploy target in generated manifests: for example, `init` emits `claude-code` rather than `github-copilot` for shared Claude-native skills and rules, and emits `gemini-cli` rather than `antigravity` for shared `GEMINI.md` rules surfaces. `files` and `configs` remain empty — `init` emits guidance when it detects a `files/` or `configs/` directory.
 
 ## Quick Start
 
@@ -27,7 +27,7 @@ inception-engine reads a manifest file (`inception.json`) from the target direct
 
 Managed skills overwrite their previous version. If a target exists but was not created by inception-engine, deployment refuses to replace it. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
 
-Before executing, the deploy command runs preflight analysis on instruction files: it validates that `agentRules` and `agentDefinitions` for targets requiring specific structure (like `github-copilot` and `antigravity`) include valid YAML frontmatter with `name` and `description` fields. For `github-copilot`, it further ensures either `tools` or `instructions` are defined; for `antigravity`, it validates the shape of any `mcp-servers` or `mcpServers` defined in the frontmatter. It also warns when the same agent will have multiple `agentRules` scopes active simultaneously, when the same source file is deployed to multiple scopes (duplicate-content risk), when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk), and when GitHub Copilot appears to be running under enterprise-managed policy that may override local configuration. Warnings are printed but do not block deployment; structural validation failures block deployment for the affected targets.
+Before executing, the deploy command runs preflight analysis on instruction files and capability planning inputs. It validates that `agentRules` and `agentDefinitions` for targets requiring specific structure (like `github-copilot` and `antigravity`) include valid YAML frontmatter with `name` and `description` fields. For `github-copilot`, it further ensures either `tools` or `instructions` are defined; for `antigravity`, it validates the shape of any `mcp-servers` or `mcpServers` defined in the frontmatter. It also warns when a manifest targets a surface that is implementation-only, planned, unsupported, or shared through another agent, when the same agent will have multiple `agentRules` scopes active simultaneously, when the same source file is deployed to multiple scopes (duplicate-content risk), when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk), and when GitHub Copilot appears to be running under enterprise-managed policy that may override local configuration. Warnings are printed but do not block deployment; structural validation failures block deployment for the affected targets.
 
 ## Agent Compatibility Matrix
 
@@ -50,14 +50,14 @@ Before executing, the deploy command runs preflight analysis on instruction file
 | Skills (SKILL.md) | All agents via manifest and CLI | All agents |
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
-| MCP Servers | claude-code, gemini-cli, codex, antigravity, opencode; github-copilot repo-scoped surfaces are warned and skipped | claude-code, gemini-cli, codex, antigravity, opencode |
+| MCP Servers | claude-code (`scope: "global"` → `~/.claude.json`; `scope: "repo"` → `{repo}/.claude/mcp.json`; `scope: "workspace"` → `{workspace}/.claude/mcp.json`), gemini-cli, codex, antigravity, opencode; github-copilot with `scope: "repo"` deploys to `{repo}/.vscode/mcp.json` and `scope: "workspace"` deploys to `{workspace}/.vscode/mcp.json`; github-copilot with `scope: "global"` (default) is unsupported and warns | claude-code, gemini-cli, codex, antigravity, opencode, github-copilot |
 | Global/Repo/Workspace Rules Files | `scope: "global"` and `scope: "repo"` are supported on the implemented agent surfaces; `scope: "workspace"` is supported for `claude-code`, `codex`, and `gemini-cli`; `github-copilot` reads Claude-native rules via `claude-code` and has no separate rules deployment target | All supported agents |
-| Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`); other agents are warned and skipped | claude-code, codex |
-| Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`), github-copilot (`{repo}/.github/agents/{name}.agent.md`); codex is warned and skipped | All supported agents |
-| `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), `mcp-servers.json` (`mcpServers`), and agent-definition Markdown files (`agentDefinitions`); emits hints for `files/` and `configs/` directories | N/A |
-| Instruction preflight analysis | Emits `precedence` warnings when an agent has multiple `agentRules` scopes active simultaneously or the same source file is deployed to multiple scopes; emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB; emits GitHub Copilot enterprise-policy warnings when local configuration may be overridden | N/A |
+| Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`), opencode (`~/.config/opencode/opencode.json` on POSIX, `%APPDATA%\\opencode\\opencode.json` on Windows); other agents are warned and skipped | claude-code, codex, opencode |
+| Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md` or `.toml`, plus `scope: "global"` to `~/.gemini/agents/{name}.md` or `.toml`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`, plus `scope: "global"` to the user config dir), github-copilot (`{repo}/.github/copilot/agents/{name}.md`, with migration from legacy `.github/agents/{name}.agent.md`); codex is warned and skipped | All supported agents |
+| `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), `mcp-servers.json` (`mcpServers`), and agent-definition Markdown files (`agentDefinitions`); shared surfaces default to the primary deploy target instead of shared riders; emits hints for `files/` and `configs/` directories | N/A |
+| Instruction preflight analysis | Emits capability warnings for implementation-only, planned, unsupported, and shared-through surfaces used by the manifest; emits `precedence` warnings when an agent has multiple `agentRules` scopes active simultaneously or the same source file is deployed to multiple scopes; emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB; emits GitHub Copilot enterprise-policy warnings when local configuration may be overridden; emits a `config-authority` warning when Gemini CLI's `settings.json` contains an `instructionFilename` override that differs from the deploy target | N/A |
 
-Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
+Features that depend on agent-specific config surfaces are intentionally conservative: deploy and preflight now classify each surface through the same planner. If a target path or schema is implementation-only, planned, unsupported, or only shared through another agent, inception-engine warns and either routes through the primary surface or skips it rather than guessing.
 
 For GitHub Copilot specifically, the portability rule is Claude-first: if Copilot accepts the same Claude-native instruction or skill artifact, inception-engine should not add a separate Copilot deployment feature for it.
 
@@ -95,6 +95,12 @@ Create an `inception.json` file at the root of your skills directory:
       "name": "my-server",
       "agents": ["claude-code", "gemini-cli"],
       "config": { "command": "npx", "args": ["-y", "my-mcp-server"] }
+    },
+    {
+      "name": "my-server",
+      "agents": ["github-copilot"],
+      "scope": "repo",
+      "config": { "type": "stdio", "command": "npx", "args": ["-y", "my-mcp-server"] }
     }
   ],
   "agentRules": [
@@ -160,13 +166,23 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 - **name** - Unique identifier (same format as skill names); used as the server's key in the config
 - **agents** - Array of agent IDs to register this server with
 - **config** - Raw server descriptor object. For the currently supported JSON-backed adapters, inception-engine requires at least one non-empty `command` or `url` field, validates `args` as an array of strings when present, and validates `env` as a string-to-string object when present. Additional keys are passed through verbatim.
+- **scope** - `"global"` (default), `"repo"`, or `"workspace"`. For most agents this field is ignored (they have only a single user-level config path). For `github-copilot`, `scope` selects the target file:
+  - `"global"` — unsupported; emits a warning and is skipped
+  - `"repo"` — deploys to `{repo}/.vscode/mcp.json` under the `servers` key
+  - `"workspace"` — deploys to `{workspace}/.vscode/mcp.json` under the `servers` key
 
-MCP server registration is supported for all agents except GitHub Copilot. Inception-engine automatically uses the correct adapter for each agent's configuration schema:
-- **JSON (Merge Patch)**: `claude-code` (`~/.claude.json`), `gemini-cli` (`~/.gemini/settings.json`), and `opencode` (`~/.config/opencode/opencode.json` using the custom `"mcp"` key).
+  GitHub Copilot's `.vscode/mcp.json` uses `servers` (not `mcpServers`) as the top-level key and optionally accepts a `type` field (`"stdio"` | `"sse"` | `"http"`) in the server descriptor, which is passed through verbatim.
+
+MCP server registration is supported for all agents. Inception-engine automatically uses the correct adapter for each agent's configuration schema:
+- **JSON (Merge Patch)**: `claude-code` (`~/.claude.json` for `scope: "global"`; `{repo}/.claude/mcp.json` for `scope: "repo"`; `{workspace}/.claude/mcp.json` for `scope: "workspace"`), `gemini-cli` (`~/.gemini/settings.json`), `opencode` (`~/.config/opencode/opencode.json` using the custom `"mcp"` key), and `github-copilot` (`{repo}/.vscode/mcp.json` or `{workspace}/.vscode/mcp.json` using the `"servers"` key).
 - **TOML (Patch)**: `codex` (`~/.codex/config.toml`).
 - **Markdown Frontmatter (Emit)**: `antigravity` (repo-local `.agents/rules/{name}.md` files).
 
-Revert removes the registered server entry from the respective configuration file. GitHub Copilot, which uses repo-scoped MCP surfaces not yet implemented by inception-engine, continues to emit a schema-aware warning and is skipped.
+For Markdown frontmatter targets, inception-engine now records patch-level provenance for the emitted frontmatter block. Deploy merges only the owned frontmatter keys, preserves unrelated frontmatter and Markdown body content, and `revert` removes only the engine-owned keys instead of deleting the whole file unless inception-engine originally created an otherwise-empty file.
+
+Because Antigravity currently reuses `.agents/rules/{name}.md` for both MCP frontmatter emit and agent-definition files, planning now rejects a manifest when an `mcpServers` entry and an `agentDefinitions` entry would resolve to the same Antigravity target.
+
+Revert removes the registered server entry from the respective configuration file or frontmatter block.
 
 Each **agentRules** entry deploys a Markdown instruction file to an agent's supported instruction file location:
 
@@ -232,20 +248,28 @@ Valid `approval_policy` values are `"auto"`, `"manual"`, `"suggest"`, and `"on-f
 
 Revert restores the previous config values using the undo patch recorded at deploy time.
 
-Each **agentDefinitions** entry deploys a Markdown agent-definition file to the repo-local agent-definitions directory of each targeted agent:
+Each **agentDefinitions** entry deploys an agent-definition file to the agent-definition directory of each targeted agent. `scope: "repo"` is the default, and some agents also support `scope: "global"`:
 
 - **name** - Unique identifier (same format as skill names); used as the definition filename
-- **path** - Relative path to the source Markdown file within the repo; must be a `.md` or `.markdown` file
+- **path** - Relative path to the source file within the repo; `.md` or `.markdown` for Markdown definitions, `.toml` for Gemini CLI TOML subagent definitions
 - **agents** - Array of agent IDs to deploy this definition to
 
-Agent-definition deployment is supported for `claude-code`, `gemini-cli`, `antigravity`, `opencode`, and `github-copilot`. For `codex`, inception-engine emits a warning and skips the entry — use `agentRules` to deploy persona instructions to Codex instead.
+Agent-definition deployment is supported for `claude-code`, `gemini-cli`, `antigravity`, `opencode`, and `github-copilot`. For `codex`, inception-engine emits a warning and skips the entry. Gemini CLI and OpenCode also support `scope: "global"` definitions; other supported agents are repo-local only.
+
+Gemini CLI supports two definition formats: Markdown (`.md`) files deploy to `{scope}/.gemini/agents/{name}.md`, and TOML (`.toml`) subagent configuration files deploy to `{scope}/.gemini/agents/{name}.toml`. TOML files are deployed verbatim without frontmatter validation. Agents other than `gemini-cli` that do not have a TOML definition surface silently produce no action when a `.toml` source is specified.
 
-All targets are repo-local (they land inside the repository being deployed, not the user's home directory):
+Repo-local targets:
 - **claude-code**: `{repo}/.claude/agents/{name}.md`
-- **gemini-cli**: `{repo}/.gemini/agents/{name}.md`
+- **gemini-cli**: `{repo}/.gemini/agents/{name}.md` (Markdown) or `{repo}/.gemini/agents/{name}.toml` (TOML)
 - **antigravity**: `{repo}/.agents/rules/{name}.md`
 - **opencode**: `{repo}/.opencode/agents/{name}.md`
-- **github-copilot**: `{repo}/.github/agents/{name}.agent.md` (note the `.agent.md` suffix)
+- **github-copilot**: `{repo}/.github/copilot/agents/{name}.md`
+
+Global targets where supported:
+- **gemini-cli**: `~/.gemini/agents/{name}.md` or `~/.gemini/agents/{name}.toml`
+- **opencode**: `~/.config/opencode/agents/{name}.md` on POSIX, `%APPDATA%\\opencode\\agents\\{name}.md` on Windows
+
+For GitHub Copilot, deploy also records migration from the legacy `{repo}/.github/agents/{name}.agent.md` path so older installs can be cleaned up safely.
 
 Revert removes the deployed agent-definition file.
 
@@ -277,11 +301,11 @@ Current `init` behavior:
 - Applies either the `--agents` list or all currently known agent IDs
 - Refuses to overwrite an existing `inception.json` unless `--force` is provided
 - Supports `--plan` so you can inspect the generated manifest before writing it
-- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`), mapping them to agents using Claude-first portability conventions: `copilot-instructions.md` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), and the fallback for unrecognized files excludes agents whose agentRules surface is unsupported
+- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`), mapping them to agents using Claude-first portability conventions: `copilot-instructions.md` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), and the fallback for unrecognized files excludes unsupported agents plus shared-surface riders that should default to their primary deploy target
 - Reads `mcp-servers.json` from the repo root (if present) and generates `mcpServers` entries; invalid entries are warned and skipped
 - Reads `files-manifest.json` from the repo root (if present) and generates `files` entries; invalid entries are warned and skipped
 - Reads `configs-manifest.json` from the repo root (if present) and generates `configs` entries; invalid entries are warned and skipped
-- Reads `agent-definitions-manifest.json` from the repo root (if present) and generates `agentDefinitions` entries; if absent, auto-discovers agent-definition Markdown files from `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, and `.github/agents/`; invalid entries are warned and skipped
+- Reads `agent-definitions-manifest.json` from the repo root (if present) and generates `agentDefinitions` entries; if absent, auto-discovers agent-definition Markdown files from `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, `.github/copilot/agents/`, and legacy `.github/agents/`; invalid entries are warned and skipped
 - Emits guidance to create a sidecar manifest when a `files/` or `configs/` directory is detected but the corresponding sidecar file is absent
 
 Current `init` limitations:
@@ -343,10 +367,12 @@ Place an `agent-definitions-manifest.json` file at the repo root to have `init`
 ]
 ```
 
-If no `agent-definitions-manifest.json` is present, `init` auto-discovers agent-definition Markdown files from five conventional subdirectories: `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, and `.github/agents/`. Each discovered file is mapped to the owning agent(s). GitHub Copilot files named `{name}.agent.md` have the `.agent` infix stripped to derive the manifest name (e.g., `foo.agent.md` → name `foo`).
+If no `agent-definitions-manifest.json` is present, `init` auto-discovers agent-definition Markdown files from six conventional subdirectories: `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, `.github/copilot/agents/`, and legacy `.github/agents/`. Each discovered file is mapped to the owning agent(s). GitHub Copilot files named `{name}.agent.md` in the legacy directory have the `.agent` infix stripped to derive the manifest name (e.g., `foo.agent.md` -> name `foo`).
 
 Invalid entries are warned and skipped; the rest are written into the generated manifest verbatim.
 
+For shared surfaces, `init` prefers the primary deploy target instead of emitting both agents. That means generated `skills` entries exclude `github-copilot` in favor of `claude-code`, and generated shared `GEMINI.md` `agentRules` entries exclude `antigravity` in favor of `gemini-cli`. This keeps starter manifests minimal while preserving deploy behavior for explicitly authored shared-rider entries.
+
 ## CLI Reference
 
 ```
@@ -433,11 +459,11 @@ Revert targets all agents listed in the manifest by default (regardless of detec
 
 ### Ownership Tracking and Safe Revert
 
-inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, skill name, agent ID, action-specific provenance (`source`/`method` for skill-dir, `source` for file-write, `patch`/`undoPatch` for config-patch), and timestamp. No files are written to the source repository.
+inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, skill name, agent ID, action-specific provenance (`source`/`method` for skill-dir, `source` for file-write, `patch`/`undoPatch` for config-patch, `patch`/`undoPatch` plus frontmatter-shape metadata for frontmatter-emit), and timestamp. Registry entries also carry a stable surface ID so future surface migrations can preserve ownership continuity. No files are written to the source repository.
 
 - **Registry-based ownership**: On revert, the registry is checked before removing any target. Only targets with a valid registry entry are removed. On redeploy, unmanaged targets are never replaced.
 
-- **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind. For `skill-dir` and `file-write`, ownership checks also require the recorded `source` to match before an existing target is treated as managed. For `config-patch`, overwrite protection is keyed by target path, kind, skill, and agent; the stored `patch` and `undoPatch` are used for revert bookkeeping rather than deploy-time identity checks.
+- **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind. For `skill-dir` and `file-write`, ownership checks also require the recorded `source` to match before an existing target is treated as managed. For `config-patch` and `frontmatter-emit`, overwrite protection is keyed by target path, kind, skill, and agent; the stored `patch` and `undoPatch` are used for patch-level revert bookkeeping rather than deploy-time identity checks.
 
 - **Atomic redeploy**: When overwriting an existing managed `skill-dir` target, the engine renames the old target to a backup, creates the new deployment, and only removes the backup on success. If the new deployment fails, the backup is restored. `file-write` and `config-patch` deployments write directly to the target without this backup/rollback model.
 

package/dist/{config → src/config}/agents.js

@@ -28,6 +28,22 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude.json"],
             },
         },
+        mcpRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local .claude/mcp.json",
+            path: {
+                posix: ["{repo}", ".claude", "mcp.json"],
+                windows: ["{repo}", ".claude", "mcp.json"],
+            },
+        },
+        mcpWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local .claude/mcp.json",
+            path: {
+                posix: ["{workspace}", ".claude", "mcp.json"],
+                windows: ["{workspace}", ".claude", "mcp.json"],
+            },
+        },
         agentRulesSupport: {
             status: "supported",
             schemaLabel: "global Markdown rules file",
@@ -52,7 +68,7 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude", "settings.json"],
             },
         },
-        agentDefinitionsSupport: {
+        agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
             path: {
@@ -120,7 +136,7 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".codex", "config.toml"],
             },
         },
-        agentDefinitionsSupport: {
+        agentDefinitionsRepoSupport: {
             status: "unsupported",
             schemaLabel: "dedicated agent definition directory",
             reason: "OpenAI Codex does not expose a documented dedicated per-agent definition directory surface separate from AGENTS.md and config.toml — use agentRules to deploy persona instructions instead",
@@ -152,7 +168,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             mcpConfig: "documented",
             agentRules: "documented",
-            agentDefinitions: "implementation-only",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -162,6 +178,9 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".gemini", "settings.json"],
             },
         },
+        // NOTE: Gemini CLI also reads AGENTS.md as a fallback when GEMINI.md is absent.
+        // inception-engine intentionally targets GEMINI.md to avoid ownership collisions
+        // with codex and opencode, which also write AGENTS.md.
         agentRulesSupport: {
             status: "supported",
             schemaLabel: "global Markdown rules file",
@@ -184,6 +203,14 @@ export const AGENT_REGISTRY = [
             reason: "Gemini CLI does not expose a documented global per-user permission or approval config surface",
         },
         agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "global agent definition Markdown file",
+            path: {
+                posix: ["{home}", ".gemini", "agents", "{name}.md"],
+                windows: ["{home}", ".gemini", "agents", "{name}.md"],
+            },
+        },
+        agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
             path: {
@@ -191,6 +218,22 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".gemini", "agents", "{name}.md"],
             },
         },
+        agentDefinitionsTomlSupport: {
+            status: "supported",
+            schemaLabel: "global agent definition TOML file",
+            path: {
+                posix: ["{home}", ".gemini", "agents", "{name}.toml"],
+                windows: ["{home}", ".gemini", "agents", "{name}.toml"],
+            },
+        },
+        agentDefinitionsTomlRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition TOML file",
+            path: {
+                posix: ["{repo}", ".gemini", "agents", "{name}.toml"],
+                windows: ["{repo}", ".gemini", "agents", "{name}.toml"],
+            },
+        },
         agentRulesWorkspaceSupport: {
             status: "supported",
             schemaLabel: "workspace-local GEMINI.md",
@@ -253,7 +296,7 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "Antigravity does not expose a documented global per-user permission or approval config surface",
         },
-        agentDefinitionsSupport: {
+        agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
             path: {
@@ -286,6 +329,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentRules: "documented",
             agentDefinitions: "documented",
+            permissions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -313,11 +357,22 @@ export const AGENT_REGISTRY = [
             },
         },
         permissionsSupport: {
-            status: "unsupported",
-            schemaLabel: "global permissions surface",
-            reason: "OpenCode does not expose a documented global per-user permission or approval config surface",
+            status: "supported",
+            schemaLabel: "opencode.json permissions config",
+            path: {
+                posix: ["{xdg_config}", "opencode", "opencode.json"],
+                windows: ["{appdata}", "opencode", "opencode.json"],
+            },
         },
         agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "global agent definition Markdown file",
+            path: {
+                posix: ["{xdg_config}", "opencode", "agents", "{name}.md"],
+                windows: ["{appdata}", "opencode", "agents", "{name}.md"],
+            },
+        },
+        agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
             path: {
@@ -348,12 +403,30 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
             agentDefinitions: "documented",
+            mcpConfig: "documented",
         },
         mcpSupport: {
-            status: "planned",
-            schemaLabel: "repo-scoped MCP surfaces",
-            plannedSurface: "devcontainer (.devcontainer/devcontainer.json) and agent-frontmatter (.github/agents/*.agent.md)",
-            reason: "GitHub Copilot MCP support will be implemented via repo-scoped devcontainer features and agent-frontmatter mappings — surfaces that are genuinely Copilot-specific and not covered by other agent targets",
+            status: "unsupported",
+            schemaLabel: "global MCP config",
+            reason: 'GitHub Copilot has no user-level MCP config file; use scope: "repo" or scope: "workspace" to target .vscode/mcp.json instead',
+        },
+        mcpRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local .vscode/mcp.json",
+            mcpPatchKey: "servers",
+            path: {
+                posix: ["{repo}", ".vscode", "mcp.json"],
+                windows: ["{repo}", ".vscode", "mcp.json"],
+            },
+        },
+        mcpWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local .vscode/mcp.json",
+            mcpPatchKey: "servers",
+            path: {
+                posix: ["{workspace}", ".vscode", "mcp.json"],
+                windows: ["{workspace}", ".vscode", "mcp.json"],
+            },
         },
         // GitHub Copilot reads Claude-native instruction files (CLAUDE.md) without
         // a separate deploy action. These surfaces are marked shared-via claude-code
@@ -404,12 +477,12 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "GitHub Copilot permissions are managed via organization policy, not a deployable per-user config surface",
         },
-        agentDefinitionsSupport: {
+        agentDefinitionsRepoSupport: {
             status: "supported",
             schemaLabel: "repo-local agent definition Markdown file",
             path: {
-                posix: ["{repo}", ".github", "agents", "{name}.agent.md"],
-                windows: ["{repo}", ".github", "agents", "{name}.agent.md"],
+                posix: ["{repo}", ".github", "copilot", "agents", "{name}.md"],
+                windows: ["{repo}", ".github", "copilot", "agents", "{name}.md"],
             },
         },
         policyNote: "Organization policies may override locally deployed configuration. Verify with your GitHub org admin if deployed skills or rules are not active.",

package/dist/{core → src/core}/adapters/agent-definitions.d.ts

@@ -4,17 +4,5 @@ export interface AgentDefinitionsAdapterResult {
     actions: FileWriteDeployAction[];
     warnings: PlanWarning[];
 }
-/**
- * Compiles deploy actions for agentDefinitions manifest entries.
- *
- * Agent definition files are Markdown files (typically with YAML frontmatter)
- * that define custom agents or subagents for a given platform. Unlike
- * agentRules (which target a single shared global file per agent), each
- * definition entry produces a separate file named after the entry in the
- * agent's dedicated agent-definitions directory (repo-local).
- *
- * Target paths use the `{repo}` placeholder so definitions land in the
- * repository being deployed, not the user's home directory.
- */
 export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<AgentDefinitionsAdapterResult>;
 export declare function compileAgentDefinitionReverts(entry: AgentDefinitionEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

package/dist/src/core/adapters/agent-definitions.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+/**
+ * Compiles deploy actions for agentDefinitions manifest entries.
+ *
+ * Agent definition files are Markdown (typically with YAML frontmatter) or
+ * TOML files that define custom agents or subagents for a given platform.
+ * Unlike agentRules (which target a single shared global file per agent),
+ * each definition entry produces a separate file named after the entry in
+ * the agent's dedicated agent-definitions directory.
+ *
+ * Target paths use the `{repo}` placeholder so definitions land in the
+ * repository being deployed, not the user's home directory.
+ *
+ * TOML source files (e.g. Gemini CLI `.gemini/agents/*.toml`) bypass
+ * Markdown-specific validation and are deployed verbatim.
+ */
+/**
+ * Returns the TOML-specific surface for an agent (global or repo-local),
+ * or undefined when the agent has no TOML definition surface.
+ */
+function resolveTomlDefinitionsSurface(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent)
+        return undefined;
+    const tomlSupport = scope === "repo"
+        ? (agent.agentDefinitionsTomlRepoSupport ??
+            agent.agentDefinitionsTomlSupport)
+        : agent.agentDefinitionsTomlSupport;
+    if (!tomlSupport || tomlSupport.status !== "supported")
+        return undefined;
+    return tomlSupport;
+}
+/** Returns a warning when the requested scope cannot be resolved, or null when it is fine. */
+function scopeAvailabilityWarning(entry, agentId, repo, workspace) {
+    if (entry.scope === "repo" && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentDefinitions: scope "repo" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    if (entry.scope === "workspace" && !workspace && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentDefinitions: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    return null;
+}
+function resolveSupportedTargets(entry, targetAgents, home, repo, workspace) {
+    const targets = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const agentId of targetAgents) {
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "agentDefinitions",
+            entryName: entry.name,
+            targetAgentIds: targetAgents,
+            scope: entry.scope,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
+            continue;
+        }
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        // For TOML sources, use the agent's TOML-specific surface instead of the
+        // default Markdown surface. Agents without a TOML surface are skipped.
+        const support = isToml
+            ? resolveTomlDefinitionsSurface(agentId, entry.scope)
+            : resolveCapabilitySurface(agentId, "agentDefinitions", entry.scope)
+                .support;
+        if (!support)
+            continue;
+        const scopeWarning = scopeAvailabilityWarning(entry, agentId, repo, workspace);
+        if (scopeWarning) {
+            warnings.push(scopeWarning);
+            continue;
+        }
+        targets.push({
+            agentId,
+            confidence: plan.confidence ?? "provisional",
+            target: resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace),
+        });
+    }
+    return { targets, warnings };
+}
+async function createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace) {
+    const actions = [];
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const target of supportedTargets) {
+        // TOML definition files have no YAML frontmatter — skip Markdown validation.
+        if (!isToml) {
+            validateAgentRuleMarkdownPath(entry.path, target.agentId);
+            await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        }
+        let migratedFrom;
+        if (target.agentId === "github-copilot") {
+            migratedFrom = [
+                resolvePlaceholders(["{repo}", ".github", "agents", "{name}.agent.md"], entry.name, home, repo, workspace),
+            ];
+        }
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: target.agentId,
+            source,
+            target: target.target,
+            confidence: target.confidence,
+            migratedFrom,
+        });
+    }
+    return actions;
+}
+export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
+    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    if (targetAgents.length === 0) {
+        return { actions: [], warnings: [] };
+    }
+    const { targets: supportedTargets, warnings } = resolveSupportedTargets(entry, targetAgents, home, repo, workspace);
+    if (supportedTargets.length === 0) {
+        return { actions: [], warnings };
+    }
+    // Validate the shared source file only when at least one target is active.
+    const source = path.resolve(sourceDir, entry.path);
+    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSourceFile(source, entry.path);
+    const actions = await createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace);
+    return { actions, warnings };
+}
+export function compileAgentDefinitionReverts(entry, agentFilter, home, repo, workspace) {
+    const actions = [];
+    const platform = getPlatformKey();
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const support = isToml
+            ? resolveTomlDefinitionsSurface(agentId, entry.scope)
+            : resolveCapabilitySurface(agentId, "agentDefinitions", entry.scope)
+                .support;
+        if (!support)
+            continue;
+        if (entry.scope === "repo" && !repo)
+            continue;
+        if (entry.scope === "workspace" && !workspace && !repo)
+            continue;
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

package/dist/{core → src/core}/adapters/frontmatter.d.ts

@@ -12,6 +12,7 @@ export declare function splitFrontmatter(raw: string): {
 export declare function parseFrontmatterDocument<T = Record<string, unknown>>(raw: string): {
     attributes: T;
     body: string;
+    hasFrontmatter: boolean;
 };
 /**
  * Serializes an object to a YAML block.
@@ -21,6 +22,9 @@ export declare function serializeFrontmatter(data: Record<string, unknown>): str
  * Builds the full content of a frontmatter-bearing Markdown file.
  */
 export declare function buildFrontmatterDocument(frontmatter: Record<string, unknown>, body?: string): string;
+export declare function buildMarkdownDocument(frontmatter: Record<string, unknown>, body?: string, options?: {
+    hasFrontmatter?: boolean;
+}): string;
 /**
  * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
@@ -29,6 +33,12 @@ export declare function readFrontmatterFile(filePath: string): Promise<{
     attributes: Record<string, unknown>;
     body: string;
 }>;
+export declare function readFrontmatterDocumentFile(filePath: string): Promise<{
+    exists: boolean;
+    hasFrontmatter: boolean;
+    attributes: Record<string, unknown>;
+    body: string;
+}>;
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional
  * body. Preserves any existing body content when `preserveBody` is true.

package/dist/{core → src/core}/adapters/frontmatter.js

@@ -26,10 +26,10 @@ export function splitFrontmatter(raw) {
 export function parseFrontmatterDocument(raw) {
     const { frontmatter, body } = splitFrontmatter(raw);
     if (!(frontmatter || raw.startsWith("---"))) {
-        return { attributes: {}, body };
+        return { attributes: {}, body, hasFrontmatter: false };
     }
     const attributes = YAML.parse(frontmatter);
-    return { attributes: (attributes || {}), body };
+    return { attributes: (attributes || {}), body, hasFrontmatter: true };
 }
 /**
  * Serializes an object to a YAML block.
@@ -42,9 +42,15 @@ export function serializeFrontmatter(data) {
  * Builds the full content of a frontmatter-bearing Markdown file.
  */
 export function buildFrontmatterDocument(frontmatter, body = "") {
+    return buildMarkdownDocument(frontmatter, body, { hasFrontmatter: true });
+}
+export function buildMarkdownDocument(frontmatter, body = "", options = {}) {
+    const cleanBody = body.trimStart();
+    if (Object.keys(frontmatter).length === 0 && !options.hasFrontmatter) {
+        return cleanBody;
+    }
     const serialized = serializeFrontmatter(frontmatter);
     // Ensure exactly one newline after the closing delimiter before the body
-    const cleanBody = body.trimStart();
     const separator = cleanBody ? "\n\n" : "\n";
     return `---\n${serialized}\n---\n${separator}${cleanBody}`;
 }
@@ -58,17 +64,28 @@ function createAtomicTempPath(targetPath) {
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export async function readFrontmatterFile(filePath) {
+    const document = await readFrontmatterDocumentFile(filePath);
+    return { attributes: document.attributes, body: document.body };
+}
+export async function readFrontmatterDocumentFile(filePath) {
     let raw;
     try {
         raw = await readFile(filePath, "utf-8");
     }
     catch (err) {
         const code = err.code;
-        if (code === "ENOENT")
-            return { attributes: {}, body: "" };
+        if (code === "ENOENT") {
+            return {
+                exists: false,
+                hasFrontmatter: false,
+                attributes: {},
+                body: "",
+            };
+        }
         throw err;
     }
-    return parseFrontmatterDocument(raw);
+    const parsed = parseFrontmatterDocument(raw);
+    return { exists: true, ...parsed };
 }
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional