docs: add CodeGraph OpenClaw example tutorial

[BingqingLyu]

Adds a CodeGraph use case tutorial to the documentation.

Changes

• Added doc/source/tutorials/codegraph-openclaw-example.md: end-to-end walkthrough of CodeGraph with the OpenClaw codebase, covering indexing, CLI usage, Python API, hotspot/bridge/dead-code analysis, and semantic search
• Registered the new page in doc/source/index.rst under the Tutorials section

Greptile Summary

This PR adds an end-to-end tutorial (codegraph-openclaw-example.md) for the CodeGraph skill — a code analysis tool built on NeuG and a vector database — and registers it in the documentation's Tutorials toctree. The tutorial walks through installation, CLI usage, Python API queries, and built-in analysis methods (hotspots, bridge functions, dead code, semantic search) using the OpenClaw codebase as a concrete example.

Key issues found:

• Factual inconsistency in hotspot ranking (line 229): The section states hotspots are "ranked by fan-in × fan-out," but the example output places functions with fan_out=0 (e.g., push with fan_in=1747, fan_out=0 → product=0) at the very top, which contradicts the stated formula. The ranking criterion should be corrected or the formula description should be updated.
• Semantic search output is opaque (line 323): The example only prints truncated vector IDs and scores. Readers have no way to identify which functions matched from the output alone — function names and file paths should be shown.
• Dead code filter note lacks a code example (line 317): The note recommends filtering by is_external = 0 to exclude vendored/virtual-env files, but provides no snippet demonstrating how to apply that filter in practice.

Confidence Score: 3/5

• Safe to merge after addressing the hotspot ranking factual inconsistency; the other two issues are polish-level improvements.
• The index.rst change is trivial and correct. The tutorial itself is well-structured and covers the feature thoroughly, but the hotspot description contains a demonstrable factual error (items with fan_out=0 cannot rank first under a fan-in × fan-out formula), which would mislead readers about how the scoring actually works. The semantic search and dead-code issues are usability gaps rather than blockers.
• doc/source/tutorials/codegraph-openclaw-example.md — specifically the hotspot ranking description and the semantic search output example.

Important Files Changed

Filename	Overview
doc/source/tutorials/codegraph-openclaw-example.md	New 353-line tutorial for CodeGraph with the OpenClaw codebase. Contains a factual inconsistency in the hotspot ranking description (claims fan-in × fan-out but the example output contradicts this), and the semantic search example output shows only opaque IDs without resolving them to function names.
doc/source/index.rst	One-line addition registering the new tutorial in the Tutorials toctree. Change is correct and consistent with the existing entry format.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Source Repository] -->|codegraph init| B[Indexing Pipeline]
    B --> C[(NeuG Graph DB\nFile, Function, Class,\nModule, Commit nodes)]
    B --> D[(zvec Vector DB\nFunction Embeddings)]

    C & D --> E[CodeGraph API / CLI]

    E --> F[CLI Commands]
    F --> F1[codegraph status]
    F --> F2[codegraph query NL]
    F --> F3[codegraph analyze]

    E --> G[Python API — CodeScope]
    G --> G1[cs.conn.execute\nCypher Queries]
    G --> G2[cs.hotspots\nfan-in × fan-out ranking]
    G --> G3[cs.bridge_functions\ncross-module callers]
    G --> G4[cs.dead_code\nzero-caller functions]
    G --> G5[cs.vector_only_search\nsemantic similarity]

    G1 --> H[Call Chain / Impact Analysis]
    G2 --> I[Architecture Hotspots]
    G3 --> J[Bridge Functions Report]
    G4 --> K[Dead Code Report]
    G5 --> L[Semantic Search Results]

Loading

_{Last reviewed commit: "add a codegraph exam..."}

Greptile also left 3 inline comments on this PR.

[qodo-code-review]

Review Summary by Qodo

Add CodeGraph tutorial with OpenClaw codebase example

📝 Documentation

Walkthroughs

Description

• Adds comprehensive CodeGraph tutorial with OpenClaw codebase example
• Demonstrates CLI usage, Python API, and built-in analysis methods
• Includes practical examples of hotspot, bridge, and dead code analysis
• Registers tutorial in documentation index under Tutorials section

Diagram

flowchart LR
  A["Documentation Index"] -->|registers| B["CodeGraph Tutorial"]
  B -->|covers| C["CLI Usage"]
  B -->|covers| D["Python API"]
  B -->|covers| E["Analysis Methods"]
  E -->|includes| F["Hotspots"]
  E -->|includes| G["Bridge Functions"]
  E -->|includes| H["Dead Code Detection"]
  E -->|includes| I["Semantic Search"]

Loading

File Changes

1. doc/source/tutorials/codegraph-openclaw-example.md 📝 Documentation +353/-0

CodeGraph tutorial with OpenClaw analysis examples

• New comprehensive tutorial covering CodeGraph capabilities and architecture
• Includes environment setup, indexing instructions, and CLI usage examples
• Demonstrates Python API with real OpenClaw codebase examples
• Documents built-in analysis methods: hotspots, bridge functions, dead code, semantic search
• Provides Cypher query templates for common code analysis patterns

doc/source/tutorials/codegraph-openclaw-example.md

---

2. doc/source/index.rst 📝 Documentation +1/-0

Register CodeGraph tutorial in documentation index

• Registers new CodeGraph tutorial in documentation index
• Added under Tutorials section alongside existing tinysnb_tutorial

doc/source/index.rst

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. No MODIFIES backfill enabled 🐞 Bug ✓ Correctness

Description

The tutorial’s codegraph init command omits --backfill-limit, so function-level MODIFIES edges
are never computed and evolution features relying on them won’t work (your own sample output shows
MODIFIES: 0). This contradicts the documented requirement that MODIFIES edges require backfill.

Code

doc/source/tutorials/codegraph-openclaw-example.md[R52-58]

+```bash
+# Create index (first time)
+codegraph init --repo /path/to/your/project --lang auto --commits 100
+
+# Check index status
+codegraph status --db $CODESCOPE_DB_DIR
+```

Evidence

The tutorial’s indexing command doesn’t include backfill and the shown status output confirms there
are zero MODIFIES edges. Repo docs explicitly state MODIFIES edges require backfill /
--backfill-limit.

doc/source/tutorials/codegraph-openclaw-example.md[52-58]
doc/source/tutorials/codegraph-openclaw-example.md[74-78]
skills/codegraph/SKILL.md[53-62]
skills/codegraph/schema.md[24-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The tutorial instructs running `codegraph init` without `--backfill-limit`, which prevents generating function-level `MODIFIES` edges and breaks evolution workflows that depend on them.

### Issue Context
Repository CodeGraph docs state `MODIFIES` edges require backfill and the CLI supports this via `--backfill-limit`.

### Fix Focus Areas
- doc/source/tutorials/codegraph-openclaw-example.md[52-58]
- doc/source/tutorials/codegraph-openclaw-example.md[74-78]

### What to change
- Update the `codegraph init` example to include an explicit `--backfill-limit` value (or add an adjacent note explaining that without backfill `MODIFIES` remains 0 and evolution queries will be limited).
- Ensure the sample `codegraph status` output is consistent with the updated command (either show non-zero MODIFIES, or explicitly explain why it may be 0).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. CodeScope never closed 🐞 Bug ⛯ Reliability

Description

The Python API section creates a CodeScope instance but never shows calling cs.close(),
contradicting existing CodeGraph docs that say to always close it. This omission encourages
copy/paste usage that can leave resources open and contribute to lock-related errors.

Code

doc/source/tutorials/codegraph-openclaw-example.md[R137-143]

+```python
+import os
+os.environ['HF_HUB_OFFLINE'] = '1'
+
+from codegraph.core import CodeScope
+cs = CodeScope(os.environ['CODESCOPE_DB_DIR'])
+```

Evidence

The new tutorial instantiates CodeScope and proceeds with many examples without ever demonstrating
closing it. Existing CodeGraph documentation includes cs.close()  # always close when done and
lists lock-related errors in troubleshooting, reinforcing that proper cleanup matters.

doc/source/tutorials/codegraph-openclaw-example.md[137-143]
doc/source/tutorials/codegraph-openclaw-example.md[225-337]
skills/codegraph/SKILL.md[74-90]
skills/codegraph/bug-analysis.md[15-31]
skills/codegraph/SKILL.md[374-381]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The tutorial demonstrates creating a `CodeScope` object but never demonstrates closing it. Existing repository docs explicitly instruct calling `cs.close()`.

### Issue Context
The Python section is structured as a shared setup plus multiple subsequent snippets, so the most natural fix is to add a closing snippet at the end of the Python API section (or show a `try/finally` pattern).

### Fix Focus Areas
- doc/source/tutorials/codegraph-openclaw-example.md[137-143]
- doc/source/tutorials/codegraph-openclaw-example.md[225-337]

### What to change
- Add a short snippet near the end of the Python API section:
 - `cs.close()` (and/or `try: ... finally: cs.close()`), matching the style in `skills/codegraph/SKILL.md`.
- Optionally add a one-line note that the connection should be closed when finished.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[greptile-apps]

Hotspot ranking formula contradicts the actual output

The section header states hotspots are "ranked by fan-in × fan-out," but several of the top-ranked results have fan_out=0, which would produce a score of 0 under that formula and should place them at the bottom — not the top:

• push: fan_in=1747, fan_out=0 → product = 0
• fn: fan_in=533, fan_out=1 → product = 533
• now: fan_in=857, fan_out=0 → product = 0

createConfigIO (fan_in=18, fan_out=57 → 1,026) and startGatewayServer (10 × 88 = 880) would actually rank highest under the stated formula. Either the formula description is incorrect (the actual ranking may be something like max(fan_in, fan_out) or fan_in + fan_out), or the output was produced with different logic. This inconsistency will confuse readers trying to understand the hotspot scoring model.

[greptile-apps]

Semantic search output shows only opaque IDs — function names are missing

The example prints truncated vector IDs and scores, but gives readers no way to identify which functions were matched:

id=59744ec14e23575012c1... score=0.514

As a tutorial, this output is not actionable — a user can't act on an ID alone without knowing the corresponding function name and file path. If the vector_only_search result dict contains those fields (e.g., name, file_path), the example should include them. For instance:

results = cs.vector_only_search('heartbeat periodic wake agent schedule', topk=5)
for r in results:
    print(f"{r.get('name', r['id'][:20])} @ {r.get('file_path', '?')} — score={r['score']:.3f}")

Even if the API only returns IDs, the tutorial should explain what a reader should do next (e.g., query the graph to resolve the ID to a function node).

[greptile-apps]

Dead-code filter note lacks a code example

The note advises filtering by is_external = 0 to exclude virtual-environment files, but the tutorial is code-driven and this is exactly the kind of practical pitfall a reader will hit first. Providing the actual query would make this note actionable:

# Filter out external/vendored dependencies
for d in cs.dead_code()[:10]:
    if not getattr(d, 'is_external', 0):
        print(f"{d.name} @ {d.file_path}")

Or, if dead_code() accepts a parameter:

for d in cs.dead_code(is_external=False)[:10]:
    print(f"{d.name} @ {d.file_path}")

Without a working snippet, the reader must guess the attribute name and the filtering mechanism.

[qodo-code-review]

1. No modifies backfill enabled 🐞 Bug ✓ Correctness

The tutorial’s codegraph init command omits --backfill-limit, so function-level MODIFIES edges
are never computed and evolution features relying on them won’t work (your own sample output shows
MODIFIES: 0). This contradicts the documented requirement that MODIFIES edges require backfill.

Agent Prompt

### Issue description
The tutorial instructs running `codegraph init` without `--backfill-limit`, which prevents generating function-level `MODIFIES` edges and breaks evolution workflows that depend on them.

### Issue Context
Repository CodeGraph docs state `MODIFIES` edges require backfill and the CLI supports this via `--backfill-limit`.

### Fix Focus Areas
- doc/source/tutorials/codegraph-openclaw-example.md[52-58]
- doc/source/tutorials/codegraph-openclaw-example.md[74-78]

### What to change
- Update the `codegraph init` example to include an explicit `--backfill-limit` value (or add an adjacent note explaining that without backfill `MODIFIES` remains 0 and evolution queries will be limited).
- Ensure the sample `codegraph status` output is consistent with the updated command (either show non-zero MODIFIES, or explicitly explain why it may be 0).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[longbinlai]

LGTM