pantheon-opencode 1.6.0-beta.9 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +144 -365
  4. package/README.md +124 -607
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +504 -141
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +22 -13
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +850 -45
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +99 -383
  29. package/scripts/install/interrupt.mjs +78 -0
  30. package/scripts/install/migrate.mjs +49 -25
  31. package/scripts/install/model-picker.mjs +218 -250
  32. package/scripts/install/opencode-state.mjs +91 -0
  33. package/scripts/install/opencode-version.mjs +83 -21
  34. package/scripts/install/opencode.mjs +1675 -187
  35. package/scripts/install/plan-artifact.mjs +517 -0
  36. package/scripts/install/plan.mjs +475 -0
  37. package/scripts/install/plugin.mjs +214 -27
  38. package/scripts/install/prompt-result.mjs +2 -0
  39. package/scripts/install/run-record.mjs +115 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +93 -8
  43. package/scripts/install/v2-capabilities.mjs +205 -0
  44. package/scripts/install/venv.mjs +90 -47
  45. package/scripts/install/verify.mjs +128 -0
  46. package/scripts/install/vision-prompt.mjs +173 -0
  47. package/scripts/install-mcp.mjs +2 -2
  48. package/scripts/manifest-inventory.mjs +49 -3
  49. package/scripts/mcp_persistence.py +1535 -1050
  50. package/scripts/memory_mcp.py +12 -843
  51. package/scripts/node-engine-policy.mjs +85 -0
  52. package/scripts/package-evidence.mjs +10 -2
  53. package/scripts/postinstall.mjs +26 -26
  54. package/scripts/probe-pantheon-cost.mjs +118 -19
  55. package/scripts/prune.mjs +9 -3
  56. package/scripts/reconcile.mjs +325 -0
  57. package/scripts/release-gates.mjs +687 -0
  58. package/scripts/restore.mjs +222 -0
  59. package/scripts/run-node-tests.mjs +24 -8
  60. package/scripts/sync-artifacts.mjs +19 -7
  61. package/scripts/sync-tui.mjs +5 -1
  62. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  63. package/scripts/uninstall.mjs +369 -34
  64. package/scripts/update.mjs +164 -0
  65. package/scripts/validate-node-engine-policy.mjs +13 -0
  66. package/scripts/version-check.mjs +34 -1
  67. package/scripts/versioning.mjs +23 -3
  68. package/scripts/vision-status.mjs +682 -0
  69. package/skills-lock.json +8 -8
  70. package/src/agents/aphrodite.md +13 -10
  71. package/src/agents/apollo.md +4 -5
  72. package/src/agents/athena.md +74 -46
  73. package/src/agents/demeter.md +10 -7
  74. package/src/agents/gaia.md +0 -1
  75. package/src/agents/hephaestus.md +4 -3
  76. package/src/agents/hermes.md +10 -9
  77. package/src/agents/iris.md +6 -1
  78. package/src/agents/mnemosyne.md +10 -4
  79. package/src/agents/nyx.md +4 -4
  80. package/src/agents/prometheus.md +12 -11
  81. package/src/agents/talos.md +6 -0
  82. package/src/agents/zeus.md +84 -56
  83. package/src/instructions/agent-return-format.instructions.md +12 -41
  84. package/src/instructions/memory-protocol.instructions.md +5 -11
  85. package/src/instructions/test-economy.instructions.md +12 -0
  86. package/src/instructions/yagni.instructions.md +6 -15
  87. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  88. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  89. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  90. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  91. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  92. package/src/mcp/_pantheon_paths.py +24 -0
  93. package/src/mcp/mcp_codemap_module.py +86 -18
  94. package/src/mcp/mcp_persistence.py +1535 -1050
  95. package/src/mcp/memory_mcp.py +444 -94
  96. package/src/mcp/pantheon_vision.py +285 -41
  97. package/src/mcp/requirements-mcp.txt +6 -1
  98. package/src/mcp/requirements-vision.txt +1 -1
  99. package/src/pantheon/context-pruner.ts +541 -0
  100. package/src/pantheon/cost-command.ts +901 -60
  101. package/src/pantheon/delegation-enforce.ts +160 -23
  102. package/src/pantheon/goal-loop.ts +11 -8
  103. package/src/pantheon/guard-path.ts +162 -0
  104. package/src/pantheon/memory-context.ts +1017 -0
  105. package/src/pantheon/model-agents.ts +19 -0
  106. package/src/pantheon/model-command.ts +218 -56
  107. package/src/pantheon/model-pricing.ts +536 -0
  108. package/src/pantheon/presets.mjs +2 -0
  109. package/src/pantheon/task-result-guard.ts +50 -14
  110. package/src/pantheon/v2-bounded-read.ts +654 -0
  111. package/src/pantheon/v2-bridge.ts +27 -0
  112. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  113. package/src/pantheon/v2-execute-after.ts +135 -24
  114. package/src/pantheon/v2-model-overrides.ts +275 -0
  115. package/src/pantheon/v2-shell-hooks.ts +260 -0
  116. package/src/pantheon/v2-tools.ts +89 -35
  117. package/src/pantheon/v2-unsupported.mjs +34 -7
  118. package/src/pantheon/v2-vision.ts +622 -0
  119. package/src/pantheon/vision-local.ts +531 -0
  120. package/src/pantheon/vision.ts +1166 -116
  121. package/src/plugin-v2.ts +1039 -171
  122. package/src/plugin.ts +37 -13
  123. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  124. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  125. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  126. package/src/plugins/tui/dist/tui.js +1 -1
  127. package/src/plugins/tui/package-lock.json +15 -15
  128. package/src/plugins/tui/package.json +7 -5
  129. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  130. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  131. package/src/routing.yml +50 -5
  132. package/src/skills/agent-coordination/SKILL.md +7 -2
  133. package/src/skills/artifact-management/SKILL.md +5 -1
  134. package/src/skills/auto-continue/SKILL.md +14 -6
  135. package/src/skills/codemap/SKILL.md +1 -1
  136. package/src/skills/memory-bank/SKILL.md +21 -13
  137. package/src/skills/session-goal/SKILL.md +12 -22
  138. package/src/skills/spec-driven-development/SKILL.md +3 -1
  139. package/src/skills/worktrees/SKILL.md +30 -11
  140. package/scripts/probe-context-rehydrate.mjs +0 -263
package/README.pt-BR.md CHANGED
@@ -1,392 +1,167 @@
1
+ <!-- synced-from: README.md @ 7359e4f -->
1
2
  # Pantheon
2
3
 
3
- **Uma forma mais clara de trabalhar com OpenCode em projetos reais.** O
4
- Pantheon reúne planejamento, implementação, revisão e documentação em uma
5
- experiência guiada. É um plugin e instalador para OpenCode, feito para pessoas
6
- e equipes que querem mais estrutura sem perder o controle do próprio código.
4
+ **Uma forma mais clara de trabalhar com OpenCode em projetos de software
5
+ reais.** O Pantheon reúne planejamento, implementação, revisão e documentação
6
+ numa experiência guiada. É um plugin e instalador para OpenCode, feito para
7
+ desenvolvedores e equipes que querem estrutura útil sem abrir mão do controle
8
+ sobre o próprio código.
7
9
 
8
10
  [English](README.md) ·
9
11
  [Repositório](https://github.com/ils15/pantheon-opencode) · [Licença MIT](LICENSE)
10
12
 
11
- [![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=versão)](https://github.com/ils15/pantheon-opencode/releases/latest)
13
+ [![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/latest)
12
14
  [![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)
13
15
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22650136.svg)](https://doi.org/10.5281/zenodo.22650136)
14
16
 
15
17
  ## O que é?
16
18
 
17
- O Pantheon é um companheiro para o [OpenCode](https://opencode.ai/) que ajuda a
18
- transformar uma ideia em uma alteração revisada. Ele oferece uma forma comum
19
- de planejar o trabalho, avançar, conferir resultados e preservar o contexto
20
- útil do projeto.
19
+ O Pantheon é um companheiro do [OpenCode](https://opencode.ai/) que ajuda a ir
20
+ de uma ideia a uma mudança revisada. Quatorze agentes especializados
21
+ compartilham um único fluxo: planejar, implementar, checar, revisar e registrar
22
+ o que importou. Você continua no controle de cada decisão e de cada merge.
21
23
 
22
24
  ## Por que usar?
23
25
 
24
- - **Menos troca de contexto:** planeje e construa no mesmo fluxo.
25
- - **Alterações mais conscientes:** peça revisões e verificações antes de
26
- considerar o trabalho concluído.
27
- - **Um ponto de partida repetível:** use a mesma configuração em projetos e
28
- com colaboradores diferentes.
29
- - **Você continua no comando:** o Pantheon apoia suas decisões, mas não
30
- substitui seu julgamento nem a revisão do código gerado.
26
+ - **Menos troca de contexto:** planejamento e construção no mesmo fluxo.
27
+ - **Mudanças mais deliberadas:** peça revisões e checagens antes de considerar
28
+ o trabalho concluído.
29
+ - **Um ponto de partida repetível:** o mesmo setup entre projetos e
30
+ colaboradores.
31
+ - **Você no comando:** o Pantheon apoia seu julgamento; não o substitui.
32
+ - **Coordenação na medida:** trabalho limitado vai para um especialista;
33
+ planejamento, descoberta, trabalho paralelo e revisão entram quando escopo e
34
+ risco pedem. `/pantheon-deepwork` continua sendo o fluxo com checkpoints para
35
+ trabalho pesado em várias fases.
31
36
 
32
37
  ## Comece em 2 minutos
33
38
 
34
- Requisitos: [OpenCode 1.18.4+](https://opencode.ai/docs/) e Node.js `^22.22.2 || ^24.15.0 || >=26.0.0`.
39
+ Requisitos: [OpenCode](https://opencode.ai/docs/) **1.19.x** (V1) ou **OpenCode
40
+ 2.x** (V2), e Node.js **>=26.4.0** para a CLI e as ferramentas. **OpenCode 2.0.22
41
+ tem falha conhecida**; veja [Compatibilidade](docs/COMPATIBILITY.md).
35
42
 
36
- No projeto em que você quer usar o Pantheon:
43
+ No projeto onde você quer usar o Pantheon:
37
44
 
38
45
  ```bash
39
46
  npx pantheon-opencode init
40
47
  opencode
41
48
  ```
42
49
 
43
- O instalador orienta você pelas opções disponíveis. Para servidores MCP
44
- opcionais, instalação local no projeto ou uso sem perguntas, consulte o
45
- [guia de instalação](docs/INSTALLATION.md).
46
-
47
- ## Um exemplo simples
48
-
49
- Com o OpenCode em execução, descreva o resultado que você quer:
50
+ Depois descreva o resultado desejado:
50
51
 
51
52
  ```text
52
- /pantheon Adicione exportação CSV à página de relatórios, com testes e revisão.
53
+ /pantheon Add CSV export to the reports page, including tests and a review.
53
54
  ```
54
55
 
55
- O Pantheon ajuda a transformar esse pedido em um plano e em etapas revisadas.
56
-
57
- ## Para quem é?
58
-
59
- Para desenvolvedores, mantenedores e equipes que usam OpenCode e querem uma
60
- forma mais consistente de lidar com correções pequenas e mudanças maiores. É
61
- especialmente útil quando o projeto se beneficia de decisões registradas,
62
- verificações repetíveis e passagens claras entre etapas do trabalho.
63
-
64
- ## O que inclui?
65
-
66
- - Um instalador guiado para disponibilizar o Pantheon no OpenCode.
67
- - Instruções e comandos reutilizáveis para planejar, construir, revisar e
68
- documentar o trabalho.
69
- - Memória de projeto para preservar contexto relevante entre sessões.
70
- - Integrações opcionais para tarefas comuns de desenvolvimento.
71
-
72
- ## Status
73
-
74
- Versão operacional neste checkout: **v1.6.0-beta.1** (primeira beta compatível
75
- com OpenCode 2; esta página não afirma publicação). O Pantheon foi feito para OpenCode e depende da
76
- disponibilidade e da configuração do OpenCode e dos serviços opcionais que você
77
- escolher. Veja as [releases](https://github.com/ils15/pantheon-opencode/releases)
78
- e o [changelog](CHANGELOG.md) para acompanhar as mudanças publicadas.
79
-
80
-
81
- ## Execução code-mode (opt-in explícito)
82
-
83
- Scripts executados pelo MCP server `pantheon-code-mode` (`execute_code_script`)
84
- só rodam quando aprovados explicitamente. A aprovação fica em
85
- `.pantheon/code-mode/manifest.json` com o SHA-256 de cada script.
86
-
87
- - **Sem manifest → nada executa** (`INVALID_STATE`); nunca há execução implícita.
88
- - **Script fora do manifest → `CONFLICT`**; é preciso aprovar antes.
89
- - **Hash divergente → `CORRUPT_DATA`**; edições após a aprovação são detectadas.
90
-
91
- Aprove (ou reaprove) um script com a tool `approve_code_script`. O instalador
92
- semeia o manifest com o hash de todos os scripts empacotados. Os resultados
93
- seguem o contrato de nove códigos (`OK`, `UNSUPPORTED`, `UNAVAILABLE`,
94
- `INVALID_INPUT`, `INVALID_STATE`, `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`,
95
- `ESCALATE`) e, com `json_output=true`, incluem o campo `status`.
96
-
97
- O code-mode resolve primeiro o projeto: `.opencode/.pantheon/code-mode` vem
98
- antes de `.pantheon/code-mode`. `PANTHEON_PROJECT` sobrescreve o diretório de
99
- trabalho, e o MCP instalado usa `cwd: "."` para receber o workspace do
100
- OpenCode. O diretório global só é usado sem um diretório de projeto utilizável;
101
- depois de selecionar um diretório de projeto, manifest ausente ou corrompido
102
- falha fechado, sem fallback silencioso. O `doctor` valida o manifest e o
103
- SHA-256 de cada script sem regenerá-lo.
104
-
105
-
106
- ## Novidades da 1.6.0-beta.1
107
-
108
- - Primeira beta compatível com o contrato de plugin do OpenCode 2.
109
- - Remoção do pipeline legado de vector-memory, preservando a busca por palavras-
110
- chave SQLite FTS5/BM25 e as ferramentas de codemap `code_*`.
111
- - Validações de CI e release fail-closed; `doctor` e o sandbox exclusivo V2
112
- cobrem o caminho de instalação do OpenCode 2.
113
-
114
- ## OpenCode V1/V2 — Versão dupla (1.6.0-beta.1)
56
+ Quando você pede um plano, Athena devolve o plano a Zeus, que o exibe na
57
+ conversa principal antes de pedir aprovação — nunca como um plano escondido na
58
+ conversa de um agente filho.
115
59
 
116
- Esta é a primeira beta compatível com o OpenCode 2. O Pantheon tem dois contratos de plugin OpenCode **exclusivos**. A configuração
117
- comum do OpenCode pode ser compartilhada, mas o registro do plugin Pantheon é
118
- selecionado por instalação; os plugins Pantheon V1 e V2 nunca devem ser
60
+ Reinicie o OpenCode depois de instalar ou trocar a geração do plugin. O
61
+ instalador seleciona uma geração por instalação; plugins V1 e V2 nunca são
119
62
  registrados juntos.
120
63
 
121
- | | V1 | V2 |
122
- |---|---|---|
123
- | Chave de config do OpenCode | `plugin` singular | `plugins` plural |
124
- | Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
125
- | Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 3 ferramentas (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos, session hooks (`prompt`, `context`), um hook de ferramenta `execute.before` que impõe sessões somente-leitura, além de transforms de configuração |
126
- | APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
127
-
128
- O plugin V2 fornece 3 ferramentas de orquestração (`hashline_edit`,
129
- `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
130
- `session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
131
- `context`) e um hook de ferramenta `execute.before` que impõe sessões
132
- somente-leitura. As 3 ferramentas de goal **não** são
133
- registradas no V2: o goal loop precisa de um `GoalStore`, de um
134
- `GoalLoopClient` e de um `BackgroundJobBoard`, nenhum dos quais o
135
- `PluginContext` do V2 expõe, então a lacuna é reportada como o marcador de
136
- recurso sem suporte `goal-tools`. Use o contrato V1 se precisar do goal loop.
137
-
138
- O hook `execute.before` do V2 é o ponto de imposição de sessões somente-leitura
139
- dessa superfície: o host inclui o agente ativo no evento, um agente somente-leitura
140
- (`apollo`, `gaia`) registra sua sessão, e o `createEnforcementGuard`
141
- compartilhado lança para negar `edit`, `write`, `bash`, `task`,
142
- `hashline_edit` e `pantheon_model`. Ele **não** depende do hook
143
- `tool.execute.before` do V1, que vive em `src/plugin.ts` e não é carregado
144
- quando apenas `plugin-v2` está configurado. O hook `permission.evaluate`
145
- aplica no V2 a matriz caller/target para destinos gerenciados pelo Pantheon,
146
- considerando todos os itens do array `resources` do host. Recursos
147
- exclusivamente nativos são repassados sem alteração à política de permissões do
148
- OpenCode; pedidos mistos (nativos/Pantheon) e com vários destinos são negados,
149
- a menos que todos os destinos Pantheon sejam explicitamente permitidos para o
150
- chamador autoritativo. Uma negação explícita do host é final, e dados de
151
- recursos ausentes ou desconhecidos são negados por padrão. O `execute.after` do
152
- V2 executa a cadeia de resultados concluídos `task-result-guard` →
153
- `context-sandbox` → `read-enhancer`; eventos de erro permanecem inalterados.
154
-
155
- Toda ferramenta V2 declara um schema `output`. O OpenCode 2.0.x exige que a
156
- declaração e o resultado resolvido concordem nos dois sentidos, então uma
157
- ferramenta sem declaração — ou que retorne `output` sem declará-lo — falha em
158
- toda chamada. Os recursos V2 sem suporte são `legacy-hooks` (a superfície de
159
- hooks específica do V1), `catalog-transform`, `integration-transform`,
160
- `skill-transform` e `goal-tools`.
161
-
162
- O pacote expõe os dois contratos como exports importáveis:
163
- `pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
164
- `pantheon-opencode/v2-bridge` (interop opcional), para que o host carregue
165
- explicitamente o contrato desejado.
166
-
167
- A ponte V1→V2 (`src/pantheon/v2-bridge.ts`) habilita interop opcional:
168
- singletons de infraestrutura V1 (BackgroundJobBoard,
169
- GoalStore, TodoEnforcer, VisionHandler) são repassados via `ctx.options` do V2.
170
- A ponte é opcional — o V2 funciona standalone com degradação graciosa.
171
-
172
- Selecione o contrato explicitamente na instalação:
64
+ Flags do instalador, códigos de saída, planos salvos, backup e restore,
65
+ desinstalação, reconcile e pins de MCP estão no
66
+ [guia de instalação](docs/INSTALLATION.md). Para os primeiros dez minutos
67
+ apenas — `init` → reiniciar → `/dispatch` → primeiro resultado — veja o
68
+ [Início rápido](docs/QUICKSTART.md).
69
+
70
+ ## O que está incluído?
71
+
72
+ - **14 agentes especializados**, com um orquestrador, especialistas de
73
+ implementação, um gate de qualidade e papéis de apoio.
74
+ - **20 skills** e instruções reutilizáveis para planejar, construir, revisar e
75
+ documentar.
76
+ - **5 servidores MCP locais** para memória de projeto, persistência, recursos,
77
+ execução confinada de scripts e visão.
78
+ - **Uma TUI opcional**, com bloco de dispatch na sidebar e painel `/dispatch`
79
+ em largura total.
80
+
81
+ A memória é usada seletivamente: o coordenador busca uma vez apenas quando o
82
+ histórico do projeto pode afetar a tarefa e repassa os resultados relevantes aos
83
+ especialistas. Grave um resultado conciso e reutilizável ao concluir a tarefa
84
+ quando ele for importar depois; resumos rotineiros de filhos ficam no handoff.
85
+ Veja [Memória](docs/MEMORY.md).
86
+
87
+ ## Compatibilidade
88
+
89
+ OpenCode **1.19.x** (plugin V1) e **OpenCode 2.x** (plugin V2) são suportados.
90
+ **OpenCode 2.0.22 tem falha conhecida.** A partir da 1.7, a linha abandona o
91
+ contrato V1 e mira apenas o OpenCode 2.
92
+
93
+ A política de suporte, a exceção conhecida e a evidência de versões verificadas
94
+ têm um único lar: [Compatibilidade](docs/COMPATIBILITY.md).
95
+
96
+ A matriz de suporte, o piso de Node e as notas de host/build, as regras de
97
+ geração OpenCode 1.x/2.x, a posição de fim de vida e os problemas conhecidos têm
98
+ um único lar: [Compatibilidade](docs/COMPATIBILITY.md).
99
+
100
+ ## Delegação
101
+
102
+ O Pantheon delega pelo motor nativo de sessões filhas do host: `subagent` no
103
+ runtime raiz relatado pelo usuário, chamado de `task()` na documentação de
104
+ host/API. Disponibilidade de ferramenta, suporte a background e observabilidade
105
+ de conclusão dependem do runtime; quando a conclusão não é observável, use
106
+ dispatch síncrono ou aguarde uma notificação do host.
107
+
108
+ Todo dispatch raiz leva um briefing conciso — objetivo, escopo limitado,
109
+ entradas relevantes, restrições, formato de retorno esperado e verificação. Os
110
+ contratos de retorno são específicos por papel: implementação usa
111
+ `## subtask_summary`, investigação devolve achados estruturados, Athena devolve
112
+ o plano completo e respostas de conselho usam `## specialist_response`.
113
+ Trabalho delegado tem no máximo uma retentativa após falha transitória, e o
114
+ Pantheon nunca alega fan-in determinístico ou recuperação de job sem um
115
+ mecanismo exposto.
116
+
117
+ O modelo de delegação, a matriz chamador/alvo e os gates de aprovação estão em
118
+ [Arquitetura](docs/ARCHITECTURE.md) e
119
+ [Permissões, Gates e Delegação](docs/PERMISSIONS-QUALITY-DELEGATION.md).
173
120
 
174
- ```bash
175
- npx pantheon-opencode init --opencode-version v1
176
- npx pantheon-opencode init --opencode-version v2
177
- npx pantheon-opencode init --opencode-version auto
178
- ```
179
-
180
- `auto` é o padrão. `--version v1|v2|auto` é aceito como a grafia antiga do seletor
181
- quando usado depois de `init`. `auto` resolve a geração a partir do host nesta
182
- ordem: um `OPENCODE_VERSION=v1|v2` explícito vence; caso contrário, um
183
- `OPENCODE_BIN` terminando em `opencode2` seleciona V2; caso contrário o binário
184
- do host é consultado com `--version` e uma major >= 2 seleciona V2. Qualquer
185
- outro caso — uma sonda ilegível, um banner não interpretável, ou um banner
186
- cujos tokens de versão se contradizem sem um nome de ferramenta que desfaça o
187
- empate — avisa uma vez e volta para V1, porque uma entrada de diretório em
188
- `plugins` plural em um host 1.x desconhecido perde o plugin inteiro.
189
-
190
- A sonda prefere o token que vem logo após o nome da ferramenta, então um token
191
- de runtime antes dele (`node v22.1.0 (opencode 1.18.33)`) ou uma data de build
192
- no final (`opencode v1.18.33 built 2026.10.04`) não conseguem virar a geração.
193
- O instalador remove referências Pantheon das duas formas de config antes de
194
- gravar apenas o registro Pantheon selecionado. Entradas de terceiros não são
195
- convertidas nem reivindicadas por essa regra.
196
-
197
- O relatório `pantheon_cost`, disponível nos plugins V1 e V2, resolve o banco por
198
- CAMINHO, nesta ordem: um `dbPath` explícito fornecido pelo chamador da
199
- ferramenta, depois `PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db`,
200
- depois `OPENCODE_DB`, e por fim o padrão do XDG `opencode.db`. Não há nome de
201
- arquivo por versão nessa cadeia: `opencode-v2.db` não é um banco de um host 2.x
202
- — é o nome que um sandbox dá ao próprio banco de estado via `OPENCODE_DB`.
203
-
204
- A distinção v1/v2 é o SCHEMA DETECTADO, não o nome do arquivo. O relatório
205
- procura as tabelas `message` e `session_message` e lê aquele que o banco aberto
206
- realmente tiver, porque um banco migrado carrega as duas famílias ao mesmo
207
- tempo. `PANTHEON_OPENCODE_VERSION=v1|v2` não seleciona arquivo nenhum: apenas
208
- estreita um conjunto já detectado para uma família de tabelas, e falha rápido
209
- quando o valor não é `v1` nem `v2` ou quando a família pedida não existe lá.
210
- Sem a variável, todas as famílias detectadas são lidas. Um banco sem nenhuma
211
- das duas tabelas volta como erro acionável (`CORRUPT_DATA`), e um ledger que
212
- existe mas não produz tokens legíveis como `UNSUPPORTED` — nunca como um
213
- relatório vazio com sucesso.
214
-
215
- O instalador continua gravando as configurações de compatibilidade exigidas
216
- pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
217
- converte um plugin V1 em V2 nem dá hooks V1 ao V2.
218
-
219
- O Pantheon não define mais um teto de passos para os agentes. No OpenCode 2 o
220
- campo `steps` é opcional e não tem default: ausente significa que o host não
221
- aplica nenhum limite nativo. Uma config escrita antes dessa mudança ainda
222
- carrega o valor antigo, e o caminho de instalação v2 o remove de todos os
223
- agentes que o Pantheon gerencia — um agente definido por você nunca é tocado,
224
- e o bloco V1 singular `agent`, em retirada, é deixado intacto. Rode o
225
- instalador uma vez para limpar um valor antigo de uma config existente:
226
-
227
- ```bash
228
- npx pantheon-opencode init --opencode-version=v2
229
- ```
230
-
231
- O controle de contexto não é uma configuração do Pantheon. Qualquer orçamento
232
- que um agente terá vem das settings de compactação do próprio host OpenCode,
233
- e o Pantheon não as define.
234
-
235
- Quando um bloco V1 `agent` e um bloco V2 `agents` coexistem — o que acontece
236
- em qualquer `opencode.json` já instalado — a conversão V1→V2 mescla os dois em
237
- vez de deixar um substituir o outro. O bloco V2 é a base, os campos
238
- gerenciados que vêm do V1 sobrescrevem, e os seus próprios campos são
239
- preservados, com a mesma precedência que o instalador já aplica em outros
240
- pontos. A ordem das chaves não muda o resultado.
241
-
242
- ## Atualizando entre releases (beta.5+)
243
-
244
- Um comando mantém uma instalação existente em dia:
245
-
246
- ```bash
247
- # Sem instalação global, SEMPRE fixe o dist-tag — `npx pantheon-opencode`
248
- # puro resolve a tag `latest`, que é o release estável (1.4.3):
249
- npx pantheon-opencode@beta update # canal beta do npm + refresh do config
250
- npx pantheon-opencode@beta update --stable # canal estável
251
-
252
- # Com instalação global, use o bin global (o padrão é o canal beta):
253
- pantheon-opencode update
254
- ```
121
+ ## Documentação
255
122
 
256
- O `update` compara a versão instalada com o dist-tag do npm, roda
257
- `npm install -g pantheon-opencode@<canal>` e re-executa `init --yes
258
- --headless` para alinhar merge de config, venv e entradas de MCP com o novo
259
- pacote. Duas garantias de freshness sustentam isso:
260
-
261
- - **Sync de artifacts no postinstall** — depois de qualquer `npm install`, os
262
- artefatos de cópia (agents, skills, AGENTS.md, commands, scripts MCP,
263
- payload code-mode) são atualizados automaticamente no config dir existente;
264
- você nunca precisa re-rodar `init` só para atualizar arquivos.
265
- - **Detecção de drift** — o instalador grava a versão instalada em
266
- `.pantheon/install-state.json` e o `doctor` avisa quando o pacote é mais
267
- novo que o último sync, apontando para o `update`.
268
-
269
- O `init` também ganhou `--components agents,skills,...` (instalação enxuta),
270
- `--clean` (alias de `--force`), `--opencode-version auto`, escrita atômica do
271
- config com backup em `opencode.json.bak`, pré-checagens de python3/npm antes
272
- de escrever qualquer arquivo e runtime Python não-fatal: se a venv falha, a
273
- instalação completa mas as entradas MCP ficam de fora (com aviso) em vez de
274
- apontar para um interpretador quebrado.
275
-
276
- ## Releases
277
-
278
- A publicação é autorizada **somente** por um `workflow_dispatch` explícito do
279
- workflow `Release` (o input `release_channel` escolhe beta ou stable). Labels
280
- de PR, push, merge e tag nunca publicam nada, e todos os gates de validação são
281
- fail-closed: somente um PASS explícito autoriza release evidence. Consulte
282
- [docs/RELEASING.md](docs/RELEASING.md) para detalhes de validação e recuperação.
283
-
284
- A validação mantém cada manifest junto do seu lockfile: o root
285
- `package.json` + `package-lock.json` e o TUI
286
- `src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Ambos usam
287
- `npm ci --ignore-scripts`; uma falha em `npm ci` bloqueia a execução e não há
288
- fallback para `npm install`. Uma release carrega um único tarball `.tgz`, calcula
289
- o SHA-256 desse mesmo artefato e vincula o tarball e o GitHub Release ao
290
- `TARGET_SHA` completo; um segundo pack não é intercambiável.
291
-
292
- ## Validação em sandbox (V2)
293
-
294
- O `scripts/test-opencode-v2-sandbox.sh` valida o pacote instalado
295
- globalmente como um usuário real dentro de um sandbox isolado (com `HOME`,
296
- prefix npm e venv próprios) — nunca o ambiente de desenvolvimento. Ele verifica
297
- a perna OpenCode V2: o binário, conectividade MCP, `doctor` e — com
298
- `--prompts` — uma bateria de prompts cobrindo o recurso `pantheon://agents`,
299
- memory store/recall, escrita no filesystem e delegação de agente. O gate é
300
- fail-closed: todo check obrigatório precisa terminar em PASS explícito;
301
- timeout, falha de auth/rede/provider e pré-requisitos ausentes bloqueiam a
302
- execução.
303
-
304
- "V2" aqui se refere somente ao canário de hooks observado em um host OpenCode
305
- v2.0.18, no qual ao menos um callback testado foi disparado; isso não
306
- estabelece compatibilidade com o SDK estável `@opencode/plugin@2.0.18` nem com
307
- o contrato 2.x completo. Esta branch ainda fixa a dependência transitória
308
- `@opencode-ai/plugin@1.18.30`. Em hosts com `opencode` e `opencode2`, este
309
- último costuma ser um shim que executa o mesmo binário; a comparação lado a
310
- lado anterior, portanto, não provava nada sobre o binário em si. O projeto é
311
- exclusivo V2, portanto há uma única perna.
123
+ | Comece aqui | Aprofunde |
124
+ |---|---|
125
+ | [Instalação](docs/INSTALLATION.md) | [Arquitetura](docs/ARCHITECTURE.md) |
126
+ | [Início rápido](docs/QUICKSTART.md) | [MCP](docs/MCP.md) · [Ferramentas MCP](docs/mcp-tools.md) |
127
+ | [Atualização](docs/UPGRADING.pt-BR.md) | [Memória](docs/MEMORY.md) |
128
+ | [Compatibilidade](docs/COMPATIBILITY.md) | [OpenCode V2](docs/opencode-v2.md) |
129
+ | [Agentes e Skills](docs/agents/README.md) | [Plataformas](docs/PLATFORMS.md) |
130
+ | [Processo de release](docs/RELEASING.md) | [Proteção de branch](docs/BRANCH-PROTECTION.md) |
131
+ | [Roteamento de modelos](docs/reference/model-routing.md) | [Variáveis de ambiente](docs/reference/env-vars.md) · [Code Mode](docs/reference/code-mode.md) |
132
+ | [Contribuição](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) |
133
+
134
+ > Os demais documentos são publicados apenas em inglês, que é a fonte canônica.
135
+ > Este README e o [guia de atualização](docs/UPGRADING.pt-BR.md) são as duas
136
+ > páginas mantidas em português.
312
137
 
313
- ```bash
314
- scripts/test-opencode-v2-sandbox.sh --prepare # tarball + install + init no sandbox
315
- scripts/test-opencode-v2-sandbox.sh --run v2 # apenas validação base
316
- scripts/test-opencode-v2-sandbox.sh --prompts # validação base + bateria de prompts
317
- scripts/test-opencode-v2-sandbox.sh --rehydrate # sondas offline de rehydration/summary de sessão
318
- scripts/test-opencode-v2-sandbox.sh --hooks # canário de callbacks de hooks V2
319
- scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # executa os dois canários
320
- scripts/test-opencode-v2-sandbox.sh --reset # limpa a raiz do sandbox
321
- ```
138
+ ## Status
322
139
 
323
- Os modos são combináveis (ex.: `--prepare --run v2 --prompts`). `--rehydrate`
324
- executa sondas offline de `context_rehydrate` e `context_session_summary`.
325
- `--hooks` executa um canário de hooks V2 com o binário do sandbox para verificar
326
- se os callbacks de hooks são disparados; ele não testa os efeitos dos callbacks
327
- de transform nem comprova o enforcement de segurança `execute.before` do
328
- Pantheon. Com o par de sondas `--rehydrate --hooks` (sem `--run`, `--prompts` ou
329
- `--cost`), o canário de hooks ainda é executado se a rehydration falhar, e o
330
- comando retorna falha em seguida. Esses canários de teste/sandbox não são prova
331
- de enforcement de segurança do Pantheon. Os binários são resolvidos estritamente
332
- dentro do prefix npm do sandbox — um sandbox não preparado falha rápido em vez
333
- de testar silenciosamente a instalação do host.
334
-
335
- Isso valida somente o sandbox isolado e preparado. Um PASS não prova suporte
336
- para todo host real nem para configurações de host que não foram exercitadas.
337
-
338
- ## Cobertura TypeScript do Plugin V2
339
-
340
- `npm run coverage:plugin-v2` executa a suíte `tests/pantheon/*.test.ts` com a
341
- cobertura nativa do Node habilitada para source maps e exige pelo menos 80% de
342
- cobertura de linhas somente para `src/plugin-v2.ts`. Requer Node `v24.15.0`;
343
- coberturas de branches e funções são informativas, não gates. Isso não é uma
344
- alegação de cobertura do repositório inteiro.
345
-
346
- Variáveis de ambiente:
347
-
348
- | Variável | Padrão | Finalidade |
349
- |----------|---------|---------|
350
- | `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Raiz do sandbox (recusada se insegura para `--reset`) |
351
- | `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configura somente o plugin V1; o runner de sandbox exclusivo V2 não consome nem oferece suporte a essa variável |
352
- | `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | Spec npm que fornece o binário `opencode2` |
353
- | `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Modelo usado pelo init e pelos prompts |
354
- | `PANTHEON_PROMPT_TIMEOUT` | `300` | Timeout por prompt em segundos |
355
-
356
- Códigos de saída: `0` sem falhas reais · `1` falha real (veja
357
- `prompts-report.md` na raiz do sandbox) · `2` erro de uso · `3` sandbox não
358
- preparado.
359
-
360
- ### Divergência intencional do memory MCP
361
-
362
- `scripts/memory_mcp.py` e `src/mcp/memory_mcp.py` são
363
- intencionalmente diferentes. A cópia independente em `scripts/` mantém o
364
- contrato leve de `memory_*`; a cópia instalada em `src/mcp/` também expõe o
365
- schema opcional de codemap e `code_index`, `code_query` e `code_neighbors`. As
366
- outras cópias compartilhadas permanecem idênticas. Não sobrescreva uma cópia de
367
- memória com a outra.
140
+ Os manifests neste checkout expressam a versão em preparação, não uma publicação
141
+ confirmada. Consulte a dist-tag `beta` do npm para saber o que está realmente
142
+ publicado. Veja [Compatibilidade](docs/COMPATIBILITY.md) para os hosts
143
+ suportados e as [releases](https://github.com/ils15/pantheon-opencode/releases)
144
+ para as mudanças publicadas mais recentes.
368
145
 
369
- ## Documentação
146
+ ## Novidades
370
147
 
371
- - [Instalação](docs/INSTALLATION.md) · [Início rápido](docs/QUICKSTART.md)
372
- - [Arquitetura](docs/ARCHITECTURE.md) · [Ferramentas MCP](docs/mcp-tools.md)
373
- - [Plataformas](docs/PLATFORMS.md) · [Atualização](docs/UPGRADING.pt-BR.md)
374
- - [Referência de agentes](docs/agents/README.md) · [Referência de skills](src/skills/README.md)
375
- - [Processo de release](docs/RELEASING.md) · [Contribuição](CONTRIBUTING.md)
376
- - [Changelog](CHANGELOG.md)
148
+ Veja a [release no GitHub](https://github.com/ils15/pantheon-opencode/releases)
149
+ e o [CHANGELOG.md](CHANGELOG.md) para as mudanças da 1.6.0.
377
150
 
378
151
  ## Contribua
379
152
 
380
- Ideias, relatos de problemas, melhorias na documentação e contribuições de
381
- código são bem-vindos. Leia [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir
382
- uma issue ou pull request.
153
+ Ideias, relatos de bugs, melhorias de documentação e contribuições de código são
154
+ bem-vindos. Leia o [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir uma issue ou
155
+ pull request. Esse arquivo também define a regra de documentação: um único lar
156
+ por fato, com uma lista curta de fatos que não devem ser duplicados.
383
157
 
384
158
  ## Citação e DOI
385
159
 
386
160
  O Pantheon é distribuído sob a [Licença MIT](LICENSE). Cite o
387
- [DOI conceitual do Zenodo](https://doi.org/10.5281/zenodo.22650136), que sempre
388
- resolve para a última release arquivada; cada release também tem seu próprio
389
- version DOI. Os metadados de citação também estão em [CITATION.cff](CITATION.cff).
161
+ [DOI de conceito do Zenodo](https://doi.org/10.5281/zenodo.22650136), que sempre
162
+ resolve para a release arquivada mais recente; cada release também tem seu
163
+ próprio DOI de versão. Os metadados de citação estão em
164
+ [CITATION.cff](CITATION.cff).
390
165
 
391
166
  Repositório canônico: <https://github.com/ils15/pantheon-opencode>
392
167