pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/README.pt-BR.md

@@ -0,0 +1,308 @@
+# Pantheon
+
+**Uma forma mais clara de trabalhar com OpenCode em projetos reais.** O
+Pantheon reúne planejamento, implementação, revisão e documentação em uma
+experiência guiada. É um plugin e instalador para OpenCode, feito para pessoas
+e equipes que querem mais estrutura sem perder o controle do próprio código.
+
+[English](README.md) ·
+[Repositório](https://github.com/ils15/pantheon-opencode) · [Licença MIT](LICENSE)
+
+[![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=versão)](https://github.com/ils15/pantheon-opencode/releases/latest)
+[![CI](https://img.shields.io/github/actions/workflow/status/ils15/pantheon-opencode/ci.yml?branch=main&label=CI)](https://github.com/ils15/pantheon-opencode/actions)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22306637.svg)](https://doi.org/10.5281/zenodo.22306637)
+
+## O que é?
+
+O Pantheon é um companheiro para o [OpenCode](https://opencode.ai/) que ajuda a
+transformar uma ideia em uma alteração revisada. Ele oferece uma forma comum
+de planejar o trabalho, avançar, conferir resultados e preservar o contexto
+útil do projeto.
+
+## Por que usar?
+
+- **Menos troca de contexto:** planeje e construa no mesmo fluxo.
+- **Alterações mais conscientes:** peça revisões e verificações antes de
+  considerar o trabalho concluído.
+- **Um ponto de partida repetível:** use a mesma configuração em projetos e
+  com colaboradores diferentes.
+- **Você continua no comando:** o Pantheon apoia suas decisões, mas não
+  substitui seu julgamento nem a revisão do código gerado.
+
+## Comece em 2 minutos
+
+Requisitos: [OpenCode 1.18.4+](https://opencode.ai/docs/) e Node.js 18+.
+
+No projeto em que você quer usar o Pantheon:
+
+```bash
+npx pantheon-opencode init
+opencode
+```
+
+O instalador orienta você pelas opções disponíveis. Para servidores MCP
+opcionais, instalação local no projeto ou uso sem perguntas, consulte o
+[guia de instalação](docs/INSTALLATION.md).
+
+## Um exemplo simples
+
+Com o OpenCode em execução, descreva o resultado que você quer:
+
+```text
+/pantheon Adicione exportação CSV à página de relatórios, com testes e revisão.
+```
+
+O Pantheon ajuda a transformar esse pedido em um plano e em etapas revisadas.
+
+## Para quem é?
+
+Para desenvolvedores, mantenedores e equipes que usam OpenCode e querem uma
+forma mais consistente de lidar com correções pequenas e mudanças maiores. É
+especialmente útil quando o projeto se beneficia de decisões registradas,
+verificações repetíveis e passagens claras entre etapas do trabalho.
+
+## O que inclui?
+
+- Um instalador guiado para disponibilizar o Pantheon no OpenCode.
+- Instruções e comandos reutilizáveis para planejar, construir, revisar e
+  documentar o trabalho.
+- Memória de projeto para preservar contexto relevante entre sessões.
+- Integrações opcionais para tarefas comuns de desenvolvimento.
+
+## Status
+
+Versão operacional neste checkout: **v1.5.0-beta.2** (candidata; esta página
+não afirma publicação). O Pantheon foi feito para OpenCode e depende da
+disponibilidade e da configuração do OpenCode e dos serviços opcionais que você
+escolher. Veja as [releases](https://github.com/ils15/pantheon-opencode/releases)
+e o [changelog](CHANGELOG.md) para acompanhar as mudanças publicadas.
+
+
+## Execução code-mode (opt-in explícito)
+
+Scripts executados pelo MCP server `pantheon-code-mode` (`execute_code_script`)
+só rodam quando aprovados explicitamente. A aprovação fica em
+`.pantheon/code-mode/manifest.json` com o SHA-256 de cada script.
+
+- **Sem manifest → nada executa** (`INVALID_STATE`); nunca há execução implícita.
+- **Script fora do manifest → `CONFLICT`**; é preciso aprovar antes.
+- **Hash divergente → `CORRUPT_DATA`**; edições após a aprovação são detectadas.
+
+Aprove (ou reaprove) um script com a tool `approve_code_script`. O instalador
+semeia o manifest com o hash de todos os scripts empacotados. Os resultados
+seguem o contrato de nove códigos (`OK`, `UNSUPPORTED`, `UNAVAILABLE`,
+`INVALID_INPUT`, `INVALID_STATE`, `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`,
+`ESCALATE`) e, com `json_output=true`, incluem o campo `status`.
+
+O code-mode resolve primeiro o projeto: `.opencode/.pantheon/code-mode` vem
+antes de `.pantheon/code-mode`. `PANTHEON_PROJECT` sobrescreve o diretório de
+trabalho, e o MCP instalado usa `cwd: "."` para receber o workspace do
+OpenCode. O diretório global só é usado sem um diretório de projeto utilizável;
+depois de selecionar um diretório de projeto, manifest ausente ou corrompido
+falha fechado, sem fallback silencioso. O `doctor` valida o manifest e o
+SHA-256 de cada script sem regenerá-lo.
+
+
+## Novidades da 1.5.0-beta.2
+
+- Instalador exclusivo para OpenCode: guias de plataformas consolidados em um
+  único [guia OpenCode](docs/platforms/opencode.md).
+- Novo CLI `uninstall` com escopos project/global e checagem de ownership:
+  `node scripts/uninstall.mjs --project|--global [--dry-run] [--force]`.
+- Recursos MCP endurecidos: correção do `pantheon://agents` e proteção contra
+  symlink/traversal nos caminhos de recursos.
+- Compatibilidade com OpenCode V2: merge de configuração `plugins` /
+  `mcp.servers.enabled` e launch stdio MCP com PWD correto.
+- `doctor` e health checks de instalação expandidos.
+- Validador de sandbox para instalações globais
+  (`scripts/test-opencode-v1-v2-sandbox.sh`) cobrindo OpenCode V1/V2 lado a
+  lado — veja [Validação em sandbox](#validação-em-sandbox-v1v2).
+- A flag `--prompts` do instalador está planejada para uma release futura.
+
+## OpenCode V1/V2 — Versão dupla (1.5.0-beta.2)
+
+O Pantheon tem dois contratos de plugin OpenCode **exclusivos**. A configuração
+comum do OpenCode pode ser compartilhada, mas o registro do plugin Pantheon é
+selecionado por instalação; os plugins Pantheon V1 e V2 nunca devem ser
+registrados juntos.
+
+| | V1 | V2 |
+|---|---|---|
+| Chave de config do OpenCode | `plugin` singular | `plugins` plural |
+| Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
+| Contrato de runtime | Plugin Pantheon legado, incluindo `pantheon_delegate`, ferramentas read/list, hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 9 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de transforms de configuração |
+| APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
+
+O plugin V2 fornece 9 ferramentas de orquestração (`pantheon_delegate`,
+`pantheon_delegation_read`, `pantheon_delegation_list`, `hashline_edit`,
+`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
+`pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
+`session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
+`context`) e tool hooks (`execute.before`, `execute.after`). O único recurso V2
+sem suporte é `legacy-hooks` (a superfície de API de delegate específica do V1).
+
+O pacote expõe os dois contratos como exports importáveis:
+`pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
+`pantheon-opencode/v2-bridge` (interop opcional), para que o host carregue
+explicitamente o contrato desejado.
+
+A ponte V1→V2 (`src/pantheon/v2-bridge.ts`) habilita interop opcional:
+singletons de infraestrutura V1 (BackgroundJobBoard, DelegationClient,
+GoalStore, TodoEnforcer, VisionHandler) são repassados via `ctx.options` do V2.
+A ponte é opcional — o V2 funciona standalone com degradação graciosa.
+
+Selecione o contrato explicitamente na instalação:
+
+```bash
+npx pantheon-opencode init --opencode-version v1
+npx pantheon-opencode init --opencode-version v2
+npx pantheon-opencode init --opencode-version auto
+```
+
+`--version v1|v2|auto` é aceito como a grafia antiga do seletor quando usado
+depois de `init`. `auto` é conservador, não uma autodetecção geral de
+plataforma: `OPENCODE_VERSION=v1|v2` vence; caso contrário, um `OPENCODE_BIN`
+terminando em `opencode2` seleciona V2; qualquer outro caso seleciona V1. O
+instalador remove referências Pantheon das duas formas de config antes de
+gravar apenas o registro Pantheon selecionado. Entradas de terceiros não são
+convertidas nem reivindicadas por essa regra.
+
+O relatório `pantheon_cost`, disponível nos plugins V1 e V2, pode selecionar o banco com
+`PANTHEON_OPENCODE_VERSION=v1` ou `v2` (`opencode.db` ou `opencode-v2.db`).
+`PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db` tem precedência sobre o
+seletor de versão, e um `dbPath` explícito fornecido pelo chamador da
+ferramenta tem precedência sobre ambos. O resolver nunca consulta o banco da
+outra versão e reporta um erro acionável quando o banco selecionado está
+ausente ou com schema incompatível.
+
+O instalador continua gravando as configurações de compatibilidade exigidas
+pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
+converte um plugin V1 em V2 nem dá hooks V1 ao V2.
+
+## Atualizando entre releases (beta.5+)
+
+Um comando mantém uma instalação existente em dia:
+
+```bash
+# Sem instalação global, SEMPRE fixe o dist-tag — `npx pantheon-opencode`
+# puro resolve a tag `latest`, que é o release estável (1.4.3):
+npx pantheon-opencode@beta update            # canal beta do npm + refresh do config
+npx pantheon-opencode@beta update --stable   # canal estável
+
+# Com instalação global, use o bin global (o padrão é o canal beta):
+pantheon-opencode update
+```
+
+O `update` compara a versão instalada com o dist-tag do npm, roda
+`npm install -g pantheon-opencode@<canal>` e re-executa `init --yes
+--headless` para alinhar merge de config, venv e entradas de MCP com o novo
+pacote. Duas garantias de freshness sustentam isso:
+
+- **Sync de artifacts no postinstall** — depois de qualquer `npm install`, os
+  artefatos de cópia (agents, skills, AGENTS.md, commands, scripts MCP,
+  payload code-mode) são atualizados automaticamente no config dir existente;
+  você nunca precisa re-rodar `init` só para atualizar arquivos.
+- **Detecção de drift** — o instalador grava a versão instalada em
+  `.pantheon/install-state.json` e o `doctor` avisa quando o pacote é mais
+  novo que o último sync, apontando para o `update`.
+
+O `init` também ganhou `--components agents,skills,...` (instalação enxuta),
+`--clean` (alias de `--force`), `--opencode-version auto`, escrita atômica do
+config com backup em `opencode.json.bak`, pré-checagens de python3/npm antes
+de escrever qualquer arquivo e runtime Python não-fatal: se a venv falha, a
+instalação completa mas as entradas MCP ficam de fora (com aviso) em vez de
+apontar para um interpretador quebrado.
+
+## Releases
+
+A publicação é autorizada **somente** por um `workflow_dispatch` explícito do
+workflow `Release` (o input `release_channel` escolhe beta ou stable). Labels
+de PR, push, merge e tag nunca publicam nada, e todos os gates de validação são
+fail-closed: somente um PASS explícito autoriza release evidence. Consulte
+[docs/RELEASING.md](docs/RELEASING.md) para detalhes de validação e recuperação.
+
+A validação mantém cada manifest junto do seu lockfile: o root
+`package.json` + `package-lock.json` e o TUI
+`src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Ambos usam
+`npm ci --ignore-scripts`; uma falha em `npm ci` bloqueia a execução e não há
+fallback para `npm install`. Uma release carrega um único tarball `.tgz`, calcula
+o SHA-256 desse mesmo artefato e vincula o tarball e o GitHub Release ao
+`TARGET_SHA` completo; um segundo pack não é intercambiável.
+
+## Validação em sandbox (V1/V2)
+
+O `scripts/test-opencode-v1-v2-sandbox.sh` valida o pacote instalado
+globalmente como um usuário real dentro de um sandbox isolado (com `HOME`,
+prefix npm e venv próprios) — nunca o ambiente de desenvolvimento. Ele verifica
+OpenCode V1 (`opencode`) e V2 (`opencode2`) lado a lado: binários, conectividade
+MCP, `doctor` e — com `--prompts` — uma bateria de prompts cobrindo o recurso
+`pantheon://agents`, memory store/recall, escrita no filesystem e delegação de
+agente. O gate é fail-closed: todo check obrigatório precisa terminar em PASS
+explícito; timeout, falha de auth/rede/provider e pré-requisitos ausentes
+bloqueiam a execução.
+
+```bash
+scripts/test-opencode-v1-v2-sandbox.sh --prepare          # tarball + install + init no sandbox
+scripts/test-opencode-v1-v2-sandbox.sh --run v1 --prompts # validação base + bateria de prompts (V1)
+scripts/test-opencode-v1-v2-sandbox.sh --run v2           # apenas validação base (V2)
+scripts/test-opencode-v1-v2-sandbox.sh --prompts          # bateria de prompts para as duas versões
+scripts/test-opencode-v1-v2-sandbox.sh --reset            # limpa a raiz do sandbox
+```
+
+Os modos são combináveis (ex.: `--prepare --run v1 --prompts`). Os binários são
+resolvidos estritamente dentro do prefix npm do sandbox — um sandbox não
+preparado falha rápido em vez de testar silenciosamente a instalação do host.
+
+Isso valida somente o sandbox isolado e preparado. Um PASS não prova suporte
+para todo host real nem para configurações de host que não foram exercitadas.
+
+Variáveis de ambiente:
+
+| Variável | Padrão | Finalidade |
+|----------|---------|---------|
+| `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Raiz do sandbox (recusada se insegura para `--reset`) |
+| `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Spec npm que fornece o binário `opencode` |
+| `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | Spec npm que fornece o binário `opencode2` |
+| `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Modelo usado pelo init e pelos prompts |
+| `PANTHEON_PROMPT_TIMEOUT` | `300` | Timeout por prompt em segundos |
+
+Códigos de saída: `0` sem falhas reais · `1` falha real (veja
+`prompts-report.md` na raiz do sandbox) · `2` erro de uso · `3` sandbox não
+preparado.
+
+### Divergência intencional do memory MCP
+
+`scripts/memory_mcp_server.py` e `src/mcp/memory_mcp_server.py` são
+intencionalmente diferentes. A cópia independente em `scripts/` mantém o
+contrato leve de `memory_*`; a cópia instalada em `src/mcp/` também expõe o
+schema opcional de codemap e `code_index`, `code_query` e `code_neighbors`. As
+outras cópias compartilhadas permanecem idênticas. Não sobrescreva uma cópia de
+memória com a outra.
+
+## Documentação
+
+- [Instalação](docs/INSTALLATION.md) · [Início rápido](docs/QUICKSTART.md)
+- [Arquitetura](docs/ARCHITECTURE.md) · [Ferramentas MCP](docs/mcp-tools.md)
+- [Plataformas](docs/PLATFORMS.md) · [Atualização](docs/UPGRADING.pt-BR.md)
+- [Referência de agentes](docs/agents/README.md) · [Referência de skills](src/skills/README.md)
+- [Processo de release](docs/RELEASING.md) · [Contribuição](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## Contribua
+
+Ideias, relatos de problemas, melhorias na documentação e contribuições de
+código são bem-vindos. Leia [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir
+uma issue ou pull request.
+
+## Citação e DOI
+
+O Pantheon é distribuído sob a [Licença MIT](LICENSE). Para o registro histórico
+publicado da v1.4.3 apenas, use o [DOI do Zenodo](https://doi.org/10.5281/zenodo.22306637);
+essa não é a versão operacional atual. Os metadados de citação também estão em
+[CITATION.cff](CITATION.cff).
+
+Repositório canônico: <https://github.com/ils15/pantheon-opencode>
+
+---
+
+[Read in English](README.md)

package/bin/pantheon-init.mjs

@@ -14,17 +14,18 @@
  * install for the operator; state isolation is a runtime concern
  * (OPENCODE_DB ~/.local/share/opencode/opencode-v2.db, service port 49375).
  */
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { fileURLToPath } from 'url'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
 
-const REQUIRED_NODE_MAJOR = 18
+const REQUIRED_NODE_MAJOR = 22
 if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
   console.error(`❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`)
+  console.error('   Install a newer Node via nvm: https://github.com/nvm-sh/nvm')
   process.exit(1)
 }
 
@@ -50,15 +51,21 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --interactive  # Force interactive TUI mode')
   console.log('  npx pantheon-opencode init --headless     # Force non-interactive mode')
   console.log('  npx pantheon-opencode init -y             # Skip confirmations, use defaults')
-  console.log('  npx pantheon-opencode init --version v2    # Label install for OpenCode V2 (beta)')
+  console.log('  npx pantheon-opencode init --components agents,skills,instructions')
+  console.log('  npx pantheon-opencode init --opencode-version v1|v2|auto')
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset')
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)')
+  console.log(
+    '  npx pantheon-opencode update [--stable]    # Update package + re-run init (default: beta channel)',
+  )
   console.log(
     '  npx pantheon-opencode set-tier <name> --project  # Set active model preset (project)',
   )
   console.log('  npx pantheon-opencode prune               # List legacy artifacts (dry-run)')
   console.log('  npx pantheon-opencode prune --apply       # Remove stale backups')
   console.log('  npx pantheon-opencode doctor [--profile]  # Run health check')
+  console.log('  npx pantheon-opencode uninstall --project   # Remove project artifacts safely')
+  console.log('  npx pantheon-opencode uninstall --global    # Remove global artifacts safely')
   console.log('  npx pantheon-opencode --version, -v       # Print version and exit')
   console.log('  npx pantheon-opencode --help              # Show this help')
 }
@@ -78,11 +85,21 @@ async function main() {
   // prune handles its own --help (delegated to scripts/prune.mjs), so its
   // dispatch must run BEFORE the generic --help check.
   if (command === 'prune') {
-    const { spawnSync } = await import('child_process')
+    const { spawnSync } = await import('node:child_process')
     const pruneScript = path.join(ROOT, 'scripts', 'prune.mjs')
     const result = spawnSync(process.execPath, [pruneScript, ...args.slice(1)], {
       stdio: 'inherit',
-      cwd: ROOT,
+      cwd: process.cwd(),
+    })
+    process.exit(result.status ?? 1)
+  }
+
+  if (command === 'uninstall') {
+    const { spawnSync } = await import('node:child_process')
+    const uninstallScript = path.join(ROOT, 'scripts', 'uninstall.mjs')
+    const result = spawnSync(process.execPath, [uninstallScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
     })
     process.exit(result.status ?? 1)
   }
@@ -91,7 +108,7 @@ async function main() {
   // Forwarding the FULL args (profile, target, --fix, ...) keeps the packaged
   // CLI a thin wrapper; the doctor banner reports the resolved profile.
   if (command === 'doctor') {
-    const { spawnSync } = await import('child_process')
+    const { spawnSync } = await import('node:child_process')
     const doctorScript = path.join(ROOT, 'scripts', 'doctor.mjs')
     const result = spawnSync(process.execPath, [doctorScript, ...args.slice(1)], {
       stdio: 'inherit',
@@ -100,6 +117,78 @@ async function main() {
     process.exit(result.status ?? 1)
   }
 
+  // beta.5: one-command update — check npm dist-tag, install, re-init.
+  // Default channel is `beta` (the prerelease line); `--stable` uses `latest`.
+  if (command === 'update') {
+    const channel = args.includes('--stable') ? 'latest' : 'beta'
+    const current = readVersion()
+    const { spawnSync } = await import('node:child_process')
+    const _S = (await import('../scripts/install/strings.mjs')).strings()
+
+    console.log(`Pantheon OpenCode v${current} — checking the "${channel}" channel...`)
+    const view = spawnSync('npm', ['view', `pantheon-opencode@${channel}`, 'version'], {
+      encoding: 'utf8',
+      timeout: 30_000,
+    })
+    const latest = (view.stdout || '').trim().split('\n').filter(Boolean).pop()
+    if (view.status !== 0 || !latest) {
+      console.error(
+        `❌ Could not reach the npm registry: ${(view.stderr || view.stdout || '').trim() || 'no version returned'}`,
+      )
+      process.exit(1)
+    }
+
+    // Prerelease-aware compare: core (major.minor.patch) first, then the
+    // beta counter; a stable release outranks any beta of the same core.
+    const parsePantheonVersion = (v) => {
+      const m = String(v)
+        .trim()
+        .match(/^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/)
+      if (!m) return null
+      return {
+        core: [+m[1], +m[2], +m[3]],
+        beta: m[4] === undefined ? Number.POSITIVE_INFINITY : +m[4],
+      }
+    }
+    const cmp = (a, b) => {
+      const pa = parsePantheonVersion(a)
+      const pb = parsePantheonVersion(b)
+      if (!pa || !pb) return 0
+      for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
+      }
+      return pa.beta - pb.beta
+    }
+    if (cmp(latest, current) <= 0) {
+      console.log(`✅ Already up to date (installed v${current}; ${channel} channel: v${latest}).`)
+      return
+    }
+
+    console.log(`Updating v${current} → v${latest} (channel: ${channel})...`)
+    const install = spawnSync('npm', ['install', '-g', `pantheon-opencode@${channel}`], {
+      stdio: 'inherit',
+    })
+    if (install.status !== 0) {
+      console.error('❌ npm install failed — the previous installation is untouched.')
+      process.exit(install.status ?? 1)
+    }
+
+    // Refresh config/venv/MCP entries with the NEW package (resolved via
+    // PATH — the freshly installed global bin).
+    const init = spawnSync('pantheon-opencode', ['init', '--yes', '--headless'], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    })
+    if (init.status !== 0 || init.error) {
+      console.error(
+        '⚠️  Updated, but the config refresh did not complete — run `npx pantheon-opencode init` manually.',
+      )
+      process.exit(init.status ?? 1)
+    }
+    console.log(`✅ Updated to v${latest}.`)
+    return
+  }
+
   if (args.includes('--help')) {
     printUsage()
     process.exit(0)
@@ -183,11 +272,49 @@ async function main() {
     const isProject = args.includes('--project')
     const isDryRun = args.includes('--dry-run')
     const skipMCP = args.includes('--no-mcp')
-    const forceReinstall = args.includes('--force')
+    // --clean is an alias of --force (both wipe component dirs + recreate venv).
+    const forceReinstall = args.includes('--force') || args.includes('--clean')
     const runDoctor = args.includes('--doctor')
     const forceInteractive = args.includes('--interactive')
     const forceHeadless = args.includes('--headless')
     const autoYes = args.includes('--yes') || args.includes('-y')
+
+    // beta.5: warn on unrecognized flags instead of silently ignoring them.
+    const VALUE_FLAGS = new Set([
+      '--preset',
+      '--model',
+      '--small-model',
+      '--version',
+      '--opencode-version',
+      '--components',
+    ])
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i]
+      if (!arg.startsWith('--') || arg === '--help') continue
+      if (VALUE_FLAGS.has(arg)) {
+        i++ // skip the flag's value
+        continue
+      }
+      const bare = arg.split('=', 1)[0]
+      if (
+        !VALUE_FLAGS.has(bare) &&
+        ![
+          '--project',
+          '--dry-run',
+          '--no-mcp',
+          '--force',
+          '--clean',
+          '--doctor',
+          '--interactive',
+          '--headless',
+          '--yes',
+          '-y',
+        ].includes(bare)
+      ) {
+        console.error(`⚠️  Unknown option ignored: ${arg}`)
+      }
+    }
+
     const presetIndex = args.indexOf('--preset')
     const presetOpt = presetIndex >= 0 ? (args[presetIndex + 1] ?? null) : null
     // Explicit top-level model overrides for the generated config.
@@ -195,24 +322,73 @@ async function main() {
     const modelOpt = modelIndex >= 0 ? (args[modelIndex + 1] ?? null) : null
     const smallModelIndex = args.indexOf('--small-model')
     const smallModelOpt = smallModelIndex >= 0 ? (args[smallModelIndex + 1] ?? null) : null
-    // --version v1|v2 labels the install target (informational; the config is
-    // shared and V1-shaped under both versions). Invalid values fail fast.
+    // --version v1|v2|auto labels the install target. `auto` resolves the
+    // generation from the opencode binary at install time (see
+    // scripts/install/opencode-version.mjs). Invalid values fail fast.
     const versionIndex = args.indexOf('--version')
-    const versionOpt = versionIndex >= 0 ? (args[versionIndex + 1] ?? null) : null
-    if (versionOpt !== null && versionOpt !== 'v1' && versionOpt !== 'v2') {
-      console.error(`❌ Invalid --version "${versionOpt}" — expected v1 or v2`)
+    const legacyVersionIndex = args.indexOf('--opencode-version')
+    const inlineVersion = args.find((arg) => arg.startsWith('--opencode-version='))
+    const versionOpt =
+      versionIndex >= 0
+        ? (args[versionIndex + 1] ?? null)
+        : legacyVersionIndex >= 0
+          ? (args[legacyVersionIndex + 1] ?? null)
+          : (inlineVersion?.split('=', 2)[1] ?? null)
+    if (
+      versionOpt !== null &&
+      versionOpt !== 'v1' &&
+      versionOpt !== 'v2' &&
+      versionOpt !== 'auto'
+    ) {
+      console.error(`❌ Invalid --version "${versionOpt}" — expected v1, v2 or auto`)
       process.exit(1)
     }
 
-    const components = ['agents', 'skills', 'instructions', 'commands', 'plugins']
-    if (!skipMCP) components.push('runtime')
+    // --components agents,skills,... narrows the install; --no-mcp drops the
+    // runtime component. Unknown component names fail fast (typo protection).
+    const KNOWN_COMPONENTS = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime']
+    const componentsIndex = args.indexOf('--components')
+    const inlineComponents = args.find((arg) => arg.startsWith('--components='))
+    const componentsOpt =
+      componentsIndex >= 0
+        ? (args[componentsIndex + 1] ?? null)
+        : (inlineComponents?.split('=', 2)[1] ?? null)
+    let requestedComponents = null
+    if (componentsOpt !== null) {
+      requestedComponents = componentsOpt
+        .split(',')
+        .map((c) => c.trim())
+        .filter(Boolean)
+      const unknown = requestedComponents.filter((c) => !KNOWN_COMPONENTS.includes(c))
+      if (requestedComponents.length === 0 || unknown.length > 0) {
+        console.error(
+          `❌ Invalid --components "${componentsOpt}" — expected comma-separated names from: ${KNOWN_COMPONENTS.join(', ')}`,
+        )
+        process.exit(1)
+      }
+    }
+
+    const components = requestedComponents ?? [
+      'agents',
+      'skills',
+      'instructions',
+      'commands',
+      'plugins',
+    ]
+    if (!skipMCP && !components.includes('runtime')) components.push('runtime')
+    if (skipMCP) {
+      const runtimeIndex = components.indexOf('runtime')
+      if (runtimeIndex >= 0) components.splice(runtimeIndex, 1)
+    }
 
     // Version info
     const version = readVersion()
+    const { strings } = await import('../scripts/install/strings.mjs')
+    const S = strings()
 
     console.log('')
     if (!forceInteractive || isDryRun) {
-      console.log(`Pantheon OpenCode v${version} — ${isDryRun ? 'DRY RUN' : 'Installing...'}`)
+      console.log(`Pantheon OpenCode v${version} — ${isDryRun ? S.dryRun : S.installing}`)
       console.log('')
     }
 
@@ -229,17 +405,19 @@ async function main() {
         version: versionOpt ?? 'v1',
       })
     } catch (err) {
-      console.error(
-        `❌ Installation failed: ${err.message}\n   Run with --no-mcp to skip Python dependencies:\n     npx pantheon-opencode init --no-mcp\n   Or retry with --force to recreate the venv:\n     npx pantheon-opencode init --force`,
-      )
+      if (err?.message === 'Canceled') {
+        console.error(S.canceled)
+        process.exit(130)
+      }
+      console.error(`${S.installFailed(err.message)}\n${S.failHintNoMcp}\n${S.failHintForce}`)
       process.exit(1)
     }
 
     if (runDoctor && !isDryRun) {
       console.log('')
-      console.log('  Running health check...')
+      console.log(`  ${S.runningHealthCheck}`)
       try {
-        const { spawnSync } = await import('child_process')
+        const { spawnSync } = await import('node:child_process')
         const doctorScript = path.join(ROOT, 'scripts', 'doctor.mjs')
         spawnSync(process.execPath, [doctorScript], { stdio: 'inherit', cwd: ROOT })
       } catch {
@@ -249,16 +427,14 @@ async function main() {
 
     console.log('')
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
-    console.log(`  ✅ Pantheon OpenCode v${version} installed!`)
+    console.log(`  ${S.installedTitle(version)}`)
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
     console.log('')
-    console.log('  Next steps:')
-    console.log('  1. Verify installation:')
-    console.log('     npx pantheon-opencode doctor')
-    console.log('  2. Launch your AI coding tool (OpenCode, Claude Code, Cursor, etc.)')
-    console.log('  3. Invoke agents with @agent-name in chat')
-    console.log('  4. For project-local install:')
-    console.log('     npx pantheon-opencode init --project')
+    console.log(`  ${S.nextSteps}`)
+    console.log(`  ${S.nextVerify}`)
+    console.log(`  ${S.nextLaunch}`)
+    console.log(`  ${S.nextAgents}`)
+    console.log(`  ${S.nextProject}`)
     console.log('')
 
     return

package/opencode.json

@@ -11,6 +11,7 @@
     }
   },
   "default_agent": "zeus",
+  "plugins": ["src/plugin-v2"],
   "experimental": {
     "subagent_depth": 2
   },