index-graph 2.16.0

Adds index navigate and index outline-map: code for a plain-language question, found one
typed question per level, with a frozen benchmark beside it.

• index navigate ROOT "question" finds the code for a plain-language question. It walks
  directory, file and symbol with one typed question per level, follows every child at
  least half as likely as the top child (up to four), keeps the rest in a backlog for
  backtracking, and delivers only the best leaf of each file it reached. --json adds
  the source text and the decision path (index.decision-path/v1). Code files only by
  default; --include-docs adds prose and config.

• index outline-map ROOT --node ID prints one outline node's children as a map: a name
  and description for a model, and a handle with the node id for the code. A host model
  can walk the tree itself and only ever choose among nodes that exist.

• MCP tools index.navigate and index.outline-map, in the full server and the
  read-only client profile.

• Benchmark on 60 frozen questions from merged pull requests (query file SHA-256
  a264681f...): navigate recall@5 0.389 against grep 0.422 (difference -0.033,
  interval -0.114 to 0.055) at 0.33 of grep's tokens (interval 0.27 to 0.41). The bar
  set before the run passes on point estimates; the stricter interval version does not.
  Details, the design-set shortfall and limits in docs/NAVIGATE.md; inputs, builder
  and results in benchmarks/navigate/.

• The local client profile marks Git as unavailable before any Git code runs. In a
  Git workspace, index.map no longer reads INDEX_GIT_TIMEOUT_SECONDS or copies the
  environment for a Git call that the audit hook would refuse. A test with a planted
  token checks that the client tools never read it. The full CLI and MCP server keep
  their Git behavior.

• The plugin folder now carries its own copy of the server code under
  client-plugin/server/src, so a directory install that receives only that folder
  starts. python scripts/build_client_package.py --sync-vendored rewrites it from
  src/, and a test fails when the copy drifts. The launcher no longer falls back to
  the repository's src and reports a missing copy in one line.

• The plugin folder stays within the directory limits: 512 files, and 256 KiB for every file that is not an image or font.

• The Claude plugin manifest carries directory listing fields: display name, keywords,
  homepage, documentation, support, privacy and terms links, and a 1024 px icon.

• Claude Code now asks for the readable workspace and the optional state directory
  when the plugin is enabled. The Claude .mcp.json passes them as ${user_config.*}
  launch arguments with the same settings and defaults as the MCPB. Portable and Codex
  manifests are unchanged.

• The client README gains a data and network table derived from the launcher code.

• The client README and PRIVACY.md gain a "What this plugin runs and handles" section:
  hooks (none), the exact launch command, network (none), files written in the state
  directory, and every environment variable the client code reads.

index-graph 2.15.0

Adds local client packages with explicit launch permissions. Client-specific installation
and marketplace acceptance remain separate qualification steps.

• Add a local MCP profile with an explicit readable workspace, typed permission refusals, and process/network denial at launch. The full CLI/MCP remains available separately.
• Add portable source plugins for Claude/Codex-compatible clients and Windows x64 ZIP/MCPB packages containing the runtime, licenses, source hashes and checksums.
• Check actual stdio behavior before packaging, reject untracked or credential-like release payloads, and attach checked client assets to the same product release.
• Add an explicit launch-time state directory for bounded map caching and existing job status, result and cooperative cancellation. Tool arguments cannot grant writes. Job start/resume and Git remain unavailable because processes are denied.

index-graph 2.14.1

• Router inventory preserves workspace-relative repository and document names
  when Windows directory junctions point to offloaded repositories. Duplicate
  basenames retain distinct relative keys instead of raising a path error.
• Graph preloads retain each repository's captured physical root. A changed root
  fails explicitly; repository-internal junctions outside that root stay excluded
  during preload reuse and fallback after an ordinary file change. Junctions
  entering below a nested repository's marker retain that ownership boundary.
  This preserves the shared traversal without claiming an atomic filesystem
  snapshot.
• An exhausted inventory budget raises the existing ScanBudgetExceeded result
  before repository sorting. Partial discovery does not become a complete map.

index-graph 2.14.0

• Route: add index route --path REPO --json, the index.route MCP tool, and
  the build_route() Python entry point for explicit-path context envelopes that
  validate named repositories under the root without discovering unrelated sibling
  repositories. The route receipt is portable, reconciles selected and rejected
  paths, and embeds the existing context-envelope payload.
• Context envelopes: add opt-in bounded serialized output with --bounded-output,
  the bounded_output MCP/Python argument, and source_ref_omissions records. The
  default remains the existing lossless-by-reference retained-selection budget; the
  opt-in mode compacts oversized source-ref lists into omission counts, hashes, and
  reissue handles and reports packet size as serialized UTF-8 bytes divided by four,
  rounded up, not as tokenizer truth. CLI and MCP calls now measure their emitted
  transport surfaces; bounded CLI JSON writes the measured UTF-8 LF byte payload
  directly so Windows newline translation cannot exceed the reported budget. MCP
  rejects malformed boolean values, and minimal overflow receipts preserve
  pre-existing omitted-repo metadata.
• Releases: a tag push runs the test suite and checks the tag against the package
  version before it builds, uploads to PyPI with skip-existing so a partial
  upload can be re-run, and creates the GitHub Release with the wheel, the sdist
  and SHA256SUMS.txt once PyPI serves those same files. RELEASE.md lists the
  steps, and tests/test_version_sites.py fails when the README or CHANGELOG
  names a version other than the package's.

index-graph 2.13.0

What's Changed

• Reduce repeated router traversal while preserving freshness and cancellation by @HarperZ9 in #41
• Fix router job completion events and worker clock identity by @HarperZ9 in #42
• Release index-graph 2.13.0 by @HarperZ9 in #43

Full Changelog: v2.12.0...v2.13.0

Index 2.12.0: durable workspace mapping

Index can now build a large workspace router as a durable local job. Start returns promptly, status reports progress, and result returns the map only after completion checks. Cancellation and recovery have explicit states. CLI and MCP expose the same five job actions; the synchronous MCP tool points large-workspace callers to them.

index router-job start --root /path/to/workspace
index router-job status JOB_ID
index router-job result JOB_ID

Source caches bind built-in resolver facts to the bytes actually read. Custom resolvers without an explicit shared-reader contract bypass persistence. Source I/O failures cannot silently become complete graphs. Status discovers all 22 current MCP tools.

Validation: 788 tests passed. Two live full-workspace jobs completed 703/703 repository instances; cold wall time was 430 seconds and warm was 493 seconds. The corpus changed and other tests ran concurrently. This demonstrates completed background jobs, not a controlled speedup or semantic completeness. Warm runtime remains an optimization target.

Attached wheel and sdist were independently checked against the accepted source, reproduced from a clean archive, installed in a clean environment, and exercised through real CLI/MCP calls. SHA256SUMS.txt covers both assets. Historical internal planning documents are omitted from the sdist. Source commit: ba73aec; release tag has the identical source tree.

Index 2.11.0

Index 2.11.0

Index 2.11.0 hardens large-workspace inventory and interactive agent surfaces. Complete workspace maps now have a resumable JSONL checkpoint path, and interactive router, graph, context, and context-envelope calls return typed UNVERIFIABLE results when repository discovery exceeds their configured budget.

What changed

• Fixed fresh-process interactive MCP cache identity so warm calls can return before repository discovery instead of recursively walking the workspace during cache lookup.
• Added --budget-ms to index router, index graph, index context, and index context-envelope; matching interactive MCP tools accept budget_ms.
• Added index map --resume-state PATH and MCP index.map resume_state for resumable complete repository inventory builds.
• Made map resume reuse freshness-aware across Git/control-file identity, dirty/untracked state, markers, and row-affecting config.
• Added explicit metadata uncertainty fields: row-level metadata_status, optional metadata_error, and top-level metadata_status, metadata_ok_count, metadata_unknown_count, and dirty_count_status.
• Changed index.map MCP behavior so complete inventory calls do not use the interactive TTL text cache and do not advertise an unsupported budget_ms parameter.
• Prevented broken nested Git markers from inheriting parent repository metadata; failed Git metadata now reports unknown instead of false cleanliness.

Published artifacts

These GitHub release assets are the PyPI-published bytes downloaded back from PyPI during verification, not the earlier local release-candidate build bytes. The local candidate and CI/PyPI builds are content-equivalent against the accepted source, but the archive bytes differ, so the hashes below are authoritative for public downloads.

70c41ff3920a79755465cd0d920acd73d665052f065fa06fc3a61e6bf776ad86  index_graph-2.11.0-py3-none-any.whl
231c9f630c140dcfce5a8ef314f8258faed6399aec5f3e2658f158c64176cef2  index_graph-2.11.0.tar.gz

Accepted local candidate hashes for traceability only:

a003be9115e93e5343f4e651b277aff87ef19e6740a70989aa87c6c8496fb390  index_graph-2.11.0-py3-none-any.whl
1335acd2df103849f30c9f2f45b13601dfa8809c3886e230fc86ff4f5fda7283  index_graph-2.11.0.tar.gz

Provenance and checks

• Tag v2.11.0 peels to merge commit 79f5f65dd516c27618fe80bf45080a9bd1cf8526.
• Accepted source commit 01b2b28ebd443f81898b57dc2ee3f392408f3f92 has an empty tree diff against the merge commit.
• PyPI JSON digests match the downloaded wheel and sdist bytes.
• Wheel provenance check compared 109 packaged Python files against the tag tree with zero mismatches.
• Sdist provenance check compared 312 tracked files against the tag tree with zero mismatches.
• twine check with twine 7 passed for both downloaded distributions.
• GitHub Actions run 34112180947 completed successfully, including the package build and PyPI publish jobs.

Large-workspace acceptance measurement

A final frozen-source private workspace measurement was run at version 2.11.0, commit 01b2b28. The measurement is aggregate-only here; raw path lists were not uploaded.

Surface	Time	Repositories	Diagnostic fixture repos	Metadata ok	Metadata unknown	Dirty count status	Path reconciliation
CLI fresh map	16.609s	617	84	515	102	known_only	exact
CLI resumed map	11.817s	617	84	515	102	known_only	exact
MCP fresh index.map	12.210s	617	84	515	102	known_only	exact
MCP resumed index.map	10.078s	617	84	515	102	known_only	exact

The metadata status is partial because broken or synthetic Git fixtures fail closed as unknown. dirty_count is therefore a known-only aggregate, not a complete workspace cleanliness assertion.

Boundary

This release fixes complete map reliability and bounds interactive discovery failure modes. It does not claim that a cold full router build over every large workspace finishes inside every host timeout; the supported complete-inventory path is index map --resume-state PATH or MCP index.map with resume_state.

v2.9.0

What's Changed

• Improve flagship presentation assets by @HarperZ9 in #14
• Use the Project Telos flagship card as the repo banner by @HarperZ9 in #15
• feat: path selector with typed rejection receipts (index.path-selection/v1) by @HarperZ9 in #16
• index wiki: the verified wiki (derived, receipted, commit-pinned) by @HarperZ9 in #17
• Browser-evidence pipeline (parallel-session work, preserved + integrated) by @HarperZ9 in #19
• feat: staleness contract (index.invalidation/1) + typed focus rejection by @HarperZ9 in #18
• feat: index onboarding overhaul P2 (README wow-first, map write notice, --dry-run) by @HarperZ9 in #20
• refactor(cli): split cli.py into handler and parser modules by @HarperZ9 in #21
• Index elevation P3-P5: wiki URL ingestion, router wiki pointers, Beta classifier by @HarperZ9 in #22
• feat: index serve, on-demand consent-clean verified-wiki server by @HarperZ9 in #23
• feat(symbols): index symbols navigation with find-implementations by @HarperZ9 in #24
• Style: spectrum banner + feature-first README header by @HarperZ9 in #25
• Release v2.9.0 by @HarperZ9 in #26

Full Changelog: v2.8.0...v2.9.0

index 2.8.0

index 2.8.0

A workspace of many repositories has a shape, and past a handful of repos that shape lives only in someone's head. index draws it from evidence: how your repositories depend on each other, the architecture you meant, and whether the code still matches it. Deterministic, fully offline, zero dependencies. No API, no account, no model, no network.

pip install index-graph
index atlas --root /path/to/workspace --format html --out atlas.html

This is the first 2.x release published as a GitHub release, so the notes below cover the whole arc since 1.2.0: index grew from a dependency map into a re-checkable architecture brain.

What index does now

• The two-layer atlas. index atlas renders repos and your markdown docs as one navigable, self-contained HTML map. Pan, zoom, search repos and docs together, read a doc rendered in place with clickable wiki-links. One offline file.
• A dependency graph from real evidence. Every edge is derived from a manifest line and a source import, and carries the file and line that witnesses it, graded by confidence. Nothing enters the graph on faith. Nine ecosystems: Python, JavaScript and TypeScript, Rust, Go, Java, C#, Ruby, PHP, and C and C++. Zero runtime dependencies for any of them.
• Module graph (internals). index internals builds the dependency graph inside one repo, where architecture actually erodes. Python is exact, read from the syntax tree; others best-effort. It reports internal cycles and what every module leans on, and it is honest about what a static scan could not verify (parse failures, dynamic imports).
• Architecture conformance with a re-checkable certificate. Declare the layers, forbidden edges, a cycle ceiling, and required edges in .index.toml. index check measures the real graph against that and returns a certificate whose verdict is one of three words, MATCH, DRIFT, or UNVERIFIABLE, never a fourth. There is no TRUSTED. You believe it by re-running its recheck command and recomputing the hashes, not because it told you to.
• Drift across time. index snapshot then index drift records the shape today and diffs it tomorrow: repos and edges added or removed, cycles introduced or cleared, role changes.
• Freshness. index check --freshness stamps the certificate with a content fingerprint; later index freshness answers whether the ground truth has moved, FRESH or STALE, naming the repos that changed. The mid-loop "has anything changed since I verified?" check.
• Claim grounding. index verify --depends "A -> B" or --exists NAME grounds a claim against the real graph and returns MATCH with the file:line, REFUTED, or UNVERIFIABLE. The anti-hallucination check: confirm a dependency instead of trusting memory.
• The router. index router emits a deterministic, evidence-carrying workspace map for your CLAUDE.md or AGENTS.md, replacing the index plus read-first plus brief that teams maintain by hand.
• A protocol face. index mcp serves an MCP-shaped, zero-dependency JSON-RPC stdio server, so an agent host calls index's deterministic tools by name.
• Token economy you can reproduce. index bench measures how much smaller the structural pack is than the source it distills. On a 47-repo, ~50 MB workspace the pack came back about 70x smaller. Run it on your own workspace.

Why it is built this way

Every verdict is re-checkable by anyone holding only the artifact and the evidence, with no model in the loop. The whole tool runs offline and is agnostic to whatever produced the code it reads. Specified in docs/PROTOCOL.md.

Install and read

pip install index-graph        # Python 3.11+, zero dependencies

• README and the full flag reference: README.md and USAGE.md
• The seam (snapshot, certificate, freshness, hashing rule, resolution bounds): docs/PROTOCOL.md

Fair source (FSL-1.1-MIT): source-available, converts to MIT two years after each release.

index 1.2.0

index 1.2.0 reaches three more ecosystems. It now reads Rust (Cargo.toml), Go (go.mod), and Java (Maven pom.xml, with best-effort Gradle) workspaces, so a polyglot or non-Python workspace finally shows its real dependency edges, each with the file and line that proves it. Rust and Go reach high confidence when a manifest and an import agree; Java is manifest-only.

Under the hood, edge resolution gained a longest-prefix fallback, so a Go import of a module's sub-package resolves to that module. Python and JavaScript resolution is unchanged.

Zero runtime dependencies. Python 3.11 or newer. Fair source (FSL-1.1-MIT).

Install or upgrade:

pip install -U index-graph