@firela/api-types 0.0.0-canary.8cbdced0 → 0.0.0-canary.9256c41b

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,22 @@ 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: {
+    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 +66,7 @@ export const $CreateAccountDto = {
       example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
     }
   },
-  required: ['path', 'openDate']
+  required: ['path']
 } as const;
 
 export const $AccountResponseDto = {
@@ -90,13 +80,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',
@@ -145,26 +129,26 @@ 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: 'Localized display name (ADR-0114, 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'
       }
@@ -192,7 +176,6 @@ export const $AccountResponseDto = {
   required: [
     'id',
     'path',
-    'displayName',
     'type',
     'status',
     'openDate',
@@ -225,11 +208,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 +229,15 @@ 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: {
+    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 +284,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,11 +332,6 @@ 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',
@@ -353,7 +356,7 @@ export const $AccountStandardResponseDto = {
       example: 'bank-icbc'
     }
   },
-  required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
+  required: ['path', 'type', 'description', 'tags', 'icon']
 } as const;
 
 export const $AccountStandardListResponseDto = {
@@ -383,18 +386,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 = {
@@ -533,7 +531,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,7 +690,7 @@ export const $PostingResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     units: {
       type: 'string',
@@ -1058,7 +1056,7 @@ export const $PostingDetailDto = {
     account: {
       type: 'string',
       description: 'Fully-qualified Beancount account path',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     units: {
       type: 'string',
@@ -1247,6 +1245,77 @@ export const $TransactionDetailDto = {
   ]
 } 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, 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'
+    },
+    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 $TransactionListResponseDto = {
   type: 'object',
   properties: {
@@ -1271,6 +1340,15 @@ export const $TransactionListResponseDto = {
       type: 'number',
       description: 'Number of items skipped',
       example: 0
+    },
+    summary: {
+      description:
+        'Amount summary for the full filtered set (#514). Present only when the request has a single account OR category viewpoint; omitted for search-only / plain-list / dual-perspective requests.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/TransactionListSummaryDto'
+        }
+      ]
     }
   },
   required: ['data', 'total', 'limit', 'offset']
@@ -1370,7 +1448,7 @@ export const $BalanceResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     balance: {
       type: 'string',
@@ -1397,7 +1475,7 @@ export const $MultiCurrencyBalanceResponseDto = {
     account: {
       type: 'string',
       description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     balances: {
       type: 'object',
@@ -1453,7 +1531,7 @@ export const $TransactionSummaryDto = {
     accountName: {
       type: 'string',
       description: 'Source account name (first posting)',
-      example: 'Assets:Bank:Checking'
+      example: 'Assets:Checking'
     },
     sourceType: {
       type: 'string',
@@ -2745,127 +2823,284 @@ export const $UpdateCommodityDto = {
   }
 } as const;
 
-export const $CreateRecurringRuleDto = {
+export const $CreateBeanPriceDto = {
   type: 'object',
   properties: {
-    name: {
-      type: 'string',
-      description: 'Rule name (unique per user)',
-      maxLength: 100
-    },
-    icon: {
-      type: 'string',
-      description: 'Icon emoji',
-      maxLength: 10
-    },
-    frequency: {
-      type: 'string',
-      description: 'Recurring frequency',
-      enum: [
-        'WEEKLY',
-        'BIWEEKLY',
-        'MONTHLY',
-        'BIMONTHLY',
-        'QUARTERLY',
-        'YEARLY',
-        'CUSTOM'
-      ]
-    },
-    expectedAmount: {
-      type: 'number',
-      description: 'Expected amount (positive number)',
-      minimum: 0
-    },
-    expectedDay: {
-      type: 'number',
-      description: 'Expected day of month (1-31)',
-      minimum: 1,
-      maximum: 31
-    },
-    customIntervalDays: {
-      type: 'number',
-      description: 'Custom interval in days (required for CUSTOM frequency)',
-      minimum: 1
-    },
     currency: {
       type: 'string',
-      description: 'Currency code',
-      default: 'CNY',
-      maxLength: 10
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'USD'
     },
-    matchPayeePattern: {
+    quoteCurrency: {
       type: 'string',
-      description: 'Payee matching pattern (supports wildcards)',
-      maxLength: 200
+      description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
+      example: 'CNY'
     },
-    matchAmountTolerance: {
+    amount: {
       type: 'number',
-      description: 'Amount tolerance percentage (0-1)',
-      default: 0.075,
-      minimum: 0,
-      maximum: 1
-    },
-    defaultExpenseAccount: {
-      type: 'string',
-      description: 'Default expense account for auto-create',
-      maxLength: 200
-    },
-    defaultPaymentAccount: {
-      type: 'string',
-      description: 'Default payment account for auto-create',
-      maxLength: 200
-    },
-    defaultPayee: {
-      type: 'string',
-      description: 'Default payee for auto-create',
-      maxLength: 200
-    },
-    autoCreate: {
-      type: 'boolean',
-      description: 'Auto-create transaction when expected date arrives',
-      default: false
+      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
     },
-    startDate: {
+    date: {
       type: 'string',
-      description: 'Rule start date (ISO format)'
+      description: 'Price date (ISO 8601 format)',
+      example: '2024-11-05'
     },
-    endDate: {
-      type: 'string',
-      description: 'Rule end date (ISO format)'
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (validated by Zod schema, max field lengths enforced)',
+      example: {
+        source: 'MANUAL',
+        note: 'Bank valuation report',
+        confidence: 0.95
+      }
     }
   },
-  required: [
-    'name',
-    'frequency',
-    'expectedAmount',
-    'currency',
-    'matchAmountTolerance',
-    'autoCreate'
-  ]
+  required: ['currency', 'quoteCurrency', 'amount', 'date']
 } as const;
 
-export const $RecurringRuleResponseDto = {
+export const $PriceResponseDto = {
   type: 'object',
   properties: {
     id: {
       type: 'string',
-      description: 'Rule ID'
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
     },
     userId: {
       type: 'string',
-      description: 'User ID'
+      description: 'User ID (owner of the price)',
+      example: 'user-123'
     },
-    name: {
+    currency: {
       type: 'string',
-      description: 'Rule name'
-    },
-    icon: {
-      type: 'object',
-      description: 'Icon emoji'
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'BTC'
     },
-    frequency: {
+    quoteCurrency: {
       type: 'string',
-      description: 'Recurring frequency'
+      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',
+    'amount',
+    'date',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $PriceListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of prices',
+      type: 'array',
+      items: {
+        $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 $CreateRecurringRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Rule name (unique per user)',
+      maxLength: 100
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon emoji',
+      maxLength: 10
+    },
+    frequency: {
+      type: 'string',
+      description: 'Recurring frequency',
+      enum: [
+        'WEEKLY',
+        'BIWEEKLY',
+        'MONTHLY',
+        'BIMONTHLY',
+        'QUARTERLY',
+        'YEARLY',
+        'CUSTOM'
+      ]
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount (positive number)',
+      minimum: 0
+    },
+    expectedDay: {
+      type: 'number',
+      description: 'Expected day of month (1-31)',
+      minimum: 1,
+      maximum: 31
+    },
+    customIntervalDays: {
+      type: 'number',
+      description: 'Custom interval in days (required for CUSTOM frequency)',
+      minimum: 1
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      default: 'CNY',
+      maxLength: 10
+    },
+    matchPayeePattern: {
+      type: 'string',
+      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 for auto-create',
+      maxLength: 200
+    },
+    defaultPaymentAccount: {
+      type: 'string',
+      description: 'Default payment account for auto-create',
+      maxLength: 200
+    },
+    defaultPayee: {
+      type: 'string',
+      description: 'Default payee for auto-create',
+      maxLength: 200
+    },
+    autoCreate: {
+      type: 'boolean',
+      description: 'Auto-create transaction when expected date arrives',
+      default: false
+    },
+    startDate: {
+      type: 'string',
+      description: 'Rule start date (ISO format)'
+    },
+    endDate: {
+      type: 'string',
+      description: 'Rule end date (ISO format)'
+    }
+  },
+  required: [
+    'name',
+    'frequency',
+    'expectedAmount',
+    'currency',
+    'matchAmountTolerance',
+    'autoCreate'
+  ]
+} as const;
+
+export const $RecurringRuleResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Rule ID'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Rule name'
+    },
+    icon: {
+      type: 'object',
+      description: 'Icon emoji'
+    },
+    frequency: {
+      type: 'string',
+      description: 'Recurring frequency'
     },
     expectedAmount: {
       type: 'number',
@@ -4189,6 +4424,27 @@ export const $SignupDto = {
   }
 } 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: {
@@ -4312,446 +4568,1876 @@ export const $UpdatePropertyDto = {
   required: ['value']
 } as const;
 
-export const $FileImportDto = {
+export const $CreateBeanEventDto = {
   type: 'object',
   properties: {
-    file: {
+    date: {
       type: 'string',
-      format: 'binary',
-      description: 'Bill file to import (CSV, PDF, OFX, etc.)',
-      example: 'alipay.csv'
+      description: 'Life event date (ISO 8601)',
+      example: '2024-03-15'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
+      example: {
+        note: 'Promotion'
+      }
     }
   },
-  required: ['file']
+  required: ['date', 'type', 'description']
 } as const;
 
-export const $ImportErrorDto = {
+export const $EventResponseDto = {
   type: 'object',
   properties: {
-    index: {
-      type: 'number',
-      description: 'Index of failed transaction in the file',
-      example: 5
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
     },
-    error: {
+    userId: {
       type: 'string',
-      description: 'Error message',
-      example: 'Transaction does not balance: -100 USD != 0'
-    }
-  },
-  required: ['index', 'error']
-} as const;
-
-export const $ReviewItemPreviewDto = {
-  type: 'object',
-  properties: {
-    index: {
-      type: 'number',
-      description: 'Index in the import batch (for tracking)',
-      example: 0
+      description: 'User ID (owner of the life event)',
+      example: 'user-123'
     },
     date: {
       type: 'string',
-      description: 'Transaction date (ISO format)',
-      example: '2026-03-05'
-    },
-    amount: {
-      type: 'number',
-      description: 'Transaction amount (absolute value)',
-      example: 99
+      description: 'Life event date (ISO 8601 format)',
+      example: '2024-03-15',
+      format: 'date'
     },
-    currency: {
+    type: {
       type: 'string',
-      description: 'Currency code',
-      example: 'CNY'
+      description:
+        'Life event type (user-defined, e.g., "employer", "location")',
+      example: 'employer'
     },
-    narration: {
+    description: {
       type: 'string',
-      description: 'Transaction narration/description',
-      example: 'Restaurant expense'
+      description:
+        'Life event description. May be an empty string (a valid value distinct from absence).',
+      example: 'Acme Corp'
     },
-    payee: {
-      type: 'string',
-      description: 'Payee name',
-      example: 'Restaurant ABC'
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)',
+      example: {
+        note: 'Promotion'
+      }
     },
-    category: {
+    createdAt: {
+      format: 'date-time',
       type: 'string',
-      description: 'Inferred category from rule matching',
-      example: 'food'
-    },
-    confidence: {
-      type: 'number',
-      description: 'Confidence score for the match (0-1)',
-      example: 0.85
+      description: 'Creation timestamp',
+      example: '2024-03-15T10:00:00Z'
     },
-    branchType: {
+    updatedAt: {
+      format: 'date-time',
       type: 'string',
-      description: 'Type of branch requiring review',
-      enum: [
-        'DUPLICATE',
-        'PAYEE_MATCH',
-        'RULE_MATCH',
-        'ACCOUNT_VALIDATION',
-        'PIPELINE_ERROR'
-      ],
-      example: 'RULE_MATCH'
-    },
-    reasons: {
-      description: 'Human-readable reasons for requiring review',
-      example: ['Moderate confidence rule match', 'Multiple rules matched'],
-      type: 'array',
-      items: {
-        type: 'string'
-      }
+      description:
+        'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
+      example: '2024-03-15T10:00:00Z'
     }
   },
-  required: ['index', 'date', 'narration']
+  required: [
+    'id',
+    'userId',
+    'date',
+    'type',
+    'description',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
 } as const;
 
-export const $ImportResultDto = {
+export const $EventListResponseDto = {
   type: 'object',
   properties: {
-    imported: {
-      type: 'number',
-      description: 'Number of successfully imported transactions',
-      example: 45
-    },
-    failed: {
-      type: 'number',
-      description: 'Number of failed transactions',
-      example: 2
-    },
-    skipped: {
-      type: 'number',
-      description:
-        'Number of skipped transactions (high confidence duplicates, auto-skipped)',
-      example: 3
-    },
-    pendingReview: {
-      type: 'number',
-      description:
-        'Number of transactions pending review (medium confidence duplicates)',
-      example: 2
-    },
-    errors: {
-      description: 'Array of error details for failed transactions',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/ImportErrorDto'
-      }
-    },
-    reviewItems: {
-      description:
-        'Array of transactions pending review with preview data. Contains essential information for displaying in the import preview UI.',
+    items: {
+      description: 'List of life events',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/ReviewItemPreviewDto'
+        $ref: '#/components/schemas/EventResponseDto'
       }
     },
-    transactions: {
-      type: 'object',
-      description: 'Array of imported transactions (optional, for debugging)'
+    total: {
+      type: 'number',
+      description: 'Total number of life events matching the query',
+      example: 42
     }
   },
-  required: ['imported', 'failed', 'skipped', 'pendingReview', 'errors']
+  required: ['items', 'total']
 } as const;
 
-export const $IdentifyResultDto = {
+export const $UpdateBeanEventDto = {
   type: 'object',
   properties: {
-    identified: {
-      type: 'boolean',
-      description: 'Whether the file was successfully identified',
-      example: true
-    },
-    importerName: {
+    date: {
       type: 'string',
-      description: 'Name of the importer that can handle this file',
-      example: 'AlipayImporter'
+      description: 'Life event date (ISO 8601)'
     },
-    importerId: {
+    type: {
       type: 'string',
-      description: 'Unique identifier of the importer',
-      example: 'alipay'
+      description: 'Life event type (user-defined)'
     },
-    account: {
+    description: {
       type: 'string',
-      description: 'Default account used by this importer',
-      example: 'Assets:Alipay:Balance'
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).'
     },
-    message: {
-      type: 'string',
-      description: 'Message when file cannot be identified',
-      example: 'No matching importer found'
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)'
     }
-  },
-  required: ['identified']
+  }
 } as const;
 
-export const $MapperDefaultsDto = {
+export const $OnboardingAccountDto = {
   type: 'object',
   properties: {
-    sourceAccount: {
+    path: {
       type: 'string',
-      description: 'Source account for transactions (Beancount format)',
-      example: 'Assets:Alipay:Balance'
+      description:
+        'Account path (Assets/Liabilities only; format validated by the account service)',
+      example: 'Assets:Checking'
     },
     currency: {
       type: 'string',
-      description: 'Default currency (ISO 4217 code)',
-      example: 'CNY'
+      description: 'ISO 4217 currency code (3 letters)',
+      example: 'USD'
     },
-    expenseAccount: {
+    openingBalance: {
       type: 'string',
-      description: 'Default expense account',
-      example: 'Expenses:Unknown'
+      description:
+        'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
+      example: '1000.00'
     },
-    incomeAccount: {
+    platformId: {
       type: 'string',
-      description: 'Default income account',
-      example: 'Income:Unknown'
-    },
-    accountMapping: {
-      type: 'object',
       description:
-        'Filename prefix to account mapping (for HK importers). Maps filename prefix to Beancount account path.',
-      example: {
-        One: 'Assets:HSBC:One',
-        PULSE: 'Liabilities:CreditCards:HSBC:Pulse'
+        'Platform ID to bind the account to (references Platform.id); omit for unbound',
+      example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
+    }
+  },
+  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'
       }
     },
-    useCnh: {
+    skipAssetRegistration: {
       type: 'boolean',
       description:
-        'Convert CNY to CNH (offshore RMB) (for HK importers). Default: false.',
-      example: false
-    },
-    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'
-      }
+        'Skip asset registration; only bootstrap the core account set',
+      default: false
     }
-  },
-  required: ['sourceAccount', 'currency']
+  }
 } as const;
 
-export const $ImporterConfigDataDto = {
+export const $ActualBalanceDto = {
   type: 'object',
   properties: {
-    defaults: {
-      description: 'Mapper defaults configuration',
-      allOf: [
-        {
-          $ref: '#/components/schemas/MapperDefaultsDto'
-        }
-      ]
+    amount: {
+      type: 'string',
+      description:
+        'Actual balance amount as a decimal string (preserves precision for tolerance inference).',
+      example: '1234.56'
+    },
+    ccy: {
+      type: 'string',
+      description: 'Currency code (ISO 4217 or commodity ticker).',
+      example: 'CNY'
     }
   },
-  required: ['defaults']
+  required: ['amount', 'ccy']
 } as const;
 
-export const $VersionedConfigDto = {
+export const $ComputeReconciliationDto = {
   type: 'object',
   properties: {
-    version: {
+    accountId: {
       type: 'string',
-      description: 'Configuration version (semver)',
-      example: '1.0.0'
+      description: 'BeanAccount id to reconcile.'
     },
-    schema: {
+    asOfDate: {
       type: 'string',
-      description: 'Configuration schema identifier',
-      example: 'importer-config-v1'
+      description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
+      example: '2026-07-24'
     },
-    data: {
-      description: 'Configuration data',
+    actualBalance: {
+      description: 'Actual balance from the external statement.',
       allOf: [
         {
-          $ref: '#/components/schemas/ImporterConfigDataDto'
+          $ref: '#/components/schemas/ActualBalanceDto'
         }
       ]
     }
   },
-  required: ['version', 'schema', 'data']
+  required: ['accountId', 'asOfDate', 'actualBalance']
 } as const;
 
-export const $ImporterConfigDto = {
+export const $ReconciliationComputeResultDto = {
   type: 'object',
   properties: {
-    id: {
+    accountId: {
+      type: 'string'
+    },
+    asOfDate: {
+      type: 'string'
+    },
+    bookBalance: {
       type: 'string',
-      description: 'Configuration ID',
-      example: 'clx1234567890'
+      description: 'System-computed book balance (decimal string).'
     },
-    userId: {
+    actualBalance: {
       type: 'string',
-      description: 'User ID',
-      example: 'user-abc-123'
+      description: 'User-entered actual balance (decimal string).'
     },
-    importerId: {
+    currency: {
+      type: 'string'
+    },
+    diff: {
       type: 'string',
-      description: 'Importer identifier',
-      example: 'alipay',
-      enum: [
-        'alipay',
-        'alipay-web',
-        'alipay-yuebao',
-        'wechat',
-        'wechat-xlsx',
-        'boc',
-        'boc-credit',
-        'ccb',
-        'cmb',
-        'cmbc',
-        'cmbc-credit',
-        'icbc',
-        'icbc-credit',
-        'hsbc-hk-credit',
-        'hsbc-hk-debit'
-      ]
+      description: 'Diff = book − actual (decimal string).'
     },
-    version: {
+    tolerance: {
       type: 'string',
-      description: 'Configuration version (semver)',
-      example: '1.0.0'
+      description: 'Applied tolerance (decimal string).'
     },
-    schema: {
+    withinTolerance: {
+      type: 'boolean',
+      description: 'true when |diff| ≤ tolerance.'
+    },
+    suggestedAction: {
       type: 'string',
-      description: 'Configuration schema identifier',
-      example: 'importer-config-v1'
+      enum: ['assert', 'pad'],
+      description:
+        'Suggested next action: assert when within tolerance, pad otherwise.'
+    }
+  },
+  required: [
+    'accountId',
+    'asOfDate',
+    'bookBalance',
+    'actualBalance',
+    'currency',
+    'diff',
+    'tolerance',
+    'withinTolerance',
+    'suggestedAction'
+  ]
+} as const;
+
+export const $AssertReconciliationDto = {
+  type: 'object',
+  properties: {
+    accountId: {
+      type: 'string',
+      description: 'BeanAccount id to reconcile.'
     },
-    config: {
-      description: 'Configuration data (validated against Zod schema)',
+    asOfDate: {
+      type: 'string',
+      description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
+      example: '2026-07-24'
+    },
+    actualBalance: {
+      description: 'Actual balance from the external statement.',
       allOf: [
         {
-          $ref: '#/components/schemas/VersionedConfigDto'
+          $ref: '#/components/schemas/ActualBalanceDto'
         }
       ]
     },
-    createdAt: {
-      format: 'date-time',
+    tolerance: {
       type: 'string',
-      description: 'Creation timestamp',
-      example: '2025-01-27T10:00:00Z'
+      description:
+        'Optional explicit tolerance override. Omit to infer from amount precision (Beancount default).',
+      example: '0.01'
+    }
+  },
+  required: ['accountId', 'asOfDate', 'actualBalance']
+} as const;
+
+export const $ReconciliationRecordDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string'
     },
-    updatedAt: {
-      format: 'date-time',
+    accountId: {
+      type: 'string'
+    },
+    date: {
+      type: 'string'
+    },
+    amount: {
       type: 'string',
-      description: 'Last update timestamp',
-      example: '2025-01-27T10:00:00Z'
+      description: 'Asserted (actual) amount.'
+    },
+    currency: {
+      type: 'string'
+    },
+    tolerance: {
+      type: 'string'
+    },
+    diffAmount: {
+      type: 'string',
+      description: 'book − actual.'
+    },
+    diffCurrency: {
+      type: 'string'
+    },
+    createdAt: {
+      type: 'string'
     }
   },
-  required: [
-    'id',
-    'userId',
-    'importerId',
-    'version',
-    'schema',
-    'config',
-    'createdAt',
-    'updatedAt'
-  ]
+  required: ['id', 'accountId', 'date', 'amount', 'currency', 'createdAt']
 } as const;
 
-export const $UpdateMapperDefaultsDto = {
+export const $PadReconciliationDto = {
   type: 'object',
   properties: {
+    accountId: {
+      type: 'string',
+      description: 'BeanAccount id to reconcile.'
+    },
+    asOfDate: {
+      type: 'string',
+      description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
+      example: '2026-07-24'
+    },
+    actualBalance: {
+      description: 'Actual balance from the external statement.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ActualBalanceDto'
+        }
+      ]
+    },
     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-:]+$'
+      description:
+        'Pad source account. Defaults to Equity:Opening-Balances (official Beancount convention).',
+      example: 'Equity:Opening-Balances',
+      default: 'Equity:Opening-Balances'
+    }
+  },
+  required: ['accountId', 'asOfDate', 'actualBalance']
+} as const;
+
+export const $PadResultDto = {
+  type: 'object',
+  properties: {
+    transactionId: {
+      type: 'string',
+      description: 'Created pad adjusting transaction id.'
+    }
+  },
+  required: ['transactionId']
+} as const;
+
+export const $FileImportDto = {
+  type: 'object',
+  properties: {
+    file: {
+      type: 'string',
+      format: 'binary',
+      description: 'Bill file to import (CSV, PDF, OFX, etc.)',
+      example: 'alipay.csv'
+    }
+  },
+  required: ['file']
+} as const;
+
+export const $ImportErrorDto = {
+  type: 'object',
+  properties: {
+    index: {
+      type: 'number',
+      description: 'Index of failed transaction in the file',
+      example: 5
+    },
+    error: {
+      type: 'string',
+      description: 'Error message',
+      example: 'Transaction does not balance: -100 USD != 0'
+    }
+  },
+  required: ['index', 'error']
+} as const;
+
+export const $ReviewItemPreviewDto = {
+  type: 'object',
+  properties: {
+    index: {
+      type: 'number',
+      description: 'Index in the import batch (for tracking)',
+      example: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)',
+      example: '2026-03-05'
+    },
+    amount: {
+      type: 'number',
+      description: 'Transaction amount (absolute value)',
+      example: 99
     },
     currency: {
       type: 'string',
-      description: 'Default currency (ISO 4217 code)',
-      example: 'CNY',
-      minLength: 3,
-      maxLength: 3,
-      pattern: '^[A-Z]{3}$'
+      description: 'Currency code',
+      example: 'CNY'
     },
-    expenseAccount: {
+    narration: {
       type: 'string',
-      description: 'Default expense account (optional)',
-      example: 'Expenses:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+      description: 'Transaction narration/description',
+      example: 'Restaurant expense'
     },
-    incomeAccount: {
+    payee: {
       type: 'string',
-      description: 'Default income account (optional)',
-      example: 'Income:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+      description: 'Payee name',
+      example: 'Restaurant ABC'
     },
-    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'
+    category: {
+      type: 'string',
+      description: 'Inferred category from rule matching',
+      example: 'food'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for the match (0-1)',
+      example: 0.85
+    },
+    branchType: {
+      type: 'string',
+      description: 'Type of branch requiring review',
+      enum: [
+        'DUPLICATE',
+        'PAYEE_MATCH',
+        'RULE_MATCH',
+        'ACCOUNT_VALIDATION',
+        'PIPELINE_ERROR'
+      ],
+      example: 'RULE_MATCH'
+    },
+    reasons: {
+      description: 'Human-readable reasons for requiring review',
+      example: ['Moderate confidence rule match', 'Multiple rules matched'],
+      type: 'array',
+      items: {
+        type: 'string'
       }
     }
-  }
+  },
+  required: ['index', 'date', 'narration']
 } as const;
 
-export const $UpdateConfigDataDto = {
+export const $ImportResultDto = {
   type: 'object',
   properties: {
-    defaults: {
-      description: 'Mapper defaults configuration',
+    imported: {
+      type: 'number',
+      description: 'Number of successfully imported transactions',
+      example: 45
+    },
+    failed: {
+      type: 'number',
+      description: 'Number of failed transactions',
+      example: 2
+    },
+    skipped: {
+      type: 'number',
+      description:
+        'Number of skipped transactions (high confidence duplicates, auto-skipped)',
+      example: 3
+    },
+    pendingReview: {
+      type: 'number',
+      description:
+        'Number of transactions pending review (medium confidence duplicates)',
+      example: 2
+    },
+    errors: {
+      description: 'Array of error details for failed transactions',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ImportErrorDto'
+      }
+    },
+    reviewItems: {
+      description:
+        'Array of transactions pending review with preview data. Contains essential information for displaying in the import preview UI.',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ReviewItemPreviewDto'
+      }
+    },
+    transactions: {
+      type: 'object',
+      description: 'Array of imported transactions (optional, for debugging)'
+    }
+  },
+  required: ['imported', 'failed', 'skipped', 'pendingReview', 'errors']
+} as const;
+
+export const $IdentifyResultDto = {
+  type: 'object',
+  properties: {
+    identified: {
+      type: 'boolean',
+      description: 'Whether the file was successfully identified',
+      example: true
+    },
+    importerName: {
+      type: 'string',
+      description: 'Name of the importer that can handle this file',
+      example: 'AlipayImporter'
+    },
+    importerId: {
+      type: 'string',
+      description: 'Unique identifier of the importer',
+      example: 'alipay'
+    },
+    account: {
+      type: 'string',
+      description: 'Default account used by this importer',
+      example: 'Assets:CN:Alipay:Balance'
+    },
+    message: {
+      type: 'string',
+      description: 'Message when file cannot be identified',
+      example: 'No matching importer found'
+    }
+  },
+  required: ['identified']
+} as const;
+
+export const $MapperDefaultsDto = {
+  type: 'object',
+  properties: {
+    sourceAccount: {
+      type: 'string',
+      description: 'Source account for transactions (Beancount format)',
+      example: 'Assets:CN:Alipay:Balance'
+    },
+    currency: {
+      type: 'string',
+      description: 'Default currency (ISO 4217 code)',
+      example: 'CNY'
+    },
+    expenseAccount: {
+      type: 'string',
+      description: 'Default expense account',
+      example: 'Expenses:Unknown'
+    },
+    incomeAccount: {
+      type: 'string',
+      description: 'Default income account',
+      example: 'Income:Unknown'
+    },
+    accountMapping: {
+      type: 'object',
+      description:
+        'Filename prefix to account mapping (for HK importers). Maps filename prefix to Beancount account path.',
+      example: {
+        One: 'Assets:HSBC:One',
+        PULSE: 'Liabilities:CreditCards:HSBC:Pulse'
+      }
+    },
+    useCnh: {
+      type: 'boolean',
+      description:
+        'Convert CNY to CNH (offshore RMB) (for HK importers). Default: false.',
+      example: false
+    },
+    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'
+      }
+    }
+  },
+  required: ['sourceAccount', 'currency']
+} as const;
+
+export const $ImporterConfigDataDto = {
+  type: 'object',
+  properties: {
+    defaults: {
+      description: 'Mapper defaults configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/MapperDefaultsDto'
+        }
+      ]
+    }
+  },
+  required: ['defaults']
+} as const;
+
+export const $VersionedConfigDto = {
+  type: 'object',
+  properties: {
+    version: {
+      type: 'string',
+      description: 'Configuration version (semver)',
+      example: '1.0.0'
+    },
+    schema: {
+      type: 'string',
+      description: 'Configuration schema identifier',
+      example: 'importer-config-v1'
+    },
+    data: {
+      description: 'Configuration data',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ImporterConfigDataDto'
+        }
+      ]
+    }
+  },
+  required: ['version', 'schema', 'data']
+} as const;
+
+export const $ImporterConfigDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Configuration ID',
+      example: 'clx1234567890'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID',
+      example: 'user-abc-123'
+    },
+    importerId: {
+      type: 'string',
+      description: 'Importer identifier',
+      example: 'alipay',
+      enum: [
+        'alipay',
+        'alipay-web',
+        'alipay-yuebao',
+        'wechat',
+        'wechat-xlsx',
+        'boc',
+        'boc-credit',
+        'ccb',
+        'cmb',
+        'cmbc',
+        'cmbc-credit',
+        'icbc',
+        'icbc-credit',
+        'hsbc-hk-credit',
+        'hsbc-hk-debit'
+      ]
+    },
+    version: {
+      type: 'string',
+      description: 'Configuration version (semver)',
+      example: '1.0.0'
+    },
+    schema: {
+      type: 'string',
+      description: 'Configuration schema identifier',
+      example: 'importer-config-v1'
+    },
+    config: {
+      description: 'Configuration data (validated against Zod schema)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/VersionedConfigDto'
+        }
+      ]
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2025-01-27T10:00:00Z'
+    },
+    updatedAt: {
+      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:CN: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: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;
+
+export const $ProviderSyncConfigDto = {
+  type: 'object',
+  properties: {
+    sourceAccount: {
+      type: 'string',
+      description: 'Source account for the first posting',
+      example: 'Assets:US:Chase:Checking'
+    },
+    defaultCurrency: {
+      type: 'string',
+      description: 'Default currency for transactions',
+      example: 'USD'
+    },
+    defaultExpenseAccount: {
+      type: 'string',
+      description: 'Default expense account for the second posting',
+      example: 'Expenses:Unknown'
+    },
+    defaultIncomeAccount: {
+      type: 'string',
+      description: 'Default income account for the second posting',
+      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'
+  ]
+} as const;
+
+export const $ProviderSyncDto = {
+  type: 'object',
+  properties: {
+    provider: {
+      type: 'string',
+      description:
+        'Provider name (already in URL path, optional here for reference)',
+      example: 'plaid'
+    },
+    syncId: {
+      type: 'string',
+      description: 'Unique sync identifier for idempotency',
+      example: 'sync-12345'
+    },
+    config: {
+      description: 'Provider sync configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ProviderSyncConfigDto'
+        }
+      ]
+    },
+    transactions: {
+      type: 'array',
+      description: 'Raw transactions from provider',
+      example: [
+        {
+          transaction_id: 'txn-001',
+          amount: 50,
+          iso_currency_code: 'USD',
+          date: '2024-01-15',
+          merchant_name: 'Starbucks',
+          name: 'STARBUCKS STORE 12345',
+          pending: false,
+          account_id: 'acc-001'
+        }
+      ]
+    }
+  },
+  required: ['config', 'transactions']
+} as const;
+
+export const $ProviderSyncResponseDto = {
+  type: 'object',
+  properties: {
+    imported: {
+      type: 'number',
+      description: 'Number of transactions successfully imported',
+      example: 10
+    },
+    skipped: {
+      type: 'number',
+      description: 'Number of transactions skipped (duplicates)',
+      example: 2
+    },
+    pendingReview: {
+      type: 'number',
+      description: 'Number of transactions pending review',
+      example: 3
+    },
+    failed: {
+      type: 'number',
+      description: 'Number of transactions that failed to import',
+      example: 0
+    },
+    importedTransactionIds: {
+      description: 'IDs of successfully imported transactions',
+      example: ['txn-001', 'txn-002'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    reviewItemIds: {
+      description: 'IDs of review items created for branched transactions',
+      example: ['review-001', 'review-002'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['imported', 'skipped', 'pendingReview', 'failed']
+} as const;
+
+export const $SupportedProvidersResponseDto = {
+  type: 'object',
+  properties: {
+    providers: {
+      description: 'List of supported provider names',
+      example: [
+        'plaid',
+        'teller',
+        'truelayer',
+        'gocardless',
+        'simplefin',
+        'yodlee',
+        'beancount-direct',
+        'parsed-bill'
+      ],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  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 $ProcessNlpDto = {
+  type: 'object',
+  properties: {
+    message: {
+      type: 'string',
+      description: 'Natural language text describing a transaction (Chinese)',
+      example: 'yesterday Starbucks spent 35 yuan',
+      maxLength: 500
+    },
+    sessionId: {
+      type: 'string',
+      description:
+        'Session ID for multi-turn conversation (auto-generated if not provided)',
+      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'
+      }
+    }
+  },
+  required: ['message']
+} as const;
+
+export const $NlpTransactionInfoDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Transaction ID'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'number',
+      description: 'Transaction amount'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    warning: {
+      type: 'string',
+      description:
+        'Warning message for special transaction scenarios (e.g., cross-currency settlement)',
+      example: '此交易使用USD账户结算。如需记录CNY支出，请创建货币转换交易。'
+    }
+  },
+  required: ['id', 'date', 'amount', 'currency']
+} as const;
+
+export const $NlpParsedDataDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'number',
+      description: 'Extracted amount'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      default: 'CNY'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    category: {
+      type: 'string',
+      description: 'Category'
+    },
+    incomeType: {
+      type: 'string',
+      description: 'Income type (e.g., Salary, Bonus, Dividend, Interest)',
+      example: 'Salary'
+    },
+    incomeSource: {
+      type: 'string',
+      description: 'Income source (e.g., company name)',
+      example: 'Anthropic Inc.'
+    },
+    symbol: {
+      type: 'string',
+      description: 'Security symbol code (e.g., 600519, AAPL)',
+      example: '600519'
+    },
+    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:
+        'Warning message for special scenarios (e.g., cross-currency settlement)',
+      example: '此交易使用USD账户结算。如需记录CNY支出，请创建货币转换交易。'
+    }
+  }
+} as const;
+
+export const $NlpSourceTransactionDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'string',
+      description: 'Amount as string'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    }
+  },
+  required: ['date', 'amount', 'currency', 'narration']
+} as const;
+
+export const $NlpTargetTransactionDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Existing transaction ID'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'string',
+      description: 'Amount as string'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    }
+  },
+  required: ['id', 'date', 'amount', 'currency', 'narration']
+} as const;
+
+export const $NlpSimilarityDto = {
+  type: 'object',
+  properties: {
+    dateMatch: {
+      type: 'boolean',
+      description: 'Whether dates match'
+    },
+    dateDiff: {
+      type: 'number',
+      description: 'Date difference in days'
+    },
+    amountMatch: {
+      type: 'boolean',
+      description: 'Whether amounts match'
+    },
+    amountDiff: {
+      type: 'string',
+      description: 'Amount difference as decimal string'
+    },
+    payeeMatch: {
+      type: 'boolean',
+      description: 'Whether payees match'
+    },
+    payeeSimilarity: {
+      type: 'number',
+      description: 'Payee similarity score (0-1)'
+    },
+    accountOverlap: {
+      type: 'number',
+      description: 'Account overlap score (0-1)'
+    }
+  },
+  required: [
+    'dateMatch',
+    'dateDiff',
+    'amountMatch',
+    'amountDiff',
+    'payeeMatch',
+    'payeeSimilarity',
+    'accountOverlap'
+  ]
+} as const;
+
+export const $NlpDuplicateConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Duplicate detection confidence score (0.5-0.89)',
+      example: 0.85
+    },
+    sourceTransaction: {
+      description:
+        'Source transaction summary (the new transaction being entered)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSourceTransactionDto'
+        }
+      ]
+    },
+    targetTransaction: {
+      description: 'Target transaction summary (existing potential duplicate)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpTargetTransactionDto'
+        }
+      ]
+    },
+    similarity: {
+      description: 'Detailed similarity information',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSimilarityDto'
+        }
+      ]
+    },
+    reasons: {
+      description: 'Human-readable reasons for duplicate detection',
+      example: ['日期匹配', '金额匹配', '商户相似'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'sourceTransaction',
+    'targetTransaction',
+    'similarity',
+    'reasons'
+  ]
+} as const;
+
+export const $NlpRuleConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Rule match confidence score (0.5-0.74)',
+      example: 0.65
+    },
+    matchedRule: {
+      type: 'object',
+      description: 'Matched rule information'
+    },
+    suggestedAccounts: {
+      type: 'object',
+      description: 'Suggested accounts from the rule'
+    },
+    alternatives: {
+      type: 'array',
+      description: 'Alternative rules that also match'
+    },
+    reasons: {
+      description: 'Human-readable reasons for the match',
+      example: [
+        'Moderate confidence (65%)',
+        'Some keywords matched (OR logic)'
+      ],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'matchedRule',
+    'suggestedAccounts',
+    'alternatives',
+    'reasons'
+  ]
+} as const;
+
+export const $NlpAccountConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    invalidAccount: {
+      type: 'string',
+      description: 'The invalid account name',
+      example: 'Expenses:Food:Coffee'
+    },
+    suggestedAccount: {
+      type: 'string',
+      description: 'Suggested replacement account',
+      example: 'Expenses:Food:Drinks'
+    },
+    similarAccounts: {
+      description: 'Similar accounts for user selection',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    errorMessage: {
+      type: 'string',
+      description: 'Error message explaining the issue',
+      example: 'No similar account found'
+    },
+    transactionContext: {
+      type: 'object',
+      description: 'Transaction context for reference'
+    }
+  },
+  required: [
+    'invalidAccount',
+    'suggestedAccount',
+    'similarAccounts',
+    'errorMessage',
+    'transactionContext'
+  ]
+} as const;
+
+export const $NlpSuggestedPayeeDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Payee ID',
+      example: 'payee-123'
+    },
+    name: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Starbucks'
+    },
+    category: {
+      type: 'string',
+      description: 'Payee category',
+      example: 'food'
+    },
+    source: {
+      type: 'string',
+      description: 'Source of the payee',
+      enum: ['user', 'global']
+    },
+    payeeProfileId: {
+      type: 'string',
+      description: 'PayeeProfile ID (if matched from global)',
+      example: 'profile-456'
+    }
+  },
+  required: ['id', 'name']
+} as const;
+
+export const $NlpAlternativePayeeDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Payee ID',
+      example: 'payee-alt-1'
+    },
+    name: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Starbucks Coffee'
+    },
+    similarity: {
+      type: 'number',
+      description: 'Similarity score (0-1)',
+      example: 0.75
+    }
+  },
+  required: ['id', 'name', 'similarity']
+} as const;
+
+export const $NlpPayeeConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for the payee match (0-1)',
+      example: 0.65
+    },
+    originalPayee: {
+      type: 'string',
+      description: 'Original payee string from user input',
+      example: '星巴'
+    },
+    suggestedPayee: {
+      description: 'Suggested payee to use (null when no similar payees found)',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedPayeeDto'
+        }
+      ]
+    },
+    similarity: {
+      type: 'number',
+      description: 'Similarity score between original and suggested (0-1)',
+      example: 0.85
+    },
+    alternatives: {
+      description: 'Alternative payee options',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/NlpAlternativePayeeDto'
+      }
+    },
+    reasons: {
+      description: 'Human-readable reasons for the match',
+      example: ['Moderate similarity (65%)', 'Fuzzy match on name'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'originalPayee',
+    'similarity',
+    'alternatives',
+    'reasons'
+  ]
+} as const;
+
+export const $RecurringMatchInfoDto = {
+  type: 'object',
+  properties: {
+    expectedId: {
+      type: 'string',
+      description: 'Expected transaction ID'
+    },
+    ruleId: {
+      type: 'string',
+      description: 'Recurring rule ID'
+    },
+    ruleName: {
+      type: 'string',
+      description: 'Rule name for display'
+    },
+    ruleIcon: {
+      type: 'string',
+      description: 'Rule icon'
+    },
+    expectedDate: {
+      type: 'string',
+      description: 'Expected date (YYYY-MM-DD)',
+      example: '2026-01-05'
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount',
+      example: 3000
+    },
+    confidence: {
+      type: 'number',
+      description: 'Match confidence score (0-1)',
+      example: 0.88
+    },
+    isAutoMatched: {
+      type: 'boolean',
+      description: 'Whether auto-matched (confidence >= 0.82)'
+    }
+  },
+  required: [
+    'expectedId',
+    'ruleId',
+    'ruleName',
+    'expectedDate',
+    'expectedAmount',
+    'confidence',
+    'isAutoMatched'
+  ]
+} as const;
+
+export const $NlpSuggestedAccountDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description: 'Suggested account path',
+      example: 'Assets:Checking'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for this suggestion (0-1)',
+      example: 0.9
+    }
+  },
+  required: ['account']
+} as const;
+
+export const $NlpSuggestedAccountsDto = {
+  type: 'object',
+  properties: {
+    source: {
+      description:
+        'Source account suggestion (where money comes from). For expense: asset/liability account. For income: income account.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountDto'
+        }
+      ]
+    },
+    destination: {
+      description:
+        'Destination account suggestion (where money goes to). For expense: expense account. For income: asset/liability account.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountDto'
+        }
+      ]
+    }
+  }
+} as const;
+
+export const $NlpDefaultAccountsDto = {
+  type: 'object',
+  properties: {
+    asset: {
+      type: 'string',
+      description: 'Default asset account',
+      example: 'Assets:Checking'
+    },
+    expense: {
+      type: 'string',
+      description: 'Default expense account',
+      example: 'Expenses:Uncategorized'
+    },
+    income: {
+      type: 'string',
+      description: 'Default income account',
+      example: 'Income:Uncategorized'
+    },
+    liability: {
+      type: 'string',
+      description: 'Default liability account',
+      example: 'Liabilities:CreditCard'
+    }
+  },
+  required: ['asset', 'expense', 'income', 'liability']
+} as const;
+
+export const $NlpResponseDto = {
+  type: 'object',
+  properties: {
+    status: {
+      type: 'string',
+      description: 'Response status',
+      enum: ['success', 'pending', 'error']
+    },
+    action: {
+      type: 'string',
+      description: 'Action taken or requested',
+      enum: [
+        'created',
+        'ask',
+        'confirm',
+        'confirm_duplicate',
+        'confirm_rule',
+        'confirm_account',
+        'confirm_payee',
+        'cancel'
+      ]
+    },
+    intent: {
+      type: 'string',
+      description:
+        'Transaction intent detected by EntityRouter (v6.0: 5 core intents). Frontend uses this to render scenario-specific form fields.',
+      enum: ['expense', 'asset', 'income', 'liability', 'equity'],
+      example: 'expense'
+    },
+    assetSubType: {
+      type: 'string',
+      description:
+        'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
+      enum: ['transfer', 'banking', 'investment'],
+      example: 'investment'
+    },
+    liabilitySubType: {
+      type: 'string',
+      description:
+        'Liability sub-type (only present when intent is "liability"). borrow: borrowing money (Liabilities → Assets), repay: repaying debt (Assets → Liabilities).',
+      enum: ['borrow', 'repay'],
+      example: 'borrow'
+    },
+    equitySubType: {
+      type: 'string',
+      description:
+        'Equity sub-type (only present when intent is "equity"). opening: account opening balance (Equity → Assets), adjustment: balance correction.',
+      enum: ['opening', 'adjustment'],
+      example: 'opening'
+    },
+    paymentSource: {
+      type: 'string',
+      description:
+        'Payment source for expense transactions (v6.1). Indicates whether payment comes from asset or liability account. Only present when intent is "expense".',
+      enum: ['asset', 'liability'],
+      example: 'liability'
+    },
+    liabilityHint: {
+      type: 'string',
+      description:
+        'Liability account type hint for credit card/BNPL spending (v6.1). Only present when paymentSource is "liability". Values: CreditCard, Huabei, Baitiao',
+      example: 'CreditCard'
+    },
+    message: {
+      type: 'string',
+      description:
+        'Human-readable message (for ask or error actions). Deprecated: Use messageKey for i18n support.',
+      example: 'How much did you spend?',
+      deprecated: true
+    },
+    messageKey: {
+      type: 'string',
+      description:
+        'i18n message key for frontend translation. Use this instead of message for internationalization support.',
+      example: 'nlp.slot.prompt'
+    },
+    messageParams: {
+      type: 'object',
+      description:
+        'Parameters for message interpolation. Used with messageKey for dynamic values in translated messages.',
+      example: {
+        slot: 'amount',
+        name: 'Starbucks',
+        similarity: 85
+      }
+    },
+    sessionId: {
+      type: 'string',
+      description:
+        'Session ID for multi-turn dialogue. Must be included in subsequent requests to continue the conversation.',
+      example: 'session_abc123'
+    },
+    waitingFor: {
+      type: 'string',
+      description: 'Which slot is waiting for user input',
+      example: 'amount'
+    },
+    transaction: {
+      description: 'Created transaction info (for created action)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpTransactionInfoDto'
+        }
+      ]
+    },
+    parsedData: {
+      description:
+        'Parsed data for confirmation (when action is "confirm"). Contains extracted fields that user should verify before transaction creation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpParsedDataDto'
+        }
+      ]
+    },
+    duplicateData: {
+      description:
+        'Duplicate detection data (when action is "confirm_duplicate"). Contains information about potential duplicate transaction for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpDuplicateConfirmationDataDto'
+        }
+      ]
+    },
+    ruleData: {
+      description:
+        'Rule match data (when action is "confirm_rule"). Contains information about medium-confidence rule match for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpRuleConfirmationDataDto'
+        }
+      ]
+    },
+    accountData: {
+      description:
+        'Account validation data (when action is "confirm_account"). Contains information about invalid account for user correction.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpAccountConfirmationDataDto'
+        }
+      ]
+    },
+    payeeData: {
+      description:
+        'Payee confirmation data (when action is "confirm_payee"). Contains information about medium/low confidence payee match for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpPayeeConfirmationDataDto'
+        }
+      ]
+    },
+    confidence: {
+      type: 'number',
+      description: 'Overall confidence score (0-1)',
+      example: 0.85
+    },
+    confidenceThreshold: {
+      type: 'number',
+      description:
+        'Confidence threshold for automatic creation (default: 0.75). When confidence < threshold, action will be "confirm" requiring user verification.',
+      example: 0.75
+    },
+    recurringMatch: {
+      description:
+        'Recurring transaction match info (when action is "created"). Contains match details when transaction matches a pending expected transaction.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/RecurringMatchInfoDto'
+        }
+      ]
+    },
+    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/UpdateMapperDefaultsDto'
+          $ref: '#/components/schemas/RecurringSuggestionDto'
         }
       ]
-    }
-  }
-} as const;
-
-export const $UpdateImporterConfigDto = {
-  type: 'object',
-  properties: {
-    data: {
-      description: 'Configuration data (v1 schema)',
+    },
+    suggestedAccounts: {
+      description:
+        'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
       allOf: [
         {
-          $ref: '#/components/schemas/UpdateConfigDataDto'
+          $ref: '#/components/schemas/NlpSuggestedAccountsDto'
+        }
+      ]
+    },
+    defaultAccounts: {
+      description:
+        'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpDefaultAccountsDto'
         }
       ]
     }
-  }
+  },
+  required: ['status', 'action']
 } as const;
 
-export const $CreatePlatformDto = {
+export const $PlatformListItemDto = {
   type: 'object',
   properties: {
-    name: {
+    id: {
       type: 'string',
-      description: 'Platform name',
-      example: 'Binance'
+      description: 'Global platform ID'
     },
-    canonical: {
+    name: {
       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: 'Platform name'
     },
     url: {
       type: 'string',
-      description: 'Platform URL',
-      example: 'https://www.binance.com'
+      description: 'Platform URL'
     },
     type: {
       type: 'string',
@@ -4764,48 +6450,53 @@ export const $CreatePlatformDto = {
         'INVESTMENT',
         'INSURANCE',
         'OTHER'
-      ],
-      example: 'CRYPTO_EXCHANGE'
+      ]
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
+    },
+    suggestedSegment: {
+      type: 'string',
+      description:
+        'Suggested path segment — canonical with first char uppercased (ACC_COMP_NAME_RE)'
     },
     logoUrl: {
       type: 'string',
-      description: 'Platform logo URL',
-      example: 'https://example.com/logos/binance.png'
+      description: 'Logo URL',
+      nullable: true
     },
-    isActive: {
+    isBound: {
       type: 'boolean',
-      description: 'Whether the platform is active',
-      default: true
+      description: 'Whether user has accounts using this platform'
     }
   },
-  required: ['name', 'canonical', 'aliases', 'url', 'type']
+  required: [
+    'id',
+    'name',
+    'url',
+    'type',
+    'canonical',
+    'suggestedSegment',
+    'logoUrl',
+    'isBound'
+  ]
 } as const;
 
-export const $UpdatePlatformDto = {
+export const $PlatformMatchResultDto = {
   type: 'object',
   properties: {
-    name: {
+    id: {
       type: 'string',
-      description: 'Platform name',
-      example: 'Binance'
+      description: 'Global platform ID'
     },
-    canonical: {
+    name: {
       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: 'Platform name (e.g., "ICBC")'
     },
-    url: {
+    canonical: {
       type: 'string',
-      description: 'Platform URL',
-      example: 'https://www.binance.com'
+      description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
     },
     type: {
       type: 'string',
@@ -4818,178 +6509,167 @@ export const $UpdatePlatformDto = {
         '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'
-    }
-  }
-} as const;
-
-export const $ProviderSyncConfigDto = {
-  type: 'object',
-  properties: {
-    sourceAccount: {
-      type: 'string',
-      description: 'Source account for the first posting',
-      example: 'Assets:Bank:Chase'
+      ]
     },
-    defaultCurrency: {
+    suggestedSegment: {
       type: 'string',
-      description: 'Default currency for transactions',
-      example: 'USD'
+      description:
+        'Suggested path segment — canonical, already in ACCOUNT_RE format'
     },
-    defaultExpenseAccount: {
+    logoUrl: {
       type: 'string',
-      description: 'Default expense account for the second posting',
-      example: 'Expenses:Unknown'
+      description: 'Logo URL',
+      nullable: true
     },
-    defaultIncomeAccount: {
+    matchType: {
       type: 'string',
-      description: 'Default income account for the second posting',
-      example: 'Income:Unknown'
-    },
-    filterPending: {
-      type: 'boolean',
-      description: 'Filter pending transactions',
-      default: true
+      description: "How this row matched: 'exact' > 'prefix' > 'substring'",
+      enum: ['exact', 'prefix', 'substring']
     }
   },
   required: [
-    'sourceAccount',
-    'defaultCurrency',
-    'defaultExpenseAccount',
-    'defaultIncomeAccount'
+    'id',
+    'name',
+    'canonical',
+    'type',
+    'suggestedSegment',
+    'logoUrl',
+    'matchType'
   ]
 } as const;
 
-export const $ProviderSyncDto = {
+export const $PlatformMatchResponseDto = {
   type: 'object',
   properties: {
-    provider: {
-      type: 'string',
-      description:
-        'Provider name (already in URL path, optional here for reference)',
-      example: 'plaid'
+    platforms: {
+      description: 'Ranked matches, best tier first (at most 10 rows)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PlatformMatchResultDto'
+      }
     },
-    syncId: {
+    matchType: {
       type: 'string',
-      description: 'Unique sync identifier for idempotency',
-      example: 'sync-12345'
+      description:
+        "Overall match quality — top row's tier, or 'none' when no hits",
+      enum: ['none', 'exact', 'prefix', 'substring']
     },
-    config: {
-      description: 'Provider sync configuration',
-      allOf: [
-        {
-          $ref: '#/components/schemas/ProviderSyncConfigDto'
-        }
-      ]
+    total: {
+      type: 'number',
+      description: 'Total matches before LIMIT (truncation transparency)'
     },
-    transactions: {
-      type: 'array',
-      description: 'Raw transactions from provider',
-      example: [
-        {
-          transaction_id: 'txn-001',
-          amount: 50,
-          iso_currency_code: 'USD',
-          date: '2024-01-15',
-          merchant_name: 'Starbucks',
-          name: 'STARBUCKS STORE 12345',
-          pending: false,
-          account_id: 'acc-001'
-        }
-      ]
+    hasMore: {
+      type: 'boolean',
+      description: 'true when total > platforms.length (more matches exist)'
     }
   },
-  required: ['config', 'transactions']
+  required: ['platforms', 'matchType', 'total', 'hasMore']
 } as const;
 
-export const $SupportedProvidersResponseDto = {
+export const $CreatePlatformDto = {
   type: 'object',
   properties: {
-    providers: {
-      description: 'List of supported provider names',
-      example: [
-        'plaid',
-        'teller',
-        'truelayer',
-        'gocardless',
-        'simplefin',
-        'yodlee',
-        'beancount-direct',
-        'parsed-bill'
-      ],
+    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'
       }
-    }
-  },
-  required: ['providers']
-} as const;
-
-export const $ParserTelemetryReportDto = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $UncoveredFormatMissDto = {
-  type: 'object',
-  properties: {}
-} as const;
-
-export const $ProcessNlpDto = {
-  type: 'object',
-  properties: {
-    message: {
+    },
+    url: {
       type: 'string',
-      description: 'Natural language text describing a transaction (Chinese)',
-      example: 'yesterday Starbucks spent 35 yuan',
-      maxLength: 500
+      description: 'Platform URL',
+      example: 'https://www.binance.com'
     },
-    sessionId: {
+    type: {
       type: 'string',
-      description:
-        'Session ID for multi-turn conversation (auto-generated if not provided)',
-      example: 'session_abc123'
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ],
+      example: 'CRYPTO_EXCHANGE'
     },
-    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'
-      }
+    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: ['message']
+  required: ['name', 'canonical', 'aliases', 'url', 'type']
 } as const;
 
-export const $BalanceByCurrencyDto = {
+export const $UpdatePlatformDto = {
   type: 'object',
   properties: {
-    currency: {
+    name: {
       type: 'string',
-      description: 'ISO 4217 currency code',
-      example: 'CNY'
+      description: 'Platform name',
+      example: 'Binance'
     },
-    balance: {
+    canonical: {
       type: 'string',
-      description: 'Balance amount',
-      example: '50000.00'
+      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'
     }
-  },
-  required: ['currency', 'balance']
+  }
 } as const;
 
 export const $NetWorthByCurrencyDto = {
@@ -5061,28 +6741,6 @@ export const $ConvertedNetWorthDto = {
   ]
 } 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 $NetWorthResponseDto = {
   type: 'object',
   properties: {
@@ -5168,7 +6826,7 @@ export const $AccountItemDto = {
     name: {
       type: 'string',
       description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
+      example: 'Assets:CN:CMB:Savings'
     },
     displayName: {
       type: 'string',
@@ -5184,6 +6842,12 @@ export const $AccountItemDto = {
       type: 'string',
       description: 'Currency code',
       example: 'CNY'
+    },
+    convertedBalance: {
+      type: 'string',
+      description:
+        'FX-converted balance in base currency; omitted when not convertible',
+      example: '50000.00'
     }
   },
   required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -5210,11 +6874,66 @@ export const $PlatformGroupDto = {
     },
     totalBalance: {
       type: 'string',
-      description: 'Total balance across all accounts in platform',
+      description: 'FX-converted total balance in base currency',
+      example: '100000.00'
+    },
+    balanceByCurrency: {
+      description: 'Raw (unconverted) balances grouped by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    convertedBalance: {
+      type: 'string',
+      description:
+        'Converted balance in base currency (omitted when no currency is convertible)',
       example: '100000.00'
+    },
+    sharePct: {
+      type: 'number',
+      description:
+        'Share of the grand converted total (0-100); 0 when grand total is 0',
+      example: 42.5
+    }
+  },
+  required: [
+    'platformId',
+    'platformName',
+    'accounts',
+    'totalBalance',
+    'balanceByCurrency',
+    'sharePct'
+  ]
+} as const;
+
+export const $AccountExchangeRateWarningDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_EXCHANGE_RATE'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency without exchange rate',
+      example: 'USD'
+    },
+    accounts: {
+      description: 'Affected account paths',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    totalAmount: {
+      type: 'string',
+      description: 'Total amount in this currency',
+      example: '5000.00'
     }
   },
-  required: ['platformId', 'platformName', 'accounts', 'totalBalance']
+  required: ['type', 'currency', 'accounts', 'totalAmount']
 } as const;
 
 export const $AccountsSummaryDto = {
@@ -5227,9 +6946,21 @@ export const $AccountsSummaryDto = {
     totalPlatforms: {
       type: 'number',
       description: 'Total number of platforms'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Per-account exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountExchangeRateWarningDto'
+      }
     }
   },
-  required: ['totalAccounts', 'totalPlatforms']
+  required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
 } as const;
 
 export const $AccountsResponseDto = {
@@ -5264,7 +6995,7 @@ export const $AccountItemWithAssetClassDto = {
     name: {
       type: 'string',
       description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
+      example: 'Assets:CN:CMB:Savings'
     },
     displayName: {
       type: 'string',
@@ -5281,6 +7012,12 @@ export const $AccountItemWithAssetClassDto = {
       description: 'Currency code',
       example: 'CNY'
     },
+    convertedBalance: {
+      type: 'string',
+      description:
+        'FX-converted balance in base currency; omitted when not convertible',
+      example: '50000.00'
+    },
     assetClass: {
       type: 'string',
       description: 'Asset class',
@@ -5360,35 +7097,6 @@ export const $AssetClassGroupDto = {
   required: ['assetClass', 'accounts', 'balanceByCurrency']
 } as const;
 
-export const $AccountExchangeRateWarningDto = {
-  type: 'object',
-  properties: {
-    type: {
-      type: 'string',
-      description: 'Warning type',
-      example: 'MISSING_EXCHANGE_RATE'
-    },
-    currency: {
-      type: 'string',
-      description: 'Currency without exchange rate',
-      example: 'USD'
-    },
-    accounts: {
-      description: 'Affected account paths',
-      type: 'array',
-      items: {
-        type: 'string'
-      }
-    },
-    totalAmount: {
-      type: 'string',
-      description: 'Total amount in this currency',
-      example: '5000.00'
-    }
-  },
-  required: ['type', 'currency', 'accounts', 'totalAmount']
-} as const;
-
 export const $AssetClassSummaryDto = {
   type: 'object',
   properties: {
@@ -5462,7 +7170,7 @@ export const $HoldingAssetClassAccountSliceDto = {
     accountPath: {
       type: 'string',
       description: 'Full account path',
-      example: 'Assets:US:Investments:Brokerage'
+      example: 'Assets:US:Fidelity:Brokerage'
     },
     accountCurrency: {
       type: 'string',
@@ -5646,26 +7354,121 @@ export const $CashFlowResponseDto = {
       description: 'Converted values in base currency',
       allOf: [
         {
-          $ref: '#/components/schemas/ConvertedCashFlowDto'
+          $ref: '#/components/schemas/ConvertedCashFlowDto'
+        }
+      ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: [
+    'period',
+    'income',
+    'expense',
+    'netSavings',
+    'savingsRate',
+    'currency'
+  ]
+} as const;
+
+export const $CategoryGroupDto = {
+  type: 'object',
+  properties: {
+    category: {
+      type: 'string',
+      description:
+        'Functional category (account-path Group segment); regional and universal account paths merge under it',
+      example: 'Food'
+    },
+    totalExpense: {
+      type: 'string',
+      description:
+        'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
+      example: '1200.00'
+    },
+    sharePct: {
+      type: 'number',
+      description: 'Share of grand total (0-100); 0 when grand total is 0',
+      example: 42.5
+    },
+    balanceByCurrency: {
+      description: 'Raw (unconverted) expense per currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    convertedBalance: {
+      type: 'string',
+      description:
+        'Converted total in base currency (omitted when FX missing for all currencies in this category)',
+      example: '1200.00'
+    }
+  },
+  required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
+} as const;
+
+export const $ExpensesByCategorySummaryDto = {
+  type: 'object',
+  properties: {
+    totalExpense: {
+      type: 'string',
+      description:
+        'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
+      example: '5000.00'
+    },
+    categoryCount: {
+      type: 'number',
+      description: 'Number of categories',
+      example: 8
+    }
+  },
+  required: ['totalExpense', 'categoryCount']
+} as const;
+
+export const $ExpensesByCategoryResponseDto = {
+  type: 'object',
+  properties: {
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '1m'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    groups: {
+      description:
+        'Expense groups by functional category, sorted by converted total desc',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CategoryGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
         }
       ]
     },
     warnings: {
-      description: 'Exchange rate warnings',
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
       type: 'array',
       items: {
         $ref: '#/components/schemas/ExchangeRateWarningDto'
       }
     }
   },
-  required: [
-    'period',
-    'income',
-    'expense',
-    'netSavings',
-    'savingsRate',
-    'currency'
-  ]
+  required: ['period', 'baseCurrency', 'groups', 'summary']
 } as const;
 
 export const $MonetaryDto = {
@@ -5957,163 +7760,6 @@ export const $HoldingPnlResponseDto = {
   required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
 } 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',
-    'amount',
-    'date',
-    'meta',
-    'createdAt',
-    'updatedAt'
-  ]
-} as const;
-
-export const $PriceListResponseDto = {
-  type: 'object',
-  properties: {
-    items: {
-      description: 'List of prices',
-      type: 'array',
-      items: {
-        $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 $CurrencyBalanceDto = {
   type: 'object',
   properties: {
@@ -6149,6 +7795,16 @@ export const $TimeSeriesPointDto = {
       description: 'Change from previous point',
       example: '5000.00'
     },
+    assets: {
+      type: 'string',
+      description: 'Total assets at this date (in base currency)',
+      example: '494338.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Total liabilities at this date (in base currency)',
+      example: '310098.00'
+    },
     byCurrency: {
       description: 'Multi-currency breakdown for this point',
       type: 'array',
@@ -6258,6 +7914,111 @@ export const $PortfolioTrendsResponseDto = {
   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: {}
@@ -6288,3 +8049,15 @@ export const $AnonymousLoginDto = {
   },
   required: ['accessToken']
 } as const;
+
+export const $AnonymousLoginResponseDto = {
+  type: 'object',
+  properties: {
+    authToken: {
+      type: 'string',
+      description: 'JWT auth token',
+      example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+    }
+  },
+  required: ['authToken']
+} as const;