pantheon-opencode 1.0.0 → 1.0.6

package/docs/mcp-recommendations.md

@@ -1,439 +0,0 @@
-# MCP Server Recommendations for Pantheon
-
-MCP (Model Context Protocol) servers extend Pantheon agents with external capabilities — library documentation lookup, web search, content fetching, browser automation, and **persistent memory**.
-
-This document covers the **6 built-in + external MCPs** available to Pantheon agents.
-
----
-
-## Our MCPs at a Glance
-
-| MCP | What it does | Who uses it | Setup |
-|-----|-------------|-------------|-------|
-| **context7** | Fetches up-to-date, version-specific library documentation | 11 agents (zeus, athena, apollo, hermes, aphrodite, demeter, themis, hephaestus, nyx, talos, gaia) | `npx -y @upstash/context7-mcp` — free, no API key needed |
-| ~~exa~~ | *Removed in v3.15.0* | — | Use `websearch` tool instead |
-| **playwright** | Browser automation — screenshots, accessibility snapshots | aphrodite, themis, hermes | `npx -y @playwright/mcp@latest` — free, requires Playwright browsers installed |
-| **pantheon-resources** | Pantheon framework resources — agents, skills, routing, deepwork, memory bank | all agents | `python scripts/mcp_resources_server.py` — built-in, no setup needed |
-| **pantheon-code-mode** | Confined orchestration script execution via MCP | zeus, prometheus, hermes, talos | `python scripts/code_mode_server.py` — built-in, scripts in `.pantheon/code-mode/` |
-| **pantheon-memory** | Persistent memory with semantic search, recall, knowledge graph, compression, export | all agents | `python scripts/memory_mcp_server.py` — built-in, requires `chromadb` + `sentence-transformers` |
-| **pantheon-persistence** | KV store with FTS5 search, TTL, namespace isolation | all agents | `python scripts/mcp_persistence_server.py` — built-in, zero deps |
-
----
-
-## Quick Setup
-
-### context7 (Library Documentation)
-
-**No API key required.** Zero-config after install.
-
-```bash
-npx -y @upstash/context7-mcp
-```
-
-**What it provides:**
-- `context7_resolve-library-id` — Resolves a package name to a Context7 library ID
-- `context7_query-docs` — Queries library documentation with a specific question
-
-**Used by:** Agents needing current API docs — Hermes (FastAPI), Aphrodite (React), Demeter (SQLAlchemy), Hephaestus (LangChain), etc.
-
----
-
-> **Note:** Exa MCP was removed in v3.15.0. Use the `websearch` tool instead.
-
----
-
-### playwright (Browser Automation)
-
-Enables browser-level interaction: navigation, screenshot capture, accessibility tree snapshots.
-
-```bash
-npx -y @playwright/mcp@latest
-# Then install browsers:
-npx playwright install chromium
-```
-
-**What it provides:**
-- `browser/screenshotPage` — Full-page screenshot capture
-- `browser/snapshot` — Accessibility/structured content tree
-- Navigation, click, type, and other browser interaction tools
-
-**Used by:** Aphrodite (visual review pipeline), Themis (visual regression checking).
-
----
-
-### pantheon-memory (Persistent Memory)
-
-Built-in Python MCP server providing multi-strategy memory using ChromaDB + sentence-transformers.
-
-```bash
-# In the Pantheon project directory
-python scripts/memory_mcp_server.py
-```
-
-Requires Python packages:
-```bash
-pip install chromadb sentence-transformers fastmcp
-```
-
-**What it provides (14 tools + 2 resources):**
-
-| Category | Tools |
-|----------|-------|
-| **Store & Recall** | `memory_store`, `memory_recall`, `memory_search` |
-| **Knowledge Graph** | `memory_link`, `memory_traverse` |
-| **Compression** | `memory_compress`, `memory_expand`, `memory_consolidate` |
-| **Management** | `memory_delete`, `memory_update`, `memory_verify`, `memory_cleanup`, `memory_sessions`, `memory_export` |
-| **Resources** | `pantheon://memory/sessions`, `pantheon://memory/status` |
-
-**Key features:**
-- **Fusion scoring**: dense vector similarity + 30-day freshness decay + importance boost
-- **Knowledge graph**: bidirectional links with relation labels (references, causes, supersedes)
-- **Deterministic compression**: DCP-style range compression (not LLM-based)
-- **Claim verification**: Shokunin-style freshness validation
-- **Markdown export**: formatted output for memory-bank archival
-
-**Storage:** `~/.pantheon/memory/chroma.sqlite3` (SQLite-backed ChromaDB)
-
-**Used by:** All 14 agents for persistent memory across sessions. Mnemosyne has the deepest integration (export, consolidate, compress).
-
----
-
-### pantheon-persistence (Key-Value Store)
-
-Built-in Python MCP server providing a lightweight KV store with SQLite + FTS5, TTL, and namespace isolation. Zero external dependencies.
-
-```bash
-python scripts/mcp_persistence_server.py
-```
-
-**No external dependencies required.** Uses stdlib only (sqlite3).
-
-**What it provides (6 tools):**
-
-| Tool | Signature | Description |
-|------|-----------|-------------|
-| `kv_store` | `(namespace, key, value, ttl?, scope?)` | Store a key-value pair with optional TTL |
-| `kv_get` | `(namespace, key, scope?)` | Retrieve value by namespace+key |
-| `kv_delete` | `(namespace, key, scope?)` | Remove an entry |
-| `kv_list` | `(namespace, prefix?, scope?, limit?)` | List keys with prefix filter |
-| `kv_search` | `(query, namespace?, scope?, limit?)` | FTS5 full-text search with BM25 ranking |
-| `purge_expired` | `(scope?, dry_run?)` | Remove expired TTL entries with deletelog |
-
-**Key features:**
-- **FTS5 full-text search**: BM25-ranked searches across keys and values
-- **TTL per entry**: automatic expiration filtering at read time
-- **Namespace isolation**: logical grouping with prefix listing
-- **Dual scope**: project-scoped (`.pantheon/persistence/project.db`) + global (`~/.config/opencode/persistence/global.db`)
-- **Deletelog**: audit trail for expired entry purges, rotates at 1MB (keeps last 3)
-- **Soft delete**: TTL purge marks entries as deleted instead of immediate removal
-
-**Comparison with pantheon-memory:**
-
-| Aspect | persistence | memory |
-|--------|-------------|--------|
-| Engine | SQLite KV | ChromaDB vector |
-| Search | FTS5 (keyword) | cosine similarity (semantic) |
-| TTL | ✅ per entry | ❌ |
-| Dependencies | zero (stdlib) | chromadb + sentence-transformers |
-| Startup | <0.5s | 3-8s |
-| Best for | Cache, session state, ephemeral data | Long-term semantic memory |
-
-**Used by:** All agents for cross-agent caching, session state, and ephemeral data.
-
----
-
-## Browser MCPs
-
-For browser automation, Pantheon supports a range of MCPs from full Chrome (Playwright) to ultra-lightweight engines (Lightpanda). Pick based on your use case.
-
-| MCP | Engine | Tools | RAM | Speed vs Playwright | Best For |
-|-----|--------|-------|-----|---------------------|----------|
-| **Playwright MCP** (Microsoft) | Full Chrome | 25+ | ~400MB | 1x (baseline) | SPAs, debugging, screenshot visual review |
-| **Lightpanda** (native MCP) | Zig (zero fork) | 11 | ~50MB | **11x faster** | Scraping, docs, simple navigation |
-| **Pandabridge** (community) | Lightpanda + CDP | 23 | ~60MB | **9x faster** | Scraping + compact agent interaction |
-| **Agent-Browser** (community) | Lightpanda + Chromium fallback | 55 | 50-300MB | Auto-fallback | Production: combines speed + reliability |
-
-### Decision Guide
-
-| If you need... | Pick |
-|----------------|------|
-| Screenshots, visual review, SPA interaction | **Playwright** (~400MB, 25+ tools) |
-| Fast scraping, docs, simple nav (lightweight) | **Lightpanda** (~50MB, 11 tools) |
-| Scraping with richer interaction tools | **Pandabridge** (~60MB, 23 tools) |
-| Production dual-engine (speed + fallback) | **Agent-Browser** (50-300MB, 55 tools) |
-
-**Pantheon default:** Playwright MCP — required by Aphrodite's visual review pipeline and Themis for visual regression checking.
-
----
-
-## Documentation & Knowledge MCPs
-
-For library docs, web search, and content extraction — these MCPs overlap in capability but differ in focus:
-
-| MCP | Benchmark Score | Setup | Best For |
-|-----|----------------|-------|----------|
-| **context7** | **🥇 89** | `npx -y @upstash/context7-mcp` — free, no API key | Library docs, version-pinned APIs |
-| **mcp-fetch** (official) | **🥈 86** | Zero config (built-in to Claude) | Simple webpage fetching |
-| ~~Exa Search~~ | *Removed in v3.15.0* | — | Use `websearch` tool instead |
-| **Firecrawl** | — | API key required | Web-to-markdown, clean content extraction |
-
-### Which One to Use
-
-| Task | Use |
-|------|-----|
-| "How do I use FastAPI's `Annotated` dependency injection?" | **context7** — version-pinned library docs |
-| "Find recent blog posts about RAG evaluation techniques" | **websearch** — semantic web search |
-| "Read this specific article and summarize it" | **mcp-fetch** — zero config, just works |
-| "Extract clean markdown from this messy product page" | **Firecrawl** — intelligent content cleaning |
-
-**Pantheon default:** context7 for library documentation (11 agents, no API key). Exa was removed in v3.15.0 — use the built-in `websearch` tool instead.
-
----
-
-## Infrastructure & DevOps MCPs
-
-Connect Pantheon agents directly to your infrastructure — databases, CI/CD, cloud services, and monitoring.
-
-| MCP | Official? | Setup | Best For |
-|-----|-----------|-------|----------|
-| **GitHub MCP** | ✅ Anthropic (official) | GitHub token | PRs, issues, code search, Actions management |
-| **Postgres MCP** | ✅ Anthropic (official) | DB credentials | Direct database queries (read-only mode) |
-| **Supabase MCP** | ✅ Supabase | API key | Full Supabase stack: DB, auth, storage |
-| **Cloudflare MCP** | ✅ Cloudflare | API token | Workers, KV, D1, R2, DNS |
-| **Sentry MCP** | ✅ Sentry | DSN | Error tracking, traces, performance in-prompt |
-| **Kubernetes MCP** | ❌ Community | kubeconfig | kubectl operations through MCP |
-| **AWS MCP** | ❌ Community | AWS credentials | EC2, S3, Lambda, CloudWatch |
-
-### Reliability Note (Galaxy/Telemetry — May 2026)
-
-A production benchmark across **140 tasks over 14 agents** (May 2026) found:
-
-- **Official Anthropic MCPs** (Filesystem, GitHub, Postgres) — **>85% reliability**
-- **Community MCPs** — **34-68% reliability**
-
-Prefer official servers when available. Community MCPs are useful but budget extra review time.
-
----
-
-## Which MCPs Should You Install?
-
-For most Pantheon setups, start with these **3 core MCPs**:
-
-| Priority | MCP | Why |
-|----------|-----|-----|
-| **1 (required)** | **pantheon-memory** | All agents need persistent memory. Zero external dependencies. |
-| **2 (required)** | **pantheon-resources** | Framework agents, skills, routing — core Pantheon infra. |
-| **3 (recommended)** | **pantheon-persistence** | Lightweight KV for cache, session state, TTL — zero deps, <0.5s startup. |
-| **4 (recommended)** | **context7** | 11 agents benefit from library docs. Free, no API key. **Highest benchmark score (89).** |
-
-Then add based on your workflow:
-
-| If you... | Add |
-|-----------|-----|
-| Do frontend visual review | **Playwright MCP** (required by Aphrodite review pipeline) |
-| Need web research (Apollo) | **websearch** tool (built-in) |
-| Run infrastructure tasks | **GitHub MCP** + **Cloudflare MCP** |
-| Hit databases directly | **Postgres MCP** (read-only) or **Supabase MCP** |
-| Need fast browser scraping | **Lightpanda** or **Pandabridge** (11-23x RAM savings) |
-
----
-
-## Per-Agent Internet Access
-
-Not all agents need continuous internet. Here's the breakdown:
-
-| Agent | Internet Needed? | Why |
-|-------|----------------|------|
-| **gaia** | ✅ **Yes** | Satellite imagery (Copernicus, USGS), remote sensing data APIs |
-| **apollo** | ✅ **Yes** | Web search, external research, codebase discovery |
-| **hermes** | ⚠️ Optional | Library docs via context7 (cached), not continuous |
-| **aphrodite** | ⚠️ Optional | Library docs via context7, CDN resource fetching |
-| **demeter** | ⚠️ Optional | Library docs via context7, migration references |
-| **zeus** | ⚠️ Optional | Orchestration patterns, reference lookups |
-| **athena** | ⚠️ Optional | Planning references, architecture patterns |
-| **themis** | ⚠️ Optional | Code review references, security pattern lookups |
-| **prometheus** | ⚠️ Optional | Docker registries, package repositories |
-| **hephaestus** | ⚠️ Optional | AI model docs, research papers |
-| **nyx** | ❌ **Not needed** | All local operations (logs, traces, metrics) |
-| **iris** | ❌ **Not needed** | GitHub operations via GitHub MCP (token-based, not web) |
-| **mnemosyne** | ❌ **Not needed** | Memory bank operations — all local |
-| **talos** | ❌ **Not needed** | Hotfix patches — all local code changes |
-
-**Key insight:** Only **gaia** and **apollo** require continuous internet. The rest work offline with context7 for cached docs.
-
----
-
-## The 3-7 Rule
-
-Every MCP server adds tools to the agent's context window. Beyond 7 servers, tool selection accuracy degrades significantly.
-
-| MCP Count | Tool Selection Accuracy | Notes |
-|-----------|------------------------|-------|
-| 1-3 | Excellent | Zero overhead, fast tool discovery |
-| 4-5 | Good | Manageable, small prompt overhead |
-| 6-7 | Acceptable | Push the limit — works with disciplined scoping |
-| 8+ | **Degraded** | Tool call failures, wrong tool selection, context waste |
-
-### Guidelines
-
-1. **Start with 2-3** — memory + resources + one domain MCP (e.g., context7)
-2. **Never exceed 7** — beyond this, agents start picking the wrong tool
-3. **Scoped per-agent** — not every agent needs every MCP. Use frontmatter binding (see below)
-4. **Review quarterly** — remove unused MCPs, add ones you actually use
-
-Pantheon enforces **max 5 MCPs per agent** via frontmatter constraints (see below).
-
----
-
-## MCP Configuration via Frontmatter
-
-Each agent template includes an `mcpServers` field in its frontmatter that declares which MCP servers the agent can use. This enables per-agent MCP binding with tool scoping.
-
-### Schema
-
-```yaml
-mcpServers:
-  - name: string (required)
-    tools: [string] (required)
-    when: string (required)
-    constraints: object (optional)
-      queryMode: string ("parameterized-only" | "free")
-      readOnly: boolean
-      forbiddenPatterns: [string]
-      forbiddenFlags: [string]
-      requiredFlags: [string]
-      imagePolicy: string ("verified-only" | "any")
-      auditLog: boolean
-```
-
-### Constraints
-- Maximum 5 MCPs per agent
-- `tools` lists the MCP tools the agent can access
-- `when` describes the activation condition
-
-### Example
-
-```yaml
-mcpServers:
-  - name: context7
-    tools:
-      - context7_resolve-library-id
-      - context7_query-docs
-    when: "resolving library documentation"
-  - name: playwright
-    tools:
-      - browser_screenshotPage
-      - browser_snapshot
-    when: "visual verification needed"
-```
-
-### Agent-MCP Mapping
-
-| Agent | MCPs |
-|-------|------|
-| @zeus | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @athena | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @apollo | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @hermes | context7, playwright, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @aphrodite | context7, playwright, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @demeter | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @themis | context7, playwright, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @prometheus | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @hephaestus | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @nyx | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @iris | pantheon-resources, pantheon-memory, pantheon-persistence |
-| @talos | context7, pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-| @gaia | context7, pantheon-resources, pantheon-memory, pantheon-persistence |
-| @mnemosyne | pantheon-resources, pantheon-code-mode, pantheon-memory, pantheon-persistence |
-
----
-
-## MCP Tool Discovery Pattern
-
-When an agent needs external capabilities beyond the codebase:
-
-1. **Check if MCP is available** — ask the user or check config
-2. **Use progressive discovery** — don't load all tool definitions; search for the right tool
-3. **Prefer MCP over webfetch** — MCP tools have typed schemas and structured outputs
-4. **Fall back to webfetch** — if no MCP server is configured for the needed capability
-
-Example (Athena researching a library):
-```
-Need: Current FastAPI documentation
-MCP: context7/get-library-docs → structured, version-specific
-Fallback: web/fetch → unstructured, may be stale
-```
-
----
-
-## Security Notes
-
-- **Never commit secrets** in MCP config files. Use `${VAR}` interpolation for env variables.
-- **Sandbox local MCP servers** when possible ( supports `sandboxEnabled: true`).
-- **Review MCP tool permissions** before enabling. Some servers expose destructive tools.
-- **Playwright** runs headless Chromium locally — ensure it's used in a controlled environment.
-
----
-
-## Security Hardening
-
-See `skill: mcp-security` for complete MCP security rules.
-
-### Constraint Types
-
-| Constraint | Purpose | Example |
-|-----------|---------|----------|
-| `readOnly` | Prevent write operations | `true` for read-only agents |
-| `auditLog` | Require audit comments | `true` for certain operations |
-
-### Enforcement
-
-These constraints are enforced by @themis during code review.
-
----
-
-## 🔧 Troubleshooting
-
-### MCP Not Connecting
-
-| Symptom | Likely Cause | Fix |
-|---------|-------------|-----|
-| "MCP server not found" | Server not installed | Run `npx -y @upstash/context7-mcp` or install via your platform's MCP config |
-| "Tool not available" | Agent template missing mcpServers entry | Verify `agents/*.agent.md` has the MCP in frontmatter |
-| "Authentication failed" | Missing env var | Check provider credentials |
-| "Command not found: npx" | Node.js not installed | Install Node.js 18+ from nodejs.org |
-| "Browser not found" | Playwright browsers not installed | Run `npx playwright install chromium` |
-| "pantheon-memory not connecting" | Missing Python deps | Run `pip install chromadb sentence-transformers fastmcp` |
-| "memory_recall returns empty" | No entries stored | First call `memory_store` to seed the database |
-| "Code-mode script not found" | Wrong directory | Scripts must live in `.pantheon/code-mode/` |
-| "ChromaDB import error" | out-of-date package | Run `pip install --upgrade chromadb` |
-
-### Platform-Specific Issues
-
-**OpenCode:**
-- Config is in `opencode.json` under `mcpServers`
-- Run `opencode mcp list` to see configured servers
-- Run `opencode mcp debug <name>` to test connectivity
-
-** / :**
-- Restart after modifying `opencode.json` or `./mcp.json`
-- Open Command Palette → `MCP: List Servers` to verify connection
-
-**:**
-- Config is in `.mcp.json` (project) or `~/.claude/settings.json` (global)
-- Run `claude mcp list` to verify
-- Project config takes precedence over global
-
-### Verify MCP is Working
-
-```bash
-# OpenCode
-opencode mcp list
-opencode mcp debug context7
-
-# 
-claude mcp list
-
-# 
-# Command Palette → MCP: List Servers
-```

package/docs/mcp-tools.md

@@ -1,156 +0,0 @@
-# MCP Tool Registry
-
-Canonical reference for Pantheon agents. Lists every tool across the 3 native MCP servers, with signatures, descriptions, and which agents use them.
-
-> **Agent tip:** Tool names are platform-dependent. See [Platform Naming Conventions](#platform-naming-conventions) below to map these names to your runtime.
-
----
-
-## Servers
-
-Pantheon provides 4 native MCP servers. See below for full tool registries.
-
-### pantheon-resources (read-only)
-
-Read-only resource server. No tools — read resources directly via `pantheon://` URIs using `read_mcp_resource`.
-
-| Resource URI | Description |
-|---|---|
-| `pantheon://agents` | List all 14 agent definitions (YAML frontmatter) |
-| `pantheon://agents/{name}` | Single agent config by name (case-insensitive) |
-| `pantheon://routing` | Full `routing.yml` — delegation rules, handoff contracts |
-| `pantheon://skills` | List all skills with descriptions |
-| `pantheon://skills/{name}` | Specific skill `SKILL.md` content |
-| `pantheon://deepwork/{slug}` | Deepwork `PLAN.md` |
-| `pantheon://deepwork/{slug}/status` | Deepwork `STATUS.md` (defaults to IN_PROGRESS) |
-| `pantheon://memory-bank/{path}` | Any file under `.pantheon/memory-bank/` (path traversal blocked) |
-| `pantheon://code-mode/scripts` | List all available code-mode scripts |
-| `pantheon://code-mode/scripts/{name}` | View script content by name |
-| `pantheon://memory/sessions` | List all memory sessions with counts and timestamps |
-| `pantheon://memory/status` | Memory server stats: entries, sessions, disk usage |
-
-**Used by:** ALL agents. Common reads: `routing` (zeus, athena), `agents/{name}` (any), `skills/{name}` (implementers), `memory-bank/{path}` (aphrodite, mnemosyne).
-
-**Call pattern:**
-```
-read_mcp_resource(server="pantheon-resources", uri="pantheon://routing")
-```
-
----
-
-### pantheon-memory (persistent storage)
-
-Vector memory with ChromaDB + sentence-transformers. 14 tools for storing, searching, linking, compressing, and managing memories across sessions.
-
-| Tool | Signature | Description | Who uses it |
-|------|-----------|-------------|-------------|
-| `memory_recall` | `(context: str, n_results?: 3)` | Auto-retrieve relevant memories for prompt injection | ALL agents — called at session start |
-| `memory_store` | `(content, category?, agent?, session_id?, importance?: 0.5, links?)` | Persist a fact, decision, or pattern | Implementers: hermes, aphrodite, demeter, prometheus, hephaestus, nyx, mnemosyne, zeus |
-| `memory_search` | `(query: str, n_results?: 5, category_filter?)` | Vector similarity search with freshness decay + importance boost | apollo, themis, mnemosyne |
-| `memory_delete` | `(entry_id: str)` | Permanently delete an entry | mnemosyne only |
-| `memory_update` | `(entry_id, content?, category?, importance?)` | Update an existing entry's content/metadata | mnemosyne only |
-| `memory_export` | `(session_id?, filename?)` | Export memories as formatted markdown | mnemosyne only |
-| `memory_link` | `(from_id, to_id, relation?: "references")` | Create bidirectional relationship between entries | mnemosyne, hephaestus |
-| `memory_traverse` | `(entry_id, max_depth?: 1)` | Walk knowledge graph from entry following links | mnemosyne only |
-| `memory_compress` | `(session_id, max_entries?: 50, compression_ratio?: 0.5)` | Compress oldest entries into summaries (DCP-style) | mnemosyne only |
-| `memory_consolidate` | `(session_id?)` | Merge duplicate/similar entries via cosine similarity | mnemosyne only |
-| `memory_verify` | `(entry_id)` | Validate entry exists and check freshness | mnemosyne only |
-| `memory_sessions` | `(format?: "json")` | List all unique session IDs with counts and timestamps | mnemosyne, nyx |
-| `memory_expand` | `(entry_id)` | Restore a compressed entry back to detailed form | mnemosyne only |
-| `memory_cleanup` | `(session_prefix?: "test-")` | Delete test/old sessions (prefix min 3 chars) | mnemosyne only |
-
-**Call pattern:**
-```
-memory_recall(context="implementing JWT auth in FastAPI")
-memory_store(content="Decided to use refresh token rotation", category="decision", importance=0.9)
-memory_search(query="existing auth patterns", n_results=5)
-```
-
----
-
-### pantheon-persistence (KV store + FTS5 search)
-
-Lightweight key-value store with SQLite FTS5, TTL-based expiration, and namespace isolation. Zero external dependencies (stdlib only).
-
-| Tool | Signature | Description | Who uses it |
-|------|-----------|-------------|-------------|
-| `kv_store` | `(namespace, key, value, ttl?, scope?)` | Store a key-value pair with optional TTL (seconds) | ALL agents — cache, session state |
-| `kv_get` | `(namespace, key, scope?)` | Retrieve a value by namespace + key (auto-filters expired) | ALL agents — read cached data |
-| `kv_delete` | `(namespace, key, scope?)` | Remove a key-value pair | zeus, talos — cleanup tasks |
-| `kv_list` | `(namespace, prefix?, scope?, limit?)` | List keys in a namespace with optional prefix filter | apollo, zeus — discovery |
-| `kv_search` | `(query, namespace?, scope?, limit?)` | FTS5 full-text search with BM25 ranking | mnemosyne, zeus — find across namespaces |
-| `purge_expired` | `(scope?, dry_run?)` | Purge expired TTL entries with deletelog audit trail | mnemosyne, zeus — maintenance |
-
-**Call pattern:**
-```
-kv_store(namespace="cache-apollo", key="api-response", value="...", ttl=3600)
-kv_get(namespace="cache-apollo", key="api-response")
-kv_search(query="auth token refresh")
-purge_expired(scope="project", dry_run=True)
-```
-
----
-
-### pantheon-code-mode (script execution)
-
-Confined automation scripts from `.pantheon/code-mode/`. One tool, 30s timeout, `.sh` and `.py` only.
-
-| Tool | Signature | Description | Who uses it |
-|------|-----------|-------------|-------------|
-| `execute_code_script` | `(script_name: str, args?: list[str])` | Run a script from `.pantheon/code-mode/` and return output | Agents with `bash: allow` (zeus, hermes, aphrodite, demeter, themis, prometheus, hephaestus, talos) |
-
-**NOT available to:** athena, apollo, gaia, iris, nyx, mnemosyne (no bash access).
-
-**Use cases by agent:**
-| Agent | Typical scripts |
-|-------|----------------|
-| zeus | Orchestration sequences |
-| hermes | `pytest`, `ruff check`, `ruff format` |
-| aphrodite | `npm test`, `biome check` |
-| demeter | `alembic upgrade head && pytest` |
-| themis | Lint/quality check scripts during review |
-| prometheus | Docker builds, CI/CD pipeline scripts |
-| talos | Automated hotfix sequences, batch fixes |
-
-**Call pattern:**
-```
-execute_code_script("lint-and-test.sh", args=["backend/"])
-```
-
----
-
-## Platform Naming Conventions
-
-Each platform exposes MCP tools with different naming. The same tool `memory_recall` from server `pantheon-memory` gets different names:
-
-| Platform | Naming Pattern | Example for `memory_recall` |
-|----------|---------------|-----------------------------|
-| **OpenCode** | `{server}_{tool}` | `pantheon-memory_memory_recall` |
-| **** | `mcp__{server}__{tool}` | `mcp__pantheon-memory__memory_recall` |
-| **** | `<use_mcp_tool>` XML | `<use_mcp_tool><server_name>pantheon-memory</server_name><tool_name>memory_recall</tool_name></use_mcp_tool>` |
-| **** | Original name | `memory_recall` (injected via schema) |
-| **** | Original name | `memory_recall` (injected via schema) |
-| **Continue** | Original name | `memory_recall` (injected via schema) |
-| ** ** | Original name | `memory_recall` (injected via schema) |
-
----
-
-## Permission Tiers
-
-| Server | Recommended Tier | Rationale |
-|--------|-----------------|-----------|
-| pantheon-resources | `allow` | Read-only, same trust boundary as repo |
-| pantheon-code-mode | `ask` | Executes scripts — needs user confirmation |
-| pantheon-memory | `allow` | Read/write within agent sandbox, no system access |
-| pantheon-persistence | `allow` | SQLite KV, same trust boundary as repo |
-
----
-
-## Security Notes
-
-- **pantheon-resources** — path traversal protection on `memory-bank/{path}`
-- **pantheon-code-mode** — only `.sh`/`.py` in `.pantheon/code-mode/`, 30s timeout, no `../` escape
-- **pantheon-memory** — all data in `~/.pantheon/memory/chroma.sqlite3`, no system-level access
-- **pantheon-persistence** — SQLite KV in `~/.pantheon/persistence/`, TTL auto-purge, namespace isolation
-
-See `skill: mcp-security` for complete rules.