@firela/api-types 0.0.0-canary.209966 → 0.0.0-canary.285599dd

package/src/generated/schemas.gen.ts

@@ -8,6 +8,12 @@ export const $CreateAccountDto = {
       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: '工资卡'
+    },
     openDate: {
       format: 'date-time',
       type: 'string',
@@ -86,6 +92,12 @@ export const $AccountResponseDto = {
       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: '工资卡'
+    },
     type: {
       type: 'string',
       description: 'Account type (root segment)',
@@ -180,6 +192,7 @@ export const $AccountResponseDto = {
   required: [
     'id',
     'path',
+    'displayName',
     'type',
     'status',
     'openDate',
@@ -212,6 +225,11 @@ 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,7 +269,7 @@ export const $UpdateAccountDto = {
       }
     },
     platformId: {
-      type: 'object',
+      type: 'string',
       description:
         'Platform ID (references Platform.id), null to clear association',
       example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2',
@@ -292,6 +310,222 @@ export const $ReopenAccountDto = {
   }
 } as const;
 
+export const $AccountStandardResponseDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Account path (hierarchical, colon-separated)',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    type: {
+      type: 'string',
+      description: 'Account type in Beancount hierarchy',
+      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',
+      example: 'Housing Fund'
+    },
+    description: {
+      type: 'string',
+      description: 'Account description (stable semantics only)',
+      example: 'ICBC checking account for daily transactions'
+    },
+    tags: {
+      description: 'Account tags for categorization',
+      example: ['bank', 'checking', 'primary'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon identifier for UI display',
+      example: 'bank-icbc'
+    }
+  },
+  required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
+} as const;
+
+export const $AccountStandardListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'Array of account templates',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountStandardResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of account templates',
+      example: 150
+    },
+    region: {
+      type: 'string',
+      description: 'Region code',
+      example: 'CN'
+    }
+  },
+  required: ['items', 'total', 'region']
+} as const;
+
+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']
+} as const;
+
+export const $TemplateMetadataResponseDto = {
+  type: 'object',
+  properties: {
+    metadata: {
+      $ref: '#/components/schemas/TemplateMetadataDto'
+    }
+  }
+} as const;
+
+export const $RegionConfigDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      example: 'EUR'
+    },
+    dateFormat: {
+      type: 'string',
+      example: 'DD.MM.YYYY'
+    },
+    locale: {
+      type: 'string',
+      example: 'de-DE'
+    }
+  },
+  required: ['currency', 'dateFormat', 'locale']
+} as const;
+
+export const $RegionInfoDto = {
+  type: 'object',
+  properties: {
+    code: {
+      type: 'string',
+      example: 'de'
+    },
+    displayName: {
+      type: 'string',
+      example: 'Germany'
+    },
+    parent: {
+      type: 'string'
+    },
+    chain: {
+      example: ['de'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    config: {
+      $ref: '#/components/schemas/RegionConfigDto'
+    }
+  },
+  required: ['code', 'displayName', 'chain', 'config']
+} as const;
+
+export const $RegionsMetadataResponseDto = {
+  type: 'object',
+  properties: {
+    regions: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/RegionInfoDto'
+      }
+    }
+  },
+  required: ['regions']
+} as const;
+
+export const $CostSpecDto = {
+  type: 'object',
+  properties: {
+    mode: {
+      type: 'string',
+      enum: ['per-unit', 'total', 'date', 'label', 'auto'],
+      description: 'Cost specification mode (mirrors engine CostSpec)'
+    },
+    numberPerUnit: {
+      type: 'string',
+      description: 'Per-unit cost (required when mode is "per-unit")',
+      example: '240'
+    },
+    totalNumber: {
+      type: 'string',
+      description: 'Total cost for all units (required when mode is "total")',
+      example: '12000'
+    },
+    currency: {
+      type: 'string',
+      description: 'Cost currency (required in all modes)',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description:
+        'Lot acquisition date, ISO 8601 (required when mode is "date")',
+      example: '2024-01-15'
+    },
+    label: {
+      type: 'string',
+      description:
+        'Lot label (required when mode is "label"; optional tag in buy modes)'
+    },
+    merge: {
+      type: 'boolean',
+      description: 'Merge lots for AVERAGE booking (mode: auto)'
+    }
+  },
+  required: ['mode', 'currency']
+} as const;
+
+export const $AmountDto = {
+  type: 'object',
+  properties: {
+    number: {
+      type: 'string',
+      description:
+        'Amount as decimal string (max 15 integer + 15 decimal digits)',
+      example: '170.50'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency/commodity code',
+      example: 'USD'
+    }
+  },
+  required: ['number', 'currency']
+} as const;
+
 export const $CreatePostingDto = {
   type: 'object',
   properties: {
@@ -321,6 +555,33 @@ export const $CreatePostingDto = {
       example: {
         'tax-lot': 'Q1-2024'
       }
+    },
+    cost: {
+      description:
+        'Cost basis (Beancount `{...}`). Maps to engine costSpec. Required for commodity holdings so they carry a monetary weight that can balance.',
+      example: {
+        mode: 'per-unit',
+        numberPerUnit: '240',
+        currency: 'USD'
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostSpecDto'
+        }
+      ]
+    },
+    price: {
+      description:
+        'Price annotation (Beancount `@...`). Maps to engine price. Used for valuation; cost takes priority for balance weight.',
+      example: {
+        number: '170',
+        currency: 'USD'
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/AmountDto'
+        }
+      ]
     }
   },
   required: ['account']
@@ -399,6 +660,32 @@ export const $CreateTransactionDto = {
   required: ['date', 'narration', 'postings']
 } as const;
 
+export const $CostDetailDto = {
+  type: 'object',
+  properties: {
+    number: {
+      type: 'string',
+      description: 'Per-unit cost basis (mirrors engine Cost.number)',
+      example: '240'
+    },
+    currency: {
+      type: 'string',
+      description: 'Cost currency',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description: 'Lot acquisition date (ISO yyyy-mm-dd)',
+      example: '2024-01-15'
+    },
+    label: {
+      type: 'string',
+      description: 'Lot label',
+      example: 'lot-2024-01'
+    }
+  }
+} as const;
+
 export const $PostingResponseDto = {
   type: 'object',
   properties: {
@@ -409,13 +696,23 @@ export const $PostingResponseDto = {
     },
     units: {
       type: 'string',
-      description: 'Amount (may be null if interpolated)',
+      description:
+        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
       example: '100.50'
     },
     currency: {
       type: 'string',
       description: 'Currency',
       example: 'USD'
+    },
+    cost: {
+      description:
+        'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostDetailDto'
+        }
+      ]
     }
   },
   required: ['account']
@@ -607,28 +904,167 @@ export const $ApiProblemResponseDto = {
   required: ['type', 'title', 'status', 'detail']
 } as const;
 
-export const $PostingDetailDto = {
+export const $BatchCreateTransactionDto = {
   type: 'object',
   properties: {
-    id: {
-      type: 'string',
-      description: 'Posting ID',
-      example: 'clh1234567890abcdef'
-    },
-    accountId: {
-      type: 'string',
-      description: 'Account ID',
-      example: 'clh1234567890abcdef'
+    transactions: {
+      description: 'Array of transactions to create',
+      minItems: 1,
+      maxItems: 100,
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CreateTransactionDto'
+      }
+    }
+  },
+  required: ['transactions']
+} as const;
+
+export const $BatchTransactionErrorDto = {
+  type: 'object',
+  properties: {
+    index: {
+      type: 'number',
+      description: 'Index of failed transaction in the input array',
+      example: 0
     },
-    accountName: {
+    error: {
       type: 'string',
-      description: 'Account name',
-      example: 'Assets:Bank:Checking'
+      description: 'Error message describing the failure',
+      example: 'Transaction does not balance'
     },
-    units: {
+    errorCode: {
       type: 'string',
-      description: 'Amount (may be null if interpolated)',
-      example: '100.50'
+      description: 'Structured error code for programmatic handling',
+      example: 'INSUFFICIENT_QUANTITY'
+    }
+  },
+  required: ['index', 'error']
+} as const;
+
+export const $BatchTransactionResponseDto = {
+  type: 'object',
+  properties: {
+    succeeded: {
+      description: 'Successfully created transactions',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TransactionResponseDto'
+      }
+    },
+    failed: {
+      description: 'Failed transactions with error details',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BatchTransactionErrorDto'
+      }
+    }
+  },
+  required: ['succeeded', 'failed']
+} as const;
+
+export const $CorrectTransactionDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO 8601 format)',
+      example: '2024-11-28'
+    },
+    flag: {
+      type: 'string',
+      description: 'Transaction flag: * (cleared), ! (pending)',
+      enum: ['*', '!'],
+      example: '*'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration/description',
+      example: 'Grocery shopping'
+    },
+    tags: {
+      description: 'Transaction tags (without # prefix)',
+      example: ['vacation', 'personal'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    links: {
+      description: 'Transaction links (without ^ prefix)',
+      example: ['invoice-123'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    postings: {
+      description:
+        'Transaction postings (minimum 1, typically 2 for double-entry)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CreatePostingDto'
+      }
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction-level metadata',
+      example: {
+        invoice: '12345'
+      }
+    },
+    idempotencyKey: {
+      type: 'string',
+      description:
+        'Unique key for idempotent transaction creation. If provided, duplicate requests with the same key will return the existing transaction.',
+      example: 'import-2024-01-15-batch-001',
+      maxLength: 128
+    },
+    autoCreateAccounts: {
+      type: 'boolean',
+      description:
+        'Auto-create accounts if not found. When true, missing accounts will be automatically created. When false (default for API), missing accounts will cause a validation error. Set to true for quick entry scenarios where you want to create accounts on-the-fly.',
+      default: true,
+      example: true
+    },
+    correctionReason: {
+      type: 'string',
+      description: 'Reason for correcting/superseding the original transaction',
+      example: 'Wrong amount — corrected from receipt',
+      maxLength: 500
+    }
+  },
+  required: ['date', 'narration', 'postings']
+} as const;
+
+export const $PostingDetailDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Posting ID',
+      example: 'clh1234567890abcdef'
+    },
+    accountId: {
+      type: 'string',
+      description: 'Account ID',
+      example: 'clh1234567890abcdef'
+    },
+    account: {
+      type: 'string',
+      description: 'Fully-qualified Beancount account path',
+      example: 'Assets:Bank:Checking'
+    },
+    units: {
+      type: 'string',
+      description:
+        'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
+      example: '100.50'
     },
     currency: {
       type: 'string',
@@ -650,6 +1086,15 @@ export const $PostingDetailDto = {
       description: 'Cost date',
       example: '2024-01-15'
     },
+    cost: {
+      description:
+        'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostDetailDto'
+        }
+      ]
+    },
     priceAmount: {
       type: 'string',
       description: 'Price amount',
@@ -670,7 +1115,7 @@ export const $PostingDetailDto = {
       description: 'Posting metadata'
     }
   },
-  required: ['id', 'accountId', 'accountName']
+  required: ['id', 'accountId', 'account']
 } as const;
 
 export const $TransactionDetailDto = {
@@ -742,8 +1187,8 @@ export const $TransactionDetailDto = {
     },
     sourceType: {
       type: 'string',
-      description: 'Source type (how the transaction was created)',
-      enum: ['NLP', 'CSV', 'OCR', 'API']
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
     },
     sourcePlatform: {
       type: 'string',
@@ -776,6 +1221,18 @@ export const $TransactionDetailDto = {
       type: 'string',
       description: 'Correction reason (if voided or superseded)',
       example: 'Duplicate entry'
+    },
+    supersededBy: {
+      type: 'string',
+      description:
+        'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
+      example: 'clh1234567890abcdef'
+    },
+    originalTxn: {
+      type: 'string',
+      description:
+        'ID of the transaction this one corrected/replaced (back-link on the replacement)',
+      example: 'clh1234567890abcdef'
     }
   },
   required: [
@@ -819,6 +1276,37 @@ export const $TransactionListResponseDto = {
   required: ['data', 'total', 'limit', 'offset']
 } as const;
 
+export const $TagSuggestionDto = {
+  type: 'object',
+  properties: {
+    tag: {
+      type: 'string',
+      description: 'Tag name',
+      example: 'Monthly'
+    },
+    count: {
+      type: 'number',
+      description: 'Usage count across ACTIVE transactions',
+      example: 12
+    }
+  },
+  required: ['tag', 'count']
+} as const;
+
+export const $TagSuggestionsResponseDto = {
+  type: 'object',
+  properties: {
+    data: {
+      description: 'Tag suggestions sorted as requested',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TagSuggestionDto'
+      }
+    }
+  },
+  required: ['data']
+} as const;
+
 export const $UpdateTransactionDto = {
   type: 'object',
   properties: {
@@ -876,71 +1364,6 @@ export const $UpdateTransactionDto = {
   }
 } as const;
 
-export const $AccountStandardResponseDto = {
-  type: 'object',
-  properties: {
-    path: {
-      type: 'string',
-      description: 'Account path (hierarchical, colon-separated)',
-      example: 'Assets:CN:Bank:ICBC:Checking'
-    },
-    type: {
-      type: 'string',
-      description: 'Account type in Beancount hierarchy',
-      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'
-    },
-    description: {
-      type: 'string',
-      description: 'Account description',
-      example: 'ICBC checking account for daily transactions'
-    },
-    tags: {
-      description: 'Account tags for categorization',
-      example: ['bank', 'checking', 'primary'],
-      type: 'array',
-      items: {
-        type: 'string'
-      }
-    },
-    icon: {
-      type: 'string',
-      description: 'Icon identifier for UI display',
-      example: 'bank-icbc'
-    }
-  },
-  required: ['path', 'type']
-} as const;
-
-export const $AccountStandardListResponseDto = {
-  type: 'object',
-  properties: {
-    items: {
-      description: 'Array of account templates',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/AccountStandardResponseDto'
-      }
-    },
-    total: {
-      type: 'number',
-      description: 'Total number of account templates',
-      example: 150
-    },
-    region: {
-      type: 'string',
-      description: 'Region code',
-      example: 'CN'
-    }
-  },
-  required: ['items', 'total', 'region']
-} as const;
-
 export const $BalanceResponseDto = {
   type: 'object',
   properties: {
@@ -1034,8 +1457,8 @@ export const $TransactionSummaryDto = {
     },
     sourceType: {
       type: 'string',
-      description: 'Source type (NLP, CSV, OCR, API)',
-      enum: ['NLP', 'CSV', 'OCR', 'API']
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
     },
     sourcePlatform: {
       type: 'string',
@@ -1075,12 +1498,23 @@ export const $ReviewSummaryDto = {
     },
     confidenceLevel: {
       type: 'string',
-      description: 'Confidence level derived from score',
-      enum: ['HIGH', 'MEDIUM', 'LOW']
+      description:
+        'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
+      enum: ['HIGH', 'MEDIUM', 'LOW'],
+      nullable: true
     },
-    summary: {
+    summaryKey: {
       type: 'string',
-      description: 'Human-readable summary of the review item'
+      description:
+        'i18n message key for summary (e.g., review.summary.duplicate). Translate on frontend with summaryParams.'
+    },
+    summaryParams: {
+      type: 'object',
+      description:
+        'Parameters for summary message interpolation (e.g., { date: "2024-01-15", amount: "50" })',
+      additionalProperties: {
+        type: 'string'
+      }
     },
     matchReasons: {
       description: 'Human-readable reasons for branching',
@@ -1091,7 +1525,8 @@ export const $ReviewSummaryDto = {
     },
     sourceType: {
       type: 'string',
-      description: 'Source type (NLP, CSV, OCR, API)'
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
     },
     sourcePlatform: {
       type: 'string',
@@ -1140,7 +1575,7 @@ export const $ReviewSummaryDto = {
     'status',
     'confidence',
     'confidenceLevel',
-    'summary',
+    'summaryKey',
     'matchReasons',
     'sourceType',
     'createdAt'
@@ -1201,7 +1636,20 @@ export const $DecisionOptionDto = {
   properties: {
     value: {
       type: 'string',
-      description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)'
+      description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)',
+      enum: [
+        'UPGRADE_REPLACE',
+        'LINK_KEEP_BOTH',
+        'IGNORE_NEW',
+        'CONFIRM_DIFFERENT',
+        'ACCEPT',
+        'REJECT',
+        'ACCEPT_AND_LEARN',
+        'CHOOSE_OTHER',
+        'CANCEL',
+        'FIX',
+        'IGNORE'
+      ]
     },
     labelKey: {
       type: 'string',
@@ -1249,12 +1697,23 @@ export const $ReviewDetailDto = {
     },
     confidenceLevel: {
       type: 'string',
-      description: 'Confidence level derived from score',
-      enum: ['HIGH', 'MEDIUM', 'LOW']
+      description:
+        'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
+      enum: ['HIGH', 'MEDIUM', 'LOW'],
+      nullable: true
     },
-    summary: {
+    summaryKey: {
       type: 'string',
-      description: 'Human-readable summary of the review item'
+      description:
+        'i18n message key for summary (e.g., review.summary.duplicate). Translate on frontend with summaryParams.'
+    },
+    summaryParams: {
+      type: 'object',
+      description:
+        'Parameters for summary message interpolation (e.g., { date: "2024-01-15", amount: "50" })',
+      additionalProperties: {
+        type: 'string'
+      }
     },
     matchReasons: {
       description: 'Human-readable reasons for branching',
@@ -1265,7 +1724,8 @@ export const $ReviewDetailDto = {
     },
     sourceType: {
       type: 'string',
-      description: 'Source type (NLP, CSV, OCR, API)'
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
     },
     sourcePlatform: {
       type: 'string',
@@ -1330,7 +1790,7 @@ export const $ReviewDetailDto = {
     'status',
     'confidence',
     'confidenceLevel',
-    'summary',
+    'summaryKey',
     'matchReasons',
     'sourceType',
     'createdAt',
@@ -1339,39 +1799,242 @@ export const $ReviewDetailDto = {
   ]
 } as const;
 
-export const $PayeeResponseDto = {
+export const $ResolveReviewDto = {
   type: 'object',
   properties: {
-    id: {
-      type: 'string',
-      description: 'Unique identifier (UUID)',
-      example: 'uuid-123-456'
-    },
-    userId: {
-      type: 'string',
-      description: 'User ID (owner of this payee mapping)',
-      example: 'user-123'
-    },
-    payee: {
+    action: {
       type: 'string',
-      description: "User's original payee name (e.g., 'Starbucks', 'McDonald')",
-      example: 'Starbucks'
-    },
-    payeeProfileId: {
-      type: 'object',
       description:
-        'Reference to global PayeeProfile (merchant info, i18n keys, categories)',
-      example: 'uuid-789',
-      nullable: true
+        'Decision action. Valid actions vary by review type — see DecisionOptionDto.value returned by the review detail endpoint.',
+      enum: [
+        'UPGRADE_REPLACE',
+        'LINK_KEEP_BOTH',
+        'IGNORE_NEW',
+        'CONFIRM_DIFFERENT',
+        'ACCEPT',
+        'REJECT',
+        'ACCEPT_AND_LEARN',
+        'CHOOSE_OTHER',
+        'CANCEL',
+        'FIX',
+        'IGNORE'
+      ],
+      example: 'ACCEPT'
     },
-    customCategory: {
+    data: {
       type: 'object',
       description:
-        "User's custom category (overrides PayeeProfile category if set)",
-      example: 'Dining:Coffee',
-      nullable: true
-    },
-    customTags: {
+        'Additional data for the decision (e.g., selected account ID)',
+      example: {
+        accountId: 'acc-123'
+      }
+    }
+  },
+  required: ['action']
+} as const;
+
+export const $ResolveResultDto = {
+  type: 'object',
+  properties: {
+    success: {
+      type: 'boolean',
+      description: 'Whether resolution was successful'
+    },
+    messageKey: {
+      type: 'string',
+      description:
+        'i18n message key for result message (e.g., review.payee.result.mapped)'
+    },
+    messageParams: {
+      type: 'object',
+      description:
+        'Parameters for message interpolation (e.g., { name: "PayeeName" })',
+      additionalProperties: {
+        type: 'string'
+      }
+    },
+    resolutionId: {
+      type: 'string',
+      description:
+        'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
+    },
+    canUndo: {
+      type: 'boolean',
+      description: 'Whether this decision can be undone'
+    },
+    undoDeadline: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Deadline for undo (24h from resolution)'
+    },
+    learnedRuleId: {
+      type: 'string',
+      description:
+        'Rule ID if learning was triggered (ACCEPT_AND_LEARN actions). Use this to deep-link to the rule management page.',
+      example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
+    }
+  },
+  required: ['success']
+} as const;
+
+export const $UndoResultDto = {
+  type: 'object',
+  properties: {
+    success: {
+      type: 'boolean',
+      description: 'Whether undo was successful'
+    },
+    message: {
+      type: 'string',
+      description: 'Message'
+    },
+    reviewId: {
+      type: 'string',
+      description: 'Review item ID that was restored'
+    }
+  },
+  required: ['success', 'reviewId']
+} as const;
+
+export const $BatchResolveDto = {
+  type: 'object',
+  properties: {
+    reviewIds: {
+      description: 'Review item IDs to resolve',
+      example: ['review-1', 'review-2', 'review-3'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    action: {
+      type: 'string',
+      description: 'Decision action to apply to all items',
+      enum: [
+        'UPGRADE_REPLACE',
+        'LINK_KEEP_BOTH',
+        'IGNORE_NEW',
+        'CONFIRM_DIFFERENT',
+        'ACCEPT',
+        'REJECT',
+        'ACCEPT_AND_LEARN',
+        'CHOOSE_OTHER',
+        'CANCEL',
+        'FIX',
+        'IGNORE'
+      ],
+      example: 'ACCEPT'
+    },
+    data: {
+      type: 'object',
+      description: 'Additional data for the decision'
+    }
+  },
+  required: ['reviewIds', 'action']
+} as const;
+
+export const $BatchResolveResultDto = {
+  type: 'object',
+  properties: {
+    successCount: {
+      type: 'number',
+      description: 'Number of successfully resolved items'
+    },
+    failedCount: {
+      type: 'number',
+      description: 'Number of failed items'
+    },
+    results: {
+      description: 'Details for each item',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['successCount', 'failedCount', 'results']
+} as const;
+
+export const $CreatePayeeDto = {
+  type: 'object',
+  properties: {
+    payee: {
+      type: 'string',
+      description:
+        "User's original payee name (e.g., 'Starbucks', 'McDonald'). This is the raw payee string as entered by the user.",
+      example: 'Starbucks',
+      maxLength: 200
+    },
+    payeeProfileId: {
+      type: 'string',
+      description:
+        'Optional reference to global PayeeProfile for standardized data (merchant info, i18n keys, categories)',
+      example: 'uuid-123',
+      format: 'uuid'
+    },
+    customCategory: {
+      type: 'string',
+      description:
+        "User's custom category for this payee (overrides PayeeProfile category)",
+      example: 'Dining:Coffee',
+      maxLength: 100
+    },
+    customTags: {
+      description:
+        "User's custom tags for this payee (e.g., ['favorite', 'work_meal'])",
+      example: ['favorite', 'work_meal'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Metadata for extended information (location, notes, contact info, etc.)',
+      example: {
+        location: 'Zhongguancun',
+        note: 'Near subway station',
+        favorite: true
+      }
+    }
+  },
+  required: ['payee']
+} as const;
+
+export const $PayeeResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier (UUID)',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of this payee mapping)',
+      example: 'user-123'
+    },
+    payee: {
+      type: 'string',
+      description: "User's original payee name (e.g., 'Starbucks', 'McDonald')",
+      example: 'Starbucks'
+    },
+    payeeProfileId: {
+      type: 'string',
+      description:
+        'Reference to global PayeeProfile (merchant info, i18n keys, categories)',
+      example: 'uuid-789',
+      nullable: true
+    },
+    customCategory: {
+      type: 'string',
+      description:
+        "User's custom category (overrides PayeeProfile category if set)",
+      example: 'Dining:Coffee',
+      nullable: true
+    },
+    customTags: {
       description: "User's custom tags (e.g., ['favorite', 'work_meal'])",
       example: ['favorite', 'work_meal'],
       type: 'array',
@@ -1489,21 +2152,64 @@ export const $PayeeStatsResponseDto = {
   required: ['payee', 'transactionCount', 'lastUsedAt']
 } as const;
 
-export const $PayeeProfileResponseDto = {
+export const $UpdatePayeeDto = {
   type: 'object',
   properties: {
-    id: {
+    payeeProfileId: {
       type: 'string',
-      description: 'Unique identifier (UUID)',
-      example: '550e8400-e29b-41d4-a716-446655440000'
+      description:
+        'Optional reference to global PayeeProfile for standardized data (merchant info, i18n keys, categories)',
+      example: 'uuid-123',
+      format: 'uuid'
+    },
+    customCategory: {
+      type: 'string',
+      description:
+        "User's custom category for this payee (overrides PayeeProfile category)",
+      example: 'Dining:Coffee',
+      maxLength: 100
     },
+    customTags: {
+      description:
+        "User's custom tags for this payee (e.g., ['favorite', 'work_meal'])",
+      example: ['favorite', 'work_meal'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Metadata for extended information (location, notes, contact info, etc.). Will merge with existing metadata.',
+      example: {
+        location: 'Zhongguancun',
+        note: 'Updated note',
+        favorite: true
+      }
+    },
+    isActive: {
+      type: 'boolean',
+      description:
+        'Enable or disable this payee. Disabled payees will not appear in autocomplete suggestions.',
+      example: true
+    }
+  }
+} as const;
+
+export const $CreatePayeeProfileDto = {
+  type: 'object',
+  properties: {
     canonical: {
       type: 'string',
-      description: 'Canonical payee name (unique, case-insensitive)',
-      example: 'Starbucks'
+      description:
+        'Canonical payee name (unique, case-insensitive). This is the primary identifier for the payee.',
+      example: 'Starbucks',
+      maxLength: 200
     },
     aliases: {
-      description: 'Multi-language aliases',
+      description:
+        'Multi-language aliases for the payee. Used for matching user input in different languages.',
       example: ['Starbucks Coffee', 'SBUX'],
       type: 'array',
       items: {
@@ -1511,14 +2217,15 @@ export const $PayeeProfileResponseDto = {
       }
     },
     i18nKey: {
-      type: 'object',
-      description: 'Translation key for i18n',
+      type: 'string',
+      description:
+        'Translation key for i18n integration (XLIFF translation system)',
       example: 'payee.starbucks',
-      nullable: true
+      maxLength: 100
     },
     category: {
       type: 'string',
-      description: 'Payee category',
+      description: 'Payee category classification',
       enum: [
         'RESTAURANT',
         'CAFE',
@@ -1547,13 +2254,14 @@ export const $PayeeProfileResponseDto = {
       example: 'CAFE'
     },
     subCategory: {
-      type: 'object',
-      description: 'Sub-category',
+      type: 'string',
+      description: 'Sub-category for more specific classification',
       example: 'coffee_chain',
-      nullable: true
+      maxLength: 100
     },
     countries: {
-      description: 'Country codes where payee operates',
+      description:
+        'Country/region codes where the payee operates (ISO 3166-1 alpha-2)',
       example: ['CN', 'US', 'JP'],
       type: 'array',
       items: {
@@ -1561,297 +2269,582 @@ export const $PayeeProfileResponseDto = {
       }
     },
     primaryCountry: {
-      type: 'object',
-      description: 'Primary operating country',
+      type: 'string',
+      description: 'Primary operating country (ISO 3166-1 alpha-2)',
       example: 'US',
-      nullable: true
+      maxLength: 2
     },
     keywords: {
-      description: 'Search keywords',
-      example: ['coffee', 'cafe'],
+      description: 'Search keywords for fuzzy matching',
+      example: ['coffee', 'cafe', 'drinks'],
       type: 'array',
       items: {
         type: 'string'
       }
     },
     logoUrl: {
-      type: 'object',
-      description: 'Logo URL',
-      example: 'https://example.com/logo.png',
-      nullable: true
+      type: 'string',
+      description: 'Payee logo URL',
+      example: 'https://example.com/logo.png'
     },
     website: {
-      type: 'object',
-      description: 'Official website',
-      example: 'https://www.starbucks.com',
-      nullable: true
+      type: 'string',
+      description: 'Official website URL',
+      example: 'https://www.starbucks.com'
     },
     description: {
-      type: 'object',
-      description: 'Description',
-      example: 'Global coffeehouse chain',
-      nullable: true
+      type: 'string',
+      description: 'Payee description',
+      example: 'Global coffeehouse chain headquartered in Seattle',
+      maxLength: 1000
     },
     meta: {
       type: 'object',
-      description: 'Extended metadata'
+      description:
+        'Extended metadata (business hours, contact info, additional details)',
+      example: {
+        businessHours: '07:00-22:00',
+        phone: '+1-800-782-7282'
+      }
     },
     dataSource: {
       type: 'string',
-      description: 'Data source',
+      description: 'Data source for this profile',
       enum: ['MANUAL', 'IMPORT', 'API', 'CROWDSOURCED'],
-      example: 'MANUAL'
-    },
-    verifiedAt: {
-      type: 'object',
-      description: 'Verification timestamp (null if not verified)',
-      example: '2025-01-01T00:00:00.000Z',
-      nullable: true
-    },
-    isActive: {
-      type: 'boolean',
-      description: 'Whether the profile is active',
-      example: true
-    },
-    createdAt: {
-      format: 'date-time',
-      type: 'string',
-      description: 'Creation timestamp',
-      example: '2025-01-01T00:00:00.000Z'
-    },
-    updatedAt: {
-      format: 'date-time',
-      type: 'string',
-      description: 'Last update timestamp',
-      example: '2025-01-01T00:00:00.000Z'
+      default: 'MANUAL'
     }
   },
-  required: [
-    'id',
-    'canonical',
-    'aliases',
-    'category',
-    'countries',
-    'keywords',
-    'meta',
-    'dataSource',
-    'isActive',
-    'createdAt',
-    'updatedAt'
-  ]
+  required: ['canonical', 'category']
 } as const;
 
-export const $PayeeProfileListResponseDto = {
+export const $PayeeProfileResponseDto = {
   type: 'object',
   properties: {
-    items: {
-      description: 'List of payee profiles',
+    id: {
+      type: 'string',
+      description: 'Unique identifier (UUID)',
+      example: '550e8400-e29b-41d4-a716-446655440000'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical payee name (unique, case-insensitive)',
+      example: 'Starbucks'
+    },
+    aliases: {
+      description: 'Multi-language aliases',
+      example: ['Starbucks Coffee', 'SBUX'],
       type: 'array',
       items: {
-        $ref: '#/components/schemas/PayeeProfileResponseDto'
+        type: 'string'
       }
     },
-    total: {
-      type: 'number',
-      description: 'Total count of matching records',
-      example: 100
-    }
-  },
-  required: ['items', 'total']
-} as const;
-
-export const $CommodityResponseDto = {
-  type: 'object',
-  properties: {
-    id: {
+    i18nKey: {
       type: 'string',
-      description: 'Unique identifier',
-      example: 'uuid-123-456'
-    },
-    userId: {
-      type: 'object',
-      description: 'User ID (owner of the commodity)',
-      example: 'user-123',
+      description: 'Translation key for i18n',
+      example: 'payee.starbucks',
       nullable: true
     },
-    symbol: {
+    category: {
       type: 'string',
-      description: 'Commodity symbol (corresponds to Beancount currency field)',
-      example: 'AAPL'
+      description: 'Payee category',
+      enum: [
+        'RESTAURANT',
+        'CAFE',
+        'FAST_FOOD',
+        'BAR',
+        'SUPERMARKET',
+        'CONVENIENCE_STORE',
+        'SHOPPING_MALL',
+        'ONLINE_SHOPPING',
+        'TAXI',
+        'RIDE_SHARING',
+        'PUBLIC_TRANSPORT',
+        'PARKING',
+        'GAS_STATION',
+        'UTILITIES',
+        'TELECOM',
+        'STREAMING',
+        'HEALTHCARE',
+        'EDUCATION',
+        'ENTERTAINMENT',
+        'SPORTS',
+        'TRAVEL',
+        'HOTEL',
+        'OTHER'
+      ],
+      example: 'CAFE'
     },
-    date: {
+    subCategory: {
       type: 'string',
-      description:
-        'Commodity definition date (required per Beancount spec). Represents when this commodity was first defined in the accounting system.',
-      example: '2024-01-01',
-      format: 'date'
+      description: 'Sub-category',
+      example: 'coffee_chain',
+      nullable: true
     },
-    metadata: {
-      type: 'object',
-      description:
-        'Metadata (corresponds to Beancount meta field). Contains name, assetClass, precision, note, tags, etc.',
-      example: {
-        name: 'Apple Inc.',
-        assetClass: 'stock',
-        precision: 2,
-        note: 'Tech stock',
-        source: 'AUTO_CREATED'
+    countries: {
+      description: 'Country codes where payee operates',
+      example: ['CN', 'US', 'JP'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    primaryCountry: {
+      type: 'string',
+      description: 'Primary operating country',
+      example: 'US',
+      nullable: true
+    },
+    keywords: {
+      description: 'Search keywords',
+      example: ['coffee', 'cafe'],
+      type: 'array',
+      items: {
+        type: 'string'
       }
     },
-    symbolProfileId: {
+    logoUrl: {
+      type: 'string',
+      description: 'Logo URL',
+      example: 'https://example.com/logo.png',
+      nullable: true
+    },
+    website: {
+      type: 'string',
+      description: 'Official website',
+      example: 'https://www.starbucks.com',
+      nullable: true
+    },
+    description: {
+      type: 'string',
+      description: 'Description',
+      example: 'Global coffeehouse chain',
+      nullable: true
+    },
+    meta: {
       type: 'object',
-      description:
-        'Reference to SymbolProfile (market data integration, SaaS feature)',
-      example: 'uuid-789',
+      description: 'Extended metadata'
+    },
+    dataSource: {
+      type: 'string',
+      description: 'Data source',
+      enum: ['MANUAL', 'IMPORT', 'API', 'CROWDSOURCED'],
+      example: 'MANUAL'
+    },
+    verifiedAt: {
+      type: 'string',
+      description: 'Verification timestamp (null if not verified)',
+      example: '2025-01-01T00:00:00.000Z',
+      format: 'date-time',
       nullable: true
     },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the profile is active',
+      example: true
+    },
     createdAt: {
       format: 'date-time',
       type: 'string',
       description: 'Creation timestamp',
-      example: '2024-11-03T10:00:00Z'
+      example: '2025-01-01T00:00:00.000Z'
     },
     updatedAt: {
       format: 'date-time',
       type: 'string',
       description: 'Last update timestamp',
-      example: '2024-11-03T10:00:00Z'
+      example: '2025-01-01T00:00:00.000Z'
     }
   },
-  required: ['id', 'symbol', 'date', 'metadata', 'createdAt', 'updatedAt']
+  required: [
+    'id',
+    'canonical',
+    'aliases',
+    'category',
+    'countries',
+    'keywords',
+    'meta',
+    'dataSource',
+    'isActive',
+    'createdAt',
+    'updatedAt'
+  ]
 } as const;
 
-export const $CommodityListResponseDto = {
+export const $PayeeProfileListResponseDto = {
   type: 'object',
   properties: {
     items: {
-      description: 'List of commodities',
+      description: 'List of payee profiles',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/CommodityResponseDto'
+        $ref: '#/components/schemas/PayeeProfileResponseDto'
       }
     },
     total: {
       type: 'number',
-      description: 'Total number of commodities',
-      example: 42
+      description: 'Total count of matching records',
+      example: 100
     }
   },
   required: ['items', 'total']
 } as const;
 
-export const $RecurringRuleResponseDto = {
+export const $UpdatePayeeProfileDto = {
   type: 'object',
   properties: {
-    id: {
+    aliases: {
+      description:
+        'Multi-language aliases for the payee. Used for matching user input in different languages.',
+      example: ['Starbucks Coffee', 'SBUX'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    i18nKey: {
       type: 'string',
-      description: 'Rule ID'
+      description:
+        'Translation key for i18n integration (XLIFF translation system)',
+      example: 'payee.starbucks',
+      maxLength: 100
     },
-    userId: {
+    category: {
       type: 'string',
-      description: 'User ID'
+      description: 'Payee category classification',
+      enum: [
+        'RESTAURANT',
+        'CAFE',
+        'FAST_FOOD',
+        'BAR',
+        'SUPERMARKET',
+        'CONVENIENCE_STORE',
+        'SHOPPING_MALL',
+        'ONLINE_SHOPPING',
+        'TAXI',
+        'RIDE_SHARING',
+        'PUBLIC_TRANSPORT',
+        'PARKING',
+        'GAS_STATION',
+        'UTILITIES',
+        'TELECOM',
+        'STREAMING',
+        'HEALTHCARE',
+        'EDUCATION',
+        'ENTERTAINMENT',
+        'SPORTS',
+        'TRAVEL',
+        'HOTEL',
+        'OTHER'
+      ],
+      example: 'CAFE'
     },
-    name: {
+    subCategory: {
       type: 'string',
-      description: 'Rule name'
+      description: 'Sub-category for more specific classification',
+      example: 'coffee_chain',
+      maxLength: 100
     },
-    icon: {
-      type: 'object',
-      description: 'Icon emoji'
+    countries: {
+      description:
+        'Country/region codes where the payee operates (ISO 3166-1 alpha-2)',
+      example: ['CN', 'US', 'JP'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
     },
-    frequency: {
+    primaryCountry: {
       type: 'string',
-      description: 'Recurring frequency'
+      description: 'Primary operating country (ISO 3166-1 alpha-2)',
+      example: 'US',
+      maxLength: 2
     },
-    expectedAmount: {
+    keywords: {
+      description: 'Search keywords for fuzzy matching',
+      example: ['coffee', 'cafe', 'drinks'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Payee logo URL',
+      example: 'https://example.com/logo.png'
+    },
+    website: {
+      type: 'string',
+      description: 'Official website URL',
+      example: 'https://www.starbucks.com'
+    },
+    description: {
+      type: 'string',
+      description: 'Payee description',
+      example: 'Global coffeehouse chain headquartered in Seattle',
+      maxLength: 1000
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Extended metadata (business hours, contact info, additional details)',
+      example: {
+        businessHours: '07:00-22:00',
+        phone: '+1-800-782-7282'
+      }
+    },
+    dataSource: {
+      type: 'string',
+      description: 'Data source for this profile',
+      enum: ['MANUAL', 'IMPORT', 'API', 'CROWDSOURCED'],
+      default: 'MANUAL'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the payee profile is active (soft delete)',
+      example: true
+    },
+    verifiedAt: {
+      type: 'string',
+      description:
+        'Verification timestamp. Set to current time to verify, or null to unverify.',
+      example: '2025-01-01T00:00:00.000Z',
+      format: 'date-time',
+      nullable: true
+    }
+  }
+} as const;
+
+export const $CreateCommodityDto = {
+  type: 'object',
+  properties: {
+    symbol: {
+      type: 'string',
+      description:
+        'Commodity symbol (e.g., AAPL, USD, BTC) - corresponds to Beancount currency field',
+      example: 'AAPL',
+      maxLength: 50
+    },
+    date: {
+      type: 'string',
+      description:
+        'Commodity definition date (ISO 8601, required per Beancount spec). Represents when this commodity was first defined in the accounting system.',
+      example: '2024-01-01',
+      format: 'date'
+    },
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Can contain name, assetClass, precision, note, tags, etc.',
+      example: {
+        name: 'Apple Inc.',
+        assetClass: 'stock',
+        precision: 2,
+        note: 'Long-term investment',
+        tags: ['tech', 'dividend']
+      }
+    }
+  },
+  required: ['symbol', 'date']
+} as const;
+
+export const $CommodityResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the commodity)',
+      example: 'user-123',
+      nullable: true
+    },
+    symbol: {
+      type: 'string',
+      description: 'Commodity symbol (corresponds to Beancount currency field)',
+      example: 'AAPL'
+    },
+    date: {
+      type: 'string',
+      description:
+        'Commodity definition date (required per Beancount spec). Represents when this commodity was first defined in the accounting system.',
+      example: '2024-01-01',
+      format: 'date'
+    },
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Contains name, assetClass, precision, note, tags, etc.',
+      example: {
+        name: 'Apple Inc.',
+        assetClass: 'stock',
+        precision: 2,
+        note: 'Tech stock',
+        source: 'AUTO_CREATED'
+      }
+    },
+    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', 'symbol', 'date', 'metadata', 'createdAt', 'updatedAt']
+} as const;
+
+export const $CommodityListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of commodities',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CommodityResponseDto'
+      }
+    },
+    total: {
       type: 'number',
-      description: 'Expected amount'
+      description: 'Total number of commodities',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateCommodityDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description:
+        'Commodity definition date (ISO 8601). Represents when this commodity was first defined in the accounting system.',
+      example: '2024-01-01',
+      format: 'date'
     },
-    expectedDay: {
+    metadata: {
       type: 'object',
-      description: 'Expected day of month'
+      description:
+        'Metadata (corresponds to Beancount meta field). Will merge with existing metadata. Can contain name, assetClass, precision, note, tags, etc.',
+      example: {
+        name: 'Updated Apple Inc.',
+        assetClass: 'equity',
+        precision: 4,
+        note: 'Updated investment strategy',
+        lastReviewed: '2024-11-03'
+      }
+    }
+  }
+} 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: 'object',
-      description: 'Custom interval in days'
+      type: 'number',
+      description: 'Custom interval in days (required for CUSTOM frequency)',
+      minimum: 1
     },
     currency: {
       type: 'string',
-      description: 'Currency code'
+      description: 'Currency code',
+      default: 'CNY',
+      maxLength: 10
     },
     matchPayeePattern: {
-      type: 'object',
-      description: 'Payee matching pattern'
+      type: 'string',
+      description: 'Payee matching pattern (supports wildcards)',
+      maxLength: 200
     },
     matchAmountTolerance: {
       type: 'number',
-      description: 'Amount tolerance percentage'
+      description: 'Amount tolerance percentage (0-1)',
+      default: 0.075,
+      minimum: 0,
+      maximum: 1
     },
     defaultExpenseAccount: {
-      type: 'object',
-      description: 'Default expense account'
+      type: 'string',
+      description: 'Default expense account for auto-create',
+      maxLength: 200
     },
     defaultPaymentAccount: {
-      type: 'object',
-      description: 'Default payment account'
+      type: 'string',
+      description: 'Default payment account for auto-create',
+      maxLength: 200
     },
     defaultPayee: {
-      type: 'object',
-      description: 'Default payee'
-    },
-    isActive: {
-      type: 'boolean',
-      description: 'Whether rule is active'
-    },
-    startDate: {
       type: 'string',
-      description: 'Rule start date (YYYY-MM-DD)'
-    },
-    endDate: {
-      type: 'object',
-      description: 'Rule end date (YYYY-MM-DD)'
+      description: 'Default payee for auto-create',
+      maxLength: 200
     },
     autoCreate: {
       type: 'boolean',
-      description: 'Auto-create transaction on expected date'
-    },
-    lastOccurrence: {
-      type: 'object',
-      description: 'Last matched occurrence date (YYYY-MM-DD)'
-    },
-    totalCount: {
-      type: 'number',
-      description: 'Total matched transactions count'
+      description: 'Auto-create transaction when expected date arrives',
+      default: false
     },
-    createdAt: {
-      format: 'date-time',
+    startDate: {
       type: 'string',
-      description: 'Created at timestamp'
+      description: 'Rule start date (ISO format)'
     },
-    updatedAt: {
-      format: 'date-time',
+    endDate: {
       type: 'string',
-      description: 'Updated at timestamp'
+      description: 'Rule end date (ISO format)'
     }
   },
   required: [
-    'id',
-    'userId',
     'name',
     'frequency',
     'expectedAmount',
     'currency',
     'matchAmountTolerance',
-    'isActive',
-    'startDate',
-    'autoCreate',
-    'totalCount',
-    'createdAt',
-    'updatedAt'
+    'autoCreate'
   ]
 } as const;
 
-export const $RecurringRuleWithStatsResponseDto = {
+export const $RecurringRuleResponseDto = {
   type: 'object',
   properties: {
     id: {
@@ -1943,19 +2936,161 @@ export const $RecurringRuleWithStatsResponseDto = {
       format: 'date-time',
       type: 'string',
       description: 'Updated at timestamp'
-    },
-    pendingCount: {
-      type: 'number',
-      description: 'Number of pending expected transactions'
-    },
-    overdueCount: {
-      type: 'number',
-      description: 'Number of overdue expected transactions'
-    },
-    nextExpectedDate: {
-      type: 'object',
-      description: 'Next expected date (YYYY-MM-DD)'
-    },
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'name',
+    'frequency',
+    'expectedAmount',
+    'currency',
+    'matchAmountTolerance',
+    'isActive',
+    'startDate',
+    'autoCreate',
+    'totalCount',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $CreateRuleFromTransactionDto = {
+  type: 'object',
+  properties: {
+    frequency: {
+      type: 'string',
+      description: 'Recurring frequency',
+      enum: [
+        'WEEKLY',
+        'BIWEEKLY',
+        'MONTHLY',
+        'BIMONTHLY',
+        'QUARTERLY',
+        'YEARLY',
+        'CUSTOM'
+      ],
+      example: 'MONTHLY'
+    },
+    name: {
+      type: 'string',
+      description: 'Optional name override (default: transaction payee)',
+      maxLength: 100
+    },
+    icon: {
+      type: 'string',
+      description: 'Optional icon emoji',
+      maxLength: 10
+    }
+  },
+  required: ['frequency']
+} as const;
+
+export const $RecurringRuleWithStatsResponseDto = {
+  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',
+      description: 'Expected amount'
+    },
+    expectedDay: {
+      type: 'object',
+      description: 'Expected day of month'
+    },
+    customIntervalDays: {
+      type: 'object',
+      description: 'Custom interval in days'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    matchPayeePattern: {
+      type: 'object',
+      description: 'Payee matching pattern'
+    },
+    matchAmountTolerance: {
+      type: 'number',
+      description: 'Amount tolerance percentage'
+    },
+    defaultExpenseAccount: {
+      type: 'object',
+      description: 'Default expense account'
+    },
+    defaultPaymentAccount: {
+      type: 'object',
+      description: 'Default payment account'
+    },
+    defaultPayee: {
+      type: 'object',
+      description: 'Default payee'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether rule is active'
+    },
+    startDate: {
+      type: 'string',
+      description: 'Rule start date (YYYY-MM-DD)'
+    },
+    endDate: {
+      type: 'object',
+      description: 'Rule end date (YYYY-MM-DD)'
+    },
+    autoCreate: {
+      type: 'boolean',
+      description: 'Auto-create transaction on expected date'
+    },
+    lastOccurrence: {
+      type: 'object',
+      description: 'Last matched occurrence date (YYYY-MM-DD)'
+    },
+    totalCount: {
+      type: 'number',
+      description: 'Total matched transactions count'
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Created at timestamp'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Updated at timestamp'
+    },
+    pendingCount: {
+      type: 'number',
+      description: 'Number of pending expected transactions'
+    },
+    overdueCount: {
+      type: 'number',
+      description: 'Number of overdue expected transactions'
+    },
+    nextExpectedDate: {
+      type: 'object',
+      description: 'Next expected date (YYYY-MM-DD)'
+    },
     totalAmount: {
       type: 'number',
       description: 'Total amount of all matched transactions'
@@ -2009,6 +3144,94 @@ export const $RecurringRuleWithStatsResponseDto = {
   ]
 } as const;
 
+export const $UpdateRecurringRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Rule name',
+      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',
+      minimum: 0
+    },
+    expectedDay: {
+      type: 'number',
+      description: 'Expected day of month (1-31)',
+      minimum: 1,
+      maximum: 31
+    },
+    customIntervalDays: {
+      type: 'number',
+      description: 'Custom interval in days',
+      minimum: 1
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      maxLength: 10
+    },
+    matchPayeePattern: {
+      type: 'string',
+      description: 'Payee matching pattern',
+      maxLength: 200
+    },
+    matchAmountTolerance: {
+      type: 'number',
+      description: 'Amount tolerance percentage (0-1)',
+      minimum: 0,
+      maximum: 1
+    },
+    defaultExpenseAccount: {
+      type: 'string',
+      description: 'Default expense account',
+      maxLength: 200
+    },
+    defaultPaymentAccount: {
+      type: 'string',
+      description: 'Default payment account',
+      maxLength: 200
+    },
+    defaultPayee: {
+      type: 'string',
+      description: 'Default payee',
+      maxLength: 200
+    },
+    autoCreate: {
+      type: 'boolean',
+      description: 'Auto-create transaction'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Rule active status'
+    },
+    endDate: {
+      type: 'string',
+      description: 'Rule end date (ISO format)'
+    }
+  }
+} as const;
+
 export const $ExpectedTransactionRuleDto = {
   type: 'object',
   properties: {
@@ -2125,6 +3348,50 @@ export const $ExpectedTransactionListResponseDto = {
   required: ['items', 'total']
 } as const;
 
+export const $ConfirmMatchDto = {
+  type: 'object',
+  properties: {
+    transactionId: {
+      type: 'string',
+      description: 'Transaction ID to match with'
+    }
+  },
+  required: ['transactionId']
+} as const;
+
+export const $EnterNowDto = {
+  type: 'object',
+  properties: {
+    expenseAccount: {
+      type: 'string',
+      description:
+        'Override expense account (uses rule default if not provided)',
+      maxLength: 200
+    },
+    paymentAccount: {
+      type: 'string',
+      description:
+        'Override payment account (uses rule default if not provided)',
+      maxLength: 200
+    },
+    amount: {
+      type: 'number',
+      description: 'Override amount (uses expected amount if not provided)',
+      minimum: 0
+    },
+    payee: {
+      type: 'string',
+      description: 'Override payee (uses rule default if not provided)',
+      maxLength: 200
+    },
+    narration: {
+      type: 'string',
+      description: 'Optional narration',
+      maxLength: 500
+    }
+  }
+} as const;
+
 export const $ForecastItemDto = {
   type: 'object',
   properties: {
@@ -2149,7 +3416,7 @@ export const $ForecastItemDto = {
       example: '2024-04-01'
     },
     icon: {
-      type: 'object',
+      type: 'string',
       description: 'Rule icon emoji',
       example: '🏠',
       nullable: true
@@ -2249,6 +3516,107 @@ export const $ForecastResponseDto = {
   ]
 } as const;
 
+export const $CreateTransactionRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 100
+    },
+    description: {
+      type: 'string',
+      maxLength: 500
+    },
+    narrationKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    payeeKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    categoryKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    methodKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
+      type: 'array'
+    },
+    categoryAccount: {
+      type: 'string',
+      maxLength: 200,
+      description:
+        'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
+    },
+    matchLogic: {
+      type: 'string',
+      enum: ['OR', 'AND'],
+      default: 'OR'
+    },
+    amountMin: {
+      type: 'number',
+      minimum: 0,
+      description: 'Minimum transaction amount (inclusive)'
+    },
+    amountMax: {
+      type: 'number',
+      minimum: 0,
+      description: 'Maximum transaction amount (inclusive)'
+    },
+    priority: {
+      type: 'number',
+      default: 50,
+      minimum: 0,
+      maximum: 1000
+    },
+    additionalTags: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 20,
+      type: 'array'
+    },
+    additionalMetadata: {
+      type: 'object'
+    },
+    upsertByPayee: {
+      type: 'boolean',
+      description:
+        'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
+    }
+  },
+  required: ['name', 'matchLogic', 'priority']
+} as const;
+
+export const $AmountRangeDto = {
+  type: 'object',
+  properties: {
+    min: {
+      type: 'number',
+      description: 'Minimum amount'
+    },
+    max: {
+      type: 'number',
+      description: 'Maximum amount'
+    }
+  }
+} as const;
+
 export const $TransactionRuleResponseDto = {
   type: 'object',
   properties: {
@@ -2303,12 +3671,12 @@ export const $TransactionRuleResponseDto = {
       example: 'OR'
     },
     amountRange: {
-      type: 'object',
       description: 'Amount range for matching',
-      example: {
-        min: 0,
-        max: 100
-      }
+      allOf: [
+        {
+          $ref: '#/components/schemas/AmountRangeDto'
+        }
+      ]
     },
     priority: {
       type: 'number',
@@ -2323,6 +3691,7 @@ export const $TransactionRuleResponseDto = {
       type: 'string',
       description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
       enum: ['NLP', 'REVIEW_CENTER'],
+      nullable: true,
       example: 'REVIEW_CENTER'
     },
     autoApplyEnabled: {
@@ -2344,7 +3713,9 @@ export const $TransactionRuleResponseDto = {
     additionalMetadata: {
       type: 'object',
       description: 'Additional metadata',
-      example: {}
+      additionalProperties: {
+        type: 'string'
+      }
     },
     createdAt: {
       format: 'date-time',
@@ -2517,6 +3888,64 @@ export const $ValidateRuleResponseDto = {
   required: ['valid', 'errors', 'warnings']
 } as const;
 
+export const $BulkCreateRulesDto = {
+  type: 'object',
+  properties: {
+    rules: {
+      items: {
+        type: 'array'
+      },
+      description: 'Array of rules to import',
+      type: 'array'
+    },
+    conflictStrategy: {
+      type: 'string',
+      enum: ['replace', 'skip'],
+      default: 'skip',
+      description:
+        'Conflict handling strategy: skip (default) ignores duplicates, replace soft-deletes existing rule'
+    }
+  },
+  required: ['rules', 'conflictStrategy']
+} as const;
+
+export const $BulkCreateRulesResponseDto = {
+  type: 'object',
+  properties: {
+    successCount: {
+      type: 'number',
+      description: 'Number of successfully created rules'
+    },
+    failureCount: {
+      type: 'number',
+      description: 'Number of failed rules'
+    },
+    errors: {
+      type: 'array',
+      description: 'Error details for failed rules',
+      items: {
+        type: 'object',
+        properties: {
+          index: {
+            type: 'number'
+          },
+          message: {
+            type: 'string'
+          }
+        }
+      }
+    },
+    createdRuleIds: {
+      description: 'IDs of successfully created rules',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['successCount', 'failureCount', 'errors', 'createdRuleIds']
+} as const;
+
 export const $ExportRulesResponseDto = {
   type: 'object',
   properties: {
@@ -2597,6 +4026,89 @@ export const $RuleStatisticsResponseDto = {
   ]
 } as const;
 
+export const $UpdateTransactionRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 100
+    },
+    description: {
+      type: 'string',
+      maxLength: 500
+    },
+    narrationKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    payeeKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    categoryKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    methodKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
+      type: 'array'
+    },
+    categoryAccount: {
+      type: 'string',
+      maxLength: 200,
+      description:
+        'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
+    },
+    matchLogic: {
+      type: 'string',
+      enum: ['OR', 'AND']
+    },
+    amountMin: {
+      type: 'number',
+      minimum: 0,
+      description: 'Minimum transaction amount (inclusive)'
+    },
+    amountMax: {
+      type: 'number',
+      minimum: 0,
+      description: 'Maximum transaction amount (inclusive)'
+    },
+    priority: {
+      type: 'number',
+      minimum: 0,
+      maximum: 1000
+    },
+    enabled: {
+      type: 'boolean',
+      description: 'Enable or disable the rule'
+    },
+    additionalTags: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 20,
+      type: 'array'
+    },
+    additionalMetadata: {
+      type: 'object'
+    }
+  }
+} as const;
+
 export const $TestRuleDto = {
   type: 'object',
   properties: {
@@ -2789,31 +4301,180 @@ export const $UpdateUserSettingDto = {
   }
 } as const;
 
-export const $FileImportDto = {
+export const $UpdatePropertyDto = {
   type: 'object',
   properties: {
-    file: {
+    value: {
       type: 'string',
-      format: 'binary',
-      description: 'Bill file to import (CSV, PDF, OFX, etc.)',
-      example: 'alipay.csv'
+      description: 'Property value'
     }
   },
-  required: ['file']
+  required: ['value']
 } as const;
 
-export const $ImportErrorDto = {
+export const $CreateBeanEventDto = {
   type: 'object',
   properties: {
-    index: {
-      type: 'number',
-      description: 'Index of failed transaction in the file',
-      example: 5
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)',
+      example: '2024-03-15'
     },
-    error: {
+    type: {
       type: 'string',
-      description: 'Error message',
-      example: 'Transaction does not balance: -100 USD != 0'
+      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: ['date', 'type', 'description']
+} as const;
+
+export const $EventResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the life event)',
+      example: 'user-123'
+    },
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601 format)',
+      example: '2024-03-15',
+      format: 'date'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (user-defined, e.g., "employer", "location")',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. May be an empty string (a valid value distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)',
+      example: {
+        note: 'Promotion'
+      }
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-03-15T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      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: [
+    'id',
+    'userId',
+    'date',
+    'type',
+    'description',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $EventListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of life events',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/EventResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of life events matching the query',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateBeanEventDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)'
+    },
+    type: {
+      type: 'string',
+      description: 'Life event type (user-defined)'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)'
+    }
+  }
+} 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']
@@ -3088,7 +4749,8 @@ export const $ImporterConfigDto = {
         'cmbc-credit',
         'icbc',
         'icbc-credit',
-        'hsbc-hk'
+        'hsbc-hk-credit',
+        'hsbc-hk-debit'
       ]
     },
     version: {
@@ -3134,6 +4796,181 @@ export const $ImporterConfigDto = {
   ]
 } as const;
 
+export const $UpdateMapperDefaultsDto = {
+  type: 'object',
+  properties: {
+    sourceAccount: {
+      type: 'string',
+      description: 'Source account for transactions (Beancount format)',
+      example: 'Assets:Alipay:Balance',
+      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+    },
+    currency: {
+      type: 'string',
+      description: 'Default currency (ISO 4217 code)',
+      example: 'CNY',
+      minLength: 3,
+      maxLength: 3,
+      pattern: '^[A-Z]{3}$'
+    },
+    expenseAccount: {
+      type: 'string',
+      description: 'Default expense account (optional)',
+      example: 'Expenses:Unknown',
+      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+    },
+    incomeAccount: {
+      type: 'string',
+      description: 'Default income account (optional)',
+      example: 'Income:Unknown',
+      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+    },
+    methodAccountMapping: {
+      type: 'object',
+      description:
+        'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
+      example: {
+        HuaBei: 'Liabilities:Alipay:Huabei',
+        CreditCard: 'Liabilities:CreditCard'
+      }
+    }
+  }
+} as const;
+
+export const $UpdateConfigDataDto = {
+  type: 'object',
+  properties: {
+    defaults: {
+      description: 'Mapper defaults configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UpdateMapperDefaultsDto'
+        }
+      ]
+    }
+  }
+} as const;
+
+export const $UpdateImporterConfigDto = {
+  type: 'object',
+  properties: {
+    data: {
+      description: 'Configuration data (v1 schema)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UpdateConfigDataDto'
+        }
+      ]
+    }
+  }
+} as const;
+
+export const $CreatePlatformDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Platform name',
+      example: 'Binance'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Platform canonical identifier (lowercase, kebab-case)',
+      example: 'binance'
+    },
+    aliases: {
+      description: 'Platform aliases (multi-language names for lookup)',
+      example: ['Binance', 'Binance Exchange', 'BNB'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    url: {
+      type: 'string',
+      description: 'Platform URL',
+      example: 'https://www.binance.com'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ],
+      example: 'CRYPTO_EXCHANGE'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Platform logo URL',
+      example: 'https://example.com/logos/binance.png'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the platform is active',
+      default: true
+    }
+  },
+  required: ['name', 'canonical', 'aliases', 'url', 'type']
+} as const;
+
+export const $UpdatePlatformDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Platform name',
+      example: 'Binance'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Platform canonical identifier (lowercase, kebab-case)',
+      example: 'binance'
+    },
+    aliases: {
+      description: 'Platform aliases (multi-language names for lookup)',
+      example: ['Binance', 'Binance Exchange', 'BNB'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    url: {
+      type: 'string',
+      description: 'Platform URL',
+      example: 'https://www.binance.com'
+    },
+    type: {
+      type: 'string',
+      description: 'Platform type',
+      enum: [
+        'BANK',
+        'BROKERAGE',
+        'CRYPTO_EXCHANGE',
+        'PAYMENT',
+        'INVESTMENT',
+        'INSURANCE',
+        'OTHER'
+      ],
+      example: 'CRYPTO_EXCHANGE'
+    },
+    logoUrl: {
+      type: 'string',
+      description: 'Platform logo URL',
+      example: 'https://example.com/logos/binance.png'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the platform is active'
+    }
+  }
+} as const;
+
 export const $ProviderSyncConfigDto = {
   type: 'object',
   properties: {
@@ -3268,7 +5105,8 @@ export const $SupportedProvidersResponseDto = {
         'gocardless',
         'simplefin',
         'yodlee',
-        'beancount-direct'
+        'beancount-direct',
+        'parsed-bill'
       ],
       type: 'array',
       items: {
@@ -3279,6 +5117,16 @@ export const $SupportedProvidersResponseDto = {
   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: {
@@ -3293,6 +5141,16 @@ export const $ProcessNlpDto = {
       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']
@@ -4007,116 +5865,663 @@ export const $NlpResponseDto = {
         'Account validation data (when action is "confirm_account"). Contains information about invalid account for user correction.',
       allOf: [
         {
-          $ref: '#/components/schemas/NlpAccountConfirmationDataDto'
+          $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/RecurringSuggestionDto'
+        }
+      ]
+    },
+    suggestedAccounts: {
+      description:
+        'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
+      allOf: [
+        {
+          $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 $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 $NetWorthByCurrencyDto = {
+  type: 'object',
+  properties: {
+    netWorth: {
+      description: 'Net worth by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    assets: {
+      description: 'Assets by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    liabilities: {
+      description: 'Liabilities by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    }
+  },
+  required: ['netWorth', 'assets', 'liabilities']
+} as const;
+
+export const $ConvertedNetWorthDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    netWorth: {
+      type: 'string',
+      description: 'Converted net worth',
+      example: '500000.00'
+    },
+    assets: {
+      type: 'string',
+      description: 'Converted assets',
+      example: '600000.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Converted liabilities',
+      example: '100000.00'
+    },
+    exchangeRates: {
+      type: 'object',
+      description: 'Exchange rates used for conversion',
+      example: {
+        USD: '7.200000',
+        EUR: '7.800000'
+      }
+    }
+  },
+  required: [
+    'baseCurrency',
+    'netWorth',
+    'assets',
+    'liabilities',
+    'exchangeRates'
+  ]
+} 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: {
+    netWorth: {
+      type: 'string',
+      description:
+        'Total net worth (assets - liabilities, converted to base currency)',
+      example: '500000.00'
+    },
+    assets: {
+      type: 'string',
+      description: 'Total assets value (converted)',
+      example: '600000.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Total liabilities value (positive number, converted)',
+      example: '100000.00'
+    },
+    monthlyReturn: {
+      type: 'string',
+      description: 'Monthly return (change from last month)',
+      example: '15000.00'
+    },
+    monthlyReturnPercentage: {
+      type: 'string',
+      description: 'Monthly return percentage',
+      example: '3.15'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency code',
+      example: 'CNY'
+    },
+    asOf: {
+      type: 'string',
+      description: 'Data as of date (ISO 8601)',
+      example: '2024-06-15T00:00:00.000Z'
+    },
+    byCurrency: {
+      description: 'Balances grouped by original currency',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NetWorthByCurrencyDto'
+        }
+      ]
+    },
+    converted: {
+      description:
+        'Converted values in base currency (undefined if no exchange rates available)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ConvertedNetWorthDto'
+        }
+      ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: [
+    'netWorth',
+    'assets',
+    'liabilities',
+    'monthlyReturn',
+    'monthlyReturnPercentage',
+    'currency',
+    'asOf'
+  ]
+} as const;
+
+export const $AccountItemDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Account ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Full account name',
+      example: 'Assets:Bank:CMB:Savings'
+    },
+    displayName: {
+      type: 'string',
+      description: 'Display name (last part of account path)',
+      example: 'Savings'
+    },
+    balance: {
+      type: 'string',
+      description: 'Account balance',
+      example: '50000.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    }
+  },
+  required: ['id', 'name', 'displayName', 'balance', 'currency']
+} as const;
+
+export const $PlatformGroupDto = {
+  type: 'object',
+  properties: {
+    platformId: {
+      type: 'string',
+      description: 'Platform ID'
+    },
+    platformName: {
+      type: 'string',
+      description: 'Platform display name',
+      example: 'CMB Bank'
+    },
+    accounts: {
+      description: 'Accounts within this platform',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountItemDto'
+      }
+    },
+    totalBalance: {
+      type: 'string',
+      description: 'Total balance across all accounts in platform',
+      example: '100000.00'
+    }
+  },
+  required: ['platformId', 'platformName', 'accounts', 'totalBalance']
+} as const;
+
+export const $AccountsSummaryDto = {
+  type: 'object',
+  properties: {
+    totalAccounts: {
+      type: 'number',
+      description: 'Total number of accounts'
+    },
+    totalPlatforms: {
+      type: 'number',
+      description: 'Total number of platforms'
+    }
+  },
+  required: ['totalAccounts', 'totalPlatforms']
+} as const;
+
+export const $AccountsResponseDto = {
+  type: 'object',
+  properties: {
+    groups: {
+      description: 'Account groups by platform',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PlatformGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AccountsSummaryDto'
+        }
+      ]
+    }
+  },
+  required: ['groups', 'summary']
+} as const;
+
+export const $AccountItemWithAssetClassDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Account ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Full account name',
+      example: 'Assets:Bank:CMB:Savings'
+    },
+    displayName: {
+      type: 'string',
+      description: 'Display name (last part of account path)',
+      example: 'Savings'
+    },
+    balance: {
+      type: 'string',
+      description: 'Account balance',
+      example: '50000.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    assetClass: {
+      type: 'string',
+      description: 'Asset class',
+      example: 'LIQUIDITY'
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'Asset sub-class (Prisma-compatible)',
+      example: 'RETIREMENT_ACCOUNT'
+    },
+    regionalSubClass: {
+      type: 'string',
+      description: 'Regional sub-class (region-specific, for display)',
+      example: 'FOUR_ZERO_ONE_K'
+    },
+    riskLevel: {
+      type: 'string',
+      description: 'Risk level',
+      example: 'LOW'
+    },
+    source: {
+      type: 'string',
+      description:
+        'ADR-0105 classification provenance (holding level always; account level only on FALLBACK)',
+      enum: ['USER_META', 'FIAT_CURRENCY', 'OPENBB_MAPPING', 'FALLBACK']
+    }
+  },
+  required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
+} as const;
+
+export const $AssetClassGroupDto = {
+  type: 'object',
+  properties: {
+    assetClass: {
+      type: 'string',
+      description: 'Asset class name',
+      example: 'LIQUIDITY',
+      enum: [
+        'LIQUIDITY',
+        'EQUITY',
+        'FIXED_INCOME',
+        'PRECIOUS_METALS',
+        'COMMODITY',
+        'INSURANCE',
+        'ALTERNATIVE_INVESTMENT',
+        'PERSONAL_ASSETS',
+        'LIABILITY',
+        'REAL_ESTATE',
+        'INDEX'
+      ]
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'Asset sub-class name',
+      example: 'DEPOSIT'
+    },
+    accounts: {
+      description: 'Accounts within this asset class',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountItemWithAssetClassDto'
+      }
+    },
+    balanceByCurrency: {
+      description: 'Balances grouped by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    convertedBalance: {
+      type: 'string',
+      description: 'Converted balance in base currency',
+      example: '100000.00'
+    }
+  },
+  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: {
+    totalAccounts: {
+      type: 'number',
+      description: 'Total number of accounts'
+    },
+    totalAssetClasses: {
+      type: 'number',
+      description: 'Total number of asset classes'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountExchangeRateWarningDto'
+      }
+    },
+    fallback: {
+      type: 'object',
+      description:
+        'ADR-0105 §4 fallback provenance stats (holding level only). valueRatio is the grey-area share of total converted value; count is the number of source=FALLBACK holdings.'
+    }
+  },
+  required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
+} as const;
+
+export const $AssetClassAccountsResponseDto = {
+  type: 'object',
+  properties: {
+    groups: {
+      description: 'Account groups by asset class',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AssetClassGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassSummaryDto'
         }
       ]
     },
-    payeeData: {
+    uncategorized: {
       description:
-        'Payee confirmation data (when action is "confirm_payee"). Contains information about medium/low confidence payee match for user confirmation.',
+        'ADR-0105 §6 holding-level grey-area bucket (source=FALLBACK holdings peeled out of groups). Present only for groupBy=holdingAssetClass when FALLBACK holdings exist.',
       allOf: [
         {
-          $ref: '#/components/schemas/NlpPayeeConfirmationDataDto'
+          $ref: '#/components/schemas/AssetClassGroupDto'
         }
       ]
+    }
+  },
+  required: ['groups', 'summary']
+} as const;
+
+export const $HoldingAssetClassAccountSliceDto = {
+  type: 'object',
+  properties: {
+    accountId: {
+      type: 'string',
+      description: 'Account ID'
     },
-    confidence: {
-      type: 'number',
-      description: 'Overall confidence score (0-1)',
-      example: 0.85
+    accountPath: {
+      type: 'string',
+      description: 'Full account path',
+      example: 'Assets:US:Investments:Brokerage'
     },
-    confidenceThreshold: {
-      type: 'number',
+    accountCurrency: {
+      type: 'string',
       description:
-        'Confidence threshold for automatic creation (default: 0.75). When confidence < threshold, action will be "confirm" requiring user verification.',
-      example: 0.75
+        'Currency of the holding with the largest converted base value; undefined when no holding is convertible',
+      example: 'USD'
     },
-    recurringMatch: {
+    marketValueBase: {
+      type: 'string',
       description:
-        'Recurring transaction match info (when action is "created"). Contains match details when transaction matches a pending expected transaction.',
-      allOf: [
-        {
-          $ref: '#/components/schemas/RecurringMatchInfoDto'
-        }
-      ]
+        "Account's market value in base currency (Σ converted holdings; grey bucket included)",
+      example: '50000.00'
     },
-    recurringSuggestion: {
+    shareOfTotalPct: {
+      type: 'number',
       description:
-        'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
-      allOf: [
-        {
-          $ref: '#/components/schemas/RecurringSuggestionDto'
-        }
-      ]
+        'Share of the global total (0-100). 0 when globalTotal is zero (no NaN/Infinity).',
+      example: 42.5
     },
-    suggestedAccounts: {
+    groups: {
+      description: 'Per-account asset-class breakdown',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AssetClassGroupDto'
+      }
+    },
+    uncategorized: {
       description:
-        'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
+        'Per-account grey bucket (source=FALLBACK holdings, incl. broker cash)',
       allOf: [
         {
-          $ref: '#/components/schemas/NlpSuggestedAccountsDto'
+          $ref: '#/components/schemas/AssetClassGroupDto'
         }
       ]
     },
-    defaultAccounts: {
+    holdings: {
       description:
-        'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
-      allOf: [
-        {
-          $ref: '#/components/schemas/NlpDefaultAccountsDto'
-        }
-      ]
+        'Every holding row for this account (account ID in each row’s `id` field)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountItemWithAssetClassDto'
+      }
     }
   },
-  required: ['status', 'action']
+  required: [
+    'accountId',
+    'accountPath',
+    'marketValueBase',
+    'shareOfTotalPct',
+    'groups',
+    'holdings'
+  ]
 } as const;
 
-export const $BalanceByCurrencyDto = {
+export const $HoldingAssetClassCrossAccountResponseDto = {
   type: 'object',
   properties: {
-    currency: {
-      type: 'string',
-      description: 'ISO 4217 currency code',
-      example: 'CNY'
+    global: {
+      description: 'Merged cross-account holding aggregation',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassAccountsResponseDto'
+        }
+      ]
     },
-    balance: {
-      type: 'string',
-      description: 'Balance amount',
-      example: '50000.00'
+    byAccount: {
+      description: 'Per-account slices',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/HoldingAssetClassAccountSliceDto'
+      }
     }
   },
-  required: ['currency', 'balance']
+  required: ['global', 'byAccount']
 } as const;
 
-export const $NetWorthByCurrencyDto = {
+export const $CashFlowByCurrencyDto = {
   type: 'object',
   properties: {
-    netWorth: {
-      description: 'Net worth by currency',
+    income: {
+      description: 'Income by currency',
       type: 'array',
       items: {
         $ref: '#/components/schemas/BalanceByCurrencyDto'
       }
     },
-    assets: {
-      description: 'Assets by currency',
+    expense: {
+      description: 'Expense by currency',
       type: 'array',
       items: {
         $ref: '#/components/schemas/BalanceByCurrencyDto'
       }
     },
-    liabilities: {
-      description: 'Liabilities by currency',
+    netSavings: {
+      description: 'Net savings by currency',
       type: 'array',
       items: {
         $ref: '#/components/schemas/BalanceByCurrencyDto'
       }
     }
   },
-  required: ['netWorth', 'assets', 'liabilities']
+  required: ['income', 'expense', 'netSavings']
 } as const;
 
-export const $ConvertedNetWorthDto = {
+export const $ConvertedCashFlowDto = {
   type: 'object',
   properties: {
     baseCurrency: {
@@ -4124,114 +6529,78 @@ export const $ConvertedNetWorthDto = {
       description: 'Base currency for conversion',
       example: 'CNY'
     },
-    netWorth: {
+    income: {
       type: 'string',
-      description: 'Converted net worth',
-      example: '500000.00'
+      description: 'Converted income',
+      example: '25000.00'
     },
-    assets: {
+    expense: {
       type: 'string',
-      description: 'Converted assets',
-      example: '600000.00'
+      description: 'Converted expense',
+      example: '18000.00'
     },
-    liabilities: {
+    netSavings: {
       type: 'string',
-      description: 'Converted liabilities',
-      example: '100000.00'
+      description: 'Converted net savings',
+      example: '7000.00'
     },
     exchangeRates: {
       type: 'object',
       description: 'Exchange rates used for conversion',
       example: {
-        USD: '7.200000',
-        EUR: '7.800000'
+        USD: '7.200000'
       }
     }
   },
-  required: [
-    'baseCurrency',
-    'netWorth',
-    'assets',
-    'liabilities',
-    'exchangeRates'
-  ]
-} 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']
+  required: ['baseCurrency', 'income', 'expense', 'netSavings', 'exchangeRates']
 } as const;
 
-export const $NetWorthResponseDto = {
+export const $CashFlowResponseDto = {
   type: 'object',
   properties: {
-    netWorth: {
+    period: {
       type: 'string',
-      description:
-        'Total net worth (assets - liabilities, converted to base currency)',
-      example: '500000.00'
+      description: 'Period identifier (YYYY-MM)',
+      example: '2024-06'
     },
-    assets: {
+    income: {
       type: 'string',
-      description: 'Total assets value (converted)',
-      example: '600000.00'
+      description: 'Total income for the period (converted)',
+      example: '25000.00'
     },
-    liabilities: {
+    expense: {
       type: 'string',
-      description: 'Total liabilities value (positive number, converted)',
-      example: '100000.00'
+      description: 'Total expenses for the period (converted)',
+      example: '18000.00'
     },
-    monthlyReturn: {
+    netSavings: {
       type: 'string',
-      description: 'Monthly return (change from last month)',
-      example: '15000.00'
+      description: 'Net savings (income - expense, converted)',
+      example: '7000.00'
     },
-    monthlyReturnPercentage: {
+    savingsRate: {
       type: 'string',
-      description: 'Monthly return percentage',
-      example: '3.15'
+      description: 'Savings rate percentage (netSavings / income * 100)',
+      example: '28.00'
     },
     currency: {
       type: 'string',
       description: 'Base currency code',
       example: 'CNY'
     },
-    asOf: {
-      type: 'string',
-      description: 'Data as of date (ISO 8601)',
-      example: '2024-06-15T00:00:00.000Z'
-    },
     byCurrency: {
-      description: 'Balances grouped by original currency',
+      description: 'Cash flow grouped by original currency',
       allOf: [
         {
-          $ref: '#/components/schemas/NetWorthByCurrencyDto'
+          $ref: '#/components/schemas/CashFlowByCurrencyDto'
         }
       ]
     },
     converted: {
-      description:
-        'Converted values in base currency (undefined if no exchange rates available)',
+      description: 'Converted values in base currency',
       allOf: [
         {
-          $ref: '#/components/schemas/ConvertedNetWorthDto'
+          $ref: '#/components/schemas/ConvertedCashFlowDto'
         }
       ]
     },
@@ -4244,417 +6613,553 @@ export const $NetWorthResponseDto = {
     }
   },
   required: [
-    'netWorth',
-    'assets',
-    'liabilities',
-    'monthlyReturn',
-    'monthlyReturnPercentage',
-    'currency',
-    'asOf'
+    'period',
+    'income',
+    'expense',
+    'netSavings',
+    'savingsRate',
+    'currency'
   ]
 } as const;
 
-export const $AccountItemDto = {
+export const $CategoryGroupDto = {
   type: 'object',
   properties: {
-    id: {
-      type: 'string',
-      description: 'Account ID'
-    },
-    name: {
-      type: 'string',
-      description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
-    },
-    displayName: {
-      type: 'string',
-      description: 'Display name (last part of account path)',
-      example: 'Savings'
-    },
-    balance: {
+    category: {
       type: 'string',
-      description: 'Account balance',
-      example: '50000.00'
+      description:
+        'Functional category (account-path Group segment); regional and universal account paths merge under it',
+      example: 'Food'
     },
-    currency: {
-      type: 'string',
-      description: 'Currency code',
-      example: 'CNY'
-    }
-  },
-  required: ['id', 'name', 'displayName', 'balance', 'currency']
-} as const;
-
-export const $PlatformGroupDto = {
-  type: 'object',
-  properties: {
-    platformId: {
+    totalExpense: {
       type: 'string',
-      description: 'Platform ID'
+      description: 'Converted total expense in base currency',
+      example: '1200.00'
     },
-    platformName: {
-      type: 'string',
-      description: 'Platform display name',
-      example: 'CMB Bank'
+    sharePct: {
+      type: 'number',
+      description: 'Share of grand total (0-100); 0 when grand total is 0',
+      example: 42.5
     },
-    accounts: {
-      description: 'Accounts within this platform',
+    balanceByCurrency: {
+      description: 'Raw (unconverted) expense per currency',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/AccountItemDto'
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
       }
     },
-    totalBalance: {
+    convertedBalance: {
       type: 'string',
-      description: 'Total balance across all accounts in platform',
-      example: '100000.00'
+      description:
+        'Converted total in base currency (omitted when FX missing for all currencies in this category)',
+      example: '1200.00'
     }
   },
-  required: ['platformId', 'platformName', 'accounts', 'totalBalance']
+  required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
 } as const;
 
-export const $AccountsSummaryDto = {
+export const $ExpensesByCategorySummaryDto = {
   type: 'object',
   properties: {
-    totalAccounts: {
-      type: 'number',
-      description: 'Total number of accounts'
+    totalExpense: {
+      type: 'string',
+      description:
+        'Total expense across all categories (converted; convertible categories only)',
+      example: '5000.00'
     },
-    totalPlatforms: {
+    categoryCount: {
       type: 'number',
-      description: 'Total number of platforms'
+      description: 'Number of categories',
+      example: 8
     }
   },
-  required: ['totalAccounts', 'totalPlatforms']
+  required: ['totalExpense', 'categoryCount']
 } as const;
 
-export const $AccountsResponseDto = {
+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: 'Account groups by platform',
+      description:
+        'Expense groups by functional category, sorted by converted total desc',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/PlatformGroupDto'
+        $ref: '#/components/schemas/CategoryGroupDto'
       }
     },
     summary: {
       description: 'Summary statistics',
       allOf: [
         {
-          $ref: '#/components/schemas/AccountsSummaryDto'
+          $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
         }
       ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
     }
   },
-  required: ['groups', 'summary']
+  required: ['period', 'baseCurrency', 'groups', 'summary']
 } as const;
 
-export const $AccountItemWithAssetClassDto = {
+export const $MonetaryDto = {
   type: 'object',
   properties: {
-    id: {
-      type: 'string',
-      description: 'Account ID'
-    },
-    name: {
-      type: 'string',
-      description: 'Full account name',
-      example: 'Assets:Bank:CMB:Savings'
-    },
-    displayName: {
-      type: 'string',
-      description: 'Display name (last part of account path)',
-      example: 'Savings'
-    },
-    balance: {
+    amount: {
       type: 'string',
-      description: 'Account balance',
-      example: '50000.00'
+      description: 'Amount (Decimal string)',
+      example: '3000'
     },
     currency: {
       type: 'string',
-      description: 'Currency code',
-      example: 'CNY'
+      description: 'ISO 4217 currency',
+      example: 'USD'
     },
-    assetClass: {
+    baseCcyEquivalent: {
+      type: 'object',
+      description: 'Converted to user base currency (Decimal string)',
+      example: '21600',
+      nullable: true
+    }
+  },
+  required: ['amount', 'currency']
+} as const;
+
+export const $CurrentPriceDto = {
+  type: 'object',
+  properties: {
+    amount: {
       type: 'string',
-      description: 'Asset class',
-      example: 'LIQUIDITY'
+      description: 'Price amount (Decimal string)',
+      example: '250'
     },
-    assetSubClass: {
+    currency: {
       type: 'string',
-      description: 'Asset sub-class (Prisma-compatible)',
-      example: 'RETIREMENT_ACCOUNT'
+      description: 'Price currency (ISO 4217)',
+      example: 'USD'
     },
-    regionalSubClass: {
+    date: {
       type: 'string',
-      description: 'Regional sub-class (region-specific, for display)',
-      example: 'FOUR_ZERO_ONE_K'
+      description: 'Price date (ISO 8601)',
+      example: '2024-06-01'
     },
-    riskLevel: {
+    source: {
       type: 'string',
-      description: 'Risk level',
-      example: 'LOW'
+      description: 'Price source',
+      example: 'USER_OVERRIDE',
+      enum: ['USER_OVERRIDE', 'OPENBB_EQUITY', 'OPENBB_CURRENCY']
     }
   },
-  required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
+  required: ['amount', 'currency', 'date', 'source']
 } as const;
 
-export const $AssetClassGroupDto = {
+export const $FxRateDto = {
   type: 'object',
   properties: {
-    assetClass: {
+    from: {
       type: 'string',
-      description: 'Asset class name',
-      example: 'LIQUIDITY',
-      enum: [
-        'LIQUIDITY',
-        'EQUITY',
-        'FIXED_INCOME',
-        'PRECIOUS_METALS',
-        'COMMODITY',
-        'INSURANCE',
-        'ALTERNATIVE_INVESTMENT',
-        'PERSONAL_ASSETS',
-        'LIABILITY',
-        'REAL_ESTATE',
-        'INDEX'
-      ]
+      example: 'USD'
     },
-    assetSubClass: {
+    to: {
       type: 'string',
-      description: 'Asset sub-class name',
-      example: 'DEPOSIT'
-    },
-    accounts: {
-      description: 'Accounts within this asset class',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/AccountItemWithAssetClassDto'
-      }
+      example: 'CNY'
     },
-    balanceByCurrency: {
-      description: 'Balances grouped by currency',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
-      }
+    rate: {
+      type: 'string',
+      description: 'FX rate (Decimal string)',
+      example: '7.2'
     },
-    convertedBalance: {
+    date: {
       type: 'string',
-      description: 'Converted balance in base currency',
-      example: '100000.00'
+      description: 'Rate date (ISO 8601)',
+      example: '2024-01-15'
     }
   },
-  required: ['assetClass', 'accounts', 'balanceByCurrency']
+  required: ['from', 'to', 'rate', 'date']
 } as const;
 
-export const $AccountExchangeRateWarningDto = {
+export const $HoldingPnlRowDto = {
   type: 'object',
   properties: {
-    type: {
+    accountId: {
       type: 'string',
-      description: 'Warning type',
-      example: 'MISSING_EXCHANGE_RATE'
+      description: 'Account UUID',
+      example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
     },
-    currency: {
+    accountPath: {
       type: 'string',
-      description: 'Currency without exchange rate',
+      description: 'Full account path',
+      example: 'Assets:US:Broker:AAPL'
+    },
+    accountCcy: {
+      type: 'object',
+      description: 'Account settlement currency (ISO 4217), from cost currency',
+      nullable: true,
       example: 'USD'
     },
-    accounts: {
-      description: 'Affected account paths',
-      type: 'array',
-      items: {
-        type: 'string'
-      }
+    brokerType: {
+      type: 'object',
+      description: 'Broker type derived from Platform.type',
+      nullable: true,
+      example: 'broker'
     },
-    totalAmount: {
+    symbol: {
       type: 'string',
-      description: 'Total amount in this currency',
-      example: '5000.00'
-    }
-  },
-  required: ['type', 'currency', 'accounts', 'totalAmount']
-} as const;
-
-export const $AssetClassSummaryDto = {
-  type: 'object',
-  properties: {
-    totalAccounts: {
-      type: 'number',
-      description: 'Total number of accounts'
+      description: 'Commodity symbol',
+      example: 'AAPL'
     },
-    totalAssetClasses: {
-      type: 'number',
-      description: 'Total number of asset classes'
+    chartToken: {
+      type: 'string',
+      description: 'Chart segment token (libs/common resolver)',
+      example: 'equity',
+      enum: ['equity', 'fund', 'bond', 'cash', 'other']
     },
-    baseCurrency: {
+    assetClass: {
       type: 'string',
-      description: 'Base currency for conversion',
-      example: 'CNY'
+      example: 'EQUITY'
     },
-    warnings: {
-      description: 'Exchange rate warnings',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/AccountExchangeRateWarningDto'
-      }
+    assetSubClass: {
+      type: 'object',
+      nullable: true,
+      example: 'STOCK'
+    },
+    units: {
+      type: 'string',
+      description: 'Net held units (Decimal string)',
+      example: '12'
+    },
+    averageCostPerUnit: {
+      description:
+        'Average cost per unit; null when cost currency conflicts or no cost',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    costBasis: {
+      description: 'Cost basis of held units',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    marketValue: {
+      description: 'Market value at asOf price',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    currentPrice: {
+      description: 'Price used for market value',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/CurrentPriceDto'
+        }
+      ]
+    },
+    unrealizedPnlBase: {
+      type: 'object',
+      description:
+        'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
+      nullable: true,
+      example: '6000'
+    },
+    unrealizedPnlPct: {
+      type: 'object',
+      description: 'Unrealized P&L % (Decimal string)',
+      nullable: true,
+      example: '25'
+    },
+    costFxRate: {
+      description: 'Historical FX rate applied to cost basis',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/FxRateDto'
+        }
+      ]
+    },
+    marketFxRate: {
+      description: 'FX rate applied to market value',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/FxRateDto'
+        }
+      ]
+    },
+    pctOfInvestedAssets: {
+      type: 'object',
+      description:
+        'Share of invested assets % (Decimal string); only for invested chartTokens',
+      nullable: true,
+      example: '40'
+    },
+    realizedPnl: {
+      description:
+        'Cumulative realized P&L on sold lots (asOf-date cutoff); null when the method has no applicable sells, a sell lacks a price, or any required FX rate is missing (never-mix). When a sell spans multiple currencies (cross-currency sale), amount and currency reflect the base currency; baseCcyEquivalent is always the authoritative dual-FX figure',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
     }
   },
-  required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
+  required: [
+    'accountId',
+    'accountPath',
+    'symbol',
+    'chartToken',
+    'assetClass',
+    'units'
+  ]
 } as const;
 
-export const $AssetClassAccountsResponseDto = {
+export const $HoldingPnlWarningDto = {
   type: 'object',
-  properties: {
-    groups: {
-      description: 'Account groups by asset class',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/AssetClassGroupDto'
-      }
-    },
-    summary: {
-      description: 'Summary statistics',
-      allOf: [
-        {
-          $ref: '#/components/schemas/AssetClassSummaryDto'
-        }
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_COST_FX_RATE',
+      enum: [
+        'MISSING_COST_FX_RATE',
+        'MISSING_MARKET_FX_RATE',
+        'MISSING_SALE_PRICE',
+        'MISSING_REALIZED_FX_RATE',
+        'OVERSOLD_LOTS',
+        'NO_PRICE',
+        'MIXED_COST_CURRENCY'
       ]
+    },
+    symbol: {
+      type: 'object',
+      nullable: true
+    },
+    accountId: {
+      type: 'object',
+      nullable: true
+    },
+    currency: {
+      type: 'object',
+      nullable: true
     }
   },
-  required: ['groups', 'summary']
+  required: ['type']
 } as const;
 
-export const $CashFlowByCurrencyDto = {
+export const $HoldingPnlResponseDto = {
   type: 'object',
   properties: {
-    income: {
-      description: 'Income by currency',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
-      }
+    asOfDate: {
+      type: 'string',
+      example: '2026-07-08'
     },
-    expense: {
-      description: 'Expense by currency',
+    baseCurrency: {
+      type: 'string',
+      example: 'CNY'
+    },
+    method: {
+      type: 'string',
+      description:
+        'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
+      enum: ['average', 'FIFO'],
+      example: 'average'
+    },
+    rows: {
       type: 'array',
       items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
+        $ref: '#/components/schemas/HoldingPnlRowDto'
       }
     },
-    netSavings: {
-      description: 'Net savings by currency',
+    warnings: {
       type: 'array',
       items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
+        $ref: '#/components/schemas/HoldingPnlWarningDto'
       }
     }
   },
-  required: ['income', 'expense', 'netSavings']
+  required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
 } as const;
 
-export const $ConvertedCashFlowDto = {
+export const $CreateBeanPriceDto = {
   type: 'object',
   properties: {
-    baseCurrency: {
+    currency: {
       type: 'string',
-      description: 'Base currency for conversion',
-      example: 'CNY'
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'USD'
     },
-    income: {
+    quoteCurrency: {
       type: 'string',
-      description: 'Converted income',
-      example: '25000.00'
+      description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
+      example: 'CNY'
     },
-    expense: {
-      type: 'string',
-      description: 'Converted expense',
-      example: '18000.00'
+    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
     },
-    netSavings: {
+    date: {
       type: 'string',
-      description: 'Converted net savings',
-      example: '7000.00'
+      description: 'Price date (ISO 8601 format)',
+      example: '2024-11-05'
     },
-    exchangeRates: {
+    metadata: {
       type: 'object',
-      description: 'Exchange rates used for conversion',
+      description:
+        'Metadata (validated by Zod schema, max field lengths enforced)',
       example: {
-        USD: '7.200000'
+        source: 'MANUAL',
+        note: 'Bank valuation report',
+        confidence: 0.95
       }
     }
   },
-  required: ['baseCurrency', 'income', 'expense', 'netSavings', 'exchangeRates']
+  required: ['currency', 'quoteCurrency', 'amount', 'date']
 } as const;
 
-export const $CashFlowResponseDto = {
+export const $PriceResponseDto = {
   type: 'object',
   properties: {
-    period: {
+    id: {
       type: 'string',
-      description: 'Period identifier (YYYY-MM)',
-      example: '2024-06'
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
     },
-    income: {
+    userId: {
       type: 'string',
-      description: 'Total income for the period (converted)',
-      example: '25000.00'
+      description: 'User ID (owner of the price)',
+      example: 'user-123'
     },
-    expense: {
+    currency: {
       type: 'string',
-      description: 'Total expenses for the period (converted)',
-      example: '18000.00'
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'BTC'
     },
-    netSavings: {
+    quoteCurrency: {
       type: 'string',
-      description: 'Net savings (income - expense, converted)',
-      example: '7000.00'
+      description: 'Quote currency (pricing currency, e.g., USD, CNY)',
+      example: 'USD'
     },
-    savingsRate: {
-      type: 'string',
-      description: 'Savings rate percentage (netSavings / income * 100)',
-      example: '28.00'
+    amount: {
+      type: 'number',
+      description:
+        'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
+      example: 50000
     },
-    currency: {
+    date: {
       type: 'string',
-      description: 'Base currency code',
-      example: 'CNY'
+      description:
+        'Price date (ISO 8601 format). Represents the date this price was valid.',
+      example: '2024-01-01',
+      format: 'date'
     },
-    byCurrency: {
-      description: 'Cash flow grouped by original currency',
-      allOf: [
-        {
-          $ref: '#/components/schemas/CashFlowByCurrencyDto'
-        }
-      ]
+    meta: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
+      example: {
+        source: 'MANUAL',
+        note: 'User-defined price',
+        confidence: 1
+      }
     },
-    converted: {
-      description: 'Converted values in base currency',
-      allOf: [
-        {
-          $ref: '#/components/schemas/ConvertedCashFlowDto'
-        }
-      ]
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-11-03T10:00:00Z'
     },
-    warnings: {
-      description: 'Exchange rate warnings',
+    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/ExchangeRateWarningDto'
+        $ref: '#/components/schemas/PriceResponseDto'
       }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of prices',
+      example: 42
     }
   },
-  required: [
-    'period',
-    'income',
-    'expense',
-    'netSavings',
-    'savingsRate',
-    'currency'
-  ]
+  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 = {
@@ -4801,6 +7306,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: {}