@plan-fi/imports 0.6.0

package/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md — planfi-import
+
+planfi-import turns raw financial data — aggregator API dumps (Plaid, MX, Finicity, FDX) or
+user-downloaded CSV/OFX files — into a planfi `generate_financial_plan` wire body via one canonical
+model (the CFP). Adapters translate provider vocabulary; ONE shared mapper (`src/to-planfi.mjs`)
+does all the planfi thinking.
+
+## Invariants (non-negotiable)
+
+- **NEVER fabricate values.** Missing cost basis stays `undefined` (+ `NO_COST_BASIS` info
+  warning). A value no data source can know (age, goals, home value, missing APR) becomes a
+  structured `needsInput` ask — the shared mapper emits those; adapters never invent defaults to
+  paper over gaps.
+- **ALL domain logic lives in `src/to-planfi.mjs`.** Adapters ONLY translate one provider's
+  vocabulary into the Canonical Financial Profile (`src/canonical.ts`). If you are writing IRS
+  limits, LTV estimates, tax buckets, or wire fields inside an adapter, stop — that belongs in the
+  shared mapper, once.
+- **Warnings use stable codes from the catalog.** Every judgment call is a
+  `{ code, severity, message, accountId? }` built with `warning()` from `src/util.mjs`; `code`
+  MUST be a member of the append-only `WarningCode` union in `src/canonical.ts` (mirror any
+  addition in `planfi-import.d.ts` — a test compares them). Never invent ad-hoc codes; never
+  repurpose an existing one.
+- **Emit `needsInput` for anything a source can't know.** Fields come from the `NeedsInputField`
+  enum in `src/canonical.ts`; each entry carries a form-ready `label` and a one-sentence `why`.
+- **Zero runtime dependencies.** Node built-ins and sibling modules only. `tsx`/`zod` are
+  test-only devDependencies; nothing under `src/` or `bin/` may import a package.
+- **`normalize()` is a total, deterministic function.** Any input — `null`, junk, truncated files,
+  hostile arrays with `null` members — returns a structurally valid CFP; never throw. Same input →
+  same output (only exception: `defaultAsOf()` when the payload has no `asOf`).
+- **Every adapter is fully registered.** `ADAPTERS` + named export in `src/index.mjs`, types in
+  `planfi-import.d.ts`, source list in `bin/planfi-import.mjs` USAGE, a fixture at
+  `fixtures/<id>-sandbox.mjs` exporting `<id>Raw`, registered in
+  `test/helpers/fixture-registry.mjs` (which feeds wire-conformance), a `test/<id>.test.mjs`, and
+  a generator in `test/fuzz.test.mjs`. `test/adapter-contract.test.mjs` enforces most of this —
+  run it and read its failure messages.
+
+## Verify (run all three; all must pass)
+
+```bash
+npm ci          # installs the test-only dev deps (runtime stays zero-dep)
+node --test     # every suite: per-adapter, contract harness, fuzz, CLI, wire-conformance
+npm run demo    # prints a full ImportResult from the Plaid fixture — must emit valid JSON
+```
+
+`node --test` must end `fail 0`. Inside the planfi-app monorepo, wire-conformance also round-trips
+every fixture through the real engine mapper; in the standalone repo it skips loudly (that skip is
+expected and not a failure).
+
+## To add an adapter
+
+Follow **docs/ADAPTER_GUIDE.md** step by step — it contains the canonical-model reference, the
+copy-me template (`src/adapters/_template.mjs`), the classification cheat sheet, the warning-code
+catalog with when-to-emit rules, fixture requirements, and a self-verification checklist whose
+checks are the executable tests in `test/adapter-contract.test.mjs`.

package/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog
+
+> **npm:** published as **`@plan-fi/imports`** (public, scoped to the `plan-fi` org) as of 0.6.0.
+
+
+All notable changes to `planfi-import`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org/) (pre-1.0: minor bumps may break).
+
+## 0.6.0 — 2026-07-03
+
+### Added
+
+- **`batch` CLI command** — bulk-load thousands of customers through the managed
+  `import_financial_data_batch` endpoint (25 items per call):
+  `npx planfi-import batch <dir-or-ndjson> --source plaid --token pft_…
+  [--concurrency 4] [--resume manifest.json] [--batch-size 25 | --single]`.
+  Input is a directory of `<user_id>.json` payload files (filename stem = `user_id`) or an
+  `.ndjson` file (`{"user_id", "payload"[, "plan_name", "source"]}` per line). The command
+  chunks the load through the batch endpoint with a small worker pool, writes a **resume
+  manifest / results file** (per-customer `ok`/`plan_id`/`updated`/`error` plus **full
+  `needsInput` objects** — `field`/`label`/`accountId` — for collection worklists), skips
+  already-ok items on re-run, never crashes on one malformed file (recorded, run continues),
+  and prints a final report with the missing-data rollup (needsInput field → customers).
+  Exit 0 all-ok / 1 if any item failed / 2 usage error.
+- **Import upserts (server-side; documented here because the CLI relies on them)** — the
+  managed import tools now key on **(partner account, `user_id`)**: the first import for a
+  customer mints their plan; every re-import for the same `user_id` **updates that plan in
+  place** (same `plan_id` back, `updated: true`). Batch runs are therefore idempotent — the
+  resume manifest just saves quota. This deliberately differs from `generate_financial_plan`,
+  which always mints; the `plan` command (which uses `generate_financial_plan`) is unchanged.
+- **Consumer-tool CSV dialects** — the existing `csv` adapter's dialect table now fingerprints the
+  export formats of the consumer finance tools the FIRE audience actually uses (no new adapters —
+  dialect work inside `src/adapters/csv.mjs`):
+  - **Monarch Money balances** (`Date/Account/Account Type/Institution/Balance`) — the file is a
+    balance HISTORY, so rows are collapsed to the newest date per account (history is never
+    summed). Explicit `Account Type` values classify at high confidence; the Monarch-specific
+    `Real Estate`/`Vehicle`/`Valuables` types become `property`-class accounts (owned homes /
+    physical assets), not fake investment balances.
+  - **Monarch Money transactions** (`Date/Merchant/Category/Account/Original Statement/Notes/
+    Amount/Tags`) — Mint-style signs; the Category vocabulary feeds contribution inference with
+    "Dividends & Capital Gains"/"Interest" excluded as growth.
+  - **YNAB register** (`Account/Flag/Date/Payee/Category Group/Category/Memo/Outflow/Inflow/
+    Cleared`) — the `Outflow`/`Inflow` column PAIR nets to a signed amount; transfers into
+    tracking accounts count as contributions while reconciliation balance adjustments (market
+    growth) do not. YNAB structurally exports **no balances**, so the import emits the new
+    `CSV_TRANSACTIONS_ONLY` warning telling the caller to pair the register with a balances file.
+  - **Empower / Personal Capital holdings** (`Account/Ticker/Name/Shares/Price/…/Value`,
+    community-documented column set) — rows group into accounts by the `Account` column; the
+    export carries no cost basis → `NO_COST_BASIS` per holding. Empower offers no official
+    all-accounts balances CSV; a hand-assembled one falls through to generic-accounts deliberately.
+  - **Copilot Money transactions** (community-documented, LOW-confidence dialect fingerprinted on
+    its `parent category` column) — Copilot's INVERTED sign convention (spending positive,
+    money-in negative) is flipped before inference; if the convention is ever wrong, inflows read
+    as outflows and are excluded (conservative — no contributions fabricated). Copilot's accounts
+    export fingerprints as generic-accounts by design.
+- **`CSV_TRANSACTIONS_ONLY` warning code** (append-only catalog addition, registered in
+  `src/canonical.ts` + `planfi-import.d.ts` + the README/guide catalogs): the imported file's tool
+  structurally cannot export balances — pair it with a balances source.
+- Transactions dialects gained per-dialect vocabulary switches: `labelKeys` (compose the
+  growth/inflow test label from several columns), `amountSign: -1` (inverted-sign sources), and an
+  Outflow/Inflow column-pair path; `paycheck` joined the shared inflow words.
+- CSV `Type`/name cells naming real estate or vehicles now classify as `property` (same
+  routing-around-`classify()` pattern as the MX adapter), so they reach the plan as real estate,
+  not as a taxable-investment guess.
+- The `csv` sandbox fixture now carries one realistic synthetic file per consumer dialect (seven
+  files total) and still round-trips the real monorepo mapper in wire-conformance.
+
+## [0.4.0] — 2026-07-02
+
+### Added
+
+- **FDX adapter** — `importToPlan('fdx', { accounts, holdings, transactions, owner, asOf })`
+  for the Financial Data Exchange standard (the US open-banking vocabulary named by the CFPB
+  §1033 rule; Akoya speaks it natively). Accepts FDX Account entities both WRAPPED in their
+  shape keys (`{ depositAccount: {…} }`, `{ investmentAccount }`, `{ loanAccount }`,
+  `{ locAccount }`, `{ lineOfCredit }`, `{ annuityAccount }`) and already flattened; the wrapper
+  key doubles as the fallback class signal for unknown `accountType` values. Maps the FDX
+  `accountType` enum (CHECKING/SAVINGS/CD/MONEYMARKET → depository; BROKERAGE/IRA/ROTH/ROTH401K/
+  401K/403B/457/529/HSA/KEOGH/SEPIRA/SIMPLEIRA → investment with matching tax treatment;
+  TDA/ANNUITY → traditional at low confidence, warned; MORTGAGE/HOMEEQUITYLOAN + LOAN/AUTOLOAN/
+  STUDENTLOAN/PERSONALLOAN → loans; CREDITCARD/LINEOFCREDIT → credit), InvestmentHolding
+  (holdingType/symbol/units/marketValue/costBasis — DIGITALASSET → speculative crypto; missing
+  cost basis never fabricated), and transactions with `debitCreditMemo` respected (DEBITs never
+  count as contributions). Liability balances are treated as positive amounts owed per FDX
+  conventions with an `|x|` defense; a depositAccount `interestRate` is a savings yield and never
+  becomes a debt APR. Ships with a two-earner sandbox fixture, a full test file, fuzz coverage
+  (wrapped AND flat entities), wire-conformance registration, and enum-alignment notes in
+  `canonical.ts`.
+- **Adapter-contract harness** — `test/adapter-contract.test.mjs`: one GENERIC suite that
+  discovers every adapter in `ADAPTERS` and runs the identical battery — (a) `normalize(fixture)`
+  yields a structurally valid CFP (new `test/helpers/validate-cfp.mjs` validator) clearing a
+  content floor, (b) `toPlanfiPlan` succeeds with every warning code from the append-only catalog
+  and every needsInput field from the enum (both PARSED out of `src/canonical.ts`, with
+  `planfi-import.d.ts` asserted to mirror them), (c) hostile inputs never throw
+  (null/undefined/primitives/null-member arrays + 60 deterministic scrambles of each adapter's
+  own fixture), (d) determinism (two identical runs → deep-equal), (e) every adapter has a
+  fixture registered for wire-conformance — the fixture list moved to
+  `test/helpers/fixture-registry.mjs`, shared by both suites so they cannot drift.
+- **AI-agent authoring docs** — `AGENTS.md` (repo purpose, the invariants as imperatives, exact
+  verify commands) and `docs/ADAPTER_GUIDE.md` (ships in the npm package): canonical-model
+  reference table, the adapter contract, classification cheat sheet, warning-code catalog with
+  when-to-emit rules, fixture requirements, registration checklist, and a self-verification
+  checklist whose checks are the contract harness. Plus `src/adapters/_template.mjs`, a fully
+  commented copy-me skeleton that emits an empty-but-valid CFP, is excluded from registration,
+  and is covered by a guide-consistency test.
+
+### Fixed
+
+_All three found by the new contract harness's hostile-input battery (the fuzz suite generated
+plausible payloads and never hit these):_
+
+- **Every adapter threw on `normalize(null)`** — the `raw = {}` default parameter only covers
+  `undefined`. All adapters now coerce non-object payloads to `{}` (a total function returns an
+  empty profile instead of `TypeError`).
+- **Plaid/MX/Finicity threw on `null` members inside provider arrays** (`accounts`, `holdings`,
+  `positions`, `transactions`, `liabilities.*`, income streams). New `objs()` helper in
+  `src/util.mjs` drops non-object members at every array boundary.
+- **Finicity threw `RangeError: Invalid time value`** on absurd epoch-second dates (beyond the
+  ECMAScript ±8.64e15 ms range) — `finDateIso` now returns `undefined` for out-of-range values.
+- **`toPlanfiPlan` threw on non-object members in a caller-supplied `owner.earners` array** —
+  they are now treated as empty earner contexts (their demographics surface as needsInput asks).
+
+## [0.3.0] — 2026-07-02
+
+### Added
+
+- **CSV adapter (keyless)** — `importToPlan('csv', { files, owner, asOf })`:
+  dependency-free CSV parsing (quoted fields, embedded commas/newlines, CRLF,
+  BOM, unclosed quotes never throw) and a header-fingerprint DIALECTS table:
+  Fidelity positions, Schwab positions, Vanguard downloads, generic accounts,
+  and generic transactions layouts. Money cells handle `$`, thousands commas,
+  and `(1,850.00)` accounting negatives. Files matching no dialect import
+  best-effort with the new **`CSV_UNMAPPED_COLUMNS`** warning code (append-only
+  catalog) naming the skipped columns. Account types classify from a Type
+  column; absent one, name hints are used and ALWAYS surfaced as
+  `CLASSIFICATION_GUESSED`. Transactions files feed the shared contribution
+  inference with the same growth-exclusion rules as the API adapters.
+- **OFX adapter (keyless)** — `importToPlan('ofx', { content, owner, asOf })`:
+  one tolerant dependency-free parser for both OFX 1.x SGML (unclosed leaves)
+  and 2.x XML. Reads BANKMSGSRSV1 (checking/savings/CD/money-market balances;
+  ACCTTYPE CREDITLINE → revolving credit), CREDITCARDMSGSRSV1 (card balances —
+  OFX reports them NEGATIVE; normalized to positive amount owed, tested),
+  INVSTMTMSGSRSV1 (POSSTOCK/POSMF/POSDEBT/POSOTHER positions with SECID →
+  SECLISTMSGSRSV1 ticker/name lookup, UNITS/MKTVAL, INVBAL cash) and
+  INVBANKTRAN deposits for contribution inference (INCOME/dividends excluded
+  as growth). OFX carries no tax-treatment info → investment accounts are
+  taxable at LOW confidence with `CLASSIFICATION_GUESSED`; no cost basis
+  exists in the format (info-noted, never fabricated).
+- **CLI** — `npx planfi-import` (zero-dep, Node ≥ 18, `bin` wired):
+  `demo [--source id]` runs a bundled fixture offline; `validate <payload…>
+  --source <id>` prints structured warnings/needsInput and exits 0 unless the
+  import hard-fails (warnings are diagnostics); `plan <payload…> --source <id>
+  [--token pft_…] [--user-id <id>] [--base <url>]` creates a real plan via
+  `POST /v1/tools/generate_financial_plan` and prints the `plan_id`
+  (`--user-id` is sent as the `X-Planfi-User-Id` end-user attribution header).
+  CSV/OFX payloads are file paths passed directly; `--json` everywhere;
+  colors only on a TTY; unknown args → help + exit 2. Tested via
+  child-process spawns with the `plan` command hitting a node:http mock
+  server, never the real API.
+- Both new adapters are registered in `ADAPTERS`, exported from the package
+  root, typed in `planfi-import.d.ts`, covered by sandbox fixtures + full test
+  files, added to the wire-conformance suite (fixtures round-trip the real
+  monorepo mapper) and to the fuzz suite (hostile/truncated CSV and OFX never
+  throw).
+
+## [0.2.0] — 2026-07-02
+
+### Breaking
+
+- **`needsInput` entries are structured objects**, not strings. Each is
+  `{ field, accountId?, accountName?, earnerIndex?, label, why }` with `field`
+  one of `age | retirement_age | annual_salary | desired_annual_spend |
+  home_value | debt_rate`. Entries are de-duplicated on
+  `(field, accountId, earnerIndex)` and emitted in deterministic order
+  (earner demographics → per-account asks in account order → plan-level goals).
+  Migration: `needsInput.includes('age')` → `needsInput.some(n => n.field === 'age')`;
+  `'home_value:<name>'` prefixes → `n.field === 'home_value'` + `n.accountId`.
+- **`warnings` entries are structured objects**, not strings. Each is
+  `{ code, severity: 'info' | 'warn', message, accountId? }` where `code` is a
+  stable SCREAMING_SNAKE id (see the README warnings catalog). Codes are
+  append-only. Migration: `/regex/.test(w)` → match on `w.code` (or `w.message`).
+- `cfp.meta.warnings` (adapter-level warnings on the canonical profile) carry
+  the same structured shape.
+
+### Added
+
+- **Finicity (Mastercard Open Banking) adapter** — `importToPlan('finicity', …)`
+  with the full Finicity account-type vocabulary (`investmentTaxDeferred`,
+  `529plan`, `homeEquityLoan`, `studentLoan`, …), positions → holdings,
+  transaction-based contribution inference (epoch-second dates handled,
+  dividends/interest excluded), and loan `detail` fields → liability shape.
+  Ships with a synthetic sandbox fixture, a full test file, fuzz coverage, and
+  wire-conformance round-tripping through the real monorepo mapper.
+- **TypeScript declarations** — hand-written `planfi-import.d.ts` covering
+  `importToPlan`, `toPlanfiPlan`, adapters, the CFP, and the new structured
+  result types; wired via the `types` field/export condition. Runtime stays
+  zero-dependency ESM.
+- `classify()` understands `tax-deferred` subtypes (traditional treatment at
+  low confidence) for Finicity's `investmentTaxDeferred`.
+
+### Notes on 0.1.x
+
+- `0.1.0` was the initial release (Plaid + MX). Three wire-mapping bugs in it
+  were fixed on `main` after release, before this version: retirement balances
+  were omitted from the `stocks` total (silently shrinking projections), the
+  package emitted an `hsa_retirement` field that does not exist on the wire,
+  and `education_account` used snake_case keys the engine dropped. `0.2.0` is
+  the first tagged version carrying those fixes — if you are on `0.1.0`,
+  upgrade; do not pin it.
+
+## [0.1.0] — 2026-07-01
+
+- Initial release: canonical model (CFP), Plaid + MX adapters, shared
+  `toPlanfiPlan` mapper, contribution inference, fuzz + fixture tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kameron Kales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# planfi-import
+
+[![tests](https://github.com/holdequity/planfi-import/actions/workflows/test.yml/badge.svg)](https://github.com/holdequity/planfi-import/actions/workflows/test.yml)
+![zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+![node >= 18](https://img.shields.io/badge/node-%E2%89%A5%2018-blue)
+![license MIT](https://img.shields.io/badge/license-MIT-lightgrey)
+
+**Turn raw financial data — an aggregator dump (Plaid, MX, Finicity, FDX) or the CSV/OFX files a
+user can download from any bank — into a [planfi](https://api.planfi.app) financial plan.
+One function call, zero runtime dependencies. Ships a CLI.**
+
+You don't need to know Plaid or planfi to use this. An *aggregator* is a service that, with a
+customer's permission, fetches their real bank/brokerage/loan data as JSON. *planfi* is a financial
+projection engine with a public API: you POST a plan (balances, salaries, debts…) and get back a
+`plan_id` that unlocks 100+ analysis tools (FIRE date, Roth conversions, Monte Carlo backtesting…).
+This package is the bridge between the two.
+
+```
+Plaid ────┐
+MX ───────┤
+Finicity ─┤
+FDX ──────┼─ adapter.normalize() ─► Canonical Financial ─ toPlanfiPlan() ─► wire body ─ POST ─► plan_id
+CSV files ┤   (vocabulary only)      Profile (CFP)          (all domain          (generate_
+OFX files ┘                                                  logic, once)         financial_plan)
+```
+
+Adapters translate each provider's vocabulary into one canonical model; a single shared mapper does
+all the planfi thinking. Adding a provider never means re-writing the domain logic — to write a new
+adapter (human or AI), follow [docs/ADAPTER_GUIDE.md](./docs/ADAPTER_GUIDE.md) (invariants in
+[AGENTS.md](./AGENTS.md)); a generic contract harness (`test/adapter-contract.test.mjs`) enforces
+the guide.
+
+## Quick start (90 seconds)
+
+Install (not yet on npm — install from GitHub):
+
+```bash
+npm install @plan-fi/imports
+```
+
+**1. Import.** Pass the merged responses from your aggregator's endpoints (a bundled sandbox
+fixture works out of the box if you don't have credentials yet):
+
+```js
+import { importToPlan } from '@plan-fi/imports';
+// No Plaid account? Use the bundled fixture: fixtures/plaid-sandbox.mjs
+import { plaidRaw } from '@plan-fi/imports/fixtures/plaid-sandbox.mjs';
+
+const { plan, warnings, needsInput } = importToPlan('plaid', plaidRaw);
+```
+
+The emitted `plan` is a complete `generate_financial_plan` request body (real fixture output,
+trimmed):
+
+```jsonc
+{
+  "name": "Imported plan (plaid)",
+  "earners": [{ "name": "Alex", "age": 41, "annual_salary": 185000,
+                "retirement_accounts": { "k401": { "employee_annual": 21600 } } }, /* … */],
+  "stocks": { "current_value": 680000, "monthly_contribution": 2400, "annual_return": 0.07 },
+  "account_balances": { "taxable": 255000, "traditional": 315000, "roth": 88000 },
+  "real_estate": [{ "current_value": 640000, "mortgage": { "balance": 512000, "rate": 0.0625 } }],
+  "debts": [{ "name": "Student loan", "balance": 28000, "rate": 0.055, "min_payment": 310 }],
+  "education_account": { "enabled": true, "initialBalance": 41000 },
+  "desired_annual_spend": 90000, "tax_settings": { "state": "CA" }
+}
+```
+
+**2. Mint the plan.** POST it to the public planfi API:
+
+```bash
+node -e "import('@plan-fi/imports').then(async ({ importToPlan }) => {
+  const { plaidRaw } = await import('@plan-fi/imports/fixtures/plaid-sandbox.mjs');
+  process.stdout.write(JSON.stringify(importToPlan('plaid', plaidRaw).plan));
+})" > plan.json
+
+curl -X POST https://api.planfi.app/v1/tools/generate_financial_plan \
+  -H 'Content-Type: application/json' \
+  --data @plan.json
+```
+
+```jsonc
+{ "plan_id": "plan_af83…", "fire_age": 58, /* …full projection… */ }
+```
+
+(Anonymous calls get a small free monthly quota; add `-H "Authorization: Bearer $PLANFI_API_TOKEN"`
+with a free API key for more.)
+
+**3. Use it.** You now have a `plan_id` — every planfi tool accepts it
+(`analyze_roth_conversion`, `run_backtesting`, `analyze_fire_number`, …). The connected accounts
+became a living financial plan.
+
+For MX: `importToPlan('mx', { accounts, holdings, transactions, owner, asOf })`.
+For Finicity: `importToPlan('finicity', { accounts, positions, transactions, owner, asOf })`.
+For FDX: `importToPlan('fdx', { accounts, holdings, transactions, owner, asOf })` — accounts may be
+FDX-wrapped (`{ depositAccount: {…} }`) or flattened.
+No aggregator at all? See [Keyless import (CSV / OFX)](#keyless-import-csv--ofx) and the [CLI](#cli).
+Each adapter's file header documents exactly which provider endpoints feed each key.
+`owner` is your onboarding data (ages, goals — see [needsInput](#what-imports-vs-what-you-must-collect)).
+
+## What maps where
+
+| Source (Plaid / MX / Finicity / FDX) | Plan field | What the engine does with it |
+|---|---|---|
+| depository accounts (`checking`, `SAVINGS`, `cd`, …) | `cash.current_value` | Grows at the cash rate; funds spending first |
+| taxable investment (`brokerage`, `INVESTMENT`, `brokerageAccount`) | `stocks.current_value` + `account_balances.taxable` | Projected at `annual_return`; taxed as taxable in decumulation |
+| pre-tax retirement (`401k`, `IRA`, `rollover`, `investmentTaxDeferred`) | `stocks.current_value` + `account_balances.traditional` | In the portfolio total; withdrawn as ordinary income |
+| Roth accounts (`roth`, `ROTH_IRA`) | `stocks.current_value` + `account_balances.roth` | In the portfolio total; withdrawn tax-free |
+| HSA balance | folded into `stocks.current_value` (warned) | No wire HSA-balance field exists — see [limitations](#limitations-honest) |
+| 529 / education (`529`, `529plan`, `educationIRA`) | `education_account.initialBalance` | Dedicated education projection (camelCase inside — engine shape) |
+| mortgage + property (MX `PROPERTY` pairs a real value; Plaid/Finicity/FDX have none → 80%-LTV estimate) | `real_estate[]` with `mortgage {balance, rate, years_remaining}` | Amortizes the loan, appreciates the home at 3.5%/yr |
+| student/auto loans, credit cards | `debts[]` (`balance`, `rate`, `min_payment`) | Paid down in cash flow; APR compounds |
+| crypto holdings (security type) | `speculative[]` at 10% assumed growth | Kept out of the core stock projection |
+| investment transactions (deposits in) | `stocks.monthly_contribution` / `earners[].retirement_accounts.{k401,ira,hsa}` | Inferred savings rates (dividends/interest excluded; IRS-limit clamped) |
+| `owner` context you pass (ages, salary, goals) | `earners[]`, `desired_annual_spend`, `tax_settings.state` | Drives retirement timing and tax math |
+
+Everything else the provider sent lands untouched in `cfp.meta.unmapped` — nothing is silently
+dropped. The full canonical profile (`cfp`) preserves per-holding ticker/shares/cost-basis.
+
+## What imports vs what you must collect
+
+Aggregators know *balances*, not *people*. Anything they can't know arrives in `needsInput` as a
+structured, form-ready ask — with the why:
+
+```jsonc
+// needsInput — real fixture output
+[{
+  "field": "home_value",
+  "accountId": "mtg1",
+  "accountName": "Home mortgage",
+  "label": "Home value for Home mortgage",
+  "why": "The provider reported the mortgage but not the property's market value — currently estimated at 80% LTV."
+}]
+```
+
+| `field` | Why the import can't supply it |
+|---|---|
+| `age`, `retirement_age` | Aggregators report balances, not birthdays or goals (`earnerIndex` says whose) |
+| `annual_salary` | Only payroll-linked products (e.g. Plaid Income) carry it; otherwise ask |
+| `desired_annual_spend` | A retirement-spending goal — no account data implies it |
+| `home_value` | Providers report the *mortgage*, not the home's market value (MX `PROPERTY` is the exception) |
+| `debt_rate` | Some institutions omit the APR; the debt is modeled at 0% (optimistic) until supplied |
+
+Entries are de-duplicated on `(field, accountId, earnerIndex)` and deterministic in order. Collect
+them at onboarding, merge into `owner` (or patch the plan), re-run.
+
+## Warnings catalog
+
+Every judgment call is surfaced as `{ code, severity, message, accountId? }`. Codes are **stable and
+append-only** — switch on them; the human `message` may improve between versions.
+
+| Code | Sev | Meaning → suggested handling |
+|---|---|---|
+| `CLASSIFICATION_GUESSED` | warn | Ambiguous account type; tax treatment guessed → show the account, let the user reclassify |
+| `NO_COST_BASIS` | info | Institution omitted a holding's cost basis → fine for projections; collect before tax-lot analysis |
+| `COARSE_INFERENCE` | warn | Unlabeled deposits counted as contributions → have the user verify savings rates |
+| `CONTRIBUTION_CLAMPED` | warn | Inferred contribution exceeded the IRS limit; clamped → likely a rollover; verify |
+| `CONTRIBUTION_IMPLAUSIBLE` | warn | Inferred savings > 50% of known salary → likely transfers counted; verify |
+| `HSA_FOLDED_INTO_PORTFOLIO` | info | HSA balance modeled inside the aggregate portfolio → no action; see limitations |
+| `HSA_COVERAGE_ASSUMED` | info | HSA coverage type assumed `family` → ask self/family if precision matters |
+| `IRA_SPLIT_ASSUMED` | info | Trad + Roth IRA contributions merged as type `both` (engine models 50/50) → note if lopsided |
+| `HOME_VALUE_ESTIMATED` | warn | Home value estimated at 80% LTV → replace via the `home_value` ask |
+| `MORTGAGE_SKIPPED` | warn | Mortgage had no balance or value; dropped → check the source record |
+| `NEGATIVE_BALANCE_CLAMPED` | warn | Negative *asset* balance clamped to $0 → check for margin/overdraft |
+| `DEBT_RATE_MISSING` | warn | Debt modeled at 0% APR → supply the rate via the `debt_rate` ask |
+| `CSV_UNMAPPED_COLUMNS` | warn | CSV columns matched no dialect mapping; named in the message → rename headers or accept the best-effort import |
+| `CSV_TRANSACTIONS_ONLY` | warn | The file's tool (e.g. YNAB) structurally exports no account balances → pair it with a balances file or collect balances from the user |
+| `IMPORT_EMPTY` | warn | Zero accounts recognized in the payload — almost always a format/shape problem. At batch scale, a systematic export error shows up as this code in the rollup instead of hiding behind ok-counts. |
+
+## Limitations (honest)
+
+- **No catch-up contributions.** Inferred contributions clamp to the base 2026 IRS limits
+  (401k $24,500 / IRA $7,500 / HSA family $8,750); age-50+ catch-ups are not modeled.
+- **Home values estimated at 80% LTV** when the provider has no property record (Plaid, Finicity) —
+  always warned, always asked for.
+- **HSA balances ride inside the portfolio total.** The wire schema has no HSA-balance field; the
+  engine's dedicated `hsaRetirement` block is `NetWorthInput`-only (targeting it is the next hop,
+  alongside per-ticker `individualHoldings`).
+- **IRA `both` = 50/50.** An earner with both traditional and Roth IRA contributions gets one wire
+  block the engine splits evenly, whatever the real split (warned with the real numbers).
+- **Contribution inference is a heuristic.** Transfers and rollovers look like savings in a
+  transaction feed; MX/Finicity credits without labels are counted coarsely (`COARSE_INFERENCE`).
+  Sanity checks (salary %, IRS limits) warn, not fix.
+- **A defined-benefit pension "balance"** is bucketed as a traditional account, low confidence — a
+  coarse stand-in for an income stream.
+- **Keyless formats guess account types.** CSV positions exports and OFX carry no tax-treatment
+  vocabulary — types come from a CSV Type column when present, else the account NAME, else default
+  to taxable; every guess is a `CLASSIFICATION_GUESSED` warning. OFX cost basis doesn't exist in
+  the format; OFX 401(k)-specific records (`INV401K`) and CSV non-US number formats (`1.234,56`)
+  are not parsed.
+
+## Adapters
+
+| Source | `importToPlan(id, …)` | Notes |
+|---|---|---|
+| Plaid | `'plaid'` | accounts + holdings + liabilities + income + investment transactions |
+| MX | `'mx'` | accounts + holdings + transactions; `PROPERTY` gives real home values |
+| Finicity (Mastercard Open Banking) | `'finicity'` | accounts + positions + transactions; epoch-second dates handled |
+| FDX (Financial Data Exchange) | `'fdx'` | the US open-banking standard (CFPB §1033; Akoya speaks it natively); wrapped or flat Account entities, `debitCreditMemo`-aware contribution inference |
+| CSV files | `'csv'` | keyless; dialect table for Fidelity/Schwab/Vanguard positions, Monarch Money, YNAB, Empower/Personal Capital, Copilot Money exports + generic accounts/transactions layouts |
+| OFX files | `'ofx'` | keyless; OFX 1.x SGML and 2.x XML; bank + card + investment message sets |
+
+### Keyless import (CSV / OFX)
+
+No aggregator contract? Every US bank and brokerage still offers **Download → CSV** and most offer
+**Download → Quicken (.ofx/.qfx)**. The `csv` and `ofx` adapters turn those files into the same
+canonical profile — same mapper, same warnings, same `needsInput` asks:
+
+```js
+import { importToPlan } from '@plan-fi/imports';
+import { readFileSync } from 'node:fs';
+
+// CSV: any mix of files; the header fingerprint picks the dialect per file
+const { plan, warnings } = importToPlan('csv', {
+  files: [
+    { name: 'fidelity-positions.csv', content: readFileSync('fidelity-positions.csv', 'utf8') },
+    { name: 'accounts.csv', content: readFileSync('accounts.csv', 'utf8') },
+  ],
+  owner: { age: 39, retirementAge: 60, annualSalary: 165000 },
+});
+
+// OFX: one statement file (SGML or XML — both parse)
+importToPlan('ofx', { content: readFileSync('statement.ofx', 'utf8'), owner: { age: 45 } });
+```
+
+Recognized CSV dialects — brokerages: **Fidelity positions** (Account Number/Account Name/Symbol/…/
+Cost Basis Total), **Schwab positions** (Symbol/Description/Qty/Price/Mkt Val/Cost Basis),
+**Vanguard downloads** (Account Number/Investment Name/Symbol/Shares/Share Price/Total Value).
+Consumer finance tools: **Monarch Money** balances (Date/Account/Account Type/Institution/Balance —
+a balance HISTORY, collapsed to the newest row per account, never summed) and transactions
+(Date/Merchant/Category/…/Amount; the "Dividends & Capital Gains" category is excluded as growth),
+**YNAB** register (Account/…/Outflow/Inflow pair — transactions ONLY: YNAB structurally exports no
+balances, so the import says so with `CSV_TRANSACTIONS_ONLY` and expects a balances file alongside),
+**Empower / Personal Capital** holdings (Account/Ticker/Name/Shares/Price/Value; the export carries
+no cost basis → `NO_COST_BASIS` per holding), and **Copilot Money** transactions
+(community-documented format; its inverted sign convention — spending positive — is flipped). Plus
+**generic accounts** (Account Name/Type/Balance + optional Interest Rate/Minimum Payment) and
+**generic transactions** (Account/Date/Amount/Description) layouts — Copilot's accounts export
+fingerprints as generic accounts by design. Files matching no dialect import best-effort with a
+`CSV_UNMAPPED_COLUMNS` warning naming what was skipped. Money cells handle `$`, thousands commas,
+and accounting-style `(1,850.00)` negatives.
+
+Keyless honesty (both formats carry less signal than an API — the gaps are surfaced, not papered
+over): positions CSVs and OFX carry **no tax-treatment info**, so account types are guessed
+(from a Type column when present, else the account name) and every guess is a
+`CLASSIFICATION_GUESSED` warning; OFX reports **card balances negative** — normalized to positive
+amount owed; OFX positions carry **no cost basis** (noted, never fabricated); contribution
+inference uses the same growth-exclusion rules as every other adapter.
+
+## CLI
+
+The package ships a zero-dependency CLI (Node ≥ 18):
+
+```bash
+npx @plan-fi/imports demo --source csv          # run a bundled sandbox fixture, no network
+npx @plan-fi/imports validate accounts.csv --source csv          # your files, structured diagnostics
+npx @plan-fi/imports validate statement.ofx --source ofx --json  # machine-readable output
+npx @plan-fi/imports validate payload.json --source plaid        # API-shaped sources take one .json
+npx @plan-fi/imports plan accounts.csv --source csv --token pft_… [--user-id u123]  # create a REAL plan
+npx @plan-fi/imports batch ./payloads --source plaid --token pft_…  # bulk-load THOUSANDS of customers
+```
+
+- `demo` prints the plan + warnings + needsInput for a bundled fixture (colors only on a TTY).
+- `validate` runs `importToPlan` on your payload and exits **0 even with warnings** (they are
+  diagnostics, not failures); a hard failure (unreadable file, bad JSON, unknown source) exits 1.
+- `plan` POSTs the emitted body to `POST /v1/tools/generate_financial_plan` and prints the
+  `plan_id`. `--base` overrides the API host. `--user-id <id>` is sent as the `X-Planfi-User-Id`
+  header: the API token identifies your (partner) tenant, while `X-Planfi-User-Id` attributes the
+  plan and its usage to a specific end user within that tenant — optional, partner-supplied.
+- `batch` drives the managed `import_financial_data_batch` endpoint (25 items per call) over a
+  directory of `<user_id>.json` payload files (**filename stem = `user_id`**) or an `.ndjson`
+  file with `{"user_id", "payload"[, "plan_name", "source"]}` per line. Every item carries its
+  own `user_id`, and **(your account, `user_id`) is a stable upsert identity** — re-importing a
+  customer *updates* their plan (same `plan_id`) instead of duplicating it, so the whole run is
+  **safe to re-run**. 5,000 customers = 200 requests; `--concurrency 4` (default) finishes in
+  ~10 minutes at typical latencies.
+  - Writes a **resume manifest / results file** next to the input
+    (`<input>.planfi-manifest.json`, or `--resume <path>`): per-customer `ok` / `plan_id` /
+    `updated` / `error`, plus **full `needsInput` objects** (`field`, `label`, `accountId`) for
+    building collection worklists. A re-run skips customers already imported ok.
+  - **Partial failure never stops the run** — a malformed file or a rejected payload is recorded
+    and the rest continue. The final report prints ok/failed counts plus the missing-data rollup
+    (needsInput field → customers). Exit 0 all-ok, 1 if any item failed.
+  - `--batch-size N` (≤ 25) tunes items per call; `--single` sends one `import_financial_data`
+    call per item instead of the batch endpoint.
+- `--json` on every command for machine output; unknown commands/flags print help and exit 2.
+
+## Testing
+
+```bash
+npm install   # dev deps for the conformance test only — runtime stays zero-dep
+npm test      # node --test: fixtures, CLI spawns, the generic adapter-contract harness,
+              # fuzz (6×3000 randomized/hostile payloads), wire conformance
+npm run demo  # print the full ImportResult built from the Plaid sandbox fixture
+```
+
+`test/adapter-contract.test.mjs` is the generic floor: it discovers every adapter in `ADAPTERS`
+and runs the identical battery (structural CFP validity, cataloged warning codes, hostile inputs
+never throw, determinism, fixture registered for wire-conformance). It is the executable version
+of the checklist in [docs/ADAPTER_GUIDE.md](./docs/ADAPTER_GUIDE.md).
+
+Inside the planfi-app monorepo, `test/wire-conformance.test.mjs` round-trips every fixture through
+the **real** engine mapper and asserts each emitted field is consumed (in this standalone repo that
+test skips loudly; the monorepo CI enforces it).
+
+## Versioning
+
+SemVer, pre-1.0 (minor bumps may break — see [CHANGELOG.md](./CHANGELOG.md)). v0.2.0 made
+`warnings`/`needsInput` structured objects and added Finicity; warning **codes** are append-only
+from here. TypeScript types ship in `planfi-import.d.ts`.
+
+## License
+
+MIT.