agentpack-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{agentpack_cli-0.3.0 → agentpack_cli-0.3.2}/.gitignore

@@ -12,6 +12,8 @@ env/
 
 # agentpack:start
 # AgentPack generated context/cache (safe to ignore)
+.agentpack/*
+!.agentpack/config.toml
 .agentpack/cache/
 .agentpack/snapshots/
 .agentpack/context*
@@ -23,9 +25,11 @@ env/
 .agentpack/session.json
 .agentpack/task.md
 .agentpack/benchmark_results.jsonl
+.agentignore
 .agent/skills/agentpack/
+.vscode/tasks.json
+GEMINI.md
 # agentpack:end
-
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/

agentpack_cli-0.3.0/README.md → agentpack_cli-0.3.2/PKG-INFO

@@ -1,19 +1,60 @@
+Metadata-Version: 2.4
+Name: agentpack-cli
+Version: 0.3.2
+Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
+License: MIT
+License-File: LICENSE
+Keywords: ai,ai-coding-agents,antigravity,ci,claude,claude-code,codex,context,context-engine,context-packing,cursor,developer-tools,llm,mcp,packing,prompt-context,repo-analysis,windsurf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: watchdog>=4.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
+[![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
 [![Python versions](https://img.shields.io/pypi/pyversions/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
 [![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.3.0).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.2).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. 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.
 
 **Local context engine for AI coding agents.**
 
-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.
+AgentPack gives Claude Code, Codex, Cursor, Windsurf, Antigravity, CI jobs, and other agent workflows a better starting point. It analyzes your repo locally, finds the relevant files for a task, and packages them into compact task-focused context packs for CLI and MCP tool workflows.
 
-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.
+Use AgentPack when a repo is too large to paste and you want faster, more consistent context preparation before an agent starts working. It works offline, keeps the product boundary explicit, and is a context preparation tool, not a coding agent.
 
 ## Contents
 
@@ -21,6 +62,7 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Quality Bar](#quality-bar)
+- [Download Stats](#download-stats)
 - [Debugging Selection](#debugging-selection)
 - [Supported Integrations](#supported-integrations)
 - [Commands](#commands)
@@ -31,8 +73,9 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, and repo history.
+- **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.
+- **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **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.
@@ -41,11 +84,51 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+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.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+If `pipx` is not installed yet:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+`pipx` is the recommended default because it keeps the CLI isolated and avoids many macOS/Linux global `pip install` issues, including PEP 668 `externally-managed-environment` errors. If you prefer `pip`, install inside a virtual environment.
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -54,7 +137,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. See the [npm README](https://github.com/vishal2612200/agentpack/blob/main/npm/README.md) for wrapper cache controls and troubleshooting. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -125,6 +208,24 @@ ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
 against files actually changed by the commit. Synthetic fixtures are useful
 regression tests, but should not be presented as market proof.
 
+## Download Stats
+
+npm exposes official package download counts through its public registry API and the npm downloads badge above:
+
+```bash
+curl https://api.npmjs.org/downloads/point/last-month/%40vishal2612200%2Fagentpack
+curl https://api.npmjs.org/downloads/point/last-week/%40vishal2612200%2Fagentpack
+```
+
+PyPI does not show official project download counts on package pages. For rough trend data on the Python core package, use third-party mirrors:
+
+```bash
+curl https://pypistats.org/api/packages/agentpack-cli/recent
+```
+
+- PyPI Stats: <https://pypistats.org/packages/agentpack-cli>
+- pepy.tech: <https://pepy.tech/project/agentpack-cli>
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -415,7 +516,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -728,9 +829,13 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" watch
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack watch` may still resolve to the Node launcher.
+
 ---
 
 ### `agentpack claude`
@@ -750,10 +855,13 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
-agentpack mcp
+pipx inject agentpack-cli "agentpack-cli[mcp]"
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" mcp
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack mcp` may still resolve to the Node launcher instead of the extras-enabled Python CLI.
+
 Register in Claude Code settings (`~/.claude/settings.json`):
 
 ```json
@@ -1172,7 +1280,8 @@ Works like `.gitignore`. Default rules exclude:
           │                                         │
           │  Summary cache  ── role, imports,       │
           │  (offline)        symbols, side effects, │
-          │                   public API, errors     │
+          │                   public API, naming     │
+          │                   signals, errors        │
           │                                         │
           │  Import graph  ──  Python AST           │
           │  (6 languages)  ─  JS/TS regex          │
@@ -1185,6 +1294,9 @@ Works like `.gitignore`. Default rules exclude:
           │  ast.get_source_segment)   classes,     │
           │                    ── arrow fns w/ =>)  │
           │                                         │
+          │  Naming signals ── public files/symbols │
+          │                  ── env/config/test ids │
+          │                  ── generic-name hints  │
           │  Test detection  ── name heuristics     │
           │  Task keywords   ── stopwords + variants│
           │                  ── concept synonyms    │
@@ -1210,6 +1322,7 @@ Works like `.gitignore`. Default rules exclude:
           │   +70 symbol    +60 content match       │
           │   +50 dep       +40 rev-dep             │
           │   +35 test      +25 config  +20 recent  │
+          │   +20 naming    -6 generic public API   │
           │   -50 large unrelated                   │
           │  History noise penalty from metrics     │
           └────────────────────┬────────────────────┘
@@ -1297,14 +1410,15 @@ src/agentpack/
     rust_imports.py            # use, mod, extern crate
     java_imports.py            # Java import + Kotlin import
     symbols.py                 # AST symbols + body via ast.get_source_segment
+    naming_signals.py          # public-name classification for summaries + ranking boosts
     tests.py                   # source → test file mapping heuristics
-    ranking.py                 # keyword extraction, concept synonyms, scoring
+    ranking.py                 # keyword extraction, concept synonyms, scoring, naming receipts
     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, role, side effects, API, errors
+    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, naming signals, errors
     base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
@@ -1425,15 +1539,25 @@ Post-0.3 release focus: broader real-repo proof, npm publish reliability, and co
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---
 
 ## Development
 
+## Public Naming And Ranking
+
+AgentPack works better when public surfaces carry domain context. Prefer domain-revealing names for files, exported functions/classes, CLI commands, tests, and config/env identifiers.
+
+- `verify_otp` is better than `handle`
+- `StripeWebhookHandler` is better than `Processor`
+- `session_token_expiry_test` is better than `test_flow`
+
+This is guidance, not a lint rule. Local variable names are out of scope for AgentPack ranking.
+
 Clone and run locally:
 
 ```bash

agentpack_cli-0.3.0/PKG-INFO → agentpack_cli-0.3.2/README.md

@@ -1,58 +1,21 @@
-Metadata-Version: 2.4
-Name: agentpack-cli
-Version: 0.3.0
-Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
-License: MIT
-License-File: LICENSE
-Keywords: ai,claude,codex,coding-agent,context,cursor,llm,packing,windsurf
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-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: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
-Requires-Dist: pathspec>=0.12.1
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tiktoken>=0.7.0
-Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: tomli>=2.0.0; python_version < '3.11'
-Requires-Dist: typer>=0.12.0
-Provides-Extra: all
-Requires-Dist: mcp>=1.0.0; extra == 'all'
-Requires-Dist: watchdog>=4.0.0; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Provides-Extra: watch
-Requires-Dist: watchdog>=4.0.0; extra == 'watch'
-Description-Content-Type: text/markdown
-
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
+[![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
 [![Python versions](https://img.shields.io/pypi/pyversions/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
 [![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.3.0).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
+> **Status: alpha (v0.3.2).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. 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.
 
 **Local context engine for AI coding agents.**
 
-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.
+AgentPack gives Claude Code, Codex, Cursor, Windsurf, Antigravity, CI jobs, and other agent workflows a better starting point. It analyzes your repo locally, finds the relevant files for a task, and packages them into compact task-focused context packs for CLI and MCP tool workflows.
 
-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.
+Use AgentPack when a repo is too large to paste and you want faster, more consistent context preparation before an agent starts working. It works offline, keeps the product boundary explicit, and is a context preparation tool, not a coding agent.
 
 ## Contents
 
@@ -60,6 +23,7 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Quality Bar](#quality-bar)
+- [Download Stats](#download-stats)
 - [Debugging Selection](#debugging-selection)
 - [Supported Integrations](#supported-integrations)
 - [Commands](#commands)
@@ -70,8 +34,9 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, and repo history.
+- **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.
+- **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **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.
@@ -80,11 +45,51 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+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.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+If `pipx` is not installed yet:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+`pipx` is the recommended default because it keeps the CLI isolated and avoids many macOS/Linux global `pip install` issues, including PEP 668 `externally-managed-environment` errors. If you prefer `pip`, install inside a virtual environment.
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -93,7 +98,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. See the [npm README](https://github.com/vishal2612200/agentpack/blob/main/npm/README.md) for wrapper cache controls and troubleshooting. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -164,6 +169,24 @@ ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
 against files actually changed by the commit. Synthetic fixtures are useful
 regression tests, but should not be presented as market proof.
 
+## Download Stats
+
+npm exposes official package download counts through its public registry API and the npm downloads badge above:
+
+```bash
+curl https://api.npmjs.org/downloads/point/last-month/%40vishal2612200%2Fagentpack
+curl https://api.npmjs.org/downloads/point/last-week/%40vishal2612200%2Fagentpack
+```
+
+PyPI does not show official project download counts on package pages. For rough trend data on the Python core package, use third-party mirrors:
+
+```bash
+curl https://pypistats.org/api/packages/agentpack-cli/recent
+```
+
+- PyPI Stats: <https://pypistats.org/packages/agentpack-cli>
+- pepy.tech: <https://pepy.tech/project/agentpack-cli>
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -454,7 +477,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -767,9 +790,13 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" watch
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack watch` may still resolve to the Node launcher.
+
 ---
 
 ### `agentpack claude`
@@ -789,10 +816,13 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
-agentpack mcp
+pipx inject agentpack-cli "agentpack-cli[mcp]"
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" mcp
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack mcp` may still resolve to the Node launcher instead of the extras-enabled Python CLI.
+
 Register in Claude Code settings (`~/.claude/settings.json`):
 
 ```json
@@ -1211,7 +1241,8 @@ Works like `.gitignore`. Default rules exclude:
           │                                         │
           │  Summary cache  ── role, imports,       │
           │  (offline)        symbols, side effects, │
-          │                   public API, errors     │
+          │                   public API, naming     │
+          │                   signals, errors        │
           │                                         │
           │  Import graph  ──  Python AST           │
           │  (6 languages)  ─  JS/TS regex          │
@@ -1224,6 +1255,9 @@ Works like `.gitignore`. Default rules exclude:
           │  ast.get_source_segment)   classes,     │
           │                    ── arrow fns w/ =>)  │
           │                                         │
+          │  Naming signals ── public files/symbols │
+          │                  ── env/config/test ids │
+          │                  ── generic-name hints  │
           │  Test detection  ── name heuristics     │
           │  Task keywords   ── stopwords + variants│
           │                  ── concept synonyms    │
@@ -1249,6 +1283,7 @@ Works like `.gitignore`. Default rules exclude:
           │   +70 symbol    +60 content match       │
           │   +50 dep       +40 rev-dep             │
           │   +35 test      +25 config  +20 recent  │
+          │   +20 naming    -6 generic public API   │
           │   -50 large unrelated                   │
           │  History noise penalty from metrics     │
           └────────────────────┬────────────────────┘
@@ -1336,14 +1371,15 @@ src/agentpack/
     rust_imports.py            # use, mod, extern crate
     java_imports.py            # Java import + Kotlin import
     symbols.py                 # AST symbols + body via ast.get_source_segment
+    naming_signals.py          # public-name classification for summaries + ranking boosts
     tests.py                   # source → test file mapping heuristics
-    ranking.py                 # keyword extraction, concept synonyms, scoring
+    ranking.py                 # keyword extraction, concept synonyms, scoring, naming receipts
     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, role, side effects, API, errors
+    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, naming signals, errors
     base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
@@ -1464,15 +1500,25 @@ Post-0.3 release focus: broader real-repo proof, npm publish reliability, and co
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---
 
 ## Development
 
+## Public Naming And Ranking
+
+AgentPack works better when public surfaces carry domain context. Prefer domain-revealing names for files, exported functions/classes, CLI commands, tests, and config/env identifiers.
+
+- `verify_otp` is better than `handle`
+- `StripeWebhookHandler` is better than `Processor`
+- `session_token_expiry_test` is better than `test_flow`
+
+This is guidance, not a lint rule. Local variable names are out of scope for AgentPack ranking.
+
 Clone and run locally:
 
 ```bash

{agentpack_cli-0.3.0 → agentpack_cli-0.3.2}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.0"
-description = "Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity"
+version = "0.3.2"
+description = "Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs."
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
-keywords = ["context", "llm", "packing", "claude", "cursor", "windsurf", "codex", "ai", "coding-agent"]
+keywords = ["ai-coding-agents", "developer-tools", "repo-analysis", "context-engine", "context-packing", "prompt-context", "mcp", "ci", "claude-code", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing", "claude"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",

{agentpack_cli-0.3.0 → agentpack_cli-0.3.2}/src/agentpack/__init__.py

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