vaultspec-rag

When search results look wrong

Copied from vaultspec-rag's own documentation, and read against the pages written here at commit 04610a5c. Nothing in it needed answering differently.

Before you copy these

Every command below is written bare, with no prefix, which is what the standalone and prebuilt-binary routes want. In a project, put uv run in front of vaultspec-rag; without installing, put uvx --from "vaultspec-rag[gpu]" there instead. Choose an install route sets out the four routes and which prefix each one needs.

Search reads the stored index. Start with an installed and provisioned workspace.

Examples use the installed-tool form and call vaultspec-rag directly. If vaultspec-rag is a project dependency, prefix each command with uv run; see the installation guide for lane selection, including the standalone tool and no-install routes.

Is the service healthy?

Command

vaultspec-rag server doctor

Inspect Live service, Installed dependencies, and, when present, Provisioning (vaultspec-rag).

• For dependency faults, follow the installation troubleshooting guide.

• For service faults, follow the service troubleshooting guide.

• For provisioning faults, read the reported detail.

If none of these checks reports a problem, check index status.

Check index status

Command

vaultspec-rag status

Counts describe stored sections, not source files, and don’t prove the index is current.

Under Index generations, each domain shows its latest recorded indexing job for this project. not indexed yet means no matching job was found in the retained history; it doesn’t establish that the store is empty. succeeded records that job’s success, not whether the index matches your current files.

To index the domains you need, follow reindexing. If expected files are missing, check file coverage.

Is it indexing the right files?

Preview which source files would be indexed without changing the index:

Command

vaultspec-rag index --type code --dry-run

Check that expected files appear and unwanted files stay out. The admission summary counts admitted and rejected files by reason.

By default, the preview displays up to 50 paths. Use --dry-run-limit N to change that limit, or add --json for the full admitted path list.

If file selection is wrong, review the admission rules and routing configuration. Repeat the preview after making changes.

Reindexing

To update the index after changing files or indexing settings:

Command

vaultspec-rag index

Scope it with --type vault, --type code, or --type document when only one kind has changed. To delete and rebuild a domain, pass both --type and --rebuild.

The running service reindexes as files change. See watcher operation for automatic updates.

Gating a script on these checks

See scripting and automation for JSON output and exit-code handling.

Related documentation

• Storage maintenance covers pruning what indexing leaves behind.

• Search and index covers the search and index commands in full.