diffctx 1.15.0 → 1.16.0

package/README.md

@@ -81,15 +81,22 @@ keeps its git meaning.
 
 | Flag        | Default | Description                                                              |
 |-------------|---------|--------------------------------------------------------------------------|
-| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals) |
-| `--budget`  | auto    | Hard cap in o200k_base tokens (see [Token counting](docs/product/token-budget.md)): `N` enforces a fixed cap, `-1` disables it, `0` is a strict-zero floor (empty selection; use `--full` for changed files only) |
-| `--alpha`   | 0.60    | PPR damping; higher = context clusters tighter around changes (`--scoring ppr` only) |
+| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals); `pit` = the same fusion on score percentiles |
+| `--budget`  | auto    | Cap in o200k_base tokens on the whole rendered artifact (see [Token counting](docs/product/token-budget.md)): every changed file gets one witness first, relevance fills the rest, and the renderer drops context from the tail until the document fits. A budget smaller than the summary yields the summary alone. `N` = fixed cap, `-1` disables it, `0` is a strict-zero floor (no fragments; use `--full` for changed files only) |
+| `--alpha`   | 0.60    | PPR continuation probability: higher = relevance travels further from the change, lower = tighter around it (`--scoring ppr` only) |
 | `--tau`     | 0.05    | Relevance threshold for full fragment content; lower-scoring fragments are stubbed or dropped (lower = more context) |
 | `--full`    | false   | Only the changed files, every fragment, no related-code context          |
-| `--timeout` | 300     | Wall-clock deadline in seconds; on expiry diffctx exits 124 instead of hanging |
+| `--timeout` | 300     | Wall-clock deadline in seconds; on expiry the run stops cooperatively and emits a partial artifact whose `coverage` block names the limit (exit 0). 124 is the watchdog behind it, 30 s later, for a phase that could not stop |
 | `--with-raw-diff` | false | Also embed git's raw unified diff ahead of the selected fragments — additive (selection unchanged), not charged to `--budget`, lock/ignored/secret-like sections omitted. Python CLI only |
 | `--mode` | `pack` | `locate` emits the same ranked selection as compact `diffctx.locate.v1` JSON — path, lines, score, provenance reasons, a blast-radius `summary` and per-item impact `group` (`test`/`type`/`config`), NO source bodies. Adds a `coverage` block naming what the run could not see (`unparsed_files`, `zero_edge_files`, `ppr_truncated`, `next_up`, a heuristic `confidence`) and an `overflow` ranking of what the budget left behind — omitted entirely when there is nothing to disclose. `diffctx . --diff --mode locate` = impact of your uncommitted change. The MCP tool takes it as `mode="locate"` |
 
+Every JSON/YAML artifact opens with `schema: diffctx.context.v1` and validates
+against [`schemas/diffctx.context.v1.json`](schemas/diffctx.context.v1.json),
+generated from the engine's own type; it closes with a `provenance` block
+(engine version, input object ids, the effective configuration and its hash,
+the selection parameters, the tokenizer) and, when a limit stopped the run
+short, a `coverage` block naming it.
+
 ### `graph` subcommand
 
 Explore the underlying dependency graph directly, without a diff:
@@ -141,7 +148,7 @@ from diffctx import build_diff_context, map_directory, to_json, to_markdown, to_
 ctx = build_diff_context(
     Path("."),
     "HEAD~1..HEAD",
-    budget_tokens=None,       # None = auto; 0 = strict-zero floor (empty); -1 = uncapped; N = hard cap
+    budget_tokens=None,       # None = auto; 0 = no fragments; -1 = uncapped; N = cap on the whole artifact
     alpha=0.6,
     tau=0.05,
     full=False,
@@ -193,17 +200,45 @@ reviewing PRs, explaining changes, or investigating broken tests. It ranks the
 code that explains a diff, then reads only the fragments the assistant picked —
 two calls that pay for the selection instead of a whole pack. The wider
 `get_tree_map` and `get_file_context` tools are opt-in via
-`DIFFCTX_MCP_LEGACY_TOOLS=1`. Tool reference and JSON configs for Claude
-Desktop, Cursor, Continue, Windsurf, and Zed:
-[`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
+`DIFFCTX_MCP_LEGACY_TOOLS=1`. Filesystem confinement via
+`DIFFCTX_ALLOWED_PATHS`: see [SECURITY.md](SECURITY.md).
+
+Every stdio client takes the same server shape; only the config file differs:
+
+| Client | Config file | Key |
+|---|---|---|
+| Claude Code (project) | `.mcp.json` | `mcpServers` |
+| Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
+| Cursor | `~/.cursor/mcp.json` | `mcpServers` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
+| Continue | `~/.continue/config.json` | `experimental.modelContextProtocolServers` (transport object) |
+| Zed | `~/.config/zed/settings.json` | `context_servers` (`command.path`) |
+
+```json
+{
+  "mcpServers": {
+    "diffctx": {
+      "command": "uvx",
+      "args": ["--from", "diffctx[mcp]", "diffctx-mcp"]
+    }
+  }
+}
+```
+
+With `pip install 'diffctx[mcp]'` already done, `"command": "diffctx-mcp"` with
+no args works everywhere instead. Use the `diffctx-mcp` entry point, not the
+`diffctx mcp` subcommand: the latter only exists from 1.12.3 onward and would
+map a directory named `mcp` on older releases.
 
 ## Ignore patterns
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
 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).
+anchored `/root_only.txt`), and the output file is always auto-ignored. Three
+controls are tree mode only and are refused with `--diff`: `.diffctx/whitelist`
+(`-w`) as an include-only filter, `-i` for an extra ignore file, and
+`--no-default-ignores` / `--no-ignores` to drop the built-in patterns or every
+ignore rule.
 
 An excluded path never appears in the output in any role: in diff mode it is
 dropped both from `changed_files` and from the candidate universe, so it cannot
@@ -227,7 +262,7 @@ its size (default 512 MB, `0` disables eviction).
 | `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/lockfile-only diffs list `deleted_files`/`renamed_files`/`lockfile_changes` and exit `0` |
-| `124`| `--diff` exceeded the `--timeout` wall-clock deadline |
+| `124`| `--diff` ran 30 s past the `--timeout` deadline without stopping cooperatively (the deadline itself yields a partial artifact and exit 0) |
 | `130`| Interrupted (Ctrl-C) |
 | `141`| Broken pipe (e.g. piping into `head`) |
 
@@ -243,12 +278,18 @@ Apache 2.0
 
 - [Documentation site](https://nikolay-e.github.io/diffctx/) — the pipeline
   end to end: diff → fragments → graph → relevance → selection
+- [Command-line reference](docs/product/cli.md) — every flag with its default
+  and meaning, rendered from `diffctx --help`
 - [GitHub Action](docs/product/github-action.md) — diff context as a CI step
   for LLM review
 - [Token counting](docs/product/token-budget.md) — which encoder, and what
   `--budget` means for non-GPT models
 - [Comparison](COMPARISON.md) — measured results, and when a whole-repo packer
   or a persistent code-graph server fits better
+- [Benchmarks](BENCHMARKS.md) — every published number with what it was
+  measured on, and how to reproduce it
+- [FAQ](docs/product/faq.md) — heuristic or oracle, whose tokens, monorepos,
+  the raw diff, secrets
 - [Paper](https://doi.org/10.5281/zenodo.18824579) — budgeted typed-graph
   retrieval for diff-aware context selection (Zenodo, 2026)
 - [Changelog](CHANGELOG.md)

package/checksums.json

@@ -1,6 +1,6 @@
 {
-  "diffctx-1.15.0-aarch64-apple-darwin.tar.gz": "721f534c2f6c3c6b6bd1a8e9e1a9595116202cb9177c294d625f55d34fb00bed",
-  "diffctx-1.15.0-aarch64-unknown-linux-gnu.tar.gz": "1c9bc1fb064547f24f74401a9e7bab4b85b1c93006e740faae6c1ee2a9bf1a87",
-  "diffctx-1.15.0-x86_64-pc-windows-msvc.zip": "91bb8437cab735b674bb14a76ddc04f8477d8e37766336157551854dc5ab2e1d",
-  "diffctx-1.15.0-x86_64-unknown-linux-gnu.tar.gz": "bfe4b6efc300bd9f38832d10e8a1bb63d6c1e3a328ccf774901f34c914fa513f"
+  "diffctx-1.16.0-aarch64-apple-darwin.tar.gz": "1ef7e2a1609a446f5dce62cd5060878c4d4a1c9032b8971e0fbe73b7089d5951",
+  "diffctx-1.16.0-aarch64-unknown-linux-gnu.tar.gz": "726b07c7925da947912da755f0348879a2510af193eb824ad516283db0a0bff2",
+  "diffctx-1.16.0-x86_64-pc-windows-msvc.zip": "f690a79444040efff1328380ff14b509bf39dacd1e6502fe2a5684bbcc5a0dfa",
+  "diffctx-1.16.0-x86_64-unknown-linux-gnu.tar.gz": "5af02c55d8ce57b868c4006ff6b055d1672530bc7911f08cb754d8b24a44bd6a"
 }

package/install.js

@@ -24,7 +24,9 @@ function selectTarget() {
   if (!selected) {
     throw new Error(
       `diffctx has no prebuilt binary for ${key}. ` +
-        'Install via pip ("pip install diffctx") or cargo ("cargo install diffctx") instead.'
+        'On an Intel Mac, pip has no wheel for it either: run under Rosetta with an arm64 Node, ' +
+        'or build from source with "pip install diffctx --no-binary diffctx" (needs Rust) ' +
+        'or "cargo install diffctx".'
     );
   }
   return selected;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "diffctx",
   "mcpName": "io.github.nikolay-e/diffctx",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Selects the minimum code an LLM needs to review a git diff",
   "keywords": [
     "git",