# Cold Display Guard Agent Instructions

## Repository Snapshot

- Root purpose: `cold-display-guard` monitors refrigerated display food batches, tracks dwell time per configured display zone, and records disposal compliance events.
- Backend: Python 3.11+ package in `src/cold_display_guard`, using only the standard library for application code.
- Frontend: Vite + vanilla JavaScript management console in `web/`.
- Data/storage: JSONL runtime outputs under `logs/` by default; configuration is TOML in `config/example.toml`.
- Runtime services:
  - Management API: `127.0.0.1:19080`, routes under `/api/manage/*`.
  - Web console: `127.0.0.1:23000`, Vite proxies `/api` to the management API.
  - Runtime monitor: RTSP frame sampling through `ffmpeg`, writing events and diagnostics JSONL.
- Deployment: Docker/Compose files are present; containers mount `config/` and `logs/`, use `Asia/Shanghai`, and prefer China-accessible package/image mirrors.

## Repository Map

- `src/cold_display_guard/engine.py`: pure batch state machine and compliance event generation.
- `src/cold_display_guard/models.py`: domain dataclasses and observation parsing.
- `src/cold_display_guard/config.py`: TOML loading, saving, calibration merge, and path resolution.
- `src/cold_display_guard/manage_api.py`: standard-library HTTP management API and RTSP snapshot capture.
- `src/cold_display_guard/main.py`: long-running RTSP monitor that connects frame capture, vision detection, engine, and JSONL sinks.
- `src/cold_display_guard/frame_source.py`: `ffmpeg` raw RGB frame capture.
- `src/cold_display_guard/vision.py`: heuristic ROI occupancy and trash-motion detection.
- `src/cold_display_guard/cli.py`: JSONL observation CLI for deterministic engine processing.
- `web/src/main.js` and `web/src/styles.css`: management console UI.
- `scripts/`: local launch scripts for API, web, and runtime services.
- `deploy/`, `Dockerfile`, `web/Dockerfile`: container deployment artifacts.
- `tests/`: unittest coverage for engine, CLI, config, management summary/config behavior, and vision heuristics.
- `docs/plans/`, `task_plan.md`, `progress.md`, `findings.md`: existing planning and project-history artifacts.

## Core Domain Rules

- The reliable business unit is a display-zone batch, not an individual food item.
- Default layout is 2 rows by 4 columns with zone IDs `r1c1` through `r2c4`; layout and polygons are configurable.
- A batch starts when a zone changes from empty to occupied.
- A batch ends when a zone changes from occupied to empty.
- Count decreases keep the same batch active and emit `batch_count_changed`.
- Count increases before the zone clears are mixed-batch violations and emit `mixed_batch_violation`.
- Removal before `max_dwell_seconds` emits `batch_consumed`.
- Removal at or after `max_dwell_seconds` emits `batch_pending_disposal` and waits for trash confirmation.
- A trash deposit within `trash_confirmation_seconds` emits `batch_discarded`.
- No trash deposit before the deadline emits `missing_disposal_violation`.
- Any new occupied zone while an overdue batch is pending disposal emits `overdue_return_violation`.
- The current vision layer reports binary `0/1` occupancy per zone; it does not count individual items.
- The detector learns an empty baseline from the first configured frames. If food is already present at startup, it may become baseline until the image changes.

## Change Rules

- Keep `BatchEngine` deterministic and free of camera, file, HTTP, subprocess, or wall-clock dependencies.
- Add or update focused tests when changing business rules, event names, event payloads, observation parsing, config formatting, or path resolution.
- Keep the observation contract stable: `ts`, `zone_counts`, and `trash_deposit` or `trash_deposit_count`.
- If event names or payload shapes change, update engine tests, CLI tests, runtime code, management summary behavior, frontend rendering, and README examples together.
- Keep ROI and polygon coordinates normalized to `0.0..1.0`; clamp or validate inputs at config/API boundaries.
- Keep `manage_api.py` as a small standard-library HTTP service unless the user explicitly asks to introduce a web framework.
- Preserve explicit `ffmpeg` timeout and error reporting behavior in `frame_source.py` and snapshot capture.
- Treat RTSP URLs, camera credentials, captured frames, and logs as sensitive operational data. Do not paste secrets into new docs, commits, or test fixtures.
- Do not commit generated runtime data such as `logs/`, captured snapshots, Vite `dist/`, Python caches, or ad hoc diagnostics.
- Frontend changes should preserve the current Vite single-page app, `/api/manage/*` backend contract, and 23000/19080 local development split.
- Deployment changes must keep README commands, scripts, ports, env vars, compose volumes, Docker health checks, and config paths aligned.
- Be careful with mirror settings in Dockerfiles; they are intentional for the expected deployment network.

## Local Commands

- Full Python test suite:
  - `PYTHONPATH=src python3 -m unittest discover -s tests -v`
- Targeted Python tests:
  - `PYTHONPATH=src python3 -m unittest tests/test_engine.py -v`
  - `PYTHONPATH=src python3 -m unittest tests/test_config.py -v`
  - `PYTHONPATH=src python3 -m unittest tests/test_manage_api.py -v`
  - `PYTHONPATH=src python3 -m unittest tests/test_vision.py -v`
  - `PYTHONPATH=src python3 -m unittest tests/test_cli.py -v`
- Management API:
  - `scripts/run_manage_api.sh`
  - Health check: `curl http://127.0.0.1:19080/api/manage/health`
- Web console:
  - `scripts/run_web.sh`
  - Build check: `cd web && pnpm build`
- Runtime monitor:
  - `scripts/run_runtime.sh`
  - One-frame smoke test when RTSP and `ffmpeg` are available: `PYTHONPATH=src python3 -m cold_display_guard.main --config config/example.toml --once`
- Compose config check:
  - `docker compose --env-file deploy/cold-display-guard.env -f deploy/docker-compose.yml config`

## Validation Matrix

- Engine or domain behavior: run the targeted engine/CLI tests first, then the full Python test suite.
- Config or calibration behavior: run `tests/test_config.py`, `tests/test_manage_api.py`, then the full Python test suite.
- Vision or RTSP capture behavior: run `tests/test_vision.py`; use the one-frame runtime smoke test only when camera access and `ffmpeg` are available.
- Management API changes: run management API tests and, when practical, start `scripts/run_manage_api.sh` and hit `/api/manage/health`.
- Frontend changes: run `cd web && pnpm build`; if API interactions changed, also run or inspect the management API route behavior.
- Deployment changes: run the compose config check and verify Dockerfile/package mirror choices, ports, volumes, and health checks.
- Documentation-only changes: verify the documented paths, commands, ports, and business rules against the current files before reporting completion.

## Workflow

- Read the relevant source and tests before editing; this project has tight coupling between business rules, event payloads, README examples, and UI summaries.
- Prefer small, surgical changes that preserve the current architecture.
- For non-trivial work, update or add planning notes in the existing project style (`docs/plans/`, `task_plan.md`, `progress.md`, or `findings.md`) only when useful for handoff or explicitly requested.
- Keep the final response grounded in verification evidence: say exactly which commands were run, or say when a validation step was skipped because it requires RTSP, Docker, network, or another external dependency.