plasalid 0.7.2 → 0.7.4

package/README.md

@@ -15,15 +15,17 @@
 
 <br />
 
-In the US/EU, a financial data aggregator like Plaid empowers most finance apps: one connection, and every app sees the same unified view of your accounts. Most of the world doesn't have that, including Thailand, where there's no such aggregator platform. All bank data is siloed: to know where your financial status stands means logging into five bank apps one by one. Creating a unified view of personal financial data is very challenging.
+In US and Europe, the most of financial apps is likely powered by a hidden aggregators engine like Plaid. You can link your bank accounts once and see your entire financial life in one place. But for most of the world, Thailand included, that infrastructure simply does not exist.
 
-That's why Plasalid emerged to resolve this pain point. Your data has stayed fragmented for decades, with no way to bring it together. You can't manage a mortgage effectively without the full picture, and you may be completely blind to your recurring monthly income and expenses. Subscriptions stay active long after they're forgotten, unknown charges go unverified, bank accounts opened years ago drift unchecked, and unexpected spending may silently grow beyond what any single statement shows. When your finances are hard to manage, your life definitely becomes more difficult. Your plans toward financial stability or freedom slip further out of reach. Plasalid is built to solve this.
+Your data is locked in bank silos. Tracking your net worth means logging into half a dozen apps and crunching the numbers manually. This fragmentation creates massive blind spots. Subscriptions are forgotten, strange charges go unnoticed, and planning for big financial goals becomes a guessing game.
 
-Plasalid addresses this with a simple founding concept: let users drop all their financial documents - bank statements, credit-card statements, payslips, brokerage statements - onto their own machine, where Plasalid leverages AI to extract every transaction, balance, and holding into a single, structured, double-entry database that serves as context for future processing.
+Plasalid is a local data harness built to fix this. Think of it as a personal financial harness.
 
-Moreover, Plasalid comes with a built-in agentic chat that queries the data directly, so questions like which subscriptions are still active, where money went last month, or what your current net worth is can be answered against actual records rather than estimates. You can talk with your money on Plasalid to help you understand your financial situation and plan efficiently.
+You drop your raw financial documents (bank statements, credit card bills, payslips) straight into a folder on your machine. Plasalid parses those files and extracts every transaction, balance, and holding. It transforms a messy pile of PDFs into a clean, double-entry ledger. You only have to build this foundation once. The result is an open, structured backend for your finances, ready to plug into any tool you want.
 
-The data ledger also serves as a harness, open to any AI agent that connects to it, so the picture you assemble once is reusable across whatever tools you choose to use.
+To show you the power of this harness out of the box, Plasalid includes a built-in AI agent. Because your ledger is fully structured, you can actually talk to your money. Ask a question like "Which subscriptions are still active?" or "What did I spend on food last month?". You get exact numbers pulled directly from your records, not estimates or AI hallucinations.
+
+We also built strict boundaries around your privacy. The database is encrypted locally. Plasalid automatically strips out all PII before sending data to an external API. This mean if you swap in a local AI model, your setup runs can stay 100% private and offline.
 
 <p align="center">
   <img src=".github/plasalid-demo.png" alt="demo" width="100%" />
@@ -67,15 +69,14 @@ 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` — it parses your PDFs end-to-end without stopping.
-3. Run `plasalid resolve` to connect related transactions, learn your recurring rhythms, and clear up anything the scanner flagged as a unknown.
+3. Run `plasalid clarify` to connect related transactions, learn your recurring rhythms, and clear up anything the scanner flagged as a question.
 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 resolve` — walk every open unknown one at a time and apply your decision (categorize, merge duplicates, link recurrences, skip). Filter with `--account`, `--from`, `--to`, or `--kind`.
-- `plasalid revert <regex>` — delete scanned files matching the regex and every transaction derived from them.
+- `plasalid clarify` — walk every open question one at a time and apply your decision (categorize, merge duplicates, link recurrences, etc). 
 
 ## Commands
 
@@ -90,8 +91,7 @@ plasalid transactions               # List transactions and their postings (filt
 plasalid status                     # Net worth and this-month income/expense totals
 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 transactions
-plasalid resolve                    # Walk every open unknown and apply your decision (--account, --from, --to, --kind also accepted)
+plasalid clarify                    # Walk every open question and apply your decision
 ```
 
 ## How It Works
@@ -110,7 +110,7 @@ plasalid resolve                    # Walk every open unknown and apply your dec
        AI provider (PII-redacted)
                   │
        ┌──────────▼──────────┐
-       │     Encrypted DB    │◀──── plasalid resolve
+       │     Encrypted DB    │◀──── plasalid clarify
        └──────────┬──────────┘       
                   │                   
                plasalid               
@@ -139,15 +139,15 @@ Plasalid stores everything in `~/.plasalid/`:
   data/                # Drop any PDFs here (subfolders allowed; AI classifies)
 ```
 
-`db.sqlite` holds the three-layer ledger (hierarchical accounts, deduplicated merchants with learned default categories, transactions and postings), scan history, open unknowns awaiting resolve, recurring transactions (Spotify, salary, rent — recognized during resolve 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.
+`db.sqlite` holds the three-layer ledger (hierarchical accounts, deduplicated merchants with categories, transactions and postings), scan history, open questions awaiting clarify, recurring transactions (Spotify, salary, rent — recognized during clarify transaction), persisted long-term memories, and AES-GCM-encrypted passwords. Everything is wrapped in libsql's AES-256 page encryption.
 
 ### Environment Variables
 
 ```bash
 ANTHROPIC_API_KEY=            # Anthropic API key (required when provider is anthropic)
 PLASALID_MODEL=               # Model name; default for Anthropic: claude-sonnet-4-6
-PLASALID_PROVIDER=            # anthropic | openai-compatible. Default: anthropic
-OPENAI_COMPATIBLE_BASE_URL=   # e.g. http://localhost:11434/v1 (Ollama)
+PLASALID_PROVIDER=            # anthropic | openai-compatible. default: anthropic
+OPENAI_COMPATIBLE_BASE_URL=   # e.g. http://localhost:11434/v1 (ollama)
 OPENAI_COMPATIBLE_API_KEY=    # API key for the OpenAI-compatible server (often unused)
 PLASALID_DB_ENCRYPTION_KEY=   # DB encryption passphrase
 PLASALID_DB_PATH=             # Default: ~/.plasalid/db.sqlite

package/dist/accounts/taxonomy.d.ts

@@ -1,7 +1,7 @@
 export type AccountType = "asset" | "liability" | "income" | "expense" | "equity";
 export declare const ACCOUNT_TYPE_DESCRIPTIONS: Record<AccountType, string>;
 /**
- * Stringified Thai taxonomy block for the scan/resolve system prompts.
+ * Stringified Thai taxonomy block for the scan/clarify 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

@@ -169,7 +169,7 @@ const SUGGESTED_INCOME_SUBTYPES = [
     "other",
 ];
 /**
- * Stringified Thai taxonomy block for the scan/resolve system prompts.
+ * Stringified Thai taxonomy block for the scan/clarify 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 ResolvePromptOptions, type RecordPromptOptions } from "./system-prompt.js";
+import { type ScanPromptOptions, type ClarifyPromptOptions, type RecordPromptOptions } from "./system-prompt.js";
 import { type AgentExecutionContext } from "./tools/index.js";
 import type { NormalizedMessage } from "./provider.js";
 export { AbortedError } from "./errors.js";
@@ -18,7 +18,7 @@ export declare function handleChatMessage(db: Database.Database, userMessage: st
  * Scan-time agent loop. Caller supplies the initial user message (which carries
  * the PDF as a content block) and a AgentExecutionContext that scopes the file
  * id, scanId, and progress sink. A truncated run records a scan_truncated
- * question so resolve can surface it later.
+ * question so clarify can surface it later.
  */
 export declare function runScanAgent(opts: {
     db: Database.Database;
@@ -41,14 +41,14 @@ export declare function runRecordAgent(opts: {
     signal?: AbortSignal;
 }): Promise<string>;
 /**
- * Resolve-time agent loop. Driven by RESOLVE_PERSONA. Surveys every open
+ * Clarify-time agent loop. Driven by CLARIFY_PERSONA. Surveys every open
  * question, applies memory/heuristic resolutions silently, groups whatever
  * remains and asks the user once per group via ask_user.
  */
-export declare function runResolveAgent(opts: {
+export declare function runClarifyAgent(opts: {
     db: Database.Database;
     initialMessages: NormalizedMessage[];
-    prompt: ResolvePromptOptions;
+    prompt: ClarifyPromptOptions;
     agentCtx: AgentExecutionContext;
     onProgress?: ProgressCallback;
     signal?: AbortSignal;

package/dist/ai/agent.js

@@ -1,5 +1,5 @@
 import { config } from "../config.js";
-import { buildChatSystemPrompt, buildScanSystemPrompt, buildResolveSystemPrompt, buildRecordSystemPrompt, } from "./system-prompt.js";
+import { buildChatSystemPrompt, buildScanSystemPrompt, buildClarifySystemPrompt, buildRecordSystemPrompt, } from "./system-prompt.js";
 import { getToolDefinitions, executeTool } from "./tools/index.js";
 import { getConversationHistory, saveMessage } from "./memory.js";
 import { recordQuestion } from "../db/queries/questions.js";
@@ -125,7 +125,7 @@ export async function handleChatMessage(db, userMessage, onProgress, signal) {
  * Scan-time agent loop. Caller supplies the initial user message (which carries
  * the PDF as a content block) and a AgentExecutionContext that scopes the file
  * id, scanId, and progress sink. A truncated run records a scan_truncated
- * question so resolve can surface it later.
+ * question so clarify can surface it later.
  */
 export async function runScanAgent(opts) {
     const systemPrompt = redact(buildScanSystemPrompt(opts.db, opts.prompt));
@@ -173,16 +173,16 @@ export async function runRecordAgent(opts) {
     return text;
 }
 /**
- * Resolve-time agent loop. Driven by RESOLVE_PERSONA. Surveys every open
+ * Clarify-time agent loop. Driven by CLARIFY_PERSONA. Surveys every open
  * question, applies memory/heuristic resolutions silently, groups whatever
  * remains and asks the user once per group via ask_user.
  */
-export async function runResolveAgent(opts) {
-    const systemPrompt = redact(buildResolveSystemPrompt(opts.db, opts.prompt));
+export async function runClarifyAgent(opts) {
+    const systemPrompt = redact(buildClarifySystemPrompt(opts.db, opts.prompt));
     const { text } = await runAgent({
         db: opts.db,
         systemPrompt,
-        tools: getToolDefinitions("resolve"),
+        tools: getToolDefinitions("clarify"),
         initialMessages: opts.initialMessages,
         agentCtx: opts.agentCtx,
         onProgress: opts.onProgress,

package/dist/ai/personas.d.ts

@@ -8,4 +8,4 @@
 export declare function chatPersona(name: string): string;
 export declare const SCAN_PERSONA: string;
 export declare const RECORD_PERSONA: string;
-export declare const RESOLVE_PERSONA: string;
+export declare const CLARIFY_PERSONA: string;

package/dist/ai/personas.js

@@ -55,7 +55,7 @@ Rules:
 6. **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:
    - \`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\`: **do not** set this on first sight, even when you're confident. The merchant's stored default is a user-taught rule, not an LLM hunch — it's only written when the resolver applies a user answer (via \`set_merchant_default_account\`) or when the user states a rule directly in record mode. Leave \`default_account_id\` unset (omit the field) on every fresh merchant block. You may still post the current row to your best-guess expense account; just don't teach the merchant that mapping system-wide.
+   - \`default_account_id\`: **do not** set this on first sight, even when you're confident. The merchant's stored default is a user-taught rule, not an LLM hunch — it's only written when the clarifier applies a user answer (via \`set_merchant_default_account\`) or when the user states a rule directly in record mode. Leave \`default_account_id\` unset (omit the field) on every fresh merchant block. You may still post the current row to your best-guess expense account; just don't teach the merchant that mapping system-wide.
    Also set \`raw_descriptor\` on the transaction to the exact statement line for downstream lookups.
    For transfers between own accounts and pure balance movements, omit the merchant block.
 7. **Pre-resolved merchants.** If the prompt context shows a merchant already known for the descriptor, use the supplied \`merchant_id\` and \`default_account_id\` 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).
@@ -63,7 +63,7 @@ Rules:
 
    Reserve \`expense:uncategorized\` + \`note_question\` with \`kind="uncategorized_expense"\` for the genuinely uncategorizable: opaque descriptors like \`PAYMENT 0042\`, \`POS 12345\`, \`BANK FEE\`, \`ATM WITHDRAWAL ID 99\`, or rows where you'd be picking randomly between three or more equally plausible categories. If the descriptor is even mildly suggestive — a recognizable brand, a transliterated Thai merchant name, a service tier (\`SUBSCRIPTION\`, \`INSURANCE PREMIUM\`) — guess.
 
-   **Income stays strict.** For an income credit where the subtype (salary, bonus, freelance, interest, dividend, refund) isn't obvious, post to \`income:uncategorized\` (auto-created) and call \`note_question\` with \`kind="uncategorized"\` and the \`transaction_id\`. Do not pick \`income:other\` or any subtype as a guess. Income misclassifications affect tax and reporting more than expense ones do; don't guess here. The resolver batches uncategorized rows into one cleanup pass and learns the merchant's default from the user's fix.
+   **Income stays strict.** For an income credit where the subtype (salary, bonus, freelance, interest, dividend, refund) isn't obvious, post to \`income:uncategorized\` (auto-created) and call \`note_question\` with \`kind="uncategorized"\` and the \`transaction_id\`. Do not pick \`income:other\` or any subtype as a guess. Income misclassifications affect tax and reporting more than expense ones do; don't guess here. The clarifier batches uncategorized rows into one cleanup pass and learns the merchant's default from the user's fix.
 9. Dates: convert Buddhist Era → Gregorian by subtracting 543 from the year. Store as YYYY-MM-DD.
 10. Default currency is THB. Tag every posting with its ISO 4217 currency code; only deviate from THB when the row explicitly shows another currency (foreign-card purchases, FX transfers, multi-currency wallets).
 11. Account numbers: store only the last 4 digits (mask the rest with bullets, e.g. \`••1234\`). Never persist the full account number.
@@ -74,7 +74,7 @@ Rules:
     - **Category uncertainty alone is NOT a reason to flag.** Pick the best expense category and move on (per rule 8). Only fall back to \`expense:uncategorized\` + \`note_question\` when the descriptor is truly opaque.
     - If a row is *unparseable* (amount unreadable, date missing entirely, can't tell what account is involved), **skip the row entirely** — do not post a placeholder. Call \`note_question\` with the raw row text and no \`transaction_id\`. A missing row is better than a wrong row.
     - If you have a question 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_question\` with \`account_id\` set. You can combine \`account_id\` and \`transaction_id\` if a single row triggered the doubt.
-    - The resolver will work through questions later with the full picture across statements.
+    - The clarifier will work through questions later with the full picture across statements.
     - **Apply what you've already been told.** Before flagging a question, 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 question. Only flag a question when the row genuinely doesn't fit any saved rule. Asking the user about something they've already told us is bad UX.
 15. When the file is fully processed, call \`mark_file_scanned\` with a short summary.
 
@@ -85,8 +85,8 @@ Common Thai statement patterns to expect:
 - Transfer slips (PromptPay / mobile banking) show source account, destination account, amount, and a reference number.
 
 How to phrase note_question:
-- Write a complete sentence with enough context for a later resolver 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 resolver to join on.
+- Write a complete sentence with enough context for a later clarifier 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 clarifier 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.`;
@@ -100,8 +100,8 @@ Mission flow:
 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.
+3. If find_similar_accounts returns one match with similarity >= 0.7 and the name isn't an exact id hit, call confirm 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 confirm 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:
@@ -120,7 +120,7 @@ Action dispatch:
 - DELETE ("delete my old empty cash account", "remove asset:old-savings") → resolve the account via find_similar_accounts, then delete_account. delete_account refuses if the account still has postings — tell the user to merge or recategorize first.
 - 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.
+- "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 confirm 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 ...").
 
@@ -132,7 +132,7 @@ Date: default to today (the date shown in the system prompt). Honor an explicit
 
 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):
+When you must confirm (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).
@@ -141,11 +141,11 @@ When you must ask clarify (use sparingly — every question costs the user a bea
 
 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.
+- Reply in the dominant language of the user's utterance. The same rule applies to confirm 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 RESOLVE_PERSONA = `You are Plasalid ("ปลาสลิด"), currently working through every question the scanner couldn't resolve. The user message hands you EVERY question at once. Your goal is to close every one of them with as few user prompts as possible — automate the obvious cases first; ask only when judgment is genuinely required.
+- If you genuinely cannot proceed (non-interactive mode and confirm is required), reply explaining what's missing.`;
+export const CLARIFY_PERSONA = `You are Plasalid ("ปลาสลิด"), currently working through every question the scanner couldn't resolve. The user message hands you EVERY question at once. Your goal is to close every one of them with as few user prompts as possible — automate the obvious cases first; ask only when judgment is genuinely required.
 
 Inputs you receive:
 - One line per question in the user message: id, kind, transaction/account/file ids, prompt, options.
@@ -154,7 +154,7 @@ Inputs you receive:
 
 The workflow is five steps. Do them in order. Do not skip step 1.
 
-**Step 1 — Survey.** Read the entire question list. Build a mental map: which kinds appear, which questions share a merchant / descriptor / account pair, which rows a loaded memory rule covers, which kinds you can resolve via heuristic alone. The goal is to know the whole shape before mutating anything.
+**Step 1 — Survey.** Read the entire question list. Build a mental map: which kinds appear, which questions share a merchant / descriptor / account pair, which rows a loaded memory rule covers, which kinds you can clarify via heuristic alone. The goal is to know the whole shape before mutating anything.
 
 **Step 2 — Apply memory-driven silent resolutions.** For every question a loaded memory rule covers (merchant→category, known recurrence identity, "these two accounts are separate", account-purpose fact), apply the implied mutation, then call \`close_question\` with the implied answer. Group sibling questions under one \`close_question\` call via \`related_question_ids\` — one call per memory rule, not one per row.
 
@@ -178,7 +178,7 @@ For each group, call \`ask_user\` ONCE, passing every sibling's id in \`related_
 
 **Step 5 — Learn and finalize.** After every non-skip user answer that implies a generalizable rule (e.g. "Lazada on KTC Card → Shopping"), call \`save_memory(content=<rule>, category="scanning_hint")\` so the next scan applies it silently. For merchant categorization, also call \`set_merchant_default_account\`. Phrase rules as reusable classifications, not one-event records (GOOD: "Lazada Thailand on KTC Card ••5678 → expense:shopping." BAD: "On 2026-03-15 the user said Shopping.").
 
-**Closing invariant.** Every question in the input list must have \`resolved_at\` set by the end. If anything is still open after step 4, close it with \`close_question(answer="Skip — could not interpret")\`. The pipeline reads the DB after you finish — if any question is still open it will re-invoke you with the leftovers, so always finish each row before yielding.
+**Closing invariant.** Every question in the input list must be closed by the end. Closing deletes the row from the \`questions\` table. If anything is still open after step 4, close it with \`close_question(answer="Skip — could not interpret")\`. The pipeline reads the DB after you finish — if any question is still open it will re-invoke you with the leftovers, so always finish each row before yielding.
 
 **Tool errors.** If a tool result comes back marked as an error (e.g. a malformed id, a row that no longer exists, a constraint violation), do NOT call \`close_question\` for the affected row. Either fix the input and retry the same mutation, or close that one row with \`close_question(answer="Skip — tool error: <short reason>")\` so the loop can move on. Never close a row whose underlying mutation failed.
 

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

@@ -12,13 +12,13 @@ import type Database from "libsql";
 /** Date headers */
 /** Long-form date for chat ("Today is Friday, March 5, 2026."). */
 export declare function renderTodayHuman(): string;
-/** ISO date for scan/resolve ("Today is 2026-03-05."). */
+/** ISO date for scan/clarify ("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; `resolve` is terse. */
-    emptyState: "scan" | "resolve";
+    /** Empty-state copy. `scan` hints at creating accounts; `clarify` is terse. */
+    emptyState: "scan" | "clarify";
 }
 export declare function renderChartOfAccounts(db: Database.Database, opts: ChartOfAccountsOptions): string;
 /**
@@ -37,7 +37,7 @@ export interface MemoriesOptions {
     showCategory: boolean;
 }
 export declare function renderMemories(db: Database.Database, opts: MemoriesOptions): string | null;
-/** Resolve scope */
+/** Clarify scope */
 export interface ScopeOptions {
     accountId?: string;
     from?: string;

package/dist/ai/prompt-sections.js

@@ -21,7 +21,7 @@ export function renderTodayHuman() {
         year: "numeric",
     })}.`;
 }
-/** ISO date for scan/resolve ("Today is 2026-03-05."). */
+/** ISO date for scan/clarify ("Today is 2026-03-05."). */
 export function renderTodayIso() {
     return `Today is ${new Date().toISOString().slice(0, 10)}.`;
 }

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

@@ -2,7 +2,7 @@ import type Database from "libsql";
 export interface ScanPromptOptions {
     fileName: string;
 }
-export interface ResolvePromptOptions {
+export interface ClarifyPromptOptions {
     accountId?: string;
     from?: string;
     to?: string;
@@ -18,6 +18,6 @@ export interface RecordPromptOptions {
  * shuffle the array.
  */
 export declare function buildChatSystemPrompt(db: Database.Database): string;
-export declare function buildResolveSystemPrompt(db: Database.Database, opts: ResolvePromptOptions): string;
+export declare function buildClarifySystemPrompt(db: Database.Database, opts: ClarifyPromptOptions): string;
 export declare function buildRecordSystemPrompt(db: Database.Database, opts: RecordPromptOptions): string;
 export declare function buildScanSystemPrompt(db: Database.Database, opts: ScanPromptOptions): string;

package/dist/ai/system-prompt.js

@@ -1,6 +1,6 @@
 import { config } from "../config.js";
 import { readContext } from "./context.js";
-import { chatPersona, SCAN_PERSONA, RESOLVE_PERSONA, RECORD_PERSONA } from "./personas.js";
+import { chatPersona, SCAN_PERSONA, CLARIFY_PERSONA, RECORD_PERSONA } from "./personas.js";
 import { getThaiTaxonomyHint } from "../accounts/taxonomy.js";
 import { renderChartOfAccounts, renderChatChartOrEmpty, renderMemories, renderScope, renderTodayHuman, renderTodayIso, renderUserContext, } from "./prompt-sections.js";
 /**
@@ -23,11 +23,11 @@ export function buildChatSystemPrompt(db) {
         }),
     ]);
 }
-export function buildResolveSystemPrompt(db, opts) {
+export function buildClarifySystemPrompt(db, opts) {
     return joinSections([
-        RESOLVE_PERSONA,
+        CLARIFY_PERSONA,
         renderTodayIso(),
-        renderChartOfAccounts(db, { withBalance: true, emptyState: "resolve" }),
+        renderChartOfAccounts(db, { withBalance: true, emptyState: "clarify" }),
         renderScope(opts),
         renderMemories(db, {
             header: "Rules you've already learned (apply directly; do not re-ask the user)",

package/dist/ai/tools/clarify.d.ts

@@ -0,0 +1,2 @@
+import type { ToolModule } from "./types.js";
+export declare const clarifyTools: ToolModule;

package/dist/ai/tools/clarify.js

@@ -0,0 +1,169 @@
+import { deleteTransaction, updateTransaction, updatePosting, } from "../../db/queries/transactions.js";
+import { mergeAccounts } from "../../db/queries/account-balance.js";
+import { linkTransactionToRecurrence, recordRecurrence, } from "../../db/queries/recurrences.js";
+import { sanitizeForPrompt } from "../sanitize.js";
+const DEFS = [
+    {
+        name: "update_transaction",
+        description: "Header-only update: date, description, or source_page. To change amounts, delete the transaction and record a new one.",
+        input_schema: {
+            type: "object",
+            properties: {
+                transaction_id: { type: "string" },
+                date: { type: "string" },
+                description: { type: "string" },
+                source_page: { type: "number" },
+            },
+            required: ["transaction_id"],
+        },
+    },
+    {
+        name: "update_posting",
+        description: "Safe single-posting edit: re-categorize (account_id) or update memo. Refuses changes to debit/credit/currency — delete and re-record the transaction for those.",
+        input_schema: {
+            type: "object",
+            properties: {
+                posting_id: { type: "string" },
+                account_id: { type: "string" },
+                memo: { type: "string" },
+            },
+            required: ["posting_id"],
+        },
+    },
+    {
+        name: "delete_transaction",
+        description: "Delete a transaction and (via cascade) all its postings. The primitive for removing duplicates.",
+        input_schema: {
+            type: "object",
+            properties: { transaction_id: { type: "string" } },
+            required: ["transaction_id"],
+        },
+    },
+    {
+        name: "record_recurrence",
+        description: "Create a recurrences row and link every supplied transaction to it. Computes first_seen_date, last_seen_date, and next_expected_date from the member transactions. Use this after the user confirms a recurrence_candidate question.",
+        input_schema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "string",
+                    description: "The account this recurs on.",
+                },
+                description: {
+                    type: "string",
+                    description: "Human label, e.g. 'Spotify subscription', 'Salary', 'Rent'.",
+                },
+                frequency: {
+                    type: "string",
+                    enum: ["weekly", "biweekly", "monthly", "annually"],
+                },
+                amount_typical: {
+                    type: "number",
+                    description: "Representative amount (typically the matching amount of the member transactions).",
+                },
+                currency: { type: "string", default: "THB" },
+                transaction_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Transaction ids to link to this recurrence.",
+                },
+                notes: {
+                    type: "string",
+                    description: "Optional context the chat agent can read later.",
+                },
+            },
+            required: ["account_id", "description", "frequency", "transaction_ids"],
+        },
+    },
+    {
+        name: "link_transaction_to_recurrence",
+        description: "Attach a single newly-seen transaction to an existing recurrence. Recomputes last_seen_date and next_expected_date on the recurrence.",
+        input_schema: {
+            type: "object",
+            properties: {
+                transaction_id: { type: "string" },
+                recurrence_id: { type: "string" },
+            },
+            required: ["transaction_id", "recurrence_id"],
+        },
+    },
+    {
+        name: "merge_accounts",
+        description: "Move every posting on `from_id` over to `to_id`, then delete the source account. Use to apply a similar_accounts question's 'Merge A into B' resolution. Refuses if the source still has child accounts.",
+        input_schema: {
+            type: "object",
+            properties: { from_id: { type: "string" }, to_id: { type: "string" } },
+            required: ["from_id", "to_id"],
+        },
+    },
+];
+const LABELS = {
+    update_transaction: "Updating transaction",
+    update_posting: "Updating posting",
+    delete_transaction: "Deleting transaction",
+    record_recurrence: "Recording recurrence",
+    link_transaction_to_recurrence: "Linking transaction to recurrence",
+    merge_accounts: "Merging accounts",
+};
+async function execute(db, name, input, _ctx) {
+    switch (name) {
+        case "update_transaction": {
+            const changed = updateTransaction(db, input.transaction_id, {
+                date: input.date,
+                description: input.description,
+                source_page: input.source_page,
+            });
+            return changed === 0
+                ? `Transaction ${input.transaction_id} not found or no fields to update.`
+                : `Updated transaction ${input.transaction_id}.`;
+        }
+        case "update_posting": {
+            const changed = updatePosting(db, input.posting_id, {
+                account_id: input.account_id,
+                memo: input.memo,
+            });
+            return changed === 0
+                ? `Posting ${input.posting_id} not found or no fields to update.`
+                : `Updated posting ${input.posting_id}.`;
+        }
+        case "delete_transaction": {
+            const changed = deleteTransaction(db, input.transaction_id);
+            return changed === 0
+                ? `Transaction ${input.transaction_id} not found.`
+                : `Deleted transaction ${input.transaction_id} and its postings.`;
+        }
+        case "record_recurrence": {
+            try {
+                const id = recordRecurrence(db, {
+                    account_id: input.account_id,
+                    description: input.description,
+                    frequency: input.frequency,
+                    amount_typical: input.amount_typical ?? null,
+                    currency: input.currency,
+                    transaction_ids: input.transaction_ids || [],
+                    notes: input.notes ?? null,
+                });
+                return `Recorded recurrence ${id} ("${sanitizeForPrompt(input.description)}", ${input.frequency}); linked ${(input.transaction_ids || []).length} transaction(s).`;
+            }
+            catch (err) {
+                return `Could not record recurrence: ${err.message}`;
+            }
+        }
+        case "link_transaction_to_recurrence": {
+            try {
+                linkTransactionToRecurrence(db, input.transaction_id, input.recurrence_id);
+                return `Linked transaction ${input.transaction_id} → recurrence ${input.recurrence_id}.`;
+            }
+            catch (err) {
+                return `Could not link: ${err.message}`;
+            }
+        }
+        case "merge_accounts": {
+            const moved = mergeAccounts(db, input.from_id, input.to_id);
+            return `Merged ${input.from_id} → ${input.to_id}; moved ${moved} posting(s).`;
+        }
+        default:
+            return undefined;
+    }
+}
+export const clarifyTools = { DEFS, LABELS, execute };

package/dist/ai/tools/index.js

@@ -1,8 +1,8 @@
 import { commonTools } from "./common.js";
 import { readTools } from "./read.js";
-import { accountIngestTools, scanQuestionTools, resolveIngestTools } from "./ingest.js";
+import { accountIngestTools, scanQuestionTools, clarifyIngestTools } from "./ingest.js";
 import { scanTools } from "./scan.js";
-import { resolveTools } from "./resolve.js";
+import { clarifyTools } from "./clarify.js";
 import { recordTools } from "./record.js";
 import { merchantTools } from "./merchants.js";
 /**
@@ -13,7 +13,7 @@ import { merchantTools } from "./merchants.js";
 const PROFILES = {
     scan: [commonTools, accountIngestTools, scanQuestionTools, scanTools, merchantTools],
     chat: [commonTools, readTools],
-    resolve: [commonTools, readTools, accountIngestTools, resolveIngestTools, resolveTools, merchantTools],
+    clarify: [commonTools, readTools, accountIngestTools, clarifyIngestTools, clarifyTools, merchantTools],
     record: [commonTools, readTools, accountIngestTools, recordTools, merchantTools],
 };
 export function getToolDefinitions(profile) {
@@ -24,9 +24,9 @@ const MODULES = [
     readTools,
     accountIngestTools,
     scanQuestionTools,
-    resolveIngestTools,
+    clarifyIngestTools,
     scanTools,
-    resolveTools,
+    clarifyTools,
     recordTools,
     merchantTools,
 ];
@@ -49,9 +49,9 @@ export const TOOL_LABELS = {
     ...readTools.LABELS,
     ...accountIngestTools.LABELS,
     ...scanQuestionTools.LABELS,
-    ...resolveIngestTools.LABELS,
+    ...clarifyIngestTools.LABELS,
     ...scanTools.LABELS,
-    ...resolveTools.LABELS,
+    ...clarifyTools.LABELS,
     ...recordTools.LABELS,
     ...merchantTools.LABELS,
 };

package/dist/ai/tools/ingest.d.ts

@@ -1,4 +1,4 @@
 import type { ToolModule } from "./types.js";
 export declare const accountIngestTools: ToolModule;
 export declare const scanQuestionTools: ToolModule;
-export declare const resolveIngestTools: ToolModule;
+export declare const clarifyIngestTools: ToolModule;