docs: Simplify README for technical audience

Remove specific file path references while keeping technical architecture
and concepts. Focus on how the system works rather than implementation details.

Author: X

README.md

@@ -9,15 +9,13 @@ A containment environment for AI agents that can write and execute code. Built f
 | Mode | How to Run | Notes |
 |------|------------|-------|
 | **Fully local** | `npm install && npm run dev` | No network needed after hydration. Uses local models (Ollama, WebLLM). |
-| **Hosted UI (https://replo.id)** | Open the site directly | Use WebLLM, cloud API keys, or point the UI at your **local** proxy by enabling CORS on that proxy. |
-| **Hybrid** | Hosted UI + local proxy | Run `npm start` locally, set `CORS_ORIGINS="https://replo.id,https://your-domain.example"` (or configure `server.corsOrigins`), then connect the hosted UI to `http://127.0.0.1:8000`. |
+| **Hosted UI (https://replo.id)** | Open the site directly | Use WebLLM, cloud API keys, or connect to your local proxy. |
+| **Hybrid** | Hosted UI + local proxy | Run `npm start` locally with CORS configured, then connect the hosted UI. |
 
-In all modes, the agent still runs in your browser. The proxy is only needed if you want to access local model servers (e.g., Ollama) from the hosted UI or route cloud API calls through your own machine.
+In all modes, the agent runs in your browser. The proxy is only needed to access local model servers from the hosted UI or route cloud API calls through your machine.
 
 ---
 
-See [TODO.md](TODO.md) for roadmap | [AGENTS.md](AGENTS.md) for agent profile
-
 ## Why REPLOID?
 
 AI agents that write code are powerful but dangerous. Most frameworks give agents unrestricted filesystem access, shell execution, or Docker root — then hope nothing goes wrong.
@@ -30,10 +28,6 @@ REPLOID takes a different approach: **everything runs in a browser sandbox** wit
 - **Self-modification gating** — Test proposed code changes before committing them
 - **Alignment prototyping** — Experiment with oversight patterns before deploying to production
 
-## How It Works
-
-The agent operates on a Virtual File System (VFS) backed by IndexedDB. It can read, write, and execute code — but only within the sandbox. All mutations pass through a verification layer that checks for syntax errors, dangerous patterns, and policy violations.
-
 ## Architecture
 
 ```mermaid
@@ -55,106 +49,64 @@ graph TD
     end
 ```
 
-### Safety First
-
-1.  **Genesis Snapshot at Boot**: Full VFS snapshot captured immediately after hydration, before any user action. Enables offline rollback to pristine state—no network required for recovery.
+### How It Works
 
-2.  **Verification Manager**: All code changes pass through pre-flight checks in an isolated Web Worker. Catches syntax errors, infinite loops, `eval()`, and other dangerous patterns before they reach the VFS.
+The agent operates on a **Virtual File System (VFS)** backed by IndexedDB. It can read, write, and execute code — but only within the sandbox. All mutations pass through a verification layer that checks for syntax errors, dangerous patterns, and policy violations.
 
-3.  **VFS Snapshots**: Transactional rollback. Capture state before mutations, restore if verification fails. No permanent damage from bad agent decisions.
+**Core execution loop:**
+1. **Think** — Agent analyzes context and decides next action
+2. **Act** — Tool call executed against VFS
+3. **Observe** — Results captured and fed back to agent
 
-4.  **Arena Mode**: Test-driven selection for self-modifications. Multiple candidates compete, only verified solutions win. Located in `/testing/arena/`.
+**Key subsystems:**
+- **Agent Loop** — Cognitive cycle with circuit breakers (default: 50 iterations max)
+- **Virtual File System** — Browser-native filesystem on IndexedDB with snapshot/restore
+- **LLM Client** — Multi-provider abstraction (WebLLM, Ollama, OpenAI, Anthropic, Google, Groq)
+- **Worker Manager** — Multi-worker orchestration with permission tiers
+- **Tool Runner** — Dynamic tool loading with arena gating for self-modifications
+- **Verification Manager** — Pre-flight safety checks in isolated Web Worker
 
-5.  **Circuit Breakers**: Rate limiting and iteration caps (default: 50 cycles) prevent runaway agents. Automatic recovery on failure.
+### Safety Mechanisms
 
-6.  **Audit Logging**: Every tool call, VFS mutation, and agent decision is logged. Full replay capability for debugging and analysis.
+1. **Genesis Snapshot** — Full VFS snapshot captured at boot, before any user action. Enables offline rollback to pristine state.
 
-7.  **Service Worker Module Loader**: All ES6 imports intercepted and served from VFS (IndexedDB). Once hydrated, the agent runs entirely offline. Entry points (`boot.js`, `index.html`) stay on network for clean genesis boundaries.
+2. **Pre-flight Verification** — All code changes pass through isolated Web Worker. Catches syntax errors, infinite loops, `eval()`, and dangerous patterns before reaching VFS.
 
-8.  **Genesis Diff Visualization**: Color-coded comparison showing all changes from initial state (green = added, yellow = modified, red = deleted). Instant visibility into what the agent has modified.
+3. **Transactional Rollback** — VFS snapshots before mutations, restores on verification failure. No permanent damage from bad agent decisions.
 
-### Core Components
+4. **Arena Mode** — Test-driven selection for self-modifications. Multiple candidates compete, only verified solutions win.
 
-| Component | Purpose |
-|-----------|---------|
-| `agent-loop.js` | Cognitive cycle (Think → Act → Observe) with circuit breakers |
-| `vfs.js` | Browser-native filesystem on IndexedDB |
-| `llm-client.js` | Multi-provider LLM abstraction (WebLLM, Ollama, Cloud APIs) |
-| `worker-manager.js` | Multi-worker orchestration with permission tiers |
-| `tool-runner.js` | Dynamic tool loading and execution with arena gating |
-| `verification-manager.js` | Pre-flight safety checks in sandboxed worker |
-| `persona-manager.js` | System prompt customization per genesis level |
-| `arena-harness.js` | Competitive selection for code changes |
+5. **Circuit Breakers** — Rate limiting and iteration caps prevent runaway agents. Automatic recovery on failure.
 
-### Proto UI
+6. **Audit Logging** — Every tool call, VFS mutation, and agent decision logged. Full replay capability.
 
-The Proto interface (`ui/proto.js`) provides full observability:
+7. **Service Worker Isolation** — All ES6 imports intercepted and served from VFS. Once hydrated, the agent runs entirely offline.
 
-| Tab | Purpose |
-|-----|---------|
-| **History** | LLM responses, tool calls, streaming output |
-| **Reflections** | Agent learning entries with success/error status |
-| **Status** | Agent state, token usage, error log |
-| **Workers** | Active/completed workers, per-worker logs |
-| **Debug** | System prompt, conversation context, model config |
-
-Additional features: VFS browser with diff/preview, command palette (Ctrl+K), Genesis snapshot management.
+8. **Genesis Diff Visualization** — Color-coded comparison showing all changes from initial state (green=added, yellow=modified, red=deleted).
 
 ### Multi-Worker Orchestration
 
-The WorkerManager enables parallel task execution through permission-filtered subagents:
+The system enables parallel task execution through permission-filtered subagents:
 
 | Worker Type | Permissions | Use Case |
 |-------------|-------------|----------|
-| **explore** | Read-only (ReadFile, ListFiles, Grep, Find) | Codebase analysis |
+| **explore** | Read-only | Codebase analysis |
 | **analyze** | Read + JSON tools | Data processing |
 | **execute** | Full tool access | Task execution |
 
-**Model Roles:** Each worker can use a different model role (orchestrator, fast, code, local) for cost optimization.
-
-**Worker Tools:**
-- `SpawnWorker` — Create a new worker with type, task, and optional model role
-- `ListWorkers` — View active and completed workers
-- `AwaitWorkers` — Wait for specific workers or all to complete
-
-Workers run in a flat hierarchy (no worker can spawn workers) and all actions flow through the same audit pipeline.
-
-### Available Tools
+Each worker can use a different model role (orchestrator, fast, code, local) for cost optimization. Workers run in a flat hierarchy (no nested spawning) and all actions flow through the audit pipeline.
 
-**All tools are dynamic** — loaded from `/tools/` at boot. No hardcoded tools means full RSI capability: the agent can modify any tool, including core file operations. All tool names use CamelCase (e.g., ReadFile, Grep, CreateTool) to keep the interface consistent.
+### Tool System
 
-**Core VFS Operations:**
-- `ReadFile`, `WriteFile`, `ListFiles`, `DeleteFile` — VFS operations with audit logging
+All tools are **dynamically loaded** at boot. No hardcoded tools means full RSI capability: the agent can modify any tool, including core file operations.
 
-**Meta-Tools (RSI):**
-- `CreateTool` — Dynamic tool creation at runtime (L1 RSI)
-- `LoadModule` — Hot-reload modules from VFS
-- `ListTools` — Discover available tools
-- `Edit` — Apply literal match/replacement edits to files
+**Tool categories:**
+- **VFS Operations** — Read, write, list, delete files with audit logging
+- **Meta-Tools (RSI)** — Create new tools at runtime, hot-reload modules
+- **Worker Tools** — Spawn subagents, list/await workers
+- **Utilities** — Grep, find, sed, jq, git (VFS-scoped shim)
 
-**Worker Tools:**
-- `SpawnWorker` — Spawn permission-filtered subagent
-- `ListWorkers` — List active/completed workers
-- `AwaitWorkers` — Wait for worker completion
-
-**Utilities:**
-- `FileOutline` — Analyze file structure without reading content
-- `Cat`, `Head`, `Tail`, `Ls`, `Pwd`, `Touch` — Familiar filesystem navigation primitives
-- `Grep`, `Find`, `Sed`, `Jq` — Search, filter, and transform file contents
-- `Git` — Version control operations (VFS-scoped shim)
-- `Mkdir`, `Rm`, `Mv`, `Cp` — File management
-
-All tools operate within the VFS sandbox with no access to host filesystem. Tools receive a `deps` object with VFS, EventBus, ToolWriter, WorkerManager, and other modules for full capability.
-
----
-
-## Why JavaScript, Not TypeScript?
-
-REPLOID is pure JavaScript because the agent generates, modifies, and executes code at runtime—entirely in the browser. TypeScript requires compilation, but there's no Node.js or build toolchain in-browser.
-
-When the agent writes a new tool to the VFS, the Service Worker immediately serves it as an ES module. No compilation step, no latency. TypeScript would require bundling a 10MB+ compiler or maintaining separate source/artifact trees—defeating the self-modification model.
-
-Runtime safety comes from verification (syntax checks, sandboxed execution, arena testing), not static types. The `[SW]` logs show this: modules loading from VFS, no build step.
+All tools operate within the VFS sandbox with no access to host filesystem.
 
 ---
 
@@ -170,34 +122,11 @@ REPLOID is designed to study [recursive self-improvement](https://en.wikipedia.o
 | **L2: Meta** | Agent improves its tool-creation mechanism | Arena Mode |
 | **L3: Substrate** | Agent modifies core loop or memory | Human Approval (planned) |
 
-### Example: Tool Creation (L1)
-**Goal:** "Create a tool that adds two numbers"
-
-```
-[Agent] Iteration 1: Analyzing goal...
-[Agent] I need a tool to add numbers
-[TOOL_CALL] CreateTool
-[ARGS] {
-  name: "AddNumbers",
-  code: "export default async function({a, b}) { return a + b; }"
-}
-[TOOL_RESULT] ✓ Tool created: /tools/AddNumbers.js
-[Agent] Testing new tool...
-[TOOL_CALL] AddNumbers
-[ARGS] {a: 5, b: 3}
-[TOOL_RESULT] 8
-[Agent] ✓ Goal complete
-```
+**L1 Example:** Agent creates an "AddNumbers" tool, writes it to VFS, tests it, confirms it works.
 
-### Example: Meta-Tool Creation (L2)
-**Goal:** "Build a system that creates tools from descriptions"
+**L2 Example:** Agent creates a "CreateToolFromDescription" tool that uses the LLM to generate code, then persists via the tool-creation mechanism. A tool that makes tools.
 
-Agent creates `CreateToolFromDescription` which calls the LLM to generate code, then calls `CreateTool` to persist it. A tool that makes tools.
-
-### Example: Substrate Modification (L3)
-**Goal:** "Optimize your tool creation process"
-
-Agent reads `/core/tool-writer.js`, identifies a bottleneck, writes an improved version with `WriteFile`, and hot-reloads via `LoadModule`. Self-modification of core infrastructure.
+**L3 Example:** Agent reads its own core modules, identifies a bottleneck, writes an improved version, and hot-reloads it. Self-modification of core infrastructure.
 
 ---
 
@@ -213,9 +142,18 @@ Agent reads `/core/tool-writer.js`, identifies a bottleneck, writes an improved
 | **Offline capable** | Yes (WebLLM) | Yes | Yes | No |
 | **Multi-model** | 6+ providers | Limited | Claude only | Unknown |
 | **Subagents** | Worker tiers | N/A | Task tool | Unknown |
-| **Inspectable** | Full source | Full source | Partial | Closed |
 
-**REPLOID's niche:** Safe experimentation with self-modifying agents. Not the most powerful agent framework — the most observable and recoverable one. Unique advantages: multi-model orchestration, browser-native local models (WebLLM), and permission-tiered worker subagents.
+**REPLOID's niche:** Safe experimentation with self-modifying agents. Not the most powerful agent framework — the most observable and recoverable one.
+
+---
+
+## Why JavaScript?
+
+REPLOID is pure JavaScript because the agent generates, modifies, and executes code at runtime — entirely in the browser. TypeScript requires compilation, but there's no build toolchain in-browser.
+
+When the agent writes a new tool to the VFS, the Service Worker immediately serves it as an ES module. No compilation step, no latency. TypeScript would require bundling a 10MB+ compiler or maintaining separate source/artifact trees — defeating the self-modification model.
+
+Runtime safety comes from verification (syntax checks, sandboxed execution, arena testing), not static types.
 
 ---
 
@@ -246,24 +184,14 @@ npm run dev
 
 REPLOID offers 3 genesis configurations (selectable at boot):
 
-| Level | Modules | Description |
-|-------|---------|-------------|
-| **TABULA RASA** | 13 | Minimal agent core — fast boot, smallest surface |
-| **REFLECTION** | 19 | + Self-awareness, streaming, verification, HITL |
-| **FULL SUBSTRATE** | 32 | + Cognition, semantic memory, arena testing |
+| Level | Description |
+|-------|-------------|
+| **TABULA RASA** | Minimal agent core — fast boot, smallest surface |
+| **REFLECTION** | + Self-awareness, streaming, verification, HITL |
+| **FULL SUBSTRATE** | + Cognition, semantic memory, arena testing |
 
 Select "FULL SUBSTRATE" for RSI experiments with maximum capability.
 
-**Example Goals:**
-- "Create a recursive tool chain: a tool that builds tools that enhance tools"
-- "Analyze your source code in /core and identify bottlenecks"
-- "Build a tool that generates test cases from function signatures"
-
-The VFS Explorer (right panel) provides:
-- **Preview (▶)** - Execute HTML/CSS/JS files in sandboxed iframe
-- **Diff (⊟)** - Compare current VFS to genesis state
-- **Snapshots (◷)** - Timeline of all saved states with restore capability
-
 ---
 
 ## License