# How to Run the Knowledge Graph Lint and Reconcile Product with Code Docs in TeamAI

> Learn how to run the TeamAI knowledge graph lint and reconcile product with code docs using simple CLI commands. Ensure your TeamAI knowledge graph is healthy and synchronized.

- Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To validate your TeamAI knowledge graph health, execute `teamai codebase --lint`; to cross-reference product documentation with extracted code evidence, run `teamai codebase --reconcile`.**

The Tencent/teamai-cli repository maintains a structured knowledge graph of your codebase inside the `teamwiki/` folder. Understanding how to run the knowledge graph lint and reconcile product with code docs ensures your documentation stays synchronized with actual source implementations and that the underlying graph index remains valid for AI-powered queries.

## Linting the Knowledge Graph with `--lint`

The **`--lint`** sub-command validates the consistency and structural integrity of your knowledge graph. Implemented in **[`src/codebase-wiki-lint.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/codebase-wiki-lint.ts)**, the `lintTeamwiki` function constructs a `WikiLintReport` (lines 35-43) that aggregates issues across multiple validation checkpoints.

### Critical Checks Performed

The linter validates the following components with assigned severity levels:

- **Graph Index Presence** (**high**): Verifies [`teamwiki/.indices/graph-index.json`](https://github.com/Tencent/teamai-cli/blob/main/teamwiki/.indices/graph-index.json) exists and contains valid JSON
- **Evidence Directory** (**high**/**medium**): Confirms `teamwiki/evidence/code/` exists and contains at least one project
- **Project Structure** (**low**): Checks that each project under `evidence/code/` contains an [`index.md`](https://github.com/Tencent/teamai-cli/blob/main/index.md) entry point
- **Navigation Files** (**low**): Validates existence of [`router.md`](https://github.com/Tencent/teamai-cli/blob/main/router.md), [`index.md`](https://github.com/Tencent/teamai-cli/blob/main/index.md), and [`hot.md`](https://github.com/Tencent/teamai-cli/blob/main/hot.md) wiki entry points
- **Source Manifest** (**low**/**medium**): Ensures [`teamwiki/source-manifest.json`](https://github.com/Tencent/teamai-cli/blob/main/teamwiki/source-manifest.json) exists and is recent (< 60 days)
- **Graph Health Metrics** (**medium**/**high**): Analyzes node/edge counts, orphan nodes, and connectivity to detect isolated sub-graphs

### Running the Lint Command

Execute the basic lint to receive a human-readable report:

```bash
teamai codebase --lint

```

Filter output by severity for focused debugging:

```bash

# Show only critical issues

teamai codebase --lint --severity high

```

Generate JSON output for automated CI pipelines:

```bash
teamai codebase --lint --json

```

The command produces a structured summary indicating specific failures:

```

❯ teamai codebase --lint
✖ graph-missing   teamwiki/.indices/graph-index.json   graph-index.json 不存在，知识图谱未构建
✖ evidence-missing teamwiki/evidence/code/            evidence 目录不存在，无代码事实页
…
Summary: 2 high, 0 medium, 0 low, 0 info issues (2 total)

```

## Reconciling Product Documentation with Code Evidence

The **`--reconcile`** workflow bridges the gap between product documentation and code evidence pages. Located in **[`src/wiki-engine/knowledge-reconciler.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/wiki-engine/knowledge-reconciler.ts)**, the `reconcileKnowledge` function (lines 260-300) maps product Markdown files to corresponding code evidence and creates bidirectional linkages.

### How Reconciliation Works

The process executes four key steps:

1. **Validate Graph Index**: Aborts if [`graph-index.json`](https://github.com/Tencent/teamai-cli/blob/main/graph-index.json) is missing or corrupt
2. **Load Product Docs**: Parses Markdown headings from your `docs/` folder and extracts identifiers to locate matching code pages
3. **Create Bridge Edges**: Generates edges labeled with the provenance type `"bridge-reconcile"` (defined in **[`src/wiki-engine/core/graph-index.schema.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/wiki-engine/core/graph-index.schema.ts)**) linking product sections to code evidence
4. **Persist Updates**: Writes the modified graph back to disk with a status summary

### Executing Reconciliation

Run the reconcile command to update bridge edges:

```bash
teamai codebase --reconcile

```

Combine with linting to verify changes immediately:

```bash
teamai codebase --reconcile --lint

```

The CLI outputs detected conflicts, such as:

```

✖ missing-bridge   docs/feature-x.md → evidence/code/feature-x/   No matching code page found

```

## Complete Workflow for Knowledge Graph Maintenance

A typical maintenance cycle ensures your knowledge graph remains accurate and synchronized:

```bash

# 1. Extract fresh evidence (if not already present)

teamai codebase --extract /path/to/repo

# 2. Validate current state

teamai codebase --lint --severity high

# 3. Synchronize product and code documentation

teamai codebase --reconcile

# 4. Verify reconciliation succeeded

teamai codebase --lint

```

For CI automation, fail the pipeline on high-severity issues:

```bash
teamai codebase --lint --json | jq 'select(.summary.high > 0)' && exit 1

```

## Summary

- The **`--lint`** command in [`src/codebase-wiki-lint.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/codebase-wiki-lint.ts) validates graph integrity, evidence presence, and navigation structure with configurable severity filtering.
- The **`--reconcile`** command in [`src/wiki-engine/knowledge-reconciler.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/wiki-engine/knowledge-reconciler.ts) creates `"bridge-reconcile"` edges linking product docs to code evidence pages.
- Both commands operate on the `teamwiki/` directory, specifically targeting [`.indices/graph-index.json`](https://github.com/Tencent/teamai-cli/blob/main/.indices/graph-index.json) and `evidence/code/` paths.
- JSON output and severity flags support integration into automated CI/CD pipelines for continuous knowledge graph validation.

## Frequently Asked Questions

### What does the knowledge graph lint check in TeamAI?

The lint command verifies that [`teamwiki/.indices/graph-index.json`](https://github.com/Tencent/teamai-cli/blob/main/teamwiki/.indices/graph-index.json) exists and is valid, confirms that `teamwiki/evidence/code/` contains extracted project data, checks for required navigation files ([`router.md`](https://github.com/Tencent/teamai-cli/blob/main/router.md), [`index.md`](https://github.com/Tencent/teamai-cli/blob/main/index.md), [`hot.md`](https://github.com/Tencent/teamai-cli/blob/main/hot.md)), and analyzes graph health metrics including orphan nodes and connectivity issues. Each check carries a severity level (high, medium, low) that you can filter using the `--severity` flag.

### How do I fix missing bridge edges between product and code docs?

Execute `teamai codebase --reconcile` to trigger the `reconcileKnowledge` function, which scans your product documentation (typically under `docs/`), matches sections to code evidence pages in `teamwiki/evidence/code/`, and creates bridge edges with the `"bridge-reconcile"` provenance label. If the command reports `missing-bridge` warnings, ensure your code evidence exists for the referenced product features or adjust your documentation identifiers to match the extracted code page names.

### Can I automate the lint process in CI pipelines?

Yes. Use the `--json` flag to output machine-readable results and pipe the output to validation tools like `jq`. For example: `teamai codebase --lint --json | jq 'select(.summary.high > 0)' && exit 1` will fail the build if any high-severity issues exist. The JSON structure includes the `issues` array and summary counts generated by the `WikiLintReport` class in [`src/codebase-wiki-lint.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/codebase-wiki-lint.ts).

### Where is the reconciliation logic implemented in the source code?

The core reconciliation algorithm resides in **[`src/wiki-engine/knowledge-reconciler.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/wiki-engine/knowledge-reconciler.ts)**, specifically within the `reconcileKnowledge` function (lines 260-300). The CLI entry point that parses the `--reconcile` flag is located in **[`src/codebase-cmd.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/codebase-cmd.ts)**, and the graph schema defining the `"bridge-reconcile"` edge type is declared in **[`src/wiki-engine/core/graph-index.schema.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/wiki-engine/core/graph-index.schema.ts)**.