DocNeedle

Local-first deterministic doc lookup/update prototype using SQLite FTS5.

DocNeedle has two separate modes of use:

1. Normal CLI usage: index a markdown tree, search it, read a chunk, run stale-term checks.
2. Benchmark usage: run the repo's evaluation scripts against a real corpus and task set.

Do not mix them. The benchmark scripts are repo-specific evaluation harnesses, not the normal way to use the tool.

Requirements

• Python 3.11+
• SQLite with FTS5 support
• uv recommended for environment setup
• rg required only for the benchmark baselines

Setup

Create a local virtualenv and install the repo in editable mode:

uv venv
source .venv/bin/activate
uv pip install -e . pytest

Quick verification:

python -m docneedle.cli --help
python -m pytest -q

Normal CLI usage

This is the main product surface.

1) Build or refresh an index

python -m docneedle.cli index \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --changed-only \
  --json

Notes:

• --root is the markdown corpus root.
• --db is the SQLite database DocNeedle will create/update.
• --changed-only does incremental refresh instead of full rebuild.

2) Search

python -m docneedle.cli search \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --query "home action center doc index router" \
  --limit 8 \
  --json

Optional:

• --feature <name> filters search results to one feature.

3) Read a result chunk

Take a chunk_id from search output, then:

python -m docneedle.cli read \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --chunk-id <chunk-id> \
  --json

4) Run a stale/conflict check

python -m docneedle.cli check \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --topic "weight logging" \
  --terms '["weight check-in", "ranked steps recommendation"]' \
  --json

CLI commands

• index: parse markdown and write chunk/file metadata into SQLite.
• search: retrieve ranked chunk candidates for a query.
• read: fetch one chunk payload by chunk_id.
• check: scan for stale/conflicting phrases for a topic.

Benchmark setup

Use this only if you want to reproduce the repo's evaluation runs.

Current benchmark scripts are under:

• benchmarks/real-doc/run_real_doc_benchmark.py
• benchmarks/holdout-doc/run_holdout_doc_benchmark.py
• benchmarks/dev-broad-doc/run_dev_broad_doc_benchmark.py

These scripts are not generic. They currently hardcode:

• a real docs root (ROOT)
• the expected repo/worktree location (WORK_ROOT)
• temp DB paths
• report output paths
• task JSON locations for some benchmark sets

Before running them on another machine or corpus, patch those constants near the top of each script.

Minimum benchmark prerequisites:

• repo installed in a venv
• target markdown corpus exists locally
• rg installed
• write access to the configured artifact/report paths

Benchmark usage

Real-doc benchmark

python benchmarks/real-doc/run_real_doc_benchmark.py

Produces artifacts in benchmarks/real-doc/ and writes a markdown report to the configured REPORT_PATH inside the script.

Holdout benchmark

python benchmarks/holdout-doc/run_holdout_doc_benchmark.py

Uses benchmarks/holdout-doc/holdout_tasks.json and writes summary artifacts to benchmarks/holdout-doc/ plus the configured report path.

Broad dev benchmark

python benchmarks/dev-broad-doc/run_dev_broad_doc_benchmark.py

Uses benchmarks/dev-broad-doc/dev_tasks.json, compares against the configured holdout task file, and writes artifacts/report to the paths configured in the script.

When to use which path

Use normal CLI usage when you want to:

• index your own docs
• answer a query
• inspect one result chunk
• detect stale terms/conflicts

Use benchmark scripts when you want to:

• measure retrieval quality on a fixed task set
• compare DocNeedle against rg baselines
• generate evaluation reports
• detect regressions after ranking/parser changes

Current MVP limitations

• No LLM or remote API is used for indexing or retrieval.
• Index data lives in SQLite with FTS5.
• Patch mechanics are scaffolded but not exposed as a CLI command in this MVP slice.
• Benchmark scripts are still author-environment-oriented and need constant/path cleanup before they become portable.