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

agentpack_cli-0.3.1/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.1).** 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.
@@ -66,6 +109,27 @@ sudo pacman -S python-pipx
 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:
 
 ```bash
@@ -73,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
 
@@ -144,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:
@@ -748,8 +830,12 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 Install watchdog for better performance:
 ```bash
 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`
@@ -770,9 +856,12 @@ Run AgentPack as an MCP server — exposes context packing as tools that Claude
 
 ```bash
 pipx inject agentpack-cli "agentpack-cli[mcp]"
-agentpack 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
@@ -1191,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          │
@@ -1204,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    │
@@ -1229,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     │
           └────────────────────┬────────────────────┘
@@ -1316,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
@@ -1453,6 +1548,16 @@ 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.1/PKG-INFO → agentpack_cli-0.3.2/README.md

@@ -1,58 +1,21 @@
-Metadata-Version: 2.4
-Name: agentpack-cli
-Version: 0.3.1
-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.1).** 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.
@@ -105,6 +70,27 @@ sudo pacman -S python-pipx
 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:
 
 ```bash
@@ -112,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
 
@@ -183,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:
@@ -787,8 +791,12 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 Install watchdog for better performance:
 ```bash
 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`
@@ -809,9 +817,12 @@ Run AgentPack as an MCP server — exposes context packing as tools that Claude
 
 ```bash
 pipx inject agentpack-cli "agentpack-cli[mcp]"
-agentpack 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
@@ -1230,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          │
@@ -1243,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    │
@@ -1268,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     │
           └────────────────────┬────────────────────┘
@@ -1355,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
@@ -1492,6 +1509,16 @@ 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.1 → agentpack_cli-0.3.2}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.1"
-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.1 → 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.1"
+__version__ = "0.3.2"

agentpack_cli-0.3.2/src/agentpack/analysis/naming_signals.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentpack.analysis.symbols import extract_symbols
+
+
+_GENERIC_PUBLIC_STEMS = {
+    "base",
+    "common",
+    "data",
+    "handle",
+    "helper",
+    "manager",
+    "misc",
+    "process",
+    "processor",
+    "run",
+    "service",
+    "thing",
+    "tool",
+    "util",
+    "utils",
+}
+
+_GENERIC_FILE_STEMS = {"base", "common", "helpers", "misc", "shared", "util", "utils"}
+_IGNORE_TOKENS = {"api", "app", "class", "component", "controller", "file", "function", "handler", "http", "method", "module", "page", "route", "service", "test"}
+_DOMAIN_HINTS = {
+    "auth", "billing", "cache", "chart", "checkout", "compatibility", "config",
+    "context", "cursor", "env", "invoice", "jwt", "kundali", "mcp", "notification",
+    "otp", "pack", "payment", "ranking", "redis", "repo", "search", "session",
+    "stats", "stripe", "summaries", "summary", "token", "watch", "webhook",
+}
+_ACTION_HINTS = {
+    "add", "apply", "build", "check", "collect", "create", "delete", "dispatch",
+    "enrich", "explain", "extract", "fetch", "find", "generate", "get", "infer",
+    "install", "issue", "load", "manage", "pack", "parse", "rank", "read",
+    "refresh", "render", "resolve", "save", "scan", "score", "select", "send",
+    "start", "stop", "summarize", "sync", "track", "update", "validate", "verify",
+    "watch", "write",
+}
+
+
+@dataclass
+class PublicNameSignal:
+    name: str
+    label: str
+    keywords: list[str]
+    reasons: list[str]
+
+
+def name_tokens(name: str) -> list[str]:
+    spaced = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name)
+    raw = re.split(r"[^a-zA-Z0-9]+", spaced.lower())
+    return [tok for tok in raw if tok]
+
+
+def classify_public_name(name: str) -> PublicNameSignal:
+    tokens = name_tokens(name)
+    meaningful = [tok for tok in tokens if len(tok) >= 3 and tok not in _IGNORE_TOKENS]
+    generic = [tok for tok in meaningful if tok in _GENERIC_PUBLIC_STEMS]
+    domain = [tok for tok in meaningful if tok in _DOMAIN_HINTS]
+    action = [tok for tok in meaningful if tok in _ACTION_HINTS]
+
+    if len(meaningful) == 1 and meaningful[0] in _GENERIC_PUBLIC_STEMS:
+        return PublicNameSignal(name=name, label="generic", keywords=meaningful, reasons=["unqualified generic public stem"])
+    if domain and (action or len(meaningful) >= 2):
+        return PublicNameSignal(name=name, label="domain_revealing", keywords=_dedupe([*domain, *action, *meaningful]), reasons=["domain-qualified public name"])
+    if len(meaningful) >= 2 and not generic:
+        return PublicNameSignal(name=name, label="domain_revealing", keywords=meaningful, reasons=["multi-part public name"])
+    if generic and len(meaningful) == len(generic):
+        return PublicNameSignal(name=name, label="generic", keywords=meaningful, reasons=["mostly generic public stems"])
+    return PublicNameSignal(name=name, label="neutral", keywords=meaningful, reasons=[])
+
+
+def filename_signal(path: str) -> PublicNameSignal:
+    stem = Path(path).stem
+    signal = classify_public_name(stem)
+    if signal.label == "neutral" and stem.lower() in _GENERIC_FILE_STEMS:
+        return PublicNameSignal(name=stem, label="generic", keywords=[stem.lower()], reasons=["generic filename stem"])
+    return signal
+
+
+def collect_public_name_candidates(path: Path, language: str | None) -> list[str]:
+    if language in {"javascript", "typescript"}:
+        return _collect_js_export_names(path)
+
+    candidates: list[str] = []
+    for sym in extract_symbols(path, language):
+        tail = sym.name.split(".")[-1]
+        if tail.startswith("_"):
+            continue
+        candidates.append(sym.name)
+    return _dedupe(candidates)
+
+
+def summarize_naming_signals(path: str, public_names: list[str], extra_names: list[str] | None = None) -> tuple[list[str], list[str]]:
+    signals: list[str] = []
+    keywords: list[str] = []
+    for signal in [filename_signal(path), *[classify_public_name(name.split(".")[-1]) for name in public_names]]:
+        if signal.label == "domain_revealing":
+            signals.append(f"strong public name: {signal.name}")
+        elif signal.label == "generic":
+            signals.append(f"generic public name: {signal.name}")
+        keywords.extend(signal.keywords)
+    for name in extra_names or []:
+        extra_signal = classify_public_name(name)
+        if extra_signal.label == "domain_revealing":
+            signals.append(f"strong public name: {name}")
+        keywords.extend(extra_signal.keywords)
+    return _dedupe(signals)[:12], _dedupe(keywords)[:12]
+
+
+def _collect_js_export_names(path: Path) -> list[str]:
+    try:
+        text = path.read_text(errors="replace")
+    except OSError:
+        return []
+
+    names: list[str] = []
+    patterns = [
+        re.compile(r"export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*\("),
+        re.compile(r"export\s+(?:default\s+)?class\s+(\w+)"),
+        re.compile(r"export\s+(?:const|let|var)\s+(\w+)\s*="),
+    ]
+    for pattern in patterns:
+        names.extend(pattern.findall(text))
+    return _dedupe(names)
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in items:
+        if item and item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result

{agentpack_cli-0.3.1 → agentpack_cli-0.3.2}/src/agentpack/analysis/ranking.py

@@ -578,6 +578,23 @@ def score_files(
                 score += _summary_boost_weight(field, value, amount) * match_weight
                 reasons.append(f"{label}: {_short_reason_value(value)}")
 
+            naming_keywords = _summary_values(summary_data, "naming_keywords")
+            naming_signals = _summary_values(summary_data, "naming_signals")
+            naming_match = _best_summary_match(naming_keywords, keywords)
+            if naming_match:
+                value, match_weight = naming_match
+                score += min(20.0, match_weight * 18.0)
+                reasons.append(f"matched naming keyword: {_short_reason_value(value)}")
+
+            generic_public_names = [
+                value.split(": ", 1)[1]
+                for value in naming_signals
+                if value.startswith("generic public name: ")
+            ]
+            if generic_public_names and filename_weight == 0 and symbol_weight == 0:
+                score += min(-6.0, w.weak_filename_match_penalty / 2)
+                reasons.append(f"generic public API penalty: {generic_public_names[0]}")
+
         content_hits = 0
         if fi.content is not None:
             hits, hit_weight = _content_matches_keywords(fi.content, keywords)

{agentpack_cli-0.3.1 → agentpack_cli-0.3.2}/src/agentpack/core/models.py

@@ -64,6 +64,8 @@ class FileSummary(BaseModel):
     ranking_keywords: list[str] = Field(default_factory=list)
     related_hints: list[str] = Field(default_factory=list)
     public_api: list[str] = Field(default_factory=list)
+    naming_signals: list[str] = Field(default_factory=list)
+    naming_keywords: list[str] = Field(default_factory=list)
     error_paths: list[str] = Field(default_factory=list)
     test_hints: list[str] = Field(default_factory=list)
 

{agentpack_cli-0.3.1 → agentpack_cli-0.3.2}/src/agentpack/data/agentpack.md

@@ -82,25 +82,34 @@ Then read `.agentpack/context.claude.md` in full.
 ### Step 1: Check agentpack is installed
 
 ```bash
-agentpack --help 2>/dev/null || pipx install agentpack-cli
+if command -v pipx >/dev/null 2>&1; then
+  export AGENTPACK_BIN="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+  test -x "$AGENTPACK_BIN" || pipx install agentpack-cli
+elif command -v agentpack >/dev/null 2>&1; then
+  export AGENTPACK_BIN="$(command -v agentpack)"
+else
+  python3 -m venv .venv
+  "$PWD/.venv/bin/pip" install agentpack-cli
+  export AGENTPACK_BIN="$PWD/.venv/bin/agentpack"
+fi
 ```
 
 ### Step 2: Initialize if not already done
 
 ```bash
-test -f .agentpack/config.toml || agentpack init --yes
+test -f .agentpack/config.toml || "$AGENTPACK_BIN" init --yes
 ```
 
 ### Step 3: Determine workflow
 
 **Session active** (`.agentpack/session.json` exists, `"active": true`):
 - Update `.agentpack/task.md` if task changed
-- Run `agentpack pack --task auto` unless watch already refreshed it
+- Run `"$AGENTPACK_BIN" pack --task auto` unless watch already refreshed it
 - Read `.agentpack/context.md`
 - Proceed immediately
 
 **No session**:
-- Run `agentpack session start` or `agentpack pack --task auto`
+- Run `"$AGENTPACK_BIN" session start` or `"$AGENTPACK_BIN" pack --task auto`
 - Read the context file
 - Proceed
 
@@ -116,9 +125,9 @@ Do not say "context pack ready" and stop. Do not tell the user to run more comma
 
 ## Stale pack handling
 
-If `agentpack status` exits non-zero or context seems unrelated to the task:
-- Run `agentpack session refresh` (if session active)
-- Or run `agentpack pack --task auto` (manual mode)
+If `"$AGENTPACK_BIN" status` exits non-zero or context seems unrelated to the task:
+- Run `"$AGENTPACK_BIN" session refresh` (if session active)
+- Or run `"$AGENTPACK_BIN" pack --task auto` (manual mode)
 - Re-read the context, then proceed
 
 Do not ask the user — just refresh and proceed.
@@ -126,9 +135,9 @@ Do not ask the user — just refresh and proceed.
 ## Debugging selection
 
 ```bash
-agentpack explain --task auto                          # show ranked file list
-agentpack explain --file src/auth/session.py           # per-file score breakdown
-agentpack explain --omitted                            # see what was excluded and why
+"$AGENTPACK_BIN" explain --task auto                   # show ranked file list
+"$AGENTPACK_BIN" explain --file src/auth/session.py    # per-file score breakdown
+"$AGENTPACK_BIN" explain --omitted                     # see what was excluded and why
 ```
 
 ## Subcommand routing

{agentpack_cli-0.3.1 → agentpack_cli-0.3.2}/src/agentpack/summaries/offline.py

@@ -10,6 +10,7 @@ from agentpack.analysis.role_inference import (
     extract_side_effects,
     infer_role_domain,
 )
+from agentpack.analysis.naming_signals import collect_public_name_candidates, summarize_naming_signals
 from agentpack.analysis.symbols import extract_python_symbols, extract_js_symbols
 from agentpack.analysis.python_imports import extract_imports as py_imports
 from agentpack.analysis.js_ts_imports import extract_imports as js_imports
@@ -42,6 +43,8 @@ def _python_summary(path: str, abs_path: Path, file_hash: str) -> FileSummary:
     role = role_info.role or _infer_responsibility(path, intel.defines)
     failure_hints = extract_failure_hints(text)
     public_api = _dedupe([*_infer_public_api(path, intel.defines, text), *intel.entrypoints])[:12]
+    public_names = collect_public_name_candidates(abs_path, "python")
+    naming_signals, naming_keywords = summarize_naming_signals(path, public_names, effects.reads_env)
     test_hints = _infer_test_hints(path, role, intel.defines)
     summary_text = _render_summary(
         language="Python",
@@ -81,6 +84,8 @@ def _python_summary(path: str, abs_path: Path, file_hash: str) -> FileSummary:
         ranking_keywords=role_info.ranking_keywords,
         related_hints=role_info.reasons,
         public_api=public_api,
+        naming_signals=naming_signals,
+        naming_keywords=naming_keywords,
         error_paths=failure_hints,
         test_hints=test_hints,
     )
@@ -105,6 +110,8 @@ def _js_summary(path: str, abs_path: Path, language: str, file_hash: str) -> Fil
     role = role_info.role or _infer_responsibility(path, intel.defines)
     failure_hints = extract_failure_hints(text)
     public_api = _dedupe([*_infer_public_api(path, intel.defines, text), *intel.entrypoints])[:12]
+    public_names = collect_public_name_candidates(abs_path, language)
+    naming_signals, naming_keywords = summarize_naming_signals(path, public_names, effects.reads_env)
     test_hints = _infer_test_hints(path, role, intel.defines)
     summary_text = _render_summary(
         language=language.capitalize(),
@@ -144,6 +151,8 @@ def _js_summary(path: str, abs_path: Path, language: str, file_hash: str) -> Fil
         ranking_keywords=role_info.ranking_keywords,
         related_hints=role_info.reasons,
         public_api=public_api,
+        naming_signals=naming_signals,
+        naming_keywords=naming_keywords,
         error_paths=failure_hints,
         test_hints=test_hints,
     )
@@ -206,6 +215,8 @@ def _generic_summary(path: str, abs_path: Path, language: str | None, file_hash:
         ranking_keywords=role_info.ranking_keywords,
         related_hints=role_info.reasons,
         public_api=[],
+        naming_signals=[],
+        naming_keywords=[],
         error_paths=failure_hints,
         test_hints=_infer_test_hints(path, role, []),
     )