AGENTS.md

Engineering Rules

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.
Local Docker first, deploy later.
- Use local Docker/OrbStack for fast feedback.
- Only deploy after local behavior is verified.
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.
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.
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.
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).

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.

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.