# Code graph

> Index a repository's files, symbols, and imports so you and your agents can locate code, assess change impact, and understand indexing refusals.

The code graph is Estelle's indexed view of a repository. It records files, functions, classes, methods, and import relationships. Use it to find a definition, locate call sites, see which files depend on a change, and check code against the repository Estelle last indexed.

Use a sweep when you first connect a repository, reindex after changes, and check the repository named in any result before relying on it.

## Index a repository

Choose the workflow that matches where the code is:

- **GitHub**: connect the App and select repositories in the dashboard. This indexes code available through that installation. See [GitHub](https://docs.fatelabs.ca/github).
- **Local checkout**: run the CLI from the repository root. This can include uncommitted files in the checkout.

```bash
estelle sweep --dry-run
estelle sweep
```

`--dry-run` lists what would be sent without sending it. After later changes, update the index with:

```bash
estelle reindex
```

Run a fresh sweep after substantial changes. The index reflects the content you last sent, not every subsequent edit on your machine or every later push.

## Ask navigation questions from your agent

Connect your agent through [MCP](https://docs.fatelabs.ca/mcp), then ask questions such as “where is `createInvoice` defined?” or “what depends on this file?” The agent uses these tools:

| Tool | Result |
|---|---|
| `verify` | A verdict on code or a repository claim, including APIs that could not be resolved. |
| `find_definition` | File and line locations for a symbol. |
| `locate` | Files matching a symbol name or concept. |
| `find_usages` | Call sites for a function, with a partial-coverage warning when the searched corpus is incomplete. |
| `find_references` | Files that import a given file. |
| `blast_radius` | Files that depend on a given file, directly or through other files. |
| `dependency_path` | An import chain between two files. |
| `core_files`, `chokepoints`, `subsystems` | Orientation around important files and repository areas. |
| `import_cycles`, `refactor_order` | Circular imports and a dependency-aware order for a refactor. |
| `estelle_grep` | Text matches with a coverage header that identifies what could not be searched. |

On an account with several indexed repositories, include `repo: "owner/name"` when the tool accepts it. Otherwise Estelle may need to ask which repository you mean.

## Understand a refusal

**A refusal is not a negative finding:**
“Not swept,” “not indexed,” “stale,” or “could not verify” means Estelle lacks current evidence. It does not prove that a symbol is absent or that the code is correct.

| Message or reason | What to do |
|---|---|
| `not_indexed` or “not swept” | Index the repository for this account, then ask again. The response can list repositories that are available. |
| `repo_required` | Repeat the call with the intended `owner/name` repository. |
| `index_stale` | Reindex or sweep the current code. An older index cannot establish current line numbers or absence. |
| `index_currency_unknown` | Refresh the index so its source commit is known, then retry. |
| Partial or capped results | Treat them as incomplete evidence, not as an exhaustive search. Narrow the query or inspect the remaining files directly. |

If Estelle disagrees with a file you just edited, trust the current file and update the index. The index can trail uncommitted work.

## Inspect the Code graph page

Open **Settings → Code graph**.

- **Graph figures** shows counts of files, symbols, subsystems, and import cycles. Read the scope line directly below: it names the one repository those figures describe.
- **Code map** lets you inspect indexed files and symbols. Search for a file, class, or function; show individual objects with **All kinds**; or enable **Repository memory** to include saved memories. Select an object to open its inspector.
- **File index** lists indexed files and their symbol counts.
- **Entities** lists symbols and their defining files. Filter by symbol or file and check whether the displayed rows are a capped subset.

The page does not provide a repository picker. On a multi-repository account, Estelle chooses the repository shown and names it in the scope line.

## Review ontology changes

The ontology defines the classes and relationships used to describe your workspace. **Ontology changes** at the bottom of the Code graph page provides a review-before-apply workflow.

### Prepare and plan

Choose **Load current version** to start with the active ontology, or paste a complete proposed version in Turtle. Choose **Plan change**.

### Review the consequences

Inspect the reported risk, added and removed terms, existing data that mentions removed terms, and statements that would become true or stop being true. **Check drift** separately reports undeclared classes, undeclared properties, and disjointness violations in current data.

### Apply or roll back

Tick **I reviewed these consequences** and choose **Apply as version N**. Applying requires a signed-in person. To restore an earlier version, choose **Plan rollback** beside it, review the new plan, and apply it in the same way.

## Limits

- Results describe only what was indexed for your account and selected scope.
- Large-repository maps, file lists, and entity lists can be capped. The page says how many rows it is showing when that information is available.
- A connection appears only when it was recorded. Shared names do not automatically make two objects the same entity.

## Related

- [Atlas](https://docs.fatelabs.ca/atlas): Turn an indexed repository into a readable guide.
- [CLI](https://docs.fatelabs.ca/cli): Sweep and reindex from a local checkout.
- [MCP server](https://docs.fatelabs.ca/mcp): Use navigation tools from your coding agent.