AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4- Code: `app/` (Rails MVC, services, jobs, mailers, components), JS in `app/javascript/`, styles/assets in `app/assets/` (Tailwind, images, fonts).
5- Config: `config/`, environment examples in `.env.local.example` and `.env.test.example`.
6- Data: `db/` (migrations, seeds), fixtures in `test/fixtures/`.
7- Tests: `test/` mirroring `app/` (e.g., `test/models/*_test.rb`).
8- Tooling: `bin/` (project scripts), `docs/` (guides), `public/` (static), `lib/` (shared libs).
9 
10## Build, Test, and Development Commands
11- Setup: `cp .env.local.example .env.local && bin/setup` — install deps, set DB, prepare app.
12- Run app: `bin/dev` — starts Rails server and asset/watchers via `Procfile.dev`.
13- Test suite: `bin/rails test` — run all Minitest tests; add `TEST=test/models/user_test.rb` to target a file.
14- Lint Ruby: `bin/rubocop` — style checks; add `-A` to auto-correct safe cops.
15- Lint/format JS/CSS: `npm run lint` and `npm run format` — uses Biome.
16- Security scan: `bin/brakeman` — static analysis for common Rails issues.
17 
18## Coding Style & Naming Conventions
19- Ruby: 2-space indent, `snake_case` for methods/vars, `CamelCase` for classes/modules. Follow Rails conventions for folders and file names.
20- Views: ERB checked by `erb-lint` (see `.erb_lint.yml`). Avoid heavy logic in views; prefer helpers/components.
21- JavaScript: `lowerCamelCase` for vars/functions, `PascalCase` for classes/components. Let Biome format code.
22- Commit small, cohesive changes; keep diffs focused.
23 
24## Testing Guidelines
25- Framework: Minitest (Rails). Name files `*_test.rb` and mirror `app/` structure.
26- Run: `bin/rails test` locally and ensure green before pushing.
27- Fixtures/VCR: Use `test/fixtures` and existing VCR cassettes for HTTP. Prefer unit tests plus focused integration tests.
28 
29## Commit & Pull Request Guidelines
30- Commits: Imperative subject ≤ 72 chars (e.g., "Add account balance validation"). Include rationale in body and reference issues (`#123`).
31- PRs: Clear description, linked issues, screenshots for UI changes, and migration notes if applicable. Ensure CI passes, tests added/updated, and `rubocop`/Biome are clean.
32 
33## Security & Configuration Tips
34- Never commit secrets. Start from `.env.local.example`; use `.env.local` for development only.
35- Run `bin/brakeman` before major PRs. Prefer environment variables over hard-coded values.
36 
37## API Development Guidelines
38 
39### OpenAPI Documentation (MANDATORY)
40When adding or modifying API endpoints in `app/controllers/api/v1/`, you **MUST** create or update corresponding OpenAPI request specs for **DOCUMENTATION ONLY**:
41 
421. **Location**: `spec/requests/api/v1/{resource}_spec.rb`
432. **Framework**: RSpec with rswag for OpenAPI generation
443. **Schemas**: Define reusable schemas in `spec/swagger_helper.rb`
454. **Generated Docs**: `docs/api/openapi.yaml`
465. **Regenerate**: Run `RAILS_ENV=test bundle exec rake rswag:specs:swaggerize` after changes
47 
48### Post-commit API consistency (LLM checklist)
49After every API endpoint commit, ensure: (1) **Minitest** behavioral coverage in `test/controllers/api/v1/{resource}_controller_test.rb` (no behavioral assertions in rswag); (2) **rswag** remains docs-only (no `expect`/`assert_*` in `spec/requests/api/v1/`); (3) **rswag auth** uses the same API key pattern everywhere (`X-Api-Key`, not OAuth/Bearer). Full checklist: [.cursor/rules/api-endpoint-consistency.mdc](.cursor/rules/api-endpoint-consistency.mdc).
50 
51## Design System Hygiene (UI PRs)
52 
53When a PR touches `.erb`, view components, or `.css`:
54 
551. **Tokens, not palette.** Use functional tokens from `app/assets/tailwind/sure-design-system.css` (`bg-warning/10`, `text-destructive`, `bg-container`, `text-primary`, `border-primary`). No raw Tailwind palette (`bg-blue-50`, `text-red-500`, hex literals).
562. **Reach for `DS::*` first.** Check `app/components/DS/` (`DS::Alert`, `DS::Button`, `DS::Disclosure`, `DS::Dialog`, `DS::Menu`, etc.) before writing an alert, badge, button, disclosure, dialog, or input shape.
573. **Two copies → lift to DS.** Same hand-rolled shape ≥2× in a diff with no DS equivalent → propose a new `DS::*` primitive before the second copy lands.
584. **Conventions.** Use the `icon` helper (never `lucide_icon` directly), no raw SVG outside DS primitives, user-facing strings via `t()`, avoid arbitrary `*-[Npx]` values when a scale token fits.
59 
60Reviewers escalate violations of (2)–(3) to close/rewrite; (1) and (4) are request-changes.
61 
62## Securities Providers
63 
64If you need to add a new securities price provider (Tiingo, EODHD, Binance-style crypto, etc.), see [adding-a-securities-provider.md](./docs/llm-guides/adding-a-securities-provider.md) for the full walkthrough — provider class, registry wiring, MIC handling, settings UI, locales, and tests.
65 
66## Debug Logging for Provider Syncs
67 
68When a provider sync/import path hits a recoverable error or suspicious partial response that support may need to inspect later, prefer `DebugLogEntry.capture(...)` over `Rails.logger.*`.
69 
70- Record support-relevant diagnostics in the debug log so they surface in the super-admin-friendly `/settings/debug` UI.
71- Include `category`, `level`, `message`, `source`, `provider_key`, and useful structured `metadata`.
72- Attach `family` and `account_provider` when available so support can filter and trace the affected connection.
73- Reserve raw Rails logging for low-value local noise; anything operators may need should go to the debug log.
74 
75## Providers: Pending Transactions and FX Metadata (SimpleFIN/Plaid/Lunchflow)
76 
77- Pending detection
78  - SimpleFIN: pending when provider sends `pending: true`, or when `posted` is blank/0 and `transacted_at` is present.
79  - Plaid: pending when Plaid sends `pending: true` (stored at `transaction.extra["plaid"]["pending"]` for bank/credit transactions imported via `PlaidEntry::Processor`).
80  - Lunchflow: pending when API returns `isPending: true` in transaction response (stored at `transaction.extra["lunchflow"]["pending"]`).
81- Storage (extras)
82  - Provider metadata lives on `Transaction#extra`, namespaced (e.g., `extra["simplefin"]["pending"]`).
83  - SimpleFIN FX: `extra["simplefin"]["fx_from"]`, `extra["simplefin"]["fx_date"]`.
84- UI
85  - Shows a small “Pending” badge when `transaction.pending?` is true.
86- Variability
87  - Some providers don’t expose pendings; in that case nothing is shown.
88- Configuration (default-off)
89  - SimpleFIN runtime toggles live in `config/initializers/simplefin.rb` via `Rails.configuration.x.simplefin.*`.
90  - Lunchflow runtime toggles live in `config/initializers/lunchflow.rb` via `Rails.configuration.x.lunchflow.*`.
91  - ENV-backed keys:
92    - `SIMPLEFIN_INCLUDE_PENDING=1` (forces `pending=1` on SimpleFIN fetches when caller didn’t specify a `pending:` arg)
93    - `SIMPLEFIN_DEBUG_RAW=1` (logs raw payload returned by SimpleFIN)
94    - `LUNCHFLOW_INCLUDE_PENDING=1` (forces `include_pending=true` on Lunchflow API requests)
95    - `LUNCHFLOW_DEBUG_RAW=1` (logs raw payload returned by Lunchflow)
96 
97### Provider support notes
98 
99- SimpleFIN: supports pending + FX metadata; stored under `extra["simplefin"]`.
100- Plaid: supports pending when the upstream Plaid payload includes `pending: true`; stored under `extra["plaid"]`.
101- Plaid investments: investment transactions currently do not store pending metadata.
102- Lunchflow: supports pending via `include_pending` query parameter; stored under `extra["lunchflow"]`.
103- Manual/CSV imports: no pending concept.
104