---
id: indexing
kind: architecture
title: Indexing
status: active
---

# Indexing

Charter needs an index so agents can find the relevant parts of the spec without rereading every document on every turn.

The first index is deliberately lexical and inspectable. It is not a semantic vector store yet. A dumb index that exists beats an elegant index that lives only in a diagram.

## Command

```bash
charter index
```

The command scans the current projection and builds a lexical index over document ids. The prototype writes `.spec/state/index.json` as a disposable local cache. The target model is still database-native: index rows or derived query state attached to the same document ids, not an authoritative filesystem artifact.

## Indexed fields

For each spec document:

- document id
- path
- title
- kind
- status
- hash
- heading outline
- Markdown links
- wikilinks
- normalized lexical terms

The index also contains:

- `pathIndex`: spec path to document id.
- `termIndex`: term to document ids.
- `backlinks`: target document id or path to source document ids.

## Search

```bash
charter search agent runtime
```

Search is term-overlap over the current in-memory index built from the projection. It can later use persisted index rows or a semantic adapter, but the command should remain stable.

## Future semantic layer

Semantic indexing should be an adapter over the same document ids, not a replacement for the lexical index. Agents need stable ids, hashes, and provenance before they need vibes with cosine similarity.