agent-notes 2.32.0__tar.gz → 2.33.1__tar.gz

{agent_notes-2.32.0 → agent_notes-2.33.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.32.0
+Version: 2.33.1
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -13,21 +13,21 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-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 :: Code Generators
 Classifier: Topic :: Utilities
 Classifier: Environment :: Console
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Requires-Dist: tomli-w>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
 Dynamic: license-file
 
 # agent-notes
@@ -37,14 +37,16 @@ AI agent configuration manager for Claude Code and OpenCode — orchestrates a t
 ## Quick Start
 
 ```bash
-pip install agent-notes
+pipx install agent-notes
 agent-notes install    # interactive wizard guides you through setup
 agent-notes doctor
 ```
 
+> No `pipx`? Use `uv tool install agent-notes` instead, or see **Troubleshooting: externally-managed-environment** below.
+
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 50+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 25 on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails (including a ban on AI self-attribution in commits/PRs)
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -63,6 +65,13 @@ pipx install agent-notes
 agent-notes install
 ```
 
+**uv tool (lightweight alternative to pipx):**
+
+```bash
+uv tool install agent-notes
+agent-notes install
+```
+
 **venv + pip (if you prefer to manage your own environment):**
 
 ```bash
@@ -96,6 +105,7 @@ agent-notes uninstall && pipx uninstall agent-notes && pipx install agent-notes
 
 With venv:
 ```bash
+source .venv/bin/activate
 agent-notes uninstall && pip uninstall agent-notes && pip install agent-notes && agent-notes install
 ```
 
@@ -119,6 +129,38 @@ To produce a release artifact (wheel for distribution), use `python -m build` +
 
 The plugin runs a `session.start` hook that surfaces agent-notes context to the CLI session. It does **not** include the full `agent-notes` CLI (wizard, doctor, config, memory, etc.). For those, use install method 1 or 2.
 
+---
+
+**Note on two meanings of "plugin":** This distribution plugin (the `.claude-plugin/` marketplace artifact) is distinct from **agent-notes plugins** — an internal toggleable subsystem documented below. See [Plugins](#plugins) to tell them apart.
+
+### Plugins (toggleable subsystems)
+
+Agent-notes includes toggleable subsystems (plugins) that can be enabled or disabled post-install. Currently, only **cost-report** is available as a plugin.
+
+**List available plugins:**
+```bash
+agent-notes plugins list
+```
+
+Example output:
+```
+  cost-report          [off]  Emit a per-session token cost report at the Stop hook
+```
+
+**Enable or disable a plugin:**
+```bash
+agent-notes plugins enable cost-report   # Enable cost-report
+agent-notes plugins disable cost-report  # Disable cost-report
+agent-notes install                      # Apply changes
+```
+
+**Show plugin details:**
+```bash
+agent-notes plugins info cost-report
+```
+
+After enabling or disabling a plugin, run `agent-notes install` to apply the changes. For details, see `docs/WRITING_A_PLUGIN.md`.
+
 ### API keys
 
 Provider API keys live in `~/.agent-notes/credentials.toml` (mode 0600, never committed). Add or update via:
@@ -135,6 +177,46 @@ agent-notes config provider openrouter   # prints "configured" or "no key"
 
 </details>
 
+### Troubleshooting: externally-managed-environment
+
+On Arch, Debian, Ubuntu, and other distributions that mark the system Python as externally-managed (PEP 668), you may see an error like:
+
+```
+error: externally-managed-environment
+
+× This environment is externally managed
+```
+
+This error occurs because `pip` refuses to install into the system Python. **Solution:** use an isolated package manager instead:
+
+1. **Recommended — pipx:**
+   ```bash
+   pipx install agent-notes
+   agent-notes install
+   ```
+
+2. **Alternative — uv tool:**
+   ```bash
+   uv tool install agent-notes
+   agent-notes install
+   ```
+
+3. **Alternative — Create a venv first:**
+   ```bash
+   python -m venv .venv && source .venv/bin/activate
+   pip install agent-notes
+   agent-notes install
+   ```
+
+**Last resort only** (discouraged — system packages may conflict):
+```bash
+pip install --user agent-notes
+# or
+pip install --break-system-packages agent-notes
+```
+
+---
+
 <details>
 <summary>Uninstall</summary>
 
@@ -170,7 +252,7 @@ If you configured agent-notes to access your memory vault (Obsidian or local), t
 <details>
 <summary>Agent Team</summary>
 
-Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+Specialized subagents with hierarchical model strategy: **Opus 4.8 reasons (high effort), Sonnet 5 executes (medium effort), Haiku 4.5 scouts (low effort).**
 
 | Agent | Role | Model Tier | Purpose |
 |---|---|---|---|
@@ -194,7 +276,7 @@ Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonn
 | analyst | scout | haiku | Requirements translation, acceptance criteria |
 | tech-writer | scout | haiku | READMEs, API docs, changelogs |
 
-**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($5/$25 per 1M tokens in/out), Sonnet executes ($3/$15), Haiku scouts ($1/$5). A premium `fable` tier ($10/$50) is available for explicit pinning, but no role defaults to it.
 
 ### Delegation rules
 
@@ -216,6 +298,18 @@ Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonn
 - **tech-writer** — Documentation, READMEs, API docs
 - **devil** — Challenges assumptions and plans
 
+### Reconfiguring roles, models, and effort
+
+During `agent-notes install`, wizard step 2 asks you to pick a model per role, and — for models served by a provider with a known effort vocabulary (currently `anthropic`, `openai`) — a follow-up effort prompt, pre-selected to the role's typical effort when that value is valid for the chosen provider. Providers with no effort registry entry (`github-copilot`, `openrouter`, `google`, `moonshot`) skip the effort prompt entirely.
+
+To change these after install:
+```bash
+agent-notes config role-model [--cli <cli>] <role> <model>    # e.g. role-model worker claude-sonnet-5
+agent-notes config role-effort [--cli <cli>] <role> <effort>  # e.g. role-effort worker high
+agent-notes config wizard                                     # interactive menu for both
+```
+`role-effort` validates the effort against the role's currently-assigned model's provider — an invalid value prints that provider's name and its valid effort list. There's no cross-provider mapping: each provider (anthropic, openai) has its own independent effort vocabulary and default.
+
 </details>
 
 ---
@@ -282,7 +376,7 @@ agent-notes memory lint               # health-check
 <details>
 <summary>Skills</summary>
 
-50+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+25 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`. For additional workflows (brainstorming, test-driven development, writing skills), see the complementary [Superpowers](https://github.com/obra/superpowers) plugin.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -299,14 +393,13 @@ Load the docker-compose skill for multi-service setup
 |---|---|---|
 | Misalignment | Claude starts building before the problem is resolved | `/grill-me`, `/grilling`, `/grill-with-docs` |
 | Vague scope | Work starts without a spec or ticketed breakdown | `/to-spec`, `/to-tickets`, `/wayfinder`, `/triage` |
-| Broken code | Claude codes without a feedback loop or evidence trail | `/tdd`, `/diagnosing-bugs` |
+| Broken code | Claude codes without a feedback loop or evidence trail | `/diagnosing-bugs` |
 | Ball of mud | Architecture drifts; modules grow shallow and tangled | `/improve-codebase-architecture`, `/codebase-design`, `/domain-modeling` |
 
 **Skill descriptions:**
 
 - `/grill-me`, `/grilling` — Interview the user relentlessly until the plan is fully resolved before touching code
 - `/grill-with-docs` — Same, but cross-references CONTEXT.md and ADRs and updates them inline
-- `/tdd` — RED-GREEN-REFACTOR with tracer-bullet vertical slices; integration-first testing
 - `/diagnosing-bugs` — Diagnosis loop for hard bugs and performance regressions (build a feedback loop first)
 - `/improve-codebase-architecture` — Scan for deepening opportunities, present a visual HTML report, then grill the chosen one
 - `/codebase-design` — Shared vocabulary for designing deep modules and choosing where seams go
@@ -319,7 +412,6 @@ Load the docker-compose skill for multi-service setup
 - `/research` — Investigate a question against primary sources and capture findings as Markdown
 - `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
 - `/setup-agent-tracker` — One-time per-repo setup of the issue tracker, triage labels, and domain doc layout
-- `/writing-great-skills` — Reference for writing and editing skills well
 
 </details>
 
@@ -419,7 +511,7 @@ agent-notes config provider <name>      # check if configured (without exposing
 
 ### Building and testing
 
-Python 3.10+ required. Create an isolated environment and run tests:
+Python 3.11+ required. Create an isolated environment and run tests:
 
 ```bash
 python -m venv .venv && source .venv/bin/activate
@@ -512,7 +604,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI
 ## Inspired by
 
 - [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
-- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, broken code, architectural degradation), and a set of engineering/productivity skills vendored from the upstream repo (tdd, grill-me, grilling, grill-with-docs, diagnosing-bugs, improve-codebase-architecture, codebase-design, domain-modeling, prototype, handoff, research, to-spec, to-tickets, triage, wayfinder, writing-great-skills). Last synced from upstream commit [`391a270`](https://github.com/mattpocock/skills/commit/391a2701dd948f94f56a39f7533f8eea9a859c87) (2026-07-10), reviewed for prompt-injection before import.
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, broken code, architectural degradation), and a set of engineering/productivity skills vendored from the upstream repo (grill-me, grilling, grill-with-docs, diagnosing-bugs, improve-codebase-architecture, codebase-design, domain-modeling, prototype, handoff, research, to-spec, to-tickets, triage, wayfinder). Last synced from upstream commit [`391a270`](https://github.com/mattpocock/skills/commit/391a2701dd948f94f56a39f7533f8eea9a859c87) (2026-07-10), reviewed for prompt-injection before import.
 
 ## License
 

{agent_notes-2.32.0 → agent_notes-2.33.1}/README.md

@@ -5,14 +5,16 @@ AI agent configuration manager for Claude Code and OpenCode — orchestrates a t
 ## Quick Start
 
 ```bash
-pip install agent-notes
+pipx install agent-notes
 agent-notes install    # interactive wizard guides you through setup
 agent-notes doctor
 ```
 
+> No `pipx`? Use `uv tool install agent-notes` instead, or see **Troubleshooting: externally-managed-environment** below.
+
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 50+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 25 on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails (including a ban on AI self-attribution in commits/PRs)
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -31,6 +33,13 @@ pipx install agent-notes
 agent-notes install
 ```
 
+**uv tool (lightweight alternative to pipx):**
+
+```bash
+uv tool install agent-notes
+agent-notes install
+```
+
 **venv + pip (if you prefer to manage your own environment):**
 
 ```bash
@@ -64,6 +73,7 @@ agent-notes uninstall && pipx uninstall agent-notes && pipx install agent-notes
 
 With venv:
 ```bash
+source .venv/bin/activate
 agent-notes uninstall && pip uninstall agent-notes && pip install agent-notes && agent-notes install
 ```
 
@@ -87,6 +97,38 @@ To produce a release artifact (wheel for distribution), use `python -m build` +
 
 The plugin runs a `session.start` hook that surfaces agent-notes context to the CLI session. It does **not** include the full `agent-notes` CLI (wizard, doctor, config, memory, etc.). For those, use install method 1 or 2.
 
+---
+
+**Note on two meanings of "plugin":** This distribution plugin (the `.claude-plugin/` marketplace artifact) is distinct from **agent-notes plugins** — an internal toggleable subsystem documented below. See [Plugins](#plugins) to tell them apart.
+
+### Plugins (toggleable subsystems)
+
+Agent-notes includes toggleable subsystems (plugins) that can be enabled or disabled post-install. Currently, only **cost-report** is available as a plugin.
+
+**List available plugins:**
+```bash
+agent-notes plugins list
+```
+
+Example output:
+```
+  cost-report          [off]  Emit a per-session token cost report at the Stop hook
+```
+
+**Enable or disable a plugin:**
+```bash
+agent-notes plugins enable cost-report   # Enable cost-report
+agent-notes plugins disable cost-report  # Disable cost-report
+agent-notes install                      # Apply changes
+```
+
+**Show plugin details:**
+```bash
+agent-notes plugins info cost-report
+```
+
+After enabling or disabling a plugin, run `agent-notes install` to apply the changes. For details, see `docs/WRITING_A_PLUGIN.md`.
+
 ### API keys
 
 Provider API keys live in `~/.agent-notes/credentials.toml` (mode 0600, never committed). Add or update via:
@@ -103,6 +145,46 @@ agent-notes config provider openrouter   # prints "configured" or "no key"
 
 </details>
 
+### Troubleshooting: externally-managed-environment
+
+On Arch, Debian, Ubuntu, and other distributions that mark the system Python as externally-managed (PEP 668), you may see an error like:
+
+```
+error: externally-managed-environment
+
+× This environment is externally managed
+```
+
+This error occurs because `pip` refuses to install into the system Python. **Solution:** use an isolated package manager instead:
+
+1. **Recommended — pipx:**
+   ```bash
+   pipx install agent-notes
+   agent-notes install
+   ```
+
+2. **Alternative — uv tool:**
+   ```bash
+   uv tool install agent-notes
+   agent-notes install
+   ```
+
+3. **Alternative — Create a venv first:**
+   ```bash
+   python -m venv .venv && source .venv/bin/activate
+   pip install agent-notes
+   agent-notes install
+   ```
+
+**Last resort only** (discouraged — system packages may conflict):
+```bash
+pip install --user agent-notes
+# or
+pip install --break-system-packages agent-notes
+```
+
+---
+
 <details>
 <summary>Uninstall</summary>
 
@@ -138,7 +220,7 @@ If you configured agent-notes to access your memory vault (Obsidian or local), t
 <details>
 <summary>Agent Team</summary>
 
-Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+Specialized subagents with hierarchical model strategy: **Opus 4.8 reasons (high effort), Sonnet 5 executes (medium effort), Haiku 4.5 scouts (low effort).**
 
 | Agent | Role | Model Tier | Purpose |
 |---|---|---|---|
@@ -162,7 +244,7 @@ Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonn
 | analyst | scout | haiku | Requirements translation, acceptance criteria |
 | tech-writer | scout | haiku | READMEs, API docs, changelogs |
 
-**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($5/$25 per 1M tokens in/out), Sonnet executes ($3/$15), Haiku scouts ($1/$5). A premium `fable` tier ($10/$50) is available for explicit pinning, but no role defaults to it.
 
 ### Delegation rules
 
@@ -184,6 +266,18 @@ Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonn
 - **tech-writer** — Documentation, READMEs, API docs
 - **devil** — Challenges assumptions and plans
 
+### Reconfiguring roles, models, and effort
+
+During `agent-notes install`, wizard step 2 asks you to pick a model per role, and — for models served by a provider with a known effort vocabulary (currently `anthropic`, `openai`) — a follow-up effort prompt, pre-selected to the role's typical effort when that value is valid for the chosen provider. Providers with no effort registry entry (`github-copilot`, `openrouter`, `google`, `moonshot`) skip the effort prompt entirely.
+
+To change these after install:
+```bash
+agent-notes config role-model [--cli <cli>] <role> <model>    # e.g. role-model worker claude-sonnet-5
+agent-notes config role-effort [--cli <cli>] <role> <effort>  # e.g. role-effort worker high
+agent-notes config wizard                                     # interactive menu for both
+```
+`role-effort` validates the effort against the role's currently-assigned model's provider — an invalid value prints that provider's name and its valid effort list. There's no cross-provider mapping: each provider (anthropic, openai) has its own independent effort vocabulary and default.
+
 </details>
 
 ---
@@ -250,7 +344,7 @@ agent-notes memory lint               # health-check
 <details>
 <summary>Skills</summary>
 
-50+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+25 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`. For additional workflows (brainstorming, test-driven development, writing skills), see the complementary [Superpowers](https://github.com/obra/superpowers) plugin.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -267,14 +361,13 @@ Load the docker-compose skill for multi-service setup
 |---|---|---|
 | Misalignment | Claude starts building before the problem is resolved | `/grill-me`, `/grilling`, `/grill-with-docs` |
 | Vague scope | Work starts without a spec or ticketed breakdown | `/to-spec`, `/to-tickets`, `/wayfinder`, `/triage` |
-| Broken code | Claude codes without a feedback loop or evidence trail | `/tdd`, `/diagnosing-bugs` |
+| Broken code | Claude codes without a feedback loop or evidence trail | `/diagnosing-bugs` |
 | Ball of mud | Architecture drifts; modules grow shallow and tangled | `/improve-codebase-architecture`, `/codebase-design`, `/domain-modeling` |
 
 **Skill descriptions:**
 
 - `/grill-me`, `/grilling` — Interview the user relentlessly until the plan is fully resolved before touching code
 - `/grill-with-docs` — Same, but cross-references CONTEXT.md and ADRs and updates them inline
-- `/tdd` — RED-GREEN-REFACTOR with tracer-bullet vertical slices; integration-first testing
 - `/diagnosing-bugs` — Diagnosis loop for hard bugs and performance regressions (build a feedback loop first)
 - `/improve-codebase-architecture` — Scan for deepening opportunities, present a visual HTML report, then grill the chosen one
 - `/codebase-design` — Shared vocabulary for designing deep modules and choosing where seams go
@@ -287,7 +380,6 @@ Load the docker-compose skill for multi-service setup
 - `/research` — Investigate a question against primary sources and capture findings as Markdown
 - `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
 - `/setup-agent-tracker` — One-time per-repo setup of the issue tracker, triage labels, and domain doc layout
-- `/writing-great-skills` — Reference for writing and editing skills well
 
 </details>
 
@@ -387,7 +479,7 @@ agent-notes config provider <name>      # check if configured (without exposing
 
 ### Building and testing
 
-Python 3.10+ required. Create an isolated environment and run tests:
+Python 3.11+ required. Create an isolated environment and run tests:
 
 ```bash
 python -m venv .venv && source .venv/bin/activate
@@ -480,7 +572,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI
 ## Inspired by
 
 - [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
-- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, broken code, architectural degradation), and a set of engineering/productivity skills vendored from the upstream repo (tdd, grill-me, grilling, grill-with-docs, diagnosing-bugs, improve-codebase-architecture, codebase-design, domain-modeling, prototype, handoff, research, to-spec, to-tickets, triage, wayfinder, writing-great-skills). Last synced from upstream commit [`391a270`](https://github.com/mattpocock/skills/commit/391a2701dd948f94f56a39f7533f8eea9a859c87) (2026-07-10), reviewed for prompt-injection before import.
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, broken code, architectural degradation), and a set of engineering/productivity skills vendored from the upstream repo (grill-me, grilling, grill-with-docs, diagnosing-bugs, improve-codebase-architecture, codebase-design, domain-modeling, prototype, handoff, research, to-spec, to-tickets, triage, wayfinder). Last synced from upstream commit [`391a270`](https://github.com/mattpocock/skills/commit/391a2701dd948f94f56a39f7533f8eea9a859c87) (2026-07-10), reviewed for prompt-injection before import.
 
 ## License
 

agent_notes-2.33.1/agent_notes/VERSION

@@ -0,0 +1 @@
+2.33.1

{agent_notes-2.32.0 → agent_notes-2.33.1}/agent_notes/cli.py

@@ -283,7 +283,7 @@ def main():
     # memory
     p_memory = subparsers.add_parser("memory", help="Manage agent memory")
     p_memory.add_argument("action", nargs="?", default="list",
-        choices=["init", "list", "vault", "index", "add", "size", "show", "reset", "export", "import", "ingest", "query", "lint"],
+        choices=["init", "list", "vault", "index", "add", "size", "show", "reset", "export", "import"],
         help="Memory action")
     p_memory.add_argument("name", nargs="?", help="Agent name / note title (for show/reset/add)")
     p_memory.add_argument("extra", nargs="*", help="Additional args (for add: body [type] [agent] [project])")
@@ -299,10 +299,31 @@ def main():
     p_cost_report.add_argument("--since", help="Only include messages at or after this UTC datetime (ISO 8601)")
     p_cost_report.add_argument("--session", help="Session ID to report on (Claude Code only)")
 
+    # models
+    p_models = subparsers.add_parser("models", help="Manage the model catalog")
+    p_models_sub = p_models.add_subparsers(dest="subaction", metavar="")
+    p_refresh = p_models_sub.add_parser("refresh", help="Fetch latest models from providers and update cache")
+    p_refresh.add_argument("--provider", choices=["anthropic", "openai"],
+        help="Limit to one provider")
+    p_refresh.add_argument("--dry-run", action="store_true", dest="dry_run",
+        help="Print diff but do not write cache")
+    p_models_sub.add_parser("freeze", help="Promote cache to seed.json for committing")
+
+    # plugins
+    p_plugins = subparsers.add_parser("plugins", help="Manage agent-notes plugins")
+    p_plugins_sub = p_plugins.add_subparsers(dest="subaction", metavar="{list,enable,disable,info}")
+    p_plugins_sub.add_parser("list", help="List available plugins and their status")
+    p_plugins_enable = p_plugins_sub.add_parser("enable", help="Enable a plugin")
+    p_plugins_enable.add_argument("name", help="Plugin name")
+    p_plugins_disable = p_plugins_sub.add_parser("disable", help="Disable a plugin")
+    p_plugins_disable.add_argument("name", help="Plugin name")
+    p_plugins_info = p_plugins_sub.add_parser("info", help="Show details for a plugin")
+    p_plugins_info.add_argument("name", help="Plugin name")
+
     # config
     p_config = subparsers.add_parser("config", help="Reconfigure role/agent/model/memory/skill assignments after install")
     p_config.add_argument("action", nargs="?", default="wizard",
-        choices=["wizard", "show", "role-model", "role-agent", "provider", "providers", "memory", "cost-report"],
+        choices=["wizard", "show", "role-model", "role-agent", "role-effort", "provider", "providers", "memory", "cost-report"],
         help="Config action (default: wizard)")
     p_config.add_argument("extra", nargs="*", help="Additional positional args (role, model, agent)")
     p_config.add_argument("--cli", help="Target CLI (claude / opencode / both)")
@@ -364,6 +385,35 @@ def main():
     elif args.command == "memory":
         from .commands.memory import memory
         memory(args.action, args.name, getattr(args, "extra", None), description=getattr(args, "description", ""))
+    elif args.command == "models":
+        subaction = getattr(args, "subaction", None)
+        if subaction == "refresh":
+            from .commands.models import refresh
+            refresh(
+                provider=getattr(args, "provider", None),
+                dry_run=getattr(args, "dry_run", False),
+            )
+        elif subaction == "freeze":
+            from .commands.models import freeze
+            freeze()
+        else:
+            parser.parse_args(["models", "--help"])
+    elif args.command == "plugins":
+        subaction = getattr(args, "subaction", None)
+        if subaction == "list":
+            from .commands.plugins import list_plugins
+            list_plugins()
+        elif subaction == "enable":
+            from .commands.plugins import enable_plugin
+            enable_plugin(args.name)
+        elif subaction == "disable":
+            from .commands.plugins import disable_plugin
+            disable_plugin(args.name)
+        elif subaction == "info":
+            from .commands.plugins import info_plugin
+            info_plugin(args.name)
+        else:
+            parser.parse_args(["plugins", "--help"])
     elif args.command == "config":
         from .commands.config import config
         config(action=args.action, args=getattr(args, "extra", None) or [], cli_filter=args.cli)
@@ -371,20 +421,10 @@ def main():
         from .commands.hook import hook
         hook(args.subaction)
     elif args.command == "cost-report":
-        # Rebuild sys.argv slice so cost_report.main() can parse it normally
-        argv = []
-        if args.since:
-            argv += ["--since", args.since]
-        if args.session:
-            argv += ["--session", args.session]
-        import sys
-        old_argv = sys.argv
-        sys.argv = ["agent-notes cost-report"] + argv
-        try:
-            from .scripts.cost_report import main as _cost_report_main
-            sys.exit(_cost_report_main())
-        finally:
-            sys.argv = old_argv
+        from .cost.cost_report import main as _cost_report_main, _parse_since
+        since = _parse_since(args.since) if args.since else None
+        session_id = args.session or None
+        sys.exit(_cost_report_main(since=since, session_id=session_id))
 
 if __name__ == "__main__":
     main()

{agent_notes-2.32.0 → agent_notes-2.33.1}/agent_notes/commands/_install_helpers.py

@@ -188,7 +188,7 @@ def count_agents(backend) -> int:
         return 0
     from ..registries.agent_registry import load_agent_registry
     registry = load_agent_registry()
-    return sum(1 for a in registry.all() if not a.excluded_from(backend.name))
+    return sum(1 for a in registry.available() if not a.excluded_from(backend.name))
 
 
 def count_global() -> int:

{agent_notes-2.32.0 → agent_notes-2.33.1}/agent_notes/commands/build.py

@@ -89,24 +89,60 @@ def count_lines(file_path: Path) -> int:
         return 0
 
 
-def build() -> None:
-    """Build agent configuration files from source."""
+def count_dist_clis(files: list[Path], dist_dir: Path, cli_names: set[str]) -> int:
+    """Count distinct CLI backends among generated files (dist/<cli>/... paths).
+
+    Files outside dist_dir or under non-CLI top-level dirs (rules/, skills/)
+    are ignored."""
+    found = set()
+    for f in files:
+        try:
+            rel = f.relative_to(dist_dir)
+        except ValueError:
+            continue
+        if rel.parts and rel.parts[0] in cli_names:
+            found.add(rel.parts[0])
+    return len(found)
+
+
+def format_build_summary(n_files: int, n_lines: int, n_clis: int) -> str:
+    """One-line build summary, e.g. 'Generated 96 files (13,748 lines) across 4 CLIs'."""
+    file_word = "file" if n_files == 1 else "files"
+    cli_word = "CLI" if n_clis == 1 else "CLIs"
+    return f"Generated {n_files} {file_word} ({n_lines:,} lines) across {n_clis} {cli_word}"
+
+
+def build(role_models=None, role_efforts=None, scope='global', project_path=None,
+          profile_label: str = "") -> None:
+    """Build agent configuration files from source.
+
+    Args:
+        role_models: Optional explicit {cli: {role: model_id}} pins that override
+            persisted state (e.g. wizard selections not yet written to state.json)
+        role_efforts: Optional explicit {cli: {role: effort}} pins, same semantics
+        scope: which state.json scope's pins drive the render ('global' or 'local')
+        project_path: project path for scope='local'
+        profile_label: named profile whose pins drive the render ("" = default profile)
+    """
     from ..services.state_store import load_state
-    from ..config import ROOT
+    from ..registries.cli_registry import load_registry
 
     # Read configuration
     try:
-        agents_config, tiers = load_agents_config()
+        agents_config = load_agents_config()
     except FileNotFoundError as e:
         print(f"Error: {e}")
         return
 
     # Load state if present (no error if missing)
     state = load_state()
-    
+
     # Generate agent files (state=None is backward compatible)
     print("Generating agent files...")
-    agent_files = generate_agent_files(agents_config, tiers, state=state)
+    agent_files = generate_agent_files(agents_config, state=state,
+                                       scope=scope, project_path=project_path,
+                                       role_models=role_models, role_efforts=role_efforts,
+                                       profile_label=profile_label)
     
     # Copy global files
     print("Copying global files...")
@@ -120,21 +156,12 @@ def build() -> None:
     print("Copying commands...")
     command_files = copy_commands()
 
-    # Report results
+    # Report results — one-line summary (per-file listing was too noisy)
     all_files = agent_files + global_files + skill_files + command_files
-    print(f"\nGenerated {len(all_files)} files:")
-    
-    total_lines = 0
-    for file_path in sorted(all_files):
-        try:
-            rel_path = file_path.relative_to(ROOT)
-        except ValueError:
-            rel_path = file_path  # absolute path if outside the package tree
-        lines = count_lines(file_path)
-        total_lines += lines
-        print(f"  {rel_path} ({lines} lines)")
-    
-    print(f"\nTotal: {total_lines} lines across {len(all_files)} files")
+    total_lines = sum(count_lines(f) for f in all_files)
+    cli_names = {b.name for b in load_registry().all()}
+    n_clis = count_dist_clis(all_files, DIST_DIR, cli_names)
+    print(f"\n{format_build_summary(len(all_files), total_lines, n_clis)}")
 
 
 if __name__ == '__main__':