feat: document setup, explain unwritable persist paths, add GPU offload

[n0nuser]

Four setup and performance friction points found while getting the stack running locally.

Setup was undocumented

CONTRIBUTING said "Install Task 3.x" with no link and no command, and nothing listed the other prerequisites. Adds a prerequisite table (Task, uv, Python 3.13+, Docker Compose v2, Ollama) with official install links, per-platform Task install commands, and a verification block. Cross-linked from README, AGENTS.md, and docs/agent-navigation.md, each noting Task is optional since every task maps to a plain uv run ….

Unwritable persist path gave an undiagnosable error

A persist directory owned by another user surfaced as SQLite's bare attempt to write a readonly database, naming neither the path nor the cause — and reaching the user wrapped in PluginExecutionError: Unable to create retriever plugin 'builtin', which hides it further.

Adds PersistPathError, raised from a single _connect helper covering both VectorStore.create and .open (the only two PersistentClient call sites) plus the mkdir path for an unwritable parent:

PersistPathError: Chroma persist path is not writable: /home/user/dev/LocalRAG/data/chroma
(owned by root:root, running as user:user). Fix ownership with:
sudo chown -R $(id -un):$(id -gn) /home/user/dev/LocalRAG/data/chroma
— or point CHROMA_PERSIST_PATH at a directory you own.

The remedy branches on cause — another user's directory needs chown, one with bad mode bits needs chmod. Suggesting the wrong one sends the reader down a dead end. Unrelated client errors re-raise untouched. README gains a Troubleshooting section covering this and the plugin wrapper.

chromadb healthcheck could never pass

The probe was CMD-SHELL "echo > /dev/tcp/localhost/8000", but /dev/tcp is a bash builtin and the image's /bin/sh is dash:

/bin/sh: 1: cannot create /dev/tcp/localhost/8000: Directory nonexistent

65 consecutive failures observed while Chroma was serving normally. This is more than cosmetic — other services gate on depends_on: condition: service_healthy. Switched to CMD with bash, which the image ships. Verified: STATUS=healthy failing=0 after recreate.

Ollama ran on CPU with no way to opt into a GPU

Embedding dominated ingest at ~4.7 chunks/s, flat across file sizes. Adds docker-compose.gpu.yml as an opt-in override, so the base stack keeps working on hosts without a GPU:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

Also corrects CONTRIBUTING, which claimed the Compose file already requested an NVIDIA GPU — it had no GPU block at all.

Verification

Measured end to end on an RTX 4070 Ti, deleting the localrag collection and re-ingesting through the GPU override:

	CPU	GPU
Rate	4.7 chunks/s	18.7 chunks/s
4193 chunks	~15 min	224 s

offloaded 13/13 layers to GPU on CUDA0 confirms the offload; 4193 vectors restored exactly, and a query returned correctly grounded answers with sources.

Gates: ruff, ruff format, mypy (100 files), and bandit all clean. 480 unit tests pass, 4 of them new (both remedy branches, unwritable parent, non-permission passthrough).

Note for reviewers

The unit suite reads a developer's real .env, so 26 tests fail locally whenever one exists (480 passed with it moved aside, 26 failed with it present). Pre-existing on main and unrelated to these changes — filed separately rather than widening this branch.

https://claude.ai/code/session_0159MZxHDCaAxhZB9V1ab8oJ