ragx-cli 0.9.0__tar.gz → 0.11.0__tar.gz

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `ragx-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.11.0] — 2026-10-28
+
+### Changed
+
+- Discovery now honors every `.gitignore` in the corpus tree, not only the root one. Git
+  precedence applies: the deepest `.gitignore` with a matching pattern decides, so a subdirectory
+  can re-include (`!pattern`) what the root ignores; anchored patterns (`/foo.md`) resolve
+  relative to the directory holding the `.gitignore`; ignored directories are pruned, so a
+  negation can't re-include a file under them. Patterns are parsed with
+  `pathspec.GitIgnoreSpec`. An incremental `ragx-cli index` drops already-indexed files that a
+  nested `.gitignore` now excludes.
+
+## [0.10.0] — 2026-10-21
+
+### Added
+
+- `ragx-cli index --edges-only` — rebuilds sub-chunks, graph edges and communities from the
+  stored chunks per the current `[graph]` config, without re-chunking or re-embedding files.
+  Lets an existing index switch `graph.edge_source` (or `subchunk_size_tokens`) cheaply: chunk
+  embeddings and the vector index are kept; a chunk that stays whole reuses its own stored
+  vector, so only the sub-chunk pieces a split chunk actually produces go through the embedder.
+  Mutually exclusive with `--full`/`--changed`. The incremental-index manifest mismatch message
+  for `edge_source`/`subchunk_size_tokens` now also suggests `--edges-only`.
+
+### Changed
+
+- `ragx-cli web` no longer requires an index built with `graph.edge_source = "subchunk"`: it
+  renders whatever edges the index has — sub-chunk similarity when the index has them, otherwise
+  the stored whole-chunk cosine edges. An index with zero edges renders as a node-only cloud.
+
+### Fixed
+
+- `ragx-cli web` layout: ForceAtlas2 now uses edge weights (`edgeWeightInfluence = 1`), so more
+  similar chunks sit closer together. Before, every edge pulled equally.
+
 ## [0.9.0] — 2026-10-21
 
 ### Added

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/CLAUDE.md

@@ -55,7 +55,7 @@ src/ragx/
     models.py      #   Chunk, ChunkDraft, FileRecord, Edge, ScoredChunk, QueryOutput
     store.py       #   SQLite: files/chunks/edges/meta; replace_edges normalizes src<dst
     vectors.py     #   hnswlib wrapper; soft-delete via JSON sidecar; get_vectors for graph
-    discovery.py   #   file walk, root-level .gitignore, binary/size/junk-dir filters, xxh64
+    discovery.py   #   file walk, nested .gitignore (git precedence), binary/size/junk-dir filters, xxh64
     chunking.py    #   markdown/code/recursive splitters; byte-exact slices; tiny-fragment merge;
                    #   subchunk_texts (sentence-aligned windows for subchunk edge mode)
     graph.py       #   knn_edges + subchunk_knn_edges (max over sub-chunk pairs, near-dup guard)
@@ -73,8 +73,10 @@ src/ragx/
     catalog.py     #   curated embedding/reranker catalog (tiers, prefixes) + spec detect
     lmstudio.py    #   `lms` CLI wrapper: find/download (`lms get --yes`)/`lms ls --json`;
                    #   LM Studio can't download plain safetensors — rerankers stay on HF
-    graph_export.py #  build_graph: ragx.graph.v1 payload for `web`; fails loud unless the
-                   #   index's stored edge_source is "subchunk" (see Flows)
+    graph_export.py #  build_graph: ragx.graph.v1 payload for `web`; renders whatever edges the
+                   #   index has, subchunk or chunk-mode cosine (see Flows)
+    reedge.py      #   rebuild_edges: `index --edges-only` — rebuilds sub-chunks/edges/
+                   #   communities from stored chunks, no re-chunk/re-embed (see Flows)
   providers/       # base.py protocols (Embedder/Generator/Reranker); openai_compat.py;
                    # st_reranker.py; lmstudio_process.py (LM Studio autostart);
                    # llama_process.py (managed llama-server lifecycle) +
@@ -88,13 +90,13 @@ src/ragx/
                    # handlers.py (routing), query_runner.py (lazy providers, lock-serialized
                    # queries), static_files.py (path-traversal-safe static serving);
                    # static/ (frontend-owned: index.html, JS/CSS, vendored sigma.js)
-tests/             # 295 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
+tests/             # 305 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
 ```
 
 ## Flows
 
 **Index** (`ragx-cli index`): discover files (include/exclude globs — defaults in
-`core/corpus_globs.py`: source + text docs, minus lockfiles/requirements/build output — root .gitignore,
+`core/corpus_globs.py`: source + text docs, minus lockfiles/requirements/build output — every .gitignore in the tree (deeper overrides shallower, ignored dirs pruned),
 skip node_modules/.venv/hidden/binaries/>2MB) → xxhash diff (incremental by default since 0.8.0;
 `--full` rebuilds everything; `--changed` is a deprecated no-op alias for the default) → chunk
 (~800 tok target, chunks are exact byte slices, sub-100-char fragments
@@ -108,8 +110,10 @@ max cos over sub-chunk pairs; edges with whole-chunk cos ≥ `graph.near_dup_sim
 Query side untouched. In subchunk mode `graph.k` means links per SUB-chunk (no per-chunk cap —
 edge budget scales with concept count; graph gets ~1.4x denser at the 256-tok default). The
 manifest guards `edge_source`/`subchunk_size_tokens` like the embedding model — an incremental
-`index` after a flip fails loud, naming the old/new value; `index --full` rebuilds, or pin the
-old value in `ragx.toml`. Rationale + literature: `research/fine-grained-sub-chunk-edges-*.md`.
+`index` after a flip fails loud, naming the old/new value; `index --edges-only` (`core/reedge.py`)
+rebuilds just sub-chunks/edges/communities from the stored chunks — no re-chunk/re-embed, reusing
+each whole chunk's stored vector — or `index --full` rebuilds everything, or pin the old value in
+`ragx.toml`. Rationale + literature: `research/fine-grained-sub-chunk-edges-*.md`.
 MEASURED 2026-07-12 (`.lab` experiments #10–#11): on the scoped notes eval corpus the dense
 concept graph at hops2 TIES the tuned chunk-graph baseline (r@10 .923 / MRR .718 vs .717) at
 ~4.5x index embed cost (128-tok sub-chunks) — no win because the corpus's short single-topic
@@ -144,9 +148,9 @@ Each result chunk also carries grep-style `-B`/`-A`/`-C` context lines (`core/co
 reads since no text is shown.
 
 **Web** (`ragx-cli web`): builds the `ragx.graph.v1` payload once at startup (`graph_export.py`
-— requires the index's stored `edge_source` to be `"subchunk"`, fails loud otherwise) and serves
-it plus `/api/chunk/{id}` and `/api/query` (same pipeline as `query`, providers built lazily and
-cached, one query at a time behind a lock) over stdlib `http.server`.
+— renders the index's stored edges, sub-chunk or chunk-mode cosine; fails loud only when no
+index exists) and serves it plus `/api/chunk/{id}` and `/api/query` (same pipeline as `query`,
+providers built lazily and cached, one query at a time behind a lock) over stdlib `http.server`.
 
 ## State & benchmarks (as of 2026-07-10)
 
@@ -201,7 +205,7 @@ mostly on Dutch/multilingual queries. Details: `research/bge-m3-dense-q8-vs-nomi
 
 ## Dev loop
 
-`uv sync --group dev --extra rerank` · `uv run pytest -q` (295 pass, ~7 s) ·
+`uv sync --group dev --extra rerank` · `uv run pytest -q` (304 pass + 1 skipped, ~13 s) ·
 `uv run ruff check src tests` · file soft cap ~150 lines · expected failures raise `RagxError`
 (CLI maps to exit 2). Live smoke: LM Studio must be running with the configured embedding model.
 Changes that impact usage (CLI flags, config keys/precedence, output schemas, install steps)

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ragx-cli
-Version: 0.9.0
+Version: 0.11.0
 Summary: Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it
 Project-URL: Repository, https://github.com/alber70g/ragx-cli
 Project-URL: Issues, https://github.com/alber70g/ragx-cli/issues
@@ -52,6 +52,7 @@ ragx-cli init                  # create ragx.toml next to your corpus (interacti
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (incremental after the first run)
 ragx-cli query "why did we switch build tools?" --json --files-only
 ragx-cli index --full          # full rebuild: re-chunk + re-embed everything
+ragx-cli index --edges-only    # rebuild sub-chunks/edges/communities only; keeps chunk embeddings
 ragx-cli models                # recommend + download an embedding/reranker combo via LM Studio
 ragx-cli doctor                # check the configured providers start and answer, and the index matches
 ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
@@ -97,8 +98,10 @@ chunk mixing several concepts gets one sharp edge per concept instead of a dilut
 between near-duplicate chunks (whole-chunk cosine ≥ `near_dup_sim`) are dropped — those are the
 measured precision-killers. Costs ~2× more embedding calls at index time than `edge_source =
 "chunk"`; retrieval units, traversal, and query flow are unchanged. Switching `edge_source` (or
-the sub-chunk size) requires `index --full`; incremental runs fail loud on the mismatch, naming
-the old/new value and the fix. Literature grounding:
+the sub-chunk size) requires either `index --edges-only` (cheap: rebuilds sub-chunks, edges and
+communities from the stored chunks — chunk embeddings and the HNSW index are kept) or
+`index --full`; incremental runs fail loud on the mismatch, naming the old/new value and both
+fixes. Literature grounding:
 `research/fine-grained-sub-chunk-edges-with-coarse-chunk-nodes-multi-granularity-graph-rag-literature-validation.md`.
 In this mode `k` counts links per *sub-chunk* with no per-chunk cap, so the graph is denser and
 shallower traversal suffices (the default `hops=2` already matches this). Quality ties
@@ -129,17 +132,24 @@ flowchart TD
 re-embeds only new/modified files, drops deleted ones, and repairs only the edge lists those
 chunks touch. Content hashes make `touch`-ed but unchanged files free, and include/exclude glob
 changes converge to the same file set a rebuild would produce. `--full` rebuilds from scratch;
-changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens` requires
-it — incremental runs fail loud on the manifest mismatch, naming the changed key and its old/new
-value. `ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so
-you can see when a re-index is due without running one.
+changing `embeddings.model` or `chunking.*` requires it — incremental runs fail loud on the
+manifest mismatch, naming the changed key and its old/new value. Changing `graph.edge_source`/
+`subchunk_size_tokens` alone is cheaper: `--edges-only` rebuilds just the sub-chunks, edges and
+communities from the chunks already stored — it skips chunking and embedding entirely, reusing
+each chunk's stored vector (via the HNSW index) for chunks that stay whole, and only calls the
+embedder for the sub-chunk pieces a long chunk splits into. It fails loud the same way `--full`
+does if `embeddings.model`/`chunking.*` don't match the stored manifest (those invalidate the
+chunks it reuses), but `edge_source`/`subchunk_size_tokens` are exactly what it's meant to change.
+`ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so you can
+see when a re-index is due without running one.
 
 Upgrading from an older `ragx-cli` after a default change (e.g. the `graph.edge_source` flip to
 `"subchunk"`): `ragx-cli init` always writes every `[graph]` key explicitly into `ragx.toml`
 (`Config.save` bakes the full default set, not just overrides), so an init-created corpus already
 pins its `edge_source`/`subchunk_size_tokens` and is unaffected by a later default change. Only a
 hand-written `ragx.toml` missing those keys picks up the new default; its next incremental
-`index` then fails loud — `index --full` rebuilds, or pin the old value back in `ragx.toml`.
+`index` then fails loud — `index --edges-only` rebuilds just the graph (cheapest), `index --full`
+rebuilds everything, or pin the old value back in `ragx.toml`.
 
 ### Querying
 
@@ -477,11 +487,11 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 ragx-cli web [--host 127.0.0.1] [--port 8765] [--open/--no-open]
 ```
 
-Requires an index built with `graph.edge_source = "subchunk"` (the default) — the graph view
-renders stored edge weights as sub-chunk similarity, and a `"chunk"`-mode index's whole-chunk
-cosine weights would mislabel what the edges mean. Fails loud (exit 2) naming the mismatch, or
-when no index exists yet. `--open` (default) launches the browser; Ctrl-C shuts the server down
-cleanly.
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+`graph.edge_source = "subchunk"` (the default), whole-chunk cosine when `"chunk"`. Fails loud
+(exit 2) only when no index exists yet. To switch an existing index to sub-chunk edges without a
+full re-embed, set the `[graph]` keys in `ragx.toml` and run `ragx-cli index --edges-only`.
+`--open` (default) launches the browser; Ctrl-C shuts the server down cleanly.
 
 Endpoints (JSON; errors are `{"error": "<message>"}`):
 
@@ -696,7 +706,7 @@ Key defaults:
 
 | section | defaults |
 |---|---|
-| `[corpus]` | `include` = source code (`*.py`, `*.ts`, `*.go`, `*.rs`, … ~70 extensions, plus `Dockerfile`/`Makefile`) and text docs (`*.md`, `*.mdx`, `*.rst`, `*.txt`, `*.adoc`, `*.org`); `exclude` = lockfiles (`*.lock`, `package-lock.json`, `pnpm-lock.yaml`, `go.sum`, …), `requirements*.txt`/`constraints*.txt`, `LICENSE*`/`COPYING*`, `*.min.js`/`*.min.css`/`*.map`, and `dist/`, `build/`, `target/`, `coverage/`, `vendor/`; `respect_gitignore=true`. Full lists: `src/ragx/core/corpus_globs.py`. Existing `ragx.toml` files keep their own lists |
+| `[corpus]` | `include` = source code (`*.py`, `*.ts`, `*.go`, `*.rs`, … ~70 extensions, plus `Dockerfile`/`Makefile`) and text docs (`*.md`, `*.mdx`, `*.rst`, `*.txt`, `*.adoc`, `*.org`); `exclude` = lockfiles (`*.lock`, `package-lock.json`, `pnpm-lock.yaml`, `go.sum`, …), `requirements*.txt`/`constraints*.txt`, `LICENSE*`/`COPYING*`, `*.min.js`/`*.min.css`/`*.map`, and `dist/`, `build/`, `target/`, `coverage/`, `vendor/`; `respect_gitignore=true` (every `.gitignore` in the tree applies to its own subtree, with git precedence: deeper files override shallower ones, ignored directories are skipped whole). Full lists: `src/ragx/core/corpus_globs.py`. Existing `ragx.toml` files keep their own lists |
 | `[chunking]` | `size_tokens=800`, `overlap=0.15` |
 | `[graph]` | `k=8`, `min_edge_sim=0.55`, `edge_source="subchunk"`, `subchunk_size_tokens=256`, `near_dup_sim=0.9` |
 | `[traversal]` | `hops=2`, `decay=0.5`, `query_floor=0.35`, `max_frontier=150` |

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/README.md

@@ -24,6 +24,7 @@ ragx-cli init                  # create ragx.toml next to your corpus (interacti
 ragx-cli index                 # chunk -> embed -> HNSW + kNN similarity graph (incremental after the first run)
 ragx-cli query "why did we switch build tools?" --json --files-only
 ragx-cli index --full          # full rebuild: re-chunk + re-embed everything
+ragx-cli index --edges-only    # rebuild sub-chunks/edges/communities only; keeps chunk embeddings
 ragx-cli models                # recommend + download an embedding/reranker combo via LM Studio
 ragx-cli doctor                # check the configured providers start and answer, and the index matches
 ragx-cli --version             # version, repo, and the effective models (corpus config + ~/.ragxrc overrides)
@@ -69,8 +70,10 @@ chunk mixing several concepts gets one sharp edge per concept instead of a dilut
 between near-duplicate chunks (whole-chunk cosine ≥ `near_dup_sim`) are dropped — those are the
 measured precision-killers. Costs ~2× more embedding calls at index time than `edge_source =
 "chunk"`; retrieval units, traversal, and query flow are unchanged. Switching `edge_source` (or
-the sub-chunk size) requires `index --full`; incremental runs fail loud on the mismatch, naming
-the old/new value and the fix. Literature grounding:
+the sub-chunk size) requires either `index --edges-only` (cheap: rebuilds sub-chunks, edges and
+communities from the stored chunks — chunk embeddings and the HNSW index are kept) or
+`index --full`; incremental runs fail loud on the mismatch, naming the old/new value and both
+fixes. Literature grounding:
 `research/fine-grained-sub-chunk-edges-with-coarse-chunk-nodes-multi-granularity-graph-rag-literature-validation.md`.
 In this mode `k` counts links per *sub-chunk* with no per-chunk cap, so the graph is denser and
 shallower traversal suffices (the default `hops=2` already matches this). Quality ties
@@ -101,17 +104,24 @@ flowchart TD
 re-embeds only new/modified files, drops deleted ones, and repairs only the edge lists those
 chunks touch. Content hashes make `touch`-ed but unchanged files free, and include/exclude glob
 changes converge to the same file set a rebuild would produce. `--full` rebuilds from scratch;
-changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens` requires
-it — incremental runs fail loud on the manifest mismatch, naming the changed key and its old/new
-value. `ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so
-you can see when a re-index is due without running one.
+changing `embeddings.model` or `chunking.*` requires it — incremental runs fail loud on the
+manifest mismatch, naming the changed key and its old/new value. Changing `graph.edge_source`/
+`subchunk_size_tokens` alone is cheaper: `--edges-only` rebuilds just the sub-chunks, edges and
+communities from the chunks already stored — it skips chunking and embedding entirely, reusing
+each chunk's stored vector (via the HNSW index) for chunks that stay whole, and only calls the
+embedder for the sub-chunk pieces a long chunk splits into. It fails loud the same way `--full`
+does if `embeddings.model`/`chunking.*` don't match the stored manifest (those invalidate the
+chunks it reuses), but `edge_source`/`subchunk_size_tokens` are exactly what it's meant to change.
+`ragx-cli status` reports **drift** (files new/changed/deleted since the last index) so you can
+see when a re-index is due without running one.
 
 Upgrading from an older `ragx-cli` after a default change (e.g. the `graph.edge_source` flip to
 `"subchunk"`): `ragx-cli init` always writes every `[graph]` key explicitly into `ragx.toml`
 (`Config.save` bakes the full default set, not just overrides), so an init-created corpus already
 pins its `edge_source`/`subchunk_size_tokens` and is unaffected by a later default change. Only a
 hand-written `ragx.toml` missing those keys picks up the new default; its next incremental
-`index` then fails loud — `index --full` rebuilds, or pin the old value back in `ragx.toml`.
+`index` then fails loud — `index --edges-only` rebuilds just the graph (cheapest), `index --full`
+rebuilds everything, or pin the old value back in `ragx.toml`.
 
 ### Querying
 
@@ -449,11 +459,11 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 ragx-cli web [--host 127.0.0.1] [--port 8765] [--open/--no-open]
 ```
 
-Requires an index built with `graph.edge_source = "subchunk"` (the default) — the graph view
-renders stored edge weights as sub-chunk similarity, and a `"chunk"`-mode index's whole-chunk
-cosine weights would mislabel what the edges mean. Fails loud (exit 2) naming the mismatch, or
-when no index exists yet. `--open` (default) launches the browser; Ctrl-C shuts the server down
-cleanly.
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+`graph.edge_source = "subchunk"` (the default), whole-chunk cosine when `"chunk"`. Fails loud
+(exit 2) only when no index exists yet. To switch an existing index to sub-chunk edges without a
+full re-embed, set the `[graph]` keys in `ragx.toml` and run `ragx-cli index --edges-only`.
+`--open` (default) launches the browser; Ctrl-C shuts the server down cleanly.
 
 Endpoints (JSON; errors are `{"error": "<message>"}`):
 
@@ -668,7 +678,7 @@ Key defaults:
 
 | section | defaults |
 |---|---|
-| `[corpus]` | `include` = source code (`*.py`, `*.ts`, `*.go`, `*.rs`, … ~70 extensions, plus `Dockerfile`/`Makefile`) and text docs (`*.md`, `*.mdx`, `*.rst`, `*.txt`, `*.adoc`, `*.org`); `exclude` = lockfiles (`*.lock`, `package-lock.json`, `pnpm-lock.yaml`, `go.sum`, …), `requirements*.txt`/`constraints*.txt`, `LICENSE*`/`COPYING*`, `*.min.js`/`*.min.css`/`*.map`, and `dist/`, `build/`, `target/`, `coverage/`, `vendor/`; `respect_gitignore=true`. Full lists: `src/ragx/core/corpus_globs.py`. Existing `ragx.toml` files keep their own lists |
+| `[corpus]` | `include` = source code (`*.py`, `*.ts`, `*.go`, `*.rs`, … ~70 extensions, plus `Dockerfile`/`Makefile`) and text docs (`*.md`, `*.mdx`, `*.rst`, `*.txt`, `*.adoc`, `*.org`); `exclude` = lockfiles (`*.lock`, `package-lock.json`, `pnpm-lock.yaml`, `go.sum`, …), `requirements*.txt`/`constraints*.txt`, `LICENSE*`/`COPYING*`, `*.min.js`/`*.min.css`/`*.map`, and `dist/`, `build/`, `target/`, `coverage/`, `vendor/`; `respect_gitignore=true` (every `.gitignore` in the tree applies to its own subtree, with git precedence: deeper files override shallower ones, ignored directories are skipped whole). Full lists: `src/ragx/core/corpus_globs.py`. Existing `ragx.toml` files keep their own lists |
 | `[chunking]` | `size_tokens=800`, `overlap=0.15` |
 | `[graph]` | `k=8`, `min_edge_sim=0.55`, `edge_source="subchunk"`, `subchunk_size_tokens=256`, `near_dup_sim=0.9` |
 | `[traversal]` | `hops=2`, `decay=0.5`, `query_floor=0.35`, `max_frontier=150` |

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.9.0"
+version = "0.11.0"
 description = "Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it"
 readme = "README.md"
 license = "MIT"

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/skills/ragx-cli/SKILL.md

@@ -35,6 +35,7 @@ ragx-cli query "..." --json --rerank            # higher precision: cross-encode
 echo "..." | ragx-cli query - --json            # long/multiline query from stdin
 ragx-cli index                  # incremental reindex (hash-based, cheap) — the default
 ragx-cli index --full           # full rebuild: re-chunks + re-embeds everything
+ragx-cli index --edges-only     # rebuild sub-chunks/edges/communities only; keeps embeddings
 ```
 
 Other query flags: `--expand` (one LLM call: multi-query + HyDE), `--no-graph` (pure vector),
@@ -60,8 +61,10 @@ default 5). `--no-expand`/`--no-rerank` are deprecated no-ops (both stages are o
   (incremental, safe, converges even after include/exclude glob changes).
 - Changing `embeddings.model`, `chunking.*`, or `graph.edge_source`/`subchunk_size_tokens`
   invalidates the index: commands fail loud on the manifest mismatch, naming the changed
-  key and old/new value. Fix is `ragx-cli index --full` — re-embeds everything, so confirm
-  before running on a large corpus — or pin the old value back in `ragx.toml`.
+  key and old/new value. For an `edge_source`/`subchunk_size_tokens` change, `ragx-cli index
+  --edges-only` is the cheap fix — rebuilds sub-chunks/edges/communities, keeps chunk
+  embeddings. Otherwise `ragx-cli index --full` — re-embeds everything, so confirm before
+  running on a large corpus — or pin the old value back in `ragx.toml`.
 - `ragx-cli models` picks + downloads an embedding/reranker combo. All files download via
   LM Studio; serving is per engine — `--embed-engine llama-server|lm-studio` and
   `--rerank-engine llama-server|sentence-transformers`. With both on `llama-server`

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/src/ragx/cli/pipeline.py

@@ -12,6 +12,7 @@ from ragx.core.config import Config, require_root
 from ragx.core.errors import RagxError
 from ragx.core.indexer import run_index
 from ragx.core.query import QueryOptions, run_query, to_files_json, to_query_json
+from ragx.core.reedge import rebuild_edges
 from ragx.providers import lmstudio_process
 from ragx.providers.registry import make_embedder, make_generator, make_reranker
 
@@ -24,6 +25,12 @@ def register(app: typer.Typer) -> None:
 def index(
     path: Path | None = typer.Argument(None),
     full: bool = typer.Option(False, "--full", help="full rebuild: re-chunk and re-embed everything"),
+    edges_only: bool = typer.Option(
+        False,
+        "--edges-only",
+        help="rebuild sub-chunks, graph edges and communities from the stored chunks per "
+        "the current [graph] config; chunk embeddings and the vector index are kept",
+    ),
     changed: bool = typer.Option(
         False, "--changed", hidden=True, help="deprecated: incremental is now the default"
     ),
@@ -32,13 +39,20 @@ def index(
     """Chunk, embed, and index the corpus (incremental by default; --full rebuilds)."""
     if changed and full:
         fail("--changed and --full are mutually exclusive")
+    if edges_only and full:
+        fail("--edges-only and --full are mutually exclusive")
+    if edges_only and changed:
+        fail("--edges-only and --changed are mutually exclusive")
     if changed:
         print("warning: --changed is deprecated; incremental is now the default", file=sys.stderr)
     try:
         root = require_root(path)
         cfg = Config.load(root, confirm=migrate_confirm())
         lmstudio_process.ensure_for_section(cfg, "embeddings")
-        stats = run_index(root, cfg, make_embedder(cfg), full=full)
+        if edges_only:
+            stats = rebuild_edges(root, cfg, make_embedder(cfg))
+        else:
+            stats = run_index(root, cfg, make_embedder(cfg), full=full)
     except RagxError as exc:
         fail(str(exc))
     doc = {"schema": "ragx.index.v1", **stats.__dict__}

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/src/ragx/core/discovery.py

@@ -20,12 +20,29 @@ def _is_binary(path: Path) -> bool:
     return b"\x00" in chunk
 
 
-def _load_gitignore_spec(root: Path) -> pathspec.PathSpec | None:
-    gitignore = root / ".gitignore"
+def _load_gitignore_spec(directory: Path) -> pathspec.GitIgnoreSpec | None:
+    gitignore = directory / ".gitignore"
     if not gitignore.is_file():
         return None
     lines = gitignore.read_text(encoding="utf-8", errors="ignore").splitlines()
-    return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+    return pathspec.GitIgnoreSpec.from_lines(lines)
+
+
+def _is_gitignored(rel: str, specs: dict[str, pathspec.GitIgnoreSpec]) -> bool:
+    """Git precedence: the deepest .gitignore with a matching pattern decides.
+
+    `specs` maps a directory's root-relative POSIX path ("" = root) to its .gitignore.
+    Directory paths carry a trailing "/" so dir-only patterns (`build/`) match them.
+    """
+    parts = rel.rstrip("/").split("/")
+    for depth in range(len(parts) - 1, -1, -1):
+        spec = specs.get("/".join(parts[:depth]))
+        if spec is None:
+            continue
+        verdict = spec.check_file("/".join(parts[depth:]) + ("/" if rel.endswith("/") else ""))
+        if verdict.include is not None:
+            return verdict.include
+    return False
 
 
 def discover_files(
@@ -37,17 +54,27 @@ def discover_files(
     """Return sorted relative POSIX paths of files matching include/exclude under root.
 
     Always skips ALWAYS_SKIP_DIRS, hidden directories, the corpus's own root-level
-    ragx.toml, binaries (NUL byte in first 8KB), and files larger than 2MB. Only a
-    root-level .gitignore is honored (MVP limitation).
+    ragx.toml, binaries (NUL byte in first 8KB), and files larger than 2MB. With
+    respect_gitignore, every .gitignore in the tree applies to its own subtree (git
+    semantics: deeper files override shallower ones; ignored directories are pruned,
+    so a negation can't re-include a file under them).
     """
     include_spec = pathspec.PathSpec.from_lines("gitwildmatch", include)
     exclude_spec = pathspec.PathSpec.from_lines("gitwildmatch", exclude) if exclude else None
-    gitignore_spec = _load_gitignore_spec(root) if respect_gitignore else None
+    gitignore_specs: dict[str, pathspec.GitIgnoreSpec] = {}
 
     results: list[str] = []
     for dirpath, dirnames, filenames in root.walk():
+        dir_rel = dirpath.relative_to(root).as_posix()
+        dir_rel = "" if dir_rel == "." else dir_rel
+        if respect_gitignore and (spec := _load_gitignore_spec(dirpath)) is not None:
+            gitignore_specs[dir_rel] = spec
         dirnames[:] = [
-            d for d in dirnames if d not in ALWAYS_SKIP_DIRS and not d.startswith(".")
+            d
+            for d in dirnames
+            if d not in ALWAYS_SKIP_DIRS
+            and not d.startswith(".")
+            and not _is_gitignored(f"{dir_rel}/{d}/".lstrip("/"), gitignore_specs)
         ]
         for name in filenames:
             path = dirpath / name
@@ -59,7 +86,7 @@ def discover_files(
                 continue
             if exclude_spec is not None and exclude_spec.match_file(rel):
                 continue
-            if gitignore_spec is not None and gitignore_spec.match_file(rel):
+            if _is_gitignored(rel, gitignore_specs):
                 continue
 
             try:

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/src/ragx/core/graph_export.py

@@ -1,14 +1,13 @@
 """Builds the ragx.graph.v1 payload (nodes/edges/communities) for `ragx-cli web`.
 
-Requires an index built with graph.edge_source="subchunk": the viewer renders the
-stored edge weights as sub-chunk similarity, and a whole-chunk-cosine graph (edge_source
-="chunk") would mislabel those edges as concept-level links they aren't."""
+Renders whatever edges the index has: sub-chunk similarity when it was built with
+graph.edge_source="subchunk", whole-chunk cosine when edge_source="chunk". An index with
+zero edges (nodes only) is valid — the viewer just shows an unconnected cloud."""
 
 from __future__ import annotations
 
 from pathlib import Path
 
-from ragx.core.errors import RagxError
 from ragx.core.store import Store
 
 LABEL_MAX_CHARS = 80
@@ -16,12 +15,7 @@ LABEL_MAX_CHARS = 80
 
 def build_graph(root: Path, store: Store) -> dict:
     edge_source = store.get_meta("edge_source")
-    if edge_source != "subchunk":
-        raise RagxError(
-            "ragx-cli web shows sub-chunk edges, but this index was built with "
-            f'edge_source="{edge_source}". Set graph.edge_source = "subchunk" in '
-            "ragx.toml and run ragx-cli index."
-        )
+    sub_size = store.get_meta("subchunk_size_tokens")
 
     chunks = store.get_chunks(store.all_chunk_ids())
     edges = store.all_edges()
@@ -51,7 +45,7 @@ def build_graph(root: Path, store: Store) -> dict:
         "meta": {
             "root": root.name,
             "edge_source": edge_source,
-            "subchunk_size_tokens": int(store.get_meta("subchunk_size_tokens") or 0),
+            "subchunk_size_tokens": int(sub_size) if edge_source == "subchunk" and sub_size else None,
             "embedding_model": store.get_meta("embedding_model"),
             "nodes": len(nodes),
             "edges": len(edge_list),

{ragx_cli-0.9.0 → ragx_cli-0.11.0}/src/ragx/core/indexer.py

@@ -16,7 +16,7 @@ from ragx.core.config import Config, db_path, vectors_path
 from ragx.core.discovery import discover_files, hash_file
 from ragx.core.errors import ManifestMismatchError, RagxError
 from ragx.core.graph import affected_ids, knn_edges, subchunk_knn_edges
-from ragx.core.models import ChunkDraft, FileRecord
+from ragx.core.models import FileRecord
 from ragx.core.store import Store
 from ragx.core.vectors import VectorIndex
 from ragx.providers.base import Embedder
@@ -94,7 +94,7 @@ def run_index(root: Path, cfg: Config, embedder: Embedder, *, full: bool = False
             vectors = embedder.embed_documents([d.text for d in drafts])
             index.add(ids, vectors)
             if edge_source == "subchunk":
-                _embed_subchunks(store, embedder, ids, drafts, vectors, sub_size)
+                _embed_subchunks(store, embedder, ids, [d.text for d in drafts], vectors, sub_size)
             new_ids.extend(ids)
             stats.files_indexed += 1
             stats.chunks_added += len(ids)
@@ -150,9 +150,15 @@ def _check_manifest(
     for key, current in checks:
         prev = store.get_meta(key)
         if prev and prev != str(current) and not allow_rewrite:
+            rebuild_hint = "run `ragx-cli index --full` to rebuild"
+            if key in ("edge_source", "subchunk_size_tokens"):
+                rebuild_hint = (
+                    "run `ragx-cli index --edges-only` to rebuild just the graph (cheaper: "
+                    "keeps chunk embeddings), or `ragx-cli index --full` to rebuild everything"
+                )
             raise ManifestMismatchError(
                 f"index was built with {key}={prev!r} but config says {current!r}; "
-                "run `ragx-cli index --full` to rebuild, or pin the old value "
+                f"{rebuild_hint}, or pin the old value "
                 f"({key} = {prev!r}) in ragx.toml to keep the existing index"
             )
 
@@ -192,18 +198,21 @@ def _embed_subchunks(
     store: Store,
     embedder: Embedder,
     ids: Sequence[int],
-    drafts: Sequence[ChunkDraft],
+    texts: Sequence[str],
     chunk_vectors: Sequence[Sequence[float]],
     sub_size: int,
-) -> None:
-    """Split each chunk into sub-chunks and persist their unit vectors.
-    A chunk that stays whole reuses its own embedding — no extra provider call."""
+) -> tuple[int, int]:
+    """Split each chunk's text into sub-chunks and persist their unit vectors.
+    A chunk that stays whole reuses its own embedding — no extra provider call.
+    Returns (sub-chunks embedded, sub-chunks reused from the chunk embedding)."""
     to_embed: list[str] = []
     spans: list[tuple[int, int, int]] = []  # (chunk_id, start, end) into to_embed
-    for cid, draft, cvec in zip(ids, drafts, chunk_vectors):
-        subs = subchunk_texts(draft.text, sub_size)
+    reused = 0
+    for cid, text, cvec in zip(ids, texts, chunk_vectors):
+        subs = subchunk_texts(text, sub_size)
         if len(subs) == 1:
             store.insert_subchunk_vectors(cid, [_unit(cvec)])
+            reused += 1
         else:
             spans.append((cid, len(to_embed), len(to_embed) + len(subs)))
             to_embed.extend(subs)
@@ -211,6 +220,7 @@ def _embed_subchunks(
         vectors = embedder.embed_documents(to_embed)
         for cid, start, end in spans:
             store.insert_subchunk_vectors(cid, [_unit(v) for v in vectors[start:end]])
+    return len(to_embed), reused
 
 
 def _subchunk_edge_fn(