From 49c395cd95a4a01609900a8296693a3958a3c858 Mon Sep 17 00:00:00 2001
From: Kobe <dev.skyachieve91@gmail.com>
Date: Tue, 15 Sep 2026 05:45:56 +0900
Subject: [PATCH 1/3] docs: update Korean README translation

This PR updates docs/translations/README.ko-KR.md using the English README on the v8 branch.

It expands the Korean documentation for installation, supported platforms, commands, environment variables, troubleshooting, and contributing, while improving the wording for Korean readers.

This change is limited to documentation.
---
 docs/translations/README.ko-KR.md | 970 +++++++++++++++++++++++++-----
 1 file changed, 827 insertions(+), 143 deletions(-)

diff --git a/docs/translations/README.ko-KR.md b/docs/translations/README.ko-KR.md
index 0fa46a211d..74361f34c4 100644
--- a/docs/translations/README.ko-KR.md
+++ b/docs/translations/README.ko-KR.md
@@ -2,281 +2,965 @@
 
 🇺🇸 [English](../../README.md) | 🇨🇳 [简体中文](README.zh-CN.md) | 🇯🇵 [日本語](README.ja-JP.md) | 🇰🇷 [한국어](README.ko-KR.md) | 🇩🇪 [Deutsch](README.de-DE.md) | 🇫🇷 [Français](README.fr-FR.md) | 🇪🇸 [Español](README.es-ES.md) | 🇮🇳 [हिन्दी](README.hi-IN.md) | 🇧🇷 [Português](README.pt-BR.md) | 🇷🇺 [Русский](README.ru-RU.md) | 🇸🇦 [العربية](README.ar-SA.md) | 🇮🇹 [Italiano](README.it-IT.md) | 🇵🇱 [Polski](README.pl-PL.md) | 🇳🇱 [Nederlands](README.nl-NL.md) | 🇹🇷 [Türkçe](README.tr-TR.md) | 🇺🇦 [Українська](README.uk-UA.md) | 🇻🇳 [Tiếng Việt](README.vi-VN.md) | 🇮🇩 [Bahasa Indonesia](README.id-ID.md) | 🇸🇪 [Svenska](README.sv-SE.md) | 🇬🇷 [Ελληνικά](README.el-GR.md) | 🇷🇴 [Română](README.ro-RO.md) | 🇨🇿 [Čeština](README.cs-CZ.md) | 🇫🇮 [Suomi](README.fi-FI.md) | 🇩🇰 [Dansk](README.da-DK.md) | 🇳🇴 [Norsk](README.no-NO.md) | 🇭🇺 [Magyar](README.hu-HU.md) | 🇹🇭 [ภาษาไทย](README.th-TH.md) | 🇺🇿 [Oʻzbekcha](README.uz-UZ.md) | 🇹🇼 [繁體中文](README.zh-TW.md)
 
-[![CI](https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v3)](https://github.com/safishamsi/graphify/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/graphifyy)](https://pypi.org/project/graphifyy/)
-[![Sponsor](https://img.shields.io/badge/sponsor-safishamsi-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/safishamsi)
+<p align="center">
+  <a href="https://graphify.com"><img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/graphify-card.png" width="300" height="214" alt="Graphify"/></a>
+</p>
 
-**AI 코딩 어시스턴트를 위한 스킬.** Claude Code, Codex, OpenCode, OpenClaw, Factory Droid, 또는 Trae에서 `/graphify`를 입력하면 파일을 읽고 지식 그래프를 구축하여, 미처 몰랐던 구조를 보여줍니다. 코드베이스를 더 빠르게 이해하고, 아키텍처 결정의 "이유"를 찾아보세요.
+<p align="center">
+  <a href="https://trendshift.io/repositories/25296?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-25296" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/25296" alt="Graphify-Labs%2Fgraphify | Trendshift" width="250" height="55"/></a>
+</p>
 
-완전한 멀티모달 지원. 코드, PDF, 마크다운, 스크린샷, 다이어그램, 화이트보드 사진, 심지어 다른 언어로 된 이미지까지 — graphify는 Claude Vision을 사용하여 이 모든 것에서 개념과 관계를 추출하고 하나의 그래프로 연결합니다. tree-sitter AST를 통해 20개 언어를 지원합니다(Python, JS, TS, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia).
+<div align="center">
+<details><summary><b>다른 언어로 읽기</b></summary>
 
-> Andrej Karpathy는 논문, 트윗, 스크린샷, 메모를 모아두는 `/raw` 폴더를 관리합니다. graphify는 바로 그 문제에 대한 답입니다 — 원본 파일을 직접 읽는 것 대비 쿼리당 토큰 소비가 71.5배 적고, 세션 간에 영속적이며, 발견한 것과 추측한 것을 정직하게 구분합니다.
+🇺🇸 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/README.md">English</a> | 🇨🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.zh-CN.md">简体中文</a> | 🇯🇵 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ja-JP.md">日本語</a> | 🇰🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ko-KR.md">한국어</a> | 🇩🇪 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.de-DE.md">Deutsch</a> | 🇫🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fr-FR.md">Français</a> | 🇪🇸 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.es-ES.md">Español</a> | 🇮🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.hi-IN.md">हिन्दी</a> | 🇧🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.pt-BR.md">Português</a> | 🇷🇺 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ru-RU.md">Русский</a> | 🇸🇦 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ar-SA.md">العربية</a> | 🇮🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fa-IR.md">فارسی</a> | 🇮🇹 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.it-IT.md">Italiano</a> | 🇵🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.pl-PL.md">Polski</a> | 🇳🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.nl-NL.md">Nederlands</a> | 🇹🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.tr-TR.md">Türkçe</a> | 🇺🇦 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.uk-UA.md">Українська</a> | 🇻🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.vi-VN.md">Tiếng Việt</a> | 🇮🇩 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.id-ID.md">Bahasa Indonesia</a> | 🇸🇪 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.sv-SE.md">Svenska</a> | 🇬🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.el-GR.md">Ελληνικά</a> | 🇷🇴 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ro-RO.md">Română</a> | 🇨🇿 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.cs-CZ.md">Čeština</a> | 🇫🇮 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fi-FI.md">Suomi</a> | 🇩🇰 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.da-DK.md">Dansk</a> | 🇳🇴 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.no-NO.md">Norsk</a> | 🇭🇺 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.hu-HU.md">Magyar</a> | 🇹🇭 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.th-TH.md">ภาษาไทย</a> | 🇺🇿 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.uz-UZ.md">Oʻzbekcha</a> | 🇹🇼 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.zh-TW.md">繁體中文</a> | 🇵🇭 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fil-PH.md">Filipino</a> | 🇮🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.he-IL.md">עברית</a>
 
+</details>
+</div>
+
+<p align="center">
+  <a href="https://pypi.org/project/graphifyy/"><img src="https://img.shields.io/pypi/v/graphifyy" alt="PyPI"/></a>
+  <a href="https://pepy.tech/project/graphifyy"><img src="https://img.shields.io/pepy/dt/graphifyy?color=blue&label=downloads" alt="다운로드 수"/></a>
+  <a href="https://discord.gg/2DDrEgvZb4"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord"/></a>
+  <a href="https://www.youtube.com/@graphifylabs"><img src="https://img.shields.io/badge/YouTube-Graphify%20Labs-FF0000?style=flat&logo=youtube&logoColor=white" alt="YouTube"/></a>
+  <a href="https://www.linkedin.com/company/graphify-labs"><img src="https://img.shields.io/badge/LinkedIn-Graphify%20Labs-0077B5?logo=linkedin" alt="LinkedIn"/></a>
+  <a href="https://www.ycombinator.com/companies/graphify-labs"><img src="https://img.shields.io/badge/Y%20Combinator-S26-F0652F?style=flat&logo=ycombinator&logoColor=white" alt="YC S26"/></a>
+</p>
+
+<p align="center">
+  <b>graphify 플랫폼의 v1 정식 출시를 앞두고 얼리 액세스가 시작되었습니다: <a href="https://app.graphify.com/login">app.graphify.com</a></b>
+</p>
+
+AI 코딩 도우미에서 `/graphify`를 입력하면 프로젝트 전체(코드, 문서, PDF, 이미지, 동영상)를 **지식 그래프**로 만들어 줍니다. 이제 파일을 일일이 grep으로 검색하는 대신 **그래프에 질문**할 수 있습니다.
+
+- **코드 그래프는 무료로, 모든 처리는 로컬에서.** 코드는 tree-sitter의 추상 구문 트리(AST)로 파싱합니다. 같은 입력에는 같은 결과를 내며, LLM을 사용하지 않고 데이터도 컴퓨터 밖으로 전송하지 않습니다. (문서, PDF, 이미지, 동영상은 도우미의 모델이나 설정한 API 키를 사용해 의미를 분석합니다.)
+- **모든 연결에는 근거가 있습니다.** 각 연결에는 `EXTRACTED`(소스에 명시됨) 또는 `INFERRED`(graphify가 관계를 해석해 도출함) 태그가 붙어, 직접 추출한 정보와 추론한 정보를 구분할 수 있습니다.
+- **벡터 인덱스가 아닌 실제 그래프입니다.** 임베딩이나 벡터 저장소 없이 그래프를 직접 탐색합니다. 질문을 하거나, 두 요소 사이의 경로를 추적하거나, 특정 개념에 대한 설명을 확인할 수 있습니다.
+
+> 필요할 때만 실행하는 데서 나아가, 코드·문서·회의 전반의 정보를 백그라운드에서 계속 갱신하고 싶으신가요? **[graphify.com](https://graphify.com)**에서 바로 그런 서비스를 만들고 있습니다. 지금 **[app.graphify.com](https://app.graphify.com/login)**에서 얼리 액세스를 이용할 수 있습니다.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/graph-hero.png" alt="FastAPI 코드베이스를 힘 기반 레이아웃의 지식 그래프로 보여 주는 graphify의 대화형 graph.html. 탐지된 커뮤니티의 범례도 표시됩니다." width="900">
+</p>
+<p align="center">
+  <em>graphify로 시각화한 FastAPI 코드베이스입니다. 각 노드는 하나의 개념을, 색상은 탐지된 커뮤니티를 나타냅니다. graph.html에서 모든 요소를 클릭해 살펴볼 수 있습니다.</em>
+</p>
+
+**시작하기**(30초):
+
+```bash
+uv tool install graphifyy      # CLI 설치 (또는: pipx install graphifyy)
+graphify install               # AI 도우미에 스킬 등록
 ```
-/graphify .                        # 어떤 폴더든 동작 - 코드베이스, 노트, 논문, 무엇이든
+
+그런 다음 AI 도우미에서 다음을 입력합니다.
+
 ```
+/graphify .
+```
+
+이것으로 끝입니다. 다음 **파일 3개**가 생성됩니다.
 
 ```
 graphify-out/
-├── graph.html       인터랙티브 그래프 - 노드 클릭, 검색, 커뮤니티별 필터
-├── GRAPH_REPORT.md  갓 노드, 의외의 연결, 추천 질문
-├── graph.json       영속 그래프 - 몇 주 후에도 재읽기 없이 쿼리 가능
-└── cache/           SHA256 캐시 - 재실행 시 변경된 파일만 처리
+├── graph.html       브라우저에서 열어 노드를 클릭하고 필터링·검색
+├── GRAPH_REPORT.md  핵심 개념, 의외의 연결 관계, 추천 질문을 정리한 보고서
+└── graph.json       전체 그래프 — 원본 파일을 다시 읽지 않고 언제든 질의 가능
 ```
 
-그래프에 포함하지 않을 폴더를 제외하려면 `.graphifyignore` 파일을 추가하세요:
+Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot을 비롯해 **15개 이상의 다른 도우미에서도 작동합니다.** — [사용하는 플랫폼 선택하기](#install)
+
+---
+
+## 실제 사용 예시
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/demo-path.svg" alt="graphify 경로 질의 예시: 터미널에서 FastAPI와 ModelField 사이의 최단 경로를 요청하면 지식 그래프의 해당 경로가 단계별로 강조됩니다." width="900">
+</p>
+
+그래프를 한 번 만들면 파일을 직접 읽는 대신 그래프에 질의할 수 있습니다. 위의 FastAPI 코드베이스에 graphify를 실행한 실제 출력입니다.
 
+```text
+$ graphify explain "APIRouter"
+Node: APIRouter
+  Source:    routing.py L2210
+  Community: 2
+  Degree:    47
+
+Connections (47):
+  --> RequestValidationError [uses] [INFERRED]
+  --> Dependant [uses] [INFERRED]
+  --> .get() [method] [EXTRACTED]
+  <-- __init__.py [imports] [EXTRACTED]
+  ...
+
+$ graphify path "FastAPI" "ModelField"
+Shortest path (3 hops):
+  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField
 ```
-# .graphifyignore
-vendor/
-node_modules/
-dist/
-*.generated.py
+
+모든 엣지(연결 관계)에는 **신뢰도 태그**가 붙습니다. `EXTRACTED`는 소스에 명시된 관계, `INFERRED`는 관계를 해석해 도출한 결과를 뜻하므로, 직접 읽어 낸 정보와 추론한 정보를 구분할 수 있습니다. `graphify query "<question>"`은 자연어 질문과 관련된 부분 그래프를 반환하고, `graphify path A B`는 두 요소가 어떻게 연결되는지 추적합니다.
+
+---
+
+## 주요 기능
+
+기본으로 제공되는 기능은 다음과 같습니다.
+
+| 기능 | 제공 내용 |
+|---|---|
+| **핵심 허브 노드(God nodes)** | 연결이 가장 많은 개념을 찾아, 프로젝트의 흐름이 어디에 집중되는지 보여 줍니다. |
+| **커뮤니티** | Leiden 알고리즘으로 그래프를 하위 시스템 단위로 나누고, LLM 없이 이름을 붙입니다. |
+| **파일 간 연결** | tree-sitter AST를 사용해 약 40개 언어에서 `calls` / `imports` / `inherits` / `mixes_in` 관계를 파악합니다. |
+| **질의·경로 추적·설명** | `graph.json`을 바탕으로 질문에 답하고, 두 요소 사이의 경로를 추적하고, 특정 개념을 설명합니다. |
+| **설계 근거와 문서 참조** | `# NOTE:` / `# WHY:` 주석과 ADR/RFC 인용을 독립적인 노드로 만들고 관련 코드에 연결합니다. |
+| **코드 외의 자료도 지원** | 문서, PDF, 이미지, 동영상·오디오를 모두 같은 그래프에 담습니다. |
+| **로컬 우선 처리** | 코드는 tree-sitter로 로컬에서 파싱합니다(LLM을 사용하지 않으며 외부 전송도 없습니다). 문서·미디어의 의미 분석에만 백엔드를 호출하며, 이 역시 백엔드를 설정했을 때만 수행합니다. |
+
+---
+
+## 벤치마크
+
+| 벤치마크 | 지표 | graphify | 비교 대상 |
+|---|---|---|---|
+| LOCOMO (n=300) | recall@10 | **0.497** | mem0 0.048, supermemory 0.149 |
+| LOCOMO (n=300) | 질의응답 정확도 | 45.3% | supermemory 49.7%, mem0 27.3% |
+| LongMemEval-S (n=50) | 질의응답 정확도 | **76%** | dense RAG와 동률 |
+| 그래프 구축 | LLM 크레딧 | **0** | 대부분의 시스템은 토큰별 과금 |
+
+모든 시스템을 동일한 테스트 환경에서 같은 모델과 예산으로 실행했습니다. 평가는 별도의 두 번째 평가자와 블라인드 방식으로 대조 검증했습니다(일치율 90.6%, Cohen's kappa 0.81). 시스템별 전체 결과표, 코드 이해 성능 결과, 재현 명령어는 **[BENCHMARKS.md](https://github.com/Graphify-Labs/graphify/blob/v8/BENCHMARKS.md)**에서 확인할 수 있습니다.
+
+---
+
+## 사전 준비
+
+| 필수 도구 | 최소 버전 | 확인 방법 | 설치 방법 |
+|---|---|---|---|
+| Python | 3.10 이상 | `python --version` | [python.org](https://www.python.org/downloads/) |
+| uv *(권장)* | 제한 없음 | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| pipx *(대안)* | 제한 없음 | `pipx --version` | `pip install pipx` |
+
+**macOS 빠른 설치(Homebrew):**
+
+```bash
+brew install python@3.12 uv
 ```
 
-`.gitignore`와 동일한 문법입니다. 패턴은 graphify를 실행한 폴더 기준의 상대 경로에 대해 매칭됩니다.
+**Windows 빠른 설치:**
+
+```powershell
+winget install astral-sh.uv
+```
 
-## 동작 원리
+**Ubuntu/Debian:**
 
-graphify는 두 번의 패스로 실행됩니다. 첫 번째는 결정론적 AST 패스로, 코드 파일에서 구조(클래스, 함수, 임포트, 콜 그래프, docstring, 근거 주석)를 LLM 없이 추출합니다. 두 번째는 Claude 서브에이전트가 문서, 논문, 이미지에 대해 병렬로 실행되어 개념, 관계, 설계 근거를 추출합니다. 결과는 NetworkX 그래프로 병합되고, Leiden 커뮤니티 탐지로 클러스터링되며, 인터랙티브 HTML, 쿼리 가능한 JSON, 그리고 일반 언어 감사 보고서로 내보내집니다.
+```bash
+sudo apt install python3.12 python3-pip pipx
+# 또는 uv 설치:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
 
-**클러스터링은 그래프 토폴로지 기반 — 임베딩을 사용하지 않습니다.** Leiden은 엣지 밀도를 기반으로 커뮤니티를 찾습니다. Claude가 추출하는 의미적 유사성 엣지(`semantically_similar_to`, INFERRED로 표시)는 이미 그래프에 포함되어 있으므로 커뮤니티 탐지에 직접 영향을 줍니다. 그래프 구조 자체가 유사성 신호이며 — 별도의 임베딩 단계나 벡터 데이터베이스가 필요하지 않습니다.
+---
 
-모든 관계는 `EXTRACTED`(소스에서 직접 발견), `INFERRED`(합리적 추론, 신뢰도 점수 포함), `AMBIGUOUS`(리뷰 필요 표시) 중 하나로 태깅됩니다. 무엇이 발견된 것이고 무엇이 추측된 것인지 항상 알 수 있습니다.
+<a id="install"></a>
 
 ## 설치
 
-**필수 요구사항:** Python 3.10+ 및 다음 중 하나: [Claude Code](https://claude.ai/code), [Codex](https://openai.com/codex), [OpenCode](https://opencode.ai), [OpenClaw](https://openclaw.ai), [Factory Droid](https://factory.ai), 또는 [Trae](https://trae.ai)
+> **공식 패키지:** PyPI 패키지 이름은 `graphifyy`입니다(y가 두 개). PyPI의 다른 `graphify*` 패키지는 이 프로젝트와 관련이 없습니다. CLI 명령어는 그대로 `graphify`입니다.
+
+**1단계 — 패키지 설치:**
+
+```bash
+# 권장 (격리된 환경에 설치. 설치 후 'graphify'를 찾지 못하면 uv tool update-shell 실행):
+uv tool install graphifyy
+
+# 다른 설치 방법:
+pipx install graphifyy
+pip install graphifyy  # PATH 설정이 필요할 수 있음 — 아래 참고
+```
+
+**2단계 — AI 도우미에 스킬 등록:**
+
+```bash
+graphify install
+```
+
+설치가 끝났습니다. AI 도우미를 열고 `/graphify .`를 입력하세요.
+
+사용자 프로필 대신 현재 저장소에 도우미 스킬을 설치하려면 `--project`를 추가합니다.
 
 ```bash
-pip install graphifyy && graphify install
+graphify install --project
+graphify install --project --platform codex
 ```
 
-> PyPI 패키지는 `graphify` 이름을 되찾는 동안 임시로 `graphifyy`로 명명되어 있습니다. CLI와 스킬 명령은 여전히 `graphify`입니다.
+프로젝트 단위 설치는 현재 디렉터리 아래에 파일을 생성합니다. 예를 들어 `.claude/skills/graphify/SKILL.md` 또는 `.agents/skills/graphify/SKILL.md`와, 스킬이 필요할 때 불러오는 보조 자료 디렉터리 `references/`가 만들어집니다. 커밋할 수 있는 파일에 대해서는 `git add` 안내도 출력합니다. 프로젝트 단위 설치를 지원하는 플랫폼별 명령어에도 같은 플래그를 사용할 수 있습니다. 예: `graphify claude install --project`, `graphify codex install --project`.
+
+> **PowerShell 참고:** `/graphify .` 대신 `graphify .`를 사용하세요. PowerShell에서는 맨 앞의 슬래시를 경로 구분자로 해석합니다.
+
+> **`graphify: command not found`가 표시되나요?** `uv tool install` / `pipx install`은 도구 실행 파일 디렉터리(`~/.local/bin`)에 `graphify` 명령어를 설치합니다. 설치 직후 셸이 명령어를 찾지 못한다면 이 디렉터리가 아직 `PATH`에 없는 것입니다. 새로 설정한 macOS + zsh 환경에서 흔히 발생합니다. `uv tool update-shell`(또는 `pipx ensurepath`)을 실행한 뒤 새 터미널을 여세요. 일반 `pip`로 설치했다면 `~/.local/bin`(Linux) 또는 `~/Library/Python/3.x/bin`(Mac)을 PATH에 추가하거나 `python -m graphify`로 실행하세요.
+
+> **설치 없이 `uvx` / `uv tool run`으로 실행하려면?** 명령어 이름이 아닌 패키지 이름을 지정하세요: `uvx --from graphifyy graphify install`. 단순히 `uvx graphify …`로 실행하면 `No solution found … no versions of graphify` 오류가 발생합니다. `uv tool run`은 첫 단어를 *패키지* 이름으로 해석하기 때문입니다. 패키지 이름은 `graphifyy`이고, 그 안에 `graphify` 명령어가 들어 있습니다.
 
-### 플랫폼 지원
+> **Mac/Windows에서는 가능하면 `pip install`을 피하세요.** 스킬은 실행 시 `graphify-out/.graphify_python`에서 Python 경로를 확인합니다. 이 경로가 `pip`로 패키지를 설치한 환경과 다르면 `ModuleNotFoundError: No module named 'graphify'`가 발생합니다. `uv tool install`과 `pipx install`은 패키지를 별도 환경에 격리하므로 이 문제를 방지할 수 있습니다.
 
-| 플랫폼 | 설치 명령 |
-|--------|-----------|
+> **Git 훅과 uv tool / pipx:** `graphify hook install`은 설치 시점의 인터프리터 경로를 훅 스크립트에 직접 기록합니다. 덕분에 `~/.local/bin`이 PATH에 없는 GUI Git 클라이언트나 CI 실행 환경에서도 post-commit 훅이 정상 작동합니다. graphify를 재설치하거나 업그레이드했다면 `graphify hook install`을 다시 실행해 경로를 갱신하세요.
+
+> **엄격 모드(Claude Code):** `graphify install --project --strict`를 사용하면 도우미가 실제로 그래프를 사용하도록 강제할 수 있습니다. 기본 설치는 파일을 읽기 전에 `graphify query`를 실행하도록 *권고*합니다. 엄격 모드는 세션에서 첫 번째 원본 소스 읽기를 *차단*하고 그래프로 안내한 뒤, 다시 권고 방식으로 돌아갑니다. 따라서 세션당 최대 한 번만 차단하며 반복 차단에 빠지지 않습니다. 실행 시 `GRAPHIFY_HOOK_STRICT=1`/`0`으로 켜거나 끌 수 있습니다. 기본 설치의 동작은 기존과 같은 권고 방식입니다.
+
+<details>
+<summary><b>플랫폼 선택</b> (20개 이상의 도우미 지원, 클릭하여 펼치기)</summary>
+
+| 플랫폼 | 설치 명령어 |
+|----------|----------------|
 | Claude Code (Linux/Mac) | `graphify install` |
 | Claude Code (Windows) | `graphify install` (자동 감지) 또는 `graphify install --platform windows` |
+| CodeBuddy | `graphify install --platform codebuddy` |
 | Codex | `graphify install --platform codex` |
 | OpenCode | `graphify install --platform opencode` |
+| Kilo Code | `graphify install --platform kilo` |
+| GitHub Copilot CLI | `graphify install --platform copilot` |
+| VS Code Copilot Chat | `graphify vscode install` |
+| Aider | `graphify install --platform aider` |
 | OpenClaw | `graphify install --platform claw` |
 | Factory Droid | `graphify install --platform droid` |
 | Trae | `graphify install --platform trae` |
 | Trae CN | `graphify install --platform trae-cn` |
+| Gemini CLI | `graphify install --platform gemini` |
+| Hermes | `graphify install --platform hermes` |
+| Kimi Code | `graphify install --platform kimi` |
+| Amp | `graphify amp install` |
+| Agent Skills (프레임워크 공통) | `graphify install --platform agents` (별칭: `--platform skills`) |
+| Kiro IDE/CLI | `graphify kiro install` |
+| Pi coding agent | `graphify install --platform pi` |
+| Cursor | `graphify cursor install` |
+| Devin CLI | `graphify devin install` |
+| Google Antigravity | `graphify antigravity install` |
 
-Codex 사용자는 병렬 추출을 위해 `~/.codex/config.toml`의 `[features]` 아래에 `multi_agent = true`도 필요합니다. Factory Droid는 병렬 서브에이전트 디스패치에 `Task` 도구를 사용합니다. OpenClaw는 순차 추출을 사용합니다(해당 플랫폼의 병렬 에이전트 지원은 아직 초기 단계입니다). Trae는 병렬 서브에이전트 디스패치에 Agent 도구를 사용하며 PreToolUse 훅을 **지원하지 않습니다** — AGENTS.md가 상시 작동 메커니즘입니다.
+Codex에서 병렬 추출을 사용하려면 `~/.codex/config.toml`의 `[features]` 아래에 `multi_agent = true`도 설정해야 합니다. CodeBuddy는 Claude Code와 같은 Agent 도구 및 PreToolUse 훅 방식을 사용합니다. Factory Droid는 `Task` 도구로 하위 에이전트를 병렬 실행합니다. OpenClaw와 Aider는 순차 추출을 사용합니다(두 플랫폼의 병렬 에이전트 지원은 아직 초기 단계입니다). Trae는 Agent 도구로 하위 에이전트를 병렬 실행하며, `PreToolUse` 훅을 지원하지 **않으므로** AGENTS.md를 통해 그래프 사용 지침을 상시 적용합니다.
 
-그런 다음 AI 코딩 어시스턴트를 열고 입력하세요:
+`--platform agents`(별칭: `--platform skills`)는 여러 프레임워크에서 공통으로 사용하는 [Agent-Skills](https://github.com/anthropics/skills) 경로를 대상으로 합니다. 전역 설치에는 사양에 정의된 사용자 공통 경로 `~/.agents/skills/`를 사용하며(`npx skills`와 해당 사양을 준수하는 프레임워크가 이 경로를 읽습니다), 프로젝트 설치(`--project`)에는 `./.agents/skills/`를 사용합니다. 옵션 없는 `graphify install`은 설계상 단일 플랫폼(Claude Code)만 대상으로 합니다. `.agents/skills`를 읽는 모든 프레임워크에서 스킬을 발견할 수 있게 하려면 `agents` 플랫폼을 명시하세요.
 
-```
-/graphify .
-```
+> Codex에서는 `/graphify` 대신 `$graphify`를 사용합니다.
+
+</details>
+
+<details>
+<summary><b>선택 기능</b> (필요한 항목만 설치하세요)</summary>
+
+| 추가 옵션 | 제공 기능 | 설치 명령어 |
+|---|---|---|
+| `pdf` | PDF 추출 | `uv tool install "graphifyy[pdf]"` |
+| `office` | `.docx` 및 `.xlsx` 지원 | `uv tool install "graphifyy[office]"` |
+| `google` | Google Sheets 렌더링 | `uv tool install "graphifyy[google]"` |
+| `video` | 동영상·오디오 전사(faster-whisper + yt-dlp) | `uv tool install "graphifyy[video]"` |
+| `mcp` | MCP stdio 서버 | `uv tool install "graphifyy[mcp]"` |
+| `neo4j` | Neo4j로 전송 지원 | `uv tool install "graphifyy[neo4j]"` |
+| `falkordb` | FalkorDB로 전송 지원 | `uv tool install "graphifyy[falkordb]"` |
+| `svg` | 그래프를 SVG로 내보내기 | `uv tool install "graphifyy[svg]"` |
+| `leiden` | Leiden 커뮤니티 탐지(Python 3.13 미만은 graspologic, 3.13 이상은 네이티브 백엔드) | `uv tool install "graphifyy[leiden]"` |
+| `ollama` | Ollama 로컬 추론 | `uv tool install "graphifyy[ollama]"` |
+| `openai` | OpenAI 및 OpenAI 호환 API | `uv tool install "graphifyy[openai]"` |
+| `gemini` | Google Gemini API | `uv tool install "graphifyy[gemini]"` |
+| `anthropic` | Anthropic Claude API(`--backend claude`, `ANTHROPIC_API_KEY` 사용) | `uv tool install "graphifyy[anthropic]"` |
+| `bedrock` | AWS Bedrock(IAM 사용, API 키 불필요) | `uv tool install "graphifyy[bedrock]"` |
+| `azure` | Azure OpenAI Service(`--backend azure`, `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` 사용) | `uv tool install "graphifyy[openai]"` |
+| `sql` | SQL 스키마 추출 | `uv tool install "graphifyy[sql]"` |
+| `postgres` | 실행 중인 PostgreSQL의 스키마 조사(`--postgres DSN`) | `uv tool install "graphifyy[postgres]"` |
+| `dm` | BYOND DreamMaker `.dm`/`.dme` AST 추출(플랫폼에 맞는 wheel이 없으면 C 컴파일러와 `python3-dev`가 필요할 수 있음) | `uv tool install "graphifyy[dm]"` |
+| `terraform` | Terraform / HCL `.tf`/`.tfvars`/`.hcl` AST 추출 | `uv tool install "graphifyy[terraform]"` |
+| `pascal` | Pascal / Delphi `.pas`/`.dpr`/`.dpk`/`.inc` AST 추출(`calls`/`inherits` 관계의 정확도 향상, 미설치 시 정규식 추출기로 대체) | `uv tool install "graphifyy[pascal]"` |
+| `ocaml` | OCaml `.ml`/`.mli` AST 추출 | `uv tool install "graphifyy[ocaml]"` |
+| `commonlisp` | Common Lisp `.lisp`/`.cl`/`.lsp`/`.asd` AST 추출 | `uv tool install "graphifyy[commonlisp]"` |
+| `robot` | Robot Framework `.robot`/`.resource` 추출(스위트, 테스트 케이스, 키워드, 키워드 호출 및 리소스·라이브러리 가져오기 관계) | `uv tool install "graphifyy[robot]"` |
+| `chinese` | 중국어 질의 분절(jieba) | `uv tool install "graphifyy[chinese]"` |
+| `all` | 위의 모든 기능 | `uv tool install "graphifyy[all]"` |
+
+</details>
 
-참고: Codex는 스킬 호출에 `/` 대신 `$`를 사용하므로 `$graphify .`라고 입력하세요.
+---
 
-### 어시스턴트가 항상 그래프를 사용하도록 설정 (권장)
+## 도우미가 항상 그래프를 사용하도록 설정하기
 
-그래프를 빌드한 후, 프로젝트에서 한 번만 실행하세요:
+그래프를 만든 뒤 프로젝트에서 아래 명령어를 한 번 실행하세요.
 
-| 플랫폼 | 명령 |
-|--------|------|
+| 플랫폼 | 명령어 |
+|----------|---------|
 | Claude Code | `graphify claude install` |
+| CodeBuddy | `graphify codebuddy install` |
 | Codex | `graphify codex install` |
 | OpenCode | `graphify opencode install` |
+| Kilo Code | `graphify kilo install` |
+| GitHub Copilot CLI | `graphify copilot install` |
+| VS Code Copilot Chat | `graphify vscode install` |
+| Aider | `graphify aider install` |
 | OpenClaw | `graphify claw install` |
 | Factory Droid | `graphify droid install` |
 | Trae | `graphify trae install` |
 | Trae CN | `graphify trae-cn install` |
+| Cursor | `graphify cursor install` |
+| Gemini CLI | `graphify gemini install` |
+| Hermes | `graphify hermes install` |
+| Kimi Code | `graphify install --platform kimi` |
+| Amp | `graphify amp install` |
+| Agent Skills (프레임워크 공통) | `graphify agents install` (별칭: `graphify skills install`) |
+| Kiro IDE/CLI | `graphify kiro install` |
+| Pi coding agent | `graphify pi install` |
+| Devin CLI | `graphify devin install` |
+| Google Antigravity | `graphify antigravity install` |
+
+이 명령어는 코드베이스 관련 질문에 답할 때 지식 그래프를 참조하도록 안내하는 작은 설정 파일을 만듭니다. 전체 보고서를 읽거나 원본 파일을 grep으로 검색하기보다 `graphify query "<question>"`처럼 범위를 좁힌 질의를 우선하도록 합니다.
+
+- **훅을 사용하는 플랫폼**(Claude Code, Gemini CLI): 검색 도구를 호출하기 전에 훅이 자동 실행되어 도우미가 그래프를 활용하도록 안내합니다. Claude Code에서는 Read/Glob 도구로 소스 파일을 하나씩 읽기 전에도 실행됩니다.
+- **지침 파일을 사용하는 플랫폼**(Codex, OpenCode, Cursor 등): 상시 적용되는 지침 파일(`AGENTS.md`, `.cursor/rules/` 등)을 통해 동일한 질의 우선 원칙을 전달합니다.
+
+전체 아키텍처를 검토할 때는 여전히 `GRAPH_REPORT.md`를 사용할 수 있습니다.
+
+**CodeBuddy**는 Claude Code와 같은 두 가지 설정을 수행합니다. 아키텍처 질문에 답하기 전에 `graphify-out/GRAPH_REPORT.md`를 읽도록 `CODEBUDDY.md`에 섹션을 추가하고, Bash 검색 명령과 파일 읽기 전에 실행되는 `PreToolUse` 훅(`.codebuddy/settings.json`)을 설치해 `graphify query`를 우선 사용하도록 안내합니다.
+
+**Codex**에서는 `AGENTS.md`에 지침을 기록하며, 이 파일이 실제로 그래프 사용 지침을 상시 전달합니다. `graphify codex install`은 `.codex/hooks.json`에 `PreToolUse` 훅(`graphify hook-check`)도 등록하지만, 이 항목은 의도적으로 **아무 동작도 하지 않습니다(no-op)**. Codex Desktop은 `PreToolUse`의 `hookSpecificOutput.additionalContext`를 허용하지 않으므로, 여기서 안내를 출력하면 Bash 도구 호출이 실패하기 때문입니다. Claude Code에서는 훅(`graphify hook-guard`)이 안내를 담당하지만, Codex에서는 훅이 실행되어도 아무 작업을 하지 않으며 `AGENTS.md`가 상시 안내를 담당합니다.
 
-**Claude Code**는 두 가지를 수행합니다: 아키텍처 질문에 답하기 전에 `graphify-out/GRAPH_REPORT.md`를 읽도록 Claude에게 지시하는 `CLAUDE.md` 섹션을 작성하고, 모든 Glob 및 Grep 호출 전에 실행되는 **PreToolUse 훅**(`settings.json`)을 설치합니다. 지식 그래프가 존재하면 Claude는 다음 메시지를 보게 됩니다: _"graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files."_ — 이를 통해 Claude는 모든 파일을 grep하는 대신 그래프를 통해 탐색합니다.
+**Kilo Code**는 Graphify 스킬을 `~/.config/kilo/skills/graphify/SKILL.md`에, 네이티브 `/graphify` 명령을 `~/.config/kilo/command/graphify.md`에 설치합니다. `graphify kilo install`은 `AGENTS.md`와 네이티브 `tool.execute.before` 플러그인도 생성합니다(`.kilo/plugins/graphify.js` + `.kilo/kilo.json` 또는 `.kilo/kilo.jsonc`에 등록). 이를 통해 Kilo에서도 네이티브 `.kilo` 설정으로 그래프 사용 안내를 상시 받을 수 있습니다.
 
-**Codex**는 `AGENTS.md`에 작성하고 Bash 도구 호출 전에 실행되는 **PreToolUse 훅**을 `.codex/hooks.json`에 설치합니다 — Claude Code와 동일한 상시 작동 메커니즘입니다.
+**Cursor**는 `alwaysApply: true`가 설정된 `.cursor/rules/graphify.mdc`를 생성합니다. Cursor가 모든 대화에 이 파일을 자동으로 포함하므로 훅이 필요하지 않습니다.
 
-**OpenCode, OpenClaw, Factory Droid, Trae**는 프로젝트 루트의 `AGENTS.md`에 동일한 규칙을 작성합니다. 이 플랫폼들은 PreToolUse 훅을 지원하지 않으므로 AGENTS.md가 상시 작동 메커니즘입니다.
+모든 플랫폼에서 graphify를 한 번에 제거하려면 `graphify uninstall`을 실행하세요(`--purge`를 추가하면 `graphify-out/`도 삭제됩니다). 플랫폼별 명령어(예: `graphify claude uninstall`)를 사용해도 됩니다.
 
-제거는 대응하는 uninstall 명령으로 수행합니다(예: `graphify claude uninstall`).
+---
 
-**상시 작동 vs 명시적 트리거 — 차이점은?**
+## 보고서에 담기는 내용
 
-상시 작동 훅은 `GRAPH_REPORT.md`를 노출합니다 — 갓 노드, 커뮤니티, 의외의 연결을 한 페이지로 요약한 것입니다. 어시스턴트는 파일 검색 전에 이것을 읽으므로 키워드 매칭이 아닌 구조 기반으로 탐색합니다. 이것만으로 대부분의 일상적인 질문을 처리할 수 있습니다.
+- **핵심 허브 노드(God nodes)** — 프로젝트에서 가장 많은 연결을 가진 개념입니다. 주요 흐름이 이 노드들을 거칩니다.
+- **의외의 연결 관계** — 서로 다른 파일이나 모듈에 있는 요소 사이의 연결입니다. 예상하기 어려운 관계일수록 높은 순위에 표시됩니다.
+- **설계의 이유** — 인라인 주석(`# NOTE:`, `# WHY:`, `# HACK:`), 독스트링, 문서에 담긴 설계 근거를 별도 노드로 추출하고, 해당 내용이 설명하는 코드에 연결합니다.
+- **추천 질문** — 그래프를 활용하면 특히 잘 답할 수 있는 질문 4~5개를 제안합니다.
+- **신뢰도 태그** — 추론된 모든 관계에 `EXTRACTED`, `INFERRED`, `AMBIGUOUS` 중 하나를 표시합니다. 확인된 사실과 추정을 언제나 구분할 수 있습니다.
 
-`/graphify query`, `/graphify path`, `/graphify explain`은 더 깊이 들어갑니다: 원시 `graph.json`을 홉 단위로 순회하고, 노드 간의 정확한 경로를 추적하며, 엣지 수준의 세부 정보(관계 유형, 신뢰도 점수, 소스 위치)를 보여줍니다. 일반적인 오리엔테이션이 아닌 그래프에서 특정 질문에 답하고 싶을 때 사용하세요.
+---
 
-이렇게 생각하면 됩니다: 상시 작동 훅은 어시스턴트에게 지도를 주고, `/graphify` 명령은 그 지도를 정확하게 탐색하게 합니다.
 
-## `graph.json`을 LLM과 함께 사용하기
+## 지원하는 파일
 
-`graph.json`은 프롬프트에 한 번에 전부 붙여넣기 위한 것이 아닙니다. 유용한 워크플로우는 다음과 같습니다:
+| 유형 | 확장자 |
+|------|-----------|
+| 코드(tree-sitter 문법 37종) | `.py .ts .mts .cts .js .jsx .tsx .mjs .go .rs .java .c .cpp .cc .cxx .h .hpp .cu .cuh .metal .rb .cs .kt .kts .scala .php .swift .lua .luau .toc .zig .ps1 .psm1 .psd1 .ex .exs .m .mm .ml .mli .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml` (`.dm`/`.dme`는 `uv tool install graphifyy[dm]`, `.ml`/`.mli`는 `uv tool install graphifyy[ocaml]` 필요. `.mts`/`.cts`는 TypeScript 문법을, `.cc`/`.cxx`, CUDA의 `.cu`/`.cuh`, Metal의 `.metal`은 C++ 문법을 재사용) |
+| Salesforce Apex | `.cls .trigger` (정규식 기반. 클래스, 인터페이스, 열거형, 메서드, 트리거, SOQL/DML 관계 추출) |
+| Terraform / HCL | `.tf .tfvars .hcl` (`uv tool install graphifyy[terraform]` 필요) |
+| OCaml | `.ml .mli` (`uv tool install graphifyy[ocaml]` 필요) |
+| Common Lisp | `.lisp .cl .lsp .asd` (`uv tool install graphifyy[commonlisp]` 필요) |
+| Robot Framework | `.robot .resource` (공식 `robot.api` 파서 사용, `uv tool install graphifyy[robot]` 필요. 스위트, 테스트 케이스, 사용자 키워드, 키워드 호출 및 Resource/Library/Variables 가져오기 관계 추출) |
+| MCP 설정 | `.mcp.json` `mcp.json` `mcp_servers.json` `claude_desktop_config.json` — 서버 노드, 패키지 참조, 필요한 환경 변수 추출 |
+| 패키지 매니페스트 | `apm.yml` `pyproject.toml` `go.mod` `pom.xml` — 이름을 기준으로 패키지마다 하나의 대표 노드를 만들고 `depends_on` 관계를 추가. 여러 매니페스트에서 참조하는 패키지도 하나의 허브로 통합 |
+| 문서 | `.md .mdx .qmd .html .txt .rst .yaml .yml` (Markdown의 `[text](./other.md)` 링크와 `[[wikilinks]]`를 문서 간 `references` 관계로 변환) |
+| Office | `.docx .xlsx` (`uv tool install graphifyy[office]` 필요) |
+| Google Workspace | `.gdoc .gsheet .gslides` (명시적으로 활성화해야 함. `gws` 인증과 `--google-workspace` 필요. Sheets는 `uv tool install graphifyy[google]` 필요) |
+| PDF | `.pdf` |
+| 이미지 | `.png .jpg .webp .gif` |
+| 동영상 / 오디오 | `.mp4 .mov .mp3 .wav` 등 (`uv tool install graphifyy[video]` 필요) |
+| YouTube / URL | 모든 동영상 URL (`uv tool install graphifyy[video]` 필요) |
 
-1. `graphify-out/GRAPH_REPORT.md`로 높은 수준의 개요를 파악합니다.
-2. `graphify query`를 사용하여 답하려는 특정 질문에 대한 더 작은 서브그래프를 가져옵니다.
-3. 전체 원시 코퍼스 대신 그 집중된 결과를 어시스턴트에게 제공합니다.
+코드는 **API 호출 없이 로컬에서 추출**합니다(tree-sitter AST 사용). 그 외의 자료는 AI 도우미의 모델 API를 거칩니다.
 
-예를 들어, 프로젝트에서 graphify를 실행한 후:
+데스크톱용 Google Drive의 `.gdoc`, `.gsheet`, `.gslides` 파일은 문서 내용 자체가 아니라 바로가기입니다. IDE 없이 실행하는 추출 작업에 Google Docs, Sheets, Slides 원본 문서를 포함하려면 [`gws` CLI](https://github.com/googleworkspace/cli)를 설치하고 인증한 뒤 다음을 실행하세요.
 
 ```bash
-graphify query "show the auth flow" --graph graphify-out/graph.json
-graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
+uv tool install "graphifyy[google]"  # Google Sheets의 표 렌더링에 필요
+gws auth login -s drive
+graphify extract ./docs --google-workspace
 ```
 
-출력에는 노드 레이블, 엣지 유형, 신뢰도 태그, 소스 파일, 소스 위치가 포함됩니다. 이는 LLM을 위한 좋은 중간 컨텍스트 블록이 됩니다:
+`GRAPHIFY_GOOGLE_WORKSPACE=1`을 설정해도 됩니다. Graphify는 바로가기가 가리키는 문서를 `graphify-out/converted/` 아래에 Markdown 보조 파일로 내보낸 다음, 이 파일에서 정보를 추출합니다.
+
+---
+
+## 자주 사용하는 명령어
+
+```bash
+/graphify .                        # 현재 폴더의 그래프 생성
+/graphify ./docs --update          # 변경된 파일만 다시 추출
+/graphify . --cluster-only         # 재추출 없이 클러스터링만 다시 실행
+/graphify . --cluster-only --resolution 1.5      # 커뮤니티를 더 세밀하게 분할
+/graphify . --cluster-only --exclude-hubs 99     # 핵심 허브 순위에서 연결이 지나치게 많은 유틸리티 허브를 억제
+/graphify . --no-viz               # HTML 없이 보고서와 JSON만 생성
+/graphify . --wiki                 # 그래프에서 Markdown 위키 생성
+graphify export callflow-html      # Mermaid 아키텍처·호출 흐름 HTML 생성 (훅 설치 시 Git 커밋마다 자동 재생성)
+
+/graphify query "what connects auth to the database?"
+/graphify path "UserService" "DatabasePool"
+/graphify explain "RateLimiter"
+
+/graphify add https://arxiv.org/abs/1706.03762   # 논문을 가져와 추가
+/graphify add <youtube-url>                       # 동영상을 전사해 추가
+
+graphify hook install              # 커밋·브랜치 체크아웃 시 자동 재생성 (git pull 후에는 graphify update . 실행 — 아래 권장 작업 흐름 참고)
+graphify merge-graphs a.json b.json              # 두 그래프 병합
+
+graphify prs                       # PR 대시보드: CI 상태, 리뷰 상태, worktree 연결 정보
+graphify prs 42                    # 그래프에 미치는 영향을 포함해 PR #42 상세 분석
+graphify prs --triage              # AI가 리뷰 대기 목록의 우선순위 지정 (설정된 백엔드 사용)
+graphify prs --conflicts           # 같은 그래프 커뮤니티를 수정하는 PR 확인 — 병합 순서에 따른 위험
+```
+
+아래의 [전체 명령어 참조](#full-command-reference)도 확인하세요.
+
+---
+
+## 파일 제외하기
+
+프로젝트 루트에 `.graphifyignore`를 만드세요. `!`를 사용하는 제외 규칙의 반전까지 포함해 `.gitignore`와 같은 문법을 사용합니다.
+
+**`.gitignore`는 자동으로 적용됩니다.** graphify는 각 디렉터리의 `.gitignore`를 읽습니다. `.graphifyignore`도 있으면 두 파일의 규칙을 **합쳐서** 적용합니다. `.graphifyignore` 패턴을 마지막에 평가하므로 규칙이 충돌하면 이쪽이 우선합니다(`!` 반전 규칙 포함). `.graphifyignore`를 추가하면 제외 대상이 늘어날 뿐, `.gitignore`가 이미 제외한 파일을 다시 포함하지는 않습니다. 하위 디렉터리 범위는 Git과 같은 방식으로 처리합니다. 각 ignore 파일은 자신이 속한 디렉터리와 그 하위에만 영향을 줍니다.
+
+Git에서 제외한 생성 코드나 트랜스파일된 코드도 그래프에 포함하려면 `graphify extract`에 `--no-gitignore`를 전달하세요. 이 옵션은 `.gitignore`와 `.git/info/exclude`를 비활성화합니다. `.graphifyignore`는 계속 적용됩니다.
+
+```
+# .graphifyignore
+node_modules/
+dist/
+*.generated.py
+
+# src/만 인덱싱하고 나머지는 모두 제외
+*
+!src/
+!src/**
+```
+
+---
+
+## 팀 환경 설정
+
+`graphify-out/`은 팀원 모두가 프로젝트 지도를 갖고 시작할 수 있도록 Git에 커밋하는 것을 전제로 합니다.
+
+**`.gitignore`에 추가할 권장 항목:**
 
-```text
-이 그래프 쿼리 결과를 사용하여 질문에 답하세요. 추측보다 그래프 구조를 우선하고,
-가능한 경우 소스 파일을 인용하세요.
 ```
+graphify-out/cost.json        # 로컬에서만 사용
+# graphify-out/cache/         # 선택 사항: 속도를 원하면 커밋, 저장소 크기를 줄이려면 제외
+```
+
+> 이제 `manifest.json`은 다른 환경에서도 사용할 수 있습니다. 키를 상대 경로로 저장하고 불러올 때 기준 경로를 다시 설정하므로, 커밋해도 안전하며 첫 체크아웃 시 전체 그래프를 다시 만들지 않아도 됩니다.
+
+<a id="recommended-workflow"></a>
+
+### 권장 작업 흐름
+
+저장소를 복제한 뒤 한 번만 설정하세요. 이후에는 평소 사용하는 Git 명령어 세 개가 그래프를 자동으로 최신 상태로 유지하고, 나머지 한 단계로 팀의 변경 사항과 동기화할 수 있습니다.
+
+| 실행하는 작업 | graphify의 동작 |
+|---|---|
+| `graphify hook install` (복제 직후 한 번) | 아래 훅과 함께 병합 드라이버를 설치해 `graph.json`에 충돌 표시가 생기지 않도록 함 |
+| `git commit` | 자동 재생성 — AST만 사용하므로 API 비용 없음 |
+| `git checkout` / `git switch` (브랜치 전환) | 자동 재생성(파일만 체크아웃하는 `git checkout -- <path>`는 해당 없음) |
+| `git pull` / `git merge` | 직후에 `graphify update .` 실행 필요 |
+| `git push` | 별도 작업 없음 |
+
+커밋과 브랜치 전환에 따른 재생성은 백그라운드에서 실행되며 명령어는 즉시 반환됩니다. 따라서 큰 저장소에서는 그래프 갱신이 커밋보다 몇 초 늦을 수 있습니다. 갱신 전에 질의하는 드문 경우의 대처 방법은 아래 5단계를 참고하세요.
 
-어시스턴트가 도구 호출이나 MCP를 지원하는 경우, 텍스트를 붙여넣는 대신 그래프를 직접 사용하세요. graphify는 `graph.json`을 MCP 서버로 노출할 수 있습니다:
+**단계별 안내:**
+
+1. 저장소를 복제하고 `graphify hook install`을 한 번 실행합니다.
+2. 평소처럼 커밋하고 브랜치를 전환합니다. 그래프는 자동으로 최신 상태를 유지합니다.
+3. `git pull` 또는 병합을 할 때마다 바로 `graphify update .`를 실행해 방금 가져온 변경 사항을 반영합니다. 크거나 변경이 잦은 저장소에서는 다음 pull 별칭으로 자동화할 수 있습니다.
+   ```bash
+   git config --global alias.gpull '!git pull && graphify update .'
+   ```
+4. 문서나 논문이 변경되면 `/graphify --update`를 실행해 해당 노드도 갱신합니다. 코드와 문서는 별도로 갱신됩니다.
+5. 질의 결과에 방금 추가한 내용이 빠져 있는 것 같다면 먼저 `graphify update .`를 실행한 뒤 다시 질문하세요.
+
+---
+
+## 그래프 직접 사용하기
 
 ```bash
+# 터미널에서 그래프에 질의
+graphify query "show the auth flow"
+graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
+
+# 그래프를 MCP 서버로 제공 (도구 호출로 반복 접근 가능)
 python -m graphify.serve graphify-out/graph.json
+python -m graphify.serve --graph graphify-out/graph.json  # --graph 플래그도 사용 가능
+
+# Kimi Code에 등록:
+kimi mcp add --transport stdio graphify -- python -m graphify.serve graphify-out/graph.json
+
+# 또는 HTTP로 제공해 팀 전체가 하나의 URL 사용 (각자 graphify를 설치할 필요 없음):
+python -m graphify.serve graphify-out/graph.json --transport http --port 8080
+python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"
 ```
 
-이를 통해 어시스턴트가 `query_graph`, `get_node`, `get_neighbors`, `shortest_path` 같은 반복 쿼리에 구조화된 그래프 접근을 할 수 있습니다.
+MCP 서버는 도우미가 구조화된 방식으로 접근할 수 있는 다음 도구를 제공합니다: `query_graph`, `get_node`, `get_neighbors`, `shortest_path`, `list_prs`, `get_pr_impact`, `triage_prs`.
 
-<details>
-<summary>수동 설치 (curl)</summary>
+### 공유 HTTP 서버
+
+`--transport stdio`(기본값)는 개발자마다 로컬 서버를 하나씩 실행합니다. `--transport http`는 같은 도구를 MCP Streamable HTTP 전송 방식으로 제공하므로, 하나의 공유 프로세스가 팀 전체에 그래프를 제공할 수 있습니다. 각 클라이언트는 graphify를 로컬에서 실행하는 대신 IDE의 MCP 설정에 `http://<host>:8080/mcp`를 지정하면 됩니다.
+
+| 플래그 | 기본값 | 용도 |
+|---|---|---|
+| `--transport {stdio,http}` | `stdio` | 서버의 전송 방식 |
+| `--host` | `127.0.0.1` | HTTP 바인딩 호스트(localhost 외부에 공개하려면 `0.0.0.0` 사용) |
+| `--port` | `8080` | HTTP 바인딩 포트 |
+| `--api-key` | 환경 변수 `GRAPHIFY_API_KEY` | `Authorization: Bearer <key>` 또는 `X-API-Key` 인증 요구 |
+| `--path` | `/mcp` | HTTP 서비스 경로 |
+| `--json-response` | 꺼짐 | SSE 스트림 대신 일반 JSON 반환 |
+| `--stateless` | 꺼짐 | 세션별 상태를 유지하지 않음(로드 밸런싱·CI 배포용) |
+| `--session-timeout` | `3600` | 상태를 유지하는 세션이 N초 동안 유휴 상태이면 정리(`0`이면 비활성화) |
+
+기본 바인딩 주소 `127.0.0.1`은 루프백 연결만 허용합니다. 공유 호스트에서 외부에 공개할 때는 `--host 0.0.0.0`**과** `--api-key`를 함께 설정하세요. 컨테이너에서 실행하는 예시는 다음과 같습니다.
 
 ```bash
-mkdir -p ~/.claude/skills/graphify
-curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v3/graphify/skill.md \
-  > ~/.claude/skills/graphify/SKILL.md
+docker build -t graphify .
+docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
+  /data/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"
 ```
 
-`~/.claude/CLAUDE.md`에 추가:
+> **WSL / Linux 참고:** Ubuntu는 `python`이 아니라 `python3`를 제공합니다. 충돌을 피하려면 가상 환경을 사용하세요.
+> ```bash
+> python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"
+> ```
+
+---
+
+## 환경 변수
+
+다음 변수는 **헤드리스 환경 또는 CI에서 추출**할 때(`graphify extract`)만 필요합니다. IDE 안에서 `/graphify` 스킬로 실행하면 IDE 세션이 모델 API를 제공하므로 추가 키가 필요하지 않습니다.
+
+| 변수 | 용도 | 필요한 경우 |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Claude(Anthropic) 백엔드 | `--backend claude` |
+| `ANTHROPIC_BASE_URL` | Anthropic 호환 엔드포인트 URL(LiteLLM 프록시, 게이트웨이 등) | `--backend claude` (기본값: `https://api.anthropic.com`) |
+| `ANTHROPIC_MODEL` | Claude 백엔드의 모델 이름. 사용자 지정 엔드포인트에서는 서버가 제공하는 모델 이름이나 별칭 사용 | `--backend claude` (기본값: `claude-sonnet-4-6`) |
+| `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY` | Google Gemini 백엔드 | `--backend gemini` |
+| `OPENAI_API_KEY` | OpenAI 또는 OpenAI 호환 API | `--backend openai` (로컬 서버는 비어 있지 않은 값이면 허용) |
+| `OPENAI_BASE_URL` | OpenAI 호환 서버 URL(llama.cpp, vLLM, LM Studio 등) | `--backend openai` (기본값: `https://api.openai.com/v1`) |
+| `OPENAI_MODEL` | OpenAI 백엔드의 모델 이름. 자체 호스팅 서버에서는 서버가 제공하는 모델 이름이나 별칭 사용(`/v1/models` 엔드포인트에서 확인). 예: llama.cpp의 `LFM2.5-8B-A1B-UD-Q4_K_XL` | `--backend openai` (기본값: `gpt-4.1-mini`) |
+| `DEEPSEEK_API_KEY` | DeepSeek 백엔드 | `--backend deepseek` |
+| `MOONSHOT_API_KEY` | Kimi Code 백엔드 | `--backend kimi` |
+| `OLLAMA_BASE_URL` | Ollama 로컬 추론 URL | `--backend ollama` (기본값: `http://localhost:11434`) |
+| `OLLAMA_MODEL` | Ollama 모델 이름 | `--backend ollama` (기본값: 자동 감지) |
+| `GRAPHIFY_OLLAMA_NUM_CTX` | Ollama KV 캐시 윈도 크기를 직접 지정 | 선택 사항 — 기본적으로 자동 조정 |
+| `GRAPHIFY_OLLAMA_KEEP_ALIVE` | Ollama 모델을 메모리에 유지할 시간(분) | 선택 사항 — `0`으로 설정하면 청크 처리 후마다 모델을 메모리에서 해제 |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI Service 백엔드 | `--backend azure` |
+| `AZURE_OPENAI_ENDPOINT` | Azure 리소스 엔드포인트 URL | `--backend azure` (API 키와 함께 필수) |
+| `AZURE_OPENAI_API_VERSION` | Azure API 버전을 직접 지정 | 선택 사항 — 기본값 `2024-12-01-preview` |
+| `AZURE_OPENAI_DEPLOYMENT` 또는 `GRAPHIFY_AZURE_MODEL` | Azure 배포 이름 | 선택 사항 — 기본값 `gpt-4o` |
+| `AWS_*` / `~/.aws/credentials` | AWS Bedrock — 표준 자격 증명 체인 | `--backend bedrock` (API 키 없이 IAM 사용) |
+| `GRAPHIFY_MAX_WORKERS` | AST 병렬 처리 스레드 수 | 선택 사항 — `--max-workers` 플래그로도 설정 가능 |
+| `GRAPHIFY_MAX_OUTPUT_TOKENS` | 정보 밀도가 높은 자료 모음의 출력 한도 상향 | 선택 사항 — 큰 파일의 경우 예: `32768` |
+| `GRAPHIFY_API_TIMEOUT` | HTTP, claude-cli, Anthropic SDK, Bedrock 백엔드의 호출별 제한 시간(초, 기본값: 600) | 선택 사항 — `--api-timeout` 플래그로도 설정 가능 |
+| `GRAPHIFY_MAX_RETRIES` | 요청 한도 초과(429) 시 포기하기 전 재시도 횟수(기본값: 6, `Retry-After` 준수) | 선택 사항 — 조직별 한도가 엄격한 경우(예: kimi) 늘릴 수 있음. `0`이면 비활성화 |
+| `GRAPHIFY_MAX_RETRY_DEPTH` | 응답이 잘린 청크를 이분할해 재추출할 최대 깊이(기본값: 3, 청크 하나당 하위 호출이 최대 8배까지 증가) | 선택 사항 — 최악의 경우 비용을 제한하려면 낮게 설정. `0`이면 모든 재시도(이분할 및 내용 없는 응답의 재시도)를 비활성화하여 청크당 정확히 한 번만 호출 |
+| `GRAPHIFY_FORCE` | 노드 수가 줄어도 그래프 강제 재생성 | 선택 사항 — `--force` 플래그로도 설정 가능 |
+| `GRAPHIFY_GOOGLE_WORKSPACE` | Google Workspace 내보내기 자동 활성화 | 선택 사항 — `1`로 설정 |
+| `GRAPHIFY_TRIAGE_BACKEND` | `graphify prs --triage`에 사용할 백엔드 | 선택 사항 — 사용 가능한 키에서 자동 감지 |
+| `GRAPHIFY_TRIAGE_MODEL` | 우선순위 분류에 사용할 모델을 직접 지정 | 선택 사항 — 예: `claude-opus-4-7` |
+| `GRAPHIFY_QUERY_LOG_ENABLE` | `1`로 설정하면 `~/.cache/graphify-queries.log`의 로컬 질의 로그 활성화(query/path/explain의 각 질문과 자료 경로 기록). 기본적으로 꺼져 있으며, 명시적으로 활성화하지 않으면 기록하지 않음(#1797) | 선택 사항 |
+| `GRAPHIFY_QUERY_LOG` | 질의 로그를 활성화하고 기본 경로 대신 지정한 경로에 기록 | 선택 사항 — 이 변수나 `_ENABLE`을 설정하지 않으면 꺼짐 |
+| `GRAPHIFY_QUERY_LOG_DISABLE` | `1`로 설정하면 질의 로그를 강제로 끔(활성화 변수보다 우선) | 선택 사항 |
+| `GRAPHIFY_QUERY_LOG_RESPONSES` | 로그 활성화 시 전체 부분 그래프 응답도 기록(기본적으로 꺼짐) | 선택 사항 |
+| `GRAPHIFY_MAX_GRAPH_BYTES` | graph.json의 512 MiB 크기 제한 변경 — 예: `700MB`, `2GB` 또는 바이트 단위 숫자 | 선택 사항 — 매우 큰 자료 모음에 유용 |
+| `GRAPHIFY_MAX_CONTEXTS` | 다중 프로젝트 MCP 서버 하나가 유지할 기본 프로젝트 외 그래프의 최대 수 | 선택 사항 — 기본값: `8`. 잘못된 값은 `8`, `1`보다 작은 값은 `1` 사용 |
+| `GRAPHIFY_LLM_TEMPERATURE` | 의미 추출에 사용할 LLM temperature를 직접 지정 — 예: `0.7`, 생략하려면 `none` | 선택 사항 — o1/o3/o4/gpt-5 추론 모델에서는 자동으로 생략 |
+
+---
+
+## 개인정보 및 데이터 처리
+
+- **코드 파일** — tree-sitter로 로컬에서 처리하며 외부로 전송하지 않습니다. 코드만 있는 자료 모음에는 API 키가 필요 없고, `graphify extract`가 완전히 오프라인으로 실행됩니다. 여러 유형의 파일이 섞인 저장소에서는 `--code-only`를 추가하면 코드만 인덱싱하고 LLM이 필요한 문서·PDF·이미지는 건너뜁니다.
+- **동영상 / 오디오** — faster-whisper로 로컬에서 전사하며 외부로 전송하지 않습니다.
+- **문서, PDF, 이미지** — 의미 추출을 위해 AI 도우미로 전송합니다(`/graphify` 스킬을 통해 IDE 세션에서 사용 중인 모델을 이용). 헤드리스 방식의 `graphify extract`에는 `GEMINI_API_KEY` / `GOOGLE_API_KEY`(Gemini), `MOONSHOT_API_KEY`(Kimi), `ANTHROPIC_API_KEY`(Claude), `OPENAI_API_KEY`(OpenAI), `DEEPSEEK_API_KEY`(DeepSeek), 실행 중인 Ollama 인스턴스(`OLLAMA_BASE_URL`), 표준 공급자 체인의 AWS 자격 증명(Bedrock — API 키 없이 IAM 사용), 또는 `claude` CLI 실행 파일(Claude Code — API 키 없이 Claude 구독 사용) 중 하나가 필요합니다. `--dedup-llm` 플래그도 같은 키를 사용합니다.
+- **데이터 처리 위치** — `graphify extract`는 설정된 API 키를 기준으로 공급자를 자동 감지합니다(우선순위: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). 데이터 처리 위치에 관한 요구 사항이 있는 코드에는 `--backend ollama`(완전한 로컬 처리)를 사용하거나 `--backend` 플래그로 백엔드를 명시하세요. Kimi(`MOONSHOT_API_KEY`)는 중국에 있는 Moonshot AI 서버로 요청을 보냅니다.
+- **텔레메트리 없음** — 사용 추적이나 분석 데이터를 수집하지 않습니다.
+- **질의 로그** — 모든 `graphify query`, `graphify path`, `graphify explain`, MCP `query_graph` 호출을 `~/.cache/graphify-queries.log`에 JSON Lines 형식으로 기록합니다(타임스탬프, 질문, 자료 모음, 반환된 노드, 소요 시간). 전체 부분 그래프 응답은 기본적으로 저장하지 **않습니다**. 기록을 끄려면 `GRAPHIFY_QUERY_LOG_DISABLE=1`을 설정하세요. 로깅 코드 경로를 비활성화하지 않고 출력을 버리려면 `GRAPHIFY_QUERY_LOG=/dev/null`을 사용하세요.
+
+---
+
+
+## 문제 해결
+
+**설치 후 `graphify: command not found`가 표시되는 경우**
+
+CLI는 설치되었지만 실행 파일 디렉터리가 셸의 `PATH`에 없는 상태입니다. 설치 방식에 맞는 방법을 사용하세요.
+
+- **uv** (`uv tool install graphifyy`): 명령어는 uv의 도구 실행 파일 디렉터리(`~/.local/bin`)에 설치됩니다. 새로 설정한 macOS/zsh 환경에서는 이 경로가 `PATH`에 없는 경우가 많습니다. `uv tool update-shell`을 실행한 뒤 새 터미널을 여세요. (`uv tool dir --bin`으로 디렉터리를 확인할 수 있습니다.)
+- **pipx** (`pipx install graphifyy`): `pipx ensurepath`를 실행한 뒤 새 터미널을 여세요.
+- **pip** (`pip install graphifyy`): pip가 스크립트를 설치하는 사용자 실행 파일 디렉터리가 `PATH`에 없을 수 있습니다. `~/.zshrc`/`~/.bashrc`에서 `~/Library/Python/3.x/bin`(macOS) 또는 `~/.local/bin`(Linux)을 `PATH`에 추가하거나, `python -m graphify`로 실행하세요.
+
+**`uvx graphify …` 또는 `uv tool run graphify …`가 `graphify` 패키지를 찾지 못하는 경우**
+
+PyPI 패키지 이름은 `graphifyy`이며, `graphify`는 이 패키지가 제공하는 명령어일 뿐입니다. `uv tool run`은 첫 단어를 *패키지 이름*으로 처리하므로 `graphify`라는 패키지를 찾다가 `No solution found … no versions of graphify`를 출력합니다. 패키지를 명시적으로 지정하세요: `uvx --from graphifyy graphify install`(`uv tool run --from graphifyy graphify install`과 동일). 또는 `uv tool install graphifyy`로 한 번 설치한 뒤 `graphify`를 직접 실행하세요.
+
+**`uv run --with graphifyy python -m graphify`가 별다른 경고 없이 이전 설치본을 실행하는 경우**
+
+`uv run`은 *시스템* Python을 사용합니다. 따라서 같은 환경에 이전 `graphifyy`가 설치되어 있으면(예: 과거에 `pip install graphifyy`로 설치), Python이 `sys.path`에서 그 사본을 먼저 찾을 수 있으며 `--with graphifyy`가 이를 대체하지 못합니다. 오류 없이 실행되지만 *이전* 버전처럼 동작합니다. 예를 들어 `OPENAI_BASE_URL` 같은 환경 변수 설정이 조용히 무시되어 요청이 기본 엔드포인트로 전달되고, 잘못된 API 키처럼 보이는 401 오류가 발생할 수 있습니다. `warning: skill is from graphify <newer>, package is <older>`라는 줄이 보인다면 이 경우를 의심할 수 있습니다. 단순히 스킬이 오래된 것이 아니라 다른 설치본을 불러왔다는 뜻입니다. 실제로 불러온 사본을 확인하세요.
 
+```bash
+python -c "import graphify; print(graphify.__file__)"
 ```
-- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
-When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
+
+그런 다음 설치된 명령어를 직접 실행해 uv가 관리하는 사본을 사용하거나, 시스템의 오래된 설치본을 제거하세요.
+
+```bash
+uvx --from graphifyy graphify extract . --backend openai   # 패키지 이름을 명시적으로 지정
+pip uninstall graphifyy                                    # 또는 시스템의 이전 설치본 제거
 ```
 
-</details>
+**`python -m graphify`는 되지만 `graphify` 명령어는 작동하지 않는 경우**
+
+명령어가 설치된 실행 파일 디렉터리가 셸의 `PATH`에 없습니다. 일반 `pip` 대신 `uv tool install` / `pipx install`을 권장합니다. 설치 후 `uv tool update-shell` / `pipx ensurepath`를 실행하고 새 터미널을 여세요(위의 설치 참고 사항 참조).
+
+**PowerShell에서 `/graphify .` 실행 시 경로를 인식할 수 없다는 오류가 발생하는 경우**
 
-## 사용법
+PowerShell은 맨 앞의 `/`를 경로 구분자로 처리합니다. Windows에서는 슬래시 없이 `graphify .`를 사용하세요.
 
+**`--update` 또는 재생성 후 그래프의 노드 수가 줄어드는 경우**
+
+리팩터링으로 파일을 삭제해도 기존 노드가 남아 있을 수 있습니다. 재생성한 그래프의 노드 수가 더 적더라도 덮어쓰려면 `--force`를 전달하거나 `GRAPHIFY_FORCE=1`을 설정하세요.
+
+**`extract`가 `extraction was incomplete ... refusing to overwrite` 메시지와 함께 종료되는 경우**
+
+추출 도중 비정상 종료되거나 파일 순회 과정에서 자료 전체를 읽지 못하면, 결과가 완전한 추출 결과보다 작아집니다. `graphify extract`는 `graph.json`을 보호하기 위해 더 큰 기존 그래프를 불완전한 결과로 덮어쓰지 않습니다. 원인을 해결하고 다시 실행하거나, 그대로 덮어쓰려면 `--allow-partial`을 전달하세요.
+
+**같은 엔터티의 노드가 중복되는 경우(유령 중복)**
+
+유령 중복은 같은 심볼이 AST 추출에서는 소스 위치를 포함한 노드로, 의미 추출에서는 소스 위치가 없는 노드로 각각 나타나는 현상입니다. 이제는 그래프 생성 시 자동으로 병합됩니다. v0.8.33 이전에 만든 그래프에서 이 문제가 보이면 전체를 다시 추출해 정리하세요.
+
+```bash
+graphify extract . --force
 ```
-/graphify                          # 현재 디렉토리에서 실행
-/graphify ./raw                    # 특정 폴더에서 실행
-/graphify ./raw --mode deep        # 더 적극적인 INFERRED 엣지 추출
-/graphify ./raw --update           # 변경된 파일만 재추출하여 기존 그래프에 병합
-/graphify ./raw --cluster-only     # 기존 그래프의 클러스터링만 재실행, 재추출 없음
-/graphify ./raw --no-viz           # HTML 건너뛰기, 보고서 + JSON만 생성
-/graphify ./raw --obsidian                          # Obsidian 볼트도 생성 (옵트인)
-/graphify ./raw --obsidian --obsidian-dir ~/vaults/myproject  # 볼트를 특정 디렉토리에 생성
 
-/graphify add https://arxiv.org/abs/1706.03762        # 논문 가져오기, 저장, 그래프 업데이트
-/graphify add https://x.com/karpathy/status/...       # 트윗 가져오기
-/graphify add https://... --author "Name"             # 원저자 태그
-/graphify add https://... --contributor "Name"        # 코퍼스에 추가한 사람 태그
+**Ollama의 VRAM이 부족하거나 컨텍스트 윈도를 초과하는 경우**
 
-/graphify query "어텐션과 옵티마이저를 연결하는 것은?"
-/graphify query "어텐션과 옵티마이저를 연결하는 것은?" --dfs   # 특정 경로 추적
-/graphify query "어텐션과 옵티마이저를 연결하는 것은?" --budget 1500  # N 토큰으로 제한
-/graphify path "DigestAuth" "Response"
-/graphify explain "SwinTransformer"
+KV 캐시 윈도 크기는 자동 조정되지만 GPU 용량에 비해 클 수 있습니다. 크기를 줄여 보세요.
+
+```bash
+GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000
+```
+
+**`LLM returned invalid JSON` / `Unterminated string` 경고가 표시되는 경우**
+
+모델의 JSON 응답이 출력 토큰 한도에 도달해 문자열 중간에서 잘린 것입니다. graphify는 청크를 둘로 나눠 각각 다시 추출하는 방식으로 자동 복구합니다. 단일 문서가 너무 크면 먼저 제목·문단 경계를 기준으로 나누므로 파일 전체가 처리 대상에 포함됩니다. 따라서 이 경고가 반복되어도 데이터가 손실된 것은 아닙니다. 재처리를 줄이려면 출력 한도를 높이거나 청크별 출력량을 줄이세요.
+
+```bash
+GRAPHIFY_MAX_OUTPUT_TOKENS=16384 graphify extract . --mode deep   # 출력 한도 상향
+graphify extract . --mode deep --token-budget 4000                # 입력 청크를 줄여 출력량 축소
+```
+
+OpenRouter 같은 클라우드 게이트웨이를 사용할 때는 Ollama 호환 계층보다 `--backend openai`와 `OPENAI_BASE_URL` 설정을 권장합니다. OpenAI 호환 경로를 더 직접적으로 사용할 수 있습니다. 모델 자체에 최대 출력 한도가 있다면 `--token-budget`을 낮추는 것이 확실한 조정 방법입니다.
+
+**그래프 HTML이 너무 커서 브라우저에서 열리지 않는 경우(노드 5,000개 초과)**
+
+HTML 생성을 건너뛰고 JSON을 직접 사용하세요.
+
+```bash
+graphify cluster-only ./my-project --no-viz
+graphify query "..."
+```
+
+**개발자 두 명이 동시에 커밋한 뒤 `graph.json`에 충돌 표시가 생기는 경우**
+
+`graphify hook install`을 실행하세요. `graph.json`의 내용을 자동으로 합집합 병합하는 Git 병합 드라이버를 설정해 충돌을 방지합니다.
 
-/graphify ./raw --watch            # 파일 변경 시 그래프 자동 동기화 (코드: 즉시, 문서: 알림)
-/graphify ./raw --wiki             # 에이전트가 크롤 가능한 위키 빌드 (index.md + 커뮤니티별 문서)
-/graphify ./raw --svg              # graph.svg 내보내기
-/graphify ./raw --graphml          # graph.graphml 내보내기 (Gephi, yEd)
+**팀원의 최근 변경 사항이 그래프에 반영되지 않는 경우**
+
+`git pull`이나 병합 직후 `graphify update .`를 실행하세요. [권장 작업 흐름](#recommended-workflow)을 참고하세요. 커밋과 브랜치 전환은 설치된 훅이 그래프를 자동 갱신하지만, pull 후 동기화는 직접 실행해야 합니다. pull 별칭에 포함하면 한 명령으로 처리할 수 있습니다.
+
+```bash
+git config --global alias.gpull '!git pull && graphify update .'
+```
+
+`graphify hook status`로 훅이 활성화되어 있는지 확인하세요. 인터프리터를 업그레이드하거나 재설치했다면 `graphify hook install`을 다시 실행해 훅을 갱신하세요.
+
+**문서나 PDF에서 노드·엣지가 비어 있는 결과가 반환되는 경우**
+
+문서, PDF, 이미지는 LLM 호출이 필요합니다. 코드만 있는 자료 모음에는 키가 필요하지 않습니다. API 키가 설정되어 있고 백엔드가 올바른지 확인하세요.
+
+```bash
+ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude
+```
+
+**IDE에 스킬 버전 불일치 경고가 표시되는 경우**
+
+설치된 graphify와 스킬 파일의 버전이 다릅니다. 다음과 같이 업데이트하세요.
+
+```bash
+uv tool upgrade graphifyy
+graphify install  # 스킬 파일 덮어쓰기
+```
+
+**`graphify extract`를 실행할 때마다 Claude Code의 프롬프트 캐시가 무효화되는 경우**
+
+Graphify는 작업 공간에 출력 파일(`graph.json`, `graphify-out/`)을 기록합니다. 이 경로들이 제외되어 있지 않으면 파일을 쓸 때마다 Claude Code의 프롬프트 캐시가 무효화되어, 다음 턴에 전체 내용을 다시 업로드하고 캐시 쓰기 요금이 적용됩니다. `.claudeignore`에 다음을 추가하세요.
+
+```text
+# .claudeignore
+graph.json
+graphify-out/
+```
+
+---
+
+<a id="full-command-reference"></a>
+
+## 전체 명령어 참조
+
+```
+/graphify                          # 현재 디렉터리에서 실행
+/graphify ./raw                    # 지정한 폴더에서 실행
+/graphify ./raw --mode deep        # 관계를 더 적극적으로 추출
+graphify extract ./raw --code-only # 코드만 인덱싱 — 로컬 AST 사용, API 키 불필요 (문서·PDF·이미지 제외). 스킬이 아닌 extract 명령의 플래그
+/graphify ./raw --update           # 변경된 파일만 다시 추출
+/graphify ./raw --directed         # 엣지 방향 유지
+/graphify ./raw --cluster-only     # 기존 그래프에서 클러스터링 다시 실행
+/graphify ./raw --no-viz           # HTML 시각화 생략
+/graphify ./raw --obsidian         # Obsidian 보관함 생성
+/graphify ./raw --obsidian --obsidian-dir ~/vault  # 기존 보관함에 저장 (사용자 노트나 .obsidian 설정은 덮어쓰지 않음)
+/graphify ./raw --wiki             # 에이전트가 탐색할 수 있는 Markdown 위키 생성
+/graphify ./raw --svg              # graph.svg로 내보내기
+/graphify ./raw --graphml          # Gephi / yEd용으로 내보내기
 /graphify ./raw --neo4j            # Neo4j용 cypher.txt 생성
-/graphify ./raw --neo4j-push bolt://localhost:7687    # 실행 중인 Neo4j 인스턴스에 직접 푸시
+/graphify ./raw --neo4j-push bolt://localhost:7687
+/graphify ./raw --falkordb         # FalkorDB용 cypher.txt 생성
+/graphify ./raw --falkordb-push falkordb://localhost:6379
+/graphify ./raw --watch            # 파일 변경 시 자동 동기화
 /graphify ./raw --mcp              # MCP stdio 서버 시작
 
-# git 훅 - 플랫폼 무관, 커밋 및 브랜치 전환 시 그래프 재빌드
-graphify hook install
+/graphify add https://arxiv.org/abs/1706.03762
+/graphify add <video-url>
+/graphify add https://... --author "Name" --contributor "Name"
+
+/graphify query "what connects attention to the optimizer?"
+/graphify query "..." --dfs --budget 1500
+/graphify path "DigestAuth" "Response"
+/graphify explain "SwinTransformer"
+
+graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome useful   # 질의응답 결과 기록 (작업 기억. outcome 값: useful|dead_end|corrected)
+graphify reflect                   # graphify-out/memory/의 결과를 모아 reflections/LESSONS.md에 정리
+graphify reflect --if-stale        # LESSONS.md가 모든 입력보다 최신이면 생략 (세션마다 실행해도 부담이 적음)
+graphify reflect --out docs/LESSONS.md    # 학습 내용 문서를 다른 위치에 저장
+graphify reflect --graph graphify-out/graph.json  # 학습 내용을 커뮤니티별로 묶고 작업 기억 오버레이(.graphify_learning.json) 저장
+                                   # 오버레이는 노드에 preferred/tentative/contested 태그 부여 (최근 정보에 가중치, 근거 출처 포함)
+                                   # 이후 graphify explain / query에 "Lesson:" 안내 표시. 소스가 변경되면 "code changed — re-verify"로 재확인 필요 표시
+
+graphify uninstall                 # 모든 플랫폼에서 한 번에 제거
+graphify uninstall --purge         # graphify-out/도 삭제
+graphify uninstall --project --platform codex  # 프로젝트 단위로 설치한 파일만 제거
+
+graphify hook install              # post-commit + post-checkout 훅 설치
 graphify hook uninstall
 graphify hook status
 
-# 상시 작동 어시스턴트 지시 - 플랫폼별
+# 도우미에 상시 적용할 지침 — 플랫폼별 설정
 graphify claude install            # CLAUDE.md + PreToolUse 훅 (Claude Code)
 graphify claude uninstall
-graphify codex install             # AGENTS.md (Codex)
-graphify opencode install          # AGENTS.md (OpenCode)
+graphify codebuddy install         # CODEBUDDY.md + PreToolUse 훅 (CodeBuddy)
+graphify codebuddy uninstall
+graphify codex install             # AGENTS.md + .codex/hooks.json의 PreToolUse 훅 (Codex)
+graphify opencode install          # AGENTS.md + tool.execute.before 플러그인 (OpenCode)
+graphify kilo install              # Kilo 네이티브 스킬 + /graphify 명령 + AGENTS.md + .kilo 플러그인
+graphify kilo uninstall
+graphify cursor install            # .cursor/rules/graphify.mdc (Cursor)
+graphify cursor uninstall
+graphify gemini install            # GEMINI.md + BeforeTool 훅 (Gemini CLI)
+graphify gemini uninstall
+graphify copilot install           # 스킬 파일 (GitHub Copilot CLI)
+graphify copilot uninstall
+graphify aider install             # AGENTS.md (Aider)
+graphify aider uninstall
 graphify claw install              # AGENTS.md (OpenClaw)
+graphify claw uninstall
 graphify droid install             # AGENTS.md (Factory Droid)
+graphify droid uninstall
 graphify trae install              # AGENTS.md (Trae)
 graphify trae uninstall
 graphify trae-cn install           # AGENTS.md (Trae CN)
 graphify trae-cn uninstall
-
-# 터미널에서 직접 그래프 쿼리 (AI 어시스턴트 불필요)
-graphify query "어텐션과 옵티마이저를 연결하는 것은?"
-graphify query "인증 흐름 보기" --dfs
-graphify query "CfgNode이 뭐지?" --budget 500
-graphify query "..." --graph path/to/graph.json
+graphify hermes install             # AGENTS.md + ~/.hermes/skills/ (Hermes)
+graphify hermes uninstall
+graphify amp install               # 스킬 파일 (Amp)
+graphify amp uninstall
+graphify agents install            # ~/.agents/skills/ + AGENTS.md (프레임워크 공통. 별칭: graphify skills)
+graphify agents uninstall
+graphify kiro install               # .kiro/skills/ + .kiro/steering/graphify.md (Kiro IDE/CLI)
+graphify kiro uninstall
+graphify pi install                # 스킬 파일 (Pi coding agent)
+graphify pi uninstall
+graphify devin install             # 스킬 파일 + .windsurf/rules/graphify.md (Devin CLI)
+graphify devin uninstall
+graphify antigravity install       # .agents/rules + .agents/workflows (Google Antigravity)
+graphify antigravity uninstall
+
+graphify extract ./docs                        # CI용 헤드리스 LLM 추출 (IDE 불필요)
+graphify extract ./docs --backend gemini       # 백엔드 명시: gemini, kimi, claude, openai, deepseek, ollama, bedrock, claude-cli 중 선택
+graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
+graphify extract ./docs --backend ollama       # 로컬 Ollama (OLLAMA_BASE_URL / OLLAMA_MODEL 설정). 루프백 연결은 API 키 불필요
+OPENAI_BASE_URL=http://localhost:8080/v1 OPENAI_MODEL=my-model graphify extract ./docs --backend openai   # 모든 OpenAI 호환 서버 (llama.cpp, vLLM, LM Studio)
+ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_MODEL=my-model graphify extract ./docs --backend claude   # 모든 Anthropic 호환 엔드포인트 (LiteLLM 프록시, 게이트웨이)
+GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama   # KV 캐시 윈도 크기 직접 지정 (기본값은 자동 조정)
+GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama    # 청크 처리 후마다 모델 해제 (소형 GPU의 VRAM 절약)
+graphify extract ./docs --backend bedrock      # IAM으로 AWS Bedrock 사용. API 키 없이 AWS 자격 증명 체인 사용
+graphify extract ./docs --backend claude-cli   # Claude Code CLI를 경유. API 키 없이 Claude 구독 사용
+graphify extract ./docs --backend azure        # Azure OpenAI (AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT 설정)
+graphify extract ./docs --max-workers 16       # AST 병렬 처리 수 (GRAPHIFY_MAX_WORKERS로도 설정 가능)
+graphify extract --postgres "postgresql://user:pass@host/db"   # 실행 중인 PostgreSQL 스키마를 직접 조사
+graphify extract ./my-workspace --cargo        # Rust Cargo 작업 공간의 의존성을 직접 조사
+graphify extract ./docs --token-budget 30000   # 로컬·소형 모델용으로 의미 분석 청크 크기 축소
+graphify extract ./docs --max-concurrency 2    # 병렬 LLM 호출 수 축소 (로컬 추론에 유용)
+graphify extract ./docs --api-timeout 900      # 느린 로컬 모델을 위해 HTTP 제한 시간 연장 (기본값 600초)
+graphify extract ./docs --google-workspace     # 추출 전에 gws로 .gdoc/.gsheet/.gslides 내보내기
+graphify extract ./src --no-gitignore          # Git에서 제외한 소스도 포함. .graphifyignore는 계속 적용
+graphify extract ./docs --mode deep            # 확장된 시스템 프롬프트로 더 풍부하게 의미 추출
+graphify extract ./docs --no-cluster           # 클러스터링 없이 원시 추출만 수행
+graphify extract ./docs --timing               # 단계별 실제 경과 시간을 stderr에 출력 (cluster-only에서도 사용 가능)
+graphify extract ./docs --force                # 새 그래프의 노드 수가 적어도 graph.json 덮어쓰기 (리팩터링 후 또는 유령 중복 정리에 사용)
+graphify extract ./docs --dedup-llm            # 모호한 엔터티 쌍의 중복 여부를 LLM으로 판정 (같은 API 키 사용)
+graphify extract ./src --no-dedup              # 엔터티 중복 제거 생략. 증분 병합 시 변경되지 않은 파일의 노드를 삭제하지 못하게 하는 축소 방지 기능도 활성화
+graphify extract ./docs --global --as myrepo   # 추출 후 여러 프로젝트를 아우르는 전역 그래프에 등록
+GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude  # 정보 밀도가 높은 자료 모음의 출력 한도 상향
+
+graphify export callflow-html                       # graphify-out/<project>-callflow.html
+graphify export callflow-html --max-sections 8      # 생성할 아키텍처 섹션 수 제한
+graphify export callflow-html --output docs/arch.html
+graphify export callflow-html ./some-repo/graphify-out
+
+graphify global add graphify-out/graph.json --as myrepo   # 프로젝트 그래프를 ~/.graphify/global-graph.json에 등록
+graphify global remove myrepo                         # 전역 그래프에서 프로젝트 제거
+graphify global list                                  # 등록된 모든 저장소와 노드·엣지 수 표시
+graphify global path                                  # 전역 그래프 파일 경로 출력
+
+graphify prs                              # PR 대시보드: CI, 리뷰, worktree, 그래프 영향
+graphify prs 42                           # PR #42 상세 분석
+graphify prs --triage                     # AI 우선순위 분류 (환경 변수에서 백엔드 자동 감지)
+graphify prs --worktrees                  # worktree → 브랜치 → PR 연결 정보
+graphify prs --conflicts                  # 그래프 커뮤니티를 공유하는 PR (병합 순서에 따른 위험)
+graphify prs --base main                  # 특정 대상 브랜치로 향하는 PR만 필터링
+graphify prs --repo owner/repo            # 다른 GitHub 저장소를 대상으로 실행
+GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage   # 우선순위 분류에 사용할 백엔드 지정
+
+graphify clone https://github.com/karpathy/nanoGPT
+graphify merge-graphs a.json b.json --out merged.json
+graphify --version                                    # 설치된 버전 출력
+graphify watch ./src
+graphify check-update ./src
+graphify update ./src
+graphify update ./src --no-cluster  # 재클러스터링 없이 원시 AST 그래프만 저장
+graphify update ./src --force       # 새 그래프의 노드 수가 적어도 덮어쓰기
+graphify cluster-only ./my-project
+graphify cluster-only ./my-project --graph path/to/graph.json  # 그래프 위치 직접 지정
+graphify cluster-only ./my-project --max-concurrency 16 --batch-size 200  # 커뮤니티 이름을 병렬로 지정 (대형 그래프용)
+graphify cluster-only ./my-project --resolution 1.5            # 더 작고 많은 커뮤니티로 분할
+graphify cluster-only ./my-project --exclude-hubs 99           # 연결 차수가 99백분위인 노드를 분할에서 제외
+graphify cluster-only ./my-project --no-label                  # 임시 이름 "Community N" 유지
+graphify cluster-only ./my-project --backend=gemini            # 커뮤니티 이름 지정에 사용할 백엔드
+graphify cluster-only ./my-project --backend=gemini --model gemini-2.5-pro  # 특정 모델 지정
+graphify label ./my-project                                    # 설정된 백엔드로 커뮤니티 이름 지정·재지정
+graphify label ./my-project --backend=openai --model gpt-4o   # 특정 백엔드와 모델을 강제로 지정
 ```
 
-다양한 파일 유형의 조합과 함께 동작합니다:
+> **커뮤니티 이름:** 에이전트(Claude Code, Gemini CLI) 안에서는 에이전트가 직접 이름을 붙입니다. CLI만 실행하는 경우에는 `cluster-only`가 설정된 백엔드(내장 공급자 또는 사용자 지정 OpenAI 호환 공급자)로 이름을 자동 생성합니다. `Community N`을 유지하려면 `--no-label`을 전달하고, 필요할 때 이름을 생성하거나 다시 생성하려면 `graphify label`을 실행하세요.
 
-| 유형 | 확장자 | 추출 방식 |
-|------|--------|-----------|
-| 코드 | `.py .ts .js .jsx .tsx .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .exs .m .mm .jl` | tree-sitter AST + 콜 그래프 + docstring/주석 근거 |
-| 문서 | `.md .txt .rst` | Claude를 통한 개념 + 관계 + 설계 근거 |
-| 오피스 | `.docx .xlsx` | 마크다운으로 변환 후 Claude를 통해 추출 (`pip install graphifyy[office]` 필요) |
-| 논문 | `.pdf` | 인용 마이닝 + 개념 추출 |
-| 이미지 | `.png .jpg .webp .gif` | Claude Vision - 스크린샷, 다이어그램, 모든 언어 |
+---
 
-## 결과물
 
-**갓 노드** - 최고 차수의 개념 (모든 것이 연결되는 허브)
+## 더 알아보기
 
-**의외의 연결** - 복합 점수로 순위 지정. 코드-논문 엣지는 코드-코드보다 높게 순위됩니다. 각 결과에는 쉬운 설명이 포함됩니다.
+- [작동 원리](https://github.com/Graphify-Labs/graphify/blob/v8/docs/how-it-works.md) — 추출 파이프라인, 커뮤니티 탐지, 신뢰도 평가, 벤치마크
+- [ARCHITECTURE.md](https://github.com/Graphify-Labs/graphify/blob/v8/ARCHITECTURE.md) — 모듈 구성과 언어 추가 방법
+- [선택적 연동](https://github.com/Graphify-Labs/graphify/blob/v8/docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
+- [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo) — graphify의 바탕이 된 아이디어와 전체 아키텍처를 설명하는 책
 
-**추천 질문** - 그래프가 고유하게 답할 수 있는 4~5개의 질문
+---
 
-**"이유"** - docstring, 인라인 주석(`# NOTE:`, `# IMPORTANT:`, `# HACK:`, `# WHY:`), 문서의 설계 근거가 `rationale_for` 노드로 추출됩니다. 코드가 무엇을 하는지뿐만 아니라 — 왜 그렇게 작성되었는지.
+## graphify Enterprise
 
-**신뢰도 점수** - 모든 INFERRED 엣지에는 `confidence_score`(0.0~1.0)가 있습니다. 무엇이 추측되었는지뿐 아니라 모델이 얼마나 확신했는지도 알 수 있습니다. EXTRACTED 엣지는 항상 1.0입니다.
+[**graphify Enterprise**](https://graphify.com)는 graphify를 기반으로 상시 작동하는 서비스입니다. 회의, 파일, 문서, 코드 등 업무 맥락 전체에 같은 그래프 접근 방식을 적용하고, 백그라운드에서 계속 갱신합니다.
 
-**의미적 유사성 엣지** - 구조적 연결 없는 파일 간 개념 링크. 서로를 호출하지 않으면서 같은 문제를 해결하는 두 함수, 코드의 클래스와 같은 알고리즘을 설명하는 논문의 개념 등.
+수백 건의 대화와 문서에 흩어진 업무 내용을 온전히 되짚기 어려운 개인과 팀을 위해 만들었습니다.
 
-**하이퍼엣지** - 쌍별 엣지로는 표현할 수 없는 3개 이상 노드의 그룹 관계. 공유 프로토콜을 구현하는 모든 클래스, 인증 흐름의 모든 함수, 논문 섹션에서 하나의 아이디어를 구성하는 모든 개념 등.
+**[graphify.com에서 대기자 명단에 등록하세요](https://graphify.com).** 무료 체험도 곧 제공될 예정입니다.
 
-**토큰 벤치마크** - 매 실행 후 자동으로 출력됩니다. 혼합 코퍼스(Karpathy 리포지토리 + 논문 + 이미지)에서: 원본 파일 대비 쿼리당 **71.5배** 적은 토큰. 첫 실행은 추출과 그래프 빌드를 수행합니다(토큰이 소비됩니다). 이후 모든 쿼리는 원본 파일 대신 압축된 그래프를 읽습니다 — 여기서 절약이 복리로 누적됩니다. SHA256 캐시로 재실행 시 변경된 파일만 재처리합니다.
+---
 
-**자동 동기화** (`--watch`) - 백그라운드 터미널에서 실행하면 코드베이스가 변경될 때 그래프가 자동으로 업데이트됩니다. 코드 파일 저장 시 즉시 재빌드가 트리거됩니다(AST만, LLM 없음). 문서/이미지 변경 시에는 LLM 재처리를 위해 `--update` 실행을 알려줍니다.
+<details>
+<summary>기여하기</summary>
 
-**Git 훅** (`graphify hook install`) - post-commit 및 post-checkout 훅을 설치합니다. 모든 커밋과 브랜치 전환 후 그래프가 자동으로 재빌드됩니다. 재빌드가 실패하면 훅이 0이 아닌 코드로 종료하여 git이 에러를 표시하고 조용히 계속 진행하지 않습니다. 백그라운드 프로세스가 필요 없습니다.
+### 개발 환경 설정
 
-**위키** (`--wiki`) - 커뮤니티 및 갓 노드별 위키피디아 스타일 마크다운 문서와 `index.md` 진입점. 어떤 에이전트든 `index.md`를 가리키면 JSON을 파싱하는 대신 파일을 읽어서 지식 베이스를 탐색할 수 있습니다.
+이 프로젝트는 개발 작업에 [uv](https://docs.astral.sh/uv/)를 사용합니다. uv를 한 번 설치한 뒤 다음을 실행하세요.
 
-## 실전 예제
+```bash
+git clone https://github.com/safishamsi/graphify.git
+cd graphify
+git checkout v8                        # 현재 개발이 진행되는 브랜치
+
+# 프로젝트 가상 환경을 만들고 graphify, 모든 선택 기능, 개발 의존성 그룹
+# (pytest)을 설치합니다. uv는 기본적으로 개발 의존성 그룹도 설치합니다.
+# 제외하려면 --no-dev를 전달하세요.
+uv sync --all-extras
+```
 
-| 코퍼스 | 파일 수 | 축소율 | 결과 |
-|--------|---------|--------|------|
-| Karpathy 리포지토리 + 논문 5편 + 이미지 4장 | 52 | **71.5x** | [`worked/karpathy-repos/`](worked/karpathy-repos/) |
-| graphify 소스 + Transformer 논문 | 4 | **5.4x** | [`worked/mixed-corpus/`](worked/mixed-corpus/) |
-| httpx (합성 Python 라이브러리) | 6 | ~1x | [`worked/httpx/`](worked/httpx/) |
+소스 수정 사항이 바로 반영되는 편집 가능 설치가 되었는지 확인하세요.
 
-토큰 축소는 코퍼스 크기에 비례하여 확장됩니다. 6개 파일은 어차피 컨텍스트 윈도우에 들어가므로, 그래프의 가치는 압축이 아닌 구조적 명확성에 있습니다. 52개 파일(코드 + 논문 + 이미지)에서는 71배 이상을 달성합니다. 각 `worked/` 폴더에는 원본 입력 파일과 실제 출력(`GRAPH_REPORT.md`, `graph.json`)이 있어 직접 실행하여 수치를 검증할 수 있습니다.
+```bash
+uv run graphify --version
+uv run python -c "import graphify; print(graphify.__file__)"
+```
 
-## 개인정보 보호
+### 테스트 실행
 
-graphify는 문서, 논문, 이미지의 의미적 추출을 위해 파일 내용을 AI 코딩 어시스턴트의 기반 모델 API로 전송합니다 — Anthropic(Claude Code), OpenAI(Codex), 또는 사용 중인 플랫폼의 제공자. 코드 파일은 tree-sitter AST를 통해 로컬에서 처리됩니다 — 코드의 경우 파일 내용이 사용자의 머신을 벗어나지 않습니다. 어떠한 텔레메트리, 사용 추적, 분석도 없습니다. 유일한 네트워크 호출은 추출 중 플랫폼 모델 API에 대한 것이며, 사용자 본인의 API 키를 사용합니다.
+```bash
+uv run pytest tests/ -q                # 전체 테스트 실행
+uv run pytest tests/test_extract.py -q # 단일 모듈 실행
+uv run pytest tests/ -q -k "python"    # 이름으로 필터링
+```
 
-## 기술 스택
+### CI와 동일한 조건으로 검사하기
 
-NetworkX + Leiden (graspologic) + tree-sitter + vis.js. 의미적 추출은 Claude(Claude Code), GPT-4(Codex), 또는 플랫폼이 실행하는 모델을 통해 수행됩니다. Neo4j 불필요, 서버 불필요, 완전히 로컬에서 실행됩니다.
+기준이 되는 CI 명령어는 [`.github/workflows/`](https://github.com/Graphify-Labs/graphify/tree/v8/.github/workflows/)에 있습니다. 로컬에서 CI와 같은 방식으로 검증하려면 Python 3.10, 3.12, 3.13 또는 3.14를 사용해 다음을 실행하세요.
 
-## 다음 계획
+```bash
+uv sync --all-extras --frozen
+uv run --frozen pytest tests/ -q --tb=short
+uv run --frozen python -m tools.skillgen --check
+uv run --frozen python -m tools.skillgen --audit-coverage
+uv run --frozen python -m tools.skillgen --schema-singleton
+uv run --frozen python -m tools.skillgen --monolith-roundtrip
+uv run --frozen python -m tools.skillgen --always-on-roundtrip
+uv run --frozen graphify --help
+uv run --frozen graphify install
+```
 
-graphify는 그래프 레이어입니다. 그 위에 [Penpax](https://safishamsi.github.io/penpax.ai)를 개발하고 있습니다 — 회의, 브라우저 기록, 파일, 이메일, 코드를 하나의 지속적으로 업데이트되는 지식 그래프로 연결하는 온디바이스 디지털 트윈입니다. 클라우드 없음, 데이터 학습 없음. [대기 목록에 등록하세요.](https://safishamsi.github.io/penpax.ai)
+Ruff는 추가 로컬 검사(`uv run --frozen ruff check .`)에 유용하지만, 현재는 실패 시 CI를 중단시키는 필수 작업이 아닙니다. Pyright도 향후 CI에 추가되기 전까지는 로컬 참고용 검사입니다. Bandit과 pip-audit CI 단계에는 현재 `continue-on-error`가 설정되어 있으므로, 발견 사항은 참고용이며 CI를 중단시키지 않습니다.
 
-## 스타 히스토리
+> macOS 참고: 테스트 모음에는 `sample.f90`과 `sample.F90` 픽스처가 모두 포함되어 있습니다. 대소문자를 구분하지 않는 HFS+ / APFS 파일 시스템에서는 두 파일이 충돌합니다. 두 Fortran 변형을 동시에 테스트하려면 Linux나 Docker 컨테이너에서 실행하세요.
 
-[![Star History Chart](https://starchart.cc/safishamsi/graphify.svg)](https://starchart.cc/safishamsi/graphify)
+> Windows 참고: 네이티브 Windows 테스트 모음은 심볼릭 링크, 긴 경로, POSIX 권한, 경로 구분자, UTF-8 파일 시스템 동작을 검사합니다. 관리자 권한 없이 심볼릭 링크를 만들 수 있도록 Windows 개발자 모드를 켜거나, 관리자 권한 셸에서 테스트를 실행하세요. 긴 경로 테스트를 사용하기 전에 Windows의 `LongPathsEnabled` 정책을 활성화하세요. 두 설정 중 하나를 변경했다면 영향을 받는 셸이나 애플리케이션을 다시 시작하세요. 필수 GitHub Actions 테스트 매트릭스와 정확히 같은 조건을 맞추려면 WSL이나 Linux에서 테스트를 실행하세요. 현재 CI는 Ubuntu에서 Python 3.10, 3.12, 3.13, 3.14로 실행됩니다. Pyright는 로컬 참고용 검사로 사용할 수 있지만, 현재 필수 CI 작업은 아닙니다.
 
-<details>
-<summary>기여하기</summary>
+### Git 작업 흐름
+
+- 개발은 `v8` 브랜치에서 진행합니다.
+- 커밋 형식: `fix: <description>` / `feat: <description>` / `docs: <description>`
+- PR을 열기 전에 `uv run pytest tests/ -q`를 실행하고 통과하는지 확인하세요.
+- 새 언어 추출기를 추가할 때는 `tests/fixtures/`에 픽스처 파일을, `tests/test_languages.py`에 테스트를 추가하세요.
+
+### 기여할 수 있는 내용
 
-**실전 예제**는 가장 신뢰를 쌓는 기여 방식입니다. 실제 코퍼스에서 `/graphify`를 실행하고, 결과를 `worked/{slug}/`에 저장하고, 그래프가 맞게 파악한 것과 틀린 것을 평가하는 솔직한 `review.md`를 작성하여 PR을 제출하세요.
+가장 유용한 기여는 **실제 사용 사례**입니다. 실제 자료 모음에 `/graphify`를 실행하고, 결과를 `worked/{slug}/`에 저장한 뒤, 그래프가 잘 파악한 점과 잘못 파악한 점을 솔직하게 담은 `review.md`를 작성해 PR을 열어 주세요.
 
-**추출 버그** - 입력 파일, 캐시 엔트리(`graphify-out/cache/`), 그리고 누락되거나 날조된 내용과 함께 이슈를 열어주세요.
+**추출 버그** — 입력 파일, 캐시 항목(`graphify-out/cache/`), 누락되거나 잘못된 내용을 첨부해 이슈를 등록하세요.
 
-모듈 책임과 언어 추가 방법은 [ARCHITECTURE.md](ARCHITECTURE.md)를 참조하세요.
+모듈별 역할과 언어 추가 방법은 [ARCHITECTURE.md](https://github.com/Graphify-Labs/graphify/blob/v8/ARCHITECTURE.md)를 참고하세요.
 
 </details>
+
+---
+
+## 커뮤니티 및 링크
+
+<p align="center">
+  <a href="https://graphify.com"><img src="https://img.shields.io/badge/Website-graphify.com-4c1?style=flat&logo=googlechrome&logoColor=white" alt="웹사이트"/></a>
+  <a href="https://discord.gg/2DDrEgvZb4"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord"/></a>
+  <a href="https://x.com/graphify"><img src="https://img.shields.io/badge/X-graphify-000000?logo=x&logoColor=white" alt="X"/></a>
+  <a href="https://www.youtube.com/@graphifylabs"><img src="https://img.shields.io/badge/YouTube-Graphify%20Labs-FF0000?style=flat&logo=youtube&logoColor=white" alt="YouTube"/></a>
+  <a href="https://github.com/sponsors/safishamsi"><img src="https://img.shields.io/badge/sponsor-safishamsi-ea4aaa?logo=github-sponsors" alt="후원"/></a>
+  <a href="https://safishamsi.gumroad.com/l/qetvlo"><img src="https://img.shields.io/badge/Book-The%20Memory%20Layer-2ea44f?style=flat&logo=gitbook&logoColor=white" alt="The Memory Layer"/></a>
+</p>

From a192dfacde18354e6b0aea06cd041877e8c376d4 Mon Sep 17 00:00:00 2001
From: Kobe <dev.skyachieve91@gmail.com>
Date: Tue, 15 Sep 2026 06:07:17 +0900
Subject: [PATCH 2/3] docs: fix repository URL in Korean README

Update the git clone URL from safishamsi/graphify to Graphify-Labs/graphify to match the repository links used throughout the Korean README.
---
 docs/translations/README.ko-KR.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/translations/README.ko-KR.md b/docs/translations/README.ko-KR.md
index 74361f34c4..9a8ee50fec 100644
--- a/docs/translations/README.ko-KR.md
+++ b/docs/translations/README.ko-KR.md
@@ -888,7 +888,7 @@ graphify label ./my-project --backend=openai --model gpt-4o   # 특정 백엔드
 이 프로젝트는 개발 작업에 [uv](https://docs.astral.sh/uv/)를 사용합니다. uv를 한 번 설치한 뒤 다음을 실행하세요.
 
 ```bash
-git clone https://github.com/safishamsi/graphify.git
+git clone https://github.com/Graphify-Labs/graphify.git
 cd graphify
 git checkout v8                        # 현재 개발이 진행되는 브랜치
 

From 7e67f567e3db233b64366451c0ba04573562bffd Mon Sep 17 00:00:00 2001
From: Kobe <dev.skyachieve91@gmail.com>
Date: Tue, 15 Sep 2026 06:28:26 +0900
Subject: [PATCH 3/3] docs: revise Korean README translation and fix
 inconsistencies

Review the Korean translation against the English README and improve technical wording.

- Update the clone URL to Graphify-Labs/graphify.
- Clarify opt-in query logging and ignore-rule behavior based on the v8 implementation.
- Remove the duplicate language list and use repository-relative documentation links.
- Check section coverage, command examples, table values, and links.

Documentation only; no application code changed. Tests were not run.
---
 docs/translations/README.ko-KR.md | 45 +++++++++++++++----------------
 1 file changed, 21 insertions(+), 24 deletions(-)

diff --git a/docs/translations/README.ko-KR.md b/docs/translations/README.ko-KR.md
index 9a8ee50fec..1f5ccac45b 100644
--- a/docs/translations/README.ko-KR.md
+++ b/docs/translations/README.ko-KR.md
@@ -13,7 +13,7 @@
 <div align="center">
 <details><summary><b>다른 언어로 읽기</b></summary>
 
-🇺🇸 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/README.md">English</a> | 🇨🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.zh-CN.md">简体中文</a> | 🇯🇵 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ja-JP.md">日本語</a> | 🇰🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ko-KR.md">한국어</a> | 🇩🇪 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.de-DE.md">Deutsch</a> | 🇫🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fr-FR.md">Français</a> | 🇪🇸 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.es-ES.md">Español</a> | 🇮🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.hi-IN.md">हिन्दी</a> | 🇧🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.pt-BR.md">Português</a> | 🇷🇺 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ru-RU.md">Русский</a> | 🇸🇦 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ar-SA.md">العربية</a> | 🇮🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fa-IR.md">فارسی</a> | 🇮🇹 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.it-IT.md">Italiano</a> | 🇵🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.pl-PL.md">Polski</a> | 🇳🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.nl-NL.md">Nederlands</a> | 🇹🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.tr-TR.md">Türkçe</a> | 🇺🇦 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.uk-UA.md">Українська</a> | 🇻🇳 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.vi-VN.md">Tiếng Việt</a> | 🇮🇩 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.id-ID.md">Bahasa Indonesia</a> | 🇸🇪 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.sv-SE.md">Svenska</a> | 🇬🇷 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.el-GR.md">Ελληνικά</a> | 🇷🇴 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.ro-RO.md">Română</a> | 🇨🇿 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.cs-CZ.md">Čeština</a> | 🇫🇮 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fi-FI.md">Suomi</a> | 🇩🇰 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.da-DK.md">Dansk</a> | 🇳🇴 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.no-NO.md">Norsk</a> | 🇭🇺 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.hu-HU.md">Magyar</a> | 🇹🇭 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.th-TH.md">ภาษาไทย</a> | 🇺🇿 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.uz-UZ.md">Oʻzbekcha</a> | 🇹🇼 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.zh-TW.md">繁體中文</a> | 🇵🇭 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.fil-PH.md">Filipino</a> | 🇮🇱 <a href="https://github.com/Graphify-Labs/graphify/blob/v8/docs/translations/README.he-IL.md">עברית</a>
+🇺🇸 <a href="../../README.md">English</a> | 🇨🇳 <a href="README.zh-CN.md">简体中文</a> | 🇯🇵 <a href="README.ja-JP.md">日本語</a> | 🇰🇷 <a href="README.ko-KR.md">한국어</a> | 🇩🇪 <a href="README.de-DE.md">Deutsch</a> | 🇫🇷 <a href="README.fr-FR.md">Français</a> | 🇪🇸 <a href="README.es-ES.md">Español</a> | 🇮🇳 <a href="README.hi-IN.md">हिन्दी</a> | 🇧🇷 <a href="README.pt-BR.md">Português</a> | 🇷🇺 <a href="README.ru-RU.md">Русский</a> | 🇸🇦 <a href="README.ar-SA.md">العربية</a> | 🇮🇷 <a href="README.fa-IR.md">فارسی</a> | 🇮🇹 <a href="README.it-IT.md">Italiano</a> | 🇵🇱 <a href="README.pl-PL.md">Polski</a> | 🇳🇱 <a href="README.nl-NL.md">Nederlands</a> | 🇹🇷 <a href="README.tr-TR.md">Türkçe</a> | 🇺🇦 <a href="README.uk-UA.md">Українська</a> | 🇻🇳 <a href="README.vi-VN.md">Tiếng Việt</a> | 🇮🇩 <a href="README.id-ID.md">Bahasa Indonesia</a> | 🇸🇪 <a href="README.sv-SE.md">Svenska</a> | 🇬🇷 <a href="README.el-GR.md">Ελληνικά</a> | 🇷🇴 <a href="README.ro-RO.md">Română</a> | 🇨🇿 <a href="README.cs-CZ.md">Čeština</a> | 🇫🇮 <a href="README.fi-FI.md">Suomi</a> | 🇩🇰 <a href="README.da-DK.md">Dansk</a> | 🇳🇴 <a href="README.no-NO.md">Norsk</a> | 🇭🇺 <a href="README.hu-HU.md">Magyar</a> | 🇹🇭 <a href="README.th-TH.md">ภาษาไทย</a> | 🇺🇿 <a href="README.uz-UZ.md">Oʻzbekcha</a> | 🇹🇼 <a href="README.zh-TW.md">繁體中文</a> | 🇵🇭 <a href="README.fil-PH.md">Filipino</a> | 🇮🇱 <a href="README.he-IL.md">עברית</a>
 
 </details>
 </div>
@@ -33,14 +33,14 @@
 
 AI 코딩 도우미에서 `/graphify`를 입력하면 프로젝트 전체(코드, 문서, PDF, 이미지, 동영상)를 **지식 그래프**로 만들어 줍니다. 이제 파일을 일일이 grep으로 검색하는 대신 **그래프에 질문**할 수 있습니다.
 
-- **코드 그래프는 무료로, 모든 처리는 로컬에서.** 코드는 tree-sitter의 추상 구문 트리(AST)로 파싱합니다. 같은 입력에는 같은 결과를 내며, LLM을 사용하지 않고 데이터도 컴퓨터 밖으로 전송하지 않습니다. (문서, PDF, 이미지, 동영상은 도우미의 모델이나 설정한 API 키를 사용해 의미를 분석합니다.)
+- **코드는 무료로, 로컬에서만 그래프로 변환합니다.** 코드는 tree-sitter의 추상 구문 트리(AST)로 파싱합니다. 같은 입력에는 같은 결과를 내며, LLM을 사용하지 않고 데이터도 컴퓨터 밖으로 전송하지 않습니다. (문서, PDF, 이미지, 동영상은 도우미의 모델이나 설정한 API 키를 사용해 의미를 분석합니다.)
 - **모든 연결에는 근거가 있습니다.** 각 연결에는 `EXTRACTED`(소스에 명시됨) 또는 `INFERRED`(graphify가 관계를 해석해 도출함) 태그가 붙어, 직접 추출한 정보와 추론한 정보를 구분할 수 있습니다.
 - **벡터 인덱스가 아닌 실제 그래프입니다.** 임베딩이나 벡터 저장소 없이 그래프를 직접 탐색합니다. 질문을 하거나, 두 요소 사이의 경로를 추적하거나, 특정 개념에 대한 설명을 확인할 수 있습니다.
 
 > 필요할 때만 실행하는 데서 나아가, 코드·문서·회의 전반의 정보를 백그라운드에서 계속 갱신하고 싶으신가요? **[graphify.com](https://graphify.com)**에서 바로 그런 서비스를 만들고 있습니다. 지금 **[app.graphify.com](https://app.graphify.com/login)**에서 얼리 액세스를 이용할 수 있습니다.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/graph-hero.png" alt="FastAPI 코드베이스를 힘 기반 레이아웃의 지식 그래프로 보여 주는 graphify의 대화형 graph.html. 탐지된 커뮤니티의 범례도 표시됩니다." width="900">
+  <img src="https://raw.githubusercontent.com/Graphify-Labs/graphify/v8/docs/graph-hero.png" alt="FastAPI 코드베이스를 힘 기반 배치 방식의 지식 그래프로 보여 주는 graphify의 대화형 graph.html. 탐지된 커뮤니티의 범례도 표시됩니다." width="900">
 </p>
 <p align="center">
   <em>graphify로 시각화한 FastAPI 코드베이스입니다. 각 노드는 하나의 개념을, 색상은 탐지된 커뮤니티를 나타냅니다. graph.html에서 모든 요소를 클릭해 살펴볼 수 있습니다.</em>
@@ -128,7 +128,7 @@ Shortest path (3 hops):
 | LongMemEval-S (n=50) | 질의응답 정확도 | **76%** | dense RAG와 동률 |
 | 그래프 구축 | LLM 크레딧 | **0** | 대부분의 시스템은 토큰별 과금 |
 
-모든 시스템을 동일한 테스트 환경에서 같은 모델과 예산으로 실행했습니다. 평가는 별도의 두 번째 평가자와 블라인드 방식으로 대조 검증했습니다(일치율 90.6%, Cohen's kappa 0.81). 시스템별 전체 결과표, 코드 이해 성능 결과, 재현 명령어는 **[BENCHMARKS.md](https://github.com/Graphify-Labs/graphify/blob/v8/BENCHMARKS.md)**에서 확인할 수 있습니다.
+모든 시스템을 동일한 평가 환경에서 같은 모델과 예산으로 실행했습니다. 평가자가 결과를 채점했으며, 그 판정을 두 번째 평가자의 판정과 블라인드 방식으로 대조해 검증했습니다(일치율 90.6%, Cohen's kappa 0.81). 시스템별 전체 결과표, 코드 이해 성능 결과, 재현 명령어는 **[BENCHMARKS.md](../../BENCHMARKS.md)**에서 확인할 수 있습니다.
 
 ---
 
@@ -253,7 +253,7 @@ Codex에서 병렬 추출을 사용하려면 `~/.codex/config.toml`의 `[feature
 | `pdf` | PDF 추출 | `uv tool install "graphifyy[pdf]"` |
 | `office` | `.docx` 및 `.xlsx` 지원 | `uv tool install "graphifyy[office]"` |
 | `google` | Google Sheets 렌더링 | `uv tool install "graphifyy[google]"` |
-| `video` | 동영상·오디오 전사(faster-whisper + yt-dlp) | `uv tool install "graphifyy[video]"` |
+| `video` | 동영상·오디오 전사(음성을 텍스트로 변환, faster-whisper + yt-dlp) | `uv tool install "graphifyy[video]"` |
 | `mcp` | MCP stdio 서버 | `uv tool install "graphifyy[mcp]"` |
 | `neo4j` | Neo4j로 전송 지원 | `uv tool install "graphifyy[neo4j]"` |
 | `falkordb` | FalkorDB로 전송 지원 | `uv tool install "graphifyy[falkordb]"` |
@@ -273,7 +273,7 @@ Codex에서 병렬 추출을 사용하려면 `~/.codex/config.toml`의 `[feature
 | `ocaml` | OCaml `.ml`/`.mli` AST 추출 | `uv tool install "graphifyy[ocaml]"` |
 | `commonlisp` | Common Lisp `.lisp`/`.cl`/`.lsp`/`.asd` AST 추출 | `uv tool install "graphifyy[commonlisp]"` |
 | `robot` | Robot Framework `.robot`/`.resource` 추출(스위트, 테스트 케이스, 키워드, 키워드 호출 및 리소스·라이브러리 가져오기 관계) | `uv tool install "graphifyy[robot]"` |
-| `chinese` | 중국어 질의 분절(jieba) | `uv tool install "graphifyy[chinese]"` |
+| `chinese` | 중국어 질의의 단어 분리(jieba) | `uv tool install "graphifyy[chinese]"` |
 | `all` | 위의 모든 기능 | `uv tool install "graphifyy[all]"` |
 
 </details>
@@ -332,19 +332,18 @@ Codex에서 병렬 추출을 사용하려면 `~/.codex/config.toml`의 `[feature
 
 - **핵심 허브 노드(God nodes)** — 프로젝트에서 가장 많은 연결을 가진 개념입니다. 주요 흐름이 이 노드들을 거칩니다.
 - **의외의 연결 관계** — 서로 다른 파일이나 모듈에 있는 요소 사이의 연결입니다. 예상하기 어려운 관계일수록 높은 순위에 표시됩니다.
-- **설계의 이유** — 인라인 주석(`# NOTE:`, `# WHY:`, `# HACK:`), 독스트링, 문서에 담긴 설계 근거를 별도 노드로 추출하고, 해당 내용이 설명하는 코드에 연결합니다.
+- **설계의 이유** — 인라인 주석(`# NOTE:`, `# WHY:`, `# HACK:`), 독스트링(docstring), 문서에 담긴 설계 근거를 별도 노드로 추출하고, 해당 내용이 설명하는 코드에 연결합니다.
 - **추천 질문** — 그래프를 활용하면 특히 잘 답할 수 있는 질문 4~5개를 제안합니다.
 - **신뢰도 태그** — 추론된 모든 관계에 `EXTRACTED`, `INFERRED`, `AMBIGUOUS` 중 하나를 표시합니다. 확인된 사실과 추정을 언제나 구분할 수 있습니다.
 
 ---
 
-
 ## 지원하는 파일
 
 | 유형 | 확장자 |
 |------|-----------|
 | 코드(tree-sitter 문법 37종) | `.py .ts .mts .cts .js .jsx .tsx .mjs .go .rs .java .c .cpp .cc .cxx .h .hpp .cu .cuh .metal .rb .cs .kt .kts .scala .php .swift .lua .luau .toc .zig .ps1 .psm1 .psd1 .ex .exs .m .mm .ml .mli .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml` (`.dm`/`.dme`는 `uv tool install graphifyy[dm]`, `.ml`/`.mli`는 `uv tool install graphifyy[ocaml]` 필요. `.mts`/`.cts`는 TypeScript 문법을, `.cc`/`.cxx`, CUDA의 `.cu`/`.cuh`, Metal의 `.metal`은 C++ 문법을 재사용) |
-| Salesforce Apex | `.cls .trigger` (정규식 기반. 클래스, 인터페이스, 열거형, 메서드, 트리거, SOQL/DML 관계 추출) |
+| Salesforce Apex | `.cls .trigger` (정규식 기반. 클래스, 인터페이스, 열거형, 메서드, 트리거 및 SOQL/DML 연결 관계 추출) |
 | Terraform / HCL | `.tf .tfvars .hcl` (`uv tool install graphifyy[terraform]` 필요) |
 | OCaml | `.ml .mli` (`uv tool install graphifyy[ocaml]` 필요) |
 | Common Lisp | `.lisp .cl .lsp .asd` (`uv tool install graphifyy[commonlisp]` 필요) |
@@ -380,7 +379,7 @@ graphify extract ./docs --google-workspace
 /graphify ./docs --update          # 변경된 파일만 다시 추출
 /graphify . --cluster-only         # 재추출 없이 클러스터링만 다시 실행
 /graphify . --cluster-only --resolution 1.5      # 커뮤니티를 더 세밀하게 분할
-/graphify . --cluster-only --exclude-hubs 99     # 핵심 허브 순위에서 연결이 지나치게 많은 유틸리티 허브를 억제
+/graphify . --cluster-only --exclude-hubs 99     # 핵심 허브 순위에서 연결이 지나치게 많은 유틸리티 노드의 비중을 줄임
 /graphify . --no-viz               # HTML 없이 보고서와 JSON만 생성
 /graphify . --wiki                 # 그래프에서 Markdown 위키 생성
 graphify export callflow-html      # Mermaid 아키텍처·호출 흐름 HTML 생성 (훅 설치 시 Git 커밋마다 자동 재생성)
@@ -395,7 +394,7 @@ graphify export callflow-html      # Mermaid 아키텍처·호출 흐름 HTML 
 graphify hook install              # 커밋·브랜치 체크아웃 시 자동 재생성 (git pull 후에는 graphify update . 실행 — 아래 권장 작업 흐름 참고)
 graphify merge-graphs a.json b.json              # 두 그래프 병합
 
-graphify prs                       # PR 대시보드: CI 상태, 리뷰 상태, worktree 연결 정보
+graphify prs                       # PR 대시보드: CI 상태, 리뷰 상태, 워크트리(worktree) 연결 정보
 graphify prs 42                    # 그래프에 미치는 영향을 포함해 PR #42 상세 분석
 graphify prs --triage              # AI가 리뷰 대기 목록의 우선순위 지정 (설정된 백엔드 사용)
 graphify prs --conflicts           # 같은 그래프 커뮤니티를 수정하는 PR 확인 — 병합 순서에 따른 위험
@@ -409,7 +408,7 @@ graphify prs --conflicts           # 같은 그래프 커뮤니티를 수정하
 
 프로젝트 루트에 `.graphifyignore`를 만드세요. `!`를 사용하는 제외 규칙의 반전까지 포함해 `.gitignore`와 같은 문법을 사용합니다.
 
-**`.gitignore`는 자동으로 적용됩니다.** graphify는 각 디렉터리의 `.gitignore`를 읽습니다. `.graphifyignore`도 있으면 두 파일의 규칙을 **합쳐서** 적용합니다. `.graphifyignore` 패턴을 마지막에 평가하므로 규칙이 충돌하면 이쪽이 우선합니다(`!` 반전 규칙 포함). `.graphifyignore`를 추가하면 제외 대상이 늘어날 뿐, `.gitignore`가 이미 제외한 파일을 다시 포함하지는 않습니다. 하위 디렉터리 범위는 Git과 같은 방식으로 처리합니다. 각 ignore 파일은 자신이 속한 디렉터리와 그 하위에만 영향을 줍니다.
+**`.gitignore`는 자동으로 적용됩니다.** graphify는 각 디렉터리의 `.gitignore`를 읽습니다. `.graphifyignore`도 있으면 두 파일의 규칙을 **합쳐서** 적용합니다. `.graphifyignore` 패턴을 마지막에 평가하므로 규칙이 충돌하면 이쪽이 우선합니다(`!` 반전 규칙 포함). 다만 Git과 마찬가지로, 상위 디렉터리가 제외되어 있으면 `!` 규칙만으로 그 안의 파일을 다시 포함할 수 없습니다. 해당 디렉터리도 먼저 제외 대상에서 해제해야 합니다. 하위 디렉터리 범위는 Git과 같은 방식으로 처리합니다. 각 ignore 파일은 자신이 속한 디렉터리와 그 하위에만 영향을 줍니다.
 
 Git에서 제외한 생성 코드나 트랜스파일된 코드도 그래프에 포함하려면 `graphify extract`에 `--no-gitignore`를 전달하세요. 이 옵션은 `.gitignore`와 `.git/info/exclude`를 비활성화합니다. `.graphifyignore`는 계속 적용됩니다.
 
@@ -505,7 +504,7 @@ MCP 서버는 도우미가 구조화된 방식으로 접근할 수 있는 다음
 | `--stateless` | 꺼짐 | 세션별 상태를 유지하지 않음(로드 밸런싱·CI 배포용) |
 | `--session-timeout` | `3600` | 상태를 유지하는 세션이 N초 동안 유휴 상태이면 정리(`0`이면 비활성화) |
 
-기본 바인딩 주소 `127.0.0.1`은 루프백 연결만 허용합니다. 공유 호스트에서 외부에 공개할 때는 `--host 0.0.0.0`**과** `--api-key`를 함께 설정하세요. 컨테이너에서 실행하는 예시는 다음과 같습니다.
+기본 바인딩 주소 `127.0.0.1`은 루프백 연결만 허용합니다. 공유 호스트에서 외부에 공개할 때는 **`--host 0.0.0.0`과 `--api-key`를 함께** 설정하세요. 컨테이너에서 실행하는 예시는 다음과 같습니다.
 
 ```bash
 docker build -t graphify .
@@ -548,7 +547,7 @@ docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
 | `GRAPHIFY_MAX_OUTPUT_TOKENS` | 정보 밀도가 높은 자료 모음의 출력 한도 상향 | 선택 사항 — 큰 파일의 경우 예: `32768` |
 | `GRAPHIFY_API_TIMEOUT` | HTTP, claude-cli, Anthropic SDK, Bedrock 백엔드의 호출별 제한 시간(초, 기본값: 600) | 선택 사항 — `--api-timeout` 플래그로도 설정 가능 |
 | `GRAPHIFY_MAX_RETRIES` | 요청 한도 초과(429) 시 포기하기 전 재시도 횟수(기본값: 6, `Retry-After` 준수) | 선택 사항 — 조직별 한도가 엄격한 경우(예: kimi) 늘릴 수 있음. `0`이면 비활성화 |
-| `GRAPHIFY_MAX_RETRY_DEPTH` | 응답이 잘린 청크를 이분할해 재추출할 최대 깊이(기본값: 3, 청크 하나당 하위 호출이 최대 8배까지 증가) | 선택 사항 — 최악의 경우 비용을 제한하려면 낮게 설정. `0`이면 모든 재시도(이분할 및 내용 없는 응답의 재시도)를 비활성화하여 청크당 정확히 한 번만 호출 |
+| `GRAPHIFY_MAX_RETRY_DEPTH` | 응답이 잘린 청크를 이분할해 재추출할 최대 깊이(기본값: 3, 청크 하나가 최대 8개의 하위 청크로 나뉘어 각각 재호출됨) | 선택 사항 — 최악의 경우 비용을 제한하려면 낮게 설정. `0`이면 모든 재시도(이분할 및 내용 없는 응답의 재시도)를 비활성화하여 청크당 정확히 한 번만 호출 |
 | `GRAPHIFY_FORCE` | 노드 수가 줄어도 그래프 강제 재생성 | 선택 사항 — `--force` 플래그로도 설정 가능 |
 | `GRAPHIFY_GOOGLE_WORKSPACE` | Google Workspace 내보내기 자동 활성화 | 선택 사항 — `1`로 설정 |
 | `GRAPHIFY_TRIAGE_BACKEND` | `graphify prs --triage`에 사용할 백엔드 | 선택 사항 — 사용 가능한 키에서 자동 감지 |
@@ -570,11 +569,10 @@ docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
 - **문서, PDF, 이미지** — 의미 추출을 위해 AI 도우미로 전송합니다(`/graphify` 스킬을 통해 IDE 세션에서 사용 중인 모델을 이용). 헤드리스 방식의 `graphify extract`에는 `GEMINI_API_KEY` / `GOOGLE_API_KEY`(Gemini), `MOONSHOT_API_KEY`(Kimi), `ANTHROPIC_API_KEY`(Claude), `OPENAI_API_KEY`(OpenAI), `DEEPSEEK_API_KEY`(DeepSeek), 실행 중인 Ollama 인스턴스(`OLLAMA_BASE_URL`), 표준 공급자 체인의 AWS 자격 증명(Bedrock — API 키 없이 IAM 사용), 또는 `claude` CLI 실행 파일(Claude Code — API 키 없이 Claude 구독 사용) 중 하나가 필요합니다. `--dedup-llm` 플래그도 같은 키를 사용합니다.
 - **데이터 처리 위치** — `graphify extract`는 설정된 API 키를 기준으로 공급자를 자동 감지합니다(우선순위: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). 데이터 처리 위치에 관한 요구 사항이 있는 코드에는 `--backend ollama`(완전한 로컬 처리)를 사용하거나 `--backend` 플래그로 백엔드를 명시하세요. Kimi(`MOONSHOT_API_KEY`)는 중국에 있는 Moonshot AI 서버로 요청을 보냅니다.
 - **텔레메트리 없음** — 사용 추적이나 분석 데이터를 수집하지 않습니다.
-- **질의 로그** — 모든 `graphify query`, `graphify path`, `graphify explain`, MCP `query_graph` 호출을 `~/.cache/graphify-queries.log`에 JSON Lines 형식으로 기록합니다(타임스탬프, 질문, 자료 모음, 반환된 노드, 소요 시간). 전체 부분 그래프 응답은 기본적으로 저장하지 **않습니다**. 기록을 끄려면 `GRAPHIFY_QUERY_LOG_DISABLE=1`을 설정하세요. 로깅 코드 경로를 비활성화하지 않고 출력을 버리려면 `GRAPHIFY_QUERY_LOG=/dev/null`을 사용하세요.
+- **질의 로그** — 기본적으로 꺼져 있으며, 명시적으로 활성화하지 않으면 기록하지 않습니다. `GRAPHIFY_QUERY_LOG_ENABLE=1`을 설정하면 `graphify query`, `graphify path`, `graphify explain`, MCP `query_graph` 호출을 `~/.cache/graphify-queries.log`에 JSON Lines 형식으로 기록합니다(타임스탬프, 질문, 자료 모음, 반환된 노드 수, 소요 시간). `GRAPHIFY_QUERY_LOG`에 경로를 지정하면 로깅을 활성화하고 해당 경로에 기록합니다. 전체 부분 그래프 응답은 기본적으로 저장하지 **않으며**, 로깅이 활성화된 상태에서 `GRAPHIFY_QUERY_LOG_RESPONSES=1`을 설정해야 함께 기록됩니다. `GRAPHIFY_QUERY_LOG_DISABLE=1`은 다른 활성화 설정보다 우선하며 로깅을 강제로 끕니다. 로깅 코드 경로를 비활성화하지 않고 출력을 버리려면 `GRAPHIFY_QUERY_LOG=/dev/null`을 사용하세요.
 
 ---
 
-
 ## 문제 해결
 
 **설치 후 `graphify: command not found`가 표시되는 경우**
@@ -848,7 +846,7 @@ graphify cluster-only ./my-project
 graphify cluster-only ./my-project --graph path/to/graph.json  # 그래프 위치 직접 지정
 graphify cluster-only ./my-project --max-concurrency 16 --batch-size 200  # 커뮤니티 이름을 병렬로 지정 (대형 그래프용)
 graphify cluster-only ./my-project --resolution 1.5            # 더 작고 많은 커뮤니티로 분할
-graphify cluster-only ./my-project --exclude-hubs 99           # 연결 차수가 99백분위인 노드를 분할에서 제외
+graphify cluster-only ./my-project --exclude-hubs 99           # 연결 차수의 99백분위수를 기준으로 허브 노드를 분할에서 제외
 graphify cluster-only ./my-project --no-label                  # 임시 이름 "Community N" 유지
 graphify cluster-only ./my-project --backend=gemini            # 커뮤니티 이름 지정에 사용할 백엔드
 graphify cluster-only ./my-project --backend=gemini --model gemini-2.5-pro  # 특정 모델 지정
@@ -860,12 +858,11 @@ graphify label ./my-project --backend=openai --model gpt-4o   # 특정 백엔드
 
 ---
 
-
 ## 더 알아보기
 
-- [작동 원리](https://github.com/Graphify-Labs/graphify/blob/v8/docs/how-it-works.md) — 추출 파이프라인, 커뮤니티 탐지, 신뢰도 평가, 벤치마크
-- [ARCHITECTURE.md](https://github.com/Graphify-Labs/graphify/blob/v8/ARCHITECTURE.md) — 모듈 구성과 언어 추가 방법
-- [선택적 연동](https://github.com/Graphify-Labs/graphify/blob/v8/docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
+- [작동 원리](../../docs/how-it-works.md) — 추출 파이프라인, 커뮤니티 탐지, 신뢰도 평가, 벤치마크
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — 모듈 구성과 언어 추가 방법
+- [선택적 연동](../../docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
 - [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo) — graphify의 바탕이 된 아이디어와 전체 아키텍처를 설명하는 책
 
 ---
@@ -898,7 +895,7 @@ git checkout v8                        # 현재 개발이 진행되는 브랜치
 uv sync --all-extras
 ```
 
-소스 수정 사항이 바로 반영되는 편집 가능 설치가 되었는지 확인하세요.
+소스 수정 사항이 바로 반영되는 개발용 설치(editable install)가 정상적으로 되었는지 확인하세요.
 
 ```bash
 uv run graphify --version
@@ -915,7 +912,7 @@ uv run pytest tests/ -q -k "python"    # 이름으로 필터링
 
 ### CI와 동일한 조건으로 검사하기
 
-기준이 되는 CI 명령어는 [`.github/workflows/`](https://github.com/Graphify-Labs/graphify/tree/v8/.github/workflows/)에 있습니다. 로컬에서 CI와 같은 방식으로 검증하려면 Python 3.10, 3.12, 3.13 또는 3.14를 사용해 다음을 실행하세요.
+기준이 되는 CI 명령어는 [`.github/workflows/`](../../.github/workflows/)에 있습니다. 로컬에서 CI와 같은 방식으로 검증하려면 Python 3.10, 3.12, 3.13 또는 3.14를 사용해 다음을 실행하세요.
 
 ```bash
 uv sync --all-extras --frozen
@@ -948,7 +945,7 @@ Ruff는 추가 로컬 검사(`uv run --frozen ruff check .`)에 유용하지만,
 
 **추출 버그** — 입력 파일, 캐시 항목(`graphify-out/cache/`), 누락되거나 잘못된 내용을 첨부해 이슈를 등록하세요.
 
-모듈별 역할과 언어 추가 방법은 [ARCHITECTURE.md](https://github.com/Graphify-Labs/graphify/blob/v8/ARCHITECTURE.md)를 참고하세요.
+모듈별 역할과 언어 추가 방법은 [ARCHITECTURE.md](../../ARCHITECTURE.md)를 참고하세요.
 
 </details>