Document native plugin registration and activation

[mishamilovidov]

Problem

dotagents add and dotagents install report a plugin as installed after dotagents installs the canonical bundle and writes runtime output.

For marketplace-based agents, this does not make the plugin available. The user must register the generated marketplace and install or activate the plugin in the native client.

The public guide describes add as adding a plugin and install as installing declared dependencies. It does not explain the second stage. dotagents doctor can also pass when the native client has no registered marketplace or installed plugin.

PR #166 adds follow-up commands for GitHub Copilot. It does not define the general lifecycle for all supported agents.

Affected plugin targets

Agent	Dotagents output	Native step after dotagents add or install
Claude Code	Generated marketplace and, when required, a native manifest	Register the marketplace, then install the plugin with the Claude CLI.
GitHub Copilot CLI/Desktop	Generated .github/plugin/marketplace.json after PR #166	Register the marketplace, then install the plugin with the Copilot CLI.
Codex	Generated .agents/plugins/marketplace.json and, when required, a native manifest	Register the marketplace, then add the plugin from dotagents-local.
Cursor	Generated marketplace and, when required, a native manifest	Use a supported Cursor activation path. Cursor has no marketplace subcommand in its CLI. The docs must explain the Desktop, team-marketplace, local-plugin, and --plugin-dir options that apply.
Grok Build	Managed copy under .grok/plugins/	None. Grok discovers this directory directly.
OpenCode	Managed skill links and merged MCP entries	None. Dotagents projects these resources directly.
Pi	Managed skill links under .agents/skills/	None. Pi reads this directory directly.
VS Code	No plugin adapter	Not applicable.

This table must stay explicit. The generated marketplace files for Claude, Copilot, Codex, and Cursor are not equivalent to installed native plugins.

Proposed documentation

Add a Plugin activation section to the guide and CLI reference. Define these separate stages:

1. Dotagents installs the canonical bundle under .agents/plugins/<name>/.
2. Dotagents writes the runtime output for each selected agent.
3. Marketplace-based clients register that output and install the plugin into native client state.

Include tested project-scope examples for the clients that have marketplace CLIs:

claude plugin marketplace add ./ --scope project
claude plugin install <name>@dotagents --scope project

copilot plugin marketplace add ./
copilot plugin install <name>@dotagents

codex plugin marketplace add ./ --json
codex plugin add <name>@dotagents-local --json

Add equivalent global examples. These examples must use the exact source root for the default ~/.agents layout and a custom DOTAGENTS_HOME. Codex requires special care because its generated catalog path differs from the Claude and Copilot paths.

Document the Cursor flow separately. Cursor supports installation through Customize or a team marketplace. It also supports local plugins and cursor-agent --plugin-dir. The Dotagents docs must state which flow works with each generated project and global output.

Document update and removal behavior. Updating or removing a Dotagents declaration does not necessarily update or uninstall a plugin from a native client cache. List the required native update, reinstall, or uninstall step for each affected client.

State the boundary of dotagents doctor. It validates Dotagents-managed bundles and generated outputs. It does not prove that a native marketplace is registered or that a plugin is installed and enabled.

Acceptance criteria

• The public guide, CLI reference, README, and llms.txt explain the two-stage lifecycle.
• The documentation accounts for every supported agent ID: claude, cursor, codex, copilot, vscode, grok, opencode, and pi.
• Claude, Codex, Copilot, and Cursor have accurate project and global activation instructions.
• Grok, OpenCode, Pi, and VS Code state why no marketplace activation command applies.
• The examples match the repository QA commands and current project and global output paths.
• The Codex examples use @dotagents if the marketplace-name issue lands first.
• The docs do not describe canonical bundle installation as native client installation.
• The docs explain the native update and removal steps for clients that cache installed plugins.

Related work

Issue #175 defines the final Codex marketplace name.

The documentation change must use the marketplace names in the code when it lands. If the naming issue lands first, Codex examples must use @dotagents.

Scope

This issue covers documentation only. Automatic native marketplace registration, plugin installation, cache reconciliation, marketplace naming, and doctor checks belong in separate product work.

References

• Public guide: https://dotagents.sentry.dev/guide/
• PR #166
• Cursor plugin docs: https://cursor.com/docs/plugins