d51fa05d5a
- add real browser test for overview and options pages - document engineering learnings in AGENTS.md - commit NiceGUI header layout fix - limit options initial expirations for faster first render
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# 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.
|
|
|
|
## 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
|