Make wiki retrieval DB primary

Author: tae2089

README.md

@@ -69,7 +69,7 @@ ccg search "payment"    # finds functions with @intent/@domainRule about payment
 # Build docs and the default vectorless RAG index for agent-oriented exploration
 ccg docs --out docs
 
-# Serve the browser Wiki UI from built assets; builds the graph and uses DB-backed fallback
+# Serve the browser Wiki UI from built assets; builds the graph for DB-backed APIs
 make wiki-run
 
 # Graph statistics
@@ -89,12 +89,16 @@ ccg eval --suite parser
 ccg eval --suite parser --update
 ```
 
-`ccg docs` writes generated Markdown plus `.ccg/wiki-index.json` for the browser
-Wiki. By default it also refreshes community structure and writes
-`.ccg/doc-index.json` for vectorless RAG retrieval. Use `--rag=false` when you
-only want Markdown and the Wiki index, or `--rag-refresh=false` when you want to
-rebuild the RAG index from existing community rows without recalculating
-communities.
+`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
+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
@@ -119,8 +123,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 PageIndex-style `retrieve_docs` over generated indexes,
-  with DB-backed fallback when index files have not been generated
+- Keyword search and DB-primary `retrieve_docs`, with generated indexes kept as
+  compatibility fallbacks
 - 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
@@ -135,7 +139,8 @@ make wiki-run
 ```
 
 Use `make wiki-run-indexed` when you also want generated Markdown,
-`wiki-index.json`, and `doc-index.json` before starting the server.
+`wiki-index.json` snapshot, and the compatibility `doc-index.json` before
+starting the server.
 
 For self-hosted deployments, run `ccg-server --wiki-dir <dist-dir>` and protect
 `/wiki/api/*` with the same bearer token policy used for `/mcp`. See

guide/README.md

@@ -7,10 +7,12 @@ docs and the RAG index. Use graph/search tools after the relevant module,
 document, or symbol candidate is identified.
 
 The browser Wiki is served by `ccg-server` when `--wiki-dir` points at built
-React assets. It uses `wiki-index.json` for presentation, `doc-index.json` for
-retrieval, and `/wiki/api/graph` for the visual graph tab. Use it when a human
-developer needs to browse docs, inspect annotation-rich symbol cards, collect
-Context Tray Markdown, or visually explore graph edges.
+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.
 
 | Document | Description |
 |----------|-------------|

guide/cli-reference.md

@@ -46,8 +46,8 @@ 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, `wiki-index.json`, and the default RAG index (prunes stale generator-managed docs by default) |
-| `ccg docs --rag=false` | Generate Markdown and `wiki-index.json` only, without rebuilding communities or the RAG index |
+| `ccg docs [--out dir]` | Generate Markdown documentation, the `wiki-index.json` compatibility snapshot, and the default RAG index (prunes stale generator-managed docs by default) |
+| `ccg docs --rag=false` | Generate Markdown and the `wiki-index.json` snapshot 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` and `wiki-index.json` output directory (default `.ccg` or `rag.index_dir`) |
 | `ccg docs --prune=false` | Regenerate docs without deleting older generator-managed files |
@@ -84,9 +84,11 @@ ccg build .
 ccg docs --out docs
 ```
 
-`ccg docs` always writes `.ccg/wiki-index.json` for the ccg-server Wiki UI.
-That Wiki index is a presentation tree built directly from folders, packages,
-files, and symbols; it does not depend on community postprocessing. Symbol
+`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
 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
@@ -96,7 +98,8 @@ 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` RAG index for MCP/PageIndex retrieval.
+writes the default `.ccg/doc-index.json` compatibility snapshot for MCP
+retrieval fallback.
 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.

guide/development.md

@@ -14,7 +14,7 @@ make build        # build stripped ccg and ccg-server binaries (same as make rel
 make release      # stripped build with embedded version/commit/date
 make build-debug  # unstripped ccg and ccg-server binaries with embedded version/commit/date
 make wiki-db      # migrate the local Wiki DB and build the graph from WIKI_REPO
-make wiki-run     # build Wiki UI, build graph, run ccg-server with DB-backed Wiki fallback
+make wiki-run     # build Wiki UI, build graph, run ccg-server with DB-backed Wiki APIs
 make wiki-run-indexed # build Wiki UI, build graph, generate docs/indexes, then run ccg-server
 ```
 

guide/docker.md

@@ -106,12 +106,12 @@ ccg-server \
 The static `/wiki` app shell is served without request headers so browsers can
 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 docs --out docs` for each served namespace before opening the Wiki so
-`.ccg/wiki-index.json` exists. The Wiki API reads `wiki-index.json`; MCP
-retrieval continues to use the separate community-based `doc-index.json`. 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.
+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
+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.
 
 ## Choosing SQLite vs PostgreSQL
 

guide/ko/README.md

@@ -9,9 +9,11 @@ CCG는 GPT, Claude, Codex 같은 LLM 기반 코딩 에이전트가 개발 중 
 LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 생성 문서와 RAG 인덱스에서 시작하십시오. 관련 모듈, 문서 또는 심볼 후보를 찾은 뒤 graph/search 도구로 정확한 위치와 관계를 확인하는 흐름을 권장합니다.
 
 브라우저 Wiki는 `ccg-server`에서 `--wiki-dir`가 빌드된 React asset을
-가리킬 때 제공됩니다. 표시용 `wiki-index.json`, retrieval용 `doc-index.json`,
-시각적 Graph 탭용 `/wiki/api/graph`를 함께 사용합니다. 개발자가 문서를
-탐색하고 annotation-rich symbol card를 확인하거나, Context Tray Markdown을
+가리킬 때 제공됩니다. 표시에는 graph database를 우선 사용하고,
+`wiki-index.json`과 `doc-index.json`은 호환 snapshot으로 사용합니다.
+runtime retrieve 모드는 설정된 DB를 우선 사용하며, 시각적 Graph 탭은
+`/wiki/api/graph`를 사용합니다.
+개발자가 문서를 탐색하고 annotation-rich symbol card를 확인하거나, Context Tray Markdown을
 모아 다른 LLM 도구에 붙여 넣고, graph edge를 시각적으로 살펴볼 때 사용합니다.
 
 | 문서 | 설명 |

guide/ko/cli-reference.md

@@ -48,8 +48,8 @@ ccg update ./backend --namespace backend
 | `ccg status --recent <n>` | 확인할 최근 사후 처리 실패 개수 (기본값 `5`) |
 | `ccg search <query>` | 전체 텍스트 검색 |
 | `ccg search --path <prefix> <query>` | 경로 접두사로 검색 범위 제한 |
-| `ccg docs [--out dir]` | 마크다운 문서, `wiki-index.json`, 기본 RAG 인덱스 생성 (기본적으로 그래프에 없는 generator-managed 문서를 prune) |
-| `ccg docs --rag=false` | community/RAG 인덱스 재생성 없이 Markdown과 `wiki-index.json`만 생성 |
+| `ccg docs [--out dir]` | 마크다운 문서, `wiki-index.json` 호환 snapshot, 기본 RAG 인덱스 생성 (기본적으로 그래프에 없는 generator-managed 문서를 prune) |
+| `ccg docs --rag=false` | community/RAG 인덱스 재생성 없이 Markdown과 `wiki-index.json` snapshot만 생성 |
 | `ccg docs --rag-refresh=false` | community를 재계산하지 않고 기존 community row로 RAG 인덱스 재생성 |
 | `ccg docs --rag-index-dir <dir>` | `doc-index.json` 및 `wiki-index.json` 출력 디렉터리 지정 (기본 `.ccg` 또는 `rag.index_dir`) |
 | `ccg docs --prune=false` | 기존 generator-managed 문서를 삭제하지 않고 문서만 다시 생성 |
@@ -86,8 +86,10 @@ ccg build .
 ccg docs --out docs
 ```
 
-`ccg docs`는 ccg-server Wiki UI를 위한 `.ccg/wiki-index.json`을 항상
-기록합니다. 이 Wiki index는 folder, package, file, symbol에서 직접 만든
+`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에서 직접 만든
 표시용 tree이며 community postprocess에 의존하지 않습니다. Symbol node는
 구조화된 annotation detail을 함께 담기 때문에 symbol 자체에 생성 Markdown
 파일이 없어도 브라우저 Wiki에서 params, returns, rules, side effects 등
@@ -98,7 +100,7 @@ tag를 보여줄 수 있습니다. Wiki와 RAG index는 숨겨진 annotation sea
 데이터베이스에서 해당 네임스페이스의 graph node와 edge를 직접 읽고, 클릭한
 file/symbol node를 같은 문서 viewer로 엽니다.
 `--rag=false`가 설정되지 않은 경우에는 community 구조도 갱신하고
-MCP/PageIndex retrieval용 기본 `.ccg/doc-index.json` RAG 인덱스를 함께
+MCP retrieval fallback용 기본 `.ccg/doc-index.json` 호환 snapshot을 함께
 기록합니다. 기존 community row를 의도적으로 재사용하려면
 `--rag-refresh=false`를 사용하십시오. 독립 `ccg rag-index` 명령은 생성 문서와
 이미 계산된 community를 사용한 수동 재생성 용도로 남아 있습니다.

guide/ko/development.md

@@ -16,7 +16,7 @@ make build        # stripped ccg 및 ccg-server 바이너리 빌드 (make releas
 make release      # 버전/커밋/날짜 정보가 포함된 stripped 빌드
 make build-debug  # 버전/커밋/날짜 정보가 포함된 unstripped ccg 및 ccg-server 바이너리 빌드
 make wiki-db      # 로컬 Wiki DB 마이그레이션 및 WIKI_REPO 그래프 빌드
-make wiki-run     # Wiki UI 빌드, 그래프 빌드, DB-backed fallback으로 ccg-server 실행
+make wiki-run     # Wiki UI 빌드, 그래프 빌드, DB-backed Wiki API로 ccg-server 실행
 make wiki-run-indexed # Wiki UI 빌드, 그래프/문서/index 생성 후 ccg-server 실행
 ```
 

guide/ko/docker.md

@@ -99,11 +99,12 @@ ccg-server \
 정적 `/wiki` app shell은 브라우저에서 직접 열 수 있도록 요청 헤더 없이
 서빙됩니다. `/wiki/api/*`는 `/mcp`와 같은 Bearer 토큰을 사용하며, UI는 API가
 `401`을 반환하면 토큰 입력을 요청합니다.
-Wiki를 열기 전에 각 네임스페이스에서 `ccg docs --out docs`를 실행해
-`.ccg/wiki-index.json`을 생성하십시오. Wiki API는 `wiki-index.json`을 읽고,
-MCP retrieval은 별도의 community 기반 `doc-index.json`을 계속 사용합니다.
-Wiki Graph 탭은 `/wiki/api/graph`를 통해 설정된 데이터베이스의 graph node와
-edge를 직접 읽으므로 최신 `ccg build` 또는 webhook sync 상태를 반영합니다.
+Wiki를 열기 전에 각 네임스페이스에서 `ccg build`를 실행해 DB-backed tree
+navigation, search, retrieve가 읽을 graph row를 준비하십시오. `ccg docs
+--out docs`는 생성 Markdown, `doc-index.json` retrieval fallback,
+`wiki-index.json` 호환 snapshot이 필요할 때 계속 유용합니다. Wiki Graph 탭은
+`/wiki/api/graph`를 통해 설정된 데이터베이스의 graph node와 edge를 직접
+읽으므로 최신 `ccg build` 또는 webhook sync 상태를 반영합니다.
 
 ## SQLite vs PostgreSQL 선택 (Choosing SQLite vs PostgreSQL)
 

guide/ko/mcp-tools.md

@@ -106,12 +106,13 @@ CCG는 아직 Prometheus `/metrics` 엔드포인트를 제공하지 않습니다
 | `get_rag_tree` | node ID 기반 RAG 문서 트리 탐색 (네임스페이스 지원) |
 | `get_doc_content` | 문서 파일 내용 확인 (네임스페이스 지원) |
 | `search_docs` | 키워드로 RAG 문서 트리 검색 (네임스페이스 지원) |
-| `retrieve_docs` | RAG tree에서 관련 문서를 찾아 evidence와 제한된 Markdown 본문 반환 |
+| `retrieve_docs` | DB-backed graph evidence에서 관련 문서를 찾고, doc-index fallback, evidence, 제한된 Markdown 본문 반환 |
 
 자연어 기반 코드 이해에는 문서/RAG 도구를 먼저 사용하십시오.
-`retrieve_docs`는 file subtree를 점수화하므로 여러 키워드가 관련 심볼에
-나뉘어 있어도 같은 문서를 후보로 찾고, tree evidence와 제한된 Markdown
-본문을 반환합니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
+`retrieve_docs`는 file-level graph evidence를 점수화하므로 여러 키워드가
+관련 심볼에 나뉘어 있어도 같은 문서를 후보로 찾고, 제한된 Markdown 본문과
+evidence를 반환합니다. DB retrieval을 사용할 수 없으면 생성된
+`doc-index.json` snapshot으로 fallback합니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
 인자 없이 호출해 tree를 받고, 반환된 `node_id`를 넘겨 `community`,
 `package`, `file`, `symbol` 노드로 내려갑니다. 기존 `community_id`
 파라미터는 `node_id`의 호환 alias로 유지됩니다. `get_doc_content`는
@@ -124,23 +125,22 @@ CCG는 아직 Prometheus `/metrics` 엔드포인트를 제공하지 않습니다
 
 `retrieve_docs`의 score는 같은 query 결과 안에서 순위를 정하기 위한
 신호이며, 절대적인 품질 점수가 아닙니다. 서로 다른 query의 score를 직접
-비교하는 용도로는 사용하지 마십시오. 현재 점수는 정확한 심볼/파일 이름을
-우선합니다. label이 term과 정확히 같으면 8점, label에 포함되면 5점, node
-ID에 포함되면 3점, summary에 포함되면 2점, 숨겨진 annotation search text에
-포함되면 1점이 더해지고, 매칭된 고유 query term마다 10점이 추가됩니다.
-숨겨진 search text는 annotation summary, context, tag kind, tag name/type,
-tag value로 구성되며 matching을 위해 index에 저장되지만 MCP payload를 작게
-유지하기 위해 tree/search 응답에서는 제외됩니다. 점수는 file node와 그 하위
-symbol 노드들에서 누적되며, `matched_terms`와 `matches`가 어떤 term과 tree
-node가 근거로 사용됐는지 보여줍니다.
+비교하는 용도로는 사용하지 마십시오. 현재 DB-backed 점수는 정확한 심볼/파일
+이름과 high-signal annotation bucket을 우선합니다. exact label, label
+contains, `qualified_name`, `@intent`, `@index`, `@domainRule`, `@requires`,
+`@ensures`, `@sideEffect`, `@mutates`, `@see`, generic annotation text가
+가중치에 반영되고, 매칭된 고유 query term마다 ranking bonus가 추가됩니다.
+`matched_fields`, `matched_terms`, `matches`가 어떤 field, term, graph node가
+근거로 사용됐는지 보여줍니다.
 
 RAG 인덱스 품질은 생성 문서와 비어 있지 않은 community postprocess 결과에
 의존합니다. CLI `ccg docs` 명령은 community를 갱신하고 기본
-`doc-index.json` RAG 인덱스를 자동으로 기록합니다. 또한 브라우저 Wiki를 위한
-별도 `wiki-index.json`도 기록하며, MCP retrieval 도구는 이 표시용 인덱스에
-의존하지 않습니다. MCP만 사용하는 워크플로우에서 community가 없을 수 있으면
-`build_rag_index` 전에 `run_postprocess`를 `communities=true`, `flows=false`,
-`fts=false`로 호출하십시오.
+`doc-index.json` 호환 snapshot을 자동으로 기록합니다. 또한 브라우저 Wiki를
+위한 별도 `wiki-index.json` 호환 snapshot도 기록하며, MCP retrieval 도구는
+DB를 우선 사용하고 snapshot은 fallback surface로만 사용합니다. MCP만 사용하는
+워크플로우에서 community가 없을 수 있으면 `build_rag_index` 전에
+`run_postprocess`를 `communities=true`, `flows=false`, `fts=false`로
+호출하십시오.
 
 ### 네임스페이스 파일 관리 (Namespace File Management)