plasalid 0.8.3 → 0.9.1

package/README.md

@@ -12,6 +12,10 @@
     Turn your scattered financial documents into structured, insightful, AI-readable context.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/plasalid"><img src="https://img.shields.io/npm/v/plasalid.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/plasalid"><img src="https://img.shields.io/npm/dt/plasalid.svg" alt="npm total downloads" /></a>
+</p>
 
 <br />
 
@@ -116,7 +120,7 @@ plasalid clarify                    # Walk every open question and apply your de
                plasalid               
 ```
 
-Two outbound calls: the AI provider during scan, and the AI provider during chat. Both are PII-redacted. Your financial data is never stored off your machine. The same encrypted ledger is open to external AI agents through a local MCP / API server (coming next). No telemetry. No analytics.
+Two main outbound calls: the AI provider during scan, and the AI provider during chat. Both are PII-redacted. Your financial data is never stored off your machine. No telemetry. No analytics.
 
 ## Security & Privacy
 

package/dist/ai/personas.js

@@ -6,7 +6,7 @@
  * Edit a persona's voice or rules here without touching the builders.
  */
 export function chatPersona(name) {
-    return `You are Plasalid ("ปลาสลิด"), ${name}'s second pair of eyes on their own money. You've read every statement ${name} has fed the system — bank, credit card, payslip, brokerage — and you know their accounts, balances, merchants, and recurring rhythms cold. You answer ${name}'s questions about their own ledger by calling the read tools below. Strictly local data — no cloud sync, no third-party aggregator, no figures invented.
+    return `You are Plasalid ("ปลาสลิด"), ${name}'s second pair of eyes on their own money. You've read every statement ${name} has fed the system — bank, credit card, payslip, brokerage — and you know their accounts, balances, merchants, and recurring rhythms cold. You can both read the ledger and edit it: recategorize miscategorized postings, fix bad descriptions, delete duplicates, add manual entries, link merchants. Strictly local data — no cloud sync, no third-party aggregator, no figures invented.
 
 ## How you talk
 - You're not a chatbot and not a help-desk script. You're a direct, honest read of ${name}'s actual situation. Talk like a person who has been watching the money all month, not a customer-service rep.
@@ -22,6 +22,16 @@ export function chatPersona(name) {
 4. For questions about ${name} themselves (family, employer, household, stated goals), 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\`.
 5. Default currency is THB unless an account is explicitly in another. Don't mix currencies in a single total.
 
+## When ${name} states a rule or correction
+When ${name} says something like "X is salary", "those should be food not shopping", "this merchant is rent" — act on it, don't just acknowledge it:
+1. Briefly confirm what you understood ("OK — salary deposits from บริษัท คริปโตมายด์ go to income:salary.").
+2. Preview the blast radius with \`list_postings\` if you're unsure how many past rows are affected.
+3. Call \`bulk_update_postings\` to backfill every matching past posting in one call. For descriptor variants (e.g. truncated names), call it once per variant.
+4. Call \`save_memory\` to persist the natural-language rule for future sessions.
+5. Report the count of rows fixed and the new account. Don't say "I can't rewrite past postings" — you can.
+
+Confirm with ${name} before \`delete_transaction\` or before a \`bulk_update_postings\` that would touch more than ten rows. For amount/currency corrections, \`delete_transaction\` + \`record_transaction\` — never try to silently rewrite amounts on an existing posting (it breaks the double-entry balance).
+
 ## Output rules
 - Reply in the dominant language of ${name}'s message (Thai or English). Match register — terse Thai stays terse in reply.
 - Be concise: 2–4 sentences for simple questions. Skip "Great question!", "Let me look that up.", "I'd be happy to help" and any other preamble.
@@ -132,6 +142,8 @@ 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.
 
+Backfill past data when a correction implies it: if the utterance is a categorization fix that should also rewrite past postings ("the rent payments were going to expense:uncategorized, they're expense:housing"), call bulk_update_postings with a filter that targets the wrong account_id (and merchant_id or description_contains as appropriate) and set.account_id to the right one. Then save_memory the rule. For amount/currency corrections, delete the wrong transaction and record_transaction the right one — never silently rewrite amounts.
+
 When you must confirm (use sparingly — every question costs the user a beat):
 - Ambiguous accounts (above).
 - Missing amount in a transaction utterance.
@@ -176,18 +188,29 @@ In each case, call \`close_question\` with the implied answer and \`related_ques
 
 For each group, call \`ask_user\` ONCE, passing every sibling's id in \`related_question_ids\`. Include "Skip — leave as is" as the last option. After the user answers, apply the mutation(s) the answer implies for every member of the group.
 
-**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.").
+**Step 5 — Finalize.** After every non-skip user answer that resolves the question, apply the implied mutation (e.g. \`update_posting\`, \`merge_accounts\`, \`record_recurrence\`) and \`close_question\` with the user's answer. The pipeline derives a structural rule from the closed question automatically — keyed on merchant id, normalized descriptor, or account pair from the question's stored context — and upserts it into the rules table for the next scan. You do NOT call \`save_memory\` for scanner rules; that path is reserved for general facts, preferences, and life events.
 
-**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.
+For merchant categorization, also call \`set_merchant_default_account\` so the merchant defaults table is updated alongside the structural rule.
 
-**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.
+**The four outcomes (preference order: Resolved > Deferred > Left open > Skipped).** Every question hands off in exactly one of these states. Pick the closest fit; do NOT collapse "I lack info today" into a Skip.
+
+1. **Resolved.** \`close_question(answer=<real answer>)\`. The user gave a concrete answer and you applied the mutation. Synthesizes a structural rule for the next scan.
+2. **Deferred.** \`defer_question(question_id, days=N)\`. You genuinely lack the info today and another scan, another conversation, or the user's own memory may surface it later. The row stays in the table but is hidden from the next \`plasalid clarify\` run for N days. Default N=7. Use shorter (1–2) when the user said "ask me tomorrow" or "let me check"; longer (30+) for genuinely seasonal data (annual statement, year-end review). Prefer Deferred over Skipped whenever the question is still worth answering eventually.
+3. **Left open.** No tool call. The question persists exactly as-is and the next clarify run sees it again. Use sparingly — only when you've taken a real swing at it this run and want the next run to try too, without a specific delay. The converge loop stops cleanly when nothing changes, so leaving rows open does not stall the system.
+4. **Skipped.** \`close_question(answer="Skip — leave as is")\`. The user explicitly said skip, OR the underlying entity is genuinely gone (tool error on an id that no longer exists). One-time recovery decision — does NOT become a rule and will not be replayed. Use this when the right action is "do nothing about this row, ever". This is the **last resort**; if you find yourself reaching for Skip because you ran out of ideas, choose Deferred instead.
+
+**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 — if the underlying entity is genuinely gone — Skip the row (per outcome 4). If the error is transient or you suspect retrying later might succeed, Defer instead. Never close a row whose underlying mutation failed silently.
 
 Question kind → mutation tool map (use after a user answer in step 4):
-- \`uncategorized\` / \`uncategorized_expense\` → \`update_posting(account_id=...)\` for each posting on the transaction. If the transaction has a merchant_id, also \`set_merchant_default_account\`.
+- \`uncategorized\` / \`uncategorized_expense\` → \`update_posting(account_id=...)\` for each posting on the transaction. If the transaction has a merchant_id, also \`set_merchant_default_account\`. The rule stored is "descriptor or merchant → account". When the same descriptor or merchant appears on other past postings still sitting in an uncategorized account, also call \`bulk_update_postings\` once (filter by \`merchant_id\` or \`description_contains\` plus the uncategorized \`account_id\`) so past data matches the rule you just learned — don't leave the user to clean up by hand.
+- \`unknown_merchant\` → confirm the merchant via \`find_or_create_merchant\` so it exists for future scans. The rule stored is "descriptor → merchant canonical name"; the transaction's existing merchant_id stays NULL (re-link via \`plasalid record\` if needed).
+- \`similar_accounts\` → "Merge A into B" / "Merge B into A" → \`merge_accounts(from_id, to_id)\`. "Keep separate" / "Skip" → no mutation. The rule stored is "account-pair → merge direction or keep-separate".
 - \`duplicate\` → "Delete this one" → \`delete_transaction\` on the question's transaction_id. "Delete the older one" → identify the older tx from the prompt body, then \`delete_transaction\`. "Keep both" / "Skip" → no mutation.
 - \`correlation\` → "Merge into one transaction" → \`delete_transaction\` on one side and \`update_posting\` on the other so it reflects the cross-account movement. "Keep separate" / "Skip" → no mutation.
 - \`recurrence_candidate\` → "Link as recurring" → \`record_recurrence\` with the candidate's transaction_ids and the implied frequency. "Not recurring" / "Skip" → no mutation.
-- \`similar_accounts\` → "Merge A into B" / "Merge B into A" → \`merge_accounts(from_id, to_id)\`. "Keep separate" / "Skip" → no mutation.
+- \`dirty_input\` → these are AI-output validation failures (no date, malformed amount). Not auto-resolvable. Close with \`Skip — leave as is\`; the user can re-enter via \`plasalid record\` if the row matters.
+
+**Wiping a whole scanned file.** If the user explicitly asks to redo a file ("this scan came out wrong, drop it and I'll re-scan with a different model", "delete the march statement"), use \`delete_scanned_file(file_id)\`. The cascade removes every transaction and question tied to that file in one shot. Two rules: (1) confirm with the user before calling — cascading deletes are irreversible. (2) Resolve the file by id, not by guess: every question carries a \`file_id\` in its context line; if the user names a file you don't see in the question list, call \`list_scanned_files\` first to find the id. Never call \`delete_scanned_file\` to resolve an individual question — that's what \`close_question\` is for.
 
 How to phrase \`ask_user\`:
 - Use the question's \`prompt\` verbatim (or a tightened version when grouping). Don't restate amounts/dates/accounts in prose — that's what \`facts\` is for.

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

@@ -46,3 +46,13 @@ export interface ScopeOptions {
 export declare function renderScope(opts: ScopeOptions): string;
 /** Chat user context */
 export declare function renderUserContext(name: string, contextMd: string | null): string;
+/** Rules (structured scanner hints) */
+export declare function renderRules(db: Database.Database, header: string): string | null;
+/** Open clarify-questions backlog (chat surface) */
+/**
+ * Emit a discreet hint about open clarify questions when the backlog is
+ * non-empty. The chat agent decides when to mention it based on the user's
+ * message — don't volunteer the count out of context. Returns null when the
+ * backlog is empty so `joinSections` drops the slot entirely.
+ */
+export declare function renderOpenQuestionsHint(db: Database.Database): string | null;

package/dist/ai/prompt-sections.js

@@ -1,4 +1,6 @@
 import { getMemories } from "./memory.js";
+import { listRules } from "../db/queries/rules.js";
+import { countQuestions } from "../db/queries/questions.js";
 import { getAccountBalances, } from "../db/queries/account-balance.js";
 import { stripControls } from "./sanitize.js";
 /**
@@ -105,3 +107,30 @@ function formatMemoryLine(m, showCategory) {
         ? `- [${m.category}] ${stripControls(m.content)}`
         : `- ${stripControls(m.content)}`;
 }
+/** Rules (structured scanner hints) */
+export function renderRules(db, header) {
+    const rules = listRules(db, { limit: 500 });
+    if (rules.length === 0)
+        return null;
+    const lines = rules.map(formatRuleLine);
+    return `## ${header}\n${lines.join("\n")}`;
+}
+function formatRuleLine(r) {
+    return `- [${r.kind}] ${stripControls(r.key)} -> ${stripControls(r.target)}`;
+}
+/** Open clarify-questions backlog (chat surface) */
+/**
+ * Emit a discreet hint about open clarify questions when the backlog is
+ * non-empty. The chat agent decides when to mention it based on the user's
+ * message — don't volunteer the count out of context. Returns null when the
+ * backlog is empty so `joinSections` drops the slot entirely.
+ */
+export function renderOpenQuestionsHint(db) {
+    const n = countQuestions(db);
+    if (n === 0)
+        return null;
+    return [
+        "## Open clarify questions",
+        `There ${n === 1 ? "is 1 open question" : `are ${n} open questions`} in the backlog. Mention this only when the user's message is related (e.g. they ask about uncategorized spending, a specific merchant, or "what's pending"); don't volunteer it otherwise. When you do mention it, suggest \`plasalid clarify\`.`,
+    ].join("\n");
+}

package/dist/ai/system-prompt.js

@@ -2,7 +2,7 @@ import { config } from "../config.js";
 import { readContext } from "./context.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";
+import { renderChartOfAccounts, renderChatChartOrEmpty, renderMemories, renderOpenQuestionsHint, renderRules, renderScope, renderTodayHuman, renderTodayIso, renderUserContext, } from "./prompt-sections.js";
 /**
  * Builders
  *
@@ -17,6 +17,7 @@ export function buildChatSystemPrompt(db) {
         renderTodayHuman(),
         renderUserContext(name, readContext()),
         renderChatChartOrEmpty(db, name),
+        renderOpenQuestionsHint(db),
         renderMemories(db, {
             header: `Things to remember about ${name}`,
             showCategory: true,
@@ -29,8 +30,9 @@ export function buildClarifySystemPrompt(db, opts) {
         renderTodayIso(),
         renderChartOfAccounts(db, { withBalance: true, emptyState: "clarify" }),
         renderScope(opts),
+        renderRules(db, "Rules you've already learned (apply directly; do not re-ask the user)"),
         renderMemories(db, {
-            header: "Rules you've already learned (apply directly; do not re-ask the user)",
+            header: "User memory (general facts, preferences, life events)",
             showCategory: true,
         }),
     ]);
@@ -41,9 +43,10 @@ export function buildRecordSystemPrompt(db, opts) {
         renderTodayIso(),
         renderChartOfAccounts(db, { withBalance: true, emptyState: "scan" }),
         `## What the user said\n> ${opts.utterance.replace(/\n/g, " ")}`,
+        renderRules(db, "Rules you've already learned (apply silently)"),
         renderMemories(db, {
-            header: "Rules you've already learned (apply silently)",
-            filterCategories: ["scanning_hint", "general", "preference"],
+            header: "User memory (general facts, preferences)",
+            filterCategories: ["general", "preference"],
             showCategory: false,
         }),
     ]);
@@ -55,9 +58,10 @@ export function buildScanSystemPrompt(db, opts) {
         renderChartOfAccounts(db, { withBalance: false, emptyState: "scan" }),
         `## File context\nFile: ${opts.fileName}`,
         `## Taxonomy hints\n${getThaiTaxonomyHint()}`,
+        renderRules(db, "Rules you've already learned (apply silently before raising a question)"),
         renderMemories(db, {
-            header: "Rules you've already learned (apply silently before raising a question)",
-            filterCategories: ["scanning_hint", "general"],
+            header: "User memory (general facts)",
+            filterCategories: ["general"],
             showCategory: false,
         }),
     ]);

package/dist/ai/tools/clarify.js

@@ -1,6 +1,7 @@
 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 { deleteScannedFile, listScannedFiles } from "../../db/queries/files.js";
 import { sanitizeForPrompt } from "../sanitize.js";
 const DEFS = [
     {
@@ -96,6 +97,20 @@ const DEFS = [
             required: ["from_id", "to_id"],
         },
     },
+    {
+        name: "list_scanned_files",
+        description: "List every scanned_files row with id, path, status, provider, model, and scanned_at. Use to resolve a file the user mentions by name (e.g. 'drop march-statement.pdf') into a file_id before calling delete_scanned_file. Returns at most 200 rows, newest first.",
+        input_schema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "delete_scanned_file",
+        description: "Delete a scanned_files row by id. Cascades to remove every transaction and question tied to that file (via ON DELETE CASCADE). Use ONLY when the user explicitly wants to drop a file's data so they can re-scan it with a different model — e.g. 'this scan came out wrong, let me redo it'. Never use to resolve a single question; that's `close_question`. Always confirm with the user before calling: cascading deletes are irreversible.",
+        input_schema: {
+            type: "object",
+            properties: { file_id: { type: "string" } },
+            required: ["file_id"],
+        },
+    },
 ];
 const LABELS = {
     update_transaction: "Updating transaction",
@@ -104,6 +119,8 @@ const LABELS = {
     record_recurrence: "Recording recurrence",
     link_transaction_to_recurrence: "Linking transaction to recurrence",
     merge_accounts: "Merging accounts",
+    list_scanned_files: "Listing scanned files",
+    delete_scanned_file: "Deleting scanned file",
 };
 async function execute(db, name, input, _ctx) {
     switch (name) {
@@ -162,6 +179,24 @@ async function execute(db, name, input, _ctx) {
             const moved = mergeAccounts(db, input.from_id, input.to_id);
             return `Merged ${input.from_id} → ${input.to_id}; moved ${moved} posting(s).`;
         }
+        case "list_scanned_files": {
+            const files = listScannedFiles(db).slice(0, 200);
+            if (files.length === 0)
+                return "No scanned files on record.";
+            return files
+                .map(f => {
+                const stamp = f.provider && f.model ? ` [${f.provider}/${f.model}]` : "";
+                const when = f.scanned_at ? ` · ${f.scanned_at}` : "";
+                return `${f.id} | ${sanitizeForPrompt(f.path)} | ${f.status}${stamp}${when}`;
+            })
+                .join("\n");
+        }
+        case "delete_scanned_file": {
+            const result = deleteScannedFile(db, input.file_id);
+            if (!result.removed)
+                return `Scanned file ${input.file_id} not found.`;
+            return `Deleted scanned file ${result.removed.path} (${input.file_id}); cascade removed ${result.removedTransactions} transaction(s) and ${result.removedQuestions} question(s).`;
+        }
         default:
             return undefined;
     }

package/dist/ai/tools/common.js

@@ -22,14 +22,15 @@ const DEFS = [
     },
     {
         name: "save_memory",
-        description: "Persist a fact or bank-specific scanning hint to long-term memory.",
+        description: "Persist a fact, preference, or life-event note to long-term memory. NOT for scanner rules — those are derived structurally from closed questions and live in the rules table.",
         input_schema: {
             type: "object",
             properties: {
                 content: { type: "string", description: "What to remember." },
                 category: {
                     type: "string",
-                    description: "Category: general, scanning_hint, preference, life_event.",
+                    description: "Category: general, preference, life_event.",
+                    enum: ["general", "preference", "life_event"],
                     default: "general",
                 },
             },

package/dist/ai/tools/index.js

@@ -5,6 +5,7 @@ import { scanTools } from "./scan.js";
 import { clarifyTools } from "./clarify.js";
 import { recordTools } from "./record.js";
 import { merchantTools } from "./merchants.js";
+import { mutateTools } from "./mutate.js";
 /**
  * Profile composition. Each profile is the union of one or more tool modules;
  * the dispatcher iterates every module on each tool call so we never need a
@@ -12,9 +13,9 @@ import { merchantTools } from "./merchants.js";
  */
 const PROFILES = {
     scan: [commonTools, accountIngestTools, scanQuestionTools, scanTools, merchantTools],
-    chat: [commonTools, readTools],
-    clarify: [commonTools, readTools, accountIngestTools, clarifyIngestTools, clarifyTools, merchantTools],
-    record: [commonTools, readTools, accountIngestTools, recordTools, merchantTools],
+    chat: [commonTools, readTools, accountIngestTools, clarifyTools, merchantTools, mutateTools],
+    clarify: [commonTools, readTools, accountIngestTools, clarifyIngestTools, clarifyTools, merchantTools, mutateTools],
+    record: [commonTools, readTools, accountIngestTools, recordTools, clarifyTools, merchantTools, mutateTools],
 };
 export function getToolDefinitions(profile) {
     return PROFILES[profile].flatMap(m => m.DEFS);
@@ -29,6 +30,7 @@ const MODULES = [
     clarifyTools,
     recordTools,
     merchantTools,
+    mutateTools,
 ];
 export async function executeTool(db, name, input, ctx) {
     try {
@@ -54,4 +56,5 @@ export const TOOL_LABELS = {
     ...clarifyTools.LABELS,
     ...recordTools.LABELS,
     ...merchantTools.LABELS,
+    ...mutateTools.LABELS,
 };

package/dist/ai/tools/ingest.js

@@ -1,8 +1,9 @@
 import { createAccount, updateAccountMetadata, } from "../../db/queries/account-balance.js";
-import { validateTransaction, insertTransactionRows, recordTransaction, } from "../../db/queries/transactions.js";
-import { recordQuestion } from "../../db/queries/questions.js";
+import { recordTransaction, } from "../../db/queries/transactions.js";
 import { runExclusive as runAccountExclusive } from "./account-mutex.js";
 import { ACCOUNT_TYPE_DESCRIPTIONS } from "../../accounts/taxonomy.js";
+import { recordQuestion } from "../../db/queries/questions.js";
+import { commitTransaction } from "../../scanner/committer.js";
 const ACCOUNT_TYPES = Object.keys(ACCOUNT_TYPE_DESCRIPTIONS);
 const BATCH_MAX = 50;
 const TRANSACTION_ITEM_SCHEMA = {
@@ -264,40 +265,23 @@ function buildTransactionInput(input, ctx) {
         })),
     };
 }
+/**
+ * Thin adapter that wires the agent's execution context into the staged
+ * commit pipeline. The pipeline does best-effort resolution (NULL unknown
+ * merchant, fuzzy-match-or-create unknown account) and only drops a row on
+ * genuine validation failure. Failures raise typed questions rather than
+ * burning a "scan_commit_failure" memory rule.
+ */
 async function persistOneTransaction(db, ctx, txInput) {
-    try {
-        const validated = validateTransaction(txInput);
-        const tx = db.transaction(() => {
-            insertTransactionRows(db, validated);
-        });
-        tx();
-        if (ctx.progress && ctx.chunkId) {
-            ctx.progress.emit({ chunkId: ctx.chunkId, kind: "tx" });
-        }
-        return { ok: true, id: validated.id };
-    }
-    catch (err) {
-        const message = err?.message ?? String(err);
-        if (ctx.scanId) {
-            try {
-                recordQuestion(db, {
-                    file_id: ctx.fileId ?? null,
-                    scan_id: ctx.scanId,
-                    transaction_id: null,
-                    account_id: null,
-                    kind: "scan_commit_failure",
-                    prompt: `Could not record "${txInput.description}" on ${txInput.date}: ${message}. Review the source statement and re-enter via the record flow.`,
-                });
-                if (ctx.progress && ctx.chunkId) {
-                    ctx.progress.emit({ chunkId: ctx.chunkId, kind: "question" });
-                }
-            }
-            catch {
-                // failure to record a failure shouldn't crash the scan
-            }
-        }
-        return { ok: false, error: message };
-    }
+    const outcome = commitTransaction(db, {
+        scanId: ctx.scanId ?? null,
+        fileId: ctx.fileId ?? null,
+        chunkId: ctx.chunkId ?? null,
+        progress: ctx.progress ?? null,
+    }, txInput);
+    if (outcome.ok)
+        return { ok: true, id: outcome.transactionId };
+    return { ok: false, error: outcome.message };
 }
 async function accountExecute(db, name, input, ctx) {
     switch (name) {
@@ -529,14 +513,33 @@ const RESOLVE_DEFS = [
             required: ["question_id", "answer"],
         },
     },
+    {
+        name: "defer_question",
+        description: "Defer a question for `days` days. The row stays in the questions table but is hidden from `plasalid clarify` until the timestamp passes — the next run won't re-encounter it. Use when you genuinely lack info today and a future scan, a future conversation, or the user's own memory might surface the answer later. Prefer this over `close_question(answer=\"Skip — leave as is\")` whenever the question is still worth answering eventually.",
+        input_schema: {
+            type: "object",
+            properties: {
+                question_id: { type: "string" },
+                days: {
+                    type: "number",
+                    description: "Days to defer. Default 7. Use shorter (1-2) when the user said 'ask me tomorrow' or 'let me check'; longer (30+) for genuinely seasonal data like annual statements.",
+                    default: 7,
+                },
+            },
+            required: ["question_id"],
+        },
+    },
 ];
 const RESOLVE_LABELS = {
     ask_user: "Asking for clarification",
     close_question: "Closing question",
+    defer_question: "Deferring question",
 };
 async function clarifyIngestExecute(db, name, input, ctx) {
     if (name === "close_question")
         return closeQuestionTool(db, input, ctx);
+    if (name === "defer_question")
+        return deferQuestionTool(db, input);
     if (name !== "ask_user")
         return undefined;
     if (!ctx)
@@ -567,6 +570,15 @@ async function clarifyIngestExecute(db, name, input, ctx) {
     }
     return `Awaiting user input — cannot proceed in non-interactive mode.`;
 }
+async function deferQuestionTool(db, input) {
+    const { deferQuestion } = await import("../../db/queries/questions.js");
+    const id = String(input.question_id ?? "");
+    if (!id)
+        return "defer_question requires question_id.";
+    const days = Number.isFinite(input.days) ? Math.max(1, Math.floor(input.days)) : 7;
+    const updated = deferQuestion(db, id, days);
+    return updated ? `Deferred question ${id} for ${days} day${days === 1 ? "" : "s"}.` : `Question ${id} not found.`;
+}
 async function closeQuestionTool(db, input, ctx) {
     const { closeQuestion } = await import("../../db/queries/questions.js");
     const primary = String(input.question_id ?? "");

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

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

package/dist/ai/tools/mutate.js

@@ -0,0 +1,81 @@
+import { bulkUpdatePostings, } from "../../db/queries/transactions.js";
+const DEFS = [
+    {
+        name: "bulk_update_postings",
+        description: "Recategorize (and/or re-memo) every posting matching the filter in a single call. " +
+            "Use this when the user confirms a categorization rule for past data " +
+            "(e.g. \"every salary from บริษัท คริปโตมายด์ should be income:salary\"). " +
+            "Pair this with save_memory so the rule also persists for future sessions. " +
+            "For amount/currency corrections, delete the transaction and re-record it instead.",
+        input_schema: {
+            type: "object",
+            properties: {
+                filter: {
+                    type: "object",
+                    description: "At least one field is required.",
+                    properties: {
+                        account_id: {
+                            type: "string",
+                            description: "Current account (e.g. income:uncategorized).",
+                        },
+                        description_contains: {
+                            type: "string",
+                            description: "Case-insensitive substring match against the transaction description. " +
+                                "Use multiple calls for descriptor variants (no regex).",
+                        },
+                        currency: { type: "string" },
+                        from: { type: "string", description: "ISO date (inclusive)." },
+                        to: { type: "string", description: "ISO date (inclusive)." },
+                        merchant_id: { type: "string" },
+                    },
+                },
+                set: {
+                    type: "object",
+                    description: "At least one field is required.",
+                    properties: {
+                        account_id: {
+                            type: "string",
+                            description: "New account_id to assign to every matching posting.",
+                        },
+                        memo: {
+                            type: "string",
+                            description: "New memo to apply to every matching posting.",
+                        },
+                    },
+                },
+            },
+            required: ["filter", "set"],
+        },
+    },
+];
+const LABELS = {
+    bulk_update_postings: "Backfilling postings",
+};
+async function execute(db, name, input, _ctx) {
+    if (name !== "bulk_update_postings")
+        return undefined;
+    try {
+        const filter = (input?.filter ?? {});
+        const set = (input?.set ?? {});
+        const result = bulkUpdatePostings(db, filter, set);
+        if (result.affected === 0) {
+            return "No postings matched the filter; nothing changed.";
+        }
+        const targetSummary = describeSet(set);
+        const sample = result.sample_posting_ids.join(", ");
+        return (`Updated ${result.affected} posting(s) → ${targetSummary}. ` +
+            `Sample ids: ${sample}.`);
+    }
+    catch (err) {
+        return `Could not bulk update postings: ${err?.message ?? String(err)}`;
+    }
+}
+function describeSet(set) {
+    const parts = [];
+    if (set.account_id !== undefined)
+        parts.push(`account_id=${set.account_id}`);
+    if (set.memo !== undefined)
+        parts.push(`memo=${JSON.stringify(set.memo)}`);
+    return parts.join(", ") || "(no changes)";
+}
+export const mutateTools = { DEFS, LABELS, execute };

package/dist/cli/commands/files.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Open the scanned-files browser. The user-facing surface for dropping a
+ * file's data — same `d`-confirm-`y/n` loop as the rules browser, but
+ * typed for scanned_files rows so the layout shows path / status /
+ * provider / model / scanned_at.
+ */
+export declare function showFiles(): Promise<void>;

package/dist/cli/commands/files.js

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import { getDb } from "../../db/connection.js";
+import { listScannedFiles } from "../../db/queries/files.js";
+/**
+ * Open the scanned-files browser. The user-facing surface for dropping a
+ * file's data — same `d`-confirm-`y/n` loop as the rules browser, but
+ * typed for scanned_files rows so the layout shows path / status /
+ * provider / model / scanned_at.
+ */
+export async function showFiles() {
+    const db = getDb();
+    const files = listScannedFiles(db);
+    if (files.length === 0) {
+        console.log("No scanned files yet.\n\n" +
+            chalk.dim("Drop PDFs into ~/.plasalid/data/ and run `plasalid scan`."));
+        return;
+    }
+    const [{ runBrowser }, { FilesBrowser }, { createElement }] = await Promise.all([
+        import("../ink/runBrowser.js"),
+        import("../ink/FilesBrowser.js"),
+        import("react"),
+    ]);
+    await runBrowser(createElement(FilesBrowser, { files, db }));
+}

package/dist/cli/commands/rules.js

@@ -1,29 +1,32 @@
 import chalk from "chalk";
 import { getDb } from "../../db/connection.js";
 import { getMemories, deleteMemory } from "../../ai/memory.js";
+import { listRules, deleteRule } from "../../db/queries/rules.js";
 import { listMerchants, clearMerchantDefaultAccount, } from "../../db/queries/merchants.js";
 export function collectRules(db) {
-    const out = [];
-    for (const m of getMemories(db)) {
-        out.push({
-            displayId: `mem:${m.id}`,
-            text: m.content,
-            forget: (db) => {
-                deleteMemory(db, m.id);
-            },
-        });
-    }
+    return [...collectStructuredRules(db), ...collectMemories(db), ...collectMerchantDefaults(db)];
+}
+function collectStructuredRules(db) {
+    return listRules(db).map((r) => ({
+        displayId: `rule:${r.id}`,
+        text: `[${r.kind}] ${r.key} → ${r.target}`,
+        forget: (db) => { deleteRule(db, r.id); },
+    }));
+}
+function collectMemories(db) {
+    return getMemories(db).map((m) => ({
+        displayId: `mem:${m.id}`,
+        text: m.content,
+        forget: (db) => { deleteMemory(db, m.id); },
+    }));
+}
+function collectMerchantDefaults(db) {
     const merchants = listMerchants(db, { withDefaultOnly: true });
-    merchants.forEach((m, i) => {
-        out.push({
-            displayId: `mch:${i + 1}`,
-            text: `${m.canonical_name} → ${m.default_account_id}`,
-            forget: (db) => {
-                clearMerchantDefaultAccount(db, m.id);
-            },
-        });
-    });
-    return out;
+    return merchants.map((m, i) => ({
+        displayId: `mch:${i + 1}`,
+        text: `${m.canonical_name} → ${m.default_account_id}`,
+        forget: (db) => { clearMerchantDefaultAccount(db, m.id); },
+    }));
 }
 export async function showRules() {
     const db = getDb();