@tienne/gestalt 0.15.0 → 0.15.1

package/README.ko.md

@@ -77,7 +77,7 @@ Gestalt는 코드를 작성하기 전에 요구사항을 함께 구체화해줘
 
 ### Passthrough 모드는 어떻게 작동하나요?
 
-Gestalt는 **MCP 서버**로 실행돼요. Claude Code를 통해 사용할 경우 Claude Code가 LLM 역할을 담당해요 — Gestalt는 프롬프트와 컨텍스트를 반환하고, 실제 추론은 Claude Code가 수행해요. 서버 자체는 별도 API 호출을 하지 않아요.
+Gestalt는 **MCP 서버**로 실행돼요. Claude Code를 통해 사용할 경우 Claude Code가 LLM 역할을 담당해요 — Gestalt는 프롬프트와 컨텍스트를 반환하고, 실제 추론은 Claude Code가 해요. 서버 자체는 별도 API 호출을 하지 않아요.
 
 ```
 Claude Code
@@ -116,7 +116,7 @@ Spec과 실행 결과는 레포 루트의 `.gestalt/memory.json`에 자동으로
 }
 ```
 
-- **커밋하세요** — `.gestalt/memory.json`은 일반 JSON 파일이에요. 커밋하면 팀원도 `git pull` 후 이전 결정 사항을 그대로 이어받을 수 있어요.
+- **커밋하세요** — `.gestalt/memory.json`은 일반 JSON 파일이에요. 커밋해두면 팀원도 `git pull` 후 이전 결정 사항을 그대로 이어받을 수 있어요.
 - **컨텍스트 반영** — 다음 Spec을 생성할 때 이전 목표와 아키텍처 결정 사항이 프롬프트에 자동으로 반영돼요.
 - **User Profile** — 개인 설정은 `~/.gestalt/profile.json`에 저장돼요. git에는 올라가지 않아요.
 
@@ -126,7 +126,7 @@ Spec과 실행 결과는 레포 루트의 `.gestalt/memory.json`에 자동으로
 
 ### 옵션 1: Claude Code 플러그인 (권장)
 
-설치 한 번에 MCP 서버, 슬래시 커맨드, Gestalt 에이전트, 프로젝트 컨텍스트를 모두 사용할 수 있어요.
+설치 한 번에 MCP 서버, 슬래시 커맨드, Gestalt 에이전트, 프로젝트 컨텍스트를 모두 쓸 수 있어요.
 
 **터미널에서:**
 
@@ -208,7 +208,7 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 /interview "Stripe로 결제 플로우를 만들고 싶어"
 ```
 
-각 라운드는 모호한 부분을 집중해서 파악해요:
+각 라운드는 모호한 부분을 집중적으로 파악해요:
 
 - **Closure** — 빠진 요구사항과 말하지 않고 가정한 것을 찾아요
 - **Proximity** — 함께 묶여야 할 기능을 식별해요
@@ -226,7 +226,7 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 
 #### 인터뷰가 길어질 때 (Context Compression)
 
-라운드가 5개를 초과하면 Gestalt가 자동으로 압축을 제안해요. `compress` action을 사용하면 이전 대화를 요약해 컨텍스트를 줄일 수 있어요:
+라운드가 5개를 초과하면 Gestalt가 자동으로 압축을 제안해요. `compress` action을 쓰면 이전 대화를 요약해 컨텍스트를 줄일 수 있어요:
 
 ```
 1. respond 응답에 needsCompression: true + compressionContext 포함
@@ -343,7 +343,7 @@ ges_execute({
 
 #### 실행 진행 패널
 
-`/execute` 실행 중 Claude Code Task 패널에 진행 상태가 실시간으로 표시돼요. Planning 단계부터 Evaluate까지 각 완료 태스크 수, 현재 태스크 이름, 실패 수, 병렬 그룹 구조가 자동으로 갱신돼요.
+`/execute` 실행 중 Claude Code Task 패널에 진행 상태가 실시간으로 표시돼요. Planning 단계부터 Evaluate까지 완료 태스크 수, 현재 태스크 이름, 실패 수, 병렬 그룹 구조가 자동으로 갱신돼요.
 
 #### 하위 에이전트 생성 (Spawn)
 
@@ -390,7 +390,7 @@ evolve_fix → 수정 태스크 제출 → 재평가
 evolve → Spec 패치 (AC/constraints) → 영향받은 태스크 재실행 → 재평가
 ```
 
-Spec 패치 범위: AC와 constraints는 자유 수정; ontology는 추가/변경만; **goal은 변경 불가**.
+Spec 패치 범위: AC와 constraints는 자유롭게 수정할 수 있어요. ontology는 추가/변경만 가능하고, **goal은 변경할 수 없어요**.
 
 **Flow C — Lateral Thinking** (답보 상태 감지 시)
 
@@ -403,7 +403,7 @@ Spec 패치 범위: AC와 constraints는 자유 수정; ontology는 추가/변
 | 진전 없음 (no drift) | **Reification** | 빠진 것 채우기 |
 | 효과 감소 | **Invariance** | 성공한 패턴 복제 |
 
-4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요. 직접 해결할 수 있도록 구체적인 제안도 함께 제공해요.
+4개 Persona를 모두 소진하면 세션이 **Human Escalation**으로 종료돼요. 직접 해결할 수 있도록 구체적인 제안도 함께 알려줘요.
 
 **종료 조건:**
 
@@ -448,7 +448,7 @@ review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 | `performance-reviewer` | 메모리 누수, N+1 쿼리, 번들 크기, 비동기 |
 | `quality-reviewer` | 가독성, SOLID, 에러 핸들링, DRY |
 
-파이프라인 밖에서도 `/agent`로 언제든 에이전트를 사용할 수 있어요:
+파이프라인 밖에서도 `/agent`로 언제든 에이전트를 쓸 수 있어요:
 
 ```bash
 # 사용 가능한 에이전트 목록 조회
@@ -460,7 +460,7 @@ review_start → 에이전트 관점 제출 → 합의 → 자동 수정
 /agent technical-writer "이 모듈의 README를 작성해줘"
 ```
 
-인터뷰 결과에서 커스텀 Role 에이전트를 생성할 수도 있어요:
+인터뷰 결과에서 커스텀 Role 에이전트를 만들 수도 있어요:
 
 ```
 # 인터뷰 완료 후 커스텀 에이전트 생성
@@ -478,15 +478,12 @@ ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
 
 ### CLI 모드 (Claude Code 없이 사용하기)
 
-Claude Code 없이 터미널에서 바로 사용하고 싶다면 CLI 모드를 이용할 수 있어요. **`ANTHROPIC_API_KEY`가 필요해요.**
+Claude Code 없이 터미널에서 바로 쓰고 싶다면 CLI 모드를 이용할 수 있어요. **`ANTHROPIC_API_KEY`가 필요해요.**
 
 ```bash
 # 인터랙티브 인터뷰 시작
 npx @tienne/gestalt interview "주제"
 
-# 터미널 세션을 GIF로 녹화
-npx @tienne/gestalt interview "주제" --record
-
 # 완료된 세션에서 Spec 생성
 npx @tienne/gestalt spec <session-id>
 
@@ -500,24 +497,6 @@ npx @tienne/gestalt setup
 npx @tienne/gestalt serve
 ```
 
-#### 인터뷰 세션 녹화
-
-`--record` (또는 `-r`) 플래그를 추가하면 터미널 세션을 GIF로 녹화할 수 있어요:
-
-```bash
-npx @tienne/gestalt interview "주제" --record
-```
-
-인터뷰가 완료되면 현재 디렉토리에 GIF 파일이 생성돼요:
-
-```
-user-auth-interview-20260327.gif
-```
-
-파일명은 LLM이 인터뷰 주제를 기반으로 kebab-case로 생성하고, `YYYYMMDD` 날짜를 붙여요. 외부 바이너리는 필요하지 않아요 — `gifencoder`와 `jimp` npm 패키지만 사용해요.
-
-**중단된 세션 이어 녹화:** 녹화 중 세션이 중단되더라도 걱정하지 않아도 돼요. 동일 세션을 다시 실행하면 `.frames` 파일을 자동으로 감지해 이어서 녹화해요. 임시 프레임 데이터는 `.gestalt/recordings/{sessionId}.frames`에 저장되고, GIF 생성이 완료되면 자동으로 삭제돼요.
-
 ---
 
 ## 설정

package/README.md

@@ -19,27 +19,52 @@
 
 ---
 
-## What is Gestalt?
+Gestalt is an MCP (Model Context Protocol) server that runs inside Claude Code. It conducts a structured requirement interview, generates a validated **Spec** — a JSON document capturing your goal, constraints, and acceptance criteria — and transforms that Spec into a dependency-aware execution plan.
 
-Gestalt is an MCP (Model Context Protocol) server that runs inside Claude Code. It conducts structured requirement interviews, generates a validated **Spec** (a JSON document capturing your goal, constraints, and acceptance criteria), and transforms that Spec into a dependency-aware execution plan.
+Claude Code acts as the LLM throughout. Gestalt manages state, validates results, and advances the pipeline. No API key required.
 
-> **Prerequisites:** Node.js >= 20.0.0. Use `nvm install 22 && nvm use 22` if needed.
+> **Requires Node.js >= 20.0.0.** Use `nvm install 22 && nvm use 22` if needed.
+
+---
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [The Pipeline](#the-pipeline)
+  - [1. Interview](#1-interview)
+  - [2. Spec Generation](#2-spec-generation)
+  - [3. Execute](#3-execute)
+  - [4. Evaluate](#4-evaluate)
+  - [5. Evolve](#5-evolve)
+  - [6. Code Review](#6-code-review)
+- [Agents](#agents)
+- [CLI Mode](#cli-mode)
+- [Project Memory](#project-memory)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
 
 ---
 
 ## Quick Start
 
-Install the plugin once, then use it in any Claude Code session:
+Install the plugin once, then use it in any Claude Code session.
+
+**From a terminal (outside a session):**
 
 ```bash
-# Step 1: Add to marketplace (one-time setup)
-/plugin marketplace add tienne/gestalt
+claude plugin install gestalt@gestalt
+```
 
-# Step 2: Install the plugin
+**Inside a Claude Code session:**
+
+```bash
+/plugin marketplace add tienne/gestalt
 /plugin install gestalt@gestalt
 ```
 
-Then in any Claude Code session:
+Then run the pipeline:
 
 ```bash
 /interview "user authentication system"
@@ -47,34 +72,34 @@ Then in any Claude Code session:
 /execute
 ```
 
-→ **[Full MCP Reference](./docs/mcp-reference.md)** — all tools, parameters, and examples
+**[Full MCP Reference](./docs/mcp-reference.md)** — all tools, parameters, and examples
 
 ---
 
-## Why Gestalt?
+## How It Works
 
-Vague requirements are the primary source of implementation drift. When the goal isn't precise, Claude fills in gaps with assumptions — and those assumptions diverge from intent as the project grows.
+Vague requirements are the primary cause of implementation drift. When the goal isn't precise, Claude fills gaps with assumptions — and those assumptions diverge from intent as the project grows.
 
-Gestalt addresses this at the source. Before any code is written, it runs a structured interview guided by **Gestalt psychology principles** to raise resolution to a measurable threshold (≥ 0.8). The result is a **Spec**: a validated JSON document that serves as the single source of truth for planning and execution.
+Gestalt addresses this before any code is written. It runs a structured interview guided by five **Gestalt psychology principles** to raise requirement resolution to a measurable threshold (≥ 0.8). The result is a **Spec**: a validated JSON document that drives every subsequent step.
 
 ### The Five Gestalt Principles
 
-- **Closure** — Finds what's missing; fills in implicit requirements
-- **Proximity** — Groups related features and tasks by domain
-- **Similarity** — Identifies repeating patterns across requirements
-- **Figure-Ground** — Separates MVP (figure) from nice-to-have (ground)
-- **Continuity** — Validates dependency chains; detects contradictions
-
-> "The whole is greater than the sum of its parts." — Aristotle
+| Principle | Role |
+|-----------|------|
+| **Closure** | Finds what's missing; surfaces implicit requirements |
+| **Proximity** | Groups related features and tasks by domain |
+| **Similarity** | Identifies repeating patterns across requirements |
+| **Figure-Ground** | Separates MVP (figure) from nice-to-have (ground) |
+| **Continuity** | Validates dependency chains; detects contradictions |
 
-### How does Passthrough Mode work?
+### Passthrough Mode
 
-Gestalt runs as an **MCP server**. Claude Code acts as the LLM: Gestalt returns prompts and context, and Claude Code does the reasoning. The server makes no API calls.
+Gestalt runs as an MCP server. Claude Code acts as the LLM: Gestalt returns prompts and context, and Claude Code does the reasoning. The server makes no API calls.
 
 ```
 You (in Claude Code)
        │
-       ▼ /interview "topic"
+       ▼  /interview "topic"
   Gestalt MCP Server
   (returns context + prompts)
        │
@@ -86,32 +111,12 @@ You (in Claude Code)
   Gestalt MCP Server
   (validates, stores state, advances)
        │
-       ▼ repeat until resolution ≥ 0.8
+       ▼  repeat until resolution ≥ 0.8
   Final Spec → Execution Plan
 ```
 
 ---
 
-## Project Memory
-
-Every spec and execution result is automatically recorded in `.gestalt/memory.json` at your repo root.
-
-```json
-{
-  "specHistory": [
-    { "specId": "...", "goal": "Build a user auth system", "sourceType": "text" }
-  ],
-  "executionHistory": [],
-  "architectureDecisions": []
-}
-```
-
-- **Commit it** — `.gestalt/memory.json` is plain JSON. Commit it and teammates inherit all prior decisions on `git pull`.
-- **Context injection** — When generating the next spec, prior goals and architecture decisions are automatically injected into the prompt.
-- **User profile** — Personal preferences are stored in `~/.gestalt/profile.json` and are never committed.
-
----
-
 ## Installation
 
 ### Option 1: Claude Code Plugin (Recommended)
@@ -127,29 +132,24 @@ claude plugin install gestalt@gestalt
 **Inside a Claude Code session:**
 
 ```bash
-# Step 1: Add to marketplace (one-time setup)
 /plugin marketplace add tienne/gestalt
-
-# Step 2: Install the plugin
 /plugin install gestalt@gestalt
 ```
 
-What you get out of the box:
+What you get:
 
 | Item | Details |
 |------|---------|
-| **MCP Tools** | `ges_interview`, `ges_generate_spec`, `ges_execute`, `ges_create_agent`, `ges_agent`, `ges_status`, `ges_code_graph`, `ges_graph_visualize`, `ges_benchmark` |
+| **MCP Tools** | `ges_interview`, `ges_generate_spec`, `ges_execute`, `ges_create_agent`, `ges_agent`, `ges_status`, `ges_code_graph`, `ges_graph_visualize`, `ges_benchmark`, `ges_generate_kb`, `ges_search`, `ges_sync` |
 | **Slash Commands** | `/interview`, `/spec`, `/execute`, `/agent` |
-| **Agents** | 5 Gestalt pipeline agents + 9 Role agents + 3 Review agents |
+| **Agents** | 5 pipeline agents + 9 Role agents + 3 Review agents |
 | **CLAUDE.md** | Project context and MCP usage guide auto-injected |
 
-> **Requires Node.js >= 20.0.0** — use [nvm](https://github.com/nvm-sh/nvm) if needed: `nvm install 22 && nvm use 22`
-
 ---
 
 ### Option 2: Claude Code Desktop
 
-Open your Claude Code Desktop settings and add to `settings.json` (or `claude_desktop_config.json`):
+Add this to your `settings.json` (or `claude_desktop_config.json`) and restart:
 
 ```json
 {
@@ -162,18 +162,17 @@ Open your Claude Code Desktop settings and add to `settings.json` (or `claude_de
 }
 ```
 
-Restart Claude Code Desktop. The MCP tools become available immediately. Slash commands require the plugin or manual skills setup.
+MCP tools are available immediately after restart. Slash commands require the plugin or manual skills setup.
 
 ---
 
 ### Option 3: Claude Code CLI
 
 ```bash
-# Via the claude CLI
 claude mcp add gestalt -- npx -y @tienne/gestalt
 ```
 
-Or edit `~/.claude/settings.json` directly:
+Or add directly to `~/.claude/settings.json`:
 
 ```json
 {
@@ -188,11 +187,11 @@ Or edit `~/.claude/settings.json` directly:
 
 ---
 
-## Usage: Full Pipeline
+## The Pipeline
 
-### Step 1 — Interview
+### 1. Interview
 
-Start with any topic. A single rough sentence is enough.
+Start with any topic. A rough sentence is enough.
 
 ```bash
 /interview "I want to build a checkout flow with Stripe"
@@ -206,7 +205,7 @@ Gestalt conducts a multi-round interview. Each round targets a specific resoluti
 - **Figure-Ground** — What's the core MVP vs. what's optional?
 - **Continuity** — Any contradictions or conflicts?
 
-The interview continues until the **resolution score reaches ≥ 0.8**:
+The interview continues until the resolution score reaches ≥ 0.8:
 
 ```
 Round 1 → resolution: 0.28  (lots of unknowns)
@@ -214,9 +213,9 @@ Round 4 → resolution: 0.55  (getting clearer)
 Round 8 → resolution: 0.81  ✓ ready for Spec
 ```
 
-#### Long interviews: Context Compression
+#### Context Compression
 
-When rounds exceed 5, Gestalt automatically signals that compression is available. Use the `compress` action to summarize earlier rounds and keep the context window lean:
+When rounds exceed 5, Gestalt signals that compression is available. Use the `compress` action to summarize earlier rounds and keep the context window lean:
 
 ```
 1. respond returns needsCompression: true + compressionContext
@@ -228,114 +227,111 @@ The compressed summary is automatically injected into all subsequent rounds.
 
 ---
 
-### Step 2 — Spec Generation
+### 2. Spec Generation
 
-**Option A — From text (no interview required):**
+**From a completed interview:**
 
 ```bash
-ges_generate_spec({ text: "Build a checkout flow with Stripe" })
+/spec
 ```
 
-**Option A-2 — With a built-in template:**
+**From text (no interview required):**
+
+```bash
+ges_generate_spec({ text: "Build a checkout flow with Stripe" })
+```
 
-Three starter templates pre-fill common constraints and acceptance criteria:
+**With a built-in template:**
 
 | Template ID | Description |
 |-------------|-------------|
-| `rest-api` | REST API server with auth, CRUD, and OpenAPI |
+| `rest-api` | REST API with auth, CRUD, and OpenAPI |
 | `react-dashboard` | React dashboard with charts, filters, and responsive layout |
-| `cli-tool` | CLI tool with subcommands, config, and distribution |
+| `cli-tool` | CLI with subcommands, config file, and distribution |
 
 ```bash
 ges_generate_spec({ text: "API with JWT authentication", template: "rest-api" })
 ```
 
-**Option B — From a completed interview:**
-
-```bash
-/spec
-```
-
-Generates a structured **Spec** — a validated JSON document that drives the rest of the pipeline:
+The generated Spec includes:
 
 ```
 goal                → Clear, precise project objective
 constraints         → Technical and business constraints
 acceptanceCriteria  → Measurable, verifiable success conditions
-ontologySchema      → Entity-relationship model (entities + relations)
+ontologySchema      → Entity-relationship model
 gestaltAnalysis     → Key findings per Gestalt principle
 ```
 
 ---
 
-### Step 3 — Execute (Planning + Execution)
+### 3. Execute
 
-Transforms the Spec into a dependency-aware execution plan and runs it:
+Transform the Spec into a dependency-aware execution plan and run it:
 
 ```bash
 /execute
 ```
 
-**Planning phase** applies 4 Gestalt principles in a fixed sequence:
+**Planning** applies four Gestalt principles in a fixed sequence:
 
 | Step | Principle | What it does |
 |:---:|-----------|-------------|
-| 1 | **Figure-Ground** | Classifies acceptance criteria (ACs) as critical (figure) vs. supplementary (ground) |
+| 1 | **Figure-Ground** | Classifies acceptance criteria as critical vs. supplementary |
 | 2 | **Closure** | Decomposes ACs into atomic tasks, including implicit ones |
-| 3 | **Proximity** | Groups related tasks by domain into logical task groups |
-| 4 | **Continuity** | Validates the dependency DAG — no cycles, clear topological order |
+| 3 | **Proximity** | Groups related tasks by domain |
+| 4 | **Continuity** | Validates the dependency DAG — no cycles, topological order confirmed |
 
-**Execution phase** runs tasks in topological order. After each task, **drift detection** checks alignment with the Spec:
+**Execution** runs tasks in topological order. After each task, drift detection checks alignment with the Spec:
 
 - 3-dimensional score: Goal (50%) + Constraint (30%) + Ontology (20%)
-- Jaccard similarity-based measurement
-- Auto-triggers a retrospective when drift exceeds threshold
+- Jaccard similarity measurement
+- Auto-triggers a retrospective when drift exceeds the threshold
 
-#### Parallel execution groups
+#### Parallel Execution
 
-The `plan_complete` response includes `parallelGroups: string[][]`. Tasks with no mutual dependencies land in the same group and can be executed concurrently:
+The `plan_complete` response includes `parallelGroups: string[][]`. Tasks with no mutual dependencies are placed in the same group and can run concurrently:
 
 ```json
 "parallelGroups": [
-  ["setup-db", "setup-env"],   // run in parallel
-  ["create-schema"],           // after group above
-  ["seed-data", "run-tests"]   // run in parallel
+  ["setup-db", "setup-env"],
+  ["create-schema"],
+  ["seed-data", "run-tests"]
 ]
 ```
 
-#### Resuming an interrupted execution
-
-Pick up where you left off when a session is interrupted:
+#### Resuming an Interrupted Session
 
 ```bash
 ges_execute({ action: "resume", sessionId: "<id>" })
 ```
 
-Returns `ResumeContext`: completed task IDs, next task, and `progressPercent`. The `ges_status` response also includes `resumeContext` automatically for any executing session.
+Returns `ResumeContext`: completed task IDs, next task, and `progressPercent`. The `ges_status` response also includes `resumeContext` automatically for any active session.
 
-#### Brownfield audit
+#### Brownfield Audit
 
-When a codebase already exists, audit it against the Spec before executing new tasks:
+When a codebase already exists, audit it against the Spec before running new tasks:
 
 ```bash
 # Step 1: request audit context
 ges_execute({ action: "audit", sessionId: "<id>" })
-→ auditContext (systemPrompt, auditPrompt)
+# → returns auditContext (systemPrompt, auditPrompt)
 
 # Step 2: submit codebase snapshot + audit result
 ges_execute({
   action: "audit",
   sessionId: "<id>",
   codebaseSnapshot: "...",
-  auditResult: { implementedACs: [0,2], partialACs: [1], missingACs: [3], gapAnalysis: "..." }
+  auditResult: {
+    implementedACs: [0, 2],
+    partialACs: [1],
+    missingACs: [3],
+    gapAnalysis: "..."
+  }
 })
 ```
 
-#### Real-time progress panel
-
-When using the `/execute` slash command, Gestalt displays live execution status in the Claude Code Task panel — showing completed/total tasks, current task name, failed task count, and parallel group progress. Updated automatically at each planning step, task completion, and evaluation stage.
-
-#### Sub-agent spawning
+#### Sub-Agent Spawning
 
 Decompose a complex task into sub-tasks dynamically during execution:
 
@@ -351,31 +347,37 @@ ges_execute({
 })
 ```
 
+#### Real-Time Progress Panel
+
+The `/execute` slash command displays live execution status in the Claude Code Task panel — completed/total tasks, current task name, failed count, and parallel group progress. Updated automatically at each planning step, task completion, and evaluation stage.
+
 ---
 
-### Step 4 — Evaluate
+### 4. Evaluate
 
-Execution triggers a 2-stage evaluation:
+Execution triggers a two-stage evaluation automatically:
 
 | Stage | Method | On failure |
 |:---:|-------|-----------|
-| 1 | **Structural** — runs lint → build → test | Short-circuits; skips Stage 2 |
-| 2 | **Contextual** — LLM validates each AC + goal alignment | Enters Evolution Loop |
+| 1 | **Structural** — runs lint → build → test | Short-circuits; Stage 2 is skipped |
+| 2 | **Contextual** — LLM validates each AC and goal alignment | Enters the Evolution Loop |
 
 **Success condition:** `score ≥ 0.85` AND `goalAlignment ≥ 0.80`
 
 ---
 
-### Step 5 — Evolve
+### 5. Evolve
 
 When evaluation fails, the Evolution Loop engages. Three recovery flows are available:
 
 **Flow A — Structural Fix** (when lint/build/test fails)
+
 ```
 evolve_fix → submit fix tasks → re-evaluate
 ```
 
 **Flow B — Contextual Evolution** (when AC score is too low)
+
 ```
 evolve → patch Spec (ACs/constraints) → re-execute impacted tasks → re-evaluate
 ```
@@ -388,12 +390,12 @@ Gestalt rotates through lateral thinking personas rather than terminating:
 
 | Stagnation Pattern | Persona | Strategy |
 |--------------------|---------|---------|
-| Hard cap hit | **Multistability** | See from a different angle |
+| Hard cap hit | **Multistability** | View from a different angle |
 | Oscillating scores | **Simplicity** | Strip down and converge |
 | No progress (no drift) | **Reification** | Fill in what's missing |
 | Diminishing returns | **Invariance** | Replicate what worked |
 
-When all 4 personas are exhausted, the session terminates with **Human Escalation** — a structured list of actionable suggestions for manual resolution.
+When all four personas are exhausted, the session ends with **Human Escalation** — a structured list of actionable suggestions for manual resolution.
 
 **Termination conditions:**
 
@@ -408,7 +410,7 @@ When all 4 personas are exhausted, the session terminates with **Human Escalatio
 
 ---
 
-### Step 6 — Code Review
+### 6. Code Review
 
 When evolution finishes, code review starts automatically:
 
@@ -416,7 +418,27 @@ When evolution finishes, code review starts automatically:
 review_start → agents submit perspectives → consensus → auto-fix
 ```
 
-9 built-in **Role Agents** provide multi-perspective review:
+See [Agents](#agents) for the full list of built-in reviewers.
+
+---
+
+## Agents
+
+Use any agent directly, outside the pipeline:
+
+```bash
+# List all available agents
+/agent
+
+# Run a specific agent on any task
+/agent architect "review the module boundaries in this codebase"
+/agent security-reviewer "check this authentication code for vulnerabilities"
+/agent technical-writer "write a README for this module"
+```
+
+### Role Agents
+
+Nine built-in role agents provide multi-perspective review:
 
 | Agent | Domain |
 |-------|--------|
@@ -430,7 +452,9 @@ review_start → agents submit perspectives → consensus → auto-fix
 | `researcher` | Analysis, data, benchmarks |
 | `technical-writer` | Documentation, API docs, guides, README |
 
-3 built-in **Review Agents** run focused code analysis:
+### Review Agents
+
+Three built-in review agents run focused code analysis:
 
 | Agent | Focus |
 |-------|-------|
@@ -438,44 +462,31 @@ review_start → agents submit perspectives → consensus → auto-fix
 | `performance-reviewer` | Memory leaks, N+1 queries, bundle size, async |
 | `quality-reviewer` | Readability, SOLID, error handling, DRY |
 
-Use any agent outside the pipeline with `/agent`:
-
-```bash
-# List all available agents
-/agent
-
-# Run a specific agent on any task
-/agent architect "review the module boundaries in this codebase"
-/agent security-reviewer "check this authentication code for vulnerabilities"
-/agent technical-writer "write a README for this module"
-```
+### Custom Agents
 
-Generate custom Role Agents from interview results:
+Generate a custom Role Agent from interview results:
 
-```
-# Step 1: Get agent creation context
-ges_create_agent  →  action: "start", sessionId: "<id>"
-                  →  returns agentContext (systemPrompt, creationPrompt, schema)
+```bash
+# Step 1: get agent creation context
+ges_create_agent({ action: "start", sessionId: "<id>" })
+# → returns agentContext (systemPrompt, creationPrompt, schema)
 
-# Step 2: Submit the generated AGENT.md content
-ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
-                  →  creates agents/{name}/AGENT.md
+# Step 2: submit the generated AGENT.md content
+ges_create_agent({ action: "submit", sessionId: "<id>", agentContent: "..." })
+# → creates agents/{name}/AGENT.md
 ```
 
 ---
 
-### CLI Mode (without Claude Code)
+## CLI Mode
 
-Want to run Gestalt without Claude Code? CLI mode runs interviews directly in your terminal. **Requires `ANTHROPIC_API_KEY`.**
+Run Gestalt without Claude Code. **Requires `ANTHROPIC_API_KEY`.**
 
 ```bash
 # Start an interactive interview
 npx @tienne/gestalt interview "my topic"
 
-# Record the session as a GIF
-npx @tienne/gestalt interview "my topic" --record
-
-# Generate Spec from a completed session
+# Generate a Spec from a completed session
 npx @tienne/gestalt spec <session-id>
 
 # List all sessions
@@ -488,29 +499,33 @@ npx @tienne/gestalt setup
 npx @tienne/gestalt serve
 ```
 
-#### Recording an interview session
-
-Add `--record` (or `-r`) to capture the terminal session as a GIF:
+---
 
-```bash
-npx @tienne/gestalt interview "my topic" --record
-```
+## Project Memory
 
-When the interview completes, a GIF is written to the current directory:
+Every spec and execution result is automatically recorded in `.gestalt/memory.json` at your repo root.
 
+```json
+{
+  "specHistory": [
+    { "specId": "...", "goal": "Build a user auth system", "sourceType": "text" }
+  ],
+  "executionHistory": [],
+  "architectureDecisions": []
+}
 ```
-user-auth-interview-20260327.gif
-```
 
-The filename is generated by the LLM from the interview topic (kebab-case) plus a `YYYYMMDD` date stamp. No external binaries are required — recording uses `gifencoder` and `jimp` only.
+**Commit it.** `.gestalt/memory.json` is plain JSON. Teammates inherit all prior decisions on `git pull`.
+
+**Context injection.** Prior goals and architecture decisions are automatically injected into the next spec prompt.
 
-**Resuming an interrupted session:** If a session is interrupted mid-recording, restarting the same session automatically detects the `.frames` file and continues where it left off. Temporary frame data is stored at `.gestalt/recordings/{sessionId}.frames` and deleted once the GIF is written.
+**User profile.** Personal preferences are stored in `~/.gestalt/profile.json` and are never committed.
 
 ---
 
 ## Configuration
 
-Generate a `gestalt.json` with IDE autocompletion support:
+Generate a `gestalt.json` with IDE autocomplete support:
 
 ```bash
 npx @tienne/gestalt setup
@@ -536,23 +551,22 @@ npx @tienne/gestalt setup
 
 **Config priority** (highest → lowest): code overrides → shell env vars → `.env` → `gestalt.json` → built-in defaults
 
-### Multi-Provider Configuration (LLM Tiers)
+### Multi-Provider LLM Tiers
 
-Gestalt supports routing LLM calls by task complexity across three tiers: **frugal**, **standard**, and **frontier**.
+Route LLM calls by task complexity across three tiers:
 
 | Tier | Purpose | Example models |
 |------|---------|---------------|
 | **frugal** | Lightweight tasks — scoring, classification, short responses | `llama3.2`, `claude-haiku` |
 | **standard** | General tasks — interviews, spec generation, execution | `claude-sonnet-4-20250514` |
-| **frontier** | High-complexity reasoning — architecture, code review, evolution loop | `claude-opus-4-20250514` |
+| **frontier** | High-complexity reasoning — architecture, code review, evolution | `claude-opus-4-20250514` |
 
-Mix providers freely. The example below uses Anthropic for standard/frontier and a local Ollama model for frugal tasks:
+Mix providers freely. This example uses Anthropic for standard/frontier and a local Ollama model for frugal tasks:
 
 ```json
 {
   "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
   "llm": {
-    "apiKey": "",
     "model": "claude-sonnet-4-20250514",
     "frugal": {
       "provider": "openai",
@@ -572,16 +586,14 @@ Mix providers freely. The example below uses Anthropic for standard/frontier and
 }
 ```
 
-> If no tiers are configured, all tiers fall back to the top-level `llm.apiKey` + `llm.model` with the Anthropic adapter — fully backward-compatible.
-
-Invalid values emit a warning and fall back to defaults.
+If no tiers are configured, all tiers fall back to the top-level `llm.model` with the Anthropic adapter — fully backward-compatible.
 
 ### Environment Variables
 
-| Variable | Config Path | Default | Description |
+| Variable | Config path | Default | Description |
 |----------|-------------|---------|-------------|
 | `ANTHROPIC_API_KEY` | `llm.apiKey` | `""` | Required only for CLI direct mode |
-| `GESTALT_MODEL` | `llm.model` | `claude-sonnet-4-20250514` | LLM model (provider-backed mode) |
+| `GESTALT_MODEL` | `llm.model` | `claude-sonnet-4-20250514` | LLM model |
 | `GESTALT_RESOLUTION_THRESHOLD` | `interview.resolutionThreshold` | `0.8` | Interview completion threshold |
 | `GESTALT_MAX_ROUNDS` | `interview.maxRounds` | `10` | Max interview rounds |
 | `GESTALT_DRIFT_THRESHOLD` | `execute.driftThreshold` | `0.3` | Task drift detection threshold |
@@ -608,9 +620,6 @@ Invalid values emit a warning and fall back to defaults.
 
 ## Architecture
 
-![Gestalt Architecture](./docs/architecture.png)
-_(Diagram coming soon.)_
-
 ```
 Claude Code (you)
      │
@@ -620,7 +629,7 @@ Claude Code (you)
 │                                  │
 │  Interview Engine                │
 │  ├─ GestaltPrincipleSelector     │
-│  ├─ ResolutionScorer              │
+│  ├─ ResolutionScorer             │
 │  ├─ SessionManager               │
 │  └─ ContextCompressor            │
 │                                  │
@@ -650,6 +659,13 @@ Claude Code (you)
 └──────────────────────────────────┘
 ```
 
+**Further reading:**
+
+- [MCP Reference](./docs/mcp-reference.md) — all tools, parameters, and action schemas
+- [Getting Started](./docs/getting-started.md) — 5-minute walkthrough
+- [Configuration Reference](./docs/configuration.md) — full config options
+- [Code Knowledge Graph](./docs/code-graph.md) — static analysis and blast-radius
+
 ---
 
 ## License

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",