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.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,635 +46,155 @@ 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
82
+ routine child summaries stay in the handoff. See [Memory](docs/MEMORY.md).
94
83
 
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:
84
+ ## Compatibility
238
85
 
239
- ```json
240
- {
241
- "version": 1,
242
- "scripts": {
243
- "example-sync.sh": "<sha256>"
244
- }
245
- }
246
- ```
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.
247
89
 
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.
90
+ The support policy, the known-broken exception, and the verified-version
91
+ evidence have exactly one home: [Compatibility](docs/COMPATIBILITY.md).
253
92
 
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.
93
+ ### V2 plugin options (opt-in features)
257
94
 
258
- Approve or re-approve a script with the `approve_code_script` MCP tool:
95
+ The OpenCode V2 host hands a plugin its `options` only from the object form of
96
+ the entry, and two features — per-request context pruning and ambient memory
97
+ injection — read exactly that bag. `init` therefore writes the object form, so
98
+ enabling them is one edit away and nothing is on by default:
259
99
 
100
+ ```json
101
+ {
102
+ "plugins": [
103
+ {
104
+ "package": "/path/to/pantheon-opencode/src/plugin-v2",
105
+ "options": {
106
+ "context_pruner": { "enabled": true },
107
+ "memory_injection": { "enabled": true }
108
+ }
109
+ }
110
+ ]
111
+ }
260
112
  ```
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
113
 
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.
114
+ Keep the `package` value `init` wrote and add keys inside `options`; any key you
115
+ add by hand survives a re-run. Both features are off unless `enabled` is
116
+ literally `true`.
278
117
 
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 |
118
+ | Option | Default | Effect |
302
119
  |---|---|---|
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:
406
-
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.
414
-
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.
120
+ | `options.context_pruner.enabled` | `false` | Prune old turns from the request payload and at compaction. Off by default because per-request pruning invalidates the provider prompt cache. |
121
+ | `options.memory_injection.enabled` | `false` | Ride the most relevant memory entries along on the session's first request, bounded by `maxEntries`/`maxChars`. |
122
+
123
+ `context_pruner` also accepts `keepTurns`, `purgeAfterTurns`, `protectedTools`,
124
+ `minSavingsTokens` and `charsPerToken`; `memory_injection` accepts `maxEntries`,
125
+ `maxChars` and `namespace`. Unknown keys are ignored with a one-time warning in
126
+ the hook log, so a typo cannot silently change behaviour. Run
127
+ `npx pantheon-opencode doctor` to see whether the installed entry can receive
128
+ options at all. Full rules: [OpenCode V2](docs/opencode-v2.md) and
129
+ [Memory](docs/MEMORY.md).
130
+
131
+ ## Delegation
132
+
133
+ Pantheon delegates through the host's native child-session engine: `subagent`
134
+ in the user-reported root runtime, referred to as `task()` in host/API
135
+ documentation. Tool availability, background support, and completion
136
+ observability are runtime-dependent; when completion is not observable, use
137
+ synchronous dispatch or wait for a host notification.
138
+
139
+ Every root dispatch carries a concise handoff brief — objective, bounded scope,
140
+ relevant inputs, constraints, expected return format, and verification. Work is
141
+ routed qualitatively — uncertainty, domain expertise, dependencies, risk, and
142
+ verification — not by fixed file or line thresholds. Return
143
+ contracts are role-specific: implementation uses `## subtask_summary`,
144
+ investigation returns structured findings, Athena returns the complete plan,
145
+ and council responses use `## specialist_response`. Delegated work gets at most
146
+ one retry after a transient failure, and Pantheon never claims deterministic
147
+ fan-in or job recovery without an exposed mechanism.
148
+
149
+ The delegation model, caller/target matrix, and approval gates are documented
150
+ in [Architecture](docs/ARCHITECTURE.md) and
151
+ [Permissions, Gates & Delegation](docs/PERMISSIONS-QUALITY-DELEGATION.md).
421
152
 
422
- ## Updating between releases (beta.5+)
423
-
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.
428
-
429
- One command keeps an existing installation current:
430
-
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
- ```
440
-
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:
486
-
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. The build includes separate V1 and native
522
- OpenCode V2 TUI entrypoints; `init` selects the entrypoint and sidebar slot API
523
- for the host generation in use.
524
-
525
- ## Sandbox validation (V2)
526
-
527
- `scripts/test-opencode-v2-sandbox.sh` validates the globally installed
528
- package as a real user inside an isolated sandbox (own `HOME`, npm prefix and
529
- venv) — never the dev environment. It checks the OpenCode V2 leg: the binary,
530
- MCP connectivity, `doctor`, and — with `--prompts` — a prompt battery covering
531
- the `pantheon://agents` resource, memory store/recall, filesystem writes and
532
- agent delegation. The gate is fail-closed: every required check must return an
533
- explicit PASS; timeouts, auth/network/provider failures and missing
534
- prerequisites block the run.
535
-
536
- The runner defaults to the current stable `@opencode/cli` package and its
537
- `opencode2` alias; set `OPENCODE_V2_SPEC` only when a test needs a different
538
- host build. This keeps Pantheon beta testing separate from the OpenCode CLI
539
- release channel.
540
-
541
- "V2" here refers only to the hook canary observed against an OpenCode v2.0.18
542
- host, where at least one tested hook callback fired; it does not establish
543
- compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
544
- contract. This branch still pins transitional `@opencode-ai/plugin@1.18.30`.
545
- On hosts where both `opencode` and `opencode2` exist, the latter is typically
546
- a shim that execs the same binary, so an older side-by-side comparison proved
547
- nothing about the binary itself. The project is V2-exclusive, so there is a
548
- single leg.
549
-
550
- ```bash
551
- scripts/test-opencode-v2-sandbox.sh --prepare # tarball + install + init in the sandbox
552
- ~/pantheon-sandbox/start-pantheon.sh # interactive TUI in that isolated beta sandbox
553
- scripts/test-opencode-v2-sandbox.sh --run v2 # base validation only
554
- scripts/test-opencode-v2-sandbox.sh --prompts # base validation + prompt battery
555
- scripts/test-opencode-v2-sandbox.sh --rehydrate # offline context rehydration/session-summary probe
556
- scripts/test-opencode-v2-sandbox.sh --hooks # V2 hook callback canary
557
- scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # run both canaries
558
- scripts/test-opencode-v2-sandbox.sh --reset # wipe the sandbox root
559
- ```
560
-
561
- Modes are combinable (e.g. `--prepare --run v2 --prompts`). `--rehydrate` runs
562
- offline `context_rehydrate` and `context_session_summary` probes. `--hooks` runs
563
- a V2 hook canary against the sandbox binary to check that hook callbacks fire;
564
- it does not test transform callback effects or prove Pantheon's
565
- `execute.before` security enforcement. With the probe-only `--rehydrate --hooks`
566
- pair (without `--run`, `--prompts`, or `--cost`), the hooks canary still runs if
567
- rehydration fails, and the command returns a failing status afterward. These
568
- are test/sandbox canaries, not proof of Pantheon security enforcement. Binaries
569
- are resolved strictly inside the sandbox npm prefix — a non-prepared sandbox
570
- fails fast instead of silently testing the host installation. The sandbox is
571
- always built from the checkout this script lives in; it never infers a
572
- repository from a sibling directory.
573
-
574
- This validates the prepared isolated sandbox only. A PASS is not proof of
575
- support for every real host or for host configurations that were not exercised.
576
-
577
- ## Plugin V2 TypeScript coverage
578
-
579
- `npm run coverage:plugin-v2` runs the `tests/pantheon/*.test.ts` suite with
580
- Node's source-mapped native coverage and enforces an 80% line-coverage minimum
581
- for `src/plugin-v2.ts` only. It requires Node `v24.15.0`; branch and function
582
- coverage are reported but are not gates. This is not a repository-wide coverage
583
- claim.
584
-
585
- Env overrides:
586
-
587
- | Variable | Default | Purpose |
588
- |----------|---------|---------|
589
- | `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
590
- | `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configures the V1 plugin only; the V2-only sandbox runner does not consume or support it |
591
- | `OPENCODE_V2_SPEC` | `@opencode/cli@latest` | npm spec providing the `opencode2` binary |
592
- | `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
593
- | `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |
594
-
595
- Exit codes: `0` no real failures · `1` real failure (see `prompts-report.md`
596
- in the sandbox root) · `2` usage error · `3` sandbox not prepared.
597
-
598
- ### Intentional memory MCP divergence
599
-
600
- `scripts/memory_mcp.py` and `src/mcp/memory_mcp.py` are
601
- intentionally different. The standalone `scripts/` copy keeps the lightweight
602
- `memory_*` contract; the installed `src/mcp/` copy additionally exposes the
603
- optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
604
- The other shared MCP copies remain identical. Do not overwrite one memory copy
605
- with the other.
606
-
607
- ### Task-result guard
608
-
609
- A `task-result-guard` intercepts calls to the native `task()` tool where the
610
- child session returns an empty or missing result. Instead of surfacing a silent
611
- `completed` with no payload (which confuses the orchestrator), the guard now
612
- raises an explicit error. This catches the common free-tier failure mode where a
613
- child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
614
- and returns nothing. Prefer `background=true` dispatches with an explicit
615
- `task_status(wait=true)` fan-in so large payloads are collected deterministically.
616
-
617
-
618
- ## Configuration (environment variables)
619
-
620
- The `pantheon-memory` MCP server needs no configuration: search is SQLite FTS5
621
- (BM25) only, all stdlib, with no embedding model, no vector index, and no
622
- `sqlite-vec`/`fastembed` dependency. Other environment variables are documented
623
- in the sections above.
153
+ ## Documentation
624
154
 
155
+ | Start here | Go deeper |
156
+ |---|---|
157
+ | [Installation](docs/INSTALLATION.md) | [Architecture](docs/ARCHITECTURE.md) |
158
+ | [Quick Start](docs/QUICKSTART.md) | [MCP](docs/MCP.md) · [MCP tools](docs/mcp-tools.md) |
159
+ | [Upgrading](docs/UPGRADING.md) | [Memory](docs/MEMORY.md) |
160
+ | [Compatibility](docs/COMPATIBILITY.md) | [OpenCode V2](docs/opencode-v2.md) |
161
+ | [Agents & Skills](docs/agents/README.md) | [Platforms](docs/PLATFORMS.md) |
162
+ | [Release Process](docs/RELEASING.md) | [Branch Protection](docs/BRANCH-PROTECTION.md) |
163
+ | [Model Routing](docs/reference/model-routing.md) | [Env Vars](docs/reference/env-vars.md) · [Code Mode](docs/reference/code-mode.md) |
164
+ | [Contributing](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) |
165
+
166
+ The release install gate's tool canary loads the installed tarball's V2 plugin
167
+ entry under OpenCode 2.0.30 and verifies `hashline_edit` registration, Code Mode
168
+ visibility, and a bounded edit in an isolated project. It does not prove npm
169
+ publication or compatibility with untested host versions; details are in the
170
+ [release process](docs/RELEASING.md).
625
171
 
626
- ## Documentation
172
+ ## Status
627
173
 
628
- ### Local evaluations
174
+ The manifests in this checkout express the version being prepared, not a
175
+ confirmed publication. Check the npm `beta` dist-tag for what is actually
176
+ published. See [Compatibility](docs/COMPATIBILITY.md) for the supported hosts
177
+ and [releases](https://github.com/ils15/pantheon-opencode/releases) for the
178
+ latest published changes.
629
179
 
630
- Promptfoo/evaluation experiments are local-only: place them under
631
- `evals/promptfoo/`, which is gitignored and excluded from npm packaging,
632
- package evidence, CI tests, coverage, and release gates. Publish reviewed
633
- findings as documentation, not the local harness, datasets, outputs, or
634
- credentials.
180
+ ## What's new
635
181
 
636
- - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)
637
- - [Architecture](docs/ARCHITECTURE.md) · [MCP tools](docs/mcp-tools.md)
638
- - [Platforms](docs/PLATFORMS.md) · [Upgrading](docs/UPGRADING.md)
639
- - [Agent reference](docs/agents/README.md) · [Skills reference](src/skills/README.md)
640
- - [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
641
- - [Changelog](CHANGELOG.md)
182
+ See the [GitHub release](https://github.com/ils15/pantheon-opencode/releases)
183
+ and [CHANGELOG.md](CHANGELOG.md) for the changes in 1.6.1.
642
184
 
643
185
  ## Contribute
644
186
 
645
187
  Ideas, bug reports, documentation improvements, and code contributions are
646
- welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
647
- or pull request.
648
-
649
- ### Reproducible benchmark evidence
650
-
651
- The beta2 benchmark records reported token usage separately from its
652
- character-based fallback estimate; source bytes and logical line counts remain
653
- provenance data and are never converted into tokens. Cross-report comparisons
654
- require matching model/config provenance and reported OpenCode usage. Offline
655
- fixture responses are mocked: their reported values are labeled separately,
656
- excluded from `actual` usage, and blocked from comparative metrics and GEPA.
657
- Fixture quality outcomes test the offline contract; they are not evaluation
658
- evidence.
659
- Reproduce the
660
- checked-in AGENTS.md history manifest with
661
- `python3 -m benchmarks.beta2.provenance --output benchmarks/beta2/fixtures/agent-baseline-provenance.json`.
662
- For OpenCode benchmark runs, provide `--model` and `--config-sha256` so reports
663
- can be compared safely.
664
-
665
- ### Project-level `opencode.json`
666
-
667
- The published package carries no `opencode.json` template. `init` still writes
668
- your project's `opencode.json` itself, and the few product defaults an install
669
- seeds — `default_agent: zeus` and `permission.skill` — come from the installer
670
- code, not from a packaged file. Contributors who keep a project-level
671
- `opencode.json` for their own OpenCode sessions should leave it untracked —
672
- `.git/info/exclude` per clone, or a shared `.gitignore` decision — rather than
673
- versioning it.
188
+ welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull
189
+ request. That file also defines the documentation rule: one home per fact, with
190
+ a short list of facts that must not be duplicated.
674
191
 
675
192
  ## Citation and DOI
676
193
 
677
194
  Pantheon is released under the [MIT License](LICENSE). Cite the
678
195
  [Zenodo concept DOI](https://doi.org/10.5281/zenodo.22650136), which always
679
196
  resolves to the latest archived release; each release also has its own version
680
- DOI. Citation metadata is also available in [CITATION.cff](CITATION.cff).
197
+ DOI. Citation metadata is in [CITATION.cff](CITATION.cff).
681
198
 
682
199
  Canonical repository: <https://github.com/ils15/pantheon-opencode>
683
200