plasalid 0.3.5 → 0.5.0

package/README.md

@@ -1,59 +1,47 @@
 <h1 align="center">Plasalid</h1>
 
 <p align="center">
-  <strong>Talk to your money</strong>
+  <strong>The Harness for Personal Finance</strong>
 </p>
 
 <p align="center">
-  A local-first AI that reads every line of your transactions and coaches you the best move.
+  Turn the financial documents you already receive into a structured, AI-readable context.
 </p>
 
 
 <br />
 
-Plasalid lets you actually *talk* to your money. Drop your bank and credit-card statement PDFs into a folder. Plasalid scans every transaction, every balance, every late fee into a double-entry database on your own machine. Then you chat with it — an AI that's read every line and tells you, sharply and proactively, what's going on. Local, private, yours.
-
-Plasalid exists because in markets like Thailand there's no Plaid. In the US, a single API gives apps a live view of every balance and transaction across all your accounts — one complete picture of your money. In Thailand, knowing where you stand means logging into five different bank apps in sequence one by one. Most people just don't bother. And most people can't afford a financial advisor to do it for them either. The result is people fly blind with their own money — and grow careless with it. Bills slip past, small leaks compound, and the first real look tends to come after something has already gone wrong.
-
-In addition, personal finance isn't taught well in Thai schools. Fee-based advisors are out of reach for most households. The loudest "advice" channels are bank salespeople pitching their employer's products. The result: over **5 million Thais** are already flagged as non-performing borrowers, and a generation that wants to manage money better has nowhere accessible to learn how. Plasalid's bet is that capable AI changes that. The same intelligence that reads your statements can explain what the numbers mean. It flags what's about to go wrong. It coaches you through real decisions — debt, budget, savings.
-
-And when survival isn't the question anymore, the same Plasalid can scales up with you. Saving for a trip. Building an emergency fund. Choosing investments. Planning a down payment or retirement. Working toward the freedom to walk away from a bad job. From getting out of debt to financial freedom, Plasalid grows with you.
+In markets like Thailand there's no Plaid: no public API that gives apps a unified view of every account, no easy way to assemble a complete picture of your money. Knowing where you stand means logging into five bank apps one by one — and most people just don't bother. Plasalid goes further than a local Plaid — it's a harness layer: drop your bank and credit-card statement PDFs into a folder and Plasalid parses every transaction, balance into a double-entry database on your own machine, ready for any AI to plug into. No cloud aggregator. No upstream account to trust. One source of truth for every account.
 
 ## Features
 
-### Your personal money coach
-
-- **Sees every balance, every transaction** — Plasalid's chat reads from your bank and credit-card statements, not generic categories. "Where did ฿14k go in March?" gets a specific answer.
-- **Sharp and proactive** — Leads with the insight, not the breakdown. Flags concerning patterns (overdraft trajectory, unusual spending, payments due soon) even if you didn't ask.
-- **Has a point of view** — When you ask "what should I do?", you get a recommendation, not a list of options.
-- **Remembers what matters** — Persists biographical context (family, employer, goals) and per-statement scanning hints across sessions, so each conversation starts smarter than the last.
+Plasalid is a chain of three stages: **Scan → Review → Chat.** Underneath sits a three-layer ledger: hierarchical accounts (small, stable, colon-path ids like `expense:food:groceries`), deduplicated merchants (raw statement descriptors collapse to one canonical name with a learned default category), and balanced transactions with postings. Today's chat is one consumer; the same data will power a local MCP / API server next.
 
-### A data harness AI can plug into
+### Scan — parse without blocking
 
-- **The missing aggregator** — In markets without Plaid, there's no bank API that easy to access. Plasalid turns the documents you already receive into a database that machine can read, so the data layer stops being the blocker.
-- **Composable substrate** — Plasalid's local SQLite is plain, queryable double-entry data. Any tool that can read SQLite — Claude Code, MCP servers, your own scripts, dashboards — can build automations, alerts, exporters, or personalized analyses on top, with no further integration work.
-- **No vendor lock, no rate limits** — Standard accounts and journal lines, your encryption key, your machine. Nothing to revoke, throttle, or paywall.
-- **BYO model** — Pick Anthropic (Claude) or any OpenAI-compatible server (Ollama, OpenAI, LM Studio, vLLM, …) at setup time. Local models keep the conversation 100% on your machine.
+- **Drop PDFs in, get balanced transactions out.** The scanner infers account type, masks account numbers, converts Buddhist-Era dates, and posts a double-entry record for every transaction.
+- **Merchants as first-class.** Statement descriptors (`STARBUCKS #1234 BKK`, `Starbucks #5678 BANGKOK`) normalize to one canonical merchant. Categorize a merchant once; future statements use the cached default category — the LLM skips re-categorizing known merchants.
+- **Never pauses to ask you.** Ambiguous rows post best-guess transactions with a structured *concern* attached; lines the scanner can't confidently categorize land in `expense:uncategorized` for the review cleanup pass; unparseable rows are skipped, not guessed. A missing row is better than a wrong row — review clears them up later.
+- **Encrypted PDFs handled inline.** Statement password-protected? Plasalid prompts you once, remembers the password (AES-GCM at rest) under a filename pattern, and unlocks next month's statement silently.
 
-### Drop documents in, get structured data out
+### Review — see the whole picture
 
-- **Encrypted PDFs handled inline** — Statement password-protected? Plasalid prompts you once, then remembers the password (encrypted at rest) under a filename pattern so the next month's statement unlocks silently.
-- **Asks instead of guessing** — Ambiguous row? The scanner pauses and prompts you.
-- **Idempotent scan** — Files are hashed; re-running `plasalid scan` skips what it already scanned. `--force` cascade-deletes prior records before re-scanning.
-- **Learns your statements** — Per-bank scanning hints persist across runs (the AI saves them in a local memory table) so each new statement scans more accurately than the last.
+- **Uncategorized cleanup.** Every posting parked in `expense:uncategorized` shows up here; categorizing one teaches the merchant's default account for next time, so a single answer can resolve dozens of rows across future months.
+- **Connects related transactions.** A transfer that lands on both a bank statement and a credit-card statement is surfaced as one pair; merge on confirmation.
+- **Recurrences as first-class data.** Spotify, salary, rent get their own `recurrences` rows with cadence (weekly / biweekly / monthly / annually) and next-expected dates, linked back to every member transaction. Not a UI category — a structured fact any AI consumer can read.
+- **Step-by-step clarification.** Re-poses every scan-noted concern as one focused question; loops until concerns are clear or you skip them. `--dry-run` previews everything; writes only after you confirm.
 
-### Correctness, not vibes
+### Chat — ask questions about your data
 
-- **Double-entry bookkeeping** — Every transaction balances enforced by standard double-entry accounting.
-- **Account metadata preserved** — Bank, masked number, statement day, due day, points.
-- **Dates normalized** — ISO Gregorian; Localization dates converted automatically.
-- **Reconcile pass** — `plasalid reconcile` surfaces duplicate entries, similar accounts, and unused accounts; merges, renames, and deletes happen only after explicit confirmation. `--dry-run` previews without writing.
+- **Reads your real transactions and postings.** Not generic categories. "Where did ฿14k go in March?" gets an answer drawn from actual postings against real expense categories, with figures, dates, account names, and merchants cited; nothing invented.
+- **One of many possible consumers.** A local MCP / API server is coming next so external AI tools (Claude Desktop, your own scripts, dashboards) read the same data without sync, login, or upload.
 
-### Your data never leaves your machine
+### Built to be plugged into
 
-- **Encrypted local database** — All data stays on your machine in an AES-256 encrypted SQLite database.
-- **PII masking** — Names, national IDs, phones, full account/card numbers scrubbed before anything reaches the AI.
-- **No telemetry. No analytics.** Only outbound traffic is to your configured AI provider.
+- **Local-first.** AES-256 encrypted SQLite on your machine. No cloud sync, no third-party aggregator, no upstream account to trust.
+- **Standard double-entry.** No proprietary schema; any tool that speaks SQL can plug in. No vendor lock, no rate limits, no paywall.
+- **PII redacted on the way out.** Names, national IDs, phone numbers, and full account/card numbers are scrubbed before any prompt leaves your machine.
+- **BYO model.** Pick Anthropic (Claude) or any OpenAI-compatible server (Ollama, OpenAI, LM Studio, vLLM, …) at setup. Local models keep everything 100% on your machine.
 
 
 ## Install
@@ -73,15 +61,16 @@ plasalid setup
 Then:
 
 1. Run `plasalid open` to pop open your data folder in Finder/Explorer, then drag in any bank or credit-card statement PDF you've got. **One file is enough to start** — Plasalid will already give you useful answers about that account. More files make the picture richer.
-2. Run `plasalid scan` and answer any clarifying questions inline.
-3. Run `plasalid` to chat with what was scanned.
+2. Run `plasalid scan` — it parses your PDFs end-to-end without stopping.
+3. Run `plasalid review` to connect related transactions, learn your recurring rhythms, and clear up anything the scanner flagged as a concern.
+4. Run `plasalid` to chat with what was scanned.
 
 Other day-to-day commands:
 
 - `plasalid scan <regex>` — only scan files whose path matches the regex.
 - `plasalid scan <regex> --force` — re-scan matching files (replaces prior records).
-- `plasalid reconcile --dry-run` — periodically surface duplicate entries and similar accounts; re-run without `--dry-run` to apply fixes interactively.
-- `plasalid revert <regex>` — delete scanned files matching the regex and every journal entry derived from them.
+- `plasalid review --dry-run` — preview the picture (correlated transactions, recurrences, open concerns) without writing; re-run without `--dry-run` to step through fixes interactively.
+- `plasalid revert <regex>` — delete scanned files matching the regex and every transaction derived from them.
 
 ## Commands
 
@@ -93,10 +82,11 @@ plasalid setup                      # Configure API key, encryption, and data di
 plasalid data                       # Open the Plasalid data folder in your OS file explorer
 plasalid accounts                   # Show the chart of accounts with balances
 plasalid status                     # Net worth and this-month income/expense totals
-plasalid transactions               # List journal lines (filter by --account, --from, --to, --query, --limit)
+plasalid transactions               # List transactions and their postings (filter by --account, --from, --to, --query, --limit)
+plasalid record <utterance>         # Add a manual transaction, account, balance, or merchant from a plain-language line
 plasalid scan [regex] [--force]     # Scan new PDFs; --force cascade-deletes prior records before re-scanning
-plasalid revert <regex>             # Delete scanned files matching <regex> and their journal entries
-plasalid reconcile [--dry-run]      # Review the journal: duplicates, similar accounts, unused accounts (--account, --from, --to also accepted)
+plasalid revert <regex>             # Delete scanned files matching <regex> and their transactions
+plasalid review [--dry-run]         # Connect related transactions, learn recurring rhythms, resolve open concerns (--account, --from, --to also accepted)
 ```
 
 ## How It Works
@@ -115,7 +105,7 @@ plasalid reconcile [--dry-run]      # Review the journal: duplicates, similar ac
        Claude API (PII-redacted)
                   │
        ┌──────────▼──────────┐
-       │     Encrypted DB    │◀──── plasalid reconcile
+       │     Encrypted DB    │◀──── plasalid review
        └──────────┬──────────┘       
                   │                   
         plasalid · chat               
@@ -144,7 +134,7 @@ Plasalid stores everything in `~/.plasalid/`:
   data/                # Drop any PDFs here (subfolders allowed; AI classifies)
 ```
 
-`db.sqlite` holds the journal, chart of accounts, scan history, persisted long-term memories, and AES-GCM-encrypted PDF passwords keyed by filename pattern. Everything is wrapped in libsql's AES-256 page encryption.
+`db.sqlite` holds the three-layer ledger (hierarchical accounts, deduplicated merchants with learned default categories, transactions and postings), scan history, open concerns awaiting review, recurring transactions (Spotify, salary, rent — recognized during review and linked from each member transaction), an action log for record-mode audit, persisted long-term memories, and AES-GCM-encrypted PDF passwords keyed by filename pattern. Everything is wrapped in libsql's AES-256 page encryption.
 
 ### Environment Variables
 

package/dist/accounts/taxonomy.d.ts

@@ -24,7 +24,7 @@ export declare const SUGGESTED_LIABILITY_SUBTYPES: string[];
 export declare const SUGGESTED_EXPENSE_SUBTYPES: string[];
 export declare const SUGGESTED_INCOME_SUBTYPES: string[];
 /**
- * Stringified Thai taxonomy block for the scan/reconcile system prompts.
+ * Stringified Thai taxonomy block for the scan/review system prompts.
  * Lists known Thai institutions and suggested subtypes so the model picks
  * consistent `bank_name` and `subtype` values across statements.
  */

package/dist/accounts/taxonomy.js

@@ -122,7 +122,7 @@ export const ACCOUNT_TYPE_DESCRIPTIONS = {
     liability: "Credit cards, loans, mortgages, money the user owes.",
     income: "Salary, side income, dividends, refunds.",
     expense: "Spending categories (food, transport, utilities, etc.).",
-    equity: "Owner's equity / opening balance equity (for reconciliation).",
+    equity: "Owner's equity / opening balance equity (for review adjustments).",
 };
 export const SUGGESTED_ASSET_SUBTYPES = [
     "bank",
@@ -169,7 +169,7 @@ export const SUGGESTED_INCOME_SUBTYPES = [
     "other",
 ];
 /**
- * Stringified Thai taxonomy block for the scan/reconcile system prompts.
+ * Stringified Thai taxonomy block for the scan/review system prompts.
  * Lists known Thai institutions and suggested subtypes so the model picks
  * consistent `bank_name` and `subtype` values across statements.
  */

package/dist/ai/agent.d.ts

@@ -1,5 +1,5 @@
 import type Database from "libsql";
-import { type ScanPromptOptions, type ReconcilePromptOptions } from "./system-prompt.js";
+import { type ScanPromptOptions, type ReviewPromptOptions, type RecordPromptOptions } from "./system-prompt.js";
 import { type AgentExecutionContext } from "./tools/index.js";
 import type { NormalizedMessage } from "./provider.js";
 export type ProgressCallback = (event: {
@@ -30,13 +30,27 @@ export declare function runScanAgent(opts: {
     signal?: AbortSignal;
 }): Promise<string>;
 /**
- * Reconcile-time agent loop. Walks the existing journal with the reconcile
- * tool profile (read tools + write/merge/delete primitives).
+ * Record-time agent loop. Takes one natural-language utterance and walks the
+ * record tool profile (read tools + account/entry writers + adjust_balance +
+ * clarify). Single-shot — does not persist conversation history.
  */
-export declare function runReconcileAgent(opts: {
+export declare function runRecordAgent(opts: {
     db: Database.Database;
     initialMessages: NormalizedMessage[];
-    prompt: ReconcilePromptOptions;
+    prompt: RecordPromptOptions;
+    agentCtx: AgentExecutionContext;
+    onProgress?: ProgressCallback;
+    signal?: AbortSignal;
+}): Promise<string>;
+/**
+ * Review-time agent loop. Surveys the existing transactions with the review
+ * tool profile (read tools + write/merge/delete primitives + recurrence
+ * detection/recording).
+ */
+export declare function runReviewAgent(opts: {
+    db: Database.Database;
+    initialMessages: NormalizedMessage[];
+    prompt: ReviewPromptOptions;
     agentCtx: AgentExecutionContext;
     onProgress?: ProgressCallback;
     signal?: AbortSignal;

package/dist/ai/agent.js

@@ -1,5 +1,5 @@
 import { config } from "../config.js";
-import { buildChatSystemPrompt, buildScanSystemPrompt, buildReconcileSystemPrompt, } from "./system-prompt.js";
+import { buildChatSystemPrompt, buildScanSystemPrompt, buildReviewSystemPrompt, buildRecordSystemPrompt, } from "./system-prompt.js";
 import { getToolDefinitions, executeTool } from "./tools/index.js";
 import { getConversationHistory, saveMessage } from "./memory.js";
 import { redact, unredact } from "./redactor.js";
@@ -136,15 +136,35 @@ export async function runScanAgent(opts) {
     return text;
 }
 /**
- * Reconcile-time agent loop. Walks the existing journal with the reconcile
- * tool profile (read tools + write/merge/delete primitives).
+ * Record-time agent loop. Takes one natural-language utterance and walks the
+ * record tool profile (read tools + account/entry writers + adjust_balance +
+ * clarify). Single-shot — does not persist conversation history.
  */
-export async function runReconcileAgent(opts) {
-    const systemPrompt = redact(buildReconcileSystemPrompt(opts.db, opts.prompt));
+export async function runRecordAgent(opts) {
+    const systemPrompt = redact(buildRecordSystemPrompt(opts.db, opts.prompt));
     const { text } = await runAgent({
         db: opts.db,
         systemPrompt,
-        tools: getToolDefinitions("reconcile"),
+        tools: getToolDefinitions("record"),
+        initialMessages: opts.initialMessages,
+        agentCtx: opts.agentCtx,
+        onProgress: opts.onProgress,
+        signal: opts.signal,
+        maxToolSteps: 30,
+    });
+    return text;
+}
+/**
+ * Review-time agent loop. Surveys the existing transactions with the review
+ * tool profile (read tools + write/merge/delete primitives + recurrence
+ * detection/recording).
+ */
+export async function runReviewAgent(opts) {
+    const systemPrompt = redact(buildReviewSystemPrompt(opts.db, opts.prompt));
+    const { text } = await runAgent({
+        db: opts.db,
+        systemPrompt,
+        tools: getToolDefinitions("review"),
         initialMessages: opts.initialMessages,
         agentCtx: opts.agentCtx,
         onProgress: opts.onProgress,

package/dist/ai/memory.d.ts

@@ -1,14 +1,23 @@
 import type Database from "libsql";
-export declare function getConversationHistory(db: Database.Database, limit?: number): {
+export interface ConversationMessage {
     role: string;
     content: string;
     created_at: string;
-}[];
-export declare function saveMessage(db: Database.Database, role: "user" | "assistant", content: string): void;
-export declare function getMemories(db: Database.Database): {
+}
+export interface Memory {
     id: number;
     content: string;
     category: string;
     created_at: string;
-}[];
+}
+/** Conversation history */
+export declare function getConversationHistory(db: Database.Database, limit?: number): ConversationMessage[];
+export declare function saveMessage(db: Database.Database, role: "user" | "assistant", content: string): void;
+/** Memories */
+export declare function getMemories(db: Database.Database): Memory[];
+/**
+ * Idempotent on (category, content): a verbatim repeat is a no-op. Semantic
+ * dedup (different wording for the same rule) is the agent's job — the persona
+ * tells it not to save what's already in the loaded memories.
+ */
 export declare function saveMemory(db: Database.Database, content: string, category?: string): void;

package/dist/ai/memory.js

@@ -1,12 +1,24 @@
+/** Conversation history */
 export function getConversationHistory(db, limit = 20) {
     return db.prepare(`SELECT role, content, created_at FROM conversation_history ORDER BY id DESC LIMIT ?`).all(limit).reverse();
 }
 export function saveMessage(db, role, content) {
     db.prepare(`INSERT INTO conversation_history (role, content) VALUES (?, ?)`).run(role, content);
 }
+/** Memories */
 export function getMemories(db) {
     return db.prepare(`SELECT id, content, category, created_at FROM memories ORDER BY created_at DESC`).all();
 }
+/**
+ * Idempotent on (category, content): a verbatim repeat is a no-op. Semantic
+ * dedup (different wording for the same rule) is the agent's job — the persona
+ * tells it not to save what's already in the loaded memories.
+ */
 export function saveMemory(db, content, category = "general") {
+    const existing = db
+        .prepare(`SELECT 1 FROM memories WHERE category = ? AND content = ? LIMIT 1`)
+        .get(category, content);
+    if (existing)
+        return;
     db.prepare(`INSERT INTO memories (content, category) VALUES (?, ?)`).run(content, category);
 }

package/dist/ai/personas.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Persona text constants for the four agent profiles. These are pure prose —
+ * no logic, no template assembly. The system-prompt builders import them and
+ * concat them with section helpers from prompt-sections.ts.
+ *
+ * Edit a persona's voice or rules here without touching the builders.
+ */
+export declare function chatPersona(name: string): string;
+export declare const SCAN_PERSONA: string;
+export declare const RECORD_PERSONA: string;
+export declare const REVIEW_PERSONA: string;

package/dist/ai/personas.js

@@ -0,0 +1,193 @@
+/**
+ * Persona text constants for the four agent profiles. These are pure prose —
+ * no logic, no template assembly. The system-prompt builders import them and
+ * concat them with section helpers from prompt-sections.ts.
+ *
+ * Edit a persona's voice or rules here without touching the builders.
+ */
+export function chatPersona(name) {
+    return `Your name is Plasalid ("ปลาสลิด") — ${name}'s local personal-finance harness. You answer ${name}'s questions about their own ledger by calling the read tools below. Local data only — no third-party aggregator, no upstream sync, no cloud.
+
+## How you answer
+- Lead with the number, not preamble. "Dining was ฿2,400 in March, up ฿900 from February." — not "Here's the breakdown."
+- Always cite real figures, dates, account names, and merchant names from tool results. Never invent data.
+- Stick to what was asked. The harness reports; recommendations are ${name}'s call. If ${name} explicitly asks "what should I do?", you can offer options drawn from the data — never proactive unsolicited advice.
+- Be concise. 2–4 sentences for simple questions. Skip "Great question!", "Let me look that up.", and similar openers.
+
+## How you work
+1. Call the read tools to look up current data — never guess balances, dates, transactions, or postings.
+2. For period comparisons, give both the percentage and the absolute difference when both fit in a sentence.
+3. For questions about ${name} themselves (name, family, employer, household), answer from the "## About ${name}" block — it's authoritative. If a fact isn't there, say so plainly; don't redirect biographical questions to \`plasalid scan\`.
+4. Default currency is THB unless an account is explicitly in another. Don't mix currencies in a single total.
+
+## Output rules
+- Reply in the dominant language of ${name}'s message.
+- Markdown sparingly: **bold** for figures, simple bullets, no code blocks.
+- No emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, arrows-as-emoji). Use plain words.
+- No tables — no markdown \`|\` tables, no ASCII grids, no pipe-delimited rows. The TUI breaks them. Use prose, dashes, or numbered lists.
+- If the data needed to answer isn't in the database, say so plainly and suggest \`plasalid scan\` when relevant.`;
+}
+export const SCAN_PERSONA = `You are Plasalid's scanner. You scan one financial document at a time (bank statement, credit-card statement, payslip, transfer slip) and post the contents to the local three-layer ledger: hierarchical accounts, deduplicated merchants, and balanced transactions with postings.
+
+Vocabulary:
+- A **transaction** is one real-world event (a purchase, a payment, a transfer).
+- A **posting** is one debit or credit on a transaction. A transaction has two or more postings and they balance (SUM debits = SUM credits per currency).
+- A **merchant** is a deduplicated counter-party. Same store under many statement descriptors collapses into one merchant row.
+
+Rules:
+1. Infer the primary account type (asset, liability, income, expense) from the document itself — header text, account type field, transaction signs, statement layout. Do not rely on the filename or directory.
+2. Every transaction must become a balanced \`record_transaction\` call. Total debits must equal total credits per currency.
+3. Account-type conventions (debit/credit semantics, unchanged from regular bookkeeping):
+   - **Asset** (e.g. bank, cash): DEBIT increases, CREDIT decreases.
+   - **Liability** (e.g. credit card, loan): CREDIT increases what is owed, DEBIT decreases it (a payment).
+   - **Income**: CREDIT increases.
+   - **Expense**: DEBIT increases.
+4. **Hierarchical accounts.** Account ids are colon-paths under one of five top-level type roots: \`asset\`, \`liability\`, \`income\`, \`expense\`, \`equity\`. Every account that is not a top-level root must declare its \`parent_id\`. Examples:
+   - \`asset:kbank-savings-1234\` → parent_id \`asset\`.
+   - \`expense:food\` → parent_id \`expense\`.
+   - \`expense:food:groceries\` → parent_id \`expense:food\`.
+   Before creating a leaf like \`expense:food:groceries\`, make sure \`expense:food\` exists; create it (parent_id=\`expense\`) if not. The top-level roots are auto-bootstrapped on first descendant create.
+5. **Merchants are first-class.** Every transaction with an external counter-party (a charge to a store, a payment to a service, a refund from a vendor) must include a \`merchant\` block on \`record_transaction\`:
+   - \`canonical_name\`: Title-cased name (e.g. \`"Starbucks"\`, \`"Amazon"\`, \`"Spotify"\`). Normalize across descriptor variations — \`"STARBUCKS #1234 BKK"\`, \`"Starbucks #5678 BANGKOK"\`, \`"SBUX TH"\` all share \`"Starbucks"\`.
+   - \`alias\`: the exact raw statement descriptor. Plasalid normalizes and dedups it.
+   - \`default_account_id\`: when categorization is confident on first sight, set this to the matching expense account (e.g. \`expense:food:dining\` for Starbucks). The next scan that sees the same merchant will skip re-asking the LLM.
+   Also set \`raw_descriptor\` on the transaction to the exact statement line for downstream review.
+   For transfers between own accounts and pure balance movements, omit the merchant block.
+6. **Pre-resolved merchants.** If the prompt context shows a merchant already known for the descriptor, use the supplied \`merchant_id\` and \`default_account_id\` on \`record_transaction\` instead of proposing a fresh merchant block. You may override the default expense account when the row's context says otherwise (e.g. a Starbucks gift-card top-up is not Dining).
+7. **Suspense fallback.** If you cannot categorize an expense with reasonable confidence, post the expense side to \`expense:uncategorized\` (auto-created on first use) and call \`note_concern\` with \`kind="uncategorized_expense"\` and the just-posted transaction_id. Do **not** invent a category. The reviewer batches these into one cleanup pass and learns the merchant's default from your fix.
+8. Dates: convert Buddhist Era → Gregorian by subtracting 543 from the year. Store as YYYY-MM-DD.
+9. Default currency is THB. Tag every posting with its ISO 4217 currency code on the \`record_transaction\` call; only deviate from THB when the row explicitly shows another currency (foreign-card purchases, FX transfers, multi-currency wallets).
+10. Account numbers: store only the last 4 digits (mask the rest with bullets, e.g. \`••1234\`). Never persist the full account number.
+11. If the document reveals an account that doesn't exist yet, call \`create_account\` once before posting transactions to it. Reuse existing accounts; don't create duplicates — call \`list_accounts\` first.
+12. Persist account metadata when the document carries it: bank name, masked number, statement day, due day, points balance.
+13. **Never pause for the user.** Your only job is to parse this document as accurately as possible.
+    - If a row is ambiguous (unclear category, unclear sign, suspicious total), still post your best-guess \`record_transaction\`, then call \`note_concern\` with the row's date, amount (฿N,NNN.NN), description, and exactly what you're unsure about. Pass the just-posted \`transaction_id\` so review can find it.
+    - If a row is *unparseable* (amount unreadable, date missing entirely, can't tell what account is involved), **skip the row entirely** — do not call \`record_transaction\` with placeholder values. Call \`note_concern\` with the raw row text and no \`transaction_id\`. A missing row is better than a wrong row.
+    - If you have a concern about an **account itself** — the statement's bank name disagrees with the stored account, the currency disagrees, the statement_day/due_day on the statement conflicts with what's stored, or you suspect the account you're about to \`create_account\` duplicates an existing one but can't be sure — call \`note_concern\` with \`account_id\` set. You can combine \`account_id\` and \`transaction_id\` if a single row triggered the doubt.
+    - The reviewer will resolve concerns later with the full picture across statements.
+    - **Apply what you've already been told.** Before flagging a concern, scan the "Rules you've already learned" section below. If a saved rule classifies the row — a merchant→category mapping, an account identity, a recurring-charge identity — apply it silently and do **not** raise a concern. Only flag a concern when the row genuinely doesn't fit any saved rule. Asking the user about something they've already told us is bad UX.
+14. When the file is fully processed, call \`mark_file_scanned\` with a short summary.
+
+Common Thai statement patterns to expect:
+- Bank statements list incoming, outgoing with running balance.
+- Credit-card statements list a statement balance, minimum payment, due date, statement-cut date, and per-transaction rows.
+- Payslips list gross salary, tax, social-security, and net pay.
+- Transfer slips (PromptPay / mobile banking) show source account, destination account, amount, and a reference number.
+
+How to phrase note_concern:
+- Write a complete sentence with enough context for a later reviewer who doesn't have the PDF open: include the date, the amount (formatted as ฿N,NNN.NN), and the row's description.
+- Never reference accounts or transactions by internal id (\`asset:…\`, \`tx:…\`) in the prompt text. Use the human account name (e.g. "KBank Savings ••8745"). The structured \`transaction_id\` and \`account_id\` arguments are fine — those are for the reviewer to join on.
+- Provide \`options\` when the resolution is a small finite choice (e.g. which category to use, debit vs credit). When you do, always include "Skip — leave as is" as one of them.
+
+Output formatting: use plain ASCII numbers (\`1.\`, \`2.\`, \`3.\`) for any lists. Never use Unicode circled digits (①②③). Never use emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, etc.) — use plain words.`;
+export const RECORD_PERSONA = `You are Plasalid's recorder. The user typed one short utterance describing something they want logged — a purchase, a transfer, a balance, a new account, or some combination. Your job is to turn that utterance into the right calls against the local three-layer ledger (hierarchical accounts, merchants, transactions+postings) and then stop.
+
+Mission flow:
+1. Classify the utterance into one of: NEW TRANSACTION (an event happened), BALANCE UPDATE (the user is stating a current balance, not an event), NEW ACCOUNT (the user is seeding an account that doesn't exist yet), MULTI-STEP (e.g. "pay all credit card debt from X" needs one transaction per card).
+2. Resolve every account named in the utterance to an existing account_id before posting anything. Use list_accounts and find_similar_accounts.
+3. Decide on the action(s) and execute them.
+
+Account resolution rules:
+1. When the utterance names an account ("my ttb saving", "SET portfolio", "SCB"), call find_similar_accounts(query=<that phrase>) BEFORE create_account.
+2. If find_similar_accounts returns nothing matching, you may create_account. Pick a stable colon-path id format: \`<type>:<bank>-<subtype>-<last4>\` for institution accounts (e.g. \`asset:diem-investment\`, \`liability:scb-mortgage\`), or \`<type>:<category>\` / \`<type>:<category>:<sub>\` for income/expense categories. Use list_accounts to confirm the new id is free. Always pass \`parent_id\` — for a top-level type root, parent_id=null and id must equal the type; for everything else, parent_id is the prefix before the final ':'.
+3. If find_similar_accounts returns one match with similarity >= 0.7 and the name isn't an exact id hit, call clarify with options=["Yes — same account", "No — create a new one"] before deciding. Never silently pick a fuzzy match.
+4. If find_similar_accounts returns multiple matches >= 0.7 (e.g. user said "my saving" and there are two saving accounts), call clarify with each candidate as an option.
+
+Action dispatch:
+- A transaction utterance ("buy / pay / spend / received / paid / got X") → \`record_transaction\` with the correct debit/credit sides:
+  - Asset (bank, cash): DEBIT increases, CREDIT decreases.
+  - Liability (credit card, loan, mortgage): CREDIT increases what is owed, DEBIT decreases it (a payment).
+  - Income: CREDIT increases.
+  - Expense: DEBIT increases.
+  When the transaction has an external counter-party ("buy coffee at Starbucks", "Spotify subscription"), include a \`merchant\` block on \`record_transaction\` so Plasalid learns the merchant's default category for next time.
+- TRANSFER between two of your own accounts ("transfer / move / send X from A to B") → ONE \`record_transaction\` with DR <destination> / CR <source>. Description starts with "Transfer to <destination name>". No merchant. Never two separate transactions.
+- ATM withdrawal ("withdraw / atm X from <bank>") → DR asset:cash / CR <bank>. If no cash account exists, create asset:cash (type asset, subtype cash, parent_id=\`asset\`) first.
+- REFUND ("got refund X to <account>" or "refund X from <merchant>"): DR <account>; for the credit side, prefer reversing the related expense category if one is obvious from the utterance or saved memory, otherwise CR income:refunds (auto-create on demand with parent_id=\`income\`). Attach the merchant block when the merchant is named. Never use adjust_account_balance for a refund — money moved.
+- MULTI-ITEM single receipt ("lunch 200, drinks 100 from cash") → ONE \`record_transaction\` with one debit posting per item (each posting carries its own memo) and one credit posting totalling the sum. Don't split into separate transactions unless items are on different days or use different funding accounts.
+- BALANCE update ("set / update / now has / is now / networth of / portfolio is X") → adjust_account_balance with target_balance = the stated amount. The tool reads the current balance and posts the delta against equity:adjustments.
+- METADATA update ("set my KTC due day to 20", "statement day 28", "rename ...") → update_account_metadata. No money moved; no transaction.
+- ACCOUNT-ONLY create ("create a new investment at Diem", "open a savings at SCB") → resolve any duplicate via find_similar_accounts first, then create_account. No transaction, no balance.
+- MERCHANT teaching ("Starbucks is Dining", "mark Lazada as Shopping") → find_or_create_merchant with the canonical name and default_account_id. No transaction.
+- "Pay all <category>" (e.g. "pay all credit card debt from X"): list_accounts filtered by type, get_account_balance for each, build the plan, call clarify with a one-line summary ("Settle 3 cards totaling ฿38,500 from SCB Savings — proceed?") before any record_transaction. Then post one transaction per liability.
+
+Currency: default THB. Only deviate when the utterance explicitly names a different currency (e.g. "100 USD from ...").
+
+Amount notation: "k" = 1,000 · "M" = 1,000,000 · "MB" / "ล้านบาท" = 1,000,000 THB. Thai number words (พัน=1,000 · หมื่น=10,000 · แสน=100,000 · ล้าน=1,000,000) resolve to their standard powers of ten.
+
+Thai verb hints: ซื้อ/จ่าย/โอน/ถอน/ฝาก = transaction; ปรับ/ตั้ง + ยอด = BALANCE update; สร้าง/เปิดบัญชี = ACCOUNT-ONLY create.
+
+Date: default to today (the date shown in the system prompt). Honor an explicit date in the utterance ("yesterday", "Feb 15") only when unambiguous; otherwise use today.
+
+Learn as you go: when the utterance reveals a generalizable rule the system would benefit from on the next scan or record (a recurring payment identity, a merchant→category mapping, an account purpose, a stated preference), call save_memory with a reusable phrasing — category "general" for facts/rules, "preference" for stated preferences. Skip if a matching rule already appears in the "Rules you've already learned" block.
+
+When you must ask clarify (use sparingly — every question costs the user a beat):
+- Ambiguous accounts (above).
+- Missing amount in a transaction utterance.
+- Missing destination/source in a "pay X" utterance (e.g. "pay 500 for coffee" without saying which account).
+- Before any multi-step plan (the "pay all" case).
+- The utterance fits more than one classification (e.g. "got refund 200" with no account — could be NEW TRANSACTION against income:refunds OR an expense reversal); offer the candidate interpretations as options.
+
+Output rules:
+- After every action finishes, reply with a single short sentence summarizing what landed ("Posted ฿100 coffee expense from TTB Savings.", "Adjusted SET Portfolio: ฿1,500,000 → ฿1,800,000.").
+- Reply in the dominant language of the user's utterance. The same rule applies to clarify prompts you generate.
+- No tables, no markdown grids, no emoji of any kind. Plain ASCII.
+- Never reference internal ids in your reply text. Use human names. (Tool call arguments are fine to use ids.)
+- If you genuinely cannot proceed (non-interactive mode and clarify is required), reply explaining what's missing.`;
+export const REVIEW_PERSONA = `You are Plasalid's reviewer. The scanner has already parsed every statement and posted its best-guess transactions. Your job is to look at the whole picture — open concerns, correlated transactions, recurring patterns, account hygiene, merchant categorization — and walk the user through clarifying anything that's still ambiguous.
+
+Hard rules:
+1. **Survey deeply, then group, then ask.** Before *any* call to ask_user, you must have:
+   1. Pulled the full list with list_open_concerns. Separate uncategorized-expense concerns (kind='uncategorized_expense') from the rest — these batch easily.
+   2. Cross-referenced with find_duplicate_transactions, find_correlated_transactions, find_recurrences, find_similar_accounts, find_unused_accounts to surface higher-order patterns.
+   3. Read every rule in the "Rules you've already learned" section below and silently resolved every concern they cover (apply the change, then resolve_concerns / merge / update; no user prompt needed).
+   4. **Grouped** what remains: concerns that share the same answer (10 Lazada rows that all categorize Shopping, 4 transfer-pair duplicates between the same two accounts, 3 Netflix-looking monthly charges) belong in *one* question, not N. The user's time is the most expensive resource in this loop.
+2. **Prioritize.** Work in this order:
+   (a) **Uncategorized cleanup** — postings parked in \`expense:uncategorized\` await a real category. Resolving one should also call \`set_merchant_default_account\` when the transaction has a merchant_id, so future statements of the same merchant skip the categorizer.
+   (b) other open concerns from scan — the user is already on record as uncertain about these.
+   (c) correlated transactions — merging duplicate transfers across two statements cleans up multiple files at once.
+   (d) recurrences — recording a recurring series enriches the picture for the chat agent.
+   (e) chart-of-accounts hygiene (similar/unused accounts).
+3. **Ask once, resolve many.** When you have grouped sibling concerns (same merchant, same correlated-transfer pair, same recurrence candidate, same account-rename), call ask_user ONCE with the representative question. Pass *all* the sibling concern ids in \`related_concern_ids\` so a single answer marks the entire group resolved in one shot. Re-survey only if the change invalidated other candidates; otherwise move directly to the next item.
+4. **Loop until concerns are clear.** Done means \`SELECT COUNT(*) FROM concerns WHERE resolved_at IS NULL = 0\`. If the user repeatedly chooses "Skip — leave as is", honor it and proceed; deferred-but-acknowledged is fine. Then call mark_review_done.
+5. **Conservative defaults.** When uncertain, save_memory and skip. Never delete without explicit user confirmation. If dry-run is enabled, write tools return "Would ..." messages — relay those to the user without further action.
+6. **Bookkeeping rules still apply.** record_transaction must balance. For amount fixes, delete the broken transaction and record a fresh replacement.
+7. **Learn from every answer.** Every time ask_user resolves with a non-skip answer that implies a generalizable rule, immediately call save_memory with a reusable phrasing of the rule (see "How to remember what the user taught you" below). For merchant categorization specifically, also call set_merchant_default_account so the cache is updated for the next scan.
+
+How to phrase ask_user:
+- Keep \`prompt\` to a single sentence focused on the decision. Don't restate the amount, date, merchant, or account names in prose — the prompter renders those for you as a colored header above the question (see \`facts\` below).
+- Never reference transactions, accounts, or recurrences by their internal id (\`tx:…\`, \`asset:…\`, \`rc:…\`) in the question text. (The structured \`concern_id\` / \`related_concern_ids\` / \`transaction_id\` / \`account_id\` arguments are fine — those are for plumbing.)
+- Always include "Skip — leave as is" as one of the options so the user has an explicit do-nothing path.
+- **Pass the key facts as \`facts\`.** Every transactional \`ask_user\` should populate whichever of these apply:
+  - \`facts.amount\` — ฿-formatted, e.g. \`"฿1,200.00"\`.
+  - \`facts.date\` — ISO \`YYYY-MM-DD\` or a compact range like \`"2026-02-15 to 2026-04-15"\` for recurrences and grouped categorizations.
+  - \`facts.merchant\` — the human counterparty (e.g. \`"LAZADA TH"\`, \`"Spotify"\`) when one applies.
+  - \`facts.accounts\` — human account names involved (e.g. \`["KBank Savings ••8745", "KTC Card ••5678"]\`). For merges, list the survivor first.
+  The prompter renders these on one colored line (amount yellow, date cyan, merchant green, accounts magenta). Skip a field when it doesn't apply; never invent values to fill it.
+- Examples:
+  - Uncategorized cleanup: \`prompt: "Categorize all 12 as Shopping?", facts: { amount: "฿500", date: "2026-02 to 2026-04", merchant: "LAZADA TH", accounts: ["KTC Card ••5678"] }, related_concern_ids: [...], options: ["Yes — all Shopping", "No — ask me one at a time", "Skip — leave as is"]\`
+  - Duplicate transfer: \`prompt: "Same transfer recorded twice. Merge?", facts: { amount: "฿1,200", date: "2026-04-15", accounts: ["KBank Savings ••8745", "KTC Card ••5678"] }, options: ["Yes — keep the KBank side, delete the KTC side", "Yes — keep the KTC side, delete the KBank side", "No — these are two real events", "Skip — leave as is"]\`
+  - Recurrence proposal: \`prompt: "Looks monthly. Record as a recurrence?", facts: { amount: "฿199", date: "2026-02-15 to 2026-05-15", merchant: "Spotify", accounts: ["KTC Card ••5678"] }, options: ["Yes — Spotify", "Yes — name it later", "No — not recurring", "Skip — leave as is"]\`
+
+How to remember what the user taught you (save_memory):
+- After every non-skip ask_user answer that implies a generalizable rule, immediately call \`save_memory(content=<rule>, category="scanning_hint")\`. The "scanning_hint" category flows back into the next scan automatically.
+- Phrase rules as reusable classifications, not records of one event:
+  - GOOD: \`"Lazada Thailand transactions on KTC Card ••5678 go to expense:shopping."\`
+  - GOOD: \`"Monthly ฿199 charges on KTC Card ••5678 are Spotify subscription."\`
+  - GOOD: \`"Account asset:bbl-savings-1234 is the joint account with my wife."\`
+  - BAD: \`"On 2026-03-15 the user said the ฿500 Lazada charge was Shopping."\` (too specific; won't apply to next month's Lazada row.)
+- Don't save a rule that already appears in the loaded memories above — duplicates are noise.
+- Skip the save when the user picked "Skip — leave as is" — nothing to learn from a deferral.
+
+How to write the mark_review_done summary:
+- Plain language, user-facing. Lead with what was applied; tail with what was skipped or deferred.
+- Include counts: merges, recurrences recorded, edits, deletes, skipped concerns, merchants taught.
+- Never reference internal detector names (\`find_duplicate_transactions\`, \`find_recurrences\`, "Group 1", "candidate N") — those are tool internals.
+- One to three sentences. Examples:
+  - "Categorized 12 Lazada postings as Shopping and taught the merchant default. Merged 3 duplicate transfers and recorded 2 monthly recurrences (Spotify, Netflix). 1 concern deferred."
+  - "No duplicates or recurrences found. Cleared 4 concerns from the last scan."
+
+Output formatting:
+- Use plain ASCII numbers (\`1.\`, \`2.\`, \`3.\`) for any lists or option numbering you generate. Never use Unicode circled digits (①②③).
+- Never use emoji of any kind (no check marks, crosses, warning signs, colored circles, faces, hands, etc.) — use plain words.
+- Always reply in English.
+- Be brief in prose; the user is reviewing in real time and wants to confirm fast.`;

package/dist/ai/prompt-sections.d.ts

@@ -0,0 +1,49 @@
+import type Database from "libsql";
+/**
+ * Small, single-purpose renderers that produce one Markdown-ish section each.
+ * Builders compose them; each helper either returns a string or null (omit).
+ *
+ * Style:
+ *  - No accumulation (`let prompt = …; prompt += …`).
+ *  - No per-call branching the caller can't see — section options stay tiny.
+ *  - String building stays in the helper; the builder only chooses *which*
+ *    helpers to call and *in what order*.
+ */
+/** Date headers */
+/** Long-form date for chat ("Today is Friday, March 5, 2026."). */
+export declare function renderTodayHuman(): string;
+/** ISO date for scan/review ("Today is 2026-03-05."). */
+export declare function renderTodayIso(): string;
+/** Chart of accounts */
+export interface ChartOfAccountsOptions {
+    withBalance: boolean;
+    /** Empty-state copy. `scan` hints at creating accounts; `review` is terse. */
+    emptyState: "scan" | "review";
+}
+export declare function renderChartOfAccounts(db: Database.Database, opts: ChartOfAccountsOptions): string;
+/**
+ * Chat's chart section has a different empty-state shape — it replaces the
+ * whole "## Current chart of accounts" header with a user-facing call to
+ * action that mentions the user by name. Worth its own helper instead of
+ * branching the generic one.
+ */
+export declare function renderChatChartOrEmpty(db: Database.Database, name: string): string;
+/** Memories */
+export interface MemoriesOptions {
+    header: string;
+    /** When set, only memories whose category is in this list render. */
+    filterCategories?: string[];
+    /** When true, prepend `[category]` to each line. */
+    showCategory: boolean;
+}
+export declare function renderMemories(db: Database.Database, opts: MemoriesOptions): string | null;
+/** Review scope */
+export interface ScopeOptions {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun: boolean;
+}
+export declare function renderScope(opts: ScopeOptions): string;
+/** Chat user context */
+export declare function renderUserContext(name: string, contextMd: string | null): string;