@firela/api-types 0.0.0-canary.6a42fd0e → 0.0.0-canary.6af2ffd3

package/src/generated/schemas.gen.ts

@@ -6,18 +6,12 @@ export const $CreateAccountDto = {
     path: {
       type: 'string',
       description: 'Account path (hierarchical, colon-separated)',
-      example: 'Assets:CN:Bank:ICBC:Checking'
-    },
-    displayName: {
-      type: 'string',
-      description:
-        'Display name to distinguish accounts at the same path (default: "")',
-      example: '工资卡'
+      example: 'Assets:CN:ICBC:Checking'
     },
     openDate: {
       format: 'date-time',
       type: 'string',
-      description: 'Account open date',
+      description: 'Account open date (server defaults to today)',
       example: '2024-01-01'
     },
     currencies: {
@@ -45,26 +39,30 @@ export const $CreateAccountDto = {
     templatePath: {
       type: 'string',
       description: 'Reference to account-standards template path',
-      example: 'Assets:CN:Bank:ICBC:Checking'
+      example: 'Assets:CN:Checking'
     },
     isCustom: {
       type: 'boolean',
       description: 'Whether this is a custom (user-created) account',
       default: false
     },
-    i18nKey: {
-      type: 'string',
-      description: 'i18n key for display name (overrides template)',
-      example: 'account.custom.mybank'
-    },
     icon: {
       type: 'string',
       description: 'Icon identifier (overrides template)',
       example: 'bank-custom'
     },
-    openMeta: {
+    displayName: {
+      type: 'string',
+      description:
+        'User-set display name override (omit/null = keep the derived name)',
+      nullable: true,
+      maxLength: 50,
+      example: 'Salary card'
+    },
+    openDirectiveMeta: {
       type: 'object',
-      description: 'Additional metadata',
+      description:
+        'Open directive metadata (NOT an opening-balance amount — use the opening-balance endpoint)',
       example: {
         branch: 'Downtown',
         accountNumber: '1234'
@@ -76,7 +74,7 @@ export const $CreateAccountDto = {
       example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
     }
   },
-  required: ['path', 'openDate']
+  required: ['path']
 } as const;
 
 export const $AccountResponseDto = {
@@ -90,13 +88,7 @@ export const $AccountResponseDto = {
     path: {
       type: 'string',
       description: 'Account path (hierarchical, colon-separated)',
-      example: 'Assets:CN:Bank:ICBC:Checking'
-    },
-    displayName: {
-      type: 'string',
-      description:
-        'Display name distinguishing multiple accounts at the same path',
-      example: '工资卡'
+      example: 'Assets:CN:ICBC:Checking'
     },
     type: {
       type: 'string',
@@ -104,6 +96,49 @@ export const $AccountResponseDto = {
       enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
       example: 'Assets'
     },
+    assetSubClass: {
+      type: 'string',
+      description:
+        'Account-level asset sub-class (product type, e.g. STOCK/DEPOSIT/CREDIT_CARD/PERSONAL_LOAN). Computed from the account path via the asset-classifier (ADR-0077). Null for non-asset accounts (Income/Expenses/Equity) or unmatched paths.',
+      enum: [
+        'DEPOSIT',
+        'CASH',
+        'MONEY_MARKET_FUND',
+        'STOCK',
+        'ETF',
+        'MUTUAL_FUND',
+        'EQUITY_COMPENSATION',
+        'GOVERNMENT_BOND',
+        'CORPORATE_BOND',
+        'BOND_FUND',
+        'PRIMARY_RESIDENCE',
+        'INVESTMENT_PROPERTY',
+        'REIT',
+        'GOLD',
+        'SILVER',
+        'PRECIOUS_METAL',
+        'PRECIOUS_METAL_FUND',
+        'COMMODITY',
+        'COMMODITY_FUND',
+        'CRYPTOCURRENCY',
+        'RETIREMENT_ACCOUNT',
+        'HEALTH_ACCOUNT',
+        'EDUCATION_ACCOUNT',
+        'INSURANCE',
+        'PRIVATE_EQUITY',
+        'HEDGE_FUND',
+        'COLLECTIBLES',
+        'MORTGAGE',
+        'STUDENT_LOAN',
+        'CREDIT_CARD',
+        'PERSONAL_LOAN',
+        'ACCOUNTS_PAYABLE',
+        'TAX_PAYABLE',
+        'OTHER'
+      ],
+      nullable: true,
+      example: 'STOCK'
+    },
     status: {
       type: 'string',
       description: 'Account status',
@@ -145,32 +180,33 @@ export const $AccountResponseDto = {
     templatePath: {
       type: 'string',
       description: 'Template path reference',
-      example: 'Assets:CN:Bank:ICBC:Checking'
+      example: 'Assets:CN:Checking'
     },
     isCustom: {
       type: 'boolean',
       description: 'Whether this is a custom (user-created) account',
       example: false
     },
-    i18nKey: {
+    displayName: {
       type: 'string',
-      description: 'i18n key for display name',
-      example: 'account.assets.cn.bank.icbc.checking'
+      description:
+        'Display name with precedence: user-set name (#762) > ADR-0114 localized name > path leaf (read-time projection)',
+      example: 'Checking'
     },
     icon: {
       type: 'string',
       description: 'Icon identifier',
       example: 'bank-icbc'
     },
-    openMeta: {
+    openDirectiveMeta: {
       type: 'object',
-      description: 'Account metadata',
+      description: 'Open directive metadata (ADR-0115 Decision 9)',
       example: {
         branch: 'Downtown'
       }
     },
     platformId: {
-      type: 'object',
+      type: 'string',
       description: 'Platform ID (null if unbound)',
       example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
     },
@@ -192,7 +228,6 @@ export const $AccountResponseDto = {
   required: [
     'id',
     'path',
-    'displayName',
     'type',
     'status',
     'openDate',
@@ -225,11 +260,6 @@ export const $AccountListResponseDto = {
 export const $UpdateAccountDto = {
   type: 'object',
   properties: {
-    displayName: {
-      type: 'string',
-      description: 'Display name to distinguish accounts at the same path',
-      example: '招行工资卡'
-    },
     currencies: {
       description: 'Allowed currencies (null = no restriction)',
       example: ['CNY', 'USD'],
@@ -251,19 +281,23 @@ export const $UpdateAccountDto = {
         'NONE'
       ]
     },
-    i18nKey: {
-      type: 'string',
-      description: 'i18n key for display name',
-      example: 'account.custom.mybank'
-    },
     icon: {
       type: 'string',
       description: 'Icon identifier',
       example: 'bank-custom'
     },
-    openMeta: {
+    displayName: {
+      type: 'string',
+      description:
+        'User-set display name override (null = clear the override and fall back to the derived name, omit = unchanged)',
+      nullable: true,
+      maxLength: 50,
+      example: 'Salary card'
+    },
+    openDirectiveMeta: {
       type: 'object',
-      description: 'Additional metadata (merged with existing)',
+      description:
+        'Open directive metadata (merged with existing; NOT an opening-balance amount)',
       example: {
         branch: 'Uptown'
       }
@@ -310,13 +344,47 @@ export const $ReopenAccountDto = {
   }
 } as const;
 
+export const $CreateOpeningBalanceDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'number',
+      description: 'Opening balance amount (non-negative)',
+      example: 1000
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    date: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Opening-balance date (defaults to now)',
+      example: '2024-01-01'
+    }
+  },
+  required: ['amount', 'currency']
+} as const;
+
+export const $OpeningBalanceResultDto = {
+  type: 'object',
+  properties: {
+    transactionId: {
+      type: 'string',
+      description: 'Created opening-balance transaction id.'
+    }
+  },
+  required: ['transactionId']
+} as const;
+
 export const $AccountStandardResponseDto = {
   type: 'object',
   properties: {
     path: {
       type: 'string',
       description: 'Account path (hierarchical, colon-separated)',
-      example: 'Assets:CN:Bank:ICBC:Checking'
+      example: 'Assets:CN:Checking'
     },
     type: {
       type: 'string',
@@ -324,23 +392,45 @@ export const $AccountStandardResponseDto = {
       enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
       example: 'Assets'
     },
-    i18nKey: {
-      type: 'string',
-      description: 'i18n key for localized display name',
-      example: 'account.assets.cn.bank.icbc.checking'
-    },
     name: {
       type: 'string',
-      description: 'Short localized display name',
+      description:
+        'Short display name. Universal rows project to the request locale (Accept-Language); regional rows keep the authored native name — mixed-language by design (ADR-0131 class P vs class A).',
       example: 'Housing Fund'
     },
+    aliases: {
+      description:
+        'Authored market-language alternative names delivered verbatim (not localized copy, not xlf-managed, not locale-projected). Flat string[] per ADR-0129 D1; ADR-0131 class A.',
+      example: ['Alipay', 'WeChat Pay'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    searchTerms: {
+      description:
+        'Locale-projected search synonyms (e.g. the zh bank-card / debit-card everyday terms for the checking account). Pure-locale projection — absent when the locale has no seeded synonyms; English fallback rides the authored aliases field. Search-only vocabulary, not the NLP routing corpus (#698, ADR-0131 fourth-class adjudication).',
+      example: ['yinhangka', 'jiejika'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    currency: {
+      type: 'string',
+      description:
+        'Product denomination as a 3-letter ISO 4217 code, authored market data delivered verbatim (not localized, not xlf-managed). ADR-0131 class A. Absent = single-currency not asserted — consumers fall back to their own region currency (#714).',
+      example: 'HKD'
+    },
     description: {
       type: 'string',
-      description: 'Account description (stable semantics only)',
+      description:
+        'Account description (stable semantics only). Mixed-language contract: universal rows project to the request locale via the accountDesc xlf axis with an en fallback (ADR-0131 class P, ADR-0132; unseeded locales falling back to English are expected); regional rows deliver the authored market language (ADR-0131 class A, verbatim, never xlf-managed).',
       example: 'ICBC checking account for daily transactions'
     },
     tags: {
-      description: 'Account tags for categorization',
+      description:
+        'Account tags for categorization — structured metadata delivered verbatim (not localized, not xlf-managed). ADR-0131 class A.',
       example: ['bank', 'checking', 'primary'],
       type: 'array',
       items: {
@@ -351,9 +441,47 @@ export const $AccountStandardResponseDto = {
       type: 'string',
       description: 'Icon identifier for UI display',
       example: 'bank-icbc'
+    },
+    productCategory: {
+      type: 'string',
+      description:
+        'Onboarding product category (coarse grouping derived from assetSubClass)',
+      enum: [
+        'cash',
+        'investment',
+        'credit_card',
+        'loan',
+        'payable_tax',
+        'other'
+      ],
+      example: 'investment'
+    },
+    assetClass: {
+      type: 'string',
+      description:
+        'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
+      enum: [
+        'LIQUIDITY',
+        'EQUITY',
+        'FIXED_INCOME',
+        'PRECIOUS_METALS',
+        'COMMODITY',
+        'INSURANCE',
+        'ALTERNATIVE_INVESTMENT',
+        'PERSONAL_ASSETS',
+        'LIABILITY',
+        'REAL_ESTATE',
+        'INDEX'
+      ]
+    },
+    assetSubClass: {
+      type: 'string',
+      description:
+        'Asset sub-class (product type, derived at read time from classification rules)',
+      example: 'STOCK'
     }
   },
-  required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
+  required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
 } as const;
 
 export const $AccountStandardListResponseDto = {
@@ -383,18 +511,13 @@ export const $AccountStandardListResponseDto = {
 export const $TemplateMetadataDto = {
   type: 'object',
   properties: {
-    extendable: {
-      type: 'boolean',
-      description: 'Whether this path can be extended',
-      example: true
-    },
     rootType: {
       type: 'string',
       description: 'Root account type',
       example: 'Assets'
     }
   },
-  required: ['extendable', 'rootType']
+  required: ['rootType']
 } as const;
 
 export const $TemplateMetadataResponseDto = {
@@ -419,7 +542,10 @@ export const $RegionConfigDto = {
     },
     locale: {
       type: 'string',
-      example: 'de-DE'
+      example: 'de-DE',
+      pattern: '^[a-z]{2,8}-[A-Z]{2}$',
+      description:
+        "Region-qualified BCP-47 tag whose region subtag equals the region's own ISO 3166-1 code (e.g., ja-JP, zh-CN, zh-HK)"
     }
   },
   required: ['currency', 'dateFormat', 'locale']
@@ -432,6 +558,12 @@ export const $RegionInfoDto = {
       type: 'string',
       example: 'de'
     },
+    open: {
+      type: 'boolean',
+      example: true,
+      description:
+        'Whether the region is open (has a ready regional account template). Not-yet-open regions still return identity metadata and degrade to the universal-only catalog.'
+    },
     displayName: {
       type: 'string',
       example: 'Germany'
@@ -450,7 +582,7 @@ export const $RegionInfoDto = {
       $ref: '#/components/schemas/RegionConfigDto'
     }
   },
-  required: ['code', 'displayName', 'chain', 'config']
+  required: ['code', 'open', 'displayName', 'chain', 'config']
 } as const;
 
 export const $RegionsMetadataResponseDto = {
@@ -533,7 +665,7 @@ export const $CreatePostingDto = {
       type: 'string',
       description:
         'Account name in Beancount format (must start with uppercase, colon-separated)',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     units: {
       type: 'string',
@@ -692,12 +824,12 @@ export const $PostingResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     units: {
       type: 'string',
       description:
-        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
+        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.',
       example: '100.50'
     },
     currency: {
@@ -1058,12 +1190,12 @@ export const $PostingDetailDto = {
     account: {
       type: 'string',
       description: 'Fully-qualified Beancount account path',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     units: {
       type: 'string',
       description:
-        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
+        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.',
       example: '100.50'
     },
     currency: {
@@ -1247,93 +1379,254 @@ export const $TransactionDetailDto = {
   ]
 } as const;
 
-export const $BalanceByCurrencyDto = {
+export const $TransactionListItemDto = {
   type: 'object',
   properties: {
-    currency: {
+    id: {
       type: 'string',
-      description: 'ISO 4217 currency code',
-      example: 'CNY'
+      description: 'Transaction ID',
+      example: 'clh1234567890abcdef'
     },
-    balance: {
-      type: 'string',
-      description: 'Balance amount',
-      example: '50000.00'
-    }
-  },
-  required: ['currency', 'balance']
-} as const;
-
-export const $ExchangeRateWarningDto = {
-  type: 'object',
-  properties: {
-    type: {
+    date: {
       type: 'string',
-      description: 'Warning type',
-      example: 'MISSING_EXCHANGE_RATE'
+      description: 'Transaction date',
+      example: '2024-11-28'
     },
-    currency: {
+    flag: {
       type: 'string',
-      description: 'Currency without exchange rate',
-      example: 'EUR'
+      description: 'Transaction flag',
+      enum: [
+        'CLEARED',
+        'PENDING',
+        'PADDING',
+        'SUMMARIZE',
+        'TRANSFER',
+        'CONVERSIONS'
+      ],
+      example: 'CLEARED'
     },
-    totalAmount: {
+    customFlag: {
       type: 'string',
-      description: 'Total amount affected',
-      example: '1000.00'
-    }
-  },
-  required: ['type', 'currency', 'totalAmount']
-} as const;
-
-export const $TransactionListSummaryDto = {
-  type: 'object',
-  properties: {
-    totalAmount: {
+      description: 'Custom flag (if not using standard flags)',
+      example: 'R'
+    },
+    payee: {
       type: 'string',
-      description:
-        'Partial converted total in base currency (rated currencies only, raw Beancount sign). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.',
-      example: '-6000.00'
+      description: 'Payee name',
+      example: 'Whole Foods Market'
     },
-    currency: {
+    narration: {
       type: 'string',
-      description: 'Base currency (ISO 4217)',
-      example: 'CNY'
+      description: 'Transaction narration',
+      example: 'Grocery shopping'
     },
-    balanceByCurrency: {
-      description: 'Raw (unconverted) balance per currency',
+    tags: {
+      description: 'Transaction tags',
+      example: ['groceries'],
       type: 'array',
       items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
+        type: 'string'
       }
     },
-    warnings: {
-      description: 'Currencies missing an FX rate (omitted when empty)',
+    links: {
+      description: 'Transaction links',
+      example: ['invoice-2024-001'],
       type: 'array',
       items: {
-        $ref: '#/components/schemas/ExchangeRateWarningDto'
+        type: 'string'
       }
-    }
-  },
-  required: ['totalAmount', 'currency', 'balanceByCurrency']
-} as const;
-
-export const $TransactionListResponseDto = {
-  type: 'object',
-  properties: {
-    data: {
-      description: 'List of transactions',
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction metadata'
+    },
+    status: {
+      type: 'string',
+      description: 'Transaction status',
+      enum: ['ACTIVE', 'VOIDED', 'SUPERSEDED'],
+      example: 'ACTIVE'
+    },
+    sourceType: {
+      type: 'string',
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)',
+      example: 'alipay'
+    },
+    postings: {
+      description: 'Transaction postings',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/TransactionDetailDto'
+        $ref: '#/components/schemas/PostingDetailDto'
       }
     },
-    total: {
-      type: 'number',
-      description: 'Total count of matching transactions',
-      example: 100
+    createdAt: {
+      type: 'string',
+      description: 'Created at timestamp',
+      example: '2024-11-28T10:30:00.000Z'
     },
-    limit: {
+    voidedAt: {
+      type: 'string',
+      description: 'Voided at timestamp (if voided)',
+      example: '2024-11-29T15:00:00.000Z'
+    },
+    voidedBy: {
+      type: 'string',
+      description: 'User ID who voided this transaction',
+      example: 'clh1234567890abcdef'
+    },
+    correctionReason: {
+      type: 'string',
+      description: 'Correction reason (if voided or superseded)',
+      example: 'Duplicate entry'
+    },
+    supersededBy: {
+      type: 'string',
+      description:
+        'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
+      example: 'clh1234567890abcdef'
+    },
+    originalTxn: {
+      type: 'string',
+      description:
+        'ID of the transaction this one corrected/replaced (back-link on the replacement)',
+      example: 'clh1234567890abcdef'
+    },
+    viewpointAmount: {
+      type: 'string',
+      description:
+        'Row amount under the request viewpoint (ADR-0126). Category viewpoint (category + flow): per-leg sign-normalized sum over the category account set (Income-root legs negated, Expenses-root identity) — positive under normal booking but NOT clamped (explicit negative expense legs and net-flip refund months stay negative). No viewpoint (plain list / search, no accountId): wallet money-flow net = raw-sign sum over cost-less Assets/Liabilities legs (income positive, expenses negative, transfers net ~0); color cue is the wallet sign (net < 0 = wealth-decreasing). Status-orthogonal: audit views match too (ADR-0128 amount-as-matching-key). Omitted under the account viewpoint (incl. dual) and for rows with no wallet leg.',
+      example: '10000.00'
+    },
+    viewpointCurrency: {
+      type: 'string',
+      description:
+        'Currency of viewpointAmount. A row spanning multiple currencies takes the largest-magnitude currency group (known simplification, ADR-0126).',
+      example: 'CNY'
+    }
+  },
+  required: [
+    'id',
+    'date',
+    'narration',
+    'tags',
+    'links',
+    'status',
+    'postings',
+    'createdAt'
+  ]
+} as const;
+
+export const $BalanceByCurrencyDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'ISO 4217 currency code',
+      example: 'CNY'
+    },
+    balance: {
+      type: 'string',
+      description: 'Balance amount',
+      example: '50000.00'
+    }
+  },
+  required: ['currency', 'balance']
+} as const;
+
+export const $ExchangeRateWarningDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_EXCHANGE_RATE'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency without exchange rate',
+      example: 'EUR'
+    },
+    totalAmount: {
+      type: 'string',
+      description: 'Total amount affected',
+      example: '1000.00'
+    }
+  },
+  required: ['type', 'currency', 'totalAmount']
+} as const;
+
+export const $TransactionListSummaryDto = {
+  type: 'object',
+  properties: {
+    totalAmount: {
+      type: 'string',
+      description:
+        'Partial converted total in base currency (rated currencies only). Sign by viewpoint (ADR-0126): account viewpoint keeps the raw Beancount sign (income negative); category viewpoint is per-leg sign-normalized (Income legs negated, Expenses legs identity — positive under normal booking, not clamped). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.',
+      example: '-6000.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency (ISO 4217)',
+      example: 'CNY'
+    },
+    balanceByCurrency: {
+      description: 'Raw (unconverted) balance per currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    warnings: {
+      description: 'Currencies missing an FX rate (omitted when empty)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['totalAmount', 'currency', 'balanceByCurrency']
+} as const;
+
+export const $TransactionListViewpointDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description:
+        'Viewpoint type (only category drill-down carries a viewpoint today)',
+      enum: ['category'],
+      example: 'category'
+    },
+    flow: {
+      type: 'string',
+      description: 'Flow root the category account set is restricted to',
+      enum: ['income', 'expense'],
+      example: 'expense'
+    }
+  },
+  required: ['type', 'flow']
+} as const;
+
+export const $TransactionListResponseDto = {
+  type: 'object',
+  properties: {
+    data: {
+      description: 'List of transactions',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TransactionListItemDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total count of matching transactions',
+      example: 100
+    },
+    limit: {
       type: 'number',
       description: 'Number of items per page',
       example: 20
@@ -1351,6 +1644,15 @@ export const $TransactionListResponseDto = {
           $ref: '#/components/schemas/TransactionListSummaryDto'
         }
       ]
+    },
+    viewpoint: {
+      description:
+        'Viewpoint metadata (ADR-0126). Present only for a single category filter (category + flow, no accountId); dual-perspective requests are viewpoint-less (raw signs, no viewpointAmount).',
+      allOf: [
+        {
+          $ref: '#/components/schemas/TransactionListViewpointDto'
+        }
+      ]
     }
   },
   required: ['data', 'total', 'limit', 'offset']
@@ -1450,7 +1752,7 @@ export const $BalanceResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     balance: {
       type: 'string',
@@ -1477,7 +1779,7 @@ export const $MultiCurrencyBalanceResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     balances: {
       type: 'object',
@@ -1533,7 +1835,7 @@ export const $TransactionSummaryDto = {
     accountName: {
       type: 'string',
       description: 'Source account name (first posting)',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     sourceType: {
       type: 'string',
@@ -1702,13 +2004,17 @@ export const $ReviewStatsDto = {
       type: 'object',
       description: 'Count by type'
     },
+    resolved: {
+      type: 'number',
+      description: 'Current count of reviews in RESOLVED status'
+    },
     oldestPending: {
       format: 'date-time',
       type: 'string',
       description: 'Oldest pending review date'
     }
   },
-  required: ['total', 'byType']
+  required: ['total', 'byType', 'resolved']
 } as const;
 
 export const $DecisionOptionDto = {
@@ -2261,10 +2567,10 @@ export const $UpdatePayeeDto = {
     meta: {
       type: 'object',
       description:
-        'Metadata for extended information (location, notes, contact info, etc.). Will merge with existing metadata.',
+        'Metadata for extended information (location, notes, contact info, etc.)',
       example: {
         location: 'Zhongguancun',
-        note: 'Updated note',
+        note: 'Near subway station',
         favorite: true
       }
     },
@@ -2825,106 +3131,385 @@ export const $UpdateCommodityDto = {
   }
 } as const;
 
-export const $CreateBeanPriceDto = {
+export const $CurrencyBalanceDto = {
   type: 'object',
   properties: {
     currency: {
       type: 'string',
-      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
-      example: 'USD'
-    },
-    quoteCurrency: {
-      type: 'string',
-      description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
+      description: 'ISO 4217 currency code',
       example: 'CNY'
     },
-    amount: {
-      type: 'number',
-      description:
-        'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
-      example: 175.5,
-      minimum: 0
-    },
-    date: {
+    balance: {
       type: 'string',
-      description: 'Price date (ISO 8601 format)',
-      example: '2024-11-05'
-    },
-    metadata: {
-      type: 'object',
-      description:
-        'Metadata (validated by Zod schema, max field lengths enforced)',
-      example: {
-        source: 'MANUAL',
-        note: 'Bank valuation report',
-        confidence: 0.95
-      }
+      description: 'Balance amount',
+      example: '500000.00'
     }
   },
-  required: ['currency', 'quoteCurrency', 'amount', 'date']
+  required: ['currency', 'balance']
 } as const;
 
-export const $PriceResponseDto = {
+export const $TimeSeriesPointDto = {
   type: 'object',
   properties: {
-    id: {
+    date: {
       type: 'string',
-      description: 'Unique identifier',
-      example: 'uuid-123-456'
+      description: 'Date in YYYY-MM-DD format',
+      example: '2024-06-15'
     },
-    userId: {
+    value: {
       type: 'string',
-      description: 'User ID (owner of the price)',
-      example: 'user-123'
+      description: 'Value at this date (in base currency)',
+      example: '500000.00'
     },
-    currency: {
+    change: {
       type: 'string',
-      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
-      example: 'BTC'
+      description: 'Change from previous point',
+      example: '5000.00'
     },
-    quoteCurrency: {
+    assets: {
       type: 'string',
-      description: 'Quote currency (pricing currency, e.g., USD, CNY)',
-      example: 'USD'
-    },
-    amount: {
-      type: 'number',
-      description:
-        'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
-      example: 50000
+      description: 'Total assets at this date (in base currency)',
+      example: '494338.00'
     },
-    date: {
+    liabilities: {
       type: 'string',
-      description:
-        'Price date (ISO 8601 format). Represents the date this price was valid.',
-      example: '2024-01-01',
-      format: 'date'
+      description: 'Total liabilities at this date (in base currency)',
+      example: '310098.00'
     },
-    meta: {
-      type: 'object',
-      description:
-        'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
-      example: {
-        source: 'MANUAL',
-        note: 'User-defined price',
-        confidence: 1
+    byCurrency: {
+      description: 'Multi-currency breakdown for this point',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CurrencyBalanceDto'
       }
-    },
-    createdAt: {
-      format: 'date-time',
-      type: 'string',
-      description: 'Creation timestamp',
-      example: '2024-11-03T10:00:00Z'
-    },
-    updatedAt: {
-      format: 'date-time',
-      type: 'string',
-      description: 'Last update timestamp',
-      example: '2024-11-03T10:00:00Z'
     }
   },
-  required: [
-    'id',
+  required: ['date', 'value']
+} as const;
+
+export const $TrendSummaryDto = {
+  type: 'object',
+  properties: {
+    startValue: {
+      type: 'string',
+      description: 'Value at start of period',
+      example: '450000.00'
+    },
+    endValue: {
+      type: 'string',
+      description: 'Value at end of period',
+      example: '500000.00'
+    },
+    totalChange: {
+      type: 'string',
+      description: 'Total change over period',
+      example: '50000.00'
+    },
+    totalChangePercentage: {
+      type: 'string',
+      description: 'Total change percentage',
+      example: '+11.11%'
+    }
+  },
+  required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
+} as const;
+
+export const $MultiCurrencyPointDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Date in YYYY-MM-DD format',
+      example: '2024-06-15'
+    },
+    byCurrency: {
+      description: 'Balances by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CurrencyBalanceDto'
+      }
+    }
+  },
+  required: ['date', 'byCurrency']
+} as const;
+
+export const $PortfolioTrendsResponseDto = {
+  type: 'object',
+  properties: {
+    series: {
+      description: 'Time series data points',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TimeSeriesPointDto'
+      }
+    },
+    summary: {
+      description: 'Period summary',
+      allOf: [
+        {
+          $ref: '#/components/schemas/TrendSummaryDto'
+        }
+      ]
+    },
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '6m'
+    },
+    granularity: {
+      type: 'string',
+      description: 'Data granularity',
+      example: 'month'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    byCurrency: {
+      description:
+        'Multi-currency time series (each point has currency breakdown)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/MultiCurrencyPointDto'
+      }
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['series', 'summary', 'period', 'granularity', 'currency']
+} as const;
+
+export const $CashFlowPointDto = {
+  type: 'object',
+  properties: {
+    month: {
+      type: 'string',
+      description: 'Month key (YYYY-MM)',
+      example: '2024-03'
+    },
+    income: {
+      type: 'string',
+      description: 'Income in base currency (absolute, converted)',
+      example: '10000.00'
+    },
+    expense: {
+      type: 'string',
+      description: 'Expense in base currency (absolute, converted)',
+      example: '5000.00'
+    },
+    netSavings: {
+      type: 'string',
+      description: 'netSavings = income − expense (savings positive)',
+      example: '5000.00'
+    }
+  },
+  required: ['month', 'income', 'expense', 'netSavings']
+} as const;
+
+export const $CashFlowTrendSummaryDto = {
+  type: 'object',
+  properties: {
+    totalIncome: {
+      type: 'string',
+      description: 'Total income across the period',
+      example: '60000.00'
+    },
+    totalExpense: {
+      type: 'string',
+      description: 'Total expense across the period',
+      example: '30000.00'
+    },
+    totalNetSavings: {
+      type: 'string',
+      description: 'income − expense across the period',
+      example: '30000.00'
+    },
+    averageMonthlyNetSavings: {
+      type: 'string',
+      description:
+        'totalNetSavings divided by the window length (N months, incl. zero-filled)',
+      example: '5000.00'
+    }
+  },
+  required: [
+    'totalIncome',
+    'totalExpense',
+    'totalNetSavings',
+    'averageMonthlyNetSavings'
+  ]
+} as const;
+
+export const $CashFlowTrendsResponseDto = {
+  type: 'object',
+  properties: {
+    series: {
+      description:
+        'Monthly cash-flow series (fixed N-month window, zero-filled)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CashFlowPointDto'
+      }
+    },
+    summary: {
+      description: 'Period totals',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CashFlowTrendSummaryDto'
+        }
+      ]
+    },
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '6m'
+    },
+    granularity: {
+      type: 'string',
+      description: 'Data granularity (v1 returns month buckets)',
+      example: 'month'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['series', 'summary', 'period', 'granularity', 'currency']
+} as const;
+
+export const $GenerateSnapshotBody = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $GenerateSnapshotResponse = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $BackfillSnapshotsBody = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $BackfillSnapshotsResponse = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $CreateBeanPriceDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'USD'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
+      example: 'CNY'
+    },
+    amount: {
+      type: 'number',
+      description:
+        'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
+      example: 175.5,
+      minimum: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Price date (ISO 8601 format)',
+      example: '2024-11-05'
+    },
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (validated by Zod schema, max field lengths enforced)',
+      example: {
+        source: 'MANUAL',
+        note: 'Bank valuation report',
+        confidence: 0.95
+      }
+    }
+  },
+  required: ['currency', 'quoteCurrency', 'amount', 'date']
+} as const;
+
+export const $PriceResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the price)',
+      example: 'user-123'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'BTC'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency, e.g., USD, CNY)',
+      example: 'USD'
+    },
+    amount: {
+      type: 'number',
+      description:
+        'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
+      example: 50000
+    },
+    date: {
+      type: 'string',
+      description:
+        'Price date (ISO 8601 format). Represents the date this price was valid.',
+      example: '2024-01-01',
+      format: 'date'
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
+      example: {
+        source: 'MANUAL',
+        note: 'User-defined price',
+        confidence: 1
+      }
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-11-03T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2024-11-03T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
     'userId',
     'currency',
     'quoteCurrency',
@@ -2943,45 +3528,257 @@ export const $PriceListResponseDto = {
       description: 'List of prices',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/PriceResponseDto'
+        $ref: '#/components/schemas/PriceResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of prices',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateBeanPriceDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'Currency being priced'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency)'
+    },
+    amount: {
+      type: 'number',
+      description: 'Price amount (MUST be >= 0 per Beancount spec)',
+      minimum: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Price date (ISO 8601 format)'
+    },
+    metadata: {
+      type: 'object',
+      description: 'Metadata'
+    }
+  }
+} as const;
+
+export const $DeleteOwnUserDto = {
+  type: 'object',
+  properties: {
+    accessToken: {
+      type: 'string',
+      description: 'Access token for user verification',
+      example: 'abc123xyz'
+    }
+  },
+  required: ['accessToken']
+} as const;
+
+export const $UserSettingsResponseDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description:
+        'Stored base currency choice (ISO 4217) for net-worth/report aggregation. null = user never chose; aggregates fall back to the region default at display time (#713).',
+      example: 'USD',
+      nullable: true
+    }
+  },
+  required: ['baseCurrency']
+} as const;
+
+export const $UserResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'User ID'
+    },
+    role: {
+      type: 'string',
+      description: 'Assigned user role'
+    },
+    permissions: {
+      description: 'Permission strings',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    settings: {
+      description: 'User settings',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UserSettingsResponseDto'
+        }
+      ]
+    }
+  },
+  required: ['id', 'role', 'permissions', 'settings']
+} as const;
+
+export const $SignupDto = {
+  type: 'object',
+  properties: {
+    turnstileToken: {
+      type: 'string',
+      description:
+        'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
+      example: '0.abc123def456...'
+    }
+  }
+} as const;
+
+export const $SignupResponseDto = {
+  type: 'object',
+  properties: {
+    authToken: {
+      type: 'string',
+      description: 'JWT auth token',
+      example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+    },
+    accessToken: {
+      type: 'string',
+      description: 'Auto-generated access token'
+    },
+    role: {
+      type: 'string',
+      description: 'Assigned user role',
+      enum: ['USER', 'ADMIN', 'DEMO', 'INACTIVE', 'PAID', 'OPS']
+    }
+  },
+  required: ['authToken', 'accessToken', 'role']
+} as const;
+
+export const $UpdateUserSettingDto = {
+  type: 'object',
+  properties: {
+    secId: {
+      type: 'number',
+      description: 'Security ID'
+    },
+    annualInterestRate: {
+      type: 'number',
+      description: 'Annual interest rate',
+      example: 0.05
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'USD'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency code',
+      example: 'USD'
+    },
+    benchmark: {
+      type: 'string',
+      description: 'Benchmark symbol',
+      example: 'SPY'
+    },
+    colorScheme: {
+      type: 'string',
+      description: 'Color scheme',
+      enum: ['DARK', 'LIGHT']
+    },
+    dateRange: {
+      type: 'string',
+      description: 'Date range filter',
+      example: '1y'
+    },
+    emergencyFund: {
+      type: 'number',
+      description: 'Emergency fund amount',
+      example: 10000
+    },
+    'filters.accounts': {
+      description: 'Account filter IDs',
+      type: 'array',
+      items: {
+        type: 'string'
       }
     },
-    total: {
-      type: 'number',
-      description: 'Total number of prices',
-      example: 42
-    }
-  },
-  required: ['items', 'total']
-} as const;
-
-export const $UpdateBeanPriceDto = {
-  type: 'object',
-  properties: {
-    currency: {
+    'filters.assetClasses': {
+      description: 'Asset class filters',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    'filters.dataSource': {
       type: 'string',
-      description: 'Currency being priced'
+      description: 'Data source filter'
     },
-    quoteCurrency: {
+    'filters.symbol': {
       type: 'string',
-      description: 'Quote currency (pricing currency)'
+      description: 'Symbol filter'
     },
-    amount: {
+    'filters.tags': {
+      description: 'Tag filters',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    isExperimentalFeatures: {
+      type: 'boolean',
+      description: 'Enable experimental features'
+    },
+    isRestrictedView: {
+      type: 'boolean',
+      description: 'Enable restricted view mode'
+    },
+    language: {
+      type: 'string',
+      description: 'Language code',
+      example: 'en'
+    },
+    locale: {
+      type: 'string',
+      description: 'Locale code',
+      example: 'en-US'
+    },
+    projectedTotalAmount: {
       type: 'number',
-      description: 'Price amount (MUST be >= 0 per Beancount spec)',
-      minimum: 0
+      description: 'Projected total amount',
+      example: 1000000
     },
-    date: {
+    retirementDate: {
       type: 'string',
-      description: 'Price date (ISO 8601 format)'
+      description: 'Retirement date in ISO 8601 format',
+      example: '2050-01-01'
     },
-    metadata: {
-      type: 'object',
-      description: 'Metadata'
+    savingsRate: {
+      type: 'number',
+      description: 'Savings rate percentage',
+      example: 0.2
+    },
+    viewMode: {
+      type: 'string',
+      description: 'View mode',
+      enum: ['DEFAULT', 'ZEN']
     }
   }
 } as const;
 
+export const $UpdatePropertyDto = {
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description: 'Property value'
+    }
+  },
+  required: ['value']
+} as const;
+
 export const $CreateRecurringRuleDto = {
   type: 'object',
   properties: {
@@ -3027,7 +3824,6 @@ export const $CreateRecurringRuleDto = {
     currency: {
       type: 'string',
       description: 'Currency code',
-      default: 'CNY',
       maxLength: 10
     },
     matchPayeePattern: {
@@ -3075,7 +3871,6 @@ export const $CreateRecurringRuleDto = {
     'name',
     'frequency',
     'expectedAmount',
-    'currency',
     'matchAmountTolerance',
     'autoCreate'
   ]
@@ -3097,7 +3892,7 @@ export const $RecurringRuleResponseDto = {
       description: 'Rule name'
     },
     icon: {
-      type: 'object',
+      type: 'string',
       description: 'Icon emoji'
     },
     frequency: {
@@ -3109,11 +3904,11 @@ export const $RecurringRuleResponseDto = {
       description: 'Expected amount'
     },
     expectedDay: {
-      type: 'object',
+      type: 'number',
       description: 'Expected day of month'
     },
     customIntervalDays: {
-      type: 'object',
+      type: 'number',
       description: 'Custom interval in days'
     },
     currency: {
@@ -3121,7 +3916,7 @@ export const $RecurringRuleResponseDto = {
       description: 'Currency code'
     },
     matchPayeePattern: {
-      type: 'object',
+      type: 'string',
       description: 'Payee matching pattern'
     },
     matchAmountTolerance: {
@@ -3129,15 +3924,15 @@ export const $RecurringRuleResponseDto = {
       description: 'Amount tolerance percentage'
     },
     defaultExpenseAccount: {
-      type: 'object',
+      type: 'string',
       description: 'Default expense account'
     },
     defaultPaymentAccount: {
-      type: 'object',
+      type: 'string',
       description: 'Default payment account'
     },
     defaultPayee: {
-      type: 'object',
+      type: 'string',
       description: 'Default payee'
     },
     isActive: {
@@ -3149,7 +3944,7 @@ export const $RecurringRuleResponseDto = {
       description: 'Rule start date (YYYY-MM-DD)'
     },
     endDate: {
-      type: 'object',
+      type: 'string',
       description: 'Rule end date (YYYY-MM-DD)'
     },
     autoCreate: {
@@ -3157,7 +3952,7 @@ export const $RecurringRuleResponseDto = {
       description: 'Auto-create transaction on expected date'
     },
     lastOccurrence: {
-      type: 'object',
+      type: 'string',
       description: 'Last matched occurrence date (YYYY-MM-DD)'
     },
     totalCount: {
@@ -3239,7 +4034,7 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Rule name'
     },
     icon: {
-      type: 'object',
+      type: 'string',
       description: 'Icon emoji'
     },
     frequency: {
@@ -3251,11 +4046,11 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Expected amount'
     },
     expectedDay: {
-      type: 'object',
+      type: 'number',
       description: 'Expected day of month'
     },
     customIntervalDays: {
-      type: 'object',
+      type: 'number',
       description: 'Custom interval in days'
     },
     currency: {
@@ -3263,7 +4058,7 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Currency code'
     },
     matchPayeePattern: {
-      type: 'object',
+      type: 'string',
       description: 'Payee matching pattern'
     },
     matchAmountTolerance: {
@@ -3271,15 +4066,15 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Amount tolerance percentage'
     },
     defaultExpenseAccount: {
-      type: 'object',
+      type: 'string',
       description: 'Default expense account'
     },
     defaultPaymentAccount: {
-      type: 'object',
+      type: 'string',
       description: 'Default payment account'
     },
     defaultPayee: {
-      type: 'object',
+      type: 'string',
       description: 'Default payee'
     },
     isActive: {
@@ -3291,7 +4086,7 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Rule start date (YYYY-MM-DD)'
     },
     endDate: {
-      type: 'object',
+      type: 'string',
       description: 'Rule end date (YYYY-MM-DD)'
     },
     autoCreate: {
@@ -3299,7 +4094,7 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Auto-create transaction on expected date'
     },
     lastOccurrence: {
-      type: 'object',
+      type: 'string',
       description: 'Last matched occurrence date (YYYY-MM-DD)'
     },
     totalCount: {
@@ -3325,7 +4120,7 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Number of overdue expected transactions'
     },
     nextExpectedDate: {
-      type: 'object',
+      type: 'string',
       description: 'Next expected date (YYYY-MM-DD)'
     },
     totalAmount: {
@@ -3341,11 +4136,11 @@ export const $RecurringRuleWithStatsResponseDto = {
       description: 'Number of matched transactions'
     },
     firstDate: {
-      type: 'object',
+      type: 'string',
       description: 'First matched transaction date (YYYY-MM-DD)'
     },
     lastDate: {
-      type: 'object',
+      type: 'string',
       description: 'Last matched transaction date (YYYY-MM-DD)'
     },
     variance: {
@@ -3386,7 +4181,7 @@ export const $UpdateRecurringRuleDto = {
   properties: {
     name: {
       type: 'string',
-      description: 'Rule name',
+      description: 'Rule name (unique per user)',
       maxLength: 100
     },
     icon: {
@@ -3409,7 +4204,7 @@ export const $UpdateRecurringRuleDto = {
     },
     expectedAmount: {
       type: 'number',
-      description: 'Expected amount',
+      description: 'Expected amount (positive number)',
       minimum: 0
     },
     expectedDay: {
@@ -3418,11 +4213,6 @@ export const $UpdateRecurringRuleDto = {
       minimum: 1,
       maximum: 31
     },
-    customIntervalDays: {
-      type: 'number',
-      description: 'Custom interval in days',
-      minimum: 1
-    },
     currency: {
       type: 'string',
       description: 'Currency code',
@@ -3430,41 +4220,48 @@ export const $UpdateRecurringRuleDto = {
     },
     matchPayeePattern: {
       type: 'string',
-      description: 'Payee matching pattern',
+      description: 'Payee matching pattern (supports wildcards)',
       maxLength: 200
     },
     matchAmountTolerance: {
       type: 'number',
       description: 'Amount tolerance percentage (0-1)',
+      default: 0.075,
       minimum: 0,
       maximum: 1
     },
     defaultExpenseAccount: {
       type: 'string',
-      description: 'Default expense account',
+      description: 'Default expense account for auto-create',
       maxLength: 200
     },
     defaultPaymentAccount: {
       type: 'string',
-      description: 'Default payment account',
+      description: 'Default payment account for auto-create',
       maxLength: 200
     },
     defaultPayee: {
       type: 'string',
-      description: 'Default payee',
+      description: 'Default payee for auto-create',
       maxLength: 200
     },
     autoCreate: {
       type: 'boolean',
-      description: 'Auto-create transaction'
-    },
-    isActive: {
-      type: 'boolean',
-      description: 'Rule active status'
+      description: 'Auto-create transaction when expected date arrives',
+      default: false
     },
     endDate: {
       type: 'string',
       description: 'Rule end date (ISO format)'
+    },
+    customIntervalDays: {
+      type: 'number',
+      description: 'Custom interval in days',
+      minimum: 1
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Rule active status'
     }
   }
 } as const;
@@ -3477,7 +4274,7 @@ export const $ExpectedTransactionRuleDto = {
       description: 'Rule name'
     },
     icon: {
-      type: 'object',
+      type: 'string',
       description: 'Rule icon'
     },
     frequency: {
@@ -3520,15 +4317,15 @@ export const $ExpectedTransactionResponseDto = {
       description: 'Status (PENDING, COMPLETED, SKIPPED)'
     },
     matchedTransactionId: {
-      type: 'object',
+      type: 'string',
       description: 'Matched transaction ID'
     },
     matchedAt: {
-      type: 'object',
+      type: 'string',
       description: 'Match timestamp (ISO 8601)'
     },
     matchConfidence: {
-      type: 'object',
+      type: 'number',
       description: 'Match confidence score (0-1)'
     },
     isOverdue: {
@@ -4312,7 +5109,8 @@ export const $UpdateTransactionRuleDto = {
     },
     matchLogic: {
       type: 'string',
-      enum: ['OR', 'AND']
+      enum: ['OR', 'AND'],
+      default: 'OR'
     },
     amountMin: {
       type: 'number',
@@ -4326,13 +5124,10 @@ export const $UpdateTransactionRuleDto = {
     },
     priority: {
       type: 'number',
+      default: 50,
       minimum: 0,
       maximum: 1000
     },
-    enabled: {
-      type: 'boolean',
-      description: 'Enable or disable the rule'
-    },
     additionalTags: {
       items: {
         type: 'array'
@@ -4342,6 +5137,10 @@ export const $UpdateTransactionRuleDto = {
     },
     additionalMetadata: {
       type: 'object'
+    },
+    enabled: {
+      type: 'boolean',
+      description: 'Enable or disable the rule'
     }
   }
 } as const;
@@ -4402,151 +5201,81 @@ export const $TestRuleResponseDto = {
   required: ['ruleId', 'matches', 'confidence', 'matchDetails']
 } as const;
 
-export const $DeleteOwnUserDto = {
-  type: 'object',
-  properties: {
-    accessToken: {
-      type: 'string',
-      description: 'Access token for user verification',
-      example: 'abc123xyz'
-    }
-  },
-  required: ['accessToken']
-} as const;
-
-export const $SignupDto = {
-  type: 'object',
-  properties: {
-    turnstileToken: {
-      type: 'string',
-      description:
-        'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
-      example: '0.abc123def456...'
-    }
-  }
-} as const;
-
-export const $UpdateUserSettingDto = {
+export const $CategoryCatalogEntryDto = {
   type: 'object',
   properties: {
-    secId: {
-      type: 'number',
-      description: 'Security ID'
-    },
-    annualInterestRate: {
-      type: 'number',
-      description: 'Annual interest rate',
-      example: 0.05
-    },
-    currency: {
-      type: 'string',
-      description: 'Currency code',
-      example: 'USD'
-    },
-    baseCurrency: {
-      type: 'string',
-      description: 'Base currency code',
-      example: 'USD'
-    },
-    benchmark: {
+    slug: {
       type: 'string',
-      description: 'Benchmark symbol',
-      example: 'SPY'
+      description: 'Category slug (single source-of-truth)',
+      example: 'food'
     },
-    colorScheme: {
+    scenario: {
       type: 'string',
-      description: 'Color scheme',
-      enum: ['DARK', 'LIGHT']
+      description: 'Display scenario group (maps to frontend picker _scenario)',
+      enum: [
+        'expense',
+        'income',
+        'investment',
+        'banking',
+        'transfer',
+        'payment'
+      ],
+      example: 'expense'
     },
-    dateRange: {
+    icon: {
       type: 'string',
-      description: 'Date range filter',
-      example: '1y'
-    },
-    emergencyFund: {
-      type: 'number',
-      description: 'Emergency fund amount',
-      example: 10000
+      description: 'Lucide icon name',
+      example: 'utensils'
     },
-    'filters.accounts': {
-      description: 'Account filter IDs',
+    regions: {
+      description: "Applicable regions ('*' = all, 'cn' = CN-only)",
+      example: ['*'],
       type: 'array',
       items: {
         type: 'string'
       }
     },
-    'filters.assetClasses': {
-      description: 'Asset class filters',
+    categoryAccounts: {
+      description:
+        "Beancount account paths (categoryAccount) of the region-enabled system rules whose categoryKeywords include this slug (#816). System rules only (public endpoint — user rules excluded); one-to-many by design (e.g. 'utilities' → Electricity/Water/Internet/Gas), sorted, [] when no rule maps the slug.",
+      example: [
+        'Expenses:Utilities:Electricity',
+        'Expenses:Utilities:Gas',
+        'Expenses:Utilities:Internet',
+        'Expenses:Utilities:Water'
+      ],
       type: 'array',
       items: {
         type: 'string'
       }
-    },
-    'filters.dataSource': {
-      type: 'string',
-      description: 'Data source filter'
-    },
-    'filters.symbol': {
-      type: 'string',
-      description: 'Symbol filter'
-    },
-    'filters.tags': {
-      description: 'Tag filters',
+    }
+  },
+  required: ['slug', 'scenario', 'icon', 'regions', 'categoryAccounts']
+} as const;
+
+export const $CategoryCatalogListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'Category entries (region-scoped, query-filtered)',
       type: 'array',
       items: {
-        type: 'string'
+        $ref: '#/components/schemas/CategoryCatalogEntryDto'
       }
     },
-    isExperimentalFeatures: {
-      type: 'boolean',
-      description: 'Enable experimental features'
-    },
-    isRestrictedView: {
-      type: 'boolean',
-      description: 'Enable restricted view mode'
-    },
-    language: {
-      type: 'string',
-      description: 'Language code',
-      example: 'en'
-    },
-    locale: {
-      type: 'string',
-      description: 'Locale code',
-      example: 'en-US'
-    },
-    projectedTotalAmount: {
-      type: 'number',
-      description: 'Projected total amount',
-      example: 1000000
-    },
-    retirementDate: {
-      type: 'string',
-      description: 'Retirement date in ISO 8601 format',
-      example: '2050-01-01'
-    },
-    savingsRate: {
+    total: {
       type: 'number',
-      description: 'Savings rate percentage',
-      example: 0.2
+      description:
+        'Total category entries for the region (before query filtering)',
+      example: 30
     },
-    viewMode: {
-      type: 'string',
-      description: 'View mode',
-      enum: ['DEFAULT', 'ZEN']
-    }
-  }
-} as const;
-
-export const $UpdatePropertyDto = {
-  type: 'object',
-  properties: {
-    value: {
+    region: {
       type: 'string',
-      description: 'Property value'
+      description: 'Region code',
+      example: 'cn'
     }
   },
-  required: ['value']
+  required: ['items', 'total', 'region']
 } as const;
 
 export const $CreateBeanEventDto = {
@@ -4687,6 +5416,63 @@ export const $UpdateBeanEventDto = {
   }
 } as const;
 
+export const $OnboardingAccountDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description:
+        'Account path (Assets/Liabilities only; format validated by the account service)',
+      example: 'Assets:Checking'
+    },
+    currency: {
+      type: 'string',
+      description: 'ISO 4217 currency code (3 letters)',
+      example: 'USD'
+    },
+    openingBalance: {
+      type: 'string',
+      description:
+        'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
+      example: '1000.00'
+    },
+    platformId: {
+      type: 'string',
+      description:
+        'Platform ID to bind the account to (references Platform.id); omit for unbound',
+      example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
+    },
+    displayName: {
+      type: 'string',
+      description:
+        'User-set display name override (omit/null = keep the derived name)',
+      nullable: true,
+      maxLength: 50,
+      example: 'Salary card'
+    }
+  },
+  required: ['path', 'currency']
+} as const;
+
+export const $OnboardingDto = {
+  type: 'object',
+  properties: {
+    accounts: {
+      description: 'Asset/Liability accounts to register with opening balances',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/OnboardingAccountDto'
+      }
+    },
+    skipAssetRegistration: {
+      type: 'boolean',
+      description:
+        'Skip asset registration; only bootstrap the core account set',
+      default: false
+    }
+  }
+} as const;
+
 export const $ActualBalanceDto = {
   type: 'object',
   properties: {
@@ -5055,7 +5841,7 @@ export const $IdentifyResultDto = {
     account: {
       type: 'string',
       description: 'Default account used by this importer',
-      example: 'Assets:Alipay:Balance'
+      example: 'Assets:CN:Alipay:Balance'
     },
     message: {
       type: 'string',
@@ -5072,7 +5858,7 @@ export const $MapperDefaultsDto = {
     sourceAccount: {
       type: 'string',
       description: 'Source account for transactions (Beancount format)',
-      example: 'Assets:Alipay:Balance'
+      example: 'Assets:CN:Alipay:Balance'
     },
     currency: {
       type: 'string',
@@ -5109,7 +5895,7 @@ export const $MapperDefaultsDto = {
       description:
         'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
       example: {
-        HuaBei: 'Liabilities:Alipay:Huabei',
+        HuaBei: 'Liabilities:CN:CreditLine',
         CreditCard: 'Liabilities:CreditCard'
       }
     }
@@ -5220,192 +6006,89 @@ export const $ImporterConfigDto = {
       format: 'date-time',
       type: 'string',
       description: 'Last update timestamp',
-      example: '2025-01-27T10:00:00Z'
-    }
-  },
-  required: [
-    'id',
-    'userId',
-    'importerId',
-    'version',
-    'schema',
-    'config',
-    'createdAt',
-    'updatedAt'
-  ]
-} as const;
-
-export const $UpdateMapperDefaultsDto = {
-  type: 'object',
-  properties: {
-    sourceAccount: {
-      type: 'string',
-      description: 'Source account for transactions (Beancount format)',
-      example: 'Assets:Alipay:Balance',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
-    },
-    currency: {
-      type: 'string',
-      description: 'Default currency (ISO 4217 code)',
-      example: 'CNY',
-      minLength: 3,
-      maxLength: 3,
-      pattern: '^[A-Z]{3}$'
-    },
-    expenseAccount: {
-      type: 'string',
-      description: 'Default expense account (optional)',
-      example: 'Expenses:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
-    },
-    incomeAccount: {
-      type: 'string',
-      description: 'Default income account (optional)',
-      example: 'Income:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
-    },
-    methodAccountMapping: {
-      type: 'object',
-      description:
-        'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
-      example: {
-        HuaBei: 'Liabilities:Alipay:Huabei',
-        CreditCard: 'Liabilities:CreditCard'
-      }
-    }
-  }
-} as const;
-
-export const $UpdateConfigDataDto = {
-  type: 'object',
-  properties: {
-    defaults: {
-      description: 'Mapper defaults configuration',
-      allOf: [
-        {
-          $ref: '#/components/schemas/UpdateMapperDefaultsDto'
-        }
-      ]
-    }
-  }
-} as const;
-
-export const $UpdateImporterConfigDto = {
-  type: 'object',
-  properties: {
-    data: {
-      description: 'Configuration data (v1 schema)',
-      allOf: [
-        {
-          $ref: '#/components/schemas/UpdateConfigDataDto'
-        }
-      ]
-    }
-  }
-} as const;
-
-export const $CreatePlatformDto = {
-  type: 'object',
-  properties: {
-    name: {
-      type: 'string',
-      description: 'Platform name',
-      example: 'Binance'
-    },
-    canonical: {
-      type: 'string',
-      description: 'Platform canonical identifier (lowercase, kebab-case)',
-      example: 'binance'
-    },
-    aliases: {
-      description: 'Platform aliases (multi-language names for lookup)',
-      example: ['Binance', 'Binance Exchange', 'BNB'],
-      type: 'array',
-      items: {
-        type: 'string'
-      }
-    },
-    url: {
-      type: 'string',
-      description: 'Platform URL',
-      example: 'https://www.binance.com'
-    },
-    type: {
-      type: 'string',
-      description: 'Platform type',
-      enum: [
-        'BANK',
-        'BROKERAGE',
-        'CRYPTO_EXCHANGE',
-        'PAYMENT',
-        'INVESTMENT',
-        'INSURANCE',
-        'OTHER'
-      ],
-      example: 'CRYPTO_EXCHANGE'
-    },
-    logoUrl: {
-      type: 'string',
-      description: 'Platform logo URL',
-      example: 'https://example.com/logos/binance.png'
-    },
-    isActive: {
-      type: 'boolean',
-      description: 'Whether the platform is active',
-      default: true
+      example: '2025-01-27T10:00:00Z'
     }
   },
-  required: ['name', 'canonical', 'aliases', 'url', 'type']
+  required: [
+    'id',
+    'userId',
+    'importerId',
+    'version',
+    'schema',
+    'config',
+    'createdAt',
+    'updatedAt'
+  ]
 } as const;
 
-export const $UpdatePlatformDto = {
+export const $UpdateMapperDefaultsDto = {
   type: 'object',
   properties: {
-    name: {
-      type: 'string',
-      description: 'Platform name',
-      example: 'Binance'
-    },
-    canonical: {
+    sourceAccount: {
       type: 'string',
-      description: 'Platform canonical identifier (lowercase, kebab-case)',
-      example: 'binance'
-    },
-    aliases: {
-      description: 'Platform aliases (multi-language names for lookup)',
-      example: ['Binance', 'Binance Exchange', 'BNB'],
-      type: 'array',
-      items: {
-        type: 'string'
-      }
+      description: 'Source account for transactions (Beancount format)',
+      example: 'Assets:CN:Alipay:Balance',
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
-    url: {
+    currency: {
       type: 'string',
-      description: 'Platform URL',
-      example: 'https://www.binance.com'
+      description: 'Default currency (ISO 4217 code)',
+      example: 'CNY',
+      minLength: 3,
+      maxLength: 3,
+      pattern: '^[A-Z]{3}$'
     },
-    type: {
+    expenseAccount: {
       type: 'string',
-      description: 'Platform type',
-      enum: [
-        'BANK',
-        'BROKERAGE',
-        'CRYPTO_EXCHANGE',
-        'PAYMENT',
-        'INVESTMENT',
-        'INSURANCE',
-        'OTHER'
-      ],
-      example: 'CRYPTO_EXCHANGE'
+      description: 'Default expense account (optional)',
+      example: 'Expenses:Unknown',
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
-    logoUrl: {
+    incomeAccount: {
       type: 'string',
-      description: 'Platform logo URL',
-      example: 'https://example.com/logos/binance.png'
+      description: 'Default income account (optional)',
+      example: 'Income:Unknown',
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
-    isActive: {
-      type: 'boolean',
-      description: 'Whether the platform is active'
+    methodAccountMapping: {
+      type: 'object',
+      description:
+        'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
+      example: {
+        HuaBei: 'Liabilities:CN:CreditLine',
+        CreditCard: 'Liabilities:CreditCard'
+      }
+    }
+  }
+} as const;
+
+export const $UpdateConfigDataDto = {
+  type: 'object',
+  properties: {
+    defaults: {
+      description: 'Mapper defaults configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UpdateMapperDefaultsDto'
+        }
+      ]
+    }
+  }
+} as const;
+
+export const $UpdateImporterConfigDto = {
+  type: 'object',
+  properties: {
+    data: {
+      description: 'Configuration data (v1 schema)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UpdateConfigDataDto'
+        }
+      ]
     }
   }
 } as const;
@@ -5416,7 +6099,7 @@ export const $ProviderSyncConfigDto = {
     sourceAccount: {
       type: 'string',
       description: 'Source account for the first posting',
-      example: 'Assets:Bank:Chase'
+      example: 'Assets:US:Chase:Checking'
     },
     defaultCurrency: {
       type: 'string',
@@ -5425,26 +6108,29 @@ export const $ProviderSyncConfigDto = {
     },
     defaultExpenseAccount: {
       type: 'string',
-      description: 'Default expense account for the second posting',
+      description:
+        'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
       example: 'Expenses:Unknown'
     },
     defaultIncomeAccount: {
       type: 'string',
-      description: 'Default income account for the second posting',
+      description:
+        'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
       example: 'Income:Unknown'
     },
     filterPending: {
       type: 'boolean',
       description: 'Filter pending transactions',
       default: true
+    },
+    externalAccountId: {
+      type: 'string',
+      description:
+        'External account ID for per-batch providers (e.g. GoCardless). Overrides sourceAccount when an ExternalAccountLink mapping exists.',
+      example: 'acc_gocardless_001'
     }
   },
-  required: [
-    'sourceAccount',
-    'defaultCurrency',
-    'defaultExpenseAccount',
-    'defaultIncomeAccount'
-  ]
+  required: ['sourceAccount', 'defaultCurrency']
 } as const;
 
 export const $ProviderSyncDto = {
@@ -5552,18 +6238,190 @@ export const $SupportedProvidersResponseDto = {
         type: 'string'
       }
     }
-  },
-  required: ['providers']
-} as const;
-
-export const $ParserTelemetryReportDto = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $UncoveredFormatMissDto = {
-  type: 'object',
-  properties: {}
+  },
+  required: ['providers']
+} as const;
+
+export const $CreateExternalAccountLinkDto = {
+  type: 'object',
+  properties: {
+    provider: {
+      type: 'string',
+      enum: [
+        'plaid',
+        'teller',
+        'truelayer',
+        'gocardless',
+        'simplefin',
+        'yodlee',
+        'beancount-direct',
+        'parsed-bill'
+      ],
+      example: 'plaid',
+      description: 'Open Banking provider (whitelist)'
+    },
+    externalAccountId: {
+      type: 'string',
+      example: 'acc-plaid-001',
+      description: 'External account ID from the provider'
+    },
+    beanAccountId: {
+      type: 'string',
+      example: '550e8400-e29b-41d4-a716-446655440000',
+      description: 'Target BeanAccount ID (must belong to the JWT user)'
+    }
+  },
+  required: ['provider', 'externalAccountId', 'beanAccountId']
+} as const;
+
+export const $ExternalAccountLinkResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string'
+    },
+    provider: {
+      type: 'string'
+    },
+    externalAccountId: {
+      type: 'string'
+    },
+    beanAccountId: {
+      type: 'string'
+    },
+    isActive: {
+      type: 'boolean'
+    },
+    createdAt: {
+      type: 'string'
+    },
+    updatedAt: {
+      type: 'string'
+    }
+  },
+  required: [
+    'id',
+    'provider',
+    'externalAccountId',
+    'beanAccountId',
+    'isActive',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $ExternalAccountLinkListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
+      }
+    },
+    total: {
+      type: 'number'
+    },
+    provider: {
+      type: 'string',
+      description: 'Filter by provider (query param)'
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $ParserTelemetryReportDto = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $UncoveredFormatMissDto = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $ClientParsedDataDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'number',
+      description: 'Transaction amount',
+      example: 35
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO 8601)',
+      example: '2026-08-15'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee/merchant name',
+      example: 'Starbucks'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    category: {
+      type: 'string',
+      description:
+        'Category in canonical form (catalog slug or Stage-2 rule keyword token, ADR-0116) — echo back verbatim from parsedData.category. Foreign forms (locale display names, account paths) are rejected with nlp.category.invalid.',
+      example: 'food'
+    },
+    incomeType: {
+      type: 'string',
+      description: 'Income type',
+      example: 'Salary'
+    },
+    incomeSource: {
+      type: 'string',
+      description: 'Income source',
+      example: 'Anthropic Inc.'
+    },
+    symbol: {
+      type: 'string',
+      description: 'Security symbol code (e.g., 600519, AAPL)',
+      example: 'AAPL'
+    },
+    quantity: {
+      type: 'number',
+      description: 'Quantity of shares/units',
+      example: 100
+    },
+    price: {
+      type: 'number',
+      description: 'Unit price per share/unit',
+      example: 1900
+    },
+    investmentAction: {
+      type: 'string',
+      description: 'Investment action',
+      enum: ['buy', 'sell'],
+      example: 'buy'
+    },
+    paymentSource: {
+      type: 'string',
+      description: 'Payment source: asset (default) or liability (credit card)',
+      enum: ['asset', 'liability'],
+      example: 'asset'
+    },
+    liabilityHint: {
+      type: 'string',
+      description: 'Liability account hint (CreditCard/Huabei/Baitiao)',
+      example: 'CreditCard'
+    },
+    warning: {
+      type: 'string',
+      description:
+        'Display-only warning from the prior response; accepted but ignored.',
+      example: 'Cross-currency settlement applies.'
+    }
+  }
 } as const;
 
 export const $ProcessNlpDto = {
@@ -5571,10 +6429,17 @@ export const $ProcessNlpDto = {
   properties: {
     message: {
       type: 'string',
-      description: 'Natural language text describing a transaction (Chinese)',
-      example: 'yesterday Starbucks spent 35 yuan',
+      description:
+        'Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.',
+      example: 'Starbucks 35',
       maxLength: 500
     },
+    confirm: {
+      type: 'boolean',
+      description:
+        'Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.',
+      example: true
+    },
     sessionId: {
       type: 'string',
       description:
@@ -5582,17 +6447,51 @@ export const $ProcessNlpDto = {
       example: 'session_abc123'
     },
     parsedData: {
-      type: 'object',
       description:
         'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
       example: {
         amount: 35,
         currency: 'CNY',
         payee: 'Starbucks'
-      }
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/ClientParsedDataDto'
+        }
+      ]
+    },
+    selectedRuleId: {
+      type: 'string',
+      description:
+        'confirm_rule echo-back: rule id selected from the prior confirm_rule response (matchedRule.id or alternatives[i].ruleId). Applied directly when the session is confirming_rule — no NL re-parse.',
+      example: 'rule_abc123'
+    },
+    selectedAccount: {
+      type: 'string',
+      description:
+        'confirm_account echo-back: account path selected from the prior confirm_account response (suggestedAccount, similarAccounts[i].path, or a typed path). Applied directly when the session is confirming_account — no NL re-parse.',
+      example: 'Expenses:Food:Coffee'
+    },
+    viewpointAccount: {
+      type: 'string',
+      description:
+        'Viewpoint account hint: the beancount path the user drilled into (e.g. from an account drill-down). Tie-break only — never overrides accounts resolved from the text. Must be an owned, OPEN Assets:/Liabilities: account; unresolvable hints are silently ignored.',
+      example: 'Assets:CN:Bank:ICBC'
+    },
+    viewpointCategory: {
+      type: 'string',
+      description:
+        "Viewpoint category hint: the ADR-0075 Group segment the user drilled into (e.g. 'Food'). Resolved to a concrete OPEN account in that group; tie-break only — never overrides a category resolved from the text.",
+      example: 'Food'
+    },
+    viewpointFlow: {
+      type: 'string',
+      description:
+        "Companion flow root for viewpointCategory ('income' | 'expense'), mirroring the ADR-0126 list-endpoint invariant. Derived from the session's routed intent (multi-turn) when absent; a first-turn flow-less category hint is dropped — send the flow explicitly.",
+      enum: ['income', 'expense'],
+      example: 'expense'
     }
-  },
-  required: ['message']
+  }
 } as const;
 
 export const $NlpTransactionInfoDto = {
@@ -5658,7 +6557,9 @@ export const $NlpParsedDataDto = {
     },
     category: {
       type: 'string',
-      description: 'Category'
+      description:
+        'Category in canonical form: a CATEGORY_CATALOG slug (GET /{region}/bean/categories) or a Stage-2 rule categoryKeywords token (ADR-0116 D2). Never a locale display name or a beancount account path. Echo back verbatim on confirm.',
+      example: 'food'
     },
     incomeType: {
       type: 'string',
@@ -5904,6 +6805,24 @@ export const $NlpRuleConfirmationDataDto = {
   ]
 } as const;
 
+export const $NlpAccountCandidateDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Canonical beancount account path (echo back on selection)',
+      example: 'Expenses:Food:Dining'
+    },
+    name: {
+      type: 'string',
+      description:
+        'Localized display name (ADR-0114 read-time projection, user locale)',
+      example: '餐饮'
+    }
+  },
+  required: ['path', 'name']
+} as const;
+
 export const $NlpAccountConfirmationDataDto = {
   type: 'object',
   properties: {
@@ -5914,14 +6833,16 @@ export const $NlpAccountConfirmationDataDto = {
     },
     suggestedAccount: {
       type: 'string',
-      description: 'Suggested replacement account',
+      description:
+        'Suggested replacement account (omitted when no clear candidate)',
       example: 'Expenses:Food:Drinks'
     },
     similarAccounts: {
-      description: 'Similar accounts for user selection',
+      description:
+        'Similar accounts for user selection (path + localized name, #680)',
       type: 'array',
       items: {
-        type: 'string'
+        $ref: '#/components/schemas/NlpAccountCandidateDto'
       }
     },
     errorMessage: {
@@ -5936,7 +6857,6 @@ export const $NlpAccountConfirmationDataDto = {
   },
   required: [
     'invalidAccount',
-    'suggestedAccount',
     'similarAccounts',
     'errorMessage',
     'transactionContext'
@@ -6105,11 +7025,12 @@ export const $NlpSuggestedAccountDto = {
     account: {
       type: 'string',
       description: 'Suggested account path',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     confidence: {
       type: 'number',
-      description: 'Confidence score for this suggestion (0-1)',
+      description:
+        'Confidence score for this suggestion (0-1). Present = predicted (confirm/confirm_rule/confirm_account); omitted = actual persisted account (created). (#586)',
       example: 0.9
     }
   },
@@ -6145,23 +7066,31 @@ export const $NlpDefaultAccountsDto = {
   properties: {
     asset: {
       type: 'string',
-      description: 'Default asset account',
-      example: 'Assets:Bank:Checking'
+      description:
+        'Default OPEN asset account (MRU when multiple), or null when none/ambiguous',
+      example: 'Assets:Checking',
+      nullable: true
     },
     expense: {
       type: 'string',
-      description: 'Default expense account',
-      example: 'Expenses:Uncategorized'
+      description:
+        'Default OPEN expense account (MRU when multiple), or null when none/ambiguous',
+      example: 'Expenses:Food:Coffee',
+      nullable: true
     },
     income: {
       type: 'string',
-      description: 'Default income account',
-      example: 'Income:Uncategorized'
+      description:
+        'Default OPEN income account (MRU when multiple), or null when none/ambiguous',
+      example: 'Income:Salary',
+      nullable: true
     },
     liability: {
       type: 'string',
-      description: 'Default liability account',
-      example: 'Liabilities:CreditCard'
+      description:
+        'Default OPEN liability account (MRU when multiple), or null when none/ambiguous',
+      example: 'Liabilities:CreditCard',
+      nullable: true
     }
   },
   required: ['asset', 'expense', 'income', 'liability']
@@ -6186,7 +7115,8 @@ export const $NlpResponseDto = {
         'confirm_rule',
         'confirm_account',
         'confirm_payee',
-        'cancel'
+        'cancel',
+        'aborted'
       ]
     },
     intent: {
@@ -6200,7 +7130,7 @@ export const $NlpResponseDto = {
       type: 'string',
       description:
         'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
-      enum: ['transfer', 'banking', 'investment'],
+      enum: ['transfer', 'banking', 'investment', 'lend', 'lend_collect'],
       example: 'investment'
     },
     liabilitySubType: {
@@ -6337,35 +7267,387 @@ export const $NlpResponseDto = {
         }
       ]
     },
-    recurringSuggestion: {
+    recurringSuggestion: {
+      description:
+        'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/RecurringSuggestionDto'
+        }
+      ]
+    },
+    suggestedAccounts: {
+      description:
+        'Suggested accounts for this transaction (#586). confirm/confirm_rule/confirm_account: predicted (source/destination carry confidence); created: actual persisted accounts (confidence omitted). confirm_account destination is the suggested replacement, never the invalid account.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountsDto'
+        }
+      ]
+    },
+    defaultAccounts: {
+      description:
+        'Default fallback accounts for the user/region (#586). v1 returns universal constants; per-user personalization is planned.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpDefaultAccountsDto'
+        }
+      ]
+    }
+  },
+  required: ['status', 'action']
+} as const;
+
+export const $PlatformListItemDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Global platform ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Platform name'
+    },
+    url: {
+      type: 'string',
+      description: 'Platform URL'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ]
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
+    },
+    suggestedSegment: {
+      type: 'string',
+      description:
+        'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Logo URL',
+      nullable: true
+    },
+    countryCode: {
+      type: 'string',
+      description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
+      example: 'CN',
+      nullable: true
+    },
+    category: {
+      type: 'string',
+      description:
+        'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
+      nullable: true,
+      example: 'DigitalWallet'
+    },
+    isBound: {
+      type: 'boolean',
+      description: 'Whether user has accounts using this platform'
+    }
+  },
+  required: [
+    'id',
+    'name',
+    'url',
+    'type',
+    'canonical',
+    'suggestedSegment',
+    'logoUrl',
+    'countryCode',
+    'category',
+    'isBound'
+  ]
+} as const;
+
+export const $PlatformMatchResultDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Global platform ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Platform name (e.g., "ICBC")'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ]
+    },
+    suggestedSegment: {
+      type: 'string',
+      description:
+        'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Logo URL',
+      nullable: true
+    },
+    countryCode: {
+      type: 'string',
+      description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
+      example: 'CN',
+      nullable: true
+    },
+    category: {
+      type: 'string',
+      description:
+        'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
+      nullable: true,
+      example: 'DigitalWallet'
+    },
+    matchType: {
+      type: 'string',
+      description: "How this row matched: 'exact' > 'prefix' > 'substring'",
+      enum: ['exact', 'prefix', 'substring']
+    }
+  },
+  required: [
+    'id',
+    'name',
+    'canonical',
+    'type',
+    'suggestedSegment',
+    'logoUrl',
+    'countryCode',
+    'category',
+    'matchType'
+  ]
+} as const;
+
+export const $PlatformMatchResponseDto = {
+  type: 'object',
+  properties: {
+    platforms: {
+      description: 'Ranked matches, best tier first (at most 10 rows)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PlatformMatchResultDto'
+      }
+    },
+    matchType: {
+      type: 'string',
+      description:
+        "Overall match quality — top row's tier, or 'none' when no hits",
+      enum: ['none', 'exact', 'prefix', 'substring']
+    },
+    total: {
+      type: 'number',
+      description: 'Total matches before LIMIT (truncation transparency)'
+    },
+    hasMore: {
+      type: 'boolean',
+      description: 'true when total > platforms.length (more matches exist)'
+    }
+  },
+  required: ['platforms', 'matchType', 'total', 'hasMore']
+} as const;
+
+export const $PlatformStandardsPlatformDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Global platform ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Platform name (e.g., "ICBC")'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
+    },
+    suggestedSegment: {
+      type: 'string',
+      description:
+        'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ]
+    },
+    category: {
+      type: 'string',
       description:
-        'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
+        'Region-aware category (institution vocab, e.g. DigitalWallet/Bank) resolved against the final region. null = no region-aware suggestion; fall back to type.',
+      nullable: true,
+      example: 'Bank'
+    }
+  },
+  required: ['id', 'name', 'canonical', 'suggestedSegment', 'type', 'category']
+} as const;
+
+export const $PlatformStandardsResponseDto = {
+  type: 'object',
+  properties: {
+    platform: {
+      description: 'The selected platform (institution lock source)',
       allOf: [
         {
-          $ref: '#/components/schemas/RecurringSuggestionDto'
+          $ref: '#/components/schemas/PlatformStandardsPlatformDto'
         }
       ]
     },
-    suggestedAccounts: {
+    region: {
+      type: 'string',
       description:
-        'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
-      allOf: [
-        {
-          $ref: '#/components/schemas/NlpSuggestedAccountsDto'
-        }
-      ]
+        "Resolved template region (ISO 3166-1 alpha-2, UPPERCASE): the platform's own countryCode when set, else the region query param. For regions without a regional template file the template list falls back to the universal-only catalog while region still echoes the code.",
+      example: 'CN'
     },
-    defaultAccounts: {
+    templates: {
       description:
-        'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
-      allOf: [
-        {
-          $ref: '#/components/schemas/NlpDefaultAccountsDto'
-        }
-      ]
+        'Candidate account-standard templates of the resolved region (groupable by productCategory client-side)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountStandardResponseDto'
+      }
     }
   },
-  required: ['status', 'action']
+  required: ['platform', 'region', 'templates']
+} as const;
+
+export const $CreatePlatformDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Platform name',
+      example: 'Binance'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Platform canonical identifier (lowercase, kebab-case)',
+      example: 'binance'
+    },
+    aliases: {
+      description: 'Platform aliases (multi-language names for lookup)',
+      example: ['Binance', 'Binance Exchange', 'BNB'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    url: {
+      type: 'string',
+      description: 'Platform URL',
+      example: 'https://www.binance.com'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ],
+      example: 'CRYPTO_EXCHANGE'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Platform logo URL',
+      example: 'https://example.com/logos/binance.png'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the platform is active',
+      default: true
+    }
+  },
+  required: ['name', 'canonical', 'aliases', 'url', 'type']
+} as const;
+
+export const $UpdatePlatformDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Platform name',
+      example: 'Binance'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Platform canonical identifier (lowercase, kebab-case)',
+      example: 'binance'
+    },
+    aliases: {
+      description: 'Platform aliases (multi-language names for lookup)',
+      example: ['Binance', 'Binance Exchange', 'BNB'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    url: {
+      type: 'string',
+      description: 'Platform URL',
+      example: 'https://www.binance.com'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ],
+      example: 'CRYPTO_EXCHANGE'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Platform logo URL',
+      example: 'https://example.com/logos/binance.png'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the platform is active',
+      default: true
+    }
+  }
 } as const;
 
 export const $NetWorthByCurrencyDto = {
@@ -6522,11 +7804,12 @@ export const $AccountItemDto = {
     name: {
       type: 'string',
       description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
+      example: 'Assets:CN:CMB:Savings'
     },
     displayName: {
       type: 'string',
-      description: 'Display name (last part of account path)',
+      description:
+        'Display name: user-set name if provided (#762), else the ADR-0114 chain — request-locale catalog name, en pivot, then the last part of the account path (#771)',
       example: 'Savings'
     },
     balance: {
@@ -6562,7 +7845,8 @@ export const $PlatformGroupDto = {
       example: 'CMB Bank'
     },
     accounts: {
-      description: 'Accounts within this platform',
+      description:
+        'Accounts within this platform (Assets and Liabilities rows, #696)',
       type: 'array',
       items: {
         $ref: '#/components/schemas/AccountItemDto'
@@ -6570,7 +7854,8 @@ export const $PlatformGroupDto = {
     },
     totalBalance: {
       type: 'string',
-      description: 'FX-converted total balance in base currency',
+      description:
+        'FX-converted total balance in base currency (nets Assets + Liabilities rows; can be negative)',
       example: '100000.00'
     },
     balanceByCurrency: {
@@ -6589,7 +7874,7 @@ export const $PlatformGroupDto = {
     sharePct: {
       type: 'number',
       description:
-        'Share of the grand converted total (0-100); 0 when grand total is 0',
+        'Share of the converted asset-side grand total (0-100); liability balances are excluded from the basis; 0 when grand total is 0 (#696)',
       example: 42.5
     }
   },
@@ -6637,7 +7922,8 @@ export const $AccountsSummaryDto = {
   properties: {
     totalAccounts: {
       type: 'number',
-      description: 'Total number of accounts'
+      description:
+        'Total number of accounts (balance sheet: Assets + Liabilities, #696)'
     },
     totalPlatforms: {
       type: 'number',
@@ -6691,11 +7977,12 @@ export const $AccountItemWithAssetClassDto = {
     name: {
       type: 'string',
       description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
+      example: 'Assets:CN:CMB:Savings'
     },
     displayName: {
       type: 'string',
-      description: 'Display name (last part of account path)',
+      description:
+        'Display name: user-set name if provided (#762), else the ADR-0114 chain — request-locale catalog name, en pivot, then the last part of the account path (#771)',
       example: 'Savings'
     },
     balance: {
@@ -6866,7 +8153,7 @@ export const $HoldingAssetClassAccountSliceDto = {
     accountPath: {
       type: 'string',
       description: 'Full account path',
-      example: 'Assets:US:Investments:Brokerage'
+      example: 'Assets:US:Fidelity:Brokerage'
     },
     accountCurrency: {
       type: 'string',
@@ -7181,7 +8468,7 @@ export const $MonetaryDto = {
       example: 'USD'
     },
     baseCcyEquivalent: {
-      type: 'object',
+      type: 'string',
       description: 'Converted to user base currency (Decimal string)',
       example: '21600',
       nullable: true
@@ -7257,13 +8544,13 @@ export const $HoldingPnlRowDto = {
       example: 'Assets:US:Broker:AAPL'
     },
     accountCcy: {
-      type: 'object',
+      type: 'string',
       description: 'Account settlement currency (ISO 4217), from cost currency',
       nullable: true,
       example: 'USD'
     },
     brokerType: {
-      type: 'object',
+      type: 'string',
       description: 'Broker type derived from Platform.type',
       nullable: true,
       example: 'broker'
@@ -7284,7 +8571,7 @@ export const $HoldingPnlRowDto = {
       example: 'EQUITY'
     },
     assetSubClass: {
-      type: 'object',
+      type: 'string',
       nullable: true,
       example: 'STOCK'
     },
@@ -7331,14 +8618,14 @@ export const $HoldingPnlRowDto = {
       ]
     },
     unrealizedPnlBase: {
-      type: 'object',
+      type: 'string',
       description:
         'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
       nullable: true,
       example: '6000'
     },
     unrealizedPnlPct: {
-      type: 'object',
+      type: 'string',
       description: 'Unrealized P&L % (Decimal string)',
       nullable: true,
       example: '25'
@@ -7362,7 +8649,7 @@ export const $HoldingPnlRowDto = {
       ]
     },
     pctOfInvestedAssets: {
-      type: 'object',
+      type: 'string',
       description:
         'Share of invested assets % (Decimal string); only for invested chartTokens',
       nullable: true,
@@ -7407,15 +8694,15 @@ export const $HoldingPnlWarningDto = {
       ]
     },
     symbol: {
-      type: 'object',
+      type: 'string',
       nullable: true
     },
     accountId: {
-      type: 'object',
+      type: 'string',
       nullable: true
     },
     currency: {
-      type: 'object',
+      type: 'string',
       nullable: true
     }
   },
@@ -7456,292 +8743,378 @@ export const $HoldingPnlResponseDto = {
   required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
 } as const;
 
-export const $CurrencyBalanceDto = {
+export const $AnonymousLoginDto = {
   type: 'object',
   properties: {
-    currency: {
+    accessToken: {
       type: 'string',
-      description: 'ISO 4217 currency code',
-      example: 'CNY'
-    },
-    balance: {
+      description: 'Access token for anonymous login'
+    }
+  },
+  required: ['accessToken']
+} as const;
+
+export const $AnonymousLoginResponseDto = {
+  type: 'object',
+  properties: {
+    authToken: {
       type: 'string',
-      description: 'Balance amount',
-      example: '500000.00'
+      description: 'JWT auth token',
+      example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
     }
   },
-  required: ['currency', 'balance']
+  required: ['authToken']
 } as const;
 
-export const $TimeSeriesPointDto = {
+export const $ParserContributionMetaDto = {
   type: 'object',
   properties: {
-    date: {
+    institution: {
       type: 'string',
-      description: 'Date in YYYY-MM-DD format',
-      example: '2024-06-15'
+      description: 'Institution slug (lowercase kebab-case)',
+      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$',
+      example: 'icbc'
     },
-    value: {
+    region: {
       type: 'string',
-      description: 'Value at this date (in base currency)',
-      example: '500000.00'
+      enum: [
+        'cn',
+        'us',
+        'de',
+        'fr',
+        'gb',
+        'hk',
+        'jp',
+        'sg',
+        'au',
+        'ca',
+        'other'
+      ]
     },
-    change: {
-      type: 'object',
-      description: 'Change from previous point',
-      example: '5000.00'
+    accountType: {
+      type: 'string',
+      enum: ['checking', 'savings', 'credit', 'debit', 'investment']
     },
-    assets: {
+    format: {
       type: 'string',
-      description: 'Total assets at this date (in base currency)',
-      example: '494338.00'
+      enum: ['csv', 'xlsx', 'pdf', 'ofx', 'qif']
     },
-    liabilities: {
+    institutionDisplayName: {
       type: 'string',
-      description: 'Total liabilities at this date (in base currency)',
-      example: '310098.00'
+      example: '中国工商银行'
     },
-    byCurrency: {
-      description: 'Multi-currency breakdown for this point',
+    encoding: {
+      type: 'string',
+      example: 'utf-8'
+    },
+    delimiter: {
+      type: 'string',
+      description: 'CSV delimiter character: ",", ";", "\\t" or "|"'
+    },
+    headerRows: {
+      type: 'number',
+      default: 1,
+      description: 'Header row count; the client omits the field when it is 1'
+    },
+    notes: {
+      type: 'string',
+      maxLength: 2000
+    }
+  },
+  required: ['institution', 'region', 'accountType', 'format']
+} as const;
+
+export const $ParserContributionSamplesDto = {
+  type: 'object',
+  properties: {
+    rows: {
+      description:
+        'Client-sanitized sample rows (key = column name, value = cell)',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/CurrencyBalanceDto'
+        type: 'object'
       }
+    },
+    rawHeaders: {
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['rows']
+} as const;
+
+export const $FieldHintDto = {
+  type: 'object',
+  properties: {
+    columnName: {
+      type: 'string',
+      example: '交易日期'
+    },
+    format: {
+      type: 'string',
+      description: 'Date format, e.g. yyyy-MM-dd HH:mm',
+      example: 'yyyy-MM-dd'
+    },
+    signConvention: {
+      type: 'string',
+      enum: ['negative-expense', 'positive-expense', 'separate-columns']
+    },
+    creditColumn: {
+      type: 'string'
+    },
+    debitColumn: {
+      type: 'string'
+    }
+  },
+  required: ['columnName']
+} as const;
+
+export const $ParserContributionFieldHintsDto = {
+  type: 'object',
+  properties: {
+    date: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    amount: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    description: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    balance: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    payee: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    reference: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    category: {
+      $ref: '#/components/schemas/FieldHintDto'
     }
   },
-  required: ['date', 'value']
+  required: ['date', 'amount']
 } as const;
 
-export const $TrendSummaryDto = {
+export const $ExpectedTransactionDto = {
   type: 'object',
   properties: {
-    startValue: {
+    date: {
       type: 'string',
-      description: 'Value at start of period',
-      example: '450000.00'
+      example: '2026-08-01'
     },
-    endValue: {
-      type: 'string',
-      description: 'Value at end of period',
-      example: '500000.00'
+    amount: {
+      type: 'number',
+      example: -45.5
     },
-    totalChange: {
+    description: {
       type: 'string',
-      description: 'Total change over period',
-      example: '50000.00'
+      example: '星巴克-***店'
     },
-    totalChangePercentage: {
-      type: 'string',
-      description: 'Total change percentage',
-      example: '+11.11%'
+    payee: {
+      type: 'string'
+    },
+    category: {
+      type: 'string'
     }
   },
-  required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
+  required: ['date', 'amount', 'description']
 } as const;
 
-export const $MultiCurrencyPointDto = {
+export const $ParserContributionExamplesDto = {
   type: 'object',
   properties: {
-    date: {
-      type: 'string',
-      description: 'Date in YYYY-MM-DD format',
-      example: '2024-06-15'
-    },
-    byCurrency: {
-      description: 'Balances by currency',
+    expectedTransactions: {
       type: 'array',
       items: {
-        $ref: '#/components/schemas/CurrencyBalanceDto'
+        $ref: '#/components/schemas/ExpectedTransactionDto'
       }
     }
   },
-  required: ['date', 'byCurrency']
+  required: ['expectedTransactions']
 } as const;
 
-export const $PortfolioTrendsResponseDto = {
+export const $ParserContributionRequestDto = {
   type: 'object',
   properties: {
-    series: {
-      description: 'Time series data points',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/TimeSeriesPointDto'
-      }
+    meta: {
+      $ref: '#/components/schemas/ParserContributionMetaDto'
     },
-    summary: {
-      description: 'Period summary',
+    samples: {
+      $ref: '#/components/schemas/ParserContributionSamplesDto'
+    },
+    fieldHints: {
+      $ref: '#/components/schemas/ParserContributionFieldHintsDto'
+    },
+    examples: {
+      description: 'Omitted entirely by the client when empty',
       allOf: [
         {
-          $ref: '#/components/schemas/TrendSummaryDto'
+          $ref: '#/components/schemas/ParserContributionExamplesDto'
         }
       ]
-    },
-    period: {
-      type: 'string',
-      description: 'Period requested',
-      example: '6m'
-    },
-    granularity: {
-      type: 'string',
-      description: 'Data granularity',
-      example: 'month'
-    },
-    currency: {
+    }
+  },
+  required: ['meta', 'samples', 'fieldHints']
+} as const;
+
+export const $ParserContributionRelayResponseDto = {
+  type: 'object',
+  properties: {
+    issueUrl: {
       type: 'string',
-      description: 'Base currency for converted values',
-      example: 'CNY'
-    },
-    byCurrency: {
-      description:
-        'Multi-currency time series (each point has currency breakdown)',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/MultiCurrencyPointDto'
-      }
+      example: 'https://github.com/fire-zu/firela-vlt/issues/42'
     },
-    warnings: {
-      description: 'Exchange rate warnings',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/ExchangeRateWarningDto'
-      }
+    issueNumber: {
+      type: 'number',
+      example: 42
     }
   },
-  required: ['series', 'summary', 'period', 'granularity', 'currency']
+  required: ['issueUrl', 'issueNumber']
 } as const;
 
-export const $CashFlowPointDto = {
+export const $SymbolSearchResultDto = {
   type: 'object',
   properties: {
-    month: {
+    symbol: {
       type: 'string',
-      description: 'Month key (YYYY-MM)',
-      example: '2024-03'
+      example: 'AAPL'
     },
-    income: {
+    name: {
       type: 'string',
-      description: 'Income in base currency (absolute, converted)',
-      example: '10000.00'
+      example: 'Apple Inc.',
+      nullable: true
     },
-    expense: {
+    exchange: {
       type: 'string',
-      description: 'Expense in base currency (absolute, converted)',
-      example: '5000.00'
+      example: 'US',
+      nullable: true
     },
-    netSavings: {
+    assetType: {
       type: 'string',
-      description: 'netSavings = income − expense (savings positive)',
-      example: '5000.00'
+      description: 'OpenBB asset_type (e.g. stock, etf)',
+      example: 'stock',
+      nullable: true
+    },
+    assetClass: {
+      type: 'string',
+      description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
+      example: 'EQUITY',
+      nullable: true
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
+      example: 'STOCK',
+      nullable: true
+    },
+    currency: {
+      type: 'string',
+      description: 'Trading currency (extra_data or inferred from exchange)',
+      example: 'USD',
+      nullable: true
     }
   },
-  required: ['month', 'income', 'expense', 'netSavings']
+  required: ['symbol']
 } as const;
 
-export const $CashFlowTrendSummaryDto = {
+export const $SymbolQuoteDto = {
   type: 'object',
   properties: {
-    totalIncome: {
+    symbol: {
       type: 'string',
-      description: 'Total income across the period',
-      example: '60000.00'
+      example: 'AAPL'
     },
-    totalExpense: {
+    name: {
       type: 'string',
-      description: 'Total expense across the period',
-      example: '30000.00'
+      example: 'Apple Inc.',
+      nullable: true
     },
-    totalNetSavings: {
+    exchange: {
       type: 'string',
-      description: 'income − expense across the period',
-      example: '30000.00'
+      example: 'US',
+      nullable: true
     },
-    averageMonthlyNetSavings: {
+    assetType: {
       type: 'string',
+      description: 'OpenBB asset_type',
+      example: 'stock',
+      nullable: true
+    },
+    assetClass: {
+      type: 'string',
+      description: 'IGN asset class',
+      example: 'EQUITY',
+      nullable: true
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'IGN asset sub-class',
+      example: 'STOCK',
+      nullable: true
+    },
+    currency: {
+      type: 'string',
+      description: 'Trading currency (extra_data or inferred from exchange)',
+      example: 'USD',
+      nullable: true
+    },
+    price: {
+      type: 'string',
+      description: 'Latest price (Decimal string)',
+      example: '189.84',
+      nullable: true
+    },
+    priceDate: {
+      type: 'string',
+      description: 'Date the price was observed (ISO yyyy-MM-dd)',
+      example: '2026-08-05',
+      nullable: true
+    },
+    changePercent: {
+      type: 'number',
       description:
-        'totalNetSavings divided by the window length (N months, incl. zero-filled)',
-      example: '5000.00'
-    }
-  },
-  required: [
-    'totalIncome',
-    'totalExpense',
-    'totalNetSavings',
-    'averageMonthlyNetSavings'
-  ]
-} as const;
-
-export const $CashFlowTrendsResponseDto = {
-  type: 'object',
-  properties: {
-    series: {
-      description:
-        'Monthly cash-flow series (fixed N-month window, zero-filled)',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/CashFlowPointDto'
-      }
+        'Change vs previous close, in percentage points (1.7 == 1.7%). openbb stores change_percent as a normalized decimal; this exposes percentage points for frontend convenience.',
+      example: 1.7,
+      nullable: true
     },
-    summary: {
-      description: 'Period totals',
-      allOf: [
-        {
-          $ref: '#/components/schemas/CashFlowTrendSummaryDto'
-        }
-      ]
+    prevClose: {
+      type: 'string',
+      description: 'Previous close (Decimal string)',
+      nullable: true
     },
-    period: {
+    open: {
       type: 'string',
-      description: 'Period requested',
-      example: '6m'
+      description: 'Day open (Decimal string)',
+      nullable: true
     },
-    granularity: {
+    high: {
       type: 'string',
-      description: 'Data granularity (v1 returns month buckets)',
-      example: 'month'
+      description: 'Day high (Decimal string)',
+      nullable: true
     },
-    currency: {
+    low: {
       type: 'string',
-      description: 'Base currency for converted values',
-      example: 'CNY'
+      description: 'Day low (Decimal string)',
+      nullable: true
     },
-    warnings: {
-      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/ExchangeRateWarningDto'
-      }
-    }
-  },
-  required: ['series', 'summary', 'period', 'granularity', 'currency']
-} as const;
-
-export const $GenerateSnapshotBody = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $GenerateSnapshotResponse = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $BackfillSnapshotsBody = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $BackfillSnapshotsResponse = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $AnonymousLoginDto = {
-  type: 'object',
-  properties: {
-    accessToken: {
+    volume: {
       type: 'string',
-      description: 'Access token for anonymous login'
+      description: 'Day volume (Decimal string)',
+      nullable: true
+    },
+    yearHigh: {
+      type: 'string',
+      description: '52-week high (Decimal string)',
+      nullable: true
+    },
+    yearLow: {
+      type: 'string',
+      description: '52-week low (Decimal string)',
+      nullable: true
     }
-  },
-  required: ['accessToken']
+  }
 } as const;