autonomous-flow-daemon 1.1.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.5.0] - 2026-04-02 — "Trust-Builder"
+
+> The immune system now speaks. Three pillars that make afd's defenses visible, self-improving, and smarter.
+
+### Added
+
+- **Hologram L1 — Import-Based Semantic Compression**
+  - New optional `contextFile` parameter on `afd_hologram` MCP tool and `/hologram` HTTP endpoint
+  - `extractImportedSymbols()` function: regex fast-path parsing of named imports, default imports, and namespace imports from the context file
+  - L1 filtering in `generateHologram()`: directly imported symbols receive full type signatures; non-imported exports are reduced to name-only stubs with guide text `// details omitted — read directly if needed`
+  - Namespace imports (`import * as X`) trigger full L0 hologram (safe default, no false filtering)
+  - Silent fallback to L0 when `contextFile` is missing, unreadable, or yields zero import results
+  - Compression target: 85%+ with contextFile (vs ~80% L0 baseline)
+  - L1 is MCP/HTTP path only — S.E.A.M hot path remains L0 to protect the 270ms budget
+
+- **Antibody Passive Defense — Mistake History Injection**
+  - New `mistake_history` SQLite table: `file_path`, `mistake_type`, `description` (max 200 chars), `antibody_id`, `timestamp`
+  - Indexes on `file_path` and `timestamp` for sub-millisecond query performance
+  - Write-through cache: `mistakeCache: Map<string, MistakeEntry[]>` loaded on daemon startup, updated on every insert
+  - Per-file cap of 5 most recent entries enforced at write time
+  - 30-day TTL purge on daemon startup (consistent with `telemetry` table pattern)
+  - Direct DB insert on auto-heal events (not via HTTP POST): records `mistake_type` from `symptom.patternType` and `description` from `symptom.title`
+  - New GET `/mistake-history?file=<path>` HTTP endpoint (returns max 5 entries, most recent first)
+  - `pastMistakes` field injected into `afd diagnose --format a2a` output on both the healthy path (proactive warning) and the auto-heal path (reactive)
+  - `pastMistakes` is omitted entirely when no history exists (zero token overhead)
+  - Path normalization: `file_path` stored with forward slashes (cross-platform safe)
+
+- **HUD Defense Counter + Reasons**
+  - `/mini-status` endpoint enhanced with `total_defenses: number` and `defense_reasons: string[]` (in-memory only, no DB query — always under 200ms)
+  - `defense_reasons` derived from in-memory `state.autoHealLog` (capped at 100 entries), returning up to 3 most recent unique `mistake_type` values
+  - Status bar format: `[afd] {N}건 방어 ({reason1}, {reason2}, ...)` when defenses exist; `[afd] ON` when none
+  - Existing `healed_count` and `last_healed` fields preserved for backward compatibility
+
+### Fixed
+
+- **Windows path normalization in `assertInsideWorkspace()`**: backslash (`\`) separators in Windows paths are now normalized to forward slashes before workspace boundary checks, fixing false-positive "outside workspace" errors on Windows
+
+---
+
 ## [1.0.0] - 2026-03-31 — "The Immortal Flow"
 
 > [afd] 🛡️ AI agent deleted '.claudeignore' | 🩹 Self-healed in 184ms | Context preserved.

package/README.ko.md

@@ -6,15 +6,15 @@
 <p align="center"><strong>AI가 스스로 고치는 개발 환경. 복구까지 단 0.2초.</strong></p>
 
 <p align="center">
-  <img src="demo.gif" width="850" alt="afd demo" style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
-  <br>
-  <br>
-  <b>🛡️ 불멸의 컨텍스트 흐름:</b> 
-  <em>"afd는 지연 시간이 거의 없는 즉각적인 복구를 통해, AI 개발 흐름이 끊기지 않도록 보호하고 토큰 비용을 혁신적으로 절감합니다."</em>
+  <a href="https://github.com/dotoricode/autonomous-flow-daemon">
+    <img src="demo.gif" width="850" alt="afd demo" style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
+  </a>
 </p>
 
+---
+
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.1.0-blue?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-1.6.0-blue?style=flat-square" alt="version" />
   <a href="https://www.npmjs.com/package/autonomous-flow-daemon"><img src="https://img.shields.io/npm/v/autonomous-flow-daemon?style=flat-square&logo=npm&color=cb0000" alt="npm" /></a>
   <img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square&logo=bun" alt="Bun" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" />
@@ -29,48 +29,75 @@
 
 ## 왜 afd인가?
 
-> [afd] 🛡️ AI가 '.claudeignore'를 삭제했습니다 | 🩹 184ms 만에 자가 복구 완료 | 컨텍스트 보존됨.
+> [afd] AI가 '.claudeignore'를 삭제했습니다 | 184ms 만에 자가 복구 완료 | 컨텍스트 보존됨.
 
-당신은 지금 몰입의 정점에 있습니다. AI 에이전트가 실수로 설정 파일을 삭제하거나, 훅 파일을 망가뜨립니다. `afd` 없이는 작업을 멈추고, 원인을 진단하고, 직접 고쳐야 합니다: **30분이 날아갑니다**.
+AI 에이전트가 실수로 설정 파일을 삭제하거나, 훅 파일을 망가뜨립니다. `afd` 없이는 작업을 멈추고, 원인을 진단하고, 직접 고쳐야 합니다: **30분이 날아갑니다**.
 
-`afd`가 있다면, 데몬이 10ms 만에 이상을 감지하고, 184ms 안에 복구를 완료합니다. **당신은 아무것도 몰랐습니다.**
+`afd`가 있다면, 데몬이 10ms 만에 이상을 감지하고, 184ms 안에 복구를 완료합니다. **당신은 아무것도 몰랐습니다.** Bun 기반 네이티브 데몬으로 CPU 0.1% 미만, 메모리 ~40MB만 사용합니다.
 
 | 상황 | afd 없을 때 | afd 있을 때 |
 |:-----|:------------|:------------|
 | AI가 `.claudeignore` 삭제 | 30분 수동 복구 | **0.2초 자동 치유** |
 | 훅 파일 손상 | 훅 재주입, 세션 재시작 | **백그라운드 자동 복구** |
 | `git checkout`으로 파일 50개 동시 변경 | AI가 폭주 | **대규모 이벤트 억제기 작동** |
-| 신규 팀원, 환경 설정 없음 | 구전으로 전달 | **`afd sync`로 즉시 백신 접종** |
+| AI가 대용량 파일 8개 읽기 (114KB) | ~28,600 토큰 소비 | **홀로그램으로 ~1,700 토큰 (94% 절감)** |
 
 ---
 
-## 🚀 제로-간섭 약속 (Zero-Interference Promise)
-
-`afd`는 개발 흐름을 방해하는 것이 아니라, 보호하기 위해 설계되었습니다.
+## 주요 기능
 
-* **성능 저하 없음:** Bun 기반의 네이티브 백그라운드 데몬으로 실행되어, **CPU 점유율 0.1% 미만**, **메모리 약 40MB**만을 사용합니다.
-* **매끄러운 복구:** **밀리초 미만(Sub-millisecond)의 복구 속도**를 통해, Claude Code가 컨텍스트 오류를 인지하기도 전에 파일을 원래대로 되돌려 놓습니다.
-* **비침습적 설계:** `afd`는 OS 계층에서 파일 시스템 이벤트만 관찰합니다. Claude Code의 내부 실행이나 API 호출을 가로채거나 수정하지 않습니다.
+| 기능 | 설명 |
+|:-----|:-----|
+| **S.E.A.M 자율 치유** | 파일 삭제/손상을 감지하고 270ms 이내에 복구 |
+| **홀로그램 추출** | MCP를 통해 80-93% 가벼운 타입 뼈대를 AI 에이전트에 제공, 토큰 비용 대폭 절감 |
+| **스마트 파일 리더** | `afd_read` — 작은 파일은 원본, 큰 파일은 자동 홀로그램 압축; 라인 범위 읽기 지원 |
+| **워크스페이스 맵** | `afd://workspace-map` — 전체 파일 트리 + export 시그니처를 한 번에 제공 |
+| **홀로그램 L1** | import 기반 정밀 압축 — 실제 import된 심볼만 전체 시그니처 유지 (85%+ 절감) |
+| **격리 구역** | 복구 전 손상된 파일을 `.afd/quarantine/`에 백업 |
+| **자가 진화** | 격리된 실패 사례를 분석하여 `afd-lessons.md`에 방지 규칙 자동 생성 |
+| **실수 이력 주입** | PreToolUse 훅이 파일 편집 전 과거 실수를 경고로 주입 |
+| **더블탭 감지** | 한 번 삭제 = 자동 복구; 30초 내 재삭제 = 사용자 의도로 존중 |
+| **백신 네트워크** | `afd sync`로 학습된 항체를 팀 전체에 전파 |
+| **MCP 통합** | `afd mcp install`로 MCP 서버 자동 등록 |
+| **HUD 방어 카운터** | 상태 표시줄에 방어 건수와 사유 요약을 한눈에 표시 |
 
 ---
 
-## ✨ 주요 기능 (v1.1.0)
+## 토큰 절약 — 실측 데이터
 
-| 기능 | 설명 |
-|:-----|:-----|
-| **🛡️ S.E.A.M 자율 치유** | 파일 삭제를 감지하고 270ms 이내에 복구 — AI 에이전트가 눈치채기도 전에 |
-| **🔍 스마트 탐색** | `.claude/`, `.cursorrules`, `.mcp.json` 등 AI 설정 파일을 자동 감지 — 설정 필요 없음 |
-| **🏥 위트 있는 닥터** | 실시간 가치 추적: 절약한 토큰, 시간, 비용을 매 치유마다 위트 있게 알려줍니다 |
-| **🌐 자동 다국어** | 시스템 언어에 따라 한국어/영어를 자동 전환. 직접 설정도 가능: `afd lang ko` |
-| **🧬 더블탭 감지** | 실수와 의도를 구분 — 한 번 지우면 복구, 30초 내 다시 지우면 삭제를 존중 |
-| **💉 백신 네트워크** | `afd sync`로 학습된 항체를 팀 전체에 전파 |
-| **📊 홀로그램 추출** | AI 에이전트에게 80%+ 가벼운 파일 뼈대를 제공해 토큰 비용 절감 |
+홀로그램 시스템은 AI 기반 개발에서 afd의 가장 큰 가치입니다. 실제 세션에서 측정한 결과입니다:
 
----
+### 세션 스냅샷 (실제 코딩 세션에서 측정)
+
+| 지표 | 값 |
+|:-----|:---|
+| 홀로그램 요청 횟수 | 8회 |
+| 대상 파일 총 크기 | ~114.5 KB (8개 파일, 평균 14.3 KB) |
+| 원본 토큰 비용 | ~28,600 토큰 |
+| 홀로그램 압축 후 | ~1,700 토큰 |
+| **절약된 토큰** | **~26,900 토큰 (94% 절감)** |
 
-## 🚀 명령어 한 줄로 끝나는 경험
+### 규모별 효과
+
+```
+세션 사용 토큰 (ctx ~15%):  ~150,000  ████████████████
+홀로그램 절약 토큰:          ~26,900  ██░░░░░░░░░░░░░░  (세션의 18%)
+```
 
-> **"더 이상의 설정 삽질은 없습니다. 완전한 방어 환경을 구축하세요."**
+ctx 50% 이상에서는 파일 읽기가 토큰 예산의 대부분을 차지합니다. 홀로그램 없이 대용량 파일 8개를 읽으면 매번 ~28.6K 토큰이 소비됩니다. 홀로그램을 사용하면 **각 파일을 원본의 1/16 비용**으로 읽을 수 있으며, 반복 읽기가 많을수록 격차는 더 벌어집니다.
+
+### 토큰 최적화 3단계
+
+| 레이어 | 도구 | 절감률 | 방식 |
+|:-------|:-----|:-------|:-----|
+| **L0 홀로그램** | `afd_hologram` | 80%+ | 함수 본문 제거, 타입 시그니처만 보존 |
+| **L1 홀로그램** | `afd_hologram` + `contextFile` | 85%+ | import된 심볼만 필터링 |
+| **스마트 리더** | `afd_read` | 자동 | 10KB 미만은 원본, 이상은 자동 홀로그램 |
+| **워크스페이스 맵** | `afd://workspace-map` | N/A | 프로젝트 전체 구조를 한 번에 파악 |
+
+---
+
+## 명령어 한 줄로 시작
 
 ```bash
 npx @dotoricode/afd start
@@ -84,25 +111,22 @@ bun link && afd start
 
 이게 전부입니다. 나머지는 `afd`가 알아서 처리합니다:
 
-- **자동 훅(Hook) 주입** — Claude Code의 `PreToolUse` 훅을 자동으로 설치합니다. 더 이상 `.json` 파일을 직접 수정하며 고생하지 마세요.
-- **초고속 실시간 감시** — `.claude/`, `CLAUDE.md`, `.cursorrules`, `.claudeignore`, `.gitignore` 핵심 파일을 10ms 단위로 모니터링합니다.
-- **배경 자율 치유** — 파일이 삭제되거나 손상되면 **S.E.A.M 사이클**이 조용히 복구합니다. 사용자가 눈치채기도 전에 모든 상황은 종료됩니다.
+- **자동 훅 주입** — Claude Code의 `PreToolUse` 훅을 자동으로 설치합니다.
+- **초고속 실시간 감시** — 핵심 설정 파일을 10ms 단위로 모니터링합니다.
+- **배경 자율 치유** — S.E.A.M 사이클이 조용히 복구합니다.
 
 ```
 $ afd start
-  🛡️ 데몬 시작 (pid 4812, port 52413)
-  🛡️ 스마트 탐색 중: AI 컨텍스트 대상 7개 감시 시작
-  Targets: .claude/, CLAUDE.md, .cursorrules, .claudeignore, .gitignore, mcp-config.json, .mcp.json
-  ✅ .claude/hooks.json에 감시 훅 주입 완료
+  데몬 시작 (pid 4812, port 52413)
+  스마트 탐색: AI 컨텍스트 대상 7개 감시 시작
+  .claude/hooks.json에 감시 훅 주입 완료
 ```
 
-> `afd start`를 치고 나면 그냥 잊어버리세요. 그것이 우리가 추구하는 최고의 UX입니다.
-
 ---
 
-## 🧠 지능형 치유 엔진: S.E.A.M 사이클
+## S.E.A.M 사이클
 
-`afd`의 핵심 로직입니다. 모든 파일 변화는 다음의 4단계를 거쳐 즉시 정제됩니다:
+모든 파일 이벤트는 4단계를 거쳐 처리됩니다:
 
 ```mermaid
 graph LR
@@ -118,149 +142,94 @@ graph LR
 
 | 단계 | 주요 동작 | 처리 속도 |
 |:------|:-----|:-----|
-| **Sense** | Chokidar 와처가 파일의 생성, 변경, 삭제를 즉각 감지 | < 10ms |
-| **Extract** | 면역 엔진이 내장된 3단계 건강 검진 실행 (IMM-001..003) | < 5ms |
-| **Adapt** | SQLite(WAL 모드) DB에서 최적의 복구 항체(Antibody) 매칭 | < 1ms |
-| **Mutate** | RFC 6902 JSON-Patch 기술로 원본 파일을 완벽히 복원 | < 25ms |
+| **Sense** | Chokidar 와처가 파일 생성, 변경, 삭제를 즉각 감지 | < 10ms |
+| **Extract** | 홀로그램(타입 뼈대) 생성 + 건강 검진 실행 | < 5ms |
+| **Adapt** | 증상-항체 매칭, 손상 파일 격리, 수정 전략 선택 | < 1ms |
+| **Mutate** | RFC 6902 JSON-Patch로 원본 파일 복원 | < 25ms |
 
-> **최종 성적표:** 파일 삭제 감지부터 복구 완료까지 **270ms 미만**.
+> 전체 사이클: 파일 삭제 감지부터 복구 완료까지 **270ms 미만**.
 
-### 감시 대상 (Watch Targets)
-
-아래 파일들이 실시간 감시됩니다. 면역 파일(IMM-*)은 삭제 시 자동으로 복구됩니다:
-
-| 대상 | 유형 | 항체 | 자동 복구 |
-|:-----|:-----|:-----|:----------|
-| `.claude/` | 디렉토리 | IMM-002 (`hooks.json`) | ✅ |
-| `CLAUDE.md` | 파일 | IMM-003 | ✅ |
-| `.claudeignore` | 파일 | IMM-001 | ✅ |
-| `.cursorrules` | 파일 | — | 이벤트 로깅만 |
-| `.gitignore` | 파일 | — | 이벤트 로깅만 |
-| `mcp-config.json` | 파일 | — | 🔍 스마트 탐색 |
-| `.mcp.json` | 파일 | — | 🔍 스마트 탐색 |
-| `.ai/` | 디렉토리 | — | 🔍 스마트 탐색 |
-| `.windsurfrules` | 파일 | — | 🔍 스마트 탐색 |
+---
 
-> 항체는 **데몬 시작 시 자동으로 학습**되며, **파일 변경 시마다 갱신**됩니다 — 복구 시 항상 최신 내용이 반영됩니다.
->
-> 🔍 **스마트 탐색**은 시작 시 12개 이상의 AI 설정 패턴을 0.1ms 미만으로 스캔하여, 발견된 파일을 자동으로 감시 목록에 추가합니다.
+## 명령어
+
+| 명령어 | 설명 |
+|:-------|:-----|
+| `afd start` | 스마트 탐색 + 데몬 가동 + 훅/MCP 자동 주입 |
+| `afd stop` | 근무 요약 리포트 + 안전한 종료 (`--clean`으로 훅/MCP 제거) |
+| `afd score` | 진화/홀로그램 통계 포함 건강 대시보드 |
+| `afd fix` | 홀로그램 컨텍스트 기반 진단 및 항체 학습 |
+| `afd sync` | 백신 페이로드 추출/가져오기 (`--push`, `--pull`, `--remote <url>`) |
+| `afd restart` | 종료 후 재시작 |
+| `afd status` | 빠른 건강 확인 — 데몬, 훅, MCP, 방어 현황 |
+| `afd doctor` | 종합 건강 분석 + 자동 수정 권고 |
+| `afd evolution` | 격리된 실패 분석 및 방지 규칙 생성 |
+| `afd mcp install` | MCP 서버를 프로젝트 + 글로벌 설정에 등록 |
+| `afd vaccine` | 커뮤니티 항체 조회, 설치, 발행 |
+| `afd lang` | 표시 언어 전환 (`afd lang ko` / `afd lang en`) |
 
 ---
 
-## 🛠️ 명령어
+## 고급 기능
 
-복잡한 건 빼고, 꼭 필요한 것만 담았습니다.
+### Double-Tap 휴리스틱
 
-| 명령어 | 역할 | 핵심 지능 |
-|:-------|:-----|:----------|
-| `afd start` | **시동** | 스마트 탐색 + 데몬 가동 + 자동 훅 주입 |
-| `afd fix` | **수술** | 현재 프로젝트 진단 및 새로운 항체 학습 |
-| `afd score` | **대시보드** | 다국어 건강 검진 리포트 & 가치 분석 |
-| `afd sync` | **전파** | 학습된 항체를 백신 파일로 추출 (팀 공유용) |
-| `afd lang` | **언어** | 표시 언어 전환 (`afd lang ko` / `afd lang en`) |
-| `afd stop` | **종료** | 근무 요약 리포트 + 안전한 종료 |
-
----
-
-## 📊 실시간 대시보드: `afd score`
+`afd`는 **실수**와 **의도**를 구분합니다:
 
 ```
-┌──────────────────────────────────────────────┐
-│  afd score — 프로젝트 건강 검진              │
-├──────────────────────────────────────────────┤
-│  에코시스템   : Claude Code                  │
-├──────────────────────────────────────────────┤
-│  가동 시간    : 1h 23m                       │
-│  이벤트       : 156                          │
-│  감지된 파일  : 8                            │
-├──────────────────────────────────────────────┤
-│  면역 시스템                                 │
-│  ──────────────────────────────              │
-│  항체 수      : 7                            │
-│  방어 레벨    : 철통 방어                    │
-│  자동 치유    : 3건 백그라운드 치유됨        │
-├──────────────────────────────────────────────┤
-│  📈 전달된 가치                              │
-│  ──────────────────────────────              │
-│  절약한 토큰  : ~2.9K                        │
-│  아낀 시간    : ~40 min                      │
-│  절감 비용    : ~$0.01                       │
-├──────────────────────────────────────────────┤
-│  🗣️ 면역 체계 이상 무. 오늘도 한 건         │
-│     해결했습니다 💪                          │
-└──────────────────────────────────────────────┘
+$ rm .claudeignore            # 1차 삭제 -> 즉시 복구
+$ rm .claudeignore            # 30초 내 재삭제 -> "진짜 지우고 싶구나?"
+  [afd] 사용자 의도 확인. 항체 IMM-001 휴면 전환. 삭제를 존중합니다.
 ```
 
-> `afd lang en` 을 실행하면 대시보드의 모든 레이블이 영어로 전환됩니다.
-
----
-
-## 💎 고도로 설계된 안전 장치
-
-### Double-Tap 휴리스틱 (의도와 실수의 구분)
+| 시나리오 | 대응 |
+|:---------|:-----|
+| 단일 삭제 (실수) | 자동 복구 + 첫 탭 기록 |
+| 30초 내 재삭제 (의도) | 항체 휴면, 삭제 존중 |
+| 1초 내 3건 이상 (git checkout) | 대규모 이벤트 감지, 억제 일시 정지 |
 
-`afd`는 바보처럼 무조건 되살리지 않습니다. 사용자의 **진짜 의도**를 읽습니다:
+### 백신 네트워크
 
 ```bash
-$ rm .claudeignore      # 1차 삭제: "실수인가 보군." → 즉시 복구
-$ rm .claudeignore      # 30초 내 재삭제: "진짜 지우고 싶구나?"
-  🫡 [afd] 사용자 의도 확인. 항체 IMM-001 휴면 전환. 삭제를 존중합니다.
+afd sync              # .afd/global-vaccine-payload.json으로 추출
+afd sync --push       # 원격으로 백신 전파
+afd sync --pull       # 원격에서 백신 수신
 ```
 
-- **실수 방어:** 한 번의 삭제는 0.2초 만에 즉시 복구합니다.
-- **의도 존중:** 30초 내에 같은 파일을 또 지우면 사용자의 확고한 의지로 판단해 복구를 멈춥니다.
-- **Git 쇼크 방지:** `git checkout`처럼 수많은 파일이 한꺼번에 바뀌는 상황(1초 내 3개 이상)은 '대규모 이벤트'로 자동 인식하여 과도한 치유 동작을 멈춥니다.
-
-### 백신 네트워크 (팀 전파)
+페이로드는 정제되어 있어 기밀 정보가 포함되지 않습니다.
 
-나만 똑똑해지는 게 아닙니다. 내가 발견한 해결책을 팀원 모두에게 전파하세요:
+### 자가 진화
 
 ```bash
-afd sync
-# → .afd/global-vaccine-payload.json 생성
+afd evolution
 ```
-이 파일은 정제되어 있어 기밀 정보가 섞이지 않습니다. 다른 프로젝트에 넣기만 하면 `afd`가 해당 프로젝트의 면역력을 즉시 이식받습니다.
 
-### Hologram 추출 (토큰 다이어트)
-
-AI 에이전트가 파일 내용을 요구할 때, `afd`는 **뼈대만 남긴 초경량 요약본**을 제공합니다. 주석과 긴 함수 본문은 걷어내고 타입 정의와 구조만 전달하여 **토큰 비용을 80% 이상 절감**합니다.
+격리된 실패 사례를 분석하고 `afd-lessons.md`에 방지 규칙을 자동 기록합니다. AI 에이전트는 면역 파일 편집 전에 이를 읽어 과거의 실패를 미래의 예방책으로 전환합니다.
 
 ---
 
-## 🔌 Plugin / MCP 설정
-
-`afd`를 **Model Context Protocol (MCP) 서버**로 등록하면 Claude Code가 시작될 때 데몬이 자동으로 실행됩니다.
+## MCP 설정
 
-### 자동 설정 (권장)
+`afd`가 제공하는 MCP 도구와 리소스:
 
-Claude Code MCP 설정(`~/.claude/mcp.json` 또는 프로젝트 `.mcp.json`)에 추가하세요:
+| MCP 도구 | 용도 |
+|:---------|:-----|
+| `afd_read` | 스마트 파일 리더 — 작은 파일은 원본, 큰 파일은 자동 홀로그램, 라인 범위 지원 |
+| `afd_hologram` | TS/JS 파일의 토큰 효율적 타입 뼈대 (80%+ 절감) |
+| `afd_diagnose` | 건강 진단 + 홀로그램 컨텍스트 |
+| `afd_score` | 런타임 통계: 가동시간, 치유 횟수, 홀로그램 절감률 |
 
-```json
-{
-  "mcpServers": {
-    "afd": {
-      "command": "bun",
-      "args": ["run", "src/cli.ts", "start"]
-    }
-  }
-}
-```
-
-### 수동 실행
+| MCP 리소스 | 용도 |
+|:-----------|:-----|
+| `afd://workspace-map` | 전체 파일 트리 + export 시그니처를 한 번에 제공 |
 
 ```bash
-afd start   # 백그라운드 데몬 시작 및 훅 자동 주입
-```
-
-등록 후 Claude Code 상태 표시줄에서 실시간으로 확인할 수 있습니다:
-
-```
-🛡️ afd: ON | 🩹 3 Healed | last: IMM-003
+afd mcp install    # .mcp.json + ~/.claude.json에 자동 등록
 ```
 
 ---
 
-## 🛠️ 기술 스택
+## 기술 스택
 
 | 계층 | 기술 | 선택 이유 |
 |:-----|:-----|:----------|
@@ -269,11 +238,10 @@ afd start   # 백그라운드 데몬 시작 및 훅 자동 주입
 | 파일 감시 | **Chokidar** | 크로스플랫폼, 실전 검증된 와처 |
 | 패칭 | **RFC 6902 JSON-Patch** | 결정론적이고 조합 가능한 파일 변이 |
 | CLI | **Commander.js** | 표준적이고 예측 가능한 커맨드 파싱 |
-| 다국어 | **자체 i18n 엔진** | 외부 의존성 없이 0.01ms로 언어 전환 |
 
 ---
 
-## 📦 설치 및 시작하기
+## 설치
 
 ```bash
 # Bun 사용 권장
@@ -281,26 +249,18 @@ bun install
 bun link
 afd start
 
-# 설치 없이 바로 실행하기 (npx)
+# 설치 없이 바로 실행 (npx)
 npx @dotoricode/afd start
 ```
 
 ### 환경 요구 사항
-- **Bun** >= 1.0
-- **OS**: Windows, macOS, Linux 지원
-- **호환 환경**: Claude Code, Cursor 등 (생태계 자동 감지)
-
----
 
-## 🛡️ 안도감을 주는 UX
-
-`afd`의 목표는 명확합니다.
-
-> **"설정 파일 하나 날아가서 30분을 허비하는 그런 날은 이제 끝났습니다."**
-
-당신은 코드에만 집중하세요. 프로젝트 환경의 건강은 `afd`가 24시간 백그라운드에서 지켜드립니다.
+- **Bun** >= 1.0
+- **OS**: Windows, macOS, Linux
+- **호환 환경**: Claude Code, Cursor, Windsurf, Codex (생태계 자동 감지)
 
 ---
 
 ## 라이선스
+
 MIT