reTraining/AGENTS.md

# Agent Instructions

Working rules for agents in this repo. A merge of the [Karpathy coding
guidelines](https://github.com/multica-ai/andrej-karpathy-skills) and the
[Chain of Truth](https://faridsurya-dev.github.io/Vibe-Coding-Research/en/welcome)
method: **validated artifacts are the source of truth, AI is a generator and accelerator.**

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that *your* changes made unused.

The test: every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Turn tasks into verifiable goals, and for multi-step work state a brief plan:

```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
```

This repo has no automated tests, so verification means **running something**: hit the
endpoint, run the job, look at the files it produced.

## 5. Chain of Truth — documents first, then code

`docs/` is the source of truth, not the chat prompt.

| Document               | Contents                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `docs/requirements.md` | Numbered `REQ-xxx` requirements. Changes only with the user's approval.             |
| `docs/design.md`       | Data schema, API contract, disk layout. Each section names the `REQ-xxx` it serves. |
| `docs/tasks.md`        | Implementation steps + verification criteria, status `[TODO]`/`[DONE]`.             |

The rules:

- Before writing feature code, make sure a `REQ-xxx` covers it. If none does, propose
adding one to the user first.
- Once a task is finished **and verified**, flip its status in `docs/tasks.md` to `[DONE]`
in the same commit.
- If the implementation diverges from `docs/design.md`, update the design — never let a
document lie.
- Use relative paths in markdown (`./`, `../`), not absolute ones.

## 6. Repo rules

- **Package manager: `uv`.** No `pip`, `poetry`, or bare `python`/`python3`. Dependencies
live in `requirements.txt`; install them with `uv pip install -r requirements.txt` and run
scripts with `uv run`. The Docker image installs the same file, so the two environments
cannot drift.
- **File size limit: 400 lines.** Any new or refactored file that exceeds it must be split
into smaller, logical modules.
- **`sam3/` is a vendored git submodule** (Meta's `facebookresearch/sam3`). It's a
dependency, not app code — don't add scripts there or edit anything inside it. It's
installed with `uv pip install -e ./sam3`.
- **Never write into the user's video archive.** All output goes under `data/`.
- Secrets (`HF_TOKEN`) come from `.env` only; they never belong in code or docs.

## 7. Architecture

**Two backends can coexist** — bare-metal (port 8000) and Docker (port 9010). The
`start.sh` script auto-detects GPU, generates `docker-compose.override.yml` for CDI
GPU passthrough, and falls back to bare-metal if Docker is unavailable.

```
backend/          FastAPI app (main.py), API routes in backend/api/
frontend/         React 19 + Vite 7 SPA; dev on 5173, Docker on 9000
algoritma-batch/  Counting engine (tracker, line counter). In Docker image it
                  is copied to /app/src/ and /app/cfg/ — imports resolve as
                  `src.*`, not `algoritma-batch.*`.
data/             SQLite DB, projects, extracted frames, datasets, model weights
docs/             Chain of Truth: requirements, design, tasks, UI spec
```

**Port mapping:**

| Service         | Bare-metal | Docker |
|-----------------|:----------:|:------:|
| Backend API     | 8000       | 9010   |
| Frontend Web UI | 5173       | 9000   |

**Key entrypoints:**

- `backend/main.py` — FastAPI app, lifespan, health endpoint, router wiring
- `backend/jobs.py` — single-threaded GPU-locked job worker (extract, autolabel, merge, train, count, clock-scan, truck-scan)
- `backend/sam3_engine.py` — SAM3 vision backbone, loaded once per process
- `backend/hardware.py` — GPU VRAM detection and training batch-size defaults

## 8. UI/UX

Frontend work follows [ui-ux-pro-max](https://github.com/nextlevelbuilder/ui--pro-max-skill):
generate the design system first (style, palette, typography), then build against it, then
validate before delivering. Consistency across pages beats per-page cleverness.

This app is a **dense internal tool**, not a landing page. Its screens are for long review
sessions in front of a screen: the video frame and the annotation canvas are the content,
everything else is chrome and stays quiet. No decorative gradients, no marketing motion.

Pre-delivery checklist — a UI task is not `[DONE]` until all of it passes:

- [ ] No emoji as icons (SVG only: Heroicons/Lucide)
- [ ] `cursor: pointer` on every clickable element
- [ ] Hover states with smooth transitions (150–300 ms)
- [ ] Text contrast at least 4.5:1
- [ ] Focus states visible for keyboard navigation
- [ ] `prefers-reduced-motion` respected
- [ ] Responsive at 375 / 768 / 1024 / 1440 px

The review editor also has to survive keyboard-only use — see `docs/design.md`, "Frontend".

## 9. Domain invariants

Two things are easy to break without noticing, and breaking either makes the whole system
lie:

1. **Stable val split.** Once a frame lands in `val`, it stays in `val` forever. Otherwise
the base-vs-new mAP comparison is meaningless.
2. **One `set_image` per image.** `Sam3Processor.set_image()` runs the vision backbone;
`set_text_prompt()` only re-runs the grounding head against the cached `backbone_out`. An
N-prompt job calls `set_image` **once per image** and loops prompts over that same state.
Don't restructure this into set_image-per-prompt.

## 10. Scalability & Portability

**Never hardcode something that will change across environments.**

- **Hardware Agnosticism:** Do not hardcode hardware requirements (e.g., GPU configurations in `docker-compose.yml`) directly into base configuration files. Instead, use dynamic startup scripts (like `start.sh`) or environment overrides to detect the host's capabilities and inject the appropriate settings automatically.
- **Portability:** The app must be fully deployable and scalable on any device (from a CPU-only laptop to a massive multi-GPU rig) without requiring manual code edits to run.
- **Dynamic Configuration:** Do not hardcode absolute IP addresses, local network paths, or machine-specific environment variables in code. Rely on relative paths and configuration files to ensure maximum scalability.