plasalid 0.3.5 → 0.4.1

package/README.md

@@ -1,59 +1,47 @@
 <h1 align="center">Plasalid</h1>
 
 <p align="center">
-  <strong>Talk to your money</strong>
+  <strong>A local-first Plaid for your bank statements</strong>
 </p>
 
 <p align="center">
-  A local-first AI that reads every line of your transactions and coaches you the best move.
+  Turn the PDFs you already receive into a structured, AI-readable journal — on your own machine.
 </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.
+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 is the missing layer: drop your bank and credit-card statement PDFs into a folder and Plasalid parses every transaction, balance, and fee into a double-entry SQLite database that lives on your machine. One source of truth for every account, ready for any AI to read.
 
-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.
+Plasalid ships with a built-in chat so you can start asking questions right away, but the data layer is the product. A local MCP / API server is coming next, so any AI tool — Claude Desktop, your own scripts, dashboards, automations — can read the same journal without further integration. Local, private, yours.
 
 ## 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.** Today's chat is one consumer of the journal; 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 a balanced journal out.** The scanner infers account type, masks account numbers, converts Buddhist-Era dates, and posts a double-entry record for every transaction.
+- **Never pauses to ask you.** Ambiguous rows post best-guess entries with a structured *concern* attached; 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.
+- **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 entry. Not a UI category — a fact about your money the next AI tool 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 journal lines.** Not generic categories. "Where did ฿14k go in March?" gets an answer drawn from actual entries, with figures, dates, and account names 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,14 +61,15 @@ 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 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 journal entry derived from them.
 
 ## Commands
@@ -96,7 +85,7 @@ plasalid status                     # Net worth and this-month income/expense to
 plasalid transactions               # List journal lines (filter by --account, --from, --to, --query, --limit)
 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 review [--dry-run]         # Connect related transactions, learn recurring rhythms, resolve open concerns (--account, --from, --to also accepted)
 ```
 
 ## How It Works
@@ -115,7 +104,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 +133,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 journal, chart of accounts, scan history, open concerns awaiting review, recurring transactions (Spotify, salary, rent — recognized during review and linked from each member journal entry), 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 } from "./system-prompt.js";
 import { type AgentExecutionContext } from "./tools/index.js";
 import type { NormalizedMessage } from "./provider.js";
 export type ProgressCallback = (event: {
@@ -30,13 +30,14 @@ 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).
+ * Review-time agent loop. Surveys the existing journal with the review
+ * tool profile (read tools + write/merge/delete primitives + recurrence
+ * detection/recording).
  */
-export declare function runReconcileAgent(opts: {
+export declare function runReviewAgent(opts: {
     db: Database.Database;
     initialMessages: NormalizedMessage[];
-    prompt: ReconcilePromptOptions;
+    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, } 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,16 @@ 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).
+ * Review-time agent loop. Surveys the existing journal with the review
+ * tool profile (read tools + write/merge/delete primitives + recurrence
+ * detection/recording).
  */
-export async function runReconcileAgent(opts) {
-    const systemPrompt = redact(buildReconcileSystemPrompt(opts.db, opts.prompt));
+export async function runReviewAgent(opts) {
+    const systemPrompt = redact(buildReviewSystemPrompt(opts.db, opts.prompt));
     const { text } = await runAgent({
         db: opts.db,
         systemPrompt,
-        tools: getToolDefinitions("reconcile"),
+        tools: getToolDefinitions("review"),
         initialMessages: opts.initialMessages,
         agentCtx: opts.agentCtx,
         onProgress: opts.onProgress,

package/dist/ai/memory.d.ts

@@ -1,14 +1,21 @@
 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;
-}[];
+}
+export declare function getConversationHistory(db: Database.Database, limit?: number): ConversationMessage[];
+export declare function saveMessage(db: Database.Database, role: "user" | "assistant", content: string): void;
+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,10 @@
+/**
+ * Persona text constants for the three 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 REVIEW_PERSONA: string;

package/dist/ai/personas.js

@@ -0,0 +1,123 @@
+/**
+ * Persona text constants for the three 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 ("ปลาสลิด") — You're ${name}'s personal money coach. You have direct access to ${name}'s real bank balances, credit-card statements, and journal data through the tools below. Sharp, candid, proactive — a trusted friend who happens to be deep in their money every day.
+
+## How you talk
+- Lead with the insight, not the data. Don't say "Here's the breakdown." Say what the number means: "Dining is up ฿2,400 this month — your biggest jump."
+- Always cite actual figures, dates, and account names from tool results. Never make up data.
+- Have a point of view. When ${name} asks "what should I do?", say what you'd do and why. Present alternatives only after your recommendation.
+- Be proactive: if you notice something concerning (overdraft trajectory, unusual spending, a payment due soon, a balance trending the wrong way), bring it up even if not asked.
+- Be concise. 2-4 sentences for simple questions. Skip preamble like "Great question!" or "Let me look that up." Just answer.
+- Warm but direct. Celebrate wins genuinely. Flag problems without sugarcoating.
+
+## How you work
+1. Call the read tools to look up current data — never guess balances, dates, or transactions.
+2. Connect the dots. Don't just report numbers; tell ${name} what they mean for them, referencing whatever's in the "## About ${name}" block (employer, household, goals).
+3. For period comparisons, give both percentages and absolute differences.
+4. End with a next step when it helps. A good partner always has a suggestion.
+5. 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\`.
+6. Default currency is THB unless an account is explicitly in another. Don't mix currencies.
+
+## Output rules
+- Reply in the dominant language of ${name}'s message; default to English when mixed or ambiguous.
+- 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 a local double-entry bookkeeping database.
+
+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_journal_entry\` call. Total debits must equal total credits.
+3. Account-type conventions:
+   - **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. Dates: convert Buddhist Era → Gregorian by subtracting 543 from the year. Store as YYYY-MM-DD.
+5. Default currency is THB. Tag every line with its ISO 4217 currency code on the \`record_journal_entry\` call; only deviate from THB when the row explicitly shows another currency (foreign-card purchases, FX transfers, multi-currency wallets).
+6. Account numbers: store only the last 4 digits (mask the rest with bullets, e.g. \`••1234\`). Never persist the full account number.
+7. If the document reveals an account that doesn't exist yet, call \`create_account\` once before posting entries to it. Reuse existing accounts; don't create duplicates — call \`list_accounts\` first.
+8. Persist account metadata when the document carries it: bank name, masked number, statement day, due day, points balance.
+9. **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_journal_entry\`, 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 \`entry_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_journal_entry\` with placeholder values. Call \`note_concern\` with the raw row text and no \`entry_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 set both \`account_id\` and \`entry_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.
+10. 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.
+
+Pick a stable account id format: \`<type>:<bank>-<subtype>-<last4>\`, e.g. \`asset:kbank-savings-1234\`, \`liability:ktc-card-5678\`, \`expense:food\`, \`income:salary\`.
+
+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 entries by internal id (\`a:…\`, \`je:…\`) in the prompt text. Use the human account name (e.g. "KBank Savings ••8745"). The structured \`entry_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 REVIEW_PERSONA = `You are Plasalid's reviewer. The scanner has already parsed every statement and posted its best-guess journal entries. Your job is to look at the whole picture — open concerns, correlated transactions, recurring patterns, account hygiene — 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.
+   2. Cross-referenced with find_duplicate_entries, find_correlated_entries, 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) open concerns from scan — the user is already on record as uncertain about these; (b) correlated transactions — merging duplicate transfers across two statements cleans up multiple files at once; (c) recurrences — recording a recurring series enriches the picture for the chat agent; (d) 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_journal_entry must balance. For amount fixes, delete the broken entry 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). Future scans and reviews read these memories; this is how the system gets less annoying over time.
+
+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 entries, accounts, or recurrences by their internal id (\`je:…\`, \`a:…\`, \`rc:…\`) in the question text. (The structured \`concern_id\` / \`related_concern_ids\` / \`entry_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:
+  - Grouped categorization: \`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.
+- Never reference internal detector names (\`find_duplicate_entries\`, \`find_recurrences\`, "Group 1", "candidate N") — those are tool internals.
+- One to three sentences. Examples:
+  - "Merged 3 duplicate transfers and recorded 2 monthly recurrences (Spotify, Netflix). Renamed 1 account. 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,44 @@
+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*.
+ */
+/** 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;
+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;
+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;
+export interface ScopeOptions {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun: boolean;
+}
+export declare function renderScope(opts: ScopeOptions): string;
+export declare function renderUserContext(name: string, contextMd: string | null): string;

package/dist/ai/prompt-sections.js

@@ -0,0 +1,89 @@
+import { getMemories } from "./memory.js";
+import { getAccountBalances } from "../db/queries/account_balance.js";
+import { stripControls } from "./sanitize.js";
+/**
+ * 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 function renderTodayHuman() {
+    return `Today is ${new Date().toLocaleDateString("en-GB", {
+        weekday: "long",
+        month: "long",
+        day: "numeric",
+        year: "numeric",
+    })}.`;
+}
+/** ISO date for scan/review ("Today is 2026-03-05."). */
+export function renderTodayIso() {
+    return `Today is ${new Date().toISOString().slice(0, 10)}.`;
+}
+export function renderChartOfAccounts(db, opts) {
+    const balances = getAccountBalances(db);
+    if (balances.length === 0) {
+        const empty = opts.emptyState === "scan"
+            ? "(empty — you may need to create accounts)"
+            : "(empty)";
+        return `## Current chart of accounts\n${empty}`;
+    }
+    const rows = balances.map(a => formatAccountRow(a, opts.withBalance));
+    return `## Current chart of accounts\n${rows.join("\n")}`;
+}
+/**
+ * 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 function renderChatChartOrEmpty(db, name) {
+    const balances = getAccountBalances(db);
+    if (balances.length === 0) {
+        return `No accounts have been scanned yet. ${name} should drop files into ~/.plasalid/data/ and run \`plasalid scan\`.`;
+    }
+    const rows = balances.map(a => formatAccountRow(a, true));
+    return `## Accounts on file\n${rows.join("\n")}`;
+}
+export function renderMemories(db, opts) {
+    const all = getMemories(db);
+    const filtered = opts.filterCategories
+        ? all.filter(m => opts.filterCategories.includes(m.category))
+        : all;
+    if (filtered.length === 0)
+        return null;
+    const lines = filtered.map(m => formatMemoryLine(m, opts.showCategory));
+    return `## ${opts.header}\n${lines.join("\n")}`;
+}
+export function renderScope(opts) {
+    return [
+        "## Scope",
+        `- account: ${opts.accountId ?? "all"}`,
+        `- from: ${opts.from ?? "all time"}`,
+        `- to: ${opts.to ?? "now"}`,
+        `- dry run: ${opts.dryRun
+            ? "yes — write tools will not mutate the DB"
+            : "no — write tools will mutate the DB after confirmation"}`,
+    ].join("\n");
+}
+// ── Chat user context ──────────────────────────────────────────────────────
+export function renderUserContext(name, contextMd) {
+    const body = contextMd ?? `(No personal context on file yet. ${name} can edit ~/.plasalid/context.md to add family, income, or other facts.)`;
+    return `## About ${name}\n${body}`;
+}
+// ── Internal formatters ────────────────────────────────────────────────────
+function formatAccountRow(a, withBalance) {
+    const subtype = a.subtype ? `/${a.subtype}` : "";
+    const base = `- ${a.id} | ${a.name} | ${a.type}${subtype}`;
+    return withBalance ? `${base} | balance ${a.balance.toFixed(2)} ${a.currency}` : base;
+}
+function formatMemoryLine(m, showCategory) {
+    return showCategory
+        ? `- [${m.category}] ${stripControls(m.content)}`
+        : `- ${stripControls(m.content)}`;
+}

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

@@ -1,13 +1,13 @@
 import type Database from "libsql";
-export declare function buildChatSystemPrompt(db: Database.Database): string;
 export interface ScanPromptOptions {
     fileName: string;
 }
-export interface ReconcilePromptOptions {
+export interface ReviewPromptOptions {
     accountId?: string;
     from?: string;
     to?: string;
     dryRun: boolean;
 }
-export declare function buildReconcileSystemPrompt(db: Database.Database, opts: ReconcilePromptOptions): string;
+export declare function buildChatSystemPrompt(db: Database.Database): string;
+export declare function buildReviewSystemPrompt(db: Database.Database, opts: ReviewPromptOptions): string;
 export declare function buildScanSystemPrompt(db: Database.Database, opts: ScanPromptOptions): string;