feat: add default namespace to configuration and update documentation for agent skills

Author: tae2089

.ccg.yaml

@@ -2,6 +2,8 @@ db:
   driver: sqlite # sqlite | postgres
   dsn: ccg.db
 
+namespace: default
+
 output:
   dir: ./docs
   per_file: true

AGENTS.md

@@ -1,10 +1,10 @@
 # code-context-graph
 
-코드베이스를 Tree-sitter로 파싱하여 지식 그래프를 구축하는 로컬 코드 분석 도구.
+A local code analysis tool that parses codebases with Tree-sitter and builds a knowledge graph.
 
-## MCP 서버
+## MCP Server
 
-`.mcp.json`에 등록된 ccg MCP 서버가 35개 도구를 제공합니다:
+The ccg MCP server registered in `.mcp.json` provides 35 tools:
 
 - `parse_project`, `build_or_update_graph`, `run_postprocess`
 - `get_postprocess_policy`, `reset_postprocess_policy`
@@ -18,95 +18,102 @@
 - `upload_file`, `upload_files`, `list_namespaces`, `list_files`, `delete_file`, `delete_namespace`
 - `list_workspaces`, `delete_workspace` (deprecated aliases)
 
-HTTP 모드 (`--transport streamable-http`)에서는 `/health` 및 `/webhook` 엔드포인트도 제공합니다.
-Webhook은 `--allow-repo` 플래그로 허용 리포지토리를 설정하면 활성화됩니다.
-레포별 브랜치 필터링: `--allow-repo "org/api:main,develop"` (glob 패턴, 미지정 시 main/master 기본).
-GitHub (`X-Hub-Signature-256`) 및 Gitea (`X-Gitea-Signature`, `X-Gitea-Event`) 호환.
-Push 이벤트 수신 → 자동 clone/pull → 그래프 빌드 → DB 저장 파이프라인.
-Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cancel 전파.
+In HTTP mode (`--transport streamable-http`), it also provides `/health` and `/webhook` endpoints.
+Webhooks are enabled when allowed repositories are configured with the `--allow-repo` flag.
+Per-repository branch filtering: `--allow-repo "org/api:main,develop"` (glob patterns; defaults to main/master when omitted).
+Compatible with GitHub (`X-Hub-Signature-256`) and Gitea (`X-Gitea-Signature`, `X-Gitea-Event`).
+Push event pipeline: receive push event -> automatic clone/pull -> graph build -> DB persistence.
+Graceful shutdown: SIGINT/SIGTERM propagates context cancellation to in-progress clone/build work.
 
-## CLI Skills (5개)
+## Agent Skills (5)
 
-| Skill            | 설명                                                                              |
-| ---------------- | --------------------------------------------------------------------------------- |
-| `/ccg`           | 코어 빌드 & 검색 — 파싱, 그래프 빌드, 쿼리, 검색                                  |
-| `/ccg-analyze`   | 코드 분석 — 영향 반경, 플로우 추적, 데드코드, 아키텍처                            |
-| `/ccg-annotate`  | 어노테이션 시스템 — AI 어노테이션 워크플로우, 태그 레퍼런스                       |
-| `/ccg-docs`      | 문서 — 문서 생성, RAG 인덱싱, lint                                                |
-| `/ccg-workspace` | 네임스페이스 파일 관리 — 파일 업로드, 목록, 삭제 (`workspace`는 deprecated alias) |
+| Skill            | Description                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| `/ccg`           | Core build and search: parsing, graph build, query, search                                   |
+| `/ccg-analyze`   | Code analysis: impact radius, flow tracing, dead code, architecture                          |
+| `/ccg-annotate`  | Annotation system: AI annotation workflow and tag reference                                  |
+| `/ccg-docs`      | Documentation: doc generation, RAG indexing, lint                                            |
+| `/ccg-workspace` | Namespace file management: upload, list, delete (`workspace` is a deprecated alias)          |
 
-주요 커맨드:
+Skill files are located under `skills/` and are written so coding agents such as Codex and Claude Code
+can use them as slash-command style workflows.
 
-- `ccg build [dir]` — 코드 그래프 빌드 (`--exclude`, `--no-recursive` 지원)
-- `ccg docs [--out dir]` — 마크다운 문서 및 기본 RAG 인덱스 생성
-- `ccg rag-index [--out dir]` — 이미 계산된 커뮤니티와 생성 문서 기반 RAG 인덱스 생성
-- `ccg search <query>` — 전문 검색 (어노테이션 포함)
-- `ccg lint [--strict]` — 문서 품질 체크
-- `ccg annotate [file|dir]` — AI 어노테이션 생성
+Main commands:
 
-`.ccg.yaml`로 exclude 패턴, DB 설정 등을 프로젝트 기본값으로 관리할 수 있습니다.
+- `ccg build [dir]` - build the code graph (supports `--exclude`, `--no-recursive`)
+- `ccg docs [--out dir]` - generate Markdown documentation and the default RAG index
+- `ccg rag-index [--out dir]` - build a RAG index from precomputed communities and generated docs
+- `ccg search <query>` - full-text search (includes annotations)
+- `ccg lint [--strict]` - check documentation quality
+- `/ccg-annotate annotate [file|dir]` - AI annotation generation workflow
+- `ccg example [language]`, `ccg tags` - annotation examples and tag reference
 
-## 코드 검색 규칙
+Use `.ccg.yaml` to manage project defaults such as exclude patterns and DB settings.
 
-코드 위치, 관련 구현, 호출 관계, 영향 범위, 아키텍처 맥락을 찾을 때는 먼저 ccg MCP 도구와 CLI Skills를 활용합니다.
+## Code Search Rules
 
-- 자연어 기반 코드 이해, 모듈 탐색, 아키텍처 맥락 수집은 `/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`)를 우선 사용합니다.
-- 단순 문자열 확인, 파일 존재 확인, ccg 인덱스가 없거나 오래된 경우에는 `rg`를 보조로 사용하고, 필요한 경우 `ccg build .` 또는 `ccg update .`로 그래프를 갱신합니다.
+When looking for code locations, related implementations, call relationships, impact radius, or architecture context,
+use ccg MCP tools and Agent Skills first.
 
-## 문서
+- For natural-language code understanding, module exploration, and architecture context, prefer the `/ccg-docs` skill and `retrieve_docs`, `get_rag_tree`, `get_doc_content`.
+- For exact symbol locations, call relationships, and graph metadata, use ccg MCP `query_graph`, `get_node`, `get_minimal_context`, or the `/ccg` skill.
+- For annotation/keyword-based candidate search, use ccg MCP `search` or `ccg search` as a supplement.
+- For impact radius, flows, dead code, and structural analysis, prefer the `/ccg-analyze` skill and related MCP tools (`get_impact_radius`, `trace_flow`, `find_dead_code`, `get_architecture_overview`).
+- For simple string checks, file existence checks, or cases where the ccg index is missing or stale, use `rg` as a supplement. If needed, refresh the graph with `ccg build .` or `ccg update .`.
 
-상세 문서는 `guide/` 디렉토리를 참조하세요:
+## Documentation
 
-- [CLI Reference](guide/cli-reference.md) — 전체 명령어, 플래그, 설정 파일
-- [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 배포
-- [Development](guide/development.md) — 개발 가이드, Integration test, 프로젝트 구조
-- [Architecture](guide/architecture.md) — 데이터 흐름, 컴포넌트, DB 스키마
+See the `guide/` directory for detailed documentation:
 
-## 개발 규칙
+- [CLI Reference](guide/cli-reference.md) - all commands, flags, and config files
+- [MCP Tools](guide/mcp-tools.md) - 35 MCP tools, Agent Skills, AI-Driven Annotation
+- [Annotations](guide/annotations.md) - annotation tags, examples, and search
+- [Webhook](guide/webhook.md) - webhook sync, branch filtering, HMAC, graceful shutdown
+- [Docker](guide/docker.md) - Docker builds, MCP server, PostgreSQL deployment
+- [Development](guide/development.md) - development guide, integration tests, project structure
+- [Architecture](guide/architecture.md) - data flow, components, DB schema
 
-- TDD: Red → Green → Refactor
-- Tidy First: 구조적 변경과 행위 변경 분리
-- GORM 쿼리만 사용 (raw SQL 금지)
-- 테스트: `CGO_ENABLED=1 go test -tags "fts5" ./... -count=1`
-- Integration test: `./scripts/integration-test.sh` (Gitea + PostgreSQL + ccg Docker 전체 파이프라인)
+## Development Rules
 
-## 코드 작성 규칙
+- TDD: Red -> Green -> Refactor
+- Tidy First: separate structural changes from behavioral changes
+- Use GORM queries only (no raw SQL)
+- Tests: `CGO_ENABLED=1 go test -tags "fts5" ./... -count=1`
+- Integration test: `./scripts/integration-test.sh` (full Gitea + PostgreSQL + ccg Docker pipeline)
 
-새 코드를 생성하거나 기존 코드의 의미 있는 동작을 바꿀 때는 CCG annotation을 함께 작성합니다.
+## Code Writing Rules
 
-우선순위:
+When creating new code or making meaningful behavior changes to existing code, add CCG annotations as well.
 
-- 패키지/파일의 역할이 드러나야 하면 `// @index ...`
-- 새 public type/function/method, MCP handler, CLI command, service method에는 `// @intent ...`
-- 입력/출력 계약이 중요한 함수에는 `// @param`, `// @return`
-- 사전 조건/보장 조건이 중요한 경우 `// @requires`, `// @ensures`
-- 파일, DB, 네트워크, 캐시, 로그, 프로세스 등 외부 상태를 바꾸면 `// @sideEffect`
-- receiver나 인자로 받은 값을 변경하면 `// @mutates`
-- 비즈니스 규칙, 운영 정책, false-positive/false-negative 판단 기준은 `// @domainRule`
-- 관련 핸들러/서비스/모델이 있으면 `// @see`
+Priority:
 
-Annotation은 코드의 동작과 맞아야 하며, 설명을 부풀리지 않습니다. 단순 getter/setter나 자명한 한 줄 helper에는 억지로 붙이지 않습니다.
+- Use `// @index ...` when the package/file role should be discoverable.
+- Use `// @intent ...` for new public types/functions/methods, MCP handlers, CLI commands, and service methods.
+- Use `// @param`, `// @return` when input/output contracts matter.
+- Use `// @requires`, `// @ensures` when preconditions or guarantees matter.
+- Use `// @sideEffect` when the code mutates external state such as files, DB, network, cache, logs, or processes.
+- Use `// @mutates` when the receiver or argument values are modified.
+- Use `// @domainRule` for business rules, operational policies, and false-positive/false-negative criteria.
+- Use `// @see` when related handlers, services, or models exist.
 
-## 작업 완료 체크
+Annotations must match the code behavior and should not exaggerate the explanation.
+Do not force annotations onto simple getters/setters or obvious one-line helpers.
 
-코드 생성/수정 작업을 완료하면 기본적으로 다음을 실행합니다.
+## Completion Checklist
+
+After completing code generation or code modifications, run the following by default:
 
 ```bash
 ccg build .
 ccg docs --out docs
 ccg lint
 ```
 
-동작 변경이나 DB/검색/파서/MCP 핸들러 변경이 있으면 Go 테스트도 함께 실행합니다.
+If the change modifies behavior or touches DB/search/parser/MCP handlers, also run Go tests:
 
 ```bash
 CGO_ENABLED=1 go test -tags "fts5" ./... -count=1
 ```
 
-문서만 수정한 작업은 `ccg docs` 재생성과 `ccg lint`를 우선하고, 코드 테스트는 변경 범위에 따라 생략할 수 있습니다.
+For documentation-only changes, prioritize regenerating docs with `ccg docs` and running `ccg lint`.
+Code tests may be skipped depending on the change scope.

README.md

@@ -155,13 +155,13 @@ deadcode.Service.Find     function  internal/analysis/deadcode/service.go:38
 mcp.handlers.findDeadCode function  internal/mcp/handler_analysis.go:273
 ```
 
-### 4. Claude Integration via MCP
+### 4. Agent Integration via MCP
 
-After configuring `.mcp.json`, you can ask Claude Code directly:
+After configuring `.mcp.json`, you can ask an MCP-capable coding agent directly:
 
 > **"Explain the webhook sync flow in this project"**
 
-Claude calls CCG MCP tools and answers directly from the graph:
+The agent calls CCG MCP tools and answers directly from the graph:
 
 ```
 trace_flow(qualified_name: "webhook.WebhookHandler.ServeHTTP")
@@ -208,7 +208,8 @@ For remote HTTP mode:
 }
 ```
 
-Claude Code automatically connects and gets access to 35 MCP tools. See [MCP Tools Reference](guide/mcp-tools.md) for the full list.
+MCP-capable clients such as Codex or Claude Code can connect and get access to
+35 MCP tools. See [MCP Tools Reference](guide/mcp-tools.md) for the full list.
 
 ## Architecture
 
@@ -219,11 +220,11 @@ Source Code → Tree-sitter Parser → Nodes + Edges + Annotations
                                         ↓
                                    FTS Search
                                         ↓
-                              MCP Server (33 tools)
+                              MCP Server (35 tools)
                                     ↓         ↓
                               stdio       Streamable HTTP
                                 ↓              ↓
-                           Claude Code    Remote Clients
+                         Coding Agents    Remote Clients
                                                ↑
                                 GitHub / Gitea Webhook
                                     push → clone → build → DB
@@ -239,7 +240,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) | 35 MCP tools, Skills, AI-Driven Annotation |
+| [MCP Tools](guide/mcp-tools.md) | 35 MCP tools, agent 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

@@ -11,7 +11,7 @@ document, or symbol candidate is identified.
 | [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) | 35 MCP tools, Claude Code Skills, RAG-first routing, AI-driven annotation |
+| [MCP Tools](mcp-tools.md) | 35 MCP tools, agent 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 |

guide/annotations.md

@@ -56,13 +56,14 @@ func AuthenticateUser(username, password string) (string, error) {
 
 ## AI-Driven Annotation
 
-Claude Code can analyze your codebase and automatically generate annotations:
+Coding agents with the `/ccg-annotate` skill can analyze your codebase and
+generate annotations:
 
 ```
 You: "Add annotations to this project"
-Claude: reads code → generates @intent, @domainRule, @sideEffect, @mutates
-      → writes annotations → rebuilds index
-      → now searchable by business context
+Agent: reads code → generates @intent, @domainRule, @sideEffect, @mutates
+       → writes annotations → rebuilds index
+       → now searchable by business context
 ```
 
 ### CLI
@@ -78,7 +79,7 @@ ccg tags
 
 ### Skill
 
-Use directly in Claude Code with the `/ccg-annotate` skill:
+Use directly in a skill-capable coding agent with the `/ccg-annotate` skill:
 
 ```
 /ccg-annotate annotate internal/   — AI-generate annotations

guide/architecture.md

@@ -9,11 +9,11 @@ Source Code → Tree-sitter Parser → Nodes + Edges + Annotations
                                         ↓
                                    FTS Search
                                         ↓
-                              MCP Server (33 tools)
+                              MCP Server (35 tools)
                                     ↓         ↓
                               stdio       Streamable HTTP
                                 ↓              ↓
-                           Claude Code    Remote Clients
+                         Coding Agents    Remote Clients
                                                ↑
                                 GitHub / Gitea Webhook
                                     push → clone → build → DB
@@ -77,7 +77,7 @@ Golden corpus-based parser accuracy and search quality evaluation framework.
 
 ### MCP Server (`internal/mcp/`)
 
-Exposes 33 tools via MCP protocol. Supports two transport modes: stdio and Streamable HTTP.
+Exposes 35 tools via MCP protocol. Supports two transport modes: stdio and Streamable HTTP.
 
 ### Reliability
 

guide/development.md

@@ -105,15 +105,15 @@ internal/
   ctxns/              — Context namespace
   docs/               — Documentation generation
   eval/               — Parser/search quality evaluation (golden corpus, P/R/F1, P@K, MRR, nDCG)
-  mcp/                — MCP server (33 tools)
+  mcp/                — MCP server (35 tools)
   model/              — DB models
   parse/treesitter/   — Tree-sitter parser (12 languages, including Lua/Luau)
   pathutil/           — Path utilities
   ragindex/           — RAG index
   service/            — Business logic
   store/              — GORM store
   webhook/            — Webhook handler, SyncQueue, RepoFilter
-skills/               — Claude Code skill files
+skills/               — Agent skill files
 guide/                — Project documentation
 docs/                 — Auto-generated docs (ccg docs)
 testdata/eval/        — Eval golden corpus (12-language sources + golden JSON)

guide/ko/README.md

@@ -13,7 +13,7 @@ LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 생
 | [CLI 레퍼런스](cli-reference.md) | 모든 CLI 명령어, 옵션 및 설정 파일(`.ccg.yaml`) 안내 |
 | [Eval](eval.md) | 파서/검색 품질 평가, golden corpus, 지표 설명 |
 | [Lint](lint.md) | `ccg lint` 카테고리 상세 레퍼런스, 결과 해석 및 CI 활용법 |
-| [MCP 도구](mcp-tools.md) | 35개의 MCP 도구, Claude Code Skill, RAG 우선 라우팅, AI 기반 어노테이션 |
+| [MCP 도구](mcp-tools.md) | 35개의 MCP 도구, 에이전트 스킬, RAG 우선 라우팅, AI 기반 어노테이션 |
 | [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색/RAG 품질 |
 | [웹훅(Webhook)](webhook.md) | GitHub / Gitea 웹훅 동기화, 브랜치 필터링, Graceful Shutdown |
 | [Docker](docker.md) | Docker 이미지 빌드, MCP 서버 설정, PostgreSQL 연동 |