Ccg Docs

ccg-docs — Documentation Discovery

Separate DB-backed discovery from generated-file reads, then validate both the selected evidence and documentation quality.

Routing

search is a DB-backed narrowing layer. A question is scored against recorded @intent/@domainRule reasons as well as names, and every hit carries a node_id; it does not read a separately generated retrieval index. Read a file's Markdown with get_doc_content, then use graph tools for exact symbols and relationships. Local MCP clients use ccg serve; self-hosted clients connect to ccg-server over Streamable HTTP.

Discovery Pipeline

Use the ccg skill's Freshness Boundary before relying on graph evidence. If refresh is required, report the gap; do not invoke ccg-build unless the user explicitly names it. search can narrow candidates without generated Markdown:

search(query: "how does a caller get authenticated", limit: 5)

Generate files only when the task needs current Markdown, Wiki output, or get_doc_content:

ccg docs --out docs  # Markdown + wiki-index.json compatibility snapshot
ccg lint             # Documentation quality checks; --strict exits 1 on actionable issues

Content-Root Contract

search returns DB-backed candidates with source file_path values; it does not prove that a corresponding generated Markdown file exists in the filesystem root used by get_doc_content.

• For the default namespace, get_doc_content resolves file_path beneath the MCP server's configured rag.index_dir (default .ccg).
• For a named namespace, it resolves beneath {namespace_root}/{namespace}.
• ccg docs --out docs writes Markdown to docs, but it does not make those files readable beneath the default .ccg content root.
• To support default-namespace MCP reads, either generate with ccg docs --out .ccg/docs --rag-index-dir .ccg, configure rag.index_dir to a root that already contains docs, or use a direct local file read.
• For a named namespace, place generated docs beneath that namespace directory before calling get_doc_content.

Pass the selected result's relative generated-doc path to get_doc_content. If the read fails, report the configured-root mismatch; do not guess paths outside the allowed root.

Lint Categories

Quality Checkpoints

1. Sparse results: add accurate @intent or @index annotations with the ccg-annotate skill.
2. Stale generated docs: assess graph freshness with the ccg skill. If graph refresh is required, report that the user must explicitly invoke ccg-build; do not invoke it automatically.
3. Empty answers to a question-shaped search: an empty answer usually means nobody recorded a reason in the area, not that the graph is stale. Confirm namespace statistics and refresh only when the graph is missing or stale.
4. Missing get_doc_content file: compare the generated-doc path with the configured content root before regenerating.
5. Exact-answer needs: switch from documentation discovery to get_node, query_graph, or trace_flow.

Boundary

• Treat search as a narrowing layer, not a guaranteed Top-1 answer.
• Confirm the selected generated-doc path is readable before treating its body as evidence.
• Do not hand-edit generator-managed Markdown when the source annotation or generator owns the content.
• Separate current lint results from pre-existing unrelated findings.
• Never infer that successful generation to an arbitrary --out directory made the file MCP-readable.

Completion

Report generated Markdown and Wiki-index paths when generation was requested, the configured content root and selected generated-doc path for each document read, namespace and graph freshness, and the exact lint summary or why lint was not run. Record any discovery/read mismatch rather than claiming a candidate body was inspected.