fix(release): bundle default.metallib in release tarball

- Add 'Find and copy default.metallib' step to capture the freshly
  compiled metallib from .build/ artifacts (built against macOS 15 SDK)
- Package step now includes default.metallib alongside the binary so
  the tarball is fully self-contained on any Apple Silicon Mac
- Hard-fail the release if metallib is not found in build artifacts
- Update README Quick Start: document metallib co-location requirement,
  add Metal GPU error callout with fix, correct --stream-experts flag syntax
- Fix release notes Quick Start snippet to reflect bundled metallib

Author: solderzzc

.github/workflows/release.yml

@@ -69,12 +69,29 @@ jobs:
           file .build/release/SwiftLM
           .build/release/SwiftLM --help || true
 
+      - name: Find and copy default.metallib
+        run: |
+          # The Metal shader library is compiled as part of mlx-swift during
+          # `swift build`. Find it in the build artifacts and copy it to the
+          # repo root so the package step can pick it up.
+          METALLIB=$(find .build -name "default.metallib" | head -1)
+          if [ -z "$METALLIB" ]; then
+            echo "ERROR: default.metallib not found in build artifacts!"
+            exit 1
+          fi
+          echo "Found metallib: $METALLIB"
+          cp "$METALLIB" default.metallib
+          file default.metallib
+
       - name: Package binary
         run: |
           mkdir -p release
           cp .build/release/SwiftLM release/
+          cp default.metallib release/
           cp LICENSE README.md release/
           cd release
+          # Verify the tarball will be self-contained before archiving
+          ls -lh
           tar -czvf ../SwiftLM-${{ steps.tag.outputs.name }}-macos-arm64.tar.gz .
 
       - name: Upload artifact
@@ -110,10 +127,11 @@ jobs:
           ### Quick Start
           ```bash
           tar -xzf SwiftLM-${{ steps.tag.outputs.name }}-macos-arm64.tar.gz
+          # default.metallib is included — run from the extracted directory
           ./SwiftLM --model mlx-community/Qwen2.5-3B-Instruct-4bit --port 5413
           ```
 
-          > **Note:** Requires `mlx.metallib` next to the binary for GPU compute. See [README](https://github.com/SharpAI/SwiftLM#metal-shader-library) for setup.
+          > **Note:** `default.metallib` is bundled in this archive. Keep it in the same directory as the `SwiftLM` binary — Metal GPU compute will fail if it is missing.
           RELEASE_EOF
 
       - name: Create release

README.md

@@ -95,24 +95,35 @@ Then in Xcode:
 ## 🛠️ Quick Start (macOS Server)
 
 ### Fastest: Download Pre-built Binary
-The absolute fastest way to get started is to [download the latest pre-compiled macOS binary](https://github.com/SharpAI/SwiftLM/releases) directly from the Releases page. Just extract it and run!
+
+Download the latest release tarball from the [Releases page](https://github.com/SharpAI/SwiftLM/releases).
+The archive is **self-contained** — `default.metallib` is bundled alongside the binary.
+
+```bash
+tar -xzf SwiftLM-<version>-macos-arm64.tar.gz
+
+# Run from the extracted directory — default.metallib must be co-located with the binary
+./SwiftLM --model mlx-community/Qwen2.5-3B-Instruct-4bit --port 5413
+```
+
+> **⚠️ Metal GPU Error?** If you see `Failed to load the default metallib`, it means `default.metallib` is missing from the directory you are running `SwiftLM` from. Make sure you run the binary **from the extracted folder** and do not move the binary without also moving `default.metallib` alongside it.
 
 ### Build from Source
 
 ```bash
 swift build -c release
 ```
 
-### Run (Downloads model natively on first launch)
+When building from source the Metal shader library is compiled automatically by the Swift build system and placed next to the binary in `.build/release/`. Run from that directory:
 
 ```bash
 .build/release/SwiftLM \
-  --model Qwen3.5-122B-A10B-4bit \
-  --stream-experts true \
+  --model mlx-community/Qwen3.5-122B-A10B-4bit \
+  --stream-experts \
   --port 5413
 ```
 
-*(Note: Add `--stream-experts=true` if you are attempting to run oversized MoE models like Qwen3.5 122B to bypass macOS virtual memory swapping!)*
+*(Add `--stream-experts` when running oversized MoE models like Qwen3.5 122B to bypass macOS virtual memory swapping and stream expert layers directly from NVMe.)*
 
 ---