S&T Card Manager — Functional Reference

1System Overview

S&T Card Manager is a single-page application that runs a sports-card trading business end to end: intake (scan, importers, manual entry), inventory (the Ledger and the Collection gallery), sale (single, lot, and marketplace-file reconciliation), and accounting (a cards-only executive layer and a full non-card general ledger with a partner capital waterfall).

1.1Stack and deployment

Client

React + Vite, a PWA. Tailwind utility classes throughout; no component library.

Charts

Recharts, always inside <ResponsiveContainer> with a fixed pixel height.

Virtualization

@tanstack/react-virtual — useVirtualizer in the Ledger grid, useWindowVirtualizer in Collection.

Spreadsheets

SheetJS (XLSX) for every CSV/XLSX read and for the Accounting Excel export.

Backend

Supabase — Postgres (with generated columns and RLS), Auth, and Storage.

Storage buckets

card-photos (permanent card images) and scan-uploads (transient scan intake).

Server functions

Six Vercel serverless routes in /api, colocated with the Vite app.

External services

PSA public API (cert attributes + images), Ximilar collectibles/v2/sport_id (card identification), Anthropic claude-sonnet-4-6 (two routes).

Hosting

Vercel, production at bkcards71.vercel.app. Static help pages are served from /help/.

1.2Top-level navigation

The TABS array in App.jsx is the authority. Three of the five tab keys no longer match their labels; anyone reading code or writing tests must key on the label, never the key.

The Admin Console and Help & Support are not tabs — they are full-screen overlays reached from the header (gear and ? respectively).

1.3Role model and the three gate functions

Five roles, three predicates, all exported from App.jsx and all null-safe (an unloaded partner fails closed):

export const MANAGER_ROLES = ['company', 'partner', 'admin']
export const canManage     = (p) => !!p && MANAGER_ROLES.includes(p.role)
export const canEdit       = (p) => !!p && [...MANAGER_ROLES, 'user'].includes(p.role)
export const canSeeFinance = (p) =>
  !!p && (MANAGER_ROLES.includes(p.role) || p.can_access_finance === true)

Note the strict comparison in canSeeFinance: a null can_access_finance reads as false. The Users admin forces the flag to true whenever a manager role is assigned, so the two halves of the predicate can never contradict for a manager.

1.4Where each gate is enforced — and where the real boundary is

1.5Boot sequence and account lifecycle

App() resolves four mutually exclusive screens, in order:

1. Loading gate — while supabase.auth.getSession() is in flight, a single pulsing Loading….
2. Recovery / invite gate — if the URL hash matches /type=(recovery|invite)/ and Supabase has minted a temporary session, <SetPasswordScreen> renders and nothing else.
3. Unauthenticated gate — no session → <Login>.
4. Authenticated app — <SignedInApp>, a deliberately separate inner component so that useCards() mounts only after login and never while the Login screen is showing.

Password rules (all four must pass, rendered as a live checklist): at least 8 characters, one uppercase, one lowercase, one number. There is no symbol requirement and no maximum length. On success the token is stripped from the URL with history.replaceState so a refresh does not re-trigger the screen.

Account status ladder

Promotion to active happens as a side effect of the partner fetch: reaching that code proves the app loaded. last_sign_in_at is stamped on every load; invite_accepted_at is stamped on the invited → active jump.

1.6Data-loading architecture

useCards() is called exactly once, in SignedInApp, and its results are passed down to every view. Switching tabs never re-fetches. It pages the whole cards table 1,000 rows at a time with a single CARD_SELECT projection carrying 14 embedded lookup joins; at ~1,973 rows that is two round-trips.

Three surgical mutators avoid full reloads: refreshCard(id) (single-row re-fetch, swapped in place), refreshNewCard(id) (re-fetch, append and re-sort by id after an insert), and removeCardLocal(id) (pure client-side filter after a hard delete). reload() is exposed so surfaces outside the Ledger — notably Admin Console → Bulk Edit — can re-sync the whole app. A separate head-only exact count of non-archived cards feeds the Ledger's data-integrity badge.

Scan is the exception: it receives neither the cards array nor loading state and queries scan_candidates itself. The Admin Console's Integrity and Bulk Edit panes also run their own paged reads, because they need populations (soft-deleted rows, archived rows) that the shared array deliberately excludes or includes differently.

2Data Model

Everything below is inferred from the projections the app actually reads and the patches it actually writes. Column families are grouped the way the UI groups them, because the grid, the editor and the CSV exporter all share one group vocabulary.

2.1cards — field families

The canonical projection is CARD_SELECT in useCards.js, reused verbatim by the full-database CSV export, by every importer's "open the card" path, and by Scan's bring-into-app re-select. The nine groups below are the same nine that drive the Ledger's header band, the editor's field groups, and the export column picker.

2.2Generated / computed columns

Five columns are computed by Postgres and rendered read-only everywhere (as <span>s suffixed (calc), with no input element to focus). The Card Editor mirrors each formula locally so the numbers move as you type; the stored value is always the DB's.

total_cost        = base_cost + tax + shipping + handling + grade_fee     (blanks count as 0)
proj_profit_asis  = comp_as_is   − total_cost      (blank driver → blank, not 0)
proj_profit_10    = exp_sale_10  − total_cost
proj_profit_sale  = asking_price − total_cost
net_return        = sold_price + shipping_margin − total_cost
    where shipping_margin = shipping_collected − (label_cost ?? shipping_collected)
    i.e. a null label cost means shipping washes to zero margin

year_sold is not a generated column but is derived by every sale flow in JS as Number(date_sold.slice(0,4)) — Mark Sold, Bulk Sale, the eBay and CollX importers, and the Generic CSV importer all do this. It remains hand-editable in the Card Editor's Sale group, which is how the two can be made to disagree (§8 D-27).

2.3Lookup tables

Every lookup shares the shape id, label, active, sort_order. Nine of them are managed from Admin Console → Dropdowns; the rest are managed elsewhere or deliberately not managed at all.

Disposition ids that appear as literals in code

2.4Join and satellite tables

2.5The fin_* tables

useFinancials() fires nine parallel queries in one Promise.all and surfaces the first error found across all nine.

fin_entries columns that carry behaviour

Three of the seven joins in ENTRY_SELECT point at the same table and must be disambiguated by FK constraint name — renaming any of them in Postgres breaks the query:

category:      fin_categories(id, name, is_capex, is_capital_contribution, default_counts_in_books)
vendor:        fin_vendors(id, name)
contributor:   fin_contributors!fin_entries_contributor_id_fkey(id, name)
frequency:     fin_frequencies(id, name, months_interval)
pay_method:    fin_pay_methods(id, name)
reimbursed_to: fin_contributors!fin_entries_reimbursed_to_id_fkey(id, name)
owner:         fin_contributors!fin_entries_owner_contributor_id_fkey(id, name)

2.6partners and identity

Columns the app reads: id (smallint), name, display_name (NOT NULL), first_name, last_name, email, role, can_access_finance, auth_user_id, account_status, invited_at, invited_by, invite_sent_at, invite_accepted_at, last_sign_in_at.

Names are written in lockstep. Editing a name anywhere (Users tab or My Profile) writes first_name, last_name, name and display_name together, because "names drive Owned By / Paid By across the app". The partner accounting engine resolves names by case-insensitive prefix — kevin* → Kevin, brian* → Brian, bk* → BKCards71 — and anything that does not match one of the three is silently dropped from every accumulator (D-38).

3Component Reference

One section per surface. UI strings are quoted from source, including the literal typographic characters (…, —, ▾, ↻, ✕) a tester has to match.

3.1App shell and the integrity badge

The header

Sticky (top-0 z-40) so the tabs, the identity and Sign Out stay on screen while a view scrolls. Left to right: the two-line wordmark (S&T Card Manager / CARD MANAGER), the folder-tab nav, then a right cluster of — in DOM order — the integrity badge, the ? help button, the gear, the partner name, the role chip, and Sign Out. The role chip renders the raw role string, so a user literally sees company, partner, admin, user or viewer in lowercase monospace. Sign Out has no confirmation — the auth state change drops straight back to the login screen.

Tabs sit on one baseline with deliberately no vertical hop on selection. The active tab merges its bottom edge into the page (-mb-px bg-slate-950, killing the header's bottom line beneath it) and grows a 3px accent bar across its top. A disabled code path exists (Coming soon + a lowercase soon micro-label) but no tab currently uses it.

The ? button is visible to every role, unconditionally — "'?' is the ONE entrance; the gear no longer carries it." The gear opens a fully working Admin Console but is still labelled Settings (coming soon) (D-01).

The integrity badge — the header's health light

The four silhouettes are deliberately distinct "so the state reads at a glance even in grayscale". The tooltip lists each non-zero part as {n} × {label}. Clicking the badge runs setAdminSection('integrity') then opens the console — "the gear means 'settings', so it opens where it always did; the integrity badge means 'show me the problem', so it deep-links to Integrity instead of making you hunt for the tab." Closing the console increments pulseKey, which re-runs the check, "since that's where the fixes happen". Full definitions of the checks are in §7.

Deep links the shell owns

• Badge → Integrity — initialSection='integrity', validated inside the console against the caller's visible tabs so a non-manager can never be dropped onto a manager pane.
• Admin Bulk Edit → single card — handleEditCard(id) closes the console, switches to the Ledger tab, and sets pendingCardId. The Ledger receives it as openCardId, opens the card, then calls onOpenCardConsumed() so it does not reopen on the next render.

3.2Ledger — the inventory grid

Inventory.jsx, ~3,170 lines. The working surface: 64 columns, 9 group bands, 57 filter funnels, saved views, a KPI band, virtualization, two CSV exporters, and the launch point for the Card Editor and Bulk Sale.

Classification predicates (module-scope, pure)

Columns

64 columns across nine groups. The header band is computed by bandCells, which walks the visible columns in render order and coalesces adjacent columns sharing both the same group and the same freeze segment — which is what makes the band split correctly at the freeze boundary.

Flag tallies: 2 frozen, 2 locked, 56 filterable, 19 numeric (all also filterable), 4 signed red/green money, 24 mono, 15 right-aligned. DEFAULT_VIEW shows 34 of the 64; the 30 hidden ones are the CDP/intake attributes and the less-used cost and sale detail columns.

Saved views

config = { columns: visibleKeys, widths: the full 64-key map, sort }. Filters, search text, the sport chip, the status facet, the photo funnel and showArchived are not saved — a "Sales only" view still needs its filters re-applied by hand (D-22).

applyConfig validates every saved key against ALL_KEYS (silently dropping keys from renamed columns), re-injects the two locked columns even if the config omitted them, re-orders the whole set into canonical COLUMNS order, merges widths over the defaults, and adds every explicitly-saved width to the manualWidths ref so content auto-sizing will never override user intent. The default view auto-loads exactly once per mount (didAutoLoad ref) so a later refresh cannot stomp an in-session layout.

saveCurrentView matches existing names case-insensitively and updates in place, so a re-save cannot create a duplicate. setDefaultView always clears all of the partner's defaults first, backing the one-default-per-partner index client-side too.

Filters — the pipeline

cards
 → gridBase    archive scope
 → searched    global text search (7 fields)
 → filtered    status facet → card-type chip → photo funnel → checklists → numeric ranges
 → visible     sort
 → virtualRows windowing

Funnel popovers render at the document root with position:fixed so they escape the grid's overflow-auto, anchored at the header cell and horizontally clamped to [8, innerWidth − 232] so they never clip off-screen. Clear all filters is scoped to filters only — columns, widths, sort and the active saved view are deliberately left alone.

The KPI band

The Years Sold toggles: All is a reset, not a toggle; from the All state clicking a year narrows to just that year; deselecting the last remaining year falls back to all years, so an empty KPI band is unreachable. When more than one year is shown, the first three tiles grow a per-year sub-line.

The filtered rollup callout reads You have {money} across {n} cards and its dollar figure is facet-aware: sale proceeds under Sold, cost basis under For Sale or Not For Sale, and held cost basis (invDollars + nfsDollars) otherwise — so "You have $X" always means the right thing.

Grid mechanics

• Sorting — click the header label. Nulls always sink last, in both directions. No secondary tiebreak; equal values rely on Array.prototype.sort stability.
• Resizing — a 1.5px drag handle on every header's right edge; double-click resets that one column to content width. Dragging adds the key to a manualWidths ref that auto-sizing will never touch again.
• Auto-sizing — one pass per mount (didAutoSize ref, inside a requestAnimationFrame after the first non-empty cards array), measuring the visible string through a shared canvas 2D context, clamped to [60, 420] px so one long value cannot blow out a column.
• Frozen columns — only id and description. Frozen cells paint an opaque background (bg-slate-950, or bg-emerald-950 when bulk-selected), which is exactly why the grid is deliberately zebra-free: scrolling columns must disappear cleanly behind them.
• Virtualization — useVirtualizer over the already-filtered, already-sorted array, estimateSize 33px, overscan 12. Height is preserved by two aria-hidden spacer <tr>s rather than a transform, which keeps <table>, <colgroup>, sticky headers and frozen columns intact. A third always-on 24px spacer row keeps the horizontal scrollbar off the last data row.

Footer data-integrity badge

{✓|✕} Data integrity · {N} live. Green only when the server's head-count is known and strictly equals the number of rows the client loaded; red otherwise, including when the count could not be verified. It fails closed.

CSV export — two scopes

Cell rules: numeric columns export a raw spreadsheet number, never "$1,234.00"; Net Return mirrors the grid's sold-only guardrail; everything else prefers the full untruncated title text. Fields are RFC-4180 escaped. Column order is re-derived from COLUMNS regardless of tick order. Every export always appends two extra columns, Front Photo URL and Back Photo URL, so a file handed to CDP or a marketplace never loses the image links. Filename: bkcards71_{view|fulldb}_{n}rows{_hasphoto|_nophoto}_{YYYY-MM-DD}.csv.

Row interactions

• Hover thumbnail on the ID cell — 200×280, position:fixed, pointer-events-none, flips to the left of the cell when it would overflow and clamps vertically. Source is photo_url, falling back to an inline data: SVG placeholder that never makes a network request.
• Click the description → the shared <CardEditor>, keyed on the card id, wired so that onSaved/onInserted/onDeleted re-tally the grid, KPIs, chips and rollup live.
• + Add Card → the editor in insert mode with a For-Sale default.
• Select to Sell → select mode: row clicks toggle selection instead of opening the editor, hover preview and click-to-open are both disabled, and the ID column widens by 26px so the checkbox can never overlap Card Name. Selection is a Set of card ids resolved against the full cards array, so it survives filter, sort and virtualization changes.
• Recent Sales → a self-contained modal over the raw cards array (unaffected by every grid filter): all non-archived SOLD cards, local search, seven sortable columns with a descending-id tiebreak, a headline {n} sold · net {money} computed over all rows, and a hard cap of 400 displayed rows with a notice.

3.3Collection — the showcase gallery

Teal identity. An image-first gallery described in source as a "pure show-off surface; only 'insight' is the header stat line". It consumes the shared cards array — no separate fetch, no DB change — and derives rookie and autograph status in-app from the description text.

Archived cards never appear — held is the base population for stats, dropdowns and the grid alike, and there is no archived view.

Controls

A sticky region parked directly under the 56px app header, in three rows: a grid/list segmented toggle plus search; a horizontally scrollable filter rail; and a result count. The rail, in exact order: Sort · divider · For Sale / Not For Sale / Sold pills · divider · Price · divider · Graded / Rookie / Autographed pills · divider · Category · Year · × Clear.

Nine sort options (default Newest added = descending id); numeric sorts push nulls to the end regardless of direction. Five price buckets tested against the tile price (sold_price for sold cards, else asking_price); a null price is excluded by any bucket. Category and Year lists are built dynamically from the held population.

The three status pills are independent toggles unioned together, not a radio group. The default is the single-member set {FOR_SALE}, so Collection opens showing only for-sale cards; toggling all three off falls back to "everything held except Sold" rather than showing nothing. That default set is treated as "no filter" when deciding whether × Clear appears. Clearing resets search, price, status, the three tag toggles, category and year — but not the sort or the grid/list view.

Stat blocks

The asymmetry is intentional: unsold positions are valued at cost, sold ones at realised price.

Tiles

The image frame is deliberately narrower than the text column (78%) at a fixed 264px height, "so every image aligns on one baseline". Four corner overlays: a bare neon year badge top-left (colour taken from a fixed 10-colour palette indexed by year % 10, so every card of the same year wears the same colour, with a text-shadow so it stays readable over any image); a SOLD badge top-right; the grade badge bottom-left; and a show-location badge bottom-right.

The grade badge ladder: ≥10 emerald, ≥9 teal, ≥8 sky, ≥6 amber, <6 orange, grader-with-no-grade slate, and RAW when there is neither a usable grader label nor a numeric grade. A grader labelled NONE is treated as no grader. The Graded filter pill is implemented as "the badge is not RAW".

Rookie and autograph are regex heuristics over the lowercased description (/\brc\b/, /\(rc\)/, /\br\s c\b/, /\brookie\b/; and /\bauto/ as a prefix match). They are only as good as the description.

Virtualization and the detail modal

useWindowVirtualizer against the window (Collection scrolls the page; the controls are sticky, not a separate scroll box), with scrollMargin taken from the list container's offset. Column count mirrors the Tailwind breakpoints (4 / 3 / 2) and listens to resize. Grid rows estimate 380px with overscan 6; list rows 80px. The body component is memoised so it re-renders only when the result list or the view mode actually change — not when a dropdown opens.

The detail modal opens front-first and every card flips, whether or not it has a back photo: a perspective:1200px container with a 0.55s rotateY transition, falling back to a second inline SVG placeholder reading No back photo yet available. The right half is a facts panel — a definition list where any null entry is dropped entirely — and the footer hint Edit details in the Ledger view. The modal is strictly read-only; there is no edit affordance anywhere in Collection, and it renders from the captured object so it does not live-update if the underlying card changes.

3.4Financials — the executive dashboard

Violet identity. Insights.jsx, ~975 lines. Everything is computed live in useMemo from the shared cards array; nothing is fetched separately and nothing is stored. Page H1 is Executive Dashboard.

Populations

isSold(c)       → !archived && year_sold != null        // narrower than useWaterfall's
inInventory(c)  → not archived, not sold, not NOT_FOR_SALE, and
                  disposition ? disposition.is_inventory === true : true

live  = cards.filter(!isArchived)
sold  = live.filter(isSold)          // the realised book
inv   = live.filter(inInventory)     // for-sale inventory; EXCLUDES Not-For-Sale
soldF = sold narrowed by the Sales-year pill

The Sales year pill — scope semantics

KPI band — eight tiles

The seven sections

Data Quality flags and how they feed back

The AI analyst layer

Two mechanisms, one transport. CFO Board Briefing is a whole-dashboard panel under the header (Brief the board ↗ → Preparing… → Regenerate ↻) that sends 19 named metrics plus a verbatim scope instruction. Per-section Analyst panels (Ask the analyst ↗ → Thinking…) appear on six of the seven sections. Both POST {scope, metrics} to /api/analyst, which holds the key and the CFO persona server-side. See §5 for the prompt's scope fence.

Footer, verbatim: Card-trading performance · computed live from {live} live cards · {sold} sold · {inv} in inventory. Those three counts are the fastest sanity check on the tab and should tie to the Ledger's own footer.

3.5Accounting — ledger, statements, waterfall

Emerald identity. Finances.jsx, ~2,346 lines. Two sub-views under one control cluster, and a nine-sheet Excel export.

The control cluster

Sticky at top-14: an H2 still reading Finances, the eyebrow Business books · non-card, + Add Entry (Ledger sub-view only), the year toggle, the sub-view switch, and Export to Excel (Statements only, and only once Statements has handed its export closure up).

Scope helpers that govern everything

parseYMD(s)   // splits 'YYYY-MM-DD' by hand into {y, m: m-1, d}

occurrencesInScope(entry, yearKey) walks up to 1,200 steps from the start month by months_interval, using integer arithmetic only, and stops past end_date or once it reaches the current month. The in-progress month is not counted until it ends — a monthly bill started in January, viewed in mid-August, counts 7, not 8. Full algorithm at §4.9.

Sub-view 1 — Ledger

A sticky five-stat SummaryBand computed over the currently filtered rows, so it responds live to the column funnels: Operating Exp, Capital Equip, Write-Off, Owner Capital, Personal (excl.), and a right-aligned Total · in books.

Nine columns (Date · Title · Category · Vendor · Paid By · Unit Cost · Freq · Reimb · Total). A recurring row shows {frequency} ×{occ} in the Freq cell and amount × occ in Total — the "caret-expand to a generated schedule" concept is realised as an inline multiplier; there is no expandable schedule list in this build. Prior-year / this-year / all-time totals come from flipping the year toggle.

Column filters use an explicit convention worth reproducing: the Set holds the CHECKED (= shown) values; an undefined Set, an empty Set, or a Set containing everything all mean "unfiltered". On Apply, a fully-checked list is deliberately stored as an empty Set. The funnel draws active only when 0 < size < values.length.

Clicking any row opens the EntryPanel drawer — the whole row is the button; there is no separate edit affordance. Validation, first failure wins: Title is required. → Category is required. → Frequency is required. → Recurring entries need a start date. Save normalisation forces start_date/end_date to null when the entry is not recurring, and owner_contributor_id to null unless the scope is personal. There is no delete for ledger entries anywhere in the file — only distributions can be deleted from the UI.

Managed dropdowns (ManagedSelect)

One component drives all five lookup tables, each with an inline + add. The dedupe is two-stage: an exact case-insensitive match silently selects the existing row; a whitespace-insensitive near match refuses the first time and shows Did you mean "{existing}"? Click Add again to create new. — clicking Add a second time proceeds.

The reimbursement lifecycle

Checkbox Reimbursable → select Reimbursed? with exactly three options (Not yet (owed) / Partial / Fully reimbursed) → three more fields when the state is not none. It reaches the books as:

if (e.reimbursable && who && nonCardOpexPaid[who] !== undefined)
  nonCardOpexPaid[who] += Math.max(0, amt − num(e.reimbursed_amount))

• The outstanding balance is amount-driven, not state-driven. Marking an entry Fully reimbursed while leaving the amount at 0 leaves the full amount showing as owed.
• Math.max(0, …) means over-reimbursement never becomes a debt back to the company — it clamps and the excess is invisible.
• Any reimbursable category counts, not just Operating Expense.
• For a recurring reimbursable, amt is multiplied by the occurrence count but reimbursed_amount is not — recurring reimbursables are effectively unsupported (D-34).

Sub-view 2 — Statements, in render order

Excel export

BKCards71_Accounting_{All-Years|YYYY}.xlsx, nine sheets: P&L Summary, Tax Schedule, Partner Positions, Out-of-Pocket, Partner Tax, Capital Waterfall, Non-Card Ledger, Distributions, Profit Gifts. Every number passes through Number(Number(v||0).toFixed(2)). The export closure is re-registered on every change of scope, so the button always exports what is on screen.

3.6Scan — the intake pipeline

Sky identity. Heading AI Scan. Two sub-tabs: Scan (the intake flow) and Value (a placeholder card stating that per-grade market value comes from SportsCardsPro and is a later phase, deliberately kept separate from detection).

Intake path A — Add by PSA cert #

Paste one or many certs, separated by anything (the parser splits on [^0-9]+, de-duplicates, and drops empties). The pipeline: POST /api/psa {action:'lookup'} → duplicate guard (any cert already in cards is skipped) → build a proposed object per result marked {identified:true, graded:true, source:'psa'} → insert one scan_candidates row for the front (seq = idx*2) and, when PSA returned one, a second for the back (seq = idx*2+1), sharing a group_id. The report line is assembled conditionally, each clause appearing only when its counter is non-zero: Added {n} card(s) from PSA · {n} already in the app · {n} had no PSA image · {n} not found.

Intake path B — photo upload

Two modes: Front + back pairs (default — photos pair in order, 1st = front, 2nd = back) and Fronts only. Drag-and-drop, multi-select, or a folder picker (the webkitdirectory attribute is applied in an effect, since React will not set it declaratively).

Files are filtered to images, then sorted by name with numeric collation (localeCompare(…, {numeric:true, sensitivity:'base'})) so img2 sorts before img10 — that is what makes "processed in filename order" trustworthy for a folder drop. One batchId is minted for the whole drop; each file is uploaded to scan-uploads/{partnerId}/{batchId}/{0000-index}_{safeName}. Per-file failures are caught individually and the loop continues — one bad file does not abort the batch.

Review and bring-in

Candidates are bucketed by group_id, fronts first, groups newest-first — one group is one future card. The toolbar's Select all excludes groups where every item is already accepted, so brought-in cards cannot be re-selected. Status pills: pending slate, scanning sky and pulsing, scanned emerald, error red, accepted violet.

The review panel seeds an editable object from the front row's proposal, resolving the grader text to a lookup id via a two-stage match (exact case-insensitive label, then a loose substring match in either direction). Twelve editable fields, three checkboxes, an alternatives list (up to 6 from Ximilar; picking one overwrites the identity fields and rebuilds the name, preserving the current parallel), a raw-JSON disclosure, and a ↻ button that rebuilds the name from the fields. The primary button is disabled when the name is blank, with an inline amber warning saying so.

Card creation and the durability chain

buildInsertPatch lands every brought-in card as For Sale (sale_status:'NOT_SOLD', disposition_id: 12) with all five money fields zeroed, intake_source:'scan', and description set to the canonical name — at intake the name field and the card description are the same thing. Photos are deliberately not set in the insert.

PSA CDN or scan-uploads bucket
   → POST /api/photos { action:'attach' }      (server-side download)
   → re-upload into card-photos at cards/{id}.{ext} / cards/{id}-back.{ext}
   → cache-busted public URL written to photo_url / photo_back_url

Permissions

Scan.jsx does not import canManage; it re-implements the manager array inline (D-04).

3.7Card Editor — the one detail panel

CardEditor.jsx, ~1,903 lines. Described in its own header as "the ONE card detail/edit panel", lifted out of Inventory.jsx specifically so every entry point opens the same component. Current callers: the Ledger (description click, and Add Card), Admin Console Bulk Edit (amber description click), the Integrity drill-downs, and Scan (after a bring-in, to finish the card).

The colour language

Field groups

Nine groups mirroring the Ledger's bands, plus two group headers (Names, Notes) that have no GROUP_META colour and therefore render an invisible dot (D-28). Money fields render a fixed $ inside the input frame, absolutely positioned and pointer-events-none — it is chrome, never part of what you type.

Notable controls: Grade is the 19-step ladder (1 → 10 by 0.5) as a <select> with a leading blank — there is no free-text grade entry anywhere in the app. Grade Qualifier is a combo (<input list> + <datalist>) offering the six official PSA letter codes (MC, MK, OC, OF, PD, ST) plus Pristine, Black Label and Gold Label, while always allowing free text. Listed On is the one field that is not a card column — see below.

Listed On — the join-table field

A card can be listed on any set of marketplaces at once, so this lives in card_listings and outside editForm, in its own Set of platform ids. A row labelled none is filtered out of the options: unchecking everything is how you say "not listed." An empty lookup shows No platforms defined. On save, syncListings diffs against what was saved and issues one delete plus one insert, wrapped so a listings failure never fails the card save. The dirty check includes the listings set, so toggling a platform alone triggers the discard-changes confirm.

Card Name, provenance and the name engine

A dedicated bordered card above the photos: the provenance chip (PSA/SGC when the grader is authoritative, else the session's nameMode, else the stored name_source, else legacy), Generate from attributes, Use intake (only when an intake title exists), the intake line, and a lazily-loaded ▸ Name history disclosure over card_title_events.

Auto-follow. The ten name drivers are card_year, brand_id, set_name, subset, parallel, player, card_number, print_run, grader_id, grade. Editing any driver rebuilds the Card Name live only when the name is currently an unlocked canonical name. A hand-typed (locked) name or a PSA/SGC-authoritative name is never silently rewritten. Editing the Card Name by hand sets nameMode='user' and locks it.

The Status dropdown and its stale-state guard

Five options: For Sale, Not For Sale, Sold, Gifted (free — write-off), Write Off… (lost / destroyed). The last two are pseudo-statuses that resolve to a $0 sale with a Loss disposition.

The For-Sale ↔ Not-For-Sale flip is a single confirm and always resets disposition_id to 12 or 13. Leaving SOLD is never a plain confirm — it always opens the un-sell chooser. A write-off from a sold card is refused outright: "This card is Sold — its exit is already booked. Un-sell it first if the sale was wrong."

Mark Sold

Prefills from the live re-read row. Six fields; validation runs in a fixed order and the first failure wins. Net Sale is auto-filled from the fee engine (§4.8) and locked for platforms that carry fee data — tooltip "Computed from the platform fee — not editable", with a live label suffix showing the maths, e.g. (−12.35% − $0.40) or (−8% tier). Editing Total or Platform re-runs the estimate.

Confirm Sale writes ten columns including year_sold derived in JS from the date, and sold_price = net_proceeds. It then logs a sold event, re-reads the row, fires onSaved, and closes with Marked sold ✓.

The sale-time profit gift prompt

Fires immediately after a successful sale when all three hold: the owner is known, the owner is not BKCards71, and profit is strictly positive. Offers a gift amount with 25% / 50% / All quick-fills, capped at the card's profit. Saving resolves the owner to a fin_contributors row (exact case-insensitive full name first, else first-token match) and refuses helpfully on 0 or 2+ matches. Upserts fin_profit_gifts on conflict card_id.

Gift the card, and Write off

Both book a $0 sale: sale_status='SOLD', gross/net/sold all zero, a Loss disposition, and year_sold derived from the chosen date, so the card's full cost writes off as a loss in that year. Gift explains "Gifts are always free — if money changed hands, it's a sale." Write-off offers four radio stories (Lost 6, Forgery 7, Ripped Off 8, Destroyed 16) and points at the alternative: "Just damaged but still in hand? Cancel and tick the Damaged box instead — no money moves until it actually leaves."

The un-sell chooser — four stories

Any move off SOLD opens Un-sell card, which first restates what is on file: "Recorded sale: $X net on YYYY-MM-DD. What actually happened?"

SALE_CLEAR nulls twelve columns. Before wiping, saleSnapshot() captures every one of them, and the snapshot goes into both the audit row's detail.cleared and the journey event's — "The card's columns are about to lose these numbers; the timeline is where they survive."

Photos

Add mode shows a dashed placeholder: "Save the card first, then click here to add a photo." — a photo cannot be attached before the card exists. Otherwise two 190×266 tiles, Front and Back, uploading to card-photos/cards/{id}.{ext} and cards/{id}-back.{ext} with upsert:true and a ?v={timestamp} cache-buster. Remove confirms and then nulls the column only — the storage object is not deleted. The file input is reset in a finally so the same file can be picked twice in a row.

Save, Update, Archive, Delete

Add mode's only guard is Description is required to add a card. On insert it applies For-Sale defaults, coerces all five cost inputs from null to 0, lets the database mint the id, logs a purchased event whose gross is the sum of the cost inputs the user typed (because total_cost has not round-tripped yet), then switches out of add mode in place so a photo can be attached immediately.

Two eBay helpers

The What-If sandbox (sky-bordered, bottom of the panel) is the only place in the editor with hardcoded default rates (12.35%, $0.40, $6 shipping, 6% tax). It computes fee = feePct% × (price + shipping + tax) + perOrder and shows the projected net profit against the live total cost. Explicitly a scratchpad — no write path touches it.

The shipping-collected correction: editing eBay Shipping Collected on an eBay-family platform recomputes Net Sale as stored_net + (fee_pct/100) × (stored_shipping_collected − new_value). Both baselines come from the stored card, not the form, so the result is stable across keystrokes rather than compounding. The rate comes from sold_platforms, falling back to 12.35.

3.8Card Journey — the per-card timeline

Opened from the 🕘 History button in the editor header (never in add mode). A centred modal over card_events.

Sort model — three server-side keys: sort_hint ascending (the lifecycle position, stamped at write time), then occurred_on ascending with nulls last, then id as a deterministic tiebreak. Events with no date render date unknown in italics rather than sorting to the top.

21 rendered event types (§9.1); an unrecognised type degrades gracefully to a bullet, the raw type string, and neutral styling. Four types form the strike-through set — sale_reversed, returned_refunded, order_canceled, reintake_kept_paid — whose money renders struck through because it was recorded and then reversed. sale_corrected is deliberately not in that set: its amount is the money that stands.

Each entry shows the title and platform label, the date, a money line (cost $X in amber for purchased, gross $X for everything else; net $X in emerald; cost_delta in rose, labelled fee $X for sent_to_grading), an attribution line, an italic note, and a provenance badge — reconstructed from card record for source='seed', added by hand for 'manual'. App and bulk sources carry no badge.

Hand entry

+ Add event opens an inline form headed by the amber warning "⚠ Events can't be edited or deleted afterwards — check before you add." The offered type list is deliberately a subset: notes, physical facts (Found, Lost, Loaned out, At a show, Damaged), grading and listing milestones, and five explicitly historical money types (Sold — historical, Returned & refunded — historical, Order canceled & refunded — historical, Sale corrected — historical, Sale struck — historical).

What is absent matters: purchased, live sold, gifted, written_off, archived, restored and reintake_kept_paid can only ever be written by the flow that actually performs the action. Hand-entered rows carry source:'manual' and the same net-integrity validation the editor enforces. Footer, always visible: "History is a record, not a calculation — the card's own fields remain the source of truth for all money."

3.9Bulk Edit — picker and apply modal

Lives in the Admin Console. Loads all non-archived cards client-side, paged 1,000 at a time. Intro, verbatim: "Filter and select cards, then Edit selected to change one or more fields across all of them at once. … Archived cards are excluded. Derived values (total cost, net return, years, projected profits) are never bulk-editable - only their source inputs. SKU, Status, Sale Type and Mark-Sold are edited per-card in the editor."

Search matches id, SKU, description or player. Eight multi-select facets (Status, Card Type, Item Type, Brand, Grader, Location, Owner, Card Year), each with Select all / Clear and live per-value counts; blanks group under (blank) and sort last. Facets AND across keys, OR within a key. Nine sortable columns, blanks always sinking last, ties broken on id. The header checkbox selects everything in the current filter, and selection survives filter changes.

The bulk-edit modal — 8 groups, 31 fields

Every row is a checkbox + label + a control that stays disabled and grey until the field is ticked. Subtitle: "Tick the fields to change. Untouched fields are left alone. Blank = clear the value." Lookup selects load only rows where active !== false.

Not bulk-editable by design: description (use Generate names), sku, sale_status, disposition_id, every sale field, archived, damaged/damage_note, cert_number, the listings join, photos, and all five calculated columns. Sales are made one card at a time in the editor, or as a lot in Bulk Sale.

The three-layer safety model

Apply writes one update(patch).in('id', chunk) per 500 ids, patching only the ticked columns — so the database recomputes total_cost, net_return, year_sold and the projections itself. A best-effort user_audit row records fields, values, count, cleared columns, cost fields touched, the sold-card count and every id. The modal cannot be dismissed while saving.

Generate names (bulk)

Rebuilds the canonical Card Name from each selected card's attributes. Skips every card with name_locked = true — PSA/SGC-authoritative names and hand-typed overrides are never clobbered — and drops cards whose attributes produce an empty string. The confirm names both counts explicitly. Writes in batches of 40 with name_source:'canonical', name_locked:false, plus one card_title_events row per card and a bulk_generate_names audit row, both best-effort.

3.10Bulk Sale — one order, one fee, penny-exact

Launched from the Ledger's select mode. Sell a set of cards as one order on one platform: you type the single total you actually received, the app splits it across the cards proportionally by asking price to the penny, runs the order through the fee engine for net, and books every card sold.

The asking-price guard

Any card whose effective asking price is ≤ 0 blocks the whole sale. An amber panel lists every blocking card with an inline price box, and the entire order form is dimmed and non-interactive until they are priced — "the split is weighted by asking price, so every card needs one." A typed override counts; the stored value is the fallback.

The fee engine applies to the order, not the card

netForOrder uses the same tier-then-flat rules as the Card Editor (§4.8) but against the order total, because one order incurs one fee. This differs meaningfully from selling the same cards individually: a per-order flat fee is charged once for the lot, and a tiered platform brackets on the lot total rather than on each card.

grossᵢ = allocate(orderGross, askingWeights)[i]
feeᵢ   = allocate(orderFee,   askingWeights)[i]
netᵢ   = clamp(round(grossᵢ − feeᵢ, 2), 0, grossᵢ)

The clamp enforces the same net-integrity invariant as everywhere else. A preview table shows per-card asking / gross / net with a Totals footer proving the allocation lands exactly on the order totals. The allocation algorithm is at §4.5.

Commit

Book N sales enables only when every card is priced, a platform is chosen, a date is set, gross > 0, net is computed and ≥ 0, and nothing is in flight. A second guard refuses a negative net outright. After the confirm, in order: (1) persist captured asking prices, so the card's own record carries the price the split was based on; (2) one UPDATE per card writing the sale block with its allocated gross and net; (3) one sold journey event per card with source:'bulk', carrying that card's own share plus the order context and lot_card_ids.

Asymmetries with Mark Sold, worth knowing: a bulk sale writes no received_method_id (Proceeds To), offers no Trade sale type, and never raises the profit-gift prompt.

3.11Admin Console

A full-screen modal opened by the header gear (or deep-linked to Integrity by the badge). The title is role-dependent: managers see Admin Console / Configuration · users · data; everyone else sees My Account / Your profile.

Default landing tab: users for managers, profile otherwise. A deep-linked section is honoured only if that tab exists for the caller's role, and every render is double-gated. Help & Support deliberately does not live here — "one entrance, one home".

3.11.1 · Integrity — every check

One paged read-only fetch of all cards where deleted_at IS NULL, joined to graders, locations and dispositions; everything is then computed in the browser in a single useMemo. There is no server RPC and no SQL view.

Header blurb: "Standing data-quality checks, grouped by area. Archived cards are excluded. Click any count to see the exact cards, with a CSV download. {N} total flagged." Footer: "Scanned {n} live cards ({m} incl. archived)."

The 18 checks

The origin of the coherence checks: card #809 sat as NOT_SOLD carrying disposition 3 (Sold – Straight Sale) and a full sale block, because a stale edit form re-saved a sale that had just been reversed. Nothing flagged it; it was found by hand. Checks 2 and 3 exist so that shape can never hide again.

The drill-down modal

View {n} cards → opens a table (ID · Description · optional Fix column · Cert · SKU · Grade · Status · Cost · Sold $ · Sale Date) with four actions:

• Click an ID or description → re-fetches the row with the full CARD_SELECT and opens the shared Card Editor. Same guardrail as everywhere: "fetched full so a Save can't blank a field." On close it re-runs the checks and re-syncs the app's card array.
• Inline fix — only the seven checks in INTEGRITY_FIX. A single typed input plus Save (Enter also saves). On success it optimistically removes the row from the open list, then re-syncs and re-runs in the background.
• Multi-select → Edit selected → the shared bulk-edit modal, with the honest-unknowns counting described in §3.9 (these rows are exactly the partial projections that motivated it).
• Download CSV — eleven columns, filename derived from the check label.

3.11.2 · Users

Reads partners plus the 50 most recent audit rows. The Refresh button first POSTs syncStatus: Supabase stamps auth.users.confirmed_at when an invitee sets a password, and only the service key can read it, so the client asks the server to promote invited → accepted. Failure is swallowed; it still refreshes.

Row actions: Edit (inline names + role + finance radios), Resend (invited only), Reset pw, Suspend / Reactivate, Remove login, Delete. Every one confirms and every one audits. See §5.6 for the server-side guardrails, which are the ones that actually hold.

Footer note, verbatim: "Company, Partner and Admin always have Finance & Insights access, and their accounting identity is permanent — their login can be removed but the record stays so historical cards keep their owner and payer. Only User and Viewer accounts can be permanently deleted, and only when no cards reference them."

3.11.3 · Dropdowns

Nine lookup tables (§2.3), each id, label, active, sort_order.

• Add — free text; a case-insensitive duplicate is refused with "{existing}" already exists. New rows get sort_order = max + 10, so they land at the end with room to reorder later.
• Rename — in place; cards referencing the row by id are unaffected.
• Retire / Restore — flips active. Retired rows hide from future dropdowns and render struck-through behind a Show retired values checkbox.
• There is no delete path in this UI at all. Retiring is the only removal — that is the referential-integrity guardrail.

dispositions is deliberately excluded: "Disposition is managed separately because it drives accounting behaviour." sports is also absent, though it is bulk-editable elsewhere.

3.11.4 · Photo Import

Four parts. Everything routes through POST /api/photos, which holds the PSA token, downloads the third-party image, and uploads the bytes into the bucket — max 8 items per server call, so the client loops.

(a) Status header — four live head-only counts: With fronts · Missing fronts · Missing backs · PSA certs ready to try.

(b) Photo Coverage by Grader — computed entirely in the browser. Rows PSA / SGC / Other graded / Raw / TOTAL; columns Cards · Complete (F+B) · Front Only · Back Only · No Photos · Ready To Try. The buckets are mutually exclusive by construction: Complete + Front Only + Back Only + No Photos = Cards, and the caption says so. Every non-zero count is a drill-down with its own CSV. Ready To Try = PSA cards with a cert, no front photo, and no recorded PSA verdict yet.

(c) PSA Cert Photos — the backfill, sub-labelled "100 free PSA calls per day". A Calls this run input (1–100, default 90) loops psaBatch in chunks of ≤5 until the cap, a user Stop, a quota hit, or nothing left. Every log line is explicit, including cert {n} (card {id}): PSA has no front image — recorded, won't retry and STOPPED: PSA daily quota reached — run again tomorrow.

(d) CDP CSV Photos (by cert) — parses a CDP export in-browser, matches by cert (batched 200 at a time) and by base SKU (/^(BFL-[A-Z]*\d+)/, "because the random suffixes differ between systems, so both sides are normalized the same way"), with cert winning over SKU. Only the missing sides are sent; already-covered rows are counted as fully covered and skipped, and the server guards each side independently anyway.

(e) Raw Photo Matching — propose → review → approve, for cert-less cards. Rows with a cert are excluded on ingest ("they belong to the cert pipelines") and reported. Scoring is a Jaccard token-set similarity between normalised title and description, +0.05 for a matching year, +0.05 when the ledger player is contained in the CSV player, and an exact normalised match forced to 1.1. Tiers: EXACT · STRONG (≥0.80) · MAYBE (≥0.45) · NO_MATCH.

3.11.5 · Purchases

Reads up to 2,000 rows from purchases, newest first, joined to cards. Manual matching only — nothing here is automatic. A 4-way filter (all / unmatched / matched / converted), a search over item name, order number and seller, and a thumbnail that hover-pops a 288px card with the full order metadata.

• Match {n} to card → — a picker searching by description, SKU, and by numeric id when the query is all digits; picking one sets linked_card_id and match_status on all selected purchases at once.
• Turn {n} into Live Card(s) — already-converted rows are filtered out first. SKUs are allocated by scanning existing BFL-app-% SKUs and issuing BFL-app-{00000} sequentially. New cards take the item name, order date, base_cost = the order total with every other money field 0, the order number, the purchase image, and For-Sale defaults. The loop aborts on the first insert error, so a partial batch is possible and the message reports how many were actually created.

3.11.6 · Settings — platform fees

Intro, verbatim: "These rates drive every Mark-Sold estimate and the eBay importer — live, no deploy needed. Flat model: net = gross × (1 − fee%) − per-order fee. Platforms with tiers pick the bracket by sale price instead. Estimates are always trued up by the real payout."

A flat-model table over sold_platforms (retired platforms still appear, marked), where the Tiers cell reads {n} tier(s) — tiers govern; then one sub-table per tiered platform over platform_fee_tiers, plus an add-tier row. Every value must be a finite number ≥ 0; tier deletion confirms; every mutation writes a fees_update audit entry. The tiers table has no gap/overlap validation — adjacency is implied by ordering, not enforced (D-45).

3.12Data Import

DataImport.jsx is a shell around seven importers. It owns exactly three things: the mode toggle, the Tier-1 drop/detect layer, and the Generic CSV importer implemented inline. Only the active importer is mounted, which is why the hand-off store is kept per importer.

The eBay ordering is deliberate and documented: Purchases → Listings → Sales, the life-cycle order of a card, not alphabetical.

3.12.1 · Tier 1 auto-detect

Signatures, gates, the confidence model and the page rules are documented as an algorithm at §4.2. The screen-level behaviour:

• Drag overlay — a full-screen dashed-sky target reading Drop to identify · eBay · CollX · CDP · PSA — I'll read the header and open the right importer. Drag tracking uses a depth counter on window-level dragenter/dragleave so nested elements do not flicker the overlay. Listeners exist only while Data Import is mounted.
• Verdict cards are coloured by confidence — "so 'I'm sure' and 'I'm guessing' never look alike. Low means the gate matched but the importer will still refuse it." Each shows the filename, the label, the confidence, an amber books money badge where applicable, the destination and blurb, the literal reason (the matched header line, trimmed), and each warning.
• Hand-off happens only when all three hold: the whole drop resolves to one importer with zero unknowns, that importer is on HANDOFF_READY, and every item is high confidence. Otherwise the screen switches you there to look but never auto-loads.
• A mixed drop switches nothing and shows the breakdown: "guessing which half of a pile you meant is exactly the kind of 'helpful' that loses money."
• handoffs is merged, never replaced — because only the active importer is mounted, a new drop must not evict a file another importer is still holding. The panel says so: Files still held: ebaysales (1) · cdp (2) — each importer keeps its own until you press Clear.
• Every receiving importer routes the hand-off through the identical loadFile a manual pick uses — the comment repeated in each file: "auto-detect saves a click, it never skips a step."

3.12.2 · Generic CSV — propose → review → approve

Header: CSV Import — any file, propose → review → approve. Four stages: upload → map → review → apply.

Eleven column roles, single-use (assigning a role clears it from any other column), auto-mapped by a ten-entry whole-header regex table. Two gates disable Match & review: at least one of cert/name/sku must be mapped (Map Cert Number or Card Name first.) and at least one writable field must be mapped or the rename box ticked. A mapping that could match but could not write anything is refused, and vice-versa.

Matching is a six-rung tier ladder, first hit wins: CERT → SKU → EXACT → STRONG (≥0.8) → MAYBE (≥0.45) → NO_MATCH. The fuzzy scorer here is local to the file and is not cardMatch.js. Date parsing handles Excel serials, Date objects, YYYY-M-D and M/D/YY — added after a Date Sold silently vanished and no change was ever proposed.

Review offers four bulk-selection buttons and one apply button. Note what is not offered: there is no "select overwrites · STRONG", and MAYBE is never bulk-selectable at all. Multi-match (collision) rows are likewise excluded from every bulk-select and must be ticked individually. Apply confirms with the change and card counts, and separately names the overwrite count. If date_sold is written, year_sold is derived alongside it.

3.12.3 · eBay Sales — the money importer

The only eBay importer that books money. Matches by eBay Item # first, then base SKU, then title (cardMatch score ≥ 0.5), then a maybe tier (≥ 0.34) that is never auto-ticked. Uses the file's real Sold For and Shipping — no fee or shipping guesses; the fee comes from sold_platforms as data, falling back to eBay's 12.35% + $0.40 only if the platform list has not loaded.

refunded ⟺ order.total <= 0.004
        && order.components > 0.004
        && (order.ship > 0.004 || order.tax > 0.004 || order.paidDateSeen)

Six buckets: NEW SALE · MISMATCH · DONE · NOT IN APP · ⛔ SKIPPED · 🚨 REFUND BOOKED AS SALE. The last requires the order numbers to agree — "A refunded line matched by an 86% title score to a card sold under a different order number is a different sale of a similar card, not overstated revenue."

The refund sweep headline is always rendered after a match, including when the answer is none — "a silent screen can't tell you it checked." In the red state it tells you what to do: open each card and un-sell it, choosing Order canceled & refunded if it never shipped or Returned & refunded if the buyer sent it back — either keeps the history.

Apply either inserts a new card already marked Sold (for NOT IN APP rows) or updates a matched card. In both cases sold_price = net_proceeds = net and platform_sold_price = gross — the gross is reference only, never summed. Three fields are fill-only, where an existing value always wins: received_method_id, listing_name, shipping_collected.

A correction on an already-Sold card can emit two journey events in order — order_canceled for the old order (when this file proves it was refunded), then sale_corrected for the new one — because "a correction tells a two- or three-part story; a plain sale tells one." The card row is captured before the update so the correction records what it replaced, not just what it became.

3.12.4 · eBay Listings

Books nothing. Stamps the permanent eBay Item Number onto cards so every future sale matches exactly. The direction is inverted versus Sales: it iterates cards and matches each to a listing. A checkbox only cards missing an item # is on by default. SKU and title (≥0.5) matches auto-tick; maybe (≥0.34) does not. Apply writes only platform_sale_item_id and listing_name.

3.12.5 · eBay Purchases

The only importer that reads a real binary workbook. Fuzzy-matches each buy to a card by name (one threshold, score ≥ 0.4) — cards have no stored purchase-order id, so name is all there is. Each row's action defaults to Fill match when a card was found, else Create new; a per-row select offers all three including Skip.

The match branch fills blanks only — base_cost only when currently falsy or 0, purchase_date and platform_purchase_order_id only when empty; an empty patch counts the row as skipped. The new branch inserts a For-Sale card with the raw eBay item name as both description and intake title, then fires a best-effort photo attach.

3.12.6 · CollX Sales

Until 2026-08-17 this was a read-only reconciler, because the CollX CSV export is order-level only — no card lines — so it could never know which cards were in an order. "That limitation belonged to the CSV, not to CollX." The saved order page carries per-item card name, set, grade, price and often our own SKU, so it is now a booking tool.

A five-rung owner-locked matching ladder: SKU exact (BFL-EB… / BK71-…) → cert → name+set+grade (IDF-weighted with a hard grade gate) → picker → card id typed straight in. Tier 3 auto-ticks only when top[0].score ≥ 0.62 and either it is the only candidate or it leads the runner-up by ≥ 0.12 — "Anything closer than that is a decision, and decisions belong to a human." The ranker adds one bonus cardMatch does not have: −0.12 for a card that is already SOLD, because an unsold card is far more likely to be the one that just sold.

Other guards: an order already carrying cards is locked and cannot be re-booked; one card may serve exactly one line across the whole batch; refunded or canceled orders book nothing, ever; an already-SOLD card can still be chosen but shouts first. Multi-item nets are split with the same largest-remainder routine Bulk Sale uses (§4.5), so per-card nets sum to the order's net exactly.

3.12.7 · CDP Batch

Matches every row by cert number, SKU as backup, then proposes eBay platform, asking price, the CDP/eBay listing name, and the card attributes. Blank fields are pre-ticked; anything that would overwrite an existing value is shown old→new and left for you to approve. Dropdown values are never created — unmatched Card Type / Brand are surfaced as a review change with a picker, never guessed.

Two dialects: the snake_case batch-…-export.csv, and the Title Case inventory-export.csv which was unusable until CDP added a Cert Number column between 2026-07-26 and 2026-08-01. A pre-August export is refused rather than converted, because converting would hand every row an empty cert and quietly demote the whole file to SKU-only matching. Purchase Price and Purchase Date are deliberately not mapped — "they are CDP's numbers, not the ledger's, and money is never proposed without being asked for."

Three change kinds with distinct styling and pre-tick behaviour: fill pre-ticked, overwrite manual, review no value until you pick one. A review change is unselectable until a pick sets a value, which then enables and ticks it in one action.

A matched-but-archived card is pushed to the unmatched list marked matched #id but it is ARCHIVED — skipped and cannot be ticked for creation. Photos are collected as candidates for only the missing side and sent in batches of 8; created cards get one batched attach call after the inserts finish, plus card_listings rows so the card "arrives knowing where it's live". Listed On is additive only — only the literal status value listed counts, because "removing a listing is a destructive edit and this importer only ever adds."

3.12.8 · PSA Grading Return

Matches returning certs to the cards you sent in and allocates the grading bill. The candidate pool is only cards at location_id = 5 ("PSA Grading"). This is the only AI path in the import area: runMatch() POSTs certs and candidates to /api/psa-return and receives per-cert matches with a confidence tier, a reason, and parsed card attributes.

Fee allocation: autoFee = (totalBill − Σ locked) / (certCount − lockedCount), so a manually typed fee locks that row and the remainder re-spreads across the rest. A live hint reads = $47.33/card · 3 set manually.

Drafts: 💾 Save draft upserts the entire review state on the order number; Resume restores it and re-fetches the pool so any cards added since are now assignable.

Row guards: a duplicate assignment (two certs on one card) tints the row and disables Apply entirely; a cert conflict (the chosen card already has a different cert) tints amber and shows the existing cert; a missing PSA grader in the lookups blocks Apply outright. Both the create and update branches write name_source:'grader' and a card_title_events row. After Apply it automatically pulls PSA photos, looping psaBatch at most 25 times and stopping early on a quota hit.

3.12.9 · What no importer can ever write

• Refunded eBay orders — excluded from the apply set and re-checked inside the apply loop.
• Canceled, $0-gross, or net ≤ $0 eBay rows.
• Refunded or canceled CollX orders; and any CollX order already carrying cards.
• Sold Price or Date Sold onto a card that is not already SOLD.
• Archived cards — Generic CSV excludes them from matching, CDP refuses to create against them.
• Two rows onto one card in the same run.
• A dropdown value that does not already exist — CDP proposes a picker instead, for Card Type, Brand and Grader alike.
• A listing removal.

3.13Help & Support

Opened exclusively by the header ? and visible to every role. Four labelled groups under coloured underlines: Guides (User Guide, Function Reference), Ask (Submit an Issue, Request a Feature), Contact (Contact Us), and Account (Password).

Both guides are static HTML served from /help/ and open in a new tab with noopener. The Guides pane also carries six quick recipes, which reference the tabs by their current labels:

The three forms are one component with the kind switching the copy and the field layout. Fields: Area of the app (eleven fixed options), How bad is it? (issue only — blocking / annoying / cosmetic), Card ID(s) optional, Subject (max 140 chars), and a body whose label and placeholder change per kind. Both subject and body are required. Every submission writes a support_requests row carrying the partner id, and the beside-button copy makes the attribution explicit: "Submitting as {name} · your name and role ride along automatically."

My requests is always rendered at the bottom: the caller's twenty most recent rows, re-fetched whenever a form is submitted, each showing a status chip (New / Seen / In progress / Done / Declined), the type word, the truncated subject, and the area plus date. An unknown status falls back to the raw string with the new tone.

The Account pane's Change password… closes Help and opens the change-password modal — the password control was deliberately moved out of the header into Help (owner decision, Aug 13). Its copy warns: "You'll stay signed in here; other devices will need the new password next time they sign in."

4Algorithms

The nine pieces of logic that carry the most weight and are easiest to break by accident. Each is documented with its rules, its thresholds, and — where one exists — the incident that shaped it.

4.1cardMatch.js — the structured card matcher

From its own header: "Structured card matcher for eBay reconcilers. Far more precise than plain token overlap: it treats YEAR, BRAND, GRADER, GRADE, and CARD # as hard filters (a PSA 9 can't match an SGC 9.5; a Topps can't match a Panini), and weighs rare tokens (player names, set codes) far above common ones (colors) via IDF."

Consumers: EbaySales, EbayListings, EbayPurchases and CdpImport via buildMatcher; CollXSales via the exported parseCard, wrapped in its own ranker. cardMatch.js is deliberately left untouched by CollX — the eBay importers depend on it.

parseCard(s) — structured extraction

Hard filters — applied only when both sides carry the attribute

• year mismatch → skip the candidate outright
• grader mismatch → skip
• grade mismatch → skip

Brand is explicitly NOT a hard filter — "Panini Donruss vs Donruss etc. conflate" — it is handled as a weighted token instead. Year, grader and grade stay hard.

Scoring

idf(t) = log((N + 1) / (df[t] + 1)) + 1

base   = Σ idf(t ∈ both) / Σ idf(t ∈ either)          // IDF-weighted Jaccard, 0–1

return { card: best, score: bs, confidence: Math.max(0, Math.min(1, bs)) }

Threshold table across all callers

4.2fileDetect.js — Tier-1 auto-detect

The signature model

Every entry in SIGNATURES is transcribed from the importer that consumes that file:

Order matters — first match wins. The signatures genuinely overlap (an eBay orders report also carries an item-number column; a CDP export also carries a cert column), so they are listed narrowest-first.

CUSTOM_LABEL = /^custom label(\s*\(.*\))?$/ exists because eBay is not consistent with itself: the orders report says "Custom label", the active-listings report says "Custom label (SKU)".

Probe mechanics

• Workbook names go through XLSX.read(buf, {sheetRows: 40}). Only the first sheet is examined, same as every importer; a multi-sheet workbook is flagged in note.
• Page names are decoded with extractHtml() — the same function collxOrderParse.js uses, so detection and parsing can never disagree about what the page says.
• Everything else, including extensions the app does not handle, is read as text: "A mislabelled export is common enough to be worth the peek, and a binary simply yields cells that match nothing."
• splitCells() splits naively on [,\t|;], strips BOM and quotes, trims and lower-cases. The naivety is deliberate: comparisons are whole-cell against short literals and none of the target column names contain a comma, so a quoted comma-bearing cell "splits into harmless junk rather than corrupting the cells we care about."

Saved pages (detectPage)

Why both conditions are required: "'Mentions CollX' alone was enough to make the app's own User Guide impersonate an order page, because the guide documents the CollX importer."

The confidence model

i = gateIndex(sig, rows)                 // -1 → this signature yields no verdict
if (disqualify matches that row)  → null
present  = count of sig.reads found in that header row
coverage = present / sig.reads.length    // 2dp
missingRequired = sig.require not found

confidence = missingRequired.length ? 'low'
           : coverage >= 0.5        ? 'high'
           :                          'medium'

"A matched gate missing a required column is low, because we would be routing a file the importer is about to refuse." reason is always the literal evidence — the source file's header test, the coverage fraction, and the matched header line trimmed to 160 characters.

Public API: detectFile(file) → one verdict; detectFiles(files) → verdicts in order; groupByImporter(detections) → {groups, unknown, single}, where single is populated only when there is exactly one group and zero unknowns. SIGNATURES[].importer is DataImport's own mode string, deliberately, so routing is setMode(d.importer) with no lookup table between them going stale.

4.3collxOrderParse.js — the saved-order-page parser

• MHTML support. extractHtml() detects multipart/related, finds the boundary, takes the first text/html part, and decodes quoted-printable (soft line breaks first, then =XX escapes collected as bytes so multi-byte UTF-8 — Julio Urías, Sam's Card Club — survives) or base64.
• Money in integer cents everywhere — "a penny-exact tie-out is the whole point, and floats do not tie out."
• afterLabel() takes the LAST occurrence by default, because several labels appear once in a top summary and again in the authoritative totals block at the bottom — "and the bottom one is the one that ties out."
• Item extraction. Every item line ends with the marker (CollX Sale). The item region is everything between the last Items Detail heading (the first is a nav link) and the last marker, split on the marker. A chunk is name · set · [grade] · xQTY · sku-or-collx-id · price: the quantity line x N anchors it, the price is the last money-looking line after it, and the SKU is the line right after the quantity if it is not money.
• isOurSku(s) = /^(BFL-EB|BK71-)/i — anything else in that slot (notably CollX's bare 5-digit catalogue id) is CollX-side and "cannot be joined to our data … CollX has no inventory export."
• searchText = [set, name, grade].join(' ') — the best single string for the matcher, because parseCard reads year+set from the set line, card number+player from the name line, and grade from its own.

Warnings it emits (each surfaced per order in the UI): no item lines; missing gross; missing net; Item prices sum to $X but the order Price is $Y.; Gross $g + fee $f + protection $p = $e, but the page states net $n.; "{name}" sold with quantity N — one CollX line, N physical cards. Book each separately.; and an order status that is refunded or canceled. Hard failures: File contained no readable text. and No CollX order number found — is this a saved CollX order page?

4.4Normalisation primitives

stripSetPrefix — CDP's set string

CDP writes Set as <year> <brand> <set> — 2024 Panini Absolute — because it has no separate year or brand field. The app does. Dropping CDP's string in raw triples the year and brand, and a later "Generate names" then produces 2024 Panini 2024 Panini Absolute #133 Keon Coleman.

Algorithm: strip a leading 19xx/20xx , then strip a leading brand from ['Upper Deck','Topps','Panini','Bowman','Donruss','Fleer','Leaf','Score','Sage'] (longest first) only when something follows — so 2023 Topps stays Topps, because that is the set. Applied to both dialects.

"i.e. 227 of the 'disagreements' were nothing but CDP's formatting."

certKey — the leading-zero fix

cleanCert(v) trims and strips a trailing .0 (a SheetJS float artifact). certKey(v) is cleanCert with leading zeros stripped, because SheetJS parses a numeric-looking cell as a number, so 0278119 arrives as 278119 and no longer equals the stored value. SGC certs carry leading zeros far more often than PSA ones, "which is why this surfaced on a pile of SGC Drake Mayes: 5 rows in the 2026-08-21 export were cards the ledger already had, shown as 'not in the app' purely because of a lost zero." The stored value is never altered — only the comparison key.

skuBase — two different suffix rules

subsetFromTitle — subtractive parsing

Used only when a CDP structured column is blank; every result is an ordinary reviewable fill marked in the UI with ⟵name. It strips, in order: the full set string; #num and the bare number; the player; the year; the brand list (because once the year+brand prefix is stripped for storage, the brand would otherwise survive here and masquerade as a subset); bare print runs (/399, #/150 — "a print run, not a subset"); the player's name word by word as well as whole (CDP's spelling and the title's can differ — "Niko Kavades" vs "Niko Kavadas" — and a whole-name strip then removes nothing, or worse matches a fragment and leaves "ah Strong" behind); any surviving #code ("A #code is never a subset"); a trailing PSA <grade> phrase; and stranded punctuation. Results shorter than 2, longer than 60, or containing no letters are rejected.

4.5Largest-remainder cent allocation

Used by Bulk Sale (split an order across cards by asking price) and by CollX Sales (split an order's net across its item lines by item price) — the same routine, "verified penny-exact".

function allocate(total, weights)

1.  convert total to integer CENTS
2.  if every weight is zero:
        split evenly and hand the leftover cents to the LOWEST indices
3.  otherwise:
        rawᵢ   = totalCents × wᵢ / Σw
        shareᵢ = floor(rawᵢ)
        distribute the remaining cents to the LARGEST fractional parts first,
        ties broken by INDEX
4.  divide back by 100

4.6useWaterfall — the partner accounting engine

A single useMemo over six inputs (cards, entries, distributions, profitSplits, profitGifts, yearKey). PARTNERS = ['Kevin', 'Brian', 'BKCards71'] — hard-coded, exactly three; everything accumulates into three-key maps.

The three rules, verbatim from the header comment

The two frames, never mixed

cohortKey(c): purchase_year ≥ 2026 → that year as a string, otherwise the literal '2025 & before'. Everything predating the app is one lump, and selecting 2025 in the toggle shows that lump.

Step by step

The shipping-margin term

shipMargin(c):
  if (shipping_collected == null) return 0
  col = num(shipping_collected)
  ext = label_cost == null ? col : num(label_cost)   // a null label cost is a WASH
  return col − ext

The comment is emphatic: "This term is already inside the DB's generated net_return, so every profit figure here must carry it too or the screens drift from the DB."

Returned values nothing renders

pl.shipMargin (Statements recomputes it locally), rules.bkOwnedProfit, dist.capitalTaken, and profit.profitTarget / profit.profitStillOwed (the UI recomputes both from the live slider draft so the numbers move before saving).

4.7Canonical name builders

There are five implementations of "build a card name from attributes" in the codebase, in three formats. All of them uppercase, drop empty tokens, and collapse consecutive duplicate tokens (so brand BOWMAN + set BOWMAN CHROME yields one BOWMAN CHROME).

4.8The platform fee engine

computedNetFor(platformId, total):

1. TIERED?  tierFor() picks the bracket with the largest min_price <= total
            (rows arrive ascending; the first row is the fallback)
            net = round(total × (1 − fee_pct/100) − flat_fee, 2)
            → tiers TAKE PRECEDENCE over the platform's flat rate

2. FLAT?    net = round(total × (1 − fee_pct/100) − per_order_fee, 2)

3. NEITHER  fee_pct NULL and no per-order fee → return null (no auto-fill)

netLocked(platformId) is true when the platform has tiers, a positive fee_pct, or a positive per_order_fee. When locked, the Net Sale input is disabled with the tooltip "Computed from the platform fee — not editable"; unlocked it reads "Editable — defaults to Total". The field label grows a live suffix showing the maths, e.g. (−12.35% − $0.40) or (−8% tier). The tiered ladder is how PSA's eBay consignment pricing is modelled. Everything the engine produces is explicitly an estimate, "trued up by the actual payout (importer MISMATCH review or hand entry)."

Bulk Sale applies the identical rules to the order total, because one order incurs one fee (§3.10). eBay Sales uses the same rates but its own formula, because the eBay fee is charged on the whole payment: fee = fee_pct% × (sold + ship + tax) + per_order_fee.

4.9Recurrence expansion

A recurring cost is stored as one row, never materialised into per-period rows: an amount (the per-occurrence cost), a frequency whose months_interval is the step, a start_date, and an optional end_date.

for k = 0 … 1199:
    total = start.month + k × months_interval
    y = start.year + floor(total / 12)
    m = ((total % 12) + 12) % 12
    if end_date and (y,m) is past it        → stop
    if (y,m) is the current month or later  → stop      ← in-progress month excluded
    if yearKey is 'all' or y matches        → count++

• The in-progress month is not counted until it ends. A monthly bill started in January and viewed in mid-August counts 7, not 8.
• Stopping a rule means setting an End Date. Occurrences after that month stop counting immediately, in every year scope, retroactively consistent.
• No Date object is constructed anywhere in the walk — see the UTC-drift guardrail in §3.5.
• The 1,200-iteration cap silently truncates a monthly rule running longer than 100 years.

5API Surface

Six Vercel serverless routes at the repo root in /api, alongside the Vite app. Three of them share an identical hardened blueprint; the other three are looser, and two are unauthenticated.

5.0 · The shared manager guard

api/photos.js, api/psa.js and api/identify.js each define requireManager(req, db) identically:

1. Strip Bearer (case-insensitive) from the Authorization header. Missing → 401 Missing bearer token.
2. db.auth.getUser(token). Invalid → 401 Invalid or expired session.
3. Select id, name, role, account_status from partners on auth_user_id. A DB error → 500.
4. No partner row, or role not in ['company','partner','admin'] → 403 Manager role required.
5. account_status of suspended or removed → 403 Account is not active.

api/users.js uses a variant (getCaller) that checks role but not account status and returns a flat 403 for every failure mode. api/psa-return.js and api/analyst.js have no authentication at all.

5.1 · api/photos.js — the photo importer

maxDuration: 60. Env: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, PSA_TOKEN. Bucket card-photos. MAX_BATCH = 8. GET is an unauthenticated probe returning only whether the PSA token is present, never its value.

PSA batch outcomes, and the budget discipline

attachImage — the shared primitive

1. fetch(sourceUrl)                     non-ok → "image download HTTP {status}"
2. content type defaults to image/jpeg; extension is png only when the type contains "png"
3. path = cards/{id}.{ext}   for a front
          cards/{id}-back.{ext} for a back
4. upload with upsert: true
5. public URL + "?v={Date.now()}" cache-buster
6. update cards.photo_url | photo_back_url, plus updated_at

"The two sides use different storage paths and different columns, so a back operation can never touch a front image, and vice versa." An existing front is skipped as already has a photo unless overwrite is exactly true.

5.2 · api/psa.js — PSA cert lookup

Cost note in source: "PSA free tier ≈ 100 calls/day; each cert here = up to 2 calls (attrs + images)."

5.3 · api/identify.js — Ximilar identification

Endpoint collectibles/v2/sport_id. MAX_BATCH = 10 ("Ximilar accepts up to 10 records per call"). The GET probe is a diagnostic that reports the token's presence, its length, and its first and last three characters, plus the full Ximilar account body — unauthenticated (D-09).

{action:'scan', candidateIds}

1. Load the rows; filter out anything whose side is not front (reason not a front) and anything with no image. Backs never reach Ximilar.
2. Mark all survivors status:'scanning' in one update — this is what drives the pulsing sky badge in the UI.
3. Process in chunks of 10 with price_stats: true.
4. Map each record back into proposed, suggested_name, confidence (the match distance — lower is better), raw, and scan_error.
5. A non-ok response or a thrown fetch marks the whole chunk error with a message assembled from whichever of status / error / detail Ximilar returned.

It never touches cards. Ids capped at 50.

mapRecord() — the Ximilar → app mapping

pickObject takes the largest-area detected object, else the first. Identification lives at _objects[0]._identification.best_match, and best_match === null means "detected a card but couldn't identify which one" → identified: false, which the UI surfaces as No match — enter manually.

{action:'identify', cardIds} is a legacy calibration harness that proposes from existing cards' photos and writes nothing — it exists to calibrate the mapping against real output.

5.4 · api/psa-return.js — the grading-return LLM matcher

Auth: none. Model claude-sonnet-4-6, max_tokens: 12000. Request { certs: [{cert, description, grade}], candidates: [{id, name, base_cost}] }; payloads are compacted to just the needed string fields before being sent (base_cost is accepted but not forwarded).

The system prompt defines a two-task contract:

• Task 1 — MATCH. Four explicit rules: use each candidate id at most once (one physical card per cert); when several candidates are the same card, assign them one-to-one and set is_cluster; if nothing is a confident match, app_id is null and confidence is "none"; confidence ∈ high | medium | low | none. Crucially: "The candidates are ungraded, so IGNORE the grade when judging identity."
• Task 2 — PARSE. Extract year, brand, set, subset, card number, player, parallel, rookie and auto from the PSA description with precise normalisation: brand is the manufacturer only; set is the product line without year or brand; card_number is exactly as printed with no leading #; unknown strings are "".

5.5 · api/analyst.js — Insights CFO commentary

Auth: none. Model claude-sonnet-4-6, max_tokens: 1000. Request {scope, metrics}; the user message is Section: {scope}\n\nFigures (JSON):\n{pretty metrics}\n\nWrite the CFO commentary now.

Both LLM routes parse the body defensively (typeof req.body === 'string' ? JSON.parse(…) : req.body || {}) because Vercel may hand it over parsed or raw depending on runtime. An empty result is a 502, never a blank success.

5.6 · api/users.js — user administration

The most privileged route. Request shape {action, payload}. Every mutating action writes a user_audit row carrying actor id + email, action, target id + email and a JSON detail. syncStatus is the one action that writes no audit row.

5.7 · The surface at a glance

6Invariants and Guardrails

Consolidated. Each row is a rule the system actually enforces, with the place it is enforced. Rules marked advisory are surfaced to the user but not blocked.

7Integrity Model

Two distinct systems share a name. The Integrity tab is a data-quality worklist of 18 checks with no severity model. The header badge watches three invariants and is the only place broken-versus-attention exists.

7.1 · Why the badge is not the tab in miniature

7.2 · Scope and the fail-closed prerequisite

const LIVE = (q) => q.is('deleted_at', null).or('archived.is.null,archived.eq.false')

Every check is scoped to rows that are neither soft-deleted nor archived (a null archived counts as live). Deleted and archived cards can never light the badge.

Before any counting, the hook loads dispositions and derives soldReal (category === 'Sold' && is_sold), loss (category === 'Loss'), and soldOk = soldReal ∪ loss — the set of dispositions a SOLD card is legitimately allowed to carry.

7.3 · The four badge checks

All four are count:'exact', head:true queries — no card rows are transferred. Total cost: four head-only counts plus one small lookup, "so this is safe on sign-in and after every write."

broken    = residue + dispSold + dispUnsold
attention = missing
severity  = broken > 0 ? 'broken' : attention > 0 ? 'attention' : 'clean'
total     = broken + attention

The badge's number is the combined total, so a red badge reading 7 may be 2 contradictions plus 5 incomplete records; only the tooltip breaks it down. The exported PULSE labels are Books clean · Needs attention · Books broken · Check unavailable.

7.4 · How the badge maps onto the tab

The remaining 15 tab checks — the whole cost, grading, ownership, sanity and collection-facing backlog — deliberately have no badge representation.

7.5 · Failure and lifecycle

The whole body is wrapped in try/catch; any throw yields severity:'unknown' with the message. The comment states the rule precisely: "Never break the header over a health check — but never fake an all-clear." The check re-runs when the partner loads, every time the Admin Console closes, and on demand via the returned refresh().

8Known Defects, Inconsistencies and Risks

62 items. Everything the source review turned up, consolidated and numbered. Nothing here is speculative — each entry traces to code that exists. Severity is a judgement about consequence, not about how hard it is to fix: high can produce a wrong number or a data loss; medium misleads, blocks a workflow, or is a latent trap; low is cosmetic or a maintenance burden.

8.1 · Naming, labelling and duplicated logic

8.2 · Security and exposure

8.3 · Ledger and grid

8.4 · Financials, Accounting and the waterfall

8.5 · Editing, events and audit

8.6 · Importers and admin

8.7 · Architectural risks

9Appendices

9.1Event types

card_events vocabulary. Sort is EVENT_SORT, stamped at write time as sort_hint; an unknown type defaults to 50. Struck marks the four reversal types whose money renders with a line through it.

Sources

Platform labels are resolved per type: sold → sold_platforms, purchased → purchase_platforms, listed → listing_platforms. Any other type shows no platform even when platform_id is populated.

Types available in the hand-entry form

Note · Found · Lost · Loaned out · At a show · Damaged · Sent to grading · Graded · Listed · Asking price changed · Sold — historical · Returned & refunded — historical · Order canceled & refunded — historical · Sale corrected — historical · Sale struck — historical.

Deliberately absent: purchased, live sold, gifted, written_off, archived, restored, reintake_kept_paid — those are only ever written by the flow that performs the action. The five "historical" entries exist to record reversals that predate the event log; the code names Yamamoto #1692 and Misiorowski #1811 as the cases it was built for.

9.2Audit actions

user_audit columns: id · action · detail (jsonb) · created_at · actor_partner_id · actor_email · target_partner_id · target_email. There is no actor column — see §2.4 for the incident that produced the helper.

9.3Reconciliation targets and identities

Hard internal identities — must hold to the penny

Cross-tab reconciliations

External acceptance targets

These are the figures the migration and every subsequent phase have been reconciled against. Any change to the money code should be re-checked against all of them before shipping.

9.4Glossary

10Edition 4 Additions (2026-08-29)

10.1 Intelligence tab & the valuation engine

The Scan tab became Intelligence (internal key unchanged): AI Card Scan · My Card Values · Prospect (placeholder) · Industry (placeholder). api/value.js computes market values: grade-matched sold comps → IQR outlier trim → recency-weighted median; <3 comps at exact grade steps one grade down, disclosed. Returns value, sample_n, low/high, confidence (strong ≥8 / fair ≥3 / thin), last-3 sales with links, and effective_days read from the response’s real coverage. 7-day per-card cooldown enforced server-side. At-grading rule: grader set + no grade ⇒ grade renders “Pending,” card valued as RAW with bare grader words stripped from the query. Storage: cards.market_value/_at/_n/_days (single truth, in CARD_SELECT) + card_valuations history (org-walled RLS). Doctrine D-12: external values are display data — they never touch cost basis, net return, ledger, waterfall, or tax.

10.2 Financial Ledger importers

Bank Statement importer — src/lib/bankStatementParse.js + src/components/BankImport.jsx, mounted as a modal on the Finances Ledger (deliberately NOT a Data Import mode). Layout sniffing: a masked card-number column ⇒ credit-card file; a running-balance column ⇒ checking. Classification (conservative; unrecognized ⇒ human review): transfers (PAYMENT - THANK YOU ↔ WEB PMT TO) skip; marketplace payout credits and PSA transfers skip (income lives on cards); eBay O* buys and PSACARD.COM skip (card costs); PIRATE SHIP skips OpEx (label costs belong per-sale — Shipping Ledger); subscription patterns match the org’s recurring rules and mark “covered,” never double-booking; SERVICE CHARGE books to Bank Fees (vendor auto-ensured). Dedupe: same absolute amount within ±3 days of an existing entry (banks post late), flagged and un-ticked. Same-amount-across-months pattern ⇒ “monthly bill?” banner ⇒ one-click recurring-rule creation. Unknown last-4 ⇒ inline pay-method creation. Booked rows are structurally excluded from re-send; failures carry per-row plain-English reasons via friendlyDbError().

Receipt Photo importer — api/receipt-parse.js (server-side Claude vision; key never in the browser) + src/components/ReceiptImport.jsx. Up to 10 images per run ⇒ per-receipt vendor, order_date, order_number, grand_total, card_last4/brand, items with qty/unit_price/line_total, suggested title. Multi-item receipts always split one entry per item; any gap between item sum and grand total (tax/shipping) is allocated proportionally to the penny (largest-remainder — the CollX allocation doctrine) and disclosed per line. Quantity detail (“2 @ $15.94”) and the order number are persisted in fin_entries.description. Reimbursable pre-set from the pay method’s default (10.3); unknown cards addable inline with an “always reimbursable to X” answer stored on the method.

10.3 Pay-method correlation model

fin_pay_methods gained last4 (text), kind (credit/debit/checking/cash/paypal/venmo), reimbursable_default (bool), and owner_contributor_id. Importers correlate statement/receipt lines to methods by last4 as data — never by name parsing. Personal methods default reimbursable to their owner; company methods do not. Naming convention: BK CC (Kevin) - 0881.

10.4 Ledger CSV export

Ledger-view button; emits <slug>_Ledger_<scope>.csv with one row per entry including occurrences-in-scope and total-in-scope computed by the same occurrencesInScope() the screen uses — the export foots to the view by construction (sidesteps the Excel export’s K-25 recurrence mismatch).

10.5 Recurring-rule semantics (doctrine D-17)

The Active checkbox was removed: no calculation ever read it. Dates are the single truth — no end_date ⇒ running; end_date ⇒ generation stops after that month. The entry panel renders a derived status line. The fin_entries.active column remains in the schema, inert. Constraint note: reimbursed_state accepts none | partial | full — “owed” is represented by reimbursable=true + state='none'.

10.6 UI doctrine (owner rulings, 8/29)

Toolbar actions are activators: fixed labels, lit while their panel is open, one panel at a time; the exit is an in-panel terracotta Cancel ✕ (#7f3126). Importers are modals over their surface. File pickers are real buttons, never bare inputs. Result feedback is loud and doubled (top + bottom banners); booked = green ✓, grayed, never re-sent; failed = red, active, plain-English reason; duplicates arrive un-ticked. Every money input carries a frozen $ (MoneyInput). All user-facing errors pass through friendlyDbError().

10.7 Realtime: the [cards-live] resolution

Months of CHANNEL_ERROR: transport failure were caused by two trailing newline characters pasted into the Vercel VITE_SUPABASE_ANON_KEY: REST survived (fetch strips whitespace from header values) but the realtime websocket carries the key in the URL (%0A%0A), so the handshake was refused. Fixed by .trim() on both env values in src/lib/supabase.js; console now logs [cards-live] SUBSCRIBED. RLS was never involved. Rollout of live updates beyond the cards grid is now unblocked.

10.8 Vendor posture

Ximilar retired as scan vendor (subscription ended 7/31; residual credits usable). Card Hedge AI (api.cardhedger.com, OpenAPI at /docs, X-API-Key auth, agent lane from ~$0.01/call) is the scan vendor of record; awaiting per-image pricing and resale-license terms before the adapter ships. Valuation remains behind a vendor-swappable interface.

S&T Card Manager — Functional Reference · Edition 4.0 · August 29, 2026. Compiled from a full read of src/ and api/. Every behaviour described here is behaviour that ships today; planned work is deliberately out of scope. Defect IDs (D-01 … D-62) and guardrail IDs (G1 … G52) are stable within this edition and safe to cite in tickets.