MCP: short connect text, a handbook, tool annotations, safe local imports

- The 13K-character instructions (clients cut them short) become a connect text of at most 1,400 characters whose first 512 stand alone, plus books.handbook and books://handbook/{section}: the old guidance by section, with no helper commands, home paths, pull requests or file-reading suggestions (tool_text_lint). - Every tool has a title and read-only/destructive hints; no requiresUserInteraction anywhere (owner decision 2026-10-16). - books.import_local_file reads only regular files inside the import roots (the downloads folder by default, or --import-root), never the data dir, books dir, vault or the key's folder, no symlink escapes or hard links, and the file opened must be the file checked. - The store lock is a tokio mutex taken off the runtime threads. - get_info refreshes settings first; a bare books://digest reads. Review fixes (P0 review, 2026-10-16): - Fail closed: a tokio mutex never poisons and spawn_blocking caught the panic, so after a panic mid-mutation the server kept serving a Store behind its journal. A panic (the task, or while holding the store) now stops the shared store; every later request on every session is refused with a plain message; a restart re-verifies the journal. The join error goes through redact_refusal and never carries the panic's text. - books.set_w9 w9_file_path read any path (a link named w9.pdf to the vault key was stored and get_w9 wrote it out): it now goes through the import roots' lockdown, its type judged on the canonical path. - Sealed even inside a root: the key file in force, where a linked one leads, both folders, and the default key folder whatever the settings say. Refusals check the roots first, so outside them every path gets one message (no probing what exists); inside, other books-dir files say to copy them out first. - The open is O_NOFOLLOW | O_NONBLOCK (a pipe swapped in after the check can't hang a thread) and must match the checked file's device and inode. New dependency: libc (unix only), for those two open flags, which std doesn't name. - Default import roots are the downloads folder only (the plan); files with full TINs (get_w9, vendor_1099 include_tins, the CPA package with TINs) are never written into an import root, and the server refuses to import any file it wrote with TINs (by SHA-256). - set_tin and set_w9 overwrite vault records: destructive_hint = true; annotations_complete pins the key tools' hints. The read-only hint is checked in behaviour on every spec_mcp call (journal and data-dir files unchanged). - Text: the connect text names the settings file as the one local file to edit, says every entry balances on real accounts and names its party, says invoice/bill/payment/payroll tools post unchecked, rewords the exemptions, and shows the company name as one plain line; the handbook takes section "all", lists its ids in the schema and says to read contract first; books.settings drops the config.json path and no error names the data dir or the key file. tool_text_lint covers the whole tool JSON and resources and bans git/commit/WL-0001; tool descriptions over 700 characters are pinned to today's eight (P5). - digest: an empty since= is bare; the default date is pinned on every day of a month. Round-2 review fixes (2026-10-16): - TIN files (B-26): the in-memory, per-session set of TIN-file hashes became one registry beside the vault (vault/tin-files.sha256, hashes only), shared by every session and every later server. It holds the W-9 set_w9 reads (recorded as read), get_w9 copies, 1099 worksheets with TINs, CPA packages with TINs and each file in one that holds a TIN; a file is recorded before it is written, and a failure refuses. import_local_file, attach_receipt and file_document (base64 was never checked) refuse a recorded file, and a text file (by type, name, or UTF-8/UTF-16 decoding) holding a full TIN. Not caught: an altered binary copy; the docs say so (P2/P7 remove the path tools). - The text check is narrow (owner/engineer decision, 2026-10-16: bank exports are filed for reconciliation, and has_full_tin's "nine digits however separated" refused their routing numbers, long references and dates run into amounts). Text is refused when it holds (a) a TIN the vault holds for a party, anywhere, as nine digits, 3-2-4 joined by hyphens, spaces or dots, or 2-7 joined by a hyphen or space, compared on the server against the decrypted vault and never returned or logged (a vault that can't be opened leaves (b)); or (b) a stand-alone printed SSN (123-45-6789) or EIN (12-3456789) shape: no digit, and no hyphen or dot followed by a digit, beside it. Full-width digits and Unicode hyphens and spaces read as ASCII. has_full_tin still guards refusals and results (redact_refusal). Known limit, for P7: a refusal under (a) tells the agent a text it chose holds a vault TIN. New dependency: zeroize in ledger-mcp (already in the workspace through ledger-vault, same major version), so the vault's TINs decoded for the scan are wiped from memory on drop as the vault's own are. - Mutation testing of the final P0 diff (docs/testing.md): tests for each law a survivor broke (handbook titles, a dropped default root, a .jpg W-9, the waker, the walk's folder flags against a link and a pipe, the 40-link limit, save paths refused as such, the package marking only its TIN files, a registry that can't be read, text types, the short receipt rule's counts and a 12-character code). Simpler code where only a race could tell: inspect places an existing path by canonicalize itself (no second comparison), read_checked's read limit is its one size check, openat fails on -1 as specified. The 25 MiB upload test removes its 50 MB of books however it ends. - The GUI's stale-rule prompt no longer says to open a pull request: it asks the agent to find the figure from the rule's official authority, confirm it with the human, pass it explicitly, and tell the human so it can be reported upstream (as the handbook says); a lib test pins it and bans files, git, GitHub and pull requests from every attention prompt. - Import roots (local_files.rs INVARIANT 0): XDG_DOWNLOAD_DIR="$HOME/" made $HOME (or /) the root. No root may be /, the home folder or hold it, or hold the books, data dir, vault or a key: a named one stops the server at startup, a default one is dropped; the default falls back to ~/Downloads only if that is a real folder other than $HOME; with no root, an import says so. - The read is a component walk from / with openat(O_NOFOLLOW | O_DIRECTORY) per folder and O_NOFOLLOW | O_NONBLOCK for the file, so a folder swapped for a link after the check fails; no step may land on a protected inode (one renamed into a root); dev/ino and nlink stay. No /proc. Portable to macOS. (libc's openat, two small unsafe blocks.) - One refusal for missing, dangling and outside paths: resolved() follows every link, dangling ones too, so a link's target existing or not no longer changes the answer. - Sealing: the key files (in force, default) and their targets always; their folders only when not $HOME, not a root, not holding a root; and ~/.config/wanderbooks whatever XDG_CONFIG_HOME says. - Agent text (I-12): RuleNotKnown names the authority (IRS, with its address) and says to tell the human, never a repo path, PR or GitHub; the digest's stale_rules drop the repo catalog and path for it; vault, outside-books, STOPPED and local-file refusals name no git, path or flag. tool_text_lint bans docs/, .md, /home, data dir, --data-dir, --import-root, vault.key, .jsonl, sqlite, .gitignore, github, pull request, and also lints every error template (scanned from source), built error texts, and the server's refusal constants. - The receipt rule told (ReceiptPolicy::rule) is the one enforced: the exact threshold in the base currency (no "$", no rounding), required and exempt accounts, reversals exempt; the connect text fits 1,400 characters by dropping reasons, then codes, never the rule. - The connect text follows the parties setting; "offer books.digest" everywhere. shown_name drops Unicode format characters (bidi, zero width). - read_only_tools_change_nothing compares file contents, the database by every row, the vault and the settings file (raw database bytes did not change either; rows are the stable comparison). - import_local_file takes the name and type from the canonical path; the digest's journal repair says when the tail was set aside, not the journal's file name; "version-history messages" back in the TIN rule; openWorldHint false on every tool, pinned in annotations_complete. - Outside the MCP crate, for the same texts: ledger-core's DatedRule gains `authority` (the statute or publication with its address) and RuleNotKnown carries it; ledger-store's "sqlite error" reads "database error"; ledger-config's ReceiptPolicy::rule takes the base currency. New dev-dependency: rusqlite in ledger-mcp (already in the workspace, same version and features as ledger-store), to read the database's rows in read_only_tools_change_nothing. - The filing scan is no TIN oracle (tin_files.rs INVARIANT 4): text holding more than two TIN-shaped numbers (any rendering rule (a) reads) that end in a known TIN's last four (the books' TIN and W-9 facts, via known_tin_last4, before the vault is opened; then the vault's own) is refused with TIN_PROBE, the same words whether or not one is the vault's TIN; only one or two candidates are compared against the vault. Tests: unit text_probing_for_a_tin_is_refused_alike_whether_or_not_it_holds_it, one_or_two_candidates_are_compared_against_the_vault; over HTTP text_probing_for_a_tin_is_refused_alike_by_every_filing_tool. Plan: plan/served.md P0, section 6 "Immediate hole (P0)", 4.1, 4.3, 4.9. Review round 3. S1: a panic stops the server for every session, so no input may reach one. Dates are four-digit years (new ledger_core:: calendar, 0001-01-01..9999-12-31): the MCP's parse_date is strict YYYY-MM-DD, periods are bounded, last_day_of_month returns a refusal (server and store); schedules, assets, recurring entries, periods, documents, disposals and entries refuse dates outside the calendar, and replay refuses such journal dates. Every amount a command takes is at most a line's (draft lines by size, document lines, payouts, payroll, statements, shares, tax basis, proceeds, recurring templates), on replay too, so sums are exact; the 1099 vendor part and the K-1 property share use checked products (TooLargeToCompute); a recurring run makes at most 1,000 drafts. tests/hostile_args.rs drives every tool with schema-derived hostile arguments and every resource with generated URIs, asserting the server never stops; the audit's panics are pinned. S2: a `.` or `..` path name is refused as NO_SUCH_FILE up front. S3: NUL-interleaved UTF-16 without a byte-order mark is scanned both ways. S4: resource-read refusals are TIN-redacted. S5: set_w9 records its W-9 only once the call passes every check, just before the vault write. S8: idempotentHint only on verify, run_depreciation, run_schedules, run_recurring, set_party_roles (a repeat leaves journal and vault alone; spec_vault checks every candidate twice); every tool's hints pinned in one table. C1: books.settings lists receipt_required_accounts and receipt_exempt_accounts uncut. C2: the default company name reads "a new company". C3: the parties rule names no-party reasons. C4/C5: the handbook names the settings file only as books.settings' books_toml, and restores "check books.digest and offer it". C6: an import root inside the books, data dir or vault is refused at startup. The lint catches `just` however it ends and where the books are; digest_resource_bare_reads reads the server's month. Review round 4 (2026-10-17): round 3's bounds ran in replay too, so journals main wrote and reopened (an entry dated 0000-06-01 or +10000-01-01, a draft line of 2e15, an asset ending past 9999, a basis or share past the line limit, sub-cent document and payroll lines) no longer opened. Posted is forever: the bounds are the commands' only. - Replay applies main's rule exactly: parse_date takes any date chrono reads; replay_add_line(_fx) has no size bound (add_line/add_line_fx do); replay_register_asset/correct_asset (chrono overflow only), replay_set_asset_tax_basis (check_journaled), replay_set_entry_parties (check_shares_journaled), replay_register_recurring (validate_recurring_journaled), replay_register_schedule (months 1 to 600), replay_create_period (order only), replay_dispose_asset, and no line, date, payment or payroll range checks in replay_invoice/bill, their payments and replay_payroll_run. - Derived figures over such books refuse (TooLargeToCompute, DateOutOfRange), never panic: amortization plans, depreciation into chrono's last month (and the true-up for lives past 9999), intervals, document totals and aging, net pay and payroll plans, money flows and share resolution, the asset register, receipt-policy debits; the MCP tools and the viewer show what can't be computed. - tests/fixtures/old-books: the review's 13 journals, its control and 15 more edges, written by main's Store API with main's figures (expected.json); every one opens in the writer and the viewer to those figures, every derived figure computes or refuses, every MCP tool and GUI page answers; hostile_args restarts the server after each property; each bound has a command/replay test pair. Final review: a schedule's plan refuses a total of 10^26 or more (TooLargeToCompute) instead of letting Decimal round its cents silently, and a null `remaining` in the schedule output is always explained by plan_error. Replay is unaffected: no journaled schedule month can belong to a total that large (the line limit bounds every posted month). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj
2026-10-17 09:25:00 -06:00
1 parent aec55b8d12
commit b22a034746
@@ -0,0 +1,5 @@
+# 1099s
+
+- Mark contractors and landlords with books.set_vendor_1099 (and whether their W-9 is on file), and tag every payment to them with its vendor or party (books.draft_entry vendor or party, books.set_entry_vendor, or books.set_entry_party; books.pay_bill tags automatically).
+- books.vendor_1099 is the year-end worksheet for the CPA. With include_tins: true (only when the human asks for the CPA's copy) it carries the full TINs from the vault: hand it over (save_csv_to, a new file outside the books and the import folders) and never repeat those numbers anywhere else.
+- Card payments are reported by the card processor (1099-K) and are left out.
@@ -0,0 +1,6 @@
+# Attachments
+
+- File a file once and link it wherever it is evidence (books.link_attachment, or link_to on books.attach_receipt and books.file_document): an entry (a file linked to an entry counts as its receipt), an account, an asset, a party, an invoice, a bill, a period, a payroll run, a schedule, a reconciliation, or the company.
+- books.attachments lists a subject's files; books.unlink_attachment takes a link off with a reason.
+- File documents under their kind (statement, contract, photo, warranty, import_source, formation, legal, tax, accounting, other).
+- File a bank export before importing it and pass source_attachment_id to books.import_bank_csv.
@@ -0,0 +1,15 @@
+# The contract
+
+You are the bookkeeping agent for these books. The engine enforces the accounting; you enforce the workflow.
+
+- These tools are the only way to the books. Never look for the books (their journal, receipts or vault) in local files.
+- One exception, until settings move into the books: the settings file that books.settings names (books_toml) may be edited as the settings-and-conventions section says. No other local file.
+- Money is exact decimal. Always pass amounts as decimal strings ("123.45"), never floats. Amounts in every response are decimal strings: treat them as exact, and echo them to the human as written.
+- Never post directly: draft, add lines, preview, show the human the preview, then post (the entries section).
+- Every entry must balance: debits equal credits, exactly. Every line needs a real account from books.chart. The engine rejects anything else.
+- Never invent accounts. If the account you need does not exist, add it with books.add_account first.
+- Posted entries are immutable; there is no edit. Corrections go through books.reverse_entry.
+- {evidence_rule}
+- Show the numbers: after every change, show the human the affected balances.
+- After posting, check books.digest and offer it to the human (the review of what changed), so they can review it too.
+- A full TIN goes only into the vault (books.set_tin, books.set_w9); never repeat one anywhere (the parties-and-tins section).
@@ -0,0 +1,5 @@
+# Control roles
+
+- Invoices, bills, payroll, and closes post to the account filling each role (receivables, revenue, payables, general expense, retained earnings, payroll expense and withholdings); books.roles lists them.
+- A role uses its default code (1200, 4000, 2000, 6999, 3999, 6100, 6110, 2110-2150) until it is assigned one of the chart's own accounts with books.assign_role (journaled). If the chart uses a default code for a different kind of account, the engine refuses and says which. It can't tell an account of the right type but another purpose (a hosting expense at payroll's 6100): check books.roles before running payroll, bills, or invoices.
+- Never assign roles or renumber the human's accounts on your own: explain the conflict, and when they decide, assign the role to their account (best: their numbering stays) or books.renumber_account the account (its history stays).
@@ -0,0 +1,5 @@
+# CPA handoff
+
+- books.export_cpa_package carries every member's and 1099 payee's full TIN from the vault (the K-1 worksheet and the 1099 worksheet), so it needs save_to: a new .zip or a folder outside the books and the import folders.
+- Tell the human where it was saved; never open, read, attach, or copy the file, and never echo its TINs.
+- tin_gaps lists each member or payee whose TIN it lacks and why: collect them (books.set_tin, books.set_w9) and export again.
@@ -0,0 +1,5 @@
+# Drafts and reversals
+
+- Posted entries are immutable: there is no edit and no delete.
+- Corrections go through books.reverse_entry: without confirmed it previews the reversing entry and changes nothing; with confirmed=true it posts the reversal, linked to the original. Then draft and post the corrected entry through the normal flow.
+- Show the human the reversal preview before confirming, as for any posting.
@@ -0,0 +1,6 @@
+# Entries
+
+- The flow is draft (books.draft_entry) -> add lines (books.add_line) -> preview (books.post_entry without confirmed) -> show the human the preview -> post (books.post_entry with confirmed=true).
+- Every entry must balance: debits equal credits, exactly. Every line needs a real account from books.chart; add a missing one with books.add_account first, never guess one.
+- When unsure of the category, draft and ask. A draft is cheap; a wrong posting is a reversal.
+- Name the entry's party when you draft it (books.draft_entry party), so the preview can show the split (the parties-and-tins section).
@@ -0,0 +1,7 @@
+# Evidence and receipts
+
+- {evidence_rule}
+- Depreciation and amortization are exempt: their schedules are the evidence. A period close is exempt too: its closing entry is derived from the books themselves. A reversal relies on its original's receipt.
+- Not receipt-checked yet: books.create_invoice, books.create_bill, books.receive_payment, books.pay_bill, books.run_payroll and books.remit_payroll_taxes post at once, with no preview and no receipt check. Attach their evidence (the invoice, the bill, the payment confirmation, the payroll register) right after, linked to the entry they return.
+- Receipt corrections: receipts can change, but nothing is erased. To replace one, attach the new receipt, then books.unlink_receipt the old (with a reason); retire unwanted receipts or documents with books.withdraw_attachment (with a reason). The journal keeps every step.
+- File a receipt once and link it wherever it is evidence (the attachments section).
@@ -0,0 +1,6 @@
+# Files in and out
+
+- Files come in as base64 (books.attach_receipt, books.file_document), or, for a file already on this computer, with books.import_local_file: an absolute path to a regular file in the server's import folders (by default your downloads folder). Save the file there first; files of the books themselves are never read, and a path that is missing or outside the import folders gets one refusal, whatever is there.
+- A W-9 given by path (books.set_w9 w9_file_path) is read the same way.
+- Files holding full TINs (books.get_w9, books.vendor_1099 with include_tins, books.export_cpa_package with TINs) are never saved in the import folders. No file with a full TIN goes into the books, however it is filed: the server refuses every file it read or wrote with full TINs (the W-9 books.set_w9 read, and each of those outputs, or a file taken out of a CPA package), and any text file holding one: a TIN the vault keeps, written as nine digits or in the usual groups (3-2-4 with hyphens, spaces or dots; 2-7 with a hyphen or a space), or a number printed as an SSN or EIN is (3-2-4 or 2-7 digits joined by hyphens, not part of a longer number). Other numbers pass, so bank exports (routing and account numbers, long references) go in. It can't recognize an altered copy of a scan, or a TIN the vault doesn't keep written any other way, so never file a W-9 or a TIN worksheet yourself.
+- Receipts come back out through books.get_receipt.
@@ -0,0 +1,7 @@
+# Fixed assets
+
+- Register with books.register_asset, inspect with books.asset_schedule and books.list_assets, post monthly depreciation with books.run_depreciation (exempt from the receipt policy; the schedule is the evidence), and dispose with books.dispose_asset (preview first; the bill of sale is the receipt).
+- Depreciation is straight-line, book basis only; tax depreciation stays with the CPA.
+- Every asset gets a tag for the label on the thing itself (books.register_asset generates the next one, like FA-0001, unless the human has their own); record the manufacturer's serial number too, change either with books.label_asset, and print label sheets with books.asset_labels (give the human the PDF; print at 100% on Avery 5160/8160). Asset tools take the tag in place of the id.
+- Record every asset's federal tax basis beside its book value (books.set_asset_tax_basis, or tax_basis_rule on books.register_asset): cost for a purchase; for a member's contribution, the member's adjusted basis (what they paid, less depreciation they took) with rule personal_use_conversion (their personal property: tax basis is the lesser of value and their basis) or carryover (their business property). Book value stays fair market value.
+- books.export fixed_asset_register is the register for the CPA; books.show asset opens one in the viewer.
@@ -0,0 +1,11 @@
+# Parties and TINs
+
+- Keep the directory current. Every counterparty (vendor, contractor, landlord, customer, payout platform, tax agency, bank or card issuer, member, employee) gets a party: books.add_party with its roles (books.add_vendor and books.add_customer link their record to the party of the same name, or make one).
+- Tag every entry with its party (books.draft_entry party, or books.set_entry_party; a party with a vendor record tags the vendor for 1099s too).
+- An entry with several counterparties names them all with parties ([{party, amount?|percent?}] on books.draft_entry or books.set_entry_party): there is no "joint" party. A joint member transaction (paid from or reimbursed to the members' joint funds through a payable to members, a contribution from joint funds, a distribution to both) names both members with no shares, and their shares derive (from their capital or distribution lines on the entry, else their member shares in the settings); when the split is uneven, or a party isn't a member, give each party an exact amount (or a percent).
+- The post_entry preview lists each party's resolved share (parties) and refuses to post (party_shares, parties_error) until the shares add up to what the entry moved; show the split to the human before confirming.
+- Every post_entry preview says where the entry stands (party_policy, party_missing, party_suggestions): under the `[books] parties` setting "suggest" (the default), when party_missing, name the likely party to the human and tag it (or add it) before confirming; under "require", posting is refused (party_required) until the entry names a party or is marked as having none (books.set_entry_party with party null and no_party_reason, or draft_entry no_party_reason: only for an entry with truly no counterparty, like a transfer between the company's own accounts); under "off", don't raise it.
+- Record W-9 facts (books.set_w9) for contractors and landlords before paying them, and W-4 facts (books.set_w4) for employees before their first payroll; name the employee party on every books.run_payroll line.
+- Never put a full TIN or SSN anywhere in the books, only the last four digits: the engine refuses any nine-digit number in a party field. The full TIN goes only to the encrypted TIN vault, and every member's and every 1099 payee's belongs there: books.set_tin (party, tin, tin_type: ssn, ein, itin; any role, so each member's SSN for their K-1) and books.set_w9 with tin and tin_type for a payee's W-9, and the signed form with w9_file_path (never books.file_document or books.attach_receipt: the form shows the TIN).
+- Never repeat a TIN back to the human, in chat, a description, note, file name, version-history message, or anywhere else; tools show the last four only. books.get_w9 writes the form out for the human (never open or read it yourself); books.purge_tin (preview, then confirmed, with a reason) deletes a TIN no longer needed.
+- books.parties lists the directory, books.party shows one party with the year's totals, and books.show party opens it in the viewer. Archive (books.update_party archived) parties no longer dealt with; never delete history.
@@ -0,0 +1,4 @@
+# Prepaid expenses, deferred revenue and recurring entries
+
+- Prepaid expenses and deferred revenue: record the original payment (with its receipt), then books.create_schedule; books.run_schedules posts the monthly amortization (preview first; exempt from the receipt policy like depreciation).
+- Recurring entries (books.create_recurring, books.run_recurring) only ever create drafts: attach each actual receipt and post through the normal preview.
@@ -0,0 +1,6 @@
+# Reconciliation
+
+- Every month, for each bank, cash, and card account: file the statement (books.file_document category statement), record what it says (books.record_statement), mark the lines it shows (books.mark_cleared), preview books.reconcile with statement_attachment, and confirm with confirmed=true once the difference is exactly zero: that records the reconciliation with its statement.
+- Never confirm by forcing the numbers; find the difference.
+- books.void_reconciliation (with a reason) undoes a mistake; books.void_statement (with a reason) a mis-recorded statement, to record it again.
+- books.digest lists unreconciled_accounts: accounts not reconciled through the end of last month.
@@ -0,0 +1,4 @@
+# Revenue and payouts
+
+- Platform payouts (app stores, payment processors, marketplaces): never book the net deposit as revenue. books.record_payout grosses it up (gross revenue, fees, adjustments) into a draft and refuses unless it reconciles to the cent; attach the payout statement, then preview and post.
+- Invoices and bills: books.create_invoice, books.receive_payment, books.create_bill and books.pay_bill post to the control accounts (the control-roles section).
@@ -0,0 +1,5 @@
+# Rules that change with the law
+
+- wanderbooks knows some legal amounts (like the 1099 threshold) only through a given year and never guesses past it.
+- When a tool refuses with "wanderbooks knows the ... only through", or books.digest lists stale_rules: check today's date, find the current figure from the official source (the refusal names it) or ask the human (owner, CPA), confirm it with them, and pass it explicitly.
+- Then tell the human, who can report the new value and its official source upstream so the rule is updated for everyone.
@@ -0,0 +1,8 @@
+# Settings
+
+Until settings move into the books themselves (planned next), they live in the settings file books.settings names (books_toml), a TOML file; this section changes then.
+
+- That file holds the company's facts and settings (name, fiscal year, tax form, members and their capital accounts, basis, receipt threshold, cash flow roles, close target). books.settings shows what is in force and lists problems: settings that disagree with the chart.
+- Change it when the human tells you a company fact, when a tool refuses naming a setting, when books.settings or books.digest lists a settings problem, and after books.renumber_account lists config_mentions.
+- The server reloads it whenever it changes, with no restart: after each change, call books.settings and check reload_error is null (a broken edit leaves the last good settings in force) and problems is empty.
+- Never put a member's SSN or any TIN in it.
@@ -0,0 +1,5 @@
+# Tracing figures
+
+- Reports are pure functions of the posted entries. When the human questions a figure, trace it to its entries with the tools: the report (books.trial_balance, books.profit_and_loss, books.balance_sheet, books.cash_flow), then books.search_entries and books.get_entry for the entries behind it, and books.show to put them on the human's screen.
+- Never guess, and never look for the books' files: the tools are the evidence.
+- books.verify checks the books end to end when a number looks wrong or a human asks whether the books are intact.
@@ -0,0 +1,4 @@
+# The viewer
+
+- The human usually has the read-only viewer open beside you. When they ask to see something, and after you post, call books.show so it's on their screen: an entry, an account register, a report for any dates (by month, quarter or year, against the prior period or year), a receipt or document, an asset, a party, a reconciliation, or a search.
+- The viewer never changes the books; every change goes through these tools.