clawbooks 0.1.0 → 0.1.2

package/README.md

@@ -2,22 +2,47 @@
 
 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
+## Why
 
-```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
+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
+
+## 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,20 +51,20 @@ clawbooks --help
 cp policy.md.example policy.md
 ```
 
-## How it works
-
-Clawbooks stores financial events and outputs context. The LLM you're already talking to does the accounting.
+## Local setup
 
+```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
 ```
-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."
-```
+## How it works
 
-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 your policy, the latest snapshot, and the relevant events in XML-style blocks so an agent can read and reason over them.
 
 ## Commands
 
@@ -58,13 +83,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
@@ -72,7 +101,7 @@ 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 your accounting policy, the latest snapshot, and the events for a period, wrapped in XML tags so the agent can read and reason over them.
 
 ```bash
 $ clawbooks context 2026-03
@@ -95,14 +124,15 @@ Cash basis. Crypto trades are revenue income...
 
 ## 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."
 ```
@@ -122,22 +152,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)
@@ -150,7 +215,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([
@@ -762,6 +762,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 +1055,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 +1104,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 +1155,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.0",
+  "version": "0.1.2",
   "description": "Accounting by inference, not by engine. Zero dependencies.",
   "type": "module",
   "repository": {
@@ -20,12 +20,14 @@
     "llm"
   ],
   "bin": {
-    "clawbooks": "./build/cli.js"
+    "clawbooks": "build/cli.js"
   },
   "scripts": {
     "build": "tsc && chmod 755 build/cli.js",
     "prepare": "npm run build",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "scoped:prepare": "npm run build && node scripts/prepare-scoped-package.mjs",
+    "scoped:pack:dry-run": "npm run scoped:prepare && node scripts/prepare-scoped-package.mjs --pack --dry-run"
   },
   "files": [
     "build",

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