Document evidence-driven retrieve philosophy

Author: tae2089

README.md

@@ -12,8 +12,8 @@ Inspired by [code-review-graph](https://github.com/tirth8205/code-review-graph)
 
 - **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
-- **RAG-first code exploration**: generated docs + community structure let LLM agents answer natural-language questions before drilling into exact graph nodes
-- **Browser Wiki UI**: `ccg-server` can serve generated docs, tree search, PageIndex-style retrieval, Context Tray copying, and an Obsidian-style graph viewer
+- **Evidence-driven code exploration**: DB-backed retrieval returns small file-level candidates with matched fields, evidence nodes, and optional docs before agents drill into exact graph nodes
+- **Browser Wiki UI**: `ccg-server` can serve generated docs, tree search, DB-backed retrieval, Context Tray copying, and an Obsidian-style graph viewer
 - **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))
@@ -91,19 +91,21 @@ ccg eval --suite parser --update
 
 `ccg docs` writes generated Markdown plus `.ccg/wiki-index.json` as a browser
 Wiki compatibility snapshot. The Wiki prefers the graph database for tree
-navigation and search, then falls back to `wiki-index.json` when DB-backed
-navigation is unavailable. By default `ccg docs` also refreshes community structure and writes
-`.ccg/doc-index.json` as a compatibility retrieval snapshot. Runtime
-`retrieve_docs` paths prefer the graph database when it is configured and
-queryable, then fall back to `doc-index.json` when DB-backed retrieval is
-unavailable. Use `--rag=false` when you only want Markdown and the Wiki
+navigation and search, then uses `wiki-index.json` only when DB-backed
+navigation is unavailable. By default `ccg docs` also refreshes community
+structure and writes `.ccg/doc-index.json` as a compatibility snapshot for
+manual RAG-index workflows; runtime `retrieve_docs` uses DB-backed graph and
+annotation evidence. Use `--rag=false` when you only want Markdown and the Wiki
 snapshot, or `--rag-refresh=false` when you want to rebuild the RAG 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
+For LLM agents, use DB-backed `retrieve_docs` as the first stop for broad
+natural-language questions such as "how does webhook sync work?" or "where are
+the operational risks?". It is not a Top1 search engine; it is an
+evidence-driven narrowing layer that should return a small set of relevant
+files with `matched_fields`, `matched_terms`, and evidence nodes. Use
+`get_doc_content`, `get_node`, `query_graph`, `trace_flow`, and impact tools
+only after the route is narrowed. Use `ccg search` as a focused
 annotation/keyword candidate search rather than the first tool for broad code
 understanding.
 
@@ -123,8 +125,8 @@ size stays small.
 The Wiki is meant for developers and agents inspecting a generated codebase:
 
 - Tree navigation over folders, packages, files, and annotated symbols
-- Keyword search and DB-primary `retrieve_docs`, with generated indexes kept as
-  compatibility fallbacks
+- Keyword search and DB-backed `retrieve_docs` with matched evidence and small
+  file-level result sets
 - Rich symbol detail cards from CCG annotations even when a symbol has no
   generated Markdown file
 - Context Tray for collecting files and doc-less symbols into one Markdown

guide/README.md

@@ -2,24 +2,25 @@
 
 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.
+For LLM-agent workflows, start natural-language code exploration from
+DB-backed `retrieve_docs`. It is an evidence-driven narrowing layer, not a Top1
+search engine: use its small file-level candidates, matched fields, and evidence
+nodes to choose the shortest route into docs or graph tools.
 
 The browser Wiki is served by `ccg-server` when `--wiki-dir` points at built
 React assets. It prefers the graph database for presentation, uses
-`wiki-index.json` and `doc-index.json` as compatibility snapshots, and uses
-`/wiki/api/graph` for the visual graph tab. Runtime retrieve mode prefers the
-database when it is configured and queryable. Use it when a human developer
-needs to browse docs, inspect annotation-rich symbol cards, collect Context Tray
-Markdown, or visually explore graph edges.
+`wiki-index.json` as a compatibility tree snapshot, and uses `/wiki/api/graph`
+for the visual graph tab. Runtime retrieve mode uses DB-backed graph and
+annotation evidence. Use it when a human developer needs to browse docs,
+inspect annotation-rich symbol cards, collect Context Tray Markdown, or visually
+explore graph edges.
 
 | 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, agent skills, RAG-first routing, AI-driven annotation |
+| [MCP Tools](mcp-tools.md) | 33 MCP tools, agent skills, evidence-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, Wiki UI deployment, PostgreSQL integration |

guide/cli-reference.md

@@ -86,26 +86,26 @@ ccg docs --out docs
 
 `ccg docs` always writes `.ccg/wiki-index.json` as a ccg-server Wiki
 compatibility snapshot. The Wiki API prefers the graph database for tree
-navigation and search, then falls back to that snapshot when DB-backed
-navigation is unavailable. The snapshot is built directly from folders,
-packages, files, and symbols; it does not depend on community postprocessing. Symbol
+navigation and search, then uses that snapshot only when DB-backed navigation
+is unavailable. The snapshot is built directly from folders, packages, files,
+and symbols; it does not depend on community postprocessing. Symbol
 nodes carry structured annotation details so the browser Wiki can show params,
 returns, rules, side effects, and other tags even when the symbol itself has no
-generated Markdown file. Both Wiki and RAG indexes also store hidden annotation
-search text so `search_docs`, `retrieve_docs`, and Wiki search can match
-non-intent tags without returning that hidden text in normal tree payloads.
+generated Markdown file. Wiki indexes also store hidden annotation search text
+so Wiki search can match non-intent tags without returning that hidden text in
+normal tree payloads.
 The browser Wiki also provides a Graph tab backed by `/wiki/api/graph`; it reads
 the namespace's graph nodes and edges directly from the configured database and
 opens clicked file/symbol nodes through the same document viewer.
 Unless `--rag=false` is set, `ccg docs` also refreshes community structure and
-writes the default `.ccg/doc-index.json` compatibility snapshot for MCP
-retrieval fallback.
+writes the default `.ccg/doc-index.json` compatibility snapshot for manual RAG
+index workflows.
 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
+Then use MCP `retrieve_docs` to retrieve file-level candidates and bounded
+Markdown content with matched fields and graph 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

guide/docker.md

@@ -108,8 +108,8 @@ open it directly. `/wiki/api/*` uses the same bearer token as `/mcp`; the UI
 prompts for that token when the API returns `401`.
 Run `ccg build` for each served namespace before opening the Wiki so DB-backed
 tree navigation, search, and retrieve have graph rows to read. `ccg docs --out
-docs` remains useful for generated Markdown, the `doc-index.json` retrieval
-fallback, and the `wiki-index.json` compatibility snapshot. The Wiki Graph tab
+docs` remains useful for generated Markdown, `doc-index.json` compatibility
+RAG-index workflows, and the `wiki-index.json` compatibility snapshot. The Wiki Graph tab
 reads graph nodes and edges directly from the configured database via
 `/wiki/api/graph`, so it reflects the latest `ccg build` or webhook sync state.
 

guide/ko/README.md

@@ -6,12 +6,15 @@ code-context-graph의 문서 인덱스입니다. 한국어 문서는 영어 가
 
 CCG는 GPT, Claude, Codex 같은 LLM 기반 코딩 에이전트가 개발 중 코드베이스 맥락을 정확하고 작게 가져오도록 만든 로컬/셀프호스트 context infrastructure입니다. 일반 SaaS 관리자용 제품이 아니라, CLI, MCP, 로그, 문서를 이해하는 개발자와 코딩 에이전트가 코드 검색, 영향 분석, 호출 그래프, 문서/RAG, bounded response를 활용하도록 설계되었습니다.
 
-LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 생성 문서와 RAG 인덱스에서 시작하십시오. 관련 모듈, 문서 또는 심볼 후보를 찾은 뒤 graph/search 도구로 정확한 위치와 관계를 확인하는 흐름을 권장합니다.
+LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 DB-backed
+`retrieve_docs`에서 시작하십시오. Top1 정답을 강제하기보다 작은 파일 후보,
+matched fields, evidence node로 빠르게 경로를 좁힌 뒤 graph/search 도구로
+정확한 위치와 관계를 확인하는 흐름을 권장합니다.
 
 브라우저 Wiki는 `ccg-server`에서 `--wiki-dir`가 빌드된 React asset을
-가리킬 때 제공됩니다. 표시에는 graph database를 우선 사용하고,
-`wiki-index.json`과 `doc-index.json`은 호환 snapshot으로 사용합니다.
-runtime retrieve 모드는 설정된 DB를 우선 사용하며, 시각적 Graph 탭은
+가리킬 때 제공됩니다. 표시는 graph database를 우선 사용하고,
+`wiki-index.json`은 tree 호환 snapshot으로 사용합니다. runtime retrieve
+모드는 DB-backed graph/annotation evidence를 사용하며, 시각적 Graph 탭은
 `/wiki/api/graph`를 사용합니다.
 개발자가 문서를 탐색하고 annotation-rich symbol card를 확인하거나, Context Tray Markdown을
 모아 다른 LLM 도구에 붙여 넣고, graph edge를 시각적으로 살펴볼 때 사용합니다.
@@ -21,7 +24,7 @@ runtime retrieve 모드는 설정된 DB를 우선 사용하며, 시각적 Graph
 | [CLI 레퍼런스](cli-reference.md) | 모든 CLI 명령어, 옵션 및 설정 파일(`.ccg.yaml`) 안내 |
 | [Eval](eval.md) | 파서/검색 품질 평가, golden corpus, 지표 설명 |
 | [Lint](lint.md) | `ccg lint` 카테고리 상세 레퍼런스, 결과 해석 및 CI 활용법 |
-| [MCP 도구](mcp-tools.md) | 33개의 MCP 도구, 에이전트 스킬, RAG 우선 라우팅, AI 기반 어노테이션 |
+| [MCP 도구](mcp-tools.md) | 33개의 MCP 도구, 에이전트 스킬, evidence-first 라우팅, AI 기반 어노테이션 |
 | [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색/RAG 품질 |
 | [웹훅(Webhook)](webhook.md) | GitHub / Gitea 웹훅 동기화, 브랜치 필터링, Graceful Shutdown |
 | [Docker](docker.md) | Docker 이미지 빌드, MCP 서버 설정, Wiki UI 배포, PostgreSQL 연동 |

guide/ko/cli-reference.md

@@ -88,24 +88,24 @@ ccg docs --out docs
 
 `ccg docs`는 ccg-server Wiki UI 호환 snapshot인 `.ccg/wiki-index.json`을
 항상 기록합니다. Wiki API는 tree navigation과 search에 graph database를
-우선 사용하고, DB-backed navigation이 불가능할 때 이 snapshot으로
-fallback합니다. 이 snapshot은 folder, package, file, symbol에서 직접 만든
+우선 사용하고, DB-backed navigation이 불가능할 때만 이 snapshot을
+사용합니다. 이 snapshot은 folder, package, file, symbol에서 직접 만든
 표시용 tree이며 community postprocess에 의존하지 않습니다. Symbol node는
 구조화된 annotation detail을 함께 담기 때문에 symbol 자체에 생성 Markdown
 파일이 없어도 브라우저 Wiki에서 params, returns, rules, side effects 등
-tag를 보여줄 수 있습니다. Wiki와 RAG index는 숨겨진 annotation search text도
-저장하므로 `search_docs`, `retrieve_docs`, Wiki search가 non-intent tag까지
-매칭할 수 있지만, 일반 tree payload에는 이 숨겨진 text를 반환하지 않습니다.
+tag를 보여줄 수 있습니다. Wiki index는 숨겨진 annotation search text도
+저장하므로 Wiki search가 non-intent tag까지 매칭할 수 있지만, 일반 tree
+payload에는 이 숨겨진 text를 반환하지 않습니다.
 브라우저 Wiki는 `/wiki/api/graph` 기반 Graph 탭도 제공합니다. 이 탭은 설정된
 데이터베이스에서 해당 네임스페이스의 graph node와 edge를 직접 읽고, 클릭한
 file/symbol node를 같은 문서 viewer로 엽니다.
 `--rag=false`가 설정되지 않은 경우에는 community 구조도 갱신하고
-MCP retrieval fallback용 기본 `.ccg/doc-index.json` 호환 snapshot을 함께
+수동 RAG index workflow용 기본 `.ccg/doc-index.json` 호환 snapshot을 함께
 기록합니다. 기존 community row를 의도적으로 재사용하려면
 `--rag-refresh=false`를 사용하십시오. 독립 `ccg rag-index` 명령은 생성 문서와
 이미 계산된 community를 사용한 수동 재생성 용도로 남아 있습니다.
 
-그 다음 MCP `retrieve_docs`로 문서 후보와 제한된 Markdown 본문을 tree evidence와 함께 가져옵니다. `get_rag_tree`로 모듈/커뮤니티 맥락을 펼치고, `get_doc_content`로 특정 생성 문서를 직접 읽은 뒤 정확한 graph 도구로 내려갑니다. `search_docs`와 `ccg search`는 빠른 키워드 또는 어노테이션 매칭에는 유용하지만, 넓은 자연어 질문의 기본 응답 표면으로 보기는 어렵습니다.
+그 다음 MCP `retrieve_docs`로 파일 단위 후보와 제한된 Markdown 본문을 matched fields 및 graph evidence와 함께 가져옵니다. `get_rag_tree`로 모듈/커뮤니티 맥락을 펼치고, `get_doc_content`로 특정 생성 문서를 직접 읽은 뒤 정확한 graph 도구로 내려갑니다. `search_docs`와 `ccg search`는 빠른 키워드 또는 어노테이션 매칭에는 유용하지만, 넓은 자연어 질문의 기본 응답 표면으로 보기는 어렵습니다.
 
 ### 데이터베이스 선택 (Database Choice)
 

guide/ko/docker.md

@@ -101,7 +101,7 @@ ccg-server \
 `401`을 반환하면 토큰 입력을 요청합니다.
 Wiki를 열기 전에 각 네임스페이스에서 `ccg build`를 실행해 DB-backed tree
 navigation, search, retrieve가 읽을 graph row를 준비하십시오. `ccg docs
---out docs`는 생성 Markdown, `doc-index.json` retrieval fallback,
+--out docs`는 생성 Markdown, 수동 RAG-index workflow용 `doc-index.json`,
 `wiki-index.json` 호환 snapshot이 필요할 때 계속 유용합니다. Wiki Graph 탭은
 `/wiki/api/graph`를 통해 설정된 데이터베이스의 graph node와 edge를 직접
 읽으므로 최신 `ccg build` 또는 webhook sync 상태를 반영합니다.

guide/ko/mcp-tools.md

@@ -106,13 +106,13 @@ CCG는 아직 Prometheus `/metrics` 엔드포인트를 제공하지 않습니다
 | `get_rag_tree` | node ID 기반 RAG 문서 트리 탐색 (네임스페이스 지원) |
 | `get_doc_content` | 문서 파일 내용 확인 (네임스페이스 지원) |
 | `search_docs` | 키워드로 RAG 문서 트리 검색 (네임스페이스 지원) |
-| `retrieve_docs` | DB-backed graph evidence에서 관련 문서를 찾고, doc-index fallback, evidence, 제한된 Markdown 본문 반환 |
+| `retrieve_docs` | DB-backed graph evidence에서 관련 문서를 찾고, matched fields, evidence node, 제한된 Markdown 본문 반환 |
 
-자연어 기반 코드 이해에는 문서/RAG 도구를 먼저 사용하십시오.
-`retrieve_docs`는 file-level graph evidence를 점수화하므로 여러 키워드가
-관련 심볼에 나뉘어 있어도 같은 문서를 후보로 찾고, 제한된 Markdown 본문과
-evidence를 반환합니다. DB retrieval을 사용할 수 없으면 생성된
-`doc-index.json` snapshot으로 fallback합니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
+자연어 기반 코드 이해에는 `retrieve_docs`를 먼저 사용하십시오.
+`retrieve_docs`는 file-level graph/annotation evidence를 점수화하므로 여러
+키워드가 관련 심볼에 나뉘어 있어도 같은 문서를 후보로 찾고, 제한된 Markdown
+본문과 evidence를 반환합니다. Top1 정답을 보장하기보다 Top10 후보를 작게
+좁히는 evidence-driven retrieval layer입니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
 인자 없이 호출해 tree를 받고, 반환된 `node_id`를 넘겨 `community`,
 `package`, `file`, `symbol` 노드로 내려갑니다. 기존 `community_id`
 파라미터는 `node_id`의 호환 alias로 유지됩니다. `get_doc_content`는
@@ -135,10 +135,10 @@ contains, `qualified_name`, `@intent`, `@index`, `@domainRule`, `@requires`,
 
 RAG 인덱스 품질은 생성 문서와 비어 있지 않은 community postprocess 결과에
 의존합니다. CLI `ccg docs` 명령은 community를 갱신하고 기본
-`doc-index.json` 호환 snapshot을 자동으로 기록합니다. 또한 브라우저 Wiki를
-위한 별도 `wiki-index.json` 호환 snapshot도 기록하며, MCP retrieval 도구는
-DB를 우선 사용하고 snapshot은 fallback surface로만 사용합니다. MCP만 사용하는
-워크플로우에서 community가 없을 수 있으면 `build_rag_index` 전에
+`doc-index.json` 호환 snapshot을 수동 RAG-index workflow용으로 자동
+기록합니다. 또한 브라우저 Wiki를 위한 별도 `wiki-index.json` 호환 snapshot도
+기록합니다. Runtime `retrieve_docs`와 Wiki Retrieve는 DB가 설정된 경우 DB를
+사용합니다. MCP만 사용하는 워크플로우에서 community가 없을 수 있으면 `build_rag_index` 전에
 `run_postprocess`를 `communities=true`, `flows=false`, `fts=false`로
 호출하십시오.