clawbooks 0.1.1 → 0.1.3

package/README.md

@@ -2,22 +2,116 @@
 
 Accounting by inference, not by engine.
 
-An append-only ledger + plain english policy + CLI.
-Your LLM agent reads the data, reads the policy, does the accounting.
+Financial memory for agents.
+
+Clawbooks is an append-only ledger, a plain-English accounting policy, and a CLI.
+Your agent reads the data, reads the policy, and does the accounting.
+
 No rules engine. No SDK. No framework.
 
 **Two source files. Zero runtime dependencies.**
 
-## Setup
+Bring CSVs, Stripe exports, exchange fills, receipts, PDFs, or copied transaction text.
+Your agent reads the source, applies `policy.md`, writes normalized ledger events into clawbooks, and produces statements, summaries, and audit packs from the same record.
+
+## The loop
+
+```text
+Raw inputs
+bank CSVs / Stripe exports / receipts / PDFs / exchange fills / copied text
+  ->
+Agent ingestion
+reads the source + applies policy.md + writes normalized ledger events
+  ->
+Clawbooks ledger
+append-only records + snapshots + verification + context + packs
+  ->
+Agent outputs
+P&L / balance sheet / cash flow / tax views / asset register / audit-ready working files
+  ->
+Policy improvement
+you refine policy.md and the next ingestion/reporting cycle gets better
+```
 
-```bash
-git clone https://github.com/rev1ck/clawbooks.git
-cd clawbooks
-npm install
-npm run build
-cp policy.md.example policy.md   # edit with your own accounting rules
+## Why
+
+Most accounting software assumes the product should contain the accounting logic.
+Clawbooks takes the opposite view:
+
+- the ledger stores facts
+- the policy states the rules in plain English
+- the agent does the reasoning
+
+That makes clawbooks useful anywhere an agent can read files and run shell commands.
+
+## What you get
+
+- Append-only JSONL ledger with hash chaining
+- Plain-English policy file instead of embedded bookkeeping logic
+- CLI commands for recording, reviewing, reconciling, compacting, and packaging records
+- Structured `context` output designed for agent reasoning
+- Zero runtime dependencies
+
+## How ingestion works
+
+Clawbooks does not ship source-specific import logic.
+That is deliberate.
+
+Your agent is the importer:
+
+- bring raw inputs in whatever form you already have
+- the agent reads them and applies `policy.md`
+- the agent converts them into normalized ledger events
+- clawbooks stores the canonical record
+
+This keeps ingestion programmable by policy instead of hardcoded per integration.
+
+## What the agent can produce
+
+With `context`, `summary`, `verify`, `reconcile`, `assets`, and `pack`, your agent can prepare:
+
+- profit and loss statements
+- balance sheets
+- cash flow summaries
+- categorized tax views
+- asset registers and depreciation views
+- audit-ready working packs
+
+Clawbooks supplies durable memory, verification, and repeatable tooling.
+The agent does the accounting work on top of that foundation.
+
+## Boundaries
+
+You and your agent:
+
+- write and refine `policy.md`
+- ingest source documents and convert them into ledger events
+- interpret edge cases
+- review outputs and improve the policy over time
+
+clawbooks:
+
+- stores append-only financial records
+- preserves snapshots and audit history
+- provides structured context for the agent
+- verifies integrity and reconciliation surfaces
+- packages records for downstream review and reporting
+
+As `policy.md` gets better, your ingestion, classification, and reporting get better too.
+
+## Example
+
+```text
+You: "What's my P&L for March?"
+
+Agent runs:    clawbooks context 2026-03
+Agent reads:   policy + snapshot + events
+Agent reasons: applies the policy to the records
+Agent replies: "Revenue: $1,700. Expenses: $475. Net: $1,225."
 ```
 
+There is no accounting engine. In clawbooks, the agent is the engine.
+
 ## Install
 
 ```bash
@@ -26,32 +120,20 @@ clawbooks --help
 cp policy.md.example policy.md
 ```
 
-## Scoped Package Readiness
-
-The primary package should stay `clawbooks` for the clean install path.
-If you later want a brand-owned scoped companion package, the repo can stage `@clawbooks/cli` without renaming the live package:
+## Local setup
 
 ```bash
-npm run scoped:prepare
-npm run scoped:pack:dry-run
+git clone https://github.com/rev1ck/clawbooks.git
+cd clawbooks
+npm install
+npm run build
+cp policy.md.example policy.md   # edit with your own accounting rules
 ```
 
-This writes a temporary scoped package into `.dist/scoped-cli` for inspection or future publish work.
-
 ## How it works
 
-Clawbooks stores financial events and outputs context. The LLM you're already talking to does the accounting.
-
-```
-You: "What's my P&L for March?"
-
-Agent runs:    clawbooks context 2026-03
-Agent reads:   policy + events
-Agent thinks:  *applies policy to events*
-Agent responds: "Revenue: $1,700. Expenses: $475. Net: $1,225."
-```
-
-There is no accounting engine. The LLM *is* the engine.
+Clawbooks stores financial events and outputs accounting context.
+The important command is `clawbooks context`: it prints a structured context envelope with metadata, instructions, policy, summary, snapshot, and raw events so an agent can reason from both overview and detail.
 
 ## Commands
 
@@ -70,13 +152,17 @@ clawbooks context 2026-03
 clawbooks context --after 2026-01-01
 
 # Analysis
-clawbooks verify 2026-03                          # integrity + chain + duplicates
-clawbooks verify --balance 50000 --currency USD    # cross-check closing balance
+clawbooks verify 2026-03                            # integrity + chain + duplicates
+clawbooks verify --balance 50000 --currency USD     # cross-check closing balance
 clawbooks reconcile 2026-03 --source bank --count 50 --debits -12000 --gaps
-clawbooks review --source bank                     # items needing classification
-clawbooks summary 2026-03                          # aggregates for reports
-clawbooks snapshot 2026-03 --save                  # persist period snapshot
-clawbooks assets --as-of 2026-03-31                # asset register + depreciation
+clawbooks review --source bank                      # items needing classification
+clawbooks summary 2026-03                           # aggregates for reports
+clawbooks snapshot 2026-03 --save                   # persist period snapshot
+clawbooks assets --as-of 2026-03-31                 # asset register + depreciation
+
+# Maintenance
+clawbooks compact 2025-12                           # archive old events, shrink ledger
+clawbooks pack 2026-03 --out ./march-pack           # generate audit pack (CSVs + JSON)
 
 # Print the policy
 clawbooks policy
@@ -84,37 +170,72 @@ clawbooks policy
 
 ## The context command
 
-This is the important one. It outputs your accounting policy + the latest snapshot + all events in a period, wrapped in XML tags. The agent reads this output and reasons over it.
+This is the core command. It prints a `context` envelope for the requested period:
+
+- `metadata` explains the requested and effective window, whether a snapshot was used, and what kinds of records are present
+- `instructions` tells the agent how to interpret snapshot plus events
+- `policy` is your plain-English accounting policy
+- `summary` provides orientation before the raw records
+- `snapshot` is the starting state, when available
+- `events` contains the raw append-only records the agent should reason from
 
 ```bash
 $ clawbooks context 2026-03
 
+<context schema="clawbooks.context.v2">
+<metadata>
+{
+  "requested_window": {"after":"2026-03-01T00:00:00.000Z","before":"2026-03-31T23:59:59.999Z"},
+  "effective_window": {"after":"2026-03-01T00:00:00.000Z","before":"2026-03-31T23:59:59.999Z"},
+  "snapshot": {"used": true, "ts":"2026-03-01T00:00:00.000Z"},
+  "event_count": 47,
+  "sources": ["bank", "stripe"],
+  "currencies": ["USD"]
+}
+</metadata>
+
+<instructions>
+Read the policy first.
+Treat the snapshot as the starting state.
+Apply the events block on top of that snapshot.
+</instructions>
+
 <policy>
 # Accounting policy
 Cash basis. Crypto trades are revenue income...
 </policy>
 
-<snapshot as_of="2026-03-01">
-{"balances":{"USDC":45000},"ytd_pnl":18450}
+<summary>
+{
+  "by_type": {"income":{"count":12,"total":1700},"fee":{"count":3,"total":-55}},
+  "by_currency": {"USD":{"count":15,"total":1645}},
+  "cash_flow": {"inflows":1700,"outflows":-55,"net":1645}
+}
+</summary>
+
+<snapshot as_of="2026-03-01T00:00:00.000Z">
+{"balances":{"USD":45000},"ytd_pnl":18450}
 </snapshot>
 
-<events count="47" after="2026-03-01" before="2026-03-31">
+<events count="47" after="2026-03-01T00:00:00.000Z" before="2026-03-31T23:59:59.999Z">
 {"ts":"...","source":"stripe","type":"payment","data":{"amount":500,...}}
 {"ts":"...","source":"bank","type":"fee","data":{"amount":-55,...}}
 ...
 </events>
+</context>
 ```
 
 ## Importing data
 
-There is no import command. Your agent IS the importer.
+There is no import command. The agent is the importer.
 
-```
+```text
 You: [paste CSV] "Import this bank statement"
 
-Agent: *reads CSV, reads policy via `clawbooks policy`*
-       *classifies each row per the policy*
-       *outputs JSONL, pipes to `clawbooks batch`*
+Agent: reads the CSV
+       reads policy via `clawbooks policy`
+       classifies each row per the policy
+       outputs JSONL and pipes it to `clawbooks batch`
 
 Agent: "Recorded 47 events from Chase March statement."
 ```
@@ -134,22 +255,57 @@ clawbooks assets --as-of 2026-03-31
 clawbooks record '{"source":"manual","type":"disposal","data":{"asset_id":"<id>","proceeds":5000,"currency":"USD"}}'
 ```
 
+## Scaling
+
+When the ledger grows large, compact old periods into an archive:
+
+```bash
+clawbooks compact 2025-12
+# -> archives old events to ledger-archive-2025-12-31.jsonl
+# -> rewrites the main ledger as: 1 snapshot + newer events
+```
+
+The archive remains a complete hash-chained ledger for audits. The main ledger stays small enough for agent context windows.
+
+## Audit packs
+
+Generate a folder of standard-format files for accountants or auditors:
+
+```bash
+clawbooks pack 2026-01/2026-12-31 --out ./annual-pack
+```
+
+This produces `general_ledger.csv`, `summary.json`, `asset_register.csv`, `reclassifications.csv`, `verify.json`, and a copy of `policy.md`.
+The output is assistive. It gives an accountant structured working material, not a pretend finished report.
+
 ## Agent setup
 
-Point your agent at `program.md` for instructions on how to use clawbooks. For example:
+Point your agent at `program.md` for instructions on how to use clawbooks.
 
-- **Claude Code** — add to your `CLAUDE.md`: `Read program.md in the clawbooks directory for financial record-keeping instructions.`
-- **Codex** — add to your `AGENTS.md` or system prompt with the same pointer
-- **Any agent** — any agent that can shell out can use clawbooks. The CLI outputs structured text. The agent reads it and reasons.
+- **Claude Code**: add `Read program.md in the clawbooks directory for financial record-keeping instructions.`
+- **Codex**: add the same pointer in `AGENTS.md` or your system prompt
+- **Any shell-capable agent**: clawbooks prints structured text for the agent to read and reason over
 
-The npm package includes `program.md` plus all policy examples, so this workflow also works from a global install.
+The npm package includes `program.md` and the policy examples, so this workflow also works from a global install.
 
-## Files
+## Packaging
+
+The primary package should stay `clawbooks` for the clean install path.
+If you later want a brand-owned scoped companion package, the repo can stage `@clawbooks/cli` without renaming the live package:
 
+```bash
+npm run scoped:prepare
+npm run scoped:pack:dry-run
 ```
+
+This writes a temporary scoped package into `.dist/scoped-cli` for inspection or future publish work.
+
+## Files
+
+```text
 cli.ts                  CLI commands
 ledger.ts               JSONL read/write/filter
-program.md              Agent instructions (how to use clawbooks)
+program.md              Agent instructions
 policy.md               Your accounting rules (you write this, gitignored)
 policy.md.example       Example policy to start from
 ledger.jsonl            Your financial events (append-only, gitignored)
@@ -162,7 +318,7 @@ ledger.jsonl            Your financial events (append-only, gitignored)
 | `CLAWBOOKS_LEDGER` | `./ledger.jsonl` | Path to ledger |
 | `CLAWBOOKS_POLICY` | `./policy.md` | Path to policy |
 
-No API key needed. The agent brings its own LLM.
+No API key needed. Bring your own agent.
 
 ## License
 

package/build/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { readFileSync, existsSync } from "node:fs";
-import { computeId, readAll, filter, append, hashLine, latestSnapshot, } from "./ledger.js";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { computeId, readAll, filter, append, hashLine, rewrite, latestSnapshot, } from "./ledger.js";
 const LEDGER = process.env.CLAWBOOKS_LEDGER ?? "./ledger.jsonl";
 const POLICY = process.env.CLAWBOOKS_POLICY ?? "./policy.md";
 const OUTFLOW_TYPES = new Set([
@@ -106,6 +106,109 @@ function periodFromArgs(args) {
 function round2(n) {
     return Math.round(n * 100) / 100;
 }
+function buildReclassifyMap(events) {
+    const reclassifyMap = {};
+    for (const e of events) {
+        if (e.type === "reclassify" && e.data.original_id && e.data.new_category) {
+            reclassifyMap[String(e.data.original_id)] = String(e.data.new_category);
+        }
+    }
+    return reclassifyMap;
+}
+function reviewCounts(events, all) {
+    const reclassified = new Set(all.filter((e) => e.type === "reclassify").map((e) => String(e.data.original_id)));
+    const counts = { unclear: 0, inferred: 0, unset: 0, clear: 0 };
+    for (const e of events) {
+        if (e.type === "reclassify" || e.type === "snapshot" || reclassified.has(e.id))
+            continue;
+        const confidence = String(e.data.confidence ?? "unset");
+        if (confidence === "clear")
+            counts.clear++;
+        else if (confidence === "unclear")
+            counts.unclear++;
+        else if (confidence === "inferred")
+            counts.inferred++;
+        else
+            counts.unset++;
+    }
+    return counts;
+}
+function buildContextSummary(events, all) {
+    const reclassifyMap = buildReclassifyMap(all);
+    const byType = {};
+    const bySource = {};
+    const byCurrency = {};
+    const byCategory = {};
+    const eventTypes = new Set();
+    const sources = new Set();
+    const currencies = new Set();
+    let inflows = 0;
+    let outflows = 0;
+    let nonMetaEvents = 0;
+    let rawReclassifications = 0;
+    for (const e of events) {
+        eventTypes.add(e.type);
+        sources.add(e.source);
+        if (e.type === "reclassify")
+            rawReclassifications++;
+        if (META_TYPES.has(e.type))
+            continue;
+        nonMetaEvents++;
+        const amount = Number(e.data.amount);
+        const currency = String(e.data.currency ?? "UNKNOWN");
+        const category = reclassifyMap[e.id] ?? String(e.data.category ?? e.type);
+        currencies.add(currency);
+        if (!byType[e.type])
+            byType[e.type] = { count: 0, total: 0 };
+        byType[e.type].count++;
+        if (!bySource[e.source])
+            bySource[e.source] = { count: 0, total: 0 };
+        bySource[e.source].count++;
+        if (!byCurrency[currency])
+            byCurrency[currency] = { count: 0, total: 0 };
+        byCurrency[currency].count++;
+        if (!byCategory[category])
+            byCategory[category] = { count: 0, total: 0 };
+        byCategory[category].count++;
+        if (isNaN(amount))
+            continue;
+        byType[e.type].total = round2(byType[e.type].total + amount);
+        bySource[e.source].total = round2(bySource[e.source].total + amount);
+        byCurrency[currency].total = round2(byCurrency[currency].total + amount);
+        byCategory[category].total = round2(byCategory[category].total + amount);
+        if (amount > 0)
+            inflows = round2(inflows + amount);
+        else
+            outflows = round2(outflows + amount);
+    }
+    const confidence = reviewCounts(events, all);
+    const needsReview = confidence.unclear + confidence.inferred + confidence.unset;
+    const reclassifiedEventCount = events.filter((e) => reclassifyMap[e.id] !== undefined).length;
+    return {
+        event_count: events.length,
+        non_meta_event_count: nonMetaEvents,
+        event_types: [...eventTypes].sort(),
+        sources: [...sources].sort(),
+        currencies: [...currencies].sort(),
+        by_type: byType,
+        by_source: bySource,
+        by_currency: byCurrency,
+        by_category: byCategory,
+        cash_flow: {
+            inflows: round2(inflows),
+            outflows: round2(outflows),
+            net: round2(inflows + outflows),
+        },
+        reclassifications: {
+            raw_events_in_window: rawReclassifications,
+            applied_to_events_in_window: reclassifiedEventCount,
+        },
+        review: {
+            needs_review: needsReview,
+            by_confidence: confidence,
+        },
+    };
+}
 function enforceSign(type, data) {
     if (data.amount === undefined)
         return;
@@ -228,11 +331,62 @@ function cmdContext(args) {
     const snapshot = latestSnapshot(all, after);
     const effectiveAfter = snapshot?.ts ?? after;
     const events = filter(all, { after: effectiveAfter, before }).filter((e) => e.type !== "snapshot");
+    const summary = buildContextSummary(events, all);
+    const metadata = {
+        schema_version: "clawbooks.context.v2",
+        generated_at: new Date().toISOString(),
+        ledger_path: LEDGER,
+        policy_path: POLICY,
+        requested_window: {
+            after: after ?? "all",
+            before: before ?? "now",
+        },
+        effective_window: {
+            after: effectiveAfter ?? "all",
+            before: before ?? "now",
+        },
+        snapshot: snapshot ? {
+            used: true,
+            ts: snapshot.ts,
+            source: snapshot.source,
+            id: snapshot.id,
+            event_count: Number(snapshot.data.event_count ?? 0),
+        } : {
+            used: false,
+        },
+        event_count: events.length,
+        sources: summary.sources,
+        event_types: summary.event_types,
+        currencies: summary.currencies,
+    };
     // Output structured context for the agent
+    console.log(`<context schema="clawbooks.context.v2">`);
+    console.log(`<metadata>`);
+    console.log(JSON.stringify(metadata, null, 2));
+    console.log(`</metadata>`);
+    console.log();
+    console.log(`<instructions>`);
+    console.log(`Read the policy first.`);
+    if (snapshot) {
+        console.log(`Treat the snapshot as the starting state up to its as_of timestamp.`);
+        console.log(`Apply the events block on top of that snapshot to answer the user's question.`);
+    }
+    else {
+        console.log(`No snapshot is present for this window, so reason directly from the events block.`);
+    }
+    console.log(`Prefer the summary block for orientation, but use raw events for final reasoning and edge cases.`);
+    console.log(`Reclassify events are append-only corrections; use them when interpreting categories.`);
+    console.log(`Amounts are signed: inflows are positive, outflows are negative for known flow types.`);
+    console.log(`</instructions>`);
+    console.log();
     console.log(`<policy>`);
     console.log(policyText());
     console.log(`</policy>`);
     console.log();
+    console.log(`<summary>`);
+    console.log(JSON.stringify(summary, null, 2));
+    console.log(`</summary>`);
+    console.log();
     if (snapshot) {
         console.log(`<snapshot as_of="${snapshot.ts}">`);
         console.log(JSON.stringify(snapshot.data, null, 2));
@@ -243,6 +397,7 @@ function cmdContext(args) {
     for (const e of events)
         console.log(JSON.stringify(e));
     console.log(`</events>`);
+    console.log(`</context>`);
 }
 function cmdPolicy() {
     console.log(policyText());
@@ -762,6 +917,279 @@ function cmdAssets(args) {
         },
     }, null, 2));
 }
+function cmdCompact(args) {
+    const f = flags(args);
+    const { before } = periodFromArgs(args);
+    if (!before) {
+        console.error("Usage: clawbooks compact <period> or --before <date>");
+        console.error("  Moves events before the cutoff to an archive file and saves a snapshot.");
+        console.error("  Example: clawbooks compact 2025-12");
+        process.exit(1);
+    }
+    const all = readAll(LEDGER);
+    const keep = all.filter((e) => e.ts > before);
+    const archive = all.filter((e) => e.ts <= before);
+    if (archive.length === 0) {
+        console.log(JSON.stringify({ compacted: false, reason: "no events before cutoff" }));
+        return;
+    }
+    // Build snapshot of archived events
+    const balances = {};
+    const byCategory = {};
+    const pnl = {};
+    let eventCount = 0;
+    for (const e of archive) {
+        if (META_TYPES.has(e.type))
+            continue;
+        const amount = Number(e.data.amount);
+        if (isNaN(amount))
+            continue;
+        eventCount++;
+        const currency = String(e.data.currency ?? "UNKNOWN");
+        const category = String(e.data.category ?? e.type);
+        balances[currency] = round2((balances[currency] ?? 0) + amount);
+        byCategory[category] = round2((byCategory[category] ?? 0) + amount);
+        if (!pnl[currency])
+            pnl[currency] = { income: 0, expenses: 0, tax: 0, net: 0 };
+        if (e.type === "income")
+            pnl[currency].income = round2(pnl[currency].income + amount);
+        else if (e.type === "tax_payment")
+            pnl[currency].tax = round2(pnl[currency].tax + amount);
+        else if (OUTFLOW_TYPES.has(e.type))
+            pnl[currency].expenses = round2(pnl[currency].expenses + amount);
+        pnl[currency].net = round2(pnl[currency].net + amount);
+    }
+    const snapshotData = {
+        period: { after: "all", before },
+        event_count: eventCount,
+        balances,
+        by_category: byCategory,
+        pnl,
+        compacted_from: archive.length,
+    };
+    const ts = before;
+    const snapshotEvent = {
+        ts,
+        source: "clawbooks:compact",
+        type: "snapshot",
+        data: snapshotData,
+        id: computeId(snapshotData, {
+            source: "clawbooks:compact", type: "snapshot", ts,
+        }),
+        prev: "",
+    };
+    // Write archive
+    const archivePath = f.archive ?? LEDGER.replace(".jsonl", `-archive-${before.slice(0, 10)}.jsonl`);
+    rewrite(archivePath, archive);
+    // Rewrite main ledger: snapshot + remaining events
+    rewrite(LEDGER, [snapshotEvent, ...keep]);
+    console.log(JSON.stringify({
+        compacted: true,
+        archived: archive.length,
+        archive_path: archivePath,
+        snapshot_id: snapshotEvent.id,
+        remaining: keep.length + 1,
+    }, null, 2));
+}
+function csvEscape(val) {
+    if (val.includes(",") || val.includes('"') || val.includes("\n")) {
+        return '"' + val.replace(/"/g, '""') + '"';
+    }
+    return val;
+}
+function cmdPack(args) {
+    const f = flags(args);
+    const { after, before } = periodFromArgs(args);
+    const outDir = f.out ?? `./audit-pack-${(before ?? new Date().toISOString()).slice(0, 10)}`;
+    const all = readAll(LEDGER);
+    const events = filter(all, { after, before, source: f.source });
+    mkdirSync(outDir, { recursive: true });
+    // --- general_ledger.csv ---
+    const glHeader = "date,source,type,category,description,amount,currency,confidence,id";
+    const glRows = events
+        .filter((e) => !META_TYPES.has(e.type))
+        .map((e) => [
+        e.ts.slice(0, 10),
+        csvEscape(e.source),
+        e.type,
+        csvEscape(String(e.data.category ?? "")),
+        csvEscape(String(e.data.description ?? "")),
+        String(e.data.amount ?? ""),
+        String(e.data.currency ?? ""),
+        String(e.data.confidence ?? ""),
+        e.id,
+    ].join(","));
+    writeFileSync(`${outDir}/general_ledger.csv`, [glHeader, ...glRows].join("\n") + "\n", "utf-8");
+    // --- reclassifications.csv ---
+    const reclassEvents = all.filter((e) => e.type === "reclassify");
+    if (reclassEvents.length > 0) {
+        const rcHeader = "date,original_id,new_category,new_type,reason";
+        const rcRows = reclassEvents.map((e) => [
+            e.ts.slice(0, 10),
+            String(e.data.original_id ?? ""),
+            csvEscape(String(e.data.new_category ?? "")),
+            csvEscape(String(e.data.new_type ?? "")),
+            csvEscape(String(e.data.reason ?? "")),
+        ].join(","));
+        writeFileSync(`${outDir}/reclassifications.csv`, [rcHeader, ...rcRows].join("\n") + "\n", "utf-8");
+    }
+    // --- summary.json ---
+    // Build reclassification map
+    const reclassifyMap = {};
+    for (const e of all) {
+        if (e.type === "reclassify" && e.data.original_id && e.data.new_category) {
+            reclassifyMap[String(e.data.original_id)] = String(e.data.new_category);
+        }
+    }
+    const byType = {};
+    const byCategory = {};
+    const byCurrency = {};
+    let inflows = 0, outflows = 0;
+    for (const e of events) {
+        if (META_TYPES.has(e.type))
+            continue;
+        const amount = Number(e.data.amount);
+        if (isNaN(amount))
+            continue;
+        const type = e.type;
+        const category = reclassifyMap[e.id] ?? String(e.data.category ?? e.type);
+        const currency = String(e.data.currency ?? "UNKNOWN");
+        if (!byType[type])
+            byType[type] = { count: 0, total: 0 };
+        byType[type].count++;
+        byType[type].total = round2(byType[type].total + amount);
+        if (!byCategory[category])
+            byCategory[category] = { count: 0, total: 0 };
+        byCategory[category].count++;
+        byCategory[category].total = round2(byCategory[category].total + amount);
+        if (!byCurrency[currency])
+            byCurrency[currency] = { count: 0, total: 0 };
+        byCurrency[currency].count++;
+        byCurrency[currency].total = round2(byCurrency[currency].total + amount);
+        if (amount > 0)
+            inflows = round2(inflows + amount);
+        else
+            outflows = round2(outflows + amount);
+    }
+    writeFileSync(`${outDir}/summary.json`, JSON.stringify({
+        period: { after: after ?? "all", before: before ?? "now" },
+        by_type: byType,
+        by_category: byCategory,
+        by_currency: byCurrency,
+        cash_flow: { inflows, outflows, net: round2(inflows + outflows) },
+    }, null, 2) + "\n", "utf-8");
+    // --- asset_register.csv ---
+    const capitalizedEvents = all.filter((e) => e.data.capitalize === true);
+    if (capitalizedEvents.length > 0) {
+        const disposals = {};
+        const writeOffsMap = {};
+        const impairmentsMap = {};
+        for (const e of all) {
+            const aid = String(e.data.asset_id ?? "");
+            if (!aid)
+                continue;
+            if (e.type === "disposal")
+                disposals[aid] = e;
+            else if (e.type === "write_off")
+                writeOffsMap[aid] = e;
+            else if (e.type === "impairment") {
+                if (!impairmentsMap[aid])
+                    impairmentsMap[aid] = [];
+                impairmentsMap[aid].push(e);
+            }
+        }
+        const asOf = before ?? new Date().toISOString();
+        const defaultLife = 36;
+        const arHeader = "date,description,category,cost,currency,useful_life,monthly_dep,months_elapsed,acc_dep,impairment,nbv,status,proceeds,gain_loss,id";
+        const arRows = capitalizedEvents.map((e) => {
+            const amount = Math.abs(Number(e.data.amount));
+            const lifeMonths = Number(e.data.useful_life_months) || defaultLife;
+            const purchaseDate = new Date(e.ts);
+            const reportDate = new Date(asOf);
+            const monthsElapsed = Math.max(0, (reportDate.getFullYear() - purchaseDate.getFullYear()) * 12 +
+                (reportDate.getMonth() - purchaseDate.getMonth()));
+            const monthlyDep = round2(amount / lifeMonths);
+            const accDep = round2(Math.min(amount, monthlyDep * monthsElapsed));
+            let impTotal = 0;
+            if (impairmentsMap[e.id]) {
+                for (const imp of impairmentsMap[e.id]) {
+                    impTotal = round2(impTotal + Math.abs(Number(imp.data.impairment_amount) || 0));
+                }
+            }
+            const nbv = round2(Math.max(0, amount - accDep - impTotal));
+            let status = "active";
+            let proceeds = "";
+            let gainLoss = "";
+            if (disposals[e.id]) {
+                status = "disposed";
+                const p = Number(disposals[e.id].data.proceeds) || 0;
+                proceeds = String(p);
+                gainLoss = String(round2(p - nbv));
+            }
+            else if (writeOffsMap[e.id]) {
+                status = "written_off";
+                gainLoss = String(round2(-nbv));
+            }
+            return [
+                e.ts.slice(0, 10),
+                csvEscape(String(e.data.description ?? "")),
+                csvEscape(String(e.data.category ?? "")),
+                String(amount),
+                String(e.data.currency ?? ""),
+                String(lifeMonths),
+                String(monthlyDep),
+                String(Math.min(monthsElapsed, lifeMonths)),
+                String(accDep),
+                String(impTotal),
+                status === "active" ? String(nbv) : "0",
+                status,
+                proceeds,
+                gainLoss,
+                e.id,
+            ].join(",");
+        });
+        writeFileSync(`${outDir}/asset_register.csv`, [arHeader, ...arRows].join("\n") + "\n", "utf-8");
+    }
+    // --- verify.json ---
+    const hash = createHash("sha256").update(events.map((e) => e.id).join(",")).digest("hex");
+    let debits = 0, credits = 0;
+    const issues = [];
+    for (const e of events) {
+        const amount = Number(e.data.amount);
+        if (e.data.amount !== undefined && !isNaN(amount)) {
+            if (amount < 0)
+                debits = round2(debits + amount);
+            else
+                credits = round2(credits + amount);
+            if (OUTFLOW_TYPES.has(e.type) && amount > 0)
+                issues.push(`${e.id}: outflow "${e.type}" positive ${amount}`);
+            if (INFLOW_TYPES.has(e.type) && amount < 0)
+                issues.push(`${e.id}: inflow "${e.type}" negative ${amount}`);
+        }
+    }
+    writeFileSync(`${outDir}/verify.json`, JSON.stringify({
+        event_count: events.length, debits, credits, hash, issues,
+        generated: new Date().toISOString(),
+    }, null, 2) + "\n", "utf-8");
+    // --- policy.md ---
+    if (existsSync(POLICY)) {
+        writeFileSync(`${outDir}/policy.md`, readFileSync(POLICY, "utf-8"), "utf-8");
+    }
+    // Summary output
+    const files = ["general_ledger.csv", "summary.json", "verify.json"];
+    if (reclassEvents.length > 0)
+        files.push("reclassifications.csv");
+    if (capitalizedEvents.length > 0)
+        files.push("asset_register.csv");
+    if (existsSync(POLICY))
+        files.push("policy.md");
+    console.log(JSON.stringify({
+        pack: outDir,
+        period: { after: after ?? "all", before: before ?? "now" },
+        events: events.length,
+        files,
+    }, null, 2));
+}
 // --- Help ---
 const HELP = `clawbooks — accounting by inference, not by engine.
 
@@ -782,6 +1210,9 @@ Analysis commands:
   snapshot  [period] [--save]              Compute period snapshot (balances, P&L)
   assets    [--category C] [--life N] [--as-of DATE]
                                            Asset register (capitalize-flag based) with depreciation
+  compact   <period> [--archive PATH]     Archive old events, save snapshot, shrink ledger
+  pack      [period] [--source S] [--out DIR]
+                                           Generate audit pack (CSVs + JSON + policy)
 
 Common flags:
   --after  <ISO date>         Events after this date
@@ -828,6 +1259,8 @@ Examples:
   clawbooks summary 2026-03
   clawbooks snapshot 2026-03 --save
   clawbooks assets --as-of 2026-03-31
+  clawbooks compact 2025-12
+  clawbooks pack 2026-03 --out ./march-pack
 
 Agent workflow:
   1. Agent runs: clawbooks context 2026-03
@@ -877,5 +1310,11 @@ switch (cmd) {
     case "assets":
         cmdAssets(args);
         break;
+    case "compact":
+        cmdCompact(args);
+        break;
+    case "pack":
+        cmdPack(args);
+        break;
     default: console.log(HELP);
 }

package/build/ledger.js

@@ -52,6 +52,17 @@ export function append(path, event) {
     appendFileSync(path, JSON.stringify(event) + "\n", "utf-8");
     return true;
 }
+export function rewrite(path, events) {
+    let prev = "genesis";
+    const lines = [];
+    for (const e of events) {
+        e.prev = prev;
+        const line = JSON.stringify(e);
+        prev = hashLine(line);
+        lines.push(line);
+    }
+    writeFileSync(path, lines.join("\n") + (lines.length ? "\n" : ""), "utf-8");
+}
 export function latestSnapshot(events, before) {
     let snapshots = events.filter((e) => e.type === "snapshot");
     if (before)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawbooks",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Accounting by inference, not by engine. Zero dependencies.",
   "type": "module",
   "repository": {

package/program.md

@@ -113,12 +113,13 @@ Reduces carrying value by the impairment amount. Multiple impairments can accumu
 
 When asked for a P&L, tax summary, balance, etc.:
 
-1. Run `clawbooks summary <period>` for pre-computed aggregates
+1. **Start with `summary`**, not `context`. `clawbooks summary <period>` gives you pre-computed aggregates without loading every event into context.
 2. Map the output to the requested report:
    - **P&L**: `by_type` + `by_category` → Revenue - OpEx = Gross Profit - Tax = Net
    - **Balance Sheet**: `cash_flow.net` + opening balance (from snapshot or opening_balance events) → Assets. Capitalized assets from `clawbooks assets`. Equity = Assets - Liabilities
    - **Cash Flow Statement**: Map categories to Operating/Investing/Financing per policy
-3. For details or edge cases, also run `clawbooks context <period>` and reason over raw events
+3. Only use `clawbooks context <period>` when you need to drill into individual events — e.g., investigating a specific transaction, answering "what was that $500 charge?", or debugging a reconciliation mismatch.
+4. For large ledgers, use `clawbooks pack <period>` to generate a full audit pack (CSVs + JSON) that you or an accountant can review outside the agent.
 
 ## Reconciliation workflow
 
@@ -159,6 +160,42 @@ clawbooks snapshot 2026-03          # compute and print (no save)
 
 The snapshot includes balances by currency, totals by category, and P&L by currency.
 
+## Compacting the ledger
+
+When the ledger grows large (thousands of events), compact old periods into an archive:
+
+```bash
+clawbooks compact 2025-12
+```
+
+This:
+1. Saves a snapshot summarizing all events up to the cutoff
+2. Moves those events to `ledger-archive-2025-12-31.jsonl`
+3. Rewrites the main ledger with just the snapshot + newer events
+
+The archive file is a complete, hash-chained ledger — it can be re-read for audits. The main ledger stays small for fast context loading.
+
+Compact aggressively for busy ledgers. Monthly or quarterly compaction keeps context manageable.
+
+## Audit packs
+
+Generate a folder of CSVs and JSON for accountants, auditors, or your own review:
+
+```bash
+clawbooks pack 2026-03                      # pack a single month
+clawbooks pack 2026-01/2026-12-31 --out ./annual-pack   # pack a full year
+```
+
+The pack includes:
+- `general_ledger.csv` — every transaction with date, source, type, category, description, amount, currency, confidence, id
+- `summary.json` — aggregates by type, category, currency, and cash flow
+- `asset_register.csv` — capitalized assets with depreciation, disposal, write-off status (if any)
+- `reclassifications.csv` — all reclassification events (if any)
+- `verify.json` — integrity hash, debit/credit totals, issues
+- `policy.md` — copy of the accounting policy applied
+
+These files are assistive — they give the accountant standard-format data to work with. The agent can also read them back to answer questions.
+
 ## Quick reference
 
 ```
@@ -177,8 +214,23 @@ clawbooks summary [period]          # pre-computed aggregates for reports
 clawbooks snapshot [period] [--save] # compute period snapshot (balances, P&L)
 clawbooks assets [--category C] [--life N] [--as-of DATE]
                                      # asset register (capitalize-flag based)
+clawbooks compact <period>           # archive old events, shrink ledger
+clawbooks pack [period] [--out DIR]  # generate audit pack (CSVs + JSON)
 ```
 
+## Improving the policy
+
+The accounting policy (`policy.md`) should improve over time as you process more data. After classification review cycles:
+
+1. Run `clawbooks review` to see reclassifications and patterns
+2. If you notice repeated corrections (e.g., "GITHUB" always gets reclassified from `office_supplies` to `software`), update `policy.md` with the new rule
+3. Add the rule to the appropriate section (expense classification, source-specific rules, etc.)
+4. Be specific — "GitHub charges are software subscriptions" is better than "tech charges are software"
+
+The goal is that each import gets more accurate as the policy captures learned patterns. The agent should proactively suggest policy updates when it sees recurring reclassifications, but should not update the policy without the user's awareness.
+
+When updating the policy, keep it plain english. The policy is read by the agent on every `context` call — it should be clear, concise, and actionable.
+
 ## Idempotent imports
 
 When importing from a source (CSV, statement), include a stable `data.ref` field derived