delfos 0.1.0__tar.gz

delfos-0.1.0/.devin/skills/llvm-cpp-toolchain/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: llvm-cpp-toolchain
+description: LLVM-based toolchain for debugging and profiling C++ code in this project. Covers sanitizers, profiling, optimization, and benchmarking — all Clang/LLVM, no GCC or Valgrind.
+---
+
+# C++ Debugging & Profiling Toolchain (LLVM)
+
+All debugging and performance work uses the LLVM/Clang toolchain exclusively.
+
+## Sanitizers (Debug/CI)
+
+| Sanitizer | Flag | Catches | Overhead |
+|---|---|---|---|
+| AddressSanitizer | `-fsanitize=address` | Buffer overflows, use-after-free, double-free, leaks | ~2x |
+| UndefinedBehaviorSanitizer | `-fsanitize=undefined` | Signed overflow, null deref, misaligned access | ~1.2x |
+| ThreadSanitizer | `-fsanitize=thread` | Data races, lock-order inversions | ~5–15x |
+| MemorySanitizer | `-fsanitize=memory` | Reads of uninitialized memory | ~3x |
+
+Always compile with `-fno-omit-frame-pointer -g` alongside sanitizers. ASan+UBSan should run in CI on every commit. TSan when concurrency is involved.
+
+## Profiling
+
+| Tool | Purpose | Usage |
+|---|---|---|
+| `perf record -g` + flamegraphs | Find where CPU time goes | `perf record -g --call-graph=fp ./binary && perf script \| flamegraph.pl > flame.svg` |
+| `llvm-xray` | Precise per-function instrumentation tracing | Compile with `-fxray-instrument`, run with `XRAY_OPTIONS="patch_premain=true xray_mode=xray-basic"`, analyze with `llvm-xray account` or convert to Perfetto/Chrome trace |
+| `perf stat` hw counters | Cache misses, branch mispredicts | `perf stat -e cache-misses,branch-misses,LLC-load-misses ./binary` |
+| MemProf | Allocation hot/cold analysis | Compile with `-fmemory-profile -gmlt`, merge with `llvm-profdata` |
+
+Build for profiling: `CMAKE_BUILD_TYPE=RelWithDebInfo` + `-fno-omit-frame-pointer`.
+
+## Optimization
+
+| Tool | What it does | When to use |
+|---|---|---|
+| PGO (`-fprofile-generate` / `-fprofile-use`) | Profile-guided code generation (10–20% gains) | Once code is stable, before release |
+| LTO (`-flto=thin`) | Link-time optimization across translation units | Always in release builds |
+| BOLT (`llvm-bolt`) | Post-link binary layout optimization (5–15% gains) | Final production binary |
+
+PGO workflow:
+```bash
+clang++ -fprofile-generate -O2 ...       # instrumented build
+./binary --workload                       # run representative workload
+llvm-profdata merge -o default.profdata *.profraw
+clang++ -fprofile-use=default.profdata -O3 -flto=thin ...  # optimized build
+```
+
+## Benchmarking
+
+Use [nanobench](https://github.com/martinus/nanobench) (single header). It reads perf counters directly and reports median, percentiles, instructions/op, branch misses/op, cache misses/op.
+
+```cpp
+#include <nanobench.h>
+
+ankerl::nanobench::Bench().run("name", [&] {
+    auto result = function_under_test();
+    ankerl::nanobench::doNotOptimizeAway(result);
+});
+```
+
+## CMake Presets
+
+```json
+{
+  "configurePresets": [
+    {
+      "name": "debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_CXX_COMPILER": "clang++",
+        "CMAKE_CXX_FLAGS": "-fsanitize=address,undefined -fno-omit-frame-pointer"
+      }
+    },
+    {
+      "name": "profile",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "CMAKE_CXX_COMPILER": "clang++",
+        "CMAKE_CXX_FLAGS": "-fno-omit-frame-pointer -fxray-instrument"
+      }
+    },
+    {
+      "name": "release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "CMAKE_CXX_COMPILER": "clang++",
+        "CMAKE_CXX_FLAGS": "-O3 -flto=thin -march=native"
+      }
+    }
+  ]
+}
+```
+
+## Workflow
+
+```
+1. Develop with ASan+UBSan (catch memory/UB bugs immediately)
+2. Write nanobench micro-benchmarks (establish baseline)
+3. perf → flamegraph (identify hotspots)
+4. llvm-xray → Perfetto (precise function-level timing)
+5. perf stat (validate cache/branch behavior)
+6. PGO + LTO (profile-guided release build)
+7. BOLT (final binary layout optimization)
+```

delfos-0.1.0/.env.example

@@ -0,0 +1,38 @@
+# Copy to .env at your repo root and edit. Real environment variables always
+# override these; this file is loaded explicitly at startup, anchored to the
+# repo being served/indexed (via --repo or DELFOS_REPO) — never by walking up
+# from wherever the process happens to be launched.
+#
+# llama.cpp note: one llama-server serves one model, so run TWO servers and
+# point the chat/embed base URLs at their separate ports:
+#   llama-server -m chat.gguf  --port 8080 --jinja
+#   llama-server -m embed.gguf --port 8081 --embedding --pooling mean
+# (--jinja enables the chat template; --embedding turns on /v1/embeddings.)
+
+# OpenAI-compatible endpoint for the hop planner (chat).
+# llama.cpp: http://localhost:8080/v1
+# Ollama:    http://localhost:11434/v1
+# LM Studio: http://localhost:1234/v1
+DELFOS_LLM_BASE_URL=http://localhost:8080/v1
+
+# Chat model that supports JSON-schema structured outputs.
+# llama.cpp ignores this value (it serves the loaded model); set anything.
+DELFOS_LLM_MODEL=local-chat
+
+# Local servers ignore the value, but the client requires one.
+DELFOS_LLM_API_KEY=local
+
+# Embedding endpoint for semantic seeds. With llama.cpp this is a SEPARATE
+# server/port from the chat one — set it explicitly; there is no automatic
+# fallback to DELFOS_LLM_BASE_URL.
+DELFOS_EMBED_BASE_URL=http://localhost:8081/v1
+
+# Local embedding model and its output dimension (must match the model).
+# nomic-embed-text -> 768. Set DELFOS_EMBED_DIM to your model's dimension.
+DELFOS_EMBED_MODEL=local-embed
+DELFOS_EMBED_DIM=768
+
+# API key for the embedding endpoint. Local servers usually ignore the value,
+# but a string is still required. Required (no local server) when
+# DELFOS_EMBED_BASE_URL is unset — you're targeting the real OpenAI API.
+DELFOS_EMBED_API_KEY=local

delfos-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install dependencies
+        # Lint/type-check never import the compiled _delfos extension (a
+        # checked-in delfos/_delfos.pyi stub covers pyright), so skip building
+        # and installing the project itself — it's the slowest part of `uv sync`.
+        run: uv sync --no-install-project
+      - name: Ruff lint
+        # --no-sync: `uv run` auto-syncs (and would rebuild the project) otherwise.
+        run: uv run --no-sync ruff check .
+      - name: Ruff format check
+        run: uv run --no-sync ruff format --check .
+      - name: Pyright
+        run: uv run --no-sync pyright
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      FC_CACHE_DIR: ${{ github.workspace }}/.fc-cache
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Cache CMake FetchContent sources
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.FC_CACHE_DIR }}
+          key: fc-deps-${{ matrix.os }}-${{ hashFiles('CMakeLists.txt') }}
+          restore-keys: |
+            fc-deps-${{ matrix.os }}-
+      - name: Install dependencies
+        # The project itself gets built by the editable install below, so
+        # skip building it here to avoid compiling the C++ extension twice.
+        run: uv sync --no-install-project
+      - name: Build and install extension (editable)
+        run: >
+          uv pip install -e .
+          --config-settings=cmake.define.FETCHCONTENT_BASE_DIR=${{ env.FC_CACHE_DIR }}
+      - name: Pytest
+        # --no-sync: `uv run` auto-syncs (and would rebuild the project) otherwise.
+        run: uv run --no-sync pytest
+      - name: CMake configure (debug, ASan+UBSan)
+        run: cmake --preset debug -DFETCHCONTENT_BASE_DIR=${{ env.FC_CACHE_DIR }}
+      - name: CMake build
+        run: cmake --build build/debug
+      - name: Ctest
+        run: ctest --test-dir build/debug --output-on-failure

delfos-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  validate-tag:
+    name: Validate release tag
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check tag matches vMAJOR.MINOR.PATCH
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Tag '$TAG' does not match the required vMAJOR.MINOR.PATCH format (optionally with a -prerelease and/or +build suffix)"
+            exit 1
+          fi
+
+  build-wheels:
+    name: Build wheels on ${{ matrix.os }}
+    needs: [validate-tag]
+    if: always() && (needs.validate-tag.result == 'success' || needs.validate-tag.result == 'skipped')
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # setuptools_scm needs full history + tags
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v4.1.0
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build-sdist:
+    name: Build source distribution
+    needs: [validate-tag]
+    if: always() && (needs.validate-tag.result == 'success' || needs.validate-tag.result == 'skipped')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # setuptools_scm needs full history + tags
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

delfos-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# uv
+.uv/
+
+# Tooling caches
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.pytest_cache/
+
+# Databases / local artifacts
+*.duckdb
+*.duckdb.wal
+*.sqlite
+*.sqlite3
+*.db
+
+# Per-repo Delfos workspace (graph store, SCIP index, manifest — all regenerated)
+.delfos/
+
+# Legacy generated SCIP index location (pre-workspace)
+index.scip
+
+# Local env / secrets
+.env
+.env.local
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

delfos-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

delfos-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+Delfos is a graph-memory **MCP server** for codebases, with a full CLI. The
+`delfos` package provides the schema (`delfos.schema`), the graph store
+(`delfos.store` — `NativeGraphStore` over the C++ `delfos._delfos` nanobind
+extension; the earlier DuckDB store has been removed), the indexer
+(`delfos.indexer`), the read path (`delfos.reconstruct`), SCIP cross-references
+(`delfos.scip`), the FastMCP server (`delfos.mcp`), and the `delfos` CLI
+(`delfos.cli`). See `ARCHITECTURE.md` for the overview and `docs/decisions.md`
+for the rationale.
+
+### Tooling
+- Project is managed by `uv` (see `README.md`/`CLAUDE.md` for the standard
+  commands). The cloud VM installs `uv` to `~/.local/bin`; it is added to PATH via
+  `~/.bashrc`, so interactive shells have it. The startup update script runs
+  `uv sync`.
+- `uv pip install -e .` builds and installs the `_delfos` C++ extension (build
+  isolation pulls scikit-build-core + nanobind).
+- Standard commands (already documented in `CLAUDE.md`): `uv run ruff check .`,
+  `uv run ruff format --check .`, `uv run pyright` (strict mode), `uv run pytest`.
+
+### C++ toolchain (for `libdelfos`, see `CMakePresets.json` and `CLAUDE.md`)
+The cloud VM has the toolchain preinstalled: `clang++` 18
+(LLVM; the build standardizes on clang, not GCC), `cmake` 3.28, `ninja`, and the
+clang sanitizer runtimes (ASan/UBSan via `libclang-rt-18-dev`).
+`CMakePresets.json` uses the Ninja generator with `clang++`. Build/test commands
+are in `CLAUDE.md` (`cmake --preset debug`, `cmake --build build/debug`, etc.).
+
+Non-obvious gotchas:
+- `clang++` auto-selects the **GCC 14** libstdc++ install (highest version
+  present), so `libstdc++-14-dev` must be installed — not just `libstdc++-13-dev`.
+  Both are installed here; without the 14 dev package, links fail with
+  `cannot find -lstdc++` and `<span>`/`<cstdint>` headers are not found.
+- All external C++ deps (USearch, FlatBuffers, nanobind, Catch2, nanobench) are
+  pulled via CMake `FetchContent` at **configure time** — the first configure
+  needs network access to GitHub and is slower while it clones/builds them.
+
+### Running it end-to-end
+- Entry points: the `delfos` CLI (`index`, `status`, `doctor`, `search`,
+  `reconstruct`, `serve`) and `delfos-mcp` (the MCP read server over stdio).
+  Every command anchors on a repo's `.delfos/` workspace (`--repo`, default:
+  the current directory), which holds the store snapshot, `index.scip`,
+  `manifest.json`, and optional `config.toml`.
+- Configuration is via `DELFOS_*` env variables (precedence and full table in
+  `README.md`). Defaults: `nomic-embed-text`, dim 768. Point
+  `DELFOS_EMBED_BASE_URL` at any OpenAI-compatible endpoint, or leave it unset
+  for OpenAI-hosted (then `DELFOS_EMBED_API_KEY` is required). Queries against
+  an already-indexed repo read the model/dim from the manifest and need only
+  credentials.
+- For offline/deterministic runs, drive the library directly: supply any object
+  satisfying the `Embedder` protocol (`delfos.indexer.embedder.Embedder`) — a
+  deterministic hash embedder is enough to index, search, and traverse without
+  network access (this is what the tests do, along with a `FakeHopPlanner`).
+  The store's `embedding_dim`/`embedding_model` must match the embedder's, or
+  writes are rejected.

delfos-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,220 @@
+# Architecture
+
+This document is the orientation pass for contributors: what Delfos is built
+around, how the pieces fit, and which invariants hold the whole thing together.
+It is deliberately not exhaustive — the *why* behind each decision lives in
+[`docs/decisions.md`](docs/decisions.md), and the module docstrings are the
+source of truth for details. Read this first, then go where your change takes
+you.
+
+## The one idea everything serves
+
+Delfos implements the active *reconstruction* model from ["Memory is
+Reconstructed, Not Retrieved: Graph Memory for LLM Agents"](https://arxiv.org/abs/2606.06036)
+(arXiv 2606.06036) over a code repository, and exposes it as an MCP server.
+
+The premise: an agent looking for relevant code shouldn't get one shot at a
+similarity search. It should *walk* — start from a semantic entry point, look at
+the neighbors, decide what to keep, descend into the most promising branch,
+backtrack when a path dries up. Memory as an iterative, reasoning-driven
+traversal of a persistent graph, not a top-k lookup.
+
+Every layer of this codebase is shaped by that premise. If a change makes the
+walk less legible, less cheap, or less deterministic where it should be
+deterministic, it's probably fighting the architecture.
+
+## The graph: Cue → Tag → Content
+
+Three node types, defined as Pydantic models in `delfos/schema/`:
+
+- **`CueNode`** — the entry points agents query by: function names, concept
+  strings, error messages. These are the *only* nodes that carry embeddings and
+  the only ones reachable by vector search.
+- **`TagNode`** — categorical bridges (`MODULE_PATH`, `ARCH_LAYER`,
+  `PATTERN_TYPE`, `LANG_CONSTRUCT`, `LANGUAGE`). Filtered by category, never
+  embedded. Shared across files.
+- **`ContentNode`** — the payload: functions, classes, modules, commits, tests.
+  What actually gets returned to the agent.
+
+Edges are directional and typed: `CUE_OF`, `TAGGED_WITH`, `PART_OF_TOPIC`,
+`REDIRECTS_TO`.
+
+The separation is the point. Keeping cues (small, embedded, searchable) apart
+from content (rich, returned, never embedded) keeps the vector index tiny and
+the payloads unconstrained, and tags give the walk cheap categorical filtering
+without more embeddings.
+
+## Two layers, one boundary
+
+The codebase is Python orchestration over a C++ storage engine, and they meet
+at exactly one seam: the `GraphStore` abstract base class
+(`delfos/store/base.py`).
+
+```
+  indexer      mcp server      reconstruct      cli
+      \             |               |            /
+       \            |               |           /
+        +---------- GraphStore (ABC) ----------+     ← the only boundary
+                         |
+                 NativeGraphStore
+                         |
+                 delfos._delfos (nanobind)
+                         |
+                    libdelfos (C++)
+```
+
+**No component ever touches the C++ engine directly.** Not the indexer, not the
+MCP tools, not the CLI. Everything codes against `GraphStore`;
+`NativeGraphStore` (`delfos/store/native_store.py`) is the concrete backend.
+This seam is what made it possible to delete the earlier DuckDB backend without
+touching anything above it — keep it that way.
+
+### The engine: `libdelfos/`
+
+Header-only C++ under `libdelfos/include/delfos/`:
+
+- **`graph.hpp`** — an in-memory CSR directed property graph: O(1) ID lookup,
+  cache-friendly adjacency.
+- **`vector_index.hpp`** — HNSW cosine similarity over USearch; <1ms for
+  50K × dim=1536 k=5 queries.
+- **`snapshot.hpp`** — persistence via FlatBuffers + USearch's native format,
+  with atomic rename for crash safety.
+
+`libdelfos/bindings/py_delfos.cpp` exposes `Store` and `NodeData` to Python as
+the `delfos._delfos` extension. It has its own tests (`libdelfos/tests/`,
+Catch2, built with ASan+UBSan in the debug preset) and a nanobench benchmark
+(`libdelfos/bench/`).
+
+## The write path: indexing
+
+`delfos/indexer/` turns a repository into the graph. Four modules, in pipeline
+order:
+
+1. **`parser.py`** — tree-sitter parse of Python source into a `ParsedModule`
+   IR. Error-tolerant: files with syntax errors are parsed partially instead of
+   raising.
+2. **`extractor.py`** — the pure, side-effect-free heart: `ParsedModule` in,
+   nodes and edges out. No I/O, no embedding, no persistence. Per file it emits
+   one module `ContentNode`, one `ContentNode` per definition, `CueNode`s for
+   symbols and raised error messages, and shared `TagNode`s.
+3. **`embedder.py`** — attaches vectors to cue nodes via an OpenAI-compatible
+   endpoint.
+4. **`pipeline.py`** — the `Indexer` that ties it together and owns all the
+   transactional discipline (below).
+
+The crash-recovery model is simple and strict: **one file per transaction**.
+For each file the pipeline computes the git blob SHA, skips it if the checkpoint
+manifest already has that SHA, and otherwise deletes the file's prior
+nodes/edges and writes the new ones — embeddings included — inside a single
+transaction, together with the manifest entry. A crash mid-file leaves the store
+untouched and the file is retried on the next run. Staleness handling is
+**delete-and-reindex**: no symbol-level diffing, no tombstones, no rename
+detection in v1.
+
+Everything a run produces lands in one self-describing directory per repo, the
+`.delfos/` workspace (`delfos/workspace.py`):
+
+```
+<repo>/.delfos/
+├── store/          # NativeGraphStore snapshot (graph + vectors)
+├── index.scip      # SCIP cross-reference index
+├── manifest.json   # provenance + consistency metadata
+└── config.toml     # optional non-secret config
+```
+
+The manifest records which run produced the graph and the SCIP index (so
+inconsistency is detectable) and the embedding model/dimension the index was
+built with (so queries don't need to re-specify them).
+
+## The read path: reconstruction
+
+`delfos/reconstruct/` is the read-path service, sitting entirely on
+`GraphStore`. The split that matters:
+
+- **Three pure primitives** — `search` (vector search over cues),
+  `traverse_forward` (cues → content, with tag filters), `traverse_reverse`
+  (content → cues). Deterministic graph operations, independently testable,
+  no LLM anywhere near them.
+- **One LLM-in-the-loop operation** — `reconstruct`, the depth-first walk. At
+  each hop a `HopPlanner` (`planner.py`, a Protocol) sees compact
+  `CandidateSummary`s of the neighbors and decides what to collect and which
+  *single* neighbor to descend into. `budget` is a hard ceiling on planner
+  calls (backtracking spends it too). `summaries.py` is the single place that
+  decides how much of a node the LLM sees.
+
+All non-determinism and all token cost are confined to `reconstruct`. Tests
+inject `FakeHopPlanner` and a fake embedder, so the whole layer runs offline.
+
+### The MCP server: the calling agent *is* the planner
+
+Here's the twist worth understanding before touching `delfos/mcp/`: the MCP
+server does **not** run a server-side planner LLM. The agent issuing the tool
+calls (Claude Code, Cursor, …) is already an LLM capable of per-hop reasoning —
+so the server exposes the *primitives* (`search`, `traverse_forward`,
+`traverse_reverse`, `fetch`) plus a *prompt* that teaches the walk discipline
+(seed → expand → descend one → respect budget → stop). The in-tree
+`reconstruct` engine and its planners remain as an internal engine used by the
+CLI, tests, and the smoke harness; they are not MCP tools.
+
+Returns are tiered, following the MCP search+fetch convention: walk tools
+return compact `NodeSummary`s, and a separate `fetch` returns full
+`ContentDetail` bodies for the agent's final picks. Embeddings are never
+serialized back to the agent. The MCP view models live in `mcp/views.py`,
+deliberately separate from the planner's `CandidateSummary` so the tool surface
+and the planner contract can evolve independently.
+
+### SCIP cross-references
+
+`delfos/scip/` adds precise code navigation next to the semantic graph: at
+index time, `scip-python` generates `index.scip`; at read time, `ScipService`
+resolves a `ContentNode` to its references, implementations, and type
+definitions. The trick that keeps this cheap: content node IDs *are* SCIP
+symbol strings when SCIP coverage exists, so lookup is a direct key access with
+no foreign-key indirection. The MCP server exposes these as three more tools
+(`references`, `implementations`, `type_definition`).
+
+## Entry points and wiring
+
+- **`delfos/cli/`** — the `delfos` command: `index`, `status`, `doctor`,
+  `search`, `reconstruct`, `serve`. Every command anchors on a repo's
+  `.delfos/` workspace.
+- **`delfos/mcp/`** — the FastMCP read server (`delfos-mcp` / `delfos serve`).
+  Tool logic lives in plain `_`-prefixed functions so it's unit-testable
+  without an MCP transport; `build_server` registers thin wrappers.
+- **`delfos/config.py`** — env-driven startup configuration (`DELFOS_*`
+  variables; precedence documented in the README). This is also where the
+  embedding-model startup check lives.
+
+## Invariants — the short list
+
+Break one of these and things fail in ways that are hard to see:
+
+1. **Everything goes through `GraphStore`.** No reaching past the seam into
+   `delfos._delfos`.
+2. **Cue and content nodes always carry `source_file` + `git_sha`.**
+   Provenance is what makes delete-and-reindex possible. Tags are the
+   deliberate exception — they are shared across files and carry no
+   provenance; a re-index drops the file-scoped edges, not the tags.
+3. **One file per transaction**, manifest entry included. This is the entire
+   crash-recovery story.
+4. **One embedding model per store.** `NativeGraphStore` is constructed with
+   an `embedding_model` and rejects nodes whose model differs; the server
+   fail-fasts at startup if the query-time embedder doesn't match the index.
+   A mismatch here doesn't error at query time — it silently returns garbage,
+   which is why it's caught at the door.
+5. **Primitives stay pure.** LLM calls belong only in `reconstruct` (or in the
+   calling agent, in the MCP case).
+6. **Pyright strict mode and `extra="forbid"` on every Pydantic model** are
+   non-negotiable. Schema drift and untyped code surface immediately, by
+   design.
+
+## Where to go next
+
+- [`docs/decisions.md`](docs/decisions.md) — the decision log: what was chosen,
+  why, and what was explicitly ruled out.
+- [`README.md`](README.md) — setup, configuration, and build commands.
+- The module docstrings — each pipeline stage and service opens with a
+  docstring stating its contract; they are kept accurate and are the fastest
+  way to understand a module before editing it.
+- `tests/` mirrors the package layout; the reconstruct tests
+  (`tests/reconstruct/`) are the best executable walkthrough of the read path.