ragx-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.8.0] — 2026-10-20
+
+### Changed
+
+- **`query` defaults to vector search + graph traversal.** Query expansion and
+  cross-encoder rerank are now opt-in via `--expand` and `--rerank` (`QueryOptions`
+  defaults `expand=False`, `rerank=False`). A default query makes no LLM call and loads
+  no reranker. `--no-graph` is unchanged. `--no-expand` and `--no-rerank` still parse
+  as deprecated no-ops with a stderr warning. For the previous behaviour pass
+  `--expand --rerank`.
+- **Default corpus globs index source code and text docs only.** `corpus.include` lists
+  ~70 source extensions, `Dockerfile`, `Makefile`, and `*.md`/`*.mdx`/`*.rst`/`*.txt`/
+  `*.adoc`/`*.org`; `corpus.exclude` skips lockfiles, `requirements*.txt`,
+  `constraints*.txt`, licenses, minified files, source maps, and `dist/`, `build/`,
+  `target/`, `coverage/`, `vendor/`. Applies to new `ragx-cli init` configs; an existing
+  `ragx.toml` keeps its lists.
+
+- **Query results are one entry per file (`ragx.query.v2`, breaking).** A file whose
+  chunks would appear several times in the ranked list becomes one entry with up to 3
+  sub-entries; its score is their sum, so it ranks higher. Only chunks within the visible
+  window (ranked chunks until `--top` distinct files are seen) count. JSON results are
+  `{file, score, chunks: [...]}`; chunks no longer repeat `file`. `--files-only`
+  (`ragx.files.v1`) keeps its shape and now returns the same entries. On the notes eval
+  corpus: baseline MRR .646 → .665, graph config r@5 .808 → .923 and MRR .432 → .653.
+- **`--top` counts result entries (files), default 20** (`query.top`, was 8 chunks).
+  Existing `ragx.toml` files keep their own `query.top`. `ragx-cli eval` no longer
+  over-fetches `top × 3` chunks.
+
+### Added
+
+- `ragx-cli init` prints a note that an AI agent can tailor `corpus.include`/`exclude`
+  to the project and add a CLAUDE.md/AGENTS.md section on using `ragx-cli query`.
+
 ## [0.7.0] — 2026-09-17
 
 ### Added

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/CLAUDE.md

@@ -81,12 +81,13 @@ src/ragx/
   cli/             # thin shells only: app.py (init/status/config + registration),
                    # pipeline.py (index/query), inspect_cmd.py, eval_cmd.py, models_cmd.py
                    # (recommend/download/configure models), doctor_cmd.py, output.py
-tests/             # 244 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
+tests/             # 253 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
 ```
 
 ## Flows
 
-**Index** (`ragx-cli index [--changed]`): discover files (include/exclude globs, root .gitignore,
+**Index** (`ragx-cli index [--changed]`): discover files (include/exclude globs — defaults in
+`core/corpus_globs.py`: source + text docs, minus lockfiles/requirements/build output — root .gitignore,
 skip node_modules/.venv/hidden/binaries/>2MB) → xxhash diff (`--changed` = incremental, default
 = full rebuild) → chunk (~800 tok target, chunks are exact byte slices, sub-100-char fragments
 merge into neighbors) → embed batched → HNSW add → kNN edges per new chunk (k=8, cos ≥ 0.55)
@@ -116,8 +117,13 @@ no-op on failure) → embed all variants, HNSW top-20 each → RRF merge = seeds
 (2 hops, decay 0.5, heat = max not sum, neighbor admitted only if cos(query) ≥ 0.35 floor,
 frontier ≤ 150) → cross-encoder rerank of top-100 shortlist → final =
 0.6·rerank + 0.25·heat + 0.15·vector (each min-max normalized; weights renormalize when a
-stage is off). `--no-expand/--no-graph/--no-rerank` skip stages; `--files-only` ranks files
-by sum of top-3 chunk scores; `--explain` attaches seed→parent→edge_weight→hop traces.
+stage is off). Since 0.8.0 expansion and rerank are OPT-IN (`--expand`/`--rerank`;
+`QueryOptions` defaults expand=False, rerank=False; `--no-expand/--no-rerank` are hidden
+deprecated no-ops); graph stays on, `--no-graph` skips it. Output is folded per file
+(`core/grouping.py`, schema `ragx.query.v2`): walk ranked chunks until `top` (default 20)
+distinct files are seen, each file keeps its ≤3 chunks inside that window, entry score = their
+sum. The window is load-bearing — summing ALL candidates let weak graph-neighbour chunks pad
+files (graph MRR .43 → .38; windowed .65). `--files-only` = same entries, no text; `--explain` attaches seed→parent→edge_weight→hop traces.
 
 ## State & benchmarks (as of 2026-07-10)
 
@@ -129,7 +135,8 @@ full .759/**.889**/**.613**. Key finding: graph-only HURTS precision (near-dupli
 displace direct hits — parameter sweeps plateau below baseline MRR; corpus property, not a
 tuning miss), but graph+rerank together deliver the recall win — one Dutch query's target is
 unreachable by vector search or rerank-alone, surfaced only via a hop-1 edge then reranked
-19→4. Ship graph+rerank together; `--no-graph --no-rerank` is the explicit fast mode.
+19→4. Graph+rerank belong together for quality (`--rerank`); the 0.8.0 default (graph, no
+rerank) is the measured "graph-only" row — chosen for speed, not quality.
 
 UPDATE 2026-07-13: production embedding model is now `text-embedding-bge-m3` (Q8 GGUF, empty
 doc/query prefixes) — notes-repo corpus config + index flipped in place from the worktree-built
@@ -170,7 +177,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` (244 pass, ~5 s) ·
+`uv sync --group dev --extra rerank` · `uv run pytest -q` (253 pass, ~5 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.7.0 → ragx_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ragx-cli
-Version: 0.7.0
+Version: 0.8.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
@@ -130,20 +130,30 @@ since the last index) so you can see when a re-index is due without running one.
 
 ### Querying
 
-Every stage is individually skippable (`--no-expand`, `--no-graph`, `--no-rerank`) so callers
-can trade quality for latency.
+A default query runs vector search + graph traversal: no LLM call, no cross-encoder.
+Expansion (`--expand`) and rerank (`--rerank`) are opt-in; `--no-graph` skips traversal,
+which leaves pure vector search. Callers trade latency for quality per query.
+
+Results are **one entry per file**. The pipeline ranks chunks, walks that list until it has
+seen `--top` distinct files (default `query.top = 20`), and folds each file's chunks inside
+that window into one entry: up to 3 sub-entries, entry score = their sum. A file that would
+appear several times in a flat list therefore ranks higher. Chunks below the window never
+count, so graph traversal's weak neighbour chunks cannot pad a file (measured on the notes
+eval corpus: graph-config MRR .43 flat-list, .38 summing all chunks, .65 windowed).
 
 ```mermaid
 flowchart TD
     Q[query] --> X["1 · expansion (optional, one LLM call)<br/>2–4 reformulations + HyDE passage"]
     X --> S["2 · fan-out vector search<br/>top-20 per variant"]
-    Q -. "--no-expand" .-> S
+    Q -. "default (no --expand)" .-> S
     S --> R["3 · Reciprocal Rank Fusion<br/>merged seed set"]
     R --> H["4 · heat propagation over the graph<br/>2 hops · decay 0.5 · max-aggregation<br/>query-similarity floor · frontier cap"]
     R -. "--no-graph" .-> K
-    H --> K["5 · cross-encoder rerank<br/>(query, chunk) pairs, capped shortlist"]
+    H --> K["5 · cross-encoder rerank (--rerank)<br/>(query, chunk) pairs, capped shortlist"]
+    H -. "default (no --rerank)" .-> F
     K --> F["6 · combined score<br/>α·rerank + β·heat + γ·vector"]
-    F --> O["ranked chunks (or files via --files-only)<br/>+ --explain traversal trace"]
+    F --> G["7 · fold per file<br/>a file's best ≤3 chunks → one entry, score = their sum"]
+    G --> O["top 20 entries (or paths via --files-only)<br/>+ --explain traversal trace"]
 ```
 
 **Heat propagation** is what sets ragx-cli apart from plain RAG: seed chunks (from vector search)
@@ -210,8 +220,10 @@ output for that result shows the exact seed → edge → chunk path.
 **Honest caveat:** graph traversal *alone* hurts precision on this corpus (MRR 0.593 → 0.522) —
 near-duplicate neighbors (e.g. adjacent meeting notes) displace weaker direct hits. A parameter
 sweep over decay/floor/weights plateaued below baseline MRR, so this is a property of
-similarity-only edges, not a tuning miss. Conclusion baked into the defaults: **graph and
-rerank ship together**. Use `--no-graph --no-rerank` as the explicit fast mode.
+similarity-only edges, not a tuning miss. Conclusion: **graph and rerank belong together**.
+Since 0.8.0 the CLI default is the fast path (vector + graph, no rerank), which is the
+"graph-only" row above; pass `--rerank` for the measured best quality, or `--no-graph` for
+pure vector search.
 
 The parameter study below explains the mechanism behind this caveat — and shows that once the
 scoring weights stop putting heat into the final score, the graph win gets much bigger.
@@ -432,13 +444,16 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 
 ## Agent-first conventions
 
-- `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v1`,
+- `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v2`,
   `ragx.files.v1`, `ragx.status.v1`, `ragx.doctor.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go
   to stderr.
 - Exit codes: `0` results, `1` success-but-empty, `2` error.
-- Every chunk carries `file`, `line_start/line_end`, `byte_start/byte_end` — agents jump to the
-  exact source location and read the full text themselves (JSON chunk text is truncated).
-- `--files-only` aggregates chunk scores per file (sum of top-3) — the mode coding agents use most.
+- `ragx.query.v2` results are one entry per file: `{file, score, chunks: [...]}`. Each chunk
+  carries `chunk_id`, `line_start/line_end`, `byte_start/byte_end`, `score`, `breakdown`, `text`,
+  `truncated` — agents jump to the exact source location and read the full text themselves
+  (JSON chunk text is truncated). v1 (one flat entry per chunk) is gone since 0.8.0.
+- `--files-only` returns the same entries without text (`file`, `score`, `chunk_ids`) — the
+  mode coding agents use most.
 - `ragx-cli status` includes a `drift` object (`new`/`changed`/`deleted` file counts vs the index) —
   agents check it to decide whether to run `ragx-cli index` before querying.
 - `ragx-cli doctor --json` verifies the providers answer before a batch of queries (`ok: false`
@@ -458,10 +473,11 @@ This repo has a ragx-cli index (`.ragx/`). Prefer it over grep for "where is X d
 questions; fall back to grep for exact identifiers.
 
 - Find relevant files: `ragx-cli query "<natural-language question>" --json --files-only`
-- Get chunks with exact locations: `ragx-cli query "..." --json --top 8` — each result carries
-  `file` + `line_start/line_end`; the JSON `text` is truncated, so read the file yourself
-  for full context.
-- Fast mode (no LLM call, no cross-encoder): add `--no-expand --no-rerank`.
+- Get chunks with exact locations: `ragx-cli query "..." --json` — one result per `file`
+  (default 20, `--top N`), each with up to 3 `chunks` carrying `line_start/line_end`; the JSON
+  `text` is truncated, so read the file yourself for full context.
+- The default query makes no LLM call and loads no cross-encoder. For higher precision add
+  `--rerank`; add `--expand` for an LLM query-expansion pass (one extra LLM call).
 - After adding or editing files: `ragx-cli index` (incremental and cheap — hash-based).
   `ragx-cli status --json` shows `drift` counts if you want to check staleness first.
 - stdout is exactly one JSON document; logs are on stderr.
@@ -611,10 +627,15 @@ non-thinking model is the better expansion choice; detection is a best-effort na
 heuristic, the APIs expose no capability flag), and corpus include/exclude
 (gitignore-style globs, comma-separated). Every prompt is pre-filled with the defaults
 below — Enter accepts them all. With piped stdin (agents), `--yes`, or
-`--no-interactive`, it writes the defaults unchanged, exactly as before. Key defaults:
+`--no-interactive`, it writes the defaults unchanged, exactly as before. After writing the
+config, `init` prints a note: an AI agent can tailor `corpus.include`/`exclude` to the
+project, and add a CLAUDE.md/AGENTS.md section on searching it with `ragx-cli query`
+(see [Using ragx-cli from a coding agent](#using-ragx-cli-from-a-coding-agent-claudemd--agentsmd)).
+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 |
 | `[chunking]` | `size_tokens=800`, `overlap=0.15` |
 | `[graph]` | `k=8`, `min_edge_sim=0.55`, `edge_source="chunk"`, `subchunk_size_tokens=128`, `near_dup_sim=0.9` |
 | `[traversal]` | `hops=2`, `decay=0.5`, `query_floor=0.35`, `max_frontier=150` |

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/README.md

@@ -102,20 +102,30 @@ since the last index) so you can see when a re-index is due without running one.
 
 ### Querying
 
-Every stage is individually skippable (`--no-expand`, `--no-graph`, `--no-rerank`) so callers
-can trade quality for latency.
+A default query runs vector search + graph traversal: no LLM call, no cross-encoder.
+Expansion (`--expand`) and rerank (`--rerank`) are opt-in; `--no-graph` skips traversal,
+which leaves pure vector search. Callers trade latency for quality per query.
+
+Results are **one entry per file**. The pipeline ranks chunks, walks that list until it has
+seen `--top` distinct files (default `query.top = 20`), and folds each file's chunks inside
+that window into one entry: up to 3 sub-entries, entry score = their sum. A file that would
+appear several times in a flat list therefore ranks higher. Chunks below the window never
+count, so graph traversal's weak neighbour chunks cannot pad a file (measured on the notes
+eval corpus: graph-config MRR .43 flat-list, .38 summing all chunks, .65 windowed).
 
 ```mermaid
 flowchart TD
     Q[query] --> X["1 · expansion (optional, one LLM call)<br/>2–4 reformulations + HyDE passage"]
     X --> S["2 · fan-out vector search<br/>top-20 per variant"]
-    Q -. "--no-expand" .-> S
+    Q -. "default (no --expand)" .-> S
     S --> R["3 · Reciprocal Rank Fusion<br/>merged seed set"]
     R --> H["4 · heat propagation over the graph<br/>2 hops · decay 0.5 · max-aggregation<br/>query-similarity floor · frontier cap"]
     R -. "--no-graph" .-> K
-    H --> K["5 · cross-encoder rerank<br/>(query, chunk) pairs, capped shortlist"]
+    H --> K["5 · cross-encoder rerank (--rerank)<br/>(query, chunk) pairs, capped shortlist"]
+    H -. "default (no --rerank)" .-> F
     K --> F["6 · combined score<br/>α·rerank + β·heat + γ·vector"]
-    F --> O["ranked chunks (or files via --files-only)<br/>+ --explain traversal trace"]
+    F --> G["7 · fold per file<br/>a file's best ≤3 chunks → one entry, score = their sum"]
+    G --> O["top 20 entries (or paths via --files-only)<br/>+ --explain traversal trace"]
 ```
 
 **Heat propagation** is what sets ragx-cli apart from plain RAG: seed chunks (from vector search)
@@ -182,8 +192,10 @@ output for that result shows the exact seed → edge → chunk path.
 **Honest caveat:** graph traversal *alone* hurts precision on this corpus (MRR 0.593 → 0.522) —
 near-duplicate neighbors (e.g. adjacent meeting notes) displace weaker direct hits. A parameter
 sweep over decay/floor/weights plateaued below baseline MRR, so this is a property of
-similarity-only edges, not a tuning miss. Conclusion baked into the defaults: **graph and
-rerank ship together**. Use `--no-graph --no-rerank` as the explicit fast mode.
+similarity-only edges, not a tuning miss. Conclusion: **graph and rerank belong together**.
+Since 0.8.0 the CLI default is the fast path (vector + graph, no rerank), which is the
+"graph-only" row above; pass `--rerank` for the measured best quality, or `--no-graph` for
+pure vector search.
 
 The parameter study below explains the mechanism behind this caveat — and shows that once the
 scoring weights stop putting heat into the final score, the graph win gets much bigger.
@@ -404,13 +416,16 @@ anything. If a run dies with "connection refused", `doctor` names the stage and
 
 ## Agent-first conventions
 
-- `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v1`,
+- `--json` emits exactly one JSON document on stdout (versioned schemas: `ragx.query.v2`,
   `ragx.files.v1`, `ragx.status.v1`, `ragx.doctor.v1`, `ragx.eval.v1`, `ragx.inspect.*.v1`); logs go
   to stderr.
 - Exit codes: `0` results, `1` success-but-empty, `2` error.
-- Every chunk carries `file`, `line_start/line_end`, `byte_start/byte_end` — agents jump to the
-  exact source location and read the full text themselves (JSON chunk text is truncated).
-- `--files-only` aggregates chunk scores per file (sum of top-3) — the mode coding agents use most.
+- `ragx.query.v2` results are one entry per file: `{file, score, chunks: [...]}`. Each chunk
+  carries `chunk_id`, `line_start/line_end`, `byte_start/byte_end`, `score`, `breakdown`, `text`,
+  `truncated` — agents jump to the exact source location and read the full text themselves
+  (JSON chunk text is truncated). v1 (one flat entry per chunk) is gone since 0.8.0.
+- `--files-only` returns the same entries without text (`file`, `score`, `chunk_ids`) — the
+  mode coding agents use most.
 - `ragx-cli status` includes a `drift` object (`new`/`changed`/`deleted` file counts vs the index) —
   agents check it to decide whether to run `ragx-cli index` before querying.
 - `ragx-cli doctor --json` verifies the providers answer before a batch of queries (`ok: false`
@@ -430,10 +445,11 @@ This repo has a ragx-cli index (`.ragx/`). Prefer it over grep for "where is X d
 questions; fall back to grep for exact identifiers.
 
 - Find relevant files: `ragx-cli query "<natural-language question>" --json --files-only`
-- Get chunks with exact locations: `ragx-cli query "..." --json --top 8` — each result carries
-  `file` + `line_start/line_end`; the JSON `text` is truncated, so read the file yourself
-  for full context.
-- Fast mode (no LLM call, no cross-encoder): add `--no-expand --no-rerank`.
+- Get chunks with exact locations: `ragx-cli query "..." --json` — one result per `file`
+  (default 20, `--top N`), each with up to 3 `chunks` carrying `line_start/line_end`; the JSON
+  `text` is truncated, so read the file yourself for full context.
+- The default query makes no LLM call and loads no cross-encoder. For higher precision add
+  `--rerank`; add `--expand` for an LLM query-expansion pass (one extra LLM call).
 - After adding or editing files: `ragx-cli index` (incremental and cheap — hash-based).
   `ragx-cli status --json` shows `drift` counts if you want to check staleness first.
 - stdout is exactly one JSON document; logs are on stderr.
@@ -583,10 +599,15 @@ non-thinking model is the better expansion choice; detection is a best-effort na
 heuristic, the APIs expose no capability flag), and corpus include/exclude
 (gitignore-style globs, comma-separated). Every prompt is pre-filled with the defaults
 below — Enter accepts them all. With piped stdin (agents), `--yes`, or
-`--no-interactive`, it writes the defaults unchanged, exactly as before. Key defaults:
+`--no-interactive`, it writes the defaults unchanged, exactly as before. After writing the
+config, `init` prints a note: an AI agent can tailor `corpus.include`/`exclude` to the
+project, and add a CLAUDE.md/AGENTS.md section on searching it with `ragx-cli query`
+(see [Using ragx-cli from a coding agent](#using-ragx-cli-from-a-coding-agent-claudemd--agentsmd)).
+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 |
 | `[chunking]` | `size_tokens=800`, `overlap=0.15` |
 | `[graph]` | `k=8`, `min_edge_sim=0.55`, `edge_source="chunk"`, `subchunk_size_tokens=128`, `near_dup_sim=0.9` |
 | `[traversal]` | `hops=2`, `decay=0.5`, `query_floor=0.35`, `max_frontier=150` |

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.7.0"
+version = "0.8.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.7.0 → ragx_cli-0.8.0}/skills/ragx-cli/SKILL.md

@@ -11,8 +11,9 @@ description: |
 # ragx-cli — semantic search over an indexed corpus
 
 Indexes files into a chunk-level embedding similarity graph; answers queries via vector search +
-graph traversal + cross-encoder rerank. Agent-first: one JSON doc on stdout, logs on stderr,
-deterministic exit codes, byte-exact source locations.
+graph traversal, with optional cross-encoder rerank (`--rerank`) and LLM expansion (`--expand`).
+Agent-first: one JSON doc on stdout, logs on stderr, deterministic exit codes, byte-exact source
+locations.
 
 ## When
 
@@ -29,24 +30,28 @@ A corpus is ragx-indexed if its root has `ragx.toml` and `.ragx/`.
 ```bash
 ragx-cli status --json          # root, model, counts, and drift (new/changed/deleted vs index)
 ragx-cli query "question" --json --files-only   # which files are relevant — most-used mode
-ragx-cli query "..." --json --top 8             # ranked chunks with exact locations
-ragx-cli query "..." --json --no-expand --no-rerank   # fast: skip LLM call + cross-encoder
+ragx-cli query "..." --json --top 10            # one entry per file, best chunks + exact locations
+ragx-cli query "..." --json --rerank            # higher precision: cross-encoder rerank (slower)
 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
 ```
 
-Other query flags: `--no-graph`, `--hops N`, `--explain`.
+Other query flags: `--expand` (one LLM call: multi-query + HyDE), `--no-graph` (pure vector),
+`--hops N`, `--explain`. `--no-expand`/`--no-rerank` are deprecated no-ops (both stages are off
+by default).
 
 ## Output
 
-- stdout is exactly one JSON doc (`ragx.query.v1` / `ragx.files.v1` / `ragx.status.v1`); logs go
+- stdout is exactly one JSON doc (`ragx.query.v2` / `ragx.files.v1` / `ragx.status.v1`); logs go
   to stderr. Never parse stderr.
 - Exit codes: `0` results, `1` success-but-empty (report "nothing found", don't retry as failure),
   `2` error.
-- Chunk results carry `file`, `line_start/end`, `byte_start/end`, `score`, `breakdown`. JSON
-  `text` is truncated — read the file at the line range for full context.
-- Typical flow: `--files-only` to pick files → `--top 8` for locations → read files at ranges.
+- `ragx.query.v2` results are one entry per file (default 20): `file`, `score` (sum of its
+  chunks), `chunks` (up to 3, each with `line_start/end`, `byte_start/end`, `score`,
+  `breakdown`, `text`). JSON `text` is truncated — read the file at the line range for full
+  context.
+- Typical flow: `--files-only` to pick files → `--json` for line ranges → read files at ranges.
 
 ## Freshness
 

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/src/ragx/cli/app.py

@@ -27,6 +27,13 @@ from ragx.core.config import (
 from ragx.core.errors import RagxError
 
 REPO_URL = "https://github.com/alber70g/ragx-cli"
+INIT_NOTE = (
+    "note: corpus.include/exclude default to source code and text docs, minus lockfiles,\n"
+    "dependency manifests and build output. An AI agent (Claude Code, Codex, ...) can:\n"
+    f"  1. tailor corpus.include/exclude in {CONFIG_FILE} to this project's files\n"
+    "  2. add a section to CLAUDE.md or AGENTS.md telling agents to search this corpus\n"
+    '     with `ragx-cli query "..."` (--json for machine output, --files-only for paths)'
+)
 
 app = typer.Typer(add_completion=False, no_args_is_help=True)
 config_app = typer.Typer(add_completion=False, no_args_is_help=True)
@@ -133,6 +140,7 @@ def init(
     else:
         cfg_path = write_default_config(root)
     typer.echo(f"created {cfg_path}")
+    typer.echo(INIT_NOTE)
     if ask and typer.confirm(
         "recommend + download models via LM Studio now? (rerun anytime: `ragx-cli models`)",
         default=False,

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/src/ragx/cli/eval_cmd.py

@@ -59,10 +59,8 @@ def eval_cmd(
             reranker=reranker if opts.rerank else None,
         )
 
-    # retrieve chunks deep enough that file-level ranking has >= `top` files to rank
-    selected = [
-        (name, replace(_BUILTIN_CONFIGS[name], top=top * 3)) for name in names
-    ]
+    # query results are already one entry per file, ranked
+    selected = [(name, replace(_BUILTIN_CONFIGS[name], top=top)) for name in names]
     result = evaluate(queries, selected, query_fn, top=top)
 
     if json_out:

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/src/ragx/cli/pipeline.py

@@ -64,16 +64,25 @@ def _generator(cfg: Config):
 
 def query(
     text: str = typer.Argument(..., help="query text, or '-' to read from stdin"),
-    top: int | None = typer.Option(None, "--top"),
+    top: int | None = typer.Option(None, "--top", help="result entries (files); default query.top = 20"),
     json_out: bool = typer.Option(False, "--json"),
     files_only: bool = typer.Option(False, "--files-only"),
-    no_expand: bool = typer.Option(False, "--no-expand"),
+    expand: bool = typer.Option(False, "--expand", help="LLM query expansion (multi-query + HyDE)"),
     no_graph: bool = typer.Option(False, "--no-graph"),
-    no_rerank: bool = typer.Option(False, "--no-rerank"),
+    rerank: bool = typer.Option(False, "--rerank", help="cross-encoder rerank of the shortlist"),
+    no_expand: bool = typer.Option(
+        False, "--no-expand", hidden=True, help="deprecated: expansion is now off by default"
+    ),
+    no_rerank: bool = typer.Option(
+        False, "--no-rerank", hidden=True, help="deprecated: rerank is now off by default"
+    ),
     hops: int | None = typer.Option(None, "--hops"),
     explain: bool = typer.Option(False, "--explain"),
 ) -> None:
-    """Search the index; ranked chunks (or files with --files-only)."""
+    """Search the index: one entry per file with its best chunks (paths only with --files-only)."""
+    for flag, used in (("--no-expand", no_expand), ("--no-rerank", no_rerank)):
+        if used:
+            print(f"warning: {flag} is deprecated; that stage is now off by default", file=sys.stderr)
     if text == "-":
         text = sys.stdin.read().strip()
     try:
@@ -83,9 +92,9 @@ def query(
         opts = QueryOptions(
             top=top if top is not None else cfg.get("query.top"),
             files_only=files_only,
-            expand=not no_expand,
+            expand=expand,
             graph=not no_graph,
-            rerank=not no_rerank,
+            rerank=rerank,
             hops=hops,
             explain=explain,
         )
@@ -105,9 +114,11 @@ def query(
         for f in to_files_json(out)["files"]:
             typer.echo(f"{f['score']:.4f}  {f['file']}")
     else:
-        for r in out.results:
-            loc = f"{r.chunk.file_path}:{r.chunk.line_start}-{r.chunk.line_end}"
-            first_line = r.chunk.text.strip().splitlines()[0][:100] if r.chunk.text.strip() else ""
-            typer.echo(f"{r.score:.4f}  {loc}  {first_line}")
+        for f in out.results:
+            typer.echo(f"{f.score:.4f}  {f.file_path}")
+            for r in f.chunks:
+                lines = f"{r.chunk.line_start}-{r.chunk.line_end}"
+                first_line = r.chunk.text.strip().splitlines()[0][:90] if r.chunk.text.strip() else ""
+                typer.echo(f"        {r.score:.4f}  {lines:<9}  {first_line}")
     if not out.results:
         raise typer.Exit(code=1)

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/src/ragx/core/config.py

@@ -13,6 +13,7 @@ from typing import Any
 
 import tomli_w
 
+from ragx.core.corpus_globs import DEFAULT_EXCLUDE, DEFAULT_INCLUDE
 from ragx.core.errors import NotInitializedError, RagxError
 
 RAGX_DIR = ".ragx"
@@ -26,7 +27,11 @@ def rc_path() -> Path:
     return Path.home() / ".ragxrc"
 
 DEFAULTS: dict[str, dict[str, Any]] = {
-    "corpus": {"include": ["**/*"], "exclude": [], "respect_gitignore": True},
+    "corpus": {
+        "include": DEFAULT_INCLUDE,
+        "exclude": DEFAULT_EXCLUDE,
+        "respect_gitignore": True,
+    },
     "chunking": {"size_tokens": 800, "overlap": 0.15},
     "graph": {
         "k": 8,
@@ -69,7 +74,7 @@ DEFAULTS: dict[str, dict[str, Any]] = {
         "gguf": "",  # llama-server only: path to the reranker GGUF (LM Studio dir works)
         "server_bin": "llama-server",  # llama-server only: binary name or path
     },
-    "query": {"top": 8, "max_chunk_chars": 1200},
+    "query": {"top": 20, "max_chunk_chars": 1200},  # top = result entries (one per file)
 }
 
 

ragx_cli-0.8.0/src/ragx/core/corpus_globs.py

@@ -0,0 +1,29 @@
+"""Default corpus globs: index source code and prose; skip lockfiles, dependency
+manifests, licenses, minified and build output. gitignore-style patterns — a pattern
+without a slash matches at any depth. Projects tailor these in ragx.toml."""
+
+from __future__ import annotations
+
+DOC_EXTS = ["md", "mdx", "markdown", "rst", "txt", "adoc", "org"]
+
+SOURCE_EXTS = [
+    "py", "pyi", "js", "jsx", "mjs", "cjs", "ts", "tsx", "mts", "cts", "vue", "svelte",
+    "astro", "go", "rs", "java", "kt", "kts", "scala", "groovy", "c", "h", "cc", "cpp",
+    "cxx", "hpp", "hh", "cs", "fs", "swift", "m", "mm", "rb", "php", "pl", "pm", "lua",
+    "r", "R", "dart", "ex", "exs", "erl", "hrl", "clj", "cljs", "hs", "ml", "mli", "elm",
+    "zig", "nim", "jl", "sh", "bash", "zsh", "fish", "ps1", "sql", "graphql", "gql",
+    "proto", "tf", "hcl", "html", "css", "scss", "sass", "less",
+]
+
+DEFAULT_INCLUDE = [f"*.{ext}" for ext in DOC_EXTS + SOURCE_EXTS] + ["Dockerfile", "Makefile"]
+
+DEFAULT_EXCLUDE = [
+    # lockfiles and dependency manifests
+    "*.lock", "bun.lockb", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml",
+    "go.sum", "requirements*.txt", "constraints*.txt",
+    # licenses
+    "LICENSE*", "COPYING*",
+    # minified and generated output
+    "*.min.js", "*.min.css", "*.map",
+    "dist/", "build/", "target/", "coverage/", "vendor/",
+]

ragx_cli-0.8.0/src/ragx/core/grouping.py

@@ -0,0 +1,31 @@
+"""Fold ranked chunks into one entry per file."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ragx.core.models import ScoredChunk, ScoredFile
+
+PER_FILE = 3
+
+
+def group_by_file(ranked: Iterable[ScoredChunk], top: int, per_file: int = PER_FILE) -> list[ScoredFile]:
+    """Fold the chunks a flat best-first list would show into one entry per file.
+
+    The window ends where the flat list reaches `top` distinct files: chunks below it never
+    count. Each file keeps its `per_file` best chunks inside the window and scores as their
+    sum, so a file that repeats in the list outranks one that appears once. Without the
+    window, graph traversal's many weak neighbour chunks pad multi-chunk files past strong
+    single-chunk files (measured: graph MRR .43 -> .38 unwindowed, .65 windowed).
+
+    `ranked` must be best-first; returns at most `top` files, best-first."""
+    by_file: dict[str, list[ScoredChunk]] = {}
+    for r in ranked:
+        if r.chunk.file_path not in by_file and len(by_file) == top:
+            break  # the flat list would show `top` files by now; later chunks never surface
+        hits = by_file.setdefault(r.chunk.file_path, [])
+        if len(hits) < per_file:
+            hits.append(r)
+    files = [ScoredFile(path, sum(h.score for h in hits), hits) for path, hits in by_file.items()]
+    files.sort(key=lambda f: (-f.score, f.file_path))
+    return files[:top]

{ragx_cli-0.7.0 → ragx_cli-0.8.0}/src/ragx/core/models.py

@@ -58,10 +58,19 @@ class ScoredChunk:
     explain: dict | None = None  # traversal trace: seeds, edge paths, weights
 
 
+@dataclass
+class ScoredFile:
+    """One result entry: a file's best chunks folded together, scored as their sum."""
+
+    file_path: str
+    score: float
+    chunks: list[ScoredChunk]  # best-first
+
+
 @dataclass
 class QueryOutput:
-    """Top-level result of the query pipeline; serialized as ragx.query.v1."""
+    """Top-level result of the query pipeline; serialized as ragx.query.v2."""
 
     query: str
     variants: list[str] = field(default_factory=list)
-    results: list[ScoredChunk] = field(default_factory=list)
+    results: list[ScoredFile] = field(default_factory=list)