docs: document cross-namespace refs, federated reads, and list_cross_refs

Update English and Korean guides (mcp-tools, annotations, architecture,
counts in README/development/runtime-layout), CLAUDE.md, and the
ccg-analyze / ccg-namespace skills for the new cross-namespace surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tae2089

CLAUDE.md

@@ -5,11 +5,11 @@
 Follow the global prompt rules first. This file adds project-specific skill routing for a project that uses the `agent-team` CLI (github.com/tae2089/agent-team) as its durable work ledger.
 
 ## MCP 서버
-`.mcp.json`에 등록된 ccg MCP 서버가 17개 도구를 제공합니다:
+`.mcp.json`에 등록된 ccg MCP 서버가 18개 도구를 제공합니다:
 
 - `parse_project`, `build_or_update_graph`, `run_postprocess`
 - `get_node`, `search`, `query_graph`, `list_graph_stats`, `list_namespaces`, `get_minimal_context`
-- `get_impact_radius`, `trace_flow`
+- `get_impact_radius`, `trace_flow`, `list_cross_refs`
 - `detect_changes`, `get_affected_flows`, `list_flows`
 - `get_annotation`
 - `get_doc_content`, `search_docs`
@@ -45,7 +45,7 @@ Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cance
 상세 문서는 `guide/` 디렉토리를 참조하세요:
 
 - [CLI Reference](guide/cli-reference.md) — 전체 명령어, 플래그, 설정 파일
-- [MCP Tools](guide/mcp-tools.md) — 17개 MCP 도구, Skills, AI-Driven Annotation
+- [MCP Tools](guide/mcp-tools.md) — 18개 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 배포

guide/README.md

@@ -20,7 +20,7 @@ explore graph edges.
 |----------|-------------|
 | [CLI Reference](cli-reference.md) | Full CLI commands, options, and configuration file (`.ccg.yaml`) |
 | [Lint](lint.md) | Detailed `ccg lint` category reference, interpretation guide, and CI usage |
-| [MCP Tools](mcp-tools.md) | 17 MCP tools, agent skills, evidence-first routing, AI-driven annotation |
+| [MCP Tools](mcp-tools.md) | 18 MCP tools, agent skills, evidence-first routing, AI-driven annotation |
 | [Annotations](annotations.md) | Custom annotation system — tags, examples, and search 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/annotations.md

@@ -62,6 +62,8 @@ Use `ccg://{namespace}/{path}#{symbol}` in `@see` when a behavior depends on cod
 
 The path and symbol are optional, so `ccg://auth-svc/internal/auth` can point at a package/path scope and `ccg://auth-svc/` can point at a whole namespace.
 
+Every `@see ccg://` tag is materialized into the `cross_refs` table after each build or update: the target is resolved against the referenced namespace's current nodes and the row is marked `resolved` or `dead`. When either side rebuilds, refs are re-resolved automatically, so a `dead` ref recovers as soon as the target symbol appears. Materialized refs power `list_cross_refs` (repository dependency map) and the `cross_namespace: true` mode of `get_impact_radius`/`trace_flow`. Namespace-scope refs (`ccg://auth-svc/`) resolve without a node target and never appear in traversal, only in listings.
+
 ## Retrieval Quality
 
 Annotations are retrieval features. `search_docs` and generated docs rank

guide/architecture.md

@@ -62,7 +62,7 @@ closure with deterministic `go list -json` checks.
 ## Runtime and transports
 
 Both `ccg serve` (stdio) and `ccg-server` (Streamable HTTP) use the same five
-grouped MCP dependency surfaces and expose exactly 17 tools plus four prompts.
+grouped MCP dependency surfaces and expose exactly 18 tools plus four prompts.
 The local binary does not link remote HTTP, Wiki, webhook, or remote runtime
 packages. See [Runtime Layout](runtime-layout.md).
 
@@ -74,6 +74,16 @@ filters. SQLite and PostgreSQL share GORM-owned graph operations and backend-
 specific full-text search adapters. Application and inbound packages never issue
 SQL; backend-specific SQL remains encapsulated in outbound adapters and migration code.
 
+The `cross_refs` table is the one deliberate bridge across namespaces: each row
+materializes an `@see ccg://` annotation with a symbolic target
+(`to_namespace`, `to_path`, `to_symbol`) plus derived state
+(`resolved_node_id`, `status`). Rows are rebuilt from annotations after every
+build/update of the source namespace and re-resolved when the target namespace
+rebuilds, because replace-style syncs regenerate node ids. Cross-namespace
+analysis reads go through a dedicated namespace-agnostic reader that merges
+resolved refs into traversal as synthetic `cross_ref` edges; regular
+single-namespace query paths remain strictly namespace-filtered.
+
 ## Reliability and security
 
 - Repository sync verifies HMAC before trust, applies ordered allow rules, bounds

guide/development.md

@@ -103,7 +103,7 @@ internal/
   ctx/                — Request-context values (namespace isolation)
   docs/               — Documentation generation
   mcpruntime/         — Shared MCP runtime assembly, stdio runner, cache, telemetry
-  mcp/                — MCP server (17 tools)
+  mcp/                — MCP server (18 tools)
   wikiserver/         — ccg-server Wiki static serving and viewer API
   wikiindex/          — Wiki presentation index builder (`wiki-index.json`)
   model/              — DB models

guide/ko/README.md

@@ -23,7 +23,7 @@ DB-backed graph/annotation evidence를 사용하며, 시각적 Graph 탭은
 |------|------|
 | [CLI 레퍼런스](cli-reference.md) | 모든 CLI 명령어, 옵션 및 설정 파일(`.ccg.yaml`) 안내 |
 | [Lint](lint.md) | `ccg lint` 카테고리 상세 레퍼런스, 결과 해석 및 CI 활용법 |
-| [MCP 도구](mcp-tools.md) | 17개의 MCP 도구, 에이전트 스킬, evidence-first 라우팅, AI 기반 어노테이션 |
+| [MCP 도구](mcp-tools.md) | 18개의 MCP 도구, 에이전트 스킬, evidence-first 라우팅, AI 기반 어노테이션 |
 | [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색 품질 |
 | [웹훅(Webhook)](webhook.md) | GitHub / Gitea 웹훅 동기화, 브랜치 필터링, Graceful Shutdown |
 | [Docker](docker.md) | Docker 이미지 빌드, MCP 서버 설정, Wiki UI 배포, PostgreSQL 연동 |

guide/ko/architecture.md

@@ -60,7 +60,7 @@ CLI / MCP / HTTP / Wiki / webhook -> application capability -> outbound port
 ## 런타임과 전송 계층
 
 `ccg serve`(stdio)와 `ccg-server`(Streamable HTTP)는 동일한 다섯 MCP 의존성
-그룹을 사용하며 정확히 17개 tool과 4개 prompt를 노출합니다. 로컬 바이너리는
+그룹을 사용하며 정확히 18개 tool과 4개 prompt를 노출합니다. 로컬 바이너리는
 원격 HTTP, Wiki, webhook, remote runtime 패키지를 링크하지 않습니다.
 자세한 내용은 [런타임 레이아웃](runtime-layout.md)을 참고하세요.
 

guide/ko/development.md

@@ -105,7 +105,7 @@ internal/
   ctx/                — 요청 컨텍스트 값 (namespace 격리)
   docs/               — 문서 생성 로직
   mcpruntime/         — 공용 MCP runtime assembly, stdio runner, cache, telemetry
-  mcp/                — MCP 서버 (17개 도구)
+  mcp/                — MCP 서버 (18개 도구)
   wikiserver/         — ccg-server Wiki 정적 파일 서빙 및 viewer API
   wikiindex/          — Wiki 표시용 인덱스 생성기 (`wiki-index.json`)
   model/              — DB 모델

guide/ko/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP 도구
 
-code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타임 모두에서 17개의 MCP 도구를 제공합니다.
+code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타임 모두에서 18개의 MCP 도구를 제공합니다.
 
 ## 파싱 및 빌드
 
@@ -15,27 +15,28 @@ code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타
 | 도구 | 용도 |
 | ---- | ---- |
 | `get_node` | qualified name으로 node 하나 조회 |
-| `search` | path scope를 선택적으로 적용하는 code node full-text search |
+| `search` | path scope를 선택적으로 적용하는 code node full-text search; `namespaces: []`로 여러 namespace 연합 검색 (결과에 namespace 라벨) |
 | `get_annotation` | node의 annotation과 문서 tag 조회 |
-| `query_graph` | callers, callees, imports, children, tests, inheritors, file summary 조회 |
-| `list_graph_stats` | node와 edge를 kind 및 language별로 집계 |
+| `query_graph` | callers, callees, imports, children, tests, inheritors, file summary 조회; `namespaces: []`는 namespace별 그룹 응답 |
+| `list_graph_stats` | node와 edge를 kind 및 language별로 집계; `namespaces: []`는 namespace별 그룹 응답 |
 | `list_namespaces` | graph data가 있는 namespace와 node count 목록 조회 |
 
 ## 분석
 
 | 도구 | 용도 |
 | ---- | ---- |
-| `get_impact_radius` | node 주변의 제한된 BFS 영향 반경 계산 |
-| `trace_flow` | node에서 시작하는 제한된 call chain 추적 |
+| `get_impact_radius` | node 주변의 제한된 BFS 영향 반경 계산; `cross_namespace: true`면 resolved `ccg://` ref를 양방향으로 통과 |
+| `trace_flow` | node에서 시작하는 제한된 call chain 추적; `cross_namespace: true`면 resolved `ccg://` ref를 넘어 계속 추적 |
 | `detect_changes` | git diff 기반 변경 함수 탐지 및 risk score 계산 |
 | `get_affected_flows` | 최근 변경의 영향을 받는 저장 flow 조회 |
 | `list_flows` | 저장 flow를 페이지네이션해 조회 |
+| `list_cross_refs` | 실체화된 `ccg://` cross-namespace 참조 목록 (direction: outbound/inbound/both, status 필터) |
 
 ## 문서 및 컨텍스트
 
 | 도구 | 용도 |
 | ---- | ---- |
-| `search_docs` | DB-backed 문서 후보와 graph evidence 검색 |
+| `search_docs` | DB-backed 문서 후보와 graph evidence 검색; `namespaces: []`는 namespace별 그룹 응답 |
 | `get_doc_content` | 선택한 생성 Markdown 파일을 안전하게 읽기 |
 | `get_minimal_context` | 작은 프로젝트/변경 요약과 다음 도구 제안 반환 |
 
@@ -51,4 +52,4 @@ code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타
 
 `query_graph`와 `list_flows`에는 명시적인 `limit`, `offset`을 사용하십시오. 50 또는 100개로 시작하고 페이지네이션 metadata를 따라 확장합니다.
 
-로컬 MCP client는 stdio 방식의 `ccg serve`를 시작하고, 원격 client는 `ccg-server`의 `/mcp` Streamable HTTP endpoint에 연결합니다. 두 런타임은 동일한 17개 도구를 등록합니다.
+로컬 MCP client는 stdio 방식의 `ccg serve`를 시작하고, 원격 client는 `ccg-server`의 `/mcp` Streamable HTTP endpoint에 연결합니다. 두 런타임은 동일한 18개 도구를 등록합니다.

guide/ko/runtime-layout.md

@@ -29,7 +29,7 @@ HTTP host, Wiki HTTP, webhook adapter, remote runtime은 링크하지 않습니
 - `/wiki`, `/wiki/api/*` — 선택적인 CCG 내장 Wiki
 - `/webhook` — 선택적인 GitHub/Gitea repository sync
 
-두 transport 모두 `Runtime.MCPComponents()`를 사용하므로 동일한 17개 tool과
+두 transport 모두 `Runtime.MCPComponents()`를 사용하므로 동일한 18개 tool과
 4개 prompt를 등록합니다.
 
 ## 리소스 소유권