# AGENTS.md — Execution Guardrails for Codex

This file defines **how Codex should think, act, and prioritize** when working in this repository.  
Its purpose is to keep development **focused, correct, and non-drifting**.

If there is any conflict between speed and correctness, **correctness wins**.

---

## Mission

Build a **real-time, non-delayed options flow and off-exchange trade analysis platform** for personal use that is:

- explainable
- deterministic
- replayable
- microstructure-correct
- low-latency
- built on **Bun**

Codex is an **engineering executor**, not a product visionary.  
Do not invent scope. Do not “improve” the plan. Implement it faithfully.

---

## Non-Negotiable Constraints

- **Bun is mandatory**
  - Use Bun for runtime, package manager, scripts, and dev tooling.
  - Do not introduce npm, yarn, pnpm, or Node-only assumptions.
- **TypeScript only**
  - No JS-only files unless unavoidable (and document why).
- **No black-box logic**
  - All classifiers must be rule-based and explainable.
- **Personal-use architecture**
  - No multi-user assumptions.
  - No redistribution mechanisms.
- **Deterministic pipelines**
  - Live behavior must match replay behavior.

If a change violates any of the above, **do not implement it**.

---

## Source of Truth

The authoritative documents are, in order:

1. `PLAN.md`
2. `AGENTS.md`
3. Code already merged into `main`

If a request contradicts `PLAN.md`, Codex must **stop and ask for clarification**.

---

## Development Rules

### 1. Never Skip the Event Layer
- All incoming market data becomes **immutable events**.
- Never compute directly off live feeds without persisting the event.
- Never add UI-only logic that bypasses persisted data.

### 2. Separate Fact from Inference
- Raw data (`OptionPrint`, `EquityPrint`) is **fact**.
- Classifiers and dark pool signals are **inference**.
- Store and label them separately.
- Never overwrite facts with inferred labels.

### 3. Explainability Is Required
Every classifier must:
- have a unique ID
- expose its inputs
- produce a human-readable explanation string
- link back to evidence prints

If an alert cannot explain itself, it is invalid.

### 4. Favor Simple, Explicit Logic
- Prefer clear thresholds over clever heuristics.
- Avoid premature ML or probabilistic tuning.
- If logic becomes complex, break it into named steps.

This is a research system, not a trading bot.

---

## Classifier Implementation Rules

- Classifiers operate on **FlowPackets**, not raw prints.
- Each classifier:
  - returns `{ confidence, direction, explanations[] }`
  - contributes to alert scoring but does not decide alerts alone
- Never infer intent with certainty.
- Use language like:
  - “likely”
  - “suggests”
  - “consistent with”
- Never use language like:
  - “smart money”
  - “institutional intent”
  - “guaranteed”

---

## Time & Market Structure Rules

- Always join prints to NBBO using bounded time windows.
- Track and expose join quality (`nbbo_age_ms`, etc.).
- Explicitly handle:
  - 0DTE
  - low-liquidity contracts
  - wide spreads
- If confidence is low, say so.

---

## Charting Rules

- Candles are built **server-side only**.
- Client never computes OHLC.
- Overlays must be viewport-aware and decimated.
- Performance beats decoration.

If a chart stutters, reduce data density first—not visual quality.

---

## UI Rules

- Prefer clarity over density.
- Every alert must be clickable to evidence.
- No “magic colors” without legend or explanation.
- Motion must feel physical, not flashy.

UI exists to **inspect**, not to impress.

---

## Observability & Safety

- Add metrics alongside new pipelines.
- Log failures explicitly.
- Never silently drop events.
- During overload:
  - persistence > compute > UI (in that priority order)

---

## What Codex Must NOT Do

- Do not invent new features or markets.
- Do not introduce predictive claims.
- Do not optimize prematurely.
- Do not refactor without reason.
- Do not replace explicit logic with ML.
- Do not broaden scope beyond personal use.

---

## When to Stop and Ask

Codex must pause and ask for guidance if:
- a data provider limitation blocks implementation
- licensing or entitlement assumptions change
- a requested change conflicts with `PLAN.md`
- a design decision affects determinism or replayability

---

## Definition of “Done”

A task is done only when:
- it matches `PLAN.md`
- it compiles and runs under Bun
- it is deterministic
- it is explainable
- it is testable or replayable

---

## Final Reminder

This system is built to **understand markets**, not to mythologize them.

If something cannot be justified by observable data and clear logic, it does not belong here.