Steffen025 · Steffen025 · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -302,6 +302,105 @@ When the Algorithm says "subagent results are lost after compaction":
 
 ---
 
+## Code Navigation (LSP Integration)
+
+OpenCode has 35+ Language Server Protocol (LSP) servers built-in. When enabled, they provide **type-aware code navigation** that goes beyond simple text matching.
+
+### Available LSP Tools
+
+| Tool | What It Does | When to Use |
+|------|-------------|-------------|
+| `goToDefinition` | Jump to symbol definition (type-aware, follows imports) | Find where a function/type is defined |
+| `findReferences` | All usages of a function (semantic, not text-match) | Understand impact before refactoring |
+| `hover` | Show type info and docs for a symbol | Quickly inspect unfamiliar APIs |
+| `callHierarchy` | Incoming/outgoing call chains | Trace execution paths |
+
+### LSP vs. Grep — When to Use Which
+
+| Use Case | LSP | Grep |
+|----------|-----|------|
+| Find all callers of `myFunction()` | ✅ `findReferences` — semantic, exact | ⚠️ Misses renamed imports, aliases |
+| Jump to type definition across files | ✅ `goToDefinition` — follows imports | ❌ Can't follow re-exports |
+| Check TypeScript type of a variable | ✅ `hover` — live type info | ❌ Not possible |
+| Find all files containing "TODO" | ❌ LSP can't do text search | ✅ Grep is correct tool |
+| Find all uses of a string literal | ❌ LSP is symbol-only | ✅ Grep is correct tool |
+| Quick pattern match in one file | ❌ Overhead not worth it | ✅ Grep is faster |
+
+**Rule of thumb:** Use LSP for **symbols** (functions, types, variables). Use Grep for **text** (strings, comments, patterns).
+
+### Activation
+
+LSP tools are **experimental** and must be explicitly enabled:
+
+```bash
+# Enable LSP tools for the current session
+export OPENCODE_EXPERIMENTAL_LSP_TOOL=true
+opencode
+```
+
+Or add to your shell profile for permanent activation:
+
+```bash
+echo 'export OPENCODE_EXPERIMENTAL_LSP_TOOL=true' >> ~/.zshrc
+```
+
+> [!NOTE]
+> LSP tools are only available when `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` is set. Without this flag, the tools are not registered and will not appear in the tool list.
+
+---
+
+## Safe Experiments (Session Fork)
+
+> [!NOTE]
+> Plan Mode is **not available** in OpenCode. Session Fork is the native equivalent — a checkpoint system for safe experimentation.
+
+OpenCode's Session Fork creates an **exact copy** of the current session up to a specific message. The original session is untouched. If the experiment fails, discard the fork and return to the original.
+
+### When to Fork
+
+| Situation | Action |
+|-----------|--------|
+| About to do a risky refactoring | Fork first, then refactor in the fork |
+| Exploring multiple solution approaches | Fork once per approach, compare results |
+| About to run destructive operations (delete, overwrite) | Fork → verify in fork → apply to original |
+| Algorithm needs to "try something" without commitment | Fork, try, decide |
+| Pre-BUILD checkpoint in the PAI Algorithm | Fork at end of PLAN phase |
+
+### API Reference
+
+```http
+POST /session/{sessionID}/fork
+Content-Type: application/json
+
+{
+  "messageID": "msg_..."
+}
+```
+
+**Response:** A new session ID pointing to an exact copy of the session at the specified message.
+
+**How to get the current messageID:** Available via the OpenCode Session API (same endpoint used by `session_registry`).
+
+### Fork Workflow
+
+```text
+PLAN phase complete → identify last messageID
+                    → POST /session/{id}/fork
+                    → get forked_session_id
+                    → work in forked session (BUILD / EXECUTE)
+                    → if success: apply changes to original
+                    → if failure: discard fork, original is safe
+```
+
+### Key Properties
+
+- **Atomic:** Fork creates a complete snapshot — no partial state
+- **Non-destructive:** Original session is never modified by fork operations
+- **Persistent:** Forked sessions survive restarts (stored in OpenCode SQLite)
+- **Discardable:** Failed experiments leave no traces in the original session
+
+---
+
 ## Quick Reference
 
 ### Commands

diff --git a/PAI-Install/engine/steps-fresh.ts b/PAI-Install/engine/steps-fresh.ts
@@ -265,6 +265,10 @@ export async function stepInstallPAI(
 	let envContent = `# PAI-OpenCode Environment Variables
 # Generated by installer - DO NOT COMMIT THIS FILE
 ${providerEnvVar}=${state.collected.apiKey || ""}
+
+# Optional: Enable experimental LSP code navigation tools
+# Uncomment to activate goToDefinition, findReferences, hover, callHierarchy
+# OPENCODE_EXPERIMENTAL_LSP_TOOL=true
 `;
 
 	if (voiceEnvVar && state.collected.voiceApiKey) {

diff --git a/docs/epic/TODO-v3.0.md b/docs/epic/TODO-v3.0.md
@@ -9,7 +9,7 @@ date: 2026-03-10
 
 > [!NOTE]
 > **Basis:** Gap-Analysis 2026-03-06 | Reference: `GAP-ANALYSIS-v3.0.md` | Plan: `OPTIMIZED-PR-PLAN.md`
-> **Updated:** 2026-03-10 — WP-A through WP-D merged. WP-E in review. WP-N1..N5 defined for native transformation.
+> **Updated:** 2026-03-11 — WP-N1 through WP-N4 complete (PR #50–#53). WP-N5 next.
 
 ---
 
@@ -29,8 +29,8 @@ WP-E  ████████████ 100% ✅  ← PR #48 merged
 ──────────────────────────────────────
 WP-N1 ████████████ 100% ✅  ← Session Registry complete, PR #50
 WP-N2 ████████████ 100% ✅  ← Compaction Intelligence complete, PR #51
-WP-N3 ██████████░░  90% 🔄  ← Algorithm Awareness implemented, PR #52
-WP-N4 ░░░░░░░░░░░░   0% ⏳  ← LSP + Fork Documentation (next)
+WP-N3 ████████████ 100% ✅  ← Algorithm Awareness complete, PR #52+#53
+WP-N4 ████████████ 100% ✅  ← LSP + Fork Documentation complete, PR #53
 WP-N5 ░░░░░░░░░░░░   0% ⏳  ← Plan Update
 ```
 
@@ -380,10 +380,10 @@ graph TD
 
 ---
 
-### WP-N2: Compaction Intelligence — ✅ COMPLETE (PR #51)
+### WP-N2: Compaction Intelligence — ✅ Complete (PR #51)
 **Branch:** `feature/wp-n2-compaction-intelligence`
 **Spec:** ADR-015
-**Status:** Implementation complete, awaiting PR review/merge
+**Status:** Merged into `dev`
 
 - [x] Implement `experimental.session.compacting` hook in `pai-unified.ts`
 - [x] Create `plugins/handlers/compaction-intelligence.ts` with context builders
@@ -392,10 +392,10 @@ graph TD
 
 ---
 
-### WP-N3: Algorithm Awareness — ⏳ Implemented (PR #52)
+### WP-N3: Algorithm Awareness — ✅ Complete (PR #52+#53)
 **Branch:** `feature/wp-n3-algorithm-awareness`
 **Spec:** ADR-013
-**Status:** Implementation complete, awaiting PR review/merge
+**Status:** Merged into `dev`
 
 - [x] Update AGENTS.md — Session API section (already complete from WP-N1/N2)
 - [x] Update Algorithm SKILL.md — Post-Compaction recovery pattern with session tools
@@ -404,14 +404,15 @@ graph TD
 
 ---
 
-### WP-N4: LSP + Fork Documentation — ⏳ Planned
+### WP-N4: LSP + Fork Documentation — ✅ Complete (PR #53)
 **Branch:** `feature/wp-n4-lsp-fork`
 **Spec:** ADR-014 + ADR-016
 
-- [ ] Document `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`
-- [ ] Add LSP examples to AGENTS.md
-- [ ] Document Session Fork API for safe experiments
-- [ ] Create ADR-014 (LSP) + ADR-016 (Fork)
+- [x] Document `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`
+- [x] Add LSP section to AGENTS.md (LSP vs Grep table, activation)
+- [x] Document Session Fork API for safe experiments
+- [x] Add Fork section to AGENTS.md (use-cases, API reference, workflow)
+- [x] Installer legt auskommentierten `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` Eintrag in `.env` an — Anwender müssen ihn manuell aktivieren (opt-in)
 
 ---
 
@@ -442,5 +443,5 @@ graph TD
 ---
 
 *Created: 2026-03-06*
-*Updated: 2026-03-11 — WP-N1 complete; WP-N2..N6 sequential execution defined; WP-N6 System Awareness added*
+*Updated: 2026-03-11 — WP-N1 through WP-N4 complete (PR #50–#53); WP-N5 next; WP-N6 System Awareness defined*
 *Basis: GAP-ANALYSIS-v3.0.md + EPIC-v3.0-Synthesis-Architecture.md + EPIC-v3.0-OpenCode-Native.md*