# Working in this repo

Project instructions for Codex. The client-wide prompt lives in `~/.codex/AGENTS.md`; this file is
the project-specific part.

## Know which board you are on

This project spans **two different single-board computers with incompatible camera stacks**, and
Codex is installed on both. Getting this wrong produces code that runs where you tested it and
nowhere else.

- **Jetson Orin Nano** — the *target*. L4T / JetPack, CUDA, TensorRT. V4L2 / GStreamer, with Argus
  (`nvarguscamerasrc`) for CSI Bayer sensors.
- **Raspberry Pi 5** — the *test platform*. libcamera / `rpicam` / `picamera2`. CPU-only inference.

**Call `platform_info` before writing anything platform-specific.** It is client-local and reports
the machine you are actually on, not `halogen`. Do not infer the board from the fact that both are
aarch64 — that is the one thing they have in common.

⚠ **Code written directly against `picamera2` will not run on the Orin.** Put capture behind an
interface with a backend per platform, selected at runtime from what the hardware reports. Everything
above capture — streaming, UI, recognition — depends only on "a source of frames".

⚠ **The Pi proves the pipeline, never the performance.** Face recognition on the Orin goes through
TensorRT on GPU/DLA; on the Pi it is CPU-only and will not hold a live stream. Never present a Pi
timing as evidence the target is fast enough, and say which board a measurement came from.

## No camera is connected yet

No working camera has been attached to either board. The first module was not detected on the Pi 5 at
all — traced to a cable fault, with the module possibly damaged too. See README.md for the evidence
and the check commands.

⚠ **You cannot fix camera detection from software.** Do not add `dtoverlay=` lines, edit
`/boot/firmware/config.txt`, or install packages to make a sensor appear. On the Pi,
`camera_auto_detect=1` is already correct; a silent `dmesg` and a missing i2c bus mean the sensor is
not being reached electrically. Report the state and stop.

⚠ **`/dev/video*` is not evidence of a camera** — those nodes exist on both boards with nothing
attached.

Work that does not need live capture is still available: the capture interface and a synthetic or
still-image backend, the streaming plumbing, the web UI, project structure, tests. **Say plainly when
you are working against a placeholder** rather than a real frame.

## Constraints

- **Install capture libraries from system packages, not pip.** `python3-picamera2` on the Pi; the
  Jetson camera stack ships with L4T. Both bind to system libraries and a pip build will not match.
- **Do not commit captured images or video.** Frames of a real room are not test fixtures. Generate a
  synthetic fixture if one is genuinely needed.
- Keep dependencies few. Everything here has to build on aarch64, and on the Jetson it has to
  coexist with a vendor-pinned CUDA and Python.
- Face recognition runs on **downscaled frames, off the capture thread**.

## Verifying your work

Claims about hardware, the stream, or performance need a command that ran:

```bash
# is a sensor present
rpicam-hello --list-cameras          # Pi 5
v4l2-ctl --list-devices              # Orin

# is the server actually serving frames
curl -sI http://localhost:<port>/
```

⚠ **The absence of an error is not evidence that something works.** A stream endpoint returning 200
with no frames and a working one are indistinguishable to `curl -o /dev/null` — check what actually
came back. The same applies to a capture backend that constructs cleanly and yields nothing.

## Git

The remote is Gitea at `192.168.2.199:3005`, reachable over SSH on port 2222.

⚠ **`tea` (the Gitea CLI) is denied by policy** and blocked by a `PreToolUse` hook. Ordinary `git` is
fine. **Do not push** unless the operator asks — commit locally and say what is ready.