feat(init): add opencode as a fifth editor target

CLAUDE.md

@@ -68,3 +68,19 @@ The CLI dogfoods itself — see `.archgate/adrs/` for the full list of ADRs and
 ## ADR Format
 
 YAML frontmatter (`id`, `title`, `domain`, `rules`, optional `files`). Sections: Context, Decision, Do's and Don'ts, Consequences, Compliance, References. Companion `.rules.ts` exports a plain object `satisfies RuleSet`.
+
+## Adding a New Editor Target
+
+Editor integrations share the `EditorTarget` union. Adding a new editor requires coordinated edits — missing any one breaks detection, init, or tests:
+
+1. `src/helpers/init-project.ts` — extend `EditorTarget` union, `EDITOR_LABELS`, the `configureEditorSettings` switch, and (when authenticated install applies) the `tryInstallPlugin` branch
+2. `src/helpers/plugin-install.ts` — add `is<Editor>CliAvailable()` and any install/download helper
+3. `src/helpers/editor-detect.ts` — append to the `Promise.all` and the returned array
+4. `src/commands/init.ts` — extend `EDITOR_DIRS`, `SIGNUP_EDITORS`, the `--editor` `.choices([...] as const)`, and `printManualInstructions`
+5. `src/commands/plugin/install.ts` — extend `.choices([...] as const)` and add a case to `installForEditor` + the manual-instructions `catch`
+6. `src/commands/plugin/url.ts` — extend `.choices([...] as const)` and branch before the URL ternary
+7. Tests that assert the exact choice list: `tests/commands/plugin/install.test.ts`, `tests/commands/plugin/url.test.ts`, and `tests/helpers/editor-detect.test.ts` (length + id order)
+
+User-scope editors (e.g., opencode) write to a path resolved in `paths.ts` rather than the project tree — `configureEditorSettings` returns that path for the init summary and the real work happens in `tryInstallPlugin`.
+
+**Match the target editor's actual path resolution — don't assume Windows conventions.** opencode uses the `xdg-basedir` npm package, which falls back to `~/.config` on **all platforms** (including Windows, where it resolves to `C:\Users\<user>\.config\…`, not `%APPDATA%\…`). `opencodeAgentsDir()` must mirror that exact logic or the CLI writes files the editor can't find. When adding a user-scope editor, verify the editor's path helper in its source before writing the resolver.

docs/astro.config.mjs

@@ -218,6 +218,10 @@ export default defineConfig({
             { label: "VS Code Plugin", slug: "guides/vscode-plugin" },
             { label: "Copilot CLI Plugin", slug: "guides/copilot-cli-plugin" },
             { label: "Cursor Integration", slug: "guides/cursor-integration" },
+            {
+              label: "opencode Integration",
+              slug: "guides/opencode-integration",
+            },
             { label: "Pre-commit Hooks", slug: "guides/pre-commit-hooks" },
             { label: "Security", slug: "guides/security" },
           ],

docs/public/llms-full.txt

@@ -1586,6 +1586,142 @@ The command accepts two optional flags:
 
 ---
 
+## Guides: opencode Integration
+
+Source: https://cli.archgate.dev/guides/opencode-integration/
+
+Archgate integrates with [opencode](https://opencode.ai) to give AI agents a structured governance workflow. The agent reads your ADRs before writing code, validates after, and captures new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).
+
+## Setup
+
+Run `archgate init` with the `--editor opencode` flag to configure opencode integration in your project:
+
+```bash
+archgate init --editor opencode
+```
+
+The opencode agent bundle is currently in beta. Run `archgate login` to sign up and authenticate.
+
+Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead — so they live on your machine, not in your repository, and are available across every project you open with opencode.
+
+opencode uses the XDG Base Directory convention on every platform (via the `xdg-basedir` package), so the install location resolves to `$XDG_CONFIG_HOME/opencode/agents/` when that variable is set, and falls back to `$HOME/.config/opencode/agents/` otherwise. That means Windows installs land under `C:\Users\<username>\.config\opencode\agents\`, not under `%APPDATA%`:
+
+| Platform      | Install location                               |
+| ------------- | ---------------------------------------------- |
+| Linux / macOS | `~/.config/opencode/agents/`                   |
+| Windows       | `C:\Users\<username>\.config\opencode\agents\` |
+
+### Authenticated install
+
+The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory — otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`.
+
+If you have logged in via `archgate login` **and** `opencode` is on your PATH, the init command downloads and installs the Archgate agent bundle for opencode. The bundle provides a pre-built primary agent and four subagents that give opencode's AI a full governance workflow.
+
+To explicitly install the agents:
+
+```bash
+archgate login                                  # one-time setup
+archgate init --editor opencode --install-plugin
+```
+
+To install or reinstall on an already-initialized project:
+
+```bash
+archgate plugin install --editor opencode
+```
+
+The install step downloads an authenticated tarball from the Archgate plugins service and extracts the five `archgate-*.md` agent files into the opencode user-scope directory.
+
+### Generated files (user scope)
+
+| File                                            | Purpose                                                                  |
+| ----------------------------------------------- | ------------------------------------------------------------------------ |
+| `<opencode-agents>/archgate-developer.md`       | Primary agent (selectable with Tab) that runs the full ADR workflow      |
+| `<opencode-agents>/archgate-architect.md`       | Subagent that validates code changes against all project ADRs            |
+| `<opencode-agents>/archgate-quality-manager.md` | Subagent that captures learnings and proposes new ADRs                   |
+| `<opencode-agents>/archgate-adr-author.md`      | Subagent that creates and edits ADRs following project conventions       |
+| `<opencode-agents>/archgate-cli-reference.md`   | Internal reference subagent with the Archgate CLI command guide (hidden) |
+
+`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual — only the opencode-specific agent files live outside the project tree.
+
+## What the bundle provides
+
+The `archgate-` prefix avoids collision with any user-authored opencode agents in the same directory. Subagents are invoked via opencode's `@-mention` syntax.
+
+### Primary agent
+
+| Name                 | Purpose                                                                     |
+| -------------------- | --------------------------------------------------------------------------- |
+| `archgate-developer` | General development agent that reads ADRs before coding and validates after |
+
+The `archgate-developer` agent orchestrates the subagents below automatically as part of its workflow.
+
+### Subagents
+
+| Name                       | 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-adr-author`      | Creates and edits ADRs following project conventions                          |
+| `archgate-cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide |
+
+These are the same roles available in the Claude Code plugin, adapted for opencode's native primary/subagent model.
+
+## How it works in practice
+
+Select `archgate-developer` as your primary agent (use the Tab key in opencode) when starting a coding task. The agent follows a structured workflow for every change:
+
+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.
+
+4. **Architect review** -- The agent mentions `@archgate-architect` to validate structural ADR compliance beyond what automated rules catch.
+
+5. **Capture learnings** -- The agent mentions `@archgate-quality-manager` to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.
+
+## ADR-driven refusal
+
+When `archgate-developer` encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant.
+
+For example, if a developer asks the agent to add `chalk` as a dependency in a project governed by a dependency policy ADR, the agent will:
+
+1. Refuse, citing the ADR and the approved dependency list
+2. Suggest using the approved alternative instead
+3. Offer to implement the task using the compliant approach
+
+This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions.
+
+## When to use each agent or subagent
+
+| Scenario                                     | Agent / Subagent               |
+| -------------------------------------------- | ------------------------------ |
+| Day-to-day coding tasks                      | `archgate-developer` (primary) |
+| Reviewing a change for ADR compliance        | `@archgate-architect`          |
+| Noticing a recurring pattern worth codifying | `@archgate-quality-manager`    |
+| Creating or editing an ADR                   | `@archgate-adr-author`         |
+
+The `archgate-developer` agent orchestrates the subagents automatically -- it mentions `@archgate-architect` and `@archgate-quality-manager` as part of its workflow. Most of the time, you only need to select `archgate-developer` and let it run.
+
+## User-scope vs project-scope
+
+The opencode bundle lives in your user-scope opencode directory rather than in `.opencode/` inside your project. Consequences:
+
+- **One install per machine.** `archgate plugin install --editor opencode` installs the bundle globally. Every project you open with opencode sees the same `archgate-*` agents.
+- **Your repo stays clean.** No `.opencode/` folder is ever created by `archgate init`. Team members who want the agents run their own `archgate plugin install --editor opencode`.
+- **Upgrades are global.** Re-running `archgate plugin install --editor opencode` overwrites the existing files with the latest bundle.
+
+## Tips for effective usage
+
+- **Select `archgate-developer` at the start of coding sessions.** It orchestrates the full read-validate-capture workflow automatically.
+- **Use `@archgate-architect` for reviews.** It validates structural compliance beyond what automated rules catch.
+- **Use `@archgate-quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
+- **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.
+- **Re-run `archgate plugin install --editor opencode` to upgrade.** The service returns the latest agent bundle on every authenticated download.
+
+---
+
 ## Guides: Pre-commit Hooks
 
 Source: https://cli.archgate.dev/guides/pre-commit-hooks/
@@ -3311,10 +3447,10 @@ Creates the `.archgate/` directory with an example ADR, companion rules file, an
 
 ## Options
 
-| Option              | Default  | Description                                                               |
-| ------------------- | -------- | ------------------------------------------------------------------------- |
-| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`) |
-| `--install-plugin`  | auto     | Install the Archgate editor plugin (requires prior `archgate login`)      |
+| Option              | Default  | Description                                                                           |
+| ------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |
+| `--install-plugin`  | auto     | Install the Archgate editor plugin (requires prior `archgate login`)                  |
 
 When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise.
 
@@ -3324,6 +3460,8 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the
 
 **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.
 
+**opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details.
+
 ## Output
 
 ```
@@ -3496,9 +3634,9 @@ Print the plugin repository URL for manual tool configuration.
 archgate plugin url [options]
 ```
 
-| Option              | Default  | Description                                             |
-| ------------------- | -------- | ------------------------------------------------------- |
-| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) |
+| Option              | Default  | Description                                                         |
+| ------------------- | -------- | ------------------------------------------------------------------- |
+| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |
 
 The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code:
 
@@ -3521,16 +3659,17 @@ Install the Archgate plugin for the specified editor on an already-initialized p
 archgate plugin install [options]
 ```
 
-| Option              | Default  | Description                                             |
-| ------------------- | -------- | ------------------------------------------------------- |
-| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) |
+| Option              | Default  | Description                                                         |
+| ------------------- | -------- | ------------------------------------------------------------------- |
+| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |
 
 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:** 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.
+- **opencode:** Requires the `opencode` CLI to be on PATH — 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" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details.
 
 ## Examples
 
@@ -3552,6 +3691,12 @@ Install the plugin for Cursor:
 archgate plugin install --editor cursor
 ```
 
+Install the agent bundle for opencode:
+
+```bash
+archgate plugin install --editor opencode
+```
+
 ---
 
 ## Reference: archgate review-context