diffctx 1.12.0__tar.gz → 1.12.2__tar.gz

{diffctx-1.12.0 → diffctx-1.12.2}/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **The container images ran as root.** The published 1.12.1 image had no
+  `USER` directive, so every `docker run` executed as uid 0 while the README
+  promised an unprivileged user. The image now runs as uid 10001.
+- **The MCP server advertised the SDK's version as its own.** `FastMCP` takes
+  no version argument, so `initialize` reported the installed `mcp` package
+  version (e.g. `1.28.1`) as the diffctx server version — a number that drifts
+  with every SDK bump and never matched the shipped package. Clients now see
+  the real version.
+- **The native binary hard-capped every run at 4096 tokens.** `--budget`
+  carried a fixed clap default instead of leaving the budget unset, so the
+  auto-sizing the Python CLI has always used never ran on the binary shipped
+  via crates.io, npm, the container images, Scoop, AUR and the release
+  archives — the same command returned a truncated selection there (14-file
+  self-eat range: 15 fragments across 10 files, against 172 across 44). The
+  binary now defaults to auto sizing, and `--budget -1` means unlimited as it
+  does in Python.
+- The token cache grew without bound (a machine that had analyzed a few dozen
+  repositories reached 817k files / 4.0 GB). It is now capped at 512 MB,
+  overridable with `DIFFCTX_TOKEN_CACHE_MAX_BYTES` (`0` disables eviction);
+  each run trims one of the 256 shards back under its share of the cap,
+  oldest entries first (#122).
+- The native binary exited `0` on a diff that produced no semantic context
+  (clean tree, binary-only, everything over the size cap), so callers on the
+  binary channels could not tell an empty selection from a successful one. It
+  now mirrors the Python CLI: the `no semantic context` warning plus its hint
+  on stderr and exit code `4`.
+- The native binary printed no token summary, although the README documents
+  one for every run. It now writes `N tokens (o200k_base), SIZE` to stderr,
+  silenced by the new `-q/--quiet`.
+- `diffctx -v` was a usage error on the native binary while it printed the
+  version on the Python CLI. Both short forms (`-v`, `-V`) now work.
+- **A diff could lose its change signal entirely.** When the only fragment
+  covering a hunk was a whole-file chunk — flat data files, languages without a
+  tree-sitter parser, parse degradation — that chunk had no cheap variant to
+  fall back on, so an oversized core was skipped and the output carried *zero*
+  `role: "changed"` fragments while rendering the unchanged rest of the file as
+  context. Such cores now fall back to an excerpt: the changed lines plus three
+  lines of context, cut from the chunk itself and rendered as `kind: excerpt`,
+  `role: "changed"`. On the elasticsearch `muted-tests.yml` repro the output
+  goes from 121 fragments and no change signal to 118 fragments carrying the
+  appended entry, 5,337 tokens instead of 5,970 (#103). The whole-file
+  fragmentation of flat lists that the same repro shows is the separate
+  granularity issue (#105) and is unchanged.
+- A diff whose selection came back empty rendered as a bare `name`/`type` stub
+  in every format: the writer gated *all* diff metadata on there being
+  fragments, so the commit message and the list of changed files — the only
+  actionable facts about such a run — were dropped. They are now always
+  written.
+
+### Changed
+
+- **Lock files no longer render their hunks in diff mode.** A dependency bump
+  is signal, the checksum churn carrying it is not: `diffctx . --diff` used to
+  spend 12 KB of a 48 KB output on a `Cargo.lock` chunk. The touched lock files
+  are now listed under `lockfile_changes:` (paths only, like `deleted_files:`),
+  mirroring the tree-mode ignore policy while keeping the fact that they
+  changed — on the reported range the output drops from 12,947 to 7,888 tokens
+  (#112). Recognized: `Cargo.lock`, `package-lock.json`, `npm-shrinkwrap.json`,
+  `yarn.lock`, `pnpm-lock.yaml`, `bun.lock(b)`, `deno.lock`, `Pipfile.lock`,
+  `poetry.lock`, `uv.lock`, `pdm.lock`, `composer.lock`, `Gemfile.lock`,
+  `flake.lock`, `go.sum`, `mix.lock`, `packages.lock.json`, `gradle.lockfile`,
+  `Package.resolved`, `cabal.project.freeze`. `--full` still renders their
+  content — it is the escape hatch that promises every fragment of the changed
+  files.
+- Native binary CLI parity: `-f` is accepted as the short form of `--format`,
+  bare `--diff` means the working tree against `HEAD`, `--scoring` advertises
+  its accepted values, and every option carries help text.
+- The standalone binary is covered by its own integration suite
+  (`crates/diffctx-native/tests/native_cli.rs`, run in CI): exit codes, both
+  version flags,
+  the token summary, `--quiet`, format validation and budget handling are now
+  contract-tested against real git repositories. Every parity defect above
+  shipped because nothing exercised the clap parser.
+
+## [1.12.1] - 2026-07-23
+
+### Added
+
+- Standalone native binaries (linux x86_64/aarch64, macOS arm64, Windows
+  x64) are built and attached to every GitHub release. The README had
+  promised them since 1.9.x; releases only ever carried wheels and an sdist.
+- The Rust engine is published to crates.io as the `diffctx` crate
+  (`cargo install diffctx` for the native CLI, `cargo add diffctx` to embed the
+  selection pipeline). Previously the name held only a reservation stub; the
+  crate now carries the released engine, starting at 1.12.0.
+- Container image `ghcr.io/nikolay-e/diffctx` (linux amd64/arm64), built from
+  the release tag and smoke-tested against a real repository before the tag
+  moves: `docker run --rm -v "$PWD:/repo" ghcr.io/nikolay-e/diffctx . --diff HEAD~1`.
+  Mirrored to Docker Hub as `nikolajer/diffctx`.
+- Packaging manifests generated from the release checksums: Scoop
+  (`packaging/scoop/diffctx.json`), AUR (`packaging/aur/`) and an npm wrapper
+  (`packaging/npm/`) that downloads the platform binary and verifies its
+  SHA-256 against the published checksum.
+
+### Fixed
+
+- The native binary silently emitted YAML for every unrecognized `--format`,
+  including `md` — the documented default of the Python CLI. It now accepts
+  only `yaml`/`json` and exits 2 on anything else.
+
 ## [1.12.0] - 2026-07-23
 
 ### Added
@@ -55,7 +157,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   log instead of re-running the builders, so generation cost stays 1x.
   Verified: gitpod 8000s-hang -> 35.7s,
   pytorch 1848s-SIGKILL -> 7.4s, mui/material-ui OOM class recovered.
-  Outputs are bit-identical (gated by `benchmarks/equivalence_gate.py`).
+  Outputs are bit-identical (gated by `eval/analysis/equivalence_gate.py`).
 
 ### Known limitations
 
@@ -94,7 +196,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **The default `--format` is now `md` (Markdown), previously `yaml`.** Markdown
   is ~7% more token-efficient than YAML on real diffs and is preferred by
   reviewers for code-fragment-heavy output (evidence:
-  `benchmarks/real_world_diff_bench/`). YAML remains available via `-f yaml`.
+  `datasets/real-world-diff/v1/`). YAML remains available via `-f yaml`.
   This also changes the default stdout format of `treemapper` (a passthrough
   wrapper over this engine); downstream scripts that parse the default output
   must now pass `-f yaml` explicitly. (#104)
@@ -229,7 +331,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   optional `diffctx-mcp` server confines its filesystem reach via
   `DIFFCTX_ALLOWED_PATHS`.
 - Footer of `README.md` links `CHANGELOG.md`, `SECURITY.md`, and
-  `docs/parameter-strategy.md` so they are no longer orphaned.
+  `docs/engineering/parameter-strategy.md` so they are no longer orphaned.
 
 ### Changed
 
@@ -288,5 +390,5 @@ Earlier releases shipped as `treemapper`; see
 <https://github.com/nikolay-e/diffctx/releases> for the corresponding GitHub
 release notes (`1.0.0` through `1.6.1`).
 
-[Unreleased]: https://github.com/nikolay-e/diffctx/compare/v1.7.0...HEAD
+[Unreleased]: https://github.com/nikolay-e/diffctx/compare/v1.12.1...HEAD
 [1.7.0]: https://github.com/nikolay-e/diffctx/compare/v1.6.1...v1.7.0

{diffctx-1.12.0/diffctx → diffctx-1.12.2}/Cargo.lock

@@ -123,9 +123,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clap"
-version = "4.6.2"
+version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd059f9da4f5c36b3787f65d38ccaab1cc315f07b01f89abc8359ee6a8205011"
+checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -145,14 +145,14 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.1"
+version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -194,7 +194,7 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "diffctx"
-version = "1.12.0"
+version = "1.12.2"
 dependencies = [
  "anyhow",
  "clap",
@@ -330,9 +330,9 @@ dependencies = [
 
 [[package]]
 name = "glob"
-version = "0.3.3"
+version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
 [[package]]
 name = "hashbrown"
@@ -500,7 +500,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
 dependencies = [
  "proc-macro2",
- "syn",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -554,7 +554,7 @@ dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
  "quote",
- "syn",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -566,7 +566,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -675,9 +675,9 @@ checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
 
 [[package]]
 name = "serde"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
  "serde_core",
  "serde_derive",
@@ -685,29 +685,29 @@ dependencies = [
 
 [[package]]
 name = "serde_core"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.150"
+version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
  "indexmap",
  "itoa",
@@ -783,6 +783,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "target-lexicon"
 version = "0.13.5"
@@ -819,7 +830,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -865,7 +876,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.117",
 ]
 
 [[package]]
@@ -1459,7 +1470,7 @@ dependencies = [
  "heck",
  "indexmap",
  "prettyplease",
- "syn",
+ "syn 2.0.117",
  "wasm-metadata",
  "wit-bindgen-core",
  "wit-component",
@@ -1475,7 +1486,7 @@ dependencies = [
  "prettyplease",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.117",
  "wit-bindgen-core",
  "wit-bindgen-rust",
 ]

diffctx-1.12.2/Cargo.toml

@@ -0,0 +1,12 @@
+[workspace]
+members = ["crates/diffctx-native"]
+resolver = "2"
+
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+strip = true
+panic = "abort"
+debug = "line-tables-only"
+split-debuginfo = "packed"

{diffctx-1.12.0 → diffctx-1.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffctx
-Version: 1.12.0
+Version: 1.12.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -62,30 +62,35 @@ Provides-Extra: full
 Provides-Extra: mcp
 Provides-Extra: tree-sitter
 License-File: LICENSE
-Summary: Export codebase structure and contents for AI/LLM context
+Summary: Smart git diff context for LLMs and AI agents: budgeted fragment selection, deterministic, MCP server included
 Keywords: ai,chatgpt,claude,code-analysis,code-context,code-review,code-to-prompt,codebase,context,context-selection,diff-context,directory-tree,export,git-diff,json,llm,llm-context,mcp,model-context-protocol,tree,yaml
+Home-Page: https://github.com/nikolay-e/diffctx
 Author-email: Nikolay Eremeev <nikolay.eremeev@outlook.com>
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Changelog, https://github.com/nikolay-e/diffctx/releases
-Project-URL: Homepage, https://github.com/nikolay-e/diffctx
+Project-URL: Changelog, https://github.com/nikolay-e/diffctx/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://nikolay-e.github.io/diffctx/
+Project-URL: Homepage, https://nikolay-e.github.io/diffctx/
 Project-URL: Issues, https://github.com/nikolay-e/diffctx/issues
+Project-URL: Paper, https://doi.org/10.5281/zenodo.18824579
 Project-URL: Repository, https://github.com/nikolay-e/diffctx
 
 # diffctx — smart diff context for LLM code review
 
 [![CI](https://github.com/nikolay-e/diffctx/actions/workflows/ci.yml/badge.svg)](https://github.com/nikolay-e/diffctx/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/diffctx)](https://pypi.org/project/diffctx/)
+[![crates.io](https://img.shields.io/crates/v/diffctx)](https://crates.io/crates/diffctx)
+[![npm](https://img.shields.io/npm/v/diffctx)](https://www.npmjs.com/package/diffctx)
 [![License](https://img.shields.io/pypi/l/diffctx)](https://pypi.org/project/diffctx/)
 
 **diffctx selects the minimum code an LLM needs to review a git diff.**
-Instead of pasting whole files, it walks the dependency graph from the changed
-lines outward and stops as soon as additional context stops paying for itself.
+Instead of pasting whole files, it walks the dependency graph outward from the
+changed lines and stops once more context stops paying for itself.
 
 > Coming from [`treemapper`](https://pypi.org/project/treemapper/)? That name is
-> deprecated — it was a thin wrapper around diffctx. Every command, flag, and
-> API call works unchanged: `treemapper` → `diffctx`, `treemapper-mcp` → `diffctx-mcp`.
+> deprecated. Every command, flag, and API call works unchanged:
+> `treemapper` → `diffctx`, `treemapper-mcp` → `diffctx-mcp`.
 
 ## Why not just use `tree` or repomix?
 
@@ -109,10 +114,26 @@ pip install diffctx                     # or: into an active environment
 pipx install 'diffctx[mcp]'             # + MCP server for AI assistants
 ```
 
-A standalone binary (no Python required) is on the
-[releases page](https://github.com/nikolay-e/diffctx/releases/latest).
-The `[tree-sitter]` extra adds AST-level parsing for more accurate context
-selection across 30+ languages.
+Without Python:
+
+```bash
+cargo install diffctx                   # native CLI from crates.io
+npx diffctx . --diff HEAD~1             # npm wrapper over the native binary
+docker run --rm -v "$PWD:/repo" ghcr.io/nikolay-e/diffctx . --diff HEAD~1
+```
+
+The image runs as a non-root user (uid 10001) and writes to stdout — the
+native binary has no `-o` flag, so redirect to capture: `... --diff HEAD~1 >
+context.yaml`.
+
+Prebuilt binaries for linux (x86_64/aarch64), macOS (arm64) and Windows (x64)
+are attached to every [release](https://github.com/nikolay-e/diffctx/releases/latest).
+The native binary covers diff mode with YAML/JSON output; tree mode, Markdown
+output, the `graph` subcommand and the MCP server live in the Python package.
+`cargo add diffctx` embeds the pipeline in a Rust project — the library is
+imported as `_diffctx` (`use _diffctx::pipeline::build_diff_context`), since
+the crate doubles as the Python extension module
+([docs.rs](https://docs.rs/diffctx)).
 
 ## Quick start
 
@@ -121,19 +142,18 @@ diffctx . --diff HEAD~1       # smart context for last commit → paste into Cla
 diffctx . -f md -c            # full codebase export → clipboard in Markdown
 ```
 
-![diffctx demo](https://raw.githubusercontent.com/nikolay-e/diffctx/main/docs/demo.gif)
+![diffctx demo](https://raw.githubusercontent.com/nikolay-e/diffctx/main/docs/demo/demo.gif)
 
-*`diffctx . --diff HEAD~1` selects only the fragments — functions, imports,
-type definitions — that an LLM actually needs to review the last commit,
-instead of dumping every changed file in full.*
+*`diffctx . --diff HEAD~1` selects only the fragments an LLM needs to review the
+last commit, instead of dumping every changed file in full.*
 
 ## Diff context mode
 
-Finds the minimal set of code fragments needed to understand a change —
-imports, callers, type definitions, config dependencies — across 50+ file
-types. It builds a code graph (imports, co-changes, type refs), propagates
-relevance from the changed lines outward, and stops when relevance drops below
-`--tau` or the `--budget` token cap is reached.
+Finds the minimal set of fragments needed to understand a change — imports,
+callers, type definitions, config dependencies — across 50+ file types. It
+builds a code graph (imports, co-changes, type refs), propagates relevance
+outward from the changed lines, and stops when relevance drops below `--tau` or
+the `--budget` token cap is hit.
 
 | Flag        | Default | Description                                                              |
 |-------------|---------|--------------------------------------------------------------------------|
@@ -145,8 +165,10 @@ relevance from the changed lines outward, and stops when relevance drops below
 | `--timeout` | 300     | Wall-clock deadline in seconds; on expiry diffctx exits 124 instead of hanging |
 
 Calibration of `--alpha`, `--tau`, and the edge-weight priors:
-[`docs/parameter-strategy.md`](docs/parameter-strategy.md). Theory:
-[Context-Selection for Git Diff (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824580).
+[`docs/engineering/parameter-strategy.md`](docs/engineering/parameter-strategy.md).
+Theory:
+[diffctx: Budgeted Typed-Graph Retrieval for Diff-Aware Code Context
+Selection (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824579).
 
 ### `graph` subcommand
 
@@ -181,11 +203,11 @@ diffctx . --diff HEAD~1 -c               # diff context to clipboard
 <!-- END USAGE -->
 
 Every run reports token count and size on stderr — `12,847 tokens
-(o200k_base), 52.3 KB` (tiktoken, the GPT-4o tokenizer; `~`-prefixed
-approximation above 1 MB). `-c/--copy` sends output to the clipboard via
-`pbcopy` (macOS), `clip` (Windows), or `wl-copy`/`xclip`/`xsel` (Linux).
-Unreadable files are replaced by placeholders such as `<binary file: N bytes>`,
-`<file too large: N bytes>`, or `<unreadable content: not utf-8>`.
+(o200k_base), 52.3 KB` (tiktoken, the GPT-4o tokenizer; `~`-prefixed above
+1 MB). `-c/--copy` copies output via `pbcopy` (macOS), `clip` (Windows), or
+`wl-copy`/`xclip`/`xsel` (Linux). Unreadable files become placeholders like
+`<binary file: N bytes>`, `<file too large: N bytes>`, or
+`<unreadable content: not utf-8>`.
 
 ## Python API
 
@@ -221,32 +243,42 @@ print(to_yaml(tree))
 
 diffctx includes an [MCP](https://modelcontextprotocol.io) server that lets AI
 assistants (Claude Code, Cursor, Windsurf, etc.) call diff context analysis
-automatically during code review. Install with `pip install 'diffctx[mcp]'`
-and add to your MCP client config (e.g. `~/.claude/mcp.json` for Claude Code):
-
-```json
-{
-  "mcpServers": {
-    "diffctx": {
-      "command": "diffctx-mcp"
-    }
-  }
-}
+automatically during code review. Install with `pip install 'diffctx[mcp]'`,
+then register it — for Claude Code:
+
+```bash
+claude mcp add diffctx -- diffctx-mcp
 ```
 
-The server exposes a `get_diff_context` tool that assistants call when
-reviewing PRs, explaining changes, or investigating broken tests. Configs for
+The server exposes three tools — `get_diff_context`, `get_tree_map`, and
+`get_file_context` — that assistants call when reviewing PRs, explaining
+changes, or investigating broken tests. Tool reference and configs for
 Cursor, Continue, Windsurf, and Zed:
 [`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
 
 ## Ignore patterns
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
-every directory level, with gitignore semantics (negation `!important.log`,
-anchored `/root_only.txt`). `.diffctx/whitelist` acts as an include-only
-filter, and the output file is always auto-ignored. `--no-default-ignores`
-disables the built-in patterns; `--no-ignores` disables all ignore rules
-(tree mode only).
+every directory level, with full gitignore semantics (negation `!important.log`,
+anchored `/root_only.txt`). `.diffctx/whitelist` acts as an include-only filter,
+and the output file is always auto-ignored. `--no-default-ignores` disables the
+built-in patterns; `--no-ignores` disables all ignore rules (tree mode only).
+
+## Token cache
+
+Diff mode caches per-blob tokenization under
+`~/Library/Caches/diffctx/token-cache` (macOS),
+`$XDG_CACHE_HOME/diffctx/token-cache` (Linux) or
+`%LOCALAPPDATA%\diffctx\token-cache` (Windows). It is a pure speedup: deleting
+it only costs one cold run.
+
+| Variable | Effect |
+|----------|--------|
+| `DIFFCTX_TOKEN_CACHE_DIR` | Relocate the cache |
+| `DIFFCTX_TOKEN_CACHE_MAX_BYTES` | Size cap, default `536870912` (512 MB); `0` disables eviction |
+
+Eviction is amortized: each run trims one of the cache's 256 shards back under
+its share of the cap, oldest entries first.
 
 ## Exit codes
 
@@ -256,18 +288,33 @@ disables the built-in patterns; `--no-ignores` disables all ignore rules
 | `1`  | Runtime error (bad path, permission denied, etc.) |
 | `2`  | Usage error (invalid flags/arguments) |
 | `3`  | Environment error (`--diff` outside a git repo, git not installed, no commits yet) |
-| `4`  | `--diff` produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename-only diffs list `deleted_files`/`renamed_files` and exit `0` |
+| `4`  | `--diff` produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename/lockfile-only diffs list `deleted_files`/`renamed_files`/`lockfile_changes` and exit `0` |
+| `124`| `--diff` exceeded the `--timeout` wall-clock deadline |
 | `130`| Interrupted (Ctrl-C) |
 | `141`| Broken pipe (e.g. piping into `head`) |
 
+## Repository layout
+
+Rust product code lives in `crates/diffctx-native/`; the Python CLI and MCP
+package live in `src/diffctx/`. Evaluation code, immutable datasets, and paper
+artifacts are intentionally separated under `eval/`, `datasets/`, and `paper/`.
+See [repository ownership boundaries](docs/architecture/repository-layout.md)
+for the lifecycle and entry point of each area.
+
 ## License
 
 Apache 2.0
 
+<!-- mcp-name: io.github.nikolay-e/diffctx -->
+<!-- Ownership marker read from the PyPI description by the MCP registry. -->
+<!-- Must survive edits verbatim: one space after the colon, case-sensitive. -->
+
 ---
 
+- [Documentation site](https://nikolay-e.github.io/diffctx/) — the pipeline
+  end to end: diff → fragments → graph → relevance → selection
 - [Changelog](CHANGELOG.md)
 - [Security policy](SECURITY.md) — threat model and vulnerability reporting
-- [Parameter strategy](docs/parameter-strategy.md) — how `--alpha`,
+- [Parameter strategy](docs/engineering/parameter-strategy.md) — how `--alpha`,
   `--tau`, and edge weights are calibrated