@kuznai/inception-engine 0.18.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 warns when the same agent will have both global and repo `agentRules` active simultaneously, when the same source file is deployed to both scopes (duplicate-content risk), and when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk). Warnings are printed but do not block deployment.
+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 |
-| Global/Repo Rules Files | All agents via `scope: "global"` (home-dir) or `scope: "repo"` (project-root); antigravity always uses repo-local `.agents/rules/`; github-copilot reads CLAUDE.md natively (deploy via claude-code) | All 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 both global and repo `agentRules` active simultaneously (stacking advisory) or the same source file deployed to both scopes (duplicate-content warning); emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB | N/A |
+| 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`), 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,35 +166,46 @@ 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:
 
 - **name** - Unique identifier (same format as skill names)
 - **path** - Relative path to the source Markdown file within the repo; supported rules adapters require a `.md` or `.markdown` source path
 - **agents** - Array of agent IDs to deploy this file to
-- **scope** - `"global"` (default) or `"repo"`. Controls which instruction surface is targeted:
-  - `"global"` — deploys to the agent's home-directory instruction file (e.g., `~/.claude/CLAUDE.md` for `claude-code`)
-  - `"repo"` — deploys to the project-root instruction file inside the deployed repository (e.g., `{repo}/CLAUDE.md` for `claude-code`)
+- **scope** - `"global"` (default), `"repo"`, or `"workspace"`. Controls which instruction surface is targeted:
+  - `"global"` — deploys to the agent's home-directory instruction file when that surface is supported (e.g., `~/.claude/CLAUDE.md` for `claude-code`)
+  - `"repo"` — deploys to the project-root instruction file inside the deployed repository when that surface is supported (e.g., `{repo}/CLAUDE.md` for `claude-code`)
+  - `"workspace"` — deploys to the workspace-root instruction file when an agent exposes one (e.g., `{workspace}/CLAUDE.md` for `claude-code`); when unsupported, deployment is skipped with a warning
 
-Instruction rule deployment is supported for all agents. The target path depends on the agent and the `scope`:
+Instruction rule deployment is supported for implemented global, repo, and workspace surfaces. The target path depends on the agent and the `scope`:
 
-| Agent | `scope: "global"` | `scope: "repo"` |
-|---|---|---|
-| `claude-code` | `~/.claude/CLAUDE.md` | `{repo}/CLAUDE.md` |
-| `codex` | `~/.codex/AGENTS.md` | `{repo}/AGENTS.md` |
-| `gemini-cli` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` |
-| `antigravity` | `{repo}/.agents/rules/{name}.md` | `{repo}/.agents/rules/{name}.md` |
-| `opencode` | `~/.config/opencode/AGENTS.md` | `{repo}/AGENTS.md` |
-| `github-copilot` | unsupported — reads `CLAUDE.md` natively | unsupported — deploy via `claude-code` |
+| Agent | `scope: "global"` | `scope: "repo"` | `scope: "workspace"` |
+|---|---|---|---|
+| `claude-code` | `~/.claude/CLAUDE.md` | `{repo}/CLAUDE.md` | `{workspace}/CLAUDE.md` |
+| `codex` | `~/.codex/AGENTS.md` | `{repo}/AGENTS.md` | `{workspace}/AGENTS.md` |
+| `gemini-cli` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` | `{workspace}/GEMINI.md` |
+| `antigravity` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` | unsupported; warns and skips |
+| `opencode` | `~/.config/opencode/AGENTS.md` | `{repo}/AGENTS.md` | unsupported; warns and skips |
+| `github-copilot` | unsupported / Claude-first | deploy via `claude-code` | unsupported; deploy via `claude-code` with `scope: "workspace"` |
 
-For `antigravity`, both scopes target the same repo-local surface (`{repo}/.agents/rules/{name}.md`) since Antigravity has no global home-directory instruction file. For `github-copilot`, no separate deployment is needed for either scope — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
+For `antigravity`, `agentRules` now targets the shared GEMINI.md surface (`~/.gemini/GEMINI.md` for `global`, `{repo}/GEMINI.md` for `repo`) — the same paths used by `gemini-cli`. When both agents appear in the same entry, deduplication ensures only one write action is emitted. `workspace` scope is not supported and is skipped with a warning. For `github-copilot`, no separate deployment is needed — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
 
 Each **permissions** entry deploys execution and safety-oriented configuration to an agent's permission or approval surface:
 
@@ -231,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.
 
@@ -275,12 +300,12 @@ Current `init` behavior:
 - Uses the directory name as the manifest skill name
 - Applies either the `--agents` list or all currently known agent IDs
 - Refuses to overwrite an existing `inception.json` unless `--force` is provided
-- Supports `--dry-run` so you can inspect the generated manifest before writing it
-- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`, `.agents/rules/`), 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
+- 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 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:
@@ -342,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
 
 ```
@@ -366,13 +393,15 @@ inception-engine init <directory> [options]
 
 | Option | Description |
 |---|---|
-| `--dry-run` | Show what would be done without making changes |
+| `--plan` | Show what would be done without making changes |
 | `--agents <list>` | Comma-separated list of agent IDs to target (overrides deploy detection; restricts revert) |
 | `--force` | `init` only; overwrite an existing `inception.json` |
 | `--verbose` | Show detailed output including file paths |
 | `--debug` | Show full error stack traces |
 | `--help` | Show help message |
 
+With `--plan`, deploy and revert print a grouped action preview by agent. Each planned change includes the source path when applicable, the resolved target path, and action-specific details such as JSON/TOML patch payloads or emitted frontmatter content.
+
 ### Examples
 
 ```bash
@@ -380,7 +409,7 @@ inception-engine init <directory> [options]
 npx @kuznai/inception-engine ./my-skills-repo
 
 # Preview what would be deployed
-npx @kuznai/inception-engine ./my-skills-repo --dry-run
+npx @kuznai/inception-engine ./my-skills-repo --plan
 
 # Deploy only to Claude Code and Codex
 npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
@@ -389,13 +418,13 @@ npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
 npx @kuznai/inception-engine revert ./my-skills-repo
 
 # Preview what would be removed
-npx @kuznai/inception-engine revert ./my-skills-repo --dry-run
+npx @kuznai/inception-engine revert ./my-skills-repo --plan
 
 # Generate a starter manifest from discovered skill folders
 npx @kuznai/inception-engine init ./my-skills-repo
 
 # Preview the generated manifest without writing it
-npx @kuznai/inception-engine init ./my-skills-repo --dry-run
+npx @kuznai/inception-engine init ./my-skills-repo --plan
 ```
 
 ## Sample Skills
@@ -405,8 +434,8 @@ The `limbo/` directory contains exceptional sample skills for testing purposes o
 Try them out:
 
 ```bash
-npx @kuznai/inception-engine init limbo --dry-run
-npx @kuznai/inception-engine limbo --dry-run
+npx @kuznai/inception-engine init limbo --plan
+npx @kuznai/inception-engine limbo --plan
 ```
 
 ## Agent Detection
@@ -430,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: {
@@ -60,6 +76,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".claude", "agents", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local CLAUDE.md",
+            path: {
+                posix: ["{workspace}", "CLAUDE.md"],
+                windows: ["{workspace}", "CLAUDE.md"],
+            },
+        },
     },
     {
         id: "codex",
@@ -112,11 +136,19 @@ 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",
         },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local AGENTS.md",
+            path: {
+                posix: ["{workspace}", "AGENTS.md"],
+                windows: ["{workspace}", "AGENTS.md"],
+            },
+        },
     },
     {
         id: "gemini-cli",
@@ -136,7 +168,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             mcpConfig: "documented",
             agentRules: "documented",
-            agentDefinitions: "implementation-only",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -146,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",
@@ -168,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: {
@@ -175,6 +218,30 @@ 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",
+            path: {
+                posix: ["{workspace}", "GEMINI.md"],
+                windows: ["{workspace}", "GEMINI.md"],
+            },
+        },
     },
     {
         id: "antigravity",
@@ -203,20 +270,25 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".agents", "rules", "{name}.md"],
             },
         },
+        // Antigravity shares its instruction surfaces with gemini-cli (both target
+        // the same GEMINI.md paths). surfaceKind: shared-via drives deduplication
+        // when both agents appear in the same agentRules entry.
         agentRulesSupport: {
             status: "supported",
-            schemaLabel: "repo-local Markdown rules file",
+            surfaceKind: { kind: "shared-via", via: "gemini-cli" },
+            schemaLabel: "global Gemini blueprint instructions file",
             path: {
-                posix: ["{repo}", ".agents", "rules", "{name}.md"],
-                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+                posix: ["{home}", ".gemini", "GEMINI.md"],
+                windows: ["{home}", ".gemini", "GEMINI.md"],
             },
         },
         agentRulesRepoSupport: {
             status: "supported",
-            schemaLabel: "repo-local Markdown rules file",
+            surfaceKind: { kind: "shared-via", via: "gemini-cli" },
+            schemaLabel: "repo-local GEMINI.md",
             path: {
-                posix: ["{repo}", ".agents", "rules", "{name}.md"],
-                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+                posix: ["{repo}", "GEMINI.md"],
+                windows: ["{repo}", "GEMINI.md"],
             },
         },
         permissionsSupport: {
@@ -224,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: {
@@ -232,6 +304,12 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".agents", "rules", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "unsupported",
+            schemaLabel: "workspace-local instruction surface",
+            reason: "Antigravity is natively repo-local and does not expose a separate workspace-local instruction surface",
+        },
+        instructionFrontmatterRequired: true,
     },
     {
         id: "opencode",
@@ -251,6 +329,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentRules: "documented",
             agentDefinitions: "documented",
+            permissions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -278,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: {
@@ -290,6 +380,11 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".opencode", "agents", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "unsupported",
+            schemaLabel: "workspace-local AGENTS.md",
+            reason: "OpenCode does not expose a documented workspace-local instruction surface distinct from repo-local AGENTS.md",
+        },
     },
     {
         id: "github-copilot",
@@ -298,6 +393,7 @@ export const AGENT_REGISTRY = [
         // from `.claude/skills/` (the same path used by claude-code). Deploying
         // via the `claude-code` skills target automatically covers Copilot — no
         // separate `~/.copilot/skills/` path is needed or maintained.
+        skillsSurfaceKind: { kind: "shared-via", via: "claude-code" },
         detectPaths: {
             posix: ["{home}", ".copilot"],
             windows: ["{home}", ".copilot"],
@@ -307,37 +403,91 @@ 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
+        // with requiresPrimary: true so deploy skips emitting a separate action
+        // when claude-code is also targeted, and emits a guidance warning when it
+        // is not (copilot cannot write to these surfaces independently).
         agentRulesSupport: {
-            status: "unsupported",
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
             schemaLabel: "Claude-native shared instructions",
-            reason: 'GitHub Copilot reads CLAUDE.md natively, so deploy via the "claude-code" agentRules target instead of a separate rules surface',
+            path: {
+                posix: ["{home}", ".claude", "CLAUDE.md"],
+                windows: ["{home}", ".claude", "CLAUDE.md"],
+            },
         },
         agentRulesRepoSupport: {
-            status: "unsupported",
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
             schemaLabel: "repo-local CLAUDE.md",
-            reason: 'GitHub Copilot reads CLAUDE.md natively, so deploy via the "claude-code" agentRules target with scope: "repo" instead of a separate rules surface',
+            path: {
+                posix: ["{repo}", "CLAUDE.md"],
+                windows: ["{repo}", "CLAUDE.md"],
+            },
+        },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
+            schemaLabel: "workspace-local CLAUDE.md",
+            path: {
+                posix: ["{workspace}", "CLAUDE.md"],
+                windows: ["{workspace}", "CLAUDE.md"],
+            },
         },
         permissionsSupport: {
             status: "unsupported",
             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.",
+        instructionFrontmatterRequired: true,
+        enterprisePolicyDetection: true,
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

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

@@ -0,0 +1,8 @@
+import type { AgentDefinitionEntry } from "../../schemas/manifest.ts";
+import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
+export interface AgentDefinitionsAdapterResult {
+    actions: FileWriteDeployAction[];
+    warnings: PlanWarning[];
+}
+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[];