docs: update DESIGN.md v1.3 and enhance landing page

- DESIGN.md: Update to v1.3 with current file structure
- DESIGN.md: Fix IAC.md format (newest-first, 15 entries)
- DESIGN.md: Remove obsolete config.yaml references
- README.md: Add 'Deep Dive: Design Philosophy' section
- README.md: Mark landing page as complete in roadmap
- Features: Add Determinism Principle callout with core quote
- Features: Update copy with 95% failure stat
- HowItWorks: Add layered supervision subtitle

Author: CynaCons

DESIGN.md

@@ -1,7 +1,7 @@
 # Multi-Agent Orchestration System - Design Document
 
-**Version:** 1.1
-**Date:** 2025-11-29
+**Version:** 1.3
+**Date:** 2025-12-03
 **Authors:** User + Claude (Orchestrator)
 **Status:** Implemented (with MCP integration)
 
@@ -111,18 +111,22 @@ Agents are unreliable at:
 ### 3.1 Component Overview
 
 ```
-agents/
-├── DESIGN.md           # This document - architecture rationale
-├── CONTEXT.md          # Live state (auto-updated by Python)
-├── IAC.md              # Inter-Agent Communication log (auto-generated)
-├── config.yaml         # Agent configurations
-├── __init__.py         # Package exports
+powerspawn/
+├── mcp_server.py       # MCP protocol server (entry point)
 ├── spawner.py          # Main spawning logic + orchestration
 ├── context_loader.py   # Loads and formats project context
 ├── logger.py           # Writes IAC.md, updates CONTEXT.md
-├── parser.py           # Parses agent responses
+├── parser.py           # Parses agent responses (JSON, JSONL)
+├── __init__.py         # Package exports
 ├── schemas/            # Structured output schemas
-└── workflows/          # Reusable task patterns
+├── examples/           # Usage examples
+├── DESIGN.md           # This document - architecture rationale
+├── MCP_DESIGN.md       # MCP protocol implementation details
+└── README.md           # User-facing documentation
+
+Auto-generated (gitignored):
+├── CONTEXT.md          # Live state (auto-updated by Python)
+└── IAC.md              # Inter-Agent Communication log
 ```
 
 ### 3.2 Data Flow
@@ -201,35 +205,50 @@ The Python orchestrator automatically prepends project context to every prompt:
 
 **Purpose:** Immutable log of all agent spawns and results.
 
-**Format:**
+**Format (v1.4 - Newest First, 15 Entry Limit):**
 ```markdown
 # Inter-Agent Communication Log
 
-## 2025-11-29
-
-### [12:30:45] Spawn #a1b2c3
-- **Agent:** Claude (sonnet)
-- **Task:** Analyze root directory files
-- **Tools:** Bash, Read, Glob, Grep
-- **Prompt:**
-  ```
-  Analyze the files at the root...
-  ```
-- **Status:** Completed
-- **Duration:** 45.2s
-- **Cost:** $0.41
-- **Result Summary:** Found 12 files to delete, 2 security risks
+> Auto-generated by PowerSpawn. Newest entries first. Limited to last 15 entries.
+
+---
+
+### 🤖 Claude Agent #a1b2c3
+**Started:** 2025-12-01 12:30:45 UTC | **Status:** ✅ Completed (45.2s, $0.41)
+
+<details>
+<summary>📋 Prompt</summary>
+
+Analyze the files at the root directory and identify security risks...
+
+</details>
+
+<details>
+<summary>📊 Result</summary>
+
+Found 12 files to delete, 2 security risks:
+1. .env.local exposed in git
+2. API key hardcoded in config.js
+
+</details>
 
 ---
 
-### [12:31:30] Spawn #d4e5f6
+### 🤖 Codex Agent #d4e5f6
+**Started:** 2025-12-01 12:28:00 UTC | **Status:** ✅ Completed (120s, ~$0.01)
 ...
 ```
 
+**Key Features:**
+- **Newest first** - Most recent entries at top for quick access
+- **15 entry limit** - Prevents unbounded file growth
+- **Collapsible details** - Prompts and results hidden by default
+- **Status updated in-place** - Entry updated when agent completes (not appended)
+
 **Rules:**
-- Append-only (never edit past entries)
 - Auto-generated by Python (never by agents)
 - Provides audit trail for debugging
+- Git-trackable for version control
 
 ### 4.2 CONTEXT.md (Live State)
 
@@ -268,38 +287,34 @@ The Python orchestrator automatically prepends project context to every prompt:
 
 ## 5. Configuration
 
-### 5.1 Context Files to Load
+PowerSpawn uses sensible defaults with optional environment variable overrides:
 
-Defined in `config.yaml`:
+### 5.1 Environment Variables
 
-```yaml
-context:
-  # Files to inject into every prompt
-  always_include:
-    - CLAUDE.md        # Coding conventions (full)
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `POWERSPAWN_OUTPUT_DIR` | Directory for IAC.md and CONTEXT.md | Project root |
+| `ANTHROPIC_API_KEY` | For Claude agents | (from CLI config) |
+| `OPENAI_API_KEY` | For Codex agents | (from CLI config) |
 
-  # Files to summarize and inject
-  summarize:
-    - PRD.md           # Product requirements (first 100 lines)
-    - PLAN.md          # Current iteration only
-    - ARCHITECTURE.md  # Overview section only
+### 5.2 Context Injection
 
-  # Files available but not auto-injected
-  on_demand:
-    - docs/SRS_DB.md   # Database schema
-    - CONTRIBUTING.md  # Contribution guidelines
-```
+The MCP server automatically injects context files when spawning agents:
 
-### 5.2 Logging Configuration
+- **AGENTS.md** - Universal instructions for all sub-agents (always injected)
+- **CLAUDE.md** - Project-specific coding conventions (if exists)
+- **CONTEXT.md** - Current agent state (if exists)
 
-```yaml
-logging:
-  iac_file: "IAC.md"
-  context_file: "CONTEXT.md"
-  max_recent_runs: 10
-  log_prompts: true        # Include full prompts in IAC
-  log_responses: false     # Only log summaries (responses can be large)
-```
+Context is loaded by `context_loader.py` and prepended to every prompt.
+
+### 5.3 Logging Defaults
+
+| Setting | Value |
+|---------|-------|
+| Max IAC.md entries | 15 |
+| Entry order | Newest first |
+| Prompts logged | Yes (collapsible) |
+| Results logged | Yes (collapsible) |
 
 ---
 
@@ -462,3 +477,4 @@ When asked to run Playwright tests, Codex agents:
 | 1.0 | 2025-11-29 | Initial design document |
 | 1.1 | 2025-11-29 | Added MCP integration (see MCP_DESIGN.md for details) |
 | 1.2 | 2025-11-30 | Added Codex limitations and agent comparison matrix |
+| 1.3 | 2025-12-03 | Updated for standalone PowerSpawn: new file structure, IAC.md v1.4 format (newest-first, 15 entries), removed config.yaml |

README.md

@@ -286,10 +286,20 @@ Environment variables:
 
 Agent defaults are in the MCP server. Override via tool parameters.
 
+## Deep Dive: Design Philosophy
+
+For a comprehensive understanding of PowerSpawn's architecture and the reasoning behind our design decisions, read **[DESIGN.md](DESIGN.md)**.
+
+Key highlights:
+- **Why deterministic logging?** Agents are 95% unreliable at self-reporting (Section 6.1)
+- **Layered supervision model** - User → Coordinator → Python → Sub-agents (Section 2.3)
+- **The Determinism Principle** - Everything that CAN be done deterministically SHOULD be (Section 2.1)
+- **Agent capability matrix** - When to use Claude vs Codex (Section 11)
+
 ## Roadmap
 
+- [x] Landing page at powerspawn.com
 - [ ] GitHub Copilot compatibility testing
-- [ ] Landing page at powerspawn.com
 - [ ] MCP Registry submission
 - [ ] Support for Gemini models
 - [ ] Unit and integration test suite

site/src/components/Features.tsx

@@ -11,7 +11,7 @@ const features = [
   {
     icon: '🎯',
     title: 'Deterministic, Not Hopeful',
-    description: 'MCP wraps agents and captures all I/O automatically. No relying on agents to "follow instructions".',
+    description: 'MCP wraps agents and captures all I/O automatically. Agents fail 95% of the time at self-reporting — we don\'t ask them to try.',
   },
   {
     icon: '⚖️',
@@ -72,7 +72,7 @@ export function Features() {
           initial={{ opacity: 0, y: 20 }}
           animate={isInView ? { opacity: 1, y: 0 } : {}}
           transition={{ duration: 0.5 }}
-          className="text-center mb-16"
+          className="text-center mb-12"
         >
           <h2 className="text-4xl font-bold text-white mb-4">
             Why PowerSpawn?
@@ -82,6 +82,26 @@ export function Features() {
           </p>
         </motion.div>
 
+        {/* Core Principle Callout */}
+        <motion.div
+          initial={{ opacity: 0, y: 20 }}
+          animate={isInView ? { opacity: 1, y: 0 } : {}}
+          transition={{ duration: 0.5, delay: 0.1 }}
+          className="mb-12 p-6 rounded-xl bg-gradient-to-r from-indigo-900/30 to-purple-900/30 border border-indigo-500/30 max-w-3xl mx-auto"
+        >
+          <div className="text-center">
+            <div className="text-indigo-400 font-mono text-sm mb-2">THE DETERMINISM PRINCIPLE</div>
+            <blockquote className="text-xl md:text-2xl text-white font-medium italic">
+              "Everything that CAN be done deterministically SHOULD be done deterministically."
+            </blockquote>
+            <p className="mt-4 text-gray-400 text-sm">
+              Agents excel at reasoning and code generation. They're terrible at administrative tasks.
+              <br />
+              <span className="text-gray-500">Let Python handle the bookkeeping. Let agents do what they're good at.</span>
+            </p>
+          </div>
+        </motion.div>
+
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
           {features.map((feature, index) => (
             <FeatureCard key={feature.title} feature={feature} index={index} />

site/src/components/HowItWorks.tsx

@@ -20,7 +20,10 @@ export function HowItWorks() {
             How It Works
           </h2>
           <p className="text-xl text-gray-400 max-w-2xl mx-auto">
-            The IAC.md Pattern — File-based inter-agent communication
+            Layered Supervision: User → Coordinator → Python → Sub-agents
+          </p>
+          <p className="text-sm text-gray-500 mt-2">
+            The IAC.md pattern provides file-based inter-agent communication
           </p>
         </motion.div>