docs(agents): update AGENTS.md files following public convention

- Rewrite root AGENTS.md to thin pattern (~50 lines)
- Fix link format with ./ prefix for scoped files
- Rename section headers in scripts/AGENTS.md to match schema
- Update tools_snapshot.json with current state

Author: CybotTM

AGENTS.md

@@ -1,76 +1,51 @@
-<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-11-29 -->
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-11-29 -->
 
 # AGENTS.md (root)
 
 **Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
 
 ## Global rules
 
-- Keep PRs small (~≤300 net LOC changed)
+- Keep PRs small (~≤300 net LOC)
 - 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
+- Ask before: heavy deps, full rewrites, breaking changes
 - Never commit secrets, PII, or credentials
 
-## Project overview
-
-**AI CLI Preparation v2.0** - Tool version auditing and installation management for AI coding agents.
-
-**Architecture:** Modular design with 18 specialized Python modules, 74 JSON tool catalogs, and comprehensive testing.
-
-- **Phase 1 (Complete):** Detection & auditing with modular refactoring
-- **Phase 2 (Complete):** Installation & upgrade management
-- **Entry Point:** `audit.py` (50 lines) → cli_audit package
-
 ## Minimal pre-commit checks
 
 ```bash
-# Linting
 make lint                    # flake8 (required)
-
-# Type checking (optional)
-make lint-types              # mypy
-
-# Testing
+make lint-types              # mypy (optional)
 ./scripts/test_smoke.sh      # Smoke tests (required)
-
-# Audit validation
 make audit                   # Verify core workflows
 ```
 
 ## Index of scoped AGENTS.md
 
-- **[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)
+- [cli_audit/AGENTS.md](./cli_audit/AGENTS.md) — Python package (18 modules)
+- [scripts/AGENTS.md](./scripts/AGENTS.md) — Installation scripts (Bash)
+- [tests/AGENTS.md](./tests/AGENTS.md) — Test suite (pytest)
 
 ## Quick reference
 
-**Common commands:**
-```bash
-make audit               # Render from snapshot (<100ms)
-make update              # Collect fresh versions (~7s)
-make upgrade             # Interactive upgrade guide
-make upgrade-all         # Complete 5-stage system upgrade
+| Command | Purpose |
+|---------|---------|
+| `make audit` | Render from snapshot (<100ms) |
+| `make update` | Collect fresh versions (~7s) |
+| `make upgrade` | Interactive upgrade guide |
+| `make upgrade-all` | Complete 5-stage system upgrade |
+| `python3 audit.py ripgrep` | Single tool audit |
 
-python3 audit.py         # Direct invocation
-python3 audit.py ripgrep # Single tool audit
-python3 audit.py --update ripgrep  # Update single tool
-```
+## Project overview
 
-**Key files:**
-- `audit.py` — Entry point
-- `cli_audit/` — 18 Python modules (~7K lines)
-- `catalog/` — 74 JSON tool definitions
-- `latest_versions.json` — Version cache
-- `tools_snapshot.json` — Snapshot data
+**AI CLI Preparation v2.0** — Tool version auditing and installation management for AI coding agents.
 
-**Documentation:**
-- `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
+- **Architecture:** 18 Python modules, 74 JSON tool catalogs
+- **Phase 1:** Detection & auditing (complete)
+- **Phase 2:** Installation & upgrade management (complete)
+- **Entry point:** `audit.py` → `cli_audit` package
 
 ## When instructions conflict
 

scripts/AGENTS.md

@@ -23,7 +23,7 @@
 
 **Shared utilities:** `lib/` directory (colors, logging, common functions)
 
-## Setup
+## Setup & environment
 
 **Requirements:**
 - Bash 4.0+
@@ -43,7 +43,7 @@ DEBUG=1                                      # Verbose output
 make scripts-perms  # Ensure all scripts are executable
 ```
 
-## Build & Tests
+## Build & tests
 
 **Run individual script:**
 ```bash
@@ -79,7 +79,7 @@ DEBUG=1 ./scripts/install_python.sh
 bash -x ./scripts/install_python.sh  # Trace execution
 ```
 
-## Code Style
+## Code style & conventions
 
 **Shell standards:**
 - Bash 4.0+ features allowed
@@ -165,7 +165,7 @@ if [[ "${FORCE_INSTALL:-0}" != "1" ]]; then
 fi
 ```
 
-## Security
+## Security & safety
 
 **Download verification:**
 ```bash
@@ -213,7 +213,7 @@ fi
 - Use environment variables: `${GITHUB_TOKEN:-}`
 - Document required env vars in script comments
 
-## PR/Commit Checklist
+## PR/commit checklist
 
 **Before commit:**
 - [ ] Run `shellcheck <script>` (if available)
@@ -237,7 +237,7 @@ fi
 - `fix(install-python): handle uv bootstrap failure`
 - `docs(scripts): update README with reconcile action`
 
-## Good vs Bad Examples
+## Good vs. bad examples
 
 **Good: Robust download with fallback**
 ```bash
@@ -326,7 +326,7 @@ update_rust() {
 }
 ```
 
-## When Stuck
+## When stuck
 
 **Script fails silently:**
 1. Add debug: `bash -x ./scripts/install_<tool>.sh`
@@ -358,7 +358,7 @@ update_rust() {
 - Troubleshooting: [../docs/TROUBLESHOOTING.md](../docs/TROUBLESHOOTING.md)
 - Architecture: [../docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md#installation-scripts)
 
-## House Rules
+## House rules
 
 **Installation preferences** (Phase 2 planning):
 - User-level preferred: `~/.local/bin` (workstations)