fix: Windows reads of lock files, update paths cfg(unix), merge main again (P11c)

spec_vault swept every file under a book, lock files included; on Windows
a held LockFileEx lock is mandatory and the read failed. The locks are
already dedicated files (never data), so the test skips *.lock. Merged
main (P13 step 6, the macOS server.log assert, P11a's AppImage identity):
host.rs keeps main's five-field identity on Unix and size/last-write on
Windows; the update poll and set_program_version are Unix-only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp

crates/ledger-mcp/src/access.rs

@@ -86,6 +86,7 @@ pub(crate) struct Call {
     action: &'static str,
     subject: String,
     args_digest: Option<String>,
+    agent: Option<ledger_store::access::Agent>,
 }
 
 /// Why a call wasn't run, for its record and its answer.
@@ -124,6 +125,7 @@ impl Call {
             action,
             subject: subject.to_string(),
             args_digest: None,
+            agent: None,
         }
     }
 
@@ -140,6 +142,16 @@ impl Call {
         self.args_digest = args_digest;
     }
 
+    /// This call, with what the agent said about itself (`books.start`).
+    pub(crate) fn with_agent(&mut self, agent: Option<ledger_store::access::Agent>) {
+        self.agent = agent;
+    }
+
+    /// The client program's name, as it named itself at `initialize`.
+    pub(crate) fn client_name(&self) -> Option<String> {
+        self.client.as_ref().map(|c| c.name.clone())
+    }
+
     /// The call's caller, if the door named one.
     pub(crate) fn caller(&self) -> Option<&Caller> {
         self.caller.as_ref()
@@ -172,6 +184,7 @@ impl Call {
             args_digest: self.args_digest.clone(),
             result,
             head_after,
+            agent: self.agent.clone(),
         };
         match self.log.record(&access) {
             Ok(_) => Ok(()),

crates/ledger-mcp/src/guards.rs

@@ -0,0 +1,180 @@
+//! The guards: the named ways the books refuse a change, each with the
+//! tool that remedies it.
+//!
+//! ```text
+//! GOAL: an agent that is refused is told which rule refused it and which
+//!       tool to call next, in the same words every time.
+//! SOURCE: plan/served.md 4.6 (the result envelope: `guards` carry a code,
+//!         a message and a remedy tool); DECISION (P5).
+//! INVARIANTS:
+//!   1. Every guard names a remedy tool that exists (test
+//!      `every_guard_names_an_existing_tool`).
+//!   2. A code is spelled one way: the enum's `code()`; a refusal whose
+//!      text is `{"code": .., "message": ..}` JSON or says a code in words
+//!      becomes the guard of that code, and any other refusal has none.
+//! ```
+
+use serde_json::{Value, json};
+
+/// Every guard code the books know.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum Guard {
+    /// The preview a confirmation carries is not the one the books would
+    /// show now.
+    StalePreview,
+    /// The books wait for the owner's format upgrade.
+    FormatUpgradePending,
+    /// The evidence policy wants a receipt before this posts.
+    ReceiptRequired,
+    /// An approval rule wants an approver's go-ahead.
+    ApprovalRequired,
+    /// The entry's party shares do not add up.
+    PartyShares,
+    /// The parties setting requires a party (or a no-party reason).
+    PartyRequired,
+    /// Drafts stand in the way of a close.
+    OpenDrafts,
+    /// A line on a control account carries no document tag.
+    UntaggedControlLine,
+    /// A vendor already has a bill with this reference.
+    DuplicateVendorRef,
+    /// The first invoice number cannot change once one is issued.
+    FirstNumberLocked,
+    /// No audit stands at the books' current head to rest this on (plan
+    /// P8): run `books.audit`.
+    AuditRequired,
+}
+
+impl Guard {
+    /// Every guard, for the registry test.
+    pub(crate) const ALL: [Guard; 11] = [
+        Guard::StalePreview,
+        Guard::FormatUpgradePending,
+        Guard::ReceiptRequired,
+        Guard::ApprovalRequired,
+        Guard::PartyShares,
+        Guard::PartyRequired,
+        Guard::OpenDrafts,
+        Guard::UntaggedControlLine,
+        Guard::DuplicateVendorRef,
+        Guard::FirstNumberLocked,
+        Guard::AuditRequired,
+    ];
+
+    /// The code an agent reads.
+    pub(crate) fn code(self) -> &'static str {
+        match self {
+            Guard::StalePreview => "stale_preview",
+            Guard::FormatUpgradePending => "format_upgrade_pending",
+            Guard::ReceiptRequired => "receipt_required",
+            Guard::ApprovalRequired => "approval_required",
+            Guard::PartyShares => "party_shares",
+            Guard::PartyRequired => "party_required",
+            Guard::OpenDrafts => "open_drafts",
+            Guard::UntaggedControlLine => "untagged_control_line",
+            Guard::DuplicateVendorRef => "duplicate_vendor_ref",
+            Guard::FirstNumberLocked => "first_number_locked",
+            Guard::AuditRequired => "audit_required",
+        }
+    }
+
+    /// The guard of a code.
+    pub(crate) fn from_code(code: &str) -> Option<Guard> {
+        Self::ALL.into_iter().find(|g| g.code() == code)
+    }
+
+    /// The tool that remedies it; `tool` is the call that was refused (a
+    /// stale preview is remedied by previewing it again).
+    pub(crate) fn remedy_tool(self, tool: &str) -> String {
+        match self {
+            Guard::StalePreview => return tool.to_string(),
+            Guard::FormatUpgradePending => "books.start",
+            Guard::ReceiptRequired => "books.attach_receipt",
+            Guard::ApprovalRequired => "books.approve_entry",
+            Guard::PartyShares | Guard::PartyRequired => "books.set_entry_party",
+            Guard::OpenDrafts => "books.list_drafts",
+            Guard::UntaggedControlLine => "books.control_check",
+            Guard::DuplicateVendorRef => "books.search_entries",
+            Guard::FirstNumberLocked => "books.settings",
+            Guard::AuditRequired => "books.audit",
+        }
+        .to_string()
+    }
+}
+
+/// The guards a refusal's text carries, as the envelope shows them:
+/// `[{code, message, remedy_tool, remedy_args?}]`. `tool` is the refused
+/// call.
+pub(crate) fn from_refusal(tool: &str, text: &str) -> Vec<Value> {
+    // A structured refusal: the JSON the tool built.
+    if let Ok(Value::Object(o)) = serde_json::from_str::<Value>(text)
+        && let Some(code) = o.get("code").and_then(Value::as_str)
+    {
+        let remedy = o
+            .get("remedy_tool")
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .or_else(|| Guard::from_code(code).map(|g| g.remedy_tool(tool)));
+        if let Some(remedy) = remedy {
+            let mut g = json!({
+                "code": code,
+                "message": o.get("message").and_then(Value::as_str).unwrap_or(code),
+                "remedy_tool": remedy,
+            });
+            if let Some(entry) = o.get("entry_id") {
+                g["remedy_args"] = json!({ "entry_id": entry });
+            }
+            return vec![g];
+        }
+        return Vec::new();
+    }
+    // A refusal that names its code in words (the store's).
+    for g in Guard::ALL {
+        if text.starts_with(g.code()) {
+            return vec![json!({
+                "code": g.code(),
+                "message": text,
+                "remedy_tool": g.remedy_tool(tool),
+            })];
+        }
+    }
+    Vec::new()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::server::BooksServer;
+
+    #[test]
+    fn every_guard_names_an_existing_tool() {
+        let names: Vec<String> = BooksServer::tool_router()
+            .list_all()
+            .into_iter()
+            .map(|t| t.name.to_string())
+            .collect();
+        for g in Guard::ALL {
+            let remedy = g.remedy_tool("books.post_entry");
+            assert!(
+                names.contains(&remedy),
+                "guard {} names {remedy}, which is no tool",
+                g.code()
+            );
+            assert_eq!(Guard::from_code(g.code()), Some(g));
+        }
+    }
+
+    #[test]
+    fn a_refusal_becomes_its_guard() {
+        let text = json!({"code":"approval_required","message":"needs approval","entry_id":7,"remedy_tool":"books.approve_entry"}).to_string();
+        let g = from_refusal("books.post_entry", &text);
+        assert_eq!(g[0]["code"], "approval_required");
+        assert_eq!(g[0]["remedy_args"]["entry_id"], 7);
+        let g = from_refusal(
+            "books.create_invoice",
+            "format_upgrade_pending: this needs documents_v2",
+        );
+        assert_eq!(g[0]["remedy_tool"], "books.start");
+        assert!(from_refusal("books.x", "no such account").is_empty());
+    }
+}

crates/ledger-mcp/src/handbook.rs

@@ -87,6 +87,10 @@ pub const SECTIONS: &[(&str, &str)] = &[
     ),
     ("1099", include_str!("../handbook/1099.md")),
     ("cpa-handoff", include_str!("../handbook/cpa-handoff.md")),
+    (
+        "attestations-and-audit",
+        include_str!("../handbook/attestations-and-audit.md"),
+    ),
     (
         "settings-and-conventions",
         include_str!("../handbook/settings-and-conventions.md"),

crates/ledger-mcp/src/local.rs

@@ -1121,6 +1121,7 @@ async fn refused_at_door(
             args_digest: None,
             result: Outcome::Refused(code.into()),
             head_after: None,
+            agent: None,
         };
         let written = tokio::task::spawn_blocking(move || access.record(&record)).await;
         if !matches!(written, Ok(Ok(_))) {
@@ -1350,6 +1351,7 @@ async fn upload(
             args_digest: None,
             result: outcome.clone(),
             head_after: None,
+            agent: None,
         };
         let recorded = access.record(&record).is_ok();
         if !recorded && received.is_ok() {
@@ -1524,6 +1526,7 @@ async fn fetch(
                 Err((_, code, _)) => Outcome::Refused((*code).into()),
             },
             head_after: None,
+            agent: None,
         };
         let recorded = access.record(&record).is_ok();
         (found, recorded)

crates/ledger-mcp/src/next_steps.rs

@@ -0,0 +1,605 @@
+//! The result envelope: what every tool result carries besides its own
+//! fields (plan 4.6).
+//!
+//! ```text
+//! GOAL: an agent never has to guess what to do after a call: every result
+//!       says what follows (`next_steps`), what refused it and which tool
+//!       remedies that (`guards`), what to tell the human (`warnings`),
+//!       and, on a tool that can change the books, where the journal ends
+//!       now (`head`).
+//! SOURCE: plan/served.md 4.6 and P5 step 1; DECISION (P5).
+//! INVARIANTS:
+//!   1. The envelope is applied in one place (`apply`, called by
+//!      `call_tool`), so no tool can forget it.
+//!   2. Every result of a tool that is not read-only has a `head` (the
+//!      journal after the call's last write) and at least one next step; a
+//!      read has `next_steps` when something follows it and nothing else (a
+//!      resource and its tool agree). `guards` is on a refusal, and a
+//!      success without warnings has no `warnings` key.
+//!   3. A tool's own fields are never overwritten: a payload that already
+//!      has `next_steps`, `guards`, `warnings` or `head` keeps it.
+//!   4. A refused call has no head and no steps; a refusal that is a
+//!      guard (guards.rs) carries it as `structuredContent.guards`.
+//!   5. Next steps from the books' attention list are the viewer's own
+//!      items (ledger_package::attention), filtered to the subject the
+//!      call touched.
+//! ```
+
+use super::BooksServer;
+use super::guards;
+use ledger_package::{Integrity, Severity, Target};
+use rmcp::model::{CallToolResponse, ContentBlock};
+use serde_json::{Map, Value, json};
+use std::collections::HashSet;
+use std::sync::OnceLock;
+
+/// One thing to do next.
+#[derive(Clone, Debug)]
+pub(crate) struct Step {
+    /// The tool to call.
+    pub tool: Option<String>,
+    /// Or the prompt to run.
+    pub prompt: Option<String>,
+    /// Or a command for the human's computer (a download).
+    pub command: Option<String>,
+    /// Its arguments.
+    pub args: Option<Value>,
+    /// Why.
+    pub why: String,
+    /// Whether the work is not done without it.
+    pub required: bool,
+}
+
+impl Step {
+    pub(crate) fn tool(tool: &str, args: Option<Value>, why: &str, required: bool) -> Step {
+        Step {
+            tool: Some(tool.into()),
+            prompt: None,
+            command: None,
+            args,
+            why: why.into(),
+            required,
+        }
+    }
+
+    fn to_json(&self) -> Value {
+        let mut o = Map::new();
+        if let Some(t) = &self.tool {
+            o.insert("tool".into(), json!(t));
+        }
+        if let Some(p) = &self.prompt {
+            o.insert("prompt".into(), json!(p));
+        }
+        if let Some(c) = &self.command {
+            o.insert("command".into(), json!(c));
+        }
+        if let Some(a) = &self.args {
+            o.insert("args".into(), a.clone());
+        }
+        o.insert("why".into(), json!(self.why));
+        o.insert("required".into(), json!(self.required));
+        Value::Object(o)
+    }
+}
+
+/// The tools that are not read-only: their results carry a `head`.
+pub(crate) fn mutating_tools() -> &'static HashSet<String> {
+    static SET: OnceLock<HashSet<String>> = OnceLock::new();
+    SET.get_or_init(|| {
+        BooksServer::tool_router()
+            .list_all()
+            .into_iter()
+            .filter(|t| {
+                !t.annotations
+                    .as_ref()
+                    .and_then(|a| a.read_only_hint)
+                    .unwrap_or(false)
+            })
+            .map(|t| t.name.to_string())
+            .collect()
+    })
+}
+
+/// The steps a tool's own result implies (no books needed): the confirm
+/// after a preview, and what follows a particular act.
+pub(crate) fn tool_steps(
+    tool: &str,
+    args: Option<&Map<String, Value>>,
+    result: &Value,
+) -> Vec<Step> {
+    let mut steps = Vec::new();
+    let confirmed = args
+        .and_then(|a| a.get("confirmed"))
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    let entry = result
+        .get("entry_id")
+        .or_else(|| args.and_then(|a| a.get("entry_id")))
+        .and_then(Value::as_u64);
+    let with_entry = |id: u64| Some(json!({ "entry_id": id }));
+    // A preview: what is missing first, then the human confirms, then the
+    // same call with the digest.
+    // An audit already run is not previewed: its run is the answer.
+    let already_run = tool == "books.audit"
+        && result.get("status").and_then(Value::as_str) == Some("already_run");
+    if let (false, Some(preview), Some(args)) = (
+        confirmed || already_run,
+        result.get("preview").and_then(Value::as_str),
+        args,
+    ) {
+        if tool == "books.post_entry"
+            && result.get("receipt_missing").and_then(Value::as_bool) == Some(true)
+            && let Some(id) = entry
+        {
+            steps.push(Step::tool(
+                "books.attach_receipt",
+                with_entry(id),
+                "This entry needs a receipt before it posts: attach the file (upload it first).",
+                true,
+            ));
+            steps.push(Step::tool(
+                "books.set_draft_state",
+                Some(json!({ "entry_id": id, "state": "awaiting_evidence" })),
+                "Or leave the draft waiting, with a note saying what for, until the receipt arrives.",
+                false,
+            ));
+        }
+        let mut confirm = args.clone();
+        confirm.insert("confirmed".into(), json!(true));
+        confirm.insert("preview".into(), json!(preview));
+        steps.push(Step::tool(
+            tool,
+            Some(Value::Object(confirm)),
+            "Show this preview to the human; only when they agree, make the same call with confirmed true and this preview.",
+            true,
+        ));
+        return steps;
+    }
+    match tool {
+        "books.set_setting" | "books.add_account" => {
+            steps.push(Step::tool(
+                "books.add_account",
+                None,
+                "Add the accounts the human's chart needs, one at a time.",
+                false,
+            ));
+            steps.push(Step::tool(
+                "books.draft_entry",
+                None,
+                "Or record a transaction: draft it, add its lines, preview it, then post.",
+                false,
+            ));
+        }
+        "books.draft_entry" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.add_line",
+                    with_entry(id),
+                    "Add the draft's lines: each is an account, a side and an amount; debits must equal credits.",
+                    true,
+                ));
+            }
+        }
+        "books.add_line" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.add_line",
+                    with_entry(id),
+                    "Add the next line of the draft.",
+                    false,
+                ));
+                steps.push(Step::tool(
+                    "books.post_entry",
+                    with_entry(id),
+                    "When the lines balance, preview the post for the human.",
+                    false,
+                ));
+            }
+        }
+        "books.set_draft_state" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.attach_receipt",
+                    with_entry(id),
+                    "When the document arrives, upload and attach it to this draft.",
+                    false,
+                ));
+            }
+        }
+        "books.attach_receipt" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.post_entry",
+                    with_entry(id),
+                    "The evidence is attached: preview the post again for the human.",
+                    false,
+                ));
+            }
+        }
+        "books.post_entry" | "books.reverse_entry" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.show",
+                    with_entry(id),
+                    "Show the human the entry and what it moved.",
+                    false,
+                ));
+                if tool == "books.post_entry" {
+                    steps.push(Step::tool(
+                        "books.reverse_entry",
+                        with_entry(id),
+                        "Only if this was posted in error: reverse it (posted entries are never edited).",
+                        false,
+                    ));
+                }
+            }
+        }
+        "books.draft_from_template" => {
+            if let Some(id) = entry {
+                steps.push(Step::tool(
+                    "books.post_entry",
+                    with_entry(id),
+                    "Preview the draft for the human, who then confirms it.",
+                    false,
+                ));
+            }
+        }
+        "books.record_statement" => {
+            steps.push(Step::tool(
+                "books.mark_cleared",
+                None,
+                "Mark each transaction the statement shows as cleared.",
+                true,
+            ));
+            let (account, end, close, attachment) = (
+                result.get("account_code"),
+                result.get("period_end"),
+                result.get("closing_balance"),
+                result.get("attachment_id"),
+            );
+            if let (Some(account), Some(end), Some(close), Some(attachment)) =
+                (account, end, close, attachment)
+            {
+                steps.push(Step::tool(
+                    "books.reconcile",
+                    Some(json!({
+                        "account": account,
+                        "statement_date": end,
+                        "statement_balance": close,
+                        "statement_attachment": attachment,
+                    })),
+                    "When every line is marked, preview the reconciliation against the statement.",
+                    false,
+                ));
+            }
+        }
+        "books.mark_cleared" => steps.push(Step::tool(
+            "books.reconcile",
+            None,
+            "Mark the rest, then preview the reconciliation against the statement.",
+            false,
+        )),
+        "books.reconcile" => steps.push(Step::tool(
+            "books.reconciliations",
+            None,
+            "See the reconciliation among the account's others.",
+            false,
+        )),
+        "books.list_periods" => {
+            for p in result
+                .get("periods")
+                .and_then(Value::as_array)
+                .into_iter()
+                .flatten()
+                .filter(|p| p.get("status").and_then(Value::as_str) == Some("open"))
+                .take(3)
+            {
+                if let Some(id) = p.get("id").and_then(Value::as_u64) {
+                    steps.push(Step::tool(
+                        "books.close_period",
+                        Some(json!({ "period_id": id })),
+                        "Once everything in this period is recorded and reconciled, preview its close.",
+                        false,
+                    ));
+                }
+            }
+        }
+        "books.close_period" => {
+            let period = result
+                .get("period_id")
+                .or_else(|| args.and_then(|a| a.get("period_id")))
+                .and_then(Value::as_u64);
+            // The chain first (cheap, and what every close has always
+            // offered: the month_end_close eval follows it), then the
+            // audit the attestation rests on (P8).
+            steps.push(Step::tool(
+                "books.verify",
+                None,
+                "Verify the journal's chain and the projection after the close.",
+                false,
+            ));
+            steps.push(Step::tool(
+                "books.audit",
+                Some(json!({ "scope": "month" })),
+                "Audit the books through the month's end; the attestation rests on that run.",
+                false,
+            ));
+            steps.push(Step::tool(
+                "books.attest_period",
+                period.map(|p| json!({ "period": p.to_string() })),
+                "Once the audit is run and the receipts read, attest the period you closed.",
+                false,
+            ));
+        }
+        "books.audit" => {
+            if let Some(id) = result.pointer("/run/id").and_then(Value::as_u64) {
+                steps.push(Step::tool(
+                    "books.workpaper",
+                    Some(json!({ "id": id })),
+                    "Read the workpaper: what was checked and every finding. Fix findings with journaled corrections, then audit again.",
+                    false,
+                ));
+                steps.push(Step::tool(
+                    "books.attest_receipt",
+                    None,
+                    "Have separate verifier agents read each receipt (books.get_receipt, then its page image) and attest it.",
+                    false,
+                ));
+                steps.push(Step::tool(
+                    "books.review_entry",
+                    None,
+                    "Review each posted entry whole.",
+                    false,
+                ));
+                steps.push(Step::tool(
+                    "books.attest_period",
+                    None,
+                    "Then attest the period this audit covers.",
+                    false,
+                ));
+            }
+        }
+        "books.attest_receipt" => steps.push(Step::tool(
+            "books.review_entry",
+            args.and_then(|a| a.get("entry_id"))
+                .map(|e| json!({ "entry_id": e })),
+            "Review the whole entry the receipt supports.",
+            false,
+        )),
+        "books.review_entry" => steps.push(Step::tool(
+            "books.attestations",
+            None,
+            "See which claims count at the bar.",
+            false,
+        )),
+        "books.attest_period" => {
+            steps.push(Step::tool(
+                "books.attestations",
+                None,
+                "See which claims count at the bar before the CPA package.",
+                false,
+            ));
+            steps.push(Step::tool(
+                "books.export_cpa_package",
+                None,
+                "When the year is audited and attested at the bar, hand the books to the CPA.",
+                false,
+            ));
+        }
+        "books.export_cpa_package" => {
+            if let Some(cmd) = result.pointer("/file/download").and_then(Value::as_str) {
+                steps.push(Step {
+                    tool: None,
+                    prompt: None,
+                    command: Some(cmd.to_string()),
+                    args: None,
+                    why: "Run this to save the package in a folder you name, within 15 minutes."
+                        .into(),
+                    required: true,
+                });
+            }
+        }
+        _ => {}
+    }
+    steps
+}
+
+/// The attention items about the subject of the call, as steps.
+fn attention_steps(
+    server: &BooksServer,
+    subject: Subject,
+    store: &ledger_store::Store,
+) -> Vec<Step> {
+    let cfg = server.settings();
+    let settings = ledger_package::Settings {
+        company: &cfg.company,
+        cash_accounts: &cfg.roles.cash,
+        financing_accounts: &cfg.roles.financing,
+        investing_accounts: &cfg.roles.investing,
+    };
+    let today = ledger_core::settings::today_in(cfg.timezone.as_deref());
+    let items = ledger_package::find_with(store, today, &settings, &Integrity::default());
+    items
+        .into_iter()
+        .filter(|a| match (subject, a.target) {
+            (Subject::Entry(s), Target::Entry(t)) => s == t,
+            (Subject::Invoice(s), Target::Invoice(t)) => s == t,
+            _ => false,
+        })
+        .filter_map(|a| {
+            let (tool, args) = a.tool?;
+            let args = if args.is_null() {
+                match (a.target, tool.as_str()) {
+                    (
+                        Target::Entry(id),
+                        "books.attach_receipt"
+                        | "books.set_entry_party"
+                        | "books.set_entry_settles",
+                    ) => Some(json!({ "entry_id": id })),
+                    _ => None,
+                }
+            } else {
+                Some(args)
+            };
+            let title: String = a.title.chars().take(160).collect();
+            Some(Step::tool(
+                &tool,
+                args,
+                &title,
+                a.severity == Severity::Problem,
+            ))
+        })
+        .take(4)
+        .collect()
+}
+
+/// What a call touched, for the attention filter.
+#[derive(Clone, Copy)]
+enum Subject {
+    Entry(u64),
+    Invoice(u64),
+}
+
+fn subject_of(args: Option<&Map<String, Value>>, result: &Value) -> Option<Subject> {
+    let pick = |k: &str| {
+        result
+            .get(k)
+            .or_else(|| args.and_then(|a| a.get(k)))
+            .and_then(Value::as_u64)
+    };
+    pick("entry_id")
+        .map(Subject::Entry)
+        .or_else(|| pick("invoice_id").map(Subject::Invoice))
+}
+
+/// The fallback of a tool that changes things and has nothing particular
+/// to follow it.
+fn digest_step() -> Step {
+    Step::tool(
+        "books.digest",
+        None,
+        "See what changed and offer it to the human.",
+        false,
+    )
+}
+
+/// Put the envelope on a tool's answer (INVARIANT 1). `wrote` is the head
+/// after the call's last write, when it wrote.
+pub(crate) fn apply(
+    server: &BooksServer,
+    tool: &str,
+    args: Option<&Map<String, Value>>,
+    out: Result<CallToolResponse, rmcp::ErrorData>,
+) -> Result<CallToolResponse, rmcp::ErrorData> {
+    let Ok(CallToolResponse::Complete(mut r)) = out else {
+        return out;
+    };
+    if r.is_error == Some(true) {
+        // INVARIANT 4.
+        let text = r
+            .content
+            .iter()
+            .find_map(|c| match c {
+                ContentBlock::Text(t) => Some(t.text.as_str()),
+                _ => None,
+            })
+            .unwrap_or("");
+        let guards = guards::from_refusal(tool, text);
+        if !guards.is_empty() && r.structured_content.is_none() {
+            r.structured_content = Some(json!({ "guards": guards }));
+        }
+        return Ok(CallToolResponse::Complete(r));
+    }
+    let Some(Value::Object(mut body)) = r.structured_content.take() else {
+        return Ok(CallToolResponse::Complete(r));
+    };
+    let before = Value::Object(body.clone());
+    let mutating = mutating_tools().contains(tool);
+    let result = Value::Object(body.clone());
+    let mut steps = tool_steps(tool, args, &result);
+    let head = if mutating {
+        server.lock().ok().map(|store| {
+            let (seq, hash) = store.head();
+            if let Some(subject) = subject_of(args, &result)
+                && steps.iter().all(|s| !s.required)
+            {
+                steps.extend(attention_steps(server, subject, &store));
+            }
+            json!({ "seq": seq, "hash": hash })
+        })
+    } else {
+        None
+    };
+    if mutating && steps.is_empty() {
+        steps.push(digest_step());
+    }
+    // A tool that can change the books always says what follows; a read
+    // says it only when something does, so what it says is what a resource
+    // of the same name says (`books://settings` is `books.settings`).
+    // `guards` is on a refusal (above) and `warnings` is the tool's own:
+    // a success that has none says none, as the tools always did.
+    if !body.contains_key("next_steps") && (mutating || !steps.is_empty()) {
+        body.insert(
+            "next_steps".into(),
+            Value::Array(steps.iter().map(Step::to_json).collect()),
+        );
+    }
+
+    if let Some(head) = head {
+        body.entry("head").or_insert(head);
+    }
+    let after = Value::Object(body);
+    // The same JSON in the text block (server.rs INVARIANT 1).
+    for c in &mut r.content {
+        if let ContentBlock::Text(t) = c
+            && serde_json::from_str::<Value>(&t.text).is_ok_and(|v| v == before)
+        {
+            t.text = after.to_string();
+        }
+    }
+    r.structured_content = Some(after);
+    Ok(CallToolResponse::Complete(r))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_preview_gets_its_confirm_step() {
+        let args = json!({"entry_id": 3}).as_object().cloned().unwrap();
+        let steps = tool_steps(
+            "books.post_entry",
+            Some(&args),
+            &json!({"entry_id": 3, "preview": "abc", "status": "preview"}),
+        );
+        assert_eq!(steps.len(), 1);
+        let a = steps[0].args.as_ref().unwrap();
+        assert_eq!(a["confirmed"], true);
+        assert_eq!(a["preview"], "abc");
+        assert!(steps[0].required);
+    }
+
+    #[test]
+    fn every_step_a_tool_names_exists() {
+        let names: HashSet<String> = BooksServer::tool_router()
+            .list_all()
+            .into_iter()
+            .map(|t| t.name.to_string())
+            .collect();
+        let result = json!({"entry_id": 1, "file": {"download": "x"}});
+        for tool in mutating_tools() {
+            for s in tool_steps(tool, Some(&Map::new()), &result)
+                .into_iter()
+                .chain([digest_step()])
+            {
+                if let Some(t) = s.tool {
+                    assert!(
+                        names.contains(&t),
+                        "{tool}: step names {t}, which is no tool"
+                    );
+                }
+            }
+        }
+    }
+}

crates/ledger-mcp/src/opening.rs

@@ -25,6 +25,7 @@ pub(crate) fn capabilities() -> ServerCapabilities {
     ServerCapabilities::builder()
         .enable_tools()
         .enable_resources()
+        .enable_prompts()
         .build()
 }
 
@@ -85,5 +86,6 @@ mod tests {
         );
         assert!(r["capabilities"]["tools"].is_object());
         assert!(r["capabilities"]["resources"].is_object());
+        assert!(r["capabilities"]["prompts"].is_object());
     }
 }

crates/ledger-mcp/src/scopes.rs

@@ -56,7 +56,7 @@ const C: Needs = PostWhenConfirmed;
 const K: Needs = PostForApprovalRules;
 
 /// Every tool and what it needs (INVARIANT 1).
-pub const TABLE: [(&str, Needs); 133] = [
+pub const TABLE: [(&str, Needs); 140] = [
     ("books.handbook", R),
     ("books.start", R),
     // Settings are committed at once: the settings commit of the plan.
@@ -200,7 +200,17 @@ pub const TABLE: [(&str, Needs); 133] = [
     ("books.list_drafts", R),
     ("books.set_draft_state", W),
     ("books.discard_draft", C),
+    // P5
+    ("books.journal_history", R),
     ("books.preview_entry", R),
+    // P8: audits and attestations (an audit previews, then runs; a claim
+    // that someone checked is a write, not a post).
+    ("books.audit", C),
+    ("books.workpaper", R),
+    ("books.attest_receipt", W),
+    ("books.review_entry", W),
+    ("books.attest_period", W),
+    ("books.attestations", R),
 ];
 
 /// What `tool` needs, given its arguments; None for a tool this server

crates/ledger-mcp/src/server.rs

@@ -584,6 +584,8 @@ impl BooksServer {
             + Self::tax_router()
             + Self::write_offs_router()
             + Self::drafts_router()
+            + Self::journal_router()
+            + Self::audit_router()
     }
 
     /// The settings in force for this request: the books' own, taken from
@@ -1264,6 +1266,64 @@ fn resource_list() -> Vec<Resource> {
     resources
 }
 
+/// The advertised resource templates (plan 4.5; RFC 6570): the URIs a
+/// client can build, each read by `resource_body`.
+fn resource_templates() -> Vec<rmcp::model::ResourceTemplate> {
+    use rmcp::model::ResourceTemplate;
+    let mk = |uri: &str, name: &str, title: &str, description: &str| {
+        ResourceTemplate::new(uri, name)
+            .with_title(title)
+            .with_description(description)
+            .with_mime_type("application/json")
+    };
+    vec![
+        mk(
+            "books://entries/{id}",
+            "entry",
+            "An entry",
+            "One entry with its lines, receipts and history (books.get_entry).",
+        ),
+        mk(
+            "books://attachments/{id}",
+            "attachment",
+            "A stored file",
+            "A receipt or document: its metadata and the start of its text (books.get_receipt); its pages are books://attachments/{id}/page/{n}.",
+        ),
+        mk(
+            "books://journal/{seq}",
+            "journal-line",
+            "A journal line",
+            "One journal line in words (books.journal_history).",
+        ),
+        mk(
+            "books://reports/{kind}{?start,end,as_of}",
+            "report",
+            "A report",
+            "trial-balance, balance-sheet or profit-and-loss, for a day (as_of) or a range (start, end); without them as of today, or the year to date.",
+        ),
+        mk(
+            "books://digest{?since,since_seq,as_of}",
+            "digest",
+            "The activity digest",
+            "What changed, since a date, since a journal line (since_seq), as of a day; bare, this month so far.",
+        ),
+    ]
+}
+
+/// Prompts are listed and read by a token that may read the books.
+fn prompt_reader(context: &RequestContext<RoleServer>) -> Result<(), rmcp::ErrorData> {
+    match crate::access::caller(context) {
+        None => Err(rmcp::ErrorData::invalid_request(
+            crate::access::UNAUTHORIZED,
+            None,
+        )),
+        Some(c) if !c.may(ledger_store::auth::Scope::Read) => Err(
+            rmcp::ErrorData::invalid_request(crate::access::INSUFFICIENT_SCOPE, None),
+        ),
+        Some(_) => Ok(()),
+    }
+}
+
 /// The subject kinds, for messages.
 const SUBJECT_KINDS: &str = "entry, account, asset, party, project, invoice, bill, period, payroll_run, schedule, reconciliation, company";
 
@@ -1321,6 +1381,13 @@ thread_local! {
     /// The journal's head after the last write made by the request
     /// running on this thread (StoreGuard's drop), for its access record.
     static WROTE: std::cell::RefCell<Option<(u64, String)>> = const { std::cell::RefCell::new(None) };
+    /// Who the request running on this thread is, as `books.start` shows
+    /// it: `{principal, kind, scopes, client_id}`. The token's own facts
+    /// and the client's name; set at the start of the request.
+    static YOU: std::cell::RefCell<Option<serde_json::Value>> = const { std::cell::RefCell::new(None) };
+    /// What the agent said about itself in a `books.start` this request is
+    /// running (`agent`), for the call's access record.
+    static AGENT_NOTE: std::cell::RefCell<Option<ledger_store::access::Agent>> = const { std::cell::RefCell::new(None) };
     /// The company's time zone for the request running on this thread
     /// (set at its start from the settings in force: one version per
     /// request), so every "today" in it agrees.
@@ -1358,6 +1425,16 @@ fn today() -> NaiveDate {
     TIMEZONE.with(|z| ledger_core::settings::today_in(z.borrow().as_deref()))
 }
 
+/// A resource URI's query parameter `key`, when given and not empty.
+fn query_param(query: &str, key: &str) -> Option<String> {
+    query
+        .split('&')
+        .find_map(|kv| kv.strip_prefix(&format!("{key}=")))
+        .map(str::trim)
+        .filter(|v| !v.is_empty())
+        .map(str::to_string)
+}
+
 /// The `since` of a `books://digest` read: the query's `since=`, or, bare
 /// or with an empty `since=`, the first day of `today`'s month (this
 /// month so far).
@@ -1397,12 +1474,20 @@ mod access_tools;
 mod backup_tools;
 #[path = "tools/files.rs"]
 mod files;
+#[path = "guards.rs"]
+mod guards;
 #[path = "tools/instruments.rs"]
 mod instruments;
+#[path = "tools/journal.rs"]
+mod journal_tools;
 #[path = "tools/kept.rs"]
 mod kept;
+#[path = "next_steps.rs"]
+mod next_steps;
 #[path = "tools/projects.rs"]
 mod projects;
+#[path = "tools/prompts.rs"]
+mod prompts;
 pub use kept::SettingKeyOut;
 
 // The tool groups: one file each (plan/served.md 8.2 U0a). A unit adds a
@@ -1412,6 +1497,8 @@ pub use kept::SettingKeyOut;
 mod assets;
 #[path = "tools/attachments.rs"]
 mod attachments;
+#[path = "tools/audit.rs"]
+mod audit_tools;
 #[path = "tools/chart.rs"]
 mod chart;
 #[path = "tools/documents.rs"]
@@ -1500,14 +1587,17 @@ impl BooksServer {
             }
             "books://reports/trial-balance" => {
                 let Json(out) = self
-                    .trial_balance(Parameters(TrialBalanceParams::default()))
+                    .trial_balance(Parameters(TrialBalanceParams {
+                        as_of: query_param(query, "as_of"),
+                        ..TrialBalanceParams::default()
+                    }))
                     .await?;
                 json(&out)
             }
             "books://reports/balance-sheet" => {
                 let Json(out) = self
                     .balance_sheet(Parameters(BalanceSheetParams {
-                        as_of: None,
+                        as_of: query_param(query, "as_of"),
                         strict: None,
                     }))
                     .await?;
@@ -1516,8 +1606,8 @@ impl BooksServer {
             "books://reports/profit-and-loss" => {
                 let Json(out) = self
                     .profit_and_loss(Parameters(ProfitAndLossParams {
-                        start: None,
-                        end: None,
+                        start: query_param(query, "start"),
+                        end: query_param(query, "end"),
                         class: None,
                         strict: None,
                     }))
@@ -1525,16 +1615,56 @@ impl BooksServer {
                 json(&out)
             }
             "books://digest" => {
-                let since = digest_since(query, today());
+                // `since_seq` (what was posted since a journal line) wins
+                // over `since`; with neither, this month so far.
+                let since_seq = query_param(query, "since_seq")
+                    .map(|n| {
+                        n.parse::<u64>()
+                            .map_err(|_| format!("bad since_seq in {uri}"))
+                    })
+                    .transpose()?;
+                let since = if since_seq.is_some() {
+                    None
+                } else {
+                    Some(digest_since(query, today()))
+                };
                 let Json(out) = self
                     .digest(Parameters(DigestParams {
-                        since: Some(since),
-                        since_seq: None,
-                        as_of: None,
+                        since,
+                        since_seq,
+                        as_of: query_param(query, "as_of"),
                     }))
                     .await?;
                 json(&out)
             }
+            _ if path.starts_with("books://entries/") => {
+                let id: u64 = path["books://entries/".len()..]
+                    .parse()
+                    .map_err(|_| format!("bad entry resource URI: {uri}"))?;
+                let Json(out) = self
+                    .get_entry(Parameters(GetEntryParams { entry_id: id }))
+                    .await?;
+                json(&out)
+            }
+            _ if path.starts_with("books://journal/") => {
+                let seq: u64 = path["books://journal/".len()..]
+                    .parse()
+                    .map_err(|_| format!("bad journal resource URI: {uri}"))?;
+                if seq == 0 {
+                    return Err("journal seqs start at 1".into());
+                }
+                let Json(out) = self
+                    .journal_history(Parameters(journal_tools::JournalHistoryParams {
+                        after_seq: Some(seq - 1),
+                        limit: Some(1),
+                        ..Default::default()
+                    }))
+                    .await?;
+                if out.lines.first().is_none_or(|l| l.seq != seq) {
+                    return Err(format!("the journal has no line {seq}"));
+                }
+                json(&out)
+            }
             handbook::URI => {
                 let Json(out) = self.handbook(Parameters(HandbookParams::default())).await?;
                 json(&out)
@@ -1704,6 +1834,8 @@ impl ServerHandler for BooksServer {
         let running_call = call.clone();
         // Kept for the record of a call the server stopped before running.
         let request_args = request.arguments.clone();
+        let tool_name = request.name.to_string();
+        let envelope_args = request.arguments.clone();
         let result = run_blocking(&self.store, move || {
             Box::pin(async move {
                 WROTE.with(|w| w.borrow_mut().take());
@@ -1712,6 +1844,17 @@ impl ServerHandler for BooksServer {
                     .caller()
                     .map(|c| (c.token.id.clone(), c.token.name.clone()));
                 CALLER.with(|c| *c.borrow_mut() = caller);
+                AGENT_NOTE.with(|a| a.borrow_mut().take());
+                YOU.with(|y| {
+                    *y.borrow_mut() = running_call.caller().map(|c| {
+                        serde_json::json!({
+                            "principal": c.token.name,
+                            "kind": "agent",
+                            "scopes": c.token.scopes.iter().map(|s| s.as_str()).collect::<Vec<_>>(),
+                            "client_id": running_call.client_name(),
+                        })
+                    })
+                });
                 // Counted as running by now (run_blocking): hashed here.
                 let digest = Call::digest_of(request.arguments.as_ref());
                 let tcc =
@@ -1740,8 +1883,14 @@ impl ServerHandler for BooksServer {
                         std::panic::resume_unwind(panic)
                     }
                 };
+                // The result envelope (next_steps.rs INVARIANT 1).
+                let out = next_steps::apply(&server, &tool_name, envelope_args.as_ref(), out);
+                // Who asked is the request's alone: a later request on this
+                // thread (a resource read) must not see it.
+                YOU.with(|y| y.borrow_mut().take());
                 let mut c = running_call;
                 c.digested(digest);
+                c.with_agent(AGENT_NOTE.with(|a| a.borrow_mut().take()));
                 let recorded = c.record_blocking(outcome_of(&out), wrote);
                 (out, recorded)
             })
@@ -1825,6 +1974,36 @@ impl ServerHandler for BooksServer {
         Ok(ListResourcesResult::with_all_items(resource_list()))
     }
 
+    async fn list_resource_templates(
+        &self,
+        _request: Option<rmcp::model::PaginatedRequestParams>,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<rmcp::model::ListResourceTemplatesResult, rmcp::ErrorData> {
+        Ok(rmcp::model::ListResourceTemplatesResult::with_all_items(
+            resource_templates(),
+        ))
+    }
+
+    async fn list_prompts(
+        &self,
+        _request: Option<rmcp::model::PaginatedRequestParams>,
+        context: RequestContext<RoleServer>,
+    ) -> Result<rmcp::model::ListPromptsResult, rmcp::ErrorData> {
+        prompt_reader(&context)?;
+        Ok(Self::prompt_list())
+    }
+
+    async fn get_prompt(
+        &self,
+        request: rmcp::model::GetPromptRequestParams,
+        context: RequestContext<RoleServer>,
+    ) -> Result<rmcp::model::GetPromptResponse, rmcp::ErrorData> {
+        prompt_reader(&context)?;
+        self.prompt_get(&request)
+            .map(Into::into)
+            .map_err(|e| rmcp::ErrorData::invalid_params(e, None))
+    }
+
     async fn read_resource(
         &self,
         request: ReadResourceRequestParams,
@@ -1922,7 +2101,10 @@ impl BooksServer {
         let server = self.clone();
         let at = uri.clone();
         let body = run_blocking(&self.store, move || {
-            Box::pin(async move { in_timezone_async(timezone, server.resource_body(&at)).await })
+            Box::pin(async move {
+                YOU.with(|y| y.borrow_mut().take());
+                in_timezone_async(timezone, server.resource_body(&at)).await
+            })
         })
         .await?;
         // A refusal quotes the URI it was given: masked like a tool's.

crates/ledger-mcp/src/server_tests.rs

@@ -9,6 +9,25 @@
 use super::*;
 use crate::server::test_support::*;
 
+/// Plan 4.2 (P5 step 2): `books.start` is loaded up front by clients that
+/// defer tools, and no other tool asks for that.
+#[test]
+fn books_start_is_always_loaded() {
+    for tool in BooksServer::tool_router().list_all() {
+        let always = tool
+            .meta
+            .as_ref()
+            .and_then(|m| m.0.get("anthropic/alwaysLoad"))
+            .and_then(serde_json::Value::as_bool);
+        assert_eq!(
+            always == Some(true),
+            tool.name == "books.start",
+            "{}",
+            tool.name
+        );
+    }
+}
+
 /// An upload's limit, 25 MiB exactly (plan 4.7); nothing comes inline
 /// (D-46).
 #[test]
@@ -42,7 +61,7 @@ fn annotations_complete() {
     const D: Hints = (Some(false), Some(true), None);
     const WI: Hints = (Some(false), Some(false), Some(true));
     const DI: Hints = (Some(false), Some(true), Some(true));
-    let table: [(&str, Hints); 133] = [
+    let table: [(&str, Hints); 140] = [
         ("books.handbook", R),
         ("books.start", R),
         ("books.set_setting", DI),
@@ -178,7 +197,15 @@ fn annotations_complete() {
         ("books.list_drafts", R),
         ("books.set_draft_state", W),
         ("books.discard_draft", D),
+        ("books.journal_history", R),
         ("books.preview_entry", R),
+        // P8: audits and attestations.
+        ("books.audit", W),
+        ("books.workpaper", R),
+        ("books.attest_receipt", W),
+        ("books.review_entry", W),
+        ("books.attest_period", W),
+        ("books.attestations", R),
     ];
     let tools = BooksServer::tool_router().list_all();
     assert_eq!(tools.len(), table.len());
@@ -701,23 +728,10 @@ fn tool_text_lint() {
     }
 }
 
-/// Tool descriptions are at most 700 characters (plan I-12). The
-/// ones over it today are listed, each to be shortened in P5 when its
-/// text moves into the handbook; no new one may join them, and one
-/// that shrinks under the cap must leave the list.
+/// Tool descriptions are at most 700 characters (plan I-12); the long
+/// text lives in the handbook (P5 moved the last eight there).
 #[test]
 fn tool_descriptions_fit_700_characters() {
-    // Shorten in P5.
-    const OVER: &[&str] = &[
-        "books.export",
-        "books.export_cpa_package",
-        "books.import_bank_csv",
-        "books.reconcile",
-        "books.set_entry_party",
-        "books.set_w9",
-        "books.show",
-        "books.vendor_1099",
-    ];
     let mut over: Vec<String> = BooksServer::tool_router()
         .list_all()
         .iter()
@@ -725,7 +739,10 @@ fn tool_descriptions_fit_700_characters() {
         .map(|t| t.name.to_string())
         .collect();
     over.sort();
-    assert_eq!(over, OVER, "tool descriptions over 700 characters");
+    assert!(
+        over.is_empty(),
+        "tool descriptions over 700 characters: {over:?}"
+    );
 }
 
 /// The tools docs/mcp-interface.md documents: a line (or a bullet)
@@ -1528,3 +1545,100 @@ fn a_tool_list_is_cached_only_for_its_caller() {
         }
     });
 }
+
+/// Plan 4.6 (P5 step 1): the envelope is put on every result in one
+/// place; a tool that can change the books answers with the journal's
+/// `head` and at least one next step, whatever it said itself, and the
+/// text block says the same as the structured content.
+#[test]
+fn every_mutating_result_has_head_and_next_steps() {
+    use rmcp::model::{CallToolResponse, CallToolResult, ContentBlock};
+    let dir = unit_dir("envelope");
+    let server = served(store(&dir));
+    let (seq, hash) = server.lock().unwrap().head();
+    let mutating = next_steps::mutating_tools();
+    assert!(mutating.contains("books.post_entry") && !mutating.contains("books.trial_balance"));
+    let mut read_only = 0;
+    for tool in BooksServer::tool_router().list_all() {
+        let name = tool.name.to_string();
+        let answer = CallToolResponse::Complete(CallToolResult::structured(
+            serde_json::json!({"status": "ok"}),
+        ));
+        let CallToolResponse::Complete(r) =
+            next_steps::apply(&server, &name, None, Ok(answer)).expect("an answer stays an answer")
+        else {
+            panic!("{name}: not a complete answer");
+        };
+        let body = r.structured_content.expect("structured");
+        assert!(
+            body.get("guards").is_none() && body.get("warnings").is_none(),
+            "{name}: a success without them says none"
+        );
+        let ContentBlock::Text(t) = &r.content[0] else {
+            panic!("{name}: no text block");
+        };
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&t.text).unwrap(),
+            body,
+            "{name}: the text says what the structure says"
+        );
+        if mutating.contains(&name) {
+            assert_eq!(body["head"]["seq"], seq, "{name}");
+            assert_eq!(body["head"]["hash"], hash.as_str(), "{name}");
+            let steps = body["next_steps"].as_array().expect("next_steps");
+            assert!(!steps.is_empty(), "{name}: no next step");
+            for s in steps {
+                assert!(s["why"].is_string() && s["required"].is_boolean(), "{name}");
+            }
+        } else {
+            read_only += 1;
+            assert!(body.get("head").is_none(), "{name}: a read has no head");
+        }
+    }
+    assert!(read_only > 20);
+}
+
+/// A tool's own `next_steps`, `warnings` and `head` are kept (the
+/// envelope fills only what the result lacks), and a refusal that is a
+/// guard carries it.
+#[test]
+fn the_envelope_keeps_what_a_tool_said_and_carries_a_refusal_guard() {
+    use rmcp::model::{CallToolResponse, CallToolResult};
+    let dir = unit_dir("envelope-keeps");
+    let server = served(store(&dir));
+    let own = serde_json::json!({
+        "next_steps": [{"tool": "books.digest", "why": "mine", "required": false}],
+        "warnings": ["careful"],
+        "head": {"seq": 0, "hash": "x"},
+    });
+    let CallToolResponse::Complete(r) = next_steps::apply(
+        &server,
+        "books.post_entry",
+        None,
+        Ok(CallToolResponse::Complete(CallToolResult::structured(
+            own.clone(),
+        ))),
+    )
+    .unwrap() else {
+        panic!()
+    };
+    let body = r.structured_content.unwrap();
+    assert_eq!(body["next_steps"], own["next_steps"]);
+    assert_eq!(body["warnings"], own["warnings"]);
+    assert_eq!(body["head"], own["head"]);
+    let refused = CallToolResponse::Complete(CallToolResult::error(vec![
+        rmcp::model::ContentBlock::text(
+            serde_json::json!({"code": "approval_required", "message": "needs approval", "remedy_tool": "books.approve_entry"})
+                .to_string(),
+        ),
+    ]));
+    let CallToolResponse::Complete(r) =
+        next_steps::apply(&server, "books.post_entry", None, Ok(refused)).unwrap()
+    else {
+        panic!()
+    };
+    assert_eq!(r.is_error, Some(true));
+    let g = &r.structured_content.unwrap()["guards"][0];
+    assert_eq!(g["code"], "approval_required");
+    assert_eq!(g["remedy_tool"], "books.approve_entry");
+}

crates/ledger-mcp/src/tools/audit.rs

@@ -0,0 +1,780 @@
+//! The audit group (plan P8; rules.md B-45): an audit run over the books,
+//! its workpaper, and the claims that someone checked.
+//!
+//! ```text
+//! GOAL: the whole re-audit through the tools: one programme of checks
+//!       that gives the same findings and the same workpaper for the same
+//!       books, and attestations that rest on a head that has not moved.
+//! SOURCE: IRS Pub. 583 (records); Rev. Proc. 98-25 §5.01 (the audit
+//!         trail); docs/spec/rules.md B-45; DECISION D-9 (the bar), D-53
+//!         (an audit is a run, not a job), IZ-1k (the head).
+//! INVARIANTS:
+//!   1. `books.audit` previews (what it will check; nothing changes),
+//!      then with the preview's digest runs the checks, files the
+//!      workpaper (JSON and PDF) as documents and journals `audit.run`.
+//!   2. The same books (the figure head), day, scope and programme give
+//!      the run that exists: nothing is filed or journaled twice.
+//!   3. An attestation is a claim by the caller named by its token; the
+//!      method it gives is self-reported and the books say so.
+//!   4. `counted` is read against `policy.attestation_bar` as it stands
+//!      when asked, never stored.
+//!   5. A period is attested only on an audit at the current head.
+//!   6. Nothing here moves a figure.
+//! ```
+
+use super::*;
+use ledger_core::audit::{self, AttestationBar, AuditInput, Effort, Finding, Method, Scope};
+use ledger_store::audit::{self as saudit, Attested, AuditRun, BackupStanding, Claim};
+use sha2::{Digest, Sha256};
+
+fn sha_hex(bytes: &[u8]) -> String {
+    Sha256::digest(bytes)
+        .iter()
+        .map(|b| format!("{b:02x}"))
+        .collect()
+}
+
+fn err(e: impl std::fmt::Display) -> String {
+    e.to_string()
+}
+
+/// The caller's token name, else the default token's.
+fn caller_name() -> String {
+    CALLER
+        .with(|c| c.borrow().as_ref().map(|(_, name)| name.clone()))
+        .unwrap_or_else(|| ledger_store::auth::DEFAULT_NAME.to_string())
+}
+
+fn method_of(m: Option<AttestMethodParam>) -> Result<Method, String> {
+    let m = m.unwrap_or_default();
+    let reasoning_effort = match m.reasoning_effort.as_deref() {
+        None => None,
+        Some(e) => Some(Effort::parse(e).ok_or_else(|| {
+            format!("reasoning_effort {e:?} is not low, medium, high, xhigh or max")
+        })?),
+    };
+    if m.verifier_agents == Some(0) {
+        return Err("verifier_agents is at least 1".into());
+    }
+    Ok(Method {
+        model: m
+            .model
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty()),
+        reasoning_effort,
+        adversarial: m.adversarial,
+        verifier_agents: m.verifier_agents,
+    })
+}
+
+fn method_out(m: &Method) -> AttestMethodParam {
+    AttestMethodParam {
+        model: m.model.clone(),
+        reasoning_effort: m.reasoning_effort.map(|e| e.key().to_string()),
+        adversarial: m.adversarial,
+        verifier_agents: m.verifier_agents,
+    }
+}
+
+fn finding_out(f: &Finding) -> AuditFindingOut {
+    AuditFindingOut {
+        severity: f.severity.key().into(),
+        code: f.code.into(),
+        subject: f.subject.describe(),
+        message: f.message.clone(),
+    }
+}
+
+/// Every check the programme runs.
+fn checks() -> Vec<AuditCheckOut> {
+    audit::CODES
+        .iter()
+        .chain(saudit::CODES)
+        .map(|r| AuditCheckOut {
+            code: r.code.into(),
+            severity: r.severity.key().into(),
+            predicate: r.predicate.into(),
+        })
+        .collect()
+}
+
+fn run_out(store: &Store, run: &AuditRun) -> Result<AuditRunOut, String> {
+    Ok(AuditRunOut {
+        id: run.id,
+        through: run.through.to_string(),
+        through_seq: run.through_seq,
+        scope: run.scope.key().into(),
+        program_version: run.program_version.clone(),
+        tb_hash: run.tb_hash.clone(),
+        findings_sha256: run.findings_sha256.clone(),
+        workpaper_attachment: run.workpaper_attachment,
+        workpaper_pdf: run.workpaper_pdf,
+        at_current_head: store.audit_is_current(run).map_err(err)?,
+    })
+}
+
+fn summary(findings: &[Finding]) -> String {
+    let n = |s: audit::Severity| findings.iter().filter(|f| f.severity == s).count();
+    format!(
+        "{} failure(s), {} warning(s), {} note(s)",
+        n(audit::Severity::Failure),
+        n(audit::Severity::Warning),
+        n(audit::Severity::Info)
+    )
+}
+
+/// Why an attestation does not count at this bar, in words.
+fn why_not(bar: &AttestationBar, m: &Method, full: bool, disagrees: bool) -> Option<String> {
+    if bar.counts(m, full, disagrees) {
+        return None;
+    }
+    if disagrees {
+        return Some(
+            "the amount or date read off the receipt differs from the entry's: it is recorded and never counts"
+                .into(),
+        );
+    }
+    let mut why = Vec::new();
+    if !m
+        .reasoning_effort
+        .is_some_and(|e| e >= bar.reasoning_effort)
+    {
+        why.push(format!(
+            "reasoning_effort must be at least {}",
+            bar.reasoning_effort.key()
+        ));
+    }
+    if full {
+        if bar.adversarial && m.adversarial != Some(true) {
+            why.push("the check must be adversarial".into());
+        }
+        if !m.verifier_agents.is_some_and(|n| n >= bar.verifier_agents) {
+            why.push(format!(
+                "at least {} independent verifier agents",
+                bar.verifier_agents
+            ));
+        }
+    }
+    Some(format!(
+        "below policy.attestation_bar ({}): {}",
+        bar.describe(),
+        why.join("; ")
+    ))
+}
+
+/// An attestation as the tools list it.
+fn attestation_out(
+    store: &Store,
+    a: &saudit::Attestation,
+    bar: &AttestationBar,
+) -> Result<AttestationOut, String> {
+    let mut out = AttestationOut {
+        seq: a.seq,
+        kind: a.kind().into(),
+        by: a.by.clone(),
+        at: a.at.clone(),
+        attachment_id: None,
+        entry_id: None,
+        period_id: None,
+        audit_run_id: None,
+        amount_checked: None,
+        date_checked: None,
+        disagrees: false,
+        method: method_out(&a.method),
+        note: a.note.clone(),
+        counted: false,
+    };
+    let (full, disagrees) = match &a.what {
+        Attested::Receipt {
+            attachment_id,
+            entry_id,
+            amount_checked,
+            date_checked,
+            disagrees,
+        } => {
+            out.attachment_id = Some(*attachment_id);
+            out.entry_id = Some(*entry_id);
+            out.amount_checked = Some(amount_checked.to_string());
+            out.date_checked = Some(date_checked.to_string());
+            out.disagrees = *disagrees;
+            (false, *disagrees)
+        }
+        Attested::Entry { entry_id } => {
+            out.entry_id = Some(*entry_id);
+            (false, false)
+        }
+        Attested::Period {
+            period_id,
+            audit_run_id,
+        } => {
+            out.period_id = Some(*period_id);
+            out.audit_run_id = Some(*audit_run_id);
+            let scope = store
+                .audit_run(*audit_run_id)
+                .map_err(err)?
+                .map(|r| r.scope);
+            (scope.is_some_and(Scope::full_bar), false)
+        }
+    };
+    out.counted = bar.counts(&a.method, full, disagrees);
+    Ok(out)
+}
+
+/// What an attestation's tool answers.
+fn attest_out(store: &Store, a: &saudit::Attestation) -> Result<AttestOut, String> {
+    let bar = store.ledger().settings().attestation_bar();
+    let o = attestation_out(store, a, &bar)?;
+    let full = o
+        .audit_run_id
+        .and_then(|id| store.audit_run(id).ok().flatten())
+        .is_some_and(|r| r.scope.full_bar());
+    let why_not_counted = why_not(&bar, &a.method, full, o.disagrees);
+    Ok(AttestOut {
+        attestation: o,
+        bar: bar.describe(),
+        why_not_counted,
+    })
+}
+
+impl BooksServer {
+    /// Whether the CPA package may be made (plan P8 step 4, D-9): on books
+    /// that declared `audits` and a policy of refuse, an audit for the
+    /// handoff (scope cpa_handoff or full) at the current head must have a
+    /// period attested on it at the bar. `Ok(None)` when it may; the
+    /// refusal's words otherwise.
+    pub(crate) fn cpa_audit_standing(&self, store: &Store) -> Result<Option<String>, String> {
+        if !store
+            .journal_format()
+            .has_feature(ledger_store::format::AUDITS)
+        {
+            return Ok(None);
+        }
+        let settings = store.ledger().settings();
+        let bar = settings.attestation_bar();
+        let attestations = store.attestations().map_err(err)?;
+        for run in store.audit_runs().map_err(err)?.iter().rev() {
+            if !run.scope.serves_handoff() || !store.audit_is_current(run).map_err(err)? {
+                continue;
+            }
+            let counted = attestations.iter().any(|a| {
+                matches!(a.what, Attested::Period { audit_run_id, .. } if audit_run_id == run.id)
+                    && bar.counts(&a.method, run.scope.full_bar(), false)
+            });
+            if counted {
+                return Ok(None);
+            }
+        }
+        Ok(Some(format!(
+            "no audit for the handoff (books.audit with scope cpa_handoff or full) stands at the books' current head with a period attested at the bar ({}); run the audit, have it verified (books.attest_receipt, books.review_entry, books.attest_period), or pass without_audit_reason",
+            bar.describe()
+        )))
+    }
+
+    /// The findings the programme gives the books through `through`: the
+    /// statements, then what only the store, the backups and the settings
+    /// can see. Reads only.
+    fn audit_findings(
+        &self,
+        store: &Store,
+        through: NaiveDate,
+    ) -> Result<(Vec<Finding>, String), String> {
+        let ledger = store.ledger();
+        let cfg = self.settings();
+        let ps = package_settings(&cfg);
+        let receipts = store.entries_with_receipts().map_err(err)?;
+        // The statement of cash flows, from the first entry, with the
+        // books' role settings; none when they name no cash accounts.
+        let first = ledger
+            .posted_entries()
+            .filter(|e| e.date() <= through)
+            .map(|e| e.date())
+            .min();
+        let cash = match first {
+            Some(start) if !ps.cash_accounts.is_empty() => Some(
+                ledger_package::cash_flow_for(
+                    ledger,
+                    &ps,
+                    Some(&start.to_string()),
+                    Some(&through.to_string()),
+                    &[],
+                    &[],
+                    &[],
+                    today(),
+                )
+                .map(|s| s.reconciles),
+            ),
+            _ => None,
+        };
+        // Vendors paid in a way that could need a 1099 and undecided; a
+        // year whose threshold isn't known is the stale-rule item's.
+        use chrono::Datelike;
+        let undecided: Vec<(String, rust_decimal::Decimal)> =
+            ledger_package::vendor_1099_report(ledger, &ps, through.year(), None, Some(through))
+                .map(|r| {
+                    r.vendors
+                        .iter()
+                        .filter(|v| v.decision_needed)
+                        .map(|v| (v.name.clone(), v.paid))
+                        .collect()
+                })
+                .unwrap_or_default();
+        let problems = settings_problems(ledger, &cfg);
+        let mut findings = audit::statements(
+            ledger,
+            &AuditInput {
+                settings: ledger.settings(),
+                receipts: &receipts,
+                cash_flow: cash.as_ref(),
+                settings_problems: &problems,
+                undecided_1099: &undecided,
+            },
+            through,
+        );
+        findings.extend(store.integrity_findings());
+        let standing = self.backups.standing(store);
+        findings.extend(saudit::backup_findings(
+            &standing
+                .targets
+                .iter()
+                .map(|t| BackupStanding {
+                    target: format!("{} {}", t.target, t.at),
+                    stale: t.stale,
+                    last_error: t.last_error.clone(),
+                    drill_error: t.drill_error.clone(),
+                })
+                .collect::<Vec<_>>(),
+        ));
+        audit::sort(&mut findings);
+        let tb = ledger_core::reports::trial_balance_as_of(ledger, through);
+        let tb_hash = sha_hex(&serde_json::to_vec(&tb).map_err(err)?);
+        Ok((findings, tb_hash))
+    }
+}
+
+#[tool_router(router = audit_router, vis = "pub(super)")]
+impl BooksServer {
+    /// ```text
+    /// GOAL: the whole programme of checks over the books through a day,
+    ///       its workpaper filed, the run journaled.
+    /// SOURCE: plan/served.md P8; B-45; D-9, D-53.
+    /// INVARIANTS:
+    ///   1. Without `confirmed`, a preview that lists the checks and
+    ///      changes nothing; with it, the preview's digest is required.
+    ///   2. Idempotent on the figure head, day, scope and programme.
+    ///   3. The workpaper is JSON and PDF, filed as documents (category
+    ///      workpaper), the PDF with deterministic bytes.
+    /// SCENARIOS:
+    ///   1. IF the books haven't declared audits: the run is refused with
+    ///      format_upgrade_pending; the preview still lists the checks.
+    ///   2. IF the same audit is asked at the same head: SHOULD return
+    ///      the first run, status already_run.
+    /// ```
+    #[tool(
+        name = "books.audit",
+        title = "Audit the books",
+        description = "Audit the books through a day (through, default today) at a scope: month, annual, cpa_handoff (the year, for the CPA package) or full. It checks the statements, the A/R and A/P control accounts, closes, schedules, assets, each posted entry against the receipt policy, open drafts, tax categories, 1099 decisions and settings, then the journal, stored files, access log and backups. Without confirmed, a preview of the checks, changing nothing. With confirmed and the preview, it files the workpaper (books.workpaper) and journals the run; the same books, day and scope give the run that exists. Attestations rest on a run only while no entry, document, close, settings or role change follows it",
+        annotations(
+            read_only_hint = false,
+            destructive_hint = false,
+            open_world_hint = false
+        )
+    )]
+    async fn audit(&self, params: Parameters<AuditParams>) -> Result<Json<AuditOut>, String> {
+        let p = params.0;
+        let scope = Scope::parse(&p.scope).ok_or_else(|| {
+            format!(
+                "bad scope {:?}: expected month, annual, cpa_handoff or full",
+                p.scope
+            )
+        })?;
+        let through = self.as_of(p.through.as_deref())?;
+        let confirmed = p.confirmed.unwrap_or(false);
+        let mut store = self.lock()?;
+        let head = store.figure_head().map_err(err)?;
+        let digest = self.preview_of(&store, "books.audit", confirmed, p.preview.as_deref())?;
+        if let Some(run) = store.find_audit_run(through, head, scope).map_err(err)? {
+            let findings = self.stored_findings(&store, &run)?;
+            return Ok(Json(AuditOut {
+                status: "already_run".into(),
+                preview: Some(digest),
+                head,
+                checks: checks(),
+                summary: Some(summary_of(&findings)),
+                run: Some(run_out(&store, &run)?),
+                findings,
+            }));
+        }
+        if !confirmed {
+            return Ok(Json(AuditOut {
+                status: "preview".into(),
+                preview: Some(digest),
+                head,
+                checks: checks(),
+                run: None,
+                findings: Vec::new(),
+                summary: None,
+            }));
+        }
+        store
+            .ensure_feature(ledger_store::format::AUDITS)
+            .map_err(err)?;
+        let (findings, tb_hash) = self.audit_findings(&store, through)?;
+        let findings_sha256 = sha_hex(&serde_json::to_vec(&findings).map_err(err)?);
+        let summary = summary(&findings);
+        let company = self.settings().company.name.clone();
+        let rows: Vec<AuditFindingOut> = findings.iter().map(finding_out).collect();
+        let check_rows = checks();
+        let paper = serde_json::json!({
+            "company": company,
+            "title": "Audit workpaper",
+            "scope": scope.key(),
+            "through": through.to_string(),
+            "through_seq": head,
+            "program_version": saudit::PROGRAM_VERSION,
+            "tb_hash": tb_hash,
+            "findings_sha256": findings_sha256,
+            "summary": summary,
+            "findings": rows,
+            "checks": check_rows,
+        });
+        let json_bytes = serde_json::to_vec_pretty(&paper).map_err(err)?;
+        let pdf_bytes = ledger_import::workpaper_pdf(&ledger_import::Workpaper {
+            company,
+            title: "Audit workpaper".into(),
+            scope: scope.key().into(),
+            through: through.to_string(),
+            through_seq: head,
+            program_version: saudit::PROGRAM_VERSION.into(),
+            tb_hash: tb_hash.clone(),
+            findings_sha256: findings_sha256.clone(),
+            summary: summary.clone(),
+            findings: rows
+                .iter()
+                .map(|f| ledger_import::WorkpaperFinding {
+                    severity: f.severity.clone(),
+                    code: f.code.clone(),
+                    subject: f.subject.clone(),
+                    message: f.message.clone(),
+                })
+                .collect(),
+            checks: check_rows
+                .iter()
+                .map(|c| ledger_import::WorkpaperCheck {
+                    code: c.code.clone(),
+                    severity: c.severity.clone(),
+                    predicate: c.predicate.clone(),
+                })
+                .collect(),
+        })
+        .map_err(err)?;
+        let stem = format!("workpaper-{}-{through}-{head}", scope.key());
+        let describe = format!(
+            "Audit workpaper, scope {}, through {through}, books at figure head {head} ({}).",
+            scope.key(),
+            saudit::PROGRAM_VERSION
+        );
+        let (wp_json, _, _) = store
+            .file_document(
+                "workpaper",
+                &format!("{stem}.json"),
+                "application/json",
+                &json_bytes,
+                Some(&describe),
+            )
+            .map_err(err)?;
+        let (wp_pdf, _, _) = store
+            .file_document(
+                "workpaper",
+                &format!("{stem}.pdf"),
+                "application/pdf",
+                &pdf_bytes,
+                Some(&describe),
+            )
+            .map_err(err)?;
+        // A month's or a year's workpaper belongs with its period.
+        if matches!(scope, Scope::Month | Scope::Annual)
+            && let Some(period) = store
+                .ledger()
+                .list_periods()
+                .into_iter()
+                .filter(|q| q.start <= through && through <= q.end)
+                .min_by_key(|q| (q.end - q.start).num_days())
+                .map(|q| q.id)
+        {
+            for a in [wp_json, wp_pdf] {
+                let _ = store.link_attachment(a, ledger_store::Subject::Period(period));
+            }
+        }
+        let run = store
+            .record_audit_run(saudit::NewAuditRun {
+                through,
+                through_seq: head,
+                scope,
+                tb_hash,
+                findings_sha256,
+                workpaper_attachment: Some(wp_json),
+                workpaper_pdf: Some(wp_pdf),
+            })
+            .map_err(err)?;
+        Ok(Json(AuditOut {
+            status: "audited".into(),
+            preview: Some(digest),
+            head,
+            checks: check_rows,
+            summary: Some(summary),
+            run: Some(run_out(&store, &run)?),
+            findings: rows,
+        }))
+    }
+
+    /// ```text
+    /// GOAL: an audit run's workpaper, whole.
+    /// SOURCE: plan/served.md P8 step 3; B-45.
+    /// INVARIANTS:
+    ///   1. Read-only; the JSON is the one filed, the PDF is handed over.
+    /// ```
+    #[tool(
+        name = "books.workpaper",
+        title = "An audit's workpaper",
+        description = "The workpaper of an audit run (books.audit's run.id): what was checked, through which day and state of the books, and every finding, as the JSON that was filed, with the PDF handed over (run its download command to save it in a folder). Changes nothing.",
+        annotations(read_only_hint = true, open_world_hint = false)
+    )]
+    async fn workpaper(
+        &self,
+        params: Parameters<WorkpaperParams>,
+    ) -> Result<Json<WorkpaperOut>, String> {
+        let store = self.lock()?;
+        let run = store.audit_run(params.0.id).map_err(err)?.ok_or_else(|| {
+            format!(
+                "no audit run {}: books.attestations lists the ones attested",
+                params.0.id
+            )
+        })?;
+        let json_id = run
+            .workpaper_attachment
+            .ok_or("this audit run filed no workpaper")?;
+        let bytes = store.attachment_bytes(json_id).map_err(err)?;
+        let workpaper: serde_json::Value = serde_json::from_slice(&bytes).map_err(err)?;
+        let pdf = match run.workpaper_pdf {
+            Some(id) => {
+                let bytes = store.attachment_bytes(id).map_err(err)?;
+                Some(self.hand_over(
+                    &book_name(&store),
+                    &format!(
+                        "workpaper-{}-{}-{}.pdf",
+                        run.scope.key(),
+                        run.through,
+                        run.through_seq
+                    ),
+                    "application/pdf",
+                    bytes,
+                )?)
+            }
+            None => None,
+        };
+        Ok(Json(WorkpaperOut {
+            run: run_out(&store, &run)?,
+            workpaper,
+            pdf,
+        }))
+    }
+
+    /// ```text
+    /// GOAL: a checker's claim that a receipt supports an entry.
+    /// SOURCE: plan/served.md P8 step 4; B-45; D-9.
+    /// INVARIANTS:
+    ///   1. The reading is compared with the entry's amount and date; a
+    ///      difference is recorded, marked, and never counts.
+    ///   2. The method is the client's claim, self-reported.
+    /// ```
+    #[tool(
+        name = "books.attest_receipt",
+        title = "Attest a receipt",
+        description = "Record that you read a receipt and it supports a posted entry: amount and date as you read them off it (get_receipt text, then page_image), and how you checked (method: model, reasoning_effort, adversarial, verifier_agents; your own claim, which the books record but cannot verify). The books compare the reading with the entry's amounts and date; a difference is recorded as disagrees and never counts. Whether it counts is weighed against policy.attestation_bar when asked.",
+        annotations(
+            read_only_hint = false,
+            destructive_hint = false,
+            open_world_hint = false
+        )
+    )]
+    async fn attest_receipt(
+        &self,
+        params: Parameters<AttestReceiptParams>,
+    ) -> Result<Json<AttestOut>, String> {
+        let p = params.0;
+        let amount = parse_amount(&p.amount)?;
+        let date = NaiveDate::parse_from_str(p.date.trim(), "%Y-%m-%d")
+            .map_err(|_| format!("{:?} isn't a date: give YYYY-MM-DD", p.date))?;
+        let claim = Claim {
+            by: caller_name(),
+            method: method_of(p.method)?,
+            note: p.note,
+        };
+        let mut store = self.lock()?;
+        let a = store
+            .attest_receipt(p.attachment_id, p.entry_id, amount, date, claim)
+            .map_err(err)?;
+        Ok(Json(attest_out(&store, &a)?))
+    }
+
+    /// ```text
+    /// GOAL: a checker's claim that it reviewed an entry whole.
+    /// SOURCE: plan/served.md P8 step 4; B-45.
+    /// ```
+    #[tool(
+        name = "books.review_entry",
+        title = "Review an entry",
+        description = "Record that you reviewed a posted entry whole: its lines, accounts, party and evidence, and how you checked (method, as for books.attest_receipt; your own claim). Changes no figure.",
+        annotations(
+            read_only_hint = false,
+            destructive_hint = false,
+            open_world_hint = false
+        )
+    )]
+    async fn review_entry(
+        &self,
+        params: Parameters<ReviewEntryParams>,
+    ) -> Result<Json<AttestOut>, String> {
+        let p = params.0;
+        let claim = Claim {
+            by: caller_name(),
+            method: method_of(p.method)?,
+            note: p.note,
+        };
+        let mut store = self.lock()?;
+        let a = store.review_entry(p.entry_id, claim).map_err(err)?;
+        Ok(Json(attest_out(&store, &a)?))
+    }
+
+    /// ```text
+    /// GOAL: a checker's claim that a period is right, resting on an
+    ///       audit run at the books' current head.
+    /// SOURCE: plan/served.md P8 step 4; B-45; D-9; IZ-1k.
+    /// INVARIANTS:
+    ///   1. Refused unless an audit through the period's end stands at
+    ///      the current head.
+    /// ```
+    #[tool(
+        name = "books.attest_period",
+        title = "Attest a period",
+        description = "Record that you checked a period (its id or name from books.list_periods), resting on an audit (books.audit) through its end that still stands: refused when an entry, document, close, settings or role change has been made since the audit, or no audit covers it. Say how you checked (method, as for books.attest_receipt; your own claim). A year-level audit (annual, cpa_handoff, full) is held to the whole policy.attestation_bar: reasoning effort, adversarial, and the number of independent verifier agents.",
+        annotations(
+            read_only_hint = false,
+            destructive_hint = false,
+            open_world_hint = false
+        )
+    )]
+    async fn attest_period(
+        &self,
+        params: Parameters<AttestPeriodParams>,
+    ) -> Result<Json<AttestOut>, String> {
+        let p = params.0;
+        let claim = Claim {
+            by: caller_name(),
+            method: method_of(p.method)?,
+            note: p.note,
+        };
+        let mut store = self.lock()?;
+        let named = p.period.trim();
+        let period = store
+            .ledger()
+            .list_periods()
+            .into_iter()
+            .find(|q| q.name == named || q.id.to_string() == named)
+            .map(|q| q.id)
+            .ok_or_else(|| format!("no period {named:?}: books.list_periods lists them"))?;
+        let (a, _) = store.attest_period(period, claim).map_err(|e| match e {
+            ledger_store::StoreError::AuditRefused(why) => serde_json::json!({
+                "code": "audit_required",
+                "message": why,
+                "remedy_tool": "books.audit",
+            })
+            .to_string(),
+            other => other.to_string(),
+        })?;
+        Ok(Json(attest_out(&store, &a)?))
+    }
+
+    /// ```text
+    /// GOAL: every claim that someone checked, and whether it counts.
+    /// SOURCE: plan/served.md P8 step 4; B-45; D-9.
+    /// INVARIANTS:
+    ///   1. `counted` is read against the bar as it stands now.
+    /// ```
+    #[tool(
+        name = "books.attestations",
+        title = "Attestations",
+        description = "List the attestations (receipts read, entries reviewed, periods attested), oldest first, each with who made it, how they say they checked, and counted: whether it meets policy.attestation_bar as the bar stands now (a change to the bar changes what counts, earlier claims too). through limits to entries dated, and periods ending, on or before a day; kind to receipt, entry or period. Changes nothing.",
+        annotations(read_only_hint = true, open_world_hint = false)
+    )]
+    async fn attestations(
+        &self,
+        params: Parameters<AttestationsParams>,
+    ) -> Result<Json<AttestationsOut>, String> {
+        let p = params.0;
+        let through = p
+            .through
+            .as_deref()
+            .map(|t| self.as_of(Some(t)))
+            .transpose()?;
+        if let Some(k) = p.kind.as_deref()
+            && !["receipt", "entry", "period"].contains(&k)
+        {
+            return Err("kind is receipt, entry or period".into());
+        }
+        let store = self.lock()?;
+        let ledger = store.ledger();
+        let bar = ledger.settings().attestation_bar();
+        let mut out = Vec::new();
+        for a in store.attestations().map_err(err)? {
+            if p.kind.as_deref().is_some_and(|k| k != a.kind()) {
+                continue;
+            }
+            if let Some(t) = through {
+                let on = match a.what {
+                    Attested::Receipt { entry_id, .. } | Attested::Entry { entry_id } => {
+                        ledger.get_entry(entry_id).map(|e| e.date())
+                    }
+                    Attested::Period { period_id, .. } => {
+                        ledger.get_period(period_id).map(|q| q.end)
+                    }
+                };
+                if on.is_none_or(|d| d > t) {
+                    continue;
+                }
+            }
+            out.push(attestation_out(&store, &a, &bar)?);
+        }
+        Ok(Json(AttestationsOut {
+            bar: bar.describe(),
+            counted: out.iter().filter(|a| a.counted).count(),
+            attestations: out,
+        }))
+    }
+}
+
+impl BooksServer {
+    /// The findings of a run, as its filed workpaper holds them.
+    fn stored_findings(
+        &self,
+        store: &Store,
+        run: &AuditRun,
+    ) -> Result<Vec<AuditFindingOut>, String> {
+        let Some(id) = run.workpaper_attachment else {
+            return Ok(Vec::new());
+        };
+        let bytes = store.attachment_bytes(id).map_err(err)?;
+        let paper: serde_json::Value = serde_json::from_slice(&bytes).map_err(err)?;
+        serde_json::from_value(paper["findings"].clone()).map_err(err)
+    }
+}
+
+fn summary_of(findings: &[AuditFindingOut]) -> String {
+    let n = |s: &str| findings.iter().filter(|f| f.severity == s).count();
+    format!(
+        "{} failure(s), {} warning(s), {} note(s)",
+        n("failure"),
+        n("warning"),
+        n("info")
+    )
+}

crates/ledger-mcp/src/tools/documents.rs

@@ -455,17 +455,7 @@ impl BooksServer {
     ) -> Result<Json<InvoiceOut>, String> {
         let p = params.0;
         let mut store = self.lock()?;
-        let customer = match (&p.customer, p.party_id) {
-            (Some(c), None) => c.trim().to_string(),
-            (None, Some(id)) => id.to_string(),
-            (Some(c), Some(id)) if c.trim() == id.to_string() => c.trim().to_string(),
-            (Some(_), Some(_)) => {
-                return Err("give the customer once: customer or party_id, not both".into());
-            }
-            (None, None) => {
-                return Err("give customer: a customer id, a party id or a name".into());
-            }
-        };
+        let customer = p.customer.trim().to_string();
         let customer_id = resolve_customer(&store, &customer)?;
         let date = parse_date(&p.date)?;
         let lines = document_lines(&store, p.lines)?;
@@ -606,17 +596,7 @@ impl BooksServer {
     ) -> Result<Json<BillOut>, String> {
         let p = params.0;
         let mut store = self.lock()?;
-        let vendor = match (&p.vendor, p.party_id) {
-            (Some(v), None) => v.trim().to_string(),
-            (None, Some(id)) => id.to_string(),
-            (Some(v), Some(id)) if v.trim() == id.to_string() => v.trim().to_string(),
-            (Some(_), Some(_)) => {
-                return Err("give the vendor once: vendor or party_id, not both".into());
-            }
-            (None, None) => {
-                return Err("give vendor: a vendor id, a party id or a name".into());
-            }
-        };
+        let vendor = p.vendor.trim().to_string();
         let vendor_id = resolve_vendor_arg(&store, &vendor)?;
         let date = parse_date(&p.date)?;
         let received_on = p.received_on.as_deref().map(parse_date).transpose()?;

crates/ledger-mcp/src/tools/entries.rs

@@ -706,7 +706,7 @@ impl BooksServer {
     #[tool(
         name = "books.import_bank_csv",
         title = "Import a bank CSV as drafts",
-        description = "Import a QuickBooks-style bank/credit-card CSV: 3 columns Date,Description,Amount (payments negative), or 4 columns Date,Description, money out, money in (Intuit heads them Credit,Debit). Slash dates must settle month-first or day-first from the file itself or from date_order (\"month_first\" for mm/dd, \"day_first\" for dd/mm); ask the human when the tool says the dates read either way. Creates one DRAFT entry per transaction, all or none: bank account on one side, categorized offset on the other (the longest matching rule pattern, else default_offset_code). Give the CSV as upload_id: upload it with books.begin_upload purpose import and `wanderbooks upload` (a file never passes through you). Review with books.digest, then post. File the export too (books.file_document category import_source) and pass source_attachment_id: it is linked to the bank account, so the import traces to its source (never to the drafts: a bank export is not a receipt).",
+        description = "Import a bank or card CSV (Date, Description, Amount; or Date, Description, money out, money in) as one DRAFT entry per transaction, all or none: the bank account on one side, a categorized offset on the other. Give the CSV as upload_id (books.begin_upload purpose import; a file never passes through you). Ambiguous slash dates need date_order. Review with books.digest, then post. Also file the export (books.file_document category import_source) and pass source_attachment_id. Details in books.handbook section files-in-out.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,

crates/ledger-mcp/src/tools/journal.rs

@@ -0,0 +1,137 @@
+//! `books.journal_history`: the journal in words (plan P5 step 4).
+//!
+//! ```text
+//! GOAL: an agent can trace what the books did, line by line, without the
+//!       journal file: the only way to "read the journal".
+//! SOURCE: plan/served.md 4.3 (tracing figures), P5 step 4; the describer
+//!         is ledger_store::describe.
+//! INVARIANTS:
+//!   1. Read-only; needs books:read; at most 200 lines a call, 50 by
+//!      default, in journal order from the line after `after_seq`.
+//!   2. A sentence quotes no setting value and no full TIN
+//!      (ledger_store::describe INVARIANT 2).
+//!   3. `subject` is `kind:id`; a bad one is refused with the shapes.
+//! ```
+
+use super::*;
+use ledger_store::describe::{HistoryFilter, parse_subject};
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// The most lines one call returns.
+const HISTORY_MAX: usize = 200;
+/// The lines a call returns when it names no limit.
+const HISTORY_DEFAULT: usize = 50;
+
+/// Parameters for `books.journal_history`.
+#[derive(Debug, Default, Deserialize, JsonSchema)]
+pub struct JournalHistoryParams {
+    /// Only lines after this journal seq (default: from the first).
+    #[serde(default)]
+    pub after_seq: Option<u64>,
+    /// Only these line types: an exact type (`entry.posted`) or a group
+    /// ending in a dot (`entry.`).
+    #[serde(default)]
+    pub types: Vec<String>,
+    /// Only lines about one subject: `entry:12`, `invoice:3`, `bill:3`,
+    /// `account:10`, `party:5` or `asset:2`.
+    #[serde(default)]
+    pub subject: Option<String>,
+    /// At most this many lines (default 50, most 200).
+    #[serde(default)]
+    pub limit: Option<u32>,
+}
+
+/// One journal line, in words.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct JournalLineOut {
+    /// Its seq.
+    pub seq: u64,
+    /// When it was written (UTC).
+    pub ts: String,
+    /// Its type, e.g. `entry.posted`.
+    #[serde(rename = "type")]
+    pub line_type: String,
+    /// What it did, in a sentence.
+    pub summary: String,
+    /// What it is about, as `kind:id`, if it is about one thing.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub subject: Option<String>,
+    /// The entry it belongs to, if it is about one.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub entry_id: Option<u64>,
+}
+
+/// A torn journal tail set aside when the books opened.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct TailRepairOut {
+    /// When (UTC).
+    pub at: String,
+    /// How many bytes were set aside.
+    pub bytes: u64,
+}
+
+/// Result of `books.journal_history`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct JournalHistoryOut {
+    /// The lines, in journal order.
+    pub lines: Vec<JournalLineOut>,
+    /// Whether more lines match after the last (ask again with its seq as
+    /// after_seq).
+    pub more: bool,
+    /// The journal's last seq.
+    pub head_seq: u64,
+    /// Torn tails set aside on open, oldest first.
+    pub tail_repairs: Vec<TailRepairOut>,
+}
+
+#[tool_router(router = journal_router, vis = "pub(super)")]
+impl BooksServer {
+    #[tool(
+        name = "books.journal_history",
+        title = "Journal history",
+        description = "The journal in words, in order: each line's seq, time, type and a sentence saying what it did, to what, and the entry it belongs to. Filter by after_seq, types (an exact type like entry.posted, or a group like entry.) and subject (entry:12, invoice:3, bill:3, account:10, party:5, asset:2). The way to trace a figure back to what produced it, and the only way to see what the journal holds. Read-only; at most 200 lines a call.",
+        annotations(read_only_hint = true, open_world_hint = false)
+    )]
+    pub(super) async fn journal_history(
+        &self,
+        params: Parameters<JournalHistoryParams>,
+    ) -> Result<Json<JournalHistoryOut>, String> {
+        let p = params.0;
+        let subject = p
+            .subject
+            .as_deref()
+            .map(|s| parse_subject(s).map(|(k, id)| format!("{k}:{id}")))
+            .transpose()?;
+        let limit = (p.limit.unwrap_or(HISTORY_DEFAULT as u32) as usize).clamp(1, HISTORY_MAX);
+        let filter = HistoryFilter {
+            after_seq: p.after_seq.unwrap_or(0),
+            types: p.types,
+            subject,
+            limit,
+        };
+        let store = self.lock()?;
+        let h = store.journal_history(&filter).map_err(|e| e.to_string())?;
+        Ok(Json(JournalHistoryOut {
+            lines: h
+                .lines
+                .into_iter()
+                .map(|d| JournalLineOut {
+                    seq: d.seq,
+                    ts: d.ts,
+                    line_type: d.line_type,
+                    summary: d.summary,
+                    subject: d.subjects.first().cloned(),
+                    entry_id: d.entry_id,
+                })
+                .collect(),
+            more: h.more,
+            head_seq: h.head_seq,
+            tail_repairs: h
+                .tail_repairs
+                .into_iter()
+                .map(|(at, bytes)| TailRepairOut { at, bytes })
+                .collect(),
+        }))
+    }
+}

crates/ledger-mcp/src/tools/kept.rs

@@ -94,11 +94,35 @@ pub struct StartParams {
     /// (shapes next_steps). Default: daily.
     #[serde(default)]
     pub focus: Option<String>,
+    /// What the agent says about itself: its model, reasoning effort and
+    /// harness. Self-reported and never checked; written to the access
+    /// log beside the call and used for nothing else.
+    #[serde(default)]
+    pub agent: Option<AgentIn>,
+}
+
+/// What an agent says about itself (`books.start`'s `agent`).
+#[derive(Debug, Default, Deserialize, JsonSchema)]
+pub struct AgentIn {
+    /// The model's name ("claude-opus-4").
+    #[serde(default)]
+    pub model: Option<String>,
+    /// The reasoning effort it runs at ("high").
+    #[serde(default)]
+    pub reasoning_effort: Option<String>,
+    /// The program driving it ("claude-code").
+    #[serde(default)]
+    pub harness: Option<String>,
 }
 
 /// The books, in brief.
 #[derive(Debug, Serialize, JsonSchema)]
 pub struct StartBookOut {
+    /// The books' id on this server.
+    pub id: String,
+    /// Where these books answer on this server (`/b/ID/mcp`): never a
+    /// path on any disk.
+    pub url: String,
     /// The company's name.
     pub name: String,
     /// Its time zone (IANA), or null: the computer's.
@@ -222,12 +246,115 @@ pub struct FormatUpgradeOut {
 #[derive(Debug, Serialize, JsonSchema)]
 pub struct NextStepOut {
     /// The tool to call.
-    pub tool: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tool: Option<String>,
+    /// Or the prompt to run.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt: Option<String>,
     /// Its arguments, if any.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub args: Option<Value>,
     /// Why.
     pub why: String,
+    /// Whether the work is not done without it.
+    pub required: bool,
+}
+
+/// Who is asking, as the books know them (the token's own facts).
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct YouOut {
+    /// The token's name.
+    pub principal: String,
+    /// Always `agent` here.
+    pub kind: String,
+    /// What the token may do: books:read, books:write, books:post,
+    /// books:admin.
+    pub scopes: Vec<String>,
+    /// The client program, as it named itself.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_id: Option<String>,
+}
+
+/// A draft waiting on its evidence.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StartDraftOut {
+    /// The draft entry.
+    pub entry_id: u64,
+    /// Its date.
+    pub date: String,
+    /// Its total debits.
+    pub amount: String,
+    /// What it waits for.
+    pub note: String,
+}
+
+/// The open drafts.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StartDraftsOut {
+    /// Drafts being built.
+    pub building: u32,
+    /// Drafts finished and waiting for their documents (books.list_drafts
+    /// has every one).
+    pub awaiting_evidence: Vec<StartDraftOut>,
+}
+
+/// Where reconciliation stands.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StartReconciliationOut {
+    /// The accounts reconciled to statements (codes).
+    pub tracked: Vec<String>,
+    /// Of those, never reconciled.
+    pub never_reconciled: Vec<String>,
+    /// Of those, reconciled but behind.
+    pub behind: Vec<String>,
+}
+
+/// Where the books' backups stand.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StartBackupOut {
+    /// When the latest backup took (UTC), if any did.
+    pub last_at: Option<String>,
+    /// The journal seq the latest holds.
+    pub through_seq: Option<u64>,
+    /// Whether one is stale or failing, or none is set up.
+    pub stale: bool,
+}
+
+/// A prompt, in brief.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct StartPromptOut {
+    /// Its name.
+    pub name: String,
+    /// The arguments it takes.
+    pub args: Vec<String>,
+}
+
+/// One thing the books need.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AttentionBriefOut {
+    /// What it is, by kind and subject.
+    pub id: String,
+    /// problem, todo or info.
+    pub severity: String,
+    /// Its kind (`missing_receipt`, `reconcile`, ...).
+    pub kind: String,
+    /// What is wrong, in a line.
+    pub title: String,
+    /// The tool that starts the fix, if there is one.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tool: Option<String>,
+    /// Its arguments, if any.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub args: Option<Value>,
+}
+
+/// What needs attention: the most urgent, and how many of each kind.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct NeedsAttentionOut {
+    /// The most urgent (problems first), at most 12.
+    pub items: Vec<AttentionBriefOut>,
+    /// Every item by kind.
+    pub counts: std::collections::BTreeMap<String, u32>,
 }
 
 /// Result of `books.start`.
@@ -264,6 +391,19 @@ pub struct StartOut {
     /// the owner gives the go-ahead. No tool can: tell the human.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub format_upgrade: Option<FormatUpgradeOut>,
+    /// Who is asking.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub you: Option<YouOut>,
+    /// The drafts open.
+    pub drafts: StartDraftsOut,
+    /// Where reconciliation stands.
+    pub reconciliation: StartReconciliationOut,
+    /// Where the backups stand.
+    pub backup: StartBackupOut,
+    /// The prompts: whole procedures (`prompts/get`).
+    pub prompts: Vec<StartPromptOut>,
+    /// What needs attention, most urgent first.
+    pub needs_attention: NeedsAttentionOut,
     /// What to do next, in order.
     pub next_steps: Vec<NextStepOut>,
     /// How the books are kept from agents: "same_user (advisory)" locally
@@ -392,6 +532,11 @@ pub struct SetConventionParams {
     /// amount_over?}. Other kinds take none.
     #[serde(default)]
     pub structured: Option<Value>,
+    /// Only to correct who decided it, when or on what (the text exactly
+    /// as it stands): why the source is wrong. The correction is journaled
+    /// as such, the convention's revision unchanged.
+    #[serde(default)]
+    pub reason: Option<String>,
     /// Who decided, and when.
     #[serde(flatten)]
     pub source: SourceIn,
@@ -412,9 +557,12 @@ pub struct RetireConventionParams {
 /// Parameters for `books.record_decision`.
 #[derive(Debug, Deserialize, JsonSchema)]
 pub struct RecordDecisionParams {
-    /// What it is about ("Materiality policy").
+    /// What it is about ("Materiality policy"). Left out when `revises` is
+    /// given.
+    #[serde(default)]
     pub subject: String,
-    /// The decision in words (Markdown).
+    /// The decision in words (Markdown). Left out when `revises` is given.
+    #[serde(default)]
     pub decision_md: String,
     /// Who decided (names), at least one.
     pub decided_by: Vec<String>,
@@ -432,6 +580,14 @@ pub struct RecordDecisionParams {
     /// The projects it is about (ids or names), if any.
     #[serde(default)]
     pub projects: Vec<String>,
+    /// To correct only who decided an earlier decision, when and on what
+    /// (decided_by, decided_on, citation: the new source), give its id here
+    /// with `reason`; its words stay. Journaled as a source correction.
+    #[serde(default)]
+    pub revises: Option<u64>,
+    /// With `revises`: why the source was wrong.
+    #[serde(default)]
+    pub reason: Option<String>,
 }
 
 /// A decision.
@@ -487,7 +643,8 @@ pub struct DecisionsOut {
 /// Parameters for `books.raise_item`.
 #[derive(Debug, Deserialize, JsonSchema)]
 pub struct RaiseItemParams {
-    /// What is open, in a line.
+    /// What is open, in a line. Left out when `revises` is given.
+    #[serde(default)]
     pub title: String,
     /// More, if any (Markdown).
     #[serde(default)]
@@ -495,6 +652,14 @@ pub struct RaiseItemParams {
     /// When it is due, YYYY-MM-DD, if it is.
     #[serde(default)]
     pub due: Option<String>,
+    /// To correct only who raised an item, when and on what (the source
+    /// given here), give the item's id with `reason`; the item stays as it
+    /// is. Journaled as a source correction.
+    #[serde(default)]
+    pub revises: Option<u64>,
+    /// With `revises`: why the source was wrong.
+    #[serde(default)]
+    pub reason: Option<String>,
     /// Who raised it, and when.
     #[serde(flatten)]
     pub source: SourceIn,
@@ -693,6 +858,15 @@ fn open_item_out(i: &ledger_core::conventions::OpenItem) -> OpenItemOut {
     }
 }
 
+/// `books.start`'s `_meta`: a client that defers tools (tool search) loads
+/// this one up front, as the connect text says to call it first.
+fn always_load() -> rmcp::model::MetaObject {
+    let mut meta = rmcp::model::MetaObject::new();
+    meta.0
+        .insert("anthropic/alwaysLoad".into(), serde_json::json!(true));
+    meta
+}
+
 impl BooksServer {
     /// The books' `books.start` (INVARIANT 4).
     fn start_out(&self, store: &Store, focus: Option<&str>) -> StartOut {
@@ -759,9 +933,11 @@ impl BooksServer {
         projects.truncate(START_PROJECTS);
         let focus = focus.unwrap_or("daily");
         let step = |tool: &str, args: Option<serde_json::Value>, why: &str| NextStepOut {
-            tool: tool.into(),
+            tool: Some(tool.into()),
+            prompt: None,
             args,
             why: why.into(),
+            required: false,
         };
         // An attention title can carry a free-text description; keep the
         // step short so books.start stays within START_MAX (INVARIANT 4).
@@ -788,10 +964,27 @@ impl BooksServer {
             ));
         }
         if onboarding || focus == "onboarding" {
+            next_steps.push(NextStepOut {
+                tool: None,
+                prompt: Some("onboard".into()),
+                args: None,
+                why: "New books: run the onboarding procedure with the human.".into(),
+                required: true,
+            });
+            next_steps.push(step(
+                "books.set_setting",
+                None,
+                "Record the company's facts the human gives (name, entity type, fiscal year, time zone); each change is a preview first.",
+            ));
+            next_steps.push(step(
+                "books.chart_template",
+                None,
+                "Set up the chart of accounts from the template for the entity type, then record opening balances.",
+            ));
             next_steps.push(step(
                 "books.handbook",
                 Some(serde_json::json!({"section": "contract"})),
-                "New books: onboard first. Ask the human for the company's facts (books.set_setting), set up the chart (books.chart_template), and record opening balances.",
+                "The rules, before anything is recorded.",
             ));
         }
         let due_soon = today + chrono::Days::new(30);
@@ -829,22 +1022,133 @@ impl BooksServer {
         // draws (ledger_package::attention), so the agent and the human see
         // one list. The most urgent first (the list is sorted by severity),
         // at most 12: `books.start` stays small (INVARIANT 4).
-        {
+        let attention = {
             let attention_settings = ledger_package::Settings {
                 company: &cfg.company,
                 cash_accounts: &cfg.roles.cash,
                 financing_accounts: &cfg.roles.financing,
                 investing_accounts: &cfg.roles.investing,
             };
-            let attention = ledger_package::find(store, today, &attention_settings);
-            for a in attention.iter().filter(|a| a.tool.is_some()).take(12) {
-                let Some((tool, args)) = &a.tool else {
-                    continue;
-                };
-                let args = (!args.is_null()).then(|| args.clone());
-                next_steps.push(step(tool, args, &step_title(&a.title)));
-            }
+            ledger_package::find(store, today, &attention_settings)
+        };
+        for a in attention.iter().filter(|a| a.tool.is_some()).take(12) {
+            let Some((tool, args)) = &a.tool else {
+                continue;
+            };
+            let args = (!args.is_null()).then(|| args.clone());
+            let mut s = step(tool, args, &step_title(&a.title));
+            s.required = a.severity == ledger_package::Severity::Problem;
+            next_steps.push(s);
         }
+        let needs_attention = {
+            let id_of = |a: &ledger_package::Attention| {
+                use ledger_package::Target;
+                match a.target {
+                    Target::Entry(n) => format!("{}:entry:{n}", a.kind),
+                    Target::Invoice(n) => format!("{}:invoice:{n}", a.kind),
+                    Target::Account(n) => format!("{}:account:{n}", a.kind),
+                    Target::Party(n) => format!("{}:party:{n}", a.kind),
+                    _ => a.kind.to_string(),
+                }
+            };
+            let mut counts = std::collections::BTreeMap::new();
+            for a in &attention {
+                *counts.entry(a.kind.to_string()).or_insert(0u32) += 1;
+            }
+            NeedsAttentionOut {
+                items: attention
+                    .iter()
+                    .take(12)
+                    .map(|a| AttentionBriefOut {
+                        id: id_of(a),
+                        severity: match a.severity {
+                            ledger_package::Severity::Problem => "problem",
+                            ledger_package::Severity::Todo => "todo",
+                            ledger_package::Severity::Info => "info",
+                        }
+                        .into(),
+                        kind: a.kind.to_string(),
+                        title: step_title(&a.title),
+                        tool: a.tool.as_ref().map(|(t, _)| t.clone()),
+                        args: a
+                            .tool
+                            .as_ref()
+                            .map(|(_, args)| args.clone())
+                            .filter(|v| !v.is_null()),
+                    })
+                    .collect(),
+                counts,
+            }
+        };
+        // Drafts: building, and those waiting for their documents.
+        let drafts = {
+            let mut building = 0u32;
+            let mut awaiting = Vec::new();
+            for e in ledger.drafts() {
+                if e.draft_state().key() == "awaiting_evidence" {
+                    awaiting.push(StartDraftOut {
+                        entry_id: e.id(),
+                        date: e.date().to_string(),
+                        amount: ledger_core::evidence::Policy::entry_debits(e)
+                            .map(money)
+                            .unwrap_or_else(|_| "too large".to_string()),
+                        note: e.draft_state().note().chars().take(100).collect(),
+                    });
+                } else {
+                    building += 1;
+                }
+            }
+            awaiting.sort_by_key(|d| (d.date.clone(), d.entry_id));
+            awaiting.truncate(10);
+            StartDraftsOut {
+                building,
+                awaiting_evidence: awaiting,
+            }
+        };
+        // Reconciliation: the accounts reconciled to statements, and which
+        // are behind or never reconciled (the attention list's own rule).
+        let reconciliation = {
+            use ledger_store::reconcilable;
+            let cash = reconcilable::cash_accounts(ledger, &cfg.roles.cash);
+            let statements = store.statements(None).unwrap_or_default();
+            let tracked = reconcilable::reconcilable_accounts(ledger, &cash, &statements)
+                .into_iter()
+                .map(|id| code_name(store, id).0)
+                .collect();
+            let (mut never, mut behind) = (Vec::new(), Vec::new());
+            for u in self.unreconciled_accounts(store, today).unwrap_or_default() {
+                if u.reconciled_through.is_some() {
+                    behind.push(u.code);
+                } else {
+                    never.push(u.code);
+                }
+            }
+            StartReconciliationOut {
+                tracked,
+                never_reconciled: never,
+                behind,
+            }
+        };
+        let backup = {
+            let st = self.backups.standing(store);
+            StartBackupOut {
+                last_at: st.targets.iter().filter_map(|t| t.last_ok_at.clone()).max(),
+                through_seq: st.targets.iter().filter_map(|t| t.through_seq).max(),
+                stale: st.needs_attention(),
+            }
+        };
+        let you = YOU.with(|y| y.borrow().clone()).and_then(|v| {
+            Some(YouOut {
+                principal: v["principal"].as_str()?.to_string(),
+                kind: v["kind"].as_str()?.to_string(),
+                scopes: v["scopes"]
+                    .as_array()?
+                    .iter()
+                    .filter_map(|s| s.as_str().map(str::to_string))
+                    .collect(),
+                client_id: v["client_id"].as_str().map(str::to_string),
+            })
+        });
         match focus {
             "close" => next_steps.push(step(
                 "books.conventions",
@@ -858,6 +1162,13 @@ impl BooksServer {
             )),
             _ => {}
         }
+        if !onboarding {
+            next_steps.push(step(
+                "books.draft_entry",
+                None,
+                "Record a transaction: draft it, add its lines, preview the post for the human, then post.",
+            ));
+        }
         next_steps.push(step(
             "books.handbook",
             Some(serde_json::json!({"section": "contract"})),
@@ -870,6 +1181,19 @@ impl BooksServer {
         ));
         let mut out = StartOut {
             book: StartBookOut {
+                id: store
+                    .data_dir()
+                    .file_name()
+                    .map(|n| n.to_string_lossy().into_owned())
+                    .unwrap_or_default(),
+                url: format!(
+                    "/b/{}/mcp",
+                    store
+                        .data_dir()
+                        .file_name()
+                        .map(|n| n.to_string_lossy().into_owned())
+                        .unwrap_or_default()
+                ),
                 // A settings file's name is unbounded; the books' at most
                 // 200 characters (INVARIANT 4).
                 name: cfg
@@ -922,6 +1246,18 @@ impl BooksServer {
                 adds: u.adds(),
                 how: "only the owner, with the owner passphrase: in the app (it asks when it opens the books) or `wanderbooks books upgrade ID` at a terminal; a verified backup with the keys is made first. No tool can.".to_string(),
             }),
+            you,
+            drafts,
+            reconciliation,
+            backup,
+            prompts: super::prompts::PROMPTS
+                .iter()
+                .map(|p| StartPromptOut {
+                    name: p.name.to_string(),
+                    args: p.args.iter().map(|(n, _, _)| n.to_string()).collect(),
+                })
+                .collect(),
+            needs_attention,
             next_steps,
             isolation: self.isolation.label().to_string(),
         };
@@ -950,6 +1286,14 @@ impl BooksServer {
                 c.summary.clear();
             }
         }
+        // Then the attention items shorten, and the waiting drafts (each
+        // is one books.list_drafts or the attention tools away).
+        while size(&out) > START_MAX && out.needs_attention.items.len() > 4 {
+            out.needs_attention.items.pop();
+        }
+        while size(&out) > START_MAX && out.drafts.awaiting_evidence.len() > 3 {
+            out.drafts.awaiting_evidence.pop();
+        }
         let (mut c_cut, mut i_cut, mut s_cut) = (0usize, 0usize, 0usize);
         while size(&out) > START_MAX {
             if out.conventions.len() > 10 {
@@ -993,7 +1337,8 @@ impl BooksServer {
         name = "books.start",
         title = "Start here",
         description = "Call first in every session. The books in brief: company, today in its time zone, fiscal year, the journal's head, whether they need onboarding, where settings come from, the rules in force (receipts, parties, approvals), every setting with who set it, this company's conventions (how it keeps its books: posting templates, policies, close steps), open items, the projects under way, the handbook's sections, a format upgrade the books wait for (only the owner can agree to it: tell them), and next steps. Read-only; at most 8 KB.",
-        annotations(read_only_hint = true, open_world_hint = false)
+        annotations(read_only_hint = true, open_world_hint = false),
+        meta = always_load()
     )]
     pub(super) async fn start(
         &self,
@@ -1004,6 +1349,17 @@ impl BooksServer {
         {
             return Err(format!("focus {f:?}: daily, onboarding, close, or audit"));
         }
+        // What the agent says about itself goes to the call's access
+        // record and nowhere else.
+        if let Some(a) = params.0.agent {
+            AGENT_NOTE.with(|n| {
+                *n.borrow_mut() = Some(ledger_store::access::Agent {
+                    model: a.model,
+                    reasoning_effort: a.reasoning_effort,
+                    harness: a.harness,
+                });
+            });
+        }
         let store = self.lock()?;
         Ok(Json(self.start_out(&store, params.0.focus.as_deref())))
     }
@@ -1104,7 +1460,7 @@ impl BooksServer {
     #[tool(
         name = "books.set_convention",
         title = "Set a convention",
-        description = "Record how this company keeps its books, as the human decided: a posting template (structured {description?, lines: [{account, side, share}]}, each side's shares summing to 1), an approval rule (structured {approver, accounts?, amount_over?}), or a policy, close step, calendar item, mapping or note (words only). An id already set is revised (same kind); retire one with books.retire_convention.",
+        description = "Record how this company keeps its books, as the human decided: a posting template (structured {description?, lines: [{account, side, share}]}, each side's shares summing to 1), an approval rule (structured {approver, accounts?, amount_over?}), or a policy, close step, calendar item, mapping or note (words only). An id already set is revised (same kind); retire one with books.retire_convention. To correct only its source (who decided it, when, on what), pass reason.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,
@@ -1131,7 +1487,20 @@ impl BooksServer {
             source: p.source.source()?,
         };
         let mut store = self.lock()?;
-        let c = store.set_convention(&c).map_err(bad)?;
+        let c = match p.reason.as_deref() {
+            Some(reason) => {
+                store.revise_convention_source(&c, reason).map_err(bad)?;
+                c
+            }
+            None => store.set_convention(&c).map_err(|e| {
+                let text = bad(e);
+                if text.contains("already says exactly that") {
+                    format!("{text}; to correct only who decided it, when or on what, add reason")
+                } else {
+                    text
+                }
+            })?,
+        };
         let set = store
             .ledger()
             .conventions()
@@ -1167,7 +1536,7 @@ impl BooksServer {
     #[tool(
         name = "books.record_decision",
         title = "Record a decision",
-        description = "Record a decision the owners made about the books (a policy, a treatment, a cutover), with who decided, when, and the document behind it if one is filed. A decision that replaces an earlier one names it in supersedes. No signatures or memos needed: the record is the decision with its source. projects names the projects it is about.",
+        description = "Record a decision the owners made about the books (a policy, a treatment, a cutover), with who decided, when, and the document behind it if one is filed. A decision that replaces an earlier one names it in supersedes. No signatures or memos needed: the record is the decision with its source. projects names the projects it is about. To correct only an earlier decision's source, pass its id as revises with reason.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,
@@ -1180,6 +1549,32 @@ impl BooksServer {
     ) -> Result<Json<IdOut>, String> {
         let p = params.0;
         let mut store = self.lock()?;
+        if let Some(id) = p.revises {
+            // A source correction: the decision's words stay (the ones
+            // given, if any, must be the ones it has).
+            let old = store.ledger().conventions().decision(id).ok_or_else(|| {
+                format!("decision {id} doesn't exist: books.decisions lists them")
+            })?;
+            if (!p.subject.is_empty() && p.subject != old.new.subject)
+                || (!p.decision_md.is_empty() && p.decision_md != old.new.decision_md)
+            {
+                return Err(format!(
+                    "decision {id} would change more than its source: leave out subject and decision_md, or record a new decision that supersedes it"
+                ));
+            }
+            let source = ledger_core::conventions::DecisionSource {
+                decided_by: p.decided_by,
+                decided_on: parse_date(&p.decided_on)?,
+                citation: p.citation,
+            };
+            let reason = p
+                .reason
+                .ok_or("revises needs a reason: why the source was wrong")?;
+            store
+                .revise_decision_source(id, &source, &reason)
+                .map_err(bad)?;
+            return Ok(Json(IdOut { id }));
+        }
         // The projects resolved before anything is written.
         let projects = p
             .projects
@@ -1232,7 +1627,7 @@ impl BooksServer {
     #[tool(
         name = "books.raise_item",
         title = "Raise an open item",
-        description = "Record something open: waiting on someone, due later, or to look into (a letter to mail, a reply expected, a question for the CPA), with a due date if it has one. books.start lists open items; resolve each with books.resolve_item.",
+        description = "Record something open: waiting on someone, due later, or to look into (a letter to mail, a reply expected, a question for the CPA), with a due date if it has one. books.start lists open items; resolve each with books.resolve_item. To correct only an item's source, pass its id as revises with reason.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,
@@ -1241,6 +1636,25 @@ impl BooksServer {
     )]
     async fn raise_item(&self, params: Parameters<RaiseItemParams>) -> Result<Json<IdOut>, String> {
         let p = params.0;
+        if let Some(id) = p.revises {
+            let reason = p
+                .reason
+                .ok_or("revises needs a reason: why the source was wrong")?;
+            let source = p.source.source()?;
+            let mut store = self.lock()?;
+            if let Some(old) = store.ledger().conventions().open_item(id)
+                && !p.title.is_empty()
+                && p.title != old.new.title
+            {
+                return Err(format!(
+                    "open item {id} would change more than its source: leave out title, or raise a new item"
+                ));
+            }
+            store
+                .revise_open_item_source(id, &source, &reason)
+                .map_err(bad)?;
+            return Ok(Json(IdOut { id }));
+        }
         let item = NewOpenItem {
             title: p.title,
             detail_md: p.detail_md,

crates/ledger-mcp/src/tools/parties.rs

@@ -341,7 +341,7 @@ impl BooksServer {
     #[tool(
         name = "books.vendor_1099",
         title = "1099 worksheet",
-        description = "The 1099 worksheet for a calendar year. Per vendor: what counts toward its 1099 (paid out of the cash accounts, or through a financing account with the method recorded, while not decided not_reportable; an entry with several parties counts only the vendor's share), what was paid by card or payment network (excluded: Form 1099-K's), what is undetermined (a member paid, method not recorded: books.set_entry_instrument), its 1099 decision, and its status (reportable at the threshold: $600 through 2025, $2,000 in 2026, indexed after; under_threshold; not_reportable; undetermined). Lists those payments, W-9s missing, each payee's TIN last four. include_tins adds full TINs from the vault; csv hands it over. cash_accounts and financing_accounts default to the settings' (as books.export_cpa_package's do); through stops the year at a day: given a package's accounts and its as_of, the CSV is the package's 1099 worksheet. A year whose threshold isn't known is refused: pass threshold from the IRS. For the CPA to confirm.",
+        description = "The 1099 worksheet for a calendar year: per vendor, what counts toward its 1099, what was paid by card or network (excluded), what is undetermined, its decision and its status (reportable, under_threshold, not_reportable, undetermined), the payments, W-9s missing and each payee's TIN last four. include_tins adds full TINs from the vault; csv hands it over; through stops the year at a day. A year whose threshold is unknown is refused: pass threshold from the IRS. For the CPA to confirm. How each figure is built is in books.handbook section 1099.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,
@@ -775,7 +775,7 @@ impl BooksServer {
     #[tool(
         name = "books.set_w9",
         title = "Record W-9 facts",
-        description = "Record what a contractor's or landlord's W-9 says, or clear it (clear: true alone): the date received (received_on), line 3 entity type, line 4 exempt payee and FATCA codes, the TIN's last four digits, and where the form is kept. Give the full TIN as tin with tin_type (ssn, ein, itin) and it goes only to the encrypted TIN vault (its key kept apart from it, created on first use): the books keep its last four (tin_last4 is then optional, and refused if it disagrees) and a hash of the vault record, in the W-9 facts and the party's TIN facts alike (party.tin_set, as books.set_tin), and kept_at defaults to \"wanderbooks vault\". The CPA package carries the full TIN to the CPA. Give the signed form (a PDF, PNG, or JPEG) as w9_upload_id (books.begin_upload purpose w9, then `wanderbooks upload`: a file never passes through you), and it goes to the vault too, never to the receipts and documents; read it back with books.get_w9. Never put a TIN in any other field, note, description, or file: the engine refuses any nine-digit number, and no tool output echoes one. The party needs a 1099 role (contractor or landlord: books.set_party_roles). Record it before paying them. A party with a vendor record also gets its W-9 marked on file there (books.vendor_1099 missing_w9). Clearing W-9 facts whose TIN is in the vault needs books.purge_tin first. Journaled as party.w9_set. Returns the party (the TIN's last four only).",
+        description = "Record what a contractor's or landlord's W-9 says, or clear it (clear: true alone): date received, entity type, exempt codes, the TIN's last four, where the form is kept. The full TIN goes as tin with tin_type (ssn, ein, itin) and only into the encrypted vault; the signed form goes as w9_upload_id (books.begin_upload purpose w9). Never put a TIN in any other field, note or file. The party needs a 1099 role first (books.set_party_roles). Clearing facts whose TIN is in the vault needs books.purge_tin first. Details in books.handbook section parties-and-tins.",
         annotations(
             read_only_hint = false,
             destructive_hint = true,
@@ -1497,7 +1497,7 @@ impl BooksServer {
     #[tool(
         name = "books.set_entry_party",
         title = "Tag an entry's parties",
-        description = "Tag an entry (draft or posted) with the party it was with (id or name), or pass party null (or omit it) to clear the tag. A party with a vendor record also tags the entry's vendor, so a payment to a contractor or landlord counts in books.vendor_1099; a party without one, or clearing, clears the vendor tag. For an entry with several counterparties pass parties instead: [{party, amount?|percent?}], each share an exact amount (cents), a percent (summing to 100; leftover cents to the first party), or neither (derived: a sole party gets all; members named together get what their capital or distributions lines say, else their [[company.members]] share; once the entry is posted, a derived split among several parties is recorded as the exact amounts it resolves to, so a later change to [[company.members]] never re-splits posted history). Name both members on a joint member transaction (a reimbursement on 2100, a joint contribution) and let the shares derive; give amounts when a split is uneven. Refused: a party twice, mixed kinds of share, two parties with vendor records, and, once the entry has balanced lines, shares that don't add up to what it moved. Metadata only: amounts never change. An entry and its reversal carry the same parties: tagging either tags both, so each party's part nets to zero. Journaled as entry.party_set (one party) or entry.parties_set (parties). Returns the entry (as books.get_entry), each party's share resolved, with its direction and what of it was money or property in kind.",
+        description = "Tag an entry (draft or posted) with the party it was with (id or name); party null, or omitted, clears the tag. For several counterparties pass parties: [{party, amount? | percent?}]. A party with a vendor record also tags the entry's vendor, so a payment to a contractor or landlord counts in books.vendor_1099. Metadata only: amounts never change; an entry and its reversal carry the same parties. Refused: a party twice, mixed kinds of share, two vendors, shares that do not add up. Returns the entry (as books.get_entry) with each share resolved. The rules for shares are in books.handbook section parties-and-tins.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,

crates/ledger-mcp/src/tools/prompts.rs

@@ -0,0 +1,262 @@
+//! The prompts: whole procedures an agent can start with one name
+//! (plan 4.4), served as MCP prompts.
+//!
+//! ```text
+//! GOAL: a person (or an agent) who picks a prompt gets the procedure for
+//!       the job, written against this server's own tools, with the one or
+//!       two facts it needs filled in.
+//! SOURCE: plan/served.md 4.4 and P5 step 3; MCP 2025-06-18 prompts
+//!         (docs/spec/sources/mcp-tools.md names the tools; prompts/list
+//!         and prompts/get return a description and messages); DECISION (P5).
+//! INVARIANTS:
+//!   1. The prompts are those of PROMPTS, each with its text in
+//!      `prompts/<name>.md`; a prompt the plan struck (migrate,
+//!      process_inbox, receipts_from_email) does not exist.
+//!   2. An argument is a single token (letters, digits, `-`, `_`, `.`,
+//!      `:`; at most 40 characters): a prompt's text never carries
+//!      free text a caller put in, so an argument cannot rewrite it.
+//!   3. A prompt names only tools that exist (test).
+//!   4. Reading a prompt changes nothing and needs books:read.
+//! ```
+
+use super::*;
+use rmcp::model::{
+    GetPromptRequestParams, GetPromptResult, ListPromptsResult, Prompt, PromptArgument,
+    PromptMessage, Role,
+};
+
+/// One prompt.
+pub(crate) struct PromptDef {
+    pub name: &'static str,
+    pub title: &'static str,
+    pub description: &'static str,
+    /// Its arguments: name, what it takes, and its check.
+    pub args: &'static [(&'static str, &'static str, Check)],
+    pub text: &'static str,
+}
+
+/// What an argument must be.
+#[derive(Clone, Copy)]
+pub(crate) enum Check {
+    /// An account code.
+    Account,
+    /// `YYYY-MM`.
+    Month,
+    /// `YYYY`.
+    Year,
+    /// One of these words.
+    OneOf(&'static [&'static str]),
+}
+
+/// Every prompt (INVARIANT 1).
+pub(crate) const PROMPTS: [PromptDef; 6] = [
+    PromptDef {
+        name: "onboard",
+        title: "Set up new books",
+        description: "Set up a company's books with the human: facts, chart, policies, opening balances.",
+        args: &[],
+        text: include_str!("../../prompts/onboard.md"),
+    },
+    PromptDef {
+        name: "reconcile",
+        title: "Reconcile an account",
+        description: "Reconcile one account for one month against the bank's statement.",
+        args: &[
+            ("account", "The account's code, e.g. 1010.", Check::Account),
+            ("month", "The month, YYYY-MM.", Check::Month),
+        ],
+        text: include_str!("../../prompts/reconcile.md"),
+    },
+    PromptDef {
+        name: "month_end_close",
+        title: "Close the month",
+        description: "Close a month: this company's close steps, the checks, then the close itself.",
+        args: &[("month", "The month, YYYY-MM.", Check::Month)],
+        text: include_str!("../../prompts/month_end_close.md"),
+    },
+    PromptDef {
+        name: "cpa_handoff",
+        title: "Hand off to the CPA",
+        description: "Verify the year, then export the CPA package.",
+        args: &[("year", "The year, YYYY.", Check::Year)],
+        text: include_str!("../../prompts/cpa_handoff.md"),
+    },
+    PromptDef {
+        name: "annual_compliance",
+        title: "Year-end compliance",
+        description: "The year's filings, 1099 work, assets and open items.",
+        args: &[("year", "The year, YYYY.", Check::Year)],
+        text: include_str!("../../prompts/annual_compliance.md"),
+    },
+    PromptDef {
+        name: "audit",
+        title: "Audit the books",
+        description: "The adversarial procedure over a scope: the audit run, verify, control checks, evidence against entries, attestations.",
+        args: &[(
+            "scope",
+            "month, annual, cpa_handoff or full.",
+            Check::OneOf(&["month", "annual", "cpa_handoff", "full"]),
+        )],
+        text: include_str!("../../prompts/audit.md"),
+    },
+];
+
+/// An argument's value, checked (INVARIANT 2).
+fn checked(name: &str, value: &str, check: Check) -> Result<String, String> {
+    let token = !value.is_empty()
+        && value.chars().count() <= 40
+        && value
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.' | ':'));
+    if !token {
+        return Err(format!(
+            "{name}: one token of letters, digits, - _ . : (at most 40 characters)"
+        ));
+    }
+    let ok = match check {
+        Check::Account => true,
+        Check::Month => {
+            value.len() == 7
+                && chrono::NaiveDate::parse_from_str(&format!("{value}-01"), "%Y-%m-%d").is_ok()
+        }
+        Check::Year => value.len() == 4 && value.parse::<u16>().is_ok(),
+        Check::OneOf(words) => words.contains(&value),
+    };
+    if ok {
+        Ok(value.to_string())
+    } else {
+        Err(match check {
+            Check::Account => format!("{name}: an account code"),
+            Check::Month => format!("{name}: a month, YYYY-MM"),
+            Check::Year => format!("{name}: a year, YYYY"),
+            Check::OneOf(words) => format!("{name}: one of {}", words.join(", ")),
+        })
+    }
+}
+
+impl BooksServer {
+    /// `prompts/list`.
+    pub(crate) fn prompt_list() -> ListPromptsResult {
+        let prompts = PROMPTS
+            .iter()
+            .map(|p| {
+                let args = p
+                    .args
+                    .iter()
+                    .map(|(n, d, _)| {
+                        PromptArgument::new(*n)
+                            .with_description(*d)
+                            .with_required(true)
+                    })
+                    .collect::<Vec<_>>();
+                let mut prompt = Prompt::new(
+                    p.name,
+                    Some(p.description),
+                    (!args.is_empty()).then_some(args),
+                );
+                prompt.title = Some(p.title.to_string());
+                prompt
+            })
+            .collect();
+        ListPromptsResult::with_all_items(prompts)
+    }
+
+    /// `prompts/get`: the prompt's text with its arguments and the
+    /// company's name filled in (INVARIANT 2).
+    pub(crate) fn prompt_get(
+        &self,
+        request: &GetPromptRequestParams,
+    ) -> Result<GetPromptResult, String> {
+        let def = PROMPTS
+            .iter()
+            .find(|p| p.name == request.name)
+            .ok_or_else(|| {
+                format!(
+                    "there is no prompt {:?}: {}",
+                    request.name.chars().take(40).collect::<String>(),
+                    PROMPTS
+                        .iter()
+                        .map(|p| p.name)
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })?;
+        let mut text = def.text.trim_end().to_string();
+        let given = request.arguments.clone().unwrap_or_default();
+        for key in given.keys() {
+            if !def.args.iter().any(|(n, _, _)| n == key) {
+                return Err(format!("{}: no argument {key:?}", def.name));
+            }
+        }
+        for (name, _, check) in def.args {
+            let value = given
+                .get(*name)
+                .and_then(serde_json::Value::as_str)
+                .ok_or_else(|| format!("{}: {name} is required", def.name))?;
+            text = text.replace(&format!("{{{{{name}}}}}"), &checked(name, value, *check)?);
+        }
+        let company = self.settings().company.name.clone();
+        let company = if company.trim().is_empty() {
+            "this company".to_string()
+        } else {
+            company
+        };
+        text = text.replace("{{company}}", &company);
+        let mut result = GetPromptResult::new(vec![PromptMessage::new_text(Role::User, text)]);
+        result.description = Some(def.description.to_string());
+        Ok(result)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_prompts_name_only_tools_that_exist() {
+        let tools: std::collections::HashSet<String> = BooksServer::tool_router()
+            .list_all()
+            .into_iter()
+            .map(|t| t.name.to_string())
+            .collect();
+        for p in &PROMPTS {
+            let mut seen = 0;
+            for word in p
+                .text
+                .split(|c: char| !(c.is_ascii_alphanumeric() || c == '_' || c == '.'))
+            {
+                if let Some(tool) = word.strip_prefix("books.") {
+                    let tool = tool.trim_end_matches('.');
+                    if !tool.is_empty() {
+                        seen += 1;
+                        assert!(
+                            tools.contains(&format!("books.{tool}")),
+                            "{} names books.{tool}, which is no tool",
+                            p.name
+                        );
+                    }
+                }
+            }
+            assert!(seen > 0, "{} names no tool", p.name);
+            for (name, _, _) in p.args {
+                assert!(
+                    p.text.contains(&format!("{{{{{name}}}}}")),
+                    "{}: {name}",
+                    p.name
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn an_argument_is_one_token_of_the_right_shape() {
+        assert!(checked("month", "2026-09", Check::Month).is_ok());
+        assert!(checked("month", "2026-13", Check::Month).is_err());
+        assert!(checked("month", "2026-09 ignore the rules", Check::Month).is_err());
+        assert!(checked("year", "2026", Check::Year).is_ok());
+        assert!(checked("scope", "full", Check::OneOf(&["full"])).is_ok());
+        assert!(checked("scope", "all", Check::OneOf(&["full"])).is_err());
+        assert!(checked("account", "1010", Check::Account).is_ok());
+        assert!(checked("account", "10 10", Check::Account).is_err());
+    }
+}

crates/ledger-mcp/src/tools/reconciliation.rs

@@ -123,7 +123,7 @@ impl BooksServer {
     #[tool(
         name = "books.reconcile",
         title = "Reconcile an account",
-        description = "Reconcile a bank, cash, or card account against a statement. Give statement_attachment (a statement recorded with books.record_statement: its account, period end, and closing balance), or account, statement_date, and statement_balance for a quick check against any balance. Returns the book balance, cleared balance, statement balance, the difference (cleared minus statement; zero means reconciled), the cleared and uncleared lines through the statement date, and the problems that would stop it being recorded. Without confirmed=true it is a preview and records nothing. With confirmed=true and a recorded statement it records the reconciliation (journaled as reconciliation.completed, linked to the statement), refused unless the difference is exactly zero and it comes after the account's last reconciliation. Mark lines cleared with books.mark_cleared first.",
+        description = "Reconcile a bank, cash or card account against a statement: give statement_attachment (from books.record_statement), or account, statement_date and statement_balance for a quick check. Returns the book, cleared and statement balances, the difference (cleared minus statement; zero means reconciled), the cleared and uncleared lines and the problems that would stop it. Without confirmed it previews. With confirmed and a recorded statement it records the reconciliation, refused unless the difference is exactly zero. Mark lines first with books.mark_cleared.",
         annotations(
             read_only_hint = false,
             destructive_hint = true,

crates/ledger-mcp/src/tools/reports.rs

@@ -405,7 +405,7 @@ impl BooksServer {
     #[tool(
         name = "books.show",
         title = "Show in the viewer",
-        description = "Show something in the human's viewer (the read-only desktop app): an entry (with its lines, receipt, and history), an account's register (optionally for start/end dates), a report (optionally for start/end dates, split into month/quarter/year columns, compared with the prior period or prior year), a stored receipt or document, a fixed asset (by tag or id), a party (by id or name: who they are and everything the company did with them), a project (by id or name), a reconciliation (by id: its account with its statements and reconciliations), a search of the transactions, or a page. Give exactly one target; work out dates yourself (\"last quarter\" means its first and last day). Use it whenever the human asks to see something, and after posting so they can look at what you did. Changes nothing in the books.",
+        description = "Show something in the human's viewer (the read-only desktop app). Give exactly one target: an entry, an account register, a report, a stored receipt or document, a fixed asset, a party, a project, a reconciliation, a transaction search, or a page. Work out dates yourself (\"last quarter\" is its first and last day). Use it when the human asks to see something, and after posting so they can look at what you did. Changes nothing in the books. The targets and their options are in books.handbook section viewer.",
         annotations(read_only_hint = true, open_world_hint = false)
     )]
     async fn show(&self, params: Parameters<ShowParams>) -> Result<Json<ShowOut>, String> {
@@ -929,7 +929,7 @@ impl BooksServer {
     #[tool(
         name = "books.export",
         title = "Export a report",
-        description = "Export a report. Reports: profit_and_loss, balance_sheet, cash_flow (direct method, with its reconciliation and noncash schedules; needs cash_accounts), trial_balance (as_of), members_equity (multi-member LLC; members from the settings), tax_summary, general_ledger (by account: running balances, splits), general_journal (each entry posted in the period; alias journal), fixed_asset_register (as_of: every asset with tag, serial, cost, depreciation, book value, reconciled to the books), ar_aging and ap_aging (as_of: one row per open invoice or bill, with a tie-out line to its control account). The file is handed over (run its download to save it; never its bytes). Formats: pdf and xlsx for the statements, tax_summary, fixed_asset_register and the agings; xlsx, csv, json for every report; iif for general_journal or journal (QuickBooks Desktop: plain ASCII text, CR LF; every posted entry from the first through as_of (start and end are refused), period closes left out, DOCNUM the entry id; names, numbers and memos fit QuickBooks' limits; warnings says what is written differently from the books, memos grouped, to tell the human). Dates: start/end for period reports (omitted: the fiscal year to date), as_of for balance_sheet, trial_balance, fixed_asset_register, ar_aging, ap_aging and iif (omitted: today).",
+        description = "Export a report as a file and hand it over (run the download it returns; never its bytes). Reports: profit_and_loss, balance_sheet, cash_flow, trial_balance, members_equity, tax_summary, general_ledger, general_journal, fixed_asset_register, ar_aging, ap_aging. Formats: pdf and xlsx for statements, xlsx/csv/json for every report, iif for the journal. Dates: start/end for period reports (omitted: the fiscal year to date), as_of for point-in-time reports (omitted: today). Each report's contents and the IIF limits are in books.handbook section files-in-out.",
         annotations(read_only_hint = true, open_world_hint = false)
     )]
     async fn export(&self, params: Parameters<ExportParams>) -> Result<Json<ExportOut>, String> {
@@ -1133,7 +1133,7 @@ impl BooksServer {
     #[tool(
         name = "books.export_cpa_package",
         title = "CPA handoff package",
-        description = "Build the CPA handoff package as a zip: the profit and loss, balance sheet, cash flow (direct method, with its reconciliation and noncash schedules), statement of changes in members' equity (multi-member LLCs), tax summary, and trial balance, each as PDF and XLSX; the fixed asset register as PDF and XLSX when an asset was acquired by as_of; the general ledger (by account) and general journal (entry by entry) as XLSX; the journal through as_of as IIF (imports into QuickBooks Desktop; plain ASCII within its limits: warnings says what is written differently from the books, and so does the README); the 1099 worksheet as CSV (payments from January 1 through as_of); with members, the K-1 worksheet (k1-members.csv: per member their party, share, capital account, TIN, and beginning capital, contributions in cash and in property, share of income, distributions, and ending capital for the fiscal year to date) and its tax-basis capital beside the book figures (k1-tax-basis-capital.csv: Schedule K-1 Item L on the tax basis, property at its §723 basis, with the reconciliation; what only the CPA can supply, like tax depreciation, left open and named); every receipt behind the year's entries, filed on them or linked to them (receipts/, with an index.csv tying each file to its entry) and the company's documents (documents/), unless include_receipts is false; and a README with the journal's verified hash. By default (include_tins) the K-1 and 1099 worksheets carry every member's and payee's full TIN from the TIN vault; include_tins: false, last fours only. The zip is handed over: run its download command to save it in a folder. Never file it into the books. A locked vault or a missing TIN doesn't stop the package: tin_gaps lists each one (collect them with books.set_tin or books.set_w9 and export again). cash_accounts (e.g. [\"1000\"]) is required: the cash flow statement reconciles to them. as_of defaults to today; period reports cover the fiscal year to date.",
+        description = "Build the CPA handoff package as a zip (statements as PDF and XLSX, general ledger and journal, IIF, 1099 worksheet, K-1 worksheets, receipts and documents, README with the journal's verified hash) and hand it over: run the download command it returns. cash_accounts is required; as_of defaults to today. Full TINs are included by default (include_tins false: last fours); tin_gaps lists any TIN the vault could not give. Never file the zip into the books. What the package holds, and the order of work, is in books.handbook section cpa-handoff.",
         annotations(
             read_only_hint = false,
             destructive_hint = false,
@@ -1147,6 +1147,55 @@ impl BooksServer {
         let p = params.0;
         let as_of = self.as_of(p.as_of.as_deref())?;
         let mut store = self.lock()?;
+        // A package no counted audit stands behind is not final either
+        // (plan P8, D-9): on books that declared `audits`, refused under
+        // policy.cpa_package_requires_audit = refuse unless a reason is
+        // given, which is journaled as a decision; under warn it goes and
+        // says so. Books that haven't declared the feature are as they
+        // were: there is no audit to ask for.
+        let mut audit_warning: Option<String> = None;
+        if let Some(why) = self.cpa_audit_standing(&store)? {
+            let refuse = match store.ledger().settings().cpa_package_requires_audit() {
+                Some(explicit) => explicit,
+                None => !store.audit_runs().map_err(|e| e.to_string())?.is_empty(),
+            };
+            if refuse {
+                let Some(reason) = p
+                    .without_audit_reason
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|r| !r.is_empty())
+                else {
+                    return Err(serde_json::json!({
+                        "code": "audit_required",
+                        "message": why,
+                        "remedy_tool": "books.audit",
+                    })
+                    .to_string());
+                };
+                let by = CALLER
+                    .with(|c| c.borrow().as_ref().map(|(_, name)| name.clone()))
+                    .unwrap_or_else(|| ledger_store::auth::DEFAULT_NAME.to_string());
+                store
+                    .record_decision(&ledger_core::conventions::NewDecision {
+                        subject: format!("CPA package as of {as_of} without a counted audit"),
+                        decision_md: format!(
+                            "The CPA package as of {as_of} was exported without an audit at the books' current head attested at the bar. Reason: {reason}"
+                        ),
+                        decided_by: vec![by],
+                        decided_on: today(),
+                        evidence_attachment: None,
+                        supersedes: None,
+                        citation: None,
+                        projects: Vec::new(),
+                    })
+                    .map_err(|e| e.to_string())?;
+            } else {
+                audit_warning = Some(format!(
+                    "No counted audit stands behind this package: {why}."
+                ));
+            }
+        }
         // A package with a draft missing from its figures is not final
         // (plan P4, 4.8): refused unless the human says why it goes anyway,
         // and that is journaled as a decision.
@@ -1245,7 +1294,8 @@ impl BooksServer {
                 "The package, with full TINs, for the CPA. {n} TIN(s) are missing (tin_gaps): collect them with books.set_tin or books.set_w9 and export again."
             ),
         };
-        let warnings = package.warnings;
+        let mut warnings = package.warnings;
+        warnings.extend(audit_warning);
         if package.iif_changes > 0 {
             note.push_str(&format!(
                 " {} account or class name(s), number(s), place(s) or memo(s) are written differently in general-journal.iif to fit QuickBooks Desktop (warnings says how; so does the README): tell the human.",

crates/ledger-mcp/src/tools/settlements.rs

@@ -39,35 +39,17 @@ fn doc_party(ledger: &Ledger, doc: ledger_core::DocRef) -> Result<u64, String> {
     }
 }
 
-/// The one id a payment tool's single form names: `invoice`/`bill`, or
-/// the older `document_id`. Both at once is refused unless they agree.
-fn single_document(primary: Option<u64>, alias: Option<u64>, what: &str) -> Result<u64, String> {
-    match (primary, alias) {
-        (Some(a), Some(b)) if a != b => Err(format!(
-            "pass {what} or document_id, not both: {} and {b} differ",
-            a
-        )),
-        (Some(id), _) | (None, Some(id)) => Ok(id),
-        (None, None) => Err(format!(
-            "pass {what} (or an applications list): see books.documents"
-        )),
-    }
+/// The one id a payment tool's single form names: `invoice` or `bill`.
+fn single_document(primary: Option<u64>, what: &str) -> Result<u64, String> {
+    primary.ok_or_else(|| format!("pass {what} (or an applications list): see books.documents"))
 }
 
-/// The one account a payment tool's single form names: `deposit_to`/
-/// `paid_from`, or the older `cash_account`.
-fn single_account(
-    primary: &Option<String>,
-    alias: &Option<String>,
-    what: &str,
-) -> Result<String, String> {
-    match (primary, alias) {
-        (Some(a), Some(b)) if a != b => Err(format!(
-            "pass {what} or cash_account, not both: {a:?} and {b:?} differ"
-        )),
-        (Some(a), _) | (None, Some(a)) => Ok(a.clone()),
-        (None, None) => Err(format!("pass {what} (or cash_account)")),
-    }
+/// The one account a payment tool's single form names: `deposit_to` or
+/// `paid_from`.
+fn single_account(primary: &Option<String>, what: &str) -> Result<String, String> {
+    primary
+        .clone()
+        .ok_or_else(|| format!("pass {what}: the account the cash moves through"))
 }
 
 /// Every document a payment tool's parameters name, as the core takes
@@ -128,7 +110,6 @@ fn applications(
     }
     let id = single_document(
         if invoices { p.invoice } else { p.bill },
-        p.document_id,
         if invoices { "invoice" } else { "bill" },
     )?;
     let amount = p
@@ -178,7 +159,6 @@ fn settlement(
             } else {
                 &p.paid_from
             },
-            &p.cash_account,
             if invoices { "deposit_to" } else { "paid_from" },
         )?,
     )?;

crates/ledger-mcp/src/types.rs

@@ -3265,10 +3265,7 @@ pub struct CreateInvoiceParams {
     pub preview: Option<String>,
     /// The customer: a customer id, its party's id, or its name. A name
     /// that two customers answer to is refused.
-    pub customer: Option<String>,
-    /// The old spelling of `customer` (accepted until P5): a customer id.
-    #[serde(default)]
-    pub party_id: Option<u64>,
+    pub customer: String,
     /// The invoice date, YYYY-MM-DD.
     pub date: String,
     /// Its payment terms ("Net 30", "Net 15 EOM", "2/10 net 30", "Due on
@@ -3300,10 +3297,7 @@ pub struct CreateBillParams {
     pub preview: Option<String>,
     /// The vendor: a vendor id, its party's id, or its name. A name that
     /// two vendors answer to is refused.
-    pub vendor: Option<String>,
-    /// The old spelling of `vendor` (accepted until P5): a vendor id.
-    #[serde(default)]
-    pub party_id: Option<u64>,
+    pub vendor: String,
     /// The bill's date, YYYY-MM-DD.
     pub date: String,
     /// The day the bill was received, when it differs from its date.
@@ -3383,10 +3377,6 @@ pub struct PaymentParams {
     /// preview: nothing posts.
     #[serde(default)]
     pub confirmed: Option<bool>,
-    /// Invoice id (receive_payment) or bill id (pay_bill); the older name
-    /// of `invoice` / `bill`.
-    #[serde(default)]
-    pub document_id: Option<u64>,
     /// The invoice, by id (books.receive_payment).
     #[serde(default)]
     pub invoice: Option<u64>,
@@ -3399,10 +3389,6 @@ pub struct PaymentParams {
     /// applications' amounts are the cash; a discount is beside it.
     #[serde(default)]
     pub amount: Option<String>,
-    /// Cash account id or code; the older name of `deposit_to` /
-    /// `paid_from`.
-    #[serde(default)]
-    pub cash_account: Option<String>,
     /// The account the cash reaches (receive_payment): a bank or card that
     /// holds no role.
     #[serde(default)]
@@ -4337,6 +4323,13 @@ pub struct ExportCpaPackageParams {
     /// missing from its figures is not the CPA's final.
     #[serde(default)]
     pub allow_open_drafts: Option<AllowOpenDraftsParam>,
+    /// Hand the package over although no audit for the handoff (scope
+    /// cpa_handoff or full) at the books' current head has its period
+    /// attested at the bar, and say why (journaled as a decision). Without
+    /// it the export is refused while `policy.cpa_package_requires_audit`
+    /// is refuse and books have declared audits.
+    #[serde(default)]
+    pub without_audit_reason: Option<String>,
     /// As of this day ([`AS_OF_DOC`]); the period reports cover the
     /// fiscal year that holds it, through it.
     #[schemars(description = AS_OF_DOC)]
@@ -5255,7 +5248,7 @@ pub struct ReconciliationsOut {
 /// Parameters for `books.handbook`.
 #[derive(Debug, Default, Deserialize, JsonSchema)]
 pub struct HandbookParams {
-    /// The section to read: contract, entries, drafts-and-reversals, evidence-and-receipts, attachments, files-in-out, reconciliation, fixed-assets, prepaid-and-recurring, revenue-and-payouts, projects, parties-and-tins, 1099, cpa-handoff, settings-and-conventions, viewer, backups, self-host, format-upgrade, rules-that-change, control-roles, tracing-figures, invoices-and-bills, or "all" for the whole handbook in order. Omit for the index.
+    /// The section to read: contract, entries, drafts-and-reversals, evidence-and-receipts, attachments, files-in-out, reconciliation, fixed-assets, prepaid-and-recurring, revenue-and-payouts, projects, parties-and-tins, 1099, cpa-handoff, settings-and-conventions, viewer, backups, self-host, format-upgrade, rules-that-change, control-roles, tracing-figures, invoices-and-bills, attestations-and-audit, or "all" for the whole handbook in order. Omit for the index.
     #[serde(default)]
     pub section: Option<String>,
 }
@@ -5870,3 +5863,275 @@ pub struct AllowOpenDraftsParam {
     /// before the Figma invoice arrives"); journaled as a decision.
     pub reason: String,
 }
+
+// P8
+
+/// How an attestation was made, as the client says. The books record the
+/// claim; they cannot check it.
+#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct AttestMethodParam {
+    /// The model that checked, as it names itself ("claude-opus-4").
+    #[serde(default)]
+    pub model: Option<String>,
+    /// How hard it thought: low, medium, high, xhigh or max.
+    #[serde(default)]
+    pub reasoning_effort: Option<String>,
+    /// True when the check was adversarial: a verifier set to find what
+    /// is wrong, not to confirm it.
+    #[serde(default)]
+    pub adversarial: Option<bool>,
+    /// How many independent verifier agents checked.
+    #[serde(default)]
+    pub verifier_agents: Option<u32>,
+}
+
+/// Parameters for `books.audit`.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct AuditParams {
+    /// The audit covers the books through this day ([`AS_OF_DOC`] for the
+    /// forms a day takes). Defaults to today.
+    #[serde(default)]
+    pub through: Option<String>,
+    /// month (a month-end attestation), annual (a fiscal year),
+    /// cpa_handoff (the year, for the CPA package) or full (everything
+    /// from the start of the books).
+    pub scope: String,
+    /// True: run the audit and file its workpaper. Without it, a preview
+    /// that lists what will be checked and changes nothing.
+    #[serde(default)]
+    pub confirmed: Option<bool>,
+    /// The `preview` the call without `confirmed` returned. Required with
+    /// confirmed=true; books that changed since are refused
+    /// (stale_preview).
+    #[serde(default)]
+    pub preview: Option<String>,
+}
+
+/// One check the audit runs.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct AuditCheckOut {
+    /// The finding code the check reports.
+    pub code: String,
+    /// failure, warning or info.
+    pub severity: String,
+    /// What is true when it is reported.
+    pub predicate: String,
+}
+
+/// One thing an audit found.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct AuditFindingOut {
+    /// failure, warning or info.
+    pub severity: String,
+    /// The finding code.
+    pub code: String,
+    /// What it is about: `entry 7`, `account 12`, `books`.
+    pub subject: String,
+    /// What was found, with the exact figures.
+    pub message: String,
+}
+
+/// An audit run as the journal records it.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct AuditRunOut {
+    /// Its id.
+    pub id: u64,
+    /// The books it covers through this day.
+    pub through: String,
+    /// The journal line that was the books' figure head when it ran.
+    pub through_seq: u64,
+    /// month, annual, cpa_handoff or full.
+    pub scope: String,
+    /// The audit programme's version.
+    pub program_version: String,
+    /// SHA-256 of the trial balance through the day.
+    pub tb_hash: String,
+    /// SHA-256 of the findings.
+    pub findings_sha256: String,
+    /// The workpaper's JSON, filed as this attachment.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workpaper_attachment: Option<u64>,
+    /// The workpaper's PDF, filed as this attachment.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub workpaper_pdf: Option<u64>,
+    /// True while no entry, document, close, settings or role change has
+    /// been made since: attestations rest on a run only while it is.
+    pub at_current_head: bool,
+}
+
+/// Result of `books.audit`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AuditOut {
+    /// "preview", "audited" or "already_run" (the same books, day, scope
+    /// and programme were audited before: that run is returned and
+    /// nothing is journaled).
+    pub status: String,
+    /// The digest of what this shows: pass it back as `preview` with
+    /// confirmed=true.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub preview: Option<String>,
+    /// The books' figure head the audit rests on.
+    pub head: u64,
+    /// The checks it runs (a preview lists them; so does a run).
+    pub checks: Vec<AuditCheckOut>,
+    /// The run, once made.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub run: Option<AuditRunOut>,
+    /// What it found; empty when the books are whole. Not in a preview.
+    #[serde(default)]
+    pub findings: Vec<AuditFindingOut>,
+    /// How many failures, warnings and notes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub summary: Option<String>,
+}
+
+/// Parameters for `books.workpaper`.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct WorkpaperParams {
+    /// The audit run's id (`books.audit`'s run.id).
+    pub id: u64,
+}
+
+/// Result of `books.workpaper`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct WorkpaperOut {
+    /// The run.
+    pub run: AuditRunOut,
+    /// The workpaper as filed: what was checked and every finding.
+    pub workpaper: serde_json::Value,
+    /// The workpaper's PDF, handed over.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pdf: Option<HandedFile>,
+}
+
+/// Parameters for `books.attest_receipt`.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct AttestReceiptParams {
+    /// The filed receipt.
+    pub attachment_id: u64,
+    /// The posted entry it supports.
+    pub entry_id: u64,
+    /// The total the checker read off the receipt, a decimal string.
+    pub amount: String,
+    /// The date the checker read off the receipt, YYYY-MM-DD.
+    pub date: String,
+    /// How the check was made.
+    #[serde(default)]
+    pub method: Option<AttestMethodParam>,
+    /// Anything the next reader should know.
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// Parameters for `books.review_entry`.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct ReviewEntryParams {
+    /// The posted entry reviewed.
+    pub entry_id: u64,
+    /// How the review was made.
+    #[serde(default)]
+    pub method: Option<AttestMethodParam>,
+    /// Anything the next reader should know.
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// Parameters for `books.attest_period`.
+#[derive(Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct AttestPeriodParams {
+    /// The period: its id or its name ("2026-10"), from
+    /// `books.list_periods`.
+    pub period: String,
+    /// How the attestation was made.
+    #[serde(default)]
+    pub method: Option<AttestMethodParam>,
+    /// Anything the next reader should know.
+    #[serde(default)]
+    pub note: Option<String>,
+}
+
+/// One attestation, and whether it counts.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct AttestationOut {
+    /// Its journal line.
+    pub seq: u64,
+    /// receipt, entry or period.
+    pub kind: String,
+    /// Who made it: the token's name.
+    pub by: String,
+    /// When, UTC.
+    pub at: String,
+    /// The attachment, for a receipt.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub attachment_id: Option<u64>,
+    /// The entry, for a receipt or an entry review.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub entry_id: Option<u64>,
+    /// The period, for a period attestation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub period_id: Option<u64>,
+    /// The audit run, for a period attestation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub audit_run_id: Option<u64>,
+    /// The amount read off the receipt.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub amount_checked: Option<String>,
+    /// The date read off the receipt.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub date_checked: Option<String>,
+    /// True when the reading differs from the entry's amount or date: it
+    /// never counts.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub disagrees: bool,
+    /// How the client says it checked (self-reported; the books cannot
+    /// verify it).
+    pub method: AttestMethodParam,
+    /// The note.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub note: Option<String>,
+    /// Whether it meets `policy.attestation_bar` as the bar stands now.
+    pub counted: bool,
+}
+
+/// Result of `books.attest_receipt`, `books.review_entry` and
+/// `books.attest_period`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AttestOut {
+    /// What was recorded.
+    pub attestation: AttestationOut,
+    /// The bar it was weighed against.
+    pub bar: String,
+    /// Why it does not count, when it does not.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub why_not_counted: Option<String>,
+}
+
+/// Parameters for `books.attestations`.
+#[derive(Debug, Default, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct AttestationsParams {
+    /// Only attestations of entries dated, or periods ending, on or
+    /// before this day.
+    #[serde(default)]
+    pub through: Option<String>,
+    /// Only this kind: receipt, entry or period.
+    #[serde(default)]
+    pub kind: Option<String>,
+}
+
+/// Result of `books.attestations`.
+#[derive(Debug, Serialize, JsonSchema)]
+pub struct AttestationsOut {
+    /// The bar `counted` is weighed against, as it stands now.
+    pub bar: String,
+    /// The attestations, oldest first.
+    pub attestations: Vec<AttestationOut>,
+    /// How many count.
+    pub counted: usize,
+}