grist-accounting/SKILL.md

name, description

name	description
grist-accounting	Use when working with the Grist double-entry accounting system - recording transactions, entering bills, tracking vendors, querying account balances, or generating financial reports

Grist Double-Entry Accounting System

Double-entry accounting for sole proprietorship. Every transaction creates balanced journal entries (debits = credits).

Quick Reference

Task	Action
Record vendor invoice	Create Bill + BillLines + Transaction + TransactionLines, then audit
Record payment	Create payment Transaction + BillPayment, update Bill status
Query balances	Use sql_query on Accounts table
Generate reports	See queries.md

Recording Transactions: Decision Guide

Source Document	What to Create
Invoice/Bill from vendor	Bill + BillLines + Transaction + TransactionLines
Receipt showing payment	BillPayment + attach Receipt to existing Bill
Bank statement entry	Transaction + TransactionLines only
Journal adjustment	Transaction + TransactionLines only

Key Rule: If there's a vendor invoice number, always create a Bill record.

MCP Tools

Tool	Purpose
list_documents	List accessible Grist documents
list_tables	List tables in a document
describe_table	Get column schema
get_records	Fetch records (filter, sort, limit)
add_records	Insert records, returns {"inserted_ids": [...]}
update_records	Update by ID
delete_records	Delete by ID
sql_query	Read-only SQL

Document name: accounting

Date Handling

All dates use Unix timestamps (seconds since epoch).

Date	Timestamp
Oct 1, 2025	1759363200
Nov 1, 2025	1762041600
Dec 1, 2025	1764633600
Jan 1, 2026	1767312000

Key Account IDs

ID	Code	Name	Type
4	2000	Accounts Payable	Liability
14	1001	Checking Account	Asset
22	2203	Due to Owner	Liability
36	5080	Software & Subscriptions	Expense

Query all: SELECT id, Code, Name, Type FROM Accounts WHERE IsActive = true ORDER BY Code

Account Types

Type	Normal Balance	Increases With
Asset	Debit	Debit
Liability	Credit	Credit
Equity	Credit	Credit
Income	Credit	Credit
Expense	Debit	Debit

Bill Entry Workflow (6 Steps)

1. Create Bill header with Vendor, BillNumber, BillDate, DueDate, Status="Open"
2. Create BillLine(s) with expense Account and Amount
3. Create Transaction + TransactionLines (Dr Expense, Cr AP)
4. Link Bill.EntryTransaction to transaction ID
5. Upload Invoice attachment if available
6. Run post-entry audit (REQUIRED)

For detailed code: see workflows.md

Payment Workflows

Pay from Checking:

1. Create Transaction (Dr AP, Cr Checking)
2. Create BillPayment record
3. Update Bill.Status = "Paid"
4. Upload Receipt if available
5. Run post-payment audit

Owner pays personally: Same as above but Cr Due to Owner (id=22) instead of Checking

For detailed code: see workflows.md

Validation Checklist

After entering bills:

• SELECT * FROM Transactions WHERE IsBalanced = false returns empty
• SELECT Balance FROM Accounts WHERE Code = '2000' shows correct AP
• SELECT id, BillNumber FROM Bills WHERE Invoice IS NULL - upload missing

Common Mistakes

Mistake	Fix
Transaction not balanced	Ensure SUM(Debit) = SUM(Credit)
Wrong debit/credit direction	Assets/Expenses: debit increases; Liabilities/Equity/Income: credit increases
Posting to parent account	Post to leaf accounts (1001 not 1000)
Missing EntryTransaction link	Always link Bill to Transaction
Using string dates	Use Unix timestamps

Uploading Attachments

# Get session token, then:
bash scripts/upload-attachment.sh invoice.pdf Bills {id} $TOKEN Invoice
bash scripts/upload-attachment.sh receipt.pdf Bills {id} $TOKEN Receipt

Audit Subagent

REQUIRED: Run audit checks after every bill entry before considering complete.

Behavior

Claude MUST run post-entry audit checks. The audit:

1. Executes independently from entry workflow
2. Validates all aspects of newly created records
3. Reports findings in structured format
4. Does not auto-correct - alerts user to take action

Audit Categories

Category	Severity	Description
Transaction Balance	Critical	Debits must equal credits
Account Usage	Error	Correct account types
Bill Linkage	Error	EntryTransaction and Vendor set
Amount Match	Error	Bill.Amount matches transaction
PDF Verification	Warning	Document values match database
Missing Attachments	Warning	Invoice/Receipt attached

Quick Audit

-- Check transaction balanced
SELECT IsBalanced FROM Transactions WHERE id = {txn_id}

-- Check bill integrity
SELECT id, Vendor, EntryTransaction, Amount FROM Bills WHERE id = {bill_id}

Output Format

Check	Status	Details
Transaction Balanced	PASS/FAIL	...
Bill Integrity	PASS/FAIL	...
PDF Verification	PASS/WARN/SKIP	...

For full audit queries and remediation: see audit.md

Reference Files

File	Contents
references/schema.md	Complete table schemas
references/workflows.md	Detailed code examples
references/queries.md	SQL queries and financial reports
references/audit.md	Audit queries and remediation