From bdcba7cfb91c83292343df40c88d00156a077230 Mon Sep 17 00:00:00 2001
From: Rhuan Barreto <rhuan@barreto.work>
Date: Mon, 30 Mar 2026 16:00:51 +0200
Subject: [PATCH 1/2] feat: native Cursor plugin support via marketplace and
 VSIX install

Made-with: Cursor
---
 .../agent-memory/archgate-developer/MEMORY.md |  13 +-
 .gitignore                                    |   3 -
 CONTRIBUTING.md                               |  11 --
 docs/astro.config.mjs                         |   2 +-
 docs/public/llms-full.txt                     |   4 +-
 docs/public/llms.txt                          |   4 +-
 .../docs/guides/cursor-integration.mdx        |  70 +++++-----
 .../docs/pt-br/guides/cursor-integration.mdx  |  68 +++++-----
 .../content/docs/pt-br/reference/cli/init.mdx |   2 +-
 .../docs/pt-br/reference/cli/plugin.mdx       |   2 +-
 docs/src/content/docs/reference/cli/init.mdx  |   2 +-
 .../src/content/docs/reference/cli/plugin.mdx |   2 +-
 src/commands/plugin/install.ts                |  25 ++--
 src/commands/plugin/url.ts                    |  15 ++-
 src/helpers/init-project.ts                   |  31 +++--
 src/helpers/plugin-install.ts                 | 122 +++++++-----------
 tests/commands/plugin/url.test.ts             |   7 +-
 17 files changed, 176 insertions(+), 207 deletions(-)

diff --git a/.claude/agent-memory/archgate-developer/MEMORY.md b/.claude/agent-memory/archgate-developer/MEMORY.md
index ced7f6e1..5ea28e44 100644
--- a/.claude/agent-memory/archgate-developer/MEMORY.md
+++ b/.claude/agent-memory/archgate-developer/MEMORY.md
@@ -26,9 +26,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 
 ## Patterns & Fixes
 
-- **`McpServer` event loop retention on Linux** — `new McpServer()` from `@modelcontextprotocol/sdk` creates an `AjvJsonSchemaValidator` (backed by `ajv` + `ajv-formats`) that keeps Bun's event loop alive on Linux after tests complete, causing `bun test` to hang for 30+ minutes. macOS drains the event loop fine — this is a Linux-CI-only failure. Fix: manage server lifecycle in `beforeEach`/`afterEach` and call `await server.close()` in `afterEach`. Also captured in ARCH-005 Don'ts.
 - **`git commit` in temp repos requires local identity** — CI runners have no global `user.email`/`user.name` configured. Any test that runs `git commit` on a temp repo MUST call `git config user.email` and `git config user.name` locally after `git init`. Fails with a cryptic `ShellPromise` error in CI; passes locally. Also captured in ARCH-005 Do's.
-- **Bun import cache-busting**: Bun caches `import()` per-process. For long-running processes (MCP server), append `?t=${Date.now()}` to the import path to force re-reading from disk. Applied in `src/engine/loader.ts`.
 - **Never use `bunx prettier` directly** — Always use `bun run format` (to fix) or `bun run format:check` (to verify). Using `bunx prettier` can fail or use a different version than the project's devDependency. The same applies to all dev tools: prefer `bun run <script>` over `bunx <tool>` when a package.json script exists.
 - **`Bun.Glob.match()` triggers oxlint `prefer-regexp-test`** — `Bun.Glob.match()` returns a boolean (not a RegExp), but oxlint can't tell. Suppress with `// oxlint-disable-next-line prefer-regexp-test -- Bun.Glob.match() returns boolean, not RegExp`.
 - **oxlint `no-negated-condition`** — Always write ternaries with the positive condition first: `x === null ? A : B` not `x !== null ? B : A`. Applies to both `if/else` blocks and ternary expressions.
@@ -39,7 +37,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 - **`CHANGELOG.md` is auto-generated — exclude from Prettier** — `CHANGELOG.md` is written by `TrigenSoftware/simple-release-action` during the release PR workflow. It is committed directly and never formatted by Prettier. It MUST be in `.prettierignore`; otherwise `bun run format:check` (part of `bun run validate`) will fail on the release PR. Do not attempt to run prettier on it post-commit.
 - **`mock.module("node:fetch", ...)` does NOT intercept `globalThis.fetch` in Bun** — Bun's runtime fetch is `globalThis.fetch`, not the `node:fetch` module. Using `mock.module` silently fails; the real network is hit. Always mock fetch by assigning `globalThis.fetch = mockFn as unknown as typeof fetch` directly, and restore via `mock.restore()` in `afterEach`. TypeScript type cast: `as never` is insufficient for the `typeof fetch` type (which includes `preconnect`) — always use `as unknown as typeof fetch`. Also captured in ARCH-005 Don'ts.
 - **Git credential tests need system-level isolation on Windows** — Overriding `Bun.env.HOME` is NOT sufficient to isolate `git credential fill/approve` calls in tests. Windows Credential Manager is a system-level API, not file-based. Tests MUST set `Bun.env.GIT_CONFIG_NOSYSTEM = "1"` and `Bun.env.GIT_CONFIG_GLOBAL = <path-to-empty-file>` to prevent git from reading the real credential helper config. Without this, tests on machines with stored credentials will pick up real tokens.
-- **GCM prompt suppression requires 5 env vars** — `GIT_TERMINAL_PROMPT=0` alone does NOT prevent Git Credential Manager (GCM) from showing GUI prompts on Windows or askpass prompts on Linux. The full set for `gitCredentialEnv()` in `src/helpers/credential-store.ts` is: `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, `GCM_GUI_PROMPT=false`, `GIT_ASKPASS=""`, `SSH_ASKPASS=""`. Omitting any one can trigger unexpected prompts in editor/MCP contexts where the CLI runs as a subprocess.
+- **GCM prompt suppression requires 5 env vars** — `GIT_TERMINAL_PROMPT=0` alone does NOT prevent Git Credential Manager (GCM) from showing GUI prompts on Windows or askpass prompts on Linux. The full set for `gitCredentialEnv()` in `src/helpers/credential-store.ts` is: `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, `GCM_GUI_PROMPT=false`, `GIT_ASKPASS=""`, `SSH_ASKPASS=""`. Omitting any one can trigger unexpected prompts in editor contexts where the CLI runs as a subprocess.
 - **Module-level `{ ...Bun.env }` captures env at import time** — Spreading `Bun.env` into a module-level constant freezes the env snapshot. Tests that override `Bun.env.HOME` after import won't affect the constant. Fix: use a function that returns `{ ...Bun.env, ... }` on each call so it picks up test-time overrides. Applied in `src/helpers/credential-store.ts`.
 
 ## Validation Pipeline
@@ -60,12 +58,3 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 ## Telemetry Strategy
 
 - [Telemetry & Analytics Strategy](project_telemetry_strategy.md) — Decisions on PostHog analytics, Sentry error tracking, plugin surveys (2026-03-22)
-
-## MCP Tools Structure
-
-- MCP tools live in `src/mcp/tools/` — one file per tool (check, list-adrs, review-context, claude-code-session-context, cursor-session-context)
-- ADR CRUD moved to CLI: `archgate adr create`, `archgate adr update`, `archgate init` (no longer MCP tools)
-- `src/mcp/tools/index.ts` composes all registrations via `registerTools()` (contains real logic, not a barrel per ARCH-004)
-- `src/mcp/server.ts` imports from `./tools/index`
-- `src/mcp/resources.ts` registers `adr://{id}` resource template via `ResourceTemplate` (uses `variables.id` for matching)
-- `src/engine/context.ts` provides shared review context logic (section extraction, file-to-ADR matching, `buildReviewContext()`)
diff --git a/.gitignore b/.gitignore
index e60f2c37..d5a7bb06 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,9 +20,6 @@ coverage
 # OS files
 .DS_Store
 
-# Local MCP config
-.mcp.json
-
 # Claude Code worktrees
 .claude/worktrees
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5bdfb8cf..e5fba9f0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,7 +95,6 @@ src/
 ├── commands/
 │   ├── init.ts             # Project initialization
 │   ├── check.ts            # ADR compliance checks
-│   ├── mcp.ts              # MCP server
 │   ├── upgrade.ts          # CLI upgrade
 │   ├── clean.ts            # Clean cache
 │   └── adr/
@@ -121,16 +120,6 @@ src/
 │   ├── claude-settings.ts  # Claude plugin settings
 │   ├── git.ts              # Git availability checks
 │   └── getParentFolderName.ts  # Project name extraction
-└── mcp/
-    ├── server.ts           # MCP server setup
-    ├── resources.ts        # adr://{id} resource template
-    └── tools/
-        ├── index.ts        # Tool registration
-        ├── check.ts        # check tool
-        ├── list-adrs.ts    # list_adrs tool
-        ├── review-context.ts   # review_context tool
-        ├── claude-code-session-context.ts  # claude_code_session_context tool
-        └── cursor-session-context.ts  # cursor_session_context tool
 tests/                      # Mirrors src/ structure
 .archgate/adrs/             # Self-governance ADRs
 ```
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index b603a8ed..64fb0378 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -149,7 +149,7 @@ export default defineConfig({
           attrs: {
             name: "keywords",
             content:
-              "archgate, architecture decision records, ADR, executable rules, code governance, AI governance, TypeScript rules, CLI, compliance automation, MCP server",
+              "archgate, architecture decision records, ADR, executable rules, code governance, AI governance, TypeScript rules, CLI, compliance automation",
           },
         },
         // ── JSON-LD: WebSite ──────────────────────────────────────
diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index 0783c41c..a833c09a 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -8,7 +8,7 @@ Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdo
 
 - **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers.
 - **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated.
-- **AI-aware governance**: The MCP server gives AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
+- **AI-aware governance**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
 - **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills.
 - **Self-governance**: Archgate governs its own development using the same tool.
 
@@ -30,10 +30,8 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont
 - [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code.
 - [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI.
 - [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills.
-- [Guide — MCP Server](https://cli.archgate.dev/guides/mcp-server/): Give AI agents live access to ADRs via the Model Context Protocol.
 - [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit.
 - [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more.
-- [Reference — MCP Tools](https://cli.archgate.dev/reference/mcp-tools/): API reference for adr_list, adr_read, check_compliance, and review_context.
 - [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting.
 - [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs.
 - [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more.
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index 841d21c4..87655d99 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -8,7 +8,7 @@ Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdo
 
 - **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers.
 - **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated.
-- **AI-aware governance**: The MCP server gives AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
+- **AI-aware governance**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
 - **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills.
 - **Self-governance**: Archgate governs its own development using the same tool.
 
@@ -30,10 +30,8 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont
 - [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code.
 - [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI.
 - [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills.
-- [Guide — MCP Server](https://cli.archgate.dev/guides/mcp-server/): Give AI agents live access to ADRs via the Model Context Protocol.
 - [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit.
 - [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more.
-- [Reference — MCP Tools](https://cli.archgate.dev/reference/mcp-tools/): API reference for adr_list, adr_read, check_compliance, and review_context.
 - [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting.
 - [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs.
 - [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more.
diff --git a/docs/src/content/docs/guides/cursor-integration.mdx b/docs/src/content/docs/guides/cursor-integration.mdx
index 8c116808..e44ccf6f 100644
--- a/docs/src/content/docs/guides/cursor-integration.mdx
+++ b/docs/src/content/docs/guides/cursor-integration.mdx
@@ -19,7 +19,12 @@ archgate init --editor cursor
 The Cursor plugin is currently in beta. Run `archgate login` to sign up and authenticate.
 :::
 
-If you have logged in via `archgate login`, the init command also downloads and installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor's AI agent a full governance workflow.
+If you have logged in via `archgate login`, the init command also installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor's AI agent a full governance workflow.
+
+The plugin is distributed in two ways:
+
+1. **Cursor Team Marketplace** -- The plugin is published to a git-based team marketplace repository. After installation, Cursor discovers it from the team marketplace URL printed by the CLI.
+2. **VS Code Extension (VSIX)** -- A `.vsix` extension is installed into Cursor via the `cursor --install-extension` command.
 
 To explicitly install the plugin:
 
@@ -28,7 +33,7 @@ archgate login              # one-time setup
 archgate init --editor cursor --install-plugin
 ```
 
-The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. It includes agent rules and skill definitions.
+The `archgate plugin install --editor cursor` command installs the VS Code extension via `cursor` CLI if available and prints the team marketplace URL; it prints manual instructions otherwise.
 
 To install or reinstall the plugin on an already-initialized project:
 
@@ -48,30 +53,31 @@ Without the plugin, `archgate init --editor cursor` still configures a basic gov
 
 ## What the plugin provides
 
-The plugin adds an agent and role-based skills to Cursor. Each is invoked as a slash command with the `/ag-` prefix. The agent orchestrates the governance workflow, invoking skills as needed.
+The plugin adds an agent and role-based skills to Cursor. Cursor's plugin system handles namespacing, so skills use their direct names without a prefix.
 
 ### Agent
 
-| Slash command   | Purpose                                                                     |
-| --------------- | --------------------------------------------------------------------------- |
-| `/ag-developer` | General development agent that reads ADRs before coding and validates after |
+| Name        | Purpose                                                                     |
+| ----------- | --------------------------------------------------------------------------- |
+| `developer` | General development agent that reads ADRs before coding and validates after |
 
-The `/ag-developer` agent orchestrates the skills below automatically as part of its workflow.
+The `developer` agent orchestrates the skills below automatically as part of its workflow.
 
 ### Skills
 
-| Slash command         | Purpose                                                                               |
-| --------------------- | ------------------------------------------------------------------------------------- |
-| `/ag-architect`       | Validates code changes against all project ADRs for structural compliance             |
-| `/ag-quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
-| `/ag-adr-author`      | Creates and edits ADRs following project conventions                                  |
-| `/ag-onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
+| Name              | Purpose                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `architect`       | Validates code changes against all project ADRs for structural compliance             |
+| `quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
+| `adr-author`      | Creates and edits ADRs following project conventions                                  |
+| `onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
+| `cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide         |
 
-These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's slash command interface with the `ag-` prefix.
+These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's plugin system.
 
 ## Initial setup with onboard
 
-After installing the plugin, run `/ag-onboard` in your project once. This skill:
+After installing the plugin, run the `onboard` skill in your project once. This skill:
 
 1. Explores your codebase structure (directories, key files, package configuration)
 2. Interviews you about your team's conventions, constraints, and architectural decisions
@@ -84,17 +90,17 @@ The onboard skill is designed to run once per project. After onboarding, the oth
 
 ### With the plugin
 
-The `/ag-developer` skill follows a structured workflow for every coding task:
+The `developer` agent follows a structured workflow for every coding task:
 
-1. **Read applicable ADRs** -- The agent calls `review_context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.
+1. **Read applicable ADRs** -- The agent runs `archgate review-context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.
 
 2. **Write code following ADR constraints** -- The agent implements changes following the Do's and Don'ts from the applicable ADRs.
 
-3. **Run compliance checks** -- The agent runs `archgate check` to execute automated rules. Any violations are fixed before proceeding.
+3. **Run compliance checks** -- The agent runs `archgate check --staged` to execute automated rules. Any violations are fixed before proceeding.
 
-4. **Architect review** -- The agent invokes `/ag-architect` to validate structural ADR compliance beyond what automated rules catch.
+4. **Architect review** -- The agent invokes the `architect` skill to validate structural ADR compliance beyond what automated rules catch.
 
-5. **Capture learnings** -- The agent invokes `/ag-quality-manager` to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.
+5. **Capture learnings** -- The agent invokes the `quality-manager` skill to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.
 
 ### Without the plugin
 
@@ -122,15 +128,15 @@ This behavior is consistent regardless of how the developer phrases the request.
 
 ## When to use each agent or skill
 
-| Scenario                                     | Slash command         |
-| -------------------------------------------- | --------------------- |
-| Starting a new project with Archgate         | `/ag-onboard`         |
-| Day-to-day coding tasks                      | `/ag-developer`       |
-| Reviewing a PR for ADR compliance            | `/ag-architect`       |
-| Noticing a recurring pattern worth codifying | `/ag-quality-manager` |
-| Creating or editing an ADR                   | `/ag-adr-author`      |
+| Scenario                                     | Skill             |
+| -------------------------------------------- | ----------------- |
+| Starting a new project with Archgate         | `onboard`         |
+| Day-to-day coding tasks                      | `developer`       |
+| Reviewing a PR for ADR compliance            | `architect`       |
+| Noticing a recurring pattern worth codifying | `quality-manager` |
+| Creating or editing an ADR                   | `adr-author`      |
 
-The `/ag-developer` agent orchestrates the skills automatically -- it invokes `/ag-architect` and `/ag-quality-manager` as part of its workflow. Most of the time, you only need to use `/ag-developer` directly.
+The `developer` agent orchestrates the skills automatically -- it invokes `architect` and `quality-manager` as part of its workflow. Most of the time, you only need to use `developer` directly.
 
 ## Governance rule
 
@@ -147,9 +153,9 @@ The command accepts two optional flags:
 
 ## Tips for effective usage
 
-- **Use `/ag-developer` for coding tasks.** It orchestrates the full read-validate-capture workflow automatically.
-- **Run `/ag-onboard` once per project.** It sets up your initial ADRs based on your actual codebase and conventions.
-- **Use `/ag-architect` for PR reviews.** It validates structural compliance beyond what automated rules catch.
-- **Use `/ag-quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
+- **Use the `developer` skill for coding tasks.** It orchestrates the full read-validate-capture workflow automatically.
+- **Run `onboard` once per project.** It sets up your initial ADRs based on your actual codebase and conventions.
+- **Use `architect` for PR reviews.** It validates structural compliance beyond what automated rules catch.
+- **Use `quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
 - **Commit the `.cursor/` directory.** This ensures every team member gets the same governance configuration when they clone the repository.
 - **Keep ADR rules files up to date.** The agent enforces what the rules check for -- if a rule is missing, the violation will not be caught.
diff --git a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx
index b549d495..a617d1dc 100644
--- a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx
+++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx
@@ -19,7 +19,12 @@ archgate init --editor cursor
 O plugin para Cursor está atualmente em beta. Execute `archgate login` para se cadastrar e autenticar.
 :::
 
-Se você fez login via `archgate login`, o comando init também baixa e instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pré-configuradas e skills que dão ao agente de IA do Cursor um fluxo de governança completo.
+Se você fez login via `archgate login`, o comando init também instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pré-configuradas e skills que dão ao agente de IA do Cursor um fluxo de governança completo.
+
+O plugin é distribuído de duas formas:
+
+1. **Cursor Team Marketplace** -- O plugin é publicado em um repositório team marketplace baseado em git. Após a instalação, o Cursor o descobre a partir da URL do team marketplace impressa pela CLI.
+2. **Extensão VS Code (VSIX)** -- Uma extensão `.vsix` é instalada no Cursor via o comando `cursor --install-extension`.
 
 Para instalar o plugin explicitamente:
 
@@ -28,7 +33,7 @@ archgate login              # configuração única
 archgate init --editor cursor --install-plugin
 ```
 
-O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. Ele inclui regras de agente e definições de skills.
+O comando `archgate plugin install --editor cursor` instala a extensão VS Code via CLI `cursor` se disponível e exibe a URL do team marketplace; exibe instruções manuais caso contrário.
 
 Para instalar ou reinstalar o plugin em um projeto já inicializado:
 
@@ -48,30 +53,31 @@ Sem o plugin, `archgate init --editor cursor` ainda configura uma regra de gover
 
 ## O que o plugin oferece
 
-O plugin adiciona um agente e skills baseadas em papéis ao Cursor. Cada um é invocado como um slash command com o prefixo `/ag-`. O agente orquestra o fluxo de governança, invocando skills conforme necessário.
+O plugin adiciona um agente e skills baseadas em papéis ao Cursor. O sistema de plugins do Cursor gerencia o namespacing, então as skills usam seus nomes diretos sem prefixo.
 
 ### Agente
 
-| Slash command   | Propósito                                                                      |
-| --------------- | ------------------------------------------------------------------------------ |
-| `/ag-developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois |
+| Nome        | Propósito                                                                      |
+| ----------- | ------------------------------------------------------------------------------ |
+| `developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois |
 
-O agente `/ag-developer` orquestra as skills abaixo automaticamente como parte do seu fluxo.
+O agente `developer` orquestra as skills abaixo automaticamente como parte do seu fluxo.
 
 ### Skills
 
-| Slash command         | Propósito                                                                                  |
-| --------------------- | ------------------------------------------------------------------------------------------ |
-| `/ag-architect`       | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural   |
-| `/ag-quality-manager` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem                    |
-| `/ag-adr-author`      | Cria e edita ADRs seguindo as convenções do projeto                                        |
-| `/ag-onboard`         | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais |
+| Nome              | Propósito                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `architect`       | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural   |
+| `quality-manager` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem                    |
+| `adr-author`      | Cria e edita ADRs seguindo as convenções do projeto                                        |
+| `onboard`         | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais |
+| `cli-reference`   | Referência interna para agentes de IA com o guia completo de comandos CLI do Archgate      |
 
-Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptados para a interface de slash commands do Cursor com o prefixo `ag-`.
+Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptados para o sistema de plugins do Cursor.
 
 ## Configuração inicial com onboard
 
-Após instalar o plugin, execute `/ag-onboard` no seu projeto uma vez. Essa skill:
+Após instalar o plugin, execute a skill `onboard` no seu projeto uma vez. Essa skill:
 
 1. Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes)
 2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe
@@ -84,17 +90,17 @@ A skill de onboard foi projetada para ser executada uma vez por projeto. Após o
 
 ### Com o plugin
 
-O agente `/ag-developer` segue um fluxo estruturado para cada tarefa de codificação:
+O agente `developer` segue um fluxo estruturado para cada tarefa de codificação:
 
 1. **Ler os ADRs aplicáveis** -- O agente executa `archgate review-context` para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele não escreve código até ter lido os ADRs aplicáveis.
 
 2. **Escrever código seguindo as restrições dos ADRs** -- O agente implementa as alterações seguindo as seções Do's and Don'ts dos ADRs aplicáveis.
 
-3. **Executar verificações de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir.
+3. **Executar verificações de conformidade** -- O agente executa `archgate check --staged` para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir.
 
-4. **Revisão do arquiteto** -- O agente invoca `/ag-architect` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.
+4. **Revisão do arquiteto** -- O agente invoca a skill `architect` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.
 
-5. **Capturar aprendizados** -- O agente invoca `/ag-quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes.
+5. **Capturar aprendizados** -- O agente invoca a skill `quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes.
 
 ### Sem o plugin
 
@@ -122,15 +128,15 @@ Esse comportamento é consistente independentemente de como o desenvolvedor form
 
 ## Quando usar cada agente ou skill
 
-| Cenário                                                 | Slash command         |
-| ------------------------------------------------------- | --------------------- |
-| Iniciando um novo projeto com Archgate                  | `/ag-onboard`         |
-| Tarefas de codificação do dia a dia                     | `/ag-developer`       |
-| Revisando um PR para conformidade com ADRs              | `/ag-architect`       |
-| Percebendo um padrão recorrente que vale ser codificado | `/ag-quality-manager` |
-| Criando ou editando um ADR                              | `/ag-adr-author`      |
+| Cenário                                                 | Skill             |
+| ------------------------------------------------------- | ----------------- |
+| Iniciando um novo projeto com Archgate                  | `onboard`         |
+| Tarefas de codificação do dia a dia                     | `developer`       |
+| Revisando um PR para conformidade com ADRs              | `architect`       |
+| Percebendo um padrão recorrente que vale ser codificado | `quality-manager` |
+| Criando ou editando um ADR                              | `adr-author`      |
 
-O agente `/ag-developer` orquestra as skills automaticamente -- ele invoca `/ag-architect` e `/ag-quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `/ag-developer` diretamente.
+O agente `developer` orquestra as skills automaticamente -- ele invoca `architect` e `quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `developer` diretamente.
 
 ## Regra de governança
 
@@ -138,9 +144,9 @@ A regra de governança em `.cursor/rules/archgate-governance.mdc` usa `alwaysApp
 
 ## Dicas para uso eficaz
 
-- **Use `/ag-developer` para tarefas de codificação.** Ele orquestra todo o fluxo de leitura-validação-captura automaticamente.
-- **Execute `/ag-onboard` uma vez por projeto.** Ele configura seus ADRs iniciais com base no seu codebase e convenções reais.
-- **Use `/ag-architect` para revisões de PR.** Ele valida a conformidade estrutural além do que as regras automatizadas capturam.
-- **Use `/ag-quality-manager` após resolver problemas complexos.** Ele captura aprendizados para que os mesmos erros não se repitam.
+- **Use a skill `developer` para tarefas de codificação.** Ela orquestra todo o fluxo de leitura-validação-captura automaticamente.
+- **Execute `onboard` uma vez por projeto.** Ela configura seus ADRs iniciais com base no seu codebase e convenções reais.
+- **Use `architect` para revisões de PR.** Ela valida a conformidade estrutural além do que as regras automatizadas capturam.
+- **Use `quality-manager` após resolver problemas complexos.** Ela captura aprendizados para que os mesmos erros não se repitam.
 - **Faça commit do diretório `.cursor/`.** Isso garante que cada membro da equipe receba a mesma configuração de governança ao clonar o repositório.
 - **Mantenha os arquivos de regras dos ADRs atualizados.** O agente aplica o que as regras verificam -- se uma regra estiver faltando, a violação não será detectada.
diff --git a/docs/src/content/docs/pt-br/reference/cli/init.mdx b/docs/src/content/docs/pt-br/reference/cli/init.mdx
index ea022454..6b4bf112 100644
--- a/docs/src/content/docs/pt-br/reference/cli/init.mdx
+++ b/docs/src/content/docs/pt-br/reference/cli/init.mdx
@@ -24,7 +24,7 @@ Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o
 
 **Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` não for encontrada, o comando exibe os comandos de instalação manual.
 
-**Cursor:** O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`.
+**Cursor:** Se a CLI `cursor` estiver no seu PATH, a extensão VS Code é instalada automaticamente via `cursor --install-extension`. A URL do team marketplace é impressa para descoberta manual do plugin.
 
 ## Saída
 
diff --git a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx
index f6e0e85e..2cdcda3b 100644
--- a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx
+++ b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx
@@ -54,7 +54,7 @@ O comportamento de instalação varia por editor:
 
 - **Claude Code:** Instala automaticamente via CLI `claude` se disponível; exibe comandos manuais caso contrário.
 - **Copilot CLI:** Instala automaticamente via CLI `copilot` se disponível; exibe comandos manuais caso contrário.
-- **Cursor:** Baixa e extrai o pacote do plugin no diretório `.cursor/`.
+- **Cursor:** Instala a extensão VS Code via CLI `cursor` se disponível e exibe a URL do team marketplace; exibe instruções manuais caso contrário.
 - **VS Code:** Adiciona a URL do marketplace nas configurações de usuário do VS Code e instala a extensão VS Code (`.vsix`) via CLI `code` se disponível; exibe instruções manuais caso contrário.
 
 ## Exemplos
diff --git a/docs/src/content/docs/reference/cli/init.mdx b/docs/src/content/docs/reference/cli/init.mdx
index 822c82d1..f8f7b0bd 100644
--- a/docs/src/content/docs/reference/cli/init.mdx
+++ b/docs/src/content/docs/reference/cli/init.mdx
@@ -24,7 +24,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the
 
 **Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead.
 
-**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory.
+**Cursor:** If the `cursor` CLI is on your PATH, the VS Code extension is installed automatically via `cursor --install-extension`. The team marketplace URL is printed for manual plugin discovery.
 
 ## Output
 
diff --git a/docs/src/content/docs/reference/cli/plugin.mdx b/docs/src/content/docs/reference/cli/plugin.mdx
index 2ea2dcdc..ad8f5297 100644
--- a/docs/src/content/docs/reference/cli/plugin.mdx
+++ b/docs/src/content/docs/reference/cli/plugin.mdx
@@ -54,7 +54,7 @@ Installation behavior varies by editor:
 
 - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise.
 - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise.
-- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`.
+- **Cursor:** Installs the VS Code extension via `cursor` CLI if available and prints the team marketplace URL; prints manual instructions otherwise.
 - **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise.
 
 ## Examples
diff --git a/src/commands/plugin/install.ts b/src/commands/plugin/install.ts
index e1ee4486..8018a7a0 100644
--- a/src/commands/plugin/install.ts
+++ b/src/commands/plugin/install.ts
@@ -13,6 +13,7 @@ import type { EditorTarget } from "../../helpers/init-project";
 import { logError, logInfo, logWarn } from "../../helpers/log";
 import { findProjectRoot } from "../../helpers/paths";
 import {
+  buildCursorMarketplaceUrl,
   buildMarketplaceUrl,
   buildVscodeMarketplaceUrl,
   installClaudePlugin,
@@ -21,6 +22,7 @@ import {
   installVscodeExtension,
   isClaudeCliAvailable,
   isCopilotCliAvailable,
+  isCursorCliAvailable,
   isVscodeCliAvailable,
 } from "../../helpers/plugin-install";
 import { configureVscodeSettings } from "../../helpers/vscode-settings";
@@ -69,12 +71,16 @@ async function installForEditor(
       break;
     }
     case "cursor": {
-      const projectRoot = findProjectRoot() ?? process.cwd();
-      const files = await installCursorPlugin(projectRoot, token);
-      logInfo(
-        `Archgate plugin installed for ${label}.`,
-        `Extracted ${files.length} files to .cursor/`
-      );
+      if (await isCursorCliAvailable()) {
+        await installCursorPlugin(token);
+        logInfo(`Archgate extension installed for ${label}.`);
+      } else {
+        logWarn("Cursor CLI not found. To install the plugin manually:");
+        console.log(`  1. Install the VS Code extension in Cursor`);
+        console.log(
+          `  2. Add the Team Marketplace: ${buildCursorMarketplaceUrl()}`
+        );
+      }
       break;
     }
     case "vscode": {
@@ -166,9 +172,10 @@ export function registerPluginInstallCommand(plugin: Command) {
               break;
             }
             case "cursor": {
-              logInfo(
-                "To install the plugin manually, download it from the archgate dashboard."
-              );
+              const url = buildCursorMarketplaceUrl();
+              logInfo("To install the plugin manually:");
+              console.log(`  1. Install the VS Code extension in Cursor`);
+              console.log(`  2. Add the Team Marketplace: ${url}`);
               break;
             }
             case "vscode": {
diff --git a/src/commands/plugin/url.ts b/src/commands/plugin/url.ts
index 30987693..cb293c87 100644
--- a/src/commands/plugin/url.ts
+++ b/src/commands/plugin/url.ts
@@ -8,6 +8,7 @@ import {
 import type { EditorTarget } from "../../helpers/init-project";
 import { logError } from "../../helpers/log";
 import {
+  buildCursorMarketplaceUrl,
   buildMarketplaceUrl,
   buildVscodeMarketplaceUrl,
 } from "../../helpers/plugin-install";
@@ -15,7 +16,7 @@ import {
 const editorOption = new Option(
   "--editor <editor>",
   "target editor (omit to auto-detect and select)"
-).choices(["claude", "vscode", "copilot"] as const);
+).choices(["claude", "cursor", "vscode", "copilot"] as const);
 
 export function registerPluginUrlCommand(plugin: Command) {
   plugin
@@ -28,18 +29,18 @@ export function registerPluginUrlCommand(plugin: Command) {
         if (opts.editor) {
           editor = opts.editor;
         } else if (process.stdin.isTTY) {
-          const detected = (await detectEditors()).filter(
-            (e) => e.id !== "cursor"
-          );
+          const detected = await detectEditors();
           editor = await promptSingleEditorSelection(detected);
         } else {
           editor = "claude";
         }
 
         const url =
-          editor === "vscode"
-            ? buildVscodeMarketplaceUrl()
-            : buildMarketplaceUrl();
+          editor === "cursor"
+            ? buildCursorMarketplaceUrl()
+            : editor === "vscode"
+              ? buildVscodeMarketplaceUrl()
+              : buildMarketplaceUrl();
 
         console.log(url);
       } catch (err) {
diff --git a/src/helpers/init-project.ts b/src/helpers/init-project.ts
index 8d52ae5d..9392d722 100644
--- a/src/helpers/init-project.ts
+++ b/src/helpers/init-project.ts
@@ -112,7 +112,7 @@ Archgate standardizes \`.archgate/lint/\` as the location for linter rules that
   // Plugin installation (optional — requires stored credentials)
   let plugin: PluginResult | undefined;
   if (options?.installPlugin) {
-    plugin = await tryInstallPlugin(projectRoot, editor);
+    plugin = await tryInstallPlugin(editor);
   }
 
   return {
@@ -226,10 +226,7 @@ async function ensureEslintrcOverride(projectRoot: string): Promise<void> {
  * Attempt to install the archgate plugin using stored credentials.
  * Returns null-safe result — never throws.
  */
-async function tryInstallPlugin(
-  projectRoot: string,
-  editor: EditorTarget
-): Promise<PluginResult> {
+async function tryInstallPlugin(editor: EditorTarget): Promise<PluginResult> {
   const { loadCredentials } = await import("./credential-store");
   const credentials = await loadCredentials();
   if (!credentials) {
@@ -237,13 +234,23 @@ async function tryInstallPlugin(
   }
 
   if (editor === "cursor") {
-    const { installCursorPlugin } = await import("./plugin-install");
-    const files = await installCursorPlugin(projectRoot, credentials.token);
-    return {
-      installed: true,
-      autoInstalled: true,
-      detail: `Extracted ${files.length} files to .cursor/`,
-    };
+    const {
+      isCursorCliAvailable,
+      installCursorPlugin,
+      buildCursorMarketplaceUrl,
+    } = await import("./plugin-install");
+
+    if (await isCursorCliAvailable()) {
+      try {
+        await installCursorPlugin(credentials.token);
+        return { installed: true, autoInstalled: true };
+      } catch {
+        // Fall through to manual instructions
+      }
+    }
+
+    const url = buildCursorMarketplaceUrl();
+    return { installed: true, detail: url };
   }
 
   if (editor === "vscode") {
diff --git a/src/helpers/plugin-install.ts b/src/helpers/plugin-install.ts
index 6f80e128..9cd9a16b 100644
--- a/src/helpers/plugin-install.ts
+++ b/src/helpers/plugin-install.ts
@@ -1,7 +1,6 @@
 /** Download and install the archgate plugin for supported editors. */
 
-import { mkdirSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { unlinkSync } from "node:fs";
 
 import { logDebug } from "./log";
 import { internalPath } from "./paths";
@@ -14,6 +13,9 @@ const MARKETPLACE_URL = "https://plugins.archgate.dev/archgate.git";
 /** Base VS Code marketplace URL — credentials are provided by the git credential manager. */
 const VSCODE_MARKETPLACE_URL =
   "https://plugins.archgate.dev/archgate/vscode.git";
+/** Cursor Team Marketplace URL — credentials are provided by the git credential manager. */
+const CURSOR_MARKETPLACE_URL =
+  "https://plugins.archgate.dev/archgate/cursor.git";
 
 /**
  * Run a command using Bun.spawn (cross-platform, no shell).
@@ -53,6 +55,14 @@ export function buildVscodeMarketplaceUrl(): string {
   return VSCODE_MARKETPLACE_URL;
 }
 
+/**
+ * Get the Cursor Team Marketplace URL for plugin installation.
+ * Credentials are provided by the git credential manager (no tokens in URLs).
+ */
+export function buildCursorMarketplaceUrl(): string {
+  return CURSOR_MARKETPLACE_URL;
+}
+
 /**
  * Check whether the `claude` CLI is available on the system PATH.
  * On WSL, also checks for `claude.exe` (Windows-side installation).
@@ -62,6 +72,14 @@ export async function isClaudeCliAvailable(): Promise<boolean> {
   return resolved !== null;
 }
 
+/**
+ * Check whether the `cursor` CLI is available on the system PATH.
+ */
+export async function isCursorCliAvailable(): Promise<boolean> {
+  const resolved = await resolveCommand("cursor");
+  return resolved !== null;
+}
+
 /**
  * Install the archgate plugin via the `claude` CLI.
  *
@@ -127,19 +145,34 @@ async function downloadPluginAsset(
 }
 
 // ---------------------------------------------------------------------------
-// Cursor — download and extract plugin bundle
+// Cursor — download .vsix and install via `cursor` CLI
 // ---------------------------------------------------------------------------
 
-/** Download cursor.tar.gz and extract it to the project root. */
-export async function installCursorPlugin(
-  projectRoot: string,
-  token: string
-): Promise<string[]> {
-  const buffer = await downloadPluginAsset("/api/cursor", token);
+/** Install the archgate VS Code extension in Cursor via `cursor --install-extension`. */
+export async function installCursorPlugin(token: string): Promise<void> {
+  const vsixPath = internalPath("archgate.vsix");
+  const buffer = await downloadPluginAsset("/api/vscode", token);
   logDebug(
-    `Downloaded cursor plugin archive (${Math.round(buffer.byteLength / 1024)} KB)`
+    `Downloaded VS Code extension (${Math.round(buffer.byteLength / 1024)} KB)`
   );
-  return extractTarGz(new Uint8Array(buffer), projectRoot);
+  await Bun.write(vsixPath, buffer);
+
+  try {
+    const cursorCmd = (await resolveCommand("cursor")) ?? "cursor";
+    logDebug("Installing VS Code extension in Cursor via cursor CLI");
+    const result = await run([cursorCmd, "--install-extension", vsixPath]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `cursor --install-extension failed (exit ${result.exitCode})`
+      );
+    }
+  } finally {
+    try {
+      unlinkSync(vsixPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -229,70 +262,3 @@ export async function installVscodeExtension(token: string): Promise<void> {
     }
   }
 }
-
-// ---------------------------------------------------------------------------
-// Shared — tar extraction helper
-// ---------------------------------------------------------------------------
-
-/**
- * Validate that tar archive entries do not escape the destination directory
- * via path traversal ("..") or absolute paths.
- */
-function validateTarEntries(entries: string[]): void {
-  for (const entry of entries) {
-    const normalized = entry.replaceAll("\\", "/");
-    if (
-      normalized.startsWith("/") ||
-      normalized.includes("../") ||
-      normalized === ".."
-    ) {
-      throw new Error(
-        `Unsafe path in plugin archive: "${entry}" — aborting extraction`
-      );
-    }
-  }
-}
-
-/**
- * Extract a .tar.gz buffer to a destination directory.
- * Uses system tar (available on macOS, Linux, and Windows 10+).
- * Validates archive entries before extraction to prevent path traversal.
- */
-async function extractTarGz(
-  data: Uint8Array,
-  destDir: string
-): Promise<string[]> {
-  // Write the archive to a temporary file
-  const tmpArchive = join(destDir, ".archgate-cursor-plugin.tar.gz");
-  await Bun.write(tmpArchive, data);
-
-  try {
-    mkdirSync(destDir, { recursive: true });
-
-    // List entries first and validate before extracting
-    const listResult = await run(["tar", "-tzf", tmpArchive]);
-    const files = listResult.stdout
-      .split("\n")
-      .map((f) => f.trim())
-      .filter(Boolean);
-
-    validateTarEntries(files);
-
-    // Extract only after validation passes
-    const result = await run(["tar", "-xzf", tmpArchive, "-C", destDir]);
-
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to extract plugin archive (tar exit code ${result.exitCode})`
-      );
-    }
-
-    return files;
-  } finally {
-    try {
-      unlinkSync(tmpArchive);
-    } catch {
-      // Ignore cleanup errors
-    }
-  }
-}
diff --git a/tests/commands/plugin/url.test.ts b/tests/commands/plugin/url.test.ts
index 170089ac..f2af355d 100644
--- a/tests/commands/plugin/url.test.ts
+++ b/tests/commands/plugin/url.test.ts
@@ -33,6 +33,11 @@ describe("registerPluginUrlCommand", () => {
     registerPluginUrlCommand(program);
     const sub = program.commands.find((c) => c.name() === "url")!;
     const editorOpt = sub.options.find((o) => o.long === "--editor")!;
-    expect(editorOpt.argChoices).toEqual(["claude", "vscode", "copilot"]);
+    expect(editorOpt.argChoices).toEqual([
+      "claude",
+      "cursor",
+      "vscode",
+      "copilot",
+    ]);
   });
 });

From cf2f4aeb7d302db0144b1f6bde5603cac2f51e3c Mon Sep 17 00:00:00 2001
From: rhuanbarreto <283004+rhuanbarreto@users.noreply.github.com>
Date: Mon, 30 Mar 2026 14:02:24 +0000
Subject: [PATCH 2/2] docs: regenerate llms-full.txt

---
 docs/public/llms-full.txt | 74 +++++++++++++++++++++------------------
 1 file changed, 40 insertions(+), 34 deletions(-)

diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index a833c09a..dc66b553 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -1443,7 +1443,12 @@ archgate init --editor cursor
 
 The Cursor plugin is currently in beta. Run `archgate login` to sign up and authenticate.
 
-If you have logged in via `archgate login`, the init command also downloads and installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor's AI agent a full governance workflow.
+If you have logged in via `archgate login`, the init command also installs the Archgate plugin for Cursor. The plugin provides pre-built agent rules and skills that give Cursor's AI agent a full governance workflow.
+
+The plugin is distributed in two ways:
+
+1. **Cursor Team Marketplace** -- The plugin is published to a git-based team marketplace repository. After installation, Cursor discovers it from the team marketplace URL printed by the CLI.
+2. **VS Code Extension (VSIX)** -- A `.vsix` extension is installed into Cursor via the `cursor --install-extension` command.
 
 To explicitly install the plugin:
 
@@ -1452,7 +1457,7 @@ archgate login              # one-time setup
 archgate init --editor cursor --install-plugin
 ```
 
-The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. It includes agent rules and skill definitions.
+The `archgate plugin install --editor cursor` command installs the VS Code extension via `cursor` CLI if available and prints the team marketplace URL; it prints manual instructions otherwise.
 
 To install or reinstall the plugin on an already-initialized project:
 
@@ -1472,30 +1477,31 @@ Without the plugin, `archgate init --editor cursor` still configures a basic gov
 
 ## What the plugin provides
 
-The plugin adds an agent and role-based skills to Cursor. Each is invoked as a slash command with the `/ag-` prefix. The agent orchestrates the governance workflow, invoking skills as needed.
+The plugin adds an agent and role-based skills to Cursor. Cursor's plugin system handles namespacing, so skills use their direct names without a prefix.
 
 ### Agent
 
-| Slash command   | Purpose                                                                     |
-| --------------- | --------------------------------------------------------------------------- |
-| `/ag-developer` | General development agent that reads ADRs before coding and validates after |
+| Name        | Purpose                                                                     |
+| ----------- | --------------------------------------------------------------------------- |
+| `developer` | General development agent that reads ADRs before coding and validates after |
 
-The `/ag-developer` agent orchestrates the skills below automatically as part of its workflow.
+The `developer` agent orchestrates the skills below automatically as part of its workflow.
 
 ### Skills
 
-| Slash command         | Purpose                                                                               |
-| --------------------- | ------------------------------------------------------------------------------------- |
-| `/ag-architect`       | Validates code changes against all project ADRs for structural compliance             |
-| `/ag-quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
-| `/ag-adr-author`      | Creates and edits ADRs following project conventions                                  |
-| `/ag-onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
+| Name              | Purpose                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `architect`       | Validates code changes against all project ADRs for structural compliance             |
+| `quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
+| `adr-author`      | Creates and edits ADRs following project conventions                                  |
+| `onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
+| `cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide         |
 
-These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's slash command interface with the `ag-` prefix.
+These are the same agent and skills available in the Claude Code plugin (`archgate:developer`, `archgate:architect`, etc.), adapted for Cursor's plugin system.
 
 ## Initial setup with onboard
 
-After installing the plugin, run `/ag-onboard` in your project once. This skill:
+After installing the plugin, run the `onboard` skill in your project once. This skill:
 
 1. Explores your codebase structure (directories, key files, package configuration)
 2. Interviews you about your team's conventions, constraints, and architectural decisions
@@ -1508,17 +1514,17 @@ The onboard skill is designed to run once per project. After onboarding, the oth
 
 ### With the plugin
 
-The `/ag-developer` skill follows a structured workflow for every coding task:
+The `developer` agent follows a structured workflow for every coding task:
 
-1. **Read applicable ADRs** -- The agent calls `review_context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.
+1. **Read applicable ADRs** -- The agent runs `archgate review-context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.
 
 2. **Write code following ADR constraints** -- The agent implements changes following the Do's and Don'ts from the applicable ADRs.
 
-3. **Run compliance checks** -- The agent runs `archgate check` to execute automated rules. Any violations are fixed before proceeding.
+3. **Run compliance checks** -- The agent runs `archgate check --staged` to execute automated rules. Any violations are fixed before proceeding.
 
-4. **Architect review** -- The agent invokes `/ag-architect` to validate structural ADR compliance beyond what automated rules catch.
+4. **Architect review** -- The agent invokes the `architect` skill to validate structural ADR compliance beyond what automated rules catch.
 
-5. **Capture learnings** -- The agent invokes `/ag-quality-manager` to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.
+5. **Capture learnings** -- The agent invokes the `quality-manager` skill to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.
 
 ### Without the plugin
 
@@ -1546,15 +1552,15 @@ This behavior is consistent regardless of how the developer phrases the request.
 
 ## When to use each agent or skill
 
-| Scenario                                     | Slash command         |
-| -------------------------------------------- | --------------------- |
-| Starting a new project with Archgate         | `/ag-onboard`         |
-| Day-to-day coding tasks                      | `/ag-developer`       |
-| Reviewing a PR for ADR compliance            | `/ag-architect`       |
-| Noticing a recurring pattern worth codifying | `/ag-quality-manager` |
-| Creating or editing an ADR                   | `/ag-adr-author`      |
+| Scenario                                     | Skill             |
+| -------------------------------------------- | ----------------- |
+| Starting a new project with Archgate         | `onboard`         |
+| Day-to-day coding tasks                      | `developer`       |
+| Reviewing a PR for ADR compliance            | `architect`       |
+| Noticing a recurring pattern worth codifying | `quality-manager` |
+| Creating or editing an ADR                   | `adr-author`      |
 
-The `/ag-developer` agent orchestrates the skills automatically -- it invokes `/ag-architect` and `/ag-quality-manager` as part of its workflow. Most of the time, you only need to use `/ag-developer` directly.
+The `developer` agent orchestrates the skills automatically -- it invokes `architect` and `quality-manager` as part of its workflow. Most of the time, you only need to use `developer` directly.
 
 ## Governance rule
 
@@ -1571,10 +1577,10 @@ The command accepts two optional flags:
 
 ## Tips for effective usage
 
-- **Use `/ag-developer` for coding tasks.** It orchestrates the full read-validate-capture workflow automatically.
-- **Run `/ag-onboard` once per project.** It sets up your initial ADRs based on your actual codebase and conventions.
-- **Use `/ag-architect` for PR reviews.** It validates structural compliance beyond what automated rules catch.
-- **Use `/ag-quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
+- **Use the `developer` skill for coding tasks.** It orchestrates the full read-validate-capture workflow automatically.
+- **Run `onboard` once per project.** It sets up your initial ADRs based on your actual codebase and conventions.
+- **Use `architect` for PR reviews.** It validates structural compliance beyond what automated rules catch.
+- **Use `quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
 - **Commit the `.cursor/` directory.** This ensures every team member gets the same governance configuration when they clone the repository.
 - **Keep ADR rules files up to date.** The agent enforces what the rules check for -- if a rule is missing, the violation will not be caught.
 
@@ -3316,7 +3322,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the
 
 **Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead.
 
-**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory.
+**Cursor:** If the `cursor` CLI is on your PATH, the VS Code extension is installed automatically via `cursor --install-extension`. The team marketplace URL is printed for manual plugin discovery.
 
 ## Output
 
@@ -3523,7 +3529,7 @@ Installation behavior varies by editor:
 
 - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise.
 - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise.
-- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`.
+- **Cursor:** Installs the VS Code extension via `cursor` CLI if available and prints the team marketplace URL; prints manual instructions otherwise.
 - **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise.
 
 ## Examples