# AGENTS.md

## Engineering Rules

1. **Always close the test loop.**
   - Do not stop after code changes.
   - Run the app locally.
   - Run real tests against the running app.
   - For UI work, prefer real browser tests (Playwright) over assumptions.
   - Verify the exact route/page that changed.

2. **Local Docker first, deploy later.**
   - Use local Docker/OrbStack for fast feedback.
   - Only deploy after local behavior is verified.

3. **Browser-visible behavior beats log-only confidence.**
   - A route returning HTML is not sufficient.
   - Confirm page content renders and no runtime/500 error is visible.

4. **When using parallel worktrees, preserve shared domain models.**
   - New feature branches must not silently remove compatibility types used elsewhere.
   - In this project, `LombardPortfolio` is still required by strategy/core modules.

5. **Do not claim a feature is live unless the UI is wired to it.**
   - Backend service existence is not enough.
   - The rendered page must actually consume the live data path.

6. **Always work with TDD principles: Red, Orange, Green.**
   - Start by making the failure visible with a test or reproducible check (Red).
   - Iterate toward partial progress while keeping the failure scoped and observable (Orange).
   - Finish only when the behavior is implemented and the test loop passes cleanly (Green).

## Project Learnings

### NiceGUI layout constraint
- `ui.header()` must be a top-level page layout element.
- Do not nest `ui.header()` inside `ui.column()` or other containers.

### Options page performance lesson
- Loading all expiries/chains before first paint can make the page appear broken.
- Prefer rendering fast, then loading data incrementally.

### FastAPI/NiceGUI integration lesson
- NiceGUI page handlers should not assume `request.app.state.*` is always the right access path for shared services.
- Use an explicit runtime/service registry if needed.

### Docker development lesson
- Avoid mounting the whole repo over `/app` when the image contains required runtime scripts.
- Mount narrower paths in dev (`./app`, `./config`) to preserve image-managed files like entrypoints.

## Validation Checklist for UI Changes
- [ ] Local Docker stack starts cleanly
- [ ] `/health` returns OK
- [ ] Changed page opens in browser automation
- [ ] No visible 500/runtime error
- [ ] Screenshot artifact captured
- [ ] Relevant logs checked