Test the Houdini side of hShadertoy headlessly (hython, no GUI) — builder test, real OpenCL cook test, the live-header vs HDA-owner boundary, main_header.cl anatomy, and a Houdini glossary for engineers who have never opened Houdini. Use when validating HDA builds, cubemap/mainCubemap paths, runtime-header changes, cook failures, or anything involving hython, COPs,
Architecture ground truth and change workflow for the GLSL→OpenCL transpiler (src/glsl_to_opencl/) — the real pipeline, where each kind of change goes, TDD workflow, debugging recipes, and the must-know traps. Use when modifying the transpiler, adding a transformation, debugging a transpile/compile failure, adding builtin or type mappings, or touching either emitter or host script.
START HERE for anyone new to hShadertoy — what the project is, repo map, environment, the non-negotiable rules, current campaign state, and which skill/doc to use for which job. Use at the start of any session when unfamiliar with the project, when unsure which docs are trustworthy, or when deciding where a piece of work belongs.
Build/run the automated image-comparison harness that renders original Shadertoy GLSL via wgpu-shadertoy and hShadertoy output via Houdini, then diffs the images to prove render CORRECTNESS (not just compile success). Use when validating that transpiled shaders render the same as the originals, building the comparison pipeline, or investigating "compiles but looks wrong" bugs.
Run one transpiler bug-fix session end-to-end (tests/fixcampaign/) — TDD-first fix workflow, regression gates, delta measurement, backlog/handoff bookkeeping, and the accumulated traps from 11+ sessions. Use when fixing a transpiler failure category, resuming the fix campaign, proving a fix against the shader corpus, or deciding whether a fix needs owner approval.
Run the Shadertoy mass-test campaign (tests/campaign/) — fetch/test/report stages, ledger.json rules, API budget, failure-taxonomy classifier maintenance, and the long-compile batching workaround. Use when measuring transpiler pass rate, testing shader ids, resuming a campaign session, re-testing after a fix, regenerating REPORT.md/failures.csv, or refining classify.py.
Fetching shaders from the Shadertoy.com REST API — Cloudflare TLS-fingerprint workaround (curl_cffi), API key, monthly budget, caches, and what is permanently blocked (/media/). Use when downloading shaders, debugging 403 errors from shadertoy.com, adding fetch code, or reasoning about API budget for the mass-test campaign.