clawbooks 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,12 @@
-# clawbooks
+<p align="center">
+  <img src="./logo.png" alt="clawbooks logo" width="180" align="center">
+</p>
 
-Accounting by inference, not by engine.
+<h1 align="center">clawbooks</h1>
 
-Financial memory for agents.
+<p align="center"><strong>Financial memory for agents.</strong></p>
+
+<p align="center">Append-only ledger • Plain-English policy • Agent-native accounting CLI</p>
 
 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.
@@ -11,6 +15,28 @@ No rules engine. No SDK. No framework.
 
 **Two source files. Zero runtime dependencies.**
 
+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
+```
+
 ## Why
 
 Most accounting software assumes the product should contain the accounting logic.
@@ -30,6 +56,53 @@ That makes clawbooks useful anywhere an agent can read files and run shell comma
 - 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
@@ -64,7 +137,7 @@ cp policy.md.example policy.md   # edit with your own accounting rules
 ## How it works
 
 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.
+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
 
@@ -101,25 +174,59 @@ clawbooks policy
 
 ## The context command
 
-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.
+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

package/build/cli.js

@@ -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());

package/package.json

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