kernelport 0.1.0__tar.gz

kernelport-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.png binary

kernelport-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  # PRs: newest push wins. main: one group per commit, so every commit gets a full run.
+  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    # CPU-only: analyzer, harness, reports, MCP protocol, setup, CPU (Numba) backend,
+    # and the fake-runtime contract tests for metal / hip / agent. GPU tests skip.
+    name: tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install (CPU torch)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install -e ".[cpu,dev]"
+      - name: kernelport doctor
+        run: kernelport doctor
+      - name: Tests
+        run: python -m pytest -q -rs
+
+  metal:
+    # GitHub's macOS arm64 runners are Apple Silicon VMs ("Apple M1 (Virtual)") with a real
+    # Metal device, so every zoo metal port is verified for real on each push. The originals
+    # show UNVERIFIED here (no CUDA); the ports are checked against the stored references.
+    name: metal zoo (macos arm64, MLX)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[metal,dev]"
+      - name: MLX device
+        # Fail loudly rather than letting the Mac tests skip if the runner loses its Metal device.
+        run: python -c "import mlx.core as mx; print(mx.default_device()); assert mx.metal.is_available()"
+      - name: Metal backend tests
+        run: python -m pytest -q -rs tests/test_metal_backend.py
+      - name: Metal zoo
+        run: kernelport zoo --backend metal --no-bench
+      - name: llm.c example (Metal ports vs references frozen on NVIDIA)
+        working-directory: examples/llm.c
+        run: |
+          kernelport verify --backend metal
+          kernelport status
+      - uses: actions/upload-artifact@v4
+        with:
+          name: llmc-results-metal
+          path: examples/llm.c/.kernelport/kernels/*/ports/metal/results/*.json
+
+  webgpu:
+    # WGSL ports through wgpu-native: Mesa llvmpipe (software Vulkan) on Linux, Metal on macOS.
+    # Cases larger than an adapter's binding limit are reported as not tested, not as FAIL.
+    name: webgpu zoo (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Vulkan (lavapipe)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update -q && sudo apt-get install -y -q mesa-vulkan-drivers
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install -e ".[webgpu,dev]"
+      - name: Adapter
+        run: python -c "import wgpu; a = wgpu.gpu.request_adapter_sync(); print(a.info); print(sorted(a.features))"
+      - name: WebGPU backend tests
+        run: python -m pytest -q -rs tests/test_webgpu_backend.py
+      - name: WebGPU zoo
+        run: kernelport zoo --backend webgpu --no-bench
+      - name: llm.c example (WGSL ports vs references frozen on NVIDIA)
+        working-directory: examples/llm.c
+        run: |
+          kernelport verify --backend webgpu
+          kernelport status
+      - uses: actions/upload-artifact@v4
+        with:
+          name: llmc-results-webgpu-${{ matrix.os }}
+          path: examples/llm.c/.kernelport/kernels/*/ports/webgpu/results/*.json
+
+  package:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Smoke test the wheel (core install, no torch)
+        run: |
+          python -m venv /tmp/wheel-env
+          /tmp/wheel-env/bin/pip install dist/*.whl
+          cd /tmp && /tmp/wheel-env/bin/kernelport --help
+          /tmp/wheel-env/bin/python -c "import kernelport.mcp_server, kernelport.tools"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

kernelport-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Publishes to PyPI when a version tag (v0.1.0, ...) is pushed.
+# One-time setup on pypi.org: add a "trusted publisher" for this repo with
+# workflow file "release.yml" and environment "pypi". No API token is stored here.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches version
+        run: |
+          v=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != pyproject version $v"; exit 1; }
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

kernelport-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.kernelport/
+*.html.tmp
+
+# Committed example workspaces (frozen references, ports, results) are part of the repo.
+!examples/*/.kernelport/

kernelport-0.1.0/LAUNCH_PLAN.md

@@ -0,0 +1,118 @@
+# kernelport: status and launch plan
+
+*Written 2026-10-13, at commit `a376f38`. Updated 2026-10-14: Metal verified in CI, CI + release
+workflow, Colab freeze flow, autotuning.*
+
+## Where we are
+
+**About 85% of the way to a solid public v0.1, and roughly 60% of a mature product.**
+All 16 planned milestones (M0–M16) are built, committed and pushed. The test suite has
+262 passing and 43 skipped locally (the skips need a Mac, an AMD GPU, or the optional `wgpu`
+package). CI runs the CPU suite on Linux, macOS and Windows and the Metal zoo on Apple Silicon.
+What's left is mostly real-world proof and polish, not features.
+
+### Backend status
+
+| Backend | Status | Zoo ports passing |
+|---|---|---|
+| Triton | working, verified on an RTX 5060 Laptop GPU | 12/12 (fp32, fp16, bf16); 1.0–1.3× the original CUDA, matmul 6.2× |
+| CPU (Numba) | working, verified | 12/12 (fp32) |
+| WebGPU (WGSL via wgpu-native) | working, verified on the RTX 5060 through Vulkan | 12/12 (fp32, fp16) |
+| Metal (MLX) | working, verified in CI on an Apple M1 (GitHub macOS runner) | 12/12 (fp32, fp16, bf16) |
+| HIP (hipRTC) | runner and ports written, launch path tested on NVIDIA, **not verified on AMD** | 12 written |
+
+### What has been tested
+
+- Full workflow through the real MCP server (dogfood): 3/3 references frozen on the first try,
+  6/6 ports PASS, 2 needed one repair each, both diagnosed from the failure report.
+- `kernelport setup` against a real Claude Code install (server connected, skill discovered),
+  then `--uninstall`; `~/.claude.json` was confirmed identical to the pre-setup snapshot.
+- Deliberately broken ports for every working backend fail for the right reason.
+- The built-in agent (`kernelport agent`) is tested only with a scripted fake client.
+  No live API calls have been made.
+
+## Must fix before launch
+
+1. ~~**Verify Metal on an Apple Silicon Mac.**~~ **Done 2026-10-14.** GitHub's macOS arm64 runners
+   have a real Metal device; all 12 zoo ports pass every case and CI re-checks them on every push.
+   (Still worth one run on a physical Mac for timings, which a virtualized runner cannot give.)
+2. ~~**Fresh-agent dogfood.**~~ **Done 2026-10-14:** 4/4 kernels PASS on the first verify; its feedback
+   is fixed (see PROGRESS.md). Still worth repeating with Codex / Cursor. So far a person (who already knew the kernels) drove the tools.
+   Give a clean Claude Code or Codex session only "port the CUDA kernels in this repo to
+   Triton and verify them" and record pass rate, attempts, and where the skill was unclear.
+3. **Easy install.**
+   - Publish to PyPI. The name `kernelport` was free on 2026-10-14; `release.yml` publishes on a `v*`
+     tag once a trusted publisher is set up on pypi.org (owner action).
+   - ~~GitHub Actions CI: CPU-only tests on Linux, macOS and Windows.~~ Done.
+   - A one-line install path. Today the CUDA build of torch has to come from the PyTorch index first.
+   - Only Windows has been tested so far.
+4. **Make the NVIDIA reference step easy to work around.** Validating a reference runs the
+   original CUDA kernel, so it needs an NVIDIA GPU, and the main target audience (Mac users)
+   often has none. Options:
+   - ~~document "validate once on a GPU machine or free Colab, commit `.kernelport/`, verify anywhere"~~ Done
+     (docs/installation.md, and the skill tells agents what to do on UNAVAILABLE);
+   - ~~ship a Colab notebook that validates and freezes references for a repo~~ Done:
+     `notebooks/freeze_references_colab.ipynb` + `kernelport validate --all` (not yet run on Colab itself).
+5. ~~**Prove it on real code.**~~ **Done 2026-10-14:** `examples/llm.c`, five unmodified llm.c kernels
+   (host code, cuBLAS headers, macros, `Packed128` templates) validated, ported to Triton (NVIDIA) and
+   Metal (CI), plus a real precondition bug found. Still open: a multi-file project that calls
+   cuBLAS from kernels' callers, and kernels generated by macros (the slicer and analyzer are lexical).
+
+## Would make it noticeably better
+
+- ~~**Autotuning after PASS**~~ Done: `tune_port` / `kernelport tune` verifies every variant and only
+  keeps a clear, noise-resistant win.
+- **Browser demo page:** paste a CUDA kernel and watch the WGSL port get verified on your own GPU.
+- **A report worth screenshotting:** the HTML report is what people will share.
+- **A HIP run on AMD**, for example on a rented cloud GPU.
+- **Browser check for WGSL ports** (Playwright and Chromium, about 150 MB) to confirm they
+  also pass in Chrome, not just wgpu-native.
+- **Live smoke test of `kernelport agent`** (needs an API key; costs credits).
+
+## Could it trend on GitHub?
+
+**It has a real chance, but only with a deliberate launch.** Nothing reaches trending just by
+being pushed.
+
+**In its favour**
+- The hook is timely: CUDA lock-in, Apple Silicon and AI coding agents are all hot topics.
+- A distinctive angle. Existing CUDA-portability tools (HIPIFY, ZLUDA, SCALE, chipStar) are
+  translators or compatibility layers. As far as I know, none combine agents writing the ports
+  with a harness that refuses to say PASS without proof on real hardware.
+  Pitch: **"proven correct, not just translated."**
+- Agent-native: one-command `kernelport setup` for Claude Code, Codex, Cursor and Gemini CLI
+  makes "try it in 2 minutes" believable.
+
+**Against it**
+- Without a demo it's an abstract developer tool.
+- The NVIDIA-for-validation requirement can confuse the target audience.
+- Some people are sceptical of "AI ports your code". The verification angle answers that, so lead with it.
+
+### What gets repos onto trending
+
+1. **A 30–60 s demo video or GIF:** clone a CUDA-only repo, one prompt, a green report with
+   kernels passing on a MacBook.
+2. **A recognisable target:** "we ran X's CUDA kernels on a Mac, verified" beats "12 zoo kernels".
+3. **Launch posts on the same day:** Show HN, r/LocalLLaMA, r/MachineLearning, and X
+   (tag the MLX and Triton communities). Trending is driven by stars per day, so concentrated
+   attention beats a slow trickle.
+4. **A README that sells in 10 seconds:** demo GIF at the top, three-line quick start, the
+   results table. The content exists; it needs the visual.
+
+## Suggested order
+
+1. ~~CI + PyPI packaging~~ (CI done; PyPI waits on the trusted-publisher setup)
+2. ~~Fresh-agent dogfood run~~ (done)
+3. ~~Mac verification run~~ (done in CI)
+4. ~~Port one well-known CUDA-only project end to end~~ (llm.c, done)
+5. Demo GIF and README polish
+6. Launch (same-day posts)
+
+## Rules kept during development
+
+- No large downloads; anything downloaded for testing is uninstalled afterwards (`wgpu` was,
+  so WebGPU tests skip until `pip install kernelport[webgpu]`).
+- No API credits spent.
+- Any edit to real agent config (`~/.claude.json`) is reverted after testing.
+
+Full technical history and resume notes: [PROGRESS.md](PROGRESS.md).

kernelport-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kernelport contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kernelport-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: kernelport
+Version: 0.1.0
+Summary: Bring CUDA-only kernels to Mac, AMD, browsers, and CPU, with proof they are correct.
+Project-URL: Homepage, https://github.com/PS12007/kernelport
+Project-URL: Documentation, https://github.com/PS12007/kernelport/tree/main/docs
+Project-URL: Issues, https://github.com/PS12007/kernelport/issues
+Author: kernelport contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cuda,gpu,hip,kernels,mcp,metal,triton,webgpu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.11
+Requires-Dist: mcp>=2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.40; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: cupy-cuda12x>=13; extra == 'all'
+Requires-Dist: mlx>=0.22; (sys_platform == 'darwin') and extra == 'all'
+Requires-Dist: numba>=0.60; extra == 'all'
+Requires-Dist: nvidia-cuda-nvrtc-cu12; extra == 'all'
+Requires-Dist: nvidia-cuda-runtime-cu12; extra == 'all'
+Requires-Dist: pytest>=8; extra == 'all'
+Requires-Dist: torch>=2.4; extra == 'all'
+Requires-Dist: torch>=2.7; extra == 'all'
+Requires-Dist: triton-windows>=3.3; (sys_platform == 'win32') and extra == 'all'
+Requires-Dist: triton>=3.3; (sys_platform == 'linux') and extra == 'all'
+Requires-Dist: wgpu>=0.30; extra == 'all'
+Provides-Extra: cpu
+Requires-Dist: numba>=0.60; extra == 'cpu'
+Requires-Dist: torch>=2.4; extra == 'cpu'
+Provides-Extra: cuda
+Requires-Dist: cupy-cuda12x>=13; extra == 'cuda'
+Requires-Dist: nvidia-cuda-nvrtc-cu12; extra == 'cuda'
+Requires-Dist: nvidia-cuda-runtime-cu12; extra == 'cuda'
+Requires-Dist: torch>=2.7; extra == 'cuda'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: hip
+Requires-Dist: torch>=2.4; extra == 'hip'
+Provides-Extra: metal
+Requires-Dist: mlx>=0.22; (sys_platform == 'darwin') and extra == 'metal'
+Requires-Dist: torch>=2.4; extra == 'metal'
+Provides-Extra: ref
+Requires-Dist: torch>=2.4; extra == 'ref'
+Provides-Extra: triton
+Requires-Dist: torch>=2.7; extra == 'triton'
+Requires-Dist: triton-windows>=3.3; (sys_platform == 'win32') and extra == 'triton'
+Requires-Dist: triton>=3.3; (sys_platform == 'linux') and extra == 'triton'
+Provides-Extra: webgpu
+Requires-Dist: torch>=2.4; extra == 'webgpu'
+Requires-Dist: wgpu>=0.30; extra == 'webgpu'
+Description-Content-Type: text/markdown
+
+# kernelport
+
+[![CI](https://github.com/PS12007/kernelport/actions/workflows/ci.yml/badge.svg)](https://github.com/PS12007/kernelport/actions/workflows/ci.yml)
+
+Bring CUDA-only kernels to Mac, AMD, browsers, and CPU, with proof they are correct.
+
+kernelport is an **MCP server + agent skill + CLI**. Your coding agent (Claude Code, Codex,
+Cursor, Gemini CLI) writes the ports; kernelport runs them on real hardware and checks every
+one against a reference that was itself validated against the original CUDA kernel. A port is
+only ever reported as **PASS** if its current code ran on real hardware and matched.
+
+> Status: early release (0.1.0). Triton, CPU and WebGPU backends work and are verified;
+> Metal is verified on Apple Silicon in CI; the HIP runner and zoo ports are written but not yet
+> verified on an AMD GPU. See [PROGRESS.md](https://github.com/PS12007/kernelport/blob/main/PROGRESS.md).
+
+![kernelport status for nine llm.c kernels: Triton, Metal and WebGPU ports, each verified against a reference frozen on NVIDIA](https://raw.githubusercontent.com/PS12007/kernelport/main/docs/img/llmc-status.svg)
+
+*Real code, real hardware: [examples/llm.c](https://github.com/PS12007/kernelport/tree/main/examples/llm.c).*
+
+## How it works
+
+```
+your repo: kernels/*.cu
+      │  scan_kernels                    (lexical CUDA analyzer: params, kinds, features)
+      ▼
+ PyTorch reference + input spec          written by the agent
+      │  validate_reference              runs the ORIGINAL CUDA kernel on every case
+      ▼
+ frozen reference (sha256 manifest)      only a passing validation can freeze it
+      │  write_port / verify_port        port vs frozen reference, every case and dtype
+      ▼
+ PASS / FAIL (+ compact failure report) / UNVERIFIED (backend not available here)
+      │  bench_port                      only after PASS on this machine
+      ▼
+ report.html / report.md
+```
+
+The agent never sets tolerances, never edits the frozen reference, and gets at most 6 failed
+verification attempts per port. Those rules are enforced in the tools, not just in the
+skill. Details: [docs/how-it-works.md](https://github.com/PS12007/kernelport/blob/main/docs/how-it-works.md).
+
+## Quick start
+
+```bash
+# 1. install (CUDA build of torch first; see docs/installation.md)
+pip install --index-url https://download.pytorch.org/whl/cu128 torch
+pip install "kernelport[cuda,triton,cpu] @ git+https://github.com/PS12007/kernelport"
+
+# 2. check what can run here
+kernelport doctor
+
+# 3. register the MCP server and skill with your agents (shows every change, asks first)
+kernelport setup            # --print to only show instructions, --uninstall to undo
+```
+
+Then, in your repo, ask your agent:
+
+> port the CUDA kernels in this repo to Triton and verify them
+
+## Real code: llm.c's CUDA kernels on a Mac
+
+[`examples/llm.c`](https://github.com/PS12007/kernelport/tree/main/examples/llm.c) takes nine kernels from Karpathy's
+[llm.c](https://github.com/karpathy/llm.c) `dev/cuda/` (unmodified files, host code and all):
+layernorm, GELU, residual, encoder, online softmax, AdamW and cross-entropy, including bf16 and
+128-bit packed loads. References were validated against the original CUDA kernels and frozen on
+an RTX 5060, and all nine Triton ports pass there. The Metal ports pass on Apple Silicon in CI
+against those same frozen references. Four of the nine were ported by a fresh coding agent
+given only the one-line request and kernelport's guide; each of its ports passed on the first
+verification. Validation also found an undocumented precondition in llm.c:
+`softmax_forward_online_kernel8` leaves rows unwritten when C < block size.
+
+## Backends
+
+| backend | port language | runs on | status |
+|---|---|---|---|---|
+| `triton` | Triton (Python) | NVIDIA (triton / triton-windows), AMD ROCm | working |
+| `cpu` | Numba (Python) | any machine | working (float32/float64) |
+| `metal` | Metal kernel bodies via MLX `metal_kernel` | Apple Silicon | working (float32/float16/bfloat16), verified in CI on an Apple M1 |
+| `webgpu` | WGSL | any Vulkan / Metal / D3D12 GPU via wgpu-native (core WebGPU only, so browser-portable) | working (float32/float16); verified on NVIDIA (Vulkan), Apple (Metal) and llvmpipe (software Vulkan) |
+| `hip` | HIP C++ via hipRTC (CuPy ROCm) | AMD ROCm | written, launch path tested on NVIDIA, **not yet verified on AMD** |
+
+Ports for a backend that is not available on the current machine are saved as **UNVERIFIED**,
+never PASS. Commit `.kernelport/` and run `kernelport verify` on the right machine to verify them there.
+
+## No coding agent? Use the built-in one (optional)
+
+```bash
+pip install "kernelport[agent] @ git+https://github.com/PS12007/kernelport"
+export ANTHROPIC_API_KEY=...        # or: ant auth login
+kernelport agent "port the CUDA kernels in this repo to Triton and verify them"
+```
+
+`kernelport agent` runs Claude (default `claude-opus-5-5`) in a tool-use loop over the same 12
+tools the MCP server exposes, with the workflow skill as its system prompt. It can only act
+through those tools, so all writes stay in `.kernelport/` and it cannot run shell commands.
+Runs are billed to **your** Anthropic account, so it asks before starting (`--yes` skips the
+prompt). The run stops at `--max-turns` (default 80). Server-side refusal fallbacks are on by
+default (`--no-fallbacks` to disable).
+
+## The kernel zoo
+
+`zoo/` holds 12 CUDA kernels with launch specs and references: vector_add, relu, saxpy,
+transpose, reduce_sum, softmax, layernorm, rmsnorm, matmul_naive, rope, embedding_gather and
+cumsum. Between them they use templates, shared memory, `__syncthreads`, warp shuffles,
+atomics, block reductions, scans, gathers and int64 indices. Every original passes its reference.
+`kernelport zoo --backend triton|cpu` validates them and verifies the stored ports.
+
+Measured on an RTX 5060 Laptop GPU (sm_120) and an i7-14700HX (28 threads), bench case of each spec
+(the largest), float32. Every stored port passes every case: Triton in fp32/fp16/bf16, cpu in fp32, webgpu in fp32/fp16, metal in fp32/fp16/bf16 (on an Apple M1 GitHub Actions runner, checked on every push; no timings, a virtualized runner is not a fair benchmark). CI also runs the WGSL ports on Apple Metal and on llvmpipe; there the largest embedding_gather cases exceed those adapters' binding limits (128 MiB on llvmpipe) and are reported as not tested.
+
+| kernel | triton vs original CUDA | cpu (Numba) | webgpu (WGSL) | metal (MLX) |
+|---|---|---|---|---|
+| vector_add | PASS, 1.00x | PASS, 7.8 ms (n/c) | PASS, 1.12 ms (n/c) | PASS |
+| relu | PASS, 1.04x | PASS, 5.7 ms (n/c) | PASS, 1.06 ms (n/c) | PASS |
+| saxpy | PASS, 1.00x | PASS, 6.4 ms (n/c) | PASS, 1.08 ms (n/c) | PASS |
+| transpose | PASS, 1.00x | PASS, 11.2 ms (n/c) | PASS, 1.06 ms (n/c) | PASS |
+| reduce_sum | PASS, 1.04x | PASS, 3.4 ms (n/c) | PASS, 0.58 ms (n/c) | PASS |
+| softmax | PASS, 1.00x | PASS, 35.5 ms (n/c) | PASS, 0.67 ms (n/c) | PASS |
+| layernorm | PASS, 1.00x | PASS, 9.1 ms (n/c) | PASS, 0.96 ms (n/c) | PASS |
+| rmsnorm | PASS, 1.00x | PASS, 7.0 ms (n/c) | PASS, 1.13 ms (n/c) | PASS |
+| matmul_naive | PASS, 6.20x (tiled `tl.dot`, IEEE fp32) | PASS, 40.3 ms (n/c) | PASS, 4.21 ms (n/c) | PASS |
+| rope | PASS, 1.00x | PASS, 13.1 ms (n/c) | PASS, 1.42 ms (n/c) | PASS |
+| embedding_gather | PASS, 1.02x | PASS, 11.8 ms (n/c) | PASS, 1.46 ms (n/c) | PASS |
+| cumsum | PASS, 1.30x | PASS, 6.9 ms (n/c) | PASS, 1.18 ms (n/c) | PASS |
+
+(n/c = wall-clock time (CPU, or WebGPU including submission), not comparable to GPU kernel time.)
+
+## CLI
+
+Every MCP tool has a CLI equivalent, so you can drive the workflow by hand or from CI:
+
+| command | MCP tool | what it does |
+|---|---|---|
+| `kernelport doctor` | `kernelport_doctor` | OS, GPU, extras, each backend with a reason |
+| `kernelport scan [path]` | `scan_kernels` | find `__global__` kernels (also CUDA strings in .py) |
+| `kernelport read <id>` | `read_kernel` | source, parsed signature, suggested input spec |
+| `kernelport skill [name]` | `read_skill` | workflow, common_bugs, or a backend guide |
+| `kernelport write-reference` | `write_reference` | save a candidate reference + spec |
+| `kernelport validate <id>` or `--all` | `validate_reference` | original CUDA vs reference; freeze on PASS |
+| `kernelport write-port` | `write_port` | save a port |
+| `kernelport verify` | `verify_port` | port vs frozen reference |
+| `kernelport bench` | `bench_port` | time port vs original (after PASS) |
+| `kernelport tune <id> <backend>` | `tune_port` | verify + time every `TUNE` variant, keep the fastest that passes |
+| `kernelport status` | `list_status` | kernel × backend × hardware table |
+| `kernelport report [--md]` | `make_report` | HTML or Markdown report |
+| `kernelport setup` | – | register with Claude Code / Codex / Cursor / Gemini CLI |
+| `kernelport mcp` | – | run the MCP server on stdio |
+| `kernelport agent "<task>"` | – | optional built-in agent (your Anthropic API key) |
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/activate      # or source .venv/bin/activate
+pip install --index-url https://download.pytorch.org/whl/cu128 torch
+pip install -e ".[cuda,triton,cpu,dev]"
+python -m pytest -q        # ~4 min; GPU tests skip without CUDA, cpu tests need only numba
+```
+
+## License
+
+MIT