Getting Started

Who This Is For

Use this guide if you are applying RAGit to a project for the first time and want one canonical path from install to first verified ingest.

If you are developing RAGit itself inside this repository, start with Init Guide instead.

Requirements

Git repository
Node.js 22.14+
pnpm 10+
Linux: libaio (sudo apt-get install libaio-dev on Debian/Ubuntu)
A supported zvec bootstrap platform for local initialization: darwin/arm64 or linux/arm64

Node 24 is covered on both supported targets. Linux x64 and Windows x64 are not supported by the pinned zvec 0.2.1 runtime; unsupported targets fail before the native binding loads and report the supported matrix.

This guide targets RAGit 2.0.0. Upgrading from 1.1.2 raises the Node.js floor from 20.19.0 and narrows the evidence-backed native matrix to the two ARM64 targets above. Existing 1.1.2 stores are covered by the release reopen-and-query gate; back up .ragit before depending on a downgrade after new 2.0.0 writes.

Choose Your Install Path

Published CLI

Use the published CLI if you want the normal project onboarding path.

npm install -g ragit
# or
pnpm add -g ragit
# or
bun add -g ragit

Repository-Local Development

Use the repository-local script only if you are working on RAGit itself.

pnpm install
pnpm ragit --help

Happy Path

Install RAGit with the published CLI or your local repository checkout.
Initialize the repository.
Write or review the minimum document set for your project.
Commit the intended repository knowledge state.
Run a full ingest for that exact commit.
Verify the result with status and query.

ragit init
git add AGENTS.md docs .ragit/config.toml .gitignore
git commit -m "initialize ragit knowledge"
ragit ingest --all
ragit status --format json
ragit query "project goal" --format json

If you use the repository-local script while developing RAGit itself, replace ragit with pnpm ragit.

Review generated drafts before staging them. If the selected init policy ignores .ragit/config.toml, stage only the repository files that policy keeps trackable; do not force-add ignored runtime state.

RAGit binds searchable knowledge to commits. Apply-mode ingest rejects relevant modified, deleted, or untracked document candidates, and read commands continue to use the committed snapshot while warning that worktree changes are excluded.

Minimum Document Set

Start with the smallest set that lets the next agent understand the project:

One PRD
One SRS or SPEC
One ADR when you need to record a durable decision

Optional Next Step

After your first successful ingest, install managed hooks if you want incremental indexing to stay close to repository changes.

ragit hooks install

Completion Criteria

You are ready when:

status shows the repository is initialized and indexed
status.data.snapshot.status is indexed for the exact current HEAD
query returns relevant chunks and reports the same SHA in snapshotSha and snapshot.resolvedSha
your team can continue from the written docs without rereading the bootstrap steps

Once the first verification passes, choose retrieval by intent: use query for raw indexed hits, context pack for a bounded packet for the next agent step, and memory recall when you need to resume active work with working state.

If verification fails, use doctor before changing the workflow.

This workflow establishes commit-bound snapshot integrity, not complete production readiness. Exclusive ingest locking, crash recovery, retrieval evaluation, and distribution-matrix validation remain separate work.