feat: add RAG document retrieval

Author: tae2089

AGENTS.md

@@ -4,7 +4,7 @@
 
 ## MCP 서버
 
-`.mcp.json`에 등록된 ccg MCP 서버가 33개 도구를 제공합니다:
+`.mcp.json`에 등록된 ccg MCP 서버가 35개 도구를 제공합니다:
 
 - `parse_project`, `build_or_update_graph`, `run_postprocess`
 - `get_postprocess_policy`, `reset_postprocess_policy`
@@ -14,7 +14,7 @@
 - `detect_changes`, `get_affected_flows`, `list_flows`
 - `list_communities`, `get_community`, `get_architecture_overview`
 - `get_annotation`
-- `build_rag_index`, `get_rag_tree`, `get_doc_content`, `search_docs`
+- `build_rag_index`, `get_rag_tree`, `get_doc_content`, `search_docs`, `retrieve_docs`
 - `upload_file`, `upload_files`, `list_namespaces`, `list_files`, `delete_file`, `delete_namespace`
 - `list_workspaces`, `delete_workspace` (deprecated aliases)
 
@@ -38,8 +38,9 @@ Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cance
 주요 커맨드:
 
 - `ccg build [dir]` — 코드 그래프 빌드 (`--exclude`, `--no-recursive` 지원)
+- `ccg docs [--out dir]` — 마크다운 문서 및 기본 RAG 인덱스 생성
+- `ccg rag-index [--out dir]` — 이미 계산된 커뮤니티와 생성 문서 기반 RAG 인덱스 생성
 - `ccg search <query>` — 전문 검색 (어노테이션 포함)
-- `ccg docs [--out dir]` — 마크다운 문서 생성
 - `ccg lint [--strict]` — 문서 품질 체크
 - `ccg annotate [file|dir]` — AI 어노테이션 생성
 
@@ -49,17 +50,18 @@ Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cance
 
 코드 위치, 관련 구현, 호출 관계, 영향 범위, 아키텍처 맥락을 찾을 때는 먼저 ccg MCP 도구와 CLI Skills를 활용합니다.
 
-- 의미 기반 검색과 관련 코드 탐색은 ccg MCP `search`, `query_graph`, `get_node`, `get_minimal_context` 또는 `/ccg` skill을 우선 사용합니다.
+- 자연어 기반 코드 이해, 모듈 탐색, 아키텍처 맥락 수집은 `/ccg-docs` skill과 `retrieve_docs`, `get_rag_tree`, `get_doc_content`를 우선 사용합니다.
+- 정확한 심볼 위치, 호출 관계, 그래프 메타데이터 확인은 ccg MCP `query_graph`, `get_node`, `get_minimal_context` 또는 `/ccg` skill을 사용합니다.
+- 어노테이션/키워드 기반 후보 검색은 ccg MCP `search` 또는 `ccg search`를 보조로 사용합니다.
 - 영향 범위, 플로우, 데드코드, 구조 분석은 `/ccg-analyze` skill과 관련 MCP 도구(`get_impact_radius`, `trace_flow`, `find_dead_code`, `get_architecture_overview`)를 우선 사용합니다.
-- 문서/RAG 기반 맥락 검색은 `/ccg-docs` skill과 `search_docs`, `get_rag_tree`, `get_doc_content`를 우선 사용합니다.
 - 단순 문자열 확인, 파일 존재 확인, ccg 인덱스가 없거나 오래된 경우에는 `rg`를 보조로 사용하고, 필요한 경우 `ccg build .` 또는 `ccg update .`로 그래프를 갱신합니다.
 
 ## 문서
 
 상세 문서는 `guide/` 디렉토리를 참조하세요:
 
 - [CLI Reference](guide/cli-reference.md) — 전체 명령어, 플래그, 설정 파일
-- [MCP Tools](guide/mcp-tools.md) — 33개 MCP 도구, Skills, AI-Driven Annotation
+- [MCP Tools](guide/mcp-tools.md) — 35개 MCP 도구, Skills, AI-Driven Annotation
 - [Annotations](guide/annotations.md) — 어노테이션 태그, 예시, 검색
 - [Webhook](guide/webhook.md) — Webhook sync, 브랜치 필터링, HMAC, graceful shutdown
 - [Docker](guide/docker.md) — Docker 빌드, MCP 서버, PostgreSQL 배포

README.md

@@ -1,6 +1,6 @@
 # code-context-graph
 
-Local code analysis tool that parses codebases via Tree-sitter into a knowledge graph. Supports 12 languages, 33 MCP tools, and custom annotation search.
+Local code analysis tool that parses codebases via Tree-sitter into a knowledge graph. Supports 12 languages, 35 MCP tools, and custom annotation search.
 
 CCG is built primarily for GPT, Claude, Codex, and other LLM-based coding agents. It acts as local or self-hosted context infrastructure: agents can search code by intent, inspect call graphs, trace impact, retrieve docs, and keep responses bounded instead of reading entire repositories into context.
 
@@ -11,7 +11,8 @@ Inspired by [code-review-graph](https://github.com/tirth8205/code-review-graph)
 ## Features
 
 - **12 languages**: Go, Python, TypeScript, Java, Ruby, JavaScript, C, C++, Rust, Kotlin, PHP, Lua/Luau
-- **33 MCP tools**: parse, search, impact analysis, flow tracing, dead code detection, postprocess operations, namespace file management, and more
+- **35 MCP tools**: parse, search, impact analysis, flow tracing, dead code detection, postprocess operations, namespace file management, and more
+- **RAG-first code exploration**: generated docs + community structure let LLM agents answer natural-language questions before drilling into exact graph nodes
 - **Custom annotations**: `@intent`, `@domainRule`, `@sideEffect`, `@mutates`, `@index` — search code by business context ([details](guide/annotations.md))
 - **Webhook sync**: GitHub / Gitea push events → auto clone + build with per-repo branch filtering and `.ccg.yaml` `include_paths` auto-loading ([details](guide/webhook.md))
 - **Eval**: Golden corpus-based parser accuracy (P/R/F1) and search quality (P@K, MRR, nDCG) evaluation ([details](guide/eval.md))
@@ -60,6 +61,9 @@ ccg search "authentication"
 # Search by business context
 ccg search "payment"    # finds functions with @intent/@domainRule about payments
 
+# Build docs and the default vectorless RAG index for agent-oriented exploration
+ccg docs --out docs
+
 # Graph statistics
 ccg status
 
@@ -77,6 +81,18 @@ ccg eval --suite parser
 ccg eval --suite parser --update
 ```
 
+`ccg docs` refreshes community structure and writes `.ccg/doc-index.json` by
+default. Use `--rag=false` when you only want Markdown, or
+`--rag-refresh=false` when you want to rebuild the index from existing community
+rows without recalculating communities.
+
+For LLM agents, treat generated docs and the RAG index as the primary entrypoint
+for natural-language questions such as "how does webhook sync work?" or "where
+are the operational risks?". Use graph tools for exact symbols, call relations,
+impact radius, and pagination-safe result sets. Use `ccg search` as a focused
+annotation/keyword candidate search rather than the first tool for broad code
+understanding.
+
 If you use PostgreSQL, a custom SQLite DSN, an existing schema, or a controlled
 upgrade workflow, run `ccg migrate` explicitly before runtime commands. This
 also applies when upgrading CCG against an existing default `ccg.db` created by
@@ -192,7 +208,7 @@ For remote HTTP mode:
 }
 ```
 
-Claude Code automatically connects and gets access to 33 MCP tools. See [MCP Tools Reference](guide/mcp-tools.md) for the full list.
+Claude Code automatically connects and gets access to 35 MCP tools. See [MCP Tools Reference](guide/mcp-tools.md) for the full list.
 
 ## Architecture
 
@@ -223,7 +239,7 @@ See [Architecture Details](guide/architecture.md) for component breakdown and DB
 | [CLI Reference](guide/cli-reference.md) | All commands, flags, and config file (`.ccg.yaml`) |
 | [Eval](guide/eval.md) | Parser/search quality evaluation, golden corpus, and metrics |
 | [Lint](guide/lint.md) | Detailed `ccg lint` category reference, interpretation guide, and CI usage |
-| [MCP Tools](guide/mcp-tools.md) | 33 MCP tools, Skills, AI-Driven Annotation |
+| [MCP Tools](guide/mcp-tools.md) | 35 MCP tools, Skills, AI-Driven Annotation |
 | [Annotations](guide/annotations.md) | Annotation system — tags, examples, search |
 | [Webhook](guide/webhook.md) | Webhook sync, branch filtering, HMAC, graceful shutdown |
 | [Docker](guide/docker.md) | Docker build, MCP server, PostgreSQL deployment |

guide/README.md

@@ -2,13 +2,17 @@
 
 Documentation index for code-context-graph.
 
+For LLM-agent workflows, start natural-language code exploration from generated
+docs and the RAG index. Use graph/search tools after the relevant module,
+document, or symbol candidate is identified.
+
 | Document | Description |
 |----------|-------------|
 | [CLI Reference](cli-reference.md) | Full CLI commands, options, and configuration file (`.ccg.yaml`) |
 | [Eval](eval.md) | Parser/search quality evaluation, golden corpus, and metrics |
 | [Lint](lint.md) | Detailed `ccg lint` category reference, interpretation guide, and CI usage |
-| [MCP Tools](mcp-tools.md) | 33 MCP tools, Claude Code Skills, AI-driven annotation |
-| [Annotations](annotations.md) | Custom annotation system — tags, examples, search |
+| [MCP Tools](mcp-tools.md) | 35 MCP tools, Claude Code Skills, RAG-first routing, AI-driven annotation |
+| [Annotations](annotations.md) | Custom annotation system — tags, examples, search/RAG quality |
 | [Webhook](webhook.md) | GitHub / Gitea webhook sync, branch filtering, graceful shutdown |
 | [Docker](docker.md) | Docker image build, MCP server setup, PostgreSQL integration |
 | [Operations](operations.md) | Deployment profiles, database choice, readiness, webhook operations, troubleshooting |

guide/annotations.md

@@ -1,6 +1,14 @@
 # Custom Annotations
 
-Add structured metadata to your code so that AI and search can leverage business context. Annotations are indexed and searchable via `ccg search`.
+Add structured metadata to your code so that AI, generated docs, RAG, and
+focused search can leverage business context. Annotations are indexed for
+`ccg search` and are also rendered into generated Markdown that feeds the RAG
+index.
+
+For LLM-agent natural-language exploration, prefer the docs/RAG path first:
+`ccg docs`, then MCP `retrieve_docs`, `get_rag_tree`, and `get_doc_content`.
+Use `ccg search` when you need a focused list of
+annotation/keyword-matched symbol candidates.
 
 Annotation quality is validated by `ccg lint`. For category meanings such as `unannotated`, `incomplete`, `dead-ref`, `contradiction`, and `drifted`, see [Lint Guide](lint.md).
 

guide/cli-reference.md

@@ -46,11 +46,14 @@ ccg update ./backend --namespace backend
 | `ccg status --recent <n>` | Number of recent postprocess failures to inspect (default `5`) |
 | `ccg search <query>` | Full-text search |
 | `ccg search --path <prefix> <query>` | Scoped search by path prefix |
-| `ccg docs [--out dir]` | Generate Markdown documentation (prunes stale generator-managed docs by default) |
+| `ccg docs [--out dir]` | Generate Markdown documentation and the default RAG index (prunes stale generator-managed docs by default) |
+| `ccg docs --rag=false` | Generate Markdown only, without rebuilding communities or the RAG index |
+| `ccg docs --rag-refresh=false` | Rebuild the RAG index from existing community rows instead of refreshing communities |
+| `ccg docs --rag-index-dir <dir>` | Override the doc-index.json output directory (default `.ccg` or `rag.index_dir`) |
 | `ccg docs --prune=false` | Regenerate docs without deleting older generator-managed files |
 | `ccg docs --exclude <pat>` | Exclude files/paths from generated docs (repeatable) |
 | `ccg index [--out dir]` | Regenerate `index.md` only |
-| `ccg rag-index [--out dir]` | Build RAG index from generated docs and community structure |
+| `ccg rag-index [--out dir]` | Rebuild RAG index from generated docs and already-computed community structure |
 | `ccg languages` | List supported languages and extensions |
 | `ccg example [language]` | Show annotation writing example |
 | `ccg tags` | Show all annotation tag reference |
@@ -63,6 +66,37 @@ ccg update ./backend --namespace backend
 
 For the default local SQLite database (`ccg.db`, including `./ccg.db`, absolute paths ending in `ccg.db`, and `file:` DSNs for that file), runtime commands auto-run migrations only when the schema is missing. Existing SQLite schemas, PostgreSQL, custom SQLite DSNs, and controlled upgrades require an explicit `ccg migrate`. If you already have a default `ccg.db` from an older CCG version, treat it as an existing schema and run `ccg migrate` after upgrading.
 
+### Search and RAG Routing
+
+CCG has two search surfaces with different jobs:
+
+| Use case | Preferred entrypoint |
+|----------|----------------------|
+| Natural-language code understanding, module exploration, architecture questions | `ccg docs`, then MCP `retrieve_docs`, `get_rag_tree`, `get_doc_content` |
+| Exact symbol lookup, callers/callees, imports, bounded graph traversal | MCP `get_node`, `query_graph`, `get_minimal_context` |
+| Impact analysis, flow tracing, dead code, large functions | MCP analysis tools such as `get_impact_radius`, `trace_flow`, `find_dead_code`, `find_large_functions` |
+| Focused annotation/keyword candidate search | `ccg search` or MCP `search` |
+
+For coding agents, the recommended natural-language path is:
+
+```bash
+ccg build .
+ccg docs --out docs
+```
+
+`ccg docs` refreshes community structure and writes the default
+`.ccg/doc-index.json` RAG index unless `--rag=false` is set. Use
+`--rag-refresh=false` only when you intentionally want to reuse existing
+community rows. The standalone `ccg rag-index` command remains available for
+manual rebuilds from generated docs and already-computed communities.
+
+Then use MCP `retrieve_docs` to retrieve document candidates and bounded
+Markdown content with tree evidence. Use `get_rag_tree` to expand the
+module/community context and `get_doc_content` to read a specific generated doc
+directly. `search_docs` and `ccg search` remain useful for quick keyword or
+annotation matches, but they should not be treated as the primary answering
+surface for broad natural-language questions.
+
 ### Database Choice
 
 Use SQLite for local, single-user workflows where the database is a disposable

guide/ko/README.md

@@ -6,13 +6,15 @@ code-context-graph의 문서 인덱스입니다. 한국어 문서는 영어 가
 
 CCG는 GPT, Claude, Codex 같은 LLM 기반 코딩 에이전트가 개발 중 코드베이스 맥락을 정확하고 작게 가져오도록 만든 로컬/셀프호스트 context infrastructure입니다. 일반 SaaS 관리자용 제품이 아니라, CLI, MCP, 로그, 문서를 이해하는 개발자와 코딩 에이전트가 코드 검색, 영향 분석, 호출 그래프, 문서/RAG, bounded response를 활용하도록 설계되었습니다.
 
+LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 생성 문서와 RAG 인덱스에서 시작하십시오. 관련 모듈, 문서 또는 심볼 후보를 찾은 뒤 graph/search 도구로 정확한 위치와 관계를 확인하는 흐름을 권장합니다.
+
 | 문서 | 설명 |
 |------|------|
 | [CLI 레퍼런스](cli-reference.md) | 모든 CLI 명령어, 옵션 및 설정 파일(`.ccg.yaml`) 안내 |
 | [Eval](eval.md) | 파서/검색 품질 평가, golden corpus, 지표 설명 |
 | [Lint](lint.md) | `ccg lint` 카테고리 상세 레퍼런스, 결과 해석 및 CI 활용법 |
-| [MCP 도구](mcp-tools.md) | 33개의 MCP 도구, Claude Code Skill, AI 기반 어노테이션 |
-| [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색 방법 |
+| [MCP 도구](mcp-tools.md) | 35개의 MCP 도구, Claude Code Skill, RAG 우선 라우팅, AI 기반 어노테이션 |
+| [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색/RAG 품질 |
 | [웹훅(Webhook)](webhook.md) | GitHub / Gitea 웹훅 동기화, 브랜치 필터링, Graceful Shutdown |
 | [Docker](docker.md) | Docker 이미지 빌드, MCP 서버 설정, PostgreSQL 연동 |
 | [운영(Operations)](operations.md) | 배포 프로필, 데이터베이스 선택, 준비성 체크, 웹훅 운영 및 문제 해결 |

guide/ko/annotations.md

@@ -2,7 +2,9 @@
 
 [English](../annotations.md)
 
-코드에 구조화된 메타데이터를 추가하여 AI와 검색 엔진이 비즈니스 컨텍스트를 활용할 수 있도록 합니다. 어노테이션은 인덱싱되어 `ccg search`를 통해 검색할 수 있습니다.
+코드에 구조화된 메타데이터를 추가하여 AI, 생성 문서, RAG, 집중 검색이 비즈니스 컨텍스트를 활용할 수 있도록 합니다. 어노테이션은 `ccg search`를 위해 인덱싱되며, RAG 인덱스의 입력이 되는 생성 Markdown에도 반영됩니다.
+
+LLM 에이전트의 자연어 기반 코드 탐색에는 docs/RAG 경로를 먼저 사용하십시오. `ccg docs`를 실행한 뒤 MCP `retrieve_docs`, `get_rag_tree`, `get_doc_content`를 사용합니다. `ccg search`는 어노테이션/키워드에 매칭되는 심볼 후보 목록이 필요할 때 사용하십시오.
 
 어노테이션 품질은 `ccg lint`에 의해 검증됩니다. `unannotated`, `incomplete`, `dead-ref`, `contradiction`, `drifted`와 같은 카테고리의 의미는 [Lint 가이드](lint.md)를 참조하십시오.
 

guide/ko/architecture.md

@@ -11,7 +11,7 @@
                                         ↓
                                    FTS 검색
                                         ↓
-                               MCP 서버 (33개 도구)
+                               MCP 서버 (35개 도구)
                                      ↓         ↓
                                stdio       Streamable HTTP
                                  ↓              ↓
@@ -74,7 +74,7 @@ GORM ORM 기반 저장소입니다. SQLite 및 PostgreSQL과 호환됩니다.
 
 ### MCP 서버 (MCP Server) (`internal/mcp/`)
 
-MCP 프로토콜을 통해 33개의 도구를 노출합니다. stdio 및 Streamable HTTP 두 가지 전송 모드를 지원합니다.
+MCP 프로토콜을 통해 35개의 도구를 노출합니다. stdio 및 Streamable HTTP 두 가지 전송 모드를 지원합니다.
 
 ### 안정성 (Reliability)