docs(agents): update AGENTS.md files to reflect current codebase

- Add prerequisites.py module (20→21 modules)
- Add cleanup.sh, reset_pins.sh scripts (28→30 scripts)
- Add test_prerequisites.py (12→13 test files)
- Update catalog count (78→79 entries)
- Add new make targets: cleanup, upgrade-ignore-pins, reset-pins, upgrade-all

Author: CybotTM

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-01-16 -->
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-02-06 -->
 
 # AGENTS.md (root)
 
@@ -41,9 +41,9 @@ uv run python audit.py --help    # Verify CLI works
 
 ## Index of scoped AGENTS.md
 
-- [cli_audit/AGENTS.md](./cli_audit/AGENTS.md) — Python package (20 modules)
-- [scripts/AGENTS.md](./scripts/AGENTS.md) — Installation scripts (Bash)
-- [tests/AGENTS.md](./tests/AGENTS.md) — Test suite (pytest)
+- [cli_audit/AGENTS.md](./cli_audit/AGENTS.md) — Python package (21 modules)
+- [scripts/AGENTS.md](./scripts/AGENTS.md) — Installation scripts (Bash, 30 scripts)
+- [tests/AGENTS.md](./tests/AGENTS.md) — Test suite (pytest, 14 test files)
 
 ## Quick reference
 
@@ -60,8 +60,12 @@ uv run python audit.py --help    # Verify CLI works
 | `make update-local` | Update only local state (no network) |
 | `make update-baseline` | Update upstream baseline for commit |
 | `make upgrade` | Interactive upgrade guide |
+| `make cleanup` | Interactive tool removal |
 | `make upgrade-managed` | Upgrade all package managers |
 | `make upgrade-dry-run` | Preview upgrades without changes |
+| `make upgrade-ignore-pins` | Upgrade guide ignoring version pins |
+| `make reset-pins` | Remove all version pins |
+| `make upgrade-all` | Full system upgrade (data + managers + tools) |
 | `./scripts/set_auto_update.sh <tool>` | Enable auto-update for a tool |
 | `uv run python audit.py --versions` | Show multi-version runtime status |
 | `uv run python audit.py --versions php` | Show specific runtime versions |
@@ -79,7 +83,7 @@ uv run python audit.py --help    # Verify CLI works
 
 **AI CLI Preparation v2.0** — Tool version auditing and installation management for AI coding agents.
 
-- **Architecture:** 20 Python modules, 78 JSON tool catalogs
+- **Architecture:** 21 Python modules, 79 JSON tool catalogs
 - **Phase 1:** Detection & auditing (complete)
 - **Phase 2:** Installation & upgrade management (complete)
 - **Entry point:** `audit.py` → `cli_audit` package

cli_audit/AGENTS.md

@@ -1,16 +1,16 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-16 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-02-06 -->
 
 # cli_audit/ — Python Package
 
-**Modular architecture** with 20 specialized modules for tool detection, auditing, installation, and upgrade management.
+**Modular architecture** with 21 specialized modules for tool detection, auditing, installation, and upgrade management.
 
 ## Overview
 
 The `cli_audit` package provides the core functionality for AI CLI Preparation:
 
 **Phase 1: Detection & Auditing (6 modules)**
 - `tools.py` — Tool definitions and metadata
-- `catalog.py` — JSON catalog management (78 entries)
+- `catalog.py` — JSON catalog management (79 entries)
 - `detection.py` — Installation detection, version extraction, multi-version detection
 - `collectors.py` — Upstream version collection (GitHub, PyPI, npm, crates, endoflife.date)
 - `snapshot.py` — Snapshot-based caching
@@ -23,9 +23,10 @@ The `cli_audit` package provides the core functionality for AI CLI Preparation:
 - `package_managers.py` — Package manager abstractions
 - `logging_config.py` — Logging configuration
 
-**Phase 2: Installation & Upgrade (4 modules)**
+**Phase 2: Installation & Upgrade (5 modules)**
 - `installer.py` — Tool installation with retry/validation
 - `install_plan.py` — Installation planning, dependency resolution
+- `prerequisites.py` — Prerequisite resolution and dependency chain handling
 - `bulk.py` — Parallel bulk operations
 - `upgrade.py` — Upgrade workflows
 
@@ -51,7 +52,7 @@ local_state.json        # Gitignored - machine-specific installation state
 ~/.config/cli-audit/config.yml  # User preferences (auto_update, tool overrides)
 ```
 
-**Catalog entries** (78 JSON files in `catalog/`):
+**Catalog entries** (79 JSON files in `catalog/`):
 - Each tool has `name`, `candidates`, `source_kind`, `source_args`, `category`
 - Categories: python, node, go, rust, ruby, php, shell, git, devops, platform, ai, general
 - User preferences (auto_update) stored in user config, not catalog

scripts/AGENTS.md

@@ -1,12 +1,12 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-16 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-02-06 -->
 
 # Installation Scripts - Agent Guide
 
 **Scope:** Shell scripts for tool installation, update, uninstall, reconcile
 
 ## Overview
 
-28 Bash scripts for installing developer tools with multiple actions:
+30 Bash scripts for installing developer tools with multiple actions:
 - **install**: Fresh installation (default action)
 - **update**: Upgrade to latest version
 - **uninstall**: Remove installation
@@ -33,6 +33,8 @@
 - `auto_update.sh`: Automatic update runner
 - `set_auto_update.sh`: Enable/disable auto-update per tool
 - `pin_version.sh`, `unpin_version.sh`: Version pinning
+- `reset_pins.sh`: Remove all version pins from all tools
+- `cleanup.sh`: Interactive removal of installed tools
 
 **Reconciliation:**
 - `reconcile_pip_to_uv.sh`: Migrate pip packages to uv

tests/AGENTS.md

@@ -1,12 +1,12 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-16 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-02-06 -->
 
 # tests/ — Test Suite
 
 **Comprehensive testing** with unit, integration, and E2E tests for the modular cli_audit package.
 
 ## Overview
 
-The test suite validates all 20 modules across Phase 1 (Detection & Auditing) and Phase 2 (Installation & Upgrade Management).
+The test suite validates all 21 modules across Phase 1 (Detection & Auditing) and Phase 2 (Installation & Upgrade Management).
 
 **Test organization:**
 ```
@@ -20,6 +20,7 @@ tests/
 ├── test_local_state.py           # Local state management
 ├── test_logging.py               # Logging configuration
 ├── test_package_managers.py      # Package manager abstractions
+├── test_prerequisites.py         # Prerequisite resolution
 ├── test_reconcile.py             # Duplicate cleanup
 ├── test_upgrade.py               # Upgrade workflows
 ├── test_upstream_cache.py        # Upstream cache management
@@ -28,7 +29,7 @@ tests/
 ```
 
 **Test coverage:**
-- 12 unit test files covering all 20 modules
+- 13 unit test files covering all 21 modules
 - 1 integration test directory
 - Fixtures for mocking external services