docs(agents): verify and fix AGENTS.md content against actual codebase

Root AGENTS.md:
- Add missing make targets (outdated, update-local, update-baseline, etc.)
- Add data files section documenting 2-file model

cli_audit/AGENTS.md:
- Add 2 new modules: local_state.py, upstream_cache.py
- Add data model section with file locations
- Update module count 18→20, catalog 74→76

scripts/AGENTS.md:
- Remove non-existent install_core.sh
- Add 20+ undocumented scripts (install_claude.sh, pin_version.sh, etc.)
- Fix colors.sh→common.sh (colors.sh doesn't exist)
- Document all 10 lib/ modules with correct paths

tests/AGENTS.md:
- Add missing test files: test_catalog_and_collectors.py,
  test_local_state.py, test_upstream_cache.py
- Update test file count 8→12

All content verified against actual codebase using verify-content.sh

Author: CybotTM

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-11-29 -->
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-01-14 -->
 
 # AGENTS.md (root)
 
@@ -41,7 +41,7 @@ uv run python audit.py --help    # Verify CLI works
 
 ## Index of scoped AGENTS.md
 
-- [cli_audit/AGENTS.md](./cli_audit/AGENTS.md) — Python package (18 modules)
+- [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)
 
@@ -53,15 +53,31 @@ uv run python audit.py --help    # Verify CLI works
 | `uv run python -m pytest -x` | Run tests, stop on first failure |
 | `uv run python audit.py ripgrep` | Single tool audit |
 | `uv run python audit.py --help` | Show CLI options |
-| `make audit` | Render from snapshot (<100ms) |
-| `make update` | Collect fresh versions (~7s) |
+| `make audit` | Render from snapshot (fast, no network) |
+| `make audit-offline` | Offline audit with hints |
+| `make outdated` | Show only missing/outdated tools |
+| `make update` | Collect fresh versions (~10s) |
+| `make update-local` | Update only local state (no network) |
+| `make update-baseline` | Update upstream baseline for commit |
 | `make upgrade` | Interactive upgrade guide |
+| `make upgrade-managed` | Upgrade all package managers |
+| `make upgrade-dry-run` | Preview upgrades without changes |
+| `./scripts/set_auto_update.sh <tool>` | Enable auto-update for a tool |
+
+## Data files
+
+**2-file data model** (Phase 2.1):
+- `upstream_versions.json` — Latest upstream versions (committed, shared baseline)
+- `local_state.json` — Machine-specific installation state (gitignored)
+
+**User configuration:**
+- `~/.config/cli-audit/config.yml` — User preferences (auto_update, tool overrides)
 
 ## Project overview
 
 **AI CLI Preparation v2.0** — Tool version auditing and installation management for AI coding agents.
 
-- **Architecture:** 18 Python modules, 74 JSON tool catalogs
+- **Architecture:** 20 Python modules, 76 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: 2025-11-29 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-14 -->
 
 # cli_audit/ — Python Package
 
-**Modular architecture** with 18 specialized modules for tool detection, auditing, installation, and upgrade management.
+**Modular architecture** with 20 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 (74 entries)
+- `catalog.py` — JSON catalog management (76 entries)
 - `detection.py` — Installation detection, version extraction
 - `collectors.py` — Upstream version collection (GitHub, PyPI, npm, crates)
 - `snapshot.py` — Snapshot-based caching
@@ -19,7 +19,7 @@ The `cli_audit` package provides the core functionality for AI CLI Preparation:
 **Phase 2: Foundation (5 modules)**
 - `common.py` — Shared types (InstallResult, AuditResult, etc.)
 - `environment.py` — OS/arch detection, package manager detection
-- `config.py` — Configuration management (YAML support)
+- `config.py` — Configuration management (YAML, user prefs, auto_update)
 - `package_managers.py` — Package manager abstractions
 - `logging_config.py` — Logging configuration
 
@@ -29,11 +29,33 @@ The `cli_audit` package provides the core functionality for AI CLI Preparation:
 - `bulk.py` — Parallel bulk operations
 - `upgrade.py` — Upgrade workflows
 
+**Phase 2: State Management (2 modules)**
+- `local_state.py` — Machine-specific installation state (gitignored)
+- `upstream_cache.py` — Upstream version cache (committed baseline)
+
 **Phase 2: Advanced Features (3 modules)**
 - `breaking_changes.py` — Semver analysis for breaking changes
 - `reconcile.py` — Duplicate installation cleanup
 - `__init__.py` — Public API exports (backward compatibility)
 
+## Data model
+
+**2-file data model** (Phase 2.1 consolidation):
+```
+upstream_versions.json  # Committed - latest available versions (shared baseline)
+local_state.json        # Gitignored - machine-specific installation state
+```
+
+**User configuration:**
+```
+~/.config/cli-audit/config.yml  # User preferences (auto_update, tool overrides)
+```
+
+**Catalog entries** (76 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
+
 ## Setup & environment
 
 **Requirements:**

scripts/AGENTS.md

@@ -1,27 +1,56 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-11-29 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-14 -->
 
 # Installation Scripts - Agent Guide
 
 **Scope:** Shell scripts for tool installation, update, uninstall, reconcile
 
 ## Overview
 
-25+ Bash scripts for installing developer tools with multiple actions:
+28 Bash scripts for installing developer tools with multiple actions:
 - **install**: Fresh installation (default action)
 - **update**: Upgrade to latest version
 - **uninstall**: Remove installation
 - **reconcile**: Switch to preferred installation method (e.g., system → user)
 
-**Key scripts:**
-- `install_core.sh`: Core tools (fd, fzf, ripgrep, jq, yq, bat, delta, just)
+**Installation scripts** (language toolchains):
 - `install_python.sh`: Python toolchain via uv
 - `install_node.sh`: Node.js via nvm
 - `install_rust.sh`: Rust via rustup
-- `install_go.sh`, `install_aws.sh`, `install_kubectl.sh`, etc.
-- `guide.sh`: Interactive upgrade guide
+- `install_go.sh`: Go via official installer
+- `install_ruby.sh`: Ruby via rbenv/ruby-build
+- `install_uv.sh`: uv package manager
+
+**Installation scripts** (tools & services):
+- `install_tool.sh`: Main orchestrator - reads catalog, delegates to installers
+- `install_group.sh`: Install tool groups
+- `install_claude.sh`: Claude Code CLI (native installer)
+- `install_ansible.sh`, `install_brew.sh`, `install_composer.sh`
+- `install_docker.sh`, `install_gem.sh`, `install_parallel.sh`, `install_yarn.sh`
+
+**Upgrade & management:**
+- `guide.sh`: Interactive upgrade guide (supports 'a' for auto-update)
+- `upgrade_all.sh`: Batch upgrade all tools
+- `auto_update.sh`: Automatic update runner
+- `set_auto_update.sh`: Enable/disable auto-update per tool
+- `pin_version.sh`, `unpin_version.sh`: Version pinning
+
+**Reconciliation:**
+- `reconcile_pip_to_uv.sh`: Migrate pip packages to uv
+- `reconcile_pipx_to_uv.sh`: Migrate pipx packages to uv
+
+**Utilities:**
+- `check_python_package_managers.sh`: Detect multiple Python package managers
+- `check_node_package_managers.sh`: Detect multiple Node.js package managers
 - `test_smoke.sh`: Smoke test for audit output
+- `auto_update_scope_prototype.sh`: Prototype for scope detection
 
-**Shared utilities:** `lib/` directory (colors, logging, common functions)
+**Shared utilities:** `scripts/lib/` directory (10 modules):
+- `lib/common.sh` — Logging and output formatting
+- `lib/config.sh` — Read user config from `~/.config/cli-audit/config.yml`
+- `lib/catalog.sh` — Catalog access utilities
+- `lib/capability.sh`, `lib/dependency.sh` — Capability and dependency checks
+- `lib/install_strategy.sh`, `lib/reconcile.sh` — Installation strategies
+- `lib/path_check.sh`, `lib/policy.sh`, `lib/scope_detection.sh` — Path and policy utilities
 
 ## Setup & environment
 
@@ -73,6 +102,15 @@ make reconcile-node              # Switch Node.js to nvm-managed
 ./scripts/test_smoke.sh          # Verify audit output format
 ```
 
+**Auto-update management:**
+```bash
+# Enable auto-update for a tool (stores in ~/.config/cli-audit/config.yml)
+./scripts/set_auto_update.sh prettier        # Enable
+./scripts/set_auto_update.sh prettier false  # Disable
+
+# In guide.sh, press 'a' to install AND enable auto-update
+```
+
 **Debug mode:**
 ```bash
 DEBUG=1 ./scripts/install_python.sh
@@ -102,7 +140,7 @@ set -euo pipefail
 
 # Source shared utilities
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "${SCRIPT_DIR}/lib/colors.sh" || true
+source "${SCRIPT_DIR}/lib/common.sh" || true
 source "${SCRIPT_DIR}/lib/common.sh" || true
 
 # Main function per action
@@ -226,7 +264,7 @@ fi
 **Script checklist:**
 - [ ] Shebang: `#!/usr/bin/env bash`
 - [ ] Strict mode: `set -euo pipefail`
-- [ ] Source shared lib: `source "${SCRIPT_DIR}/lib/colors.sh"`
+- [ ] Source shared lib: `source "${SCRIPT_DIR}/lib/common.sh"`
 - [ ] Action dispatcher (install/update/uninstall/reconcile)
 - [ ] Error handling (check return codes, trap on exit)
 - [ ] Confirmation prompts (respect FORCE_INSTALL)

tests/AGENTS.md

@@ -1,34 +1,35 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-11-29 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2026-01-14 -->
 
 # tests/ — Test Suite
 
 **Comprehensive testing** with unit, integration, and E2E tests for the modular cli_audit package.
 
 ## Overview
 
-The test suite validates all 18 modules across Phase 1 (Detection & Auditing) and Phase 2 (Installation & Upgrade Management).
+The test suite validates all 20 modules across Phase 1 (Detection & Auditing) and Phase 2 (Installation & Upgrade Management).
 
 **Test organization:**
 ```
 tests/
-├── test_config.py          # Configuration management (48+ tests) ✅
-├── test_environment.py     # Environment detection (10KB)
-├── test_package_managers.py # Package manager abstractions (13KB)
-├── test_installer.py       # Installation logic (22KB)
-├── test_install_plan.py    # Planning & dependencies (15KB)
-├── test_bulk.py            # Bulk operations (28KB)
-├── test_reconcile.py       # Duplicate cleanup (26KB)
-├── test_upgrade.py         # Upgrade workflows
-├── test_logging.py         # Logging configuration (7KB)
-├── integration/
-│   └── test_e2e_install.py # End-to-end installation tests
-└── fixtures/               # Test data and mocks
+├── test_bulk.py                  # Bulk operations
+├── test_catalog_and_collectors.py # Catalog and version collectors
+├── test_config.py                # Configuration management
+├── test_environment.py           # Environment detection
+├── test_install_plan.py          # Planning & dependencies
+├── test_installer.py             # Installation logic
+├── test_local_state.py           # Local state management
+├── test_logging.py               # Logging configuration
+├── test_package_managers.py      # Package manager abstractions
+├── test_reconcile.py             # Duplicate cleanup
+├── test_upgrade.py               # Upgrade workflows
+├── test_upstream_cache.py        # Upstream cache management
+└── integration/
+    └── test_e2e_install.py       # End-to-end installation tests
 ```
 
 **Test coverage:**
-- 8 unit test files
+- 12 unit test files covering all 20 modules
 - 1 integration test directory
-- 48+ test cases in test_config.py alone
 - Fixtures for mocking external services
 
 ## Setup & environment