Tutorial: your first index

Goal: go from a checkout to a queryable, freshness-tracked memory of the repo — the artifact an agent loads before planning instead of re-exploring from scratch.

1. Init

cd your-repo
kuda init

This writes a commented kuda.toml and a .kuda/ skeleton. Open the toml — the defaults are fully local and deterministic:

[extract]
kinds = ["manifest", "treesitter"]   # adapter names, tried in order

[summarize]
kind = "template"                    # deterministic cards

[store]
kind = "sqlite"
path = ".kuda/index.sqlite"

If rust-analyzer is on PATH you can add "lsp" to kinds — extraction quality tiers up automatically (see extraction tiers).

2. Sync

kuda sync

Output:

sync /home/you/your-repo
indexed 19 module(s) at 3432d05

sync walks manifests, runs the tree-sitter symbol queries from data/langs/*, summarizes each module into a card, and stores the symbol/edge graph in sqlite. It writes:

path	tier	commit?
.kuda/index.yaml	L0	yes — the always-load card
.kuda/modules/*.yaml	L1	yes — reviewable in diffs
.kuda/index.sqlite	L2	no — rebuildable graph
.kuda/meta.json	meta	no — provenance record

3. Look at what it learned

kuda map

The L0 card: repo name, the module list, detected commands, and the provenance block (commit_sha, file hashes, generator). This is the ~1k-token blob an agent reads first.

kuda card kuda-store

An L1 card: purpose (from the manifest description), public API symbols, dependency edges, verify: — the files to open before trusting the card — and its own provenance.

4. Query

kuda find IndexStore

crates/kuda-store/src/lib.rs:9 Trait kuda-store

kuda dependents serde

kuda-cards --PackageDep--> serde
kuda-core --Imports--> serde

And the doc-sweep query — everything that mentions a name, useful when a change must update code and docs and comments:

kuda refs SqliteStore --docs

5. Break it, then watch kuda notice

Edit any crates/*/Cargo.toml — change a description — and:

kuda status

drifted  kuda-store
19 fresh, 1 drifted (HEAD af26b8c)

status re-hashes each card's verify: files and compares with the recorded provenance. kuda sync regenerates only what drifted.

You have built

A committed, queryable, self-checking map of the repository. Point agents at it — via kuda mcp or kuda acp — and they plan against the map instead of grepping blindly.

Next: serve it over MCP or index a multi-repo workspace.