CHANGELOG.md

# Changelog

All notable changes to trelix are documented here.

Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — [Semantic Versioning](https://semver.org/).

## [Unreleased]

_Nothing yet._

## [3.2.3] — 2026-08-28

### Overview

One real fix — a SQL `LIKE` wildcard leak in path-scoped search — plus the test
infrastructure that should catch this class of gap automatically going
forward: a real-subprocess E2E suite, a hard pre-publish gate on the actual
built wheels, two cheap CI extensions closing the exact gaps that let the
3.2.1 defects ship, and a permanent script replacing the hand-run post-publish
audit this project used for the 3.2.1 and 3.2.2 releases. No stored-vector
changes.

### Fixed

- **`path_filter` leaked results across sibling paths whose names differed only
  at a `_` or `%` position.** `db.bm25_search` and `grep_search.py`'s three
  `path_filter`-scoped queries built their SQL `LIKE` pattern with an unescaped
  f-string, so a literal underscore or percent sign in `path_filter` — plausible
  in a real directory name, e.g. `test_utils`, `src_auth` — was read as a `LIKE`
  wildcard instead of a literal character. Confirmed by hand: two files,
  `src_auth/login.py` and `srcXauth/login.py`, both matching the same query;
  `path_filter="src_auth"` returned both. Not a SQL injection — every query here
  was already parameterized with `?` — a distinct `LIKE`-semantics issue
  parameterization does not address. Fixed with a shared `escape_like_pattern()`
  helper plus an explicit `ESCAPE '\'` clause on every affected query, mirroring
  the identical fix `Database.get_index_metadata_with_prefix` already had for
  the same defect shape.

### Tests

- **A real-subprocess E2E suite** (`tests/e2e/`, new `e2e` pytest marker,
  `make test-e2e`, a new CI job): `trelix-mcp` spawned as a real OS subprocess
  speaking real stdio JSON-RPC, and a real wheel build + fresh-venv install
  (never editable source) for all four published packages. Targets the exact
  process-boundary defect class that shipped in 3.2.1 — `trelix-mcp` missing
  from the Docker image, its console script silently ignoring
  `--help`/`--version`/any flag — which every existing in-process test
  (Click's `CliRunner`, the MCP SDK's in-memory `Client`) is documented as
  structurally unable to see. Also extends `tests/integration/test_cli.py`
  (which already spawns the real `trelix` CLI) with two assertions it lacked:
  search finds the *specific* symbol a query targets, and the installed
  console script's `--version` agrees with the importable package's own
  `__version__`.
- **`release.yml`'s `publish` job is now hard-gated on installing the actual
  built wheels** — never editable source, never a live PyPI pull, which
  structurally cannot gate the release that creates the version it would
  check. A new `smoke-test-built-artifacts` job installs the exact wheels
  `build-distributions` just built and re-runs the E2E + real-CLI-subprocess
  suites against that install before `publish` is allowed to run.
- **Two cheap extensions to already-existing CI checks** close the other two
  gaps that let 3.2.1 ship: `ci.yml`'s Docker job now also checks `trelix-mcp`
  is actually present in the built image, and `helm-lint.yml` now asserts the
  rendered Deployment's image tag matches `Chart.yaml`'s `appVersion` on every
  `helm/**` PR.
- **`scripts/verify_release.py`** replaces the hand-authored, twice-run
  post-publish verification prompt with one permanent, reusable command
  (PyPI installs, Docker images, Helm chart at the tag, GitHub Release
  binaries, a security/dependency audit) — see `CONTRIBUTING.md`'s release
  checklist for when to run it.

### Migration

- No stored-vector or index changes; no reindex needed.
- No dependency floors moved.
- If you relied on `path_filter` accidentally matching sibling paths via an
  unescaped `_`/`%` (unlikely, and not a documented behavior), it now matches
  only the literal prefix you passed.

## [3.2.2] — 2026-08-26

### Overview

Two fixes to the published trelix-mcp surface, both found by a post-3.2.1 production
verification pass that installed and ran the actual shipped PyPI packages and Docker
images rather than the source tree. No stored-vector or retrieval changes.

### Fixed

- **`trelix-mcp`'s console script ignored `--help`, `-h`, `--version`, and any
  unrecognized flag** — `main()` never inspected `sys.argv` at all, so every one of those
  silently launched the real MCP server on stdio instead of doing what a CLI user expects.
  Confirmed live on the published PyPI package. `main()` now parses argv with `argparse`;
  the no-args path — how every real MCP client actually launches this — is unchanged.
- **`trelix-mcp` was entirely absent from the published Docker images.** The builder
  stage only ever copied and installed core `trelix`; `packages/trelix-mcp` was never
  copied in, and `.dockerignore`'s blanket `packages/` exclusion would have blocked it
  even if it had been. Confirmed live: `docker run --entrypoint trelix-mcp
  ghcr.io/sairam0424/trelix:3.2.1 --help` failed with exit 127, genuinely missing from
  `console_scripts`, not a PATH issue. Both tags now bundle `trelix-mcp` alongside core
  (~84MB larger on the slim `:X.Y.Z` tag; no torch pulled in).

### Migration

- No stored-vector or index changes; no reindex needed.
- No dependency floors moved.
- If you were relying on `docker run --entrypoint trelix-mcp <image>` failing (unlikely),
  it now works instead.

## [3.2.1] — 2026-08-26

### Overview

Test-infrastructure release. No stored-vector, retrieval, or CLI behavior changes — one
real production fix (a retry-path import cost) and everything else is measurement:
mutation testing, branch coverage, and a hermetic unit suite. This lands the instrument the
repo was missing: coverage alone could not say whether a test *can* fail; this release adds
tooling that measures it directly.

### Fixed

- **`retry.py`'s status-code extractor imported every LLM provider SDK on every retry
  decision**, not just the one actually in use. `_extract_status_code` branched through
  `anthropic`, `openai`, `google.genai`, `boto3`, and `azure` imports on each call regardless
  of which backend raised, pulling `torch` transitively into processes that use no LLM
  feature at all. It now imports only the SDK for the exception type it is inspecting.

### Tests

- **Hermetic unit suite.** Outbound sockets banned (`pytest-socket`), every job
  timeout-bounded, and `tests/integration/test_llm_e2e.py`'s live-LLM tests moved behind an
  explicit opt-in (`TRELIX_LIVE_LLM_TESTS=1`) instead of running whenever a `.env` happened to
  exist — removes roughly half the suite's wall clock (live HuggingFace Hub traffic) along
  with the credential exposure that came with it.
- **Branch coverage** enabled (`--cov-branch`) with per-package floors in
  `tests/coverage-floors.json`, so a coverage regression now names the offending package
  instead of hiding behind one global percentage.
- **New scoped mutation-testing driver** (`scripts/mutation.py`, wrapping `mutmut`) with a
  per-module survivor-*count* ceiling ratchet in `scripts/mutation_baseline.json` — never a
  ratio. First real measurements landed for `indexing.parser`'s per-language extractors
  (split from one coarse scope key into 23 granular ones), `store.db`, `store.vector`,
  `indexing.chunker`, `compression.extractive`, and `graph`.
- Closed the test-side gaps the mutation instrument surfaced: walker extension-map coverage,
  `ContextualChunker` boundary conditions, graph community-detection survivor patterns, and
  the operator-environment-variable leak/scrub coverage, among others.
- Added a cross-backend `VectorStoreContract` (sqlite / in-process Lance) and the suite's
  first `hypothesis` property-based tests.
- Pinned 16 known, not-yet-fixed Java/Rust extractor defects as `xfail(strict=True)` instead
  of leaving them silently uncovered — each now XPASSes loudly if fixed without an
  accompanying changelog entry.
- Registered a marker taxonomy (`slow`, `requires_network`, `component`, `e2e`, `cli`, …) so
  the suite is selectable and a `-m` typo can no longer silently collect and pass everything.
- Closed the `pyvis` CI coverage gap flagged in the previous release round.

### Migration

- No stored-vector or index changes; no reindex needed.
- `TRELIX_LIVE_LLM_TESTS=1` is now required to run `tests/integration/test_llm_e2e.py`'s
  live-provider tests — they no longer run automatically whenever a `.env` file exists.
- No dependency floors moved.

## [3.2.0] — 2026-08-22

### Overview

Three protocol defects, all of which change stored vectors, which is why this is a minor
release rather than a patch. Two were found by comparing what each model *publishes* against
what trelix *does*, side by side — the same method that produced v3.1.7's retraction. The
third is the same class of defect in the sparse leg, which no previous audit had examined.

Only the sparse fix requires action from an existing user. See **Migration** below.

### Fixed

- **The sparse leg mixed padding into every stored vector, so a chunk's representation
  depended on which other chunks shared its batch.** `SparseEmbedder.embed` tokenizes with
  `padding=True`, padding each batch to its own longest member, and then aggregated with
  `torch.log(1 + torch.relu(logits)).max(dim=1)` — a max over *all* sequence positions. A
  MaskedLM emits real logits at PAD positions too; it predicts a distribution for every
  position, including the ones that exist only because a longer chunk is in the batch. The
  attention mask was never applied: `grep -c attention_mask src/trelix/embedder/sparse.py`
  returned 0, and tree-wide `grep -rln attention_mask src/trelix/` matched no file at all.
  Measured on the real `naver/splade-v3-distilbert` at `top_k=128`: a 28-token chunk
  embedded alone versus batched with a 185-token chunk **gained 28 phantom terms and lost 28
  real ones** at the `top_k` cut — 22% of the vector — with **0.478** max weight drift on the
  terms that survived. The phantom tokens are ordinary English the chunk never contained:
  `where`, `store`, `numbers`, `text`, `gene`, `sequence`, `phrase`, `messages`. The positive
  control is what pins the cause rather than a correlate: the same chunk batched with an
  *equal-length* chunk, needing no padding, is bit-identical to it embedded alone. Batching
  was never the problem; padding was.

  Two consequences made this worth a release rather than a note. `sparse_embeddings` is a
  **persisted** table (`store/db.py`), so an index was not reproducible — re-indexing the
  same repository with a different file order, or a different `TRELIX_SPARSE_BATCH_SIZE`,
  rewrote every row. And `embed_query` routes through `embed([text])`, a batch of one that
  needs no padding, so **queries were always clean and were scored against contaminated
  documents**. No amount of query-side tuning corrects that asymmetry. The aggregation now
  multiplies by the attention mask before the max, which is also NAVER's own formulation;
  `torch.log(1 + …)` is kept verbatim rather than switched to `log1p`, so the mask is the
  only intended change to the numbers.

- **`nomic-code` had never constructed, for any user, in any release.**
  `nomic-ai/CodeRankEmbed`'s `config.json` declares
  `auto_map.AutoModel = modeling_hf_nomic_bert.NomicBertModel`, and that published module
  imports `einops` at its **top level** — so the import runs during the `trust_remote_code`
  load, before any trelix code sees the model. `einops` was declared by no trelix extra
  (`grep -c einops pyproject.toml` → 0; the `nomic-code` extra contained only
  `sentence-transformers`), and nothing else installed provides it transitively, so the
  provider raised `ModuleNotFoundError` from inside remote model code every time it was
  selected. `einops>=0.7.0` is now declared in the extra.

- **`nomic-code` sent prefixes belonging to a different model.** The module carried
  `_DOC_PREFIX = "search_document: "` and `_QUERY_PREFIX = "search_query: "`, which are
  `nomic-embed-text-v1.5`'s protocol. CodeRankEmbed publishes exactly one prefix — a query
  instruction in its own `config_sentence_transformers.json` under `prompts.query` — and
  takes **no** prefix on documents, so both sides carried a prefix the model was never
  trained on. Queries now pass `prompt_name="query"`, which makes sentence-transformers read
  the instruction from the model's own config, exactly as `Pooling.load()` reads its pooling
  method from `1_Pooling/config.json`; documents pass no prompt. The string is not hardcoded
  in the encode path, so a future model swap cannot leave this provider asserting a protocol
  its model does not declare — the mechanism that caused both this defect and the next one.

- **`bge-code` used `nomic-ai/CodeRankEmbed`'s query prompt.**
  `_QUERY_INSTRUCTION` read `"Represent this query for searching relevant code: "`, which is
  character for character CodeRankEmbed's published `prompts.query`. `BAAI/bge-code-v1`
  publishes `prompts: {}` — empty — and its model card supplies the instruction and the
  format `<instruct>{}\n<query>{}` instead, with `<instruct>` and `<query>` shipped as
  `additional_special_tokens` in its tokenizer so they tokenize as single ids. The provider
  now passes BAAI's CosQA task instruction (the published task closest to trelix's: a
  natural-language query retrieving code) together with `query_instruction_format`, which
  `FlagModel` accepts and which otherwise defaults to plain concatenation `"{}{}"`.

  **This does not make `bge-code` usable, and must not be read as doing so.** The provider
  remains EXPERIMENTAL for the pooling reason v3.1.7 documented: with CLS pooling on a causal
  decoder, token 0 is now `<instruct>` for every query instead of `Represent` for every
  query — still one shared token, so every query embedding is still identical. The prompt was
  corrected here because it is provably wrong independently of the pooling question, under
  every candidate loader. The pooling fix is a separate change and is not in this release.

  Why it survived 28 tagged releases: the pooling degeneracy made every query embedding
  byte-identical, so the prompt text could not change any observable, and the tests asserted
  `encoded_text.startswith(_QUERY_INSTRUCTION)` — deriving the expected value from the
  constant under test, so they passed for any value at all.

### Changed

- `nomic-code` now honours `TRELIX_EMBEDDER_BATCH_SIZE`. `embed` hardcoded `batch_size=32`,
  silently ignoring the knob every other sentence-transformers provider reads. Safe to change
  because the provider has never produced a vector, so there is no memory profile to preserve.
- `SparseEmbedder.embed`'s exception handler logs at WARNING instead of DEBUG. The
  degradation is deliberate — a failing sparse leg must not fail the whole index — but every
  chunk receives `{}`, the dot product over an empty vector is 0, and the leg contributes
  nothing while reporting nothing. At DEBUG the CLI's default level hid it entirely, so a
  uniformly empty sparse index produced no signal anywhere.

### Migration

- **If `TRELIX_RETRIEVAL_SPARSE` is enabled, reindex.** Every stored sparse vector was
  computed with padding mixed in, and the fix changes them. Dimension is unchanged, so
  nothing detects this automatically. Old and new sparse vectors are directly comparable in
  the dot product, so a partially-reindexed store degrades silently rather than failing —
  prefer a full reindex over an incremental one, since an incremental run re-embeds only
  changed files. If sparse retrieval is off (the default), nothing to do.
- **`nomic-code` needs no reindex, because no `nomic-code` index can exist.** The provider
  could never construct, so there are no stored vectors to invalidate. Users who want it must
  reinstall to pick up `einops`: `pip install -U 'trelix[nomic-code]'`.
- **`bge-code` vectors change.** The provider is EXPERIMENTAL and its query embeddings were
  degenerate before and after, so no retrieval-quality claim is affected either way. Reindex
  if you have an index built with it.
- No dependency floors moved. `trelix-mcp` still requires `trelix>=3.1.5`; both adapters
  still require `trelix>=3.0.0`.

### Tests

- `tests/unit/test_sparse_padding_contamination.py` — nine tests, all mutation-verified:
  dropping `* mask` from the aggregation fails five of them and leaves the equal-length
  control passing, which is what localises the cause to padding. Includes an offline
  real-weights arm gated on the cached snapshot, and three fixture self-checks, because the
  existing `test_sparse_embedder.py` fakes all return `attention_mask=torch.ones(...)` — an
  all-ones mask makes the masked and unmasked aggregations identical by construction, so all
  ten of those tests passed either way.
- `tests/unit/test_provider_prompt_provenance.py` — asserts the invariant the prompt bugs
  violated rather than the instances: each prompt constant matches what its own model
  publishes, and appears in exactly one provider. The cross-provider check parses the AST
  rather than searching text, so a comment explaining the historical bug does not trip it
  while a real string literal does; a self-test pins that distinction, since an AST walk that
  silently returned nothing would make the check pass for every input.
- `tests/unit/test_embedder_nomic.py` — the two prefix tests are replaced. They asserted
  `called_texts[0].startswith(_DOC_PREFIX)`, taking their oracle from the code under test, so
  they could not fail for any prefix value. The replacements record the actual `encode` call
  with a plain class rather than a `MagicMock` — a mock answers to any kwarg name and cannot
  tell an absent prompt from a misspelled one.
- The `nomic-code` extra is now installed by the `ci.yml` unit job, and
  `test_readme_install_commands.py` asserts the extra declares `einops`. Without both, the
  `einops` fix shipped with nothing that would fail if the requirement were unresolvable or
  the declaration were deleted: no CI job installed the extra, so pip never resolved it. pip
  resolution is the positive control. Neither half can prove the provider *constructs* —
  that needs the model weights, which CI does not download — so the claim they support is
  exactly "the extra resolves and `einops` is importable", and the release makes no stronger
  one.

## [3.1.7] — 2026-08-22

### Changed

- **Retracted: `bge-code` does not "work now". v3.1.6's dimension fix unblocked a
  degenerate path, and the provider is marked EXPERIMENTAL.** v3.1.6 correctly found that
  `BGECodeEmbedder.dimension` raised `AttributeError` on every real install and fixed the
  width, but the framing that followed — that `bge-code` could then index and query — was
  wrong. What the fix unblocked was a provider that pools the wrong token.
  `from FlagEmbedding import FlagModel` is the alias `from .base import BaseEmbedder as
  FlagModel` (FlagEmbedding 1.4.0, `inference/embedder/encoder_only/__init__.py:1`): the
  ENCODER-ONLY `BaseEmbedder`, `DEFAULT_POOLING_METHOD = "cls"`
  (`encoder_only/base.py:38`), `__init__` default `pooling_method: str = "cls"` (`:50`,
  assigned `:76`), and `pooling()` for that method is `return last_hidden_state[:, 0]`
  (`:302`). `BGECodeEmbedder.__init__` passes no `pooling_method`. But `BAAI/bge-code-v1`
  is a causal Qwen2 decoder — `config.json` `architectures: ["Qwen2Model"]`, `model_type:
  "qwen2"` — published with `1_Pooling/config.json` `pooling_mode_lasttoken: true` and
  `pooling_mode_cls_token: false`; the model card's own examples use `FlagLLMModel` with
  `trust_remote_code=True`, or `last_token_pool` directly. Position 0 of a causal decoder
  cannot attend forward, so a CLS vector depends on token 0 and nothing else. Measured
  against a randomly initialised `Qwen2Model` from a small `Qwen2Config` (no weights)
  pooled by the real `FlagModel.pooling`: two sequences identical in token 0 and
  different in every later token gave **cosine 1.0, max|diff| 0.0** — bitwise identical —
  while the same hidden states through FlagEmbedding's real `last_token_pool` gave cosine
  0.10 and through the real `mean` branch 0.65, and changing token 0 alone moved CLS to
  cosine -0.015. Across 200 resamples of every token after position 0, position 0's
  output never moved: the loss is total, not partial. Queries are worst — `encode_queries`
  prefixes all of them with the same instruction via `get_detailed_instruct`, and
  `tokenizer_config.json` has `add_bos_token: false` / `bos_token: null`, so token 0 is
  the shared prefix and **every query embedding is identical**. Documents are not all
  identical but collapse by first token: 5 distinct chunks sharing token 0 produced 1
  distinct vector, against 5 for `last_token_pool`. No kwarg fixes it —
  `FlagModel(..., pooling_method="last_token")` raises `NotImplementedError`
  (`encoder_only/base.py:308`). The correct fix is `FlagLLMModel`, which requires
  `trust_remote_code=True` and validation against real weights, and is **deliberately
  deferred**. Meanwhile `bge-code` is documented EXPERIMENTAL and unfit for retrieval, and it
  now logs a WARNING on construction — docs alone do not reach a user who never opens
  `PROVIDERS.md`, and the failure is otherwise silent: nothing raises, because
  `resolve_trust_remote_code(False, …)` returns False without error and the builtin
  `Qwen2Tokenizer` loads fine. The recommended offline alternative is **`local`**
  (all-MiniLM-L6-v2), where sentence-transformers reads the model's own
  `1_Pooling/config.json` rather than assuming a method — **not** `local-code` or
  `nomic-code`, which this same release marks EXPERIMENTAL for their own protocol
  mismatches (below). For API-based accuracy, `voyage` is unaffected. This shipped in **28 tagged releases** — every tag from v2.0.0 to v3.1.6 contains
  `793c42b`, the commit that introduced the embedder — and stayed green in all of them
  because every test in `tests/unit/test_embedder_bge.py` replaces `FlagModel` with a
  `MagicMock` or a stub, so no test ever executes `pooling()`. (An earlier draft said
  "four releases", a figure with no anchor behind it.)

- **`local-code` and `nomic-code` are also marked EXPERIMENTAL: each wrapper sends a
  different encoding protocol than its model publishes.** Checked against the model
  repositories, not against our own docstrings. `local-code`
  (`Salesforce/SFR-Embedding-Code-2B_R`) omits the query instruction its card requires —
  `LocalCodeEmbedder.embed_query` is `return self.embed([text])[0]`, i.e. that provider
  encodes queries and documents identically, while the card passes
  `prompt=query_instruction_example` for queries and leaves passages unprefixed. (Cited by
  symbol, not line: an earlier draft of this entry said `BaseEmbedder.embed_query` at
  `base.py:494-495`, which was true against the v3.1.6 tree and wrong by the time it
  shipped — this release's own diff to that file moved the body +34 lines, and the shared
  `BaseEmbedder.embed_query` is an `@abstractmethod` that encodes nothing.) `nomic-code` prefixes `search_document: ` / `search_query: `,
  which are a *different* Nomic model's task prefixes; `nomic-ai/CodeRankEmbed` publishes one
  instruction, `Represent this query for searching relevant code: `, in its own
  `config_sentence_transformers.json`, with code unprefixed. Neither is fixed here: a
  protocol change silently invalidates every existing index built with that provider, so it
  needs its own release with a migration note. `src/trelix/embedder/base.py`'s module
  docstring now defines EXPERIMENTAL precisely and lists all three — it previously said
  "seven" and listed seven while `make_embedder` had dispatched nine since v2.

### Fixed

- **Two of the nine providers could not be started by following the documentation.**
  `local-code` and `nomic-code` both route through `load_remote_code_model`, which refuses
  unless `TRELIX_ALLOW_REMOTE_MODEL_CODE` is set — a variable that appeared in exactly two
  source files and in no doc, README, CHANGELOG or config example. Running the real
  `make_embedder` for either raised `RemoteModelCodeNotAllowedError`. Compounding it for
  `local-code` specifically — `nomic-code`'s extra is real and installs correctly — the
  documented install `pip install trelix[local-code]` (`docs/PROVIDERS.md`,
  `docs/USER_GUIDE.md`, `.env.example`) names an extra `pyproject.toml` does not declare, and
  pip treats an unknown extra as a warning rather than an error — so the advertised quickstart
  for both providers silently installed nothing and then refused to run. Both now documented.

- **The pooling regression test would have been theatre without a CI change.** The unit job
  installed `.[local,otel,sso,dev]` and `bge-code` is deliberately excluded from `all`, so
  FlagEmbedding was absent from every job that runs pytest — confirmed by blocking it at
  `sys.meta_path`, where the new tests report `SKIPPED (bge-code extra not installed)`. A skip
  is reported inside a green check and is indistinguishable from a pass, which is the exact
  failure mode the test exists to close. `ci.yml` now installs `bge-code` in the unit job
  (torch, transformers and sentence-transformers were already present via `local`; the
  resolver adds 24 further packages). Measured CI impact on the job that matters: the four
  Python test legs went from a 5m23s mean to 5m30s — +7s, inside run-to-run noise, and the
  3.11 leg got faster. An earlier draft called it "~22 MB of pure-python wheels"; both
  halves were wrong. `FlagEmbedding` requires `datasets`, which requires `pyarrow>=21.0.0`
  — 118.6 MB on disk here with 37 compiled extension modules. The wall-clock number above
  is the one that was actually measured; the byte count never was. The two degeneracy tests are `xfail(strict=True)`: they document
  today's bug, and the day someone switches to `FlagLLMModel` they XPASS and fail, forcing the
  fix to be acknowledged rather than absorbed.

## [3.1.6] — 2026-08-22

> **Annotation added in 3.1.7. The entry below is the shipped 3.1.6 text and is unchanged.**
> The `bge-code` fix recorded here is correct as far as it goes — the `AttributeError` and the
> 768 default were both real — but removing that raise made a degenerate pooling path
> reachable for the first time, so it replaced a loud failure with a silent one. It did not
> establish that `bge-code` works. `bge-code` is marked **experimental** as of 3.1.7; see that
> entry.

### Fixed

- **`bge-code` could not index or query anything: `AttributeError` before Phase 1, and the
  width it advertised was wrong underneath that.** `BGECodeEmbedder.dimension` called
  `self._model.get_sentence_embedding_dimension()`, a method FlagEmbedding has never had —
  absent from every class in the 1.2.11, 1.3.5 and 1.4.0 sdists, with no `__getattr__` on
  `AbsEmbedder` or `FlagModel` to forward it. `Indexer.__init__` reads that property to size
  the vec0 table (`indexer.py:388`) and `Retriever.__init__` reads it to arm `DimensionGuard`
  (`retriever.py:262`), so every `bge-code` index and query died there. The unit test covering
  the property passed only because a `MagicMock` answers for any attribute asked of it — the
  green test was the reason nobody noticed. Behind the raise sat a second wrong number:
  `bge_code_dimensions` defaulted to 768 while `BAAI/bge-code-v1` emits 1536 (`config.json`
  `hidden_size: 1536`, `1_Pooling/config.json` `word_embedding_dimension: 1536`), and nothing
  narrowed it — `truncate_dim`, FlagEmbedding's Matryoshka knob, was never passed. Had the
  property returned 768 the vec0 table would have been created `FLOAT[768]` and Phase 3 would
  have aborted with `PartialIndexError … Expected 768 dimensions but received 1536`, leaving
  an index of zero vectors with 768 already stamped into `index_metadata`. `dimension` now
  reads the loaded model — `truncate_dim` first, then the HF config's `hidden_size`, then the
  configured value, so it cannot raise — and the default is 1536. No migration: because the
  property raised before `make_vector_store` ran, no `bge-code` index has ever been built, so
  nothing existing changes width. Switching a pre-existing 768-dim index (`nomic-code`) to
  `bge-code` now raises the intended `DimensionMismatchError` with its `migrate-vectors
  --reset --provider` instruction instead of `AttributeError`. Pinned by a plain stub class
  carrying FlagModel's real attribute surface, which a `MagicMock` cannot fake past.
  `docs/architecture.md`, `docs/PROVIDERS.md`, `docs/FAQ.md` and `docs/GLOSSARY.md` corrected
  to 1536; `docs/USER_GUIDE.md` and `docs/WHY_TRELIX.md` already said 1536.

- **`build_knowledge_graph` (MCP) reported `concept_count` with no coverage, so an agent
  got the exact misreport v3.1.5 fixed for humans.** Extraction is capped at the 200 most
  central symbols (batches of 20, at most 10 paid LLM calls); on this repo's own
  12,184-symbol index that is **1.6%**, so the count describes a sample, not the
  repository. v3.1.5 gave humans `Concepts : 47 (from the 200 most central of 12184
  symbols — 1.6%)` and gave `--json` `concept_symbols_considered` /
  `concept_symbols_total`, but `packages/trelix-mcp/src/trelix_mcp/server.py` still
  returned the bare count and its docstring — which is the text FastMCP hands an agent as
  the tool description — named neither the cost nor the bound. The tool now returns both
  counts and the docstring states "PAID: up to 10 LLM calls over the 200 most central
  symbols". Additive at the data layer: `GraphBuildResult` has carried the two fields
  since v3.1.5 (`src/trelix/graph/builder.py:44`), and added response keys are compatible
  under the **Stable** "MCP tool signatures" row of `docs/BACKWARDS_COMPATIBILITY.md`,
  which forbids removals. Unlike the CLI's `if concepts:`, the keys are emitted
  unconditionally: `0`/`0` beside `concept_count=0` is the only thing that distinguishes
  "extraction never ran" from "it ran over 200 symbols and found nothing".
  **`trelix-mcp`'s floor goes `trelix>=3.1.2` → `>=3.1.5` in the same change**, on
  measured absence rather than on the stamp: `git show v3.1.4:src/trelix/graph/builder.py`
  has neither field on `GraphBuildResult` (0 hits at v3.1.2, v3.1.3 and v3.1.4; 7 at
  v3.1.5), so at those three published cores the tool would raise `AttributeError` and
  return nothing at all. Two `server.py` citations in that same comment block were
  re-measured (`767`→`787`, `858`→`878`) because this edit moves them. The shared test
  mock had to be fixed here too, not as tidying: it is a `MagicMock`, so its auto-created
  attributes are not JSON-serializable and `test_the_payload_fits_in_a_sane_budget` fails
  with `TypeError: Object of type MagicMock is not JSON serializable` on the code change
  alone. The REST API does not share the gap — all four `/graph*` endpoints in
  `src/trelix/api/app.py` pass `extract_concepts=False` and `GraphStatsResponse` has no
  concept field, so HTTP has no concept surface to misreport (it has no way to *request*
  extraction either, which is a separate feature gap).

## [3.1.5] — 2026-08-21

### Fixed

- **The release workflow could not check out a tag, so v3.1.5's first tag published nothing.**
  `verify-version`'s checkout requested `fetch-tags: true` on an otherwise default — therefore
  shallow — fetch. When the triggering ref is itself a tag, `actions/checkout@v4` builds the
  refspec `+<sha>:refs/tags/<tag>` and, with tags also requested, writes the tag ref to that
  same destination: `fatal: Cannot fetch both 1e1a66fc… and refs/tags/v3.1.5 to
  refs/tags/v3.1.5`. Checkout retried three times, the job died before a single step ran, and
  all four downstream jobs skipped — so the gate added to protect the CHANGELOG date instead
  blocked the release outright. Nothing was published, and the tag was re-cut after this fix.
  Both other checkouts in this repo that set `fetch-tags` pair it with `fetch-depth: 0`, and
  `ci.yml`'s comment states the reason in as many words; the broken step cited that precedent
  while dropping the half that makes it work. It had also never executed before: the gate
  merged after the 3.1.4 release branch was cut, so v3.1.4 ran the previous file. Now pinned
  repo-wide by `TestCheckoutCanActuallyFetchTheTag` — a static check, because reproducing this
  needs a tag-shaped ref and no local run can produce one.

- **A local `python -m build` produced a 158 MiB sdist containing a 221 MB index database and
  2,479 query-trace files whose filenames are the query text — and `twine check` passed it.**
  Root `.gitignore` has `.trelix/`, which does not match a *renamed* index directory, so
  `.trelix.bak-selfindex/` (329 MB on this checkout) is hidden from git only by its own nested
  `.gitignore` containing `*` — and hatchling does not honour nested `.gitignore` files. That
  is the same mechanism already documented in `pyproject.toml` for `.vscode-test`; the fix had
  been applied to that one case only. Published artifacts were never affected, because CI
  builds from a fresh checkout, but the *documented local pre-flight* (`make build` then
  `make check-dist`) produced the polluted tarball and reported it clean, one `twine upload`
  from publishing an index and a list of someone's queries. `**/.trelix*` added to the sdist
  exclude list.

- **The Helm chart's own `version` had not moved for three consecutive releases, and four
  reader-facing documents still called 3.1.2 the latest release.** `Chart.yaml` held
  `version: 0.2.0` while its `image.tag` default changed again — breaking the rule its own
  comment states — so charts deploying 3.1.3, 3.1.4 and 3.1.5 were all stamped 0.2.0; now
  0.2.1. `verify-version` checks twelve stamps and no prose, so drift accumulated in the
  places a reader *acts on* a version: `.github/SECURITY.md`'s Supported Versions table (which
  tells users where security fixes land), `docs/FAQ.md`'s copy-pasteable four-way `==` pin
  block, the bug-report template's placeholder and "I am using the latest release (X)"
  checkbox, and `helm/trelix/README.md`'s `image.tag` row — which asserts of itself that it
  "always equals `Chart.yaml`'s `appVersion`". `packages/trelix-mcp/README.md` also opened
  "MCP server for trelix v2.12.0", eight releases stale, in a **PyPI long description**. All
  corrected and pinned by `tests/unit/test_docs_version_claims.py`, which reads the shipping
  version from `pyproject.toml` and holds each site to it. Historical references ("before
  v3.1.2", "through v3.1.1") are deliberately untouched, and doc *header* stamps are left for
  a follow-up: a reader does not act on those.

- **`trelix-mcp` declared `trelix>=2.8.0` while calling five core APIs that do not exist at
  that version, so `pip install trelix-mcp` could resolve a core it cannot run against.**
  The binding requirement is `Database.get_symbol_ids_for_file_id` (`server.py:508`), first
  shipped in **v3.1.2**; also `plan_from_intent_hint` (v2.10.0) and three federation APIs
  (v2.8.1). Established by grepping each symbol across every released tag, not by reading
  release notes. The floor had been false since v2.8.1 and is already published that way in
  trelix-mcp 3.1.4, where a resolver free to pick core 2.8.0 leaves every `search_code` call
  failing on a missing attribute. Now `trelix>=3.1.2`, with the newest requirement named in
  a comment beside it. Raised to what the imports demand — **not** to the current version:
  lockstep governs the version stamp, not this floor. Both adapters keep `trelix>=3.0.0`,
  which their own imports still satisfy.

- **`trelix graph --concepts` spent every one of its paid LLM calls on the ten
  earliest-indexed files — on this repository, entirely `.github/` and `.devcontainer/`
  metadata — and reported a count that read as a property of the whole repo.** Extraction
  is capped at 200 symbols in batches of 20 — a real bound, worth ≤10 LLM calls — but it
  sliced whatever order `iter_all_symbols_with_files()` returned, and that query has **no
  `ORDER BY`**. Measured on this repo's own index (read-only, `mode=ro`): 12,184 symbols,
  of which 200 (**1.6%**) were processed. The query plans as a plain `SCAN s`, so those 200
  were simply the lowest symbol ids — **2..226**, drawn from just **10 files**, every one of
  them repository metadata: issue templates (124 symbols across four of them),
  `dependabot.yml`, `devcontainer.json`, a workflow, `PULL_REQUEST_TEMPLATE.md`,
  `FUNDING.yml`, `SECURITY.md`. Not one line of `src/`. So the concepts described the issue
  templates. Meanwhile the PageRank centrality that identifies the most important symbols
  was computed **two steps earlier in the same function** and ignored. Symbols are now
  ranked by that centrality with a symbol-id tiebreak (so equal-centrality symbols cannot
  reshuffle if the DB order ever changes) before the cap applies; truncation logs a WARNING — not
  INFO, since the CLI's default level is WARNING and an INFO line is invisible without
  `-v`, which is how this went unnoticed; `GraphBuildResult` carries
  `concept_symbols_considered` / `concept_symbols_total`; the human output reads
  `Concepts : 47 (from the 200 most central of 12184 symbols — 1.6%)`; and `--json` gains
  the two counts additively, under the same rule the visualization keys already follow.
  The `--concepts` help text now states the cost and the bound at the point of decision:
  "paid: up to 10 LLM calls over the 200 most central symbols; requires an LLM API key".
  Pinned by 8 tests. Two of them exist because mutation testing caught the *tests* rather
  than the code: the first fixture made `fn_0` the hub, putting maximum centrality at the
  lowest symbol id where DB order already agreed, so every ordering test passed with the
  fix reverted; and dropping the id tiebreak passed too, because `sorted` is stable and
  two builds in one process see the same DB order. The fixture now places hubs at the
  highest ids, and the tiebreak is verified against a deliberately reversed DB order.
- **`trelix eval` reported retrieval scores without saying which pipeline produced
  them, so the same golden set against the same index scored differently depending on
  whether a credential happened to be exported.** `rerank` defaults to `true` and
  `rerank_provider` to `cohere`; with no `COHERE_API_KEY` the reranker logs a warning
  and hands back the unranked head. The results table showed nDCG@10 / Recall@10 / MRR
  and nothing else, so a reader attributed the number to a Cohere-reranked pipeline that
  had not run. Measured on the 10-query `mini_repo` fixture: nDCG@10 **0.9631** un-reranked
  against **0.9131** reranked, MRR 0.9500 against 0.8833 — a gap larger than most changes
  anyone measures with `trelix eval`, and `docs/WHY_TRELIX.md` tells readers to validate
  feature flags with exactly this command. Two of those runs printed **identical scores**
  with no way to tell them apart. Every provider now reports whether it actually applied
  and why not, the verdict rides back on `RetrievedContext.rerank`, and the table carries
  a `Rerank` row: `cross_encoder`, `disabled`, `cohere (skipped: no API key)`, or
  `MIXED across queries — 3/10 applied: …` when a run used more than one pipeline, which
  is deliberately not collapsed to a single name. `xtr` reports `applied=False` even on
  its success path, because that path re-sorts by the score each result already had and
  never reads the query. `rerank()`'s existing contract is unchanged — it still returns a
  bare list for all 33 pre-existing call sites — every one of them a test, since the single
  production caller is the one that moved to the outcome-returning form; it is available as the new
  `rerank_with_outcome()`. One limit stated rather than glossed: for `plaid`,
  `applied=True` means *dispatched*, since `PlaidReranker` has three internal fallbacks
  of its own that are not visible from outside. Pinned by 15 tests, each verified by
  mutation — including one that closed a real hole, since deleting the line that attaches
  the verdict to the context previously passed all 186 tests in the touched suites.
- **`docs/PROVIDERS.md` told users holding a partial index that `trelix watch` could not
  repair it. Its startup pass does — and bills for it.** The recovery section said
  "`trelix watch` will not do it — it only re-indexes files as they change, and never scans
  the store for holes", and `src/trelix/indexing/indexer.py` carried the same claim as a
  source comment ("`trelix watch`, which deliberately never reconciles"). Both are true of
  the **watching phase** — `FileWatcher` calls `index_file()` per changed file, with no
  repo-wide diff — and false of the **startup pass**, which calls `Indexer.index()` and so
  reaches the same reconcile that diffs the vector store against the `chunks` table.
  Measured on a 7-file fixture with the local embedder: up to date with no holes, "Nothing
  to index" and **0 chunks embedded**; up to date with 3 vectors deleted, "Repairing 3
  chunk(s)…" and **3 chunks embedded**. So a user who followed that paragraph was told the
  wrong thing in the direction that costs them a step, and a user who ran `watch` expecting
  it to be passive got a paid repair with no warning — its help text was the single line
  "Watch repo for changes and auto-update index", which mentioned no startup index at all.
  All three sites now state the distinction, and the help text names all three cost cases
  (free when current, a repair when holed, a full index when never indexed). Pinned by 5
  tests, each verified by mutation. The behavioural one reads the call order out of the
  AST rather than invoking the command: a first attempt drove `watch` through `CliRunner`
  and hung the suite until it was killed, because patching the watcher does not stop the
  command's own wait loop.

- **Three docs promised that `trelix query` and `trelix search` make no LLM calls; with a
  chat credential set they make one per distinct query.** `docs/FAQ.md` told readers the
  command runs "without calling an LLM", "works fully offline", "returns deterministic
  results", and to "use it in CI scripts"; `docs/GETTING_STARTED.md` summarised it as
  "no LLM — fast, offline, deterministic"; `docs/WHY_TRELIX.md` said `search` is
  "completely offline" with local embedders. Measured: with no chat credential retrieval
  makes **zero** calls — the planner is still constructed unconditionally, but holds no
  usable client and short-circuits to `default_plan()` — so the promise held for the
  case those docs had in mind. With one set, `QueryPlanner.plan()` draws a plan via
  `tool_call`, **one call per distinct query**. Because the draw lives in
  `Retriever.retrieve()` rather than in the `query` command, it applies to every
  retrieval consumer, `search --json` included. `--provider local` does not prevent it:
  that selects the embedder, while the planner reads the chat credential independently —
  so a CI box holding a key for `trelix ask` was paying here too, and getting
  non-deterministic plans, while three docs said otherwise. No synthesis was ever
  performed, and a failed draw still falls back to `default_plan()`; the defect was the
  published claim, not the retrieval result. All three sites now state the condition and
  name the two measured remedies: withhold the chat credential, or record and commit a
  plan cache via `TRELIX_RETRIEVAL_PLAN_CACHE_FILE`, which is record-then-replay — the
  first pass draws once, every later pass draws nothing. Pinned by five tests in
  `tests/unit/test_planner_llm_call_count.py` that count real attempts through the real
  client factory (only the outbound methods are stubbed, so the "is there a client at
  all" decision under test is never faked), each verified by mutation.

## [3.1.4] — 2026-08-21

### Security

- **The `trelix audit` read commands wrote to the databases they read, and could
  report an intact chain about a file that was not an audit log.** `list`, `verify`
  and `export` used the same store constructor as the writer, which runs
  `CREATE TABLE IF NOT EXISTS`. Pointed at any other SQLite file they *added the
  audit schema to it* — one measured case went from 8 KB and one table to 32 KB and
  five — and then reported `Audit chain intact.` at exit 0, because the chain they
  had just created was empty and therefore consistent. A zero-byte file went from 0
  to 28 KB the same way. A CI integrity gate aimed at the wrong path passed green
  and mutated the file it was aimed at. All three commands now open
  `file:<path>?mode=ro`, run no DDL, and exit 2 unless `audit_log` and `audit_meta`
  are already present. Pinned byte-for-byte — file sha256, `user_version`, every
  `sqlite_master` name, and the absence of sidecar journal files — on a clean log, a
  tampered log and a foreign database. The claim is narrow on purpose: `trelix
  serve` with auditing enabled still creates `audit.db`, runs its DDL and holds a
  write lock. Only the read commands cannot.
- **Anything that could write the audit log could crash every command that reads
  it.** `CAST(x'FFFE41' AS TEXT)` keeps TEXT storage class while holding bytes
  sqlite3 cannot decode, so the exception fired inside `fetchall()` — one layer
  *below* the anchor validation written to judge exactly this. The validation was
  right and in the wrong place; the plain-BLOB case was already handled correctly,
  which is what made it a placement bug rather than a logic bug. Measured: 61
  tracebacks across 648 real CLI invocations, and 114 raises across 226 direct
  `verify()` calls, all one root cause. Reads now go through a `text_factory` that
  hands back raw `bytes` for an undecodable cell, so the value reaches the checks
  that exist: `anchor_corrupt` in `audit_meta`, a row fault in `audit_log`. Legitimate
  values are byte-for-byte unaffected. `export` separately died on any BLOB with
  `TypeError: Object of type bytes is not JSON serializable`, mid-stream, losing the
  rows it had already written; it now serializes with `default=str`, mirroring
  `_canonical_hash`. **No audit command can be made to exit on a traceback by
  editing the data it checks.**
- **A total wipe of the audit log is now detected — the sloppy one.** Four places
  claimed an emptied `audit.db` was "byte-indistinguishable" from a legitimately new
  one. It is not: `audit_log.id` is `AUTOINCREMENT`, so SQLite keeps a
  `sqlite_sequence` high-water mark and `DELETE` does not reset it. Zero rows with
  `seq > 0` is a state normal operation cannot produce, and `verify` now reports it
  as `log_emptied`. Nothing is written to achieve this and no schema is added — the
  row was already in the file; this is not a genesis or origin marker. **It closes
  carelessness and nothing else, and the docs now name the four defeats that all
  still work**: clearing `sqlite_sequence`, zeroing or forging `seq`, setting `seq`
  below the real row count, and removing the table via `PRAGMA writable_schema=ON`
  (plain `DROP TABLE sqlite_sequence` is refused by SQLite). Absence of the row is
  deliberately *not* a finding, because it is exactly what a never-appended database
  looks like. Two look-alikes are pinned as clean: a rolled-back append leaves no
  `seq` row, and a restored `sqlite3 .dump` legitimately carries a **duplicate**
  `sqlite_sequence` row, which a check written as "exactly one row and
  `seq == COUNT(*)`" would have called tamper. This **will** become a false positive
  when retention pruning lands — `TRELIX_AUDIT_RETENTION_DAYS` is accepted but
  unimplemented and nothing in `src/` deletes audit rows today, a premise now pinned
  by a test — so whoever implements pruning has to revisit the check.
- **A damaged audit database was reported as a tampered one.** A corrupted b-tree
  page leaves the file openable and makes the first row read raise
  `sqlite3.DatabaseError`; that surfaced as a Python traceback and exit **1**, which
  is the tamper exit code, with none of the tokens an alert matches on. Restoring
  from backup and hunting an intruder are different first moves. All three commands
  now exit **2** with `Could not read audit database` and name what SQLite reported.
- **`trelix audit verify` treated a missing integrity anchor as an absence of
  information rather than as a fault.** The audit chain is checked against a `count`
  and `head_hash` pair in `audit_meta`, and both comparisons were skipped when the
  value was not there — so a log whose anchor had been removed reported *intact* and
  exited 0, and removing the anchor required no hash computation. `append` writes the
  entry and both anchor rows in one transaction, which makes a non-empty log with an
  incomplete anchor a state normal operation cannot reach: `git log` on
  `src/trelix/audit/store.py` is a single commit and both anchor keys are in that
  first version, so this has no legitimate producer and no false-positive surface,
  legacy databases included. Verification now requires **both** values to be present
  and well-formed. A malformed value is reported as a finding rather than trusted or
  raised — parsing lived in the read path, so one edited character used to end the
  command in an unhandled traceback, denying an incident responder the tool they
  reach for first. A brand-new, empty `audit.db` has no anchor rows and still
  verifies clean at exit 0.
- **The audit documentation overstated what an attack costs, and now states the
  boundary.** `docs/AUDIT.md` and the `trelix.audit.store` docstring claimed tampering
  required recomputing every subsequent `entry_hash`. That is true only of a content
  rewrite. Both now carry a per-shape table of what is and is not detected, with the
  attacker's hashing cost for each: five shapes are **not** detectable in-DB, three of
  them without computing a single hash. An in-DB anchor can only ever detect
  *incomplete* tampering, and closing the gap needs the head hash exported off-box,
  somewhere the attacker does not control, and compared later. **Nothing in trelix
  does that**, and this release does not add it. Every row of the table — including
  every "not detected" row — is pinned by a test, so a claim cannot quietly stop
  being true.

### Fixed

- **An interrupted writer made the audit read commands unusable, with a diagnosis that
  described the wrong problem.** `audit.db` uses SQLite's default rollback journal, so a
  writer killed between the journal fsync and its unlink leaves a file that must be
  rolled back before it can be read — and the read-only handle these commands now use
  cannot perform a rollback. That is the intended trade (the previous behaviour
  "recovered" such a file by writing to the very artifact it was auditing), but the
  operator saw only "check the path… and that it is readable" about a path that is a
  perfectly readable file, with the real cause leaking out as a stray log line. `list`,
  `verify` and `export` now report journal recovery as its own condition, still at exit
  2, and name the one-read-write-open remedy — which a test now proves actually works.
  This is exactly when the command matters most: a service was just killed and the
  question is whether entries were lost.
- **`audit list --limit` with a value above SQLite's 64-bit ceiling raised
  `OverflowError` and exited 1** — the code reserved for *the chain is damaged* — on a
  healthy database, with none of the tokens an alert matches on. The limit is now
  clamped, alongside the existing non-positive guard: a value the driver cannot bind is
  a caller mistake, not a finding about the data.
- **The read-only guarantee rested on one untested line.** The `mode=ro` URI is built
  with `Path.as_uri()` rather than string interpolation, because a path containing `?`
  or `#` would otherwise be parsed as URI query or fragment syntax and silently open a
  different file — or none. Reverting that line passed the entire suite, so the property
  everything else depends on had no pin. It has three now, over paths containing each
  character, including one asserting the handle is still genuinely read-only afterwards
  so the escaping cannot be "fixed" by quietly dropping `mode=ro`.
- **Verifying a live `audit.db` reported tamper on undamaged data.** `verify` read the
  rows and then the anchor as two separate statements outside any transaction, and the
  store's `threading.Lock` is per-instance, so it serialized nothing against the
  serving process doing the appending. A legitimate append landing between the two
  reads made the anchor describe one more entry than the rows did — reported as a
  truncated tail. Measured on one writer doing 2,870 appends past 30 verify runs: **24
  of 30 said TAMPERED** about a database an independent walk found perfectly intact.
  Both reads now happen inside one DEFERRED read transaction, so they come from one
  committed state: 0 of 30 after the change, with no append lost and no write to the
  file being audited. This predated the anchor bug above and was the worse of the two —
  an operational condition reported as an attack teaches operators to distrust exit 1.

- **An interrupted index run left permanent holes that re-indexing refused to fill.** Files
  are hash-tracked whole, and a file's content hash is committed in Phase 2 — the sequential
  DB write — before Phase 3 embeds its chunks. Any interruption in between (SIGKILL, laptop
  sleep, a CI timeout, OOM, embedding-quota exhaustion) therefore left chunk rows whose
  vectors were never written, and every later incremental run skipped those files as up to
  date. Measured on a real index: 68,880 chunk rows against 61,652 vectors, so 7,228 chunks
  (10.5% of the index) could never be retrieved, while a re-index reported "Files walked
  3,136 / Unchanged since last index 3,136 / Files to embed 0" and printed "Nothing to index
  — all files up to date." `index_metadata` was emptied by the same kill, which disarmed the
  dimension guard as a side effect: `DimensionGuard.check` early-returns when the stored
  value is not an int, so that index would also have accepted mixed-width vectors.
  `trelix index` now reconciles the vector store against the `chunks` table once per run and
  folds any vector-less chunks into the existing Phase 3, re-embedding **only** the holes —
  not the whole file, which would cost strictly more. This is the crash-recovery counterpart
  to `PartialIndexError`, which covers the case where Phase 3 *raises*; that abort's own
  recovery text is corrected in the next entry, because this reconcile is what made it false.
  Both pipelines heal, at different points in the run: the batch pipeline reconciles before Phase 1
  (which is what withholds the "Nothing to index" claim), while the streaming pipeline has no
  such pre-pass and reconciles after the walk instead — and skips the repair entirely when any
  file failed in the same run, since a chunk this run just failed to embed would otherwise be
  re-sent to the provider that refused it and paid for twice. Watch mode deliberately does not
  heal (a save event on one file is the wrong trigger for a repo-wide scan), which
  `trelix stats` now states under its remedy rather than leaving to be discovered by waiting.
- **`PartialIndexError` told users to delete an index that now repairs itself.** That abort's
  text predates the reconcile above, and it is the only channel there is: `cli/main.py` prints
  `str(exc)` and exits 1, and `index_file()` returns it verbatim as `error`. It still said the
  index "does not heal on the next run" and that the way out was to delete the index database.
  Reproduced end to end: run 1 aborts saying exactly that, and run 2 — a plain `trelix index`,
  nothing else changed — reconciles the holes and leaves none. Following the stale advice
  destroys every embedding that DID land (61,652 of them on the real index) to recover holes
  the re-run refills for the price of the holes alone. The message now keeps the part that is
  still true — this index is PARTIAL *right now*, and `trelix stats` keeps counting those
  chunks as indexed — and points at re-running `trelix index` once the cause is fixed, naming
  `trelix watch` as the command that will not do it and the store location where the partial
  state lives. The docstring's list of load-bearing claims is corrected with it, as is
  `docs/PROVIDERS.md`, which stated the same "does not repair itself" conclusion and the same
  delete-both-stores recovery for the LanceDB backend.
- **The streaming pipeline printed two contradictory WARNINGs back to back.** The coverage
  check announced "Re-embedding them in this run." before either caller had decided anything,
  and the streaming caller then logged "not repairing now, because a chunk this run just failed
  to embed would be re-sent to the provider that refused it" immediately after. The first line
  was false on that path and is the one a user reading top-to-bottom believes. The promise now
  comes from the two callers that actually repair, so each path emits exactly one warning and
  it describes what that run does.
- **`trelix index --dry-run` was silent about id-space exhaustion while `trelix stats` printed
  it in red.** `_repair_cost` excluded ids at or above the sub-chunk offset from the bill,
  which is correct — no real run will embed them — and then excluded them from the output too,
  so the preview rendered "Chunks missing vectors 0 / Repair tokens 0": a clean bill of health
  for chunks that cannot be retrieved at all. It now returns that count and the preview states
  it under the table as a sentence rather than a priced row, because there is nothing to price.
- **The id-space remedy in `trelix stats` was backend-blind.** It said to remove the index file
  to renumber `chunks` from 1; on lance/qdrant the vectors do not live there, so following it
  clears the id-space row but strands every vector the old ids carried. Reproduced on lancedb
  0.33.0: `Vectors with no chunk row` goes 0 → 4 on a four-chunk fixture whose ids had climbed —
  the entire former vector set on a real index — and nothing reclaims those rows. It now names
  the vector store's own location too, the way `PartialIndexError` already did.
- **Chunk rows whose id reached the vector store's sub-chunk offset are no longer treated as
  holes.** Every backend's `stored_chunk_ids()` excludes ids at or above 10,000,000 because
  that is where sub-chunk vectors live, so diffing a flat set of `chunks.id` against it
  reported every row past the offset as missing a vector *forever* — and the repair above then
  re-embedded them on every single run, for money, on a tree with nothing to do. This is
  reachable rather than theoretical: `chunks.id` is `INTEGER PRIMARY KEY AUTOINCREMENT` and
  Phase 2 deletes then re-inserts the chunk rows of every changed symbol, so the counter only
  climbs — roughly 145 full re-chunks of a 68,880-chunk index. `Database.all_chunk_ids()` now
  returns the two id classes separately; the repair services only the ids below the offset,
  and the rest are reported at error level (and as their own `trelix stats` row and remedy)
  as id-space exhaustion. Re-embedding cannot help them in any case — `search()` filters
  their vectors out through `_is_chunk_id` — so they need a re-key, not a re-embed.
- **The embedding dimension is recorded before Phase 3 only when the vector store is empty,**
  and after a successful embed otherwise. Recording early is what re-arms the dimension guard
  on an index whose store is still empty when its Phase 3 dies — "empty" being a
  sentinel-inclusive `count()`, so one Phase 2.5 file-summary vector is enough to make the
  stamp late instead — and over an empty store a wrong stamp costs nothing: no stored vector carries the other width and the `migrate-vectors
  --reset` remedy would discard zero embeddings. Over a store that already holds vectors it
  costs plenty — a repair run whose Phase 3 raised would stamp the new provider's width while
  the vec0 table kept its own (`CREATE VIRTUAL TABLE IF NOT EXISTS` can neither widen nor
  narrow a pre-existing table), locking the *correct* provider out of its own index behind a
  `DimensionMismatchError` whose remedy discards every paid-for embedding. The re-arming
  property survives where it is needed: on a populated index with the correct provider the
  embed succeeds and the late record fires.
- **`SQLiteVectorStore.count()` now takes the connection lock** like every other read on
  that connection. It was the one that did not, against a connection opened
  `check_same_thread=False`.
- **The new report told users to edit a variable that could not have the effect it promised.**
  A directory can be excluded by both tiers — `extra_ignore_dirs` is consulted first and
  `.gitignore` second — so a `packages/` that is listed *and* gitignored is excluded twice.
  The message advised removing the `extra_ignore_dirs` entry regardless, and doing that alone
  changes nothing, because the gitignore tier still excludes it (asserted, not assumed: a test
  now walks that case with the entry dropped and the file is still absent). It now names
  `.gitignore` as the real blocker and offers `TRELIX_WALKER_RESPECT_GITIGNORE=false`, with the
  caveat that this drops every other `.gitignore` exclusion in the repo too. This report exists
  to replace silence about a hidden directory; replacing it with a confident lie would have been
  worse than the silence.
- **`trelix watch` ignored `extra_ignore_dirs` entirely, so it indexed files the batch walk
  cannot reach.** `FileWatcher._should_index` checked `.gitignore`, extensions, filenames,
  size and language — under a comment claiming "Gitignore / directory ignore" — but never the
  directory list, and no per-file rule mentions those names because the walk enforces them
  during traversal instead. In a repo with no `.gitignore` it therefore returned True for
  `node_modules/left-pad/index.js`, and for every edit under `packages/` and `obj/`. A row
  written by the watcher that a walk cannot reach is exactly what `compute_drift` reports as
  `missing` and what `--prune` offers to delete, so a watched monorepo was generating its own
  phantom deletions. `MultiRepoWatcher._should_index` has carried the required ancestor loop
  since `watch-all` shipped; this was the surface that did not, and the two are now pinned
  against one `FileWalker` for every file in a fixture tree. This removes rows rather than
  adding them, so it costs nothing and re-embeds nothing.

### Changed

- **`trelix audit verify` now prints a reason code, and two different sentences.**
  Every tamper verdict used to read "first divergent entry id: `<id>`". That is true of
  a row that is present and wrong, and false of an anchor or count fault, where every
  surviving row verifies and the reported id is the first entry whose *existence* can
  no longer be proven. The second case now says so, and both carry a stable reason
  token (`row_mutated`, `row_mislinked`, `id_gap`, `count_mismatch`, `head_mismatch`,
  `anchor_missing`, `anchor_corrupt`, `log_emptied`) for alerting. `AuditStore.verify()`
  returns that verdict; `verify_chain()` keeps its signature and return type unchanged.
- **`AuditStore` takes a keyword-only `read_only` flag, and exposes `missing_tables`.**
  `AuditStore(path, read_only=True)` opens `mode=ro`, runs no DDL, creates no parent
  directory, and leaves `is_open` false with `missing_tables` populated when the file
  does not already contain both audit tables. The default is unchanged and remains
  read-write, so no existing caller behaves differently.

### Added

- **`packages/` and `bin/` are now detected as source and reported instead of silently
  skipped. The walk is unchanged, so this release costs nothing extra to run.** Those two
  names — plus `obj` — have been in the default `extra_ignore_dirs` since June 2026 (v3.1.1,
  v3.1.2, v3.1.3; this is not a regression) for .NET build output: `packages/` is a NuGet
  restore, `bin/` and `obj/` are MSBuild. They also exclude the source tree of every
  pnpm/npm/yarn/lerna/turborepo monorepo, and every Node CLI's `bin/`, which holds real
  executables rather than build output. Because directory exclusion is enforced during
  traversal, the walk never descends and the index simply contains none of it — while the run
  reports `errors: 0`. Measured across six repositories in one workspace, in **walk-units**
  (files a bare walk yields, i.e. what trelix would actually index after the language, size,
  filename and `.gitignore` filters — the same unit as every control below, and the only unit a
  plan can be sized from):

  | repo | dir | first-party source hidden | indexed today | if the default flipped |
  |---|---|---|---|---|
  | repo A | `packages` | 36 | 598 | 634 (+6%) |
  | repo B | `packages` | 168 | 31 | 199 |
  | repo C | `packages` | 137 | 200 | 337 |
  | repo D | `packages` | 104 | 510 | 614 |
  | repo E | `bin` | 189 (183 `.js`) | 2765 | 2954 |

  Repo A's controls reproduce exactly and are the proof that the exclusion is the only
  difference: its `services/` 265, `apps/` 125, `proto/` 34 and `docs/` 51 ARE indexed. Repo B
  finishes at 31 of 212 tracked files with exactly **ONE file in a code language and 0 call
  edges** — which reads as "this codebase has no call graph" rather than "the source was never
  walked". The sixth repository is trelix itself, and it is the honest limit of requiring
  proof: its own `packages/` has no root workspace manifest, so the probe finds nothing and
  says nothing. The severity was always in the silence, so that is what this release fixes:
  when a
  `packages/` sits beside a workspace manifest (`pnpm-workspace.yaml`, `pnpm-workspace.yml`,
  `lerna.json`, `nx.json`, `rush.json`, or a `package.json` with a `workspaces` key), or a
  `bin/` sits beside a `package.json` whose `bin` field points into it, the walk logs one
  WARNING naming the directory, the evidence file, and the `TRELIX_WALKER_EXTRA_IGNORE_DIRS`
  value that indexes it. WARNING is the CLI's default level, so a plain `trelix index` prints
  it. Nothing about the walk, the files yielded, or the recorded walk-config fingerprint
  changes — **no new files are embedded and no existing index becomes incomparable, so there
  is no bill and no migration.** Making the default index those directories is a separate,
  deliberately later change: it would widen the walk on every repo with a `packages/`
  directory and bill for the difference, and a silent EXPANSION of scope is the same class of
  defect as the silent contraction being fixed here. It ships with the walk-config field
  split and the history collapse that keep `--prune` working across the change.
  - Detection requires POSITIVE evidence, and both branches are load-bearing: one measured
    repo has a marker file but no `workspaces` key, and **three** have the key but no marker
    file at all.
  - `turbo.json` alone is deliberately NOT accepted — it appears in non-workspace repos.
  - A sibling `*.sln`, `*.slnx`, `*.slnf`, `*.csproj`, `*.fsproj`, `*.vbproj`, `*.vcxproj`,
    `Directory.Build.props`, `Directory.Build.targets`, `Directory.Packages.props`,
    `packages.config`, `packages.lock.json` or `NuGet.config` keeps the directory excluded even
    when workspace evidence is also present: the .NET case wins any tie, because re-including a
    NuGet tree is thousands of third-party files priced per token. **All of these are matched
    case-insensitively**, because MSBuild and NuGet resolve them that way and .NET is developed
    on Windows and macOS, where the filesystem does too.
  - A `bin/` with no declaration stays excluded. Absence of .NET evidence is not evidence of
    source, and "index unless proven otherwise" would expand the walk into every virtualenv,
    Go and compiled-output `bin/` in the wild. Requiring proof can only under-include, and
    under-inclusion is now loud while over-inclusion is silent money.
  - `obj` is unconditional and unchanged. Dropping it from the list re-admitted 0 files in all
    six measured repos — but only because none of them has a reachable .NET `obj/` (the
    workspace's only two are a gitignored Go toolchain cache and one inside `node_modules`), so
    that 0 means "untested here", not "measured harmless".
  - Directories inside a package store (`node_modules`, `.pnpm-store`, `.yarn`, `.npm`,
    `.pnp`, `.git`) are never reclassified: a store holds complete copies of other projects,
    manifests included, so evidence found inside one proves nothing. `.pnpm-store` is not in
    `extra_ignore_dirs`, so the walk really does reach inside it.
  - The report follows the NAMES the effective `extra_ignore_dirs` still lists, so customising
    the list does not silence it — only removing the name does, and removing the name is also
    what stops the directory being hidden. A hand-written override is still a choice: dropping
    `packages` (as `scripts/self-index.sh` does) leaves nothing to report about `packages`.
  - The probe costs no extra syscalls during a walk — marker names come out of the directory
    listing the traversal already has, and the one `package.json` read only happens in a
    directory that actually contains a `packages/` or `bin/`.

- **`trelix stats` reports vector coverage in both directions** — chunks with vectors, chunks
  missing vectors, and vectors with no chunk row — and never nets them, because a single
  netted number is what let a 10.5%-blind index read as healthy. It also reports
  `Embedding dimension: not recorded — dimension guard disabled` instead of guessing, which
  makes the second half of the failure above visible before any hole is counted — and reports
  the coverage anyway in that case, on the sqlite backend, through the same read-only
  dimension-free projection `--dry-run` uses. (A missing dimension used to suppress the whole
  coverage block, which is precisely the state a killed run leaves, so the command that exists
  to reveal the holes was blind on the only index that had them. What must never be guessed is
  the vec0 *width* — a projection of `chunk_id` needs none and creates nothing.) lance and
  qdrant still report "not checked" without a recorded dimension: both create on open. Exit
  code is unchanged at 0 in every case, so scripts that pipe `stats` keep working.
- **`trelix index --dry-run` prices the repair.** New `Chunks missing vectors` and
  `Repair tokens` rows, with the repair tokens included in the dollar estimate — a preview
  that under-quotes the run it is pricing is the same class of defect as the bug above. It
  quotes the same set the run will embed, ids past the sub-chunk offset excluded, so it does
  not over-quote either. The check is strictly read-only (`mode=ro` plus `PRAGMA query_only`),
  and reports "not checked (lance backend)" rather than opening a Lance or Qdrant handle, since
  both create on open — which also means the dollar figure is a **lower bound** on those two
  backends, where the repair is not priced at all.
- **`BaseVectorStore.stored_chunk_ids()`**, implemented for all three backends
  (sqlite-vec, LanceDB, Qdrant). Returns real chunk ids with summary and sub-chunk sentinels
  excluded. `count()` cannot answer this question — it is sentinel-inclusive, so
  `count_chunks() - count()` returns holes minus sentinels (405 against a true 500 on a
  fixture, and negative once sentinels outnumber holes); both `count()` docstrings that
  claimed otherwise are corrected.
- **Python 3.14 is tested and advertised.** `requires-python` has always been an open
  `>=3.11`, so pip was already willing to install trelix on 3.14 — but nothing verified it
  and the classifiers stopped at 3.13, so the honest answer to "does this work on 3.14" was
  "nobody has checked". It does: on 3.14.6 with every extra installed, the unit suite
  collects 3256 tests — identical to 3.11 — and all 3256 pass with zero skips, alongside
  102 in `trelix-mcp` and 19 and 10 in the two adapters. The whole dependency tree installs,
  including the four compiled ones that mattered: torch 2.13.0, tree-sitter 0.26.0,
  numpy 2.5.2 and tiktoken 0.14.0 ship cp314 wheels, `tree-sitter-language-pack` ships
  `cp310-abi3` (the stable ABI, so it covers every later version), and `sqlite-vec` ships
  `py3-none-manylinux` because it is a precompiled SQLite extension loaded through ctypes
  rather than a CPython C extension.
- **CI now runs the suite on 3.14** as a fourth matrix leg. This is what makes the
  `python:3.14-slim` base image safe to adopt: the Docker job only builds the image and runs
  `--help`, which cannot detect a stdlib or dependency behaviour change, so without a real
  matrix leg the shipped container would run a Python the suite had never touched.

## [3.1.3] — 2026-08-19

Correctness and security. Four paths returned confident wrong answers, one could delete a
user's files, and four were reachable by an attacker. **Upgrade if you run `trelix serve`, if
you index a repository you do not fully control, or if you have ever passed `intent_hint` or
used `search-all`.**

### Security

- **The REST API's containment check was validated against the caller's own input.** A handler
  resolved a containment root from the request body and then verified the requested path was
  inside it, so a request naming the filesystem root satisfied the check for every file the
  server could read. Setting `TRELIX_API_AUTH_TOKEN` did not close it: there is no
  authorization layer, so any token holder had the same reach. `create_app()` also took no
  parameters, so `trelix serve <repo_path>` could not constrain the application — `repo_path`
  reached only the startup banner. Fixed with one shared dependency validating every
  caller-supplied path against an allow-list captured at application construction, applied to
  every gated route; the test counts live routes programmatically so an ungated route added
  later fails it. Shipped defaults bind loopback, so reaching this required an operator to have
  widened the binding — which `docs/INSTALLATION_GUIDE.md` told them to do, also fixed here.
- **A repository-local `.env` was a live configuration source.** Fifteen settings models
  resolved `env_file=".env"` against the process working directory, in a tool whose input is an
  untrusted directory — so the repository being indexed could supply configuration, including
  the model identifier handed to a loader that executes code from the model repository. The
  loader is now **gated, not removed** (it is required for one shipped model architecture, and
  `local-code` and `nomic-code` remain available), and the gate is read from the process
  environment only. Nothing in trelix calls `load_dotenv()`, so a settings file cannot reach it.
  The CI review workflow, which indexes a pull request's own checkout, no longer does so from
  inside the checkout.
- **Stored XSS in the generated graph HTML.** A markdown heading or a filename in an indexed
  repository became a symbol name or a relative path verbatim and was assigned into
  `innerHTML`. The adversary is any repository trelix indexes that an attacker can write to;
  the victim is whoever opens the generated page. Escaped at every sink, including edge
  endpoints and a second sink that fixing the obvious one would have missed.
- **`trelix taint` reported success for a failed scan.** It exited 0 whenever the scan had
  failed but produced at least one flow. `ScanResult.is_trustworthy` existed with zero call
  sites anywhere in the tree — written and never wired. It now gates the exit code regardless
  of flow count, keeping the carve-out for a missing scanner, since an absent tool is not a
  failed scan.
- **A read route created state.** `/stats` left an index database and its sidecars behind on a
  directory it had merely been asked about, because the absolute-path property called `mkdir`
  as a side effect of being read.

### Fixed — data loss

- **`--prune` could authorise deleting files that exist on disk.** An earlier fix corrected the
  ordering — the guard had compared a run's walk configuration against a copy that same run had
  just written — and left the unsound premise: one global walk-config row was certifying a
  per-file property. Rows written under a wider configuration survive a re-index that narrows
  it, because a re-index deletes no rows, while the provenance write overwrites with the
  current configuration at the end of the run. Snapshot and current then agree, no drift is
  detected, and the surviving rows are indistinguishable from files genuinely deleted. The old
  refusal message advised "re-index, then prune", which is exactly the sequence that creates
  the unsound state. Reproduced before the fix at 12 candidates, all 12 present on disk, under
  the 10% cap, with zero refusals. Now the index retains the set of distinct walk-config
  digests it has been written under and refuses while that set has more than one member —
  chosen over stamping a digest on every row, which would need a schema migration for every
  index already on disk, on the one path where being wrong destroys a user's work.
- **The documented backup ritual poisoned drift detection.** `cp -a .trelix .trelix.bak-*`
  permanently altered the recorded walk configuration, so drift silently stopped working
  afterwards. A backup must not be indistinguishable from a configuration change.
- **`--prune` exited 1 while printing "Nothing to prune"** — the default outcome of the first
  `--prune` on any index. The nonzero exit is now kept only where a refusal actually blocked
  candidates.
- **`read_only=True` was neither read-only nor necessarily the right database.** The SQLite URI
  was built by raw f-string interpolation, so a `#` in the path truncated it as a fragment and
  a `?` opened a second query section: the `mode=ro` parameter was lost and SQLite opened — or
  created — a different file. A write through such a handle succeeded. Now percent-encoded at
  every site. `pytest`'s `tmp_path` never contains a URI metacharacter, which is exactly why
  the existing tests could not fail.

### Fixed — silently wrong answers

- **`intent_hint` disabled retrieval on every intent, over both REST and MCP.** The hint
  builder stamped the direct-answer routing tier onto all eight intents while also setting the
  correct leg strategy; the executor checks the tier first, so the strategy was never read.
  Measured on this project's own codebase: all eight values returned byte-identical output —
  40 README sections, zero code files, no overlap with the correct result set. The tier is now
  paired only with the project-overview intent. **A unit test asserted the defect as correct**
  and has been deleted and replaced with assertions on the retrieval outcome.
- **Federated `search-all` erased an entire repository's results, nondeterministically, while
  reporting `repos_skipped: 0`.** Fusion deduped on a per-database autoincrement rowid, so
  every repository's identifiers start at 1 and always collide; first-seen won, and "first" was
  thread-pool completion order. Now keyed on a globally unique identity. **The existing test
  passed for the wrong reason** — it used distinct identifiers, the one input distribution where
  the bug cannot fire.
- **Python relative imports never resolved.** The resolver split a joined path on `/` while
  Python specifiers are dot-separated. Measured on this repository's own index: JS-style
  specifiers resolved 34 of 34, Python-style 0 of 40, with import rows present and correct but
  unlinked. A direct cause of the low overall call-resolution rate.
- **`trelix stats | head` crashed** rather than exiting quietly when the pipe consumer left
  early. Five CI failures over two days were attributed to flakiness before this was understood
  as deterministic.

### Fixed — measurement

- **`trelix eval` was not repeatable, and the documented cause was wrong.** Measured
  run-to-run noise was sd 0.022–0.029, against sd exactly 0.000000 when planner output is
  replayed from frozen plans — the same score reproduced to sixteen significant figures. So no
  difference below roughly 0.06 nDCG was distinguishable at one run per arm, which is larger
  than the entire measured effect of most retrieval legs and larger than the upper bound on
  repairing the largest known retrieval defect. `eval/README.md` blamed the query and plan
  caches; that was verified false — the golden set's entries are all distinct, so a pass has
  zero possible cache hits. The cause is the planner, which rewrites every query and reproduced
  none of them byte-for-byte. New: `--plan-cache-file` records then replays plans, and a cache
  miss raises rather than silently re-drawing.
- **Two figures in `core/config.py` licensed decisions and were wrong in the same direction.**
  A comment reasoned that a measured gap was "only ~1.4× the measured same-config run-to-run
  noise (0.012)"; the real floor is two to three times that, so the gap is below it —
  indistinguishable, not small-but-real. And a pair of numbers presented as a settled range
  differ by less than 5% of the detection band: one number measured twice.
- **The knowledge-graph BFS retrieval leg is measured harmful** — nDCG@10 −0.208/−0.232 on this
  project's own golden set, replicated across two independent plan draws, several times the
  detection band. Six documentation sites recommended enabling it, including a runnable command
  in the README. They now state the measured effect. The leg remains opt-in and off by default;
  the ranking cause is a raw-score comparison across incomparable scales and is not fixed here.

### Fixed — documentation that did not match the code

- Sixteen published, user-facing claims across the four PyPI long descriptions and the README,
  from an audit that compared every documented config value, CLI flag, packaging claim,
  API/MCP surface element and provider claim against the code defining it: 129 contradictions
  across 119 sites, of which 31 break at runtime. Includes extras that install nothing, a
  provider value pydantic rejects, an MCP tool that is not registered, a golden-set schema key
  the harness never reads, and `[all]` described as half the extras it actually resolves to.
- The doc-stamp procedure in `CONTRIBUTING.md` was scoped so that it never descended into
  `packages/`, which is where the worst rot was. `tests/unit/test_readme_install_commands.py`
  now asserts in CI that every extra a README advertises exists in the owning `pyproject.toml`
  and that no README hard-pins a version.
- Eight figures published by this release's own earlier commits that did not reproduce,
  including a copy-pasteable `git diff` whose glob matched two more packages than the number
  beside it, and a reverse-order test count that could never have been right because reversing
  collection order cannot change how many tests exist.

### Fixed

- **Two README install commands that could never have worked, both live on PyPI.** Each
  distribution's `pyproject.toml` sets `readme = "README.md"`, so those files are the **PyPI
  long description** — the project page a reader copies commands from, not internal notes.
  - `packages/trelix-langchain/README.md` advertised `pip install "trelix-langchain[bedrock]"`
    and `"trelix-langchain[code-embeddings]"`. That `pyproject.toml` has no
    `[project.optional-dependencies]` table at all — PyPI reports `provides_extra: None` — and
    pip treats an unknown extra as a warning rather than an error, so a reader following the
    page silently received the base package. `code-embeddings` does not exist on core either;
    the three real backends are `bge-code`, `nomic-code` and `lance`. Both commands now use
    the two-package form the same file already used correctly six lines below:
    `pip install trelix-langchain "trelix[bedrock]"`.
  - `packages/trelix-mcp/README.md` hard-pinned `trelix-mcp==2.12.0` in **seven** places,
    including the primary command under its own `## Install` heading, while the package
    shipped `3.1.2` — five releases stale. Now unpinned, with the reason stated: all four
    distributions ship on one core tag, so an unpinned install resolves a working pair by
    construction, and pinning belongs in a reader's own `requirements.txt`.

- **The doc-stamp grep had a blind spot exactly where the worst rot was.**
  `CONTRIBUTING.md`'s procedure was scoped `docs/*.md *.md`, which never descends into
  `packages/`, so it could not see any of the seven stale pins above. Scope now includes
  `packages/*/README.md`. A grep with a blind spot reads as coverage, so the properties are
  additionally asserted in CI by `tests/unit/test_readme_install_commands.py`: every extra a
  README advertises must exist in the owning `pyproject.toml`, and no README may hard-pin a
  trelix version. Proven against the defects — 3 failures before the fix (the two nonexistent
  extras, plus the whole-set pin assertion whose single message names all seven pins), 24
  passing after, and re-introducing either defect turns it red again.

- **Fourteen more published assertions the code contradicts.** A five-dimension audit of
  every documented config value, CLI flag, packaging claim, API/MCP surface element and
  provider claim against the code that defines it found **129 contradictions** (132 raised, 3
  refuted on review): 31 that break at runtime, 68 wrong but silent, 30 merely stale. Thirty
  are both published and user-facing. This entry fixes the subset that needs no API decision;
  the rest is tracked separately. Each was confirmed by reading both the claim and the
  contradicting code line, and the replacement values were confirmed by running them.
  - `README.md` — the golden-set schema was published as `expected_file`; the harness reads
    only `relevant_files` and raises `ValueError` on the *whole run*, uncaught by the CLI, so
    a reader following the README got a traceback and no metrics. `expected_file` appears
    nowhere in the codebase.
  - `README.md` — `[all]` was described as resolving to six extras with "the other 17"
    installing separately, and named `serve`, `otel`, `sparse` and `knowledge-graph` as
    outside it. It resolves to **ten**, including all four of those, leaving **13** outside.
    `pyproject.toml:194` documents the widening the README never absorbed.
  - `README.md` — telemetry was documented as writing to `.trelix/telemetry.db`, a file that
    is never created; the rows go to the `query_telemetry` table inside `.trelix/index.db`.
    "Leg hit rates and token usage" are not recorded or rendered at all, and `trelix eval`
    reports Recall@10 only, not `Recall@1/5/10`.
  - `packages/trelix-langchain/README.md` — advertised `lance` as a `TRELIX_EMBEDDER_PROVIDER`
    value, which pydantic rejects at startup; `lance` is a `TRELIX_STORE_BACKEND` value that
    merely shares the name. Also documented `AWS_DEFAULT_REGION` (the real alias is
    `AWS_REGION`, and boto3's own fallback never applies because the region is passed
    explicitly), `TRELIX_RETRIEVAL_TELEMETRY` (no such variable; it is
    `TRELIX_TELEMETRY_ENABLED` on a different settings class), and a FLARE default of `3`
    when `3` is the `le=` ceiling and the default is `1`.
  - `packages/trelix-llama-index/README.md` — advertised a `huggingface` embedder provider,
    a `HUGGINGFACE_API_KEY`, and a runnable command using both. No such provider member,
    field or alias exists; the only `huggingface` string in the tree is a warnings filter.
    Its result example also read `metadata.get("source")`, which is always `None` — this
    adapter writes `"file"` and `"symbol"`, and `"source"` is the *langchain* adapter's key.
  - `packages/trelix-mcp/README.md` — the Tools table listed a tool named `ask`; the server
    registers 15 tools and none is `ask` (`ask_agent` is documented separately, and the
    streaming surface is REST `GET /ask`). `subscribe_resource` was shown taking a list of
    globs; it takes two required strings and has no glob support. And the change notification
    was described as carrying changed file paths and re-index stats when it carries only
    `{uri, _meta.subscriptionId}` — its own docstring says so.

## [3.1.2] — 2026-08-17

### Overview

Shipping as **3.1.2**. No 3.1.2 was ever tagged or published, so everything below — the
self-index findings, the features, and the fixes that arrived on branches after the version
was first stamped — is one release.

Sixteen defects were found by indexing this repository with trelix and then checking whether
each dimension of the resulting index was actually populated. Seven were fixed in the first
pass; the nine documented as "found, not fixed" were worked through in a second, each
researched, adversarially reviewed before implementation, and audited after. Re-auditing the
result then surfaced a further batch, and re-auditing *that* surfaced defects in the fixes
themselves.

The theme is **features that were on and doing nothing**. `.env` enabled file summaries,
PageRank boosting, adaptive query planning and telemetry. The index had 0 file summaries;
the PageRank boost had never once fired; `taint_flows` was empty on a repository semgrep
does find flows in; and the query planner classified every one of 219 recorded queries as
the same one of its eight intents. None of it was visible from outside: each failure path
logged at DEBUG while the CLI runs at WARNING, or was swallowed by a bare `except`, or was
reported as a number nobody had reason to doubt.

Several were found only by running the real thing rather than reading the code — real
semgrep output rather than a hand-written fixture, a real sqlite-vec table rather than an
assumption about what SQL it would accept, a real pty, a real fastmcp, a real lancedb. In
the first two the *obvious* fix was also wrong, and only measurement showed it.

A pattern in the test suite is worth naming, because it is why several survived: **the tests
exercised the paths that worked.** The taint parser was verified against a fixture invented
to match its own misreading. Every planner test supplies no credentials, so none could
notice credentials being dropped. The eval metric tests used unique IDs only, so none could
notice a repeated ID scoring twice. All three MCP prompts failed on use while their 82-test
package suite was fully green. The walker yielded one file 34 times with no assertion
noticing. And one test reloaded the module under test inside a `sys.modules` patch, silently
disabling its deletion path for every later test in the session.

### Security

- **The advertised security-disclosure path reached nobody.** GitHub resolves
  `.github/SECURITY.md` ahead of the repository root, so that file was the published policy —
  and **both** channels it listed were dead. The email was the literal string
  `trelix-security@[maintainer-domain]`, shipped with its own "replace with actual contact"
  note. The route it called *preferred* was equally unusable: private vulnerability reporting
  is disabled on this repository — `gh api repos/sairam0424/trelix/private-vulnerability-reporting`
  returns `{"enabled":false}` — and with it off, only users with write access can open a draft
  advisory, so `/security/advisories/new` gives an outside reporter nothing. Reporting now
  names the maintainer address the root `SECURITY.md` has carried since v1.0.0, and states the
  PVR gap outright, with the command that measures it and the one that enables it.

- **Both supported-version tables were wrong, in different directions, and both promised a
  practice that never existed.** Root claimed `1.x`/`0.7.x`; `.github/` claimed `2.7.x` active
  with `2.6.x` security-only. Neither listed any 3.x release, so the shipping version appeared
  in neither. Across all 34 releases from 0.1.0 to 3.1.2 no patch has ever landed on an older
  line after a newer minor shipped — `2.7.3` preceded `2.8.0`, `2.11.1` preceded `2.12.0`,
  `3.0.1` preceded `3.1.0` — and there are no maintenance branches. The policy now says what
  is true: latest release only, fixes ship as a new version from `main`, with PyPI rather than
  a hand-maintained table as the authority. The two files now own disjoint content — `.github/`
  the reporting policy, root the threat model — because deleting either would break links that
  other files, including two in `src/` and `tests/`, point at.

- **The release-verification example could never have run.** It documented
  `python -m pypi_attestations verify trelix==2.12.0`, which is invalid at any version:
  `verify` takes an `attestation`/`pypi` subcommand and no form accepts a `name==version`
  requirement string. The *claim* it illustrated is real, and was checked rather than assumed —
  `curl https://pypi.org/integrity/trelix/3.1.1/…/provenance` returns a populated
  `attestation_bundles` naming publisher `sairam0424/trelix`, workflow `release.yml`, an
  identity bound to `refs/tags/v3.1.1`, and a Rekor entry with an inclusion proof. Only the
  command was wrong, so only the command changed.

- **Supply-chain scanning existed nowhere** — no dependency audit, container scan, SBOM or
  SAST anywhere in `.github/`, `.pre-commit-config.yaml` or the `Makefile`, for a project that
  publishes four PyPI packages and two GHCR images. And `config/semgrep-taint.yaml` — 6.2 KB
  of real rules, with the `taint` extra pulling semgrep — shipped with **nothing invoking it.**
  Added `security-scan.yml`, and Dependabot went from 3 covered ecosystems to the 8 actually
  built (three npm projects, the Dockerfile, and the two adapter packages `release.yml`
  publishes were all uncovered).

- **`ruff` gained the `S` (bandit) and `B` (bugbear) rule sets**, which were absent from a
  project shipping a security policy.

### Added

- **`trelix index --prune`** — remove index rows for files deleted from the repository.
  Deliberately unbuilt until now: a prune keyed on "files the walk did not yield" reads a
  truncated walk as deletions and deletes embeddings that cost money. It ships only because
  every prerequisite landed — the walk-completeness signal, walk-config recording, and the
  `.gitignore`-contents digest — and it **refuses** unless all five hold: the walk was
  complete, the walk config is comparable, the walk config is unchanged, the index was built
  by this trelix version, and the removal is under a 10% cap. Each refusal names which
  condition failed and how to fix it, rather than reporting a bare "refused". Preview is the
  default; `--yes` is required to act.

  Verified against this repository's live index: **refused**, with two reasons — no walk
  config recorded, and no version recorded — over **35 candidates that are every file under
  `packages/`, all present on disk.** Without the guard a prune would have deleted 35 real
  files.

- **`trelix index --dry-run`** — walk, chunk and count tokens with the real tokenizer, then
  report the estimated embedding spend and exit without embedding anything. Reports "unknown"
  rather than guessing where a provider's rate cannot be established.

- **OpenTelemetry metrics.** Observability was tracing-only: `rg 'get_meter|create_counter'
  src/` found nothing, so with `[otel]` configured you could see that a request happened but
  not what it cost. A meter seam now sits beside the span helpers, gated on the same flag and
  degrading to a true no-op — importing nothing — when the optional extra is absent. Every
  embedder counts `trelix.embedder.requests`, `.texts`, `.characters` and `.tokens` per
  provider and model, since embedding is the only per-call billed operation in trelix. Token
  counts are recorded only where the provider actually reports them.

- **`docs/migration/v2-to-v3.md`** — the guide `BACKWARDS_COMPATIBILITY.md` promised before
  any MAJOR release and which was never written. Its central finding is that the obvious
  remediation is a **silent no-op**: v3.0.1 retracted v3.0.0's "no reindex needed" claim
  because the Python extractor's off-by-one made 8,815 of 8,815 index references wrong, and a
  plain `trelix index` afterwards selects zero files, prints "Nothing to index — all files up
  to date.", exits 0, and leaves the wrong call graph in place. The working command is
  `TRELIX_INCREMENTAL=false trelix index .`, which no CLI flag exposes. Every claimed break
  was checked against the code rather than copied from the changelog — the
  `TRELIX_RETRIEVAL_FLARE_MAX_ITER` removal scheduled for v3.0.0 **did not happen** and the
  alias is still live.

- **`trelix taint --rules PATH`.** `TaintAnalyzer.run()` always accepted a
  `rules_path`; the CLI never passed one, so every invocation ran the `p/default`
  registry pack — network-dependent, and free to change between runs. A missing path is
  an error rather than a silent fallback, because falling back reports registry findings
  under the reader's assumption that their own rules produced them.

- **`config/semgrep-taint.yaml`** — six auditable taint rules scoped to source/sink
  pairs that occur in this codebase. trelix shipped no rules of its own, so there was
  previously no offline route to a taint scan at all.

- **`scripts/self-index.sh`** — reproducible clean self-index. Needed because
  `TRELIX_WALKER_*` and `TRELIX_PARSER_*` are process-env-only, and because
  `EXTRA_IGNORE_DIRS` *replaces* rather than extends the default, so all 30 entries must
  be restated to drop `"packages"` — present for .NET NuGet output, but it also hides
  this repo's own `packages/` monorepo and its three shipped sub-packages. Refuses up
  front on an embedding-dimension mismatch, printing the one remedy that works.

- **`scripts/verify-index.sh`** — asserts that populated dimensions are non-empty *and*
  that unpopulated ones are still empty, each with its reason recorded.

- **`scripts/measure_index_hygiene.py`** — measures what share of the corpus, and of
  actual top-10 results, was never source code. Needs no golden set.

- **`eval/README.md`** — the golden-set format, and the two ways to get a silently
  wrong score from it: paths are compared by exact string equality, and an entry with
  no `relevant_files` is skipped rather than failed.

- **All twelve version stamps now agree, so the `verify-version` gate passes 12/12.** It failed
  3 of 7 when introduced, which was the gate working. The Helm chart *deployed a different
  trelix than it advertised* — `values.yaml`'s `image.tag` was `2.12.0` while `Chart.yaml`
  said `appVersion: 3.1.2`, so `helm install` at defaults ran an image five releases behind;
  `helm template` now renders `:3.1.2`. `packages/trelix-mcp/server.json` carried `2.12.0`
  in both version fields. A `v3.2.0` control still fails all 12, so the gate is fixed at the
  sites rather than defanged; those 7 checks became 12 when both adapters' stamps and
  `trelix_mcp.__version__` joined it (below). `Chart.yaml`'s own chart `version` moves 0.1.0 → 0.2.0: it had not moved across
  the five releases that bumped `appVersion`, so two structurally different charts were both
  stamped 0.1.0.

- **`scripts/verify-index.sh` gated 6 of 31 tables; four counters could fall to zero
  unnoticed.** Proven by injecting all four regressions into a copy of the live index — the
  old 22-gate script exited **0**. The new 26-gate version fails all four and still passes
  clean on the real index. Three `EXPECTED_EMPTY` reason strings also documented bugs that
  are fixed, and one was simply wrong: `generic_edges` is not empty for want of ticket
  references (the linker's own `_walk_log` matches 13 strings across 9 of 871 commits) — it
  is empty because **`trelix index` never runs the linker at all.**

- **`packages/trelix-typescript/src/generated/schema.ts` had silently drifted** to 604
  committed lines against 768 regenerated, hiding shipped server features from the typed
  client: all of `POST /parse`, the `/search` `intent_hint` and `hyde_snippet_hint` params,
  the `/graph/communities` caps, and the auth headers on every gated route. `npm run build`
  and `npm test` both pass against a stale schema, so nothing failed. Regeneration required
  a human because `codegen.mjs` could only fetch from a running `trelix serve`; it now
  defaults to an in-process `create_app().openapi()` dump — 1.37 s for the full codegen, no
  server, no port, no readiness race — which is what makes the new `schema-drift.yml` gate
  possible.

- **`trelix-langchain` and `trelix-llama-index` published as `License: UNSPECIFIED`.**
  Neither declared `license`, `classifiers`, `authors` or `keywords`; only `trelix-mcp` did.
  The LICENSE file was always *in* the wheel, but PyPI renders the field and the classifier —
  verified live against the PyPI JSON API across all 7 releases up to 2.4.0. Both now mirror
  `trelix-mcp` exactly. Both also floored on `trelix>=0.4.0`, **a core release that was never
  published** (the oldest on PyPI is 0.5.0). `workspace-vscode/package.json` had no
  `license` key at all while `vscode-extension-ci.yml` runs `vsce package`.

- **CI could not see six real type errors and ran 29 tests nowhere.** The `lint` job
  installed only `[local,sso,dev]`, so voyageai/google-genai/watchdog were absent and every
  expression touching them degraded to `Any`. The cause was the missing extras, not
  `--ignore-missing-imports`, which is a no-op because pyproject already sets
  `ignore_missing_imports = true`. A new `type-check-extras` job installs them and gates the
  errors as a recorded ceiling keyed on (file, error-code): known debt is green, anything
  outside it fails, and a mypy *crash* can no longer parse as "zero errors" and pass. `ruff`
  now covers `scripts/` and all three `packages/*/tests`. The 19 langchain and 10
  llama-index tests ran nowhere and are now separate invocations — both resolve to module
  `tests.test_retriever`, so a single combined run would silently skip one.

- **Six inert config knobs were documented as working switches**, marked **Inert.** now
  following the existing convention. `docs/GLOSSARY.md` went furthest, claiming
  `TRELIX_FEDERATION_ENABLED=true` "activates federation at retrieval time" — in fact
  `search-all` builds `FederatedRetriever(registry)` with no arguments, so it federates
  whether the flag is set or not, the worker pool is permanently the constructor default of
  4, and `max_repos` stays unbounded so `TRELIX_FEDERATION_MAX_REPOS` never applies on the
  CLI path at all.

- **`.env.example` documented 27 of ~96 `TRELIX_*` aliases** while `CONTRIBUTING.md`
  declares it stable public API. Extended to the whole 3.x surface, grouped, with no real
  secret values.

- **Two governance docs contradicted each other on three rules, and reality matched
  neither.** `BACKWARDS_COMPATIBILITY.md` and `CONTRIBUTING.md` disagreed on the deprecation
  grace period (2 minor versions vs one) and on integration-package versioning (core version
  vs "independent cadence"). Resolved to the stricter grace period — 2 minor versions **and**
  3 months, whichever is later, since v2.4.0 → v3.0.0 was 40 days and the calendar clock is
  the one that binds — and to lockstep versioning, because `release.yml` fires only on core
  `v*` tags and publishes all four dists in one job, so no independent cadence exists to be
  on. The release checklist listed five of the seven sites the gate then checked, and told
  contributors to grep for the *previous* version, which structurally cannot match a site
  stranded on 2.x — as both adapters were, on 2.4.0.

- **Docs: five broken relative links and two false claims.** `docs/README.md` linked
  `../CONFIGURATION.md` and `../CLI_REFERENCE.md` as though both lived at the repo root, and
  `v3-0-0-breaking-changes.md` was one `../` short on all three of its links. 73 links
  resolved against the filesystem: 5 broken before, 0 after. `docs/README.md` also claimed
  to be "a complete index of every documentation file" while omitting `AUDIT.md`, `SSO.md`,
  `BACKWARDS_COMPATIBILITY.md`, `ROADMAP.md` and all of `docs/reports/` — including the
  report this release reasons from. And `README.md` advertised `pip install "trelix[all]"`
  as "every optional extra (voyage, qdrant, lance, rerank, LLM providers, …)" when `[all]`
  resolves to `local,rerank,voyage,qdrant,watch,sso` — omitting exactly the two things the
  comment named.

- **A local `python -m build` produced a 928 MB sdist.** hatchling does not honour *nested*
  `.gitignore` files, and `workspace-vscode/.gitignore` ignores `.vscode-test/`, which
  `@vscode/test-electron` fills with three ~900 MB VS Code app bundles. CI publishes from a
  clean checkout so the released sdist was always ~6 MB; the new `[tool.hatch.build.targets.sdist]`
  excludes make a local build match it.

- **The release path refuses a tag that disagrees with the tree.** `release.yml` fires on
  `push: tags: v*`, derived nothing from the tree, and sets `skip-existing: true` on all
  four PyPI publish steps — so tagging `v3.2.0` on a tree stamped `3.1.2` built
  `trelix-3.1.2`, PyPI skipped it as already present, and the run went **green** with a
  GitHub Release full of binaries and **zero new packages**. Nothing in the logs said
  "published nothing". `skip-existing` is kept deliberately (it is what makes a re-run
  after a partial failure safe), so the guard is a separate `verify-version` job that every
  build and publish job now depends on.

  It checks **twelve** version stamps, not the five `CONTRIBUTING.md`'s checklist named. Two
  of the sites it added beyond that five are precisely those the documented procedure cannot
  find, because it greps for the *previous* version and both were still on `2.x`:
  `helm/trelix/values.yaml`'s `image.tag` — the chart advertised `appVersion: 3.1.2` while
  deploying **2.12.0**, having been skipped by all five release commits that did bump
  `Chart.yaml` — and `packages/trelix-mcp/server.json`, which carries the version twice.
  Run against the tree as it then stood, the gate failed 3 of 7 — which was the point; those
  three sites are fixed above, and the tree now passes 12/12.

- **The release path runs the test suite.** `ci.yml` triggers on push/PR to
  `[main, develop]` and never on tags, so the entire gate on four PyPI packages and two
  container images was `python -m build`, `twine check`, and a `--help` smoke test.

- **Both adapters were published by `release.yml` and gated by nothing.** `trelix-langchain`
  and `trelix-llama-index` sat on `2.4.0` while core reached `3.1.2`, and `verify-version`
  checked neither — so a `v3.1.2` tag would have built `trelix-langchain-2.4.0`, found it
  already on PyPI, skipped it under `skip-existing: true`, and reported success having
  published **2 of the 4 dists it advertises**. That is the exact failure the gate above
  exists to prevent, and the gate had that hole for half the distributions. Both are now
  stamped `3.1.2` in three places each — the dist version, the runtime `__version__` an
  installed package reports, and the assertion in each suite that pins it — and all four
  dist and runtime stamps joined the gate. `trelix_mcp.__version__` joined at the same time:
  it was the one stamp the checklist had marked ungated, with the instruction to "verify it
  by hand until that check is added", which is the same silent-mis-publish risk in a smaller
  package. That takes the gate from 7 checks to **12** — one per stamp, no exceptions left.
  Measured by running the job's shell body directly: `GITHUB_REF_NAME=v3.1.2` prints `ok`
  twelve times and exits 0; a `v3.2.0` control emits twelve `::error file=` annotations and
  exits 1.

  `tests/unit/test_release_version_gate.py` additionally asserts that eleven of the twelve
  stamps agree with root `pyproject.toml` *before* any tag exists — its `SITES` map is keyed
  by path, so `server.json`'s second version field is not separately representable in it. `verify-version` compares each stamp to
  the tag, so it can only fail once someone has cut one — by which point a wrong artifact may
  already be public. Stamps disagreeing with each other is the same defect, needs no tag to
  detect, and is what actually happened: nothing in the tree contradicted `2.4.0` across the
  seventeen releases that shipped after it.

  `release.yml`'s `test` job now runs all four suites. Wiring the adapter suites into
  `ci.yml` (above) did not reach the release path, because `ci.yml` fires on push/PR to
  `[main, develop]` and never on a tag — so the job that builds and publishes both dists had
  never executed their tests, including each suite's assertion that the *installed* package
  reports `3.1.2` — which the gate's grep over the source file cannot establish. Both run as
  separate `pytest` invocations, for the `tests.test_retriever` collision noted above.

  The `trelix>=3.0.0` dependency floor is deliberately **unchanged**, because lockstep
  governs the version stamp — identity — and not the floor, which is a compatibility
  contract. v2.7.1 reverted precisely this move: v2.7.0 had raised these two floors (and
  `trelix-mcp`'s) "based on an unverified assumption about API usage", and the remedy was to
  re-check every import and floor on what that supported. `3.0.0` remains the lowest
  published core verified to expose every name the adapters use, so `3.1.2` declaring
  `trelix>=3.0.0` says the honest thing: this is 3.1.2, and it works with core 3.0.0 and up.
  The stamp jump encodes nothing else either: the whole of
  `git diff v2.4.0..HEAD -- packages/trelix-*/src` is **13 insertions, 3 deletions**, every
  one of them a type annotation (a `TYPE_CHECKING` import, a `-> "Retriever"` return type,
  `__init__` parameter types). It is a re-alignment onto the core version line, not a record
  of adapter change.

- **`docker-publish.yml` had the same hole and now has the same guard.** It derived the
  image tag from `${GITHUB_REF_NAME#v}` with nothing comparing it to the tree, so a
  `v3.2.0` tag published `ghcr.io/…/trelix:3.2.0` containing a binary reporting `3.1.2`.
  Skipped for `workflow_dispatch`, whose whole purpose is backfilling an older release
  where the tree legitimately differs. Its `${{ github.event.inputs.version }}` also moved
  out of the script body into `env:` — a dispatch input interpolated into `run:` is a
  shell-injection sink.

- **`gitleaks` pre-commit hook.** There was no secret scanning anywhere — not in
  `.pre-commit-config.yaml`, not in CI — for a project publishing four PyPI packages and
  two container images. Prefix matching alone would not have sufficed either: the AWS
  credential pair in a local `.env` is base64-wrapped, so `AKIA…` never appears and every
  prefix scanner, GitHub push protection included, reads it as clean.

- **`trelix serve` warns when it is reachable off-box with no credential.**
  `api/app.py`'s `authenticate()` is open by design when neither a static token nor OIDC is
  configured, which is reasonable for the documented local use where `--host` defaults to
  `127.0.0.1`. The shipped container overrides exactly that: `Dockerfile` runs
  `serve /repo --host 0.0.0.0`, which a published port requires, and `docker-compose.yml`
  published `8765` on every host interface while bind-mounting the user's repository — so
  `docker compose up` served open, unauthenticated code search over it. Compose now
  publishes to `127.0.0.1:8765` and lists `TRELIX_API_AUTH_TOKEN` so it is discoverable.

  The warning lives at the bind boundary rather than in compose alone because it also
  catches `trelix serve --host 0.0.0.0` run directly, which no compose change can reach. It
  asks `_build_oidc_verifier` rather than reading an env var, so an SSO config that is
  enabled but unusable still warns — the case where a reader would most wrongly assume they
  were covered. `.github/SECURITY.md` claimed serve binds to `127.0.0.1`, true of the CLI
  and inverted by the image; corrected.

- **`config_lookup` no longer drops extensionless config files.** `_retrieve_config`
  gated every planner hint on six suffixes or the substring `"config"`, and
  `Path("Dockerfile").suffix` is `""` — so `Dockerfile`, `Makefile`, `Procfile`,
  `setup.cfg`, `nginx.conf` and every `*.tf` were silently unresolvable, for **every**
  repository. `find_file_by_path_fragment("Dockerfile")` worked the whole time and was
  simply never called.

  The gate could not just be deleted: `file_hints` is concatenated with `grep_hints`,
  documented at `planner/models.py:63` as "exact symbol names", so unfiltered hints would
  feed path lookups terms like `EXPOSE` and `ports:`. It now tests the filename, not only
  the suffix — `_looks_like_config` checks a config-filename set, a broadened suffix set,
  and the `Dockerfile.prod` variant shape.

  Measured on the golden set: the four ops queries went from an **unstable 0.00 / 0.50 /
  0.75 Recall@10 across identical configs to a stable 1.0000 nDCG@10 / Recall@10 / MRR**,
  and "what port does the container expose and what is its entrypoint" — which returned a
  single distinct file and answered confidently without the Dockerfile — now ranks
  `Dockerfile` first with HyDE disabled for determinism.

  **Caveat, disclosed rather than buried:** the 50-query set reads 0.6039 / 0.5791 against
  0.6105 / 0.6063 before. The within-config spread is 0.0248, *larger* than that
  difference, so two runs cannot separate the effect from noise. The plausible mechanism is
  that `config_lookup` now succeeds more often and `retriever.py`'s `if not results:`
  returns only the matched file's symbols, suppressing the vector, BM25 and grep legs
  entirely. That short-circuit is a pre-existing design issue, unchanged here and recorded
  under Known limitations.

- **`trelix[watch]` can now satisfy `watch-all`.** The extra installed only `watchdog`,
  while `indexing/multi_watcher.py` uses `watchfiles.awatch()` — so the ImportError at
  `multi_watcher.py:30-38`, which tells the user to run `pip install 'trelix[watch]'`, did
  not fix the problem it diagnosed. Masked locally because `uvicorn[standard]`, via the
  `serve` extra, pulls `watchfiles` in transitively.

- **Index provenance, reported by `trelix stats`.** `index_metadata` held exactly one row
  — `embedding_dimension` — so nothing recorded *what* an index was a snapshot of. A
  stale index does not fail loudly; it returns confident, well-ranked answers about code
  that has since changed. `trelix stats` now reports the commit, branch, worktree
  cleanliness, timestamp, trelix version and embedder the index was built from, plus how
  many commits `HEAD` has moved since.

  Captured at the **start** of an index run, not the end. Hashes are computed during the
  walk, so end-of-run capture would pair a newer commit with older content — recording an
  index as more current than it is, which is the direction that produces silent wrong
  answers. Written at the end, so a run that crashed partway leaves no record claiming
  completeness.

  A pre-v3.1.2 index says provenance was not recorded rather than guessing, and every
  field degrades independently — a non-git directory or absent `git` binary still records
  version and embedder rather than failing the index.

- **`trelix stats --drift`** — compares every indexable file on disk against its stored
  hash, reporting changed / not-yet-indexed / indexed-but-not-found counts. Opt-in
  because it costs a full walk plus a SHA-256 per file, where the rest of `stats` is a
  few SQL counts. It reuses `FileWalker` rather than reimplementing discovery: the
  indexer's own staleness rule is `db.get_file_hash(rel_path) != file.hash`, and a
  divergent hash would report every file stale on a freshly built index.

  `Indexed but not found` is deliberately **not** presented as a list of deletions. It is
  "indexed paths this walk did not yield", which has two innocent explanations, and both
  are surfaced above the counts because acting on the number deletes embeddings that cost
  money to recompute:

  - an incomplete walk (a directory that could not be read), using the walk-completeness
    signal added earlier in this release;
  - **a changed walk config**, which is now detectable because the walk-determining
    settings are recorded at index time and any difference is named in the output.
    Measured while building this: a drift check run without `scripts/self-index.sh`'s
    environment reported **35 present files** under `packages/` as deleted, because
    `TRELIX_WALKER_*` is process-env-only and `EXTRA_IGNORE_DIRS` replaces the default
    30-entry list (which contains `packages` for .NET NuGet output) rather than extending
    it. An index predating the recording reports `missing` as unverified rather than
    trustworthy.

- **Ops artifacts are indexed: shell, Dockerfile, Makefile, SQL and protobuf** (21 → 26
  languages). Two independent gaps had to close for this to work, and either alone would
  have left the files unreachable:

  - `Path("Dockerfile").suffix` is `""`, so no `EXTENSION_MAP` entry could ever match an
    extensionless artifact. Detection is now filename-aware via `FILENAME_MAP`, behind a
    shared `detect_language()` — previously each of five call sites (walker, watcher ×2,
    `api/app.py`, `indexer.py`) did its own `EXTENSION_MAP` lookup and would have needed
    the same fix five times.
  - Chunks hang off `symbol_id`, so a file yielding no symbols yields no chunks and is
    invisible to *every* retrieval leg — vector, BM25, grep, summary and sub-chunk alike.
    Shell, Dockerfile and Make have tree-sitter grammars but no structural extractor, so
    being detected was not sufficient.

- **`LineWindowParser`** — makes a file retrievable when nothing can parse its structure,
  emitting fixed line windows as `SECTION` symbols with honest 1-indexed line numbers. It
  extracts no calls, names or imports and reports `language_name == "line-window"` so a
  caller can tell the symbols came from a line split rather than a parse. Windows rather
  than one symbol per file because `Chunker` **truncates** an over-budget chunk instead of
  splitting it, so a single 200-line symbol would silently lose its tail.

  Also applied as a fallback in `_parse_one` when a real extractor returns zero symbols
  from non-empty source: a Go-templated helm manifest the YAML extractor cannot parse went
  0 → 5 `SECTION` symbols covering lines 1-184.

  Measured: walk 459 → 465 discovered, index 467 files, zero-symbol files 12 → 11.
  `Makefile` and `scripts/verify-index.sh` now rank 1 for queries about them.

### Fixed

- **The unit suite was order-dependent in 13 places, and it hid real bugs three times.**
  `tests/unit` passed forward and failed under reverse collection order — with no integration
  suite involved, contradicting a claim made earlier in this release. The causes were all the
  same shape: a test mutating process-global state and restoring it incompletely.

  Two were fixed here beyond the batch. `test_cli_audit.py`'s three failures were a **leaked
  `logging.StreamHandler`**: `_setup_logging()` builds a bare handler bound to whatever
  `sys.stderr` is at construction time, which under `CliRunner` is a capture buffer that
  closes when the invocation ends — while the handler survives on the root logger, so the next
  test to log anything dumps a `--- Logging error ---` traceback into *its* captured output.
  Those three tests are canaries, not casualties: they assert on a marker and fail with "an
  earlier test leaked a logging.StreamHandler bound to a now-closed CliRunner buffer", which is
  a correct diagnosis of someone else's mess. A guard existed but only inside
  `test_cli_markup_safety.py`; it is now an autouse fixture in `tests/unit/conftest.py`, since
  the victim is whichever test logs next rather than anything specific to one module.

  The last one was a **cumulative OpenTelemetry counter**. OTel's global `MeterProvider` can be
  set only once per process, so the in-memory reader is shared and every counter accumulates
  for the whole session. `_counter_total`'s own docstring says each test keeps its series
  disjoint via a distinct provider label — but two tests legitimately need the real `"openai"`
  label, so `test_openai_embed_counts_one_request_per_api_call` failed `assert 3 == 2` purely
  on ordering. Now asserts a delta. Fixing that surfaced a second latent hazard in the same
  helper: `get_metrics_data()` returns `None`, not an empty container, on a reader that has
  collected nothing — so taking a baseline before any recording raised `AttributeError`.

  **Reverse-order result: 3114 passed, 0 failed.** The suite is now order-independent.
    (This line first read 3068. That figure could not have been right: reversing collection
    order permutes the tests, it cannot change how many there are, so a reverse run must
    report the same count as a forward one. Corrected here rather than left standing, since a
    wrong measurement is not history.)

- **The eval harness could report a better score than reality.** It skipped a golden entry
  whose `relevant_files` was empty, which shrinks the denominator — so a malformed golden file
  scored *higher*, not lower. `eval/README.md` already listed this as one of "two ways to get a
  silently wrong score". There is now a third documented, previously recorded only in the
  self-index report: `query_cache_size` (default 256) memoises `embed_query`, so a repeat loop
  in one process measures once and echoes.

- **`TRELIX_FEDERATION_MAX_REPOS` was inert on the CLI.** Declared, documented, and enforced by
  `packages/trelix-mcp` — while `cli/main.py` built `FederatedRetriever(registry)` with no
  arguments, so `max_repos` stayed `None` and `trelix search-all` fanned out to every
  registered repo. Both sides read the same registry file, so a registry grown by a runaway
  `federation_add_repo` loop was uncapped the moment it was queried from the CLI, which is the
  exact scaling the cap exists to prevent. It now passes the cap and **names the skipped
  count** on stderr rather than truncating silently.

- **A fresh contributor's first `pytest tests/unit` was a collection error.**
  `.devcontainer/devcontainer.json` installed `.[local,dev]`, but two unit tests import `jwt`
  at module scope and pyjwt ships only in `[sso]`. pytest does not degrade to skipping those
  files — it reports "2 errors during collection / Interrupted", so all ~3000 tests vanish.
  `ci.yml` documents this exact hazard in a comment and installs `[sso]` to avoid it.

- **`scripts/measure_index_hygiene.py` accepted an invalid `--provider` and exited 0**, and was
  the single file blocking a repo-wide `ruff format` scope widening.

- **Deleting a file left its summary vector behind.** `delete_file_by_path` drove its vector
  cleanup from `get_chunk_ids_for_file()`, but a file summary's vector lives in the same
  `chunk_embeddings` table under the `chunk_id = -(file_id)` sentinel — so it was never in
  that list, while the `file_summaries` row itself cascades away with the `files` row. The
  result was a vector with neither a summary nor a file behind it. The leak long predates
  `--prune`: the watcher's delete path has taken it for as long as file summaries have
  existed.

  Found by the gate widened earlier in this release, the first time a real `--prune` removed
  a file: `verify-index.sh` reported 482 summary vectors against 481 summaries, the orphan
  being `-475` for a `file_id` that no longer existed. Both vectors now go in one
  `delete_batch` call, deliberately not gated on the chunk list being non-empty — a file can
  have a summary and no chunks, which is exactly what every zero-symbol file was.

- **A standing detector for re-introduced orphan rows.** The sweep that reclaimed 4,768
  `def_use_edges` rows is one-shot — gated on `on_disk < SCHEMA_VERSION`, and the live index is
  now stamped — and the existing gate is a row-count *floor*, which orphans only inflate.
  `verify-index.sh` now anti-joins `def_use_edges`, `sub_chunks` and `sparse_embeddings`
  against their parents, proven to fail against an orphan injected into a copy of the index.

- **A malformed retrieval-weight variable printed API-key material.** The weights were parsed
  inside `RetrievalConfig.model_post_init`, so pydantic caught the `ValueError` and re-raised
  it as a `ValidationError` carrying the model's entire settings input dict. Measured on
  pydantic 2.13.4: pydantic truncates `input_value` to ~50 characters keeping the head **and
  the tail**, so `str(exc)` and the traceback printed the trailing ~22 characters of a key
  verbatim — and `exc.errors()` and `exc.json()` printed every value in full. One typo was
  enough to put key material into a terminal, a CI log, or a pasted issue report, and *which*
  secret leaked was dict-order dependent. Weights are now parsed in `__init__`, before
  pydantic gets control, so the failure stays an ordinary `ValueError` carrying only its own
  message. The type, message and exit code are unchanged, which keeps the CLI's ten
  `except (ValueError, FileNotFoundError)` handlers and the existing tests working.

  Three cheaper fixes were rejected on evidence: a `ValueError` *subclass* is still wrapped;
  `PydanticCustomError` is itself a `ValueError`; and settings-source filtering cannot help
  because `cohere_api_key` is a legitimate field of this model, so the secret belongs in its
  input dict. Related, reported not fixed: `DotEnvSettingsSource` copies every unmatched
  dotenv key into the input dict when `extra != "forbid"`, so `.env` secrets reach all 12
  settings classes — including ones with no such field.

- **LanceDB duplicated rows under concurrent writers even when the delete succeeded.** Two
  handles on one URI, 40 upserts each over 50 chunk_ids from two threads, produced 55 rows
  with **zero exceptions raised** — a stale-snapshot race, each handle deleting against its
  own table version, distinct from the swallowed-delete defect fixed earlier in this release.
  It reaches production through the indexer's upsert `ThreadPoolExecutor`. Fixed with
  `checkout_latest()` plus a per-`(uri, table)` lock. `Table.merge_insert`, LanceDB's own
  upsert primitive, was **measured worse rather than better** — 4 threads over 50 chunk_ids
  left 53-62 rows through it — so it was rejected on evidence rather than adopted on
  reputation.

- **A thin direct lookup suppressed every hybrid leg.** `file_overview`, `project_overview`
  and `config_lookup` widened to standard retrieval only when the direct DB lookup found
  *nothing*, so one matched file yielding a handful of symbols returned exclusively those
  symbols and silently suppressed vector, BM25 and grep. Measured with a mocked DB (1 file,
  2 symbols): standard retrieval was never invoked and assembly saw 1 result. A breadth floor
  now also runs the standard path and merges when the direct lookup resolves fewer than 2
  distinct files **and** fewer than 10 symbols; direct hits keep first position, and the union
  is packed against the token budget once. Widening the config filename gate earlier in this
  release had made this more reachable, not less — that commit predicted it and deliberately
  left the mechanism alone.

  **This closed the retrieval regression this release had been carrying.** The 50-query
  golden set had drifted from a 0.6189 / 0.6312 nDCG@10 baseline to 0.6105 / 0.6063 after ops
  indexing and 0.6039 / 0.5791 after the filename gate — a cumulative ~0.034 that two runs
  could not separate from noise, disclosed at the time as unresolved with the short-circuit
  named as the suspected mechanism. With the breadth floor it reads **0.6189 / 0.6217**, back
  in the baseline range, and MRR **0.6254 / 0.6332** against a 0.5919 / 0.6142 baseline —
  above it on both runs. So the suspected mechanism was the actual one.

  The ops queries pay for it in ranking precision, which is the expected direction and worth
  stating: Recall@10 stays **1.0000** — every target file is still found — while nDCG@10 goes
  1.0000 to 0.8253, because merged standard results now compete for the top rank on queries
  where the direct hit had been the only candidate. Perfect recall with slightly diffuse
  ranking on four queries, in exchange for ~0.03 MRR across fifty, is a trade worth taking.

- **`trelix graph` reported a degenerate community partition as a healthy number.** Community
  detection returns 6,579 single-node communities out of 6,640 (99.1%) on trelix's own index,
  and the command printed only `Communities: 6640`. **Characterised rather than tuned**, which
  turned out to matter: 6,576 of the 6,579 singletons (99.95%) are nodes with **no edge at
  all** — 59.8% of the graph — and a resolution sweep over 0.2/0.5/1.0/2.0/5.0 returns the
  *same* 6,579 singletons every time, because a degree-0 node contributes zero to modularity
  in every possible partition. No resolution value can merge them. The cause is edge coverage,
  not Louvain: 50.8% of call edges are unresolved by design for stdlib and external targets,
  there are only 130 type edges, and 3,797 isolated nodes are markdown/JSON/YAML/TOML symbols
  that *cannot* have call or import edges. The build now reports singleton share and
  isolated-node count at WARNING, with the cause attributed.

- **File-summary failures were invisible.** `FileSummarizer.summarize()` returned `""` on any
  LLM error and logged at DEBUG, and the indexer had no `else` and no counter — so 0 of 467
  summaries was indistinguishable from complete success. The live count was 442/467, meaning
  25 had already failed silently. `index()` now reports `file_summaries_generated`,
  `_failed` and `_embedded`, and failures log at WARNING.

- **`watch-all`'s summary omitted `files_skipped_ignored`.** The counter existed in `stats()`
  and was invisible on the CLI.

Eight of the entries below share one shape — **switched on and doing nothing, or failing
and saying nothing** — and were found by re-auditing the tree after the first pass. Each
was reproduced by running code before being fixed, and each carries a regression test that
was proven red first.

- **`watch-all` indexed everything, including `node_modules/`.** `MultiRepoWatcher` handed
  every path watchfiles reported straight to `Indexer.index_file()`, which checks only
  language and content hash — so one `npm install`, `uv sync` or build under a registered
  repo pushed vendored trees into the embedder, work that both `trelix index` and
  single-repo `trelix watch` refuse. Measured on this repository: the pre-fix gate accepted
  **90,385** files where `FileWalker.walk()` accepts **444** — 99.5% of a full-tree event
  burst would have been `.venv/` and `node_modules/`. Events now route through the owning
  repo's own `FileWalker`, so the ignore chain, filenames, extensions, language allow-list
  and size cap are the same objects a batch index uses rather than a restatement that can
  drift. Filtering runs before the hash guard, so a 40 MB bundle is no longer read just to
  be rejected. Deletions stay unfiltered, so rows written before an ignore rule existed
  remain removable. `stats()` reports `files_skipped_ignored` separately from
  `files_skipped_unchanged`.

- **`watch-all` ignored SIGTERM, and Ctrl+C with it.** The SIGINT/SIGTERM handlers were
  registered against `asyncio.get_event_loop()` *before* `asyncio.run()`, which builds its
  own loop — measured, the two have different `id()`s and `_signal_handlers[SIGTERM]` is
  `None` inside the coroutine. So `docker stop`, `kubectl delete` and systemd were swallowed
  for the whole grace period and the process was hard-killed before printing its summary
  (reproduced: 4 s elapsed, stop event never set). Worse than SIGTERM alone:
  `add_signal_handler` repoints process-level SIGINT at asyncio's no-op handler, which stops
  `asyncio.Runner` installing its own, so the `except KeyboardInterrupt` fallback was dead
  too and Ctrl+C did nothing. Handlers are now installed from inside the coroutine via
  `asyncio.get_running_loop()`, per-signal so one failure cannot skip the other, and a
  platform that cannot install one now warns naming the signal and the lost guarantee.

- **`LanceVectorStore.upsert_batch` turned every upsert into an append.** It swallowed its
  delete with `except Exception: pass` and then called `add()` regardless. LanceDB enforces
  no uniqueness on `chunk_id`, so a single failing delete left duplicates no later upsert
  could repair: against real lancedb 0.33.0 one `chunk_id` grew 1 → 2 → 3 → 4 rows across
  three failed-delete upserts, with **zero log output at any level**. Vector search then
  returned that chunk four times, spending four of the k result slots on it, and `count()`
  over-reported by 3 against the SQLite `chunks` table. It now logs at ERROR and re-raises
  *before* adding, so the table keeps its prior single row and the caller learns the batch
  did not land. Deliberately louder than the sibling `delete_batch` seven lines below,
  whose swallowed failures only leave rows a later upsert can still replace.

- **A malformed retrieval weight killed every command without naming itself.** Two
  unguarded `float(val)` calls in `RetrievalConfig.model_post_init` meant a typo in any
  `TRELIX_RETRIEVAL_FILE_TYPE_WEIGHT_*` or `..._LEG_WEIGHT_*` aborted `trelix stats` — or
  anything else — with `could not convert string to float: 'abc'`, naming neither the
  variable nor which of ~96 `TRELIX_*` aliases to look at. This is the one knob the notes
  invite users to experiment with. Both sites now route through one parser that reports the
  variable, its value and a corrected example. The same parser rejects `nan`/`inf`, which
  `float()` accepted silently — and with a NaN weight every fused score becomes NaN,
  `nan * 0.5 > 0.9` is `False`, and results come back in insertion order with nothing raised
  or logged. Bad weights fail fast rather than being warned about and dropped, because a
  silently ignored weight leaves you measuring the default while believing otherwise.

- **PR review hid that retrieval had died under it.** `DiffReviewer._review_hunk` wrapped
  context retrieval in `except Exception: pass`, so a missing or broken vector store
  produced a page of confident review comments written against `context_text=""` —
  measured, an ERROR-severity comment returned with zero log records at any level including
  DEBUG, and nothing distinguishing it from a grounded review. The failure now logs at
  WARNING with the exception and file bound (matching the sibling handler ten lines above;
  DEBUG would have been as silent as the `pass`, since the CLI runs at WARNING), and every
  comment from a context-free hunk carries a `[trelix: no codebase context — retrieval
  failed for this hunk]` label in its text — the one field the CLI table, `--json` and
  posted GitHub comments all render. Scoped per hunk, so one broken file does not discredit
  the rest of the PR.

- **Connector syncs reported a failure count and nothing else.** `ArtifactSource.sync()`
  caught per-artefact write and auto-link failures with a bare `except Exception:` — no
  exception bound, no log call — so a run reporting `errors: 340` gave the operator no
  type, no message and no failing `source_ref`, and exited 1 with nothing to diagnose.
  Measured on a 340-artefact sync: zero log records at any level. Failures are now bound
  and logged — the first 5 in full with a traceback, the rest at DEBUG, plus one WARNING
  tallied by type (`failed to write 340 of 340 artefact(s) — ValueError x339,
  TimeoutError x1`), turning 340 identical lines into 6 that name the single outlier.

- **The vector leg silently returned fewer than `k` results.** `_vector_search` fetches
  exactly `k` (the oversample applies only under a `path_filter`), so every
  `_hydrate_chunk` returning None — an ANN entry whose chunk row is gone — permanently
  consumed a result slot with no diagnostic anywhere: measured 3 results for `k=5` with 2
  dead chunk_ids and zero log records. It now reports the shortfall at WARNING with the
  miss count and offending ids, rather than over-fetching to hide store drift behind a
  full-looking result set. Prefix rejects and small indexes stay silent, so the warning
  means exactly one thing.

- **The PageRank empty-centrality warning fired on every query** despite the comment above
  it promising it is said once — two queries against an index with empty `graph_metadata`
  produced two identical records, drowning the one actionable line (`run trelix graph`).

- **`rerank_provider="xtr"` reranked nothing.** The XTR path built a query-token dict
  containing a single synthetic token, so `xtr_score_documents` computed `sum([s])/1 == s`
  and every "reranked" score came back bit-identical to its input — measured on a 3-result
  fixture the output was exactly a descending sort of the incoming fused scores, and the
  `query` argument was never read. The only signal was a UserWarning calling XTR
  "unbenchmarked", which understates an identity function, and its
  `xtr_candidate_tokens` knob has zero reads anywhere in `src/`. Real token-level XTR needs
  a ColBERT-style multi-vector index trelix does not build, so rather than fake it the
  provider now warns on every call that it reranks nothing and that the knob has no effect,
  and the module docstring marks it DEGENERATE and points at `plaid`. Fixed in the same
  path: `results.index(r)` keyed scores by dataclass *value* equality, so value-equal
  duplicates all inherited doc 0's score — burying the true winner — at O(n²) cost.

- **`def_use_edges` — the largest table in the index — had no cleanup path at all, and
  4.0% of it was already orphaned.** `symbol_id` is `INTEGER NOT NULL` with no
  `REFERENCES`, and the table had a CREATE, an INDEX, an INSERT, one unused SELECT and
  **zero DELETE** anywhere in `src/`. Every symbol removal leaked its edges — both
  re-index paths on each changed symbol, and `delete_file_by_path()` on every file removed
  from a watched repo, since it shipped. Measured on the live 192 MB index: **4,768 of
  117,814 rows already pointed at a `symbols.id` that no longer exists.** A new
  `_purge_fkless_symbol_rows()` is called from all three symbol-removal paths and covers
  the three symbol-derived tables no `ON DELETE CASCADE` reaches — `sub_chunks`,
  `def_use_edges` and `sparse_embeddings`, the last being the same defect one level out.

- **The index schema was unversioned**, so an older install silently opened a
  newer-written index. `pragma user_version` was 0 across 30 tables and an unversioned
  chain of `CREATE TABLE IF NOT EXISTS`/`ALTER` blocks whose comments name v2.2/v2.3/v2.4
  with nothing queryable; `dimension_guard.py` was the only guard, while
  `BACKWARDS_COMPATIBILITY.md` promised additive-only evolution with no test enforcing it.
  An existing index still reads 0 and is treated as current, not corrupt.

- **`FileWalker` aborted an entire index run on a symlink loop.** With
  `TRELIX_WALKER_FOLLOW_SYMLINKS=false`, `_is_within_root` guarded `entry.resolve()` with
  `except OSError` — but `Path.resolve(strict=False)` on 3.11/3.12 *swallows* every OSError
  and re-raises ELOOP as `RuntimeError`. Measured on 3.11.14: broken, nonexistent and
  chmod-000-parent paths all resolve silently, so the handler was dead code and a mutual
  loop (`la -> lb`, `lb -> la`) killed the whole walk with an uncaught `RuntimeError`,
  losing every legitimate sibling file. Loops and dangling links are now excluded
  silently — nothing real sits behind an unresolvable path, matching the symlink-cycle
  precedent — while a non-loop resolve failure calls `_record_incomplete`, so
  `walk_was_complete` (and through it `missing_is_trustworthy`) stops claiming the index
  mirrors the repo after real content was dropped.

- **`trelix stats --drift` printed a total and a remedy it had already disclaimed.** The
  honesty warning about `missing` was gated on `missing_is_trustworthy`; the headline count
  and the remediation sentence were not. Measured here: *"99 file(s) have drifted. Run
  `trelix index` to rebuild"* directly beneath *"Treat missing as unverified"* — where 35 of
  the 99 were every file under `packages/`, all present on disk, unreachable only because
  `packages` is in the default `extra_ignore_dirs` for .NET output, and restorable by no
  `trelix index`. The total is now `actionable_drifted_count` (68 on the same tree), the row
  is labelled *(unverified)*, and the excluded count is named with the reason.

- **`.gitignore` contents were not fingerprinted, so an ignore-rule edit left drift falsely
  trustworthy.** `_WALK_FIELDS` recorded `respect_gitignore` as a bool only. Reproduced in a
  temp repo: changing `.gitignore` to `sub/` produced `missing=('sub/b.py',)` with
  `walk_config_diff=()` and `missing_is_trustworthy=True` — which a future `--prune` would
  act on by deleting a present file. The chain's contents are now digested into the
  fingerprint.

- **Test isolation: two module-scope `load_dotenv()` calls published the developer's real
  `.env` into `os.environ` for the whole pytest process.** Because pydantic-settings reads
  env vars *before* the `.env` file, either one outlived every fixture and rewrote config
  defaults for unrelated tests. `pytest tests/perf tests/unit/test_config.py::TestEmbedderConfig::test_default_provider_is_local`
  failed with `assert 'azure' == 'local'` in 0.19 s — and `pytest tests/perf/ --collect-only`
  prints "no tests collected" while still *importing* the module, so collection alone
  activated live credentials. The integration site now reads the file with `dotenv_values()`
  and injects it per-test under `monkeypatch`; the perf script loads it inside `__main__`,
  repo-root-anchored rather than cwd-relative (the old bare call silently found nothing when
  run from anywhere else).

- **`pytest -m "not integration"` deselected nothing.** `CONTRIBUTING.md` documents it as
  the credential-free run, but the marker was neither registered **nor applied to any
  test** — so it collected all 3,001 tests, byte-identical to bare pytest, and drove the
  live Azure/Bedrock calls it claimed to skip. Registering it alone would have fixed
  nothing. Now registered and applied by directory: **2,897 collected, 104 deselected**.
  `--strict-markers` added so a typo in the applied mark is a collection error rather than a
  silent no-op.

- **`_isolate_beast_mode_flags` was triplicated and had drifted.** Only the `tests/unit`
  copy carried `_CODE_DEFAULTS` and `_ENV_PREFIXES_TO_SCRUB`, so the integration and eval
  suites let a developer's environment through — the contamination the eval conftest's own
  docstring calls "load-bearing". Now one shared `tests/_env_isolation.py`, with the tables
  made immutable so one suite's fixture cannot silently change what the other two observe.

- **A test silently disabled the code it was testing for the rest of the session.**
  `test_multi_watcher.py` called `importlib.reload(multi_watcher)` inside
  `patch.dict(sys.modules, {"watchfiles": None})`. The reload re-runs a module-scope
  `try: from watchfiles import Change`, so both `Change` and `awatch` became `None`, and
  `patch.dict` restores `sys.modules` without restoring the module object it poisoned.
  `MultiRepoWatcher.run`'s deletion branch is guarded by `if Change is not None and
  change_type == Change.deleted`, so from that point on every delete event fell through to
  the ignore filter. Nothing caught it while no test depended on deletions; the first one
  that did failed only in a full-suite run and passed in isolation. Now restored in a
  `finally`, with an assertion pinning it. Verified directly: `Change is None` after the
  poisoning reload, `<enum 'Change'>` after the restoring one.

- **Nested `.gitignore` files were never read, despite the docstring saying they
  were.** `walker.py`'s module docstring advertised "respects nested .gitignore files"
  while `_load_gitignore_spec()` read only `repo_root/.gitignore`, so every
  `.gitignore` in every subdirectory of every indexed repository was ignored.

  Measured on this repository: `workspace-vscode/.gitignore` excludes `.vscode-test/`,
  which `@vscode/test-electron` fills with a **2.6 GB VS Code application bundle**. The
  walker indexed **543 of 915 files (59%) and 23,865 of 32,337 chunks (74%)** out of
  that bundle. The symbols it extracted are minified single-letter identifiers, and
  they competed with real code: the query *"how does the file walker filter ignored
  directories"* returned **6 of 10 results from the bundle** and pushed `FileWalker`
  itself down to rank 4.

  Corpus pollution and retrieval damage turned out to be very different numbers. Across
  a 10-query set, mean precision@10 was **94%** — the fusion pipeline masks the noise
  for most queries. The damage concentrates on queries whose vocabulary overlaps the
  junk, and there it is severe.

  The fix walks the `.gitignore` chain from repo root down to a path's own directory and
  applies git's real semantics, which a single root spec cannot express: each file's
  patterns match **relative to its own directory** (otherwise an anchored `/rooted.py`
  or a directory pattern `harness/` in a nested file silently matches nothing), and
  **proximity decides**, so a deeper `!keep.log` re-includes what its parent excluded.
  That last part needs pathspec's `check_file()`, which distinguishes *ignored* from
  *explicitly re-included* from *unmentioned*; `match_file()` collapses the last two and
  cannot express it. Specs are parsed once per directory and cached.

  On this repo: **915 files → 422**, zero from `.vscode-test`, walk in 0.1 s.
  `_is_ignored_file()` still works on an arbitrary path rather than requiring traversal
  state, because `watcher.py` calls it that way for single filesystem events — so
  `trelix watch` gets the fix too.

- **The taint parser was written against an invented fixture and got all three of its
  fields wrong.** Verified against real semgrep 1.x output for a rule matching
  `input()` → `cur.execute()`:

  `taint_sink` is a two-element tagged **list**, `["CliLoc", [location, code]]`, not a
  mapping. `trace.get("taint_sink", {}).get("location", {})` therefore called `.get()`
  on a list, raised `AttributeError`, and the bare `except Exception: continue` dropped
  the finding. Since only genuine taint flows carry a `dataflow_trace`, **taint analysis
  reported nothing, ever** — matching the 0 rows in `taint_flows`.

  `severity` is under `extra`, so the top-level read always fell through to the `"INFO"`
  default: every flow looked harmless and `--severity ERROR` could never match.

  And semgrep reports a match **at the sink**, so the top-level `path`/`start` is the
  sink's location. Using it as the source inverted the flow — for the fixture above it
  reported line 5 (the `execute` call) as the source and never saw line 3 (the `input`
  call).

  The existing test asserted all three misreadings, using a fixture with `severity` at
  the top level and `taint_sink` as a `{"location": ...}` dict, and passed. That is why
  this shipped: a fabricated fixture froze a wrong contract in place. The new fixture is
  captured verbatim from semgrep with only `path` values stubbed. The parser accepts
  both shapes, so the old dict form still works. End-to-end: 1 flow, `ERROR`, source
  `:3`, sink `:5`; before, 0 flows.

- **nDCG@10 and Recall@10 could exceed 1.0.** Both functions document a `[0, 1]` result
  and `docs/CLI_REFERENCE.md` shows example output in that range. `EvalHarness` ranks
  *chunks* and maps them onto file-level IDs while golden-set ground truth is
  file-level, and `Retriever._dedup` keys on `symbol_id`, never on file — so one file
  routinely occupies several of the top ten slots (this index averages ~77 chunks per
  file). Each occurrence scored again.

  Measured: one relevant file appearing 5 times in the top 10 scored **recall@10 = 5.0,
  nDCG@10 = 2.52**; all ten scored 10.0 and 4.54. Worse than the range violation,
  padding a result list with duplicates **raised** the score, so the metric rewarded
  redundancy.

  Deduplication now happens in the metric functions, covering every caller —
  `tests/eval/metrics.py` already implemented this first-hit-only rule locally, which is
  why the test-suite harness reported sane numbers while the shipped CLI did not. `mrr`
  is deduplicated too: it could not exceed 1.0, but duplicates *before* the first
  relevant hit inflate that hit's rank and **depress** the score (`[A,A,A,B]` scored 1/4
  instead of 1/2), so leaving it alone would have left the three metrics disagreeing
  about what a rank is. `@k` now means k distinct files. **Scores from before this change
  are not comparable with scores after it**, in both directions.

- **Sentinel rows stole slots from the vector search top-k.** Three kinds of row share
  the `chunk_embeddings` vec0 table: real chunks at positive ids, file summaries at
  `-file_id`, sub-chunks at `+10_000_000`. `search()` queried all three.

  That is not merely noise. `Retriever._vector_search` sets `fetch_k = k` with no
  oversample, hydrates each returned id, and `continue`s when hydration yields `None` —
  and `raw` holds only `k` rows, so **there is nothing left to backfill from**. Every
  sentinel in the top-k is a real result the caller silently never sees. Reproduced on
  an in-memory vec0: one summary and one sub-chunk vector placed nearer the query than
  any real chunk took the **top two of five** slots.

  Both obvious fixes are wrong, which is why this needed measuring rather than
  reasoning. `WHERE embedding MATCH ? AND chunk_id > 0 ... LIMIT ?` is **rejected
  outright** by sqlite-vec 0.1.9 — *"A LIMIT or 'k = ?' constraint is required on vec0
  knn queries"* — because the added predicate stops its planner recognising the `LIMIT`.
  The `k = ?` constraint form is accepted but **silently wrong**: it applies the
  predicate after the ANN cut, so a `k=5` query returned 4 rows, trading a polluted
  top-k for a short one.

  So the filter is in Python, and when the first pass comes back short it re-asks for
  `k` plus the exact number of sentinel rows stored — provably enough even if every
  sentinel outranks the k-th real chunk. The count is only paid when a filter actually
  removed something, so an index with no summaries or sub-chunks issues exactly the
  query it always did.

  Deliberately **not** applied to the Qdrant and LanceDB backends: they build
  `search_file_summaries()` and `search_sub_chunks()` *on top of* `search()` with a `k*5`
  oversample, so sentinels there are load-bearing and the same change would break both
  legs. The SQLite backend's sentinel legs run their own scans, which is what makes the
  exclusion safe here; a test pins the distinction.

- **The PageRank boost had never fired, and said nothing.**
  `get_top_central_symbols()` read `graph_metadata` without the `_ensure_table(db)` call
  its two siblings make. That table is created on demand rather than by the base schema,
  so on any index where `trelix graph` had not run the read raised
  `no such table: graph_metadata` — confirmed on this repo's index, where
  `SELECT name FROM sqlite_master WHERE name LIKE 'graph%'` returned zero rows.

  `Retriever._apply_pagerank_boost` caught that and logged at **DEBUG** while the CLI
  configures **WARNING**. With `TRELIX_RETRIEVAL_PAGERANK_BOOST=true` in `.env`, the
  result was an enabled retrieval feature that was inert and indistinguishable from a
  working one. The read now ensures the table, and an empty centrality set logs at
  WARNING naming both the fix and how to silence it.

- **A failed file summary permanently cost a file its vectors.** Phase 2.5's comment
  says failures are swallowed inside `FileSummarizer.summarize()`, and they are — but
  the `self.embedder.embed([summary])` call that follows had no boundary of its own,
  unlike the multi-granularity phase directly below it.

  The loss is permanent, not transient. The file's chunk rows **and its content hash**
  are already committed by then, so an embedder error unwinds past
  `all_pending.extend(pending)` — those chunks never receive vectors, and because the
  hash is stored, every later `trelix index` skips the file as "up to date" and never
  repairs it. The only outward sign was a generic red `DB error <path>`.

  Reproduced with an embedder that fails only on the single-text summary call:
  `files_indexed=1, symbols_extracted=1, chunks_total=0, chunks_embedded=0, errors=1` —
  a file recorded as indexed, with committed chunks and no vectors. Live for any run
  with `TRELIX_FILE_SUMMARIES_ENABLED=true`, where one Azure 429 past the retry budget
  was enough.

- **The query planner discarded its credentials, collapsing eight intents into one.**
  `QueryPlanner.__init__` builds its `LLMConfig` with `_env_file=None`, disabling dotenv
  loading, and then used it as-is. Credentials supplied via `.env` — the documented
  route — never reached the client, so `_plan_direct` fell back to `default_plan()` on
  every call and all eight `IntentType` values became the hard-coded `FEATURE_FLOW`.

  Measured with credentials in `.env` and nothing exported: eight textbook queries, one
  per intent, produced **one** distinct intent. Two are near-verbatim copies of the
  enum's own examples — *"what does this project do"* is exactly the `PROJECT_OVERVIEW`
  comment — and both classified as `feature_flow`. After the fix, with the Azure
  variables explicitly removed from the environment so credentials can only come from
  `.env`: **8 of 8**.

  `INTENT_STRATEGIES` keys off intent to choose which retrieval legs run and how far
  call-graph expansion goes, so an inert classifier gives every query an identical plan.
  On a 50-query golden set for this repository, activating it moved **nDCG@10 by +0.027
  and MRR by +0.040 while costing 0.040 recall** — a real precision-for-recall trade,
  every delta 5–8× the ±0.005 run-to-run noise floor measured on the same set. The
  direction is not the point. The point is that the number depended on whether
  credentials happened to be *exported* rather than read from `.env`, with nothing at
  the CLI's default log level to distinguish the two.

  The fix is the step its siblings already take: `Synthesizer` and `graph_rag` use the
  same shim and both follow it with `model_copy(update={…})` to carry credentials off
  the `EmbedderConfig` — `graph_rag` labels the block `# Carry over credentials`. The
  planner was the one site that skipped it. That asymmetry is also why synthesis was
  never affected: `trelix ask` worked throughout, because `Synthesizer` accepts an
  explicit `llm_config` *and* copies credentials in its fallback.

  Every pre-existing planner test supplies no credentials, so all of them passed either
  way. That is the gap that let this ship.

- **`trelix eval-synthesis` could never produce a non-empty answer.**
  `SynthesisEvalHarness.run()` passed the CLI's `IndexConfig` to `Synthesizer`, which
  takes an `EmbedderConfig` first and, with `llm_config=None`, falls into a shim reading
  `config.provider`. Every call raised `AttributeError` into a bare `except`, becoming
  `answer = ""`. Measured on the sample golden file: hallucination/completeness/
  faithfulness all 0.0000 and overall a **constant 0.4000** before, **0.8733** after.
  The `__init__` annotation was `Any`, which is what stopped mypy --strict from catching
  it, and the existing test patched `Synthesizer` wholesale — a MagicMock accepts any
  arguments, so the wrong type never raised under test.

- **`GitLinker` dropped every merge commit's file list.** `git log --name-only` prints no
  diff for a merge unless told which parent to diff against. On this repo, merge `3dea90a`
  yielded 0 files; with `--diff-merges=first-parent` it yields 4. That is the common case
  for PR-based work, where the ticket key lives in "Merge pull request … from
  feature/PROJ-456". Not `-m` (double-counts every file) and not `--first-parent` (hides
  the branch's own commits); for non-merge history the output is byte-identical.

- **The default ticket pattern read `UTF-8` and `SHA-256` as ticket ids.** `r"[A-Z]+-\d+"`
  matched 12 strings across 830 commits, **all** false positives. Anchoring alone fixes
  almost nothing — adding `\b` and a two-letter minimum removed exactly one — because a
  ticket key and a technical constant are structurally identical. The default now carries
  a noise-prefix vocabulary. The trailing guard allows a trailing hyphen deliberately: a
  stricter one dropped `feature/PROJ-456-thing`, gutting the merge fix above. The CLI
  restated the old literal as its own default and overrode the config, so both now
  reference one constant.

- **`trelix graph --visualize --json` wrote no HTML.** The `--json` branch returned before
  the export ran, so the flag was accepted and ignored — a stale 31-byte file survived
  where the same command without `--json` wrote 326 KB. The path is now reported as
  `visualization_path`; the four documented keys are unchanged.

- **`trelix taint` reported a FAILED scan as clean.** `run()` returns `[]` for four
  different situations, so the CLI could not distinguish them. The first attempt at this
  branched on `shutil.which` alone and made it worse: `--tier intrafile` without the
  Semgrep Pro Engine exits 2 with empty stdout, and that began printing "semgrep ran and
  reported nothing" at exit 0 — a confident all-clear for a scan that never ran. `scan()`
  now classifies the outcome from the exit code, semgrep's own `errors[]`, and
  `paths.scanned`, because no one of those covers every case. A failed or vacuous scan
  exits 1 and makes no clean claim.

- **Sparse indexing could not work, at two levels.** The default model
  `naver-splab/splade-code-distil` does not exist on the Hub. Correcting the id alone
  would not have helped: both real SPLADE-Code releases are `model_type=qwen3`, absent
  from transformers' MaskedLM auto-mapping, so `AutoModelForMaskedLM` cannot load them.
  And `embed()` ran ONE forward pass over every text — for this repo's 10,700 chunks that
  is a **668 GB** logits tensor — while `SparseConfig.batch_size` was referenced nowhere
  in `src/` and the constructor did not even accept it. Now a real BERT-family SPLADE,
  batched, verified at 60 snippets / 0.87 GB peak RSS.

- **`migrate-vectors --reset` did nothing while reporting success.**
  `clear_all_embeddings()` ran `DELETE FROM chunk_embeddings` on a connection with no
  sqlite-vec extension, raising `no such module: vec0` into `except: pass` — a guaranteed
  no-op on every install, with one caller and zero tests. A working delete would not have
  helped either: a vec0 table's width is fixed by its CREATE statement. And the hashes
  survived at both levels, so the re-index the message prescribed either reported
  "Nothing to index" or re-parsed everything and embedded nothing. Now: drop and rebuild
  at the new dimension (transactionally), invalidate file AND symbol hashes, clear the
  dimension record last, refuse on backends this cannot rebuild, and a new `--provider`
  to say which width to rebuild for.

- **A symbol's sub-chunks and their vectors outlived it.**
  `sub_chunks.parent_symbol_id` has no foreign key — `PRAGMA foreign_key_list(sub_chunks)`
  returns `[]`, unlike `chunks` — and no `DELETE FROM sub_chunks` existed anywhere, so
  rows accumulated on every re-index. `architecture.md` described the column as
  `FK→symbols CASCADE`, which was never true. Vectors are deleted before rows, because
  the row id is the only handle on its vector; a cascade could not have covered that half
  regardless, since the vectors live in a virtual table.

- **An unreadable directory vanished from the index in silence.** `_iter_files` caught
  `PermissionError` and bare-`return`ed, dropping the entire subtree with no trace, so
  `files_found` was reported as though it were the repository's contents. `FileWalker`
  now records what it could not read and `Indexer` reports it as `files_unreadable`. This
  is also the prerequisite for the reconciliation pass `trelix index` still lacks — see
  Known limitations.

- **Indexed content could drive the user's terminal.** `rich.markup.escape()`
  neutralises `[` markup brackets and nothing else, so ANSI/OSC control bytes
  stored in an indexed file reached the terminal verbatim when rendered by
  `trelix ask`, `search`, `review` and the agent surfaces. Two payloads mattered:
  **OSC 52**, which writes the user's clipboard on iTerm2/kitty/WezTerm, and
  cursor-up + erase-line, which lets injected content **scrub trelix's own output
  above it** so a reader cannot tell what was displayed. A new `_safe_text()`
  helper strips control bytes and then escapes markup, and is applied to every
  dynamic value rendered to the terminal by `cli/main.py` and `indexing/indexer.py`
  — the only two modules in `src/` that construct a markup-enabled `Console`.

  The indexer half landed later than the CLI half, and for a period this entry
  over-claimed. It is worth recording why that was worse than the original gap: the
  four indexer sites rendered `walker.incomplete_paths`, `orig.rel_path`,
  `pf.file.rel_path` and exception text — repo-controlled filenames, and a POSIX
  filename may contain any byte except `/` and NUL. Their only protection was
  accidental: with Rich's default `highlight=True` the reprhighlighter inserts SGR
  codes between the ESC and its payload, so multi-token sequences like OSC 52 fail
  to form. That is not a control — adding `highlight=False` anywhere removes it, and
  measured through a default-highlighting console `\x1bc` (RIS, full terminal
  reset), `\x1b#8` (DECALN screen fill) and `\x1b=` survive intact regardless. The
  helper now lives in `trelix.core.console_safety` so both modules share one copy,
  and the structural test that pins "exactly one `escape()` call in the repo" runs
  over all of `src/` rather than over `cli/main.py` alone, which is what let the gap
  exist while the guard reported green.

  The **order is load-bearing** and was wrong in the first version of this fix.
  `escape()`'s regex only treats `[` as a tag opener when the next byte is in
  `[a-z#/@]`; escaping *before* stripping therefore leaves `[` unescaped, and
  deleting the control byte then **synthesises a live markup tag** out of text that
  had none. Measured against a real pty, `pre[\x1blink=http://evil.example]CLICK`
  emitted an **OSC 8 hyperlink to an attacker-controlled URL** — a capability that
  does not exist on v3.1.1. Stripping first is what makes the escape total.

  Machine-readable output is deliberately unchanged: `--json` stays byte-exact
  (`markup=False, highlight=False, soft_wrap=True`), because escaping there would
  write stray backslashes into consumers' parsed strings. The strip is at the
  render boundary, not at index time — stored content stays intact, and the REST
  and MCP surfaces still return raw bytes for machine consumers.

- **A symlink cycle multiplied one file into dozens of copies.** A link pointing at
  one of its own ancestors (`repo/loop -> repo`) made the walk re-enter a directory
  it was already inside, yielding a single real file **17 to 33 times** depending on
  layout, at nesting depths bounded only by the OS path limit — the same multiple of
  the embedding cost, and that many duplicate results for one file. Some topologies
  (a link chain resolving to an ancestor, two loop links in one directory) **did not
  terminate at all**.

  `FileWalker._iter_files` now tracks the resolved paths of the current recursion
  chain and skips a directory whose resolved target is already an ancestor on that
  path. Deliberately **not** a global visited-set: that would collapse
  `repo/a -> repo/shared` and `repo/b -> repo/shared` into one and silently drop
  `b/`'s files from a legitimate layout. Note that `TRELIX_WALKER_FOLLOW_SYMLINKS=false`
  does *not* help here — the loop target resolves *inside* the root, so containment
  correctly permits it. Cycle detection and containment are orthogonal.

  For an index built before this, duplicate rows disappear on the next index run.
  Strictly fewer rows, never fewer *distinct* files; no reindex is required for
  correctness.

- **All three MCP prompts failed at `prompts/get`.** fastmcp ≥ 3.4 validates a
  prompt's return value and accepts only `Message` or `str`; the builders returned
  plain dicts, so every `prompts/get` raised `TypeError: messages[0] must be
  Message or str, got dict`. `prompts/list` was unaffected, so all three
  **advertised themselves and then errored on use**. Conversion now happens at the
  transport boundary in `server.py`, keeping `prompts.py` fastmcp-free, and the
  role is narrowed to the two literals the MCP spec allows. The `fastmcp` pin is
  bounded (`>=3.4.0,<4`) — an unbounded major is how this contract changed
  silently in the first place.

- **A deprecation deadline that had already passed.** `BACKWARDS_COMPATIBILITY.md`,
  `ROADMAP.md`, `FAQ.md` and the runtime `DeprecationWarning` itself all stated
  that `TRELIX_RETRIEVAL_FLARE_MAX_ITER` "will be removed in v3.0.0". v3.0.0
  shipped on 2026-08-13 and the alias is still live, so a reader was told the env
  var was gone in v3.x when it still works. Since the project's own policy permits
  removal only on a MAJOR bump, the target is retargeted to **v4.0.0** and the slip
  is recorded rather than quietly rewritten. Also corrected in the same document:
  a source citation off by 143 lines (`config.py:434` → `:577`) and a relative link
  that resolved to `docs/docs/superpowers/…`.

### Changed

- **`scikit-learn` removed from the core dependencies.** It was unconditional with **zero
  importers** — nothing under `src/`, `packages/`, `tests/`, `scripts/` or `eval/` imports
  sklearn or scipy, and all 142 modules import cleanly with sklearn, scipy, joblib and
  threadpoolctl blocked at `__import__`. Measured cost: **120 MB** on every `pip install
  trelix` (scipy 82, sklearn 36, joblib 2). `trelix.spec` already excluded all three from the
  shipped binary, which was the tell. Users on the local provider still get them transitively,
  because sentence-transformers requires them.

- **`httpx2` kept, and its comment corrected.** The audit flagged it as a third-party httpx
  fork duplicating a core dependency. It is not: `httpx2` is by the httpx author, Starlette's
  `testclient.py` does `import httpx2 as httpx` and falls back to `httpx` only with a
  `StarletteDeprecationWarning`, and its own fallback branch is marked `# pragma: no cover`. So
  it is the supported path, not redundancy, and removing it would have moved 45 `TestClient`
  constructions onto a deprecated branch. The old comment ("httpx2 replaces httpx") was wrong
  and the `>=0.27` floor was fiction — there is no 0.x line at all.

- **`fail_under` raised** from 75 against ~82.7% actual coverage, which `ci.yml`'s own comment
  had asked for.

- **The LanceDB backend's new hard-abort is documented** in `docs/PROVIDERS.md`. Making
  `upsert_batch` re-raise on a failed delete was right — it replaced silent row duplication —
  but no caller handled it, so a single failure could abort a whole index run that previously
  always completed.

- **`e2e_test.sh` deleted.** Stamped "trelix v0.4.0 beast mode", referenced by nothing in the
  `Makefile`, `.github/` or `CONTRIBUTING.md`, and covering nothing the suite does not.

- **Phase 2.5 (LLM file summaries) runs concurrently.** It was 89.6% of an index run — 428
  summaries over 1034.2 s of 1153.7 s — and fully sequential, while Phase 3 did 10,423 chunks
  in 74 s at 4-way. Chat calls now fan out over a thread pool (default 4) behind a new
  sliding-window requests-per-minute limiter: the **first chat-side rate limit in trelix**,
  since `tpm_limit` was embedder-only and fanning out without one would have leaned entirely
  on retry backoff, converting a rate limit into cost and latency. Measured 3.9x on the phase.
  Overridable via `TRELIX_FILE_SUMMARY_WORKERS` / `TRELIX_FILE_SUMMARY_RPM`. DB writes and
  summary embeds stay on the main thread. Visibility was fixed **before** concurrency, on
  purpose — parallelising an invisible failure mode multiplies a problem you cannot see.

- `Database` gained generic `get_index_metadata` / `set_index_metadata` /
  `delete_index_metadata` / `get_index_metadata_with_prefix`, and the three
  `embedding_dimension` helpers now delegate to them instead of carrying their own copy
  of the upsert. The prefix query escapes `LIKE` wildcards: `_` is a single-character
  wildcard in SQL, so an unescaped prefix of `a_` also matches `abx`.
- `docs/GETTING_STARTED.md` no longer claims `trelix stats` prints a language breakdown.
  It never did — the row also promised "embedder, timestamp", which only became true with
  provenance above.
- `TRELIX_PARSER_TAINT` is documented as **inert**. `ParserConfig.taint_enabled` is
  declared and read nowhere in `src/`; taint analysis happens only when `trelix taint`
  runs, and that command does not consult it. It had been documented as "Enable
  taint-flow tracking during parsing".
- `TRELIX_PARSER_DATAFLOW` now records that it is Python-only in practice, since the
  extractor requests the Python grammar unconditionally.
- `TRELIX_WALKER_RESPECT_GITIGNORE`, and the ignore sections of `CONFIGURATION.md`,
  `TROUBLESHOOTING.md` (two sites) and `MCP_GUIDE.md`, now describe nested-`.gitignore`
  support. All four correctly documented the old single-file limitation and would
  otherwise have been left asserting the opposite of the code.
- The `trelix taint` reference records two behaviours it had omitted: persistence to
  `taint_flows` is unconditional and happens *before* `--severity` filtering, and
  `--tier intrafile`/`interfile` both require the Semgrep Pro Engine, which
  `pip install trelix[taint]` does not provide.

- Documentation version stamps advanced to 3.1.2 across 14 files. Historical
  references ("New in v3.0.0", "Fixed in v3.0.0", the shipped-version table) are
  deliberately left alone. `CONTRIBUTING.md` now carries a release checklist naming all
  twelve stamps `verify-version` checks, the two things that look like version sites but are
  not — the Helm chart's own `version`, which tracks the chart's structure rather than the
  app, and the adapters' dependency floor, which is a compatibility contract rather than an
  identity — and why a blind `sed` over `docs/` corrupts history. An earlier revision of that
  checklist named five sites and filed the langchain and llama-index packages under
  "independently versioned" — both retired by the lockstep resolution above and by the four
  adapter stamps the gate now checks.
- `docs/architecture.md` claimed "110+ source modules"; the real count is 140.

### Known limitations

- **`trelix index --prune` needs provenance, so it refuses on an index built before this
  release.** The reconciliation pass shipped (see Added), but its guard requires a recorded
  walk config and version, and an index written by an earlier trelix has neither — so the
  first prune after upgrading refuses and says so. `trelix index` writes provenance, and a
  prune after that works. Deleting `.trelix/index.db` is **not** the remedy: it discards a
  paid-for index, and `TRELIX_INCREMENTAL=false trelix index .` re-parses everything without
  re-buying embeddings for unchanged files.
- **`TRELIX_PARSER_TAINT` is inert** — declared and read nowhere; taint analysis runs only
  via `trelix taint`.
- **SPLADE-Code models cannot be used** as the sparse model until `sparse.py` grows a
  causal-LM path; the default is a general SPLADE v3 checkpoint instead.
- **The breadth floor changes which results a thin direct lookup returns**, and its
  thresholds (fewer than 2 distinct files **and** fewer than 10 symbols) were chosen against
  one repository's golden set. `TRELIX_RETRIEVAL_BREADTH_FLOOR=false` restores the previous
  all-or-nothing behaviour; `..._MIN_FILES` and `..._MIN_SYMBOLS` tune it. The four ops
  queries keep Recall@10 = 1.0000 but lose top-rank precision (nDCG 1.0000 -> 0.8253), so a
  workload dominated by exact-filename questions may prefer it off.
- **`test_watcher.py` gained a positive case.** The import-guard test previously deleted
  `watchdog*` from `sys.modules`, which only clears the cache — an installed package
  re-imports and no `ImportError` is raised. It was therefore the sole failing test
  wherever `[watch]` was installed, and passed for the wrong reason wherever it was not:
  against an absent dependency rather than against the guard. Now uses
  `patch.dict("sys.modules", {"watchdog": None})`, the idiom already used for `trelix_mcp`
  in the same file, plus a case asserting the guard is silent when watchdog *is* importable
  — without which an unconditionally-raising guard would still pass.
- **Provenance is refreshed only by a full `trelix index`.** `trelix update-index` and
  `trelix watch` go through `index_file()`, which does not touch it, so the recorded commit
  can name an older tree than the index actually contains. Deliberate rather than
  overlooked: a per-file update has no single commit to attribute the index to, and
  stamping the current `HEAD` after touching one file would assert the whole index is
  current when it is not. `trelix stats --drift` is unaffected — it compares file hashes.
- **Ops-language ranking weight is an open question, not a tuned value.** The five
  line-window languages have no `file_type_weights` entry, so `fusion.py` gives them its
  1.0 fallback — the same weight as parsed Python, despite carrying less structural
  evidence. The 50-query golden set does read ~0.017 nDCG@10 lower with them present, but
  that is only ~1.4× measured same-config noise (0.012), and every attempt to tune it made
  ops files unreachable for queries specifically about them. Target rank moved
  **non-monotonically** with the multiplier (rank 9 at 1.0, absent at 0.8, rank 2 at 0.4),
  which means chunk-level near-ties decide it rather than the weight. Needs a ~20-query ops
  golden set before a value can be chosen honestly; overridable meanwhile with
  `TRELIX_RETRIEVAL_FILE_TYPE_WEIGHT_SHELL` and friends.
- **The 11 remaining zero-symbol files stay unreachable** until they are re-parsed. Both
  `trelix index` and `trelix update-index` skip them on the content-hash check
  (`indexer.py:512`), which the line-window fallback cannot get past.

  The remedy is `TRELIX_INCREMENTAL=false trelix index .` — **not** deleting the index.
  The `else` branch at `indexer.py:514` sets `to_parse = files`, forcing a re-parse of
  everything, and it costs almost nothing extra: `_insert_one` diffs symbols by
  qualified-name + content hash, and Phase 2.5 short-circuits on `if not chunks`
  (`indexer.py:984`), so unchanged files regenerate no chunks and re-buy no embeddings.
  An earlier revision of this entry implied a from-scratch rebuild was required, which
  would have meant discarding a 192 MB index and re-paying for ~2M tokens for nothing.
- **One ops query still fails for an unrelated reason.** "what port does the container
  expose and what is its entrypoint" returns only a *single* distinct file regardless of
  language weighting, so `Dockerfile` cannot place. That is retrieval breadth, not
  detection or parsing, and is untouched here.
- **The suite has a pre-existing test-isolation defect.** `test_config`,
  `test_llm_client`, `test_llm_bedrock_backend` and `test_git_linker` assertions about
  default providers and env precedence pass in isolation and when `tests/unit` runs alone,
  but fail once `tests/integration` runs in the same session. Minimal reproducer:
  `pytest tests/integration tests/unit/test_config.py::TestEmbedderConfig::test_default_provider_is_local`.

  `tests/integration/conftest.py::_isolate_beast_mode_flags` neither scrubs
  `_ENV_PREFIXES_TO_SCRUB` nor applies `_CODE_DEFAULTS`, both of which its `tests/unit`
  namesake does — so a `.env` present in the working tree reaches tests that assert code
  defaults.

  Measured rather than assumed: `tests/unit tests/integration` fails **10** at
  `c79f7c2` (checked in a clean `git worktree` at that commit) and **7** with these
  changes applied, and the 7 are a strict subset of the 10. Which tests get hit depends on
  collection order, so adding a test file shuffles the set — the count is not a quality
  signal in either direction. CI does not surface any of it: `pytest tests/unit/` and
  `tests/integration/` run as separate jobs.

### Closed without merging

- Dependabot **#133** (`mcp` `<2.0` → `<3.0`). `fastmcp-slim==3.4.7` itself declares
  `mcp<2.0,>=1.24.0`, so the existing pin matches upstream exactly. `mcp` 2.0.0 is
  GA, but fastmcp does not accept it; merging would advertise support fastmcp
  forbids. Revisit when fastmcp raises its own ceiling.

## [3.1.1] — 2026-08-15

### Overview

A security-documentation release. The code defect count is one; the document
defect count is four, and the most serious of them was a **safety guarantee that
was never true**.

From v2.x through v3.1.0, `SECURITY.md` stated that trelix "does not follow
symlinks outside the repo boundary." `FileWalker` had no symlink handling at all —
so a symlink out of the repository was indexed, and because `rel_path` is computed
on the unresolved path, the out-of-tree file was then reported as though it sat
inside. A link `repo/linked_dir` to an out-of-tree directory yielded
`linked_dir/secret.py`, with its bytes read from outside the repository.

A false containment guarantee is worse than a documented gap, because a reader
deciding what is safe to index acts on it. This release describes the real
behaviour and adds `TRELIX_WALKER_FOLLOW_SYMLINKS=false` to make the boundary
real for those who want it — **opt-in**, because confining by default would
silently drop files from any repository that symlinks to shared or vendored
directories.

Three smaller document defects go with it, all found in the same audit and all
verified by probe rather than inferred: the agentic off-switch that the MCP
`ask_agent` tool ignores, the federation tool that returns bodies from
repositories the caller never named, and the index that outlives the files it was
built from.

**Nothing changes at default settings.** With `follow_symlinks` at its default the
traversal is bit-for-bit what it was and costs no extra syscall per entry, proven
by comparing a default walk against an explicit `follow_symlinks=True` walk. No
reindex required, and no existing configuration behaves differently. The one new
config field is additive and default-off in effect, which is why this is a patch
release rather than a minor one.

That audit also concluded something worth recording as a **non**-finding: the
trelix-mcp surface is the same retrieval surface as the CLI and REST paths,
reaching a wider consumer — not a new capability class. It is not, however,
read-only: `index_codebase`, `build_knowledge_graph`, `federation_add_repo`,
`federation_remove_repo` and `agent_clear_session` all mutate persistent state,
as SECURITY.md already notes for the federation pair. `search_code` and
`GET /search` are byte-identical twins. trelix-mcp holds no credential, performs
no network egress, and has no exec primitive.

### Fixed

- **`SECURITY.md` claimed a symlink boundary that never existed.** Every release up
  to and including v3.1.0 stated that trelix "does not follow symlinks outside the
  repo boundary." `FileWalker` had no symlink handling at all: `_iter_files` used
  `entry.is_dir()`/`entry.is_file()`, both of which follow symlinks, and `walk()`
  computed `rel_path` with `relative_to(repo_root)` on the **unresolved** path — so a
  file outside the repository was indexed and then reported as though it sat inside
  it. Demonstrated: a repo containing a directory symlink to an out-of-tree folder
  indexes that folder's files and presents them as `linked_dir/secret.py`.

  A false containment guarantee is worse than a documented gap, because a reader
  deciding what is safe to index acts on it. The doc now describes the real
  behaviour, and `TRELIX_WALKER_FOLLOW_SYMLINKS=false` confines the walk by resolved
  path. **Opt-in on purpose:** confining by default would silently drop files from
  any repository that symlinks to shared or vendored directories, with no error to
  explain the absence. Symlinks whose targets are inside the repo are still indexed
  either way — it is a boundary, not a blanket symlink filter.

  With the flag at its default the traversal is unchanged and takes no extra
  `resolve()` syscall per entry, so existing indexes and their timings are untouched.

- **`SECURITY.md` sold an agentic off-switch that the MCP `ask_agent` tool ignores.**
  The exposure table listed the agentic loop as off by default via
  `TRELIX_RETRIEVAL_AGENTIC`, and the practical guidance said to "leave the agentic
  loop off." `trelix_mcp/server.py:762` sets `config.retrieval.agentic_enabled = True`
  unconditionally, after the env var has already been resolved. The tool's behaviour
  is intentional — it is the agent tool — so the defect is the document presenting a
  flag as a mitigation it does not cover. Both sites now say so.

### Added

- **Threat-model coverage for two capabilities that were absent from it.** Neither is
  a code change; both were verified by probe and are now documented:
  `federation_search_all` takes no `repo_path` and returns verbatim bodies from every
  registered repository, so a host agent that named no repo can receive content from
  repos it never opened — the only cross-repo content egress in the product, since
  `trelix search-all` emits no body bytes and no REST equivalent exists. And the index
  outlives its source: a symbol body is still returned after its file is deleted from
  disk, so "the consumer could have read that file anyway" does not hold for removed
  content.

- 6 walker tests (`tests/unit/test_walker.py::TestSymlinkContainment`) covering both
  settings, in-tree symlinks under confinement, broken symlinks, and a symlinked
  `repo_root` reached via `IndexConfig.model_construct` — the path
  `federation/retriever.py` and `indexing/multi_watcher.py` actually use, which
  bypasses the validator that would otherwise resolve `repo_path`.

## [3.1.0] — 2026-08-14

### Overview

A correctness release for everything trelix renders — to your terminal, to a
machine-readable pipe, and into an LLM prompt. Eight defects, all in one class:
a dynamic value meeting a sink that reinterprets it.

The common thread is that **none of them needed an attacker.** trelix's own
`rust.py` contains a regex whose `[/!]` is an unmatched Rich closing tag, so
`trelix ask` against any repository holding a Rust comment-stripper — trelix
included — died instead of showing results. 73 of this repo's 79 markdown files
contain a three-backtick run, so a markdown symbol body closed its own code fence
on the way into a prompt. A long LLM review comment wrapped mid-string and made
`trelix review --json` unparseable. A directory named `deep[` aborted an entire
`trelix index` run from inside the error handler that was supposed to skip one
file.

Two were silent rather than loud, which is why they lasted: Rich swallows a
balanced tag pair and exits 0 having dropped characters, and an ANSI spinner
prefix makes `trelix graph --json | jq` produce garbage with exit 0. Two more
were capability bugs — the agentic loop's system prompt had never reached a
model, and `VertexBackend.tool_call()` silently discarded every system message,
which had already been degrading query planning on Vertex.

Also documents the prompt-injection threat model in `SECURITY.md` for the first
time. **That section adds no mitigation** — it states plainly what indexed
content reaches a model and that trelix does no sanitization, no instruction/data
separation, and no detection. The escaping and fence changes in this release are
correctness fixes to rendering; neither is an anti-injection control, and no LLM
was called anywhere in this work.

No configuration changes, no schema changes, and **no reindex required**. Output
is byte-identical for every value that did not previously trip one of these bugs
— pinned by the 177 existing byte-identical assembler assertions plus 51 new
regression tests (2,394 -> 2,445), each demonstrated failing against v3.0.1.

### Fixed

- **A bracket in a file path or in a parser error message aborted the entire
  `trelix index` run.** `Indexer` builds its own `Console()` with markup enabled,
  and the earlier CLI markup audit covered `cli/main.py` only. Both error handlers
  interpolated their values raw — `f"[red]Parse error[/red] {rel_path}: {exc}"` —
  so an unmatched `[/…]` in **either** raised `MarkupError` from inside the
  `except` block itself. That escaped the worker loop and killed the run,
  discarding every other file's work and hiding the real cause, which survived
  only in the structlog line.

  This is strictly worse than the display bug it descends from: **the error
  handler is the sink**, so a defect that should have cost one skipped file cost
  the whole index instead. Neither value is tame — a directory named `deep[` puts
  a literal `[/` in `rel_path`, and a parser exception routinely quotes the
  offending source, so a bracket in `exc` needs no unusual filename at all.

  Note the asymmetry that let this survive review: the `logger.error("Parse error
  %s: %s", …)` call on the line directly above is correct, because `%s` args go to
  the logging framework, which never interprets markup. Only the adjacent Rich
  line was broken.

- **`trelix graph --json`, `taint --json`, `review --json` and `search-all --json`
  emitted ANSI spinner output ahead of their JSON.** Making the payload safe was
  only half of stdout purity: the `console.status()` spinner wrapping the work
  writes its animation frames and prose to the same stream. Rich suppresses those
  when stdout is not a terminal, so it is invisible in a pipe during development —
  but `FORCE_COLOR=1` is routinely set in CI, and then stdout opens with
  `\x1b[?25l\x1b[32m⠋\x1b[0m Building knowledge graph...` and
  `trelix graph --json | jq` yields garbage with **exit 0**, the worst failure mode
  for a machine-readable contract because nothing signals it.

  Status output now routes to stderr in `--json` mode via a `_status_console()`
  helper. That is the fix `review --pr` already used inline; this makes it the one
  way every command does it. Guarded by an AST test asserting no `--json` command
  spins on the stdout console, so a new command is caught when it is added rather
  than when someone pipes it.

- **`trelix ask`, `search`, `query`, `call-graph`, `review`, `taint`,
  `agent sessions show` and six more commands crashed or silently corrupted
  their output when rendering ordinary indexed content.** The CLI's module-level
  `Console()` has Rich markup enabled, so every string reaching
  `console.print()`, `Table.add_row()`, a Table title or a Panel body was parsed
  for `[tag]` console markup — and most of what these commands render is
  arbitrary text: indexed file paths and symbol names, retrieved source code,
  LLM answers and agent observations quoting that code, Semgrep findings, GitHub
  PR filenames, and persisted queries.

  Two distinct failure modes, neither requiring an attacker. An unmatched
  closing tag raises `MarkupError`, so the command renders **nothing** and exits
  nonzero; a balanced-looking tag pair is silently swallowed, so the command
  exits 0 having **dropped characters from the value**. trelix's own source trips
  the first: `src/trelix/indexing/parser/extractors/rust.py` contains
  `re.sub(r"^//[/!]?\s?", ...)`, whose `[/!]` is an unmatched closing tag — so
  `trelix ask` against any repository holding a Rust comment-stripping regex,
  trelix included, died instead of showing results.

  Fixed by escaping the value at every markup-interpreting sink — 73 new
  `escape()` call sites across 22 sink groups — while leaving trelix's own
  `[red]…[/red]` markup unescaped so colouring still works. The worst sink was
  `agent sessions show`, which replays LLM thoughts and tool observations, and a
  tool observation *is* retrieved repository source. `trelix audit list`'s Table
  **title** was also still unsafe: that command's earlier fix escaped every row
  but not the title, so `--db '/tmp/a[/x].db'` still raised.

- **`trelix review --json`, `taint --json` and `graph --json` emitted
  unparseable JSON.** These payloads went out through `console.print()`, which is
  a markup sink like any other, so they inherited both failure modes plus a
  third: Rich hard-wraps at the console width, and a wrap landing inside a JSON
  *string* injects a raw newline that `json.loads` rejects as `Invalid control
  character`. One long unbroken token in an LLM review comment was enough.
  Whitespace *between* JSON tokens is semantically free, which is why the
  existing `--json` contract tests — all using short, bracket-free comments —
  never caught it.

  Escaping is the wrong fix for a machine-readable payload (it would write stray
  backslashes into consumers' parsed strings), so these seven sites now go
  through a `_print_json()` helper that disables Rich's markup parser, syntax
  highlighter and line wrapping instead of altering the value. Output is
  byte-identical for payloads that already worked.

- **Nine functions in `cli/main.py` carried a redundant function-local
  `from rich.markup import escape`.** A function-local import binds the name for
  the *entire* function scope, so any `escape()` call above the import line
  raises `UnboundLocalError` — a live trap for exactly the kind of change made
  above, and one `mypy` does not detect (`ruff`'s F823 does). All nine removed;
  the module-level import is now the single source. Four dead
  `import json as _json` locals went with them.

- **Every code fence trelix put into an LLM prompt was hard-coded to three
  backticks, so any payload containing ``` closed its own fence early.**
  CommonMark ends a fenced block at the first fence at least as long as the
  opening one, so from that point on the remainder of the payload stopped being
  quoted code and reached the model as prose it could act on. Three sites were
  affected: the agent loop's `get_symbol` observation (`agent/loop.py`), and both
  the changed-diff and retrieved-context blocks in the PR reviewer
  (`review/reviewer.py`).

  **Deriving the fence length repaired the two reviewer sites but was a no-op at
  the agent site until two further defects were fixed**, both in
  `agent/history.py:to_text()`, which is what actually renders an observation
  into the prompt:

  - It interpolated the observation after a label on the *same line*. A
    CommonMark fence only opens a block at the **start** of a line, so
    `**Observation [ok]:** ```{code}` opened no block at all — the payload
    reached the model as prose and the *closing* fence opened an empty block
    instead. Confirmed against markdown-it-py at fence lengths 3, 4 and 11, and
    for a payload containing no backticks whatsoever: the defect is structural,
    so no fence length could ever have fixed it.
  - It sliced the rendered block at a fixed 500 characters, cutting the closing
    fence off any longer body. The block then never closed and **every later turn
    was swallowed into it** as though it were quoted code.

  Both were pre-existing rather than regressions, but together they meant the
  agent-side half of this fix would have shipped inert. The label now occupies its
  own line and truncation re-closes a fence it cuts.

  This breaks on ordinary use, not only under attack. trelix indexes markdown —
  `MarkdownParser` is wired into the parser registry — and **73 of the 79
  tracked markdown files in this repository contain a three-backtick run**, so a
  markdown symbol body pasted into a prompt truncated its own fence as a matter
  of course. Reviewing a diff that touches a markdown file put ``` directly into
  the diff text for the same reason.

  Fixed by deriving the fence from the payload in one shared helper,
  `trelix.llm.prompt.fenced_block()`, which returns
  `max(3, longest_backtick_run + 1)` backticks per CommonMark. It counts every
  backtick run rather than only line-initial ones, because the consumer is a
  language model rather than a spec-compliant parser: over-counting costs one
  backtick, under-counting truncates the payload. **Output is byte-identical to
  the previous format for any payload whose longest run is under three** — which
  is nearly all source code — and three of the new tests assert exactly that, so
  the change is a no-op for prompts that already worked.

- **The agentic loop's system prompt was defined and never sent.**
  `agent/loop.py` declared a `_SYSTEM_PROMPT` with the ReAct strategy rules, but
  nothing read it: `grep` found one hit in the file, the definition. Every turn
  went to the model as a single `role="user"` message and no system content of
  any kind, so the loop ran with zero strategy instructions and none of its own
  stated invariants were in force — including *"never call done until you've done
  at least one retrieval"*, which is what stops the agent answering from the
  question alone. The wiring appears simply never to have been written; the
  constant is present verbatim in the original v2.2 design plan.

  The obvious repair does not work: `tool_call()` declares no `system=` parameter
  on the `TrelixChatClient` ABC or on any of the five backends, unlike
  `complete()` and `stream()` which both do. The route the providers actually
  honour is a `role="system"` message at the head of the list, which is the idiom
  `QueryPlanner._call_llm` already uses; the loop now does the same. The user
  turn is unchanged byte-for-byte, so this adds the missing system message rather
  than rewriting the prompt.

  One note for operators: this is a deliberate behaviour change to what the
  agentic loop sends. The effect on model output has not been measured, because it
  cannot be without live LLM calls; the loop's public contract (`run()`'s return
  type, the tool schemas, turn accounting) is untouched.

- **`VertexBackend.tool_call()` silently discarded every system message.** It
  built its `GenerateContentConfig` without `system_instruction=` while
  `_build_contents()` filters `role == "system"` out and never re-injects it, so
  the model received the tool declarations and the user turn with no instructions
  at all. `complete()` and `stream()` in the same file compute an
  `effective_system` and pass it; only `tool_call()` did not.

  This was pre-existing and already degraded `QueryPlanner._call_llm`, which
  passes its planning rules as a system message — so query planning was quietly
  worse on Vertex than on every other provider. It would also have made the agent
  system prompt above a no-op on Vertex alone, which is the hardest kind of gap to
  notice: correct everywhere except one backend. Fixed by deriving
  `effective_system` from the messages exactly as `complete()` does, since
  `tool_call()` takes no `system=` parameter on the client ABC.

- **`trelix audit verify` reported "Audit chain intact." for a database it never
  read, and created one as a side effect.** `_open_audit_store`'s guard was
  `if not store.is_open`, but `AuditStore(path)` *creates* the file and its schema
  when the path is absent — so `is_open` was always `True`, the guard never fired,
  and a read-only integrity command exited 0 while leaving a fresh ~28 KB SQLite
  file behind. A CI integrity gate pointed at a typo'd or not-yet-created `--db`
  passed **green**.

  That function's own docstring states it exists to prevent exactly this ("a false
  integrity assurance"), which makes it the same defect class as the rest of this
  release: a documented safety guarantee the code did not deliver. The existence
  check now runs *before* construction and exits 2 (`2` = could not check; `1`
  stays reserved for detected tamper). A path that exists but is unusable — a
  directory, an unreadable file — still falls through to the `is_open` check,
  which does fire for those.

  It also had a test, and the test is why it survived: it passed a **directory**,
  which sqlite genuinely cannot open, so `is_open` was `False` and the guard fired
  correctly. The absent-path case behaves oppositely. Covered now for `verify`,
  `list` and `export`.

- **`taint --json` and `search-all --json` printed prose to stdout on the empty
  path**, so `| jq` failed on the most common path in CI — a no-semgrep install
  and an unregistered federation registry are both default states. Both returned
  before reaching their `if json_output:` branch. They now emit `[]`. This is the
  same `--json` contract fixed earlier for `graph`, `taint`, `review` and
  `search-all`'s populated paths; these were the two empty-path sites that scan
  missed.

- **The taint remediation hint told the user to install the package they already
  had.** `pip install trelix[taint]` was interpolated unescaped, so Rich read
  `[taint]` as an opening tag and swallowed it, rendering `pip install 'trelix'`.
  Identical to the swallow `_print_error()`'s docstring documents for
  `trelix[local]`, at a site that fix did not reach.

### Documentation

- **Corrections caught by the pre-release signoff, before publishing.** An
  end-to-end verification run over this release found seven inaccuracies, four of
  them introduced or shifted by this release itself. Fixed here rather than shipped:

  - **"Re-index to drop it" was false remediation.** This release's own new bullet on
    the index outliving its source told readers to re-index to purge a deleted
    file's body. `trelix index` walks the filesystem and upserts what it finds; it
    never reconciles the DB against the walk, so the row is never reaped. Verified
    for the incremental default, `incremental=false`, and two consecutive runs — the
    body survived all three. The remedy that does work is deleting
    `<repo>/.trelix/index.db` and re-indexing, and only the live watchers
    (`indexing/watcher.py:240`, `indexing/multi_watcher.py:144`) purge on delete
    events. Wrong remediation in a security document is worse than none, because it
    fails silently and in the unsafe direction.
  - **The flagship symlink example could not happen.** Both `SECURITY.md` and this
    changelog illustrated the gap with "a link `repo/linked_dir` to `/etc` yields
    `linked_dir/passwd`". `passwd` is extensionless, so the walker classifies it
    `Language.UNKNOWN` and drops it. Replaced with the reproducible
    `linked_dir/secret.py` form. A reader who tried the old example would have
    concluded the disclosure was overstated.
  - **Five `core/config.py` citations broke because of this release.** Adding
    `follow_symlinks` plus its comment inserted 7 lines at `core/config.py:55-61`,
    shifting every citation below it by exactly 7 — including the one backing the
    agentic off-switch claim, which had come to point at an unrelated field. All
    re-anchored and each verified to resolve to its named symbol.
  - **"trelix-mcp is read-only" was wrong.** `index_codebase`,
    `build_knowledge_graph`, `federation_add_repo`, `federation_remove_repo` and
    `agent_clear_session` all mutate persistent state, and `SECURITY.md` already
    said so for the federation pair — so the changelog contradicted the document it
    was correcting. The surrounding conclusion (same capability class, wider
    consumer) stands; only "read-only" was false.
  - The federation `config_path` note claimed its check was *unlike*
    `/graph/visualize`; both use `Path.is_relative_to` (`api/app.py:494`).
  - "trelix's MCP prompt templates instruct that agent to call those tools" read as
    shell and file-write tools; the templates name `search_code`, `get_symbol` and
    `blast_radius`. Reworded so the wide capability is attributed to the consumer,
    not to anything trelix directs.
  - The inherited markdown-fence count was 72 of 79; recounted, it is **73**.

- **User-facing docs no longer send readers to v3.0.0.** `docs/MCP_GUIDE.md` pinned
  `pip install trelix-mcp==3.0.0`, and three guides told users `trelix --version`
  "must show 3.0.0" — so a correct install failed the documented acceptance check.
  The pin is removed and the version assertions are now version-agnostic. Release
  binaries and Docker tags point at `releases/latest/download/` and
  `ghcr.io/sairam0424/trelix:latest`, which `docker-publish.yml` moves on every
  `v*` tag, so they cannot go stale again. **Known and not addressed here:** roughly
  40 cosmetic `v3.0.0` version stamps remain in docs titles and footers, unchanged
  since that release; they mislead nobody into a broken command but should be swept.

### Internal

- **A local `python -m build` produced a 928 MB sdist.** hatchling does not honour
  *nested* `.gitignore` files, and `workspace-vscode/.gitignore` is what ignores
  `.vscode-test/` — which `@vscode/test-electron` fills with three ~900 MB VS Code
  app bundles. Any developer who ran the extension tests and then built got 2.6 GB
  of Electron, plus `node_modules` from `infra/github-app` and
  `packages/trelix-typescript`, inside the tarball.

  **The published artifact was never affected**: the release workflow builds from a
  clean checkout, which is 6.6 MB and contains none of those directories. This is
  local-build parity only. A `[tool.hatch.build.targets.sdist] exclude` now drops
  build artifacts by glob, taking a local sdist from 928.20 MB to 1.44 MB with
  every source file — including `packages/trelix-typescript/package.json` — still
  present.

### Added

- 13 regression tests (`tests/unit/test_cli_markup_safety.py`, plus two in
  `tests/unit/test_review_pr_json.py`). Every test asserts the payload's
  **literal characters** appear in the output rather than merely that no
  exception was raised — a command that renders nothing also raises nothing, and
  the silent-swallow mode exits 0. The trigger line is read out of
  `extractors/rust.py` at test time rather than pasted, so the tests cannot
  drift from the code they pin. 11 of the 13 fail against the previous release;
  the other two are negative controls asserting `--json` output stays unescaped.

- 26 tests for prompt construction. 16 in `tests/unit/test_llm_prompt.py` cover
  the fence helper's edge cases: no backticks, runs of one and two (which must
  *not* inflate the fence, since that is what preserves byte-identity), runs of
  exactly three and longer, multiple runs, a run at the start or end of the
  payload, and empty and whitespace-only payloads. The worst-case payload is a
  verbatim excerpt of this repository's own `.github/SECURITY.md` rather than a
  crafted string, so it cannot drift from what trelix would really index.

  The other 10 live at the call sites in `tests/unit/test_agent_loop.py` and
  `tests/unit/test_reviewer.py` and assert on the **rendered prompt string**, not
  on the helper, so they pin the wiring rather than the implementation: five
  assert a well-formed block for a payload carrying ```, two assert byte-identical
  output for a plain payload, and one asserts the reviewer's two fences are
  derived independently so a long run in the retrieved context cannot inflate the
  diff's fence. The system-prompt tests capture the `tool_call()` kwargs from a
  fake client — no live LLM call — and assert the specific rule text arrives in a
  `role="system"` message, that no `system=` kwarg is passed (no backend accepts
  one), and that the rules were not smuggled into the user turn.

  23 of the 26 fail against the previous code. The other three are the
  byte-identity controls, which must pass on both sides; they were run against a
  pre-fix copy of `src/` to confirm they do.

## [3.0.1] — 2026-08-13

### Overview
A correctness release. One defect, but a total one: every call edge, parent link, and type edge the Python parser produced was wrong in any file with a module docstring — 8,815 of 8,815 index references on trelix's own source. It shipped silently in v2.12.0 and v3.0.0 because the off-by-one always resolved to a valid (just incorrect) row, so nothing ever raised or logged. **A reindex is required to get a correct call graph.** Also restores 177 byte-identical backcompat assertions that had gone dark, and unblocks an integration suite that could not complete.

### Fixed

- **Every call edge, parent link, and type edge produced by the Python parser was
  wrong in any file with a module docstring.** `PythonParser` recorded local
  indices into its `symbols` list during the AST walk, then did
  `symbols.insert(0, <module>)` afterwards when the module had a docstring —
  shifting every element by one and silently invalidating all three index
  families at once: `Symbol.parent_id` (method → enclosing class),
  `CallEdge.caller_id` (call site → enclosing function), and
  `TypeEdge.from_symbol_id` (subclass → base). The module docstring claimed the
  Indexer remapped these; it does not. `indexer.py` builds `local_to_db` by
  enumerating the *final* list, so a pre-insert index resolved to a **valid but
  wrong** row. It never raised, never logged, never produced a null — which is
  why it shipped in v2.12.0 and again in v3.0.0.

  Measured across trelix's own 139 source files, resolving every index to a
  symbol name in both arms: **8,815 of 8,815 index references (100%) were
  wrong** — 7,190 call edges, 1,525 parent links, 100 type edges. 434 parent
  links named `<module>` instead of the declaring class, and 77 call edges were
  fabricated self-recursion. 100% is arithmetic rather than a measurement
  artifact: all 2,179 symbols live in the 131 docstring-bearing files, and the 8
  files without a docstring are zero-byte `__init__.py` that emit no symbols.

  Fixed by reserving `symbols[0]` for the `<module>` symbol *before* the walk, so
  every index recorded is already correct for the list's final layout. This
  removes the bug class rather than compensating for it — no remapping exists to
  get out of step later. Verified against an oracle derived from CPython's own
  `ast` module (0 violations across 22 cases, down from 69), with 5 of 5 mutants
  killed.

  **A reindex is required to obtain a correct call graph.** This corrects
  v3.0.0's release note that "upgrading from v2.12.0 needs no reindex and no
  migration" — true of the schema, but the graph built by the old parser is
  wrong. Expect call-graph expansion, blast radius, PageRank centrality, the
  knowledge graph, and symbol hierarchy to return different, accurate results
  afterwards: on trelix's own index, 100% of PageRank values and 95.1% of ranks
  change (e.g. `CachingPlanner.plan` moves from rank 1975 to 34).

### Test coverage

- **Restored 177 byte-identical backcompat assertions that had silently stopped
  running.** `tests/unit/test_assembler_backcompat_golden.py` proves that with
  compression disabled, `ContextAssembler` output is unchanged from pre-v3.0.0 —
  including an object-identity check on the result list, so no reordering can
  hide. It built its baseline from `git show HEAD:...assembler.py`, so it only
  worked while the change was uncommitted; once merged, HEAD contained the change
  and the module skipped, contributing 0 of 2,190 passing tests. Now pinned to the
  `v2.12.0` tag, which is permanent — preferred over recording golden fixtures
  because it preserves the identity assertion a snapshot cannot express. `ci.yml`
  gained `fetch-depth: 0` / `fetch-tags: true`, without which the tag is
  unreachable in CI and the suite would go dark again. Proven to bite: two
  injected mutations were caught (141 and 8 failures) while a byte-identical
  control passed all 177.
- **Unblocked the integration suite.** `test_graph_api_integration.py` indexed the
  entire worktree, exceeding 390s across three attempts, so 16 tests had no result
  at all; it is now scoped to a fixture tree and runs in 36s. Four `test_cli.py`
  failures came from the developer `.env` leaking an embedder provider into spawned
  subprocesses — `monkeypatch` isolation is in-process only and cannot reach a
  child. All 11 files now pass (99 passed, 1 skipped) in ~576s.
- Covered the remaining `trelix audit` CLI branches: `audit_list`'s empty-log path
  and `audit_export`'s format handling including an unknown format.

## [3.0.0] — 2026-08-13

### Overview
Four internal batches consolidated into one release — there were no public 3.0/3.1/3.2 tags, so everything below lands at once on top of v2.12.0. Six feature areas: Anthropic **extended thinking** as a per-call-site request parameter, a **model-aware context budget** derived from the LLM's real context window, an **actionable VS Code extension** (code lenses + a `@trelix` chat participant), a **hash-chained audit trail** in its own `audit.db`, **OIDC SSO** with an asymmetric-only algorithm allowlist, and **SeleCom query-conditioned context compression** that shrinks retrieved bodies so more results fit the same budget. Six classes of live defect were fixed along the way, each a real failure rather than a hypothetical: an `AttributeError` that crashed *every* Anthropic response containing a thinking block, a VS Code command that returned an interpolated prompt template as if it were the model's answer, four citation-fidelity bugs in compression rendering, an unauthenticated `MarkupError` DoS of `trelix audit list`, an unbounded JWKS read a hostile issuer could turn into ~660 MB of RSS in 0.2s, and a documented env setting (`TRELIX_RETRIEVAL_CONTEXT_TOKEN_BUDGET=null`) that raised `ValidationError` instead of working.

Everything here is additive and OFF by default. **No breaking changes: upgrading from v2.12.0 needs no reindex and no migration.** The index schema is untouched, every new flag defaults to exactly today's behavior, and the audit/SSO tables live in a brand-new, deliberately separate `audit.db` that is only created when auditing or SSO is switched on. 2,341 unit tests (2,340 pass in a local run; the one failure, `tests/unit/test_watcher.py::TestWatchdogImportError`, asserts the error raised when the optional `watchdog` package is *absent* and therefore cannot pass in an environment with the `watch` extra installed).

### Added
- **Extended thinking (Anthropic) — a request parameter, opted into per call site** — new `LLMConfig.thinking_enabled` (`TRELIX_LLM_THINKING_ENABLED`, default `False`) and `thinking_budget_tokens` (`TRELIX_LLM_THINKING_BUDGET_TOKENS`, default `4096`). Thinking is a **request parameter, not a model name**: `AnthropicBackend` sends `thinking={"type": "enabled", "budget_tokens": N}` on `messages.create`/`messages.stream`, so no model string anywhere in trelix changes and no new model entry is needed. `complete()` and `stream()` on every backend gained a `thinking: bool = False` keyword for signature parity, but only the Anthropic backend acts on it — OpenAI/Azure, Bedrock, Vertex, and LiteLLM accept and ignore it. `tool_call()` deliberately did **not** get the keyword, because extended thinking is incompatible with a forced `tool_choice`: there is no valid combination to expose. Opt-in is deliberately per call site, and exactly one call site opts in: `RetrievalSynthesizer` (`src/trelix/retrieval/synthesizer.py`, both the buffered and streaming paths) passes `thinking=self._llm_config.thinking_enabled`. The two index-time LLM sites — `ContextualChunker`'s per-symbol context call and `FileSummarizer`'s per-file summary — never pass it, on purpose: a single global flag would multiply an indexing run's LLM cost by roughly 5-10x to produce reasoning no retrieval path ever reads. `ChatResponse` gained `thinking: str | None`, `cache_read_tokens`, and `cache_write_tokens` (the two cache counters are read defensively via `hasattr`, so an older `anthropic` SDK whose `usage` object lacks them yields `0` rather than raising). The `temperature=1.0` requirement is enforced in code rather than discovered in production: the backend forces it and ignores any caller-supplied temperature while thinking is on. Thinking bills as **output** tokens — Anthropic exposes no separate thinking counter — so `ChatResponse.output_tokens` covers the visible answer and the thinking blocks together. Tests: `tests/unit/test_llm_thinking.py`.
- **Model-aware context budget** — new `src/trelix/llm/context_windows.py`: a longest-prefix-first `MODEL_WINDOWS` table (Gemini, Anthropic, OpenAI, Cohere, Mistral, Meta) plus `resolve_window(model)`, which prefix-matches so version suffixes resolve without a table entry each (`"gpt-4o-2024-11-20"` → 128,000; `"claude-sonnet-4-20250514"` → 200,000; `"gemini-2.5-pro-preview-0409"` → 1,000,000). `RetrievalConfig.context_token_budget` is now `int | None` and still defaults to `12_000` — the exact v2.12.0 number, so a default install packs context byte-identically. Set it to `null`/`none`/`auto`/`""` (or `None` from Python) and `Retriever._resolve_effective_budget()` derives `window × context_window_fraction` instead, where `context_window_fraction` (`TRELIX_RETRIEVAL_CONTEXT_WINDOW_FRACTION`) defaults to `0.5` and is bounded `0.1-0.9`; the resolved budget is logged at INFO so an operator can see which number actually applied. An unrecognized model logs a warning and falls back to 12,000 rather than guessing optimistically — and that fallback is reached more often than the table suggests, because `resolve_window` matches a bare prefix and therefore does **not** resolve provider-prefixed Bedrock ids (`us.anthropic.claude-sonnet-4-…` → `None` → 12,000). Documented as a known limitation, not silently papered over.
  **The budget was never the real ceiling, and the config now says so.** `rerank_top_n` (15) and `top_k_vector`/`top_k_bm25` (20/20) cap the candidate pool *before* the packer ever sees a budget, so raising only the budget changes very little in practice. New `scale_top_k_to_budget` (`TRELIX_RETRIEVAL_SCALE_TOP_K_TO_BUDGET`, default `False`) is the explicit opt-in that scales `top_k_vector` and `rerank_top_n` by `effective_budget / 12000` — and it raises per-query cost (more reranker work, a larger fusion pool, a bigger synthesis prompt), which is exactly why it stays off even when auto-derivation is on. Tests: `tests/unit/test_context_windows.py`, `tests/unit/test_model_aware_budget.py`.
- **VS Code extension: actionable code lenses** — new `TrelixCodeLensProvider` (`workspace-vscode/src/code-lens-provider.ts`) puts two lenses above every symbol in the open file: a static `$(search) Find similar` action and a count-bearing `N dependents` action. The performance contract is the whole design: `provideCodeLenses` does **zero** MCP work — it only asks VS Code's own `executeDocumentSymbolProvider` for symbols and returns the count lens *unresolved*, with no command attached. `resolveCodeLens` is the single place MCP is touched (`blastRadius()` → `$(references) N dependents`), and its result is cached against the exact `${uri}@${version}::${symbol}` the lens was produced for, so typing never fires a network call, repeated paints at one revision are free, and an edit bumps the document version and correctly misses the cache. A cancelled resolve is never cached, and it falls back to a plain `$(references) Blast radius` action rather than showing a wrong count. Degrades to zero lenses when no document-symbol provider is installed or it errors. Gated by the existing `trelix.codeLens.enabled` setting.
- **VS Code extension: `@trelix` chat participant** — new `workspace-vscode/src/chat-participant.ts` + `chat-handler.ts` register a `trelix.chat` participant: `@trelix <question>` runs the `ask_agent` MCP tool and renders the answer into VS Code's chat view as markdown (with a `stream.progress()` line first, since the ReAct loop is not instant), alongside `/search`, `/explain`, and `/impact` slash commands. Registration is runtime-guarded (`if (!vscode.chat?.createChatParticipant) return undefined`): the chat API landed in VS Code 1.95, so on 1.90-1.94 the participant silently no-ops and the extension still activates cleanly — `engines.vscode` stays `^1.90.0`, with no forced editor upgrade for existing users. Known limitation, documented rather than pretended away: the chat API exposes no stable thread/conversation id, so trelix agent sessions are keyed by a single constant and two chat threads open at the same time share one agent session. The only per-conversation signal available is `context.history` — empty history starts a fresh session, non-empty history resumes the stored one. Tests: `workspace-vscode/src/test/suite/code-lens-provider.test.ts`, `chat-handler.test.ts`.
- **Audit logging — hash-chained, append-only, in its own `audit.db`** — new `src/trelix/audit/` (`events.py`, `store.py`, `middleware.py`) and `AuditConfig` (`TRELIX_AUDIT_ENABLED` default `False`, `TRELIX_AUDIT_DB_PATH` default `<cwd>/.trelix/audit.db`, `TRELIX_AUDIT_LOG_QUERIES` default `False`, `TRELIX_AUDIT_FAIL_CLOSED` default `False`, `TRELIX_AUDIT_RETENTION_DAYS` default `365`). The trail lives in a **separate** SQLite file, never the index DB: the index is disposable and users delete and rebuild it, while an audit trail that vanishes on reindex is not an audit trail. Each row stores `prev_hash` and `entry_hash = sha256(prev_hash || canonical_json(content))` (genesis `prev_hash` = 64 zeros), and an `audit_meta` row keeps a running `count`/`head_hash` anchor updated atomically with every append — the chain alone cannot detect a deleted *tail*, since the survivors still form a valid chain. `AuditMiddleware` records exactly one event per HTTP request and is registered **outermost** in `create_app()`, so it observes the final status code including the 401s produced by the auth dependency and the 500s produced by an unhandled route error. It never persists a header value or token: `principal` comes from `request.state.principal` (defaulting to `"static-token"`), and for `search`/`ask` the query text in `detail` is stored as `sha256(detail)` unless `log_queries=True` is set explicitly. Failure contract, chosen deliberately: a write failure logs at WARNING and lets the request proceed (`fail_closed=False`) so a full disk cannot take down the API, while `fail_closed=True` re-raises for compliance deployments that need a durable trail more than they need uptime. New CLI: `trelix audit list` (Rich table, newest first), `trelix audit verify` (walks the chain, exits nonzero and names the first divergent id), and `trelix audit export --format ndjson` — NDJSON to stdout so a SIEM can be fed by Filebeat/Vector/Fluent Bit rather than by a bespoke HTTP transport trelix would have to maintain. Tests: `tests/unit/test_audit_store.py`, `tests/unit/test_api_audit.py`.
- **OIDC SSO (`pip install 'trelix[sso]'`)** — new `src/trelix/auth/` (`oidc.py`, `principal.py`, `store.py`) and `SSOConfig` (`TRELIX_OIDC_ENABLED` default `False`, `TRELIX_OIDC_ISSUER`, `TRELIX_OIDC_AUDIENCE`, `TRELIX_OIDC_ALGORITHMS` default `["RS256", "ES256"]`, `TRELIX_OIDC_JWKS_URI`, `TRELIX_OIDC_JWKS_TTL_SECONDS` default `3600`), backed by a new `sso` extra (`pyjwt[crypto]>=2.9`). `OidcVerifier` enforces an **asymmetric-only algorithm allowlist** at two gates — construction raises `ValueError` on any non-allowlisted entry, and verification rejects a disallowed `alg` header before decode — so `alg: none` and every `HS*` variant are unreachable. That is the direct defense against the classic algorithm-confusion forgery, where an attacker re-signs a token with HS256 using the server's own RSA *public* key as the HMAC secret. `iss`, `aud`, `exp`, and `nbf` are all verified. **Identity is the `(sub, iss)` pair, never the email** — emails are mutable and reassignable, which makes email-keyed identity an account-takeover primitive; `email`/`display_name`/`groups` ride along for display and coarse authorization only. A verified caller is JIT-provisioned into a `principals` table in the same `audit.db` (`first_seen` immutable, only `last_seen` advances), so identity survives a reindex alongside the trail it belongs to. Static-token auth (`TRELIX_API_AUTH_TOKEN`) still works exactly as before, and with SSO off the API behaves byte-identically to v2.12.0. Tests: `tests/unit/test_oidc.py`.
- **SeleCom query-conditioned context compression (opt-in)** — new `src/trelix/compression/` (`base.py`, `extractive.py`) plus `src/trelix/retrieval/context_compression.py`, wired behind `compression_enabled` (`TRELIX_RETRIEVAL_COMPRESSION`, default `False`), `compression_provider` (`TRELIX_RETRIEVAL_COMPRESSION_PROVIDER`, only `"extractive"` today), `compression_target_ratio` (`TRELIX_RETRIEVAL_COMPRESSION_RATIO`, default `0.45`, bounded `0.1-1.0`, used only for an unknown/absent intent), and `compression_min_tokens` (`TRELIX_RETRIEVAL_COMPRESSION_MIN_TOKENS`, default `120` — below that the per-span headers and elision markers cost more than the shrink saves). Two invariants carry the whole safety argument:
  - **Result-lossless.** Packing runs in two waves. Wave 1 is the exact uncompressed pack the assembler already did, with the compressor never called. Wave 2 compresses **only** the candidates wave 1 could not fit — the ones today silently drops — and re-offers them against the leftover budget, walking a ladder (budget-tightened target ratio → the compressor's signature+docstring floor → skip, recorded in the trace stats so a skip is never silent). The compressed selection is therefore always a superset of the uncompressed one, so Recall/MRR/nDCG cannot go down by construction, and a result that already fits is never touched, keeping its text byte-identical.
  - **Citation fidelity.** Kept spans render as separate `[Lines a-b] <qualified_name>` blocks with explicit `# ... N lines elided ...` markers between them, so no header ever claims lines its text does not contain.
  The default `"extractive"` provider does **zero query-time inference** — no embedding, API, or network call. Its `sub_chunk` path reuses sub-chunk vectors already stored at index time (`chunk_id = sub_chunk_id + 10_000_000`) and takes the query embedding from a *peek* at the retriever's existing `embed_query` LRU, never a fresh call; when sub-chunks are absent it falls back to a lexical splitter (blank-line + brace-balance segmentation scored by query-token overlap). The lexical path is the common one today, because sub-chunks are Python-only and `multi_granularity_enabled` (`TRELIX_CHUNKER_MULTI_GRANULARITY`) defaults to `False`. Per-intent ratios are baked into `RetrievalStrategy` and individually overridable via `TRELIX_RETRIEVAL_COMPRESSION_RATIO_<INTENT>`: `symbol_lookup`, `file_overview`, `project_overview`, and `config_lookup` are all `1.0` (off — for those the body *is* the answer), `feature_flow` `0.45`, `dependency_map` and `blast_radius` `0.30`, `comparison` `0.65`. A ratio of `1.0` short-circuits before the compressor is even constructed. Honest expectation, not a benchmark claim: roughly **30-60% fewer synthesis input tokens and 15-35% lower latency on a network-API synthesis path** — this is not a "4x faster" feature, and on a local model the token saving matters more than the wall clock. Tests: `tests/unit/test_compression_extractive.py`, `tests/unit/test_assembler_compression.py`, `tests/unit/test_compression_citation_adversarial.py`, `tests/unit/test_compression_citation_truncated_body.py`.
- **FTS5 declaration-boost ranking (opt-in)** — new `RetrievalConfig.declaration_boost_enabled`/`declaration_boost_weight` (`TRELIX_RETRIEVAL_DECLARATION_BOOST`/`_WEIGHT`), threaded into `Database.bm25_search()`'s previously-unweighted FTS5 query via an explicit `bm25(symbols_fts, ...)` call. Fixes a real ranking defect: unweighted BM25 can rank a symbol that only *mentions* a query term in its body/docstring above the symbol whose *name* actually matches it — reproduced live on trelix's own self-index, where `Database.bm25_search` (the method implementing the very feature being searched for) doesn't appear in the top 15 results for the query `"bm25_search"` under the old unweighted ranking, but reaches rank #9 with `declaration_boost_weight=5.0`. Default weight `1.0` is a verified no-op — byte-for-byte identical to today's unweighted ranking. No FTS5 schema change; the existing 5-column virtual table is reweighted, not rebuilt.
- **VS Code hover provider** — hovering over any identifier now shows its signature, docstring, and file/line location via the `get_symbol` MCP tool, with a per-session `word::repo` cache. No new backend plumbing — reuses the existing `get_symbol` tool and the extension's existing `ensureConnected()`/`getRepoPath()` helpers. Registered on an unrestricted `{ scheme: "file" }` selector rather than a per-language allowlist, since trelix indexes 20+ languages. Known limitation (documented, not fixed here): `get_symbol` falls back to an ambiguous bare-name lookup when the exact qualified name doesn't resolve — a hover over a name shared by multiple symbols may show the wrong one.
- **JetBrains IDE setup docs** — `docs/MCP_GUIDE.md` now documents connecting `trelix-mcp` via JetBrains IDEs' (2025.2+) first-party built-in MCP client, mirroring the existing Cursor/Windsurf/Continue.dev sections. Docs-only — no dedicated trelix JetBrains plugin exists or is planned by this change.
- **Markdown diagram-block tagging** — `Chunker` now prepends a `# Diagram: mermaid`/`# Diagram: plantuml` context header (mirroring the existing `# File:`/`# Class:` convention) when a chunked section's body contains a fenced mermaid/plantuml block. New `ChunkerConfig.include_diagram_tags` (default `True`). Implemented in the language-agnostic `Chunker`, not the markdown parser, so it works for any language whose symbol body happens to embed a fenced diagram block. Only the first diagram fence per section is tagged (documented v1 limitation, not a bug).

### Fixed
- **Anthropic backend crashed with `AttributeError` on any response containing a thinking block** — a latent crash, live the moment extended thinking was switched on: the backend read the answer as `response.content[0].text`, and Anthropic returns the thinking block *first*, so `content[0]` is a `ThinkingBlock` with no `.text` attribute. Fixed by a new `_split_content()` that walks every content block and joins `text` and `thinking` parts separately, returning `("", None)` for an empty content list. This is why `ChatResponse.thinking` exists as a real field instead of the reasoning being discarded or, worse, concatenated into the answer.
- **VS Code `ask()` returned an interpolated prompt template as if it were the model's answer** — `TrelixMcpClient.ask()` called `getPrompt("trelix-search")`, which by MCP's own semantics returns a *filled-in prompt template*, not a completion. The "trelix: Ask about Code" command therefore rendered prompt scaffolding to the user and had never actually answered a question. Fixed to `callTool({ name: "ask_agent", … })` — the multi-turn ReAct agentic loop — returning the parsed `{answer, session_id, turn_count}` envelope, mirroring `search()`'s existing `callTool` + `JSON.parse` pattern. The surfaced `session_id` is what makes chat follow-ups possible at all. Tests: `workspace-vscode/src/test/suite/mcp-client.test.ts`.
- **Four citation-fidelity defects in compressed-block rendering** — each one produced a `[Lines a-b]` header that lied about the text underneath it, which is the single worst failure mode for a retrieval system whose output an LLM will cite verbatim. All four are fixed in `src/trelix/retrieval/context_compression.py` with regression tests in `tests/unit/test_compression_citation_adversarial.py` and `tests/unit/test_compression_citation_truncated_body.py`:
  - A passthrough result claimed the symbol's **full declared span** even when the stored body had been truncated at index time (`body=…[:2000]` while the AST span stayed complete), so the header advertised lines the text never held. `_fallback_block()` now derives its `end` from the text *actually rendered* — the leading run of real source lines, stopping at the first elision marker — and never from the unmappable spans.
  - A kept span could escape past `line_end` when a parser prepends a synthetic line, making the body's line count and the symbol's declared range disagree. Spans are now filtered against `symbol.line_start <= a <= b <= symbol.line_start + len(body_lines) - 1`, i.e. against the body actually held rather than the declared range.
  - `_envelope()` could emit an **inverted** range such as `[Lines 9000-122]`, claiming a negative-length citation, whenever every kept span lay outside the symbol: the two ends were clamped independently, pairing `max(122, 9000)` with `min(122, 9000)`. It now falls back to the declared range when no span overlaps the symbol, and can no longer return an inverted pair.
  - The trailing `# ... N lines elided ...` count was computed against `symbol.line_end`, so a truncated stored body produced a **bogus** number for lines that were never ours to elide. The tail gap is now measured against `min(symbol.line_end, body_end)`, where `body_end` comes from the real body length.
- **`TRELIX_RETRIEVAL_CONTEXT_TOKEN_BUDGET=null` raised `ValidationError`** — the documented env route to the auto-derived budget did not work. Env values arrive as strings and an `int | None` field cannot coerce `"null"`; since the entire model-aware budget path is gated on `context_token_budget is None`, the feature was reachable only from the Python API, never from env, `.env`, or the CLI. Fixed with a `mode="before"` field validator that maps `""`/`"null"`/`"none"`/`"auto"`/`"~"` (case-insensitive, whitespace-stripped) to `None`. Verified end-to-end: `TRELIX_RETRIEVAL_CONTEXT_TOKEN_BUDGET=null` now yields `context_token_budget=None` with `context_window_fraction=0.5`.
- **`IndexConfig` missing `populate_by_name=True`** — every other aliased-field
  config class in `core/config.py` (`EmbedderConfig`, `GitLinkerConfig`, and 9
  others) sets `populate_by_name=True` in `model_config`; `IndexConfig` was the
  sole exception, added when `file_summaries_enabled`/`telemetry_enabled` first
  gained their `alias=` (unlike every sibling class's identical addition).
  Without it, passing `file_summaries_enabled=`/`telemetry_enabled=` as a
  constructor kwarg by field name was silently ignored — the value fell back
  to the alias env var or default with no error, since `model_config` also
  sets `extra="ignore"`. Fixed by adding the missing `populate_by_name=True`,
  matching every sibling config class.

### Security
- **`trelix audit list` crashed with `MarkupError` on an attacker-controlled request path** — an unauthenticated DoS of the audit tooling, and of exactly the log a responder needs mid-incident. Audit rows store attacker-influenced values (the request path, and an OIDC `sub`), and Rich parses `[...]` in a cell as console markup: a single unauthenticated `GET /%5B/red%5D` persisted the resource `/[/red]`, after which every subsequent `trelix audit list` died before printing a single row. Fixed by passing every cell through `rich.markup.escape()` in `src/trelix/cli/main.py`. Note the asymmetry that made this worth fixing properly: the attacker needs no credentials to write the poisoned row, and the operator loses read access to the whole trail.
- **JWKS fetch had an unbounded read** — `_fetch_jwks()` called `response.read()` with no size cap, so a hostile or compromised issuer serving an endless body drove memory to roughly 660 MB RSS in 0.2s (the socket timeout is per-operation, not a total budget, so it does not bound the response size). Now capped at 1 MiB (`_MAX_JWKS_BYTES`): the reader asks for `cap + 1` bytes and refuses to parse anything larger, which is already absurdly generous for a document that is genuinely a few KB. The same resolver also enforces HTTPS-only, pins the JWKS host to the issuer host, refuses **every** redirect (a redirected JWKS fetch is a trust-boundary break / host-pinning bypass), and bounds the socket timeout.

### Deliberate scope decisions and known limitations
- **SAML is not implemented.** This release ships **OIDC only**, and nothing here should be read as SAML support. SAML's XML-signature and metadata handling is a materially larger and more error-prone attack surface than OIDC's JWS-over-JWKS, and shipping a half-verified SAML path would be worse than shipping none.
- **The audit trail is tamper-EVIDENT, not tamper-PROOF.** The hash chain plus the `count`/`head_hash` anchor reliably catch naive or accidental corruption — a stray `UPDATE`, a truncated file, a dropped tail, a reordered row. They do not stop a determined attacker with write access to `audit.db`, who can rewrite a row *and* recompute every subsequent `entry_hash` plus the anchor in one transaction, after which `verify_chain` passes. The anchor lives in the same file it is meant to protect and is bookkeeping, not an external root of trust. Hardening path if you need a stronger guarantee: sign the head hash with a key held outside the DB (HMAC or asymmetric) and/or anchor it to append-only/WORM storage.
- **Only the HTTP API surface is audited.** `AuditMiddleware` is HTTP middleware, so MCP tool calls and the internal agent loop are **not** on the audited path. A deployment that reaches trelix over MCP rather than over `trelix serve` produces no audit records at all.
- **`retention_days` is declarative only.** `TRELIX_AUDIT_RETENTION_DAYS` (default `365`) records the intended retention window for policy and tooling; no pruning job ships in this release, so the trail grows unbounded until an operator trims it.
- **`resolve_window()` does not resolve provider-prefixed model ids.** Prefix matching is anchored at the start of the string, so Bedrock-style ids (`us.anthropic.claude-…`, `anthropic.claude-3-5-sonnet-…`) fall through to the 12,000-token fallback with a warning rather than to their real 200,000-token window.
- **The one queued breaking change is still deferred.** `RetrievalConfig.flare_max_retries` continues to accept its legacy env alias `TRELIX_RETRIEVAL_FLARE_MAX_ITER` (deprecated in v2.4, still honored via `AliasChoices` with a `DeprecationWarning`). Dropping that alias was the single genuine breaking change reserved for a 3.x release, and it is deliberately **not** in this one — v3.0.0 is a major-version bump for the size of the feature surface, not for an incompatibility. See `docs/ROADMAP.md`.

## [2.12.0] — 2026-08-03

### Overview
Three-phase post-v2.11.1 optimization pass, scoped from a `/deep-research` pass (110 subagents, 27 primary sources) plus direct codebase exploration: a real call-graph/type-edge correctness fix, a per-leg RRF weight config activating an already-built-but-unwired fusion mechanism, and a bundle of four independent hardening/doc/CI items — including a previously-unknown packaging gap affecting every downstream consumer of the `trelix` PyPI package. All new surface is additive/opt-in; no breaking changes.

### Fixed
- **Call-graph/type-edge resolver silently picked the wrong symbol on a name collision** — `Indexer._store_call_edges()`/`_store_type_edges()` resolved a bare-name match by taking `matches[0]` unconditionally from `Database.get_symbol_by_name()`, with zero ambiguity check. When two classes defined a same-named method (e.g. `Retriever.retrieve` vs `FederatedRetriever.retrieve`), every call site anywhere in the codebase got wired to whichever symbol had the lower DB id, regardless of which one was actually called — violating a documented design invariant (`docs/architecture.md` §21 #5: "a wrong edge is worse than a missing edge"). The safe 4-priority cascade already existed in `Database.resolve_cross_file_calls()`, but that only runs for batches ≥5 files — a single-file watch re-index never reached it. Fixed by inlining the same priority cascade (exact qualified_name match, unique among candidates → type-hint-assisted match, unique among candidates → unique bare-name match → else unresolved) via a new `Indexer._resolve_symbol_match()` helper shared by both call- and type-edge resolution. Measured on trelix's own self-index: 56/65 incorrectly-resolved same-named-method calls → 4/61 correctly resolved (remainder correctly left unresolved); ~2,400 provably-wrong call edges removed codebase-wide.
- **`core/retry.py`: unbounded `Retry-After` value crashed the retry loop** — `_wait_retry_after_or_exponential` now clamps a server-supplied `Retry-After` value to `max_wait_seconds` before returning it. A hostile/malformed header (e.g. `Retry-After: 99999999999999999999999999999999`) previously reached `time.sleep()` unbounded, raising `OverflowError` and crashing the retry loop instead of retrying or failing cleanly — bypassing `stop_after_attempt` entirely. Affected every `@with_retry`-wrapped call site (all connectors, all LLM/embedder backends).
- **`indexing/connectors/jira.py`: unbounded ADF recursion crashed on deep descriptions** — `_adf_node_to_text()` now tracks recursion depth and truncates past `_ADF_MAX_DEPTH` (150 — empirically verified safe to 50,000+ nesting levels, since each ADF level costs more than one real Python stack frame). A sufficiently deep Jira description previously raised an uncaught `RecursionError`, aborting the entire connector sync run over one malformed document.
- **`trelix`'s own PyPI package shipped with no `py.typed` marker (PEP 561)** — without it, mypy silently treated every `trelix` import as `Any` once checked across the installed-package boundary, masking real type errors in every downstream package. Added `src/trelix/py.typed` (verified correctly bundled into a real built wheel) and fixed every newly-visible error in `trelix-mcp`/`trelix-langchain`/`trelix-llama-index` (missing return-type annotations, an untyped decorator chain, a genuine mypy list-invariance bug in `resources.py`'s symbol-lookup fallback).
- **`packages/trelix-mcp`'s `mcp`/`fastmcp` dependency floor was stale and would have been wrong if naively bumped** — the declared `mcp>=1.0.0` floor was stale, but bumping straight to latest (`mcp==2.0.0`) would have made `trelix-mcp` uninstallable alongside `fastmcp` (whose own latest release pins `mcp<2.0,>=1.24.0` — confirmed via a real `pip install` reproduction that fails with `ResolutionImpossible`). Set to `mcp>=1.24.0,<2.0` / `fastmcp>=3.4.0`, matching what's actually installable and was tested against.

### Added
- **Per-leg RRF weight config** — new `RetrievalConfig.leg_weights: dict[str, float]`, keyed by `vector`/`bm25`/`grep`/`summary`/`sub_chunk`/`sparse`, all default `1.0` (a no-op). Threaded through the primary single-repo `reciprocal_rank_fusion(...)` call site via the mechanism's pre-existing `list_weights=` param — already implemented, tested, and in production use by `FederatedRetriever` for per-repo weighting, just never wired up outside federation. Activates investigation of RRF's documented "weakest-link" failure mode (a weak retrieval leg fused with a strong one can drag the strong leg's score below what it would score alone — VLDB 2026, 11-dataset benchmark) without shipping any new default weights. Env var overrides: `TRELIX_RETRIEVAL_LEG_WEIGHT_<VECTOR|BM25|GREP|SUMMARY|SUB_CHUNK|SPARSE>`, mirroring the existing `TRELIX_RETRIEVAL_FILE_TYPE_WEIGHT_<LANG>` pattern.
- **`docs/CLI_REFERENCE.md`: documented `trelix eval-synthesis`** — the command existed with zero documentation. New section covers Synopsis/Description/Options/Examples/Golden file format/Output/Notes, including a genuine discovered gotcha: unlike `trelix eval`, a missing golden file for `eval-synthesis` does not error or exit non-zero — it silently prints an all-zero-score table.
- **CI now lints and type-checks `packages/trelix-mcp`, `packages/trelix-langchain`, and `packages/trelix-llama-index`** — previously unchecked anywhere, CI or locally. This is what surfaced the `py.typed` gap and the dependency-floor landmine above.

## [2.11.1] — 2026-08-02

### Security
- **`/graph/visualize` output-path containment bypass via sibling directory** —
  the `output` query param's containment check used a raw string-prefix
  match (`str(requested).startswith(str(allowed))`) to confirm the resolved
  path stays inside `<repo>/.trelix/`. A sibling directory that merely
  starts with the same characters — e.g. `<repo>/.trelix-evil/x.html` —
  passed this check, letting a caller write an arbitrary-named HTML file
  outside the intended directory. `/parse` already fixed this exact bug
  class earlier in the same file (`src/trelix/api/app.py`, with a comment
  explicitly warning about the string-prefix pitfall), but the fix was
  never back-ported to `/graph/visualize`. Fixed by switching to
  `Path.is_relative_to()`, mirroring `/parse`'s existing correct check.
  Severity: MEDIUM — a file write of graph HTML, not arbitrary read or
  RCE, and only reachable when `TRELIX_API_AUTH_TOKEN` is unset (default)
  or the caller already has a valid API key. Found during a full
  production dry-run of v2.11.0's REST API surface (path-traversal probing
  against a live container). New regression tests in
  `tests/unit/test_api_graph.py::TestGraphVisualizeContainment` (4 cases,
  confirmed fail-before/pass-after against the reverted check).

## [2.11.0] — 2026-08-02

### Overview
Six backlog phases plus four follow-up fixes: connector-fetched artifacts now auto-link into `generic_edges` on sync, opt-in Personalized PageRank for cross-source ranking, a unified retry/backoff contract shared by every LLM backend/embedder/connector/reranker/PR client, structured JSON logging with trace correlation, a new Xray Cloud connector, and a new Linear connector — plus two real bugs found by live-testing the Jira connector against a production Jira Cloud site (ADF descriptions silently dropped to empty bodies; bad credentials silently reported as success), a `.env`-leakage test-isolation fix, and a Windows binary crash caught by this release's own pre-`main` CI run (structured logging's new `structlog` dependency triggering a `colorama`/Rich console conflict). All new surface is additive/opt-in; no breaking changes.

### Added
- **Connector-to-graph auto-linking** — new `ArtifactLinker` (`src/trelix/indexing/artifact_linker.py`) scans each connector-fetched artifact's title/body for symbol name/qualified-name mentions (regex-first, identical precedent to `GitLinker`'s commit-message matching) and writes `generic_edges` rows with `edge_kind="references_artifact"`, `weight=1.0`. An opt-in embedding-similarity fallback (`TRELIX_ARTIFACT_LINKER_EMBEDDING_FALLBACK`, default `False`) runs only for artifacts with zero regex matches, at `weight=0.5` so lower-confidence matches don't dominate PageRank mass. `ArtifactSource.sync()` gained an optional `linker: ArtifactLinker | None` param — when supplied, each successfully-written artifact is immediately passed through `linker.link_one()`, so a synced artifact is reachable from the code graph the moment `sync()` returns, with no separate pass required. New standalone CLI command `trelix link-artifacts <repo>` for a batch re-link (e.g. after a schema/symbol change). `trelix connector sync` gained a `--link/--no-link` flag (default `--link`) and now reports a `linked N edge(s)` count. `ConnectorSyncResult` gained an `edges_linked: int = 0` field. New `Database.get_all_symbol_names()`/`get_all_artifacts()` bulk queries backing the linker's per-`link()`-call name index (built once, not per-artifact, to avoid an O(artifacts × symbols) scan).
- **Personalized PageRank (opt-in)** — new `RetrievalConfig.pagerank_personalization_enabled: bool = Field(default=False, alias="TRELIX_RETRIEVAL_PAGERANK_PERSONALIZATION")`. Both `rank_by_pagerank()` (`retrieval/graph.py`, query-time) and `compute_pagerank()` (`graph/community.py`, index-time) now pass `personalization=` into `nx.pagerank()` when enabled: uniform mass `1/|T|` over every node with at least one `generic_edges`-derived artifact/ticket relationship, falling back to today's uniform teleportation when the flag is off or the seed set is empty — zero behavior change for anyone not opting in. Ships with a documented interaction-risk note against `pagerank_boost_enabled` (personalization's teleport mass isn't weighted by call-graph importance, so on a repo with few ticket-linked symbols, enabling both together can invert `get_top_central_symbols()`'s ranking).
- **Unified retry/backoff contract** — new `src/trelix/core/retry.py`, built on `tenacity`: `is_retryable_http_error()` classifies 429/5xx and connection-level failures as retryable (recognizing httpx/requests/boto3/openai/anthropic/google-genai/voyageai exception shapes without hard-importing any of them) and `with_retry(max_attempts=5, ...)` returns a `@retry` decorator honoring a server-supplied `Retry-After` header when present (parses both integer-seconds and HTTP-date forms per RFC 9110 §10.2.3), falling back to full-jitter exponential backoff otherwise. Wired into all 5 LLM backends (OpenAI/Anthropic/Bedrock/LiteLLM/Vertex), all remote embedder providers, `GitHubPRClient`, `reranker.py`'s Cohere reranker, and the Jira/TestRail connectors — replacing each connector's previous hand-rolled, non-jittered backoff loop. Also disables each SDK's own built-in retry (`max_retries=0` for OpenAI/Anthropic clients, `botocore.Config(retries={"max_attempts": 0})` for boto3-backed Bedrock) so the shared contract is the sole retry layer, avoiding multiplicative retry stacking.
- **Structured logging** — new `src/trelix/core/logging_setup.py`: `setup_console_logging()` (human-readable, used by every CLI command) and `setup_json_logging()` (`structlog.stdlib.ProcessorFormatter`-based JSON, used by `trelix serve`), both built on the same processor chain so the ~164 existing `logger.*` call sites across the codebase need no rewrite. When `TRELIX_OTEL_ENABLED=true`, a processor injects the active span's `trace_id`/`span_id` into every JSON log line, correlating logs with the existing OpenTelemetry traces. `trelix serve` now passes a matching `uvicorn_log_config()` to `uvicorn.run()` so access-log lines are JSON too, not half-JSON/half-default-colorized-text.
- **Xray Cloud connector** — fourth `ArtifactSource` implementation (`src/trelix/indexing/connectors/xray.py`), Cloud-only. Auth: `client_id`/`client_secret` (issued by a Jira admin in Xray's global settings, distinct from a personal Jira API token) exchanged via `POST /api/v2/authenticate` for a short-lived bearer JWT. Fetches test content via a single GraphQL `getTests` query per page (Jira issue fields and Xray-specific steps/definition both come back in one call — no separate Jira REST call needed), `limit`/`start` pagination. New `XrayConnectorConfig` (`TRELIX_XRAY_CLIENT_ID`/`CLIENT_SECRET`/`PROJECT_KEY`/`JIRA_BASE_URL`, `page_size` default 100).
- **Linear connector** — fifth `ArtifactSource` implementation (`src/trelix/indexing/connectors/linear.py`). Auth: personal API key sent as `Authorization: <key>` — **no Bearer prefix**, Linear's own documented scheme, distinct from every other connector in this codebase. GraphQL-only (single POST to `https://api.linear.app/graphql`, no official Python SDK exists), Relay-style cursor pagination (`first`/`after`/`pageInfo.hasNextPage`/`endCursor`), scoped to one team via `TRELIX_LINEAR_TEAM_KEY`. Rate-limit handling is deliberately connector-local rather than folded into the shared retry contract: Linear signals rate-limiting via HTTP 400 (not 429) with a GraphQL body error code `RATELIMITED` and no `Retry-After` header — instead reading `X-RateLimit-*-Reset` response headers (epoch-ms) — which the shared `is_retryable_http_error()` cannot and should not be taught, since that would couple a contract shared by every other connector/LLM backend to one connector's response shape. `source_ref` uses a `linear-issue:` prefix (not Jira's `ticket:`) to avoid a silent collision if a Jira project key and Linear team key ever coincided. New `LinearConnectorConfig` (`TRELIX_LINEAR_API_KEY`/`TEAM_KEY`, `page_size` default 100). Live-verified end-to-end against a real Linear workspace: fetch, cursor pagination, idempotent re-sync, `ArtifactLinker` auto-linking into `generic_edges`/`CodeGraph`/PageRank, `--no-link`, missing-config validation, and a real 401 all confirmed working.
- **`trelix connector sync`** now accepts `xray` and `linear` alongside `jira`/`testrail`; `docs/CLI_REFERENCE.md`/`docs/CONFIGURATION.md` updated for both (and backfilled the pre-existing gap where Xray was never documented after its own merge).

### Fixed
- **Jira ADF descriptions silently rendered as empty bodies, on every real ticket** — found by live-testing the Jira connector against a production Jira Cloud site (not previously caught, since it had only ever been exercised via mocked HTTP responses): Jira Cloud's v3 API always returns `description` as Atlassian Document Format (a nested JSON tree), never a plain string, and the connector's `isinstance(description, str)` check fell back to an empty body for every single ticket — not a rare edge case, the universal case. Fixed with a new `_adf_to_text()` renderer (`src/trelix/indexing/connectors/jira.py`) covering every node type confirmed against real descriptions: paragraphs, headings, bullet/ordered lists, code blocks, inline code, panels, expand sections, rules, links (rendered inline as `text (url)`), and embedded cards, with unrecognized future node types degrading to rendering their children rather than being dropped. Live-verified against a real project: body length went from 0 chars (all 5 tickets) to 497–6529 chars of real content each, and `ArtifactLinker`'s auto-link count on the same 5 tickets went from 2 edges (title-text matches only) to 5 — direct evidence real linking recall was silently lost, not just cosmetic body text.
- **Jira connector silently reported success on bad credentials** — also found live: `/rest/api/3/search/jql` returns HTTP 200 with an empty result set (`{"issues":[],"isLast":true}`) for a bad API token, no auth at all, *and* a genuinely empty/nonexistent project — all three byte-identical, meaning a misconfigured `TRELIX_JIRA_API_TOKEN` would report `fetched 0, wrote 0, errors 0` as success forever. Fixed by adding a pre-flight `_verify_auth()` call to `/rest/api/3/myself`, which correctly returns a real 401 for bad/missing credentials, before the search loop ever runs. Live-verified: a bad token now fails with `401 Unauthorized`/exit code 1 instead of silently succeeding; real credentials against the live project are unaffected.
- **`.env`-leakage test-isolation gaps for Linear/Jira/TestRail connector tests** — `tests/unit/conftest.py`'s isolation fixture only covered a handful of beast-mode flags; a developer's real `TRELIX_LINEAR_*`/`TRELIX_JIRA_*`/`TRELIX_TESTRAIL_*` credentials in `.env` (added for the live-testing above) silently broke each connector's "missing config" unit test, since `monkeypatch.delenv()` only clears the process environment while pydantic-settings' `.env`-file source reads the file directly and independently. Fixed by overriding those vars to `""` (or `"0"` for `TestRailConnectorConfig.project_id`, which is `int | None` and can't parse an empty string) — both falsy, so every `if not val` `validate_config()` check treats them identically to unset.
- **Windows binary crashed on every command once `stats` gained `_setup_logging()`** — found by this release's own pre-`main` CI run (the Windows binary-build job, not a unit test): `structlog`, added this cycle as a new direct dependency, ships a `ConsoleRenderer` whose `colors` argument auto-defaults to `True` on Windows whenever `colorama` is importable (already a transitive dependency here). Constructing it therefore called `colorama.init()`, which monkeypatches `sys.stdout`/`sys.stderr` into `AnsiToWin32`/`StreamWrapper` objects — confirmed to collide with Rich's own `legacy_windows_render` write path on the same stream once both are active, crashing with `OSError: [Errno 22] Invalid argument` the next time Rich printed (e.g. `stats`'s summary table). This codebase's actual color output has always come from Rich (`cli/main.py`'s `Console`/`Panel`/`Table`), never from structlog's renderer, so the coloring was pure incidental risk with no product benefit. Fixed by constructing `ConsoleRenderer(colors=False)` in `setup_console_logging()` (`src/trelix/core/logging_setup.py`). New regression test `test_console_renderer_never_requests_colors` (`tests/unit/test_structured_logging.py`) asserts the real constructor argument.

### Known non-blocking issues (found during pre-release security review, not fixed this cycle)
- `core/retry.py`'s `Retry-After` header handling has no upper bound — a hostile or unrealistically large value (e.g. `Retry-After: 99999999999999`) causes `time.sleep()` to raise an uncaught `OverflowError`, bypassing `stop_after_attempt` entirely; even a plausible large value (e.g. 6 hours) is honored verbatim past the configured `max_wait_seconds` ceiling. Affects every `@with_retry`-wrapped call site (all connectors, all LLM/embedder backends).
- `jira.py`'s `_adf_node_to_text()` recurses over nested ADF content with no depth limit — a sufficiently deep `description` (500+ levels) raises an uncaught `RecursionError`, aborting the sync run.
- Both require a malicious/misbehaving external API response to trigger (crash/hang, not credential leak or data corruption) and are tracked as fast-follow items, not release blockers.

## [2.10.0] — 2026-07-28

### Overview
Five backlog phases plus two follow-up fixes: REST API-key auth + HTTP-layer OpenTelemetry spans, a new `/parse` endpoint + opt-in per-source context budgeting, leg-level path filtering + intent hints for `/search`/`search_code`, cross-source graph edges via a git-log ticket linker, and Jira/TestRail artifact connectors — plus a path-traversal fix discovered in `/parse` during this cycle and a `generic_edges` dedup fix. All new surface is additive/opt-in; no breaking changes.

### Added
- **REST API-key auth (`TRELIX_API_AUTH_TOKEN`)** — new `_ApiAuthSettings(BaseSettings)` in `src/trelix/api/app.py` (single field `api_auth_token: str | None = None`, env alias `TRELIX_API_AUTH_TOKEN`, loaded from `.env`/environ once per `create_app()` call — this lives standalone in `app.py`, not folded into `core/config.py`/`IndexConfig`). New `verify_api_key` FastAPI dependency wired via `dependencies=auth` onto every route except `/health`: `/search`, `/ask`, `/index`, `/stats`, `/graph`, `/graph/communities`, `/graph/visualize`, `/graph/search`. Token unset (default) → fully open, identical to prior behavior. Token set + header missing → `401` (short-circuits on `x_trelix_api_key is None`, before any comparison). Token set + wrong header → `401` via `hmac.compare_digest` (timing-safe compare). All `401`s log a warning; `/health` is excluded from `dependencies` outright rather than merely bypassed in logic. Tests: `tests/unit/test_api.py::TestApiAuth` (4 cases) plus a `conftest.py` fixture that `delenv`s the token so unrelated tests stay unauthenticated.
- **OpenTelemetry spans for the HTTP layer** — the same 8 auth-gated routes now wrap their handler bodies in `pipeline_stage_span(config.retrieval, "http_<name>", ...)`, reusing v2.9.0's existing `retrieval/otel_tracing.py` helper: `http_search` (attrs `k`/`cursor`), `http_ask`, `http_index`, `http_stats`, `http_graph`, `http_graph_communities`, `http_graph_visualize`, `http_graph_search`. No new package import; still gated by `TRELIX_OTEL_ENABLED`/`is_enabled(cfg)` and a no-op when disabled.
- **Helm**: new `apiAuth.token` / `apiAuth.existingSecretName` / `apiAuth.existingSecretKey` in `values.yaml`, wired into `deployment.yaml` (an `existingSecretName` wins over the inline token) and `secret.yaml` (writes `stringData` only when an inline token is set and no existing secret is named).
- **`POST /parse`** — a new one-off parse endpoint (`ParseRequest`/`ParseResponse`, `src/trelix/api/app.py`). Request: `repo_path: str` (required), `file_path: str | None` (disk-backed, relative or absolute), `content: str | None` (inline text), `file_name: str | None` (required only when `content` is set). A `model_validator` rejects with `422` unless exactly one of `file_path`/`content` is set, and rejects with `422` when `content` is set without `file_name`. Response: `symbols: list[{name, qualified_name, kind, line_start, line_end, signature}]`, `call_edge_count`/`import_edge_count`/`type_edge_count`, `parse_errors`, and a `note` that explicitly states cross-file call/type resolution was skipped for this single-file parse (or reports "No parser available for language ..." for an unrecognized extension).
- **Per-source context budgeting** — new `RetrievalConfig.context_budget_per_source: bool = Field(default=False, alias="TRELIX_RETRIEVAL_CONTEXT_BUDGET_PER_SOURCE")` in `src/trelix/core/config.py`. Default `False` reproduces the prior single-pool greedy pack byte-for-byte. `ContextAssembler` gained a matching `per_source_budget` constructor param, wired through `Retriever`.
- **Leg-level path filtering** — new `SubQuery.path_filter: str | None = None` (`src/trelix/retrieval/planner/models.py`) restricts a leg's results to files whose `rel_path` starts with the given prefix, plus `RetrievalConfig.path_filter_oversample: int = 3` (`ge=1`, env `TRELIX_RETRIEVAL_PATH_FILTER_OVERSAMPLE`). Wired per leg: the grep leg passes `path_filter=sq.path_filter` straight into `grep_search()`; the BM25 leg pushes it into `db.bm25_search`'s SQL join (`f.rel_path LIKE ?`); the vector leg (`Retriever._vector_search`) over-fetches `k * path_filter_oversample`, post-filters by `rel_path.startswith(path_filter)`, then truncates back to `k`.
- **`intent_hint`/`hyde_snippet_hint` on `/search` and `search_code`** — identical new optional params added to REST `GET /search` (`src/trelix/api/app.py`) and MCP `search_code(...)` (`packages/trelix-mcp/src/trelix_mcp/server.py`). Both call `plan_from_intent_hint(query, intent_hint, hyde_snippet_hint)` when `intent_hint` is given and pass the result as `plan=plan` into `Retriever.retrieve()` — no changes needed inside `Retriever` itself. An unrecognized `intent_hint` never raises: `plan_from_intent_hint()` catches the `IntentType(intent_hint)` `ValueError` and also checks membership in `INTENT_STRATEGIES`, returning `None` either way so the query silently falls back to `Retriever`'s normal internal LLM-based intent classification.
- **Cross-source graph edges + git-log ticket linker** — new `generic_edges` table (`src/trelix/store/db.py`, via `_apply_migrations()`): `id`, `from_symbol_id` (FK → `symbols.id`, `ON DELETE CASCADE`), `source_ref` (free-form `"<type>:<ref>"`, e.g. `"ticket:PROJ-123"`), `edge_kind`, `weight REAL DEFAULT 1.0`, with indexes on `from_symbol_id` and `source_ref`. New CLI command `trelix link-tickets <repo>` (`src/trelix/cli/main.py`) with `--max-commits` (int, default 5000), `--since` (e.g. `"90 days ago"`, passed to `git log --since`), `--ticket-pattern` (regex, default `r"[A-Z]+-\d+"`, Jira-style). `GitLinkerConfig.enabled` defaults to `False`, and the linker is not wired into `Indexer.index()` — it's reachable only via `link-tickets`. `rank_by_pagerank()` (`src/trelix/retrieval/graph.py`) now also pulls each symbol's `generic_edges` targets via `db.get_generic_edge_targets(symbol_id)` and adds them as bidirectional `symbol<->source_ref` edges into the same PageRank graph as CALLS edges — one-way `symbol->ticket` edges would only boost the ticket node since PageRank propagates via incoming edges. Results are filtered to `isinstance(sid, int)` afterward to drop the synthetic ticket nodes before returning. The PageRank algorithm itself is unchanged — plain `nx.pagerank(G, alpha=0.85)` with uniform teleportation, no Personalized PageRank — only new edges were added to the existing graph. The same bidirectional pattern is mirrored in `CodeGraph._build()` (`graph/code_graph.py`).
- **Jira/TestRail artifact connectors** — new `ArtifactSource` ABC (`src/trelix/indexing/connectors/base.py`, abstract `validate_config()`/`fetch()`, concrete `sync(db_writer: ArtifactWriter) -> ConnectorSyncResult` orchestrating validate → fetch → `db_writer.upsert_artifact()` per item) and an `ArtifactWriter` `Protocol` (`upsert_artifact(artifact: Artifact) -> int`) — deliberately not built on `BaseParser`, since tickets/test cases have no file-id/line-span concept. New env-var-only config in `src/trelix/core/config.py`: `JiraConnectorConfig` (`base_url`/`email`/`api_token`/`project_key` via `TRELIX_JIRA_*`, `page_size` default 100) and `TestRailConnectorConfig` (`base_url`/`username`/`api_key`/`project_id` via `TRELIX_TESTRAIL_*`, `page_size` default 250, capped at 250). New CLI command `trelix connector sync <repo> <jira|testrail>` (new `connector` Typer sub-app, `src/trelix/cli/main.py`) — no REST route was added. This phase writes only to the new `artifacts` table via `db.upsert_artifact()`; it deliberately does **not** create `generic_edges` rows — artifact-to-code linkage is `trelix link-tickets`'s job (or a future writer's), so Jira/TestRail artifacts are indexed but not yet wired into the PageRank graph.
- **`tests/eval/cross_source_pagerank_eval.py`** — a standalone decision-support script (run manually via `python -m tests.eval.cross_source_pagerank_eval`, not wired into any `Makefile` target or CI workflow) measuring the effect of the new cross-source edges on retrieval and ranking. Against `TRELIX_SELF_CASES` (50 queries): recall@5 0.540→0.580 (+0.040), MRR 0.274→0.296 (+0.022), NDCG@10 0.362→0.393 (+0.031), with 4,011 edges inserted across 2,438 distinct symbols and 16 distinct `#NNN` tickets; of 25 seed symbols, 22 gained a `generic_edge`, and 95.45% of those (21/22) saw their PageRank rank position change (mean |delta| 2.77, median 2.00 positions). This is eval evidence that the new bidirectional edges measurably help ranking — it is **not** an implementation of Personalized PageRank, which remains unbuilt; the underlying algorithm is still plain uniform-teleportation `nx.pagerank`.

### Security
- **`/parse` path traversal (unauthenticated arbitrary file read)** — the disk-backed branch of `/parse` took `body.file_path` and joined it under `repo_path` only when it wasn't already absolute, without ever resolving or checking containment. An absolute `file_path` (e.g. `/etc/passwd`, or any file the server process could read) was read verbatim regardless of `repo_path`, and a relative path containing `../` segments could walk out of `repo_path` entirely — the response then leaked real file contents back to the caller as parsed symbols. Because `TRELIX_API_AUTH_TOKEN` is unset by default (see Added, above), this was exploitable with no authentication on any deployment that hadn't explicitly opted into the new API auth. Fixed by resolving both `repo_root` and the target `path` via `Path.resolve()` and rejecting with `400` unless `path.is_relative_to(repo_root)` — the same containment check `/graph/visualize` already used, deliberately `is_relative_to()` rather than a string-prefix match so a sibling directory like `<repo>-evil` can't falsely pass.

### Fixed
- **Re-running `trelix link-tickets` on the same repo duplicated `generic_edges` rows** — `GitLinker.link()`'s in-memory `seen` set only deduped within a single call, so a cron re-sync or simply re-running the CLI twice inserted a second identical row per `(symbol, ticket)` pair. Fixed by adding `CREATE UNIQUE INDEX idx_generic_edges_dedup ON generic_edges(from_symbol_id, source_ref, edge_kind)` and changing `insert_generic_edges()` from a plain `INSERT` to `INSERT OR IGNORE`, so a re-run is now a DB-level no-op. New regression test `test_rerunning_link_on_same_repo_does_not_duplicate_edges` (`tests/unit/test_git_linker.py`) fails at 2 rows without the fix and passes at 1 row with it.
- **`ghcr.io/sairam0424/trelix:X.Y.Z-local` Docker image failed to build/publish** —
  `Dockerfile`'s `pip install ".[serve,local]"` resolved PyPI's default `torch`
  wheel, which bundles the full CUDA/NVIDIA runtime (`nvidia-cublas`,
  `nvidia-cudnn`, `cuda-toolkit`, ...) even though this container never has
  GPU access. That bloat exhausted the GitHub-hosted runner's disk during the
  emulated `linux/arm64` build (`OSError: [Errno 28] No space left on device`,
  surfaced on the v2.9.0 release). Fixed by adding
  `--extra-index-url https://download.pytorch.org/whl/cpu`, so pip resolves
  torch's CPU-only wheel (~104MB vs. multi-GB with the CUDA stack) instead —
  a no-op for the slim (`EXTRAS=serve`) variant, which never installs torch.
  Also added a `workflow_dispatch` trigger to `docker-publish.yml` to backfill
  a version whose Docker publish failed without cutting a new release tag.
- **`docker-publish.yml`'s `workflow_dispatch` backfill never moved `:latest`/
  `:latest-local`**, even when backfilling the current release's own missing
  variant (e.g. `2.9.0-local` right after `2.9.0` shipped) — the guard added
  to prevent an *older*-release backfill from repointing `:latest` backwards
  was too broad and blocked the common case too. Added an explicit
  `move_latest` boolean input (default `false`) so backfilling the current
  release can opt in, while backfilling an older one still can't touch
  `:latest` by default.
- **Every CLI command and the MCP `index_codebase` tool silently overrode
  `TRELIX_EMBEDDER_PROVIDER`** — `--provider` always defaulted to the literal
  string `"local"` rather than `None`, and `EmbedderConfig` is a
  pydantic-settings model where an explicit constructor kwarg always wins
  over the env var. A user who set `TRELIX_EMBEDDER_PROVIDER` (the
  documented way to configure a default provider) and never touched
  `--provider` on a given invocation would silently index/search with the
  local embedder instead, with no warning — surfacing later as a confusing
  `DimensionMismatchError` once a real provider's vectors got mixed in.
  Fixed by defaulting `--provider`/`provider` to `None` everywhere and only
  passing it to `EmbedderConfig` when actually supplied, via a new
  `_build_embedder_config()` helper (`src/trelix/cli/main.py`) used by all
  7 CLI commands plus the MCP server's `index_codebase` tool.
- **CLI error messages containing literal square brackets rendered mangled
  or misleading** — e.g. the local-embedder-missing error's fix instruction,
  `pip install 'trelix[local]'`, rendered as `pip install 'trelix'` (the
  exact broken command the user had already run), because Rich interprets
  `[...]`-shaped substrings in `console.print()` calls as markup tags and
  silently strips/mangles unrecognized ones. Every `err_console.print(f"[red]...{exc}...")`
  call site in `src/trelix/cli/main.py` (34 sites) now routes through a new
  `_print_error()` helper that escapes the dynamic text via
  `rich.markup.escape()` before interpolation, preserving literal brackets
  while keeping the surrounding color markup intact.
- **macOS PyInstaller binary crashed on every real `index`/`search` call**
  with `'sqlite3.Connection' object has no attribute 'enable_load_extension'`
  — macOS's system-style Python (what `actions/setup-python` provisions on
  GitHub's macOS runners) builds its bundled `sqlite3` without
  `SQLITE_ENABLE_LOAD_EXTENSION`, which `sqlite-vec` requires to load its
  extension. Reproduced identically on both v2.8.1 and v2.9.0 binaries —
  pre-existing, not a v2.9.0 regression, but the binary distribution's core
  workflow was completely non-functional with zero warning to users.
  `build-binaries.yml`/`release.yml`'s macOS job now provisions Python via
  `astral-sh/setup-uv` instead (a `python-build-standalone` interpreter,
  confirmed to support `enable_load_extension`); Windows/Linux are
  unaffected and unchanged. All three platforms' binary-verify steps now
  also run a real `index --provider openai` smoke test (with a bogus API
  key — the bundled binary excludes `sentence-transformers`/`torch`, so
  `--provider local` can never work there; `SQLiteVectorStore`'s
  `sqlite-vec` load happens before the network call, so this still
  exercises the regression without needing real network egress) and
  asserts the crash string is absent plus `trelix stats` shows real
  progress, so a regression like this fails CI immediately instead of
  shipping silently.
- **`astral-sh/setup-uv` still didn't fix the macOS binary — `uv venv
  --python 3.11` picked up the runner image's pre-installed
  `/usr/local/bin/python3.11` (Homebrew) instead of downloading its own
  `python-build-standalone` interpreter**, silently defeating the previous
  fix; confirmed via a real CI run where the `enable_load_extension` crash
  came right back. `uv` prefers an already-discoverable interpreter over
  downloading a new one unless told otherwise. Added `--managed-python` to
  force `uv` to use its own downloaded interpreter.
- **Windows release binary crashed on every command that renders Rich's
  progress spinner** with `'charmap' codec can't encode character
  '⠋'` — Rich's default spinner uses Unicode braille glyphs, which
  Windows' legacy console codepage (`cp1252` etc.) can't encode. Surfaced
  by the new binary smoke test above (the old `--help`-only check never
  rendered a spinner). Pre-existing, not a v2.9.0 regression — any real
  Windows user in a non-UTF-8 terminal would hit this. Fixed by
  reconfiguring `sys.stdout`/`sys.stderr` to UTF-8 with
  `errors="replace"` at CLI startup, before any `rich.Console` is
  constructed — a no-op on terminals already using UTF-8 (macOS/Linux,
  or Windows Terminal with UTF-8 active).
- **The binary smoke test itself assumed `trelix index --provider openai`
  with a bogus key always exits 0** — it doesn't: whether Phase 2's
  per-file summary/sub-chunk embedding (both off by default) or Phase 3's
  batch embed hits the bad key first determines the exit code, and
  Phase 3's `embed_async()` call has no local `try`/`except`, so a real
  auth failure there propagates all the way to `typer.Exit(1)`. Wrapped
  the `index` invocation in a subshell with `|| true` so the smoke test's
  own exit code no longer depends on whether the deliberately-invalid
  API key happens to fail before or during the real embedding phase —
  only the crash-string check and the follow-up `stats` progress check
  matter.

## [2.9.0] — 2026-07-24

### Overview
Seven backlog items shipped: TypeScript SDK, typed REST API responses + `/search`
pagination, OpenTelemetry tracing, Python 3.13 support, Docker/Helm deployment,
VS Code extension hardening + search refinement, and GitHub App GA hardening.
1,643 unit tests passing, all features additive/opt-in — no breaking changes
(the `flare_max_iterations` removal originally slated for v3.0.0 remains
deliberately deferred; see `docs/ROADMAP.md`).

### Added
- **`@trelix/sdk` TypeScript client** (`packages/trelix-typescript`) — a hand-written
  HTTP client for the `trelix serve` REST API, with types generated from the
  live OpenAPI schema (`openapi-typescript`) and a thin, hand-glued
  `TrelixClient` class on top. Covers every route (`health`, `search`
  with cursor pagination, `index`, `stats`, `graph`, `graph/communities`,
  `graph/visualize`, `graph/search`) plus a separate `askStream()` async
  generator for `/ask`'s SSE stream (tokens, `[DONE]`, and a
  `TrelixAskError`-throwing `[ERROR: ...]` frame).
- **Typed REST API response models** — every `trelix serve` route now
  declares a real Pydantic response model (`SearchResponse`,
  `IndexResponse`, `StatsResponse`, `GraphStatsResponse`,
  `CommunitySummaryModel`, `GraphVisualizeResponse`,
  `GraphSearchResultModel`), so the auto-generated OpenAPI schema
  (`/openapi.json`) carries real per-field types instead of an untyped
  `object`/`array`. Groundwork for an OpenAPI-codegen'd TypeScript client.
- **`GET /search` cursor pagination** — gained a `cursor` query param and now
  returns `{results, next_cursor, total_available}` instead of a bare list,
  matching the MCP `search_code` tool's existing pagination contract
  exactly. This is the one deliberate, narrowly-scoped response-shape
  change in an otherwise additive pass — done now, before a TS SDK locks in
  against the old bare-list shape.
- **OpenTelemetry tracing for the retrieval pipeline** — opt-in via
  `pip install trelix[otel]` + `TRELIX_OTEL_ENABLED=true` (off by default,
  zero import cost and zero behavior change when disabled). Emits one
  `gen_ai.*`-conventions retrieval span per leg (vector, BM25, grep, sparse,
  sub-chunk, file-summary) via `opentelemetry-util-genai`'s
  `TelemetryHandler.retrieval()`, plus `trelix.*`-namespaced pipeline-stage
  spans (planner, fusion, expansion, rerank, pagerank boost, assembly).
  Correctly nests leg spans under the query's root span across the
  `ThreadPoolExecutor` boundary used for parallel sub-query execution (OTel's
  context is contextvars-based and does not cross thread pools on its own).
  New optional `OTEL_EXPORTER_OTLP_ENDPOINT` exports to any OTLP collector.
  See `docs/OBSERVABILITY.md` for the full span reference and a stability
  caveat (the `gen_ai.*` conventions are officially adopted but still
  "Development," not yet "Stable," upstream).
- **Python 3.13 support** — `requires-python` no longer caps at `<3.13`.
  The only blocker was `tree-sitter-languages` (abandoned upstream, no
  cp313 wheels); swapped for the actively-maintained, API-compatible
  `tree-sitter-language-pack` behind the single existing chokepoint,
  `src/trelix/indexing/parser/_grammar.py`. Bumped `tree-sitter>=0.23`
  and `pydantic>=2.8.0` (3.13-compatible floors). CI matrix now runs
  3.11/3.12/3.13.

### Changed
- **Tree-sitter grammar loading is now network-on-first-use, not bundled.**
  `tree-sitter-language-pack` fetches each language's compiled grammar
  over the network on first use and caches it locally (unlike the old
  `tree_sitter_languages`, which bundled every grammar in its wheel).
  Call `trelix.indexing.parser._grammar.prefetch_all()` once (e.g. during
  image build or CI setup) to warm the cache so indexing itself never
  needs network access — CI does this automatically now.

### Fixed
- **`docs/INSTALLATION_GUIDE.md`'s `trelix serve`/Docker examples used the
  wrong port** (8080) and a nonexistent `--repo` flag — `serve`'s actual
  CLI default is port 8765 with a positional `repo_path` argument. Also
  removed two fabricated env vars (`TRELIX_SERVE_HOST`, `TRELIX_SERVE_PORT`)
  that don't exist anywhere in source; there is no env-var override for the
  serve host/port, only the `--host`/`--port` CLI flags.
- **C# grammar naming**: `csharp.py` was requesting the language as
  `c_sharp`; the correct name is `csharp`. Silently broken until this
  release since `tree_sitter_languages` happened to accept both.
  Regression-tested via the existing `test_parser_csharp.py` suite.
- **Kotlin extractor rewritten for the new grammar's AST shape** —
  `class_declaration`/`function_declaration`/etc. no longer expose
  tree-sitter field names (`child_by_field_name` returned `None`
  everywhere), silently breaking all Kotlin class/interface/enum/
  function/property extraction. Rewritten to walk children positionally.
- **Python docstring/module-constant extraction** — the new grammar
  drops the `expression_statement` wrapper node entirely; assignments,
  calls, and bare strings (docstrings) now appear as direct children of
  their block. Updated `python.py`'s dispatch and `_get_docstring` to
  match the unwrapped shape.
- **Go interface methods**: `method_spec` renamed to `method_elem`.
- **TypeScript interface bodies**: `object_type` (for interface bodies
  specifically — type-alias object literals are unaffected) renamed to
  `interface_body`.
- **C# `using` alias imports**: the RHS type of `using X = Y.Z;` was
  wrapped in a `name_equals` node with an `alias` field in the old
  grammar; the new grammar flattens it to plain siblings around `=`.
  Updated `_extract_using` to take the first named type node after `=`.
- **`trelix.spec` (PyInstaller build) still imported the retired
  `tree_sitter_languages` package**, missed by the tree-sitter-language-pack
  migration since the binary build pipeline runs in its own workflow, not
  under `pytest`/mypy/ruff. Broke `Build Binaries` on every push to
  `develop`/`main` with `ModuleNotFoundError: No module named
  'tree_sitter_languages'`. Dropped the now-nonexistent package's `datas`/
  `hiddenimports` entries (it ships no bundled grammar data — grammars are
  fetched into an OS cache dir at runtime) and added `tree_sitter_language_pack`
  as a hidden import instead. Verified via a local `pyinstaller trelix.spec
  --clean --noconfirm` build + `dist/trelix --help`.

### Security
- **GitHub App: payload size limit and subprocess timeout** — the webhook
  route now caps request bodies at 25MB (GitHub's own documented webhook
  payload cap), rejecting oversized bodies with `413` during parsing
  rather than buffering an arbitrarily large request into memory; this
  matters because signature verification happens *after* body parsing, so
  the size limit is the only defense against a sender who doesn't know
  the webhook secret sending a deliberately huge payload.
  `runReviewCli`'s `trelix review` shell-out now passes a 5-minute
  `timeout`, so a hung/slow review (LLM synthesis latency, a huge diff, a
  stuck index) no longer ties up the process indefinitely — Node kills
  the child process (`SIGTERM`) and the call rejects. New tests exercise
  both with real subprocesses/payloads rather than mocks: a genuinely
  slow shell shim proves the timeout actually kills the process, and a
  real 26MB request body proves the size limit actually rejects.
- **GitHub App: webhook signature verification** — `infra/github-app/src/webhook.ts`
  now verifies `X-Hub-Signature-256` (HMAC-SHA256 over the raw request
  body, keyed by the webhook secret) via `@octokit/webhooks-methods`'s
  `verify()`, which compares using `crypto.timingSafeEqual` rather than a
  naive string compare (avoids leaking timing information about how many
  leading bytes matched). Requests with a missing, wrong-secret, or
  tampered-after-signing body are rejected with `401` before the route
  handler — and therefore `runReview`/the trelix CLI shell-out — ever sees
  the payload. New tests cover both the accept-valid and reject-tampered
  paths explicitly (the common real bug is only testing the happy path):
  no-header, wrong-secret, and tampered-body all assert `401` +
  `runReview` never called; a correctly-signed control case asserts `202`.

### Added
- **GitHub App: GA-readiness docs polish** — `infra/github-app/README.md`
  finalized (production deployment notes: HTTPS requirement, secret-manager
  guidance, runtime prerequisites) and its status upgraded from
  "skeleton"/"auth wired" to "installable and hardened" now that items
  6a-6c are complete. `docs/ROADMAP.md`'s "GitHub App GA" line explicitly
  states this App is installable and hardened, **not** Marketplace-listed
  — Marketplace paid-app listing has its own separate business/adoption
  requirements out of scope for this engineering work.
- **GitHub App: installation-token minting + Check-annotation posting**
  (`infra/github-app/src/auth.ts`, `src/review-runner.ts`) — completes the
  auth/posting work stubbed in item 6a. `getInstallationToken` uses
  `@octokit/auth-app` (App-ID+private-key JWT signing -> installation-token
  exchange), with one `AuthInterface` reused per `AppConfig` (a `WeakMap`)
  so the library's own expiry-aware cache actually has a chance to hit
  across calls — verified with mocked-transport tests proving a second
  call for the same config+installation makes zero additional HTTP
  requests, while distinct installations/configs never share a cached
  token. `runReview` now mints a token, fetches the PR's head SHA via
  `octokit.rest.pulls.get`, runs `trelix review --pr ... --json`, and
  posts a completed Check run with inline annotations via
  `octokit.rest.checks.create` (same conclusion logic as the existing
  `trelix-review.yml` workflow: any `failure`-level annotation ->
  `failure`, else `success`).
- **GitHub App skeleton** (`infra/github-app/`, `@trelix/github-app`) — the
  start of a standalone, webhook-driven GitHub App for zero-setup PR
  review (install the App, no workflow YAML needed in the installing
  repo), per the explicit architecture decision to build a standalone
  webhook-to-direct-execution service rather than a thin bridge to the
  existing Actions workflow. Ships `manifest.yml` (same
  `pull_requests`/`checks`/`contents` permissions and `pull_request`
  event the existing `trelix-review.yml` workflow already uses), an
  Express server with `/health` and `/webhooks/github`, webhook routing
  for `pull_request` `opened`/`synchronize`/`reopened` (mirroring the
  existing workflow's trigger), and a review-runner that shells out to
  `trelix review --pr ... --json` and maps findings to GitHub Check
  annotations (`toAnnotations` — a TypeScript port of the mapping logic
  fixed in the `trelix-review.yml` workflow). **Not yet wired for
  production use**: signature verification, installation-token minting,
  and Check-annotation posting are explicitly stubbed/unimplemented —
  land in item 6b. `infra/github-app/README.md` rewritten to cover both
  integration paths (the existing Actions workflow and this new App) so
  its previous "no App registration required" framing doesn't read as
  false now that a real App skeleton exists. New
  `.github/workflows/github-app-ci.yml` runs
  `npm ci && npm run typecheck && npm run build && npm test`, gated on
  `infra/github-app/**`.
- **VS Code extension: live-narrowing search + snippet preview** —
  `trelix.search` is now a debounced (250ms) search-as-you-type
  `QuickPick` instead of a one-shot `showInputBox` → static-list flow.
  Highlighting a result (arrow keys, not just accepting) shows a real
  snippet preview via `showTextDocument({preview: true})` against a new
  virtual-document `TextDocumentContentProvider`
  (`trelix-preview:` scheme, `src/preview.ts`) — this gets genuine VS Code
  syntax highlighting for free, since the virtual URI keeps the real
  file's extension. A `"Load more results…"` pseudo-item appears whenever
  `search_code`'s `next_cursor` is non-null (using the pagination fields
  PR #81/item 5a fixed), fetching and appending the next page without
  losing the current results or query. The debounce/cursor-pagination/
  stale-response-rejection state machine lives in a new, Extension-Host-
  independent `SearchController` class (`src/search-controller.ts`) —
  `search-controller.test.ts` uses an injectable fake-timer harness to
  simulate rapid keystrokes and prove `search()` fires exactly once per
  debounce window (not once per keystroke), that a stale in-flight
  response is discarded once a newer query has superseded it, and that
  `loadMore()` correctly appends via `next_cursor` and no-ops when there
  isn't one.
- **`docs/ROADMAP.md`**: logged the original Phase 3 plan's `@trelix` chat
  participant + hover providers (never actually delivered — only the 2
  QuickPick/Webview commands shipped) as an explicit v3.1.0 candidate,
  rather than silently dropping it again.

### Security
- **VS Code extension: XSS in the `trelix.ask` Webview** — `panel.webview.html`
  interpolated the raw, unescaped LLM answer string directly, with the
  Webview's `options` an empty `{}` (no CSP, no `enableScripts: false`, no
  `localResourceRoots` restriction at all). A crafted or adversarial answer
  could execute arbitrary script in the Webview's context. Now HTML-escapes
  the answer before interpolation and sets `enableScripts: false` plus an
  explicit `default-src 'none'` CSP meta tag.

### Fixed
- **VS Code extension: `search_code` results were silently mis-parsed** —
  `mcp-client.ts`'s `search()` read `symbol_name`/`file_path` off each
  result, but the real MCP `search_code` tool's response keys are
  `symbol`/`file` (confirmed against `packages/trelix-mcp/src/trelix_mcp/
  server.py`) — those two fields were always empty strings, and clicking a
  search result opened a broken/empty file URI. Also fixed: `next_cursor`/
  `total_available` were parsed off the response but discarded entirely
  (`search()` returned only `parsed.results`), and `kind`/`lines`/`source`/
  `language` were dropped from the parsed shape though the server already
  returns them. `search()` now returns the full `{results, nextCursor,
  totalAvailable}` shape with every field; `extension.ts` uses the newly
  available `lines` field ("start-end", 1-indexed) to jump to and highlight
  the matched symbol's line range on open, instead of just opening the file
  with no selection.
- **`trelix review --pr ... --json`'s stdout was never valid JSON** —
  `console.print(...)` status/progress messages (e.g. "Fetching PR diff
  from GitHub...") ran unconditionally to stdout even in `--json` mode,
  and `"No issues found."`/`"No textual changes..."` styled messages ran
  *instead of* an empty `[]` when there were zero comments. Combined with
  `.github/workflows/trelix-review.yml`'s `> file 2>&1` redirect, the
  review-posting Check's `JSON.parse()` has always thrown and been
  silently swallowed by a `try/catch` — meaning **the "trelix Code
  Review" Check has never posted a single real annotation** since this
  workflow shipped. All `--pr --json` status/progress messages now go to
  `err_console` (stderr); the workflow now redirects only stdout, keeping
  stderr in a separate log for debugging.
- **The same workflow's annotation-posting logic never matched trelix's
  real output shape even when parsing succeeded** — it read
  `data.findings || data.reviews || []` against `trelix review --json`'s
  real bare-array output (never matches, so `findings` was always `[]`
  regardless), and compared `f.severity === 'error'`/`'warning'`
  (lowercase) against the real values `"ERROR"`/`"WARN"`/`"INFO"`
  (uppercase — `'WARN' !== 'warning'` either way). Every annotation would
  have posted as `notice` severity even if the JSON had parsed. Now reads
  the real `{file, lines, severity, comment}` shape directly and maps
  `ERROR`→`failure`, `WARN`→`warning`, `INFO`→`notice`.
- New `tests/unit/test_review_pr_json.py` (4 tests) — regression-tests
  `--json` stdout purity for the has-comments, zero-comments, and
  no-textual-changes paths, plus confirms non-`--json` mode still prints
  status messages to stdout (the fix is `--json`-gated, not a blanket
  behavior change). Verified these tests actually fail against the
  pre-fix code (3/4 failed with the exact `JSONDecodeError` this bug
  produces) before confirming they pass against the fix.

### Changed
- **VS Code extension build/test infrastructure** — added `esbuild`
  (bundles `dist/extension.js`, `external: ["vscode"]`) instead of plain
  `tsc` emit, so the packaged `.vsix` no longer risks shipping unbundled
  `node_modules` (the extension's only runtime dependency,
  `@modelcontextprotocol/sdk`). `tsc --noEmit` remains a separate
  `typecheck` script since esbuild doesn't type-check. Added a
  `.vscodeignore` (previously absent) and a `@vscode/test-electron`+Mocha
  test harness (`src/test/runTest.ts`, `src/test/suite/`) — new
  `extension.test.ts` verifies activation and command registration;
  `mcp-client.test.ts` verifies the `search()`/`ask()` parsing fixes above
  against a mocked MCP transport. New
  `.github/workflows/vscode-extension-ci.yml` runs
  `npm ci && npm run typecheck && npm run build && xvfb-run -a npm test`,
  gated on `workspace-vscode/**` changes. Version bumped `0.1.0` → `0.2.0`
  (unchanged since the v2.7.0 scaffold).
- **`docs/integrations/vscode-plugin.md` full rewrite** — the previous
  version described a PyInstaller-binary-bundling architecture that was
  never actually built, and never once mentioned the real MCP-stdio-client
  architecture the extension actually ships with. Rewritten to describe
  the real `dist/extension.js` (esbuild bundle) → `trelix-mcp` (stdio
  child process) → trelix core data flow, the real `search_code` response
  shape, the security notes above, and the real build/test/package
  commands.

### Added
- **Helm chart** (`helm/trelix/`) for deploying `trelix serve` to Kubernetes —
  `Deployment`/`Service`/`PVC`/`Secret`/`Ingress` templates, `values.yaml`
  covering the full `StoreConfig` surface (`store.backend`: sqlite/qdrant/
  lance, HNSW tuning, BM25 read-pool size) plus embedder-provider
  credentials (OpenAI/Voyage/Cohere, either plaintext `apiKey` for dev or
  `existingSecretName`/`existingSecretKey` for shared clusters). Models
  `trelix serve`'s actual behavior directly: since `create_app()` takes zero
  arguments and every route re-derives its config from the request's own
  `repo` param, one Deployment is already multi-repo-capable — the chart's
  PVC (mounted at `/data` by default) is a *shared* data directory across
  every repo you index/serve, documented loudly in `NOTES.txt`/`README.md`
  since it's non-obvious. `ingress.enabled` defaults to `false`: `trelix
  serve` has zero auth middleware, so `NOTES.txt` warns explicitly about
  exposing `/index`/`/ask`/`/search` before enabling a public Ingress.
  Qdrant is treated strictly as an external, user-managed dependency — this
  chart only points `QDRANT_URL`/`QDRANT_API_KEY` at one, never deploys or
  operates Qdrant itself (its own chart states support is
  community-limited; self-hosted lacks zero-downtime upgrades and
  backup/DR). New `.github/workflows/helm-lint.yml` runs `helm lint` +
  `helm template` across all three `store.backend` values plus an
  ingress-enabled render, on every push/PR touching `helm/**`.
- **Official Docker image** — a multi-stage `Dockerfile` (root) publishes
  `ghcr.io/sairam0424/trelix` for `linux/amd64`+`linux/arm64` on every
  release tag, in two variants sharing one build (`EXTRAS` build arg):
  `:X.Y.Z` (slim, API-embedder-only — OpenAI/Voyage/Cohere/Azure) and
  `:X.Y.Z-local` (bundles `sentence-transformers`/`torch` for the
  local/offline embedder and cross-encoder reranker). Runs as a non-root
  `trelix` user, `ENTRYPOINT ["trelix"]` with `CMD ["serve", "/repo",
  "--host", "0.0.0.0", "--port", "8765"]` (overrides the CLI's
  `127.0.0.1` default, which isn't reachable from outside a container's
  network namespace), and a `HEALTHCHECK` hitting `/health`. New
  `docker-compose.yml` at the repo root is a runnable version of
  `docs/INSTALLATION_GUIDE.md`'s Docker Compose snippet. New
  `.github/workflows/docker-publish.yml` builds/pushes both variants on
  `v*` tags; CI gained a `docker-build` job that builds the slim image and
  runs `--help` against it on every push/PR, mirroring the existing
  per-OS binary `--help` smoke tests in `release.yml`.
- New Makefile targets: `docker-build`, `docker-build-local`, `docker-run`.

### Fixed
- **`TRELIX_EMBEDDER` was a silent no-op env var** — `docs/
  INSTALLATION_GUIDE.md` and `docker-compose.yml` both referenced
  `TRELIX_EMBEDDER`, but `EmbedderConfig`'s real env var is
  `TRELIX_EMBEDDER_PROVIDER` (confirmed empirically: setting
  `TRELIX_EMBEDDER=openai` in a clean environment left `provider` at its
  default `"local"`). On the slim Docker image this silently falls back to
  a provider that isn't installed and crashes, rather than erroring at the
  variable name. Also fixed a `--embedder` CLI flag reference in the same
  section — the real flag is `--provider`. Found while writing this
  chart's `values.yaml` example and wanting to confirm the var name against
  source before using it.
- **`docs/INSTALLATION_GUIDE.md`'s Docker Compose/serve examples used the
  wrong port** (8080) and a nonexistent `serve --repo` flag (`repo_path`
  is positional) — same class of bug already fixed for the `docker run`
  examples in PR #77, now fixed here too since this PR touches the same
  section.

## [2.8.1] — 2026-07-20

### Security
- **MCP federation `config_path` path confinement** — `federation_list_repos`/
  `federation_add_repo`/`federation_remove_repo`/`federation_search_all`
  previously passed a caller-supplied `config_path` straight into
  `RepoRegistry.load()`/`.save()` with no validation, letting an MCP client
  (including a prompt-injected agent) point registry I/O at an arbitrary
  path. Now confined to `~/.config/trelix/` or `<mcp-server-cwd>/.trelix/`
  via `Path.is_relative_to()` (not a naive string-prefix check, which would
  incorrectly also match a sibling directory like `~/.config/trelixevil/`).
  Found in the pre-push audit of v2.8.0 (issue #69).

### Added
- **Federation repo-count and fan-out caps** — `RepoRegistry.add()` gained an
  optional `max_repos` parameter (CLI callers remain unbounded by default;
  MCP's `federation_add_repo` now passes `TRELIX_FEDERATION_MAX_REPOS`,
  default 50). `FederatedRetriever` gained a `max_repos` constructor param
  capping how many registered repos are actually queried per call;
  `federation_search_all`'s response gained a `repos_skipped` field.
  Prevents a runaway/adversarial `federation_add_repo` loop from making
  every subsequent search scale linearly with an unbounded repo count.

### Fixed
- **`federation_search_all` pagination wasn't a stable slice** — previously
  requested `fed.retrieve(query, k=max(k+cursor, k))`, so the per-repo
  candidate pool feeding RRF fusion widened as `cursor` grew, meaning page 2
  could be fused from a differently-shaped pool than page 1 (items could
  shift rank, get deduped differently, or disappear between pages). Now
  fetches a fixed, cursor-independent width once and slices pages from the
  final fused list — mirrors `search_code`'s existing single-fetch-then-slice
  pattern.

### Changed
- All 4 federation MCP tools now consistently return an `"error": str|None`
  key on every response path (previously only present on failure paths for
  `federation_add_repo`), matching the convention already used by
  `ask_agent`/`agent_list_sessions`/`agent_clear_session`.

## [2.8.0] — 2026-07-20

### Added
- **Multi-repo support in MCP** — 4 new MCP tools (`federation_list_repos`,
  `federation_add_repo`, `federation_remove_repo`, `federation_search_all`)
  expose the existing `RepoRegistry`/`FederatedRetriever` CLI infrastructure
  (`trelix federation add/list`, `trelix search-all`) to MCP clients (Claude
  Desktop, Cursor, any IDE). Also added the missing `trelix federation remove`
  CLI command (the registry method existed but had no CLI entry point).
- **Persistent agent (ReAct loop) memory** — the agentic loop
  (`trelix ask --agentic`, `TRELIX_RETRIEVAL_AGENTIC=true`) now persists turn
  history to new `agent_sessions`/`agent_turns` tables in the per-repo
  `.trelix/index.db`, keyed by a client-supplied or auto-generated UUID4
  `session_id`. `AgentLoop.run()` now returns `(answer, session_id)` — pass
  the session_id back on a follow-up call to resume with full prior context.
  New CLI: `trelix ask --session <id>`, `trelix agent sessions list/show/clear`.
  New MCP tools: `ask_agent`, `agent_list_sessions`, `agent_clear_session`.
  Sessions auto-evict after `TRELIX_RETRIEVAL_AGENT_SESSION_MAX_AGE_SECONDS`
  of inactivity (default 7 days; `0` disables eviction).

### Fixed
- **Federated search lost repo provenance** — `FederatedRetriever` used to tag
  each result's `source` with `"{alias}:{leg}"` so callers could tell which
  repo a result came from, but this was silently dropped in a prior refactor.
  `trelix search-all`'s "Repo" column and `--json` output had been blank ever
  since, with no test catching it. Restored the tagging and added a
  regression test.
- **`RepoEntry.weight` was never applied** — settable via
  `trelix federation add --weight`, stored, and documented, but the fan-out
  fusion path never forwarded it into RRF, so per-repo weighting silently did
  nothing. `reciprocal_rank_fusion()` gained a new `list_weights` parameter
  (orthogonal to the existing per-language `weights` parameter; `None` is
  backward-compatible) and `FederatedRetriever` now passes each repo's weight
  through.
- **`agent_turns.turn_index` could silently collide on session resume** — found
  in pre-push audit. `AgentLoop.run()` used to compute the resume anchor from
  `len(prior_rows)` (a row-count snapshot), which drifts from reality after
  any persistence gap (a dropped turn) or a concurrent resume of the same
  `session_id`, silently producing duplicate `turn_index` rows with no error.
  `Database.insert_agent_turn()` now assigns `turn_index` atomically via
  `MAX(turn_index)+1` under the same lock as the insert, and `agent_turns`
  gained a `UNIQUE(session_id, turn_index)` index as defense-in-depth — any
  residual race now raises `IntegrityError` (caught and logged) instead of
  silently duplicating a row.

## [2.7.3] — 2026-07-13

### Changed
- **README.md end-to-end audit and rewrite** — fixed 15+ factual bugs (wrong
  env var names, fabricated pip extras, a broken Homebrew tap, a crash-causing
  `TRELIX_RETRIEVAL_RERANK_PROVIDER` value, wrong REST method/table names),
  rewrote the "How it works" diagram to show all 7 retrieval legs (was 3) plus
  the agentic/FLARE alternate synthesis modes, and consolidated duplicated
  content (3x REST API sections, Installation/Knowledge-Graph/Embedding-Providers
  duplicating `docs/`) into short pointers. 867 → 634 lines.
- **"What's New" and "Troubleshooting" moved out of README** — backfilled
  CHANGELOG.md's empty `[2.2.0]` entry with its 5 features (agentic ReAct loop,
  data-flow analysis, taint analysis, sparse+dense hybrid, multi-granularity
  indexing — previously undocumented anywhere else) and added README's 5
  Troubleshooting entries to `docs/TROUBLESHOOTING.md`'s existing sections,
  then trimmed both README sections to short pointers.

## [2.7.2] — 2026-07-12

### Added
- **Qdrant Cloud readiness** — `QdrantVectorStore` now accepts `prefer_grpc` and
  `timeout` options, wired through `StoreConfig.qdrant_prefer_grpc`
  (`QDRANT_PREFER_GRPC`, default `false`) and `StoreConfig.qdrant_timeout`
  (`QDRANT_TIMEOUT`, default `10.0`). Enables gRPC transport (port 6334) and
  longer request timeouts for Qdrant Cloud's higher network latency.
- **Incremental per-symbol embedding on partial re-index** — new
  `symbols.content_hash` column (`sha256(signature + body)`, backfilled via an
  `ALTER TABLE ... ADD COLUMN` migration guard). `Indexer._insert_one` now diffs
  each parsed symbol's `(qualified_name, content_hash)` against the stored row;
  unchanged symbols skip delete/re-chunk/re-embed entirely and keep their
  existing chunk rows and vectors. Only changed or new symbols flow through the
  delete → re-insert → chunk → embed path.
- **Opt-in parallel BM25 read pool** — new `ReadOnlyConnectionPool`
  (`src/trelix/store/read_pool.py`) opens N read-only SQLite connections
  (`mode=ro`, `PRAGMA query_only = ON`) for concurrent FTS5 reads.
  `TRELIX_STORE_BM25_READ_POOL_SIZE` (default `0`, disabled) — when set > 0,
  `Retriever.__init__` calls `Database.enable_bm25_read_pool()` automatically.
- **Linux ARM64 binary releases** — `build-binaries.yml` and `release.yml`
  matrices add `ubuntu-24.04-arm` (artifact `trelix-linux-arm64`);
  `docs/INSTALLATION_GUIDE.md` gained a "Linux ARM64" install section.

### Fixed
- **`SparseEmbedder` TOCTOU race** — `_load()` checked `self._model is not None`
  before acquiring the lock, so two threads could both pass the check and
  double-load the model concurrently. Fixed with double-checked locking:
  `self._model is not None` is re-checked again inside `self._lock`.
- **MCP stdout notification write race** — concurrent `send_resource_notification()`
  calls from different threads could interleave partial JSON-RPC lines on
  stdout. Added a module-level `_stdout_lock` guarding the `sys.stdout.write()` +
  `flush()` pair.
- **`SubscriptionRegistry` unbounded growth** — subscriptions were never capped
  or expired, so a misbehaving client could grow the registry indefinitely.
  Added `max_subscribers` (`TRELIX_MCP_MAX_SUBSCRIBERS`, default `1000`)
  enforced via a new `SubscriptionLimitExceeded` exception, and `ttl_seconds`
  (`TRELIX_MCP_SUBSCRIPTION_TTL_SECONDS`, default `3600`) swept by
  `_evict_expired_locked()` before every registry operation. The
  `subscribe_resource` tool now catches the limit error and returns a soft
  `{"subscribed": false, ...}` payload instead of raising.
- **Silent `parent_id`/`callee_id`/`type_edges` corruption on partial re-index** —
  `symbols.parent_id`, `calls.callee_id`, and `type_edges.to_symbol_id` are all
  `ON DELETE SET NULL`, so deleting a changed symbol's old row silently nulled
  these links on any other row (including unchanged ones) that pointed at it.
  Added `Database.get_children_with_stale_parent`/`repoint_parent_ids`,
  `get_calls_referencing_symbols`/`repoint_call_callee_ids`, and
  `get_type_edges_referencing_symbols`/`repoint_type_edge_targets`; the indexer
  snapshots stale links before the cascading delete and repoints them to the
  replacement symbol's new id afterward.
- **Incomplete BM25 concurrency lock** — `Database._conn`
  (`check_same_thread=False`) is not safe for concurrent statement execution
  from multiple threads despite that flag; the grep, sparse, and vector
  retrieval legs all hydrate through the same shared connection from sibling
  `ThreadPoolExecutor` threads. Added `self._conn_lock` and applied it to
  `bm25_search()`'s non-pool fallback, `get_symbol_with_file()`,
  `get_first_chunk_for_symbol()`, `get_chunk_with_context()`,
  `grep_search.py`'s `_name_search`/`_body_search`, and a new locked
  `Database.get_chunk_by_id()` helper for `sparse_search.py`'s raw chunk
  lookup. Verified via a 60-thread x 10-iteration x 3-leg stress test with
  zero errors.
- **`qdrant-client` 1.18 API migration** — `QdrantVectorStore` used the
  deprecated `search()` method; migrated to `query_points()`. Pinned
  `qdrant-client>=1.9.0,<2.0.0` in `pyproject.toml` to prevent an unguarded
  2.x upgrade from breaking the client again.

### Changed
- **Windows ARM64 binary intentionally not shipped** — `windows-11-arm` was
  briefly added to both binary-build matrices, then reverted:
  `tree-sitter-languages` and `sqlite-vec` publish no `win_arm64` wheel or
  sdist, so `pip install` fails before the build ever runs. Linux ARM64 ships;
  Windows ARM64 does not.

## [2.7.1] — 2026-07-10

### Fixed
- **Release pipeline asset collision** — `release.yml` referenced the macOS and Linux
  PyInstaller binaries by bare basename (both built as `dist/trelix`).
  `softprops/action-gh-release` uploads by basename, so the two identically-named
  binaries collided into a single GitHub Release asset. The published v2.7.0 release
  had only 2 binary assets instead of 3, and it was unknowable whether the surviving
  `trelix` asset was macOS or Linux. Each binary is now renamed to a unique filename
  (`trelix-macos-arm64` / `trelix-windows-x64.exe` / `trelix-linux-x64`) before upload.
- **No Linux binary in PR-time CI** — `build-binaries.yml` only built and verified
  macOS + Windows even though `release.yml` already builds Linux at tag time. Added
  the `ubuntu-latest` matrix entry and a Linux verify step.
- **Unjustified dependency-floor bumps reverted** — `trelix-mcp`, `trelix-langchain`,
  and `trelix-llama-index` had their `trelix>=X.Y.Z` floors raised to `>=2.7.0`/
  `>=2.4.0` in v2.7.0 based on an unverified assumption about API usage. Re-checked
  every import in all three packages — none use any Phase 1–3 v2.7.0 API. Reverted
  to `trelix>=0.4.0`.
- **`trelix-mcp` tests never ran in CI** — `ci.yml`'s test job never installed or
  executed `packages/trelix-mcp/tests/`. This let a real regression sit undetected:
  `test_four_tools_registered` asserted "exactly 6 tools" when the server has
  registered 8 since `subscribe_resource`/`unsubscribe_resource` shipped in v2.5.0.
  Fixed the test's expected set and wired `packages/trelix-mcp/tests/` into `ci.yml`.
- **Wrong env var name in docs** — `TRELIX_GRAPH_SEARCH_ENABLED` was incorrect in
  7 places across `docs/FAQ.md`, `docs/USER_GUIDE.md`, `CONTRIBUTING.md`. The real
  variable is `TRELIX_RETRIEVAL_GRAPH_SEARCH_ENABLED` (`graph_search_enabled` has
  no explicit alias override, so it inherits `RetrievalConfig`'s
  `env_prefix="TRELIX_RETRIEVAL_"`).
- **CHANGELOG footer link collision** — `[2.2.0]` was defined twice with conflicting
  URLs; markdown silently resolves to the last definition, making the first dead.
  `[2.3.0]`, `[1.1.0]`, `[0.7.1]`, `[0.7.0]`, `[0.6.0]` had no comparison link at all
  despite existing as dated release headers. Rebuilt the footer from scratch,
  cross-checked against `git tag -l`.

## [2.7.0] — 2026-07-09

### Added — Phase 1: Watch Bridge, DB Index, AdaptiveRouter Config Fix
- `FileWatcher._do_reindex` now fires `notify_file_changed()` after a successful
  re-index (not on hash-identical skips). MCP subscribers receive live
  `notifications/resources/updated` pushes when watched files change.
  Non-fatal when `trelix-mcp` is not installed.
- `idx_files_rel_path` index added to `files.rel_path` — eliminates full table
  scan on every `GraphUpdater.update_file()` call (`WHERE rel_path = ?`).
  `CREATE INDEX IF NOT EXISTS` — safe on existing databases.
- `AdaptiveRouter.__init__` now accepts `retrieval_config: RetrievalConfig | None = None`.
  When provided, it is used directly instead of constructing a new instance from env
  vars — fixes silent-ignore of programmatic config overrides.
- `Retriever` passes `config.retrieval` through `QueryPlanner → AdaptiveRouter`.

### Added — Phase 2: Cross-Repo Symbol Resolution, Semantic Diff Embeddings, Streaming Indexing
- `make_scip_symbol_id(package, version, qualified_name)` — stable SCIP-style
  cross-repo symbol ID using `||`-separated sha256[:16]. Unambiguous for scoped
  npm packages (`@scope/pkg`).
- `FederatedRetriever.record_exports(alias, repo_path)` — indexes all symbols from
  a trelix-indexed repo into an in-memory `federation_symbols` table.
- `FederatedRetriever.resolve_symbol(qualified_name)` — returns all repos that
  define a symbol. Supports exact match and suffix-LIKE (`%.verify`). Thread-safe
  via `threading.Lock` + `check_same_thread=False`.
- `DiffEmbedder` — CCRep-style before/after body pair embeddings for PR diff hunks
  (arXiv:2302.03924). `store_pr_diff()` caps at 500 hunks/PR; `search_similar_diffs()`
  finds historically similar changes by cosine similarity with NaN guard and
  dimension mismatch protection.
- `diff_chunks` SQLite table + `idx_diff_chunks_pr_ref` index added to schema.
- `TRELIX_INDEXER_STREAMING=true` — generator-based file processing pipeline.
  `_iter_files()` yields files lazily; `_index_streaming()` uses bounded
  `Queue(maxsize=64)` with `try/finally` producer sentinel guarantee.
  Default off — zero behavior change on default path.

### Added — Phase 3: VS Code Extension, GitHub App PR Review
- `workspace-vscode/` — VS Code extension scaffold (`trelix.search` and `trelix.ask`
  commands) using `TrelixMcpClient` over MCP stdio transport. Piggybacks on existing
  `trelix-mcp` package — no new Python backend.
- `.github/workflows/trelix-review.yml` — GitHub Actions workflow that runs
  `trelix review --pr N --json` on every pull request and posts findings as
  GitHub Check annotations with file+line references.
  Permissions: `checks: write`, `pull-requests: write`, `contents: read`.
  Index step has `continue-on-error: true` for CI environments without local models.
- `infra/github-app/README.md` — GitHub App integration setup guide.

## [2.6.0] — 2026-07-08

### Added — XTR Late-Interaction Reranker (Plan C, EXPERIMENTAL)
- `TRELIX_RETRIEVAL_RERANK_PROVIDER=xtr` — XTR reranker (NeurIPS 2023,
  arXiv:2304.01982). Scoring stage is 100–1000x cheaper than ColBERT/PLAID
  by reusing already-retrieved tokens instead of loading all document tokens.
- `TRELIX_RETRIEVAL_XTR_TOKENS=100` — candidate token count for XTR retrieval
  (range 10–1000).
- `trelix.retrieval.reranker_xtr` — pure-Python XTR scoring module
  (`xtr_score_documents`, `warn_experimental`).
- **EXPERIMENTAL:** XTR has not been benchmarked on code-specific retrieval
  (CoIR/CoREB evaluation pending). Emits `UserWarning` on first use. PLAID
  remains the production-validated late-interaction option.

### Added — GroUSE-Style Synthesis Quality Harness (Plan D)
- `trelix.eval.synthesis` — `SynthesisEvalHarness`, `evaluate_synthesis`,
  `score_hallucination`, `score_completeness`, `score_faithfulness`, `SynthesisResult`.
- `trelix eval-synthesis --golden <path>` — CLI command for synthesis quality evaluation.
- `eval/golden_synthesis_sample.jsonl` — sample golden file for getting started.
- Golden file format extends the existing eval harness with optional
  `expected_answer_fragments` and `expected_symbols` fields.
- Research basis: GroUSE (arXiv:2409.06595, COLING 2025) — 7 failure modes,
  144 unit tests. GPT-4 correlation is insufficient as a quality proxy.

### Added — Short-Query Lexical Fallback (Plan B)
- `TRELIX_RETRIEVAL_SHORT_QUERY_LEXICAL=true` — enables BM25+grep-only routing
  for queries with ≤ threshold meaningful tokens (default off).
- `TRELIX_RETRIEVAL_SHORT_QUERY_TOKENS` — sets the meaningful-token threshold
  (default 5, range 1–10).
- `is_short_query(query, threshold)` and `count_meaningful_tokens(query)` helpers
  in `trelix.retrieval.bm25`.
- `SubQuery.lexical_only: bool` — new field; when True, `_run_subquery_legs` skips
  vector ANN embedding entirely.
- Research basis: CoREB benchmark (arXiv:2605.04615) confirms all embedding models
  score 0.000–0.015 nDCG@10 on short keyword queries vs 0.45–0.58 on long queries.

### Added — Incremental Louvain Community Detection (Plan A)
- `detect_communities_incremental(cg, seed_nodes, prev_partition)` — DF Louvain
  frontier heuristic (arXiv:2404.19634). Reprocesses only the affected-vertex
  frontier instead of the full graph on file-change events.
- `compute_affected_frontier(G, seed_nodes, partition)` — computes the DF Louvain
  frontier: seed nodes + their neighbors + their community members.
- `GraphUpdater` now maintains `_prev_partition` across calls and uses incremental
  detection for subsequent updates. First run and large-frontier (>50% of nodes)
  fall back to full Louvain.
- `Database.get_symbol_ids_for_file(rel_path)` — returns symbol IDs for a file
  (used to seed the incremental frontier from a file-change event).

## [2.5.0] — 2026-07-06

### Overview
Phase A–C of the v2.5.0 backlog. Three independent subsystems shipped:
multi-query expansion wired into `_retrieve_standard`, DimensionGuard at
`FileWatcher.__init__`, and MCP resource subscriptions (capability declaration
+ subscription registry + file-change notification bridge). v3.0.0 deprecation
schedule documented and regression-tested.

### Added — Multi-Query Expansion Wiring (Phase A)
- `MultiQueryExpander` is now wired into `_retrieve_standard` via `ThreadPoolExecutor`
- Enable with `TRELIX_RETRIEVAL_MULTI_QUERY=true`, tune with `TRELIX_RETRIEVAL_MULTI_QUERY_COUNT=3`
- Variant queries run in parallel; results RRF-merged with k=60 before dedup
- `ExpandResult.llm_used` indicates whether LLM expansion ran or fell back to original

### Added — DimensionGuard at Watch Startup (Phase A)
- `FileWatcher.__init__` now calls `DimensionGuard.check()` at startup
- Raises `DimensionMismatchError` immediately if provider was changed since last index run
- Prevents silent embedding corruption from mismatched providers during watch

### Added — MCP Resource Subscriptions (Phase B)
- `trelix-mcp` now advertises `resources.subscribe=True` in server capabilities
- `SubscriptionRegistry` tracks subscription IDs per resource URI (thread-safe)
- `notify_file_changed()` fires `notifications/resources/updated` (URI-only, per MCP spec)
  over stdio for all active subscribers when watchfiles detects a change
- Wire protocol: `resources/subscribe` -> `notifications/resources/updated` -> `resources/read`

### Documentation
- `docs/BACKWARDS_COMPATIBILITY.md` — v3.0.0 breaking changes table with file:line refs
- Deprecation warning for `TRELIX_RETRIEVAL_FLARE_MAX_ITER` regression-tested

### Breaking Changes
None — all changes are additive or fail-fast safety improvements.

## [2.4.0] — 2026-07-04

### Overview
Six backlog items shipped across Plans A–F. 1,467 unit tests passing, all features default-ON or backward-compatible.

### ⚠️ BREAKING CHANGE — `search_code` MCP tool response envelope

**Before (v2.3.0):** `search_code` returned `list[dict]` directly.

**After (v2.4.0):** `search_code` returns a pagination envelope:
```json
{"results": [...], "next_cursor": 10, "total_available": 25}
```

**Migration:** Update any MCP client code that iterates `search_code(...)` directly:
```python
# Before
for result in search_code(query="auth", repo_path="/repo"):
    ...

# After
response = search_code(query="auth", repo_path="/repo")
for result in response["results"]:
    ...
# Paginate: pass response["next_cursor"] as cursor= for the next page
```

### Added — Config field rename: `flare_max_retries` (Plan A)
- **`flare_max_retries`** replaces `flare_max_iterations` in `RetrievalConfig`
- Both `TRELIX_RETRIEVAL_FLARE_MAX_RETRIES` (new) and `TRELIX_RETRIEVAL_FLARE_MAX_ITER` (old) accepted via `AliasChoices`
- Using the old env var emits `DeprecationWarning`; old name removed in v3.0.0
- **⚠️ Range constraint:** field enforces `ge=1, le=3`. If you previously set `TRELIX_RETRIEVAL_FLARE_MAX_ITER` to a value >3, lower it before upgrading or pydantic raises `ValidationError` at startup.

### Added — Multi-Query Expansion Observability (Plan B)
- **`ExpandResult`** dataclass — `(queries, llm_used, elapsed_ms)` returned by `MultiQueryExpander.expand()`
- Three new nullable columns in `query_telemetry`: `expansion_used`, `expansion_variants`, `expansion_elapsed_ms`
- `TelemetryWriter.record()` accepts optional `expansion_result=` to persist expansion metadata
- Migration: idempotent `ALTER TABLE ADD COLUMN` — existing DBs upgraded automatically

### Added — FederatedRetriever TTL Cache (Plan C)
- **`FederatedRetriever(registry, cache_ttl=120.0)`** — SHA-256-keyed in-memory cache, thread-safe via `threading.Lock`
- `cache_ttl=0` disables caching; `cache_stats()` returns hit/miss/size; `clear_cache()` for forced eviction
- Expected ~90% hit rate for typical debugging-session query patterns

### Added — GitHub PR API integration (Plan D)
- **`GitHubPRClient`** — fetch PR file diffs and post review comments via GitHub REST API
- **`trelix review --pr owner/repo#N`** — fetches PR diff from GitHub and runs `DiffReviewer`
- **`trelix review --pr owner/repo#N --post-comments`** — posts findings back as a single batched GitHub review
- Token from `GITHUB_TOKEN` env var only; handles all 7 file status values; 3,000-file truncation warning

### Added — Multi-repo file watching (Plan E)
- **`MultiRepoWatcher`** — single `watchfiles.awatch(*all_paths)` call watching all registered repos simultaneously
- Hash guard prevents re-index cascade loops; deleted files are removed from the SQLite index + vector store
- **`trelix watch-all`** — new CLI command; shows per-repo stats on exit; graceful Ctrl+C shutdown

### Added — MCP pagination + progress notifications (Plan F)
- **`search_code` pagination** — `cursor=` (offset) + `next_cursor` in response; MCP-spec-approved pattern for large payloads
- **`index_codebase` progress** — `ctx.report_progress()` sends `notifications/progress` during indexing stages (best-effort)

## [2.3.0] — 2026-07-02

### Overview
Five research-grounded intelligence and infrastructure upgrades. All features default **OFF** — zero regression when disabled. 42/42 e2e checks pass, 1458 unit tests, zero blockers.

### Added — Embedding Dimension Guard (Plan E)
- **`DimensionGuard`** — detects provider/dimension mismatch at `Retriever.__init__` startup; raises `DimensionMismatchError` with exact `trelix migrate-vectors --reset` recovery instruction
- **`index_metadata` SQLite table** — records embedding dimension after each successful index run
- **`trelix migrate-vectors --reset`** — clears `chunk_embeddings` + dimension metadata for fresh re-index after provider switch
- Prevents silent wrong-results bug when switching e.g. Azure (3072-dim) → local (384-dim)

### Added — Multi-Query Retrieval Wiring (Plan A)
- **`MultiQueryExpander` wired** into `_retrieve_standard` — the class already existed; this commit connects it to the live retrieval pipeline
- When `TRELIX_RETRIEVAL_MULTI_QUERY=true`, primary query expands to N variants, each runs all retrieval legs in parallel via `ThreadPoolExecutor`, results merge into `leg_results_list` before RRF fusion
- `variants[1:]` used (not `variants[:]`) — original query never runs twice
- Falls back gracefully (non-fatal `logger.warning`) when LLM unavailable

### Added — MCP Resources + Prompts (Plan B)
- **MCP Resources** (application-controlled URI-addressable data):
  - `trelix://index/stats` — aggregate index statistics
  - `trelix://repo/{repo_path}/manifest` — indexed file list
  - `trelix://repo/{repo_path}/symbols/{qualified_name}` — symbol source code
- **MCP Prompts** (reusable LLM interaction templates):
  - `trelix-search` — structured code search prompt
  - `trelix-explain` — symbol explanation prompt
  - `trelix-blast-radius` — impact analysis prompt
- All resource handlers return JSON even on error; stdout stays clean for MCP stdio protocol
- Research basis: MCP spec (5× 3-0 adversarial votes on Resources/Templates/Prompts primitives)

### Added — Semantic PR/Diff Review (Plan C)
- **`DiffParser`** — parses unified git diff into `DiffHunk` objects; `from_git(repo, base, head)` uses `subprocess.run` with `shell=False` (no injection risk); `to_search_query()` extracts identifiers for hybrid retrieval
- **`DiffReviewer(config).review(hunks)`** — retrieval-augmented review: each hunk → search query → retrieve context → LLM generates `ReviewComment` objects; crash-safe, never raises
- **`trelix review <repo> [--diff <file>] [--base] [--head] [--json]`** CLI command with Rich table output

### Added — Multi-Repo Federated Search (Plan D)
- **`RepoRegistry`** — load/save/manage `~/.config/trelix/repos.json`; `add(alias, path, weight)`, `remove`, `list`; raises `ValueError` on duplicate alias
- **`FederatedRetriever(registry, max_workers=4).retrieve(query, k)`** — parallel fan-out across registered repos via `ThreadPoolExecutor`; RRF merge; deduplicates by `(file_path, symbol_id)`; crash-safe (returns `[]` when all repos fail)
- **`trelix search-all <query>`** — federated search CLI
- **`trelix federation add/list`** — registry management CLI
- Config: `federation_enabled=False` (`TRELIX_FEDERATION_ENABLED`), `federation_max_workers=4`

### Breaking Changes
None — all new features are opt-in via config flags.

### v2.4.0 Backlog
- Multi-query expansion observability (log which mode: LLM-assisted vs fallback)
- MCP subscription/streaming (server-push on index changes)
- FederatedRetriever caching layer for repeated queries
- `trelix review` integration with GitHub PR API
- Real-time multi-repo watch (`trelix watch-all`)

---

## [2.2.0] — 2026-07-01

### Overview
Intelligence upgrades: an agentic ReAct retrieval loop, static analysis (data-flow
and taint), and two new hybrid-search legs (sparse SPLADE-Code, multi-granularity
chunking). All opt-in via config flags that default to `False` — zero regression
when disabled.

### Added
- **Agentic ReAct loop** (`agentic_enabled`, `TRELIX_RETRIEVAL_AGENTIC=true`) —
  multi-turn retrieve → observe → re-retrieve loop with self-correction, replacing
  the single-shot Retriever → Synthesizer chain when enabled.
- **Data-flow analysis** (`dataflow_enabled`, `TRELIX_PARSER_DATAFLOW=true`) —
  per-function def-use chains extracted via a tree-sitter AST walk, stored in the
  `def_use_edges` table.
- **Taint analysis** (`taint_enabled`; `pip install trelix[taint]` then
  `trelix taint .`) — Semgrep-backed source→sink flow detection, findings stored
  in `taint_flows`.
- **Multi-granularity indexing** (`multi_granularity_enabled`,
  `TRELIX_CHUNKER_MULTI_GRANULARITY=true`) — block- and statement-level
  sub-chunks indexed as a 6th RRF leg alongside symbol-level chunks.
- **Sparse+dense hybrid retrieval** (`sparse_enabled`, `TRELIX_RETRIEVAL_SPARSE=true`)
  — SPLADE-Code sparse embeddings as a 7th RRF leg alongside BM25, with a
  memoized, thread-safe `SparseEmbedder`.

## [2.1.0] — 2026-06-30

### Overview
Two major feature sets landing together. Phase A ships the Knowledge Graph layer (v2.0.0 development).
Phase B is the Beast-Mode Upgrade: seven research-grounded retrieval improvements, all opt-in via
config flags that default to `False` — zero regression when disabled.

### Added — Knowledge Graph (Phase A)
- **Knowledge Graph**: new `trelix/graph/` module unifying call/import/type edges into a traversable `CodeGraph` (NetworkX MultiDiGraph)
- **Community Detection**: Louvain algorithm clusters codebase into architectural modules; `trelix graph ./repo` CLI command shows top communities
- **Semantic Concepts**: `ConceptExtractor` — LLM-powered extraction of architectural concepts from symbol batches (crash-safe, returns `[]` on any failure)
- **Graph Visualization**: `GraphVisualizer.export_html()` — Pyvis interactive HTML with community coloring and edge-type coloring; `pip install trelix[knowledge-graph]`
- **4th Retrieval Leg**: `graph_search_enabled=True` in `RetrievalConfig` enables CodeGraph BFS as a 4th search leg after RRF fusion
- **REST API**: `GET /graph`, `GET /graph/communities`, `GET /graph/visualize`, `GET /graph/search` endpoints
- **MCP Tools**: `build_knowledge_graph` and `graph_search_mcp` tools in `trelix-mcp`
- **Graph Persistence**: `graph_metadata` SQLite table stores community and degree centrality per symbol
- **PageRank symbol boosting** (`pagerank_boost_enabled`) — scores symbols by import-graph centrality; boosts high-centrality symbols post-rerank
- **Incremental graph updater** — `GraphUpdater.update_file()` refreshes community + PageRank for a changed file; wired into `trelix watch`

### Added — Beast-Mode Retrieval (Phase B)
- **File-summary 5th retrieval leg** (`file_summary_leg_enabled`) — RAPTOR-style file-level embeddings used as a 5th RRF leg (arXiv:2401.18059); requires `TRELIX_FILE_SUMMARIES_ENABLED=true` at index time
- **HyDE fallback** (`hyde_fallback_enabled`) — Hypothetical Document Embeddings (arXiv:2212.10496): generates a synthetic code snippet, embeds it instead of the raw NL query
- **Multi-query expansion** (`multi_query_enabled`) — decomposes a query into N variants, retrieves independently, RRF-fuses for broader recall
- **FLARE re-retrieval loop** (`flare_enabled`) — confidence-gated iterative retrieval (arXiv:2305.06983): re-retrieves when synthesis output contains uncertainty phrases
- **Query telemetry** (`telemetry_enabled`) — `TelemetryWriter` writes per-query rows (latency, intent, result count) to `query_telemetry` SQLite table; `trelix telemetry` CLI shows recent queries
- **CoIR evaluation harness** — `trelix eval --golden <file>` reports nDCG@10, Recall@10, MRR (CoIR format, ACL 2025 arXiv:2407.02883); pure-Python `trelix.eval.ndcg` with no pandas dependency

### Breaking Changes
- **CLI**: `trelix graph` renamed to `trelix call-graph` (the old call-graph/callers display).
  The name `trelix graph` now refers to the knowledge graph build command.
  Update any scripts using `trelix graph <repo> <symbol>` to `trelix call-graph <repo> <symbol>`.

---

## [2.0.0] — 2026-06-28

### Overview
Major feature release spanning three research-grounded upgrade phases. Phase 1 delivers CoIR SOTA embedding models (BGE-Code-v1 at 81.77, Nomic CodeRankEmbed) and Voyage Matryoshka compact dimensions. Phase 2 adds RAPTOR-style multi-granularity file summaries, the PLAID ColBERT late-interaction reranker (7–45× faster than exact ColBERT), and live streaming synthesis for `trelix ask`. Phase 3 ships a LanceDB vector backend (3–5× faster insert at 100k+ chunks) and a production-ready REST API (`trelix serve`) with SSE streaming and full CRUD index management. An LLM-as-judge evaluator rounds out the quality measurement story.

### Added
- **BGE-Code-v1 embedder** (`bge-code` provider) — BAAI CoIR SOTA 2025, self-reported 81.77 avg. `pip install trelix[bge-code]`
- **Nomic CodeRankEmbed embedder** (`nomic-code` provider) — task-prefix asymmetric encoding, no new deps. `pip install trelix[local]`
- **Voyage Matryoshka support** — `TRELIX_EMBEDDER_VOYAGE_OUTPUT_DIMENSIONS=512` passes `output_dimension` to voyage-code-3 API for compact embeddings
- **LLM-as-judge eval scorer** — `LLMJudge.score()` rates semantic retrieval quality 0.0–1.0; `EvalReport.mean_judge_score` aggregate
- **Multi-granularity file summaries** — `TRELIX_FILE_SUMMARIES_ENABLED=true` generates LLM file-level summaries alongside symbol chunks (RAPTOR-inspired, arXiv 2401.18059). Enables "explain this codebase" queries.
- **PLAID late-interaction reranker** — `rerank_provider=plaid` via RAGatouille. 7–45× faster than exact ColBERT with equivalent quality. `pip install trelix[plaid]`
- **Streaming synthesis** — `trelix ask` streams tokens live to the terminal; `GET /ask` SSE endpoint for REST clients
- **LanceDB vector backend** — `TRELIX_STORE_BACKEND=lance` enables ARM-native HNSW with 3–5× faster vector insert at 100k+ chunks. `pip install trelix[lance]`
- **REST API** — `trelix serve ./repo --port 8765` exposes `/search`, `/ask` (SSE), `/index`, `/health` endpoints via FastAPI. `pip install trelix[serve]`

### Fixed
- **pathspec DeprecationWarning** — upgraded `PathSpec.from_patterns()` call site to current API; eliminates deprecation warnings in all indexing paths

---

## [1.1.0] — 2026-06-28

### Overview
Search quality and performance release — all four phases from the v1.0.0 stress test audit.

### Added
- **Phase 1b: QueryPlan LRU cache** — `CachingPlanner` caches the gpt-4o query planner call (~2–4s). Combined with Phase 1 embedding cache, warm P50 drops from ~4,500ms to **23ms** (170× speedup). `TRELIX_RETRIEVAL_PLAN_CACHE_SIZE=128` (default).
- **Phase 3: Public graph API** — `Retriever.get_callers(symbol)`, `get_callees(symbol)`, `get_importers(path)` expose the call/import graph. New `trelix graph <repo> <symbol>` CLI subcommand.

### Fixed
- **Phase 2: File-type weighting** — README/YAML no longer outranks source code in search results. Per-language RRF score multipliers: source `1.0×`, markdown `0.3×`, yaml/json `0.5×`, html/css `0.4×`. Fixes 4/6 recall misses from v1.0.0 stress test.
- **Phase 4: tree-sitter API upgrade** — All 20 parser extractors migrated from deprecated `Language(path, name)` to `get_language()`. Eliminates 439 FutureWarnings per test run.

### Test coverage
- 1197 unit tests (was 1148), 8 warnings (was 439)

---

## [1.0.0] — 2026-06-27

### Overview
First stable release of trelix. Public Python API stabilised, all hard blockers
resolved, coverage gate at 75%, full v1 stability guarantees in effect.

### Added
- Public Python API: `from trelix import IndexConfig, Indexer, Retriever, TrelixChatClient`
- `trelix --version` / `trelix -V` flag
- SECURITY.md with responsible disclosure policy
- Versioning & Stability Policy in CONTRIBUTING.md
- Troubleshooting section in README
- trelix-langchain README.md (PyPI listing)
- Unit tests for retriever, reranker, indexer, planner, CLI, and 6 parser extractors

### Fixed
- `trelix ask` with Anthropic/Bedrock/Vertex no longer silently falls back to OpenAI
- `grep_search._body_search` bounded — eliminates OOM on large repos
- Incremental watch: debounced cross-file resolution passes
- Raw pydantic ValidationError replaced with clean user-facing messages
- Ctrl+C during indexing shows "Indexing cancelled." cleanly
- Empty search results show "No results found." instead of blank table
- `bedrock-titan` and `bedrock-cohere` now selectable via `--provider` flag
- requires-python tightened to <3.13 (honest — cp313 tree-sitter-languages unavailable)

### Changed
- Development Status: 4 - Beta → 5 - Production/Stable
- Coverage gate: fail_under = 75
- `dist/` added to .gitignore

---

## [0.7.1] — 2026-06-27

### Fixed
- **`BedrockCohereEmbedder` chunk truncation** — Bedrock validates text length before
  applying `truncate="END"`, so texts >2048 characters raised `ValidationException` at
  the API level. Now pre-truncates client-side to 2048 chars before each `invoke_model`
  call. Found during live end-to-end indexing with default `max_tokens_per_chunk=512`
  (code chunks with docstrings routinely exceed 2048 characters).

### Added
- **Bedrock full-pipeline e2e tests** — `tests/integration/test_llm_e2e.py` now includes
  two tests that index a synthetic Python repo end-to-end (walk → parse → chunk → embed
  via Bedrock → store → search) for both `bedrock-cohere` and `bedrock-titan` providers.
- **`trelix-llama-index` README** — PyPI listing now shows description and usage examples.

---

## [0.7.0] — 2026-06-27

### Overview
Universal LLM client factory — all 5 chat call sites migrated to a provider-agnostic
`TrelixChatClient` ABC. Adding any new provider requires zero changes to business logic.

### Added
- **`src/trelix/llm/` package** — `TrelixChatClient` ABC, `ChatMessage`, `ChatResponse`,
  `ToolCallResponse` dataclasses, `build_chat_client()` factory
- **`LLMConfig`** — new config class for chat providers (separate from `EmbedderConfig`).
  Added as `IndexConfig.llm` field.
- **`OpenAIBackend`** — OpenAI + Azure. Auto-detects `max_completion_tokens` vs `max_tokens`
  based on model family (gpt-4o→max_completion_tokens; gpt-4/gpt-3.5→max_tokens)
- **`AnthropicBackend`** — Anthropic Claude direct. `max_tokens=`, `system=` separate param,
  `input_schema` tool format, `end_turn`→`stop` normalization. `pip install trelix[anthropic]`
- **`BedrockBackend`** — AWS Bedrock Converse API. `inferenceConfig.maxTokens` (nested camelCase),
  `system=[{"text":...}]` top-level, content always list-of-dicts, `{"auto":{}}` tool choice.
  `pip install trelix[bedrock]`
- **`VertexBackend`** — Google Vertex AI / Gemini via google-genai SDK. `max_output_tokens` in
  `GenerateContentConfig`, `system_instruction=` param. `pip install trelix[vertex]`
- **`LiteLLMBackend`** — universal delegate for 100+ providers. `drop_params=True` suppresses
  UnsupportedParamsError. Model strings: `"bedrock/claude-3-5-sonnet"`, `"gemini/gemini-2.0-flash"`.
  `pip install trelix[litellm]`
- New optional dep groups: `[anthropic]`, `[bedrock]`, `[vertex]`, `[litellm]`, `[llm-all]`

### Changed
- All 5 LLM call sites now use `TrelixChatClient` via factory — never import provider SDKs directly
- `ContextualChunker` accepts `TrelixChatClient` (new) or raw openai client (backward compat)

### Fixed
- `_token_limit_param()` in OpenAIBackend correctly routes legacy models to `max_tokens=`
  and modern models to `max_completion_tokens=` — eliminates the recurring parameter bug
- `BedrockBackend`: base64-encoded AWS credentials (stored in `.env`) decoded transparently
- `BedrockBackend`: bare model IDs rejected by Bedrock — now uses `us.*` inference profile IDs
- Unit test isolation: `test_llm_field_on_index_config` no longer leaks `.env` provider state

### Added (post-task additions)
- **`BedrockTitanEmbedder`** — `amazon.titan-embed-text-v2:0`, configurable 256/512/1024 dims,
  normalize=True. Set `TRELIX_EMBEDDER_PROVIDER=bedrock-titan`. `pip install trelix[bedrock]`
- **`BedrockCohereEmbedder`** — `cohere.embed-english-v3`, 1024 dims, asymmetric doc/query
  retrieval (`search_document` vs `search_query` input_type). `pip install trelix[bedrock]`
- **Bedrock model fallback** — `BedrockBackend` defaults to `us.anthropic.claude-sonnet-4-6`
  (primary) with transparent auto-fallback to `us.anthropic.claude-haiku-4-5-20251001-v1:0`
  on `ValidationException`. Override via `TRELIX_LLM_BEDROCK_PRIMARY_MODEL` /
  `TRELIX_LLM_BEDROCK_FALLBACK_MODEL`.
- **Live e2e tests** — `tests/integration/test_llm_e2e.py`: 16 tests covering Azure + Bedrock
  chat (complete/stream/tool_call) + Bedrock embeddings. Skip gracefully when creds absent.

---

## [0.6.0] — 2026-06-27

### Overview
Contextual chunking is now production-ready — the feature works end-to-end with verified context summaries stored in the database and indexed in BM25. Two bugs fixed that prevented contextual summaries from actually persisting.

### Fixed
- **Contextual chunking context_summary persistence:** `ContextualChunker.build_chunks()` sets `symbol.context_summary` but the DB insert in `Indexer._insert_one()` happened before chunking ran. Fixed by adding an `UPDATE symbols SET context_summary = ?` pass after `build_chunks()` for any symbols that received summaries. All 66 test symbols now have `context_summary IS NOT NULL`.
- **Contextual chunking LLM call:** `ContextualChunker._generate_summary()` used `max_tokens=` — unsupported by gpt-4o / newer Azure. Changed to `max_completion_tokens=` (consistent with synthesizer.py fix in v0.3.0).
- **Test updated:** `test_llm_called_with_correct_arguments` asserts `max_completion_tokens` instead of `max_tokens`.

### Verified
- 66/66 symbols receive LLM context summaries stored in `symbols.context_summary`
- Summaries indexed in `symbols_fts` — BM25 searches now include them
- Recall@5: 10/10 = 100% on mini_repo (baseline maintained)

### How to Enable Contextual Chunking

```bash
TRELIX_CHUNKER_CONTEXTUAL=true
TRELIX_CHUNKER_CONTEXTUAL_MODEL=gpt-4o-mini
TRELIX_EMBEDDER_PROVIDER=openai   # or azure
trelix index ./your-repo
```

---

## [0.5.1] — 2026-06-27

### Fixed
- `trelix-mcp` README: add `<!-- mcp-name: io.github.sairam0424/trelix -->` ownership verification tag required by the official MCP registry
- `trelix-mcp` server.json: shorten description to ≤100 chars to pass registry validation

---

## [0.5.0] — 2026-06-27

### Overview
Ecosystem discoverability release — trelix is now reachable across every major surface in the AI developer ecosystem. Three new PyPI packages, MCP registry listing, GitHub Action marketplace, Homebrew tap, and awesome list submissions.

### Added

#### New PyPI Packages
- **`trelix-mcp`** (`pip install trelix-mcp`) — MCP server exposing 4 tools via stdio transport. Works with Claude Code, Cursor, Windsurf, and Continue.dev. One-command setup: `claude mcp add trelix -- trelix-mcp`.
  - `search_code(query, repo_path, k=10)` — hybrid semantic + BM25 code search
  - `index_codebase(repo_path, provider="local")` — index a repository (run once)
  - `get_symbol(qualified_name, repo_path)` — get full source of any symbol
  - `blast_radius(symbol_name, repo_path)` — find everything that depends on a symbol
- **`trelix-langchain`** (`pip install trelix-langchain`) — `TrelixRetriever(BaseRetriever)` for LangChain RAG pipelines. Returns `list[Document]` with full metadata (file, symbol, language, score, lines).
- **`trelix-llama-index`** (`pip install trelix-llama-index`) — `TrelixIndexRetriever(BaseRetriever)` for LlamaIndex. Returns `list[NodeWithScore]` with file + symbol metadata.

#### Registry & Discovery
- **Official MCP Registry** — submitted via `mcp-publisher` CLI. Server ID: `io.github.sairam0424/trelix`. Pip ownership verified via `mcp-name` tag in README.
- **Glama.ai** — `glama.json` added to repo root for automatic Glama MCP directory indexing.
- **GitHub Actions Marketplace** — `trelix-index-action@v1` at `github.com/sairam0424/trelix-index-action`. Auto-indexes any repo on push with cached `.trelix/index.db`.
- **Homebrew tap** — `brew tap sairam0424/trelix && brew install trelix` via `github.com/sairam0424/homebrew-trelix`.
- **Awesome list submissions** — PRs submitted to awesome-mcp-servers (#8787), awesome-llm-apps (#903), awesome-langchain (#426).

#### PyPI Metadata
- 5 new Topic classifiers: `Scientific/Engineering :: Artificial Intelligence`, `Software Development :: Libraries :: Application Frameworks`, `Text Processing :: Indexing`, `Internet :: WWW/HTTP :: Indexing/Search`
- 21 keywords including `mcp`, `model-context-protocol`, `langchain`, `llama-index`, `code-assistant`, `static-analysis`
- 3 new README badges: MCP Compatible, LangChain retriever, Downloads

#### CI/CD
- `release.yml` now publishes all 4 packages (`trelix`, `trelix-mcp`, `trelix-langchain`, `trelix-llama-index`) to PyPI on `v*` tag
- PyPI OIDC trusted publisher configured for all 4 packages (no stored secrets for future releases)

#### Documentation
- `docs/discoverability/ECOSYSTEM-ROADMAP.md` — full ecosystem strategy with registry URLs, submission templates, priority stack
- `docs/discoverability/AWESOME-LIST-SUBMISSIONS.md` — ready-to-submit PR bodies for 3 awesome lists
- `packages/trelix-mcp/README.md` — install, Claude Code / Cursor / Windsurf / Continue.dev setup, tools table
- `packages/trelix-mcp/server.json` — official MCP registry schema for `mcp-publisher`

### Changed
- `pyproject.toml` version `0.4.0` → `0.5.0`; all sub-packages at `0.5.0` (trelix-mcp at `0.5.1`)
- `src/trelix/__init__.py` `__version__` updated to `0.5.0`
- README: added Integrations table (MCP, LangChain, LlamaIndex, GitHub Action, Homebrew), MCP Quick Setup block, LangChain code example, Homebrew install option, GitHub Action quick-start

### Fixed
- Package builds: `LICENSE` copied into each sub-package (hatchling resolves paths relative to package root, not repo root)
- `trelix-mcp/__init__.py`: added `__all__ = ["__version__"]` for parity with other packages
- `trelix-llama-index/retriever.py`: import ordering fix (ruff I001)
- Test files: removed unused `patch` imports from `trelix-langchain` and `trelix-llama-index` test suites

---

## [0.4.0] — 2026-06-26

### Overview
Beast-mode upgrade across three axes simultaneously: **retrieval quality** (+49% embedding quality, 67% failure-rate reduction), **scale** (HNSW index, Qdrant backend), and **speed** (4x async pipeline, real-time file watcher). Grounded in 6 adversarially-verified research findings from the CoIR benchmark, Anthropic contextual retrieval research, and VLDB/ACL 2025 proceedings.

### Added

#### Quality — Retrieval & Embeddings
- **Contextual Chunking (U1):** `ContextualChunker` prepends a 2-3 sentence LLM-generated summary to each chunk before embedding AND BM25 indexing. Reduces retrieval failure rate from 5.7% → 1.9% (67% reduction). Config-gated via `TRELIX_CHUNKER_CONTEXTUAL=false` — off by default.
- **Voyage Code Embedder (U2):** New `voyage` provider using `voyage-code-3` (1024-dim, 16k context). Scores 56.26 avg on CoIR benchmark vs Ada-002's 45.59 (+24%). `pip install trelix[voyage]`.
- **Local Code Embedder (U2):** New `local-code` provider using `Salesforce/SFR-Embedding-Code-2B_R` (4096-dim, 2B params). Scores 67.41 on CoIR — 49% quality gain over Ada-002. No API key required.

#### Scale — Vector Store
- **Filterable HNSW Index (U3):** O(log n) vector search via sqlite-vec HNSW. Falls back to flat scan on older versions.
- **Qdrant Optional Backend (U4):** `QdrantVectorStore` drop-in for >500k chunk deployments. `trelix migrate-vectors --to qdrant`. `pip install trelix[qdrant]`.

#### Speed — Indexing & Updates
- **Async Batch Embedding (U5):** Phase 3 runs up to 4 concurrent embed batches via `asyncio.gather`. ~3-4x speedup on large repos.
- **File Watcher (U6):** `trelix watch <repo>` — 500ms debounced auto-reindex on file save. `pip install trelix[watch]`.

#### Intelligence — Planning & Synthesis
- **Adaptive 3-Tier Query Router (U7):** Tier 1 (direct/skip retrieval) → Tier 2 (8-intent single-step) → Tier 3 (multi-step decomposition).
- **GraphRAG Map-Reduce Synthesis (U8):** For >20 results or >8k tokens, map-reduce synthesis handles arbitrarily large corpora.

#### Precision — Call Graph
- **Call Graph Precision (U9):** 3-priority callee resolution (qualified_name → type_hint+name → name-only). ~40% fewer false-positive cross-file edges.

#### Evaluation
- **Production Eval Harness (U10):** MRR, Recall@1/5/10, NDCG@10 on 50 trelix-self queries. `make eval-full`.

### Changed
- New optional dep groups: `[voyage]`, `[qdrant]`, `[watch]`
- `BaseVectorStore` ABC introduced; `VectorStore` → `SQLiteVectorStore`
- `QueryPlanner` → `AdaptiveRouter` (backward-compatible)

### Fixed
- `synthesizer.py`: `max_completion_tokens` for gpt-4o compatibility
- Test fixtures: removed synthetic passwords that triggered GitGuardian

---

## [0.3.0] — 2026-06-26

### Added
- Removed all internal origin watermarks (`aava`, `AavaPlatformEmbedder`, `CODEINDEX_*`, `codeindex` binary)
- PyInstaller binary renamed `codeindex` → `trelix`
- Fixed `synthesizer.py` `max_completion_tokens` for gpt-4o
- Restored correct `tree_sitter_languages.get_language()` in 4 parsers
- Updated `.gitignore` to exclude `.claude/`, `uv.lock`, `dist/`

---

## [0.2.0] — 2026-06-25

### Added
- Ruby parser — completes all 20 language extractors
- PyInstaller spec (`trelix.spec`) — `dist/trelix` single-file binary
- `scripts/build-binary.sh`, `make binary` / `make binary-clean` / `make binary-install`
- GitHub Actions `build-binaries.yml` — macOS arm64 + Windows x64 matrix
- Release workflow attaches binaries to GitHub Releases
- `docs/integrations/vscode-plugin.md`

---

## [0.1.0] — 2026-06-25

### Added
- Initial release — Tree-sitter AST indexing for 20+ languages
- Hybrid search: vector (ANN, sqlite-vec) + BM25 (FTS5) + grep via RRF
- RRF fusion + call-graph / import / type-edge expansion with PageRank
- 8-intent LLM query planner
- Cohere + cross-encoder reranker
- Intent-aware context assembler (greedy / breadth_first)
- LLM synthesis via OpenAI or Azure (`trelix ask`)
- CLI: `index`, `search`, `ask`, `query`, `stats`, `update-index`
- Providers: `local` (no API key), `openai`, `azure`
- Zero-infra store: single SQLite file with sqlite-vec + FTS5 BM25

[Unreleased]: https://github.com/sairam0424/trelix/compare/v3.0.1...HEAD
[3.0.1]: https://github.com/sairam0424/trelix/compare/v3.0.0...v3.0.1
[3.0.0]: https://github.com/sairam0424/trelix/compare/v2.12.0...v3.0.0
[2.12.0]: https://github.com/sairam0424/trelix/compare/v2.11.1...v2.12.0
[2.11.1]: https://github.com/sairam0424/trelix/compare/v2.11.0...v2.11.1
[2.11.0]: https://github.com/sairam0424/trelix/compare/v2.10.0...v2.11.0
[2.10.0]: https://github.com/sairam0424/trelix/compare/v2.9.0...v2.10.0
[2.9.0]: https://github.com/sairam0424/trelix/compare/v2.8.1...v2.9.0
[2.8.1]: https://github.com/sairam0424/trelix/compare/v2.8.0...v2.8.1
[2.8.0]: https://github.com/sairam0424/trelix/compare/v2.7.3...v2.8.0
[2.7.3]: https://github.com/sairam0424/trelix/compare/v2.7.2...v2.7.3
[2.7.2]: https://github.com/sairam0424/trelix/compare/v2.7.1...v2.7.2
[2.7.1]: https://github.com/sairam0424/trelix/compare/v2.7.0...v2.7.1
[2.7.0]: https://github.com/sairam0424/trelix/compare/v2.6.0...v2.7.0
[2.6.0]: https://github.com/sairam0424/trelix/compare/v2.5.0...v2.6.0
[2.5.0]: https://github.com/sairam0424/trelix/compare/v2.4.0...v2.5.0
[2.4.0]: https://github.com/sairam0424/trelix/compare/v2.3.0...v2.4.0
[2.3.0]: https://github.com/sairam0424/trelix/compare/v2.2.0...v2.3.0
[2.2.0]: https://github.com/sairam0424/trelix/compare/v2.1.0...v2.2.0
[2.1.0]: https://github.com/sairam0424/trelix/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/sairam0424/trelix/compare/v1.1.0...v2.0.0
[1.1.0]: https://github.com/sairam0424/trelix/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/sairam0424/trelix/compare/v0.7.1...v1.0.0
[0.7.1]: https://github.com/sairam0424/trelix/compare/v0.7.0...v0.7.1
[0.7.0]: https://github.com/sairam0424/trelix/compare/v0.6.0...v0.7.0
[0.6.0]: https://github.com/sairam0424/trelix/compare/v0.5.1...v0.6.0
[0.5.1]: https://github.com/sairam0424/trelix/compare/v0.5.0...v0.5.1
[0.5.0]: https://github.com/sairam0424/trelix/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/sairam0424/trelix/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/sairam0424/trelix/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/sairam0424/trelix/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/sairam0424/trelix/releases/tag/v0.1.0