| type | folder | |||
|---|---|---|---|---|
| description | Cash-flow tracking: append-only ledger.csv, redacted statements, receipts; via /finance + /financial-summary | |||
| product | shared | |||
| tags |
|
Cash-flow tracking for the project. Where money went, how much, when — captured from a quick verbal note, a receipt screenshot, or a bank statement, so nothing is scattered and nothing is missed.
This folder breaks the usual one-file-per-entry KB pattern on purpose: transactions are tabular structured data, not prose. The source of truth is a single CSV, and human-readable views are generated from it (same philosophy as auto-generated INDEX.md). One markdown file per transaction would blow past every growth rule within a month.
Scope: single-entry cash-flow tracking, not bookkeeping. No double-entry, no accrual, no P&L, no tax prep. If real books are ever needed, that's QuickBooks and this becomes the feeder, not the replacement. See ../LIMITS.md § "Out of scope" for what stays out (cap tables, contracts, comp detail).
finances/
README.md # this file — the contract: schema, vocab, dedup + redaction rules
ledger.csv # SOURCE OF TRUTH — append-only, one row per transaction
receipts/ # stored receipt images, <id>-<slug>.<ext> (small images only)
statements/ # REDACTED parsed statement snapshots (.csv) — safe to re-reconcile
summaries/ # generated by /financial-summary, persisted (type: finance-summary)
INDEX.md # auto-generated (note: ledger.csv is documented here, not in INDEX)
/finance— ingest a transaction. Three modes: verbal ("$40 to Example SaaS today"), receipt image, or bank statement (local file path). Parses → categorizes → dedup/reconciles → confirms with you before writing → appends/enriches the ledger → commits + pushes./financial-summary <period> [format]— on-demand formatted summary for a month/quarter/range, persisted tosummaries/. One-off questions ("how much on SaaS in May?") need no skill — just ask; the ledger gets read live.
One row per transaction. Columns, in order:
| Column | Meaning | Notes |
|---|---|---|
id |
Internal unique id | YYYY-MM-DD-NN — NN = sequential within that date. Always distinct, even for legit duplicates. |
date |
Transaction date | ISO YYYY-MM-DD. For statements, the posting date. |
direction |
in / out / transfer |
transfer = between our own accounts (net-zero; excluded from in/out totals). |
amount |
Positive decimal | Always positive; direction carries the sign. e.g. 420.00. |
currency |
ISO code | USD default. Column exists for future multi-currency; we do not auto-convert FX. |
category |
Controlled vocab | See "Categories" below. Drives summary breakdowns. |
counterparty |
Who | Merchant / payer / payee. e.g. Example SaaS, Example Cloud, Customer payout. |
account |
Which account | Last-4 or nickname only — never a full number. e.g. Bank ••1234, Card ••0007. |
owner |
Whose money | founder-a / founder-b / company. Who fronted the transaction, frozen at write time. Auto-filled from the account→owner map below; drives per-founder contribution / reimbursement reporting. A bank ext_id does NOT carry this — account/owner is the only thing that says whose. |
ext_id |
External reference | Bank transaction ref / receipt invoice or order no. Nullable. Dedup key, scoped to the account — bank refs are only unique within an account, so dedup keys on (account, ext_id), never ext_id alone. |
source |
Provenance | verbal / receipt:<file> / statement:<file>. |
status |
pending / cleared |
pending = our capture (verbal and receipts start here); cleared = confirmed by a bank statement. A paid receipt is still pending — it proves the merchant charged us, not that the bank statement has matched it. Rule 4 flips it to cleared when the statement line lands. |
note |
Free text | Disambiguator for look-alikes ("2nd seat", "Q2 retainer"), or any context. |
CSV rules: quote any field containing a comma; one header row; append-only (never rewrite history — corrections are a new row or an edit-with-note, and git log is authoritative).
Keep categories to this list so summary breakdowns stay aggregatable. If a real new bucket is needed, add it here in the same commit that first uses it.
Outflow (direction: out):
payroll · contractors · saas · cloud · legal · accounting · marketing · travel · meals · hardware · office · fees · taxes · refund-out · misc-out
Inflow (direction: in):
revenue · fundraise · grant · reimbursement · refund-in · interest · misc-in
Neutral (direction: transfer):
transfer — moving our own money between accounts; excluded from spend/income totals.
Default category per recurring counterparty, so categorization is consistent (not saas one month, software the next) and confirmations are fast. The /finance skill pre-fills from this table, then you confirm; new mappings get appended here. Seed entries — extend as you log:
| Counterparty | Default category |
|---|---|
| Example SaaS | saas |
| Example Cloud | cloud |
| Example IDE | saas |
| Example Hosting | cloud |
| (bank) fee | fees |
Who each account belongs to, so owner auto-fills consistently and per-founder contributions stay attributable. Before there's a dedicated company account, founders often front costs on personal cards — this map is the only thing that tells us whose (the bank's ext_id can't). Extend as accounts appear:
| Account | Owner |
|---|---|
| Card ••0007 | founder-a |
company is reserved for a shared/company account. When a card isn't in this map, the /finance skill asks whose it is and appends the mapping in the same commit.
You can't auto-decide duplicates — two identical real transactions are legal. The rule is detect suspects, then confirm, tiered by whether the source carries an ID. Confirm everything before writing (current policy).
ext_idpresent and(account, ext_id)already in ledger → deterministically already recorded. Skip; report it. Key on(account, ext_id), notext_idalone — bank refs are only unique within an account, so two different banks could collide on the same ref string and trigger a false skip.ext_idpresent but differs, even if fields look identical → genuinely a separate transaction (the bank gave it a distinct ref). Append.- No
ext_id, fingerprint(date, amount, counterparty, account)matches an existing row → suspected duplicate. Show the existing row and ask: same transaction (skip) or separate (append a second row, prompt for a distinguishingnote)? - Cross-source confirmation — an incoming statement row matches an existing
pendingentry by(amount, counterparty, date ±2 days)→ it's the bank confirming your capture, not a new charge. Enrich the existing row (attachext_id, setstatus: cleared); do not append. This is exactly the path a receipt logged aspendingtakes when its bank line lands — match onaccounttoo, since you know which account's statement you're importing.
A statement import reports three buckets back to you: confirmed (enriched), new (you never logged it → appended), in-ledger-but-not-in-statement (you logged it but the bank doesn't show it → flagged for review).
This is real financial data in a private repo. Keep it private, and keep identifiers out.
- Accounts: last-4 or nickname only. Never store full account, routing, or card numbers anywhere — ledger, statements, or notes.
- Bank statements: never commit the raw file. Raw statements contain full account numbers and are large.
/financeingests a statement from a local path you point it at, parses + redacts in memory, and writes only a redacted snapshot CSV tostatements/(last-4 kept, full numbers stripped). The raw never touches the repo. - Receipts: stored as-is (they're designed to show only last-4). If a receipt ever exposes a full card number, flag it rather than committing — redact or skip the image and keep only the row.
- Keep receipt images small. No multi-MB binaries (see
../LIMITS.md).
Rules: ../CONVENTIONS.md. Routing: ../AGENT-GUIDE.md. Entries: INDEX.md — auto-generated.