net-worth-tracker

Imported from GiuseppeDM98/net-worth-tracker (AGENTS.md). Install upstream with npx skills add GiuseppeDM98/net-worth-tracker. Copyright stays with the author.

AI Agent Guidelines — Net Worth Tracker

Conventions and recurring pitfalls. Rules only: how each one was learned lives in git log, and what each feature is lives in CLAUDE.md — this file says only what an agent can get wrong.

Companion documents — do not duplicate their content into this file:

0. How this file is organised

This file is the core every session loads: every rule that holds repo-wide — conventions, data/state patterns, UI patterns, testing, workflow. A rule about one area's behaviour lives in doc/guide/<tema>.md, one file per page, tab, integration or subsystem, read only by whoever touches that area: the pages (panoramica, patrimonio, cashflow*, rendimenti, …), the cross-cutting subsystems since 2026-09-06 (stati, dialog, temi, account-condiviso-demo, Settings inside impostazioni), the test harness since 2026-09-20 (e2e-emulatori), the shell and the persisted cache since 2026-09-30 (shell, cache-persistita), the first-screen census since 2026-10-10 (prima-schermata; its record — baselines, fixture table, widened entries — since 2026-10-17, prima-schermata-misure), and since 2026-10-10 the charts (grafici) and the server layer (server), which left this file whole, the two-step dialogs and the form reset joining dialog the same day. How to use them: section 3 is the index — for each guide the 3–4 things to know BEFORE opening it, then the pointer; the three subsystem guides born from sections 2 and 4 keep their stub under the heading the code cites (§ Server Layer and API Authorization, § Dialog Form Reset, § Two-Step Create Dialogs, § Recharts). A stub that grows past 3–4 points is a guide leaking back (2026-09-20: ten had, up to 2700 characters each; 2026-09-30: four more, up to 2970). Sizes (owner, 2026-10-10): this file ~1000 lines, a guide ~500 — past that a guide splits by sub-topic in a session of its own, never trimmed at a session's close (prima-schermata.md left velocita.md at 514 lines). Each guide opens with a scope line, lists its files and the suites to run after a change there (§ Files), and ends with its Per-page blind spots — behaviours that look like bugs and are not. A session-closing lesson about a domain goes in that domain's guide, never here. Here a lesson is RULE + DATE + WHERE IT IS PINNED (the test or the file that holds it): how it was learned is git log's.

1. Conventions

Italian Localization

• UI text Italian, code comments English. formatCurrency(), formatDate() (DD/MM/YYYY), Sottocategoria (no hyphen), Buongiorno Giuseppe (no comma). English on purpose: Hall of Fame, FIRE e Simulazioni, Cashflow, Assistente AI and the standard metric names; Current Yield → Rendimento Corrente.
• formatPercentage exists TWICE and the two disagree: lib/utils/formatters' is toFixed (40.71%), the it-IT one is Intl('it-IT') (40,71%) — formatPercentageIt/formatNumberIt in lib/utils/formatters.ts, to which chartService DELEGATES (2026-08-31); formatNumberIt takes decimals and pins the width, formatNumber does not. Import from the module the surrounding component uses, or one surface prints both separators. A narrative module the server reads imports from formatters, never from chartService (which top-level-imports the client Firebase SDK): cashflowNarrative, patrimonioNarrative and expenseSplitNarrative are verified SDK-free; a pure module feeding a screen through chartService still mocks the Firebase chain in its tests.
• Curly apostrophes break .tsx (TS1127): delimit with double quotes. JSX eats the space next to an inline tag or wrapped expression once Prettier breaks the line: {' '} on both sides of <strong>/{expr}. An inline-flex chip drops the leading space of a text-node child («69,7%verso FI»): give the words their own <span> and let gap-1 space them.
• Italian Intl breaks naive matching: four-digit amounts print ungrouped (1821,01 € but 29.800,00 €) and the € carries a non-breaking space — anchor as /^821,01[\s ]*€$/, never concatenate amount + ' €'. And in the DOM the space is gone (2026-10-10, owner): NarrativeSegments draws a figure's unit («€», «pt», «pp») as its own span at ml-[0.2em] (splitFigureUnit, components/ui/narrative-text.tsx; the span carries data-figure-unit, which is how the first-screen census still counts the pair as ONE figure — doc/guide/prima-schermata.md), because in Geist Mono the no-break space is a whole cell. The segment's TEXT keeps it (narrativeToText, accessible names, identity tests), textContent does not: a spec reading a verdict, a reading or a strip cell anchors [\s ]*€, never ' €' (ten rewritten that day); figures printed outside NarrativeSegments (RecordRows, the heroes, the tables) still carry the space.

Firebase Dates and Timezone

• toDate() to convert; getItalyMonth()/getItalyYear()/getItalyMonthYear() for domain grouping, never Date.getMonth()/getFullYear(). Server "today" window (cron): getItalyDayBoundsUtc().
• A reader typed Expense[] may still hand out raw Timestamps — convert in the service (2026-09-18: getExpensesForCostCenter did, getAllExpenses converted, and ExpenseDialog threw «Invalid time value» on a row from the other reader).
• Inclusive month upper bound: endOfMonthBound(year, month) — the 1st at midnight drops the whole closing month. <input type="date"> defaults take getItalyDateIso(): toISOString() proposes yesterday from 22:00.

Tailwind Breakpoints and Responsive Layout

• desktop: = 1440px, never lg:. Dialog-internal layouts use sm:; portrait wrappers max-desktop:portrait:pb-20. min-width is inclusive: h-11 desktop:h-9 measures 36px at exactly 1440, the Playwright desktop width (2026-09-21).
• NEVER mix arbitrary min-[px]: with named breakpoints on the same property — named ones compile to rem and v4 emits them last (sm:grid-cols-2 min-[960px]:grid-cols-3 is 2 columns everywhere ≥ 640px). Between tablet: (768) and desktop: (1440) use a container query (@container + @[640px]:, all px). Container queries when one component renders at several widths: column count = container query, drawer-vs-inline = viewport; per-cell @container scales a monetary value to the CELL width. Tailwind 4 emits @container AFTER @media (2026-10-16): a container query on a property that also has a desktop: class (columns, spans, grid rows, display) carries max-desktop: — the landscape stage's max-desktop:@[880px]:contents on a grid that is desktop:grid-cols-12 —, or it wins at 1440 (the cascade, not the width, decides); one inside a tile that holds at every width on purpose (@[760px]:table-cell) does not. The landscape stage (2026-10-16; DESIGN.md → The First-Screen and Closed-Row Rules): the tablet composition's classes live in lib/utils/tabletComposition.ts alone, as literals (__tests__/tabletComposition.test.ts holds the rules over its constants and the nineteen composed grids: the verdict's box VERDICT_CELL_CLASS, the 768 grid COMPACT_GRID_WRAPPER_CLASS/COMPACT_GRID_CLASS with WIDE_CELL_CLASS placed by layoutTabletSections, «Il resto» REST_CELL_CLASS, the scope aside yielding to the answer ASIDE_YIELDS_TO_ANSWER_CLASS, the measured heights through stageCustomProperties and leftStackSticks). A page wraps its verdict and its grid in a NEW div (STAGE_WRAPPER_CLASS = @container; never PageContainer, container-type would anchor a fixed descendant) around STAGE_CLASS, with useTabletStage()'s ref; the verdict's box data-stage="verdict", THE tile's cell data-stage="lead", «Il resto» and the rows inside ONE INDEX_CLASS box (a box of several rows inside it, INDEX_GROUP_CLASS). Below a content box of 880px nothing moves (the wrapper and the grid are what they were, the index contents); from it, below 1440, the grid turns contents and the stage is a 1fr | 360px grid — the answer on the left, sticky when it fits the screen (data-stick, measured), the index on the right at least as tall (--left-h); the heights CSS cannot know are measured by the hook into custom properties. A grid composed in some states only takes THE tile's cell through leadCellClass(composed) and the rest-less states PLAIN_GRID_CLASS, never a bare LEAD_CELL_CLASS — on a plain grid its landscape classes still answer the stage's container and leave the right column empty (Obiettivi with no goal, 2026-10-16). A page hands useTabletComposition the rows it RENDERS, in DOM order (768's pairing). The closed rows ANSWER in the index (2026-10-16, DESIGN.md → The Closed-Row Rule): ONE pure describe*ClosedAnswers per page in its narrative/summary module, given by context (RowAnswers, components/ui/row-answers.tsx) and read by TileRowShell through useRowAnswer — never a prop through the tiles, never on an open or failed row, null to keep the scope aside; each guide's § Composizione mobile lists them. A tile that can be a row lays out its inside by its CONTAINER, never by the viewport (2026-10-16): in landscape every row opens in a 360px index, a phone's width at a tablet's viewport — a tablet: inside such a tile draws the wide layout in 320px (Mutuo's KPIs, Coast's Afflussi timeline, Storico's Composizione legend: @container + @[480|560px]:; Analisi's Flusso picks bar-and-rows by its cell width, useElementWidth < 608). And a container on a row tile's own section answers the page's queries too: it becomes the nearest container of the trigger, so the index's @[880px]: answer measured the 360px row and stayed hidden (BaseDiCalcoloTile, 2026-10-16) — put @container on an inner box. Checked by opening every row in landscape and at 768 on every surface and measuring each tile's right edge, not only main's. The SHELL keys on a named viewport variant, the content on its container: tablet-landscape: (@custom-variant in app/globals.css, orientation: landscape and 1000–1439px) is for the shell only — the icon rail, the one-row header, the tab bars with labels (doc/guide/shell.md § Navigation) — because the shell has no container; it is declared after the core variants so it is emitted after max-desktop:landscape: and beats it on the same property. A composed page's content never uses it.
• A grid item stretches to the row height, a normal-flow child does not inherit it without its own h-full: both the grid-item wrapper and the card div.
• sticky, three rules: it travels only inside its containing block — put it on the box whose PARENT is the tall one and prove it by scrolling main in a spec (2026-09-22, the compact PageHeader's mobile navbar, e2e/settings.mobile.spec.ts); on a grid item it needs self-start, or a stretched sticky top-6 column has no room to travel and silently behaves as static; its offset is measured from the scroller's CONTENT edge, padding excluded (2026-09-14, Strumenti's actions column: sticky right-5 mirroring a -mx-5 px-5 wrapper sat 20px over the last cell) — right-0, and draw the edge rule only while scrollWidth > clientWidth, measured.
• Horizontal page scroll on mobile: an implicit-auto-track grid expands to its widest child — explicit grid-cols-1 and min-w-0 on flex/grid children (they default to min-width:auto); to center one flex child use self-center, not items-center. main is the horizontal scroll container, not the document: <main class="flex-1 overflow-y-auto">'s non-visible overflow-y computes overflow-x to auto, so document.scrollWidth - clientWidth reads 0 while the page scrolls sideways — assert main.scrollWidth === main.clientWidth, and measure the elements, not the container: walk main * and flag rect.right > main.getBoundingClientRect().left + main.clientWidth (at 1440 main starts 256px in), the culpable node is the fix, .sr-only descendants excluded from the walk (2026-09-20, e2e/history.mobile.spec.ts: a visually hidden TABLE is clipped to 1px but its cells keep their rectangles). Reference guard: e2e/fire.mobile.spec.ts.
• One scroll container per region: a nested scrollable captures the wheel (desktop-only symptom), and overflow-x-hidden on an ancestor CLIPS a descendant's overflow-x:auto. An overflow INSIDE a tile never reaches main (2026-09-14, «Entrate per categoria»: 37px past the tile's border, 0 on main): measure a list against its own section (e2e/cashflow.tracciamento.spec.ts), let a column yield under a container query. max-w on a td does not bind an auto-layout table (2026-09-14, the armed row of the Movimenti table): constrain the BLOCK inside the cell.

shadcn Card and Dialog Surface

• CardHeader is flex flex-col: a flex justify-between row inside it makes a flex-1 grandchild act vertically (truncate dies, shrink-0 siblings get pushed off-screen) — use a plain <div className="px-4 py-3 flex items-start gap-2">.
• ResponsiveModal is the ONE modal (2026-08-31): every surface with a form, a list or a report goes through it; the only plain primitives are LogoutDialog (an AlertDialog because it interrupts, role="alertdialog", focus on «Annulla») and the popovers (doc/guide/dialog.md). DialogDescription/DrawerDescription is required in every DialogContent/DrawerContent (sr-only if it should not show), never silenced with aria-describedby={undefined}: ResponsiveModal makes the reading the Description through asChild, or renders description sr-only.
• A shadcn wrapper's own classes ride through asChild and win the merge (2026-09-14, ModalStatusLine): DialogDescription hands text-sm text-muted-foreground down, a child running cn(own…, className) lets tailwind-merge keep the wrapper's, and a font-size utility also drops a leading-* — put the incoming className BEFORE the classes that must win, and read the result with getComputedStyle.

Layout and Color Tokens

• Never hardcode structural colors in shell components — bg-background, text-foreground, border-border.
• Sign colors are tokens: text-positive/text-destructive, chips bg-positive/10, resolved via getMetricValueColor() — drop dark: variants (the token swaps itself); the function returns neutral for the currency format by design, signed currency uses signChipClass/signTextClass. No legacy text-emerald-* is left (the Tracciamento feed 2026-08-22; ExpenseTable, the dividend dialogs and table 2026-09-14; budgetProgressStyle speaks tokens). An expense type has ONE colour map (lib/constants/expenseTypeColors.ts, 2026-09-14): the feed's dot, the table's badge and the hero's legend; a row's income is the sign token positive, each outflow a chart slot, the SERIES (bars) take chart slots, never the sign token. Sign tokens mean gain and loss, and nothing else: a neutral delta (a class gaining share) stays text-muted-foreground. A figure that PRINTS as zero takes no sign and no sign token, whatever the raw value (2026-10-10, the phone composition: a strip cell and the tile beside it must print the same zero — DESIGN.md → The Lifted-Figure Rule; on the tiles since 2026-10-12): decide the «−» on the formatted text with withTypographicMinus/formatEuroMinus (lib/utils/formatters.ts, where isPrintedZero lives, pinned by __tests__/formatters.test.ts), never on value < 0; a percent or a gap in points takes printedSign/formatSignedPercentIt/formatSignedPoints from the same module (the Rendimento (TWR) tile since 2026-10-14: its hero and chips repeat a strip cell), a signed euro formatSignedEuro (Patrimonio's G/P and Storico's «ultimi 12 mesi» chip since 2026-10-14, the chip's percentage since 2026-10-15, __tests__/evoluzioneTileChips.test.ts). The sites outside the composed surfaces (the rest of Rendimenti and Storico, email, PDF) still decide on the raw value, on purpose — count them with grep -rnE "< 0 \? ['\"]−" lib components app, never quote a number (the helper itself is among the hits).
• --warning is near-white in light mode: text on a bg-warning fill MUST be text-warning-foreground; a caution reading and the verdict's dot use text-warning-foreground too.
• A chart slot is not a text colour — --chart-1..8 target ~3:1 against a plot area (text-[var(--chart-3)] measured 1.02:1 on one theme; the 2026-08-30 tail audited the twelve blocks to 3.38:1 worst case, so the range is 1..8; but on 2026-09-18 --chart-3 light measured 2,74:1 and --chart-1 dark 2,62:1 ON A CARD — re-measure before leaning on that floor, doc/guide/temi.md § Per-page blind spots). The semantic amber is --warning-foreground; only ExpenseTable's chips are exempt. A chart slot used as TEXT is held to 4,5:1: __tests__/actionColorContrast.test.ts measures COMPRA/VENDI/OK across all twelve theme blocks, on --card and on the chip's own color-mix fill (the HARDER surface).
• A computed custom property comes back as lab(), never as the oklch() you authored: anything that READS a colour token parses lab() (and #hex) too and never asserts /^oklch\(/ — through lib/utils/colorParse.ts, the ONE parser since 2026-10-08. Two readers were DEAD CODE from the day they were written: useActionColors' legibility clamp (until 2026-09-21, raw chart slots as 10-18px text at 2,39-4,02:1) and useChartColors' luminance filter (until 2026-10-08, __tests__/chartColorsContext.test.ts). Worked example: lib/utils/actionColor.ts, whose test feeds it the browser's own serialisation.
• Sidebar tokens: --sidebar-accent is a background, --sidebar-accent-foreground text ON it; hover on inactive items hover:text-sidebar-foreground. Inline style blocks Tailwind hover variants: migrate to classes first.
• CSS custom properties never reach emails or the PDF (both render outside the DOM): the sign hexes there are permanently out of sync (doc/guide/email-pdf.md § Per-page blind spots).

2. Data and State Patterns

React Query and Derived State

• Query + invalidation, never realtime — and Firestore is not the limit (measured 2026-09-26, the speed dossier: with the emulator answering in ~1 ms Cashflow still took 2,1 s and Storico 2,3 s to show a figure — browser CPU and the boot chain, not the database; in production a round trip is 50–150 ms, so what counts is round trips IN SERIES). No onSnapshot, no migration (Postgres/Supabase/Convex would rewrite ~40 services, the rules and the harness without touching the measured causes): the two Firestore levers are the function region (SETUP.md § Function region) and the materialized per-page summaries (§ Caching).
• A page or a component never calls a read service: it reads a HOOK (2026-09-29). One key per collection in lib/query/queryKeys.ts, one hook apiece in lib/hooks/: useAssets, useSnapshots, useExpenses (and its windows), useExpenseCategories, useSettings (the ONE ['settings', ownerId]), usePensionContributions, useAssetTransactions, useCostCenters, useGoalData, useDividendReceipts, useHallOfFame, useMortgageInstalments, useDashboardOverview. A service that computes from collections takes them as an argument (2026-10-04, getAllPerformanceData(userId, forceRefresh, inputs?)). An imperative read (a refresh, a dialog reading once after a write, the CSV import before it commits) goes through the hook's exported …QueryOptions(ownerId) with queryClient.fetchQuery — same key, same reader, the global staleTime; staleTime: 0 where the CURRENT document is the point («Annulla» on Impostazioni, the pre-read of its «Salva», the import's commit). A form seeded from a document OBSERVES its hook and settles the seed during render (Impostazioni since 2026-10-08): the owner's first document seeds the draft, a fresher read re-seeds only while nothing is dirty, «Annulla» is a RE-READ (fetchQuery, staleTime: 0) then a reset — never a copy kept in memory (doc/guide/impostazioni.md). The closing grep of a session: grep -rn "getSettings(\|getAllAssets(\|getUserSnapshots(\|getAllExpenses(\|getAllCategories(" app components — hooks and services only. Every writer invalidates the key its readers read (queryKeys.settings.all from the seven places of doc/guide/impostazioni.md § Settings — the FIVE places, goals.all from Obiettivi AND the assistant's goal card).
• The expenses are read by WINDOW, and lib/utils/expenseWindows.ts is the ONE source of the windows (2026-09-30): Tracciamento and Divisione (trackingWindow), Budget (budgetWindow, budgetSuggestionWindow) and FIRE (fireWindows) read useExpensesInRange(ownerId, window), one key per window UNDER expenses.all; Storico, Analisi (owner's decision: a window left out only 48 rows of 1547) and the cost centres read the whole list. A window is the UNION of what its page reads — a new reader widens it in the same commit and joins __tests__/expenseWindows.test.ts; the bounds are calendar days in both calendars, never UTC; never placeholderData on a window (doc/guide/cashflow.md § Expenses by window).
• A page over several keys composes ONE read state (composeReadState, lib/utils/readState.ts): loading while any query reads, loadFailed when any failed — then resolveSurfaceState. Storico reads six keys this way.
• Invalidate all related caches after a mutation; asset mutations need a dual invalidation (queryKeys.assets.all
  • queryKeys.dashboard.overview: the Patrimonio hero reads the overview).
• useMemo for derived state, never useEffect + setState. forceMount tabs deriving from a sibling's data MUST use React Query (a mount-time loader runs once and the tab goes stale until reload); invalidate unconditionally on expense save/delete. initialData on a query with a global staleTime silently disables its fetch (5min + refetchOnWindowFocus: false): use placeholderData. Lazy-gate expensive panels with enabled: !!userId && isOpen and read isLoading, not isPending, on a disabled query (isPending stays true forever).
• An async view must gate on EVERY query it reads (queries defaulting to [] short-circuit into "nothing tracked yet" on a cold load) and a failed fetch is not an empty set: route isError to a role="alert" notice first.
• State belonging to a subject must be stored WITH its subject, not reset by an effect (banned by react-hooks/set-state-in-effect): useState<{ scopeKey, value } | null> and derive, so a stale key falls back to the default with no effect and no extra render.

Dialog Form Reset

• The reset useEffect takes open in its deps, starts with if (!open) return and holds ONLY the react-hook-form calls (reset, setValue, replaceTiers); the dialog's own useState (step, status, toggles, a selected id) is settled during render keyed on (open, record) (2026-09-06, react-hooks/set-state-in-effect). The new-record branch enumerates every field and calls replaceTiers([]); useWatch() for render, getValues() for handlers, never watch().
• Il resto — the fields the new-record branch must enumerate and replaceTiers([]) — in doc/guide/dialog.md § Dialog Form Reset.

Two-Step Create Dialogs (AssetDialog, ExpenseDialog)

• A form whose fields depend on a discriminant is a two-step dialog (AssetDialog, ExpenseDialog, kept in step): create opens on step 1, edit skips to step 2, and setStep(record ? 2 : 1) is settled during render, never in useState's initializer, even where the host mounts the dialog only while open (Patrimonio since 2026-10-07; guard e2e/assets.rows.spec.ts «Nuovo after Modifica opens on step 1»).
• A marker on a label is a claim the validation honours: * / (opzionale), the zod schema and any onSubmit guard agree (2026-08-30, Sottocategoria).
• Il resto — when a discriminant earns a step, the optional back-link callback as the Select's switch, the module-level picker with Icon as a component, step 1 re-pointing the category — in doc/guide/dialog.md § Two-Step Create Dialogs

Firestore Writes

• updateDoc only touches fields present in the object and removeUndefinedDeep strips undefined, so clearing an optional field needs deleteField() — not allowed with setDoc() without merge:true; removeUndefinedDeep must stay deep, preserving Date/Timestamp/FieldValue. The clear-guard depends on whether partial callers exist: averageCost/taxRate/displayTicker are written only by AssetDialog with a complete form, so === undefined → deleteField() is safe; leverageRatio also rides on plain updateAsset and needs the 'leverageRatio' in updates guard, or a price refresh wipes it.
• runTransaction: ALL tx.get() before ANY write — a get→update loop breaks on the second doc and is invisible when the function is mocked; aggregate deltas per docId first (template __tests__/updateCashAssetBalancesAtomic.test.ts), success toasts AFTER the reconcile returns. Firestore rejects undefined inside an array element: assetAllocationService.ts builds docData by hand, so its array fields need a whitelisting serializer with conditional spreads.
• A bare .set() on a server-owned doc DELETES every field its object omits, and the daily cron re-runs them all. A value that disappears "sometimes" is a periodic write over a window, never a TTL (2026-09-07: the snapshot cron rewrites only the CURRENT month). Keep the replace and carry the hand-written fields across it (preserveUserAuthoredSnapshotFields, pinned by __tests__/apiAuthRoutes.test.ts → keeps the Storico note of the snapshot it overwrites); merge: true is the wrong fix whenever the doc holds a MAP the pipeline recomputes.

Firestore Queries and the Rules

• A list must carry the constraint the rule needs, or it is refused entirely: every collection guarded by allow read: if canAccess(resource.data.userId) rejects a query that does not already filter on userId — permission-denied at ANY result size, and a batch built from the empty result silently does nothing (deleteExpensesByImportBatch is the correct shape). Unit suites cannot see this: only an emulator exercise driving the CLIENT SDK evaluates the rules. Max 3 .where() calls on a chain that will be unit-tested; a 4th breaks the mock chain.

Caching

• A per-user pre-computed cache keys EVERY determining input (performance-cache/{userId}: a hash of the whole snapshot series, the base signature, the risk-free rate, the dividend category; a 6h TTL covers what the key cannot; reads/writes try/catch fire-and-forget; Date ↔ Timestamp field-by-field, never JSON). A figure whose inputs the key does not cover stays OUT of the document (2026-10-04, Rendimenti's dividend yields — doc/guide/rendimenti.md). A changed FORMULA is the one input no signature sees — bump CACHE_MATH_VERSION (v8); verifying by hand, press Aggiorna (forceRefresh) first; a new optional field needs no bump if paired with ?force=true; wire «Aggiorna» to refresh(), never to a bare refetch().
• Global shared cache (benchmark, FX, ECB): natural key as doc id, no userId, read: isAuthenticated(); write: false; client staleTime = server TTL minus headroom. A shared per-ticker cache the client NEVER reads (instrument-profile-cache, 2026-09-28): rules if false, Admin SDK only, ONLY the external source's answers (mergeFields per module) — doc/guide/allocazione.md § Esposizione.
• A server-owned materialized summary is fresh only while every write to an input invalidates it (dashboardOverviewSummaries/{userId}, 2026-10-03): a new writer owes its invalidation in the same commit; fresh = no invalidatedAt, same sourceVersion, same Italian day, ≤ 6 h; rebuilt in after() under a precondition — doc/guide/panoramica.md § The materialized summary.
• The React Query cache is persisted to IndexedDB (2026-09-29) → doc/guide/cache-persistita.md: only the PERSISTED_QUERY_PREFIXES keys (lib/constants/persistCache.ts), only successful reads, never the demo uid; gcTime per prefix (applyPersistedQueryDefaults). Bump PERSIST_CACHE_VERSION when a persisted payload's field is renamed, removed or retyped. Three traps: a surface outside ProtectedRoute gates on useIsRestoring(); the cache is forgotten at sign-out by the provider (SignOutCacheGuard); the persister's first write is immediate (e2e/freshness.spec.ts). Rollback NEXT_PUBLIC_PERSIST_QUERIES=false.

Server Layer and API Authorization → doc/guide/server.md

• Route = auth → validate → fetch → ownership check → delegate → return, with no Firestore queries or business logic in the handler. The Admin SDK bypasses Firestore rules, so ownership is checked after the doc loads. Owner-scoped routes call assertCanAccessAccount(decodedToken, ownerUserId) and never fall back to decodedToken.uid.
• A date in a request is a STRING first (2026-10-04): every request date goes through isoDateSchema + parseOr400 in lib/server/validation.ts, never an as { … } cast. On its own, z.coerce.date() turns null into 1970-01-01, which gives a 200 instead of a 400. Pinned by __tests__/performanceYieldsRoute.test.ts and serverValidation.test.ts.
• A Vercel Function never require()s an ESM-only package, on any Node version (2026-10-08, PR #436): package.json overrides → jwks-rsa ^3.2.2 and engines.node "24.x", held by __tests__/vercelConfig.test.ts. Grep a new server dependency's require( calls. The emulators cannot see this; only a real token on a deploy shows it.
• tsc does not protect a server-only module (2026-09-06): importing one from a client page type-checks and only fails in the browser. Client pages read through a client reader (lib/services/dividendReceiptsService.ts), and tests mock it with vi.mock('server-only', () => ({})).
• Il resto — the cron routes and CRON_SECRET (/api/portfolio/snapshot keeps cronSecret), the Server-Timing header (lib/server/serverTiming.ts, its stages, the recorder, counts beside the body), REGISTRATION_WHITELIST without NEXT_PUBLIC_, the files and the suites — in doc/guide/server.md.

Dynamic Imports and Module Hygiene

• Components must be at module level — one defined in a render body is a new type every render (remount, AnimatePresence enter never plays, useEffect([]) re-fires, the React Compiler throws). react-hooks/static-components flags ANY component obtained from a call during render, useMemo(() => lazy(…)) included (probed 2026-09-06): only a property read of a module constant passes — the icon pickers' ONE map LAZY_CATEGORY_ICONS (IconPickerPopover), one chunk per icon since 2026-09-30 through the 121 loaders of components/expenses/categoryIconLoaders.ts, never import('lucide-react') by a runtime name nor lucide-react/dynamicIconImports (+49 KB gz, measured); a new curated name needs its loader (__tests__/categoryIcons.test.ts) — doc/guide/cashflow.md.
• A library several pages use goes behind ONE module of real code (2026-09-30): recharts only from components/ui/charts/recharts.ts, which binds export const X = RechartsX — Turbopack batches a library by where it is ENTERED (four identical 350 KB copies, one per page) and a barrel of bare re-exports is transparent to it; perf:budget's libraryCopies is red at two copies.
• A chart inside something closed by default is a lazyComponent at MODULE level (2026-09-30, components/ui/lazy-component.tsx) with a fallback of the chart's OWN height (layout-shift 0). Not next/dynamic: React.lazy + Suspense suspends on every first render and React 19 holds a committed fallback ~300 ms. Preload with usePreloadWhenIdle(ARRAY, enabled) — a module-level array, enabled = the page's data is in (an «idle» browser waiting on Firestore is not idle: +130 ms on Analisi) and, where only one width draws the chart, that width (Patrimonio's sparkline, phone only, 2026-10-07). Lazy the PLOT, never the section that owns the trigger; decide an empty series outside the lazy module; import types only from it. A lazy TAB's fallback is the tab's own loading state, control rows included (2026-10-06, components/cashflow/CashflowTabSkeletons.tsx, e2e/lazyTabLanding.ts). Worked examples: PerformanceDettaglio, ConfrontoAnnualeSection, FlussoTile, the four lazy FIRE tabs, Cashflow's four non-default tabs, AssetRow's sparkline. Next prefetches every shell link's route, client chunks included: only a chunk reached solely by an import() stays unfetched (doc/guide/velocita.md, «Il prefetch dei link della shell»).
• Pure lib/utils modules reach calculateAssetValue injected as a valueOf param (allocationUtils, pensionFire) or imported directly with the test mocking @/lib/firebase/config + firebase/firestore + authFetch + dashboardOverviewInvalidation — check the precedent. Functions that call new Date() internally are untestable: pass now: Date. shadcn vendored surface policy: components/ui/** is knip-ignored and standard shadcn API stays even at zero references; only custom additions made in this repo get deleted.
• CSS custom property liveness — the 5-check sweep. A token is live if ANY holds: var(--name in .ts/.tsx/.css; if mapped via @theme, the generated utility name appears (grep bg-X, not the variable); getPropertyValue; an internal chain; the vendored-surface contract. A confirmed-dead token leaves every theme block in one commit.

Shared Constants and Fixed Hooks

• Rule of Three: a map used in 3+ files lives in lib/constants/<domain>.ts. The canonical symptom of a duplicated Record<Type, string> is one copy missing its dark: variants — illegible in dark mode with a clean tsc.
• Declare N fixed hook instances with enabled: false for the inactive ones — never loop over hooks.
• Yahoo module asymmetry — funds topHoldings → sectorWeightings, stocks assetProfile → sector, the two maps in lib/constants/exposureSectors.ts, two MODULES of one per-ticker document since 2026-09-28: doc/guide/allocazione.md § Esposizione — the per-ticker cache and Yahoo's two modules.

3. Domain guides

The per-area rules live in doc/guide/. Each entry below is the stub — the 3–4 things to know before opening the guide — then the pointer. In code comments and the other docs, doc/guide/<f>.md § <name> resolves to a ## heading kept verbatim from the section name this file used to carry.

Panoramica → doc/guide/panoramica.md

• Overview data flows through GET /api/dashboard/overview + useDashboardOverview() only — no page-level fan-out, no full-history expense queries; dashboardOverviewSummaries/{userId} is server-owned, fresh for the Italian day, and every write to an input invalidates it — a new writer owes its invalidation (§ The materialized summary). Both endpoints owner-scoped.
• topMovers/marketEffect are MARKET return, never the user's flows: [] when the previous snapshot has no byAsset, null when not attributable (≠ measured 0).
• Every sentence comes from overviewNarrative.ts; a falling month blames the market only when marketEffect < 0. resolveDeclineCause (lib/utils/periodSales.ts) is the ONE decision for Panoramica, Patrimonio and the email (the tax in the headline, 2026-09-13), resolveTaxedGrowth its twin for a month that did NOT fall (2026-09-19).
• A driver subject missing from CLASS_SUBJECTS drops the clause, never prints itself; the page has no «Dettaglio» of its own.
• Il resto — the mobile composition (§ Composizione mobile), salesNarrative.ts (the shared words), the tax headlines, the month's split and the user's money outside the cashflow it names (monthFlows: pension contributions, principal repaid per debt — 2026-10-14), the trade-aware market, the lived savings rate, the category deep link, the hero step-down, the tile grid, the superseded-pattern rule, the Italian-copy test trap — in doc/guide/panoramica.md.

Patrimonio · Asset Pricing, FX and Assets → doc/guide/patrimonio.md

• "Does this asset have a market price?" is ONE rule in assetPricing.ts (hasMarketPrice/requiresManualPricing); a new hand-valued type goes in MANUALLY_VALUED_TYPES and nowhere else.
• A debt is a loan ASSET worth minus its principal (2026-10-10, types/assets.ts → LOAN_ASSET_TYPE, the sign in calculateAssetValue): the property stays GROSS, the loan sits in the class of what it finances (realestate when financedAssetId, else cash = negative liquidity), out of every Rendimenti base, out of FIRE with the primary residence it finances. In the Allocazione a loan FOLLOWS what it finances (2026-10-17, resolveAllocationRoleWithin): a mortgage takes its property's role (excluded home → nets the excluded figure; a property in the allocation → nets Immobili in the base), a personal loan nets Liquidità in the base; never a plan's leg, its stored allocationRole inert. Its «Intestatario» follows the property too (resolveAssetOwnerId, lib/utils/assetOwnership.ts). Where the debt lives on the document is debtBalanceField's alone (a loan's quantity, a legacy property's outstandingDebt, read-only since the one-shot migration loanMigration.ts).
• GBp (pence) ≠ GBP — normalize price / 100 before any FX; never call Frankfurter from the browser; quantity = 0 marks a sold asset.
• A Borsa Italiana bond quote is % of par, always, and lib/utils/bondPricing.ts is the ONE conversion (quote / 100 × nominal × coefficient, nominal 1 € by default). Never re-implement it; never guard it on nominal > 1 again (issue #340).
• Every G/P, tax estimate, YOC and PMC cell stands EUR against EUR through lib/utils/costBasisEur.ts (costBasisPerUnitEur, fees included); undefined without a EUR PMC — print nothing, never dollars against euros.
• Δ columns are UNIT-PRICE variations, not P&L; isHeld (quantity > 0) gates every count/share/sum; numbers not in the payload are born in patrimonioSummary.ts; the page owns every dialog.
• Il resto — the mobile composition (§ Composizione mobile), the «Mutuo» tile, one per LOAN (interest measured only from the settled instalments, mortgageSummary.ts), the loan migration and its blind spots, the split class chip of a composite instrument (describeAssetClassChip), BTP€i, the «Andamento» view, hasCostBasis, MIN_ANNUALIZABLE_DAYS, the instrument driver, suggestIsLiquid, the cash-account picker rule, the article helpers, the failed-overview branch, the averageCostEur backfill — in doc/guide/patrimonio.md.

Asset Trade Ledger → doc/guide/registro-operazioni.md

• ALL trade money-math (replay, PMC, realized P&L, XIRR, invested capital) lives in assetTransactionUtils.ts, pure; the service/route layer is a thin atomic writer. A new AssetTransactionType updates the replay switch, the zod schema AND TransactionDialog.
• Writes are Admin-API-only, all reads before any writes, derived fields written in-tx (never via updateAsset); ledger-type edits go through updateAssetMetadata. A settlement moves CENTS (lib/utils/cents.ts), and a sell credits proceeds − fees − withheldTaxEur (lib/utils/saleTax.ts, 2026-09-20); realized P&L and XIRR stay gross of the tax.
• The migration baseline (isBaseline BUY) NEVER stamps holdingStartDate; a replay returning holdingStartDate: undefined means leave the doc untouched (never deleteField()).
• A trade date has ONE floor — the asset's OWN baseline (BASELINE_NOT_FIRST) — and the future as its only ceiling (2026-09-13); assetTransactionsMeta.baselineDate is NOT a floor.
• Per-transaction derived data comes from replayTransactionsWithEffects (one pass), never a replay per prefix.
• Il resto — settlement timing, buildDerivedAssetFields and the averageCostEur backfill, resolveBondPrice reuse, the two totalReturnAssets paths, the static-copy audit rule — in doc/guide/registro-operazioni.md.

Cashflow — expense mechanics → doc/guide/cashflow.md

• Category names are NOT unique: group by getCategoryKey/getSubCategoryKey, display via resolveDisplayLabels.
• Income positive, expenses negative, net = sum(income) + sum(expenses); classification ALWAYS by type, never by the sign of amount. Crossing the transfer boundary flips the sign and the BATCH paths refuse it; a transfer IS its two accounts (the schema refuses it otherwise).
• A recurring expense is N real future-dated rows sharing recurringParentId, not a rule; canTypeRecur = fixed/variable/debt only; MAX_RECURRENCE_OCCURRENCES keeps the batch under 500.
• A linked row moves its account ON ITS OWN DATE (lib/utils/cashSettlement.ts, 2026-09-19): balancePending until settleDueBalances runs in /api/portfolio/snapshot; the flag ABSENT means applied; edits and deletes move only what was applied.
• CSV import: MANDATORY preview, undo by importBatchId, category identity is (name, type). ONE drill destination (handleEntitySelect); Sankey ids are built from ids.
• A row's fee is a row of its own, on ANY row and on every occurrence of a series (2026-10-10, lib/utils/expenseFee.ts; a transfer's alone until then — the stored field names transferFeeExpenseId/feeOfTransferId keep their birth name): created in the same batch as its parent, edited from it, deleted with it — a SERIES delete gives the fees' balances back too (getFeesOf), from the tab AND the table. A debt row repays a LOAN (debtAssetId); «Estinzione anticipata» (isDebtPayoff) is all principal. A transfer may land on a property priced 1 (a deposit).
• Il resto — le sei regole per esteso, linkedCashAssetId su ogni occorrenza, «Collega la serie», lo schema del transfer e la sua spec, la commissione come riga propria (expenseFee.ts), la rata che riduce il debito per la QUOTA CAPITALE (mortgageRepayment.ts), l'estinzione, il trasferimento su un immobile — in doc/guide/cashflow.md.

Cashflow › Tracciamento → doc/guide/cashflow-tracciamento.md

• ONE period axis, two slices: expenses feeds the verdict and every tile; filteredExpenses feeds ONLY the Movimenti list. Never route a tile through filteredExpenses; the phone bar's picker is a second HANDLE on the same period, never a second axis.
• A period is its WHOLE calendar span; what has not happened is DECLARED (chip «In calendario», sign colour dropped). isScheduledRow = after today by Italian calendar DAY (isItalyDayAfter), shared with budgetUtils and costCenterSummary.
• The verdict judges what has HAPPENED (settleTotals, 2026-09-14), then says where the calendar takes it. The month in progress is compared with the SAME DAYS of the previous month (currentComparisonWindow/previousComparisonWindow); a previous period is honest or absent.
• «Da inizio anno» (Period.kind = 'ytd') and «Anno corrente» ('current', full-year delta since 2026-08-30) are different windows, never one.
• Every number from tracciamentoSummary.ts, every sentence from cashflowNarrative.ts.
• Il resto — the mobile composition (§ Composizione mobile; the five tabs' shared contract — forceMount, prefixed ids, a memory per tab, active — in doc/guide/cashflow.md § The tabs load their code on demand), the verdict's two sentences, previousPeriod, the two windows anchored to today, the month-end projection, the feed, the mobile filters, the Movimenti reading, «Intestatario» (lib/utils/movementsOwnerFilter.ts, memberNames) — in doc/guide/cashflow-tracciamento.md.

Analisi — a verdict over tiles → doc/guide/cashflow-analisi.md

• FOUR axis modes (Da inizio anno | Anno corrente | Anno | Storico); ytd and current are not the same window.
• A running year is NOT clipped (periodExpenses takes the whole calendar year); the pacing compares year vs year−1 on the period's own span (resolveComparisonScope), the running MONTH on the same days of its baseline (throughDay, rows through dayOf), plus the shared scheduledSentence. The history CLOSES on the current year (availableYears, the Storico slice, the two charts' BucketCeiling): a plan's rows in 2043 are a calendar, not years.
• The Scheda is a tile of the grid; every entry point lands through handleEntitySelect; URL focus is three FLAT params (?focusType&focusCat&focusSub); closing it returns the focus to its opener. Its pace divides the LIVED total by the months lived (computeEntityRunRate: livedTotal/livedMonths), the projection takes the calendar as a FLOOR under the pace, and its period carries the page's throughMonth cut.
• Every number has one source (analisiSummary.ts, comparisonDeltas.ts); every sentence from analisiNarrative.ts/cashflowNarrative.ts, never a component.
• Il resto — the mobile composition (§ Composizione mobile), «Fuori scala», the Periodo pacing, EntityDossier, the Sankey rules, the optional Flusso by 50/30/20 role (spendingRoles.ts), the Flusso's drawing below 640px (a share bar and rows, a legibility threshold of the chart), Playwright — in doc/guide/cashflow-analisi.md.

Cashflow › Budget → doc/guide/cashflow-budget.md

• Opt-in (reconcileBudgetItems never auto-creates); NO period axis (always the current Italian month; annual budgets are year-to-date on their own Off-Axis tile).
• ONE projection rule, the app's: buildSpendingForecast over the month's spending SPLIT at today (spendingProjection.ts, shared with Panoramica/Tracciamento); a FIXED category never follows the pace; MIN_FORECAST_DAYS (4).
• Risk vs fact: «Categorie a rischio» = projection over amount AND not over yet; a budget already over is a fact for «Avvisi». No row in two tiles. A threshold is a fact of what is BOOKED (BudgetAlert.spent = up to today), read against the calendar of its own window (calendarPct, aheadOfCalendar): the amber is for the rows ahead of it only. «Speso» is spentToDate; the scheduled rows are their own clause in every sentence (2026-09-14).
• The ceiling IS historicised by the cron (phase 8, one doc per month, budgetHistory/{uid}/months/{YYYY-MM}, allow write: if false). The crossing day is a fact of the EXPENSE DATES, never a cron's memory.
• Il resto — the mobile composition (§ Composizione mobile), summarizeCeiling, the two-face KPIs on exceeded, BudgetTrack, the cashflow:add-budget event — in doc/guide/cashflow-budget.md.

Centri di Costo → doc/guide/centri-di-costo.md

• NO period axis, by decision (2026-08-23): a project's cost is its whole cost; every figure is lifetime («in totale») unless the tile names its window.
• summarizeCenter splits rows at today: booked ones are the cost; scheduled ones get an «in calendario» chip, feed a window's end and a ceiling's spent, and are NEVER summed into the total.
• A CENTER HAS NO PACE (2026-09-18): a window's end is booked + calendar (ytd + yearScheduled), never projectWindowEndWithScheduled. Budget keeps its pace — do not unify; a monthly ceiling reads Budget's summarizeCeiling but re-derives exceeded.
• The open center lives in the URL (?tab=cost-centers&center=<id>); a new center opens on firstFreeColorKey, and existing documents are never re-coloured.
• Every number from costCenterSummary.ts, every sentence from costCenterNarrative.ts. Any count next to a destructive action comes from the same read the mutation runs (the rows are grouped in memory from the expenses key since 2026-09-29).
• Il resto — the mobile composition (§ Composizione mobile), risk vs fact (exceeded/atRisk) and the detail's ranking, the retired picker, the backdated row, how the detail lands and refocuses (data-center-row), CenterStackBars, «Collega spese…», session-only lenses — in doc/guide/centri-di-costo.md.

Cashflow › Divisione → doc/guide/cashflow-divisione.md

• Opt-in, on Tracciamento's period axis. ONE field carries the feature: Expense.personalMemberId; absent (or null) MEANS «in comune» (so no migration). Members are Previdenza's FamilyMembers, never a second list. Writing it is a FOUR-place fan-out.
• The share is NEVER invented: resolveSplitBasis returns unavailable (with missingNames) below two people or when one person has no income attributed in the period; every split figure is then null. The base is the PERIOD's attributed income, WHATEVER its category (owner's decision, 2026-09-27; labor-only from 2026-08-31 until then) — do not «stabilise» it silently.
• Income left «in comune» pays the pool FIRST (2026-09-27): the shares divide CommonSpending.toSplit = max(0, total − income), a surplus is declared and never distributed. A residual is of money that has MOVED (2026-09-21): the page prints and colours remainingBooked; remaining is the whole period's.
• allocateByShare charges the rounding residual to the LARGEST share and re-rounds — untestable on two shares (they cancel), test on three.
• Il resto — the mobile composition (§ Composizione mobile), unattributedIncome, the booked pool net of the income received and the «Da dividere» row, the calendar as a separate clause, laborIncomeCategoryIds no longer read, the readers outside the tab (movementsOwnerFilter.ts), the deleted-member bucket, the dialog control, effectiveTab, the one-cell people row, the verdict-explains/tile-instructs split, «Attribuisci spese» — in doc/guide/cashflow-divisione.md.

Cashflow › Dividendi · Dividends and Coupons → doc/guide/cashflow-dividendi.md

• RECEIVED AND ANNOUNCED ARE NEVER ONE FIGURE — counted, totalled and coloured apart on every surface; summarizePayments returns two halves and no sum.
• ONE period axis (resolvePeriodBounds, upper bound = end of the period's own unit, NOT today), the announced money ON it; filters narrow only the list. TWO POPULATIONS, BOTH NAMED (2026-09-14): verdict and inventory read the REGISTRY (sold included); Affidabilità and Chi paga di più measure the HELD portfolio (heldAssetIds).
• A coupon's cashflow expense is created only by the daily cron on payment date (!isAutoGenerated, idempotent via expenseId), and it credits the instrument's account, else the default, ONLY when the payment is not an arrear (lib/utils/dividendAccount.ts, 2026-09-20) — row, balance and expenseId in one transaction.
• Two inflation mechanisms, ONE field (inflationIndexation, read via resolveInflationIndexation): BTP Italia ADDS the FOI rate, a BTP€i MULTIPLIES by the coefficient. Adding a DividendType is a six-file fan-out. A CouponFrequency 'maturity' is ONE coupon with the redemption (2026-10-10, the BTP Valore Insieme): getPeriodsPerYear is 0 there and every divider asks isSingleCouponAtMaturity first; the coupon is the rate COMPOUNDED over the term (calculateMaturityCouponPerShare).
• Il resto — the mobile composition (§ Composizione mobile), the Rendimento tile off the axis, useDividendStats without date bounds, the tab's ONE request (the stats answer carries the list, useDividendRegistry; stats: null keeps the list when a measure fails), every number from dividendAnalytics.ts, a scraped dividend's ONE floor (lib/utils/dividendEligibility.ts, 2026-09-13), the zero coupon (hasCouponPayments), the calendar, the form (taxRate proposal, picker) and the armed row delete, computeDividendYieldMetrics, the legacy isInflationLinked, provisional coupons, the running-window rule, couponUtils — in doc/guide/cashflow-dividendi.md.

Storico · History and Snapshot Baselines → doc/guide/storico.md

• The snapshot cron runs DAILY (the name lies) and both writers REPLACE the document: a new MonthlySnapshot field no pipeline recomputes goes in SNAPSHOT_USER_AUTHORED_FIELDS or the cron erases it (§ Firestore Writes).
• Reuse byAsset.totalValue for per-instrument history, never recompute; byAsset.price is RAW NATIVE currency (EUR unit value = totalValue / quantity).
• The page's CAGR is WEALTH growth ((endNW/startNW)^(12/months)−1, «versamenti inclusi»), never Rendimenti's return; ONE linear pace (summarizeGrowthPace), do not compound it.
• The Driver is SIX parts (lib/utils/growthDrivers.ts, 2026-09-19), its market MEASURED per instrument (marketEffect.ts) — never «Δ − risparmio»; Lavoro takes the Driver's windows AND parts. «Mutuo» reads the LOAN rows as a total since 2026-10-10 (a loan's byAsset.totalValue is minus its principal), the legacy property pairing beside it: the two cross the migration month without a jump.
• The parts are a LEDGER (buildDriverLedger, 2026-09-20) that closes TO THE EURO (reconcileRemainder); a flow is signed and uncoloured (isFlowDominated).
• Il resto — the mobile composition (§ Composizione mobile), baselines, attribution (buildMonthAssetBreakdown), each Driver part, summarizeLaborMetrics/laborWindowsOf, the manual-snapshot cross-validation, Recharts in a flex tile, the container-query table, the two-column grid — in doc/guide/storico.md.

Hall of Fame — a verdict over tiles → doc/guide/hall-of-fame.md

• The page has NO axis and re-derives nothing: hall-of-fame/{userId} holds the rankings; "today" is a PARAMETER, never new Date() inside the module.
• hallOfFameRecords.ts is the ONE definition of a record AND a ranking — both writers and the periodic email call buildHallOfFameRankings; never re-implement a ranking.
• A stale document heals only from the page's «Aggiorna» button when the account has no assets (the cron gates on snapshotResult.success); disabled in demo. Never document a field as "the cron will fill it in".
• A savings record needs income (totalIncome > 0 guard); stats and the two savings rankings are OPTIONAL on pre-2026-08-25 documents — getBoard returns null (≠ empty board), never ?? []. Same for rankingsUpdatedAt, stats.sinceWorstMonth and YearlyRecord.monthsCovered (2026-09-24): stored by updateHallOfFame, never derived, their clause dropped when absent.
• Il resto — the mobile composition (§ Composizione mobile), the podium-vs-chronology split, the tile-never-repeats-the-verdict rule, NoteTrigger and the prefilled note, the section-key fan-out, the Playwright locators — in doc/guide/hall-of-fame.md.

Rendimenti → doc/guide/rendimenti.md

• The base is resolved ONCE by resolvePerformanceBase for its THREE call sites (service, page, PDF). An exclusion read from byAsset MUST be backfilled across the pre-byAsset months (constant E₀) or it becomes a phantom crash.
• The pension toggle WINS over a fund's allocationRole. A contribution is a flow iff it crosses the base's boundary; flows ride their own channels (externalFlowOf), netCashFlow stays the cashflow's savings.
• The flows follow the base (2026-09-07): with anything out of it, the months with byAsset on both snapshots neutralise the MEASURED boundary flows (lib/utils/portfolioFlows.ts); the ledger speaks for an instrument only once the base has SEEN it (2026-09-13).
• The first snapshot of a period is the starting valuation, never a measured month; the page must NEVER re-derive the window from new Date() (metrics.nominalPeriodStart).
• No silent filters inside a metric (null with a reason); the attribution (performanceAttribution.ts) is EURO and reconciled to the TWR numerator.
• Il resto — the mobile composition (§ Composizione mobile), buildCacheKey, the flow channels and the entry month, performanceExcludesCash, the hero below a YEAR and resolveCompanionReturnChip, Contributi's ONE answer (summarizeCapitalEntered; a migration baseline is never a purchase), the heatmap read by keyboard and tap, the residual guard (RESIDUAL_ALERT_SHARE), EUR benchmarks, drawdown, IRR signs, the verdict-over-tiles rules, the heatmap — in doc/guide/rendimenti.md.

Allocazione → doc/guide/allocazione.md

• Asset.allocationRole is ONE field, THREE values: tradable (default), frozen (in the denominator, never in the plans), excluded (out of the page entirely); no role is ever inferred at read time — save a LOAN's, which is DERIVED from the asset it finances (resolveAllocationRoleWithin, 2026-10-17; a personal loan is in the base) so every class and group sums NET of its debts, a class below zero declared, never clamped. THE RULE: partition upstream of compareAllocations, never downstream (filtering the output breaks targetValue = target% × totalValue and the Σ(current − target) = 0 invariant), and do NOT push the filter into calculateCurrentAllocation (it also serves /api/portfolio/snapshot).
• Every euro lands in a bucket: the subcategory is OPTIONAL (NO_SUBCATEGORY_LABEL), the orphaned target is the trap (findOrphanedTargets/stripOrphanedSubTargets), and ASSET_CLASS_SEQUENCE is the ONE enumeration of the union — a hand-listed class drops its EUROS, not just its label.
• "Versa" and "Preleva" are ONE tree with the sign flipped, and Ribilancia descends to the INSTRUMENT through those same splits (RebalanceDescent, 2026-09-21) — never a second algorithm. «Prelevare 1000 €» means 1000 € IN HAND: solveWithdrawalGross is a FIXED POINT, never a division by (1 − rate), and a plan that sells prices the withholding (estimatePlanSaleTax), null WITH a reason when a leg has no EUR basis or rate.
• Esposizione (2026-09-28): the engine runs in the BROWSER on the page's assets; the route answers only Yahoo's profiles from ONE cache per ticker, owner-scoped (assertCanAccessAccount), and nothing of the user's goes in a profile. Every euro of the Allocazione base has ONE of four destinies and the list adds up to 100 on screen.
• Il resto — the mobile composition (§ Composizione mobile), THE ASYMMETRY of the two plans and the band-independent score, the dormant class (isDormantClass, activeClassGaps and never the raw summarizeClassGaps), collapseRepeatedLevels and the node's own isInstrument, the leverage engine and its tree, what Titoli, Settori and Emittenti weigh (hasMarketPrice + a ticker), the per-ticker cache and Yahoo's two modules, the Bull's formula, the six label maps, the action colours' measured lightness band and the lab() trap that made th

Truncated - read the full file at https://github.com/GiuseppeDM98/net-worth-tracker/blob/9a4eb8a591c1f1a3c68e573b35e33c33a08dad6d/AGENTS.md.