feat(wp-n6): System Self-Awareness — OpenCodeSystem skill, 4 architecture docs, ADR-017

.opencode/.env.example

@@ -9,6 +9,12 @@ DA=YourAIName
 TIME_ZONE=Europe/Berlin
 PAI_DIR=/path/to/your/.opencode
 
+# ============================================================================
+# OPENCODE EXPERIMENTAL FEATURES
+# ============================================================================
+# Opt-in: set to true to enable LSP-based code navigation (experimental)
+OPENCODE_EXPERIMENTAL_LSP_TOOL=false
+
 # ============================================================================
 # VOICE SERVER CONFIGURATION (Optional)
 # ============================================================================

.opencode/skills/OpenCodeSystem/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: OpenCodeSystem
+description: PAI-OpenCode system self-awareness. USE WHEN asking about tools, config, model routing, plugin handlers, MCP servers, troubleshooting, or operating environment.
+---
+
+## Customization
+
+**Before executing, check for user customizations at:**
+`~/.opencode/skills/PAI/USER/SKILLCUSTOMIZATIONS/OpenCodeSystem/`
+
+If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
+
+# OpenCodeSystem — System Self-Awareness
+
+System self-awareness for PAI-OpenCode. Enables the Algorithm to answer questions about its own operating environment without asking the user or hallucinating.
+
+## Visibility
+
+This skill runs in the foreground. All lookups and diagnostic output should be visible to maintain transparency.
+
+---
+
+## MANDATORY — Quick Reference
+
+| Question | Answer Location |
+|----------|----------------|
+| Directory layout + handler map | `docs/architecture/SystemArchitecture.md` |
+| All available tools (native + custom + agents) | `docs/architecture/ToolReference.md` |
+| Model routing, opencode.json, settings.json | `docs/architecture/Configuration.md` |
+| Something not working? | `docs/architecture/Troubleshooting.md` |
+| Why was a decision made? | `docs/architecture/adr/README.md` → find relevant ADR |
+
+---
+
+## MANDATORY — Key Facts (Inline — No File Read Needed)
+
+### Runtime Identity
+- **Platform:** OpenCode (NOT Claude Code — never use `~/.claude/`)
+- **Correct path:** `~/.opencode/`
+- **Project config:** `opencode.json` (root) + `settings.json` (~/.opencode/)
+- **Plugin entry:** `.opencode/plugins/pai-unified.ts`
+
+### Custom Tools Always Available
+| Tool | Purpose |
+|------|---------|
+| `session_registry` | List recent sessions for CONTEXT RECOVERY |
+| `session_results` | Get detailed results for a specific session ID |
+
+### Model Tiers
+- `quick` → fast, cheap (exploration, simple tasks)
+- `standard` → balanced (default for most agents)
+- `advanced` → complex reasoning (Algorithm agent)
+- Actual model names resolved from `opencode.json` — never hardcode
+
+### The 2-Second Rule
+If Grep, Glob, or Read can answer in <2 seconds → use them directly. Never spawn an agent for what a direct tool call can do instantly.
+
+### Critical Path Rules
+```
+bash workdir parameter → ALWAYS (never cd &&)
+imports             → ALWAYS include .ts extension
+package manager     → ALWAYS bun (never npm/yarn/pnpm)
+memory paths        → ALWAYS ~/.opencode/ (never ~/.claude/)
+```
+
+---
+
+## MANDATORY — When Something Doesn't Work
+
+Walk `docs/architecture/Troubleshooting.md` top-to-bottom. The checklist covers:
+1. Plugin not loading
+2. Custom tools missing
+3. Post-compaction recovery
+4. Model routing issues
+5. Path errors
+6. Skill not triggering
+7. Runtime/bun errors
+8. Agent spawn issues
+
+---
+
+## OPTIONAL — Architecture in 30 Seconds
+
+```text
+opencode.json          → model routing, permissions, agent definitions
+pai-unified.ts         → single plugin, all event hooks registered
+handlers/              → 20+ modular handlers (session, security, capture, etc.)
+AGENTS.md              → Algorithm's runtime operating instructions
+skills/skill-index.json → skill discovery registry for CAPABILITY AUDIT
+~/.opencode/MEMORY/    → PRDs, session data, reflections
+```
+
+Full details: `docs/architecture/SystemArchitecture.md`
+
+---
+
+## OPTIONAL — USE WHEN Triggers
+
+- "What tools do I have?"
+- "What custom tools are available?"
+- "How is model routing configured?"
+- "What MCP servers are connected?"
+- "Why isn't the plugin firing?"
+- "What's the difference between opencode.json and settings.json?"
+- "How do I troubleshoot X not working?"
+- "What agents can I spawn?"
+- "Where is the memory stored?"
+- "What hooks does the plugin register?"
+- Any question about the operating environment, directory structure, or system configuration
+
+---
+
+## Tools
+
+_No dedicated CLI tools for this skill. Reference documents are read directly via `read` tool._
+
+## Workflows
+
+_No workflow files. This skill operates by directing the Algorithm to the correct reference document._
+
+---
+
+## Related Skills
+
+- **PAI** — Algorithm core, ISC creation, verification
+- **System** — System maintenance, integrity check, documentation

.opencode/skills/skill-index.json

@@ -1,11 +1,11 @@
 {
-  "generated": "2026-03-08T23:47:52.369Z",
-  "totalSkills": 52,
+  "generated": "2026-03-12T07:24:22.833Z",
+  "totalSkills": 53,
   "categories": 7,
-  "flatSkills": 17,
+  "flatSkills": 18,
   "hierarchicalSkills": 35,
   "alwaysLoadedCount": 2,
-  "deferredCount": 50,
+  "deferredCount": 51,
   "skills": {
     "agents": {
       "name": "Agents",
@@ -533,6 +533,29 @@
       "tier": "deferred",
       "isHierarchical": false
     },
+    "opencodesystem": {
+      "name": "OpenCodeSystem",
+      "path": "OpenCodeSystem/SKILL.md",
+      "category": null,
+      "fullDescription": "PAI-OpenCode system self-awareness. USE WHEN asking about tools, config, model routing, plugin handlers, MCP servers, troubleshooting, or operating environment.",
+      "triggers": [
+        "asking",
+        "tools",
+        "config",
+        "model",
+        "routing",
+        "plugin",
+        "handlers",
+        "mcp",
+        "servers",
+        "troubleshooting",
+        "operating",
+        "environment"
+      ],
+      "workflows": [],
+      "tier": "deferred",
+      "isHierarchical": false
+    },
     "osint": {
       "name": "OSINT",
       "path": "Investigation/OSINT/SKILL.md",
@@ -1039,14 +1062,19 @@
       "name": "USMetrics",
       "path": "USMetrics/SKILL.md",
       "category": null,
-      "fullDescription": "US metrics and data tracking. USE WHEN US metrics, American data, statistics, demographics, tracking.",
+      "fullDescription": "US metrics, economic indicators and data tracking. USE WHEN US metrics, American data, statistics, demographics, GDP, inflation, unemployment, economic metrics, gas prices.",
       "triggers": [
         "metrics",
         "american",
         "data",
         "statistics",
         "demographics",
-        "tracking"
+        "gdp",
+        "inflation",
+        "unemployment",
+        "economic",
+        "gas",
+        "prices"
       ],
       "workflows": [
         "UpdateData",

docs/architecture/Configuration.md

@@ -0,0 +1,191 @@
+---
+title: Configuration Reference
+doc_type: reference
+tags: [architecture, configuration, ADR-017, wp-n6]
+last_updated: 2026-03-12
+---
+
+# Configuration Reference
+
+> [!info] Authoritative Source
+> PAI-OpenCode configuration reference (ADR-017 / WP-N6).
+> **Single Source of Truth for models: `opencode.json`** — no other file should hardcode model names.
+
+---
+
+## Two-File Configuration (ADR-005)
+
+PAI-OpenCode uses two configuration files with distinct responsibilities:
+
+| File | Location | Purpose | Managed By |
+|------|----------|---------|-----------|
+| `opencode.json` | Project root (symlink) | OpenCode runtime: model routing, agents, permissions | Developer / this repo |
+| `settings.json` | `~/.opencode/` | User preferences: PAI behavior, identity, overrides | User's local install |
+
+**Rule:** `opencode.json` is committed to the repo. `settings.json` is user-local and never committed.
+
+---
+
+## Config Switching (Symlink Architecture)
+
+`opencode.json` at project root is a **symlink** pointing to one of multiple config variants:
+
+```text
+opencode.json → opencode.anthropic.json   (Anthropic models — Opus/Sonnet/Haiku)
+             → opencode.zen.json          (Zen/multi-provider models)
+```
+
+Terminal commands switch the active configuration:
+
+| Command | What It Does |
+|---------|-------------|
+| `oc-anthropic` | Switch to Anthropic model config |
+| `oc-zen` | Switch to Zen/multi-provider config |
+| `oc-which` | Show which config variant is currently active |
+
+**Key principle:** The Algorithm and all agents are **unaware** which config variant is active. They only see `opencode.json` and interact with it via the three-tier model system. This means model names change transparently without any code or documentation updates.
+
+---
+
+## opencode.json
+
+Full schema reference: `https://opencode.ai/config.json`
+
+### Top-Level Fields
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "theme": "dark",
+  "model": "<default model>",     // Default model for interactive sessions
+  "snapshot": true,                // Enable session snapshots
+  "username": "User",
+  "permission": { ... },           // Tool permission rules
+  "mode": { ... },                 // Mode-specific system prompts
+  "agent": { ... }                 // Agent model routing (three-tier)
+}
+```
+
+### Three-Tier Model System
+
+Every agent has three model tiers. The Algorithm selects tiers based on task complexity:
+
+| Tier | When | Cost Profile |
+|------|------|-------------|
+| `quick` | Simple tasks, batch operations, data transformation | Cheapest |
+| `standard` | Normal operations (default for most agents) | Balanced |
+| `advanced` | Complex reasoning, architecture decisions | Most expensive |
+
+```json
+"agent": {
+  "Engineer": {
+    "model": "<default>",
+    "model_tiers": {
+      "quick":    { "model": "<fast-cheap-model>" },
+      "standard": { "model": "<balanced-model>" },
+      "advanced": { "model": "<powerful-expensive-model>" }
+    }
+  }
+}
+```
+
+> [!important] Model Names Are NOT Documented Here
+> Actual model names live **exclusively** in `opencode.json`. This prevents documentation drift when models change (e.g., new model release, provider switch, config variant swap). To see current models: `cat opencode.json`.
+
+### Algorithm Delegation Principle
+
+The Algorithm runs on the **most capable and most expensive model** in the system. Because of this cost profile, it should:
+
+1. **Delegate aggressively** — write clear instructions for cheaper agents to execute
+2. **Write instructions, not code** — for anything >100 lines of code or significant documents, spawn an Engineer/Writer agent
+3. **Use `quick` tier agents** for batch operations, simple edits, data transformations
+4. **Reserve `advanced` tier** for genuinely complex reasoning that `standard` cannot handle
+
+The agents doing the actual work use significantly cheaper models. The Algorithm's value is in **orchestration and instruction quality**, not in doing the work itself.
+
+### Permissions
+
+```json
+"permission": {
+  "*": "allow",          // Allow all tools by default
+  "websearch": "allow",  // Web search: no prompt
+  "codesearch": "allow", // Code search: no prompt
+  "webfetch": "allow",   // URL fetch: no prompt
+  "doom_loop": "ask",    // Recursive agent calls: requires confirmation
+  "external_directory": "ask"  // Files outside project: requires confirmation
+}
+```
+
+### Mode Prompts
+
+```json
+"mode": {
+  "build": { "prompt": "You are a Personal AI assistant powered by PAI-OpenCode infrastructure." },
+  "plan":  { "prompt": "You are a Personal AI assistant powered by PAI-OpenCode infrastructure." }
+}
+```
+
+---
+
+## settings.json
+
+Located at `~/.opencode/settings.json`. User-local, never committed.
+
+### Common PAI Settings
+
+```json
+{
+  "daidentity": {
+    "name": "Jeremy"         // DA name used in voice output
+  },
+  "principal": {
+    "name": "Steffen",       // User name
+    "timezone": "Europe/Berlin"
+  }
+}
+```
+
+See `AGENTS.md` for the full list of settings.json fields the PAI Algorithm reads.
+
+---
+
+## AGENTS.md
+
+Located at project root (`AGENTS.md`). **Not a config file** — it is the Algorithm's runtime instructions document. Loaded automatically by OpenCode as project-level agent instructions.
+
+Key sections:
+- `## Build, Test & Lint Commands` — commands the Algorithm uses
+- `## Technology Stack` — stack preferences and rules
+- `## Session Recovery` (added WP-N3) — how to use `session_registry` + `session_results`
+- `## LSP Integration` (added WP-N4) — LSP opt-in instructions
+- `## Session Fork Pattern` (added WP-N4) — experiment isolation pattern
+
+---
+
+## Environment Variables
+
+Set in `.env` (auto-loaded by Bun, never committed). See `.opencode/.env.example` for template.
+
+| Variable | Purpose | Default | Where Used |
+|----------|---------|---------|-----------|
+| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | Enable LSP tool integration | `true` | OpenCode runtime, documented in ADR-014 |
+| `PAI_LOG_LEVEL` | Plugin logging verbosity | — | `pai-unified.ts` handlers |
+| `DA` | AI assistant name | — | Voice server, prompt templates |
+| `TIME_ZONE` | User timezone | — | Timestamp formatting |
+| `PAI_DIR` | Path to `.opencode/` directory | — | Skill and memory system |
+
+---
+
+## Plugin Loading
+
+> [!warning] Only `pai-unified.ts` Should Load at Startup
+> OpenCode discovers `.ts` files in `.opencode/plugins/`. The **only** file that should be loaded as a plugin is `pai-unified.ts`. All handler modules in `handlers/` are imported by `pai-unified.ts` internally — they are NOT standalone plugins.
+>
+> TypeScript files in `skills/*/Tools/` are CLI tools meant to be run on-demand with `bun run <file>`, NOT loaded as plugins. If OpenCode tries to load ALL `.ts` files in the directory tree, this creates errors and performance issues.
+
+Plugin behavior is configured via:
+1. `settings.json` values (read at runtime)
+2. Hard-coded constants in handler files
+3. Environment variables
+
+There is no separate plugin config file — all tuning is done in the handler source or environment.