vault-dash/AGENTS.md

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).

7. Linting is part of the build, not an optional extra step.

   • make build must enforce linting first.
   • Do not treat lint as a separate, skippable preflight.
   • If the build is green, lint must already be green.

8. Run the /review skill before merging worktrees back.

   • Any worktree/sub-agent implementation must go through /review before integration to main.
   • Do not merge worktree changes back based only on compile/test results.
   • Review first, then integrate.

9. Review the backlog after each sprint.

   • After each completed sprint or merged feature slice, review docs/roadmap/ROADMAP.yaml and the per-task YAML files.
   • Add any new backlog items uncovered during implementation, testing, review, or deployment.
   • Reorder priorities and update dependencies based on new knowledge.
   • Capture follow-up work explicitly instead of relying on memory or chat context.

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