# card-raytracer — project notes for Claude

This repo is a small study of Andrew Kensler's "business card raytracer".
The point of the project is **preservation + explanation**, not extension.

## The sacred rule

**`card.cc` must never be modified.** It is a historical artifact, ~1337
characters of obfuscated C++ that fits on a real business card. Any cleanup,
formatting, comment, or "fix" goes into `card_explained.cc` instead.

If a compiler warning or modern-C++ issue appears against `card.cc`, the
answer is always a CMake flag adjustment (e.g. silencing warnings), never
an edit to the source.

## Layout

| File | Role |
|---|---|
| `card.cc` | Original, golfed, untouched. Read-only by convention. |
| `card_explained.cc` | De-obfuscated rewrite with full names and comments. Same visual output. |
| `CMakeLists.txt` | Builds both binaries; provides `image` and `image_explained` render targets. |
| `docs/aek.png` | Published render used by the README. Regenerate after meaningful changes. |
| `README.md` | Human-facing description with the embedded render. |

## Build & render

```sh
cmake -S . -B build
cmake --build build                          # builds both binaries
cmake --build build --target image           # → build/aek.ppm
cmake --build build --target image_explained # → build/aek_explained.ppm
```

Convert PPM → PNG (for README, etc.) with `pnmtopng build/aek.ppm > docs/aek.png`.

## Conventions

- `card_explained.cc` is built with `-Wall -Wextra` and should stay
  warning-clean. `card.cc` is built with `-w` because we can't edit it.
- C++14, no external dependencies beyond `libm`.
- The de-obfuscated version preserves the **same `rand()` call sequence** as
  the original so the rendered image is visually identical. Don't reorder
  the `randf()` calls inside `shade()` or the per-sample loop in `main()`
  without re-checking the output.

## Remote

Hosted on Forgejo: `ssh://git@kode.naiv.no:2222/olemd/card-raytracer.git`.
Per global instructions, use the `forgejo` skill (invoke via `/forgejo`) and
the `fj` CLI for any repository interactions (PRs, issues, releases, etc.).
Never use `gh` for this repo.