agentpack-cli 0.3.20__tar.gz → 0.3.22__tar.gz

{agentpack_cli-0.3.20 → agentpack_cli-0.3.22}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.20
-Summary: Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents.
+Version: 0.3.22
+Summary: Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows.
+Project-URL: Homepage, https://github.com/vishal2612200/agentpack
+Project-URL: Documentation, https://vishal2612200.github.io/agentpack/
+Project-URL: Repository, https://github.com/vishal2612200/agentpack
+Project-URL: Issues, https://github.com/vishal2612200/agentpack/issues
+Project-URL: Changelog, https://github.com/vishal2612200/agentpack/blob/main/CHANGELOG.md
 License: MIT
 License-File: LICENSE
-Keywords: ai,ai-agent,ai-coding-agents,antigravity,ci,claude-code,codex,coding-agent,context,context-engine,context-packing,context-router,cursor,developer-tools,llm,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,windsurf
+Keywords: ai,ai-agent,ai-coding-agents,antigravity,ci,claude-code,codex,coding-agent,context,context-engine,context-packing,context-router,cursor,developer-tools,llm,local-first,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,repo-map,task-focused-context,windsurf
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -12,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -49,14 +55,21 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-**Local MCP context router for AI coding agents.**
+**Local context engine for AI coding agents.**
 
-Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
+AgentPack ranks relevant repository files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools, CI jobs, and markdown-based LLM workflows.
 
-AgentPack gives them a ranked map of likely relevant files, tests, rules, and skills for each task. It analyzes your repo locally and packages compact context for CLI and MCP workflows.
+It runs local/offline repo analysis, compresses selected files into a token budget, and keeps context fresh through CLI commands, MCP tools, hooks, and agent integrations. Use it when an AI coding agent needs a ranked starting map instead of burning tool calls rediscovering your repo.
 
-How it works: AgentPack compresses repo context into ranked packs, caches scans/summaries/pack metadata for fast refreshes, and retrieves exact file or symbol blocks later when an agent needs more detail. Rendered packs also put stable instructions before volatile task, timestamp, git, and file sections so provider prompt-prefix caches can reuse the front of repeated refreshes. No cloud indexing, embeddings, or API calls are required for scan, summarize, rank, pack, stats, or benchmark. See [How AgentPack works](docs/how-agentpack-works.md) for the full scan, rank, compress, cache, retrieve, route, and benchmark flow.
-Try the read-only task router without writing context files:
+AgentPack is a context preparation tool, not a coding agent.
+
+One workflow matters:
+
+```text
+route -> pack -> agent acts -> benchmark captures miss
+```
+
+First route the task to likely files, tests, rules, and skills:
 
 ```bash
 pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
@@ -64,89 +77,119 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
 
 ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
 
-> **Status: alpha (v0.3.20).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
+> **Status: alpha (v0.3.22).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 >
 > **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
 
-## What's New in 0.3.20
+## What's New in 0.3.22
 
-`0.3.20` adds a dedicated "How AgentPack works" guide for scan, rank, compress,
-cache, retrieve, route, stable-prefix caching, and skill keyword quality. It
-also polishes the local dashboard and expands skill-routing benchmark guidance
-for `expected_skills`, `avoid_skills`, recall, precision, MRR, and noise.
+`0.3.22` is a benchmark recall release. It promotes maintenance-context
+recovery to the current expanded public-suite baseline: **66.0% recall / 51.1%
+token precision** across 108 scored public cases.
+`0.3.21` established the prior honest baseline at **57.0% recall / 50.6% token precision**. The new result clears the 65% recall target while keeping token
+precision above the 51% release floor; remaining risk is config/build recall and NestJS token precision. Result: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md).
 
-## Before vs After
+## Core Workflow
 
-Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
+### 1. Route
 
-```text
-Task: fix auth token expiry
+Use the read-only router when you want quick orientation without writing files:
 
-Agent:
-- searches for auth files
-- opens nearby middleware and config
-- may miss related tests
-- spends early turns building a repo map
+```bash
+agentpack route --task "fix auth token expiry"
 ```
 
-With AgentPack:
+### 2. Pack
 
 ```bash
-agentpack route --task "fix auth token expiry"
+agentpack task set "fix auth token expiry"
+agentpack pack --task auto
 ```
 
-```text
-Task:
-fix auth token expiry
+AgentPack writes `.agentpack/context.md` with selected files, omitted-file
+receipts, task freshness, token stats, and suggested checks.
+
+### 3. Agent Acts
+
+Point the agent at the pack or use MCP tools. Agent still verifies code before
+editing; AgentPack is map, not correctness proof.
+
+### 4. Benchmark Captures Miss
 
-Relevant files:
-- tests/test_auth.py
-- src/app/auth.py
-- src/app/users.py
+After a task, capture the files that actually changed:
 
-Suggested commands:
-- pytest tests/test_auth.py -q
+```bash
+agentpack benchmark capture --since main --task "fix auth token expiry"
+agentpack benchmark --misses
 ```
 
+Miss diagnostics show whether a required file was ignored, scored too low,
+ranked but cut by budget, or absent from scan.
+
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
-- **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
-- **Rendered-token accounting and reserve buckets**: budgets against actual markdown while protecting changed files, tests, docs, and dependencies.
-- **Execution state**: optional task state files and git-derived fallback status show whether work is planned, in progress, blocked, done, committed, or committed but not pushed.
-- **Thread-scoped context**: explicit `--thread <id>` or `--thread auto` isolates task/context files for multiple agents in one repo and warns on same-branch file overlap.
-- **Task router**: MCP and CLI surfaces route a task to relevant files, scoped rules, installed skills, suggested commands, and safety warnings without executing skills automatically.
-- **Reversible registry and learning layer**: retrieves packed context by block ID, writes developer lessons, and feeds bounded selected-file miss feedback into future ranking.
-- **Runtime scorecard and output compression**: `perf --history` tracks activity, while `compress-output` preserves failures, paths, diffs, and search hits from noisy logs.
-- **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
-- **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
+- **Route**: read-only task map with relevant files, tests, rules, skills, commands, and warnings.
+- **Pack**: budgeted context with `full`, `diff`, `symbols`, `skeleton`, or `summary` file views.
+- **Act**: CLI, markdown, MCP, and agent integrations for Claude Code, Codex, Cursor, Windsurf, Antigravity, and generic agents.
+- **Benchmark**: expected-file recall, token precision, miss diagnostics, public commit suites, and E2E A/B reports.
+- **Local**: no cloud indexing, embeddings, or API calls for scan, summarize, rank, pack, stats, or benchmark.
 
 ## Benchmark Proof
 
-Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and MarkupSafe, scored against files actually changed by each commit.
+Current local release-candidate table: expanded public-suite historical commits
+across Python, TypeScript, Go, Java, and monorepo repos, scored against files
+actually changed by each commit.
 
 | Metric | Result |
 |---|---:|
-| Avg recall | 79.2% |
-| Avg token precision | 51.2% |
-| Pack p50 | 1,450 tokens |
-| Pack p95 | 3,805 tokens |
+| Scored cases | 108 |
+| Avg recall | 66.0% |
+| Avg token precision | 51.1% |
+| Pack p50 | 315 tokens |
+| Pack p95 | 1,150 tokens |
+
+Full local table: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md). This is scoped benchmark evidence, not a universal quality claim.
+The latest published v0.3.20 table remains available at
+[`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md).
+Reproduce the expanded public suite:
 
-Full table: [`benchmarks/results/2026-05-27-public.md`](benchmarks/results/2026-05-27-public.md). This is public smoke proof, not a claim of universal ranking quality; expand cases for your own repo with `agentpack benchmark capture`.
+```bash
+agentpack benchmark --public-suite --reproduce v0.3.20
+```
+
+Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
+
+### Release Benchmark Gate
+
+The current local release-candidate result clears the target: **66.0% recall**
+and **51.1% token precision**. The target should continue to be measured on the
+same 100+ public historical-commit suite, with per-language slices published so
+aggregate gains are not hiding TypeScript, Go, Java, or monorepo regressions.
+
+Decision gate for the next public table:
+
+- full-suite recall is at least 65.0%
+- full-suite token precision is at least 51.0%
+- no major language or task slice loses more than 2 recall points
+- Vite/TypeScript, Gin/Go, Click/Python, and NestJS monorepo misses are reported separately
+- any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
+  token cost, and time-to-first-correct-file
+
+## Trust
+
+AgentPack is MIT licensed, local-first, and uses PyPI Trusted Publishing plus
+npm provenance for release artifacts. See [`SECURITY.md`](SECURITY.md),
+[`docs/privacy.md`](docs/privacy.md), [`docs/threat-model.md`](docs/threat-model.md),
+and [`docs/data-flow.md`](docs/data-flow.md).
 
 ## Use Cases
 
-- [Claude Code context engine](docs/claude-code-context-engine.md)
-- [MCP context engine](docs/mcp-context-engine.md)
-- [Cursor context packing](docs/cursor-context-packing.md)
-- [AI coding agent context packing](docs/ai-coding-agent-context.md)
-- [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
-- [How AgentPack works](docs/how-agentpack-works.md)
-- [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
-- [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
-- [Docs index](docs/index.md)
+Start with the [docs index](docs/index.md), or jump to guides for
+[Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
+[Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
+[AI coding agent context](docs/ai-coding-agent-context.md), and [how AgentPack works](docs/how-agentpack-works.md).
 
 ## Install
 
@@ -155,7 +198,7 @@ pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+Requires Python 3.10+ and is tested on Python 3.10-3.14. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
 
 Install `pipx` first if needed:
 
@@ -274,7 +317,7 @@ budget = 8000
 output = ".agentpack/context.md"
 ```
 
-Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use `minimal`, `balanced`, or `deep` when you want progressively more file content in the generated pack.
+Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use the default `balanced` mode for normal agent work and benchmark claims. Use `deep` when the task needs broader docs and source context.
 
 Use `.agentignore` to remove generated output, vendored code, large exports, or files that repeatedly appear as ranking noise. AgentPack imports obvious generated/noisy entries from gitignore sources during init, but repository-specific outputs should still be added by hand.
 
@@ -391,18 +434,6 @@ THREAD=codex-local make context-thread
 AGENTPACK_THREAD_ID=codex-local make context-thread
 ```
 
-## Benchmark Proof
-
-AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
-
-Use real repo evals instead of trusting compression numbers:
-
-```bash
-agentpack benchmark --release-gate
-```
-
-Current benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated tables under `benchmarks/results/`. Treat these as scoped evidence for the included cases, not a universal performance claim.
-
 ## What A Pack Contains
 
 Rendered packs are meant to be readable by humans and directly useful to agents. A typical pack includes:

{agentpack_cli-0.3.20 → agentpack_cli-0.3.22}/README.md

@@ -8,14 +8,21 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-**Local MCP context router for AI coding agents.**
+**Local context engine for AI coding agents.**
 
-Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
+AgentPack ranks relevant repository files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools, CI jobs, and markdown-based LLM workflows.
 
-AgentPack gives them a ranked map of likely relevant files, tests, rules, and skills for each task. It analyzes your repo locally and packages compact context for CLI and MCP workflows.
+It runs local/offline repo analysis, compresses selected files into a token budget, and keeps context fresh through CLI commands, MCP tools, hooks, and agent integrations. Use it when an AI coding agent needs a ranked starting map instead of burning tool calls rediscovering your repo.
 
-How it works: AgentPack compresses repo context into ranked packs, caches scans/summaries/pack metadata for fast refreshes, and retrieves exact file or symbol blocks later when an agent needs more detail. Rendered packs also put stable instructions before volatile task, timestamp, git, and file sections so provider prompt-prefix caches can reuse the front of repeated refreshes. No cloud indexing, embeddings, or API calls are required for scan, summarize, rank, pack, stats, or benchmark. See [How AgentPack works](docs/how-agentpack-works.md) for the full scan, rank, compress, cache, retrieve, route, and benchmark flow.
-Try the read-only task router without writing context files:
+AgentPack is a context preparation tool, not a coding agent.
+
+One workflow matters:
+
+```text
+route -> pack -> agent acts -> benchmark captures miss
+```
+
+First route the task to likely files, tests, rules, and skills:
 
 ```bash
 pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
@@ -23,89 +30,119 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
 
 ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
 
-> **Status: alpha (v0.3.20).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
+> **Status: alpha (v0.3.22).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. API may change before 1.0.
 >
 > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. `cmd.exe` and bare Git setups are not a supported path yet.
 >
 > **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
 
-## What's New in 0.3.20
+## What's New in 0.3.22
 
-`0.3.20` adds a dedicated "How AgentPack works" guide for scan, rank, compress,
-cache, retrieve, route, stable-prefix caching, and skill keyword quality. It
-also polishes the local dashboard and expands skill-routing benchmark guidance
-for `expected_skills`, `avoid_skills`, recall, precision, MRR, and noise.
+`0.3.22` is a benchmark recall release. It promotes maintenance-context
+recovery to the current expanded public-suite baseline: **66.0% recall / 51.1%
+token precision** across 108 scored public cases.
+`0.3.21` established the prior honest baseline at **57.0% recall / 50.6% token precision**. The new result clears the 65% recall target while keeping token
+precision above the 51% release floor; remaining risk is config/build recall and NestJS token precision. Result: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md).
 
-## Before vs After
+## Core Workflow
 
-Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
+### 1. Route
 
-```text
-Task: fix auth token expiry
+Use the read-only router when you want quick orientation without writing files:
 
-Agent:
-- searches for auth files
-- opens nearby middleware and config
-- may miss related tests
-- spends early turns building a repo map
+```bash
+agentpack route --task "fix auth token expiry"
 ```
 
-With AgentPack:
+### 2. Pack
 
 ```bash
-agentpack route --task "fix auth token expiry"
+agentpack task set "fix auth token expiry"
+agentpack pack --task auto
 ```
 
-```text
-Task:
-fix auth token expiry
+AgentPack writes `.agentpack/context.md` with selected files, omitted-file
+receipts, task freshness, token stats, and suggested checks.
+
+### 3. Agent Acts
+
+Point the agent at the pack or use MCP tools. Agent still verifies code before
+editing; AgentPack is map, not correctness proof.
+
+### 4. Benchmark Captures Miss
 
-Relevant files:
-- tests/test_auth.py
-- src/app/auth.py
-- src/app/users.py
+After a task, capture the files that actually changed:
 
-Suggested commands:
-- pytest tests/test_auth.py -q
+```bash
+agentpack benchmark capture --since main --task "fix auth token expiry"
+agentpack benchmark --misses
 ```
 
+Miss diagnostics show whether a required file was ignored, scored too low,
+ranked but cut by budget, or absent from scan.
+
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
-- **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
-- **Rendered-token accounting and reserve buckets**: budgets against actual markdown while protecting changed files, tests, docs, and dependencies.
-- **Execution state**: optional task state files and git-derived fallback status show whether work is planned, in progress, blocked, done, committed, or committed but not pushed.
-- **Thread-scoped context**: explicit `--thread <id>` or `--thread auto` isolates task/context files for multiple agents in one repo and warns on same-branch file overlap.
-- **Task router**: MCP and CLI surfaces route a task to relevant files, scoped rules, installed skills, suggested commands, and safety warnings without executing skills automatically.
-- **Reversible registry and learning layer**: retrieves packed context by block ID, writes developer lessons, and feeds bounded selected-file miss feedback into future ranking.
-- **Runtime scorecard and output compression**: `perf --history` tracks activity, while `compress-output` preserves failures, paths, diffs, and search hits from noisy logs.
-- **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
-- **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
+- **Route**: read-only task map with relevant files, tests, rules, skills, commands, and warnings.
+- **Pack**: budgeted context with `full`, `diff`, `symbols`, `skeleton`, or `summary` file views.
+- **Act**: CLI, markdown, MCP, and agent integrations for Claude Code, Codex, Cursor, Windsurf, Antigravity, and generic agents.
+- **Benchmark**: expected-file recall, token precision, miss diagnostics, public commit suites, and E2E A/B reports.
+- **Local**: no cloud indexing, embeddings, or API calls for scan, summarize, rank, pack, stats, or benchmark.
 
 ## Benchmark Proof
 
-Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and MarkupSafe, scored against files actually changed by each commit.
+Current local release-candidate table: expanded public-suite historical commits
+across Python, TypeScript, Go, Java, and monorepo repos, scored against files
+actually changed by each commit.
 
 | Metric | Result |
 |---|---:|
-| Avg recall | 79.2% |
-| Avg token precision | 51.2% |
-| Pack p50 | 1,450 tokens |
-| Pack p95 | 3,805 tokens |
+| Scored cases | 108 |
+| Avg recall | 66.0% |
+| Avg token precision | 51.1% |
+| Pack p50 | 315 tokens |
+| Pack p95 | 1,150 tokens |
+
+Full local table: [`benchmarks/results/2026-06-13-public.md`](benchmarks/results/2026-06-13-public.md). This is scoped benchmark evidence, not a universal quality claim.
+The latest published v0.3.20 table remains available at
+[`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md).
+Reproduce the expanded public suite:
 
-Full table: [`benchmarks/results/2026-05-27-public.md`](benchmarks/results/2026-05-27-public.md). This is public smoke proof, not a claim of universal ranking quality; expand cases for your own repo with `agentpack benchmark capture`.
+```bash
+agentpack benchmark --public-suite --reproduce v0.3.20
+```
+
+Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
+
+### Release Benchmark Gate
+
+The current local release-candidate result clears the target: **66.0% recall**
+and **51.1% token precision**. The target should continue to be measured on the
+same 100+ public historical-commit suite, with per-language slices published so
+aggregate gains are not hiding TypeScript, Go, Java, or monorepo regressions.
+
+Decision gate for the next public table:
+
+- full-suite recall is at least 65.0%
+- full-suite token precision is at least 51.0%
+- no major language or task slice loses more than 2 recall points
+- Vite/TypeScript, Gin/Go, Click/Python, and NestJS monorepo misses are reported separately
+- any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
+  token cost, and time-to-first-correct-file
+
+## Trust
+
+AgentPack is MIT licensed, local-first, and uses PyPI Trusted Publishing plus
+npm provenance for release artifacts. See [`SECURITY.md`](SECURITY.md),
+[`docs/privacy.md`](docs/privacy.md), [`docs/threat-model.md`](docs/threat-model.md),
+and [`docs/data-flow.md`](docs/data-flow.md).
 
 ## Use Cases
 
-- [Claude Code context engine](docs/claude-code-context-engine.md)
-- [MCP context engine](docs/mcp-context-engine.md)
-- [Cursor context packing](docs/cursor-context-packing.md)
-- [AI coding agent context packing](docs/ai-coding-agent-context.md)
-- [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
-- [How AgentPack works](docs/how-agentpack-works.md)
-- [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
-- [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
-- [Docs index](docs/index.md)
+Start with the [docs index](docs/index.md), or jump to guides for
+[Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
+[Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
+[AI coding agent context](docs/ai-coding-agent-context.md), and [how AgentPack works](docs/how-agentpack-works.md).
 
 ## Install
 
@@ -114,7 +151,7 @@ pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+Requires Python 3.10+ and is tested on Python 3.10-3.14. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
 
 Install `pipx` first if needed:
 
@@ -233,7 +270,7 @@ budget = 8000
 output = ".agentpack/context.md"
 ```
 
-Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use `minimal`, `balanced`, or `deep` when you want progressively more file content in the generated pack.
+Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use the default `balanced` mode for normal agent work and benchmark claims. Use `deep` when the task needs broader docs and source context.
 
 Use `.agentignore` to remove generated output, vendored code, large exports, or files that repeatedly appear as ranking noise. AgentPack imports obvious generated/noisy entries from gitignore sources during init, but repository-specific outputs should still be added by hand.
 
@@ -350,18 +387,6 @@ THREAD=codex-local make context-thread
 AGENTPACK_THREAD_ID=codex-local make context-thread
 ```
 
-## Benchmark Proof
-
-AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
-
-Use real repo evals instead of trusting compression numbers:
-
-```bash
-agentpack benchmark --release-gate
-```
-
-Current benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated tables under `benchmarks/results/`. Treat these as scoped evidence for the included cases, not a universal performance claim.
-
 ## What A Pack Contains
 
 Rendered packs are meant to be readable by humans and directly useful to agents. A typical pack includes:

{agentpack_cli-0.3.20 → agentpack_cli-0.3.22}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.20"
-description = "Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents."
+version = "0.3.22"
+description = "Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows."
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
-keywords = ["ai-coding-agents", "coding-agent", "ai-agent", "claude-code", "developer-tools", "repo-analysis", "repo-context", "context-engine", "mcp-context-engine", "context-router", "context-packing", "prompt-context", "reduce-token-usage", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
+keywords = ["ai-coding-agents", "coding-agent", "ai-agent", "claude-code", "developer-tools", "repo-analysis", "repo-context", "context-engine", "mcp-context-engine", "context-router", "context-packing", "prompt-context", "task-focused-context", "reduce-token-usage", "local-first", "repo-map", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -14,6 +14,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Topic :: Software Development :: Build Tools",
 ]
@@ -28,6 +29,13 @@ dependencies = [
   "tomli>=2.0.0; python_version < '3.11'"
 ]
 
+[project.urls]
+Homepage = "https://github.com/vishal2612200/agentpack"
+Documentation = "https://vishal2612200.github.io/agentpack/"
+Repository = "https://github.com/vishal2612200/agentpack"
+Issues = "https://github.com/vishal2612200/agentpack/issues"
+Changelog = "https://github.com/vishal2612200/agentpack/blob/main/CHANGELOG.md"
+
 [project.scripts]
 agentpack = "agentpack.cli:app"
 

{agentpack_cli-0.3.20 → agentpack_cli-0.3.22}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.20"
+__version__ = "0.3.22"