agentpack-cli 0.1.29__tar.gz → 0.2.0__tar.gz

{agentpack_cli-0.1.29 → agentpack_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.1.29
+Version: 0.2.0
 Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
 License: MIT
 License-File: LICENSE
@@ -44,156 +44,130 @@ 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)
 
-> **Status: alpha (v0.1.29).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.2.0).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
-**Task-aware context packing for AI coding agents.**
+**Local context engine for AI coding agents.**
 
-AgentPack scans a repository, ranks files for the task you are working on, and writes a compact markdown context pack for Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, or any LLM workflow.
+AgentPack builds task-focused context packs for Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, and any LLM workflow that can read markdown. It scans your repo locally, ranks files for the task, compresses the result into a token budget, and keeps the pack fresh through CLI commands, MCP tools, hooks, and agent integrations.
 
-It is useful when the repo is too large to paste, but you still want the agent to start with more than a blank slate.
+AgentPack is useful when a repo is too large to paste, but a blank agent session wastes time rediscovering the same code structure. It is a context preparation tool, not a coding agent.
 
-**What it is**
-- A local CLI for building task-focused context packs
-- A summary cache, import graph, ranking engine, and token-budget selector
-- Optional integrations for popular coding agents
-- An eval harness for measuring whether selected files match files you actually changed
+## Contents
 
-**What it is not**
-- Not a coding agent
-- Not a semantic code search engine
-- Not a replacement for manual inspection on high-stakes changes
-- Not yet proven across a large public benchmark suite
+- [Features](#features)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Quality Bar](#quality-bar)
+- [Debugging Selection](#debugging-selection)
+- [Supported Integrations](#supported-integrations)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [Known Limitations](#known-limitations)
+- [Roadmap](#roadmap)
+- [Development](#development)
 
----
-
-## The problem
-
-Every time you start a task with an AI coding agent, it has no idea what's in your repo. It either:
+## Features
 
-1. **Reads files on demand** (Claude Code, Cursor, Windsurf) — dozens of tool calls, paying exploration cost every session, every turn, forever.
-2. **Gets the whole repo dumped in** (repomix, gitingest) — 50k–500k tokens of noise, most of it irrelevant to the task at hand.
-3. **Gets nothing** — you hand-copy the 5 files you think matter and hope you got it right.
+- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, and repo history.
+- **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
+- **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **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.
 
-None of these scale. On a 200-file codebase, option 1 wastes 5–10 turns just orienting. Option 2 degrades output quality (LLMs perform worse on long noisy context). Option 3 misses critical dependencies and configs constantly.
+## Install
 
-**The root cause:** agents don't know *what's relevant to your current task* without doing the work to figure that out — which costs tokens, time, and money on every session.
+```bash
+pip install agentpack-cli
+agentpack --version
+```
 
----
+Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
 
-## The solution
+JavaScript-heavy teams can install the npm wrapper:
 
-AgentPack solves this with a one-time offline analysis pass:
+```bash
+npm install -g @vishal2612200/agentpack
+agentpack --version
+```
 
-1. **Scans your repo once** — builds a summary cache of every file (signatures, imports, responsibilities). No API calls. Takes a few seconds.
-2. **On each task** — uses git diff, import graph traversal, keyword/concept expansion, implementation-role boosts, and cross-layer relatedness to rank every file.
-3. **Packs a tight context document** — changed files get full content, large changed files get relevant symbol bodies, dependencies and likely implementation files get summaries, everything else gets dropped.
-4. **Explains pack quality** — noisy-pack diagnostics, score receipts, token-precision metrics, and benchmark miss reports show when the pack is broad or missing expected files.
-5. **Stays current** — auto-repacks silently on commit, so next session starts fresh.
+The npm package is a Node launcher around the Python implementation. It installs the matching `agentpack-cli` package into a per-version virtual environment on first run.
 
-The result: your agent starts with a focused map of the relevant code. It should reduce blind exploration, not replace the agent's own file reads or your judgment.
+## Quickstart
 
 ```bash
-pip install agentpack-cli
-
-# Show the fastest path for your repo
-agentpack quickstart --task "fix auth token expiry"
-
-# One-time setup per project
 cd your-project
-agentpack init             # creates config/session/task.md + detected agent integration
-
-# Every terminal session
-agentpack watch            # keeps context fresh automatically — that's it
+agentpack init --agent codex       # or claude, cursor, windsurf, antigravity
+agentpack pack --task "fix auth token expiry"
 ```
 
-Then open Claude Code / Cursor / Windsurf / Codex / Antigravity and write your task normally. AgentPack keeps `.agentpack/context.md` current.
+This creates `.agentpack/` state, installs the requested agent integration, generates a ranked context pack, and writes the adapter output for that agent. For active local work, keep context fresh with:
+
+```bash
+agentpack watch
+```
 
-For power users who want background repacking on every commit and cd:
+For a guided setup that explains each next step:
 
 ```bash
-# Advanced: global automation (opt-in repos only — never touches repos without .agentpack/)
-agentpack global-install --dry-run   # preview first
-agentpack global-install
+agentpack quickstart --task "fix auth token expiry"
 ```
 
-Supported agents: **Claude Code**, **Cursor**, **Windsurf**, **Codex**, **Antigravity** (Google), or any LLM that can read markdown.
+## Project Scope
 
----
+**AgentPack is:**
+
+- A local context engine for building task-focused packs for AI coding agents.
+- A CLI, MCP server, hook runner, and integration layer.
+- A summary cache, import graph, ranking engine, semantic repo map, and token-budget selector.
+- An eval harness for measuring whether selected files match files you actually changed.
 
-## What to expect
+**AgentPack is not:**
 
-AgentPack's strongest value is repeatable orientation: it gives the agent a compact first-pass map before tool calls begin.
+- A coding agent.
+- A hosted service.
+- A semantic code search engine.
+- A replacement for normal source inspection on critical changes.
+- Proven across a large public benchmark suite yet.
 
-Typical results on large repos:
+## Quality Bar
+
+AgentPack is best treated as a **ranked starting map**. It should reduce repeated orientation work, but the agent and reviewer still own correctness.
 
 | Signal | What good looks like |
 |---|---|
-| Token reduction | 90-99% smaller than raw repo text |
+| Token reduction | 90-99% smaller than raw repo text on large repos |
 | Pack size | Usually 8k-25k tokens for a specific task |
-| Pack time | Seconds on warm cache; first summarize pass is slower |
-| Recall | Should be high for files you later edit; validate with `agentpack benchmark` |
-| Precision | Often modest; summaries are cheap but can still add noise |
-
-The compression number is easy to verify, but it is not the same as usefulness. The important question is: **did AgentPack include the files you actually needed?**
+| Pack time | Seconds on a warm cache; first summarize pass is slower |
+| Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
+| Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
+| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
 
-Use the built-in eval flow:
+Use real repo evals instead of trusting compression numbers:
 
 ```bash
 agentpack benchmark --init
-# add real historical tasks and files you actually changed
+# add historical tasks and files actually changed
 agentpack benchmark --compare --misses
+agentpack benchmark --results-template
 ```
 
-For source checkouts, there is also a small smoke suite:
+## Debugging Selection
+
+When AgentPack misses a file, the next command should explain the miss:
 
 ```bash
-agentpack benchmark --sample-fixtures --misses
+agentpack benchmark --misses
+agentpack explain --task "fix billing webhook" --file lib/billing/webhook.ts
+agentpack explain --task "fix billing webhook" --omitted
+agentpack explain --task "fix billing webhook" --budget-plan
 ```
 
-This runs FastAPI, Next.js, and mixed Python/TypeScript fixture tasks. It is a sanity check, not a substitute for real repo evals.
-
-### Current quality bar
-
-AgentPack is best described as a **map, not a compass**. It is already good at token reduction, changed-file inclusion, related tests, imports, configs, and common concepts like auth/cache/rate limiting. Recent ranking work also improves full-stack tasks by pulling service/controller/schema/handler files when UI routes or pages match the same domain.
-
-Known weak spot: recall can still be low on unfamiliar product domains or cross-language flows. Use `benchmark --misses` and `agentpack explain` when an expected file is absent. Those commands show whether the miss was caused by ignore rules, low score, summary floor, budget cutoff, or missing task signal.
-
-### Observed author-run numbers
+`benchmark --misses` reports each expected file that was not selected, including whether it was ignored, scored too low, excluded by summary floor, cut by budget, or absent from the scan. `explain --file` shows the exact score signals for one file. `explain --budget-plan` shows how the token budget was spent across full, diff, symbols, skeleton, and summary modes.
 
-These are local author-session numbers, included as anecdotal context rather than a benchmark claim.
-
-#### Token Compression
-
-| Metric | Value |
-|--------|-------|
-| Sessions | 21 |
-| Avg compression | 99.3% |
-| Min / Max | 98.7% → 99.9% |
-| Total raw (theoretical) | 116.9M tokens |
-| Total packed (actual) | 683K tokens |
-
-Per session: ~4.1M raw repo → ~35K packed context.
-
-#### Cost (Sonnet 4.6, input tokens only)
-
-| Scenario | Cost |
-|----------|------|
-| Full repo dumped each run | ~$350 |
-| With AgentPack | ~$2.05 |
-| **Realistic** (10% manual cherry-pick baseline) | **~$33 saved** |
-
-> Honest note: raw_tokens = full repo estimate. Real savings depend on how much context you'd pass manually. Compression ratio (99%+) is verifiable; dollar figure is scenario-dependent.
-
-#### Quality Signal
-
-- 42 commits in 7 days (~6/day) vs 4.9/day before
-- Shift from single-file fixes → multi-system coordinated fixes
-- AgentPack provides dependent files + callers in context → fixes root cause, not symptom
-- Correlation observed, causation not isolated
-
----
+This is the core reliability loop: pack, measure recall, inspect misses, then tune task wording, `.agentignore`, or scoring weights.
 
 ## When it helps
 
@@ -217,9 +191,9 @@ These are repo dumpers. They pack a repo (or subset) into a file and hand it to
 
 What they don't do: decide what's relevant to *your task*. You specify the scope — files, globs, directories — and they package your decision. If you want "only the files that matter for fixing this auth bug", you have to figure that out yourself. On a 200-file repo, that's 80% of the work.
 
-AgentPack does that selection automatically. You give it a task string; it uses git diff, import graph traversal, and keyword scoring to rank every file, then cuts to fit your token budget. You don't touch globs.
+AgentPack does that selection automatically. You give it a task string; it uses task classification, git diff, import graph traversal, semantic summaries, and keyword scoring to rank every file, then cuts to fit your token budget. You don't touch globs.
 
-The other difference: all three pack uniformly (full content or nothing). AgentPack is selective by inclusion mode — changed files get full content, unchanged deps get summaries, unrelated files get dropped. A repomix dump of a 50k-token repo stays 50k tokens. An agentpack of the same repo for a specific task is typically 8k–20k.
+The other difference: all three pack uniformly (full content or nothing). AgentPack is selective by inclusion mode — changed files can be full source, relevant diff hunks, symbol bodies, interface skeletons, or summaries; unrelated files get dropped. A repomix dump of a 50k-token repo stays 50k tokens. An agentpack of the same repo for a specific task is typically 8k–20k.
 
 **Use repomix/gitingest if:** you want to dump an entire small repo into a chat UI for a one-shot question. Zero setup, great for "explain this codebase."
 
@@ -241,7 +215,7 @@ These tools have native file access via tool calls. Claude reads exactly the fil
 
 AgentPack's value here is different: `agentpack init --agent <x>` configures your agent to read or inject a ranked context pack and auto-repack when the repo changes. On large repos where tool-call exploration piles up across turns, this front-loads the cost once instead of paying per-turn.
 
-### Where agentpack genuinely wins
+### Where AgentPack Wins
 
 | Scenario | repomix | gitingest | code2prompt | aider | agentpack |
 |---|---|---|---|---|---|
@@ -250,6 +224,7 @@ AgentPack's value here is different: `agentpack init --agent <x>` configures you
 | Auto task inference from git | ✗ | ✗ | ✗ | partial | ✓ |
 | Relevance ranking by task | ✗ | ✗ | ✗ | ✗ | ✓ |
 | Import graph traversal | ✗ | ✗ | ✗ | ✓ | ✓ |
+| Monorepo workspace hints | ✗ | ✗ | ✗ | manual | ✓ |
 | Token budget enforcement | manual | manual | manual | ✓ | ✓ |
 | Cursor / Windsurf / Codex / Antigravity install | ✗ | ✗ | ✗ | ✗ | ✓ |
 | Zero API calls | ✓ | ✓ | ✓ | ✗ | ✓ |
@@ -258,64 +233,17 @@ AgentPack's value here is different: `agentpack init --agent <x>` configures you
 
 _*`--agent generic` outputs standard markdown. Claude adapter has richer instructions._
 
-### What agentpack does NOT do well
+### What AgentPack Does Not Do Well
 
 - **Interactive sessions on small repos**: if your whole repo is <20k tokens, a simple repo dump may be enough
 - **One-shot public repo questions**: gitingest's "replace hub with ingest" is faster for quick read-only exploration
 - **Guaranteed source-of-truth selection**: AgentPack ranks likely files; it can miss task-critical files. Use `agentpack benchmark --misses`, `agentpack explain`, and normal `rg`/agent file reads for correctness.
 - **Deep semantic understanding**: keyword/concept scoring, imports, symbols, and path roles help, but they are not an LLM-level code understanding system
+- **Public proof without real cases**: bundled fixtures are smoke tests. Strong claims need historical tasks from real repos and published results.
 
 ---
 
-## Install
-
-```bash
-pip install agentpack-cli
-```
-
-Requires Python 3.10+.
-
-> **PyPI note:** The package is `agentpack-cli` (the name `agentpack` was already taken). The CLI command is still `agentpack`.
-
-### npm wrapper
-
-AgentPack can also be installed from npm:
-
-```bash
-npm install -g @vishal2612200/agentpack
-agentpack --version
-```
-
-The npm package is a thin Node.js wrapper around the Python CLI. It requires Node.js 18+ and Python 3.10+, then installs the matching `agentpack-cli` PyPI package into a per-version virtual environment on first run. This keeps the implementation single-source while giving JavaScript-heavy teams a familiar install path.
-
----
-
-## Start Once, Then Work Normally
-
-For a guided two-minute path in any repo:
-
-```bash
-agentpack quickstart --task "fix auth token expiry"
-```
-
-It shows the exact commands to initialize, set task text, generate a first pack, inspect stats, start watch mode, and scaffold a small benchmark file for your own tasks.
-
-The full workflow:
-
-```bash
-# One-time project setup
-agentpack init             # creates config/session/task.md + detected agent integration
-
-# Every terminal session — just one command
-agentpack watch            # auto-resumes session, refreshes context on file/task changes
-```
-
-Then open Claude Code / Cursor / Codex and write your coding task normally.
-
-- AgentPack keeps `.agentpack/context.md` and `.agentpack/context.claude.md` fresh while `watch` is running.
-- To change the task: edit `.agentpack/task.md` directly, or tell Claude — it updates the file itself. `watch` picks up the change automatically.
-
-### Agent integration matrix
+## Supported Integrations
 
 | Agent | Automation level | Method |
 |---|---|---|
@@ -326,7 +254,7 @@ Then open Claude Code / Cursor / Codex and write your coding task normally.
 | Antigravity | Medium | `init` writes `GEMINI.md`, VS Code task + git hooks |
 | Generic | Basic | `watch` mode + read `context.md` |
 
-### Honest limitations
+### Integration limitations
 
 - AgentPack cannot intercept prompts inside IDEs — Cursor/Windsurf rely on rules being followed.
 - Claude wrapper (`agentpack claude`) is the most deterministic integration.
@@ -335,29 +263,6 @@ Then open Claude Code / Cursor / Codex and write your coding task normally.
 
 ---
 
-## Quickstart
-
-```bash
-pip install agentpack-cli
-cd your-project
-agentpack init             # one-time setup: config/session/task.md + detected agent integration
-agentpack watch            # in another terminal — keeps context fresh automatically
-```
-
-Then open your agent and write your task normally.
-
-**Power users (global automation):**
-
-```bash
-agentpack global-install --dry-run   # preview
-agentpack global-install             # apply
-source ~/.zshrc
-```
-
-Then opt each project in: `cd your-project && agentpack init`. After that repo hooks or shell hooks keep context fresh, and Claude Code gets prompt-time context hints — no manual steps.
-
----
-
 ## Agent setup
 
 `agentpack init` is the normal one-command project setup. It creates `.agentpack/` state and installs the detected agent integration. Re-run it any time; integration writes are idempotent and never clobber unrelated config.
@@ -448,6 +353,7 @@ Builds an offline summary of every file — no API calls, no network. Each summa
 - What the file does and its responsibility
 - Exported classes, functions, signatures with extracted bodies
 - Import dependencies
+- Likely side effects, public API shape, error paths, and test hints
 
 Summaries are stored in `.agentpack/cache/` keyed by file hash. Only changed files are re-summarized on the next pack.
 
@@ -473,7 +379,7 @@ Token counts use tiktoken `cl100k_base` — a close approximation to Claude's ac
 
 ## CI/CD: pack per PR
 
-### agentpack's own CI
+### AgentPack's Own CI
 
 agentpack uses two workflows:
 
@@ -527,6 +433,34 @@ Reviewers download the artifact and open it in their agent of choice. No repo cl
 
 ## Commands
 
+Most users only need four commands:
+
+```bash
+agentpack init --agent codex
+agentpack pack --task "describe the change"
+agentpack watch
+agentpack doctor --agent all
+```
+
+Command map:
+
+| Command | Use when |
+|---|---|
+| `agentpack init` | Set up `.agentpack/` and install one agent integration for a repo |
+| `agentpack install` | Refresh or add an agent integration without changing project state |
+| `agentpack repair` | Restore missing or drifted integration files |
+| `agentpack pack` | Generate a ranked context pack for one task |
+| `agentpack watch` | Keep the context pack fresh while you work |
+| `agentpack doctor` | Audit hooks, agent files, CLI path, and repo health |
+| `agentpack explain` | Understand why a file was selected or omitted |
+| `agentpack benchmark` | Measure recall, precision, and misses against real tasks |
+| `agentpack tune` | Suggest fixes from recent pack metrics and benchmark misses |
+| `agentpack status` | Inspect current pack freshness and metadata |
+| `agentpack diff` | Show what changed between context snapshots |
+| `agentpack monitor` | Review recent pack runs and quality signals |
+| `agentpack scan` | Inspect packable, ignored, binary, and largest files |
+| `agentpack global-install` | Install opt-in global hooks for initialized repos |
+
 ### `agentpack global-install`
 
 Install once — works in every repo from that point on. The recommended first step.
@@ -583,13 +517,15 @@ Diagnose your agentpack installation — checks CLI, git template hooks, git con
 
 ```bash
 agentpack doctor
+agentpack doctor --agent codex
+agentpack doctor --agent all
 ```
 
 Example output:
 
 ```
 CLI
-  ✓ agentpack found at /usr/local/bin/agentpack (0.1.0)
+  ✓ agentpack found at /usr/local/bin/agentpack (0.1.x)
 
 Git template hooks (~/.git-templates/hooks/)
   ✓ post-commit
@@ -621,6 +557,7 @@ Some checks failed. Run the suggested commands above to fix.
 ```
 
 The new checks in `doctor`:
+- **Agent matrix audit**: `--agent all` checks Claude, Cursor, Windsurf, Codex, Antigravity, and Generic in one pass, including Codex `.codex/hooks.json` lifecycle hooks.
 - **Local vs global hooks**: warns when Claude hooks are only in the per-project `.claude/settings.json` — context won't auto-inject in other repos
 - **Slash command presence**: checks both local (`.claude/commands/`) and global (`~/.claude/commands/`) installations
 - **Source checkout mismatch**: warns when you're inside an AgentPack source checkout but the `agentpack` executable imports the installed site-packages copy. Use `PYTHONPATH=src python -m agentpack.cli ...` or `pip install -e .` for local development.
@@ -661,7 +598,7 @@ Also installs the detected agent integration:
 
 ### `agentpack install`
 
-Repair or reconfigure agent-specific files without reinitializing project state.
+Install or refresh one agent integration without reinitializing project state.
 
 ```bash
 agentpack install                      # auto-detect IDE
@@ -676,6 +613,18 @@ All installs are idempotent — safe to re-run, merge with existing config, neve
 
 ---
 
+### `agentpack repair`
+
+Repair missing or drifted integration files. It uses the same installer contract as `init` and `install`, but is named for the "make this repo healthy again" workflow.
+
+```bash
+agentpack repair                 # repair auto-detected agent
+agentpack repair --agent codex   # AGENTS.md + .codex/hooks.json + git hooks
+agentpack repair --agent all     # repair every supported integration
+```
+
+---
+
 ### `agentpack summarize`
 
 Build or refresh the offline summary cache. **No API calls, ever.**
@@ -696,6 +645,7 @@ Generate a context pack.
 ```bash
 agentpack pack --task "fix auth session bug"        # auto-detects your IDE
 agentpack pack --agent claude --task "fix auth bug" # explicit agent
+agentpack pack --workspace apps/web --task "fix web auth"
 
 # Only include changes since a git ref
 agentpack pack --task "review these changes" --since main
@@ -712,6 +662,7 @@ Options:
 | `--task` | `auto` | Task description, or `auto` to infer from git |
 | `--mode` | `balanced` | Budget mode: `minimal`, `balanced`, `deep` |
 | `--budget` | 0 (uses config default 25000) | Token budget |
+| `--workspace` | — | Restrict packing to a monorepo workspace and write `.agentpack/workspaces/<workspace>/context.md` |
 | `--since` | — | Only include files changed since this git ref |
 | `--session` | off | Re-pack on every file change (watch mode) |
 | `--refresh` | off | Force rebuild summaries before packing |
@@ -726,6 +677,18 @@ Options:
 
 `pack` also prints diagnostics when the pack looks noisy: very short task text, no changed files, mostly filename matches, mostly summaries, many symbol matches, weak summaries excluded by the score floor, or summaries excluded by the mode cap.
 
+AgentPack uses budget-aware compression when building context:
+
+| Include mode | Used for |
+|--------------|----------|
+| `full` | Small or highly relevant changed files |
+| `diff` | Large changed files where the edit hunk is more useful than the whole file |
+| `symbols` | Focused implementation bodies under budget pressure |
+| `skeleton` | Imports plus public class/function signatures |
+| `summary` | Lower-priority supporting files |
+
+This keeps unrelated dirty files from consuming the whole context budget while preserving changed-file recall.
+
 ---
 
 ### `agentpack quickstart`
@@ -742,18 +705,12 @@ agentpack quickstart --task "fix auth token expiry" --write
 
 ---
 
-### `agentpack session` _(removed)_
-
-Session management was removed in v0.1.12. `agentpack init` bootstraps the session automatically. Use `agentpack watch` to keep context current. To change the task, edit `.agentpack/task.md`.
-
----
-
 ### `agentpack watch`
 
 Watch for file and task changes, refresh context automatically.
 
 ```bash
-agentpack watch                        # uses session agent/mode if session active
+agentpack watch                        # refresh context on source/task changes
 agentpack watch --debounce 3.0         # wait 3s after last change before refresh
 ```
 
@@ -807,6 +764,10 @@ Register in Claude Code settings (`~/.claude/settings.json`):
 | `pack_context(task, mode, budget, max_tokens)` | Generate a ranked context pack for a task. Returns packed markdown, truncated to `max_tokens` (default 20,000). |
 | `get_context()` | Return the latest pre-built pack instantly (no repack). Prepends a freshness/staleness header so you know if it's stale. |
 | `refresh()` | Refresh using the current `task.md` or git-inferred task. |
+| `explain_file(path, task)` | Show score, inclusion mode, reasons, symbols, imports, and importers for one file. |
+| `get_related_files(path, depth)` | Return import-graph neighbours and related tests for a file. |
+| `get_delta_context(max_files)` | Return the latest selected-file delta plus top current selected files. Useful for cheap prompt-time refresh checks. |
+| `get_stats()` | Return latest pack stats, savings, selection quality, excluded files, and benchmark-style signals. |
 
 **Staleness detection:** `get_context()` compares the snapshot hash from when the pack was built against the current repo snapshot. If files changed since last pack, it prepends:
 ```
@@ -828,6 +789,7 @@ agentpack explain --task "fix auth session bug"
 agentpack explain --task auto
 agentpack explain --file src/auth/session.py   # per-file score breakdown
 agentpack explain --omitted                    # top-10 excluded files
+agentpack explain --budget-plan                # modes, token costs, value/token
 ```
 
 Per-file breakdown (`--file`):
@@ -849,7 +811,7 @@ src/auth/session.py
   symbols: create_session, revoke_session, validate_session
 ```
 
-Use `--omitted` to see what was left out and why. Use `--file` when a file you expected isn't showing up.
+Use `--omitted` to see what was left out and why. Use `--file` when a file you expected isn't showing up. Use `--budget-plan` to inspect how the compression planner spent the token budget.
 
 ---
 
@@ -861,9 +823,11 @@ Measure token efficiency, file selection quality, and speed across tasks.
 agentpack benchmark --task "fix auth token expiry"         # single task
 agentpack benchmark --task "fix auth bug" --compare        # compare minimal/balanced/deep
 agentpack benchmark --init                                 # scaffold .agentpack/benchmark.toml
+agentpack benchmark --results-template                     # scaffold publishable results note
 agentpack benchmark                                        # run all cases in benchmark.toml
 agentpack benchmark --sample-fixtures                      # source checkout demo evals
 agentpack benchmark --misses                               # explain expected-file misses
+agentpack benchmark --prove-targets                        # fail if recall/token precision targets miss
 ```
 
 Output per case:
@@ -904,6 +868,7 @@ Mode comparison: fix auth token expiry
 task = "fix auth token expiry"
 mode = "balanced"
 task_type = "backend-api"
+workspace = "apps/api" # optional, for monorepos
 expected_files = [
   "src/auth/token.py",
   "src/auth/session.py",
@@ -917,6 +882,8 @@ expected_files = [
 
 Use `--misses` when recall is low. It prints each expected file that was not selected with status, rank, score, and scoring reasons, which helps separate ignored files, budget cuts, low scores, and missing dependency signals.
 
+Use `--prove-targets` in CI or release prep when benchmark cases have `expected_files`. By default it requires average recall >=60% and token precision >=50%; tune with `--min-recall` and `--min-token-precision`.
+
 Add `task_type` to group results by workflow area. Benchmark summaries report average precision, recall, F1, and token noise by type, so a repo can show "backend-api is good, frontend-web is noisy" instead of hiding that under one aggregate.
 
 ---
@@ -925,6 +892,12 @@ Add `task_type` to group results by workflow area. Benchmark summaries report av
 
 Scan the repo and report file statistics.
 
+```bash
+agentpack scan
+agentpack scan --largest 20
+agentpack scan --ignored-summary
+```
+
 ```
 Files discovered:     1,248
 Files ignored/binary:   230
@@ -933,6 +906,8 @@ Raw estimated tokens: 940,000
 Tokens after ignore:  210,000
 ```
 
+Use `--largest` to find high-token files still entering packs. Use `--ignored-summary` when repo counts look surprising; it groups ignored and binary files by common directories or file extensions.
+
 ---
 
 ### `agentpack stats`
@@ -945,7 +920,7 @@ agentpack stats
 
 When a session is active, shows session panel (agent, mode, started, refresh count) above token stats. Also lists top included files from the latest pack and avg recall/precision/F1 over the last 10 runs.
 
-Newer metrics include token-weighted precision. File precision answers "how many selected files were later changed"; token precision answers "how many selected tokens were spent on files later changed." `stats` also breaks token precision down by inclusion mode (`full`, `symbols`, `summary`) so summary noise is visible.
+Newer metrics include token-weighted precision. File precision answers "how many selected files were later changed"; token precision answers "how many selected tokens were spent on files later changed." Context precision also credits obvious read-only support context, such as paired tests beside changed source files. `stats` breaks token precision down by inclusion mode (`full`, `symbols`, `summary`) so summary noise is visible. In monorepos, it also reports selected-file distribution by workspace when workspace metadata exists.
 
 To build a real usefulness signal for your repo:
 
@@ -954,13 +929,31 @@ agentpack benchmark --sample-fixtures
 
 agentpack benchmark --init
 # edit .agentpack/benchmark.toml with real tasks + files you actually changed
-agentpack benchmark --compare --misses
+agentpack benchmark --compare --misses --prove-targets
 ```
 
-`--sample-fixtures` runs bundled FastAPI, Next.js, and mixed Python/TypeScript fixture evals from an AgentPack source checkout. It is a smoke test, not a claim about your repo.
+`--sample-fixtures` runs bundled FastAPI, Next.js, mixed Python/TypeScript, Django REST-style, Go service, and Rails-style fixture evals from an AgentPack source checkout. It is a smoke test, not a claim about your repo.
 
 For an 8+ usefulness signal, use `benchmark.toml` with real third-party or customer-style repos: 5-20 historical tasks, `task_type` labels, the files actually changed for each task, and `--compare` results for recall, F1, rank@K, and token noise. That is better than trusting generic benchmarks because it tells you whether AgentPack selects the files that matter in code the package has never seen.
 
+See [benchmarks/README.md](benchmarks/README.md) for the public smoke-suite fixtures, quality gates, and the recommended miss-debugging workflow.
+
+---
+
+### `agentpack tune`
+
+Turn noisy `stats` and `benchmark --misses` output into next actions.
+
+```bash
+agentpack tune
+agentpack tune --write
+agentpack tune --no-benchmark
+```
+
+`tune` reads `.agentpack/metrics.jsonl` and, when present, `.agentpack/benchmark_results.jsonl`. It flags low token precision, zero-value summaries, repeated noisy paths, support-context gaps, and benchmark miss patterns. `--write` saves the same guidance to `.agentpack/tuning.md`.
+
+This command does not pretend a pack is correct. It gives the next thing to inspect: lower mode, explain noisy files, adjust `.agentignore`, add benchmark cases, or inspect budget/score misses.
+
 ---
 
 ### `agentpack status`
@@ -969,11 +962,14 @@ Check whether the context pack is stale.
 
 ```bash
 agentpack status
+agentpack status --deep
 # Context pack is up to date.
 #   Task: fix auth session bug
 #   Generated: 2026-04-29T12:00:00Z
 ```
 
+`--deep` also prints the active agent, CLI path, current task, and integration health for the detected agent.
+
 ---
 
 ### `agentpack diff`
@@ -1004,23 +1000,20 @@ agentpack monitor --clear
 ## How it works
 
 ```
-1. Scan repo  →  apply .agentignore  →  hash every file
-2. Build current snapshot  →  diff against previous snapshot
-3. Get git changed/staged files  (+ --since <ref> if specified)
-4. Build import dependency graph (Python/JS/TS: full; Go/Rust/Java: best-effort)
-5. Detect related test files
-6. Extract task keywords + concept synonym expansion
-7. Enrich keywords from changed file content (high-frequency identifiers)
-8. Score every file, rank by score
-9. Select within token budget
-10. For each selected file:
-      changed + small  →  full content
-      changed + large  →  symbol bodies (ast.get_source_segment)
-      unchanged dep    →  summary + signatures
-      low-score file   →  summary only
-11. Generate context receipts (why each file included/excluded)
-12. Render markdown for target agent  →  save context pack
-13. Save snapshot + metadata + metrics
+1. Scan repo  →  apply .agentignore  →  skip generated AgentPack outputs  →  hash files
+2. Build offline summaries  →  role, imports, symbols, side effects, public API, errors, test hints
+3. Build import dependency graph  →  Python/JS/TS full, Go/Rust/Java/Kotlin best-effort
+4. Detect changed files  →  snapshot diff + git working tree + staged + optional --since ref
+5. Classify task  →  bugfix / feature / docs / release / infra / audit / test / ui / refactor
+6. Extract weighted task terms  →  literals, variants, concept synonyms, changed-file identifiers
+7. Score every file  →  changes, task terms, symbols, content, deps, tests, configs, churn
+8. Apply history learning  →  gently downrank files that were repeatedly selected as noise
+9. Build semantic repo map  →  compact module/group map reserved inside the token budget
+10. Select by value per token  →  full / diff / symbols / skeleton / summary / omit
+11. For large diffs  →  score hunks against task keywords and keep the most relevant hunks
+12. Redact secrets at materialization  →  before content reaches any renderer or adapter
+13. Render context  →  freshness, task class, repo map, delta since last pack, receipts, files
+14. Persist state  →  adapter output, canonical .agentpack/context.md, snapshot, metadata, metrics
 ```
 
 ---
@@ -1153,7 +1146,11 @@ Works like `.gitignore`. Default rules exclude:
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
-          │            ANALYSIS LAYER                │
+          │       SUMMARY + ANALYSIS LAYER           │
+          │                                         │
+          │  Summary cache  ── role, imports,       │
+          │  (offline)        symbols, side effects, │
+          │                   public API, errors     │
           │                                         │
           │  Import graph  ──  Python AST           │
           │  (6 languages)  ─  JS/TS regex          │
@@ -1170,16 +1167,7 @@ Works like `.gitignore`. Default rules exclude:
           │  Task keywords   ── stopwords + variants│
           │                  ── concept synonyms    │
           │                  ── content enrichment  │
-          └────────────────────┬────────────────────┘
-                               │
-          ┌────────────────────▼────────────────────┐
-          │     SUMMARY CACHE  (offline, local)      │
-          │                                         │
-          │  key: path + hash + provider + schema   │
-          │  hit  → instant, zero I/O               │
-          │  miss → build from AST/regex, cache it  │
-          │                                         │
-          │  offline  ──  AST / regex extract       │
+          │  Task class      ── bugfix/docs/release │
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
@@ -1201,17 +1189,27 @@ Works like `.gitignore`. Default rules exclude:
           │   +50 dep       +40 rev-dep             │
           │   +35 test      +25 config  +20 recent  │
           │   -50 large unrelated                   │
+          │  History noise penalty from metrics     │
+          └────────────────────┬────────────────────┘
+                               │
+          ┌────────────────────▼────────────────────┐
+          │             REPO MAP                     │
+          │                                         │
+          │  Compact semantic map grouped by module │
+          │  Reserved inside the context budget     │
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
           │         BUDGET SELECTION                 │
           │                                         │
-          │  Sort by score, consume until budget    │
+          │  Sort by changed/task/value-per-token   │
           │                                         │
           │  changed + small  ──▶  full content     │
-          │  changed + large  ──▶  symbol bodies    │
-          │  unchanged dep    ──▶  summary + sigs   │
-          │  low score        ──▶  summary only     │
+          │  changed + large  ──▶  task-scored diff │
+          │  task symbols     ──▶  symbol bodies    │
+          │  interface view   ──▶  skeleton         │
+          │  low context      ──▶  summary/omit     │
+          │  budget fallback  ──▶  downgrade first  │
           └────────────────────┬────────────────────┘
                                │
           ┌────────────────────▼────────────────────┐
@@ -1224,6 +1222,8 @@ Works like `.gitignore`. Default rules exclude:
           │  Antigravity adapter ──▶  .agent/skills/agentpack/SKILL.md │
           │  Generic adapter     ──▶  context.md        │
           │                                         │
+          │  Freshness + task class + repo map      │
+          │  Delta since last pack                  │
           │  Context receipts (why each file in/out)│
           │  Secret redaction (AWS/GH/OpenAI tokens)│
           └─────────────────────────────────────────┘
@@ -1239,16 +1239,16 @@ src/agentpack/
     agentpack.md               # bundled /agentpack slash command for Claude CLI
 
   application/
-    pack_service.py            # PackPlanner: shared scan→rank→select pipeline
+    pack_service.py            # PackPlanner: shared scan→summarize→graph→rank→repo_map→select pipeline
                                # PackService: materializes plan → writes context file
                                # AdapterRegistry: maps agent names to adapter instances
                                # PackRequest / PackResult / PackPlan DTOs
 
   domain/  (via core/models.py)
     FileInfo, ScanResult       # scan output (packable / ignored / binary)
-    Symbol, FileSummary        # summary cache objects
+    Symbol, FileSummary        # summary cache objects (role, side_effects, public_api, errors, tests)
     SelectedFile, Receipt      # selection output with redaction_warnings
-    ContextPack                # final artifact with redaction_warnings
+    ContextPack                # final artifact with freshness, repo_map, delta_summary, redaction_warnings
     DependencyNode             # typed graph node (path, imports, imported_by, tests)
     DependencyGraph            # typed graph container (nodes dict + dict-like accessors)
 
@@ -1262,7 +1262,7 @@ src/agentpack/
     git.py                     # subprocess git + task inference from branch/commits
     merkle.py                  # root hash: sort(path:hash) → sha256
     cache.py                   # summary cache keyed path+hash+provider+version
-    context_pack.py            # select_files: budget selection + secret redaction
+    context_pack.py            # select_files: full/diff/symbols/skeleton/summary + hunk scoring + redaction
     token_estimator.py         # tiktoken cl100k_base (approximate)
     redactor.py                # redact_secrets: fires at content materialization
     bootstrap.py               # is_initialized, bootstrap_if_needed
@@ -1277,9 +1277,12 @@ src/agentpack/
     symbols.py                 # AST symbols + body via ast.get_source_segment
     tests.py                   # source → test file mapping heuristics
     ranking.py                 # keyword extraction, concept synonyms, scoring
+    monorepo.py                # workspace detection + workspace ownership helpers
+    repo_map.py                # compact semantic repo map reserved inside token budget
+    task_classifier.py         # coarse task class for freshness/rendering/scoring context
 
   summaries/
-    offline.py                 # zero-API: AST/regex → imports, symbols, summary
+    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, errors
     base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
@@ -1300,15 +1303,18 @@ src/agentpack/
     antigravity.py             # AntigravityInstaller: GEMINI.md + auto-repack
 
   integrations/                # system/tool integration (not core domain)
+    agents.py                  # shared agent install/check/repair contract for all supported agents
     git_hooks.py               # install/remove .git/hooks post-commit/merge/checkout
     vscode_tasks.py            # install/remove .vscode/tasks.json entries
     global_install.py          # global: git template hooks + shell rc hook
 
   renderers/
-    markdown.py                # renders pre-redacted ContextPack to markdown
+    markdown.py                # renders pre-redacted ContextPack to markdown, including freshness/map/delta
     compact.py                 # compact protocol format for session context files
     receipts.py                # context receipt formatter
 
+  mcp_server.py                # MCP tools: pack_context, get_context, explain, related, stats, delta
+
   session/
     state.py                   # SessionState dataclass + load/save/create/stop helpers
     __init__.py                # re-exports from state.py
@@ -1316,6 +1322,7 @@ src/agentpack/
   commands/                    # CLI only — parse args, call services/installers
     pack.py                    # agentpack pack → PackService.run()
     install.py                 # agentpack install / global-install → installers/
+    repair.py                  # agentpack repair → shared integration repair
     init.py                    # agentpack init
     quickstart.py              # agentpack quickstart — guided first-run commands
     scan.py                    # agentpack scan
@@ -1326,6 +1333,7 @@ src/agentpack/
     monitor.py                 # agentpack monitor
     explain.py                 # agentpack explain
     doctor.py                  # agentpack doctor
+    tune.py                    # agentpack tune — tuning suggestions from metrics + benchmark misses
     hook_cmd.py                # agentpack hook — Claude prompt hook + stale detection
     mcp_cmd.py                 # agentpack mcp — MCP server entrypoint
     watch.py                   # agentpack watch — file watcher with debounce
@@ -1337,212 +1345,21 @@ src/agentpack/
 
 - **Redaction at materialization**: secrets are stripped inside `select_files()` before content reaches any renderer or adapter. Every output format gets redacted content automatically — no per-renderer redaction needed.
 - **`ScanResult` splits cleanly**: `scan()` returns `ScanResult(packable, ignored, binary)` — downstream code only processes `packable` files, eliminating `if f.ignored or f.binary` guards throughout.
-- **`PackPlanner` owns shared planning**: `PackPlanner.plan()` runs scan → summarize → graph → rank → select and returns a `PackPlan`. Both `pack` and `explain` use the same planner — no duplicated pipeline logic, no drift.
-- **`PackService` materializes a plan**: takes a `PackPlan`, builds the `ContextPack` artifact, delegates rendering to `AdapterRegistry`, persists snapshot + metadata + metrics.
+- **`PackPlanner` owns shared planning**: `PackPlanner.plan()` runs scan → summarize → graph → changes → rank → repo map → select and returns a `PackPlan`. Both `pack` and `explain` use the same planner — no duplicated pipeline logic, no drift.
+- **`PackService` materializes a plan**: takes a `PackPlan`, computes delta since the previous pack, builds the `ContextPack` artifact, delegates rendering to `AdapterRegistry`, persists snapshot + metadata + metrics.
+- **Mode selection is value-aware**: changed files can be `full`, `diff`, `symbols`, `skeleton`, or `summary`. Large diffs keep task-relevant hunks first, and tight budgets downgrade files before dropping them.
+- **Repo maps are first-class context**: `analysis/repo_map.py` builds a compact semantic map before file context, and its token cost is reserved before file selection.
+- **Metrics feed history learning**: selection accuracy records hit/noise paths, token precision, mode counts, and mode tokens. Later packs gently penalize repeated noisy paths unless they are currently changed.
+- **Git history feeds recall**: files that historically changed in the same commits as live changed files receive a small boost, helping related tests, schemas, services, and configs surface without forcing full-content inclusion.
+- **Co-change is guarded by precision history**: one-off co-change neighbors are ignored, and paths repeatedly measured as noise do not get revived by history boosts.
+- **Precision guardrails adapt to bad history**: when summary token precision stays near zero, later packs raise the summary score floor, cap summaries more aggressively, and suppress summaries entirely for no-live-change packs. Weak filename-only matches are also damped unless other signals confirm them.
 - **`AdapterRegistry` maps agent → adapter**: adding a new agent output format requires one entry in `AdapterRegistry.get()`, not changes to `PackService`.
 - **`detect_agent()` runs at invocation time**: `--agent auto` (the default) calls `detect_agent()` fresh on every `pack` run and git hook execution — so context is always written for the active IDE, even when switching between agents or running in CI.
 - **`DependencyGraph` is typed**: `dependency_graph.build()` returns `DependencyGraph(nodes: dict[str, DependencyNode])` — no more `dict[str, dict]` with stringly-typed keys like `"imported_by"`. Typos are caught at the model layer.
 - **`integrations/` vs `core/`**: git hooks, shell rc patching, and VS Code tasks are infrastructure concerns — they live in `integrations/`, not `core/`. `core/` is pure domain logic.
 - **Adapters render; installers configure**: `adapters/` knows how to write a context file for an agent. `installers/` knows how to configure the agent's tool (CLAUDE.md, .cursorrules, settings.json). They are separate concerns and separate classes.
-
----
-
-## Practical examples
-
-### Bug fix: "I have a failing test, help me fix it"
-
-```bash
-# You're debugging a test failure in the auth module
-agentpack pack --task "fix failing test in auth token validation"
-```
-
-AgentPack selects: the failing test file (modified), `auth/token.py` (dep), `auth/session.py` (dep), `config/settings.py` (config), skips 180 unrelated files. Your agent gets 12k tokens of precisely relevant context and starts debugging immediately.
-
----
-
-### Feature: "Add rate limiting to the API"
-
-```bash
-# On a feature branch, nothing modified yet
-agentpack pack --task "add rate limiting to REST API endpoints"
-```
-
-Keyword expansion activates: "rate limiting" → `throttle`, `leaky`, `bucket`, `quota`. AgentPack scores: `middleware/` directory (path keyword `api`), existing `throttle.py` or `leaky_bucket.py` (content keyword), `routes/*.py` (deps). Your agent gets the full middleware stack and starts implementing, not exploring.
-
----
-
-### Code review: "Review my PR before I push"
-
-```bash
-# Review only what changed vs main
-agentpack pack --task "code review auth refactor" --since main
-```
-
-Only files touched in this branch are included (full content). Everything else is summaries or omitted. Your agent reviews exactly the diff-visible code, not the whole codebase.
-
----
-
-### Refactor: "Help me refactor the database layer"
-
-```bash
-agentpack pack --task "refactor database connection pooling" --mode deep
-```
-
-`--mode deep` adds: related docs, more full-content files, broader dep tree. Use when the task touches many files and you want your agent to see more context upfront.
-
----
-
-### CI: automated context on every PR
-
-Add to `.github/workflows/agentpack-context.yml` — see the full example in [CI/CD: pack per PR](#cicd-pack-per-pr). Reviewers and CI bots get focused context without cloning the repo.
-
----
-
-### Session mode: keep context fresh while you work
-
-```bash
-# One-time project setup
-agentpack init                     # creates config/session/task.md + detected agent integration
-# Edit .agentpack/task.md to set your task
-
-# Every terminal session — just one command
-agentpack watch                    # keeps context fresh automatically
-
-# Change task mid-session: edit .agentpack/task.md directly
-# watch detects the change and refreshes automatically
-```
-
----
-
-### Debug why a file isn't showing up
-
-```bash
-agentpack explain --task "fix rate limiting in auth middleware"
-# Top selected files:
-#   1. src/auth/middleware.py  score=180  [full]     modified, filename keyword match
-#   2. src/auth/limiter.py     score=130  [symbols]  dep + content keyword "throttle"
-#   ...
-# Excluded:
-#   - src/payments/billing.py  score=8    score too low
-```
-
----
-
-## Tips & tricks
-
-### Let `--task auto` do the work
-
-Skip writing a task description — agentpack infers it from your branch name, changed files, and recent commits:
-
-```bash
-agentpack pack --task auto
-```
-
-Priority order (strongest → weakest):
-
-| Source | Example output |
-|--------|---------------|
-| `task.md` (explicit) | `"migrate DB schema to multi-tenant"` |
-| branch + staged files | `"feat add-rate-limiting: payments, throttle"` |
-| staged files only | `"payments, throttle"` |
-| branch + unstaged | `"feat add-rate-limiting: session, token"` |
-| branch + latest commit | `"feat add-rate-limiting: fix token expiry check"` |
-| branch name alone | `"feat add-rate-limiting"` |
-| unstaged files | `"session, token"` |
-| recent commit messages | `"fix token expiry check; add pagination"` |
-| recently modified files | `"session, payments"` (noisy — last resort) |
-
-The heuristic that fired is logged: `Auto task (branch+staged): feat add-rate-limiting: payments`.
-
-The more descriptive your branch names (`feat/add-rate-limiting` beats `dev`) and the more you stage before running, the more accurate the inference.
-
-### Concept synonym expansion
-
-AgentPack expands task keywords automatically — "rate limiting" expands to `throttle`, `leaky`, `bucket`, `quota`, `debounce`; "auth" expands to `jwt`, `bearer`, `token`, `oauth`; "cache" expands to `lru`, `memoize`, `redis`, `ttl`; domain terms such as `kundali` expand toward astrology/chart/compatibility terms. Files that implement a concept but don't use its exact name can still rank.
-
-### Full-stack role boosts
-
-When a task points at a page, route, or API surface, AgentPack also gives a controlled boost to related implementation roles such as `service`, `controller`, `schema`, `handler`, `repository`, and `client`. This helps full-stack tasks pull backend implementation files instead of only frontend entrypoints.
-
-This is still heuristic. If a service should have appeared and did not, add it as an `expected_files` entry in `benchmark.toml` and run:
-
-```bash
-agentpack benchmark --compare --misses
-```
-
-### Content-based keyword enrichment
-
-When you run `agentpack pack`, changed file content is scanned for high-frequency identifiers. If you're editing `session_manager.py` that mentions `validate_token` 30 times, `validate` and `token` are added as keywords — related files that use the same terms get a score boost even if your task string didn't mention them.
-
-### Commit the summary cache for instant team packs
-
-```bash
-agentpack init --share-cache
-git add .agentpack/cache/
-git commit -m "chore: add agentpack summary cache"
-```
-
-Every teammate and CI job skips the summarize step. `agentpack pack` is significantly faster from a warm cache.
-
-### Use `--since` for PR reviews
-
-```bash
-agentpack pack --task "review auth changes" --since main
-```
-
-Only includes files changed since `main`. Cuts out noise from unrelated work in long-running branches.
-
-### Tune the budget for your use case
-
-```bash
-agentpack pack --task "fix bug" --mode minimal   # changed files only, fewest tokens
-agentpack pack --task "refactor" --mode deep     # everything including docs
-agentpack pack --task "fix bug" --budget 40000   # explicit token cap
-```
-
-`balanced` (default) is right for most tasks. Use `minimal` for quick fixes, `deep` when architectural context matters.
-
-### Watch mode for active sessions
-
-```bash
-agentpack init                  # one-time setup (creates session/task.md + detected agent integration)
-agentpack watch                 # in another terminal — auto-resumes each time
-```
-
-Refreshes `.agentpack/context.md` every time you save a file. Change the task by editing `.agentpack/task.md` directly — or tell Claude and it writes the file itself. `watch` picks up the change automatically.
-
-### Debug file selection with `explain`
-
-```bash
-agentpack explain --task "fix auth session bug"
-```
-
-Shows ranked scores and reasons before committing to a pack. Use when a file you expect isn't appearing.
-
-For repeatable evals, prefer `benchmark --misses` because it compares selected files against the files you actually changed for historical tasks.
-
-### Check what got included and why
-
-Every pack includes a context receipt explaining each file's inclusion or exclusion:
-
-```
-- `src/auth.py` included because modified, filename keyword match
-- `tests/test_auth.py` summarized because test for src/auth.py
-- `src/unrelated_big.py` excluded because score too low
-```
-
-Use this to tune your `.agentignore` or scoring weights when irrelevant files keep appearing.
-
-### Tune scoring weights per project
-
-If tests are always irrelevant to your tasks, drop their weight. If config files are critical, raise them:
-
-```toml
-# .agentpack/config.toml
-[scoring]
-related_test    = 5    # was 35 — tests rarely relevant
-config_file     = 60   # was 25 — configs always matter here
-```
+- **Agent integration contract is shared**: `integrations/agents.py` defines install, audit, and repair behavior for Claude, Cursor, Windsurf, Codex, Antigravity, and Generic. `install`, `repair`, `doctor --agent all`, and release verification use the same contract.
+- **MCP and hooks use deltas when possible**: MCP exposes `get_delta_context()`, and prompt hooks can emit task/top-file/delta hints instead of injecting the full context every time.
 
 ---
 
@@ -1560,7 +1377,8 @@ config_file     = 60   # was 25 — configs always matter here
 ## Known limitations
 
 - **Windows**: not supported. Git hooks use POSIX shell (`#!/bin/sh`, `>/dev/null 2>&1 &`). The Claude Code session hooks use `python3` and `rm -f`. Contributions welcome.
-- **Monorepos**: single-root repos only. If you `agentpack pack` from a monorepo root, all packages are scanned together with no workspace awareness. Workaround: `cd packages/my-pkg && agentpack init && agentpack pack`.
+- **Monorepos**: workspace-aware ranking supports npm/pnpm, Cargo, and `go.work` layouts. `--workspace` creates filtered per-workspace outputs. Package dependency hints currently come from npm/pnpm `package.json`; Cargo/Go workspace membership is detected, but package-manager dependency edges for Cargo/Go are not yet modeled.
+- **Public benchmark proof**: source-checkout fixture results are useful regressions, not market proof. Use `agentpack benchmark --results-template` to publish real historical task results.
 - **Symbol extraction**: Python (AST, full) and JavaScript/TypeScript (regex, arrow functions + classes) are well-supported. Go, Rust, Java, Kotlin have import graph traversal but no symbol extraction — they fall back to file-level summaries.
 - **Selection recall**: ranking is heuristic. It can miss files when task language differs from code language, when repos have unusual architecture, or when important files are only connected at runtime.
 - **Secret redaction**: covers AWS keys, GitHub tokens, OpenAI/Anthropic keys, JWTs, and private key blocks. Not a substitute for a dedicated secrets scanner on sensitive repos.
@@ -1569,6 +1387,18 @@ config_file     = 60   # was 25 — configs always matter here
 
 ---
 
+## Roadmap
+
+Next release target: **0.2.0 = benchmark + recall release**.
+
+- Expand public source-checkout fixtures and publish reproducible `benchmark --sample-fixtures --compare --misses` output.
+- Raise recall on real historical tasks while keeping token precision healthy; target 60%+ recall, 50%+ token precision, and balanced packs under 25k tokens.
+- Improve second-pass expansion beyond current imports, reverse imports, related tests, historical co-change, and workspace hints with framework route/service/schema pairs.
+- Make MCP pull flows more prominent so agents can ask for `explain_file`, `get_related_files`, and `get_delta_context` instead of relying only on a static startup pack.
+- Keep integration contracts stable across Claude, Cursor, Windsurf, Codex, Antigravity, and Generic before any 1.0 work.
+
+---
+
 ## Optional dependencies
 
 ```bash
@@ -1598,9 +1428,13 @@ python -m ruff check src tests
 python -m build
 npm test --prefix npm
 (cd npm && npm pack --dry-run)
+pytest tests/test_agent_integration_matrix.py -q
 agentpack benchmark --sample-fixtures --misses
+agentpack doctor
 ```
 
+For npm publish, configure GitHub secret `NPM_TOKEN`. `agentpack doctor` warns locally when neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` is present, and the npm publish workflow fails early with a clear error if the secret is missing.
+
 Good contribution areas:
 
 - More real-world benchmark fixtures and public repo eval cases