feat(mcp): books.mark_sent, and the send in the read tools (P4b S5)

`books.mark_sent` records the send the human or a delegate made: the
invoice (`invoice:7` or its id), the day, who sent it (the token's name
unless given), how (email by default, or mail, portal, hand, another
channel), to whom (the bill-to email, else the customer's), whether it
was the original or a reminder (original on the first send, reminder
after), and the channel's own id. It answers with every send on the
invoice, newest last. `books.documents` rows gain `last_sent` and
`books.document` shows the sends, so "did we send it, and when" is one
read away, while a bill (which we receive) has none.

The schema lint refuses a parameter named `to` (a path-name rule), so
the recipients parameter is `recipients`; the journal event and the
result keep the plan's `to`. The tool needs `books:write`: it changes
the record, never a figure.

The handbook gains the invoices-and-bills section (S4.5 had not landed
yet) with the send procedure: the books never send, the PDF goes to the
human, and each send is recorded afterwards.

Over the wire, mark_sent_records_who_and_how: two sends (the second a
reminder with a message id), the list's `last_sent`, the document's
`sends`, and the invoice still owing its total. The P2 cutover refuses
a send before consent and takes it after.

crates/ledger-cli/tests/documents.rs

@@ -0,0 +1,94 @@
+//! P4b S5 over the wire: `books.mark_sent` records who sent an invoice,
+//! how, to whom and when, and the read tools show it (`books.documents`'
+//! `last_sent`, `books.document`'s `sends`). Expected behavior comes only
+//! from the tool descriptions and parameter/result doc comments in
+//! `src/types.rs` (the declared interface, as `tools/list` serves it) and
+//! `docs/mcp-interface.md` ("Tools — receipts & documents"); plan
+//! `served.md` P4b S5 and A-4 (the books record sends; they never send).
+
+mod common;
+
+use common::answer_of;
+use serde_json::json;
+
+/// Two sends on one invoice: the first the original (defaults: the
+/// token's name, email, today's company day), the second a reminder with
+/// the channel's message id; then `books.documents` shows the last send
+/// and `books.document` the whole record.
+#[test]
+fn mark_sent_records_who_and_how() {
+    let books = common::Books::new("p4b-s5-mark-sent");
+    let mut wire = books.session("p4b-s5");
+    let customer = answer_of(&wire.call("books.add_customer", json!({"name": "Fernhill Labs"})))
+        .unwrap()["id"]
+        .as_u64()
+        .unwrap();
+    let invoice = answer_of(&wire.call(
+        "books.create_invoice",
+        json!({"party_id": customer, "date": "2026-03-01", "due_date": "2026-03-31",
+               "lines": [{"description": "Design", "amount": "1200.00"}]}),
+    ))
+    .unwrap()["id"]
+        .as_u64()
+        .unwrap();
+
+    let first = answer_of(&wire.call(
+        "books.mark_sent",
+        json!({"invoice": format!("invoice:{invoice}"), "on": "2026-03-05",
+               "by": "Avery Quill", "recipients": ["billing@fernhill.example"]}),
+    ))
+    .unwrap();
+    assert_eq!(first["invoice"], json!(format!("invoice:{invoice}")));
+    assert_eq!(first["sends"][0]["on"], json!("2026-03-05"));
+    assert_eq!(first["sends"][0]["by"], json!("Avery Quill"));
+    assert_eq!(
+        first["sends"][0]["via"],
+        json!("email"),
+        "the default channel"
+    );
+    assert_eq!(first["sends"][0]["to"], json!(["billing@fernhill.example"]));
+    assert_eq!(
+        first["sends"][0]["kind"],
+        json!("original"),
+        "the first send is the original"
+    );
+
+    // The second names no `by`, `via` or `kind`: this session's token
+    // (the agent), email, and a reminder now that one send is recorded.
+    let second = answer_of(&wire.call(
+        "books.mark_sent",
+        json!({"invoice": invoice.to_string(), "on": "2026-03-20",
+               "recipients": ["billing@fernhill.example"], "reference": "msg-2",
+               "note": "Second copy"}),
+    ))
+    .unwrap();
+    let sends = second["sends"].as_array().unwrap();
+    assert_eq!(sends.len(), 2, "{second}");
+    assert_eq!(sends[1]["by"], json!("test"), "the token's name");
+    assert_eq!(sends[1]["via"], json!("email"));
+    assert_eq!(sends[1]["kind"], json!("reminder"));
+    assert_eq!(sends[1]["reference"], json!("msg-2"));
+    assert_eq!(sends[1]["note"], json!("Second copy"));
+
+    let listed = answer_of(&wire.call("books.documents", json!({"kind": "invoices"}))).unwrap();
+    assert_eq!(
+        listed["documents"][0]["ref"],
+        json!(format!("invoice:{invoice}"))
+    );
+    assert_eq!(
+        listed["documents"][0]["last_sent"],
+        json!("2026-03-20"),
+        "the list shows the latest send"
+    );
+    let one = answer_of(&wire.call(
+        "books.document",
+        json!({"ref": format!("invoice:{invoice}"), "as_of": "2026-03-31"}),
+    ))
+    .unwrap();
+    assert_eq!(one["sends"].as_array().unwrap().len(), 2);
+    assert_eq!(
+        one["outstanding"],
+        json!("1200.00"),
+        "a send changes no figure"
+    );
+}

crates/ledger-cli/tests/format_upgrade.rs

@@ -703,6 +703,16 @@ fn books_p2_served_cut_over_whole() {
     // A project by name alone is a plain class, which P2 reads.
     a.call("books.add_project", json!({"name": "Lighthouse"}))
         .unwrap();
+    // An invoice for the send below: a document P2 reads (no new fields),
+    // so it is written before the go-ahead; its send waits for it.
+    let invoice = a
+        .call(
+            "books.create_invoice",
+            json!({"party_id": 1, "date": "2026-01-05", "due_date": "2026-02-04",
+                   "lines": [{"description": "Design", "amount": "400.00"}]}),
+        )
+        .unwrap()["id"]
+        .clone();
     let waiting = journal(&dir);
     let refused: Vec<(&str, Value)> = vec![
         // An invoice's or bill's line naming its project
@@ -729,6 +739,13 @@ fn books_p2_served_cut_over_whole() {
             json!({"decided_by": "Avery Quill",
                    "changes": [{"key": "invoicing.default_terms", "value": "Net 30"}]}),
         ),
+        // A recorded send (invoice.sent, documents_v2, P4b S5): an older
+        // version refuses the type.
+        (
+            "books.mark_sent",
+            json!({"invoice": invoice.to_string(), "on": "2026-01-06",
+                   "by": "Avery Quill", "recipients": ["billing@fernhill.example"]}),
+        ),
         (
             "books.add_account",
             json!({"code": "4900", "name": "Gain on sale", "account_type": "revenue",

crates/ledger-cli/tests/mcp_journeys.rs

@@ -125,7 +125,7 @@ fn mcp_end_to_end() {
     // Tool listing: the narrow tools; chart is read-only.
     let list = mcp.request("tools/list", json!({}));
     let tools = list["result"]["tools"].as_array().unwrap();
-    assert_eq!(tools.len(), 122, "expected 122 tools, got {}", tools.len());
+    assert_eq!(tools.len(), 123, "expected 123 tools, got {}", tools.len());
     // Files come in as tool input: books.begin_upload, never a local path.
     assert!(tools.iter().any(|t| t["name"] == "books.begin_upload"));
     assert!(!tools.iter().any(|t| t["name"] == "books.import_local_file"));