maryslab: Instructions file for Claude Code

Mary's Lab — agent onboarding

Monorepo for a spectral color science platform. Read docs/PRD.md before structural changes — §5 records deliberate scope cuts (do not re-add the braid kernel or fiber-bundle metamer formalism without the theorem PRD §5.2 demands).

Layout

• core/ — C++20 engine. Public surface is ONLY core/include/mary/mary.h (C ABI). No C++ types cross the boundary. No exceptions escape src/ffi/.
• mcp/ — TypeScript MCP server (npm workspace). zod schemas in src/schemas/ are the single source of truth; tool handlers stay thin.
• data/ — ingestion tooling (uv-managed Python). Records failing quality gates Q1–Q6 (see data/ingest/validate.py) never ship.
• bindings/ — node N-API and wasm wrappers around the C ABI. Python is deferred past 1.0 on purpose (bindings/python/README.md records why); do not add a fourth surface without adding it to the parity suite the same day.
• web/ — Astro site: home, instruments, docs, papers, blog, and /verify, which runs the conformance vectors in the reader's browser.
• papers/ — the fourteen technical reports. build/experiments.mjs produces the synthetic numbers, build/real.mjs the measured ones against usgs-splib07a-1, build/render.mjs typesets both into the PDFs the site serves. A paper cannot quote a number that was not computed: the renderer throws on an unresolved placeholder. {{real.*}} is measured, bare {{*}} is synthetic, and the namespaces are deliberately separate so one cannot be quoted as the other.

Build & test commands

# MCP (works on this machine — no C++ toolchain needed)
cd mcp && npm install && npm test && npm run build

# Data pipeline
cd data && uv sync && uv run pytest

# Core (requires cmake + C++20 compiler; runs in CI otherwise)
cmake --preset release && cmake --build --preset release && ctest --preset release

Hard rules

1. Canonical spectral grid = 380–750 nm @ 10 nm = 38 samples. Everywhere.
2. Engine math changes require updating golden vectors via a PR labeled golden-update with justification. Never regenerate goldens silently.
3. CVD compensation language: "remap for discriminability", never "restore".
4. Photopeak isotope output is decision support, never authoritative ID.
5. Reference TS engine (mcp/src/engine/), C++ core, and the WebAssembly build must all agree. Parity is enforced three ways, all live:
   • bindings/wasm/test/parity.mjs runs the same 401 vectors through the browser engine (wasm-ci), at the same float32 floor (2e-6). The export list is DERIVED from mary.h at configure time and the build fails below 40 exports — a hand-maintained list is how the wasm target silently sat at ABI 0.1 while the header reached 0.4. web/ ships that module at /engine/ and /verify runs the vectors in the reader's browser, so a drifting wasm build is visible on the public site.
   • core/tests/golden/vectors/conformance.csv — 401 vectors generated from the TS engine by mcp/scripts/emit-golden-vectors.mjs, checked by core/tests/golden/test_conformance.cpp. Regenerating it requires a PR labeled golden-update (see rule 2).
   • core/tests/unit/test_metamorphic.cpp runs the same algebraic relations as mcp/src/engine/metamorphic.ts, against the native engine. pipelinecheck is TS-only on purpose: pure spec logic, no numerics, so there is nothing that can diverge. All numeric kernels through batch 5 (ceiling, constraints, lutaudit, datasetdiff, blendsafety, physicality) are mirrored; ABI tests assert runtime == compiled header, never a hardcoded minor version.