feat: add VS Code extension install via plugin install

docs/public/llms-full.txt

@@ -1863,6 +1863,7 @@ If you are already logged in, this command:
 
 1. Creates the `.archgate/` governance directory (ADRs, lint rules)
 2. Adds the authenticated marketplace URL to your VS Code **user settings**
+3. Downloads and installs the Archgate VS Code extension (`.vsix`) if the `code` CLI is available
 
 The `chat.plugins.marketplaces` setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level `settings.json`:
 
@@ -1888,12 +1889,15 @@ archgate plugin install --editor vscode
 
 The command creates or updates the following:
 
-| File                 | Scope | Purpose                                                |
-| -------------------- | ----- | ------------------------------------------------------ |
-| User `settings.json` | User  | `chat.plugins.marketplaces` with the authenticated URL |
+| File                 | Scope       | Purpose                                                |
+| -------------------- | ----------- | ------------------------------------------------------ |
+| User `settings.json` | User        | `chat.plugins.marketplaces` with the authenticated URL |
+| Archgate extension   | Application | VS Code extension installed via `.vsix`                |
 
 The user settings file is merged additively -- existing settings are never overwritten. VS Code's built-in default marketplaces (`github/copilot-plugins`, `github/awesome-copilot`) are preserved when the key is set for the first time.
 
+The VS Code extension is downloaded from the Archgate plugins service and installed via `code --install-extension`. If the `code` CLI is not available, manual installation instructions are printed.
+
 The user-level marketplace setting (added to your `settings.json`):
 
 ```json
@@ -1906,7 +1910,19 @@ The user-level marketplace setting (added to your `settings.json`):
 
 ### Manual setup
 
-If you prefer not to let the CLI modify your user settings, you can add the marketplace URL manually. Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`.
+If you prefer not to let the CLI modify your user settings, you can set things up manually:
+
+**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`.
+
+**Extension:** Download and install the `.vsix` file directly:
+
+```bash
+curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
+code --install-extension archgate.vsix
+rm archgate.vsix
+```
+
+Replace `<token>` with your archgate token from `~/.archgate/credentials`.
 
 ## What the plugin provides
 
@@ -3114,7 +3130,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/`.
-- **VS Code:** Adds the marketplace URL to VS Code user settings.
+- **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
 

docs/src/content/docs/guides/vscode-plugin.mdx

@@ -43,6 +43,7 @@ If you are already logged in, this command:
 
 1. Creates the `.archgate/` governance directory (ADRs, lint rules)
 2. Adds the authenticated marketplace URL to your VS Code **user settings**
+3. Downloads and installs the Archgate VS Code extension (`.vsix`) if the `code` CLI is available
 
 The `chat.plugins.marketplaces` setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level `settings.json`:
 
@@ -68,12 +69,15 @@ archgate plugin install --editor vscode
 
 The command creates or updates the following:
 
-| File                 | Scope | Purpose                                                |
-| -------------------- | ----- | ------------------------------------------------------ |
-| User `settings.json` | User  | `chat.plugins.marketplaces` with the authenticated URL |
+| File                 | Scope       | Purpose                                                |
+| -------------------- | ----------- | ------------------------------------------------------ |
+| User `settings.json` | User        | `chat.plugins.marketplaces` with the authenticated URL |
+| Archgate extension   | Application | VS Code extension installed via `.vsix`                |
 
 The user settings file is merged additively -- existing settings are never overwritten. VS Code's built-in default marketplaces (`github/copilot-plugins`, `github/awesome-copilot`) are preserved when the key is set for the first time.
 
+The VS Code extension is downloaded from the Archgate plugins service and installed via `code --install-extension`. If the `code` CLI is not available, manual installation instructions are printed.
+
 The user-level marketplace setting (added to your `settings.json`):
 
 ```json
@@ -86,7 +90,19 @@ The user-level marketplace setting (added to your `settings.json`):
 
 ### Manual setup
 
-If you prefer not to let the CLI modify your user settings, you can add the marketplace URL manually. Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`.
+If you prefer not to let the CLI modify your user settings, you can set things up manually:
+
+**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`.
+
+**Extension:** Download and install the `.vsix` file directly:
+
+```bash
+curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
+code --install-extension archgate.vsix
+rm archgate.vsix
+```
+
+Replace `<token>` with your archgate token from `~/.archgate/credentials`.
 
 ## What the plugin provides
 

docs/src/content/docs/pt-br/guides/vscode-plugin.mdx

@@ -43,6 +43,7 @@ Se você já estiver logado, este comando:
 
 1. Cria o diretório de governança `.archgate/` (ADRs, regras de lint)
 2. Adiciona a URL autenticada do marketplace nas suas **configurações de usuário** do VS Code
+3. Baixa e instala a extensão Archgate para VS Code (`.vsix`) se o CLI `code` estiver disponível
 
 A configuração `chat.plugins.marketplaces` tem escopo de aplicação no VS Code, então não pode ser definida por workspace. O CLI escreve automaticamente no seu `settings.json` de nível de usuário:
 
@@ -68,12 +69,15 @@ archgate plugin install --editor vscode
 
 O comando cria ou atualiza o seguinte:
 
-| Arquivo                    | Escopo  | Propósito                                         |
-| -------------------------- | ------- | ------------------------------------------------- |
-| `settings.json` do usuário | Usuário | `chat.plugins.marketplaces` com a URL autenticada |
+| Arquivo                    | Escopo    | Propósito                                         |
+| -------------------------- | --------- | ------------------------------------------------- |
+| `settings.json` do usuário | Usuário   | `chat.plugins.marketplaces` com a URL autenticada |
+| Extensão Archgate          | Aplicação | Extensão VS Code instalada via `.vsix`            |
 
 O arquivo de configurações de usuário é mesclado de forma aditiva -- configurações existentes nunca são sobrescritas. Os marketplaces padrão do VS Code (`github/copilot-plugins`, `github/awesome-copilot`) são preservados quando a chave é definida pela primeira vez.
 
+A extensão do VS Code é baixada do serviço de plugins do Archgate e instalada via `code --install-extension`. Se o CLI `code` não estiver disponível, instruções de instalação manual são exibidas.
+
 A configuração do marketplace no nível de usuário (adicionada ao seu `settings.json`):
 
 ```json
@@ -86,7 +90,19 @@ A configuração do marketplace no nível de usuário (adicionada ao seu `settin
 
 ### Configuração manual
 
-Se preferir não deixar o CLI modificar suas configurações de usuário, você pode adicionar a URL do marketplace manualmente. Abra o JSON de configurações de usuário do VS Code (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") e adicione a entrada `chat.plugins.marketplaces` mostrada acima. Você pode encontrar sua URL autenticada executando `archgate login` e verificando `~/.archgate/credentials`.
+Se preferir não deixar o CLI modificar suas configurações, você pode configurar manualmente:
+
+**URL do marketplace:** Abra o JSON de configurações de usuário do VS Code (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") e adicione a entrada `chat.plugins.marketplaces` mostrada acima. Você pode encontrar sua URL autenticada executando `archgate login` e verificando `~/.archgate/credentials`.
+
+**Extensão:** Baixe e instale o arquivo `.vsix` diretamente:
+
+```bash
+curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
+code --install-extension archgate.vsix
+rm archgate.vsix
+```
+
+Substitua `<token>` pelo seu token archgate de `~/.archgate/credentials`.
 
 ## O que o plugin oferece
 

docs/src/content/docs/pt-br/reference/cli-commands.mdx

@@ -246,7 +246,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/`.
-- **VS Code:** Adiciona a URL do marketplace nas configurações de usuário do VS Code.
+- **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
 

docs/src/content/docs/reference/cli-commands.mdx

@@ -248,7 +248,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/`.
-- **VS Code:** Adds the marketplace URL to VS Code user settings.
+- **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
 

src/commands/plugin/install.ts

@@ -13,8 +13,10 @@ import {
   installClaudePlugin,
   installCopilotPlugin,
   installCursorPlugin,
+  installVscodeExtension,
   isClaudeCliAvailable,
   isCopilotCliAvailable,
+  isVscodeCliAvailable,
 } from "../../helpers/plugin-install";
 import { configureVscodeSettings } from "../../helpers/vscode-settings";
 
@@ -102,6 +104,22 @@ export function registerPluginInstallCommand(plugin: Command) {
               `Archgate plugin configured for ${label}.`,
               "Marketplace URL added to VS Code user settings."
             );
+
+            if (await isVscodeCliAvailable()) {
+              await installVscodeExtension(credentials.token);
+              logInfo(`Archgate extension installed for ${label}.`);
+            } else {
+              logWarn(
+                "VS Code CLI (`code`) not found. To install the extension manually, run:"
+              );
+              console.log(
+                `  ${styleText("bold", "curl")} -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix`
+              );
+              console.log(
+                `  ${styleText("bold", "code")} --install-extension archgate.vsix`
+              );
+              console.log(`  rm archgate.vsix`);
+            }
             break;
           }
         }

src/helpers/plugin-install.ts

@@ -1,16 +1,10 @@
-/**
- * plugin-install.ts — Download and install the archgate plugin for supported editors.
- *
- * - Claude Code: auto-installs via `claude` CLI, or prints manual commands as fallback
- * - VS Code:     marketplace URL for manual user-settings configuration (application-scoped)
- * - Copilot CLI:  auto-installs via `copilot` CLI, or prints manual commands as fallback
- * - Cursor:      downloads cursor.tar.gz from the plugins service and extracts it
- */
+/** Download and install the archgate plugin for supported editors. */
 
 import { mkdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
 import { logDebug } from "./log";
+import { internalPath } from "./paths";
 import { resolveCommand } from "./platform";
 
 const PLUGINS_API = "https://plugins.archgate.dev";
@@ -104,47 +98,48 @@ export async function installClaudePlugin(): Promise<void> {
 }
 
 // ---------------------------------------------------------------------------
-// Cursor — download and extract plugin bundle
+// Shared — authenticated asset download
 // ---------------------------------------------------------------------------
 
-/**
- * Download the cursor.tar.gz from the plugins service and extract it to the project root.
- * Creates/overwrites .cursor/ folder contents with the pre-built agent and skills.
- */
-export async function installCursorPlugin(
-  projectRoot: string,
+/** Download a plugin asset from the plugins API with Bearer auth. */
+async function downloadPluginAsset(
+  path: string,
   token: string
-): Promise<string[]> {
-  const response = await fetch(`${PLUGINS_API}/api/cursor`, {
+): Promise<ArrayBuffer> {
+  const response = await fetch(`${PLUGINS_API}${path}`, {
     headers: { Authorization: `Bearer ${token}`, "User-Agent": "archgate-cli" },
     signal: AbortSignal.timeout(30_000),
     redirect: "error",
   });
 
   if (response.status === 401) {
     throw new Error(
-      "Plugin download unauthorized. Your token may have expired — run `archgate login refresh`."
+      "Download unauthorized. Your token may have expired — run `archgate login refresh`."
     );
   }
-
   if (!response.ok) {
     throw new Error(
-      `Plugin download failed (HTTP ${response.status}). Try again later.`
+      `Download failed (HTTP ${response.status}). Try again later.`
     );
   }
 
-  const tarGzBuffer = await response.arrayBuffer();
+  return response.arrayBuffer();
+}
 
-  logDebug(
-    `Downloaded cursor plugin archive (${Math.round(tarGzBuffer.byteLength / 1024)} KB)`
-  );
+// ---------------------------------------------------------------------------
+// Cursor — download and extract plugin bundle
+// ---------------------------------------------------------------------------
 
-  const extractedFiles = await extractTarGz(
-    new Uint8Array(tarGzBuffer),
-    projectRoot
+/** 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);
+  logDebug(
+    `Downloaded cursor plugin archive (${Math.round(buffer.byteLength / 1024)} KB)`
   );
-
-  return extractedFiles;
+  return extractTarGz(new Uint8Array(buffer), projectRoot);
 }
 
 // ---------------------------------------------------------------------------
@@ -195,6 +190,46 @@ export async function installCopilotPlugin(): Promise<void> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// VS Code — download .vsix and install via `code` CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the `code` CLI is available on the system PATH.
+ * On WSL, also checks for `code.exe` (Windows-side installation).
+ */
+export async function isVscodeCliAvailable(): Promise<boolean> {
+  const resolved = await resolveCommand("code");
+  return resolved !== null;
+}
+
+/** Download the .vsix from the plugins service and install via `code` CLI. */
+export async function installVscodeExtension(token: string): Promise<void> {
+  const vsixPath = internalPath("archgate.vsix");
+  const buffer = await downloadPluginAsset("/api/vscode", token);
+  logDebug(
+    `Downloaded VS Code extension (${Math.round(buffer.byteLength / 1024)} KB)`
+  );
+  await Bun.write(vsixPath, buffer);
+
+  try {
+    const codeCmd = (await resolveCommand("code")) ?? "code";
+    logDebug("Installing VS Code extension via code CLI");
+    const result = await run([codeCmd, "--install-extension", vsixPath]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `code --install-extension failed (exit ${result.exitCode})`
+      );
+    }
+  } finally {
+    try {
+      unlinkSync(vsixPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Shared — tar extraction helper
 // ---------------------------------------------------------------------------

tests/helpers/plugin-install.test.ts

@@ -5,6 +5,7 @@ import {
   buildVscodeMarketplaceUrl,
   isClaudeCliAvailable,
   isCopilotCliAvailable,
+  isVscodeCliAvailable,
 } from "../../src/helpers/plugin-install";
 
 describe("plugin-install", () => {
@@ -59,4 +60,11 @@ describe("plugin-install", () => {
       expect(result === true || result === false).toBe(true);
     });
   });
+
+  describe("isVscodeCliAvailable", () => {
+    test("returns a boolean", async () => {
+      const result = await isVscodeCliAvailable();
+      expect(typeof result).toBe("boolean");
+    });
+  });
 });