Document -target as mandatory when building the shader metallib

[arkavo-com]

Why

The shader-build commands in CLAUDE.md pass no -target, so metal compiles for whatever the
installed SDK defaults to rather than for this package's .macOS(.v26) deployment target.

Kernels built for a newer OS than the one running them load fine, resolve every function, and
produce correct output — at roughly a quarter of the speed. Nothing about the result looks
wrong, which is exactly what makes it dangerous.

This is not hypothetical

It shipped in arkavo-agent 0.4.0 and cost ~4x on decode. Measured on an M4 mini, gemma-4 E2B
Q4_K_M, same binary with only the kernel library swapped:

kernel library	decode marginal
air64_v29-apple-macosx27.0.0 (target defaulted)	15.9 tok/s
air64_v28-apple-macosx26.0.0 (target explicit)	62.5 tok/s

Root cause and fix: arkavo-ai/arkavo-agent#192.

Why this repo has not been bitten yet

Sources/VRMMetalKit/Resources/VRMMetalKitShaders.metallib is currently
air64_v28-apple-macosx26.0.0 — correct. But that is because it was built in Oct 2025, before
the SDK default moved, not because the documented commands are right. The default is correct
until a toolchain bump moves it. Rebuilding that metallib today under Xcode 27 with the commands
as written produces air64_v29-apple-macosx27.0.0 and the slowdown, with no source change and
nothing in review to catch it.

What changed

Docs only — no code, no rebuilt binary.

• -target air64-apple-macos26.0 on the compile step, with an explanation of why it is not optional.
• The link step moves from the metallib packager to the metal driver, which validates its
  inputs against the target it links for. metallib accepts whatever AIR it is handed.
• A metal-lipo -info verification step to run before committing a rebuilt metallib
  (air64_v28 expected; v29 means the target was defaulted).
• A note that the committed metallib is macOS-only, so on iOS the loader falls through to
  makeDefaultLibrary(); an iOS artifact would need its own -target air64-apple-ios26.0 build.

Branch name is fix/workflow for historical reasons — it carried unrelated work that has since
landed on main, and this is now the only commit on it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xw8w7bQMjujBgZYiqPzVur

[gitar-bot]

💡 Quality: Benchmark figure in doc (59.6 tok/s) differs from PR description (62.5)

The PR description's comparison table reports 62.5 tok/s for the explicit-target case, but the committed CLAUDE.md text (and commit message) says 59.6 tok/s for the same comparison. This won't affect build correctness, but a reader cross-referencing the linked arkavo-agent PR #192 or the PR description against the doc may be confused by the mismatched number. Reconcile the figure so the doc and the PR narrative agree (e.g. update the PR description or the doc text to the same value).

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by August 1. Add seats for more headroom.
Learn more

Code Review 👍 Approved with suggestions 0 resolved / 1 findings

Documents the mandatory -target flag in CLAUDE.md for building shader metallib files to prevent performance degradation from SDK default mismatches. Consider reconciling the benchmark figure in the documentation with the PR description.

💡 Quality: Benchmark figure in doc (59.6 tok/s) differs from PR description (62.5)

📄 CLAUDE.md:232-234

The PR description's comparison table reports 62.5 tok/s for the explicit-target case, but the committed CLAUDE.md text (and commit message) says 59.6 tok/s for the same comparison. This won't affect build correctness, but a reader cross-referencing the linked arkavo-agent PR #192 or the PR description against the doc may be confused by the mismatched number. Reconcile the figure so the doc and the PR narrative agree (e.g. update the PR description or the doc text to the same value).

🤖 Prompt for agents

Code Review: Documents the mandatory -target flag in CLAUDE.md for building shader metallib files to prevent performance degradation from SDK default mismatches. Consider reconciling the benchmark figure in the documentation with the PR description.

1. 💡 Quality: Benchmark figure in doc (59.6 tok/s) differs from PR description (62.5)
   Files: CLAUDE.md:232-234

   The PR description's comparison table reports 62.5 tok/s for the explicit-target case, but the committed CLAUDE.md text (and commit message) says 59.6 tok/s for the same comparison. This won't affect build correctness, but a reader cross-referencing the linked arkavo-agent PR #192 or the PR description against the doc may be confused by the mismatched number. Reconcile the figure so the doc and the PR narrative agree (e.g. update the PR description or the doc text to the same value).

_{Was this helpful? React with 👍 / 👎 | Gitar}