Add Apple Metal compute documentation suite

[qhy991]

Summary

Add a substantial Apple Metal compute documentation suite for Context Hub, with a cpp-first focus for macOS kernel and host-wrapper development.

Changes

• Add 48 new Apple Metal documentation pages under content/apple/docs/...
• Cover core compute topics:
  • kernel basics
  • compute launch patterns
  • memory and threadgroup usage
  • simdgroup patterns
  • buffer layout and alignment
  • resource binding and host wrapper patterns
• Cover optimization and pipeline topics:
  • tiled matmul
  • reduction
  • image and 2D kernels
  • command buffer reuse and batching
  • library and pipeline compilation
  • argument buffers and residency
  • heaps, fences, and events
  • producer-consumer staging
  • double-buffered pipelines
  • kernel fusion tradeoffs
• Cover irregular and advanced workload topics:
  • prefix scan
  • transpose and layout reorder
  • histogram and binning
  • gather/scatter and conflict resolution
  • segmented reduction
  • ragged and masked kernels
  • streaming and online kernels
  • multistage tensor pipelines
• Cover debugging and numerical topics:
  • validation and profiling workflow
  • numerical drift debugging
  • silent NaN/Inf debugging
  • softmax/logsumexp stability
  • host-device synchronization
  • memory pressure checklist
  • prefetch/reuse heuristics
  • transpose-free layout choices
• Add one Python boundary doc for PyTorch MPS vs custom Metal:
  • content/apple/docs/pytorch-mps-vs-custom-metal/python/DOC.md
• Expand search regression coverage from existing CUDA/PTX-focused cases to include 64 total cases, including Apple Metal queries
• Refresh scripts/search_regression_baseline.json

What

This adds a practical, agent-friendly Apple Metal documentation track so coding agents can retrieve authoritative guidance for macOS compute kernel development without falling back immediately to generic web search.

The new docs are written to support:

• Metal kernel authoring
• Objective-C++ / C++ host-side launch patterns
• pipeline and staging design
• synchronization and resource lifetime reasoning
• numerical debugging and profiling workflows

Why

Context Hub already had strong CUDA/PTX coverage, but there was no comparable local documentation path for Metal.

That gap matters because Metal compute development has its own semantics and failure modes:

• threadgroup and simdgroup behavior differ from CUDA warp/block assumptions
• host-device coordination and resource residency are frequent sources of bugs
• many failures are wrapper- or pipeline-level rather than kernel-math-level
• agents can easily confuse Metal, MPS, and PyTorch mps unless local docs make those boundaries explicit

This PR improves local retrieval quality for Apple Metal topics and gives agents a cpp-first reference path for macOS GPU programming.

Testing

Content quality:

• English-only content under content/apple/docs
• Proper YAML frontmatter on all new docs
• Apple-official source links included in each page
• Structured for retrieval and practical implementation guidance rather than raw API dumps

Build and regression:

• ./cli/bin/chub build content --validate-only — passed (1670 docs, 6 skills, 0 warnings)
• ./cli/bin/chub build content — passed
• python3 scripts/search_regression.py --mode check — passed (64/64)
• python3 scripts/search_regression.py --mode snapshot --snapshot-out scripts/search_regression_baseline.json — passed
• rg -n "[\p{Han}]" content/apple/docs | wc -l — 0

Sources

Apple official documentation used for extraction:

• Metal resources: https://developer.apple.com/metal/resources/
• Compute passes: https://developer.apple.com/documentation/metal/compute-passes
• Performing calculations on a GPU: https://developer.apple.com/documentation/metal/performing-calculations-on-a-gpu
• Calculating threadgroup and grid sizes: https://developer.apple.com/documentation/metal/calculating-threadgroup-and-grid-sizes
• Processing a texture in a compute function: https://developer.apple.com/documentation/metal/processing-a-texture-in-a-compute-function
• Implementing a multistage image filter using heaps and events: https://developer.apple.com/documentation/metal/implementing-a-multistage-image-filter-using-heaps-and-events
• Improving CPU performance by using argument buffers: https://developer.apple.com/documentation/metal/improving-cpu-performance-by-using-argument-buffers
• useResource(_:usage:): https://developer.apple.com/documentation/metal/mtlcomputecommandencoder/useresource%28_%3Ausage%3A%29
• Encoding indirect command buffers on the CPU: https://developer.apple.com/documentation/metal/encoding-indirect-command-buffers-on-the-cpu
• Encoding indirect command buffers on the GPU: https://developer.apple.com/documentation/metal/encoding-indirect-command-buffers-on-the-gpu
• Synchronizing passes with a fence: https://developer.apple.com/documentation/metal/synchronizing-passes-with-a-fence
• Synchronizing a managed resource in macOS: https://developer.apple.com/documentation/metal/synchronizing-a-managed-resource-in-macos
• Metal developer tools: https://developer.apple.com/metal/tools/
• Metal shader converter: https://developer.apple.com/metal/shader-converter/
• Metal Programming Guide archive: https://developer.apple.com/library/archive/documentation/Miscellaneous/Conceptual/MetalProgrammingGuide/Cmd-Submiss/Cmd-Submiss.html
• Metal Programming Guide, Resource Heaps: https://developer.apple.com/library/archive/documentation/Miscellaneous/Conceptual/MetalProgrammingGuide/ResourceHeaps/ResourceHeaps.html
• Metal Best Practices, Persistent Objects: https://developer.apple.com/library/archive/documentation/3DDrawing/Conceptual/MTLBestPracticesGuide/PersistentObjects.html
• Metal Best Practices, Command Buffers: https://developer.apple.com/library/archive/documentation/3DDrawing/Conceptual/MTLBestPracticesGuide/CommandBuffers.html
• Metal Best Practices, Indirect Buffers: https://developer.apple.com/library/archive/documentation/3DDrawing/Conceptual/MTLBestPracticesGuide/IndirectBuffers.html
• Metal Best Practices, Resource Options: https://developer.apple.com/library/archive/documentation/3DDrawing/Conceptual/MTLBestPracticesGuide/ResourceOptions.html

PyTorch official documentation used for the boundary doc:

• MPS backend notes: https://docs.pytorch.org/docs/stable/notes/mps
• torch.mps docs: https://docs.pytorch.org/docs/stable/mps.html

Notes

Primary sources used for extraction were Apple Metal official documentation and tools pages, with PyTorch docs used only for the MPS-vs-custom-Metal boundary doc.