@fuzzle/opencode-accountant 0.4.6 → 0.5.0

package/docs/tools/classify-statements.md

@@ -18,6 +18,8 @@ This tool is **restricted to the accountant agent only**.
 - `{paths.pending}` = `import/pending`
 - `{paths.unrecognized}` = `import/unrecognized`
 
+**Note on Context IDs:** Each classified file receives a unique `contextId` (UUID). This ID references an import context file stored in `.memory/{uuid}.json` that tracks the file's metadata and progress through the import pipeline. The context is used by subsequent tools (`import-statements`, `reconcile-statement`) to locate files and retrieve metadata. See [Import Context Architecture](../architecture/import-context.md) for details.
+
 ### Success - All Files Classified
 
 When all CSV files are successfully classified:
@@ -30,13 +32,15 @@ When all CSV files are successfully classified:
       "filename": "transactions-ubs-2026-02.csv",
       "provider": "ubs",
       "currency": "chf",
-      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-2026-02.csv"
+      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-2026-02.csv",
+      "contextId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     },
     {
       "filename": "account-statement_2026-02.csv",
       "provider": "revolut",
       "currency": "eur",
-      "targetPath": "{paths.pending}/revolut/eur/account-statement_2026-02.csv"
+      "targetPath": "{paths.pending}/revolut/eur/account-statement_2026-02.csv",
+      "contextId": "8b3e9c21-1a4f-4d89-b123-9f8e7d6c5b4a"
     }
   ],
   "unrecognized": [],
@@ -61,7 +65,8 @@ When provider config includes `renamePattern` with metadata extraction:
       "originalFilename": "export.csv",
       "provider": "ubs",
       "currency": "chf",
-      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-0235-90250546.csv"
+      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-0235-90250546.csv",
+      "contextId": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
     }
   ],
   "unrecognized": [],
@@ -87,7 +92,8 @@ When some files cannot be classified:
       "filename": "transactions-ubs-2026-02.csv",
       "provider": "ubs",
       "currency": "chf",
-      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-2026-02.csv"
+      "targetPath": "{paths.pending}/ubs/chf/transactions-ubs-2026-02.csv",
+      "contextId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     }
   ],
   "unrecognized": [
@@ -207,13 +213,74 @@ ubs:
 
 This extracts metadata from the CSV (e.g., account number from row 0, column 1) and uses it in the output filename.
 
+## Import Context
+
+Each classified file gets an **import context** - a JSON file stored in `.memory/{contextId}.json` that tracks the file's metadata and progress through the import pipeline.
+
+### What Gets Stored in the Context
+
+When a CSV is classified, the context is created with:
+
+- **File tracking**: filename, file path, original filename (if renamed)
+- **Provider detection**: provider, currency, account number
+- **CSV metadata**: transaction date range (from-date, until-date), opening/closing balances
+- **Timestamps**: creation and last update times
+
+### Example Context File
+
+`.memory/f47ac10b-58cc-4372-a567-0e02b2c3d479.json`:
+
+```json
+{
+  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "createdAt": "2026-02-28T10:30:00.000Z",
+  "updatedAt": "2026-02-28T10:30:00.000Z",
+
+  "filename": "ubs-0235-90250546.1-transactions-2026-02-22-to-2026-02-24.csv",
+  "filePath": "import/pending/ubs/chf/ubs-0235-90250546.1-transactions-2026-02-22-to-2026-02-24.csv",
+  "originalFilename": "transactions-0235-90250546.1-2026-02.csv",
+
+  "provider": "ubs",
+  "currency": "chf",
+  "accountNumber": "0235-90250546.1",
+
+  "fromDate": "2026-02-22",
+  "untilDate": "2026-02-24",
+  "openingBalance": "4001.55",
+  "closingBalance": "9001.55"
+}
+```
+
+### Context Lifecycle
+
+1. **Created by classify-statements**: Initial context with provider/currency/metadata
+2. **Updated by import-statements**: Adds rules file, year journal, transaction count
+3. **Updated by reconcile-statement**: Adds reconciliation results
+4. **Persisted**: Remains in `.memory/` for audit/debugging
+
+### Why Context IDs Matter
+
+Context IDs solve the **multi-account problem**: when you have multiple accounts from the same provider/currency (e.g., UBS checking `.0` and savings `.1`), the context ID ensures each file is tracked independently and reconciled against the correct account.
+
+**Without contexts**: Tools would select CSVs by timestamp → wrong account reconciled ❌
+
+**With contexts**: Each CSV has an `accountNumber` in its context → correct account reconciled ✓
+
+See [Import Context Architecture](../architecture/import-context.md) for complete technical details.
+
 ## Directory Structure
 
 ```
 your-project/
+├── .memory/                        # Import context files (created by classify-statements)
+│   ├── f47ac10b-58cc-4372-a567-0e02b2c3d479.json  # Context for UBS checking
+│   ├── 8b3e9c21-1a4f-4d89-b123-9f8e7d6c5b4a.json  # Context for UBS savings
+│   └── a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6.json  # Context for Revolut EUR
+│
 ├── config/
 │   └── import/
 │       └── providers.yaml          # Defines all paths and detection rules
+│
 ├── {paths.import}/                 # Drop CSV files here (default: import/incoming)
 │   ├── bank1.csv
 │   └── bank2.csv
@@ -224,7 +291,8 @@ your-project/
 │   │       └── classified.csv
 │   ├── ubs/
 │   │   └── chf/
-│   │       └── transactions-ubs-0235-90250546.csv
+│   │       ├── ubs-0235-90250546.0-transactions-2026-02.csv  # Checking
+│   │       └── ubs-0235-90250546.1-transactions-2026-02.csv  # Savings
 │   └── revolut/
 │       └── eur/
 │           └── account-statement_2026-02.csv
@@ -233,6 +301,13 @@ your-project/
     └── mystery-bank.csv
 ```
 
+**Note on `.memory/` directory:**
+
+- Contains import context JSON files (one per classified CSV)
+- Each context tracks metadata and progress through the pipeline
+- Files persist for audit/debugging (not auto-deleted)
+- Directory is gitignored (contexts are local/temporary)
+
 ## Typical Workflow
 
 ### Scenario 1: Successful Classification
@@ -240,8 +315,10 @@ your-project/
 1. Drop CSV files into `{paths.import}/` (e.g., `import/incoming/`)
 2. Run `classify-statements` tool (no arguments)
 3. Check output - all files classified successfully
-4. Files organized in `{paths.pending}/<provider>/<currency>/`
-5. Proceed to `import-statements` tool
+4. **Each file gets a unique contextId** stored in `.memory/{uuid}.json`
+5. Files organized in `{paths.pending}/<provider>/<currency>/`
+6. **Context IDs are passed automatically to subsequent steps** when using `import-pipeline`
+7. Proceed to `import-statements` or `import-pipeline` tool
 
 ### Scenario 2: Handling Unrecognized Files