pantheon-opencode 1.6.0-beta.8 → 1.6.0

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 (141) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +126 -346
  4. package/README.md +83 -608
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +366 -132
  7. package/commands/pantheon-audit.md +7 -1
  8. package/commands/pantheon-consolidate.md +1 -1
  9. package/commands/pantheon-deepwork.md +14 -3
  10. package/commands/pantheon-focus.md +17 -0
  11. package/commands/pantheon-vision.md +61 -12
  12. package/package.json +19 -11
  13. package/plugin.json +1 -1
  14. package/pyproject.toml +6 -2
  15. package/scripts/_pantheon_paths.py +24 -0
  16. package/scripts/build-agents-md.mjs +368 -69
  17. package/scripts/changelog-merge.mjs +161 -0
  18. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  19. package/scripts/docs-check-changelog.mjs +204 -0
  20. package/scripts/docs-link-check.mjs +314 -0
  21. package/scripts/docs-media.mjs +157 -0
  22. package/scripts/doctor.mjs +828 -40
  23. package/scripts/install/agents-md.mjs +2 -2
  24. package/scripts/install/backup.mjs +648 -0
  25. package/scripts/install/cli-ui.mjs +303 -72
  26. package/scripts/install/component-selection.mjs +61 -0
  27. package/scripts/install/config-migration.mjs +583 -27
  28. package/scripts/install/exit-codes.mjs +26 -0
  29. package/scripts/install/file-inventory.mjs +555 -0
  30. package/scripts/install/health-check.mjs +31 -25
  31. package/scripts/install/interactive.mjs +78 -383
  32. package/scripts/install/migrate.mjs +49 -25
  33. package/scripts/install/model-picker.mjs +218 -250
  34. package/scripts/install/opencode-version.mjs +83 -21
  35. package/scripts/install/opencode.mjs +1465 -180
  36. package/scripts/install/plan-artifact.mjs +517 -0
  37. package/scripts/install/plan.mjs +475 -0
  38. package/scripts/install/plugin.mjs +251 -30
  39. package/scripts/install/prompt-result.mjs +2 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +60 -4
  43. package/scripts/install/venv.mjs +90 -47
  44. package/scripts/install/verify.mjs +128 -0
  45. package/scripts/install/vision-prompt.mjs +173 -0
  46. package/scripts/install-mcp.mjs +2 -2
  47. package/scripts/manifest-inventory.mjs +49 -3
  48. package/scripts/mcp_persistence.py +1535 -1050
  49. package/scripts/memory_mcp.py +12 -843
  50. package/scripts/node-engine-policy.mjs +85 -0
  51. package/scripts/package-evidence.mjs +10 -2
  52. package/scripts/postinstall.mjs +26 -26
  53. package/scripts/probe-pantheon-cost.mjs +118 -19
  54. package/scripts/prune.mjs +9 -3
  55. package/scripts/reconcile.mjs +325 -0
  56. package/scripts/release-gates.mjs +682 -0
  57. package/scripts/restore.mjs +222 -0
  58. package/scripts/run-node-tests.mjs +24 -8
  59. package/scripts/sync-artifacts.mjs +20 -7
  60. package/scripts/sync-tui.mjs +29 -4
  61. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  62. package/scripts/uninstall.mjs +369 -34
  63. package/scripts/update.mjs +164 -0
  64. package/scripts/validate-node-engine-policy.mjs +13 -0
  65. package/scripts/version-check.mjs +34 -1
  66. package/scripts/versioning.mjs +23 -3
  67. package/scripts/vision-status.mjs +682 -0
  68. package/skills-lock.json +8 -8
  69. package/src/agents/aphrodite.md +13 -10
  70. package/src/agents/apollo.md +4 -5
  71. package/src/agents/athena.md +74 -46
  72. package/src/agents/demeter.md +10 -7
  73. package/src/agents/gaia.md +0 -1
  74. package/src/agents/hephaestus.md +4 -3
  75. package/src/agents/hermes.md +10 -9
  76. package/src/agents/iris.md +6 -1
  77. package/src/agents/mnemosyne.md +14 -15
  78. package/src/agents/nyx.md +4 -4
  79. package/src/agents/prometheus.md +12 -11
  80. package/src/agents/talos.md +6 -0
  81. package/src/agents/zeus.md +84 -56
  82. package/src/instructions/agent-return-format.instructions.md +12 -41
  83. package/src/instructions/memory-protocol.instructions.md +5 -11
  84. package/src/instructions/test-economy.instructions.md +12 -0
  85. package/src/instructions/yagni.instructions.md +6 -15
  86. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  87. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  88. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  89. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  90. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  91. package/src/mcp/_pantheon_paths.py +24 -0
  92. package/src/mcp/mcp_codemap_module.py +86 -18
  93. package/src/mcp/mcp_persistence.py +1535 -1050
  94. package/src/mcp/memory_mcp.py +444 -94
  95. package/src/mcp/pantheon_vision.py +285 -41
  96. package/src/mcp/requirements-mcp.txt +5 -0
  97. package/src/pantheon/context-pruner.ts +541 -0
  98. package/src/pantheon/cost-command.ts +814 -60
  99. package/src/pantheon/goal-loop.ts +11 -8
  100. package/src/pantheon/memory-context.ts +1017 -0
  101. package/src/pantheon/model-agents.ts +19 -0
  102. package/src/pantheon/model-command.ts +218 -56
  103. package/src/pantheon/model-pricing.ts +536 -0
  104. package/src/pantheon/presets.mjs +2 -0
  105. package/src/pantheon/task-result-guard.ts +50 -14
  106. package/src/pantheon/v2-bounded-read.ts +640 -0
  107. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  108. package/src/pantheon/v2-execute-after.ts +135 -24
  109. package/src/pantheon/v2-model-overrides.ts +275 -0
  110. package/src/pantheon/v2-tools.ts +89 -35
  111. package/src/pantheon/v2-unsupported.mjs +2 -3
  112. package/src/pantheon/v2-vision.ts +622 -0
  113. package/src/pantheon/vision-local.ts +531 -0
  114. package/src/pantheon/vision.ts +1160 -115
  115. package/src/plugin-v2.ts +654 -162
  116. package/src/plugin.ts +15 -11
  117. package/src/plugins/tui/dist/tui-v2.d.ts +1036 -0
  118. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -0
  119. package/src/plugins/tui/dist/tui-v2.js +3808 -0
  120. package/src/plugins/tui/dist/tui-v2.js.map +1 -0
  121. package/src/plugins/tui/dist/tui.js +4 -4
  122. package/src/plugins/tui/index-v2.ts +6 -0
  123. package/src/plugins/tui/package-lock.json +5416 -1297
  124. package/src/plugins/tui/package.json +14 -10
  125. package/src/plugins/tui/src/index-v2.tsx +4372 -0
  126. package/src/plugins/tui/src/index.tsx +3 -3
  127. package/src/plugins/tui/src/opencode-v2.d.ts +13 -0
  128. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  129. package/src/plugins/tui/tsdown.config.ts +2 -2
  130. package/src/plugins/tui/tui-v2.ts +2 -0
  131. package/src/plugins/tui/tui.ts +3 -0
  132. package/src/routing.yml +50 -5
  133. package/src/skills/agent-coordination/SKILL.md +7 -2
  134. package/src/skills/artifact-management/SKILL.md +5 -1
  135. package/src/skills/auto-continue/SKILL.md +14 -6
  136. package/src/skills/codemap/SKILL.md +1 -1
  137. package/src/skills/memory-bank/SKILL.md +21 -13
  138. package/src/skills/session-goal/SKILL.md +14 -15
  139. package/src/skills/spec-driven-development/SKILL.md +3 -1
  140. package/src/skills/worktrees/SKILL.md +30 -11
  141. package/scripts/probe-context-rehydrate.mjs +0 -263
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  **A clearer way to work with OpenCode on real software projects.** Pantheon
4
4
  brings planning, implementation, review, and documentation into one guided
5
- experience. It is an OpenCode plugin and installer for teams and developers who
5
+ experience. It is an OpenCode plugin and installer for developers and teams who
6
6
  want useful structure without giving up control of their code.
7
7
 
8
8
  [Português (Brasil)](README.pt-BR.md) ·
@@ -14,9 +14,10 @@ want useful structure without giving up control of their code.
14
14
 
15
15
  ## What is it?
16
16
 
17
- Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you
18
- move from an idea to a reviewed change. It gives your coding sessions a shared
19
- way to plan work, make progress, check results, and keep useful project context.
17
+ Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you move
18
+ from an idea to a reviewed change. Fourteen specialized agents share one
19
+ workflow: plan, implement, check, review, and record what mattered. You stay in
20
+ charge of every decision and every merge.
20
21
 
21
22
  ## Why use it?
22
23
 
@@ -25,22 +26,18 @@ way to plan work, make progress, check results, and keep useful project context.
25
26
  finished.
26
27
  - **A repeatable starting point:** use the same setup across projects and
27
28
  collaborators.
28
- - **You stay in charge:** Pantheon supports your decisions; it does not replace
29
- your judgment or your review of generated code.
29
+ - **You stay in charge:** Pantheon supports your judgment; it does not replace
30
+ it.
31
+ - **Right-sized coordination:** bounded work goes to one specialist; planning,
32
+ discovery, parallel work, and review are added when scope and risk call for
33
+ them. `/pantheon-deepwork` remains the checkpointed workflow for heavy
34
+ multi-phase work.
30
35
 
31
36
  ## Start in 2 minutes
32
37
 
33
- Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js
34
- 22.22.2+ (or 24.15.0+ / 26+). For which OpenCode generation each Pantheon
35
- release line supports, see
36
- [Compatibility and support policy](#compatibility-and-support-policy).
37
-
38
- Pantheon declares `engines.node` as `^22.22.2 || ^24.15.0 || >=26.0.0`. The
39
- floor reflects what the dependency tree actually needs — the transitive
40
- `ini@7` rejects earlier 22.x/24.x builds with `EBADENGINE` — and odd-numbered
41
- Node releases (23, 25) are out of range. The `pantheon_cost` tool also needs
42
- `node:sqlite`, which requires Node >= 22.5; `doctor` warns when the running
43
- runtime cannot load it.
38
+ Requirements: [OpenCode](https://opencode.ai/docs/) **1.19.x** (V1) or **OpenCode
39
+ 2.x** (V2), and Node.js **>=26.4.0** for the CLI and tooling. **OpenCode 2.0.22
40
+ is known broken**; see [Compatibility](docs/COMPATIBILITY.md).
44
41
 
45
42
  From the project where you want to use Pantheon:
46
43
 
@@ -49,633 +46,111 @@ npx pantheon-opencode init
49
46
  opencode
50
47
  ```
51
48
 
52
- The installer guides you through the available setup. For optional MCP servers,
53
- project-local installation, or non-interactive setup, see the
54
- [installation guide](docs/INSTALLATION.md).
55
- The bundled Python MCP servers use the pinned MCP SDK 2.2.0 and standalone
56
- FastMCP 4.0.10 runtime; see the [MCP guide](docs/MCP.md).
57
- The installer also turns each agent's `mcp_tools` allowlist into native
58
- per-agent permissions for OpenCode V1 and V2; see the
59
- [agent MCP reference](docs/AGENT-MCP.md).
60
-
61
- ## A simple example
62
-
63
- Once OpenCode is running, describe the outcome you want:
49
+ Then describe the outcome you want:
64
50
 
65
51
  ```text
66
52
  /pantheon Add CSV export to the reports page, including tests and a review.
67
53
  ```
68
54
 
69
- Pantheon helps turn that request into a plan and a sequence of reviewed steps.
55
+ When you ask for a plan, Athena returns it to Zeus, who displays it in the main
56
+ conversation before asking for approval — never as a plan hidden in a child
57
+ agent's conversation.
70
58
 
71
- ## Who is it for?
59
+ Restart OpenCode after installing or changing the plugin generation. The
60
+ installer selects one generation per installation; V1 and V2 plugins are never
61
+ registered together.
72
62
 
73
- Pantheon is for developers, maintainers, and teams using OpenCode who want a
74
- more consistent way to tackle small fixes and larger changes. It is especially
75
- useful when a project benefits from written decisions, repeatable checks, and a
76
- clear handoff between stages of work.
63
+ Installer flags, exit codes, saved plans, backup and restore, uninstall,
64
+ reconcile, and MCP pins are in the [installation guide](docs/INSTALLATION.md).
65
+ For the first ten minutes only — `init` → restart → `/dispatch` → first result —
66
+ see [Quick Start](docs/QUICKSTART.md).
77
67
 
78
- ## What’s included?
68
+ ## What's included?
79
69
 
80
- - A guided installer for making Pantheon available to OpenCode.
81
- - Reusable instructions and commands for planning, building, reviewing, and
82
- documenting work.
83
- - Project memory that helps preserve relevant context between sessions.
84
- - Optional integrations for common development tasks.
70
+ - **14 specialized agents** with one orchestrator, implementation specialists,
71
+ a quality gate, and supporting roles.
72
+ - **20 skills** and reusable instructions for planning, building, reviewing,
73
+ and documenting work.
74
+ - **5 local MCP servers** for project memory, persistence, resources, confined
75
+ script execution, and vision.
76
+ - **An optional TUI** with a dispatch sidebar block and a full-width
77
+ `/dispatch` panel.
85
78
 
86
79
  Memory is used selectively: the coordinator searches once only when project
87
80
  history could affect a task, then passes relevant results to specialists. Store
88
81
  one concise, reusable outcome at task completion when it will matter later;
89
- routine child summaries and phase updates stay in the current handoff. The
90
- session-checkpoint tools are separate, optional persistence APIs and are not
91
- called automatically by compaction hooks. See [Memory usage](docs/MEMORY.md).
92
-
93
- ## Status
94
-
95
- Candidate version: the manifests in this checkout express the version being
96
- prepared, not a confirmed publication. A beta is published only after the
97
- Release workflow completes successfully. To check which version is actually
98
- published, consult the npm `beta` dist-tag. Pantheon is designed for OpenCode
99
- and depends on the availability and configuration of OpenCode and any optional
100
- services you choose to use. Check the
101
- [releases](https://github.com/ils15/pantheon-opencode/releases) and
102
- [changelog](CHANGELOG.md) for the latest published changes.
103
-
104
- ## Compatibility and support policy
105
-
106
- > ### ⚠️ 1.6.x is the LAST line that supports OpenCode 1.X
107
- >
108
- > **OpenCode 1.X support ends after the 1.6 line.** From **1.7 onward, every
109
- > release is a breaking change targeting OpenCode 2.** A 1.6.x install is the
110
- > last one that runs on an OpenCode 1.X host; do not plan an upgrade across the
111
- > 1.6 → 1.7 boundary while your host is still on OpenCode 1.X.
112
-
113
- | Pantheon line | OpenCode 1.X host | OpenCode 2 host |
114
- |---|---|---|
115
- | **1.6.x** (current line) | **Supported.** V1 plugin contract | Supported, reduced surface — V2 contract |
116
- | **1.7 and later** | **Not supported.** Breaking change | Target of the 1.7+ work |
117
-
118
- Both columns of the 1.6.x row are real, and they are not the same claim. Read
119
- [the plugin contract](#opencode-v1v2--dual-version-160-beta1) for what each
120
- generation actually registers.
121
-
122
- ### What "supported on OpenCode 1.X" concretely means
123
-
124
- On the 1.6 line, an OpenCode 1.X host gets the **V1 plugin**:
125
- `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts`, registered under the
126
- singular `plugin` config key. That surface registers 6 tools
127
- (`hashline_edit`, the 3 `pantheon_goal_*` tools, `pantheon_cost`,
128
- `pantheon_model`), the BackgroundJobBoard lifecycle, the V1 event/tool hooks and
129
- the V1 compaction path. It is selected automatically: the generation gate
130
- (`--opencode-version`, else `OPENCODE_VERSION`, else a `OPENCODE_BIN` basename of
131
- `opencode2`, else a `--version` probe where major ≥ 2 selects V2) resolves a 1.X
132
- host to V1.
133
-
134
- The two generations are exclusive. The installer strips Pantheon references from
135
- both config shapes and registers only the selected one, so a 1.X host never
136
- loads the V2 plugin and a V2 host never loads the V1 plugin. Forcing V2 on a 1.X
137
- host is an unsupported mixed/wrong-generation configuration, not a supported mode.
138
-
139
- ### What the OpenCode 2 path is — and is not
140
-
141
- **Not inert.** The V2 path (`src/plugin-v2`, registered as a directory because
142
- the V2 loader rejects bare file paths) registers real tools with real
143
- `input`/`output` schemas via `ctx.tool.transform()`, 5 event subscriptions,
144
- session hooks and tool/permission hooks that enforce read-only sessions and the
145
- caller→target delegation matrix. The matrix applies only to Pantheon-managed
146
- targets: Zeus may delegate to any registered agent; Athena and Hermes may target
147
- Apollo only; other Pantheon callers and unknown callers are denied. Child
148
- sessions cannot delegate to Pantheon agents. Calls between native/custom agents
149
- remain under host permissions. The V2 path never adds an allow grant or
150
- overrides an explicit host deny; missing or mismatched identity fails closed
151
- for the attempted Pantheon delegation. The 3 goal tools remain unsupported and
152
- are reported as `goal-tools`.
153
-
154
- **Not complete either, and the V2 support claim is currently narrowed.** Two
155
- facts, both recorded in this repository rather than smoothed over:
156
-
157
- - **The host-backed V2 gate is red on the installable OpenCode CLI.** The V2 tool
158
- canary (`tests/canary/plugin-v2-tool-canary.test.mjs`) was written against
159
- `opencode 2.0.22`, which no npm channel publishes. Against the installable
160
- `@opencode-ai/cli` host, `/api/experimental/session/{id}/wait` has been
161
- promoted to `/api/session/{id}/wait` (the old path 404s) and `ctx.tool.list`
162
- is absent, so the canary fails 12/12 there. That is a canary/host-generation
163
- mismatch, not a measured plugin regression — with only the route renamed, 10/12
164
- pass on the same host, including the edit being applied and the mutant still
165
- caught. Tracked as [issue
166
- #216](https://github.com/ils15/pantheon-opencode/issues/216); the fail-closed
167
- CI change is [PR #213](https://github.com/ils15/pantheon-opencode/pull/213).
168
- - **The 2.x host claims in `src/plugin-v2.ts` are measured against `2.0.22`
169
- specifically**, not against the current installable CLI. Re-measurement
170
- against the current host is outstanding and is tracked in the same issue.
171
-
172
- Treat the 1.6 line's OpenCode 2 support as **real but partial**, and do not read
173
- the 1.6.x row as "OpenCode 2 is finished".
174
-
175
- ### Verified against which OpenCode versions
176
-
177
- | What | Verified against | How |
178
- |---|---|---|
179
- | V1 plugin + generation gate | The OpenCode 1.18.x line. This package pins `@opencode-ai/plugin` and `@opencode-ai/sdk` to `1.18.33`; the highest published `opencode-ai` host package (the one shipping the `opencode` binary) is `1.18.34` | Dependency pin (`package.json`); generation-gate unit tests over injected host banners; installer end-to-end tests asserting the emitted `opencode.json` shape |
180
- | V2 plugin tool surface | `opencode 2.0.22` (the host the canary was written against) | `tests/canary/plugin-v2-tool-canary.test.mjs`, driving `hashline_edit` through a real `opencode serve` |
181
- | V2 against the current installable CLI | **Not verified.** Canary fails 12/12; see issue #216 | — |
182
- | Exact 1.X host version the 1.6 line is exercised against end-to-end | **Unverified.** No V1 host leg exists: the sandbox runner is V2-only and `--run v1` is rejected | — |
183
-
184
- ## Delegation (native `task()`)
185
-
186
- Pantheon delegates exclusively through OpenCode's native `task()` child-session
187
- engine. The former custom `pantheon_delegate` tool and the V1 delegation engine
188
- (`delegation.ts`, `delegate-manager.ts` and supporting modules) were removed;
189
- there is no Pantheon-specific delegation tool surface to configure. See
190
- [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
191
- historical engine contract.
192
-
193
- This beta.8 candidate combines native per-agent MCP permissions for OpenCode V1
194
- and V2, V2 delegation-permission alignment, simpler memory/compression
195
- instructions, and a sandbox check that proves the installed package matches
196
- this checkout instead of silently accepting stale npm-cached code. The isolated
197
- sandbox launcher also pins the OpenCode background service to its dedicated
198
- loopback port, rather than colliding with another OpenCode installation. The Zeus
199
- prompt reuses one task-start memory-search result for context and routing;
200
- runtime call counts and latency have not been measured. A beta.7 V2 dispatch
201
- failed because the permission hook passed a bare string to `ctx.session.get`
202
- instead of the V2 input object `{ sessionID }`; beta.8 corrects the call and
203
- adds contract tests for the success and failure cases. The user subsequently
204
- reported a successful Hermes liveness delegation in the active session, but
205
- freshly restarting and testing the beta.8 sandbox remains the end-to-end gate.
206
- The original report also included a separate `GET /api/session/{id}/permission`
207
- 404; the session ID exists in the beta7-candidate database but not the default
208
- global database. Both OpenCode services were running, so the 404 in the global
209
- log may come from the other instance; this remains an end-to-end verification
210
- item.
211
-
212
- Delegated tasks get at most one retry after an initial timeout or failure. If
213
- that retry fails, the configured fallback or escalation chain applies.
214
-
215
- ## Cost tool backend
216
-
217
- `pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
218
- `opencode.db`. When `node:sqlite` is unavailable in the host runtime (for
219
- example under Bun), the tool falls back to spawning `node scripts/cost.mjs` as
220
- a read-only subprocess. The fallback resolves a real Node.js binary —
221
- `PANTHEON_NODE` first, then `node` on `PATH` — verifies it supports
222
- `node:sqlite` (Node.js >= 22.5), and runs the script with an argument array,
223
- never a shell. If neither source resolves, the tool returns `status:
224
- UNSUPPORTED`. Database failures return a contract status such as `UNAVAILABLE`
225
- or `CORRUPT_DATA` and include diagnostic detail, including captured stderr when
226
- available.
227
-
228
- | Variable | Default | Purpose |
229
- |----------|---------|---------|
230
- | `PANTHEON_NODE` | `node` from `PATH` | Path to a Node.js >= 22.5 binary used by the CLI fallback; an explicit path must exist and be executable, otherwise the tool fails fast instead of ignoring the override |
231
-
232
-
233
- ## Code-mode execution (explicit opt-in)
234
-
235
- Scripts run through the `pantheon-code-mode` MCP server (`execute_code_script`)
236
- only when they are explicitly approved. Approval is recorded in
237
- `.pantheon/code-mode/manifest.json` with the SHA-256 of each script:
238
-
239
- ```json
240
- {
241
- "version": 1,
242
- "scripts": {
243
- "example-sync.sh": "<sha256>"
244
- }
245
- }
246
- ```
247
-
248
- - **No manifest → nothing executes.** A missing manifest returns
249
- `INVALID_STATE`; scripts are never run implicitly.
250
- - **Not listed → `CONFLICT`.** The script must be approved first.
251
- - **Hash mismatch → `CORRUPT_DATA`.** The SHA-256 of the file on disk must
252
- match the manifest entry, so edits after approval are detected.
253
-
254
- Session persistence is provided by the persistence MCP server. The bundled
255
- code-mode payload contains execution helpers only and does not export or back
256
- up a database.
257
-
258
- Approve or re-approve a script with the `approve_code_script` MCP tool:
259
-
260
- ```
261
- approve_code_script("checkpoint-session.sh")
262
- ```
263
-
264
- The installer seeds the manifest with the SHA-256 of every bundled script, so
265
- shipped scripts stay approved across installs. Re-run `approve_code_script`
266
- after intentionally editing a script. Status codes follow the shared nine-code
267
- contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
268
- `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
269
- results carry a `status` field.
270
-
271
- Code-mode resolves project-first: `.opencode/.pantheon/code-mode` is preferred,
272
- then `.pantheon/code-mode`. `PANTHEON_PROJECT` overrides the working directory,
273
- and the installed MCP uses `cwd: "."` so OpenCode supplies the workspace. A
274
- global directory is used only when no usable project directory is available;
275
- once a project directory is selected, a missing or corrupt manifest fails
276
- closed instead of falling back. `doctor` validates the manifest and every
277
- script's SHA-256 without regenerating it.
278
-
279
- The local `.pantheon/code-mode/eval-*.py` helpers and any Promptfoo/evaluation
280
- assets are development-only inputs and are excluded from the npm tarball and
281
- from the runtime manifest. `src/mcp/eval_store.py` is different: it is a
282
- shipped runtime dependency of the MCP resources server, not an evaluation
283
- asset, so it remains packaged.
284
-
285
-
286
- ## What's new in 1.6.0-beta.1
287
-
288
- - First beta compatible with the OpenCode 2 plugin contract.
289
- - Removed the legacy vector-memory pipeline while preserving SQLite FTS5/BM25
290
- keyword search and the `code_*` codemap tools.
291
- - CI and release validation are fail-closed; `doctor` checks and the V2-only
292
- sandbox validator cover the OpenCode 2 installation path.
293
-
294
- ## OpenCode V1/V2 — Dual Version (1.6.0-beta.1)
295
-
296
- This is the first beta compatible with OpenCode 2. Pantheon has two **exclusive** OpenCode
297
- plugin contracts. Ordinary OpenCode
298
- configuration may be shared, but the Pantheon plugin registration is selected
299
- per installation; V1 and V2 Pantheon plugins must never be registered together.
300
-
301
- | | V1 | V2 |
302
- |---|---|---|
303
- | OpenCode config key | singular `plugin` | plural `plugins` |
304
- | Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
305
- | Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 5 event subscriptions, session hooks (`prompt`, `context`), a read-only-enforcing tool `execute.before` hook, plus configuration transforms |
306
- | V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
307
-
308
- The V2 plugin provides 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
309
- `pantheon_model`), 5 event subscriptions (`session.created`, `session.idle`,
310
- `session.deleted`, `session.error`, `session.compacted`), session hooks
311
- (`prompt`, `context`),
312
- and a tool `execute.before` hook that enforces read-only sessions. The 3 goal
313
- tools are **not**
314
- registered on V2: the goal loop needs a `GoalStore`, a `GoalLoopClient` and a
315
- `BackgroundJobBoard`, none of which the V2 `PluginContext` exposes, so the gap
316
- is reported as the `goal-tools` unsupported-feature marker. Use the V1
317
- contract if you need the goal loop.
318
-
319
- The V2 `execute.before` hook is the read-only enforcement point for that
320
- surface: the host includes the active agent on the event, a read-only agent
321
- (`apollo`, `gaia`) registers its session, and the shared
322
- `createEnforcementGuard` throws to deny `edit`, `write`, `bash`, `task`,
323
- `hashline_edit` and `pantheon_model`. It does **not** rely on the V1
324
- `tool.execute.before` hook, which lives in `src/plugin.ts` and is not loaded
325
- when only `plugin-v2` is configured. The `permission.evaluate` hook enforces
326
- the V2 caller/target matrix for Pantheon-managed targets across every entry in
327
- the host's `resources` array. Native-only resources pass through unchanged to
328
- OpenCode's permission policy; mixed native/Pantheon requests and multi-target
329
- requests are denied unless every Pantheon target is explicitly allowed for the
330
- authoritative caller. Explicit host denies remain final, and missing or
331
- unknown resource data fails closed. If a denied evaluation has no mutable host
332
- output argument, the hook throws to fail closed rather than silently omitting
333
- the denial. V2 `execute.after` runs the completed-result chain:
334
- `task-result-guard` → `context-sandbox` → `read-enhancer`.
335
-
336
- Every V2 tool declares an `output` schema. OpenCode 2.0.x requires the
337
- declaration and the resolved result to agree in both directions, so an
338
- undeclared tool — or one that returns `output` without declaring it — fails on
339
- every call. Unsupported V2 features are `legacy-hooks` (the V1-specific hook
340
- surface), `catalog-transform`, `integration-transform`, `skill-transform` and
341
- `goal-tools`.
342
-
343
- The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
344
- (V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
345
- (optional interop), so a host can load either contract explicitly.
346
-
347
- The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
348
- V1 infrastructure singletons (BackgroundJobBoard, GoalStore,
349
- TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
350
- optional — V2 works standalone with graceful degradation.
351
-
352
- Select the contract explicitly when installing:
353
-
354
- ```bash
355
- npx pantheon-opencode init --opencode-version v1
356
- npx pantheon-opencode init --opencode-version v2
357
- npx pantheon-opencode init --opencode-version auto
358
- ```
359
-
360
- `auto` is the default. `--version v1|v2|auto` is accepted as the older
361
- selector spelling when used after `init`. `auto` resolves the generation from
362
- the host in this order: an explicit `OPENCODE_VERSION=v1|v2` wins; otherwise an
363
- `OPENCODE_BIN` path ending in `opencode2` selects V2; otherwise the host
364
- binary is asked for its `--version` and a major of 2 or more selects V2. Every
365
- other case — an unreadable probe, an unparseable banner, or a banner whose
366
- version-like tokens contradict each other with no tool name to break the tie —
367
- warns once and falls back to V1, because a plural `plugins` directory entry on
368
- an unknown 1.x host loses the plugin entirely.
369
-
370
- The probe prefers the token that follows the tool name, so a runtime token
371
- ahead of it (`node v22.1.0 (opencode 1.18.33)`) or a trailing build date
372
- (`opencode v1.18.33 built 2026.10.04`) cannot flip the generation. The
373
- installer removes Pantheon references from both config shapes before writing
374
- only the selected Pantheon registration. Third-party entries are not converted
375
- or claimed by this rule.
376
-
377
- The `pantheon_cost` report resolves its database by PATH, in this order: an
378
- explicit `dbPath` supplied by the tool caller, then
379
- `PANTHEON_COST_DB=/absolute/path/to/opencode.db`, then `OPENCODE_DB`, then the
380
- XDG default `opencode.db`. There is no per-version filename in that chain:
381
- `opencode-v2.db` is not a host 2.x database — it is the name a sandbox gives
382
- its own state database through `OPENCODE_DB`.
383
-
384
- The v1/v2 distinction is the DETECTED SCHEMA, not the file name. The report
385
- looks for the `message` and `session_message` tables and reads whichever the
386
- open database actually holds, because a migrated database carries both
387
- families at once. `PANTHEON_OPENCODE_VERSION=v1|v2` selects no file: it only
388
- narrows an already-detected set to one table family, and fails fast when the
389
- value is neither `v1` nor `v2` or when the requested family is not there. Left
390
- unset, every detected family is read. A database carrying neither table comes
391
- back as an actionable error (`CORRUPT_DATA`), and a ledger that exists but
392
- yields no readable tokens as `UNSUPPORTED` — never as a successful empty
393
- report.
394
-
395
- The installer still writes the compatibility settings required by the selected
396
- OpenCode host, such as `experimental.subagent_depth`; this does not convert a
397
- V1 plugin into V2 or provide V2 with V1 hooks.
398
-
399
- Pantheon does not set a step ceiling on agents. On OpenCode 2 the `steps`
400
- field is optional and has no default: absent means the host applies no native
401
- limit. A config written before this change still carries the old value, and the
402
- V2 install path strips it from every agent Pantheon manages — an agent you
403
- define yourself is never touched, and the retiring V1 singular `agent` block
404
- is left alone. Run the installer once to clear a stale value from an existing
405
- config:
82
+ routine child summaries stay in the handoff. See [Memory](docs/MEMORY.md).
406
83
 
407
- ```bash
408
- npx pantheon-opencode init --opencode-version=v2
409
- ```
410
-
411
- Context control is not a Pantheon setting. Whatever budget an agent runs
412
- against comes from the compaction settings of the OpenCode host you are
413
- running, and Pantheon does not define them.
84
+ ## Compatibility
414
85
 
415
- When a V1 `agent` block and a V2 `agents` block are both present — which is
416
- what an installed `opencode.json` carries — the V1→V2 conversion merges them
417
- instead of letting one replace the other. The V2 block is the base, the
418
- framework-managed fields from the V1 block overwrite, and your own fields are
419
- preserved, matching the precedence the installer already applies elsewhere.
420
- Key order does not matter.
86
+ OpenCode **1.19.x** (V1 plugin) and **OpenCode 2.x** (V2 plugin) are supported.
87
+ **OpenCode 2.0.22 is known broken.** From 1.7 onward the line drops the V1
88
+ contract and targets OpenCode 2 only.
421
89
 
422
- ## Updating between releases (beta.5+)
90
+ The support policy, the known-broken exception, and the verified-version
91
+ evidence have exactly one home: [Compatibility](docs/COMPATIBILITY.md).
423
92
 
424
- > **Read [Compatibility and support policy](#compatibility-and-support-policy)
425
- > before upgrading across a line boundary.** 1.6.x is the last line that
426
- > supports an OpenCode 1.X host; 1.7+ is breaking-change territory targeting
427
- > OpenCode 2. Within the 1.6 line, `update` is the supported path.
93
+ ## Delegation
428
94
 
429
- One command keeps an existing installation current:
95
+ Pantheon delegates through the host's native child-session engine: `subagent`
96
+ in the user-reported root runtime, referred to as `task()` in host/API
97
+ documentation. Tool availability, background support, and completion
98
+ observability are runtime-dependent; when completion is not observable, use
99
+ synchronous dispatch or wait for a host notification.
430
100
 
431
- ```bash
432
- # Without a global install, ALWAYS pin the dist-tag — plain `npx
433
- # pantheon-opencode` resolves `latest`, which is the stable release (1.4.3):
434
- npx pantheon-opencode@beta update # npm beta channel + config refresh
435
- npx pantheon-opencode@beta update --stable # stable channel instead
436
-
437
- # With a global install, use the global bin (defaults to the beta channel):
438
- pantheon-opencode update
439
- ```
101
+ Every root dispatch carries a concise handoff brief — objective, bounded scope,
102
+ relevant inputs, constraints, expected return format, and verification. Work is
103
+ routed qualitatively — uncertainty, domain expertise, dependencies, risk, and
104
+ verification — not by fixed file or line thresholds. Return
105
+ contracts are role-specific: implementation uses `## subtask_summary`,
106
+ investigation returns structured findings, Athena returns the complete plan,
107
+ and council responses use `## specialist_response`. Delegated work gets at most
108
+ one retry after a transient failure, and Pantheon never claims deterministic
109
+ fan-in or job recovery without an exposed mechanism.
440
110
 
441
- `update` compares your installed version with the npm dist-tag, runs
442
- `npm install -g pantheon-opencode@<channel>`, then re-runs `init --yes
443
- --headless` so config merges, the venv and MCP entries match the new package.
444
- Two freshness guarantees back it up:
445
-
446
- - **Postinstall artifact sync** — after any `npm install`, copy-only artifacts
447
- (agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload) are
448
- refreshed into the existing config dir automatically; you never have to
449
- re-run `init` just for file copies.
450
- - **Drift detection** — the installer stamps the installed version in
451
- `.pantheon/install-state.json` and `doctor` warns when the package is newer
452
- than the last sync, pointing at `update`. `doctor` also detects **plugin
453
- version drift** (issue #158): when `opencode.json` registers a plugin path
454
- inside a `node_modules/pantheon-opencode` copy whose `package.json` version
455
- differs from the running package, it warns that the registered tool surface
456
- is stale. Re-running `init`/`update` realigns the registration onto the
457
- current package.
458
-
459
- `init` also gained `--components agents,skills,...` (narrow install),
460
- `--clean` (alias of `--force`), `--opencode-version auto`, atomic config
461
- writes with an `opencode.json.bak` backup, preflight checks for python3/npm
462
- before any file is written, and a non-fatal Python runtime: if the venv fails,
463
- the install completes but MCP entries are omitted (with a warning) instead of
464
- pointing at a broken interpreter. Installer messages auto-detect pt-BR via
465
- `LANG`/`LC_ALL`.
466
-
467
- ## Migrating to 1.5.x (from 1.4.x)
468
-
469
- 1.5.0 removed the custom `pantheon_delegate` tool (and the V1 delegation
470
- engine) in favor of OpenCode's native `task()`; see
471
- [Delegation (native `task()`)](#delegation-native-task). Two things change on
472
- an existing install:
473
-
474
- 1. **The tool disappears from the plugin surface.** `pantheon_delegate` is no
475
- longer registered by `src/plugin.ts` or `src/plugin-v2.ts`. Agents now
476
- delegate through `task()` only — no configuration is needed.
477
- 2. **A lockfile-pinned copy can keep the old tool alive.** `npm install` is
478
- lockfile-authoritative: a `package-lock.json` pinned to `1.4.1` (which
479
- satisfies `^1.4.1`) is never re-resolved, so a project's
480
- `node_modules/pantheon-opencode` can stay on 1.4.x while the published
481
- package moved on. The plugin path your `opencode.json` registers keeps
482
- pointing at that stale copy, and you keep running the obsolete tool surface
483
- — including `pantheon_delegate` — with no warning.
484
-
485
- The fix is a realignment + a detector:
111
+ The delegation model, caller/target matrix, and approval gates are documented
112
+ in [Architecture](docs/ARCHITECTURE.md) and
113
+ [Permissions, Gates & Delegation](docs/PERMISSIONS-QUALITY-DELEGATION.md).
486
114
 
487
- ```bash
488
- # Realign the registered plugin path onto the current package (rewrites any
489
- # node_modules/pantheon-opencode reference in opencode.json):
490
- npx pantheon-opencode@latest init --yes --headless
491
- # or, with a global install:
492
- pantheon-opencode update
493
-
494
- # Then verify no drift remains:
495
- npx pantheon-opencode@latest doctor
496
- ```
497
-
498
- `doctor` now reports a **Plugin Version Drift** warning (section H3) when the
499
- registered plugin points into an installed copy whose version differs from the
500
- running package, naming both versions and the removal (`pantheon_delegate` in
501
- 1.5.0). A healthy install reports no warning.
502
-
503
- ## Releases
504
-
505
- Publication is authorized **only** by an explicit `workflow_dispatch` of the
506
- `Release` workflow (`release_channel` input selects beta or stable). PR labels,
507
- pushes, merges, and tags never publish anything, and every validation gate is
508
- fail-closed: only an explicit PASS authorizes release evidence. See
509
- [docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
510
-
511
- Release validation keeps each manifest with its lockfile: the root
512
- `package.json` + `package-lock.json` and the TUI
513
- `src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Both use
514
- `npm ci --ignore-scripts`; an `npm ci` failure blocks the run and there is no
515
- `npm install` fallback. A release carries one `.tgz` tarball, computes the
516
- SHA-256 of that same artifact, and binds the tarball and GitHub release to the
517
- full `TARGET_SHA`; a second pack is not interchangeable.
518
-
519
- CI also rebuilds the TUI with `npm run build --prefix src/plugins/tui` and
520
- checks every packaged `dist` artifact byte-for-byte against its checked-in
521
- version, including final newlines.
522
-
523
- ## Sandbox validation (V2)
524
-
525
- `scripts/test-opencode-v2-sandbox.sh` validates the globally installed
526
- package as a real user inside an isolated sandbox (own `HOME`, npm prefix and
527
- venv) — never the dev environment. It checks the OpenCode V2 leg: the binary,
528
- MCP connectivity, `doctor`, and — with `--prompts` — a prompt battery covering
529
- the `pantheon://agents` resource, memory store/recall, filesystem writes and
530
- agent delegation. The gate is fail-closed: every required check must return an
531
- explicit PASS; timeouts, auth/network/provider failures and missing
532
- prerequisites block the run.
533
-
534
- The runner defaults to the current stable `@opencode/cli` package and its
535
- `opencode2` alias; set `OPENCODE_V2_SPEC` only when a test needs a different
536
- host build. This keeps Pantheon beta testing separate from the OpenCode CLI
537
- release channel.
538
-
539
- "V2" here refers only to the hook canary observed against an OpenCode v2.0.18
540
- host, where at least one tested hook callback fired; it does not establish
541
- compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
542
- contract. This branch still pins transitional `@opencode-ai/plugin@1.18.30`.
543
- On hosts where both `opencode` and `opencode2` exist, the latter is typically
544
- a shim that execs the same binary, so an older side-by-side comparison proved
545
- nothing about the binary itself. The project is V2-exclusive, so there is a
546
- single leg.
547
-
548
- ```bash
549
- scripts/test-opencode-v2-sandbox.sh --prepare # tarball + install + init in the sandbox
550
- ~/pantheon-sandbox/start-pantheon.sh # interactive TUI in that isolated beta sandbox
551
- scripts/test-opencode-v2-sandbox.sh --run v2 # base validation only
552
- scripts/test-opencode-v2-sandbox.sh --prompts # base validation + prompt battery
553
- scripts/test-opencode-v2-sandbox.sh --rehydrate # offline context rehydration/session-summary probe
554
- scripts/test-opencode-v2-sandbox.sh --hooks # V2 hook callback canary
555
- scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # run both canaries
556
- scripts/test-opencode-v2-sandbox.sh --reset # wipe the sandbox root
557
- ```
558
-
559
- Modes are combinable (e.g. `--prepare --run v2 --prompts`). `--rehydrate` runs
560
- offline `context_rehydrate` and `context_session_summary` probes. `--hooks` runs
561
- a V2 hook canary against the sandbox binary to check that hook callbacks fire;
562
- it does not test transform callback effects or prove Pantheon's
563
- `execute.before` security enforcement. With the probe-only `--rehydrate --hooks`
564
- pair (without `--run`, `--prompts`, or `--cost`), the hooks canary still runs if
565
- rehydration fails, and the command returns a failing status afterward. These
566
- are test/sandbox canaries, not proof of Pantheon security enforcement. Binaries
567
- are resolved strictly inside the sandbox npm prefix — a non-prepared sandbox
568
- fails fast instead of silently testing the host installation. The sandbox is
569
- always built from the checkout this script lives in; it never infers a
570
- repository from a sibling directory.
571
-
572
- This validates the prepared isolated sandbox only. A PASS is not proof of
573
- support for every real host or for host configurations that were not exercised.
574
-
575
- ## Plugin V2 TypeScript coverage
576
-
577
- `npm run coverage:plugin-v2` runs the `tests/pantheon/*.test.ts` suite with
578
- Node's source-mapped native coverage and enforces an 80% line-coverage minimum
579
- for `src/plugin-v2.ts` only. It requires Node `v24.15.0`; branch and function
580
- coverage are reported but are not gates. This is not a repository-wide coverage
581
- claim.
582
-
583
- Env overrides:
584
-
585
- | Variable | Default | Purpose |
586
- |----------|---------|---------|
587
- | `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
588
- | `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configures the V1 plugin only; the V2-only sandbox runner does not consume or support it |
589
- | `OPENCODE_V2_SPEC` | `@opencode/cli@latest` | npm spec providing the `opencode2` binary |
590
- | `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
591
- | `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |
592
-
593
- Exit codes: `0` no real failures · `1` real failure (see `prompts-report.md`
594
- in the sandbox root) · `2` usage error · `3` sandbox not prepared.
595
-
596
- ### Intentional memory MCP divergence
597
-
598
- `scripts/memory_mcp.py` and `src/mcp/memory_mcp.py` are
599
- intentionally different. The standalone `scripts/` copy keeps the lightweight
600
- `memory_*` contract; the installed `src/mcp/` copy additionally exposes the
601
- optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
602
- The other shared MCP copies remain identical. Do not overwrite one memory copy
603
- with the other.
604
-
605
- ### Task-result guard
606
-
607
- A `task-result-guard` intercepts calls to the native `task()` tool where the
608
- child session returns an empty or missing result. Instead of surfacing a silent
609
- `completed` with no payload (which confuses the orchestrator), the guard now
610
- raises an explicit error. This catches the common free-tier failure mode where a
611
- child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
612
- and returns nothing. Prefer `background=true` dispatches with an explicit
613
- `task_status(wait=true)` fan-in so large payloads are collected deterministically.
614
-
615
-
616
- ## Configuration (environment variables)
617
-
618
- The `pantheon-memory` MCP server needs no configuration: search is SQLite FTS5
619
- (BM25) only, all stdlib, with no embedding model, no vector index, and no
620
- `sqlite-vec`/`fastembed` dependency. Other environment variables are documented
621
- in the sections above.
115
+ ## Documentation
622
116
 
117
+ | Start here | Go deeper |
118
+ |---|---|
119
+ | [Installation](docs/INSTALLATION.md) | [Architecture](docs/ARCHITECTURE.md) |
120
+ | [Quick Start](docs/QUICKSTART.md) | [MCP](docs/MCP.md) · [MCP tools](docs/mcp-tools.md) |
121
+ | [Upgrading](docs/UPGRADING.md) | [Memory](docs/MEMORY.md) |
122
+ | [Compatibility](docs/COMPATIBILITY.md) | [OpenCode V2](docs/opencode-v2.md) |
123
+ | [Agents & Skills](docs/agents/README.md) | [Platforms](docs/PLATFORMS.md) |
124
+ | [Release Process](docs/RELEASING.md) | [Branch Protection](docs/BRANCH-PROTECTION.md) |
125
+ | [Model Routing](docs/reference/model-routing.md) | [Env Vars](docs/reference/env-vars.md) · [Code Mode](docs/reference/code-mode.md) |
126
+ | [Contributing](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) |
623
127
 
624
- ## Documentation
128
+ ## Status
625
129
 
626
- ### Local evaluations
130
+ The manifests in this checkout express the version being prepared, not a
131
+ confirmed publication. Check the npm `beta` dist-tag for what is actually
132
+ published. See [Compatibility](docs/COMPATIBILITY.md) for the supported hosts
133
+ and [releases](https://github.com/ils15/pantheon-opencode/releases) for the
134
+ latest published changes.
627
135
 
628
- Promptfoo/evaluation experiments are local-only: place them under
629
- `evals/promptfoo/`, which is gitignored and excluded from npm packaging,
630
- package evidence, CI tests, coverage, and release gates. Publish reviewed
631
- findings as documentation, not the local harness, datasets, outputs, or
632
- credentials.
136
+ ## What's new
633
137
 
634
- - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)
635
- - [Architecture](docs/ARCHITECTURE.md) · [MCP tools](docs/mcp-tools.md)
636
- - [Platforms](docs/PLATFORMS.md) · [Upgrading](docs/UPGRADING.md)
637
- - [Agent reference](docs/agents/README.md) · [Skills reference](src/skills/README.md)
638
- - [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
639
- - [Changelog](CHANGELOG.md)
138
+ See the [GitHub release](https://github.com/ils15/pantheon-opencode/releases)
139
+ and [CHANGELOG.md](CHANGELOG.md) for the changes in 1.6.0.
640
140
 
641
141
  ## Contribute
642
142
 
643
143
  Ideas, bug reports, documentation improvements, and code contributions are
644
- welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
645
- or pull request.
646
-
647
- ### Reproducible benchmark evidence
648
-
649
- The beta2 benchmark records reported token usage separately from its
650
- character-based fallback estimate; source bytes and logical line counts remain
651
- provenance data and are never converted into tokens. Cross-report comparisons
652
- require matching model/config provenance and reported OpenCode usage. Offline
653
- fixture responses are mocked: their reported values are labeled separately,
654
- excluded from `actual` usage, and blocked from comparative metrics and GEPA.
655
- Fixture quality outcomes test the offline contract; they are not evaluation
656
- evidence.
657
- Reproduce the
658
- checked-in AGENTS.md history manifest with
659
- `python3 -m benchmarks.beta2.provenance --output benchmarks/beta2/fixtures/agent-baseline-provenance.json`.
660
- For OpenCode benchmark runs, provide `--model` and `--config-sha256` so reports
661
- can be compared safely.
662
-
663
- ### Project-level `opencode.json`
664
-
665
- The published package carries no `opencode.json` template. `init` still writes
666
- your project's `opencode.json` itself, and the few product defaults an install
667
- seeds — `default_agent: zeus` and `permission.skill` — come from the installer
668
- code, not from a packaged file. Contributors who keep a project-level
669
- `opencode.json` for their own OpenCode sessions should leave it untracked —
670
- `.git/info/exclude` per clone, or a shared `.gitignore` decision — rather than
671
- versioning it.
144
+ welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull
145
+ request. That file also defines the documentation rule: one home per fact, with
146
+ a short list of facts that must not be duplicated.
672
147
 
673
148
  ## Citation and DOI
674
149
 
675
150
  Pantheon is released under the [MIT License](LICENSE). Cite the
676
151
  [Zenodo concept DOI](https://doi.org/10.5281/zenodo.22650136), which always
677
152
  resolves to the latest archived release; each release also has its own version
678
- DOI. Citation metadata is also available in [CITATION.cff](CITATION.cff).
153
+ DOI. Citation metadata is in [CITATION.cff](CITATION.cff).
679
154
 
680
155
  Canonical repository: <https://github.com/ils15/pantheon-opencode>
681
156