diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f0c9261
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Purpose
+
+Private learning tool. Ingest study materials → build a knowledge graph → query concepts → export flashcards to Anki.
+
+Two systems:
+- **LightRAG** (`lightrag/` submodule) — graph-based RAG server. Ingests documents, builds a knowledge graph, answers queries. Primary interface.
+- **Graphiti** (`graphiti/` submodule) — temporal knowledge graph library. Tracks *when* concepts were learned and how understanding evolves. Used as a Python library, not a server.
+
+Both run fully local via Ollama. No cloud dependencies.
+
+## Running Things
+
+**Always enter via `nix develop` from the repo root — never activate the venv directly.** The shellHook sources `.env.lightrag` / `.env.graphiti` and sets `LD_LIBRARY_PATH` needed for native wheels on NixOS.
+
+```sh
+# LightRAG server (API + WebUI)
+nix develop .#lightrag
+lightrag-server
+# → http://localhost:9621/webui  (React frontend)
+# → http://localhost:9621/docs   (Swagger API)
+
+# Graphiti (library, no server)
+nix run .#neo4j-start   # required first, separate terminal
+nix develop .#graphiti
+
+# Neo4j management
+nix run .#neo4j-start
+nix run .#neo4j-stop
+```
+
+## Current Models (Ollama)
+
+| Role | Model | Dim |
+|------|-------|-----|
+| LLM | `qwen3:0.6b` | — |
+| Embeddings | `qwen3-embedding:0.6b` | 1024 |
+
+**Critical:** if the embedding model or `EMBEDDING_DIM` changes, `rag_storage/` must be deleted before restarting — old vectors are incompatible.
+
+## Configuration
+
+`.env.lightrag` is sourced by the shellHook and read by `lightrag-server` at startup. **Changes require a server restart** — the server does not hot-reload env vars.
+
+Key vars:
+- `LLM_MODEL` / `EMBEDDING_MODEL` — Ollama model tags
+- `EMBEDDING_DIM` — must exactly match what the embedding model outputs (verify with `curl -s http://localhost:11434/api/embed -d '{"model":"<name>","input":"test"}' | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['embeddings'][0]))"`)
+- `EMBEDDING_TIMEOUT` / `TIMEOUT` — in seconds; worker execution timeout is `2× EMBEDDING_TIMEOUT`
+- `RAG_DIR` — resolved relative to where `lightrag-server` is invoked (inside `lightrag/` subdir due to shellHook `cd`)
+
+## Infrastructure Notes
+
+### Nix / NixOS
+- Impure devShells: Nix provides Python 3.12 + uv; `uv sync` installs PyPI deps into `lightrag/.venv` or `graphiti/.venv` at shell entry.
+- `LD_LIBRARY_PATH` is set in shellHook for `libstdc++.so.6` — required for numpy and other native wheels on NixOS.
+- `UV_PYTHON` is pinned to the nix-provided Python 3.12 binary to prevent uv from picking up the system Python (3.14 on this machine).
+- LightRAG installs with `--extra api --extra offline-llm` (the `ollama` Python package lives in `offline-llm`, not `api`).
+- WebUI (React/Bun) is built on first shell entry if `lightrag/lightrag/api/webui/` doesn't exist.
+
+### Ollama
+- Configured in `~/nix-config/machines/n1n1/services/ollama.nix`
+- Uses `pkgs.ollama-rocm` (AMD ROCm) — iGPU is detected and used by default
+- `OLLAMA_NUM_GPU=0` is set in NixOS config to force CPU-only mode (iGPU was consuming shared RAM)
+- Ollama CORS origin includes `http://127.0.0.1:8080` (open-webui) and `https://ollama.jibai.dev`
+
+### LightRAG Storage
+File-based by default (`JsonKVStorage`, `NanoVectorDBStorage`, `NetworkXStorage`). All data lives in `rag_storage/` (gitignored). Safe to delete entirely to reset.
+
+## Known Issues / Active Debugging
+
+**LightRAG pipeline getting stuck**: After a server restart following config changes, the pipeline shows `busy: true` with pending async locks but doesn't process documents. Symptoms:
+- `GET /documents/pipeline_status` returns `busy: true`, `request_pending: true`
+- `keyed_locks.pending_async_cleanup` > 0
+- New inserts stay at `status: pending` indefinitely
+- `POST /documents/cancel_pipeline` may be needed to unblock
+
+The root cause is not yet determined. Suspicion: stale lock state inherited from previous failed runs persisted in `rag_storage/` JSON files. Try deleting `rag_storage/` and restarting the server fresh.
diff --git a/flake.nix b/flake.nix
index e9ba7ae..c4f7545 100644
--- a/flake.nix
+++ b/flake.nix
@@ -53,18 +53,14 @@
             export UV_PROJECT_ENVIRONMENT="$VIRTUAL_ENV"
             export UV_PYTHON="${pkgs.python312}/bin/python3.12"
             export LD_LIBRARY_PATH="${pkgs.lib.makeLibraryPath [ pkgs.stdenv.cc.cc pkgs.zlib ]}:$LD_LIBRARY_PATH"
-            cd "$RAGS_ROOT/lightrag"
 
             echo "Syncing lightrag venv..."
-            uv sync --extra api --extra offline-llm --quiet
-            source .venv/bin/activate
+            (cd "$RAGS_ROOT/lightrag" && uv sync --extra api --extra offline-llm --quiet)
+            source "$RAGS_ROOT/lightrag/.venv/bin/activate"
 
-            if [ ! -d lightrag/api/webui ]; then
+            if [ ! -d "$RAGS_ROOT/lightrag/lightrag/api/webui" ]; then
               echo "Building frontend (first time, ~1min)..."
-              cd lightrag_webui
-              bun install --frozen-lockfile --silent
-              bun run build:bun
-              cd ..
+              (cd "$RAGS_ROOT/lightrag/lightrag_webui" && bun install --frozen-lockfile --silent && bun run build:bun)
             fi
 
             if [ -f "$RAGS_ROOT/.env.lightrag" ]; then