docs(handbook): the invoices-and-bills procedure, whole (P4b S4.5)

Step 1 now covers the issue: preview first (nothing written, the DRAFT PDF,
an abandoned preview uses no number), confirm only after the human has
seen it, the filed issued copy that a later look never replaces,
quantities and prices, the PO, and the snapshot of the customer at issue.
Step 6 is the CPA's list: agings tied to 1200 and 2000, sequential numbers
with voids visible, bills on their real accounts with the vendor's number
and no duplicate, card payments identified for 1099-NEC, deposits as
liabilities, light governance by decision.

A {documents_v2} placeholder (handbook::section_with, the server's
documents_v2 feature test) says "your books have not declared documents_v2
yet" before the owner's upgrade and what is on after it; no other section
changes. Parity, testing (with the For-P12 paragraph) and mcp-interface
notes for S4.5.

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

crates/ledger-mcp/src/handbook.rs

@@ -132,11 +132,25 @@ pub const ALL: &str = "all";
 /// The section `id` (or [`ALL`]), rendered for these settings, the
 /// books' base currency, and whether they declared the journal feature
 /// `document_line_projects` (None: no such section).
+#[cfg(test)]
 pub fn section(
     id: &str,
     settings: &Settings,
     currency: &str,
     document_line_projects: bool,
+) -> Option<String> {
+    section_with(id, settings, currency, document_line_projects, true)
+}
+
+/// [`section`], also saying whether the books declared the journal
+/// feature `documents_v2` (the invoices-and-bills section says what
+/// waits for the owner's upgrade by it).
+pub fn section_with(
+    id: &str,
+    settings: &Settings,
+    currency: &str,
+    document_line_projects: bool,
+    documents_v2: bool,
 ) -> Option<String> {
     let render = |md: &str| {
         md.replace("{evidence_rule}", &evidence_rule(settings, currency))
@@ -145,6 +159,7 @@ pub fn section(
                 "{document_projects}",
                 document_projects_rule(document_line_projects),
             )
+            .replace("{documents_v2}", documents_v2_rule(documents_v2))
     };
     if id == ALL {
         let parts: Vec<String> = SECTIONS.iter().map(|(_, md)| render(md)).collect();
@@ -178,6 +193,17 @@ pub fn document_projects_rule(declared: bool) -> &'static str {
     }
 }
 
+/// What the books have of the document upgrade (journal feature
+/// `documents_v2`, plan P4b S4), as the invoices-and-bills section says
+/// it: on, or waiting for the owner's go-ahead.
+pub fn documents_v2_rule(declared: bool) -> &'static str {
+    if declared {
+        "These books have declared documents_v2: an invoice takes a number, terms and a purchase-order reference, a bill takes the vendor's number, and every bill line names its account."
+    } else {
+        "Your books have not declared documents_v2 yet: numbers, terms and line accounts wait for the owner's upgrade (books.start's format_upgrade). Until then an invoice is \"Invoice {id}\", a bill's lines post to 6999, and a document carrying a new field is refused with format_upgrade_pending; the issued PDF is still filed with the invoice."
+    }
+}
+
 /// The receipt rule in force (INVARIANT 2).
 pub fn evidence_rule(settings: &Settings, currency: &str) -> String {
     format!(
@@ -487,6 +513,7 @@ mod tests {
             assert!(!text.contains("{evidence_rule}"), "{id}");
             assert!(!text.contains("{period_rule}"), "{id}");
             assert!(!text.contains("{document_projects}"), "{id}");
+            assert!(!text.contains("{documents_v2}"), "{id}");
         }
         // The default period, in the descriptions' own words (B-30).
         assert!(
@@ -502,6 +529,51 @@ mod tests {
         assert!(section("nope", &s, "USD", true).is_none());
     }
 
+    /// The invoices-and-bills section says what waits for the owner's
+    /// upgrade (`documents_v2`) before the go-ahead and what is on after;
+    /// the procedure around it is the same text, and no other section
+    /// changes (plan P4b S4.5).
+    #[test]
+    fn documents_v2_follows_the_books_feature() {
+        let s = settings("Co", Decimal::ZERO);
+        let with = section_with("invoices-and-bills", &s, "USD", true, true).unwrap();
+        let without = section_with("invoices-and-bills", &s, "USD", true, false).unwrap();
+        assert!(without.contains(
+            "Your books have not declared documents_v2 yet: numbers, terms and line accounts wait for the owner's upgrade"
+        ));
+        assert!(!with.contains("have not declared documents_v2"));
+        assert!(with.contains("These books have declared documents_v2"));
+        // Every step of the procedure is there either way, in order.
+        for text in [&with, &without] {
+            let at = |needle: &str| {
+                text.find(needle)
+                    .unwrap_or_else(|| panic!("{needle:?} missing from:\n{text}"))
+            };
+            let steps = [
+                "## 1. Issue and send an invoice",
+                "## 2. Record a customer payment",
+                "## 3. Pay a vendor bill",
+                "## 4. Void, write off, or reverse",
+                "## 5. A processor's fee",
+                "## 6. What the CPA will check",
+            ];
+            let places: Vec<usize> = steps.iter().map(|h| at(h)).collect();
+            assert!(places.windows(2).all(|w| w[0] < w[1]), "{places:?}");
+            assert!(text.contains("books.mark_sent") && text.contains("books.control_check"));
+            assert!(text.contains("An abandoned preview uses up no number"));
+        }
+        for (id, _) in SECTIONS
+            .iter()
+            .filter(|(id, _)| *id != "invoices-and-bills")
+        {
+            assert_eq!(
+                section_with(id, &s, "USD", true, true),
+                section_with(id, &s, "USD", true, false),
+                "{id}"
+            );
+        }
+    }
+
     /// INVARIANT 6: the projects section tells books that declared
     /// document_line_projects to tag an invoice's or bill's lines, and the
     /// rest that it waits for their format upgrade; no other section

crates/ledger-mcp/src/server.rs

@@ -601,6 +601,15 @@ impl BooksServer {
         })
     }
 
+    /// Whether the books declared the journal feature `documents_v2` (the
+    /// handbook's invoices-and-bills section says what waits for it).
+    fn documents_v2(&self) -> bool {
+        self.lock().is_ok_and(|s| {
+            s.journal_format()
+                .has_feature(ledger_store::format::DOCUMENTS_V2)
+        })
+    }
+
     /// The books' base currency code, e.g. "USD".
     fn currency(&self) -> &str {
         self.store.currency.code()
@@ -1519,11 +1528,12 @@ impl BooksServer {
             }
             _ if path.starts_with(&format!("{}/", handbook::URI)) => {
                 let id = &path[handbook::URI.len() + 1..];
-                handbook::section(
+                handbook::section_with(
                     id,
                     &self.settings(),
                     self.currency(),
                     self.document_line_projects(),
+                    self.documents_v2(),
                 )
                 .map(ResourceBody::Text)
                 .ok_or_else(|| format!("unknown handbook section: {id}"))

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

@@ -18,11 +18,13 @@ impl BooksServer {
     ) -> Result<Json<HandbookOut>, String> {
         let settings = self.settings();
         let declared = self.document_line_projects();
+        let documents_v2 = self.documents_v2();
         let sections = handbook::SECTIONS
             .iter()
             .map(|(id, _)| {
                 let text =
-                    handbook::section(id, &settings, self.currency(), declared).unwrap_or_default();
+                    handbook::section_with(id, &settings, self.currency(), declared, documents_v2)
+                        .unwrap_or_default();
                 HandbookSectionOut {
                     id: id.to_string(),
                     title: handbook::title(&text).to_string(),
@@ -34,7 +36,7 @@ impl BooksServer {
         let section = match params.0.section.as_deref().map(str::trim) {
             None => None,
             Some(id) => {
-                let text = handbook::section(id, &settings, self.currency(), declared).ok_or_else(|| {
+                let text = handbook::section_with(id, &settings, self.currency(), declared, documents_v2).ok_or_else(|| {
                     let ids: Vec<&str> = handbook::SECTIONS.iter().map(|(id, _)| *id).collect();
                     format!(
                         "no handbook section {id:?}: the sections are {}, or \"{}\" for all of them",