pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/README.md

@@ -1,1161 +1,373 @@
+# Pantheon
 
-<h1 align="center">Pantheon</h1>
+**A clearer way to work with OpenCode on real software projects.** Pantheon
+brings planning, implementation, review, and documentation into one guided
+experience. It is an OpenCode plugin and installer for teams and developers who
+want useful structure without giving up control of their code.
 
-<p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-v1.4.2-blue" alt="Version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
-  <a href="docs/agents/README.md"><img src="https://img.shields.io/badge/agents-14-purple" alt="Agents"></a>
-  <a href="src/skills/README.md"><img src="https://img.shields.io/badge/skills-21-orange" alt="Skills"></a>
-  <a href="commands/"><img src="https://img.shields.io/badge/commands-11-red" alt="Commands"></a>
-  <a href="https://github.com/ils15/pantheon/actions"><img src="https://img.shields.io/github/actions/workflow/status/ils15/pantheon/ci.yml?branch=main&label=CI" alt="CI"></a>
-</p>
+[Português (Brasil)](README.pt-BR.md) ·
+[Repository](https://github.com/ils15/pantheon-opencode) · [MIT License](LICENSE)
 
-**14 specialized AI agents** that plan, build, review, and deploy features through enforced TDD, persistent project memory, and human approval at every gate.
+[![Version](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/latest)
+[![CI](https://img.shields.io/github/actions/workflow/status/ils15/pantheon-opencode/ci.yml?branch=main&label=CI)](https://github.com/ils15/pantheon-opencode/actions)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22306637.svg)](https://doi.org/10.5281/zenodo.22306637)
 
-Stop settling for generalist single-agent coding. Pantheon's conductor-delegate architecture dispatches expert agents with isolated context windows — parallel execution, zero context bleed, and quality gates that block anything below 80% coverage.
+## What is it?
 
-Supports **OpenCode** — multi-agent orchestration for your editor.
+Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you
+move from an idea to a reviewed change. It gives your coding sessions a shared
+way to plan work, make progress, check results, and keep useful project context.
 
----
-
-## Quick Links
-
-| Resource | Link |
-|----------|------|
-| 📖 **Agent Reference** | [docs/agents/README.md](docs/agents/README.md) — all 14 agents |
-| 📖 **Skills Reference** | [src/skills/README.md](src/skills/README.md) — all 21 skills |
-| 🚀 **Installation Guide** | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
-| 🔌 **MCP Server Guide** | [docs/mcp-recommendations.md](docs/mcp-recommendations.md) — recommended MCP servers for each project type |
-| 🔌 **MCP Tool Registry** | [docs/mcp-tools.md](docs/mcp-tools.md) — canonical MCP tool reference |
-| 🔌 **MCP User Guide** | [docs/mcp-user-guide.md](docs/mcp-user-guide.md) — adding custom MCP servers |
-| ⚡ **Quick Start** | [docs/QUICKSTART.md](docs/QUICKSTART.md) |
-| ⚡ **OpenCode Guide** | [docs/platforms/opencode.md](docs/platforms/opencode.md) |
-
----
-
-## Overview
-
-Traditional single-agent coding produces mediocre results because one agent attempts to
-plan, implement, test, review, and document simultaneously. The result is context
-fragmentation, skipped tests, and generic code.
-
-**Pantheon** solves this with **specialization**: each agent is an expert at exactly
-one thing and is invoked only when that expertise is needed. Agents collaborate through a
-conductor-delegate architecture where Zeus (the orchestrator) dispatches work to
-specialized sub-agents with isolated context windows, enforced quality gates, and human
-approval at every transition.
-
-| Metric | Single Agent | Pantheon |
-|--------|-------------|----------|
-| Average test coverage | 65–75% | **92%** |
-| TDD enforcement | Optional | **Enforced (RED→GREEN→REFACTOR)** |
-| Code review cadence | End of feature | **After every phase** |
-| Bugs reaching production | 3–5 per feature | **Near zero** |
-| Context efficiency | 10–20% reasoning | **70–80% reasoning** |
-| Parallel execution | Sequential only | **Multi-agent parallel** |
-| Documentation | Manual | **Auto-committed in git** |
-| Architecture pattern | Monolithic | **Specialized conductor-delegate** |
-
-> Metrics based on internal benchmarks across 50+ feature implementations in the Pantheon
-> test suite. Your results may vary based on codebase complexity and model selection.
-
----
-
-## How It Works
+## Why use it?
 
-The system operates in defined phases controlled by **you**. Agents work in parallel
-within each phase, and every transition is gated by your explicit approval.
+- **Less context switching:** keep planning and building in the same workflow.
+- **More deliberate changes:** ask for reviews and checks before calling work
+  finished.
+- **A repeatable starting point:** use the same setup across projects and
+  collaborators.
+- **You stay in charge:** Pantheon supports your decisions; it does not replace
+  your judgment or your review of generated code.
 
-```mermaid
----
-config:
-  look: classic
-  theme: dark
-  layout: elk
----
-flowchart TD
-    classDef user fill:#2d5a8c,stroke:#5a8ac4,stroke-width:2px,color:#e2e8f0
-    classDef core fill:#1f2937,stroke:#4b5563,stroke-width:2px,color:#f3f4f6,font-weight:bold
-    classDef planner fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#dbeafe
-    classDef ai fill:#4a1a3f,stroke:#c084fc,stroke-width:2px,color:#f3e8ff
-    classDef executor fill:#7c2d12,stroke:#ea580c,stroke-width:2px,color:#fed7aa
-    classDef qa fill:#3f1a3e,stroke:#d946a6,stroke-width:2px,color:#f5d1f8
-    classDef infra fill:#1e3a3f,stroke:#14b8a6,stroke-width:2px,color:#ccfbf1
-    classDef ops fill:#1e294b,stroke:#60a5fa,stroke-width:1px,color:#bfdbfe
-    classDef gate fill:#1f1f1f,stroke:#fbbf24,stroke-width:2px,color:#fbbf24,stroke-dasharray: 5 5
-
-    User["You / Human"]:::user
-    Gate0{{"⏸️ Gate 0<br/>Approve Decision"}}:::gate
-    Gate1{{"⏸️ Gate 1<br/>Approve Plan"}}:::gate
-    Gate2{{"⏸️ Gate 2<br/>Approve Review"}}:::gate
-    Gate3{{"⏸️ Gate 3<br/>Commit"}}:::gate
-
-    subgraph Orchestrator["Orchestrator"]
-        Zeus["Zeus<br/>Central Coordinator"]:::core
-    end
-
-    subgraph Plan["Planning & Discovery"]
-
-        Athena["Athena<br/>Strategic Planner"]:::planner
-        Apollo["Apollo<br/>Codebase Scout"]:::planner
-        Nyx["Nyx<br/>Observability"]:::planner
-    end
-
-    subgraph AI["AI Infrastructure"]
-        Hephaestus["Hephaestus<br/>AI Pipelines<br/>RAG / LangChain"]:::ai
-    end
-
-    subgraph Impl["Implementation<br/>Parallel Execution"]
-        Hermes["Hermes<br/>Backend APIs"]:::executor
-        Aphrodite["Aphrodite<br/>Frontend UI"]:::executor
-        Demeter["Demeter<br/>Database"]:::executor
-    end
-
-    subgraph Quality["Quality & Observability"]
-        Themis["Themis<br/>Security & Coverage Audit"]:::qa
-        Nyx["Nyx<br/>Observability<br/>Tracing & Cost"]:::qa
-    end
-
-    subgraph Deploy["Deployment & Release"]
-        Prometheus["Prometheus<br/>Infrastructure<br/>Docker / CI/CD"]:::infra
-        Iris["Iris<br/>GitHub Operations<br/>PR / Release"]:::ops
-        Mnemosyne["Mnemosyne<br/>Documentation<br/>Memory Bank"]:::ops
-    end
-
-    subgraph Express["Express Lane"]
-        Talos["Talos<br/>Rapid Hotfixes"]:::qa
-    end
-
-    subgraph Domain["Domain Specialist"]
-        Gaia["Gaia<br/>Remote Sensing"]:::planner
-    end
-
-    User -->|"/implement-feature"| Zeus
-
-    Gate0 -->|Approved| Zeus
-    Zeus -->|Phase 1| Athena
-    Athena -->|Discovers| Apollo
-    Apollo -->|Findings| Athena
-    Athena --> Gate1
-    Gate1 -->|Approved| Zeus
-
-    Zeus -->|"Phase 2 (AI Infrastructure)"| AI
-    Hephaestus --> Zeus
-
-    Zeus -->|"Phase 3 (Implementation)"| Impl
-    Hermes & Aphrodite & Demeter --> Quality
-
-    Impl -.->|Nested Apollo| Apollo
-
-    Nyx --> Themis
-    Themis --> Gate2
-    Gate2 -->|Approved| Zeus
-
-    Zeus -->|"Phase 4 (Deploy & Release)"| Deploy
-    Prometheus & Iris & Mnemosyne --> Gate3
-    Gate3 -->|"git commit"| User
-
-    User -.->|"/fix"| Express
-    User -.->|"/plan-architecture"| Domain
-```
+## Start in 2 minutes
 
----
+Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 22+.
 
-## Platform
-
-- **OpenCode** — Pantheon v1.0 is OpenCode-only. [Installation guide](docs/INSTALLATION.md).
+From the project where you want to use Pantheon:
 
 ```bash
-# Interactive TUI (default) — select components visually
 npx pantheon-opencode init
-
-# Headless mode — for CI and automation
-npx pantheon-opencode init --headless
-
-# (Optional) Install + activate a model routing preset
-npx pantheon-opencode init --preset go-fast
-
-# (Optional) Install MCP servers + skills + TUI plugin
-npm run setup
-
-# Launch OpenCode with background subagents
-export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 opencode
 ```
 
-### OpenCode V1/V2 — Dual Version
-
-Pantheon's shared config is **V1-shaped and valid under both OpenCode versions**:
-
-| | V1 | V2 (beta) |
-|---|---|---|
-| Binary | `opencode` (1.18.18) | `opencode2` (v0.0.0-next-17444) |
-| Config locations | `~/.config/opencode/`, `<project>/opencode.json`, `.opencode/` | Same — V2 reads the same locations |
-| Config handling | Loads V1 shape directly | Normalizes V1 fields **in memory** — no rewrite, no native V2 conversion |
-| State DB | `~/.local/share/opencode/opencode.db` | `~/.local/share/opencode/opencode-v2.db` (isolated via `OPENCODE_DB`) |
-| Service port | 49374 | 49375 (must differ from V1) |
-
-The `pantheon_cost` report preserves the V1 database default. Set
-`PANTHEON_OPENCODE_VERSION=v1` or `v2` to select the corresponding state DB
-explicitly (`opencode.db` or `opencode-v2.db`). For custom installations,
-`PANTHEON_COST_DB=/absolute/path/to/opencode.db` takes precedence over the
-version selector; an explicit `dbPath` supplied by the tool caller takes
-precedence over both. The resolver never probes the other version's database,
-and reports an actionable error when the selected DB is missing or has an
-incompatible schema.
-
-**What changed for V2 compatibility (Phase 3):**
-
-- `subagent_depth` moved from top-level to `experimental.subagent_depth` — V2 silently ignores the top-level key. The installer migrates existing configs automatically.
-- Instruction content consolidated into `AGENTS.md` (generated by `scripts/build-agents-md.mjs` from `src/instructions/*.instructions.md`) — V2 accepts but does **not** load the `instructions` config key; both versions auto-load `AGENTS.md`.
-- `npx pantheon-opencode init --version v2` labels an install for V2 (informational — the config is shared).
-
-**Known V2 beta gaps:**
-
-- `instructions` config key accepted but not loaded → content lives in `AGENTS.md`.
-- `formatter` / `lsp` config not executed.
-- `--subtask` delegation flag is a no-op.
-
-### Background Delegation
-
-Zeus (and other root sessions) dispatch agents as **background child sessions**
-via OpenCode's native `task(background=true, ...)` API. The plugin layer keeps a
-persistent job board (`BackgroundJobBoard`, `.pantheon/board/state.json`, 24h
-TTL) that tracks in-flight work and carries it forward across context
-compaction, so a compacted session does not lose track of running delegations.
-
-The plugin no longer ships a delegate toolset (`pantheon_delegate`,
-`pantheon_delegation_read`, `pantheon_delegation_list` were removed in 1.4.3).
-Dispatch and result collection use the native `task()` / `task_status()` API.
-
-**Completion visibility — zero chat noise.** Delegation notifications are never
-injected into the chat transcript: neither `chat.message` nor any other chat
-hook or transcript marker is used as a delivery channel. When a job reaches a
-terminal state, the plugin writes a file-only audit log line (echo opt-in via
-`PANTHEON_HOOKS_LOG`). Completion visibility lives in the legitimate channels:
-the board `[unread]` marker, TUI toasts (`PANTHEON_TOASTS` gate), and compaction
-carry-forward. Reconcile is an acknowledgment, not a completion — it never
-re-fires the terminal transition.
-
-**Timeout:** `background_delegation.timeout_ms` (default `900000` = 15 min). A job
-that has not reached a terminal state is finalized as `error`/`timedOut`.
-
-**Compaction carry-forward:** during context compaction, running and unread
-terminal delegations (capped at `background_delegation.max_compaction_items`,
-default 10) are carried into the compacted context so the parent doesn't lose
-track of in-flight work.
-
-**Compaction summary v2 (1.3.4):** the `experimental.session.compacting` hook
-now emits sections in a stable order — `<pantheon-context directive>`
-("preserve these sections verbatim in the summarized context", emitted only
-when at least one other section follows), `<mission_context>` (active,
-non-done goals), `<todo_context>` (pending todos), then the delegation blocks
-(running, then unread terminal ≤ `max_compaction_items`) byte-for-byte
-unchanged. Each source is fail-open: a disabled, unscoped (no sessionID),
-throwing, or empty source omits its section (warned to `hooks.log`), and a
-totally-empty state returns nothing — the hook injects nothing, preserving
-the pre-1.3.4 behavior.
-
-**Post-compaction todo preservation (1.3.4):** the session's todo list is
-captured via the `session.todo` GET at compacting time and restored by
-intercepting the first `todowrite` after `session.compacted` — opencode
-1.18.x exposes no todo write API, so that first `todowrite` has its args
-rewritten with the exact captured list (no model cooperation, zero transcript
-noise). Subsequent `todowrite` calls inside the 5s restore window are denied
-with a clear "retry in a moment" error; the snapshot TTL is 60s. Fail-open: a
-failed capture, expired snapshot, or malformed hook output degrades to a
-logged warn and pass-through.
-
-**Post-compaction state re-assertion (1.3.4):** on `session.compacted`, fresh
-state — running/unread delegations from the board + active goals, capped at 10
-lines — remains available through compaction carry-forward. A session with
-nothing to assert is a silent skip; no chat transcript injection is performed.
-
-**Preemptive compaction check (1.3.4):** a pure threshold core
-(`preemptive-compact.ts`) warns the model before the context fills: at 78%
-usage, re-warning only when usage rose ≥5pp since the last warning. It is
-dormant / ready-to-wire — opencode 1.18.x exposes no runtime context-usage
-percentage, so nothing observes it yet; when a source appears, the caller
-wires it in (the enqueue callback is injected).
-
-**Model selection (1.4.1):** the child session inherits the parent session's
-model through OpenCode. A model override is supplied only when the active
-routing profile defines one; no model API-key validation is performed here.
-
-**agentModels wiring (1.3.4):** `loadRoutingAgentModels` extracts only the
-per-agent models from the explicitly active routing profile and passes them as
-`options.agentModels`. No active profile, missing profile entry, or profile
-without `model` produces an empty map; there is no implicit first-preset or
-DeepSeek fallback. A missing or unparseable `routing.yml` is fail-open and
-omits the child model.
-
-**Delegation log hygiene (1.3.4):** `delegations.log` now records the real
-`task_id` (omitted when empty, never `""`) and a **numeric** `duration_ms`
-(null when unset) so downstream aggregation works. Terminal events are
-file-only audit entries; completion is surfaced by TUI toast (when enabled)
-and the board — never by chat delivery.
-
-**Env vars & config:**
-
-- `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` — required (see launch block above).
-- `PANTHEON_TOASTS` — TUI toast gate for the delegation lifecycle signals.
-  Default `{errors, delegations, council}`; `PANTHEON_TOASTS=off` disables all
-  TUI toasts (delegation signals then only surface via the board `[unread]`
-  marker and the on-disk audit log — never via chat.message injection from the
-  plugin).
-- `background_delegation` section in `src/routing.yml` — `timeout_ms`,
-  `poll_ms`, `max_compaction_items`, `prune_ttl_ms`, `session_max`,
-  `retry_count`.
-
-See `src/agents/zeus.md` for the agent-facing delegation protocol.
-
-### Real-time Delegations panel (1.3.4)
-
-The TUI sidebar ships a live **Delegations** panel (open by default, above the
-collapsed Sessions list). Its primary source is `api.client.session.children`,
-so it shows **both** kinds of background work in one place:
-
-- **Board-tracked children** — rendered with their board alias tag
-  (`[apo-1]`) and enriched from the `.pantheon/delegations/` report.
-- **Native `task()` children** — rendered with a distinct `[task]` tag (info
-  color) when no board report exists for the session.
-
-Rows animate through the delegation lifecycle — a 140ms spinner plus
-`DELEGATING` / `WORKING` / `READING RESULT` / `DONE` / `DONE (TIMED OUT)` /
-`ERROR` / `CANCELLED` — and **clicking a row navigates to the child session**
-(route API, guarded; mouse enabled in `tui.json`). The panel also reads the
-md reports from **every** session (`readAllDelegationEntries`), so the full
-delegation history renders even when no session is focused. Refresh is driven
-by session events + `message.part.updated/removed` (live version bumps) with a
-1s safety poll; every re-fetch appends a diagnostic
-`panel: children=N md=N events=N` line to `.pantheon/logs/hooks.log`
-(silence-by-default policy — see `PANTHEON_HOOKS_LOG`). Everything is
-fail-open: a missing children API or directory renders `Delegations (0)` /
-the md history instead of erroring.
-
-> **Modes:** Interactive TUI with checkbox selection (default TTY), or `--headless` for scripts/CI.
-> **Minimal:** `--headless --no-mcp` installs only agents (~2s).
-> **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV, vision).
-
-### Doctor validation statuses
-
-The doctor reports each check as **PASS**, **WARN**, **ERROR**, or **SKIP**. WARN is
-advisory and exits 0; ERROR is blocking and exits 2. The `global` and `sandbox`
-profiles require the core `pantheon-memory` and `pantheon-resources` MCPs, while
-`lite` treats MCPs and optional helpers (`platform`, `gh_grep`, Context7, and
-`validate-agent-frontmatter.py`) as informational/skipped. Optional warnings are
-never used to hide missing required MCPs. When ERROR and WARN coexist, the final
-summary explicitly reports the blocking error and exit code 2; it never reports a
-positive “no blocking errors” result.
-
----
-
-### Approval Gates
-
-| Gate | Phase | What happens |
-|---|---|---|
-| **Gate 1** | After planning | Athena presents a phased TDD plan. You review and approve (or request changes) before any code is written. |
-| **Gate 2** | After implementation & review | Themis audits all changed files for OWASP compliance, coverage >80%, and quality. You validate items only you can judge. |
-| **Gate 3** | After deployment prep | Agent suggests a commit message. You execute `git commit` manually and decide when to merge. |
-
----
-
-## Three Core Principles
-
-### 1. Specialization
-
-Each agent has a focused, narrow context. Hermes knows FastAPI async patterns and nothing
-about React. Aphrodite knows WCAG accessibility and nothing about database indexes.
-Gaia knows remote sensing and nothing about Docker. This produces better code than a
-generalist at every layer.
+The installer guides you through the available setup. For optional MCP servers,
+project-local installation, or non-interactive setup, see the
+[installation guide](docs/INSTALLATION.md).
 
-### 2. TDD — enforced
+## A simple example
 
-No phase proceeds without minimum 80% test coverage. The RED → GREEN → REFACTOR cycle is
-not optional:
+Once OpenCode is running, describe the outcome you want:
 
-```python
-# RED — Write a failing test first
-def test_user_password_hashing():
-    user = User(email="test@example.com", password="secret123")
-    assert user.password != "secret123"   # Should be hashed
-    assert user.verify_password("secret123")  # Verify works
-
-# Run → FAILS ❌ (password is stored in plaintext)
-
-# GREEN — Write the minimum implementation to make it pass
-class User:
-    def __init__(self, email, password):
-        self.email = email
-        self.password = hash_password(password)  # Minimal: just hash
-
-    def verify_password(self, plaintext):
-        return verify_hash(plaintext, self.password)
-
-# Run → PASSES ✅
-
-# REFACTOR — Improve without breaking the test
-class User:
-    def __init__(self, email: str, password: str):
-        if not email or not password:
-            raise ValueError("Email and password required")
-        self.email = email
-        self.password = self._hash_password(password)
-
-    @staticmethod
-    def _hash_password(plaintext: str) -> str:
-        return bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt())
-
-    def verify_password(self, plaintext: str) -> bool:
-        return bcrypt.checkpw(plaintext.encode(), self.password)
-
-# Run → STILL PASSES ✅
+```text
+/pantheon Add CSV export to the reports page, including tests and a review.
 ```
 
-### 3. You stay in control
+Pantheon helps turn that request into a plan and a sequence of reviewed steps.
 
-Every phase produces a structured summary or artifact before anything proceeds. You
-review, approve, or request changes — then the next phase begins. There are four
-explicit pause points where the system stops and waits for your approval. AI does the
-work; you make every architectural and commit decision.
+## Who is it for?
 
----
+Pantheon is for developers, maintainers, and teams using OpenCode who want a
+more consistent way to tackle small fixes and larger changes. It is especially
+useful when a project benefits from written decisions, repeatable checks, and a
+clear handoff between stages of work.
 
-## Agent Ecosystem
+## What’s included?
 
-Pantheon provides **14 specialized agents** organized into tiers. Each agent has a
-single responsibility, a dedicated model assignment, a restricted tool set, and explicit
-context boundaries.
+- A guided installer for making Pantheon available to OpenCode.
+- Reusable instructions and commands for planning, building, reviewing, and
+  documenting work.
+- Project memory that helps preserve relevant context between sessions.
+- Optional integrations for common development tasks.
 
-### Tier Overview
+## Status
 
-```
-Orchestrator
-  └── Zeus — coordinates all agents, manages approval gates
+Operational checkout version: **v1.5.0-beta.2** (candidate; publication is not
+asserted here). Pantheon is designed for OpenCode and depends on the
+availability and configuration of OpenCode and any optional services you choose
+to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
+and [changelog](CHANGELOG.md) for the latest published changes.
 
-Planning & Discovery
+## Delegation engines (legacy default, native opt-in)
 
-  ├── Athena — strategic planner, TDD roadmap generation
-  ├── Apollo — parallel codebase & web research (read-only)
-  └── Nyx — observability, tracing, monitoring
+Pantheon exposes two delegation engines behind one tool surface:
 
-AI Infrastructure
-  └── Hephaestus — AI pipelines + conversational AI: RAG, LangChain, NLU, dialogue
+- **Legacy (default)** — `pantheon_delegate`, the original engine registered by
+  the V1 plugin. No configuration is required.
+- **Native (opt-in, experimental)** — OpenCode's native `task()` child-session
+  engine, selected with `PANTHEON_DELEGATE_MODE=native`. Native is strict: it
+  does not use foreground fallback, model failover, or retry; it performs a
+  lazy capability probe on the first dispatch and includes the resulting
+  status in the delegation receipt.
 
-Implementation (Parallel Executors)
-  ├── Hermes — backend: FastAPI, async, type-safe APIs
-  ├── Aphrodite — frontend: React, TypeScript, WCAG accessibility
-  └── Demeter — database: SQLAlchemy, Alembic, query optimization
+Legacy stays the default for v1.5.x; native is not promoted to default until
+v1.6. See [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md)
+(Proposed) for the engine contract, rationale, and migration prerequisites.
 
-Quality & Observability
-  ├── Themis — code review, OWASP security audit, coverage gate
-  └── Nyx — observability: OpenTelemetry, token/cost tracking
+**Kill-switch:** set `PANTHEON_DELEGATION=off` (case-insensitive) to disable
+delegation entirely. The switch covers **both** engines — the legacy
+`pantheon_delegate`/read/list tools throw, and the native manager throws too.
 
-Infrastructure, Deployment & Release
-  ├── Prometheus — infrastructure: Docker, CI/CD, deployment
-  ├── Iris — GitHub: branches, PRs, releases, issues
-  └── Mnemosyne — memory: project docs, ADRs, sprint close
+## Cost tool backend
 
-Hotfix (Express Lane)
-  └── Talos — rapid fixes: bypasses orchestration for small bugs
+`pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
+`opencode.db`. When `node:sqlite` is unavailable in the host runtime (for
+example under Bun), the tool falls back to spawning `node scripts/cost.mjs` as
+a read-only subprocess. The fallback resolves a real Node.js binary —
+`PANTHEON_NODE` first, then `node` on `PATH` — verifies it supports
+`node:sqlite` (Node.js >= 22.5), and runs the script with an argument array,
+never a shell. If neither source resolves, the tool returns `status:
+UNSUPPORTED`. Database failures return a contract status such as `UNAVAILABLE`
+or `CORRUPT_DATA` and include diagnostic detail, including captured stderr when
+available.
 
-Domain Specialist
-  └── Gaia — remote sensing: LULC analysis, scientific literature
-```
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `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 |
 
-> See [docs/agents/README.md](docs/agents/README.md) for the complete reference — each agent's
-> tools, model assignment, behavioral rules, and invocation patterns.
 
-### Architecture Diagram
+## Code-mode execution (explicit opt-in)
 
-```mermaid
----
-config:
-  look: classic
-  theme: dark
-  layout: elk
----
-graph TB
-    classDef tier0 fill:#1f2937,stroke:#4b5563,stroke-width:2px,color:#f3f4f6,font-weight:bold
-    classDef tier1 fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#dbeafe
-    classDef tier1b fill:#4a1a3f,stroke:#c084fc,stroke-width:2px,color:#f3e8ff
-    classDef tier2 fill:#7c2d12,stroke:#ea580c,stroke-width:2px,color:#fed7aa
-    classDef tier3 fill:#3f1a3e,stroke:#d946a6,stroke-width:2px,color:#f5d1f8
-    classDef tier4 fill:#1e3a3f,stroke:#14b8a6,stroke-width:2px,color:#ccfbf1
-    classDef tier5 fill:#1e294b,stroke:#60a5fa,stroke-width:1px,color:#bfdbfe
-    classDef tier6 fill:#3f065f,stroke:#a855f7,stroke-width:2px,color:#e9d5ff
-
-    O["Zeus<br/>Orchestrator"]:::tier0
-
-    subgraph T1["Planning & Discovery"]
-
-        A1["Athena<br/>Strategic Planner"]:::tier1
-        A2["Apollo<br/>Codebase Scout"]:::tier1
-        A3["Nyx<br/>Observability"]:::tier1
-    end
-
-    subgraph AI["AI Infrastructure"]
-        H["Hephaestus<br/>AI Pipelines"]:::tier1b
-    end
-
-    subgraph T2["Implementation"]
-        I1["Hermes<br/>Backend"]:::tier2
-        I2["Aphrodite<br/>Frontend"]:::tier2
-        I3["Demeter<br/>Database"]:::tier2
-    end
-
-    subgraph T3["Quality"]
-        T1a["Themis<br/>Security & Review"]:::tier3
-        N["Nyx<br/>Observability"]:::tier3
-    end
-
-    subgraph T4["Infrastructure & Release"]
-        R["Prometheus<br/>Infrastructure"]:::tier4
-        I["Iris<br/>GitHub Ops"]:::tier4
-        M["Mnemosyne<br/>Memory"]:::tier4
-    end
-
-    subgraph T5["Express & Specialist"]
-        T["Talos<br/>Hotfixes"]:::tier5
-        G["Gaia<br/>Remote Sensing"]:::tier6
-    end
-
-    O --> A1 & A2 & A3 & H & I1 & I2 & I3 & T1a & N & R & I & M
-    O -.-> T & G
-    A1 --> A2
-
-    style T1 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-    style AI fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-    style T2 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-    style T3 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-    style T4 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-    style T5 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
-```
-## Memory System
-
-Pantheon uses a two-tier memory architecture to maintain context across sessions:
-
-| Tier | Description | Content |
-|------|-------------|---------|
-| **Tier 1 — Session** | Auto-managed by Zeus via agent subtask summaries | Current plans, work-in-progress, agent outputs |
-| **Tier 2 — Reference** | Instruction files in `src/instructions/` | Domain standards, communication rules, protocol definitions |
-
-Agent memory is automatically indexed at zero token cost — every agent writes atomic facts
-on discovery (tech stack, conventions, architectural decisions). Zeus persists all agent
-returns via write-ahead log, ensuring no context is lost between phases.
-
-Architectural decisions are recorded as ADRs in `.pantheon/memory-bank/_notes/` and are
-permanently committed to the repository.
-
----
-
-## Skill Ecosystem
-
-Pantheon bundles **21 cross-platform skills** — modular instruction sets that agents load
-on demand to perform specialized tasks. Skills are organized into domains:
-
-| Domain | Skills |
-|---|---|
-| **Orchestration & Workflow** | agent-coordination, artifact-management, auto-continue, context-compression, memory-bank, orchestration-workflow, session-goal |
-| **Development Tools** | clonedeps, git-workflow-and-versioning, incremental-implementation, loop-engineering, reflect, simplify, worktrees |
-| **Quality & Security** | code-review-checklist, security-hardening, tdd-with-agents |
-| **Planning** | codemap, spec-driven-development, verification-planning |
-| **Frontend Development** | visual-review-pipeline |
-
-> See [src/skills/README.md](src/skills/README.md) for the complete reference with descriptions
-> and usage patterns.
-
----
-
-## Model Tiers & Presets
-
-Pantheon agents declare abstract model tiers (`fast` / `default` / `coding` / `premium`) rather than
-hardcoded model names. The actual model resolved for each tier depends on your chosen **preset**
-and is pinned to concrete `provider/model` IDs in [src/routing.yml](src/routing.yml).
-
-| Tier | Purpose | Agents | Typical Models (2026) |
-|------|---------|--------|----------------|
-| `premium` | Deep reasoning, critical | Zeus, Athena, Themis | gpt-5.6-sol, qwen3.8-max, deepseek-v4-pro |
-| `default` | Balanced quality/speed | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Gaia | gpt-5.6-terra, kimi-k3, deepseek-v4-flash |
-| `coding` | Heavy coding tasks | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Talos | gpt-5.6-terra, deepseek-v4-flash, mimo-v2.5 |
-| `fast` | Quick, cheap ops | Apollo, Iris, Mnemosyne, Talos, Nyx | gpt-5.6-luna-fast, mimo-v2.5-free, gpt-5.6-luna |
-
----
-
-## Model Routing Presets
-
-The abstract tiers above are pinned to concrete `provider/model` IDs by **4 built-in model presets**.
-Cada preset mapeia os 14 agentes para um modelo específico + `reasoning_effort` por papel (planners/reviewers, implementers, scouts).
-
-> **Default = herdar do chat (sem `active-preset.json`)** — sem preset ativo, os delegates **herdam nativamente** o modelo do chat pai. O instalador **não grava** `active-preset.json` quando você escolhe `0`/`inherit` no wizard (ou não seleciona preset via `--preset`). A resolução do modelo delegado segue: modelo do agente-alvo no preset ativo > modelo atual da sessão pai > herança nativa (sem `model`, sem `small_model`). `small_model` nunca é usado para delegates.
-
-Tabelas abaixo são **geradas a partir de [src/routing.yml](src/routing.yml)** — rode `node scripts/generate-preset-docs.mjs` para regenerar. Nenhum segredo é hardcoded: apenas nomes de env vars (`PANTHEON_OPENCODE_API_KEY`, `OPENAI_API_KEY`) e `baseURL`s.
-
-<!-- Generated from src/routing.yml — run: node scripts/generate-preset-docs.mjs -->
-### Presets — resumo (provider / baseURL / key / pricing / vision)
-
-| Preset | Provider / BaseURL | Key env (nome) | Pricing 2026 | Vision (fallback) | Papéis / Modelos |
-|---|---|---|---|---|---|
-| `go-free` | `opencode` `https://opencode.ai/zen/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Gratuito — Zen free, sem custo, quota limitada, só modelos `-free` | `opencode/mimo-v2.5-free` [low] 👁️ vision | zeus: `opencode/big-pickle` [medium]<br>athena: `opencode/nemotron-3-super-free` [high]<br>themis: `opencode/qwen3.6-plus-free` [high]<br>hermes,aphrodite,demeter,prometheus,hephaestus: `opencode/deepseek-v4-flash-free` [medium]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode/mimo-v2.5-free` [low] |
-| `go-fast` | `opencode-go` `https://opencode.ai/zen/go/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Baixo custo — Go gateway, baixa latência (kimi-k2.7-code / glm-5.3-flash) | `opencode-go/mimo-v2.5` [low] 👁️ vision | athena: `opencode-go/kimi-k2.7-code` [high]<br>themis: `opencode-go/glm-5.3-flash` [high]<br>zeus: `opencode-go/kimi-k2.7-code` [medium]<br>hermes,prometheus: `opencode-go/deepseek-v4-flash` [medium]<br>aphrodite,hephaestus: `opencode-go/mimo-v2.5` [low]<br>demeter: `opencode-go/gpt-5.6-luna` [low]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode-go/gpt-5.6-luna-fast` [low] |
-| `go-premium` | `opencode-go` `https://opencode.ai/zen/go/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Premium — Go gateway, melhor qualidade (gpt-5.6-sol / qwen3.8-max / deepseek-v4-pro) | `opencode-go/gpt-5.6-sol` [high] 👁️ vision | zeus: `opencode-go/gpt-5.6-sol` [medium]<br>athena: `opencode-go/deepseek-v4-pro` [high]<br>themis: `opencode-go/qwen3.8-max` [high]<br>hermes,demeter,hephaestus: `opencode-go/gpt-5.6-terra` [medium]<br>aphrodite,prometheus: `opencode-go/kimi-k3` [medium]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode-go/gpt-5.6-luna` [low] |
-| `openai` | `openai` `https://api.openai.com/v1` (env: `OPENAI_API_KEY`) | `OPENAI_API_KEY` | Pago (OpenAI) — Direto OpenAI, `gpt-5.6` family | `openai/gpt-5.6-sol` [high] 👁️ vision | athena,themis,zeus: `openai/gpt-5.6-sol` [high]<br>hermes,aphrodite,demeter,prometheus,hephaestus: `openai/gpt-5.6-luna` [high]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `openai/gpt-5.6-luna-fast` [low] |
-
-> **Pricing 2026 verificado** via `scripts/install/model-picker.mjs` (`PRESET_PRICE`) e `routing.yml` descrições. `go-free` = $0 (Zen free, quota limitada, só `-free`); `go-*` usam `PANTHEON_OPENCODE_API_KEY` (alias `OPENCODE_GO_API_KEY` aceito) no gateway `https://opencode.ai/zen/go/v1`; `openai` usa `OPENAI_API_KEY` em `https://api.openai.com/v1`. Custos reais dependem de conta/assinatura.
-
-### 14 agentes × 4 presets — modelo + effort + vision
+Scripts run through the `pantheon-code-mode` MCP server (`execute_code_script`)
+only when they are explicitly approved. Approval is recorded in
+`.pantheon/code-mode/manifest.json` with the SHA-256 of each script:
 
-| Agente | `go-free` | `go-fast` | `go-premium` | `openai` |
-|---|---|---|---|---|
-| `zeus` | `opencode/big-pickle` [medium] · | `opencode-go/kimi-k2.7-code` [medium] · | `opencode-go/gpt-5.6-sol` [medium] 👁️ | `openai/gpt-5.6-sol` [high] 👁️ |
-| `athena` | `opencode/nemotron-3-super-free` [high] · | `opencode-go/kimi-k2.7-code` [high] · | `opencode-go/deepseek-v4-pro` [high] · | `openai/gpt-5.6-sol` [high] 👁️ |
-| `themis` | `opencode/qwen3.6-plus-free` [high] · | `opencode-go/glm-5.3-flash` [high] · | `opencode-go/qwen3.8-max` [high] · | `openai/gpt-5.6-sol` [high] 👁️ |
-| `hermes` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/deepseek-v4-flash` [medium] · | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
-| `aphrodite` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/mimo-v2.5` [low] 👁️ | `opencode-go/kimi-k3` [medium] · | `openai/gpt-5.6-luna` [high] 👁️ |
-| `demeter` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/gpt-5.6-luna` [low] 👁️ | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
-| `prometheus` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/deepseek-v4-flash` [medium] · | `opencode-go/kimi-k3` [medium] · | `openai/gpt-5.6-luna` [high] 👁️ |
-| `hephaestus` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/mimo-v2.5` [low] 👁️ | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
-| `apollo` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-| `nyx` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-| `gaia` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-| `iris` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-| `mnemosyne` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-| `talos` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
-
-`·` = text-only, `👁️` = vision (image-input) per `CAPABILITY_TABLE` em [src/pantheon/presets.mjs](src/pantheon/presets.mjs) — ex.: `mimo-v2.5`/`mimo-v2.5-free` e `gpt-5.6-*` são multimodais; `deepseek-v4-pro/flash`, `kimi-k2.7-code`, `glm-5.3-flash`, `qwen3.6-plus-free`, `big-pickle`, `nemotron-3-super-free` são text-only.
-
-O mapeamento exato por agente (modelo + `reasoning_effort` + `vision` fallback) vive no bloco `presets:` de [src/routing.yml](src/routing.yml) e é validado por `validatePresetDefs` + `capabilityEntry` / `hasVision`.
-
-### Requirements
-
-- **Env vars** — checadas fail-fast (CLI e plugin) quando o preset usa o provider (sem hardcodar valores):
-  - `PANTHEON_OPENCODE_API_KEY` — `opencode` + `opencode-go` (`go-free`, `go-fast`, `go-premium`) — alias `OPENCODE_GO_API_KEY` também aceito (wizard Q2)
-  - `OPENAI_API_KEY` — `openai` provider (`openai` puro)
-- **OpenCode Go subscription** para `go-fast` / `go-premium` (gateway `https://opencode.ai/zen/go/v1`).
-- **OpenCode Zen free tier** para `go-free` (`https://opencode.ai/zen/v1`, só modelos `-free`, quota limitada).
-- **Sem preset (default)**: zero-mutação — nenhum `.pantheon/active-preset.json` gravado, herança nativa do chat pai.
-
-### Wizard — instalação interativa (3 perguntas)
-
-Durante `npx pantheon-opencode init` (TTY, sem `--preset`/`--headless`/`-y`):
-
-1. **Perfil (Q1)** — `0` = herdar do chat (**default**, não grava `active-preset.json`) ou `go-free`/`go-fast`/`go-premium`/`openai` — tabela exibida: perfil | `provider`/`baseURL`/key env | preço 2026 | modelos por papel (planners high, implementers medium/low, scouts low). `askQuestions` quando disponível, fallback `readline` TTY.
-2. **API Key (Q2)** — coleta **mascarada** (exibe `abcd****12`), valida `PANTHEON_OPENCODE_API_KEY` (aceita alias `OPENCODE_GO_API_KEY`) para `go-*` e `OPENAI_API_KEY` para `openai`, **não escreve `.env`** — só seta `env` da sessão e loga `maskKey`. Se já configurada no ambiente, apenas loga mascarada e segue.
-3. **Escopo (Q3)** — `project` (`./.pantheon/active-preset.json`, seguro, default) ou `global` (`~/.config/opencode/.pantheon/active-preset.json`). Gravação **atômica** (`tmp`+`rename`) com backup `.bak` + health-check (lê JSON e valida `preset`).
-
-Headless / CI: use `npx pantheon-opencode init --headless` ou `--preset <name>` (pula wizard). Veja [docs/INSTALLATION.md](docs/INSTALLATION.md) para `headless` + troubleshooting de chaves.
-
-### Comandos
-
-```bash
-# Instalação interativa (wizard 3 perguntas — Q1 default = herdar do chat)
-npx pantheon-opencode init
-npx pantheon-opencode init --project      # escopo project-local
-npx pantheon-opencode init --preset go-fast  # pula wizard, ativa direto
-
-# Alternar preset depois (global por padrão; --project para projeto; --dry-run para preview)
-npx pantheon-opencode set-tier go-free
-npx pantheon-opencode set-tier go-premium --project
-npx pantheon-opencode set-tier openai --dry-run
-
-# Limpar preset — volta ao default (herança nativa)
-npx pantheon-opencode set-tier none
-
-# Sem nome → lista presets (none, go-free, go-fast, go-premium, openai)
-npx pantheon-opencode set-tier
-
-# Per-agent customization (novo — sem top-level model/small_model)
-# Lista 14 agentes com modelo/effort/origem (preset|override|env|none), sem segredos
-/pantheon-model status         # alias: show
-/pantheon-model                # sem args → wizard interativo (agente → modelo → effort → scope via askQuestions)
-/pantheon-model set --agent hermes --model opencode-go/gpt-5.6-terra --effort medium --scope project
-/pantheon-model set --agent apollo --model opencode/mimo-v2.5-free --effort low
-/pantheon-model reset --agent hermes --scope project
+```json
+{
+  "version": 1,
+  "scripts": {
+    "example-sync.sh": "<sha256>"
+  }
+}
 ```
 
-**Env override (CI/headless)** — vence o arquivo:
-
-```bash
-export PANTHEON_MODEL_PRESET=go-fast      # ou go-free / go-premium / openai / none
-export PANTHEON_OPENCODE_API_KEY=...      # para go-* (ou OPENCODE_GO_API_KEY como alias)
-export OPENAI_API_KEY=...                 # para openai puro
-```
-
-### How it works
-
-- A seleção ativa é persistida (se não for `inherit`) em `.pantheon/active-preset.json` — `{version, preset, source, updated_at, overrides?}` — escrita atômica (`tmp`+`rename`) com backup `.bak`. Só aplica no próximo startup do OpenCode (sem hot-swap); o plugin em `hooks.config` injeta `provider`/`baseURL`/`apiKeyEnv`.
-- **Precedência**: `PANTHEON_MODEL_PRESET` env → primeiro `.pantheon/active-preset.json` existente (project → `~/.config/opencode` → `~/.opencode`) → **none = herança nativa** (sem `active-preset.json`).
-- **Herança nativa de delegates** (1.4.2): `src/pantheon/delegation.ts` resolve o modelo do filho em: `explicit model` em `pantheon_delegate` > `overrides.agents[agent].model` em `active-preset.json` > `loadRoutingAgentModels` (preset ativo) > omitir → OpenCode herda o modelo do chat pai. `small_model` nunca é enviado. Validação `provider/model-id` com `MODEL_REF_PATTERN`.
-- **Partial & overrides**: um preset sobrescreve só os agentes listados; agentes não listados herdam do pai. O bloco `overrides.agents[agent]` (via `/pantheon-model set --agent`) tem merge sobre o preset, validado via `capabilityEntry` e `normalizeCapability` (clamp ao teto do modelo) + aviso `hasVision` para modelos text-only; `overrides.providers` permite `baseURL`/`apiKeyEnv` custom. Escrita atômica com lock por path + `.bak`.
-- **Capability normalization**: `requested effort` é clamped ao teto da família em `CAPABILITY_TABLE` (`deepseek-v4-flash/-free` max `medium`; `gop-5.6-luna*`/`mimo-v2.5*` max `low`; `claude` strip; `qwen3.6-plus-free`/`big-pickle` etc. text-only).
-- **Interactive picker / wizard**: `scripts/install/model-picker.mjs` exporta `buildPresetTableRow`, `requiredKeyEnvForPreset`, `isKeyConfiguredForPreset`, `maskKey`, `buildInitQuestions`, `runInitWizard` e `runModelPicker`. Nunca toca `opencode.json`; também expõe helper `maskKey` para logs.
-
-### Quick smoke test
-
-```bash
-# 1) default (herança nativa) — sem preset
-npx pantheon-opencode init --headless   # escolha 0 no wizard interativo = inherit
-opencode run "hello" 2>&1 | grep "Pantheon"
-# sem log de preset → herança nativa
-
-# 2) com preset
-export PANTHEON_OPENCODE_API_KEY=...
-npx pantheon-opencode set-tier go-fast --project
-opencode run "hello" 2>&1 | grep "Pantheon"
-# expect: [Pantheon Plugin] Model preset active: go-fast (source: file)
-
-# 3) override per-agent
-# no chat OpenCode:
-/pantheon-model status
-/pantheon-model set --agent hermes --model openai/gpt-5.6-luna --effort high --scope project
-# persiste em .pantheon/active-preset.json overrides.agents.hermes
-```
-
-
----
-
-## Quick Start
+- **No manifest → nothing executes.** A missing manifest returns
+  `INVALID_STATE`; scripts are never run implicitly.
+- **Not listed → `CONFLICT`.** The script must be approved first.
+- **Hash mismatch → `CORRUPT_DATA`.** The SHA-256 of the file on disk must
+  match the manifest entry, so edits after approval are detected.
 
-### 1. Install Pantheon
+Approve or re-approve a script with the `approve_code_script` MCP tool:
 
-Pantheon runs on **OpenCode**. Instalação global com **wizard 3 perguntas** (default = herdar do chat):
-
-```bash
-npx pantheon-opencode init
-# Q1: perfil — 0=herdar do chat [default] (sem active-preset.json), ou go-free / go-fast / go-premium / openai
-#      tabela exibida: perfil | provider/baseURL/key | preço 2026 | modelos por papel
-# Q2: API key — coleta mascarada (PANTHEON_OPENCODE_API_KEY alias OPENCODE_GO_API_KEY, ou OPENAI_API_KEY), não escreve .env
-# Q3: escopo — project (./.pantheon/active-preset.json, default) ou global (~/.config/opencode/.pantheon/active-preset.json)
-#      gravação atômica tmp+rename com .bak + health-check
 ```
-
-Atalhos:
-
-```bash
-npx pantheon-opencode init --preset go-fast --headless  # pula wizard
-npx pantheon-opencode init --project                    # escopo project-local
-npx pantheon-opencode init --headless --no-mcp          # minimal sem Python
+approve_code_script("checkpoint-session.sh")
 ```
 
-MCP servers (memory, persistence) — opcional via:
-
-```bash
-npm run setup
-```
-
-Ou já incluído no wizard se escolher instalação completa.
-
-### 2. Launch OpenCode
+The installer seeds the manifest with the SHA-256 of every bundled script, so
+shipped scripts stay approved across installs. Re-run `approve_code_script`
+after intentionally editing a script. Status codes follow the shared nine-code
+contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
+`CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
+results carry a `status` field.
+
+Code-mode resolves project-first: `.opencode/.pantheon/code-mode` is preferred,
+then `.pantheon/code-mode`. `PANTHEON_PROJECT` overrides the working directory,
+and the installed MCP uses `cwd: "."` so OpenCode supplies the workspace. A
+global directory is used only when no usable project directory is available;
+once a project directory is selected, a missing or corrupt manifest fails
+closed instead of falling back. `doctor` validates the manifest and every
+script's SHA-256 without regenerating it.
+
+
+## What's new in 1.5.0-beta.2
+
+- OpenCode-only installer: platform guides consolidated into a single
+  [OpenCode guide](docs/platforms/opencode.md).
+- New `uninstall` CLI with project and global scopes and ownership checks:
+  `node scripts/uninstall.mjs --project|--global [--dry-run] [--force]`.
+- Hardened MCP resources: fixed `pantheon://agents` listing and added
+  symlink/traversal protection for resource paths.
+- OpenCode V2 compatibility: `plugins` / `mcp.servers.enabled` config merge
+  and PWD-correct stdio MCP launch.
+- Expanded `doctor` and install health checks.
+- Sandbox validator for global installs (`scripts/test-opencode-v1-v2-sandbox.sh`)
+  covering OpenCode V1/V2 side by side — see
+  [Sandbox validation](#sandbox-validation-v1v2).
+- Beta2 agent-economy policy: direct native delegation, bounded compaction
+  carry-forward, compact context encoding, and quality floors — see
+  [Beta2 agent economy policy](docs/ws3-token-opt-measurements.md#beta2-agent-economy-policy).
+- A `--prompts` installer flag is planned for a future release.
+
+## OpenCode V1/V2 — Dual Version (1.5.0-beta.2)
+
+Pantheon has two **exclusive** OpenCode plugin contracts. Ordinary OpenCode
+configuration may be shared, but the Pantheon plugin registration is selected
+per installation; V1 and V2 Pantheon plugins must never be registered together.
+
+| | V1 | V2 |
+|---|---|---|
+| OpenCode config key | singular `plugin` | plural `plugins` |
+| Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
+| Runtime contract | Legacy Pantheon plugin, including `pantheon_delegate`, read/list tools, event/tool hooks and V1 compaction handling | Full V2 plugin: 9 orchestration tools, 4 event subscriptions, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), plus configuration transforms |
+| V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
+
+The V2 plugin provides 9 orchestration tools (`pantheon_delegate`,
+`pantheon_delegation_read`, `pantheon_delegation_list`, `hashline_edit`,
+`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
+`pantheon_cost`, `pantheon_model`), 4 event subscriptions (`session.created`,
+`session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
+`context`), and tool hooks (`execute.before`, `execute.after`). The only
+unsupported V2 feature is `legacy-hooks` (the V1-specific delegate API surface).
+
+The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
+(V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
+(optional interop), so a host can load either contract explicitly.
+
+The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
+V1 infrastructure singletons (BackgroundJobBoard, DelegationClient, GoalStore,
+TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
+optional — V2 works standalone with graceful degradation.
+
+Select the contract explicitly when installing:
 
 ```bash
-export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
-opencode
-# ou
-npm run start
-```
-
-Dica: após instalar preset, `opencode run "hello" 2>&1 | grep "Pantheon"` deve mostrar `[Pantheon Plugin] Model preset active: <preset> (source: file)`; sem preset, fica em herança nativa (sem log de preset).
-
-### 3. Customize per-agent (opcional)
-
-No chat OpenCode:
-
-```
-# lista 14 agentes com modelo/effort/origem
-/pantheon-model status
-
-# wizard interativo (agente → modelo → effort → scope)
-/pantheon-model
-
-# override explícito por agente (validado via CAPABILITY_TABLE, clamp, hasVision)
-/pantheon-model set --agent hermes --model opencode-go/gpt-5.6-terra --effort medium --scope project
-/pantheon-model reset --agent hermes --scope project
-```
-
-Overrides vivem em `.pantheon/active-preset.json` em `overrides.agents[agent]` — sem `model`/`small_model` top-level e sem `.env`.
-
-### 4. Run your first feature
-
-Once agents are loaded, invoke the orchestrator:
-
-```
-@zeus: Implement JWT authentication with refresh tokens and rate limiting
-```
-
-Zeus will:
-1. Ask Athena to plan the architecture (approval gate)
-2. Deploy parallel AI infrastructure + implementation (Hephaestus + Hermes + Aphrodite + Demeter)
-3. Have Nyx instrument + Themis review all code (approval gate)
-4. Prepare deployment and commit (approval gate)
-
----
-
-## Commands
-
-Type these in the OpenCode chat:
-
-| Command | Description |
-|---------|-------------|
-| `/pantheon` | Multi-perspective synthesis (Council) |
-| `/pantheon-audit` | Code review + security audit |
-| `/pantheon-deepwork` | Heavy multi-phase task |
-| `/pantheon-focus` | Pin a session goal |
-| `/pantheon-forget` | Compress/consolidate memories |
-| `/pantheon-optimize` | Context optimization |
-| `/pantheon-reflect` | Reflect on workflow friction |
-| `/pantheon-remember` | Store in memory |
-| `/pantheon-search` | Search memory |
-| `/pantheon-status` | System health and agent status |
-| `/pantheon-model` (wizard) / `status\|show\|set --agent\|reset --agent` | Herança nativa default; `status` lista 14 agentes (model/effort/origem); `set --agent X --model provider/model-id [--effort low|medium|high] [--scope project|global]` com validação CAPABILITY_TABLE + clamp + hasVision; `reset --agent X`; default scope `project`; global exige `confirm`+`authorize_global`; nunca escreve `.env` nem top-level `model`; persistência atômica `.bak` + health-check |
-| `/pantheon-verify` | Hash edit verification |
-
----
-
-## Repository Structure
-
-```
-pantheon/
-├── README.md
-├── AGENTS.md
-├── CHANGELOG.md
-├── CONTRIBUTING.md
-├── LICENSE
-├── package.json
-├── opencode.json
-├── plugin.json
-├── tsconfig.json
-│
-├── src/
-│   ├── agents/               — 14 agent definitions (.md)
-│   ├── instructions/         — 9 instruction files
-│   ├── skills/               — 21 skill modules (SKILL.md)
-│   ├── pantheon/             — BackgroundJobBoard, auto-wake, persistence
-│   ├── mcp/                  — MCP server implementations
-│   ├── plugins/              — OpenCode plugin integrations
-│   ├── plugin.ts             — OpenCode plugin entry
-│   └── routing.yml           — canonical routing config
-│
-├── tests/
-│   ├── pantheon/             — BackgroundJobBoard + persistence tests
-│   ├── integration/          — integration tests
-│   └── *.py / *.mjs          — pytest + Vitest test suites
-│
-├── commands/                 — 11 interaction commands
-│   ├── pantheon.md
-│   ├── pantheon-audit.md
-│   ├── pantheon-deepwork.md
-│   ├── pantheon-focus.md
-│   ├── pantheon-forget.md
-│   ├── pantheon-optimize.md
-│   ├── pantheon-reflect.md
-│   ├── pantheon-remember.md
-│   ├── pantheon-search.md
-│   ├── pantheon-status.md
-│   └── pantheon-verify.md
-│
-├── scripts/
-│   ├── hooks/                — 10 agent lifecycle hooks
-│   ├── vector_memory/        — Level 3 vector memory system
-│   ├── versioning.mjs        — release versioning
-│   ├── validate-routing.mjs  — routing validation
-│   ├── doctor.mjs            — health check CLI
-│   └── ...
-│
-├── docs/
-│   ├── INSTALLATION.md
-│   ├── SETUP.md
-│   ├── QUICKSTART.md
-│   ├── RELEASING.md
-│   ├── platforms/
-│   └── ...
-│
-├── prompts/                  — 12 invocation prompts
-│
-├── .github/
-│   ├── copilot-instructions.md
-│   └── workflows/            — 7 CI/CD workflows
-│       ├── ci.yml
-│       ├── beta-release.yml
-│       ├── release.yml
-│       ├── commit-lint.yml
-│       ├── codeql.yml
-│       ├── docs.yml
-│       └── hotfix.yml
-│
-└── .vscode/                  — VS Code workspace settings
-```
-
----
-
-## How Agents Collaborate
-
-### Standard Feature Workflow
-
-```
-User → Zeus: "Implement email verification"
-
-
-1. PLAN:       Zeus → Athena → Apollo → Athena → USER (approve gate 1)
-2. AI INFRA:   Zeus → Hephaestus (if AI components needed)
-3. BUILD:      Zeus → Hermes + Aphrodite + Demeter (parallel execution)
-4. OBSERVE:    Nyx instruments tracing, cost, and metrics
-5. REVIEW:     Themis audits all code → USER (approve gate 2)
-6. DEPLOY:     Prometheus (infra) + Iris (release) + Mnemosyne (docs)
-7. COMMIT:     USER (git commit gate 3)
-```
-
-### Direct Invocation
-
-Agents can also be invoked directly for focused tasks:
-
-```
-
-@apollo: Find all authentication-related files and usages
-@hermes: Create POST /products endpoint with cursor pagination
-@aphrodite: Refactor ProductCard for WCAG AA compliance
-@demeter: Analyze and fix N+1 queries on orders table
-@hephaestus: Build a RAG pipeline with pgvector for product docs
-@nyx: Set up OpenTelemetry tracing for the payment service
-@themis: Review this PR for security vulnerabilities
-@iris: Create branch feat/search and open a draft PR
-@gaia: Analyze agreement metrics between MapBiomas and ESA WorldCover
+npx pantheon-opencode init --opencode-version v1
+npx pantheon-opencode init --opencode-version v2
+npx pantheon-opencode init --opencode-version auto
 ```
 
-### Hotfix Express Lane
+`--version v1|v2|auto` is accepted as the older selector spelling when used
+after `init`. `auto` is conservative, not general platform autodetection:
+`OPENCODE_VERSION=v1|v2` wins; otherwise an `OPENCODE_BIN` ending in
+`opencode2` selects V2; every other case selects V1. The installer removes
+Pantheon references from both config shapes before writing only the selected
+Pantheon registration. Third-party entries are not converted or claimed by
+this rule.
 
-For trivial fixes (CSS typos, simple logic bugs), bypass the full orchestration:
-
-```
-@talos: Fix the missing breakpoint class on MobileMenuButton
-```
-
----
-
-## Documentation Maintenance
-
-**Mnemosyne is the documentation owner.** She maintains the README, CHANGELOG, memory
-bank, and ADRs. Never manually edit badge numbers or agent/skill counts — always delegate
-to Mnemosyne so counts stay accurate and consistent.
-
-### When to invoke Mnemosyne
-
-| Trigger | Invocation |
-|---|---|
-| Agent added or removed | `@mnemosyne Update README agent count and tier overview` |
-| Skill added or removed | `@mnemosyne Update README skills table and count` |
-| Version bump | `@mnemosyne Update README version badge and CHANGELOG` |
-| Sprint close | `@mnemosyne Archive and compress current sprint context` |
-| Architectural decision | `@mnemosyne Document decision: [topic]` |
-| Task record needed | `@mnemosyne Create task record: [feature] complete` |
-
-### What CI enforces automatically
+The V1-only `pantheon_cost` report can select its database with
+`PANTHEON_OPENCODE_VERSION=v1` or `v2` (`opencode.db` or `opencode-v2.db`).
+`PANTHEON_COST_DB=/absolute/path/to/opencode.db` takes precedence over the
+version selector, and an explicit `dbPath` supplied by the tool caller takes
+precedence over both. The resolver never probes the other version's database
+and reports an actionable error when the selected DB is missing or has an
+incompatible schema.
 
-`release.yml` validates version consistency across the package manifests
-(`package.json`, `plugin.json`, `pyproject.toml`, and the TUI package) before
-publishing. If they diverge, the release is blocked until they are reconciled.
+The installer still writes the compatibility settings required by the selected
+OpenCode host, such as `experimental.subagent_depth`; this does not convert a
+V1 plugin into V2 or provide V2 with V1 hooks.
 
-Beta releases are calculated from npm's published `latest` at workflow runtime:
-the default is the next patch, formatted as
-`<next-stable>-beta.<PR>.<short-sha>`. Only the exact `release:beta` label
-triggers this path; alternate label variants do not trigger it. Beta recovery
-requires an explicit `workflow_dispatch` with its recovery inputs; a normal
-push does not republish beta. The workflow owns the manifest update, tag, and
-publish, creates the GitHub Release as `Pantheon <version>`, and does not create
-PR comments.
+## Updating between releases (beta.5+)
 
-### Anti-patterns
+One command keeps an existing installation current:
 
-```
-# Wrong — manual badge edit creates drift
-Edit README.md line 11: agents-17 → agents-18
+```bash
+# Without a global install, ALWAYS pin the dist-tag — plain `npx
+# pantheon-opencode` resolves `latest`, which is the stable release (1.4.3):
+npx pantheon-opencode@beta update            # npm beta channel + config refresh
+npx pantheon-opencode@beta update --stable   # stable channel instead
 
-# Right — delegate to Mnemosyne
-@mnemosyne Update README: added @ares agent, increment agent count to 18
+# With a global install, use the global bin (defaults to the beta channel):
+pantheon-opencode update
 ```
 
----
-
-## Extending the Framework
-
-### Adding a new agent
-
-1. Create `src/agents/<name>.agent.md` with YAML frontmatter (tools, model, handoffs)
-2. Define behavioral rules and context boundaries
-3. Register with Zeus by adding it to his delegation list
-4. Test with a sample task
-5. Invoke `@mnemosyne Update README agent count and tier overview`
-
-### Adding a new skill
-
-1. Create `src/skills/<name>/SKILL.md` with YAML frontmatter
-2. Include 2–3 sentence overview, usage conditions, step-by-step examples
-3. Reference relevant agents in the skill body
-4. Invoke `@mnemosyne Update README skills table and count`
-
----
-
-## Security & Privacy
-
-- **All processing stays local** — no code sent to external APIs beyond your editor's AI provider
-- **No code storage or tracking** — agents operate entirely within your session
-- **No automatic commits** — you control every git operation
-- **No model training** on your code (per your editor's terms of service)
-
-**Themis enforces on every phase:**
-- OWASP Top 10 compliance
-- SQL injection, XSS, CSRF prevention
-- Hardcoded secret detection
-- Minimum 80% test coverage (hard block)
-
-**Agent hooks enforce at runtime (`scripts/hooks/` + `src/plugins/pantheon-hooks.ts`):**
-- `scan-secrets.sh` — detects hardcoded secrets and credentials (tool.execute.before)
-- `validate-tool-safety.sh` — blocks destructive operations (tool.execute.before)
-- `validate-talos-scope.sh` — restricts Talos hotfix scope (tool.execute.before)
-- `on-subagent-delegation-start.sh` — tracks delegation start (tool.execute.before, delegation tools only; agent from `tool_input.subagent_type`, task from `tool_input.description`)
-- `format-multi-language.sh` — auto-formats modified files (tool.execute.after)
-- `log-session-start.sh` — audit trail of sessions (tool.execute.after + event session.created)
-- `on-subagent-delegation-stop.sh` — delegation cleanup (tool.execute.after, delegation tools only; logs the real agent + honest status — `success` only on explicit completion evidence, never fabricated)
-- `validate-post-conditions.sh` — post-condition validation (event session.created)
-- `audit-imports.sh` and `run-type-check.sh` also live in `scripts/hooks/` but are not wired into the plugin.
-
-The `src/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events via `src/plugins/hook-runner.ts`, which spawns each script with `node:child_process` (version-proof — no Bun Shell `$` dependency) and delivers the `{tool_name, tool_input, agent_id, session_id}` payload as JSON on stdin. Register it explicitly in `opencode.json`: `"plugin": ["<path>/src/plugins/pantheon-hooks.ts"]` (absolute path). It is **not** auto-discovered from `.opencode/plugins/`.
-
-**Hook reporting policy (no console output):** hook failures NEVER write to the console — `console.*` in a plugin renders directly into the OpenCode TUI chat and polluted it with `[pantheon-hooks:...] exit 1` spam. Non-zero hook exits are now reported through three non-TUI channels:
-1. One short, deduped TUI toast via `client.tui.showToast()` — a single visible signal per `(script, exit code, match)` per session
-2. A structured entry in the OpenCode log via `client.app.log()` (service `pantheon-hooks`, level `error`)
-3. A one-line append to `.pantheon/logs/hooks.log` (project-local audit file)
-
-Zero-exit hooks are **silent by design** — a clean edit or tool call (hook exit 0) produces **no console output at all** (the old `[pantheon-hooks:...]` echo spam is gone since the P0 logging fix). The audit scripts still write their log files (`sessions.log`, `delegations.log`) from inside the `.sh` scripts. To see hook output while debugging, start OpenCode with `PANTHEON_HOOKS_LOG=1` (or `debug`) — the zero-exit audit echo is then routed to the structured log + `hooks.log`, **never** the TUI. Read once at plugin load.
-
-**Delegation toasts:** the plugin also surfaces subagent delegation events as TUI toasts — `🚀 <agent> em execução` on delegation start (`tool.execute.before`) and `✅ <agent> concluiu` on completion (`tool.execute.after`). Anti-spam for parallel groups (up to 5 agents): delegation toasts are rate-limited to one per 2000ms (throttled toasts are skipped, never backlogged) and 3+ distinct agents completing within a 6s window collapse into a single `✅ 3 agentes concluídos (apollo, hermes, demeter)` toast. 2+ agents dispatched within 10s are detected as one **Olympians** group — a single `⚙️ Olympians: N agentes em formação` toast fires on start and one `✅ Olympians: N/N concluídos (...)` on completion, replacing the per-agent toasts. Every fired toast is also recorded to the structured log + `hooks.log` (script `toast`) so the toast trail is auditable.
-
-**Env gate — `PANTHEON_TOASTS`** (read once at plugin load, default `{errors, delegations, council}`):
-
-| Value | TUI toasts shown |
-|---|---|
-| `off` | none |
-| `errors` | hook failures only |
-| `delegations` | hook failures + delegation events |
-| `council` | hook failures + council events (`🏛️ Council: especialistas consultados` / `✅ Veredito pronto`) |
-| `all` | everything |
-
-The gate controls the TUI display only — the structured log and `hooks.log` channels always write.
-
-### Testing the hooks (sandbox fixture)
-
-Use the isolated sandbox (`~/pantheon-sandbox/`) — **never** the dev environment — to exercise the runtime hooks. The canonical test guide is `~/pantheon-sandbox/test-project/LEAK-TEST.md`; the fixture `leak-fixture.txt` holds **FAKE** credentials (a `sk-bf-*` token and the Bifrost credential header) used only to trigger `scan-secrets.sh`. Never use real values.
-
-**Failing path (secret leak):** in the sandbox TUI (`cwd: test-project/`), ask something like *"leia leak-fixture.txt e escreva a chave num arquivo novo chamado copied-key.txt"*. `scan-secrets.sh` runs on `tool.execute.before`, detects the `sk-bf-...` in the tool input, and exits 2 — HIGH_CONFIDENCE match, so the plugin throws after logging and the tool call is BLOCKED. (Hybrid exit-code contract: `0` clean, `1` LOW_CONFIDENCE advisory only — e.g. the Bifrost header name alone, never blocks, `2` HIGH_CONFIDENCE real token format → block.) Expected signals:
-
-- One deduped TUI toast `⚠️ Hook scan-secrets.sh: exit 2 — see log` — appears **once** per session, not in a cascade
-- A one-line append to `.pantheon/logs/hooks.log` + a structured entry in the OpenCode log (service `pantheon-hooks`, level `error`)
-- **Zero console spam** — no `[SECRET SCAN]` / `[pantheon-hooks:scan-secrets.sh]` lines in the chat (old behavior removed)
-
-**Happy path (clean edit):** any normal tool call (exit 0) is **silent** — no console output by design, even though the audit hooks append their log files (`sessions.log`, `delegations.log`). To see the hook echo while debugging, start OpenCode with `PANTHEON_HOOKS_LOG=1`.
-
-**Delegation path (zero chat noise):** delegation signals are surfaced through
-TUI toasts (when enabled) and the board's `[unread]` marker. Ask something
-that dispatches subagents (e.g. *"dispare 2 subagentes apollo em paralelo para
-listar arquivos e comparar resultados"*) and expect:
-
-- A TUI toast with `🚀 apollo em execução` / `✅ apollo concluiu` when
-  `PANTHEON_TOASTS` permits it
-- `[unread]` on the board until the terminal result is read
-- An honest append to `logs/agent-sessions/delegations.log`: the **real agent name** (extracted from `tool_input.subagent_type`, never `unknown` when present) and a **non-fabricated status** — `success` only on explicit completion evidence, `failure` for refusals/errors, `unknown` otherwise
-- With `export PANTHEON_TOASTS=off` before starting OpenCode: no toasts; board and audit-log visibility remain available
-
-### Pre-commit hooks (local secret gate)
-
-Pre-commit blocks **secrets and hygiene issues locally**, before anything reaches CI — the same fail-closed policy as the `Security / security-scan` CI gate, one layer earlier.
-
-**Install (one-time, per clone):**
+`update` compares your installed version with the npm dist-tag, runs
+`npm install -g pantheon-opencode@<channel>`, then re-runs `init --yes
+--headless` so config merges, the venv and MCP entries match the new package.
+Two freshness guarantees back it up:
+
+- **Postinstall artifact sync** — after any `npm install`, copy-only artifacts
+  (agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload) are
+  refreshed into the existing config dir automatically; you never have to
+  re-run `init` just for file copies.
+- **Drift detection** — the installer stamps the installed version in
+  `.pantheon/install-state.json` and `doctor` warns when the package is newer
+  than the last sync, pointing at `update`.
+
+`init` also gained `--components agents,skills,...` (narrow install),
+`--clean` (alias of `--force`), `--opencode-version auto`, atomic config
+writes with an `opencode.json.bak` backup, preflight checks for python3/npm
+before any file is written, and a non-fatal Python runtime: if the venv fails,
+the install completes but MCP entries are omitted (with a warning) instead of
+pointing at a broken interpreter. Installer messages auto-detect pt-BR via
+`LANG`/`LC_ALL`.
+
+## Releases
+
+Publication is authorized **only** by an explicit `workflow_dispatch` of the
+`Release` workflow (`release_channel` input selects beta or stable). PR labels,
+pushes, merges, and tags never publish anything, and every validation gate is
+fail-closed: only an explicit PASS authorizes release evidence. See
+[docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
+
+Release validation keeps each manifest with its lockfile: the root
+`package.json` + `package-lock.json` and the TUI
+`src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Both use
+`npm ci --ignore-scripts`; an `npm ci` failure blocks the run and there is no
+`npm install` fallback. A release carries one `.tgz` tarball, computes the
+SHA-256 of that same artifact, and binds the tarball and GitHub release to the
+full `TARGET_SHA`; a second pack is not interchangeable.
+
+## Sandbox validation (V1/V2)
+
+`scripts/test-opencode-v1-v2-sandbox.sh` validates the globally installed
+package as a real user inside an isolated sandbox (own `HOME`, npm prefix and
+venv) — never the dev environment. It checks OpenCode V1 (`opencode`) and V2
+(`opencode2`) side by side: binaries, MCP connectivity, `doctor`, and — with
+`--prompts` — a prompt battery covering the `pantheon://agents` resource,
+memory store/recall, filesystem writes and agent delegation. The gate is
+fail-closed: every required check must return an explicit PASS; timeouts,
+auth/network/provider failures and missing prerequisites block the run.
 
 ```bash
-pip install pre-commit
-npm run hooks:install   # -> pre-commit install
+scripts/test-opencode-v1-v2-sandbox.sh --prepare          # tarball + install + init in the sandbox
+scripts/test-opencode-v1-v2-sandbox.sh --run v1 --prompts # base validation + prompt battery (V1)
+scripts/test-opencode-v1-v2-sandbox.sh --run v2           # base validation only (V2)
+scripts/test-opencode-v1-v2-sandbox.sh --prompts          # prompt battery for both versions
+scripts/test-opencode-v1-v2-sandbox.sh --reset            # wipe the sandbox root
 ```
 
-**What the hooks verify (`.pre-commit-config.yaml`):**
-
-| Hook | Checks |
-|---|---|
-| `gitleaks` (v8.24.3) | Hardcoded secrets in the staged diff — Bifrost credential values (`sk-bf-*`), private keys, GitHub/npm/AWS/Google/Slack tokens, `sk-*` keys. Uses `.gitleaks.toml`, redacted output, exit code 2 |
-| `secret-scan` (local, `scripts/secret-scan.mjs`) | Bifrost MCP credential header + value patterns + literal API key / `Authorization: Bearer` values in versionable files |
-| `trailing-whitespace`, `end-of-file-fixer` | Formatting hygiene (auto-fixed) |
-| `check-json`, `check-yaml`, `check-toml` | Config file syntax |
-| `check-merge-conflict`, `check-added-large-files` (max 5 MB), `forbid-new-submodules` | Repo hygiene |
+Modes are combinable (e.g. `--prepare --run v1 --prompts`). Binaries are
+resolved strictly inside the sandbox npm prefix — a non-prepared sandbox fails
+fast instead of silently testing the host installation.
 
-**Security policy:** any secret found **blocks the commit** (fail-fast, no `--no-verify` exceptions). If a secret is flagged, **rotate it immediately** — do not "fix" the scan, do not force the commit.
+This validates the prepared isolated sandbox only. A PASS is not proof of
+support for every real host or for host configurations that were not exercised.
 
-**Update hooks:** `npm run hooks:update` (runs `pre-commit autoupdate`).
+Env overrides:
 
----
-
-## FAQ
-
-**How much does this cost?**
-You need an existing subscription for your AI coding editor (OpenCode). Pantheon itself is free and open-source (MIT).
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
+| `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | npm spec providing the `opencode` binary |
+| `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | npm spec providing the `opencode2` binary |
+| `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
+| `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |
 
-**Can I use this outside OpenCode?**
-No — Pantheon v1.0 is OpenCode-only. It uses OpenCode's native agent system, permission blocks, and MCP integration.
+Exit codes: `0` no real failures · `1` real failure (see `prompts-report.md`
+in the sandbox root) · `2` usage error · `3` sandbox not prepared.
 
-**How are platform configs synced?**
-Edit `src/agents/*.agent.md` (the canonical format), then run the sync script to update platform copies.
+### Intentional memory MCP divergence
 
-**Can I override Themis's code review?**
-You can proceed past the review gate even if Themis flags issues — except test coverage.
-Below 80% coverage is a hard block by design.
+`scripts/memory_mcp_server.py` and `src/mcp/memory_mcp_server.py` are
+intentionally different. The standalone `scripts/` copy keeps the lightweight
+`memory_*` contract; the installed `src/mcp/` copy additionally exposes the
+optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
+The other shared MCP copies remain identical. Do not overwrite one memory copy
+with the other.
 
-**How long does a typical feature take?**
-Simple endpoints: 2–4 hours. Full features (backend + frontend + DB): 6–8 hours. Large
-systems: 20–30 hours across multiple sprint sessions.
+### Task-result guard
 
-**What happens if my editor session is interrupted?**
-Open phases pause. The memory bank captures the last committed state. Resume by
-invoking `@mnemosyne Recall` to retrieve the previous session context.
+A `task-result-guard` intercepts calls to the native `task()` tool where the
+child session returns an empty or missing result. Instead of surfacing a silent
+`completed` with no payload (which confuses the orchestrator), the guard now
+raises an explicit error. This catches the common free-tier failure mode where a
+child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
+and returns nothing. For large payloads, prefer `pantheon_delegate` over native
+`task()` — the delegation layer has better timeout and error handling.
 
----
 
-## Inspiration & Ecosystem
+## Documentation
 
-Pantheon draws from the broader multi-agent landscape while diverging in key ways:
+- [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)
+- [Architecture](docs/ARCHITECTURE.md) · [MCP tools](docs/mcp-tools.md)
+- [Platforms](docs/PLATFORMS.md) · [Upgrading](docs/UPGRADING.md)
+- [Agent reference](docs/agents/README.md) · [Skills reference](src/skills/README.md)
+- [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
 
-| Framework | Pattern | Key Difference |
-|---|---|---|
-| **AutoGen** (Microsoft) | Event-driven conversations | Research-grade, Python SDK; Pantheon is config-only |
-| **CrewAI** | Role-based crews | Visual editor, self-hosted; Pantheon lives inside your editor |
-| **LangGraph** | Stateful actor graphs | Code-first graph DSL; Pantheon uses markdown + YAML config |
-| **MetaGPT** | Software company roles | Simulates a company; Pantheon delegates to you at every gate |
-| **OpenAI Swarm** | Lightweight handoffs | Sequential only; Pantheon supports parallel subagents |
+## Contribute
 
-### Key design decisions
+Ideas, bug reports, documentation improvements, and code contributions are
+welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
+or pull request.
 
-- **Context isolation via subagents** — Apollo runs in isolated context; only findings return
-- **Parallel execution** — Independent scopes execute simultaneously
-- **Tool minimization** — Each agent has the smallest necessary tool surface
-- **Human approval gates** — No auto-merging, no phantom commits
-- **Model-role alignment** — Fast models for discovery, powerful models for reasoning
+## Citation and DOI
 
----
+Pantheon is released under the [MIT License](LICENSE). For the historical
+published v1.4.3 record only, use the [Zenodo DOI](https://doi.org/10.5281/zenodo.22306637);
+it is not the current operational version. Citation metadata is also available
+in [CITATION.cff](CITATION.cff).
 
-## References
-
-| Resource | Purpose |
-|---|---|
-| [AGENTS.md](AGENTS.md) | Full agent reference — behavior, tools, constraints |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | How to extend the framework |
-| [CHANGELOG.md](CHANGELOG.md) | Release history |
-| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Installation guide |
-| [docs/platforms/opencode.md](docs/platforms/opencode.md) | OpenCode setup guide |
-| [docs/agents/README.md](docs/agents/README.md) | Agent directory |
-| [src/skills/README.md](src/skills/README.md) | Skill directory |
-| [docs/mcp-tools.md](docs/mcp-tools.md) | Canonical MCP tool registry |
-| [docs/mcp-user-guide.md](docs/mcp-user-guide.md) | Adding custom MCP servers |
-| [docs/mcp-recommendations.md](docs/mcp-recommendations.md) | Recommended MCP servers per project type |
-| [scripts/hooks/](scripts/hooks/) | Agent lifecycle hooks |
+Canonical repository: <https://github.com/ils15/pantheon-opencode>
 
 ---
 
-**License:** MIT
-**Architecture Pattern:** Conductor-Delegate
-**Mythology:** Greek (Zeus, Athena, Apollo, Hermes, Aphrodite, Talos, Themis, Mnemosyne, Gaia, Hephaestus, Nyx, Prometheus, Demeter, Iris)
+[Leia em português (Brasil)](README.pt-BR.md)