Files

Felipe Cardoso 5b81437637 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>

2026-03-25 20:50:00 +01:00

3.2 KiB

Raw Blame History

CLAUDE.md — AI Assistant Context

Optimization toolkit for AMD Strix Halo (Ryzen AI MAX+ 395, Radeon 8060S gfx1151, 64 GB unified memory) on Fedora 43. Pure bash scripts with inline Python for JSON handling and GRUB editing. See README.md for user-facing commands.

Architecture

bin/ dispatchers → scripts/ implementations → lib/ shared libraries. All scripts source libs in order: common.sh → detect.sh → format.sh. Runtime data goes to data/ (gitignored). Full details in docs/architecture.md.

Safety Rules

scripts/optimize/kernel-params.sh modifies /etc/default/grub — requires root, backs up to data/backups/ first. Always maintain the Python-with-env-vars pattern for GRUB editing (no shell variable interpolation into Python code).
scripts/optimize/tuned-profile.sh and rollback.sh require root and save previous state for rollback.
data/backups/ contains GRUB backups and tuned profile snapshots — never delete these.
Optimization scripts that require root check $EUID at the top and exit immediately if not root.
All Python blocks receive data via environment variables (os.environ), never via shell interpolation into Python source. This prevents injection. Do not revert to '''$var''' or "$var" patterns inside Python heredocs.

Key Technical Details

GPU sysfs: Auto-detected by find_gpu_card() in lib/detect.sh (matches vendor 0x1002). Falls back to first card with mem_info_vram_total.
Memory recommendations: recommended_gttsize_mib() in detect.sh computes from total physical RAM = visible RAM + dedicated VRAM (the VRAM is still physical memory). Floor at 1 GiB.
Kernel param detection: detect_kernel_param() uses word-boundary-anchored regex to avoid iommu matching amd_iommu.
Benchmark invocation: toolbox run -c NAME -- [env ROCBLAS_USE_HIPBLASLT=1] /path/to/llama-bench -ngl 99 -mmp 0 -fa 1 -r N. ENV_ARGS passed as a proper bash array (not string splitting).
llama-bench output: Pipe-delimited table. Python parser at fixed column indices (parts[8]=test, parts[9]=t/s). Format changes upstream would break parsing.
ROCm for gfx1151: ROCBLAS_USE_HIPBLASLT=1, HSA_OVERRIDE_GFX_VERSION=11.5.1.
Fedora GRUB: Prefers grubby (BLS) over grub2-mkconfig. Both paths are handled.

Conventions

set -euo pipefail in every executable script
snake_case function names, UPPER_CASE for constants and loop variables
4-space indentation, no tabs
lib/ files are sourced (no shebang enforcement), but include #!/usr/bin/env bash for editor support
Colors gated on [[ -t 1 ]] (disabled when piped)
bc used for float math; python3 for JSON and GRUB editing only

Validating Changes

make audit          # Quick check — shows system status with pass/fail indicators
make verify         # 9-point optimization checklist
bin/audit --json | python3 -m json.tool   # Verify JSON output is valid

External Resources

All external links are centralized in docs/references.md. Key ones:

AMD ROCm Strix Halo guide (kernel params, GTT configuration)
Donato Capitella toolboxes (container images, benchmarks, VRAM estimator)

3.2 KiB Raw Blame History