getsentry · mishamilovidov · Aug 24, 2026 · Sep 2, 2026 · Sep 8, 2026 · Sep 9, 2026
diff --git a/README.md b/README.md
@@ -155,7 +155,7 @@ dotagents can also import native runtime subagent files from `.claude/agents/`,
 
 OpenCode reuses an existing project config from `.opencode/opencode.jsonc`, `.opencode/opencode.json`, `opencode.jsonc`, or `opencode.json`, in that order. New projects use `.opencode/opencode.jsonc`.
 
-Plugins are declared with `[[plugins]]` entries. In project scope, dotagents installs canonical bundles into `.agents/plugins/<name>/` and generates runtime plugin outputs such as `.claude-plugin/marketplace.json`, `.github/plugin/marketplace.json`, `.cursor-plugin/marketplace.json`, `.agents/plugins/marketplace.json`, native Claude, Cursor, and Codex manifests, `.grok/plugins/<name>/`, `.opencode/skills/<skill>/`, OpenCode MCP entries, and Pi skill links under `.agents/skills/<skill>/`. During legacy migration, generalized bundles can also project Markdown agents into `.opencode/agents/`; standard extension agents are preserved but are not projected yet:
+Plugins are declared with `[[plugins]]` entries. In project scope, dotagents installs canonical bundles into `.agents/plugins/<name>/`. It generates marketplaces for Claude, Cursor, Codex, and Copilot. Claude, Cursor, and Codex also receive native manifests when required. Grok receives a managed copy. OpenCode receives skill links and MCP entries. Pi receives skill links under `.agents/skills/<skill>/`. During legacy migration, generalized bundles can also project Markdown agents into `.opencode/agents/`. Standard extension agents are preserved but are not projected yet:
 
 ```toml
 [[plugins]]
@@ -169,6 +169,23 @@ The canonical portable format is an [Agent Plugins](https://agent-plugins.org/)
 
 Global plugins install canonical bundles under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated under `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`, and Codex uses `~/.agents/plugins/marketplace.json`. Grok plugins are copied into `~/.grok/plugins/`. OpenCode skills are linked into `~/.config/opencode/skills/`, and portable MCP servers are merged into `~/.config/opencode/opencode.json`. Pi skills are linked into `~/.agents/skills/`. `--user` remains a compatibility alias for `--global`.
 
+### Plugin activation
+
+Dotagents plugin installation and native client installation are separate stages. `dotagents add` and `dotagents install` install the canonical bundle and write each selected runtime output. Marketplace-based clients still require native registration and installation.
+
+| Agent ID | Dotagents output | Native action |
+| --- | --- | --- |
+| `claude` | Generated marketplace and native manifest when required | Register the Dotagents root, then install `<name>@dotagents` with the Claude CLI. |
+| `cursor` | Generated marketplace and native manifest when required | Use Customize, a team marketplace, `~/.cursor/plugins/local`, or `cursor-agent --plugin-dir`. Cursor has no marketplace CLI command. |
+| `codex` | Generated `.agents/plugins/marketplace.json` and native manifest when required | Register the correct source root, then install `<name>@dotagents-local` with the Codex CLI. |
+| `copilot` | Generated `.github/plugin/marketplace.json` | Register the Dotagents root, then install `<name>@dotagents` with the Copilot CLI. |
+| `grok` | Managed copy under `.grok/plugins/` | None. Grok reads the managed copy directly. |
+| `opencode` | Managed skill links and MCP entries | None. OpenCode reads the generated projections directly. |
+| `pi` | Managed skill links under `.agents/skills/` | None. Pi reads this directory directly. |
+| `vscode` | No plugin adapter | None. VS Code does not receive Dotagents plugin output. |
+
+Native clients can cache registered marketplaces and installed plugins. A later Dotagents update or removal does not update those caches. The guide and CLI reference list project, global, update, and removal commands.
+
 Pi plugin targets are global skill projections rather than isolated plugin installs: a Pi-targeted plugin skill is added to `.agents/skills/` and is therefore visible to other clients that consume that shared directory.
 
 [Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. Normal skills need no Pi-specific configuration; plugin bundles can target `pi` when their `skills/` components should be exposed there.

diff --git a/docs/public/llms.txt b/docs/public/llms.txt
@@ -315,7 +315,80 @@ Generated project-scope plugin outputs:
 
 Generated plugin JSON is deterministic: object keys and plugin entries are sorted, output is two-space indented, and files end with one trailing newline. Generated marketplaces and Claude, Cursor, and Codex manifests use adjacent `.dotagents-managed` sidecars so client-owned JSON remains schema-native; legacy `metadata.managedBy` output remains recognizable during migration. Managed Grok copies and OpenCode and Pi component symlinks are pruned when their plugin or target is removed. Plugin sources that resolve to this project's `.agents/plugins/<name>/` install destination are rejected so dotagents never installs a same-repo plugin onto itself. Existing plugin install destinations are overwritten only when their on-disk `.dotagents-managed` marker proves ownership.
 
-Global plugins install under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated below `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`. Codex uses `~/.agents/plugins/marketplace.json` with paths rooted at the user's home. Grok plugins are copied into `~/.grok/plugins/`. OpenCode skills use `~/.config/opencode/skills/`, portable plugin MCP servers use `~/.config/opencode/opencode.json`, and Pi skill projections use `~/.agents/skills/`.
+Global plugins install under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated below `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`. Codex uses `~/.agents/plugins/marketplace.json` with paths rooted at the user's home. Grok plugins are copied into `~/.grok/plugins/`, OpenCode skills use `~/.config/opencode/skills/`, portable plugin MCP servers are merged into `~/.config/opencode/opencode.json`, and Pi skill projections use `~/.agents/skills/`.
+
+### Plugin activation
+
+Dotagents plugin installation and native client installation are separate stages. `dotagents add` and `dotagents install` install the canonical bundle and generate runtime output. Marketplace-based clients must register that output and install the plugin into native client state.
+
+| Agent ID | Project output | Native action |
+| --- | --- | --- |
+| `claude` | `.claude-plugin/marketplace.json` and a native manifest when required | Register the project root, then install `<name>@dotagents`. |
+| `cursor` | `.cursor-plugin/marketplace.json` and a native manifest when required | Use Customize, a team marketplace, a local plugin, or `cursor-agent --plugin-dir`. |
+| `codex` | `.agents/plugins/marketplace.json` and a native manifest when required | Register the project root, then install `<name>@dotagents-local`. |
+| `copilot` | `.github/plugin/marketplace.json` | Register the project root, then install `<name>@dotagents`. |
+| `grok` | `.grok/plugins/<name>/` | None. Grok reads the managed copy directly. |
+| `opencode` | `.opencode/skills/` links and managed MCP entries | None. OpenCode reads the projections directly. |
+| `pi` | `.agents/skills/` links | None. Pi reads the links directly. |
+| `vscode` | No plugin output | None. VS Code has no plugin adapter. |
+
+Project activation:
+
+```shell
+claude plugin marketplace add ./ --scope project
+claude plugin install <name>@dotagents --scope project
+codex plugin marketplace add ./ --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add ./
+copilot plugin install <name>@dotagents
+```
+
+Default global activation:
+
+```shell
+claude plugin marketplace add "$HOME/.agents" --scope user
+claude plugin install <name>@dotagents --scope user
+codex plugin marketplace add "$HOME" --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add "$HOME/.agents"
+copilot plugin install <name>@dotagents
+```
+
+Codex uses `$HOME` because its default catalog is at `$HOME/.agents/plugins/marketplace.json`. Copilot registers the Dotagents root itself, the same as Claude, because its generated catalog is at `$HOME/.agents/.github/plugin/marketplace.json`.
+
+Custom global activation:
+
+```shell
+claude plugin marketplace add "$DOTAGENTS_HOME" --scope user
+claude plugin install <name>@dotagents --scope user
+codex plugin marketplace add "$DOTAGENTS_HOME" --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add "$DOTAGENTS_HOME"
+copilot plugin install <name>@dotagents
+```
+
+Cursor has no marketplace CLI command. Cursor Agent can load `.agents/plugins/<name>`, `$HOME/.agents/plugins/<name>`, or `$DOTAGENTS_HOME/plugins/<name>` with `--plugin-dir`. Cursor Desktop can load a canonical bundle from `~/.cursor/plugins/local/<name>`. A team marketplace requires a Git repository that contains the generated marketplace and every referenced plugin path.
+
+Native clients can cache installed plugins. After Dotagents updates a plugin, use the native update or reinstall flow. Replace `<scope>` with `project` or `user`:
+
+```shell
+claude plugin marketplace update dotagents
+claude plugin update <name>@dotagents --scope <scope>
+codex plugin remove <name>@dotagents-local --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace update dotagents
+copilot plugin update <name>@dotagents
+```
+
+After `dotagents remove`, remove cached native state separately. Replace `<scope>` with `project` or `user`:
+
+```shell
+claude plugin uninstall <name>@dotagents --scope <scope>
+codex plugin remove <name>@dotagents-local --json
+copilot plugin uninstall <name>@dotagents
+```
+
+Dotagents updates and removes Grok, OpenCode, and Pi projections directly. `dotagents doctor` checks canonical bundles and generated outputs. It does not check native marketplace registration, plugin installation, enablement, or caches.
 
 ### Trust
 
@@ -506,7 +579,6 @@ Check selected-scope health: gitignore setup where applicable, installed skills
 | `copilot` | GitHub Copilot CLI | `.copilot` | Project: reads `.agents/skills/`; global: `$COPILOT_HOME/skills/` symlink | `.mcp.json` or `.github/mcp.json` | Not supported | Not supported |
 | `vscode` | VS Code Copilot | `.vscode` | (reads `.agents/skills/` natively) | `.vscode/mcp.json` | `.claude/settings.json` | Not supported |
 | `opencode` | OpenCode | `.opencode` | (reads `.agents/skills/` natively) | `.opencode/opencode.jsonc` by default | Not supported | `.opencode/agents/*.md` |
-
 Claude uses `.claude/skills/`, and Cursor shares the same Claude-compatible skills symlink. Codex, VS Code, and OpenCode read `.agents/skills/` directly.
 
 [Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. Normal skills need no Pi-specific target or symlink configuration; plugin bundles can target `pi` when their `skills/` components should be exposed there.

diff --git a/docs/src/content/docs/cli.mdx b/docs/src/content/docs/cli.mdx
@@ -485,7 +485,80 @@ reinterpreting generated adapters as source input.
 | `path` | string | No | Optional explicit plugin path inside the source. |
 | `targets` | string[] | No | Optional subset of configured agents. |
 
-Generated plugin outputs include Claude, Cursor, Codex, and Copilot marketplaces, native Claude, Cursor, and Codex manifests, Grok plugin directories, OpenCode skill links and portable MCP entries, and Pi skill links. OpenCode MCP keys use `plugin.<plugin>.<server>`; dotagents expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` and preserves unrelated entries in the shared config. Generalized legacy bundles can also project Markdown agents into OpenCode; standard extension agents are preserved but not projected yet. dotagents rejects plugin sources that resolve to the same project's `.agents/plugins/<name>/` install destination. Global plugins use `~/.agents/plugins/<name>/` and global harness projections.
+Generated plugin outputs include marketplaces for Claude, Cursor, Codex, and Copilot. Claude, Cursor, and Codex also receive native manifests when required. Other outputs include Grok plugin directories, OpenCode skill links and portable MCP entries, and Pi skill links. OpenCode MCP keys use `plugin.<plugin>.<server>`; dotagents expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` and preserves unrelated entries in the shared config. Generalized legacy bundles can also project Markdown agents into OpenCode; standard extension agents are preserved but not projected yet. dotagents rejects plugin sources that resolve to the same project's `.agents/plugins/<name>/` install destination. Global plugins use `~/.agents/plugins/<name>/` and global harness projections.
+
+## Plugin activation
+
+`dotagents add` and `dotagents install` install canonical plugin bundles and write runtime outputs. These commands do not register marketplaces or install plugins in native client state.
+
+| Agent ID | Dotagents behavior | Required native action |
+| --- | --- | --- |
+| `claude` | Generates a marketplace and a native manifest when required. | Register the active scope root and install `<name>@dotagents`. |
+| `cursor` | Generates a marketplace and a native manifest when required. | Use Customize, a team marketplace, `~/.cursor/plugins/local`, or `cursor-agent --plugin-dir`. |
+| `codex` | Generates `.agents/plugins/marketplace.json` and a native manifest when required. | Register the correct source root and install `<name>@dotagents-local`. |
+| `copilot` | Generates `.github/plugin/marketplace.json`. | Register the active scope root and install `<name>@dotagents`. |
+| `grok` | Copies the plugin into `.grok/plugins/`. | None. |
+| `opencode` | Writes managed skill links and MCP entries. | None. |
+| `pi` | Writes managed skill links under `.agents/skills/`. | None. |
+| `vscode` | Has no plugin adapter. | None. |
+
+Project activation commands must run from the project root:
+
+```shell
+claude plugin marketplace add ./ --scope project
+claude plugin install <name>@dotagents --scope project
+codex plugin marketplace add ./ --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add ./
+copilot plugin install <name>@dotagents
+```
+
+Default global activation uses `~/.agents` for Claude and Copilot. Codex uses `$HOME` because its catalog is at `$HOME/.agents/plugins/marketplace.json`:
+
+```shell
+claude plugin marketplace add "$HOME/.agents" --scope user
+claude plugin install <name>@dotagents --scope user
+codex plugin marketplace add "$HOME" --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add "$HOME/.agents"
+copilot plugin install <name>@dotagents
+```
+
+With a custom `DOTAGENTS_HOME`, all three clients register that custom root:
+
+```shell
+claude plugin marketplace add "$DOTAGENTS_HOME" --scope user
+claude plugin install <name>@dotagents --scope user
+codex plugin marketplace add "$DOTAGENTS_HOME" --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace add "$DOTAGENTS_HOME"
+copilot plugin install <name>@dotagents
+```
+
+Claude, Codex, and Copilot cache installed plugins. After Dotagents updates a plugin, refresh Claude, reinstall the Codex plugin, and update the Copilot plugin. Replace `<scope>` with `project` or `user`:
+
+```shell
+claude plugin marketplace update dotagents
+claude plugin update <name>@dotagents --scope <scope>
+codex plugin remove <name>@dotagents-local --json
+codex plugin add <name>@dotagents-local --json
+copilot plugin marketplace update dotagents
+copilot plugin update <name>@dotagents
+```
+
+Native uninstall commands are also separate from `dotagents remove`. Replace `<scope>` with `project` or `user`:
+
+```shell
+claude plugin uninstall <name>@dotagents --scope <scope>
+codex plugin remove <name>@dotagents-local --json
+copilot plugin uninstall <name>@dotagents
+```
+
+Cursor has no marketplace CLI command. Load a canonical project plugin with `cursor-agent --plugin-dir .agents/plugins/<name>`. Use `$HOME/.agents/plugins/<name>` for the default global root or `$DOTAGENTS_HOME/plugins/<name>` for a custom root. Cursor Desktop can load a canonical bundle from `~/.cursor/plugins/local/<name>`. Team marketplaces require a Git repository that contains the generated marketplace and its referenced plugin paths.
+
+Grok, OpenCode, and Pi read Dotagents-managed outputs directly, so Dotagents updates and removes those projections. VS Code receives no plugin output.
+
+`dotagents doctor` checks canonical bundles and generated runtime outputs. It does not check native marketplace registration, installation, enablement, or client caches.
 
 ## Scopes