wip: pause checkpoint — P6 feature complete, gate interrupted (not for merge)

crates/ledger-mcp/handbook/evidence-and-receipts.md

@@ -5,3 +5,8 @@
 - 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).
+- **Reading a file.** Call books.get_receipt first: its default answer gives what the file is, the first 8 KiB of the text it was read as, and how many pages it has. Read the text (`view text` gives all of it). Open a page picture (`view page_image`, `page` 1 for the first) only when the text is empty or looks wrong on a page you must check, and never ask for `view bytes` into your context: a file goes to the human as a download, not through you (D-46). A picture-only receipt has no text by design (no OCR): read its pages.
+- **When a file's text failed.** A PDF whose reading failed is listed in Needs attention; read its pages and, if you need the words, ask the human. Do not retype or re-save a file to get it past a check.
+- **The same file twice.** Filing bytes the books already hold returns the existing attachment and links it to the new subject: one record, several subjects. Older books may hold two records of one file; `books.consolidate_duplicates` previews them (the oldest is kept, linked where the others were, and the rest withdrawn as duplicates, nothing deleted). It refuses whole rather than leave a posted entry the policy covers with no evidence. Annotations of a withdrawn duplicate are not moved: annotate the kept file.
+- **Annotating a receipt.** Record what you read off it with books.annotate_attachment: the receipt number, payee, amount (a decimal string), date, instrument, category, source, who is to be reimbursed, and a note. It changes no amount and no file. Receipt numbers run from the highest one annotated: the answer's `next_receipt_number` is the one to give the next new receipt, so numbers are never reused.
+- **Who paid, and who was paid back.** An expense a member paid personally is the company borrowing from them and spending it (the cash flow statement shows both). When a payment pays them back, record what it settles with books.set_entry_settles on the payment, naming the entries it pays back; Needs attention asks until you do, once per entry. Never guess which expense a payment covered (no oldest-first rule): ask the human.

crates/ledger-mcp/handbook/format-upgrade.md

@@ -5,3 +5,5 @@
 - Only the owner can agree to the upgrade, with the owner passphrase: in the app, which asks each time it opens the books, or with `wanderbooks books upgrade ID` in a terminal. No tool can, and you never ask for, take or type the passphrase. Tell the human, in plain words: the books wait for their go-ahead, what was refused, and that saying no keeps the books working as they are.
 - Before it upgrades, the server makes a backup of the books, their vault and keys included, and proves it whole; a backup that can't be made or proven upgrades nothing. Then the books move to the new format in one step, on the record.
 - After the upgrade an older version of wanderbooks can't open these books; the backup made first keeps them as they were. Going back is the owner's choice, never yours.
+
+- The journal features an upgrade can add: `members_cumulative`, `account_renamed`, `require_tax_category`, `tax_categories_gain_exempt`, `disposal_before_service`, `depreciation_catch_up`, `party_creditors`, `payment_instruments`, `vendor_1099_decisions`, `schedule_convention`, `month_reposting`, `asset_basis`, `projects`, `document_line_projects`, `document_standing`, `documents_v2`, and `attachment_text` (P6: a filed file's extracted text, what a human annotated of it, and the entries a payment settles). All are declared at once; a version that doesn't know one stops at the declaration instead of misreading the books.