clawbooks 0.1.0

package/build/ledger.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { readFileSync, appendFileSync, existsSync, writeFileSync } from "node:fs";
+export function computeId(data, meta) {
+    const sortedData = JSON.stringify(data, Object.keys(data).sort());
+    const envelope = { data: sortedData, source: meta.source, ts: meta.ts, type: meta.type };
+    const canonical = JSON.stringify(envelope);
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+export function readAll(path) {
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+}
+export function filter(events, opts) {
+    let out = events;
+    if (opts?.after)
+        out = out.filter((e) => e.ts >= opts.after);
+    if (opts?.before)
+        out = out.filter((e) => e.ts <= opts.before);
+    if (opts?.source)
+        out = out.filter((e) => e.source === opts.source);
+    if (opts?.type)
+        out = out.filter((e) => e.type === opts.type);
+    if (opts?.last)
+        out = out.slice(-opts.last);
+    return out;
+}
+export function hashLine(line) {
+    return createHash("sha256").update(line).digest("hex").slice(0, 16);
+}
+const CURRENCY_EXEMPT_TYPES = new Set(["snapshot", "reclassify", "opening_balance"]);
+export function append(path, event) {
+    if (!CURRENCY_EXEMPT_TYPES.has(event.type) && event.data.currency === undefined) {
+        throw new Error(`Event missing data.currency (type: ${event.type}, id: ${event.id})`);
+    }
+    if (!existsSync(path))
+        writeFileSync(path, "", "utf-8");
+    const existing = readAll(path);
+    if (existing.some((e) => e.id === event.id))
+        return false;
+    // Compute prev hash from last line in file
+    if (existing.length === 0) {
+        event.prev = "genesis";
+    }
+    else {
+        const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+        event.prev = hashLine(lines[lines.length - 1]);
+    }
+    appendFileSync(path, JSON.stringify(event) + "\n", "utf-8");
+    return true;
+}
+export function latestSnapshot(events, before) {
+    let snapshots = events.filter((e) => e.type === "snapshot");
+    if (before)
+        snapshots = snapshots.filter((e) => e.ts <= before);
+    return snapshots.at(-1) ?? null;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "clawbooks",
+  "version": "0.1.0",
+  "description": "Accounting by inference, not by engine. Zero dependencies.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rev1ck/clawbooks.git"
+  },
+  "homepage": "https://github.com/rev1ck/clawbooks#readme",
+  "bugs": {
+    "url": "https://github.com/rev1ck/clawbooks/issues"
+  },
+  "keywords": [
+    "accounting",
+    "ledger",
+    "cli",
+    "bookkeeping",
+    "finance",
+    "llm"
+  ],
+  "bin": {
+    "clawbooks": "./build/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/cli.js",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "build",
+    "program.md",
+    "policy.md.example",
+    "policy-simple.md.example",
+    "policy-complex.md.example"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT"
+}

package/policy-complex.md.example

@@ -0,0 +1,149 @@
+# Accounting policy
+
+## Entity
+
+Solo quantitative trader operating across centralized exchanges, DeFi protocols, and prediction markets. US tax resident. Not registered as a company — individual trader.
+
+Base currency: USD for all P&L tracking.
+Fiscal year: January 1 to December 31.
+
+## Jurisdiction notes
+
+The IRS treats crypto as property (Notice 2014-21, Rev. Rul. 2019-24). For a frequent trader:
+- Short-term gains (held < 1 year) are taxed as ordinary income
+- Long-term gains (held > 1 year) are taxed at capital gains rates (0%, 15%, or 20%)
+
+This operation is frequent trading. **All crypto gains and losses are short-term unless a specific lot has been held over 1 year.**
+
+## Cost basis
+
+FIFO (First In, First Out) for all assets across all venues.
+
+Track cost basis per asset in USD.
+
+Lot tracking: each acquisition event creates a lot. Each disposal event consumes lots in FIFO order. The LLM must maintain a running lot schedule when generating reports.
+
+## Source: Hyperliquid
+
+Hyperliquid is a perpetual futures DEX. Events from this source include:
+
+- **Trades** (type: `trade`): opening or closing perpetual positions. The `side` field indicates buy/sell. These are leveraged positions, not spot purchases. Track the notional value and the margin used.
+- **Funding payments** (type: `funding`): periodic funding rate payments. If rate is positive and you're long, you pay. If rate is positive and you're short, you receive. Classify as **interest expense** (paid) or **interest income** (received).
+- **Liquidations** (type: `liquidation`): forced closure of a position. Classify the loss as a **realized trading loss**. Flag for review — liquidations indicate risk management failure.
+- **Deposits/Withdrawals** (type: `transfer`): movement of USDC to/from the Hyperliquid bridge contract on Arbitrum. These are not income or expense — they are transfers between own accounts. Match the on-chain transfer with the Hyperliquid balance change.
+
+### Hyperliquid P&L
+
+Realized P&L on each trade = (exit price - entry price) x quantity x direction.
+Include all fees (taker/maker) as a deduction from the P&L, not as a separate expense line.
+Unrealized P&L on open positions should be reported separately and NOT included in taxable income until the position is closed.
+
+## Source: Polymarket
+
+Polymarket is a binary prediction market on Polygon. Events include:
+
+- **Position entry** (type: `trade`): buying YES or NO shares on a market. Cost basis = price paid per share x quantity. These are **speculative derivative contracts**, not purchases of an underlying asset.
+- **Settlement** (type: `settlement`): market resolves. If the position wins, payout = number of shares x $1.00. If it loses, payout = $0. Realize the gain or loss as: payout - cost basis.
+- **Redemption** (type: `trade`, side: `sell`): selling a position before settlement. Realize gain/loss as: sale proceeds - cost basis (FIFO).
+
+### Polymarket classification
+
+Classify all Polymarket activity as **speculative derivative income/loss**. This is distinct from the trading income on Hyperliquid — keep them as separate line items in reports.
+
+## Source: Ethereum / Arbitrum / Polygon (on-chain)
+
+Chain watchers emit transfer events. Classification rules:
+
+- **Transfers between own wallets**: not income/expense. Internal transfer. Match by amount and token across the two addresses. Maintain a list of own addresses (see Known Addresses below).
+- **Bridge transactions**: transfers to/from bridge contracts. These are internal transfers that may take time to complete. Match the source chain debit with the destination chain credit. If the amounts don't match after 1 hour, flag as a potential bridge failure.
+- **Gas fees**: classify as **operating expense: gas**. Always denominated in the chain's native token (ETH, MATIC). Convert to USD at the block timestamp.
+- **Token approvals**: zero economic impact, but record the gas fee.
+- **Failed transactions**: the transaction reverted but gas was still consumed. Classify the gas as **operating expense: failed transaction gas**. This is deductible.
+- **Unknown contract interactions**: flag for manual review. Do not auto-classify interactions with unrecognized contracts.
+
+## Source: Agent (autonomous agents, bots, etc.)
+
+Agent-generated events are annotations, not primary financial events. They provide context for the LLM but do not create new economic activity.
+
+- **Notes** (type: `note`): agent's commentary on a trade, strategy, or observation. Use these for context when generating reports but do not create journal entries from them.
+- **Signals** (type: `signal`): agent's trading signals. These are informational only — the actual trade event from the exchange is the authoritative record.
+
+Exception: if an agent records a type: `adjustment`, treat it as a legitimate correction (same as a human adjustment). The adjustment must include a `reason` field.
+
+## Reconciliation rules
+
+### Trade booking vs on-chain settlement
+
+When a trade is executed on Hyperliquid/Polymarket, the exchange event and the on-chain settlement may not match exactly. Rules:
+
+| Delta | Classification | Action |
+|-------|---------------|--------|
+| < 0.1% | Slippage | Auto-classify, no flag |
+| 0.1% - 1.0% | Fee variance | Log as operating expense: execution variance |
+| > 1.0% | Discrepancy | Flag for manual review, do not auto-classify |
+
+### Cross-source matching
+
+When the same economic event appears from multiple sources (e.g., a Hyperliquid trade appears both in the exchange feed and in the Arbitrum chain watcher), deduplicate:
+
+1. Check `id` (content hash) — if identical, skip the duplicate
+2. If hashes differ (different raw payloads), match by: timestamp (+/-30 seconds) + amount (+/-0.5%) + token
+3. If matched, keep the exchange source as primary (more detailed), link the on-chain source as confirmation
+4. If not matched, flag both events for review
+
+## Known addresses
+
+These are all my addresses. Transfers between them are internal.
+
+- `0x_eth_main` — Ethereum mainnet primary
+- `0x_arb` — Arbitrum primary
+- `0x_polygon` — Polygon primary
+- `0x_hl_deposit` — Hyperliquid deposit address
+
+(Replace with actual addresses)
+
+## Reporting
+
+### Monthly
+- P&L by source (Hyperliquid, Polymarket, other)
+- Realized vs unrealized breakdown
+- Funding income/expense
+- Gas costs
+- Open positions with unrealized P&L
+- Cash/stablecoin balances across all venues
+
+### Quarterly
+- Tax estimate (quarterly estimated payments due: April 15, June 15, September 15, January 15)
+- Strategy performance: arb P&L (HL long + PM short combined)
+- Win rate by market type
+- Risk metrics: max drawdown, largest single loss
+- Reconciliation status: any unresolved discrepancies
+
+### Annual (tax filing)
+- Total income from trading (all sources)
+- Total deductible expenses (gas, fees, execution variance, home office if applicable)
+- Net taxable income
+- Supporting schedule: every realized gain/loss with dates, amounts, cost basis
+- Schedule D / Form 8949 preparation notes
+
+## Special rules
+
+### The arb strategy
+
+The primary strategy is microstructure arbitrage between Hyperliquid and Polymarket on short-term BTC price windows. This means:
+
+- A Hyperliquid long/short AND a Polymarket YES/NO position are opened together as a single economic unit
+- When reporting arb P&L, combine the HL leg and PM leg into a single arb trade with net P&L
+- For tax purposes, each leg is still reported individually (IRS doesn't recognize synthetic positions)
+- For management accounting, report both: individual leg P&L AND combined arb P&L
+
+### Stablecoin treatment
+
+USDC, USDT, and DAI are treated as cash equivalents. Do not track cost basis on stablecoins — treat them as USD at 1:1. If a stablecoin depegs more than 2%, flag and begin tracking cost basis from that point.
+
+### Airdrops and rewards
+
+Any tokens received as airdrops, staking rewards, or protocol incentives:
+- Recognize as income at fair market value at time of receipt
+- Cost basis = fair market value at receipt
+- If no reliable price feed exists, flag for manual valuation

package/policy-simple.md.example

@@ -0,0 +1,48 @@
+# Accounting policy
+
+## Entity
+
+Small web design studio. US-based, single member LLC.
+Cash basis accounting. Fiscal year: January to December.
+Base currency: USD.
+
+## Revenue recognition
+
+Income is recognized when payment is received, not when invoiced.
+All client payments are service revenue.
+Crypto payments are converted to USD at the spot price at time of receipt and recognized as service revenue at that USD amount. The crypto itself is not held as an investment — convert or record the USD equivalent immediately.
+
+## Expense classification
+
+- **Software subscriptions** (Figma, hosting, domains): operating expenses
+- **Contractor payments**: cost of goods sold
+- **Hardware** (laptops, monitors): capitalize if over $2,500, otherwise operating expense. Depreciate capitalized assets over 3 years straight-line.
+- **Home office**: allocate 15% of rent and utilities as business expense
+- **Meals with clients**: 50% deductible business expense
+- **Conference travel**: fully deductible if business purpose documented
+
+## Tax
+
+Quarterly estimated tax payments due: April 15, June 15, September 15, January 15.
+Self-employment tax rate: 15.3% on net earnings.
+Set aside 30% of net income for combined federal + state + SE tax.
+State: California.
+
+## Bank accounts
+
+- Chase Business Checking: primary operating account
+- Mercury: secondary / savings
+- Stripe: payment processing (settlement to Chase, 2-day rolling)
+
+When Stripe settles to Chase, do not double-count. The Stripe payout and the Chase deposit are the same money. Match them by amount and date (±2 days).
+
+## Invoicing
+
+Net 30 terms. Invoices over 45 days past due should be flagged.
+Deposits (typically 50% upfront) are recognized as revenue when received, not deferred.
+
+## Reports
+
+- Monthly: P&L summary, outstanding invoices, cash position
+- Quarterly: tax estimate, P&L by client, expense breakdown by category
+- Annual: full P&L, balance sheet, Schedule C preparation

package/policy.md.example

@@ -0,0 +1,80 @@
+# Accounting policy
+
+## Entity
+
+Describe your business here.
+
+## Currencies
+
+Base currency: USD.
+The CLI aggregates per-currency; the agent handles cross-currency reporting and conversions when needed.
+
+## Revenue recognition
+
+Cash basis. Income is recognized when payment is received.
+
+## Expense classification
+
+### Operating expenses (OpEx)
+- **Software subscriptions** (Figma, hosting, domains, SaaS tools)
+- **Home office**: allocate 15% of rent and utilities as business expense
+- **Meals with clients**: 50% deductible business expense
+- **Conference travel**: fully deductible if business purpose documented
+- **Office supplies**: consumables, stationery, minor accessories
+- **Professional services**: legal, accounting, consulting
+- **Insurance**: business-related insurance premiums
+- **Bank fees**: monthly fees, transaction charges, card fees
+
+### Cost of goods sold (COGS)
+- **Contractor payments**: direct labor for client deliverables
+- **Platform fees**: marketplace commissions, payment processing fees tied to revenue
+
+### Capital expenditure (CapEx)
+See capitalization policy below. Hardware, equipment, and other tangible assets above the threshold are capitalized, not expensed.
+
+## Capitalization policy
+
+- **Threshold**: $2,500 — items below this are expensed immediately
+- **Method**: straight-line depreciation
+- **Default useful life**: 36 months (per-asset override via `data.useful_life_months`)
+- **Selection**: events with `data.capitalize: true` appear in the asset register
+- **Disposal**: record a `disposal` event with `data.asset_id` and `data.proceeds`. Gain/loss = proceeds - net book value
+- **Write-off**: record a `write_off` event with `data.asset_id`. Remaining NBV is a loss
+- **Impairment**: record an `impairment` event with `data.asset_id` and `data.impairment_amount`. Reduces carrying value
+
+## Tax jurisdiction
+
+Your jurisdiction and relevant rules.
+
+## Reconciliation
+
+### Post-import checklist
+1. **Count**: verify event count matches source row count
+2. **Debits/credits**: verify totals match source statement totals
+3. **Closing balance**: `clawbooks verify --balance <closing> --currency USD`
+4. **Duplicates**: review `potential_duplicates` in verify output
+5. **Gaps**: `clawbooks reconcile --source S --gaps` to find date gaps >7 days
+
+### Cross-source checks
+When importing from multiple sources (bank, Stripe, manual), verify:
+- No double-counting of the same transaction across sources
+- Transfers between accounts net to zero
+- Opening balances + net transactions = closing balances per source
+
+## Reporting
+
+### Monthly
+- **P&L**: revenue, operating expenses, COGS, tax, net income
+- **Cash flow**: inflows vs outflows by category
+- **Reconciliation**: verify + reconcile for each source imported that month
+
+### Quarterly
+- **Balance sheet**: assets (cash + capitalized), liabilities, equity
+- **Asset register**: `clawbooks assets --as-of <quarter-end>` — active, disposed, written-off
+- **Tax estimate**: projected tax based on year-to-date income
+
+### Annual
+- **Full P&L**: 12-month income statement with monthly breakdown
+- **Balance sheet**: year-end position
+- **Asset register**: full depreciation schedule, disposals, write-offs
+- **Tax preparation**: categorized expenses, income by source, deductions summary

package/program.md

@@ -0,0 +1,186 @@
+# Clawbooks
+
+You have access to `clawbooks`, a CLI tool for financial record-keeping.
+The ledger is an append-only JSONL file. The accounting policy is a markdown file.
+You are the accountant. The CLI is just data storage.
+
+## Reading the books
+
+To answer any financial question, first load context:
+
+```bash
+clawbooks context 2026-03           # specific month
+clawbooks context --after 2026-01-01  # everything since a date
+clawbooks context                    # everything (small ledgers)
+```
+
+This prints the accounting policy, the latest snapshot, and all events
+in the period. Read the output, apply the policy, answer the question.
+
+## Writing events
+
+To record a financial event:
+
+```bash
+clawbooks record '{"source":"stripe","type":"income","data":{"amount":500,"currency":"USD","customer":"acme"}}'
+```
+
+Required fields: `source`, `type`, `data` (any object). `ts` is optional (defaults to now).
+`data.currency` is **required** — the ledger rejects events without it (except snapshots, reclassify, opening_balance).
+
+The CLI enforces sign convention automatically for known types:
+- **Outflow** (stored negative): `expense`, `tax_payment`, `owner_draw`, `fee`, `dividend`, `loan_repayment`, `refund`, `transfer_out`, `withdrawal`
+- **Inflow** (stored positive): `income`, `deposit`, `equity_injection`, `loan_received`, `transfer_in`, `refund_received`, `grant`
+- **Meta types** (sign not enforced): `snapshot`, `reclassify`, `opening_balance`
+- **Asset events** (sign not enforced): `disposal`, `write_off`, `impairment`
+- **Unknown types**: the CLI warns and preserves the sign you provide. Use critical thinking — if a new type represents money leaving the business, pass a negative amount. `verify` will flag sign inconsistencies.
+
+The ledger is hash-chained — each event's `prev` field links to the previous event.
+
+For bulk data, output JSONL and pipe it:
+
+```bash
+echo '{"source":"bank","type":"income","data":{"amount":1000,"currency":"USD"}}
+{"source":"bank","type":"fee","data":{"amount":25,"currency":"USD","desc":"Monthly fee"}}' | clawbooks batch
+```
+
+## Opening balances
+
+Before importing transaction data, record opening balances for each account/currency. One event per account/currency:
+
+```bash
+clawbooks record '{"source":"manual","type":"opening_balance","ts":"2025-01-01T00:00:00.000Z","data":{"amount":50000,"currency":"USD","account":"checking","category":"cash"}}'
+clawbooks record '{"source":"manual","type":"opening_balance","ts":"2025-01-01T00:00:00.000Z","data":{"amount":-12000,"currency":"USD","account":"credit_card","category":"liability"}}'
+```
+
+Convention:
+- Positive amount = asset (cash, receivables, equipment)
+- Negative amount = liability (credit cards, loans)
+- `data.category`: `cash`, `asset`, `liability`, or `equity`
+- `data.account`: identifies which account (e.g., `checking`, `credit_card`)
+- One event per account/currency pair
+- `opening_balance` is exempt from currency requirement and sign enforcement
+
+## Importing messy data (CSVs, statements, etc.)
+
+When the user gives you a CSV or other raw financial data:
+
+1. Record opening balances first (if not already present)
+2. Read the raw data and the policy (`clawbooks policy`)
+3. Parse each row into a ledger event, classifying per the policy
+4. For hardware/equipment purchases that meet the capitalization threshold, set `data.capitalize: true` and optionally `data.useful_life_months`
+5. Output as JSONL and pipe to `clawbooks batch`
+6. Run `clawbooks verify --balance <closing_balance>` to cross-check against the statement's closing balance
+
+You are the parser. There is no import tool. You read the data and write the events.
+
+## Capitalizing assets
+
+When an expense meets the capitalization threshold (see policy), set `data.capitalize: true` on the event:
+
+```bash
+clawbooks record '{"source":"bank","type":"expense","ts":"2025-09-15T00:00:00.000Z","data":{"amount":15000,"currency":"USD","description":"MacBook Pro","category":"hardware","capitalize":true,"useful_life_months":36}}'
+```
+
+- `data.capitalize: true` — marks the event for the asset register
+- `data.useful_life_months` — overrides the default useful life (default: 36 months)
+- The `assets` command finds all events with `capitalize: true` and computes depreciation
+- `--category` on the `assets` command is an optional filter, not the selection mechanism
+
+## Asset lifecycle
+
+After capitalizing an asset, you can record disposal, write-off, or impairment events. These reference the original asset by its event ID via `data.asset_id`:
+
+**Disposal** (sold or traded in):
+```bash
+clawbooks record '{"source":"manual","type":"disposal","data":{"asset_id":"abc123","proceeds":5000,"currency":"USD"}}'
+```
+Gain/loss = proceeds - net book value at time of disposal.
+
+**Write-off** (destroyed, stolen, obsolete):
+```bash
+clawbooks record '{"source":"manual","type":"write_off","data":{"asset_id":"abc123","currency":"USD"}}'
+```
+Remaining NBV becomes a loss.
+
+**Impairment** (value reduced but still in use):
+```bash
+clawbooks record '{"source":"manual","type":"impairment","data":{"asset_id":"abc123","impairment_amount":3000,"currency":"USD"}}'
+```
+Reduces carrying value by the impairment amount. Multiple impairments can accumulate.
+
+## Generating reports
+
+When asked for a P&L, tax summary, balance, etc.:
+
+1. Run `clawbooks summary <period>` for pre-computed aggregates
+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
+
+## Reconciliation workflow
+
+After importing data from any source:
+
+1. During import, compute expected totals (count, debits, credits) from the source data
+2. Run `clawbooks verify <period> --source S` to check integrity (totals, hash, issues)
+3. Run `clawbooks verify --balance <closing_balance> --currency USD` to cross-check the statement's closing balance
+4. Run `clawbooks reconcile <period> --source S --count N --debits N --credits N --gaps` to compare and detect date gaps
+5. Review `potential_duplicates` in verify output — same source/date/amount/description
+6. If `RECONCILED`, proceed. If `MISMATCH`, investigate and fix before generating reports
+7. Include the verify hash in report footers for audit trail
+
+## Classification review
+
+When importing events, set a `confidence` field in each event's data:
+- `"clear"` — unambiguous classification (e.g., payroll labeled by bank)
+- `"inferred"` — reasonable but uncertain (e.g., "AMZN" → office supplies)
+- `"unclear"` — couldn't classify confidently
+
+After import, run `clawbooks review <period> --source S` to see items needing review.
+
+To reclassify an event, record an append-only correction:
+```bash
+clawbooks record '{"source":"manual","type":"reclassify","data":{"original_id":"abc123","new_category":"contractor"}}'
+```
+
+The `summary` command automatically applies reclassifications. The `review` command excludes already-reclassified events.
+
+## Generating snapshots
+
+When the ledger is large, generate a snapshot to keep future context bounded:
+
+```bash
+clawbooks snapshot 2026-03 --save   # compute and save to ledger
+clawbooks snapshot 2026-03          # compute and print (no save)
+```
+
+The snapshot includes balances by currency, totals by category, and P&L by currency.
+
+## Quick reference
+
+```
+clawbooks record <json>             # append one event
+clawbooks batch                     # append JSONL from stdin
+clawbooks log [--last N]            # view recent events
+clawbooks context [period]          # load policy + events for reasoning
+clawbooks policy                    # print policy.md
+clawbooks stats                     # ledger overview
+clawbooks verify [period]           # integrity + chain + balance check + duplicates
+clawbooks verify --balance N        # cross-check closing balance
+clawbooks reconcile [period] -S     # compare expected vs actual totals
+clawbooks reconcile -S --gaps       # also detect date gaps >7 days
+clawbooks review [period]           # show items needing classification review
+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)
+```
+
+## Idempotent imports
+
+When importing from a source (CSV, statement), include a stable `data.ref` field derived
+from the source row (e.g. hash of date + description + amount + running balance). This
+ensures re-importing the same source file produces identical event IDs and gets deduplicated.