docs: update AGENTS.md and documentation index

Updated agent documentation to reflect modular audit system
and new workflows:
- AGENTS.md: Updated main agent instructions
- docs/INDEX.md: Refreshed documentation index
- scripts/AGENTS.md: Updated script-specific instructions
- tests/AGENTS.md: Added test-specific instructions

These changes align documentation with the refactored codebase
structure and improved audit workflows.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: CybotTM

AGENTS.md

@@ -1,308 +1,75 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-11-03 -->
 
-# AI CLI Preparation - Agent Guide (Root)
+# AGENTS.md (root)
 
-**Thin root file**: See scoped AGENTS.md files for specific areas.
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
 
-## Precedence & Scoped Files
+## Global rules
 
-This root AGENTS.md provides global defaults. **Nearest AGENTS.md wins** for specific rules.
-
-**Scoped files:**
-- [scripts/AGENTS.md](scripts/AGENTS.md) - Shell installation scripts
-
-## Overview
-
-AI CLI Preparation is an environment audit tool ensuring AI coding agents (like Claude Code) have access to necessary developer tools. It detects 50+ tools, reports versions, and provides installation guidance.
+- Keep PRs small (~≤300 net LOC changed)
+- Conventional Commits: `type(scope): description`
+  - Types: feat, fix, docs, chore, test, refactor, perf, style
+  - Scopes: audit, catalog, scripts, docs, tests
+- Ask before: heavy dependencies, full rewrites, breaking changes
+- Never commit secrets, PII, or credentials
 
-**Architecture:**
-- **Phase 1 (Complete)**: Tool detection, version auditing, offline-first caching
-- **Phase 2 (Planned)**: Context-aware installation/upgrade management (see [docs/PRD.md](docs/PRD.md))
+## Project overview
 
-**Tech Stack:**
-- Python 3.10+ (standard library only, no external deps for core)
-- Make for task automation
-- Shell scripts (Bash) for installation
-- JSON for caching (latest_versions.json, tools_snapshot.json)
+**AI CLI Preparation v2.0** - Tool version auditing and installation management for AI coding agents.
 
-**Key Files:**
-- `cli_audit.py` (2,375 lines): Main audit engine, 50+ tool definitions
-- `smart_column.py`: ANSI/emoji-aware table formatting
-- `scripts/`: 13+ installation scripts (install/update/uninstall/reconcile)
-- `docs/`: Comprehensive technical documentation (12 files, 189KB)
+**Architecture:** Modular design with 18 specialized Python modules, 67 JSON tool catalogs, and comprehensive testing.
 
-## Setup
+- **Phase 1 (Complete):** Detection & auditing with modular refactoring
+- **Phase 2 (Complete):** Installation & upgrade management
+- **Entry Point:** `audit.py` (50 lines) → cli_audit package
 
-**Requirements:**
-- Python 3.10+ (Python 3.14.0rc2 tested)
-- Standard library only (no pip install needed for core)
-- Optional: pyflakes for linting
+## Minimal pre-commit checks
 
-**First-time setup:**
 ```bash
-# Allow direnv (if using)
-direnv allow
-
-# Show available commands
-make help
+# Linting
+make lint                    # flake8 (required)
 
-# Update snapshot (requires network)
-make update
+# Type checking (optional)
+make lint-types              # mypy
 
-# Run audit from snapshot (fast, offline-capable)
-make audit
-```
+# Testing
+./scripts/test_smoke.sh      # Smoke tests (required)
 
-**Environment variables:**
-```bash
-# See .env.default for all options
-CLI_AUDIT_COLLECT=1      # Collect-only mode (write snapshot)
-CLI_AUDIT_RENDER=1       # Render-only mode (read snapshot)
-CLI_AUDIT_OFFLINE=1      # Offline mode (manual cache only)
-CLI_AUDIT_DEBUG=1        # Debug output
-CLI_AUDIT_JSON=1         # JSON output
+# Audit validation
+make audit                   # Verify core workflows
 ```
 
-## Build & Tests
+## Index of scoped AGENTS.md
 
-**Primary commands:**
-```bash
-make audit               # Render from snapshot (no network, <100ms)
-make update              # Collect fresh data, write snapshot (~10s)
-make audit-offline       # Offline audit with hints
-make lint                # Run pyflakes (if installed)
-make upgrade             # Interactive upgrade guide
-```
-
-**Single tool audit:**
-```bash
-make audit-ripgrep       # Audit specific tool
-make audit-offline-python-core  # Role-based preset
-```
+- **[cli_audit/AGENTS.md](cli_audit/AGENTS.md)** — Python package (18 modules, Phase 1 + Phase 2)
+- **[tests/AGENTS.md](tests/AGENTS.md)** — Test suite (unit, integration, E2E)
+- **[scripts/AGENTS.md](scripts/AGENTS.md)** — Installation scripts (Bash, 25+ scripts)
 
-**Installation scripts:**
-```bash
-make install-python      # Install Python toolchain (uv)
-make install-node        # Install Node.js (nvm)
-make install-core        # Install core tools (fd, fzf, ripgrep, jq, etc.)
-```
+## Quick reference
 
-**Testing:**
+**Common commands:**
 ```bash
-# Smoke test (verifies table output and JSON format)
-./scripts/test_smoke.sh
-
-# Test single tool detection
-CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only ripgrep
-
-# Validate snapshot
-jq '.__meta__' tools_snapshot.json
-```
-
-**No formal test suite yet** - README acknowledges: "currently ships without tests"
-- Smoke tests exist (test_smoke.sh)
-- Manual validation workflows documented
-
-## Code Style
-
-**Python:**
-- PEP 8 style (4-space indent, snake_case)
-- Type hints used (`from __future__ import annotations`)
-- Frozen dataclasses for immutability (`@dataclass(frozen=True)`)
-- Docstrings minimal (focus on inline comments)
-
-**Formatting:**
-- EditorConfig enforced: LF, UTF-8, 4 spaces, trim trailing whitespace
-- No auto-formatter configured (manual formatting)
-- Lint via pyflakes: `make lint`
-
-**Shell scripts:**
-- Bash with `set -euo pipefail`
-- Shellcheck-compliant (best effort)
-- Consistent error handling (see scripts/lib/)
-
-**Conventions:**
-- File paths: Absolute paths, no auto-commit
-- Functions: Snake_case, descriptive names
-- Constants: UPPER_CASE (e.g., MANUAL_LOCK, HINTS_LOCK)
-- Lock ordering: MANUAL_LOCK → HINTS_LOCK (enforced for safety)
-
-## Security
-
-**Secrets:**
-- No secrets in VCS
-- GITHUB_TOKEN optional (for GitHub API rate limit increase)
-- Set via environment: `export GITHUB_TOKEN=ghp_...`
-
-**Network:**
-- HTTPS-only for upstream queries
-- Retry logic with exponential backoff
-- Per-origin rate limits (GitHub: 5/min, PyPI: 10/min, crates.io: 5/min)
-- Timeout enforcement (default: 3s, configurable)
-
-**Input validation:**
-- Tool names validated against TOOLS registry
-- Version strings sanitized (extract_version_number)
-- Subprocess calls use lists, not shell=True (where possible)
-
-**Caching:**
-- Atomic file writes prevent corruption
-- Offline-first design (committed latest_versions.json)
-- No arbitrary code execution (package manager commands only)
-
-## PR/Commit Checklist
-
-**Before commit:**
-- [ ] Run `make lint` (pyflakes clean)
-- [ ] Run `make audit` (verify snapshot renders)
-- [ ] Test affected tool: `make audit-<tool>`
-- [ ] Update docs if behavior changed (README.md, docs/, scripts/README.md)
-- [ ] Add/update smoke test if new output format
-
-**Commit messages:**
-- Conventional Commits format: `type(scope): description`
-- Examples:
-  - `feat(audit): add snapshot-based collect/render modes`
-  - `fix(locks): enforce MANUAL_LOCK→HINTS_LOCK ordering`
-  - `docs(prd): add Phase 2 specifications and ADRs`
-  - `chore(cache): update latest_versions.json`
-
-**Pull requests:**
-- Keep PRs small (~≤300 net LOC changed)
-- Link to issue/ticket if exists
-- Update CHANGELOG section in PR description
-- Ensure CI passes (when added)
-
-## Good vs Bad Examples
-
-**Good: Atomic dataclass with type safety**
-```python
-@dataclass(frozen=True)
-class Tool:
-    name: str
-    candidates: tuple[str, ...]
-    source_kind: str  # gh|pypi|crates|npm|gnu|skip
-    source_args: tuple[str, ...]
-```
-
-**Bad: Mutable dict with unclear types**
-```python
-# Don't do this
-tool = {
-    'name': 'ripgrep',
-    'candidates': ['rg'],  # List instead of tuple
-    'source': 'github',     # Unclear allowed values
-}
-```
-
-**Good: Lock ordering enforcement**
-```python
-def update_manual_cache(tool: str, version: str) -> None:
-    with MANUAL_LOCK:  # Acquire first
-        with HINTS_LOCK:  # Then hints
-            # Safe: consistent ordering prevents deadlock
-```
-
-**Bad: Lock ordering violation**
-```python
-def update_cache(tool: str) -> None:
-    with HINTS_LOCK:    # Wrong order!
-        with MANUAL_LOCK:
-            # Deadlock risk
-```
-
-**Good: Parallel execution with isolation**
-```python
-with ThreadPoolExecutor(max_workers=16) as executor:
-    futures = [executor.submit(audit_tool, tool) for tool in TOOLS]
-    for future in as_completed(futures):
-        result = future.result()  # Failures isolated
-```
+make audit               # Render from snapshot (<100ms)
+make update              # Collect fresh versions (~7s)
+make upgrade             # Interactive upgrade guide
 
-**Bad: Sequential execution**
-```python
-results = []
-for tool in TOOLS:  # Slow: 50 tools * 3s = 150s
-    results.append(audit_tool(tool))
+python3 audit.py         # Direct invocation
+python3 audit.py --only ripgrep  # Single tool audit
 ```
 
-## When Stuck
-
-**Tool detection failing:**
-1. Check PATH: `echo $PATH | tr ':' '\n'`
-2. Debug single tool: `CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only <tool>`
-3. Check version flag: `<tool> --version` or `<tool> -v`
-4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#version-detection-failures)
-
-**Network issues:**
-1. Increase timeout: `CLI_AUDIT_TIMEOUT_SECONDS=10 make update`
-2. More retries: `CLI_AUDIT_HTTP_RETRIES=5 make update`
-3. Use offline mode: `make audit-offline`
-4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#network-timeout-issues)
-
-**Cache corruption:**
-1. Remove caches: `rm latest_versions.json tools_snapshot.json`
-2. Regenerate: `make update`
-
-**Installation script fails:**
-1. Check permissions: `make scripts-perms`
-2. Debug script: `bash -x ./scripts/install_<tool>.sh`
-3. See [scripts/README.md](scripts/README.md) for per-script troubleshooting
+**Key files:**
+- `audit.py` — Entry point (50 lines)
+- `cli_audit/` — 18 Python modules (6,608 lines)
+- `catalog/` — 67 JSON tool definitions
+- `latest_versions.json` — Version cache
+- `tools_snapshot.json` — Snapshot data
 
 **Documentation:**
-- Start with [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) for one-liners
-- See [docs/INDEX.md](docs/INDEX.md) for navigation by role/task
-- Architecture details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-- API reference: [docs/API_REFERENCE.md](docs/API_REFERENCE.md)
-
-## House Rules
-
-**Defaults** (override in scoped AGENTS.md if needed):
-
-**Commits:**
-- Atomic commits (single logical change)
-- Conventional Commits: `type(scope): description`
-- Keep PRs small (~≤300 net LOC changed)
-- Ticket IDs in commits/PRs if exists
-
-**Type-safety:**
-- Use type hints (`from __future__ import annotations`)
-- Frozen dataclasses for immutability
-- No `Any` unless truly dynamic
-
-**Design principles:**
-- SOLID, KISS, DRY, YAGNI
-- Composition > Inheritance
-- Law of Demeter (minimal coupling)
-
-**Dependencies:**
-- Standard library preferred (no external Python deps for core)
-- Latest stable versions when external deps needed
-- Document why in Decision Log (ADRs for Phase 2)
-
-**Security:**
-- No secrets in VCS
-- HTTPS-only for network calls
-- No arbitrary code execution
-- Input validation on external data
-
-**Documentation currency:**
-- Update docs in same PR as behavior changes
-- No drift between code and docs
-- Document non-obvious decisions in ADRs (see docs/adr/)
-
-**Testing:**
-- Aim for ≥80% coverage on changed code (when test suite added)
-- Bugfixes use TDD: failing test first, then fix
-- New code paths need tests (future requirement)
-
-**Current status:**
-- Phase 1: Production-ready detection/audit
-- Phase 2: Planned installation/upgrade (see [docs/PRD.md](docs/PRD.md))
-- No unit tests yet (acknowledged in README)
-
----
+- `docs/INDEX.md` — Documentation navigation
+- `docs/MIGRATION_GUIDE.md` — v1.x → v2.0 transition
+- `docs/CATALOG_GUIDE.md` — JSON catalog system
+- `docs/ARCHITECTURE.md` — Modular design
 
-**Quick Start:** New to the project? Start with [README.md](README.md) → [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) → [docs/INDEX.md](docs/INDEX.md)
+## When instructions conflict
 
-**Contributing:** See [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for detailed contribution guide
+Nearest AGENTS.md wins. User prompts override all files.