Juan José Mata
157daf5176
* Document instruction inventory and preservation decisions Trace main history from September 2025 through September 2026, including earlier policy origins. Record preserved requirements, detailed-guide destinations, stale facts, harness boundaries and explicit policy-strength decisions before consolidating instruction sources. * Consolidate repository instructions into shared guidance Keep AGENTS concise and vendor neutral, move detailed conventions into shared guides, and use thin adapters with preserved Cursor scopes. Preserve the strict pre-PR checks globally and document the stronger scope, retired migration pin and rule-generation trigger. Update existing API guidance verification without changing application behavior. * Narrow the always-on Cursor UI adapter and correct the SimpleFIN comment Split the design-system guidance out of docs/llm-guides/ui.md into docs/llm-guides/design-system.md. The ui-ux-design-guidelines rule is alwaysApply: true, so importing all of ui.md loaded the Stimulus, localization and ViewComponent guidance (previously confined to scoped rules) on every Cursor session; the always-on adapter now imports only the design-system guide, matching the scope it had before the consolidation. view_conventions and stimulus_conventions keep the full UI guide. Also correct the stale Provider::Simplefin header comment: pending inclusion defaults on and is resolved by the importer (explicit argument, then SIMPLEFIN_INCLUDE_PENDING, then Setting.syncs_include_pending); the previous comment described the flag as default-off. * Read guidance files as UTF-8 in the API consistency validators The frontmatter regex match ran against content read with the locale default external encoding; the Cursor rule's description contains an em dash, so under US-ASCII (LC_ALL=C) Regexp#match raised ArgumentError, breaking the standalone no-Rails fallback the docs point contributors to. Read all checked files with an explicit UTF-8 encoding in both the standalone script and the Rails test.
5.5 KiB
Provider integration guidance
Read architecture for provider concepts, runtime registry
selection and Provided concerns. For a new securities price provider, follow
the complete workflow, including response
types, MIC mapping, currency handling, settings encryption, UI, locales and tests.
Support diagnostics
When a provider sync/import path encounters a recoverable error, suspicious partial
response or other support-relevant incident, prefer
DebugLogEntry.capture over Rails.logger.*
so operators can inspect it in the super-admin /settings/debug UI.
- Include
category,level,message,source,provider_keyand useful structuredmetadata. - Attach
familyandaccount_providerwhenever available so support can filter and trace the affected connection. Account/user associations can add context. - Reserve raw Rails logging for low-value local noise; incidents operators need to investigate belong in the debug log.
Pending transactions and FX metadata
Store provider metadata on Transaction#extra under the provider namespace.
Transaction#pending? and pending scopes share
PENDING_PROVIDERS; that constant is the current list of supported namespaces,
including providers beyond the three described below. The UI shows a Pending
badge when transaction.pending? is true. A provider that supplies no pending
metadata produces no badge; manual/CSV imports have no pending concept.
| Provider | Detection and storage |
|---|---|
| SimpleFIN | SimplefinEntry::Processor.pending? accepts an explicitly truthy pending flag, or posted equal to numeric 0 or string "0" with a present, positive transacted_at timestamp. A blank/missing posted value does not imply pending. Writes extra["simplefin"]["pending"] as true or false so a posted update clears stale pending metadata. |
| Plaid | PlaidEntry::Processor stores bank/credit transaction pending and pending_transaction_id under extra["plaid"]; the linking ID supports pending-to-posted reconciliation. The investment transaction processor does not store pending metadata. |
| Lunchflow | LunchflowEntry::Processor stores the boolean-cast isPending value under extra["lunchflow"]["pending"] when the upstream key is present. |
SimpleFIN additionally stores extra["simplefin"]["fx_from"] when transaction and
account currencies differ, and fx_date from the transacted date with posted-date
fallback. Preserve these namespaced fields and the existing conversion behavior.
Pending inclusion is provider- and layer-specific:
- SimpleFIN: the initializer defaults
config.x.simplefin.include_pendingto true. The importer resolves an explicitpending:argument first, then a presentSIMPLEFIN_INCLUDE_PENDINGenvironment value, thenSetting.syncs_include_pending. The entry processor also checks the environment/Setting choice before importing cached pending payloads.SIMPLEFIN_INCLUDE_PENDING=0disables the environment-controlled path. The low-level provider does not resolve these settings: it addspending=1only for a truthy argument, and otherwise omits the parameter. Do not sendpending=0; bridges can interpret its presence as inclusion. - Plaid: the initializer defaults
config.x.plaid.include_pendingto true. The transaction processor uses a presentPLAID_INCLUDE_PENDINGenvironment value beforeSetting.syncs_include_pending;PLAID_INCLUDE_PENDING=0filters pending records out. This is processing-time filtering, not a pending query flag on the Plaid sync request. - Shared SimpleFIN/Plaid setting:
Setting.syncs_include_pendingdefaults true with both environment variables absent. Its initial default is computed from both provider environment values; a persisted runtime setting can differ. Do not infer effective importer behavior from an initializer alone. - Lunchflow: the initializer defaults
config.x.lunchflow.include_pendingto false. SetLUNCHFLOW_INCLUDE_PENDING=1to enable it. The importer passes that configuration asinclude_pending:. A direct provider call defaults the argument to false and addsinclude_pending=trueonly when enabled; it does not consult the shared SimpleFIN/Plaid setting.
Raw payload debugging
Raw debugging is default-off. SIMPLEFIN_DEBUG_RAW=1 and
LUNCHFLOW_DEBUG_RAW=1 enable their importers' raw response logging through
Rails.configuration.x.simplefin.debug_raw and
Rails.configuration.x.lunchflow.debug_raw respectively.
UP_DEBUG_RAW=1 enables Up's debug configuration,
but its importer logs raw transactions only
when Rails.env.local? is also true. The dump contains PII: preserve this local-only
guard and do not enable raw Up dumps in managed/production. This guard is specific
to Up; the SimpleFIN and Lunchflow flags do not provide the same environment gate.