Quick start¶

This walkthrough creates a small offline project, inspects the work, builds the index, retrieves a chunk, and verifies durable state. It uses no API account and sends no data over the network.

1. Create a project¶

Start in an empty directory and initialize the configuration:

mkdir steadlith-demo
cd steadlith-demo
steadlith init

The command writes steadlith.toml. The generated configuration includes Markdown under docs/ and README.md, stores reusable embeddings in .steadlith/cache.sqlite3, and stores the index in .steadlith/index.sqlite3.

Create docs/notes.md:

python -c "from pathlib import Path; Path('docs').mkdir(exist_ok=True); Path('docs/notes.md').write_text('# Release notes\n\nSteadlith assigns content-defined identities to chunks.\nUnchanged chunk identities can reuse cached embeddings.\n\nThe index command publishes one SQLite snapshot after embedding succeeds.\n', encoding='utf-8')"

2. Preview the index¶

steadlith plan

The plan reports one added chunk and one required embedding, plus the target corpus root, cache hits, token estimate, and configured cost estimate. It does not write the cache or index and does not construct an embedding provider.

For automation:

steadlith plan --json

3. Build the index¶

steadlith index

The default provider computes deterministic lexical feature vectors locally. The index is published only after every required vector is available.

Run the same command again:

steadlith index

The second index run should contain only keep operations and require no new embeddings.

4. Query active content¶

steadlith query "cached embeddings"

The first result names docs/notes.md and includes a cosine score, offsets, and chunk text. The default hash provider works for matching words and short phrases. It does not infer that two different words have the same meaning.

To consume results in a program:

steadlith query --json -k 3 "cached embeddings"

5. Inspect and verify state¶

steadlith status
steadlith verify

status shows the committed corpus root, chunk counts, and embedding identity without reading configured sources; status --json also includes the generation and embedding-parameters hash. Run plan to compare current sources or embedding configuration with that committed state. verify checks the authoritative SQLite manifest and active index records, then compares the derived JSON manifest mirror with that SQLite state.

6. Make a small edit¶

Add a paragraph to docs/notes.md, then preview the delta:

steadlith plan

Review which chunk occurrences are added, kept, moved, or deleted. Apply the edit:

steadlith index --allow-delete

The deletion flag is required whenever old active occurrences will become tombstones. It protects against accidental partial source scopes and overly broad exclude rules.

Files created by the workflow¶

Back up the database and cache if they are expensive to reproduce. The cache and index contain derived information from source documents and may be sensitive.

Next steps¶

• Read Core model before using positional paths.

• Review every field in Configuration.

• Select a learned provider in Embedding providers.

• Use Indexing for deletion approvals and automation.