Skip to main content

Agent Onboarding

Read this before making Finance App code, docs, or infrastructure changes.

Read In Order​

  1. ONBOARDING.md
  2. docs-site/docs/workflows/mobile-ux-golden-rule.md
  3. docs-site/docs/workflows/observability-error-handling-rule.md
  4. AGENTS.md
  5. CODING_STANDARDS.md
  6. .tasks/README.md
  7. .tasks/INDEX.md
  8. docs/STAGING_RUNBOOK.md
  9. docs/GCP_STAGING_DEPLOYMENT.md
  10. the active .tasks/<task-file>.md
  11. package.json, scripts/setup-workspace.mjs, scripts/dev-workspaces.mjs, core/backend/package.json, core/frontend/package.json, core/backend/src/modules/README.md, core/frontend/src/router.tsx, and the relevant backend controllers and implementation files

What You Must Capture​

  • current phase or milestone
  • relevant modules or areas
  • critical constraints
  • task tracking file
  • reality-check sources used
  • immediate next files to inspect or modify
  • docs or reference pages that must stay aligned
  • mobile workflow touched and smallest viewport reviewed for UI work
  • summary-to-detail navigation, preserved account/category/month/date/review filters, and visible return paths for UI work
  • progressive forms, paginated histories, and single-focus summaries for UI work
  • visually obvious user-action states, especially classification review, with direct filtered CTAs
  • account-aware import behavior and safe Conta principal defaults
  • persisted route-owned filters for Resumo and Despesas when users switch tabs
  • user-scoped category management with rename for any category, delete-protected defaults, and deletion blocked while transactions use a category
  • async invoice and digital PDF statement classification jobs, truthful progress/current-step/fallback-error state, notification/deep-link return flow, visible row-level IA Gemini/Regras/Fallback source badges, and explicit accept/ignore actions for AI-suggested categories
  • completed async import classifications may be reused for identical file content in the same authenticated user/account/currency/mode/model/category context within a recent cache window, but cached previews must still recalculate duplicates against current transactions and show the user that the preview was reused without another IA call
  • import progress cards must stay process-only; extracted financial totals belong in the compact final review summary, and notifications should not duplicate the visible import screen
  • final import review totals must stay fully readable on mobile, using vertical value rows instead of cramped horizontal cards when necessary
  • PDF import classification must send only bounded extracted text to the model, normalize withdrawals/deposits/transfers/installments server-side, and never log raw PDF text, prompts, category payloads, merchant rows, or generated finance details
  • import previews and confirmations must detect reimports and ignored document rows on the backend, including fuzzy duplicates against saved transactions and PDF summary/balance/total rows returned by AI or parsers; do not auto-collapse equal rows within one upload because repeated detailed rows can be legitimate transactions
  • Import sign handling is a backend guarantee: explicit source signs are applied before category classification, negative rows stay withdrawals, positive rows stay deposits, and contradictory Gemini category output cannot flip signed rows or turn them into transfers. Debit/credit language and fatura-payment rules still apply, including Nubank card-payment withdrawals; progress UI must keep financial totals in the final review surface.
  • vertical-space discipline: data first, compact active-filter chips, collapsed filters/secondary controls until explicit intent
  • centered app-themed modal/overlay secondary surfaces for button-opened creation, edit, and filter workflows, with internal scroll instead of shifting the main page
  • product-simple manual finance entry that hides debit/credit lines, journals, accounting status, currency plumbing, and other implementation concepts from normal users
  • short, explicit, preview-first voice actions with confirmation before saving finance data or navigating to filtered views; transcript facts must beat contradictory AI output
  • themed app controls for mobile account, category, month, review, and other app-owned selectors, with dropdowns rendered as overlays that do not push content, and native browser inputs reserved for date/calendar and file controls
  • obvious in-place exits for action-oriented filters and expanded filter panels, with contextual exits beside the filtered work instead of only in top chips
  • app-themed confirmations for destructive, session-ending, and bulk edit/delete actions, with no native browser confirmation popups
  • fixed, stable mobile bottom navigation without scroll/flicker
  • observability and error-handling impact for runtime work

Rules Worth Preserving​

  • task tracking is live truth
  • mobile UX is the golden rule for user-facing work
  • simple, obvious navigation for non-technical users is part of the mobile UX bar
  • docs are secondary to implementation
  • observability and user-safe errors are part of feature delivery
  • complex non-core features should evaluate OSS options before custom code
  • stack deviations require an explicit explanation and user confirmation
  • auth, finance isolation, CI/CD, and staging changes must update the runbook or review notes when operator behavior changes
  • AI-suggested finance categories must remain human-reviewed suggestions and must not be created automatically
  • Default classifier categories must remain delete-protected in category management because import/classification rules depend on them, but their display names can be renamed by the user
  • Voice and AI logs must never include raw audio, transcripts, prompts, uploaded file contents, or generated finance details tied to a user