docs: remove obsolete __hints__ references

The hints cache feature was removed in prior refactoring.
Updated all documentation to reflect the simplified 2-file
data model (upstream_versions.json + local_state.json).

Author: CybotTM

docs/ARCHITECTURE.md

@@ -171,7 +171,6 @@ def _classify_install_method(path: str, tool_name: str) -> tuple[str, str]:
 1. **GitHub:**
    - Try `/repos/{owner}/{repo}/releases/latest` with redirect following
    - Fallback to Atom feed parsing if API fails
-   - Store successful method in hints for speed
 
 2. **PyPI:**
    - Query `https://pypi.org/pypi/{package}/json`
@@ -202,55 +201,31 @@ sleep_time = base * (2 ** attempt) + random.uniform(0, jitter)
 # Example: attempt 1 → 200ms + 0-100ms = 200-300ms
 ```
 
-### 6. Cache Layer (Multi-Tier)
+### 6. Data Files
 
-**Cache Hierarchy (fastest → slowest):**
+**Two-file model:**
 
-1. **Hints Cache** (`__hints__` in `upstream_versions.json`)
-   - Stores which API method worked last per tool
-   - Example: `"gh:BurntSushi/ripgrep": "latest_redirect"`
-   - Purpose: Skip failed methods, try successful ones first
-   - Lock: `HINTS_LOCK` (acquired after `MANUAL_LOCK`)
-
-2. **Manual Cache** (`upstream_versions.json`)
-   - Committed to repository
+1. **Upstream Cache** (`upstream_versions.json`) - Committed
+   - Latest available versions from upstream sources
    - Used in offline mode (`CLI_AUDIT_OFFLINE=1`)
-   - Updated on successful upstream fetches (unless `CLI_AUDIT_WRITE_MANUAL=0`)
-   - Lock: `MANUAL_LOCK` (acquired first)
-
-3. **Snapshot** (`tools_snapshot.json`)
-   - Complete audit results with metadata
-   - Schema version 1 with `__meta__` object
-   - Used for render-only mode
-   - Written atomically after collection
+   - Updated via `--update-baseline`
 
-**Lock Ordering Rule:**
-```python
-with MANUAL_LOCK:
-    # Update upstream_versions.json
-    with HINTS_LOCK:
-        # Update __hints__ section
-```
-**Critical:** MANUAL_LOCK must be acquired before HINTS_LOCK to prevent deadlock.
+2. **Local State** (`local_state.json`) - Gitignored
+   - Machine-specific installed tool versions
+   - Updated via `--update-local`
 
 ### 7. Threading Model & Synchronization
 
 **Concurrency Strategy:**
 
 ```python
-# Global locks for cache writes
-MANUAL_LOCK = threading.Lock()  # For upstream_versions.json
-HINTS_LOCK = threading.Lock()   # For __hints__ in upstream_versions.json (nested)
-
 # ThreadPoolExecutor for parallel tool audits
 with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor:
     # Each worker calls audit_tool(tool)
-    # Workers may update caches (with locks)
 ```
 
 **Thread Safety:**
-- Tool audits run in parallel (no shared state except caches)
-- Cache updates are serialized via locks
+- Tool audits run in parallel (no shared state)
 - Atomic file writes prevent corruption (write to temp, then rename)
 
 **Performance Considerations:**
@@ -367,9 +342,7 @@ for attempt in range(retries + 1):
 ```
 Attempt 1: Try upstream API (with retries)
   ↓ (on failure)
-Attempt 2: Check hints cache for alternative method
-  ↓ (on failure)
-Attempt 3: Use manual cache (upstream_versions.json)
+Attempt 2: Use cached upstream (upstream_versions.json)
   ↓ (on failure)
 Result: Mark as UNKNOWN, continue audit
 ```

docs/ARCHITECTURE_DIAGRAM.md

@@ -473,19 +473,13 @@ NOT ProcessPoolExecutor (GIL not a bottleneck)
 
 get_available_version(tool, pm, cache_ttl)
     │
-    ├─→ Check in-memory cache (TTL: 1 hour)
-    │   └─→ HIT → return cached version
-    │
-    ├─→ MISS → Query upstream API
+    ├─→ Query upstream API
     │   │
-    │   ├─→ Check hints cache (last working method)
-    │   │        └─→ Try: github/pypi/crates/npm
+    │   ├─→ Try: github/pypi/crates/npm
     │   │
     │   ├─→ Retry with exponential backoff (2x)
     │   │
     │   ├─→ SUCCESS:
-    │   │   ├─→ Update in-memory cache
-    │   │   ├─→ Update hints cache
     │   │   └─→ Write to upstream_versions.json
     │   │
     │   └─→ FAILURE:
@@ -494,26 +488,9 @@ get_available_version(tool, pm, cache_ttl)
     │
     └─→ Returns: version string
 
-Multi-Tier Cache Hierarchy:
-1. In-memory (fastest)
-2. Hints (method preference)
-3. Manual cache (upstream_versions.json)
-4. Snapshot (tools_snapshot.json)
-```
-
-### Lock Hierarchy
-
-```
-MANUAL_LOCK (file-level cache updates)
-    └─→ HINTS_LOCK (hints section updates)
-
-Rule: Always acquire MANUAL_LOCK before HINTS_LOCK
-Prevents: Deadlocks
-
-with MANUAL_LOCK:
-    # Update upstream_versions.json
-    with HINTS_LOCK:
-        # Update __hints__ section
+Data Files:
+1. upstream_versions.json (committed) - latest available versions
+2. local_state.json (gitignored) - machine-specific state
 ```
 
 ---

docs/DEPLOYMENT.md

@@ -548,28 +548,13 @@ CLI_AUDIT_OFFLINE=1 python3 cli_audit.py --only python
 
 ### Offline Cache Management
 
-**Cache File:** `upstream_versions.json` (override with `CLI_AUDIT_MANUAL_FILE`)
+**Data Files:**
+- `upstream_versions.json` - Latest available versions (committed)
+- `local_state.json` - Machine-specific state (gitignored)
 
-**Structure:**
-```json
-{
-  "__hints__": {
-    "gh:BurntSushi/ripgrep": "latest_redirect",
-    "gh:sharkdp/fd": "latest_redirect"
-  },
-  "__methods__": {
-    "pip": "pypi",
-    "pipx": "pypi"
-  },
-  "ripgrep": "14.1.1",
-  "fd": "10.3.0",
-  "python": "3.14.0"
-}
-```
-
-**Update Behavior:**
-- Online lookups automatically update cache (default)
-- Disable auto-update: `CLI_AUDIT_WRITE_MANUAL=0`
+**Update Commands:**
+- `python audit.py --update-baseline` - Refresh upstream versions
+- `python audit.py --update-local` - Refresh local state
 
 ## Environment Variable Configuration
 

docs/DEVELOPER_GUIDE.md

@@ -246,20 +246,7 @@ def risky_operation():
 
 ### Threading Safety
 
-When updating caches, always use locks:
-
-```python
-# ALWAYS acquire MANUAL_LOCK before HINTS_LOCK
-with MANUAL_LOCK:
-    # Update upstream_versions.json
-    set_manual_latest(tool_name, version)
-
-    with HINTS_LOCK:
-        # Update __hints__ section
-        set_hint(f"gh:{owner}/{repo}", method)
-```
-
-**Lock Ordering Rule:** MANUAL_LOCK → HINTS_LOCK (never reversed)
+File writes use atomic operations (write to temp, then rename) to prevent corruption.
 
 ## Testing Strategies
 
@@ -417,14 +404,11 @@ CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only problematic-tool 2>&1 | tee debug.
 ### Check Cache State
 
 ```bash
-# View manual cache
+# View upstream versions
 jq '.' upstream_versions.json
 
-# View hints
-jq '.__hints__' upstream_versions.json
-
-# View snapshot metadata
-jq '.__meta__' tools_snapshot.json
+# View local state
+jq '.' local_state.json
 ```
 
 ## Git Workflow Best Practices
@@ -494,22 +478,6 @@ CLI_AUDIT_FAST=1 python3 cli_audit.py
 
 ## Common Pitfalls
 
-### ❌ Wrong Lock Ordering
-
-```python
-# WRONG - Can deadlock
-with HINTS_LOCK:
-    with MANUAL_LOCK:  # Bad order
-        ...
-```
-
-```python
-# CORRECT
-with MANUAL_LOCK:
-    with HINTS_LOCK:  # Good order
-        ...
-```
-
 ### ❌ Unhandled Exceptions in Workers
 
 ```python

docs/FUNCTION_REFERENCE.md

@@ -11,7 +11,7 @@ Quick lookup reference for functions in `cli_audit.py`, organized by category.
 | **Classification** | `detect_install_method`, `_classify_install_method` | Installation method detection |
 | **Upstream APIs** | `latest_github`, `latest_pypi`, `latest_crates`, `latest_npm`, `latest_gnu` | Fetch upstream versions |
 | **HTTP** | `http_fetch`, `http_get` | Network layer with retries |
-| **Cache** | `load_manual_versions`, `get_manual_latest`, `set_manual_latest`, `load_hints`, `get_hint`, `set_hint` | Multi-tier cache management |
+| **Cache** | `load_manual_versions`, `get_manual_latest`, `set_manual_latest` | Cache management |
 | **Core** | `audit_tool`, `get_latest`, `main` | Main audit logic |
 
 ---
@@ -134,7 +134,6 @@ Extract version string from executable.
 - Most tools: `<path> --version`
 - `go`, `curlie`, `isort`: Custom version flags
 - `entr`, `sponge`: No version flag (returns empty)
-- Uses hints cache to remember working flags
 
 **Usage:**
 ```python
@@ -335,8 +334,6 @@ Fetch latest GitHub release.
 **Strategies:**
 1. Try `/repos/{owner}/{repo}/releases/latest` with redirect following
 2. On failure, try Atom feed at `/releases.atom`
-3. Use hints cache to skip failed methods
-4. Store successful method as hint for next run
 
 **Usage:**
 ```python
@@ -345,9 +342,6 @@ tag, method = latest_github("sharkdp", "fd")
 
 tag, method = latest_github("BurntSushi", "ripgrep")
 # ("14.1.1", "latest_redirect")
-
-# Hint is stored automatically for next run
-hint = get_hint("gh:sharkdp/fd")
 # "latest_redirect"
 ```
 
@@ -603,76 +597,6 @@ set_manual_latest("ripgrep", "14.1.1")
 
 ---
 
-### `load_hints() -> None`
-
-Load API method hints from `__hints__` in `upstream_versions.json`.
-
-**Side Effects:** Populates global `HINTS` dict
-
-**Usage:**
-```python
-load_hints()
-method = HINTS.get("gh:owner/repo", "")
-```
-
-**See:** [API_REFERENCE.md#load_hints](API_REFERENCE.md#load_hints)
-
----
-
-### `get_hint(key) -> str`
-
-Get cached API method for a source.
-
-**Parameters:**
-- `key` (`str`) - Hint key formats:
-  - `"gh:owner/repo"` - GitHub API method
-  - `"local_flag:tool"` - Version flag that worked
-
-**Returns:**
-- `str` - Method string (e.g., `"latest_redirect"`, `"--version"`) or empty
-
-**Usage:**
-```python
-# Get GitHub API method
-method = get_hint("gh:sharkdp/fd")
-if method == "latest_redirect":
-    # Try latest redirect first
-
-# Get version flag
-flag = get_hint("local_flag:ripgrep")
-if flag == "-V":
-    # Use -V instead of --version
-```
-
-**See:** [API_REFERENCE.md#get_hint](API_REFERENCE.md#get_hint)
-
----
-
-### `set_hint(key, value) -> None`
-
-Store API method hint for future runs.
-
-**Parameters:**
-- `key` (`str`) - Hint key
-- `value` (`str`) - Method that worked
-
-**Side Effects:** Writes to `__hints__` in `upstream_versions.json`
-
-**Lock Ordering:** Requires `MANUAL_LOCK` → `HINTS_LOCK`
-
-**Usage:**
-```python
-# Store successful GitHub method
-set_hint("gh:owner/repo", "latest_redirect")
-
-# Store working version flag
-set_hint("local_flag:ripgrep", "-V")
-```
-
-**See:** [API_REFERENCE.md#set_hint](API_REFERENCE.md#set_hint)
-
----
-
 ## Core Audit Functions
 
 Main audit logic coordinating all subsystems.
@@ -732,12 +656,10 @@ Get latest upstream version for a tool.
 - `tuple[str, str]` - `(version, method)` - version string and source method
 
 **Cache Strategy:**
-1. If `MANUAL_FIRST=1`, check manual cache first
-2. Check hints cache for fastest method
-3. Try upstream API (with retries)
-4. On success, update hints and manual caches
-5. On failure, fall back to manual cache
-6. Final fallback: return `("", "")`
+1. Try upstream API (with retries)
+2. On success, update cache
+3. On failure, fall back to cached upstream
+4. Final fallback: return `("", "")`
 
 **Usage:**
 ```python

docs/PRD.md

@@ -75,13 +75,11 @@ AI CLI Preparation is a specialized environment audit and installation managemen
 
 **Threading Model:**
 - ThreadPoolExecutor with configurable workers (default: 16)
-- Lock ordering enforcement (MANUAL_LOCK → HINTS_LOCK for safety)
 - Independent tool audits (failures isolated)
 
-**Cache Hierarchy:**
-- **Hints**: Optimization hints for faster lookups (__hints__ in upstream_versions.json)
-- **Manual**: User-committed versions (upstream_versions.json)
-- **Upstream**: Live API queries (fallback)
+**Data Model:**
+- **upstream_versions.json**: Cached upstream versions (committed)
+- **local_state.json**: Machine-specific state (gitignored)
 
 **Resilience Patterns:**
 - Network failures → fallback to cache