docs: address review feedback for README and ADRs

- Fix test count from 493+ to 490+ in README
- Fix fd.json example in ADR-007 to use shfmt (actual github_release_binary user)
- Add missing installers to ADR-007 Tier 2 table (docker_plugin, github_clone, npm_self_update)
- Document auto/reconciliation install method in ADR-007
- Add upgrade/update naming note to ADR-008

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>

Author: CybotTM

README.md

@@ -453,7 +453,7 @@ python3 -m pyflakes cli_audit.py
 
 - Run tests:
 ```bash
-make test              # Run all 493+ tests
+make test              # Run all 490+ tests
 make test-unit         # Unit tests only
 make test-coverage     # With coverage report
 make test-parallel     # Parallel via pytest-xdist

docs/adr/ADR-007-generic-tool-installation-architecture.md

@@ -25,12 +25,16 @@ Each tool is described by a `catalog/<tool>.json` file containing metadata and i
 
 ```json
 {
-  "name": "fd",
+  "name": "shfmt",
   "install_method": "github_release_binary",
-  "binary_name": "fd",
-  "github_repo": "sharkdp/fd",
-  "download_url_template": "https://github.com/sharkdp/fd/releases/download/v{version}/fd-v{version}-{arch}-unknown-linux-gnu.tar.gz",
-  "tags": ["core", "search"]
+  "binary_name": "shfmt",
+  "github_repo": "mvdan/sh",
+  "download_url_template": "https://github.com/mvdan/sh/releases/download/{version}/shfmt_{version}_linux_{arch}",
+  "arch_map": {
+    "x86_64": "amd64",
+    "aarch64": "arm64",
+    "armv7l": "arm"
+  }
 }
 ```
 
@@ -48,8 +52,13 @@ Generic installer scripts under `scripts/installers/` implement each installatio
 | `uv_tool.sh` | `uv tool install` for Python packages | semgrep, ruff, black |
 | `npm_global.sh` | `npm install -g` | eslint, prettier |
 | `package_manager.sh` | System package managers (apt/brew/dnf) | sponge, pipx |
+| `docker_plugin.sh` | Docker plugins | compose |
+| `github_clone.sh` | Clone and build from source | rbenv, ruby-build |
+| `npm_self_update.sh` | NPM self-update | npm |
 | `dedicated_script.sh` | Delegate to a tool-specific script | python, node, docker |
 
+**Note on `auto` install method:** 11 tools (including fd, ripgrep, bat, and hyperfine) use `"install_method": "auto"` instead of specifying a fixed installer. The `auto` method uses the reconciliation system (`scripts/lib/reconcile.sh`) to detect existing installations and choose the best available method from the tool's `available_methods` list in the catalog. This allows the system to adapt to the user's environment (e.g., preferring a GitHub binary release over cargo over apt, depending on what is already installed and available).
+
 ### Tier 3: Orchestrator
 
 `scripts/install_tool.sh` is the central orchestrator that:

docs/adr/ADR-008-makefile-pattern-target-fallback.md

@@ -104,6 +104,8 @@ These are evaluated at Makefile parse time, not at target execution time. The `i
 | `uninstall-%` | `uninstall` |
 | `reconcile-%` | `reconcile` |
 
+**Note on upgrade/update naming:** The user-facing Make target is `upgrade-%`, but it passes `update` as the action parameter to the underlying scripts. This is for historical compatibility -- the installer scripts originally used `update` as the action name. The Makefile uses the more intuitive `upgrade` terminology for the user interface.
+
 ### Testing the fallback
 
 ```bash