docs: add README, CLAUDE.md, AGENTS.md, and full docs/ suite

- README.md: project overview, quick start, command reference, workflow
- CLAUDE.md: AI safety rules, technical details, conventions
- AGENTS.md: agent workflows, file responsibility map, dependency matrix
- docs/architecture.md: script layers, data flow, unified memory, JSON schemas
- docs/optimization.md: step-by-step optimization walkthrough
- docs/benchmarking.md: methodology, test params, result interpretation
- docs/troubleshooting.md: common issues and fixes
- docs/references.md: centralized external links (single source of truth)
- docs/bios-vram-guide.md: add back-link to optimization workflow

Cross-linked non-redundantly: each doc owns one layer, others link to it.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md — Agent Workflows
+
+Read [CLAUDE.md](CLAUDE.md) first for safety rules and technical context.
+
+## Common Workflows
+
+### Add a Detection Function
+
+1. Add the function to `lib/detect.sh` following `detect_*` naming convention
+2. If it reads sysfs, use `$GPU_SYSFS` (auto-detected) with a `2>/dev/null` fallback
+3. Wire it into `scripts/audit/quick-glance.sh` (display) and/or `scripts/audit/system-report.sh` (JSON output)
+4. If it has an optimal value, add a check to `scripts/optimize/verify.sh`
+5. Validate: `make audit` and `bin/audit --json | python3 -m json.tool`
+
+### Add a Benchmark Backend
+
+1. Add the toolbox entry to `BENCH_PATHS` associative array in both `scripts/benchmark/run-baseline.sh` and `scripts/benchmark/run-suite.sh`
+2. Map the toolbox name → llama-bench binary path (Vulkan: `/usr/sbin/llama-bench`, ROCm: `/usr/local/bin/llama-bench`)
+3. If ROCm, the `ENV_ARGS` logic already handles `ROCBLAS_USE_HIPBLASLT=1`
+4. Add the toolbox to `refresh-toolboxes.sh` in the [toolboxes repo](https://github.com/kyuz0/amd-strix-halo-toolboxes)
+5. Validate: `make benchmark-setup` then `make benchmark`
+
+### Add an Optimization Script
+
+1. Create `scripts/optimize/my-optimization.sh` sourcing `lib/common.sh` (and `detect.sh` / `format.sh` as needed)
+2. Add root check at top if the script modifies system state: `[[ $EUID -ne 0 ]] && { log_error "Requires root"; exit 1; }`
+3. Add a corresponding case to `bin/optimize`
+4. Add a Makefile target
+5. Add verification criteria to `scripts/optimize/verify.sh`
+6. If the optimization is reversible, add rollback logic to `scripts/optimize/rollback.sh`
+7. Document in [docs/optimization.md](docs/optimization.md)
+
+### Add a Monitoring Metric
+
+1. In `scripts/monitor/log-metrics.sh`, cache the sysfs path at startup (avoid per-sample globbing)
+2. Read with `read -r var < "$SYSFS_PATH" 2>/dev/null || var=0` (no subshells in the hot loop)
+3. Add the column to the CSV header and the `echo` line
+4. Update the CSV schema in [docs/architecture.md](docs/architecture.md)
+
+## File Responsibility Map
+
+| Want to change... | Touch these files |
+|-------------------|-------------------|
+| What `make audit` shows | `scripts/audit/quick-glance.sh`, `lib/detect.sh` |
+| JSON audit output | `scripts/audit/system-report.sh`, `lib/detect.sh` |
+| Dashboard layout | `scripts/monitor/dashboard.sh` |
+| Metric collection | `scripts/monitor/log-metrics.sh` |
+| Benchmark parameters | `scripts/benchmark/run-baseline.sh`, `run-suite.sh` |
+| Result comparison | `scripts/benchmark/compare.sh` |
+| Kernel params | `scripts/optimize/kernel-params.sh`, `lib/detect.sh` (recommended values) |
+| Optimization checks | `scripts/optimize/verify.sh`, `scripts/audit/quick-glance.sh` |
+| Shared utilities | `lib/common.sh` (logging), `lib/format.sh` (output), `lib/detect.sh` (hardware) |
+| External links | `docs/references.md` (single source of truth) |
+
+## Dependencies by Workflow
+
+| Workflow | Requires |
+|----------|----------|
+| Audit | `bc`, `python3` |
+| Monitor | `tmux`, `amdgpu_top` or `nvtop`, `btop` or `htop` |
+| Benchmark | `toolbox`, `podman`, GGUF models in `data/models/`, `python3` |
+| Optimize | `sudo`/root, `grubby` or `grub2-mkconfig`, `tuned-adm`, `python3` |