feat(plugin): install Copilot plugin declaratively, covering the desktop app

.claude/agent-memory/archgate-developer/MEMORY.md

@@ -28,7 +28,7 @@ Exceptions: minor follow-up tweaks after validation already passed, and non-code
 - **Reproduce a described failure before scheduling work from it** — including when your own scan reports zero. Of three issues one audit derived from memory files, two collapsed to nothing once the failure was actually tested (#517 Go proxy, #518 branch protection); the third was real but larger than described (#516). And prove a zero is a real zero: `\b` inside a JS template literal is a backspace, not a word boundary, so a regex built that way found no corruption where 69 occurrences sat.
 - **Content filtering blocks policy/legal boilerplate** — generating a Contributor Covenant or license text can trip API filtering. Ask the user to copy it from the official source.
 - **Files written under `/tmp` by this agent's own Bash/Write calls can vanish between tool calls** — observed for several scratch files with no deleting command run. Write anything that must survive several calls to a real Windows path instead (e.g. `C:/Users/<user>/AppData/Local/Temp/<task-name>/`); Bun/Node on Windows don't resolve Git-Bash-style `/c/Users/...` paths.
-- **`archgate review-context`'s `--base` (auto-detect or explicit `origin/main`) diffs against the local `main`/`origin/main` ref, which can be stale-but-tree-identical after a squash merge** — same content, different commit hash, so it inflates `allChangedFiles` with every file from the last merged PR. Before trusting its output, `git fetch origin main:main`; if `git diff origin/main HEAD --stat` is empty the trees already match and `git reset origin/main` (never `--hard`) safely realigns the branch pointer without touching uncommitted work.
+- **`archgate review-context`'s `--base` (auto-detect or explicit `origin/main`) diffs against the local `main`/`origin/main` ref, which can be stale-but-tree-identical after a squash merge** — same content, different commit hash, so it inflates `allChangedFiles` with every file from the last merged PR. Before trusting its output, `git fetch origin main:main`; the default fix is `git fetch origin` + explicit `--base origin/main` (also the only option in a git worktree, where `fetch origin main:main` is refused because `main` is checked out in the primary tree). Only when the current branch IS the stale `main` and `git diff origin/main HEAD --stat` is empty may `git reset origin/main` (never `--hard`) realign the pointer — it moves the branch and unstages any staged changes, so never run it on a feature branch with local commits.
 - **The tsconfig `composite: true` project only lists `src/`, `tests/`, `lint/` in `include`** — `.archgate/lint/`, `scripts/`, and `shims/` also hold `.ts` source (per GEN-004's `files` globs) but aren't part of the tsc program. Importing from an unlisted dir (e.g. a test unit-testing an oxlint plugin) fails with TS6307, not silent transitive inclusion. Add the dir to `include` if ever needed, but expect it may surface pre-existing type errors never checked before.
 - **`docs/public/llms-full.txt` is auto-regenerated by the `update-llms.yaml` PR workflow whenever `docs/src/content/docs/**` changes** — a bot commit lands on the branch shortly after pushing docs edits. Never hand-edit this file; `git pull` before continuing work on the branch, and don't be alarmed when CodeRabbit flags stale wording inside it — fix the source `.mdx`, not the generated file.
 - **Sizing a flag-removal's blast radius by grep: search each token separately, don't require them on one line.** A pattern requiring `"check"` and `"--json"` on the same line missed `tests/commands/check.test.ts`, where `c.name() === "check"` and `o.long === "--json"` sit on adjacent lines — the test only surfaced when `bun run validate` failed after the "complete" migration.

CLAUDE.md

@@ -110,3 +110,5 @@ User-scope editors (e.g., opencode) write to a path resolved in `paths.ts` rathe
 **Match the target editor's actual path resolution — don't assume Windows conventions.** opencode uses `xdg-basedir`, which falls back to `~/.config` on **all platforms** (Windows: `C:\Users\<user>\.config\…`, not `%APPDATA%\…`). `opencodeAgentsDir()` must mirror that exactly. Verify the editor's own path helper before writing a resolver for a new user-scope editor.
 
 **opencode ships two distributions — CLI detection alone misses the Desktop app.** The Electron-based Desktop app (`@opencode-aidesktop` on Windows) ships **no CLI binary**, so `isOpencodeCliAvailable()` (PATH check) can't detect it. Both distributions share `opencodeConfigDir()` (`~/.config/opencode/`), so `isOpencodeAvailable()` in `plugin-install.ts` also treats that directory's existence as installed. All three call sites (`editor-detect.ts`, `init-project.ts`, `commands/plugin/install.ts`) use the broader `isOpencodeAvailable()` — use it for any new opencode-gated behavior too.
+
+**GitHub Copilot has the same two-distribution shape — and a declarative install path.** The Copilot desktop app ships no CLI binary but shares `copilotConfigDir()` (`~/.copilot/`) with the `copilot` CLI, so copilot-gated behavior must use `isCopilotAvailable()` (PATH check OR config dir exists), never `isCopilotCliAvailable()` alone. The plugin install is declarative-first: `installCopilotPlugin()` always writes the marketplace + plugin declaration into `~/.copilot/settings.json` (`extraKnownMarketplaces` + `enabledPlugins` — Copilot's marketplace registry and auto-install list, read by both distributions on startup; an existing `archgate` entry is overwritten to correct stale URLs), then additionally runs `copilot plugin install archgate@archgate` when the CLI is on PATH. `mode: "declarative"` in the result means the user must restart the Copilot app for the install to take effect. The settings merge lives in `copilot-user-settings.ts` (user-scope); `copilot-settings.ts` is project-scope (`.github/copilot/`).

docs/astro.config.mjs

@@ -229,7 +229,10 @@ export default defineConfig({
             { label: "CI Integration", slug: "guides/ci-integration" },
             { label: "Claude Code Plugin", slug: "guides/claude-code-plugin" },
             { label: "VS Code Plugin", slug: "guides/vscode-plugin" },
-            { label: "Copilot CLI Plugin", slug: "guides/copilot-cli-plugin" },
+            {
+              label: "GitHub Copilot Plugin",
+              slug: "guides/copilot-cli-plugin",
+            },
             { label: "Cursor Integration", slug: "guides/cursor-integration" },
             {
               label: "opencode Integration",

docs/public/llms-full.txt

@@ -9,7 +9,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 guardrails**: 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 enforcement skills.
+- **Editor plugins**: Claude Code, VS Code, Cursor, and GitHub Copilot plugins give AI agents role-based enforcement skills.
 - **Self-governance**: Archgate governs its own development using the same tool.
 
 ## Installation
@@ -28,7 +28,7 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont
 - [Guide: CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline.
 - [Guide: Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a guardrails workflow that reads ADRs, validates code, and captures patterns.
 - [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 guardrails to GitHub Copilot CLI.
+- [Guide: GitHub Copilot Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture guardrails to the GitHub Copilot CLI and desktop app.
 - [Guide: Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills.
 - [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.
@@ -1430,19 +1430,23 @@ The `archgate:developer` agent orchestrates the skills automatically -- it invok
 
 ---
 
-## Guides: Copilot CLI Plugin
+## Guides: GitHub Copilot Plugin
 
 Source: https://cli.archgate.dev/guides/copilot-cli-plugin/
 
-The Archgate Copilot CLI plugin gives AI agents working in [GitHub Copilot CLI](https://github.com/features/copilot) built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).
+The Archgate GitHub Copilot plugin gives AI agents working in [GitHub Copilot](https://github.com/features/copilot) built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).
+
+Both Copilot distributions are supported: the **Copilot CLI** (`copilot` on your PATH) and the **Copilot desktop app**. They share the same configuration directory (`~/.copilot/` by default), so one install covers both.
 
 ## How it works
 
-Copilot CLI supports plugin installation from git repositories using `copilot plugin install`. The Archgate plugin is served from a git repository at `plugins.archgate.dev/archgate.git`, which Copilot CLI recognizes natively -- the same `.claude-plugin/plugin.json` manifest format works for both Claude Code and Copilot CLI.
+Copilot supports plugin marketplaces backed by git repositories. The Archgate plugin is served from `plugins.archgate.dev/archgate/vscode.git` -- the same marketplace used by the VS Code extension, in the `.github/plugin/` manifest format Copilot recognizes natively.
+
+Installation is declarative: the CLI writes the marketplace and plugin declaration into `~/.copilot/settings.json` (`extraKnownMarketplaces` + `enabledPlugins`). Copilot reads this file on startup and installs any declared plugin automatically. When the `copilot` CLI is on your PATH, the CLI also runs `copilot plugin install` so the plugin is available immediately without a restart.
 
 ## Installation
 
-The Copilot CLI plugin is currently in beta. Run `archgate login` to sign up and authenticate before following the steps below.
+The GitHub Copilot plugin is currently in beta. Run `archgate login` to sign up and authenticate before following the steps below.
 
 ### 1. Log in with GitHub
 
@@ -1462,13 +1466,10 @@ Run `archgate init` with the `--editor copilot` flag:
 archgate init --editor copilot
 ```
 
-If you are already logged in and the `copilot` CLI is on your PATH, the plugin is installed automatically via:
-
-```bash
-copilot plugin install https://<github-user>:<token>@plugins.archgate.dev/archgate.git
-```
+If you are logged in and Copilot is installed (CLI or desktop app), the plugin is installed automatically:
 
-If the `copilot` CLI is not found, the command prints the manual command for you to run.
+- **Copilot CLI on PATH:** the plugin is installed immediately via `copilot plugin install`.
+- **Desktop app only:** the plugin is declared in `~/.copilot/settings.json`; restart the Copilot app and it installs automatically on launch.
 
 To explicitly request plugin installation:
 
@@ -1484,37 +1485,40 @@ archgate plugin install --editor copilot
 
 ### Generated files
 
-The command creates the `.github/copilot/` directory for plugin configuration. Plugin installation is handled separately via the `copilot plugin install` command.
+The command creates the `.github/copilot/` directory for project-level configuration and updates the user-level `~/.copilot/settings.json` with the Archgate marketplace and plugin declaration. An entry pointing at an outdated marketplace URL is corrected in place.
 
 ### Manual installation
 
-If the `copilot` CLI is not found during `archgate init`, you can install the plugin manually:
+To install the plugin manually with the `copilot` CLI:
 
 ```bash
-copilot plugin install https://<github-user>:<token>@plugins.archgate.dev/archgate.git
+copilot plugin marketplace add "$(archgate plugin url --editor copilot)"
+copilot plugin install archgate@archgate
 ```
 
-You can find your authenticated URL by running `archgate plugin url copilot`.
+Credentials are provided automatically by your git credential manager (stored during `archgate login`).
 
 ## What the plugin provides
 
-The plugin adds an agent and role-based skills to Copilot CLI. The agent orchestrates the guardrails workflow, invoking skills as needed.
+The plugin adds agents and role-based skills to Copilot. The agent orchestrates the guardrails workflow, invoking skills as needed.
 
-### Agent
+### Agents
 
 | Agent                | Purpose                                                                     |
 | -------------------- | --------------------------------------------------------------------------- |
 | `archgate:developer` | General development agent that reads ADRs before coding and validates after |
+| `archgate:planner`   | Read-only planning agent that designs ADR-compliant implementation plans    |
 
 The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow.
 
 ### Skills
 
 | Skill                      | Purpose                                                                               |
 | -------------------------- | ------------------------------------------------------------------------------------- |
-| `archgate:architect`       | Validates code changes against all project ADRs for structural compliance             |
-| `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
+| `archgate:reviewer`        | Validates code changes against all project ADRs for structural compliance             |
+| `archgate:lessons-learned` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
 | `archgate:adr-author`      | Creates and edits ADRs following project conventions                                  |
+| `archgate:cli-reference`   | Provides the CLI command reference and rules authoring guide to agents                |
 | `archgate:onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
 
 ## Initial setup with onboard
@@ -1544,18 +1548,19 @@ The agent writes code that complies with the constraints from the ADRs. The Do's
 
 After writing code, the agent runs `archgate check` to execute automated rules against the changes. Any violations are fixed before proceeding.
 
-### 4. Architect review
+### 4. Reviewer validation
 
-The agent invokes `archgate:architect` to validate structural ADR compliance beyond what automated rules catch.
+The agent invokes `archgate:reviewer` to validate structural ADR compliance beyond what automated rules catch.
 
 ### 5. Capture learnings
 
-The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing as new ADRs.
+The agent invokes `archgate:lessons-learned` to review the work and identify patterns worth capturing as new ADRs.
 
 ## Tips
 
 - **Run onboard once per project** to generate your initial ADRs from your actual codebase.
 - **Keep ADR rule files up to date** -- the agent enforces what the rules check for.
+- **Desktop app users:** after the first install, restart the Copilot app so it picks up the declared plugin.
 
 ---
 
@@ -4526,7 +4531,7 @@ Re-running `archgate init` does **not** overwrite a manually configured `baseBra
 
 Source: https://cli.archgate.dev/reference/cli/login/
 
-Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login.
+Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, GitHub Copilot, or Cursor), and use case, then registers you before completing the login.
 
 ```bash
 archgate login
@@ -4700,7 +4705,7 @@ archgate plugin install [options]
 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.
+- **GitHub Copilot:** Declares the Archgate marketplace and plugin in Copilot's `settings.json` (`~/.copilot/` by default, honoring `COPILOT_HOME`), which both the Copilot CLI and the Copilot desktop app read. When the `copilot` CLI is on PATH the plugin is also installed immediately; otherwise Copilot installs it automatically on next launch. Prints manual commands when no `copilot` CLI or Copilot settings directory is detected.
 - **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed. Files are written directly to the Cursor user directory.
 - **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise.
 - **opencode:** Requires the `opencode` CLI to be on PATH, and skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" because opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details.
@@ -5067,7 +5072,7 @@ Archgate upgraded to 0.35.0 successfully.
 ? Would you like to update your editor plugins too? (Y/n)
 ```
 
-The CLI auto-detects installed editors (Claude Code, Cursor, VS Code, Copilot CLI, opencode) and runs the plugin install for each selected editor. Plugin update failures are reported but do not affect the exit code -- the CLI upgrade itself is already complete.
+The CLI auto-detects installed editors (Claude Code, Cursor, VS Code, GitHub Copilot, opencode) and runs the plugin install for each selected editor. Plugin update failures are reported but do not affect the exit code -- the CLI upgrade itself is already complete.
 
 Use `--plugins` to skip the prompt and update all detected editors automatically: