docxdriver 0.3.1__tar.gz → 0.3.2__tar.gz

{docxdriver-0.3.1 → docxdriver-0.3.2}/Cargo.lock

@@ -416,7 +416,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-cli"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "clap",
  "docxdriver-core",
@@ -427,7 +427,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-core"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "hex",
  "latex2mathml",
@@ -444,7 +444,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-mcp"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "axum",
  "cap-std",
@@ -462,7 +462,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-python"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "docxdriver-core",
  "pyo3",
@@ -471,7 +471,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-wasm"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "docxdriver-core",
  "js-sys",

{docxdriver-0.3.1 → docxdriver-0.3.2}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/docxdriver-python"]
 
 [workspace.package]
-version = "0.3.1"
+version = "0.3.2"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/jhnoel/docxdriver"

{docxdriver-0.3.1 → docxdriver-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docxdriver
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python SDK for the native Rust DOCX engine
 License-Expression: MIT
 Requires-Python: >=3.10

docxdriver-0.3.2/crates/docxdriver-core/examples/list_scaling.rs

@@ -0,0 +1,71 @@
+//! List definition scaling probe: `cargo run --release -p docxdriver-core --example list_scaling -- PARAS OPS`.
+use std::io::Write;
+use std::time::Instant;
+
+use docxdriver_core::{
+    execute_plan, ChangeMode, EditOp, ParagraphAddress, Plan, PlanRequest, PlanResult, SourceHash,
+};
+
+fn package(body: &str) -> Vec<u8> {
+    let mut w = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
+    let o = zip::write::SimpleFileOptions::default();
+    let parts = [
+        ("[Content_Types].xml", "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Types xmlns=\"http://schemas.openxmlformats.org/package/2006/content-types\"><Default Extension=\"rels\" ContentType=\"application/vnd.openxmlformats-package.relationships+xml\"/><Default Extension=\"xml\" ContentType=\"application/xml\"/><Override PartName=\"/word/document.xml\" ContentType=\"application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml\"/></Types>".to_string()),
+        ("_rels/.rels", "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"><Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument\" Target=\"word/document.xml\"/></Relationships>".to_string()),
+        ("word/document.xml", body.to_string()),
+        ("word/_rels/document.xml.rels", "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\"></Relationships>".to_string()),
+    ];
+    for (n, c) in parts {
+        w.start_file(n, o).unwrap();
+        w.write_all(c.as_bytes()).unwrap();
+    }
+    w.finish().unwrap().into_inner()
+}
+
+fn main() {
+    let args: Vec<usize> = std::env::args()
+        .skip(1)
+        .map(|a| a.parse().unwrap())
+        .collect();
+    let (paras, ops) = (
+        args.first().copied().unwrap_or(1500),
+        args.get(1).copied().unwrap_or(300),
+    );
+    let body: String = (0..paras)
+        .map(|i| format!("<w:p w14:paraId=\"{:08X}\"><w:r><w:t>Paragraph {i} says the tenant shall pay rent within thirty days of notice.</w:t></w:r></w:p>", i + 1))
+        .collect();
+    let bytes = package(&format!("<?xml version=\"1.0\" encoding=\"UTF-8\"?><w:document xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" xmlns:w14=\"http://schemas.microsoft.com/office/word/2010/wordml\"><w:body>{body}</w:body></w:document>"));
+    let operations = (0..ops)
+        .map(|i| EditOp::SetList {
+            at: vec![ParagraphAddress::id(format!(
+                "{:08X}",
+                (i * paras / ops) + 1
+            ))],
+            num_id: None,
+            format: Some("decimal".into()),
+            level: 0,
+            start: None,
+            remove: false,
+            levels: None,
+        })
+        .collect();
+    let plan = Plan {
+        base: SourceHash::from_bytes(&bytes),
+        author: "bench".into(),
+        change_mode: ChangeMode::Track,
+        ops: operations,
+    };
+    let t = Instant::now();
+    let result = execute_plan(
+        &bytes,
+        &PlanRequest {
+            plan,
+            preview_key: None,
+        },
+    );
+    let ok = matches!(result, PlanResult::Previewed { .. });
+    println!(
+        "paras={paras} ops={ops} previewed={ok} elapsed={:?}",
+        t.elapsed()
+    );
+}

{docxdriver-0.3.1 → docxdriver-0.3.2}/crates/docxdriver-core/src/commands/typed.rs

@@ -26,6 +26,9 @@ use super::layout::{
 };
 use super::ExecCtx;
 
+/// Internal engine policy; intentionally absent from the public plan schema.
+const WORD_LEVEL_REDLINES: bool = true;
+
 struct SelectionProjection {
     current: String,
     to_all: Vec<usize>,
@@ -451,6 +454,7 @@ pub fn replace_text_typed(
         (&pieces, link_href),
         &input.author,
         input.tracked,
+        WORD_LEVEL_REDLINES,
         ctx,
     )?;
 
@@ -467,6 +471,190 @@ pub fn replace_text_typed(
     Ok((summary, result))
 }
 
+/// Split words, whitespace runs, and individual punctuation characters. Offsets
+/// are Unicode scalar offsets, matching the document segment engine.
+fn diff_tokens(text: &str) -> (Vec<String>, Vec<usize>) {
+    let mut tokens = Vec::<String>::new();
+    let mut offsets = vec![0];
+    let mut previous = None;
+    for (index, ch) in text.chars().enumerate() {
+        let kind = if ch.is_alphanumeric() || ch == '_' {
+            0
+        } else if ch.is_whitespace() {
+            1
+        } else {
+            2
+        };
+        if previous == Some(kind) && kind != 2 {
+            tokens.last_mut().unwrap().push(ch);
+            *offsets.last_mut().unwrap() = index + 1;
+        } else {
+            tokens.push(ch.to_string());
+            offsets.push(index + 1);
+        }
+        previous = Some(kind);
+    }
+    (tokens, offsets)
+}
+
+/// Unmatched old/new character spans around a deterministic token LCS.
+fn word_diff(old: &str, new: &str) -> Result<Vec<(usize, usize, usize, usize)>, Outcome> {
+    if old == new {
+        return Ok(Vec::new());
+    }
+    let (a, ao) = diff_tokens(old);
+    let (b, bo) = diff_tokens(new);
+    let width = b.len() + 1;
+    let cells = (a.len() + 1)
+        .checked_mul(width)
+        .filter(|&n| n <= 4_000_000)
+        .ok_or_else(|| {
+            Outcome::blocked("word-level diff selection is too large; split it into smaller replacements")
+        })?;
+    let mut lcs = vec![0u32; cells];
+    for i in (0..a.len()).rev() {
+        for j in (0..b.len()).rev() {
+            lcs[i * width + j] = if a[i] == b[j] {
+                1 + lcs[(i + 1) * width + j + 1]
+            } else {
+                lcs[(i + 1) * width + j].max(lcs[i * width + j + 1])
+            };
+        }
+    }
+    let (mut i, mut j, mut ai, mut bj) = (0, 0, 0, 0);
+    let mut spans = Vec::new();
+    while i < a.len() && j < b.len() {
+        if a[i] == b[j] {
+            if ai != i || bj != j {
+                spans.push((ao[ai], ao[i], bo[bj], bo[j]));
+            }
+            i += 1;
+            j += 1;
+            ai = i;
+            bj = j;
+        } else if lcs[(i + 1) * width + j] >= lcs[i * width + j + 1] {
+            i += 1;
+        } else {
+            j += 1;
+        }
+    }
+    if ai != a.len() || bj != b.len() {
+        spans.push((ao[ai], ao[a.len()], bo[bj], bo[b.len()]));
+    }
+    // Separator-only matches are weak anchors: keep a rewritten phrase as
+    // one deletion followed by one insertion rather than alternating revisions
+    // for every word. A retained word always separates independent changes.
+    let chars: Vec<char> = old.chars().collect();
+    let mut grouped: Vec<(usize, usize, usize, usize)> = Vec::new();
+    for span in spans {
+        if let Some(previous) = grouped.last_mut() {
+            if chars[previous.1..span.0].iter().all(|ch| !ch.is_alphanumeric() && *ch != '_') {
+                previous.1 = span.1;
+                previous.3 = span.3;
+                continue;
+            }
+        }
+        grouped.push(span);
+    }
+    Ok(grouped)
+}
+
+// Text diffing is an engine policy, not a public operation or plan option.
+// Rich replacements retain the existing path so requested formatting is applied.
+fn diff_eligible(pieces: &[InsPiece], link: Option<&str>) -> bool {
+    link.is_none() && pieces.iter().all(|piece| matches!(piece, InsPiece::Text(_, fmt) if *fmt == Fmt::default()))
+}
+
+#[allow(clippy::too_many_arguments)]
+fn replace_range_diff(
+    package: &mut Package,
+    xml: &mut DocxXml,
+    paragraph: NodeId,
+    address: &str,
+    (start, end): (usize, usize),
+    pieces: &[InsPiece],
+    link: Option<String>,
+    author: &str,
+    ctx: &ExecCtx,
+) -> Result<(), Outcome> {
+    debug_assert!(diff_eligible(pieces, link.as_deref()));
+    let new: String = pieces.iter().filter_map(|piece| match piece {
+        InsPiece::Text(text, _) => Some(text.as_str()),
+        _ => None,
+    }).collect();
+    let segments = build_segments(xml, paragraph);
+    let covered: Vec<_> = segments
+        .iter()
+        .filter(|s| s.start < end && s.end > start)
+        .collect();
+    if covered.iter().any(|s| s.wrap != RevWrap::None) {
+        return Err(blocked_at(
+            address,
+            "word-level diff selection overlaps existing tracked changes; accept or reject them first",
+        ));
+    }
+    if let (Some(first), Some(last)) = (covered.first(), covered.last()) {
+        if let Some(label) = scan_blockers_between(
+            xml,
+            first.wrapper.unwrap_or(first.run),
+            last.wrapper.unwrap_or(last.run),
+        ) {
+            return Err(blocked_at(
+                address,
+                format!("word-level diff selection crosses a protected {label}"),
+            ));
+        }
+    }
+    let old: String = segments
+        .iter()
+        .flat_map(|s| s.text.chars())
+        .skip(start)
+        .take(end - start)
+        .collect();
+    let changes = match word_diff(&old, &new) {
+        Ok(changes) => changes,
+        Err(_) => return replace_range(package, xml, paragraph, address, (start, end), (pieces, link), author, true, false, ctx),
+    };
+    let chars: Vec<char> = new.chars().collect();
+    for (a, b, c, d) in changes.into_iter().rev() {
+        let replacement: String = chars[c..d].iter().collect();
+        let pieces = if replacement.is_empty() {
+            vec![]
+        } else {
+            vec![InsPiece::Text(replacement, Fmt::default())]
+        };
+        if a == b {
+            split_boundary(xml, paragraph, start + a);
+            let id = xml.next_revision_id();
+            insert_ins_pieces_at(
+                xml,
+                paragraph,
+                start + a,
+                &pieces,
+                id,
+                author,
+                &ctx.now,
+                false,
+            )
+            .map_err(Outcome::error)?;
+        } else {
+            replace_range(
+                package,
+                xml,
+                paragraph,
+                address,
+                (start + a, start + b),
+                (&pieces, None),
+                author,
+                true,
+                false,
+                ctx,
+            )?;
+        }
+    }
+    Ok(())
+}
+
 /// Replace the `[start, end)` range of `paragraph` (all-text offsets, as
 /// returned by [`select_in_paragraph`]) with parsed `with` pieces: a tracked
 /// deletion plus insertion, or a direct rewrite. Offsets to the left of the
@@ -482,8 +670,24 @@ fn replace_range(
     (pieces, link_href): (&[InsPiece], Option<String>),
     author: &str,
     tracked: bool,
+    auto_diff: bool,
     ctx: &ExecCtx,
 ) -> Result<(), Outcome> {
+    if tracked && auto_diff && diff_eligible(pieces, link_href.as_deref())
+        && !build_segments(xml, paragraph).iter().any(|s| s.start < end && s.end > start && s.wrap != RevWrap::None)
+    {
+        return replace_range_diff(
+            package,
+            xml,
+            paragraph,
+            address,
+            (start, end),
+            pieces,
+            link_href,
+            author,
+            ctx,
+        );
+    }
     let address = address.to_string();
     if !tracked {
         let segments = build_segments(xml, paragraph);
@@ -828,6 +1032,7 @@ pub fn revise_text_typed(
             (pieces, link.clone()),
             &args.author,
             args.tracked,
+            WORD_LEVEL_REDLINES,
             ctx,
         )?;
     }
@@ -883,7 +1088,25 @@ pub fn replace_paragraph_typed(
         ));
     }
 
-    if input.tracked {
+    let count = build_segments(xml, paragraph)
+        .iter()
+        .map(|s| s.end)
+        .max()
+        .unwrap_or(0);
+    if input.tracked && WORD_LEVEL_REDLINES && diff_eligible(&pieces, link_href.as_deref()) {
+        replace_range(
+            package,
+            xml,
+            paragraph,
+            &address,
+            (0, count),
+            (&pieces, link_href),
+            &input.author,
+            true,
+            true,
+            ctx,
+        )?;
+    } else if input.tracked {
         let del_id = xml.next_revision_id();
         wrap_all_content_in_del(xml, paragraph, del_id, &input.author, &ctx.now)
             .map_err(Outcome::error)?;

{docxdriver-0.3.1 → docxdriver-0.3.2}/crates/docxdriver-core/tests/typed_api.rs

@@ -2409,3 +2409,91 @@ fn run_properties_are_written_in_sequence_order() {
         .collect();
     assert!(order.is_empty(), "out of CT_RPr sequence order at {order:?}: {rpr}");
 }
+
+fn commit_auto_diff(bytes: &[u8], op: EditOp) -> Vec<u8> {
+    let mut p = plan(bytes, vec![op]);
+    p.change_mode = ChangeMode::Track;
+    let key = match execute_plan(bytes, &PlanRequest { plan: p.clone(), preview_key: None }) {
+        PlanResult::Previewed { preview_key, .. } => preview_key,
+        other => panic!("auto_diff review failed: {other:?}"),
+    };
+    match execute_plan(bytes, &PlanRequest { plan: p, preview_key: Some(key) }) {
+        PlanResult::Committed { bytes, .. } => bytes,
+        other => panic!("auto_diff commit failed: {other:?}"),
+    }
+}
+
+#[test]
+fn auto_diff_tracks_only_changed_words_and_roundtrips_both_views() {
+    for (old, new) in [
+        ("Payment is due within thirty days.", "Payment is due within sixty days."),
+        ("one two three four five", "one TWO three FOUR five"),
+        ("hello world", "hello brave world"),
+        ("hello brave world", "hello world"),
+        ("hello", "hello!"),
+        ("hello!", "hello"),
+        ("café naïve résumé", "café wise résumé"),
+        ("a a b a", "a b a a"),
+        ("one  two", "one two"),
+        ("same words", "same words"),
+        ("delete everything", ""),
+        ("", "new text"),
+    ] {
+        for op in [
+            EditOp::ReplaceParagraph { at: ParagraphAddress::id(SOURCE_ID), with: new.into() },
+            revise(Some(SOURCE_ID), None, vec![edit(old, new)]),
+            EditOp::ReplaceText { at: ParagraphAddress::id(SOURCE_ID), select: old.into(), with: new.into(), occurrence: None },
+        ].into_iter().take(if old.is_empty() { 1 } else { 3 }) {
+            let source = document(&[(SOURCE_ID, old)]);
+            let changed = commit_auto_diff(&source, op);
+            for (action, expected) in [(RevisionAction::Accept, new), (RevisionAction::Reject, old)] {
+                let settled = commit_plan(&changed, vec![EditOp::RevisionSettle { target: RevisionTarget::All, action }]);
+                let text = read_markup_view(&settled, Some("final"));
+                let text: String = text.split('<').map(|s| s.split_once('>').map_or(s, |(_, t)| t)).collect();
+                assert_eq!(text.trim(), expected, "{old:?} -> {new:?}");
+            }
+            let xml = document_xml(&changed);
+            if old == new { assert!(!xml.contains("<w:ins") && !xml.contains("<w:del")); }
+            if old.contains("thirty") {
+                assert_eq!(xml.matches("<w:ins ").count(), 1);
+                assert_eq!(xml.matches("<w:del ").count(), 1);
+                assert!(xml.contains(">thirty</w:delText>"), "{xml}");
+                assert!(xml.contains(">sixty</w:t>"), "{xml}");
+            }
+        }
+    }
+}
+
+#[test]
+fn auto_diff_preserves_unchanged_run_formatting_and_supports_rich_replacements() {
+    let source = document(&[(SOURCE_ID, "The bold word stays old.")]);
+    let source = commit_plan(&source, vec![serde_json::from_value(serde_json::json!({
+        "op":"format_text", "at":SOURCE_ID,"select":"bold", "bold":true
+    })).unwrap()]);
+    let changed = commit_auto_diff(&source, EditOp::ReplaceParagraph {
+        at: ParagraphAddress::id(SOURCE_ID), with: "The bold word stays new.".into(),
+    });
+    let xml = document_xml(&changed);
+    assert!(xml.contains("<w:b"));
+    assert!(xml.contains(">bold</w:t>"));
+    let text = revise_final(&source, ChangeMode::Track, vec![revise(Some(SOURCE_ID), None, vec![edit("old.", "<b>new.</b>")])]).unwrap();
+    assert!(text.contains("stays new."), "{text}");
+}
+
+#[test]
+fn auto_diff_groups_rewritten_phrases_but_keeps_unchanged_words() {
+    for (old, new, groups) in [
+        ("old red car", "new blue truck", 1),
+        ("old, red car", "new, blue truck", 1),
+        ("old red car stays here", "new blue truck stays there", 2),
+    ] {
+        let source = document(&[(SOURCE_ID, old)]);
+        let output = commit_auto_diff(&source, EditOp::ReplaceParagraph {
+            at: ParagraphAddress::id(SOURCE_ID), with: new.into(),
+        });
+        let xml = document_xml(&output);
+        // Each contiguous changed phrase has at most one revision of each type.
+        assert_eq!(xml.matches("<w:del ").count(), groups, "{xml}");
+        assert_eq!(xml.matches("<w:ins ").count(), groups, "{xml}");
+    }
+}

{docxdriver-0.3.1 → docxdriver-0.3.2}/crates/docxdriver-python/python/docxdriver/repl/prelude.py

@@ -1,3 +1,3 @@
 # Generated by scripts/generate-docxdriver-repl-prelude.py; edit the shared Pi templates.
 PRELUDE = "from dataclasses import dataclass\n\n@dataclass\nclass QuoteResult:\n    text: str\n    provenance: dict\n\n@dataclass\nclass TermResult:\n    text: str\n    provenance: dict\n\nclass Term:\n\n    def __init__(self, text: str, style: str='double'):\n        self.text = text\n        self.style = style\n\n    def to_dict(self):\n        return {'$kind': 'term', 'text': self.text, 'style': self.style}\n\n@dataclass\nclass InlineResult:\n    text: str\n    audit: dict\n\nclass Inline:\n\n    def __init__(self, parts: list):\n        self.parts = parts\n\n    def to_dict(self):\n        return {'$kind': 'inline', 'parts': [part.to_dict() if hasattr(part, 'to_dict') else part for part in self.parts]}\n\nclass Quote:\n\n    def __init__(self, source: str, at: str, select: str, occurrence: int=1, style: str='double'):\n        self.source = source\n        self.at = at\n        self.select = select\n        self.occurrence = occurrence\n        self.style = style\n        self.changes = []\n\n    def omit(self, select: str, occurrence: int=1, marker: str='…'):\n        self.changes.append({'kind': 'omit', 'select': select, 'occurrence': occurrence, 'marker': marker})\n        return self\n\n    def bracket(self, select: str, replacement: str, occurrence: int=1):\n        self.changes.append({'kind': 'bracket', 'select': select, 'replacement': replacement, 'occurrence': occurrence})\n        return self\n\n    def to_dict(self):\n        return {'$kind': 'quote', 'source': self.source, 'at': self.at, 'select': self.select, 'occurrence': self.occurrence, 'style': self.style, 'changes': self.changes}\n\nasync def quote_find(source: str, query: str, ignore_case: bool=False) -> list:\n    return await _quote_find(source, query, ignore_case)\n\nasync def quote_validate(quote: Quote) -> QuoteResult:\n    result = await _quote_validate(quote.to_dict())\n    return QuoteResult(text=result['text'], provenance=result)\n\nasync def quote_lint(text: str, severity: str='error') -> list:\n    return await _quote_lint(text, severity)\n\nasync def term_render(term: Term) -> TermResult:\n    result = await _term_render(term.to_dict())\n    return TermResult(text=result['text'], provenance=result)\n\nasync def inline_validate(inline: Inline, policy: str='error') -> InlineResult:\n    result = await _inline_validate(inline.to_dict(), policy)\n    return InlineResult(text=result['text'], audit=result['audit'])\nfrom dataclasses import dataclass\nimport re\n\n@dataclass\nclass ClearFooter:\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'clear_footer'}\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass ClearHeader:\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'clear_header'}\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass CommentAdd:\n    at: str\n    text: str\n    occurrence: int | None = None\n    select: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'comment_add'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.text is not None:\n            value['text'] = self.text\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.select is not None:\n            value['select'] = self.select\n        return value\n\n@dataclass\nclass CommentDelete:\n    comment_id: str\n\n    def to_dict(self):\n        value = {'op': 'comment_delete'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        return value\n\n@dataclass\nclass CommentReply:\n    comment_id: str\n    text: str\n\n    def to_dict(self):\n        value = {'op': 'comment_reply'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        if self.text is not None:\n            value['text'] = self.text\n        return value\n\n@dataclass\nclass CommentSetStatus:\n    comment_id: str\n    status: str\n\n    def to_dict(self):\n        value = {'op': 'comment_set_status'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        if self.status is not None:\n            value['status'] = self.status\n        return value\n\n@dataclass\nclass DeleteEquation:\n    at: str\n    equation: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'delete_equation'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.equation is not None:\n            value['equation'] = self.equation\n        return value\n\n@dataclass\nclass DeleteParagraphs:\n    at: list\n\n    def to_dict(self):\n        value = {'op': 'delete_paragraphs'}\n        if self.at is not None:\n            value['at'] = self.at\n        return value\n\n@dataclass\nclass EditTable:\n    action: dict\n    at: str\n\n    def to_dict(self):\n        value = {'op': 'edit_table'}\n        if self.action is not None:\n            value['action'] = self.action\n        if self.at is not None:\n            value['at'] = self.at\n        return value\n\n@dataclass\nclass FormatParagraph:\n    at: str\n    alignment: str | None = None\n    clear: list | None = None\n    first_line_indent: float | None = None\n    indent_left: float | None = None\n    indent_right: float | None = None\n    line_spacing: dict | None = None\n    space_after: float | None = None\n    space_before: float | None = None\n    style: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'format_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.alignment is not None:\n            value['alignment'] = self.alignment\n        if self.clear is not None:\n            value['clear'] = self.clear\n        if self.first_line_indent is not None:\n            value['first_line_indent'] = self.first_line_indent\n        if self.indent_left is not None:\n            value['indent_left'] = self.indent_left\n        if self.indent_right is not None:\n            value['indent_right'] = self.indent_right\n        if self.line_spacing is not None:\n            value['line_spacing'] = self.line_spacing\n        if self.space_after is not None:\n            value['space_after'] = self.space_after\n        if self.space_before is not None:\n            value['space_before'] = self.space_before\n        if self.style is not None:\n            value['style'] = self.style\n        return value\n\n@dataclass\nclass FormatText:\n    at: str\n    select: str\n    bold: bool | None = None\n    clear: list | None = None\n    color: str | None = None\n    font_size: float | None = None\n    highlight: str | None = None\n    italic: bool | None = None\n    occurrence: int | None = None\n    strike: bool | None = None\n    subscript: bool | None = None\n    superscript: bool | None = None\n    underline: bool | None = None\n\n    def to_dict(self):\n        value = {'op': 'format_text'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.select is not None:\n            value['select'] = self.select\n        if self.bold is not None:\n            value['bold'] = self.bold\n        if self.clear is not None:\n            value['clear'] = self.clear\n        if self.color is not None:\n            value['color'] = self.color\n        if self.font_size is not None:\n            value['font_size'] = self.font_size\n        if self.highlight is not None:\n            value['highlight'] = self.highlight\n        if self.italic is not None:\n            value['italic'] = self.italic\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.strike is not None:\n            value['strike'] = self.strike\n        if self.subscript is not None:\n            value['subscript'] = self.subscript\n        if self.superscript is not None:\n            value['superscript'] = self.superscript\n        if self.underline is not None:\n            value['underline'] = self.underline\n        return value\n\n@dataclass\nclass InsertParagraph:\n    at: str\n    position: str\n    as_: str | None = None\n    style: str | None = None\n    with_: str | Inline | Quote | Term | None = None\n\n    def to_dict(self):\n        value = {'op': 'insert_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.position is not None:\n            value['position'] = self.position\n        if self.as_ is not None:\n            value['as'] = self.as_\n        if self.style is not None:\n            value['style'] = self.style\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        return value\n\n@dataclass\nclass InsertTable:\n    at: str\n    columns: int\n    position: str\n    rows: int\n    as_: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'insert_table'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.columns is not None:\n            value['columns'] = self.columns\n        if self.position is not None:\n            value['position'] = self.position\n        if self.rows is not None:\n            value['rows'] = self.rows\n        if self.as_ is not None:\n            value['as'] = self.as_\n        return value\n\n@dataclass\nclass ReplaceEquation:\n    at: str\n    mathml: str\n    display: bool | None = None\n    equation: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'replace_equation'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.mathml is not None:\n            value['mathml'] = self.mathml\n        if self.display is not None:\n            value['display'] = self.display\n        if self.equation is not None:\n            value['equation'] = self.equation\n        return value\n\n@dataclass\nclass ReplaceParagraph:\n    at: str\n    with_: str | Inline | Quote | Term\n\n    def to_dict(self):\n        value = {'op': 'replace_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        return value\n\n@dataclass\nclass ReplaceText:\n    at: str\n    select: str\n    with_: str | Inline | Quote | Term\n    occurrence: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'replace_text'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.select is not None:\n            value['select'] = self.select\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        return value\n\n@dataclass\nclass ReviseText:\n    edits: list\n    at: str | None = None\n    occurrence: int | None = None\n    within: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'revise_text'}\n        if self.edits is not None:\n            value['edits'] = self.edits\n        if self.at is not None:\n            value['at'] = self.at\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.within is not None:\n            value['within'] = self.within\n        return value\n\n@dataclass\nclass RevisionSettle:\n    action: str\n    target: str\n\n    def to_dict(self):\n        value = {'op': 'revision_settle'}\n        if self.action is not None:\n            value['action'] = self.action\n        if self.target is not None:\n            value['target'] = self.target\n        return value\n\n@dataclass\nclass SetEvenAndOddHeaders:\n    even_and_odd: bool\n\n    def to_dict(self):\n        value = {'op': 'set_even_and_odd_headers'}\n        if self.even_and_odd is not None:\n            value['even_and_odd'] = self.even_and_odd\n        return value\n\n@dataclass\nclass SetFirstPageMode:\n    enabled: bool\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_first_page_mode'}\n        if self.enabled is not None:\n            value['enabled'] = self.enabled\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetFooter:\n    with_: str | Inline | Quote | Term\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_footer'}\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetHeader:\n    with_: str | Inline | Quote | Term\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_header'}\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetList:\n    at: list\n    format: str | None = None\n    level: int | None = None\n    levels: list | None = None\n    num_id: int | None = None\n    remove: bool | None = None\n    start: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_list'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.format is not None:\n            value['format'] = self.format\n        if self.level is not None:\n            value['level'] = self.level\n        if self.levels is not None:\n            value['levels'] = self.levels\n        if self.num_id is not None:\n            value['num_id'] = self.num_id\n        if self.remove is not None:\n            value['remove'] = self.remove\n        if self.start is not None:\n            value['start'] = self.start\n        return value\n\n@dataclass\nclass SetPageMargins:\n    bottom: float | None = None\n    footer: float | None = None\n    gutter: float | None = None\n    header: float | None = None\n    left: float | None = None\n    right: float | None = None\n    section: int | None = None\n    top: float | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_page_margins'}\n        if self.bottom is not None:\n            value['bottom'] = self.bottom\n        if self.footer is not None:\n            value['footer'] = self.footer\n        if self.gutter is not None:\n            value['gutter'] = self.gutter\n        if self.header is not None:\n            value['header'] = self.header\n        if self.left is not None:\n            value['left'] = self.left\n        if self.right is not None:\n            value['right'] = self.right\n        if self.section is not None:\n            value['section'] = self.section\n        if self.top is not None:\n            value['top'] = self.top\n        return value\n\n@dataclass\nclass SetSectionLayout:\n    break_type: str | None = None\n    column_separator: bool | None = None\n    column_spacing: float | None = None\n    column_widths: list | None = None\n    columns: int | None = None\n    height: float | None = None\n    orientation: str | None = None\n    page_number_continue: bool | None = None\n    page_number_format: str | None = None\n    page_number_start: int | None = None\n    page_size: str | None = None\n    section: int | None = None\n    width: float | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_section_layout'}\n        if self.break_type is not None:\n            value['break_type'] = self.break_type\n        if self.column_separator is not None:\n            value['column_separator'] = self.column_separator\n        if self.column_spacing is not None:\n            value['column_spacing'] = self.column_spacing\n        if self.column_widths is not None:\n            value['column_widths'] = self.column_widths\n        if self.columns is not None:\n            value['columns'] = self.columns\n        if self.height is not None:\n            value['height'] = self.height\n        if self.orientation is not None:\n            value['orientation'] = self.orientation\n        if self.page_number_continue is not None:\n            value['page_number_continue'] = self.page_number_continue\n        if self.page_number_format is not None:\n            value['page_number_format'] = self.page_number_format\n        if self.page_number_start is not None:\n            value['page_number_start'] = self.page_number_start\n        if self.page_size is not None:\n            value['page_size'] = self.page_size\n        if self.section is not None:\n            value['section'] = self.section\n        if self.width is not None:\n            value['width'] = self.width\n        return value\n\n@dataclass\nclass Revise:\n    within: str | None = None\n    at: str | None = None\n    occurrence: int | None = None\n    edits: list = None\n\n    def replace(self, select: str, with_, occurrence: int | None=None, all: bool=False):\n        edit = {'select': select, 'with': with_.to_dict() if hasattr(with_, 'to_dict') else with_}\n        if occurrence is not None:\n            edit['occurrence'] = occurrence\n        if all:\n            edit['all'] = True\n        self.edits = (self.edits or []) + [edit]\n        return self\n\n    def to_dict(self):\n        return ReviseText(edits=self.edits or [], at=self.at, occurrence=self.occurrence, within=self.within).to_dict()\n\ndef AcceptRevision(target: str) -> RevisionSettle:\n    return RevisionSettle(action='accept', target=str(target))\n\ndef RejectRevision(target: str) -> RevisionSettle:\n    return RevisionSettle(action='reject', target=str(target))\n\n@dataclass\nclass ReviewResult:\n    commit_key: str\n    edits: list\n\n@dataclass\nclass ReadResult:\n    markup: str\n    equations: list = None\n    selection_space: dict = None\n    selections: dict = None\n    comments: list = None\n    assets: list = None\n    comments_error: str = None\n    styles: dict = None\n    css: dict = None\n\n    def __repr__(self):\n        return 'ReadResult(markup=' + repr(self.markup) + ', styles=' + str(len(self.styles or {})) + ' definitions, css=' + str(len(self.css or {})) + ' rules; inspect .styles and .css, equations=' + repr(self.equations) + ', selection_space=' + repr(self.selection_space) + ', selections=' + repr(self.selections) + ', comments=' + repr(self.comments) + ', assets=' + repr(self.assets) + ', comments_error=' + repr(self.comments_error) + ')'\n\n@dataclass\nclass Plan:\n    author: str = 'docxdriver'\n    change_mode: str = 'track'\n    operations: list = None\n\n    def to_dict(self):\n        ops = self.operations if self.operations is not None else []\n        return {'author': self.author, 'change_mode': self.change_mode, 'ops': [op.to_dict() if hasattr(op, 'to_dict') else op for op in ops]}\n\nasync def docx_create(path: str, html: str):\n    return await _docx_create(path, html)\n\nasync def docx_read(path: str, view: str='markup', kind: str='document'):\n    _listing_kinds = ('comments', 'styles', 'revisions', 'assets')\n    if kind == 'document' and view in _listing_kinds:\n        kind = view\n    if kind in _listing_kinds:\n        return await _docx_read(path, view, kind)\n    if kind != 'document':\n        raise ValueError('kind must be one of document, comments, styles, revisions, assets')\n    result = await _docx_read(path, view)\n    return ReadResult(markup=result['markup'], styles=result.get('styles', {}), css=result.get('css', {}), equations=result.get('equations', []), selection_space=result.get('selection_space'), selections=result.get('selections'), comments=result.get('comments', []), assets=result.get('assets', []), comments_error=result.get('comments_error'))\n\nasync def docx_find(path: str, query: str, ignore_case: bool=False) -> list:\n    return await _docx_find(path, query, ignore_case)\n\nasync def docx_help(topic: str | None=None) -> str:\n    return await _docx_help(topic)\n\nasync def docx_review(path: str, plan: Plan) -> ReviewResult | None:\n    result = await _docx_review(path, {'plan': plan.to_dict()})\n    if result is None:\n        return None\n    return ReviewResult(commit_key=result['commit_key'], edits=result['edits'])\n\nasync def docx_commit(commit_key: str):\n    await _docx_commit(commit_key)\n    return None"
-REFERENCE = '\n# docxdriver Python REPL API — Version 1 (Python-authored plan)\n\n# BEGIN GENERATED OPERATION DOCS\n## Operations\n\nSelected from the core schema (`$defs.editOp.oneOf`) through the\ncapability manifest; field shapes, types, and enums are exactly the\nchecked-in schema’s. Every op dataclass has `to_dict()`, omitting\noptional fields whose value is `None`; constructors use `with_`/`as_`\nfor Python keyword collisions and `to_dict()` maps back to the schema\nfield names. Operations are addressed by the paragraph `id` attribute\nfrom `docx_read` (uppercase eight-digit hex) or a `$name` alias.\n\n### ClearFooter\n\n`ClearFooter(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit footer reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### ClearHeader\n\n`ClearHeader(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit header reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### CommentAdd\n\n`CommentAdd(at: str, text: str, occurrence: int | None = None, select: str | None = None)`\n\nAnchor a comment with `text` to the paragraph at `at`; omit `select` to comment the whole paragraph, or pass `select`/`occurrence` (1-based) to pin one exact span.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `text` | `str` | yes |\n| `occurrence` | `int | None` | no |\n| `select` | `str | None` | no |\n\n### CommentDelete\n\n`CommentDelete(comment_id: str)`\n\nDelete a comment by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n\n### CommentReply\n\n`CommentReply(comment_id: str, text: str)`\n\nReply to an existing comment; `comment_id` is the decimal id from a prior `comment_add` or a comments-kind read.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `text` | `str` | yes |\n\n### CommentSetStatus\n\n`CommentSetStatus(comment_id: str, status: str)`\n\nSet a comment\'s status to `open` or `resolved` by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `status` | `str` | yes |\n\n### DeleteEquation\n\n`DeleteEquation(at: str, equation: int | None = None)`\n\nDelete a current equation while preserving the paragraph. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Tracked mode keeps the equation recoverable until the deletion is accepted.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `equation` | `int | None` | no |\n\n### DeleteParagraphs\n\n`DeleteParagraphs(at: list)`\n\nDelete the paragraphs listed in `at` (tracked deletion by default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n\n### EditTable\n\n`EditTable(action: dict, at: str)`\n\nDirect structural table edits using a source-bound table handle. action.kind is insert_rows/delete_rows/insert_columns/delete_columns/merge_cells/split_cell/delete; coordinates and counts are one-based. Insert/delete grid operations and merge require an unmerged rectangular grid. Split keeps content in the first resulting cell; merge concatenates content in row-major order. Rejects tracked mode and tables containing unresolved revisions, bookmarks, comments, fields or content controls. Delete the table instead of its final row or column.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `dict` | yes |\n| `at` | `str` | yes |\n\n### FormatParagraph\n\n`FormatParagraph(at: str, alignment: str | None = None, clear: list | None = None, first_line_indent: float | None = None, indent_left: float | None = None, indent_right: float | None = None, line_spacing: dict | None = None, space_after: float | None = None, space_before: float | None = None, style: str | None = None)`\n\nApply paragraph formatting to the paragraph at `at`: `style`, `alignment` (left/center/right/justify), signed `indent_left`/`indent_right`, signed `first_line_indent` (negative for hanging, zero for an explicit zero offset), `space_before`/`space_after`, `line_spacing` (dict with `mode` multiple/exact/at_least and `value`), or `clear`. Omitted properties are untouched; clear removes direct settings and inherits styles/defaults, winning over set. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `alignment` | `str | None` | no |\n| `clear` | `list | None` | no |\n| `first_line_indent` | `float | None` | no |\n| `indent_left` | `float | None` | no |\n| `indent_right` | `float | None` | no |\n| `line_spacing` | `dict | None` | no |\n| `space_after` | `float | None` | no |\n| `space_before` | `float | None` | no |\n| `style` | `str | None` | no |\n\n### FormatText\n\n`FormatText(at: str, select: str, bold: bool | None = None, clear: list | None = None, color: str | None = None, font_size: float | None = None, highlight: str | None = None, italic: bool | None = None, occurrence: int | None = None, strike: bool | None = None, subscript: bool | None = None, superscript: bool | None = None, underline: bool | None = None)`\n\nApply character formatting to an exact occurrence of `select` in the paragraph at `at`: boolean attributes (`bold`, `italic`, `underline`, `strike`, `superscript`, `subscript`), `color` (#RRGGBB), `highlight` (Word palette including none), `font_size` (points), `occurrence`, or `clear`. Omitted properties preserve source OOXML; false explicitly overrides inherited formatting (baseline for superscript/subscript). Clear removes the direct property and inherits styles/defaults, winning over set; superscript/subscript share one property. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `bold` | `bool | None` | no |\n| `clear` | `list | None` | no |\n| `color` | `str | None` | no |\n| `font_size` | `float | None` | no |\n| `highlight` | `str | None` | no |\n| `italic` | `bool | None` | no |\n| `occurrence` | `int | None` | no |\n| `strike` | `bool | None` | no |\n| `subscript` | `bool | None` | no |\n| `superscript` | `bool | None` | no |\n| `underline` | `bool | None` | no |\n\n### InsertParagraph\n\n`InsertParagraph(at: str, position: str, as_: str | None = None, style: str | None = None, with_: str | Inline | Quote | Term | None = None)`\n\nInsert a new paragraph before or after an anchor: paragraph id/alias (`at`) or body-level table number (`table:N` from markup); `with` is its text, `style` its style, and `as` names the new paragraph id (a `$name` alias).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `position` | `str` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n| `style` | `str | None` | no |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term | None` | no |\n\n### InsertTable\n\n`InsertTable(at: str, columns: int, position: str, rows: int, as_: str | None = None)`\n\nInsert a rectangular table before/after paragraph at, with rows and columns in 1..100. Direct mode only. Optional as creates a plan-local table alias for later formatting and structural edits.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `columns` | `int` | yes |\n| `position` | `str` | yes |\n| `rows` | `int` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n\n### ReplaceEquation\n\n`ReplaceEquation(at: str, mathml: str, display: bool | None = None, equation: int | None = None)`\n\nReplace a current equation using presentation MathML. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Display mode is preserved by default. Settle existing revisions before editing their equations.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `mathml` | `str` | yes |\n| `display` | `bool | None` | no |\n| `equation` | `int | None` | no |\n\n### ReplaceParagraph\n\n`ReplaceParagraph(at: str, with_: str | Inline | Quote | Term)`\n\nReplace the entire paragraph at `at` with `with`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n\n### ReplaceText\n\n`ReplaceText(at: str, select: str, with_: str | Inline | Quote | Term, occurrence: int | None = None)`\n\nReplace an exact occurrence of `select` in the paragraph at `at` with `with`; `occurrence` picks the nth match (1-based).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `occurrence` | `int | None` | no |\n\n### ReviseText\n\n`ReviseText(edits: list, at: str | None = None, occurrence: int | None = None, within: str | None = None)`\n\nSeveral exact replacements inside one bounded scope; prefer the chainable `Revise(within, at=None, occurrence=None).replace(select, with_, occurrence=None, all=False)` builder. Scope: `within` (a phrase unique in paragraph `at`, or in the whole document when `at` is omitted; `occurrence` picks a repeated one), else the paragraph `at`, else the whole document. Each edit must match exactly once in the scope unless it sets `occurrence` or `all`. All edits resolve against the scope as it stands when the operation starts, must not overlap, and become separate minimal tracked changes.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `edits` | `list` | yes |\n| `at` | `str | None` | no |\n| `occurrence` | `int | None` | no |\n| `within` | `str | None` | no |\n\n### RevisionSettle\n\n`RevisionSettle(action: str, target: str)`\n\nAccept or reject tracked changes: `target` is a decimal revision id from `await docx_read(path, kind="revisions")` or `all`; `action` is `accept` or `reject`. Prefer the `AcceptRevision(target)` / `RejectRevision(target)` shorthands. Settling `all` also settles tracked changes made by earlier operations in the same plan, and later selectors address the settled text.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `str` | yes |\n| `target` | `str` | yes |\n\n### SetEvenAndOddHeaders\n\n`SetEvenAndOddHeaders(even_and_odd: bool)`\n\nEnable or disable distinct even-page headers/footers (`even_and_odd`); when true, `kind="even"` chrome applies to even pages.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `even_and_odd` | `bool` | yes |\n\n### SetFirstPageMode\n\n`SetFirstPageMode(enabled: bool, section: int | None = None)`\n\nEnable/disable first-page stories in a section (default 1) without removing stored stories. Tracked mode records a section-property snapshot; settle pending section changes before editing again.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `enabled` | `bool` | yes |\n| `section` | `int | None` | no |\n\n### SetFooter\n\n`SetFooter(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section footer chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetHeader\n\n`SetHeader(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section header chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetList\n\n`SetList(at: list, format: str | None = None, level: int | None = None, levels: list | None = None, num_id: int | None = None, remove: bool | None = None, start: int | None = None)`\n\nAssign explicitly selected paragraphs to a new list (format defaults to decimal), continue an existing num_id, or remove membership with remove=True. level is 0..8; start is positive and creates an isolated restarted instance. Optional levels defines 1..9 per-level format/label/start/restart_after, signed indent_left/indent_right/first_line_indent and marker_bold/marker_italic/marker_font/marker_color for a new list. Label placeholders reference this or ancestor levels (%1..%9). Existing definitions are never restyled. Membership changes are tracked; settle pending paragraph changes first. Definitions remain after rejection for safe reference restoration.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n| `format` | `str | None` | no |\n| `level` | `int | None` | no |\n| `levels` | `list | None` | no |\n| `num_id` | `int | None` | no |\n| `remove` | `bool | None` | no |\n| `start` | `int | None` | no |\n\n### SetPageMargins\n\n`SetPageMargins(bottom: float | None = None, footer: float | None = None, gutter: float | None = None, header: float | None = None, left: float | None = None, right: float | None = None, section: int | None = None, top: float | None = None)`\n\nSet selected nonnegative page margins in points for a section (default 1): top/right/bottom/left/header/footer/gutter. Omitted values are preserved. Like existing header/footer setters, margin changes are direct even in tracked plans.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `bottom` | `float | None` | no |\n| `footer` | `float | None` | no |\n| `gutter` | `float | None` | no |\n| `header` | `float | None` | no |\n| `left` | `float | None` | no |\n| `right` | `float | None` | no |\n| `section` | `int | None` | no |\n| `top` | `float | None` | no |\n\n### SetSectionLayout\n\n`SetSectionLayout(break_type: str | None = None, column_separator: bool | None = None, column_spacing: float | None = None, column_widths: list | None = None, columns: int | None = None, height: float | None = None, orientation: str | None = None, page_number_continue: bool | None = None, page_number_format: str | None = None, page_number_start: int | None = None, page_size: str | None = None, section: int | None = None, width: float | None = None)`\n\nSelectively set section layout (section defaults to 1): page_size letter/legal/a4/a3/a5 or paired width/height in points; orientation portrait/landscape normalizes dimensions. Columns 1..45 with column_spacing, column_widths and column_separator; break_type nextPage/continuous/oddPage/evenPage/nextColumn; page_number_format, page_number_start or page_number_continue=true. Omission preserves properties; tracking snapshots section properties while preserving story relationships. Pending property changes must be settled first.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `break_type` | `str | None` | no |\n| `column_separator` | `bool | None` | no |\n| `column_spacing` | `float | None` | no |\n| `column_widths` | `list | None` | no |\n| `columns` | `int | None` | no |\n| `height` | `float | None` | no |\n| `orientation` | `str | None` | no |\n| `page_number_continue` | `bool | None` | no |\n| `page_number_format` | `str | None` | no |\n| `page_number_start` | `int | None` | no |\n| `page_size` | `str | None` | no |\n| `section` | `int | None` | no |\n| `width` | `float | None` | no |\n\n# END GENERATED OPERATION DOCS\n\n## Scoped revisions\n\n`Revise(within=None, at=None, occurrence=None)` builds one `ReviseText`\noperation; chain `.replace(select, with_, occurrence=None, all=False)` for each\nchange. The scope bounds every `select`, so short selectors stay unambiguous\nin long documents and each change becomes a minimal tracked change:\n\n    # unique phrase, no paragraph id needed:\n    Revise("the tenant shall pay rent within thirty days").replace("thirty", "sixty").replace("rent", "the rent")\n    Revise(at="2673269E").replace("Tenant", "Lessee", all=True)  # whole paragraph\n    Revise("Section 4(b)", at="2673269E", occurrence=2).replace("4(b)", "4(c)")\n    Revise().replace("Acme Corp.", "Acme, Inc.", all=True)       # whole document\n\n`within` must occur exactly once in its paragraph (`at`) or document unless\n`occurrence` picks one. Each `select` must occur exactly once in the scope\nunless it passes `occurrence` or `all=True`. All selectors resolve against the\nscope as it stands when the operation starts, so later replacements never see\nearlier ones; overlapping selections are rejected.\n\n`AcceptRevision(target)` and `RejectRevision(target)` build `RevisionSettle`\noperations; `target` is a revision id from `await docx_read(path, kind="revisions")`\nor `"all"`. Put settle operations first: `"all"` also settles tracked changes\nmade earlier in the same plan.\n\nEvery operation dataclass has `to_dict()`, omitting optional fields whose\nvalue is `None`; `Plan.to_dict()` returns `{"author": ..., "change_mode": ..., "ops": [...]}`.\n\n## Host functions\n\n- `await docx_create(path: str, html: str)`\n- `await docx_read(path: str, view: str = "markup", kind: str = "document") -> ReadResult | dict` — complete HTML\n  markup and a current equations-address listing (at, equation, display, editable) by default (`kind="document"`); `kind="comments"`, `"styles"`, `"revisions"`, or `"assets"` returns the\n  core listing object (and a second positional of `comments`/`styles`/`revisions` is treated as `kind`).\n- `await docx_find(path: str, query: str, ignore_case: bool = False) -> list` — core find match\n  records verbatim (`{index, id?, text, style?, number?}` per matching paragraph; `id` is\n  the canonical uppercase paragraph address)\n- `await docx_help(topic: str | None = None) -> str`\n- `await docx_review(path: str, plan: Plan) -> ReviewResult | None` — validates the complete plan and returns `commit_key` plus bounded per-operation `edits` with affected markup context; returns `None` when validation is blocked\n- `await docx_commit(commit_key: str)` — commits the immutable reviewed plan; the key owns the\n  target file and plan\nReview does not write the target. Review and commit must happen in separate later\nPython calls; changing the plan requires a new review.\n\n## Discovering paragraphs\n\n`docx_find` plus `docx_read` are the supported discovery workflow:\nfind returns core match records to locate paragraphs, and reads return\nstructural markup. Operations stay addressed\nby the markup-view paragraph `id`:\n\n    matches = await docx_find("contract.docx", "Payment is due within")\n    for m in matches:\n        print(m["id"], m["text"])\n    markup = (await docx_read("contract.docx")).markup\n\nReading `view="final"` or `view="original"` is allowed for analysis, but\nreview plans remain source-bound to the exact bytes and paragraph ids of the\ncurrent `markup` view.\n\n## Computing operations with regex\n\n`re` is pre-imported and `ReadResult.markup` is an ordinary string, so you can\ninspect it and build operations in Python loops. Return the full ReadResult or\nprint its full markup and semantic metadata when reading; prefer complete document\ncontext. Named DOCX style IDs appear in data-docx-style and map one-to-one to\nReadResult.styles (resolved CSS keyed by style ID). Presentation rules appear\nin data-docx-css and map to ReadResult.css. Both catalogs are omitted from the\ndefault display; inspect result.styles or result.css to read their definitions;\nwhen authoring a fragment, use equivalent inline formatting rather than copying\nan unresolved class. Image aliases map to canonical assets in ReadResult.assets.\nReadResult.selection_space describes comment selectors; ReadResult.selections\nprovides exact text for paragraphs where generated content or revisions make\nHTML text ambiguous:\n\n\n    original = (await docx_read("contract.docx")).markup\n    ops = []\n    for m in re.finditer(r\'<p id="([0-9A-F]{8})"[^>]*>([^<]*?)</p>\', original):\n        if "Payment is due within" in m.group(2):\n            ops.append(ReplaceText(at=m.group(1), select=m.group(2),\n                                   with_=re.sub(r\'within \\d+ days\', \'within 45 days\', m.group(2))))\n    plan = Plan(author="Pi", operations=ops)\n    review = await docx_review("contract.docx", plan)\n    if review is not None:\n        for edit in review.edits:\n            print(edit["index"], edit["context"])\n        # ...later python call...\n        await docx_commit(review.commit_key)\n\n`select` must match the paragraph\'s current visible text exactly; on a document\nwith pending tracked changes, grep the `view="final"` projection instead.\n\n## Example\n\n    original = (await docx_read("contract.docx")).markup\n    plan = Plan(author="Pi", change_mode="track", operations=[\n        ReplaceText(at="2673269E", select="thirty days", with_="sixty days"),\n        FormatText(at="2673269E", select="sixty days", bold=True),\n    ])\n    review = await docx_review("contract.docx", plan)\n    # Inspect review.edits before committing in a later Python call.\n    if review is not None:\n        print(review.commit_key)\n\n\nUse await quote_find(source, query) to obtain the paragraph id and exact source text.\nCreate Quote(source, at, select, occurrence=1, style="double"), where select is one contiguous,\nverbatim source span. Adapt it with .omit(exact_source_text) and\n.bracket(exact_source_text, replacement). Adaptation selectors always refer to\nthe original span; overlaps fail. Finish with await quote_validate(q). Only the host\nconstructs QuoteResult.text, including curly double quotation marks by default\n(style="single" or style="none" are also available). Its provenance binds the source SHA-256, paragraph\nSHA-256, paragraph id, offsets, original span, and every adaptation.\n\nRaw quotation marks in ordinary authored text are lint errors. For a\nnon-quotational mention such as the word quotation, use\nawait term_render(Term("quotation")); its quote marks are host-created and its\nprovenance is classified as kind="term" rather than a source quotation.\nFor authored document content, prefer Inline([plain_text, Term(...), Quote(...)]).\nawait inline_validate() automatically lints every plain-text part before the host\nrenders structured nodes. The default policy is error; comment must be chosen\nexplicitly and returns warning spans that require protected comment bubbles.\nIn the plan REPL\'s flagged quotation mode, pass Quote, Term, or Inline directly\nto an operation with_ field. docx_review resolves the node and binds its source;\ncopying QuoteResult.text into a plain string loses that provenance boundary.\n\nExample:\nq = Quote("source.docx", at="89ABCDEF", select="The tenant must promptly pay the charge.")\nq.omit(" promptly")\nq.bracket("tenant", "Tenant")\nvalidated = await quote_validate(q)\nprint(validated.text)\nprint(validated.provenance)\n'
+REFERENCE = '\n# docxdriver Python REPL API — Version 1 (Python-authored plan)\n\n# BEGIN GENERATED OPERATION DOCS\n## Operations\n\nSelected from the core schema (`$defs.editOp.oneOf`) through the\ncapability manifest; field shapes, types, and enums are exactly the\nchecked-in schema’s. Every op dataclass has `to_dict()`, omitting\noptional fields whose value is `None`; constructors use `with_`/`as_`\nfor Python keyword collisions and `to_dict()` maps back to the schema\nfield names. Operations are addressed by the paragraph `id` attribute\nfrom `docx_read` (uppercase eight-digit hex) or a `$name` alias.\n\n### ClearFooter\n\n`ClearFooter(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit footer reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### ClearHeader\n\n`ClearHeader(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit header reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### CommentAdd\n\n`CommentAdd(at: str, text: str, occurrence: int | None = None, select: str | None = None)`\n\nAnchor a comment with `text` to the paragraph at `at`; omit `select` to comment the whole paragraph, or pass `select`/`occurrence` (1-based) to pin one exact span.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `text` | `str` | yes |\n| `occurrence` | `int | None` | no |\n| `select` | `str | None` | no |\n\n### CommentDelete\n\n`CommentDelete(comment_id: str)`\n\nDelete a comment by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n\n### CommentReply\n\n`CommentReply(comment_id: str, text: str)`\n\nReply to an existing comment; `comment_id` is the decimal id from a prior `comment_add` or a comments-kind read.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `text` | `str` | yes |\n\n### CommentSetStatus\n\n`CommentSetStatus(comment_id: str, status: str)`\n\nSet a comment\'s status to `open` or `resolved` by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `status` | `str` | yes |\n\n### DeleteEquation\n\n`DeleteEquation(at: str, equation: int | None = None)`\n\nDelete a current equation while preserving the paragraph. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Tracked mode keeps the equation recoverable until the deletion is accepted.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `equation` | `int | None` | no |\n\n### DeleteParagraphs\n\n`DeleteParagraphs(at: list)`\n\nDelete the paragraphs listed in `at` (tracked deletion by default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n\n### EditTable\n\n`EditTable(action: dict, at: str)`\n\nDirect structural table edits using a source-bound table handle. action.kind is insert_rows/delete_rows/insert_columns/delete_columns/merge_cells/split_cell/delete; coordinates and counts are one-based. Insert/delete grid operations and merge require an unmerged rectangular grid. Split keeps content in the first resulting cell; merge concatenates content in row-major order. Rejects tracked mode and tables containing unresolved revisions, bookmarks, comments, fields or content controls. Delete the table instead of its final row or column.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `dict` | yes |\n| `at` | `str` | yes |\n\n### FormatParagraph\n\n`FormatParagraph(at: str, alignment: str | None = None, clear: list | None = None, first_line_indent: float | None = None, indent_left: float | None = None, indent_right: float | None = None, line_spacing: dict | None = None, space_after: float | None = None, space_before: float | None = None, style: str | None = None)`\n\nApply paragraph formatting to the paragraph at `at`: `style`, `alignment` (left/center/right/justify), signed `indent_left`/`indent_right`, signed `first_line_indent` (negative for hanging, zero for an explicit zero offset), `space_before`/`space_after`, `line_spacing` (dict with `mode` multiple/exact/at_least and `value`), or `clear`. Omitted properties are untouched; clear removes direct settings and inherits styles/defaults, winning over set. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `alignment` | `str | None` | no |\n| `clear` | `list | None` | no |\n| `first_line_indent` | `float | None` | no |\n| `indent_left` | `float | None` | no |\n| `indent_right` | `float | None` | no |\n| `line_spacing` | `dict | None` | no |\n| `space_after` | `float | None` | no |\n| `space_before` | `float | None` | no |\n| `style` | `str | None` | no |\n\n### FormatText\n\n`FormatText(at: str, select: str, bold: bool | None = None, clear: list | None = None, color: str | None = None, font_size: float | None = None, highlight: str | None = None, italic: bool | None = None, occurrence: int | None = None, strike: bool | None = None, subscript: bool | None = None, superscript: bool | None = None, underline: bool | None = None)`\n\nApply character formatting to an exact occurrence of `select` in the paragraph at `at`: boolean attributes (`bold`, `italic`, `underline`, `strike`, `superscript`, `subscript`), `color` (#RRGGBB), `highlight` (Word palette including none), `font_size` (points), `occurrence`, or `clear`. Omitted properties preserve source OOXML; false explicitly overrides inherited formatting (baseline for superscript/subscript). Clear removes the direct property and inherits styles/defaults, winning over set; superscript/subscript share one property. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `bold` | `bool | None` | no |\n| `clear` | `list | None` | no |\n| `color` | `str | None` | no |\n| `font_size` | `float | None` | no |\n| `highlight` | `str | None` | no |\n| `italic` | `bool | None` | no |\n| `occurrence` | `int | None` | no |\n| `strike` | `bool | None` | no |\n| `subscript` | `bool | None` | no |\n| `superscript` | `bool | None` | no |\n| `underline` | `bool | None` | no |\n\n### InsertParagraph\n\n`InsertParagraph(at: str, position: str, as_: str | None = None, style: str | None = None, with_: str | Inline | Quote | Term | None = None)`\n\nInsert a new paragraph before or after an anchor: paragraph id/alias (`at`) or body-level table number (`table:N` from markup); `with` is its text, `style` its style, and `as` names the new paragraph id (a `$name` alias).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `position` | `str` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n| `style` | `str | None` | no |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term | None` | no |\n\n### InsertTable\n\n`InsertTable(at: str, columns: int, position: str, rows: int, as_: str | None = None)`\n\nInsert a rectangular table before/after paragraph at, with rows and columns in 1..100. Direct mode only. Optional as creates a plan-local table alias for later formatting and structural edits.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `columns` | `int` | yes |\n| `position` | `str` | yes |\n| `rows` | `int` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n\n### ReplaceEquation\n\n`ReplaceEquation(at: str, mathml: str, display: bool | None = None, equation: int | None = None)`\n\nReplace a current equation using presentation MathML. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Display mode is preserved by default. Settle existing revisions before editing their equations.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `mathml` | `str` | yes |\n| `display` | `bool | None` | no |\n| `equation` | `int | None` | no |\n\n### ReplaceParagraph\n\n`ReplaceParagraph(at: str, with_: str | Inline | Quote | Term)`\n\nReplace the entire paragraph at `at` with `with`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n\n### ReplaceText\n\n`ReplaceText(at: str, select: str, with_: str | Inline | Quote | Term, occurrence: int | None = None)`\n\nReplace an exact occurrence of `select` in the paragraph at `at` with `with`; `occurrence` picks the nth match (1-based).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `occurrence` | `int | None` | no |\n\n### ReviseText\n\n`ReviseText(edits: list, at: str | None = None, occurrence: int | None = None, within: str | None = None)`\n\nSeveral exact replacements inside one bounded scope; prefer the chainable `Revise(within, at=None, occurrence=None).replace(select, with_, occurrence=None, all=False)` builder. Scope: `within` (a phrase unique in paragraph `at`, or in the whole document when `at` is omitted; `occurrence` picks a repeated one), else the paragraph `at`, else the whole document. Each edit must match exactly once in the scope unless it sets `occurrence` or `all`. All edits resolve against the scope as it stands when the operation starts, must not overlap, and become separate minimal tracked changes.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `edits` | `list` | yes |\n| `at` | `str | None` | no |\n| `occurrence` | `int | None` | no |\n| `within` | `str | None` | no |\n\n### RevisionSettle\n\n`RevisionSettle(action: str, target: str)`\n\nAccept or reject tracked changes: `target` is a decimal revision id from `await docx_read(path, kind="revisions")` or `all`; `action` is `accept` or `reject`. Prefer the `AcceptRevision(target)` / `RejectRevision(target)` shorthands. Settling `all` also settles tracked changes made by earlier operations in the same plan, and later selectors address the settled text.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `str` | yes |\n| `target` | `str` | yes |\n\n### SetEvenAndOddHeaders\n\n`SetEvenAndOddHeaders(even_and_odd: bool)`\n\nEnable or disable distinct even-page headers/footers (`even_and_odd`); when true, `kind="even"` chrome applies to even pages.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `even_and_odd` | `bool` | yes |\n\n### SetFirstPageMode\n\n`SetFirstPageMode(enabled: bool, section: int | None = None)`\n\nEnable/disable first-page stories in a section (default 1) without removing stored stories. Tracked mode records a section-property snapshot; settle pending section changes before editing again.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `enabled` | `bool` | yes |\n| `section` | `int | None` | no |\n\n### SetFooter\n\n`SetFooter(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section footer chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetHeader\n\n`SetHeader(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section header chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetList\n\n`SetList(at: list, format: str | None = None, level: int | None = None, levels: list | None = None, num_id: int | None = None, remove: bool | None = None, start: int | None = None)`\n\nAssign explicitly selected paragraphs to a new list (format defaults to decimal), continue an existing num_id, or remove membership with remove=True. level is 0..8; start is positive and creates an isolated restarted instance. Optional levels defines 1..9 per-level format/label/start/restart_after, signed indent_left/indent_right/first_line_indent and marker_bold/marker_italic/marker_font/marker_color for a new list. Label placeholders reference this or ancestor levels (%1..%9). Existing definitions are never restyled. Membership changes are tracked; settle pending paragraph changes first. Definitions remain after rejection for safe reference restoration.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n| `format` | `str | None` | no |\n| `level` | `int | None` | no |\n| `levels` | `list | None` | no |\n| `num_id` | `int | None` | no |\n| `remove` | `bool | None` | no |\n| `start` | `int | None` | no |\n\n### SetPageMargins\n\n`SetPageMargins(bottom: float | None = None, footer: float | None = None, gutter: float | None = None, header: float | None = None, left: float | None = None, right: float | None = None, section: int | None = None, top: float | None = None)`\n\nSet selected nonnegative page margins in points for a section (default 1): top/right/bottom/left/header/footer/gutter. Omitted values are preserved. Like existing header/footer setters, margin changes are direct even in tracked plans.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `bottom` | `float | None` | no |\n| `footer` | `float | None` | no |\n| `gutter` | `float | None` | no |\n| `header` | `float | None` | no |\n| `left` | `float | None` | no |\n| `right` | `float | None` | no |\n| `section` | `int | None` | no |\n| `top` | `float | None` | no |\n\n### SetSectionLayout\n\n`SetSectionLayout(break_type: str | None = None, column_separator: bool | None = None, column_spacing: float | None = None, column_widths: list | None = None, columns: int | None = None, height: float | None = None, orientation: str | None = None, page_number_continue: bool | None = None, page_number_format: str | None = None, page_number_start: int | None = None, page_size: str | None = None, section: int | None = None, width: float | None = None)`\n\nSelectively set section layout (section defaults to 1): page_size letter/legal/a4/a3/a5 or paired width/height in points; orientation portrait/landscape normalizes dimensions. Columns 1..45 with column_spacing, column_widths and column_separator; break_type nextPage/continuous/oddPage/evenPage/nextColumn; page_number_format, page_number_start or page_number_continue=true. Omission preserves properties; tracking snapshots section properties while preserving story relationships. Pending property changes must be settled first.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `break_type` | `str | None` | no |\n| `column_separator` | `bool | None` | no |\n| `column_spacing` | `float | None` | no |\n| `column_widths` | `list | None` | no |\n| `columns` | `int | None` | no |\n| `height` | `float | None` | no |\n| `orientation` | `str | None` | no |\n| `page_number_continue` | `bool | None` | no |\n| `page_number_format` | `str | None` | no |\n| `page_number_start` | `int | None` | no |\n| `page_size` | `str | None` | no |\n| `section` | `int | None` | no |\n| `width` | `float | None` | no |\n\n# END GENERATED OPERATION DOCS\n\n## Scoped revisions\n\n`Revise(within=None, at=None, occurrence=None)` builds one `ReviseText`\noperation; chain `.replace(select, with_, occurrence=None, all=False)` for each\nchange. The scope bounds every `select`, so short selectors stay unambiguous\nin long documents and each change becomes a minimal tracked change:\n\n    # unique phrase, no paragraph id needed:\n    Revise("the tenant shall pay rent within thirty days").replace("thirty", "sixty").replace("rent", "the rent")\n    Revise(at="2673269E").replace("Tenant", "Lessee", all=True)  # whole paragraph\n    Revise("Section 4(b)", at="2673269E", occurrence=2).replace("4(b)", "4(c)")\n    Revise().replace("Acme Corp.", "Acme, Inc.", all=True)       # whole document\n\n`within` must occur exactly once in its paragraph (`at`) or document unless\n`occurrence` picks one. Each `select` must occur exactly once in the scope\nunless it passes `occurrence` or `all=True`. All selectors resolve against the\nscope as it stands when the operation starts, so later replacements never see\nearlier ones; overlapping selections are rejected.\n\n`AcceptRevision(target)` and `RejectRevision(target)` build `RevisionSettle`\noperations; `target` is a revision id from `await docx_read(path, kind="revisions")`\nor `"all"`. Put settle operations first: `"all"` also settles tracked changes\nmade earlier in the same plan.\n\nEvery operation dataclass has `to_dict()`, omitting optional fields whose\nvalue is `None`; `Plan.to_dict()` returns `{"author": ..., "change_mode": ..., "ops": [...]}`.\n\nTracked plain-text replacements automatically compute word-level redlines in\nReplaceText, ReviseText, and ReplaceParagraph. Unchanged words retain their\nformatting; adjacent changed words form one deletion followed by one insertion.\nRich replacements retain whole-selection tracking to apply their formatting.\n\n## Host functions\n\n- `await docx_create(path: str, html: str)`\n- `await docx_read(path: str, view: str = "markup", kind: str = "document") -> ReadResult | dict` — complete HTML\n  markup and a current equations-address listing (at, equation, display, editable) by default (`kind="document"`); `kind="comments"`, `"styles"`, `"revisions"`, or `"assets"` returns the\n  core listing object (and a second positional of `comments`/`styles`/`revisions` is treated as `kind`).\n- `await docx_find(path: str, query: str, ignore_case: bool = False) -> list` — core find match\n  records verbatim (`{index, id?, text, style?, number?}` per matching paragraph; `id` is\n  the canonical uppercase paragraph address)\n- `await docx_help(topic: str | None = None) -> str`\n- `await docx_review(path: str, plan: Plan) -> ReviewResult | None` — validates the complete plan and returns `commit_key` plus bounded per-operation `edits` with affected markup context; returns `None` when validation is blocked\n- `await docx_commit(commit_key: str)` — commits the immutable reviewed plan; the key owns the\n  target file and plan\nReview does not write the target. Review and commit must happen in separate later\nPython calls; changing the plan requires a new review.\n\n## Discovering paragraphs\n\n`docx_find` plus `docx_read` are the supported discovery workflow:\nfind returns core match records to locate paragraphs, and reads return\nstructural markup. Operations stay addressed\nby the markup-view paragraph `id`:\n\n    matches = await docx_find("contract.docx", "Payment is due within")\n    for m in matches:\n        print(m["id"], m["text"])\n    markup = (await docx_read("contract.docx")).markup\n\nReading `view="final"` or `view="original"` is allowed for analysis, but\nreview plans remain source-bound to the exact bytes and paragraph ids of the\ncurrent `markup` view.\n\n## Computing operations with regex\n\n`re` is pre-imported and `ReadResult.markup` is an ordinary string, so you can\ninspect it and build operations in Python loops. Return the full ReadResult or\nprint its full markup and semantic metadata when reading; prefer complete document\ncontext. Named DOCX style IDs appear in data-docx-style and map one-to-one to\nReadResult.styles (resolved CSS keyed by style ID). Presentation rules appear\nin data-docx-css and map to ReadResult.css. Both catalogs are omitted from the\ndefault display; inspect result.styles or result.css to read their definitions;\nwhen authoring a fragment, use equivalent inline formatting rather than copying\nan unresolved class. Image aliases map to canonical assets in ReadResult.assets.\nReadResult.selection_space describes comment selectors; ReadResult.selections\nprovides exact text for paragraphs where generated content or revisions make\nHTML text ambiguous:\n\n\n    original = (await docx_read("contract.docx")).markup\n    ops = []\n    for m in re.finditer(r\'<p id="([0-9A-F]{8})"[^>]*>([^<]*?)</p>\', original):\n        if "Payment is due within" in m.group(2):\n            ops.append(ReplaceText(at=m.group(1), select=m.group(2),\n                                   with_=re.sub(r\'within \\d+ days\', \'within 45 days\', m.group(2))))\n    plan = Plan(author="Pi", operations=ops)\n    review = await docx_review("contract.docx", plan)\n    if review is not None:\n        for edit in review.edits:\n            print(edit["index"], edit["context"])\n        # ...later python call...\n        await docx_commit(review.commit_key)\n\n`select` must match the paragraph\'s current visible text exactly; on a document\nwith pending tracked changes, grep the `view="final"` projection instead.\n\n## Example\n\n    original = (await docx_read("contract.docx")).markup\n    plan = Plan(author="Pi", change_mode="track", operations=[\n        ReplaceText(at="2673269E", select="thirty days", with_="sixty days"),\n        FormatText(at="2673269E", select="sixty days", bold=True),\n    ])\n    review = await docx_review("contract.docx", plan)\n    # Inspect review.edits before committing in a later Python call.\n    if review is not None:\n        print(review.commit_key)\n\n\nUse await quote_find(source, query) to obtain the paragraph id and exact source text.\nCreate Quote(source, at, select, occurrence=1, style="double"), where select is one contiguous,\nverbatim source span. Adapt it with .omit(exact_source_text) and\n.bracket(exact_source_text, replacement). Adaptation selectors always refer to\nthe original span; overlaps fail. Finish with await quote_validate(q). Only the host\nconstructs QuoteResult.text, including curly double quotation marks by default\n(style="single" or style="none" are also available). Its provenance binds the source SHA-256, paragraph\nSHA-256, paragraph id, offsets, original span, and every adaptation.\n\nRaw quotation marks in ordinary authored text are lint errors. For a\nnon-quotational mention such as the word quotation, use\nawait term_render(Term("quotation")); its quote marks are host-created and its\nprovenance is classified as kind="term" rather than a source quotation.\nFor authored document content, prefer Inline([plain_text, Term(...), Quote(...)]).\nawait inline_validate() automatically lints every plain-text part before the host\nrenders structured nodes. The default policy is error; comment must be chosen\nexplicitly and returns warning spans that require protected comment bubbles.\nIn the plan REPL\'s flagged quotation mode, pass Quote, Term, or Inline directly\nto an operation with_ field. docx_review resolves the node and binds its source;\ncopying QuoteResult.text into a plain string loses that provenance boundary.\n\nExample:\nq = Quote("source.docx", at="89ABCDEF", select="The tenant must promptly pay the charge.")\nq.omit(" promptly")\nq.bracket("tenant", "Tenant")\nvalidated = await quote_validate(q)\nprint(validated.text)\nprint(validated.provenance)\n'

{docxdriver-0.3.1 → docxdriver-0.3.2}/python/docxdriver/repl/prelude.py

@@ -1,3 +1,3 @@
 # Generated by scripts/generate-docxdriver-repl-prelude.py; edit the shared Pi templates.
 PRELUDE = "from dataclasses import dataclass\n\n@dataclass\nclass QuoteResult:\n    text: str\n    provenance: dict\n\n@dataclass\nclass TermResult:\n    text: str\n    provenance: dict\n\nclass Term:\n\n    def __init__(self, text: str, style: str='double'):\n        self.text = text\n        self.style = style\n\n    def to_dict(self):\n        return {'$kind': 'term', 'text': self.text, 'style': self.style}\n\n@dataclass\nclass InlineResult:\n    text: str\n    audit: dict\n\nclass Inline:\n\n    def __init__(self, parts: list):\n        self.parts = parts\n\n    def to_dict(self):\n        return {'$kind': 'inline', 'parts': [part.to_dict() if hasattr(part, 'to_dict') else part for part in self.parts]}\n\nclass Quote:\n\n    def __init__(self, source: str, at: str, select: str, occurrence: int=1, style: str='double'):\n        self.source = source\n        self.at = at\n        self.select = select\n        self.occurrence = occurrence\n        self.style = style\n        self.changes = []\n\n    def omit(self, select: str, occurrence: int=1, marker: str='…'):\n        self.changes.append({'kind': 'omit', 'select': select, 'occurrence': occurrence, 'marker': marker})\n        return self\n\n    def bracket(self, select: str, replacement: str, occurrence: int=1):\n        self.changes.append({'kind': 'bracket', 'select': select, 'replacement': replacement, 'occurrence': occurrence})\n        return self\n\n    def to_dict(self):\n        return {'$kind': 'quote', 'source': self.source, 'at': self.at, 'select': self.select, 'occurrence': self.occurrence, 'style': self.style, 'changes': self.changes}\n\nasync def quote_find(source: str, query: str, ignore_case: bool=False) -> list:\n    return await _quote_find(source, query, ignore_case)\n\nasync def quote_validate(quote: Quote) -> QuoteResult:\n    result = await _quote_validate(quote.to_dict())\n    return QuoteResult(text=result['text'], provenance=result)\n\nasync def quote_lint(text: str, severity: str='error') -> list:\n    return await _quote_lint(text, severity)\n\nasync def term_render(term: Term) -> TermResult:\n    result = await _term_render(term.to_dict())\n    return TermResult(text=result['text'], provenance=result)\n\nasync def inline_validate(inline: Inline, policy: str='error') -> InlineResult:\n    result = await _inline_validate(inline.to_dict(), policy)\n    return InlineResult(text=result['text'], audit=result['audit'])\nfrom dataclasses import dataclass\nimport re\n\n@dataclass\nclass ClearFooter:\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'clear_footer'}\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass ClearHeader:\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'clear_header'}\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass CommentAdd:\n    at: str\n    text: str\n    occurrence: int | None = None\n    select: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'comment_add'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.text is not None:\n            value['text'] = self.text\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.select is not None:\n            value['select'] = self.select\n        return value\n\n@dataclass\nclass CommentDelete:\n    comment_id: str\n\n    def to_dict(self):\n        value = {'op': 'comment_delete'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        return value\n\n@dataclass\nclass CommentReply:\n    comment_id: str\n    text: str\n\n    def to_dict(self):\n        value = {'op': 'comment_reply'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        if self.text is not None:\n            value['text'] = self.text\n        return value\n\n@dataclass\nclass CommentSetStatus:\n    comment_id: str\n    status: str\n\n    def to_dict(self):\n        value = {'op': 'comment_set_status'}\n        if self.comment_id is not None:\n            value['comment_id'] = self.comment_id\n        if self.status is not None:\n            value['status'] = self.status\n        return value\n\n@dataclass\nclass DeleteEquation:\n    at: str\n    equation: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'delete_equation'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.equation is not None:\n            value['equation'] = self.equation\n        return value\n\n@dataclass\nclass DeleteParagraphs:\n    at: list\n\n    def to_dict(self):\n        value = {'op': 'delete_paragraphs'}\n        if self.at is not None:\n            value['at'] = self.at\n        return value\n\n@dataclass\nclass EditTable:\n    action: dict\n    at: str\n\n    def to_dict(self):\n        value = {'op': 'edit_table'}\n        if self.action is not None:\n            value['action'] = self.action\n        if self.at is not None:\n            value['at'] = self.at\n        return value\n\n@dataclass\nclass FormatParagraph:\n    at: str\n    alignment: str | None = None\n    clear: list | None = None\n    first_line_indent: float | None = None\n    indent_left: float | None = None\n    indent_right: float | None = None\n    line_spacing: dict | None = None\n    space_after: float | None = None\n    space_before: float | None = None\n    style: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'format_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.alignment is not None:\n            value['alignment'] = self.alignment\n        if self.clear is not None:\n            value['clear'] = self.clear\n        if self.first_line_indent is not None:\n            value['first_line_indent'] = self.first_line_indent\n        if self.indent_left is not None:\n            value['indent_left'] = self.indent_left\n        if self.indent_right is not None:\n            value['indent_right'] = self.indent_right\n        if self.line_spacing is not None:\n            value['line_spacing'] = self.line_spacing\n        if self.space_after is not None:\n            value['space_after'] = self.space_after\n        if self.space_before is not None:\n            value['space_before'] = self.space_before\n        if self.style is not None:\n            value['style'] = self.style\n        return value\n\n@dataclass\nclass FormatText:\n    at: str\n    select: str\n    bold: bool | None = None\n    clear: list | None = None\n    color: str | None = None\n    font_size: float | None = None\n    highlight: str | None = None\n    italic: bool | None = None\n    occurrence: int | None = None\n    strike: bool | None = None\n    subscript: bool | None = None\n    superscript: bool | None = None\n    underline: bool | None = None\n\n    def to_dict(self):\n        value = {'op': 'format_text'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.select is not None:\n            value['select'] = self.select\n        if self.bold is not None:\n            value['bold'] = self.bold\n        if self.clear is not None:\n            value['clear'] = self.clear\n        if self.color is not None:\n            value['color'] = self.color\n        if self.font_size is not None:\n            value['font_size'] = self.font_size\n        if self.highlight is not None:\n            value['highlight'] = self.highlight\n        if self.italic is not None:\n            value['italic'] = self.italic\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.strike is not None:\n            value['strike'] = self.strike\n        if self.subscript is not None:\n            value['subscript'] = self.subscript\n        if self.superscript is not None:\n            value['superscript'] = self.superscript\n        if self.underline is not None:\n            value['underline'] = self.underline\n        return value\n\n@dataclass\nclass InsertParagraph:\n    at: str\n    position: str\n    as_: str | None = None\n    style: str | None = None\n    with_: str | Inline | Quote | Term | None = None\n\n    def to_dict(self):\n        value = {'op': 'insert_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.position is not None:\n            value['position'] = self.position\n        if self.as_ is not None:\n            value['as'] = self.as_\n        if self.style is not None:\n            value['style'] = self.style\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        return value\n\n@dataclass\nclass InsertTable:\n    at: str\n    columns: int\n    position: str\n    rows: int\n    as_: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'insert_table'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.columns is not None:\n            value['columns'] = self.columns\n        if self.position is not None:\n            value['position'] = self.position\n        if self.rows is not None:\n            value['rows'] = self.rows\n        if self.as_ is not None:\n            value['as'] = self.as_\n        return value\n\n@dataclass\nclass ReplaceEquation:\n    at: str\n    mathml: str\n    display: bool | None = None\n    equation: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'replace_equation'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.mathml is not None:\n            value['mathml'] = self.mathml\n        if self.display is not None:\n            value['display'] = self.display\n        if self.equation is not None:\n            value['equation'] = self.equation\n        return value\n\n@dataclass\nclass ReplaceParagraph:\n    at: str\n    with_: str | Inline | Quote | Term\n\n    def to_dict(self):\n        value = {'op': 'replace_paragraph'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        return value\n\n@dataclass\nclass ReplaceText:\n    at: str\n    select: str\n    with_: str | Inline | Quote | Term\n    occurrence: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'replace_text'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.select is not None:\n            value['select'] = self.select\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        return value\n\n@dataclass\nclass ReviseText:\n    edits: list\n    at: str | None = None\n    occurrence: int | None = None\n    within: str | None = None\n\n    def to_dict(self):\n        value = {'op': 'revise_text'}\n        if self.edits is not None:\n            value['edits'] = self.edits\n        if self.at is not None:\n            value['at'] = self.at\n        if self.occurrence is not None:\n            value['occurrence'] = self.occurrence\n        if self.within is not None:\n            value['within'] = self.within\n        return value\n\n@dataclass\nclass RevisionSettle:\n    action: str\n    target: str\n\n    def to_dict(self):\n        value = {'op': 'revision_settle'}\n        if self.action is not None:\n            value['action'] = self.action\n        if self.target is not None:\n            value['target'] = self.target\n        return value\n\n@dataclass\nclass SetEvenAndOddHeaders:\n    even_and_odd: bool\n\n    def to_dict(self):\n        value = {'op': 'set_even_and_odd_headers'}\n        if self.even_and_odd is not None:\n            value['even_and_odd'] = self.even_and_odd\n        return value\n\n@dataclass\nclass SetFirstPageMode:\n    enabled: bool\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_first_page_mode'}\n        if self.enabled is not None:\n            value['enabled'] = self.enabled\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetFooter:\n    with_: str | Inline | Quote | Term\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_footer'}\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetHeader:\n    with_: str | Inline | Quote | Term\n    kind: str | None = None\n    section: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_header'}\n        if self.with_ is not None:\n            value['with'] = self.with_.to_dict() if hasattr(self.with_, 'to_dict') else self.with_\n        if self.kind is not None:\n            value['kind'] = self.kind\n        if self.section is not None:\n            value['section'] = self.section\n        return value\n\n@dataclass\nclass SetList:\n    at: list\n    format: str | None = None\n    level: int | None = None\n    levels: list | None = None\n    num_id: int | None = None\n    remove: bool | None = None\n    start: int | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_list'}\n        if self.at is not None:\n            value['at'] = self.at\n        if self.format is not None:\n            value['format'] = self.format\n        if self.level is not None:\n            value['level'] = self.level\n        if self.levels is not None:\n            value['levels'] = self.levels\n        if self.num_id is not None:\n            value['num_id'] = self.num_id\n        if self.remove is not None:\n            value['remove'] = self.remove\n        if self.start is not None:\n            value['start'] = self.start\n        return value\n\n@dataclass\nclass SetPageMargins:\n    bottom: float | None = None\n    footer: float | None = None\n    gutter: float | None = None\n    header: float | None = None\n    left: float | None = None\n    right: float | None = None\n    section: int | None = None\n    top: float | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_page_margins'}\n        if self.bottom is not None:\n            value['bottom'] = self.bottom\n        if self.footer is not None:\n            value['footer'] = self.footer\n        if self.gutter is not None:\n            value['gutter'] = self.gutter\n        if self.header is not None:\n            value['header'] = self.header\n        if self.left is not None:\n            value['left'] = self.left\n        if self.right is not None:\n            value['right'] = self.right\n        if self.section is not None:\n            value['section'] = self.section\n        if self.top is not None:\n            value['top'] = self.top\n        return value\n\n@dataclass\nclass SetSectionLayout:\n    break_type: str | None = None\n    column_separator: bool | None = None\n    column_spacing: float | None = None\n    column_widths: list | None = None\n    columns: int | None = None\n    height: float | None = None\n    orientation: str | None = None\n    page_number_continue: bool | None = None\n    page_number_format: str | None = None\n    page_number_start: int | None = None\n    page_size: str | None = None\n    section: int | None = None\n    width: float | None = None\n\n    def to_dict(self):\n        value = {'op': 'set_section_layout'}\n        if self.break_type is not None:\n            value['break_type'] = self.break_type\n        if self.column_separator is not None:\n            value['column_separator'] = self.column_separator\n        if self.column_spacing is not None:\n            value['column_spacing'] = self.column_spacing\n        if self.column_widths is not None:\n            value['column_widths'] = self.column_widths\n        if self.columns is not None:\n            value['columns'] = self.columns\n        if self.height is not None:\n            value['height'] = self.height\n        if self.orientation is not None:\n            value['orientation'] = self.orientation\n        if self.page_number_continue is not None:\n            value['page_number_continue'] = self.page_number_continue\n        if self.page_number_format is not None:\n            value['page_number_format'] = self.page_number_format\n        if self.page_number_start is not None:\n            value['page_number_start'] = self.page_number_start\n        if self.page_size is not None:\n            value['page_size'] = self.page_size\n        if self.section is not None:\n            value['section'] = self.section\n        if self.width is not None:\n            value['width'] = self.width\n        return value\n\n@dataclass\nclass Revise:\n    within: str | None = None\n    at: str | None = None\n    occurrence: int | None = None\n    edits: list = None\n\n    def replace(self, select: str, with_, occurrence: int | None=None, all: bool=False):\n        edit = {'select': select, 'with': with_.to_dict() if hasattr(with_, 'to_dict') else with_}\n        if occurrence is not None:\n            edit['occurrence'] = occurrence\n        if all:\n            edit['all'] = True\n        self.edits = (self.edits or []) + [edit]\n        return self\n\n    def to_dict(self):\n        return ReviseText(edits=self.edits or [], at=self.at, occurrence=self.occurrence, within=self.within).to_dict()\n\ndef AcceptRevision(target: str) -> RevisionSettle:\n    return RevisionSettle(action='accept', target=str(target))\n\ndef RejectRevision(target: str) -> RevisionSettle:\n    return RevisionSettle(action='reject', target=str(target))\n\n@dataclass\nclass ReviewResult:\n    commit_key: str\n    edits: list\n\n@dataclass\nclass ReadResult:\n    markup: str\n    equations: list = None\n    selection_space: dict = None\n    selections: dict = None\n    comments: list = None\n    assets: list = None\n    comments_error: str = None\n    styles: dict = None\n    css: dict = None\n\n    def __repr__(self):\n        return 'ReadResult(markup=' + repr(self.markup) + ', styles=' + str(len(self.styles or {})) + ' definitions, css=' + str(len(self.css or {})) + ' rules; inspect .styles and .css, equations=' + repr(self.equations) + ', selection_space=' + repr(self.selection_space) + ', selections=' + repr(self.selections) + ', comments=' + repr(self.comments) + ', assets=' + repr(self.assets) + ', comments_error=' + repr(self.comments_error) + ')'\n\n@dataclass\nclass Plan:\n    author: str = 'docxdriver'\n    change_mode: str = 'track'\n    operations: list = None\n\n    def to_dict(self):\n        ops = self.operations if self.operations is not None else []\n        return {'author': self.author, 'change_mode': self.change_mode, 'ops': [op.to_dict() if hasattr(op, 'to_dict') else op for op in ops]}\n\nasync def docx_create(path: str, html: str):\n    return await _docx_create(path, html)\n\nasync def docx_read(path: str, view: str='markup', kind: str='document'):\n    _listing_kinds = ('comments', 'styles', 'revisions', 'assets')\n    if kind == 'document' and view in _listing_kinds:\n        kind = view\n    if kind in _listing_kinds:\n        return await _docx_read(path, view, kind)\n    if kind != 'document':\n        raise ValueError('kind must be one of document, comments, styles, revisions, assets')\n    result = await _docx_read(path, view)\n    return ReadResult(markup=result['markup'], styles=result.get('styles', {}), css=result.get('css', {}), equations=result.get('equations', []), selection_space=result.get('selection_space'), selections=result.get('selections'), comments=result.get('comments', []), assets=result.get('assets', []), comments_error=result.get('comments_error'))\n\nasync def docx_find(path: str, query: str, ignore_case: bool=False) -> list:\n    return await _docx_find(path, query, ignore_case)\n\nasync def docx_help(topic: str | None=None) -> str:\n    return await _docx_help(topic)\n\nasync def docx_review(path: str, plan: Plan) -> ReviewResult | None:\n    result = await _docx_review(path, {'plan': plan.to_dict()})\n    if result is None:\n        return None\n    return ReviewResult(commit_key=result['commit_key'], edits=result['edits'])\n\nasync def docx_commit(commit_key: str):\n    await _docx_commit(commit_key)\n    return None"
-REFERENCE = '\n# docxdriver Python REPL API — Version 1 (Python-authored plan)\n\n# BEGIN GENERATED OPERATION DOCS\n## Operations\n\nSelected from the core schema (`$defs.editOp.oneOf`) through the\ncapability manifest; field shapes, types, and enums are exactly the\nchecked-in schema’s. Every op dataclass has `to_dict()`, omitting\noptional fields whose value is `None`; constructors use `with_`/`as_`\nfor Python keyword collisions and `to_dict()` maps back to the schema\nfield names. Operations are addressed by the paragraph `id` attribute\nfrom `docx_read` (uppercase eight-digit hex) or a `$name` alias.\n\n### ClearFooter\n\n`ClearFooter(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit footer reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### ClearHeader\n\n`ClearHeader(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit header reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### CommentAdd\n\n`CommentAdd(at: str, text: str, occurrence: int | None = None, select: str | None = None)`\n\nAnchor a comment with `text` to the paragraph at `at`; omit `select` to comment the whole paragraph, or pass `select`/`occurrence` (1-based) to pin one exact span.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `text` | `str` | yes |\n| `occurrence` | `int | None` | no |\n| `select` | `str | None` | no |\n\n### CommentDelete\n\n`CommentDelete(comment_id: str)`\n\nDelete a comment by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n\n### CommentReply\n\n`CommentReply(comment_id: str, text: str)`\n\nReply to an existing comment; `comment_id` is the decimal id from a prior `comment_add` or a comments-kind read.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `text` | `str` | yes |\n\n### CommentSetStatus\n\n`CommentSetStatus(comment_id: str, status: str)`\n\nSet a comment\'s status to `open` or `resolved` by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `status` | `str` | yes |\n\n### DeleteEquation\n\n`DeleteEquation(at: str, equation: int | None = None)`\n\nDelete a current equation while preserving the paragraph. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Tracked mode keeps the equation recoverable until the deletion is accepted.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `equation` | `int | None` | no |\n\n### DeleteParagraphs\n\n`DeleteParagraphs(at: list)`\n\nDelete the paragraphs listed in `at` (tracked deletion by default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n\n### EditTable\n\n`EditTable(action: dict, at: str)`\n\nDirect structural table edits using a source-bound table handle. action.kind is insert_rows/delete_rows/insert_columns/delete_columns/merge_cells/split_cell/delete; coordinates and counts are one-based. Insert/delete grid operations and merge require an unmerged rectangular grid. Split keeps content in the first resulting cell; merge concatenates content in row-major order. Rejects tracked mode and tables containing unresolved revisions, bookmarks, comments, fields or content controls. Delete the table instead of its final row or column.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `dict` | yes |\n| `at` | `str` | yes |\n\n### FormatParagraph\n\n`FormatParagraph(at: str, alignment: str | None = None, clear: list | None = None, first_line_indent: float | None = None, indent_left: float | None = None, indent_right: float | None = None, line_spacing: dict | None = None, space_after: float | None = None, space_before: float | None = None, style: str | None = None)`\n\nApply paragraph formatting to the paragraph at `at`: `style`, `alignment` (left/center/right/justify), signed `indent_left`/`indent_right`, signed `first_line_indent` (negative for hanging, zero for an explicit zero offset), `space_before`/`space_after`, `line_spacing` (dict with `mode` multiple/exact/at_least and `value`), or `clear`. Omitted properties are untouched; clear removes direct settings and inherits styles/defaults, winning over set. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `alignment` | `str | None` | no |\n| `clear` | `list | None` | no |\n| `first_line_indent` | `float | None` | no |\n| `indent_left` | `float | None` | no |\n| `indent_right` | `float | None` | no |\n| `line_spacing` | `dict | None` | no |\n| `space_after` | `float | None` | no |\n| `space_before` | `float | None` | no |\n| `style` | `str | None` | no |\n\n### FormatText\n\n`FormatText(at: str, select: str, bold: bool | None = None, clear: list | None = None, color: str | None = None, font_size: float | None = None, highlight: str | None = None, italic: bool | None = None, occurrence: int | None = None, strike: bool | None = None, subscript: bool | None = None, superscript: bool | None = None, underline: bool | None = None)`\n\nApply character formatting to an exact occurrence of `select` in the paragraph at `at`: boolean attributes (`bold`, `italic`, `underline`, `strike`, `superscript`, `subscript`), `color` (#RRGGBB), `highlight` (Word palette including none), `font_size` (points), `occurrence`, or `clear`. Omitted properties preserve source OOXML; false explicitly overrides inherited formatting (baseline for superscript/subscript). Clear removes the direct property and inherits styles/defaults, winning over set; superscript/subscript share one property. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `bold` | `bool | None` | no |\n| `clear` | `list | None` | no |\n| `color` | `str | None` | no |\n| `font_size` | `float | None` | no |\n| `highlight` | `str | None` | no |\n| `italic` | `bool | None` | no |\n| `occurrence` | `int | None` | no |\n| `strike` | `bool | None` | no |\n| `subscript` | `bool | None` | no |\n| `superscript` | `bool | None` | no |\n| `underline` | `bool | None` | no |\n\n### InsertParagraph\n\n`InsertParagraph(at: str, position: str, as_: str | None = None, style: str | None = None, with_: str | Inline | Quote | Term | None = None)`\n\nInsert a new paragraph before or after an anchor: paragraph id/alias (`at`) or body-level table number (`table:N` from markup); `with` is its text, `style` its style, and `as` names the new paragraph id (a `$name` alias).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `position` | `str` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n| `style` | `str | None` | no |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term | None` | no |\n\n### InsertTable\n\n`InsertTable(at: str, columns: int, position: str, rows: int, as_: str | None = None)`\n\nInsert a rectangular table before/after paragraph at, with rows and columns in 1..100. Direct mode only. Optional as creates a plan-local table alias for later formatting and structural edits.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `columns` | `int` | yes |\n| `position` | `str` | yes |\n| `rows` | `int` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n\n### ReplaceEquation\n\n`ReplaceEquation(at: str, mathml: str, display: bool | None = None, equation: int | None = None)`\n\nReplace a current equation using presentation MathML. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Display mode is preserved by default. Settle existing revisions before editing their equations.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `mathml` | `str` | yes |\n| `display` | `bool | None` | no |\n| `equation` | `int | None` | no |\n\n### ReplaceParagraph\n\n`ReplaceParagraph(at: str, with_: str | Inline | Quote | Term)`\n\nReplace the entire paragraph at `at` with `with`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n\n### ReplaceText\n\n`ReplaceText(at: str, select: str, with_: str | Inline | Quote | Term, occurrence: int | None = None)`\n\nReplace an exact occurrence of `select` in the paragraph at `at` with `with`; `occurrence` picks the nth match (1-based).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `occurrence` | `int | None` | no |\n\n### ReviseText\n\n`ReviseText(edits: list, at: str | None = None, occurrence: int | None = None, within: str | None = None)`\n\nSeveral exact replacements inside one bounded scope; prefer the chainable `Revise(within, at=None, occurrence=None).replace(select, with_, occurrence=None, all=False)` builder. Scope: `within` (a phrase unique in paragraph `at`, or in the whole document when `at` is omitted; `occurrence` picks a repeated one), else the paragraph `at`, else the whole document. Each edit must match exactly once in the scope unless it sets `occurrence` or `all`. All edits resolve against the scope as it stands when the operation starts, must not overlap, and become separate minimal tracked changes.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `edits` | `list` | yes |\n| `at` | `str | None` | no |\n| `occurrence` | `int | None` | no |\n| `within` | `str | None` | no |\n\n### RevisionSettle\n\n`RevisionSettle(action: str, target: str)`\n\nAccept or reject tracked changes: `target` is a decimal revision id from `await docx_read(path, kind="revisions")` or `all`; `action` is `accept` or `reject`. Prefer the `AcceptRevision(target)` / `RejectRevision(target)` shorthands. Settling `all` also settles tracked changes made by earlier operations in the same plan, and later selectors address the settled text.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `str` | yes |\n| `target` | `str` | yes |\n\n### SetEvenAndOddHeaders\n\n`SetEvenAndOddHeaders(even_and_odd: bool)`\n\nEnable or disable distinct even-page headers/footers (`even_and_odd`); when true, `kind="even"` chrome applies to even pages.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `even_and_odd` | `bool` | yes |\n\n### SetFirstPageMode\n\n`SetFirstPageMode(enabled: bool, section: int | None = None)`\n\nEnable/disable first-page stories in a section (default 1) without removing stored stories. Tracked mode records a section-property snapshot; settle pending section changes before editing again.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `enabled` | `bool` | yes |\n| `section` | `int | None` | no |\n\n### SetFooter\n\n`SetFooter(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section footer chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetHeader\n\n`SetHeader(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section header chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetList\n\n`SetList(at: list, format: str | None = None, level: int | None = None, levels: list | None = None, num_id: int | None = None, remove: bool | None = None, start: int | None = None)`\n\nAssign explicitly selected paragraphs to a new list (format defaults to decimal), continue an existing num_id, or remove membership with remove=True. level is 0..8; start is positive and creates an isolated restarted instance. Optional levels defines 1..9 per-level format/label/start/restart_after, signed indent_left/indent_right/first_line_indent and marker_bold/marker_italic/marker_font/marker_color for a new list. Label placeholders reference this or ancestor levels (%1..%9). Existing definitions are never restyled. Membership changes are tracked; settle pending paragraph changes first. Definitions remain after rejection for safe reference restoration.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n| `format` | `str | None` | no |\n| `level` | `int | None` | no |\n| `levels` | `list | None` | no |\n| `num_id` | `int | None` | no |\n| `remove` | `bool | None` | no |\n| `start` | `int | None` | no |\n\n### SetPageMargins\n\n`SetPageMargins(bottom: float | None = None, footer: float | None = None, gutter: float | None = None, header: float | None = None, left: float | None = None, right: float | None = None, section: int | None = None, top: float | None = None)`\n\nSet selected nonnegative page margins in points for a section (default 1): top/right/bottom/left/header/footer/gutter. Omitted values are preserved. Like existing header/footer setters, margin changes are direct even in tracked plans.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `bottom` | `float | None` | no |\n| `footer` | `float | None` | no |\n| `gutter` | `float | None` | no |\n| `header` | `float | None` | no |\n| `left` | `float | None` | no |\n| `right` | `float | None` | no |\n| `section` | `int | None` | no |\n| `top` | `float | None` | no |\n\n### SetSectionLayout\n\n`SetSectionLayout(break_type: str | None = None, column_separator: bool | None = None, column_spacing: float | None = None, column_widths: list | None = None, columns: int | None = None, height: float | None = None, orientation: str | None = None, page_number_continue: bool | None = None, page_number_format: str | None = None, page_number_start: int | None = None, page_size: str | None = None, section: int | None = None, width: float | None = None)`\n\nSelectively set section layout (section defaults to 1): page_size letter/legal/a4/a3/a5 or paired width/height in points; orientation portrait/landscape normalizes dimensions. Columns 1..45 with column_spacing, column_widths and column_separator; break_type nextPage/continuous/oddPage/evenPage/nextColumn; page_number_format, page_number_start or page_number_continue=true. Omission preserves properties; tracking snapshots section properties while preserving story relationships. Pending property changes must be settled first.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `break_type` | `str | None` | no |\n| `column_separator` | `bool | None` | no |\n| `column_spacing` | `float | None` | no |\n| `column_widths` | `list | None` | no |\n| `columns` | `int | None` | no |\n| `height` | `float | None` | no |\n| `orientation` | `str | None` | no |\n| `page_number_continue` | `bool | None` | no |\n| `page_number_format` | `str | None` | no |\n| `page_number_start` | `int | None` | no |\n| `page_size` | `str | None` | no |\n| `section` | `int | None` | no |\n| `width` | `float | None` | no |\n\n# END GENERATED OPERATION DOCS\n\n## Scoped revisions\n\n`Revise(within=None, at=None, occurrence=None)` builds one `ReviseText`\noperation; chain `.replace(select, with_, occurrence=None, all=False)` for each\nchange. The scope bounds every `select`, so short selectors stay unambiguous\nin long documents and each change becomes a minimal tracked change:\n\n    # unique phrase, no paragraph id needed:\n    Revise("the tenant shall pay rent within thirty days").replace("thirty", "sixty").replace("rent", "the rent")\n    Revise(at="2673269E").replace("Tenant", "Lessee", all=True)  # whole paragraph\n    Revise("Section 4(b)", at="2673269E", occurrence=2).replace("4(b)", "4(c)")\n    Revise().replace("Acme Corp.", "Acme, Inc.", all=True)       # whole document\n\n`within` must occur exactly once in its paragraph (`at`) or document unless\n`occurrence` picks one. Each `select` must occur exactly once in the scope\nunless it passes `occurrence` or `all=True`. All selectors resolve against the\nscope as it stands when the operation starts, so later replacements never see\nearlier ones; overlapping selections are rejected.\n\n`AcceptRevision(target)` and `RejectRevision(target)` build `RevisionSettle`\noperations; `target` is a revision id from `await docx_read(path, kind="revisions")`\nor `"all"`. Put settle operations first: `"all"` also settles tracked changes\nmade earlier in the same plan.\n\nEvery operation dataclass has `to_dict()`, omitting optional fields whose\nvalue is `None`; `Plan.to_dict()` returns `{"author": ..., "change_mode": ..., "ops": [...]}`.\n\n## Host functions\n\n- `await docx_create(path: str, html: str)`\n- `await docx_read(path: str, view: str = "markup", kind: str = "document") -> ReadResult | dict` — complete HTML\n  markup and a current equations-address listing (at, equation, display, editable) by default (`kind="document"`); `kind="comments"`, `"styles"`, `"revisions"`, or `"assets"` returns the\n  core listing object (and a second positional of `comments`/`styles`/`revisions` is treated as `kind`).\n- `await docx_find(path: str, query: str, ignore_case: bool = False) -> list` — core find match\n  records verbatim (`{index, id?, text, style?, number?}` per matching paragraph; `id` is\n  the canonical uppercase paragraph address)\n- `await docx_help(topic: str | None = None) -> str`\n- `await docx_review(path: str, plan: Plan) -> ReviewResult | None` — validates the complete plan and returns `commit_key` plus bounded per-operation `edits` with affected markup context; returns `None` when validation is blocked\n- `await docx_commit(commit_key: str)` — commits the immutable reviewed plan; the key owns the\n  target file and plan\nReview does not write the target. Review and commit must happen in separate later\nPython calls; changing the plan requires a new review.\n\n## Discovering paragraphs\n\n`docx_find` plus `docx_read` are the supported discovery workflow:\nfind returns core match records to locate paragraphs, and reads return\nstructural markup. Operations stay addressed\nby the markup-view paragraph `id`:\n\n    matches = await docx_find("contract.docx", "Payment is due within")\n    for m in matches:\n        print(m["id"], m["text"])\n    markup = (await docx_read("contract.docx")).markup\n\nReading `view="final"` or `view="original"` is allowed for analysis, but\nreview plans remain source-bound to the exact bytes and paragraph ids of the\ncurrent `markup` view.\n\n## Computing operations with regex\n\n`re` is pre-imported and `ReadResult.markup` is an ordinary string, so you can\ninspect it and build operations in Python loops. Return the full ReadResult or\nprint its full markup and semantic metadata when reading; prefer complete document\ncontext. Named DOCX style IDs appear in data-docx-style and map one-to-one to\nReadResult.styles (resolved CSS keyed by style ID). Presentation rules appear\nin data-docx-css and map to ReadResult.css. Both catalogs are omitted from the\ndefault display; inspect result.styles or result.css to read their definitions;\nwhen authoring a fragment, use equivalent inline formatting rather than copying\nan unresolved class. Image aliases map to canonical assets in ReadResult.assets.\nReadResult.selection_space describes comment selectors; ReadResult.selections\nprovides exact text for paragraphs where generated content or revisions make\nHTML text ambiguous:\n\n\n    original = (await docx_read("contract.docx")).markup\n    ops = []\n    for m in re.finditer(r\'<p id="([0-9A-F]{8})"[^>]*>([^<]*?)</p>\', original):\n        if "Payment is due within" in m.group(2):\n            ops.append(ReplaceText(at=m.group(1), select=m.group(2),\n                                   with_=re.sub(r\'within \\d+ days\', \'within 45 days\', m.group(2))))\n    plan = Plan(author="Pi", operations=ops)\n    review = await docx_review("contract.docx", plan)\n    if review is not None:\n        for edit in review.edits:\n            print(edit["index"], edit["context"])\n        # ...later python call...\n        await docx_commit(review.commit_key)\n\n`select` must match the paragraph\'s current visible text exactly; on a document\nwith pending tracked changes, grep the `view="final"` projection instead.\n\n## Example\n\n    original = (await docx_read("contract.docx")).markup\n    plan = Plan(author="Pi", change_mode="track", operations=[\n        ReplaceText(at="2673269E", select="thirty days", with_="sixty days"),\n        FormatText(at="2673269E", select="sixty days", bold=True),\n    ])\n    review = await docx_review("contract.docx", plan)\n    # Inspect review.edits before committing in a later Python call.\n    if review is not None:\n        print(review.commit_key)\n\n\nUse await quote_find(source, query) to obtain the paragraph id and exact source text.\nCreate Quote(source, at, select, occurrence=1, style="double"), where select is one contiguous,\nverbatim source span. Adapt it with .omit(exact_source_text) and\n.bracket(exact_source_text, replacement). Adaptation selectors always refer to\nthe original span; overlaps fail. Finish with await quote_validate(q). Only the host\nconstructs QuoteResult.text, including curly double quotation marks by default\n(style="single" or style="none" are also available). Its provenance binds the source SHA-256, paragraph\nSHA-256, paragraph id, offsets, original span, and every adaptation.\n\nRaw quotation marks in ordinary authored text are lint errors. For a\nnon-quotational mention such as the word quotation, use\nawait term_render(Term("quotation")); its quote marks are host-created and its\nprovenance is classified as kind="term" rather than a source quotation.\nFor authored document content, prefer Inline([plain_text, Term(...), Quote(...)]).\nawait inline_validate() automatically lints every plain-text part before the host\nrenders structured nodes. The default policy is error; comment must be chosen\nexplicitly and returns warning spans that require protected comment bubbles.\nIn the plan REPL\'s flagged quotation mode, pass Quote, Term, or Inline directly\nto an operation with_ field. docx_review resolves the node and binds its source;\ncopying QuoteResult.text into a plain string loses that provenance boundary.\n\nExample:\nq = Quote("source.docx", at="89ABCDEF", select="The tenant must promptly pay the charge.")\nq.omit(" promptly")\nq.bracket("tenant", "Tenant")\nvalidated = await quote_validate(q)\nprint(validated.text)\nprint(validated.provenance)\n'
+REFERENCE = '\n# docxdriver Python REPL API — Version 1 (Python-authored plan)\n\n# BEGIN GENERATED OPERATION DOCS\n## Operations\n\nSelected from the core schema (`$defs.editOp.oneOf`) through the\ncapability manifest; field shapes, types, and enums are exactly the\nchecked-in schema’s. Every op dataclass has `to_dict()`, omitting\noptional fields whose value is `None`; constructors use `with_`/`as_`\nfor Python keyword collisions and `to_dict()` maps back to the schema\nfield names. Operations are addressed by the paragraph `id` attribute\nfrom `docx_read` (uppercase eight-digit hex) or a `$name` alias.\n\n### ClearFooter\n\n`ClearFooter(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit footer reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### ClearHeader\n\n`ClearHeader(kind: str | None = None, section: int | None = None)`\n\nRemove the explicit header reference for a section/kind (defaults: section 1, kind default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### CommentAdd\n\n`CommentAdd(at: str, text: str, occurrence: int | None = None, select: str | None = None)`\n\nAnchor a comment with `text` to the paragraph at `at`; omit `select` to comment the whole paragraph, or pass `select`/`occurrence` (1-based) to pin one exact span.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `text` | `str` | yes |\n| `occurrence` | `int | None` | no |\n| `select` | `str | None` | no |\n\n### CommentDelete\n\n`CommentDelete(comment_id: str)`\n\nDelete a comment by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n\n### CommentReply\n\n`CommentReply(comment_id: str, text: str)`\n\nReply to an existing comment; `comment_id` is the decimal id from a prior `comment_add` or a comments-kind read.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `text` | `str` | yes |\n\n### CommentSetStatus\n\n`CommentSetStatus(comment_id: str, status: str)`\n\nSet a comment\'s status to `open` or `resolved` by decimal `comment_id`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `comment_id` | `str` | yes |\n| `status` | `str` | yes |\n\n### DeleteEquation\n\n`DeleteEquation(at: str, equation: int | None = None)`\n\nDelete a current equation while preserving the paragraph. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Tracked mode keeps the equation recoverable until the deletion is accepted.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `equation` | `int | None` | no |\n\n### DeleteParagraphs\n\n`DeleteParagraphs(at: list)`\n\nDelete the paragraphs listed in `at` (tracked deletion by default).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n\n### EditTable\n\n`EditTable(action: dict, at: str)`\n\nDirect structural table edits using a source-bound table handle. action.kind is insert_rows/delete_rows/insert_columns/delete_columns/merge_cells/split_cell/delete; coordinates and counts are one-based. Insert/delete grid operations and merge require an unmerged rectangular grid. Split keeps content in the first resulting cell; merge concatenates content in row-major order. Rejects tracked mode and tables containing unresolved revisions, bookmarks, comments, fields or content controls. Delete the table instead of its final row or column.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `dict` | yes |\n| `at` | `str` | yes |\n\n### FormatParagraph\n\n`FormatParagraph(at: str, alignment: str | None = None, clear: list | None = None, first_line_indent: float | None = None, indent_left: float | None = None, indent_right: float | None = None, line_spacing: dict | None = None, space_after: float | None = None, space_before: float | None = None, style: str | None = None)`\n\nApply paragraph formatting to the paragraph at `at`: `style`, `alignment` (left/center/right/justify), signed `indent_left`/`indent_right`, signed `first_line_indent` (negative for hanging, zero for an explicit zero offset), `space_before`/`space_after`, `line_spacing` (dict with `mode` multiple/exact/at_least and `value`), or `clear`. Omitted properties are untouched; clear removes direct settings and inherits styles/defaults, winning over set. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `alignment` | `str | None` | no |\n| `clear` | `list | None` | no |\n| `first_line_indent` | `float | None` | no |\n| `indent_left` | `float | None` | no |\n| `indent_right` | `float | None` | no |\n| `line_spacing` | `dict | None` | no |\n| `space_after` | `float | None` | no |\n| `space_before` | `float | None` | no |\n| `style` | `str | None` | no |\n\n### FormatText\n\n`FormatText(at: str, select: str, bold: bool | None = None, clear: list | None = None, color: str | None = None, font_size: float | None = None, highlight: str | None = None, italic: bool | None = None, occurrence: int | None = None, strike: bool | None = None, subscript: bool | None = None, superscript: bool | None = None, underline: bool | None = None)`\n\nApply character formatting to an exact occurrence of `select` in the paragraph at `at`: boolean attributes (`bold`, `italic`, `underline`, `strike`, `superscript`, `subscript`), `color` (#RRGGBB), `highlight` (Word palette including none), `font_size` (points), `occurrence`, or `clear`. Omitted properties preserve source OOXML; false explicitly overrides inherited formatting (baseline for superscript/subscript). Clear removes the direct property and inherits styles/defaults, winning over set; superscript/subscript share one property. Formatting changes are always tracked.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `bold` | `bool | None` | no |\n| `clear` | `list | None` | no |\n| `color` | `str | None` | no |\n| `font_size` | `float | None` | no |\n| `highlight` | `str | None` | no |\n| `italic` | `bool | None` | no |\n| `occurrence` | `int | None` | no |\n| `strike` | `bool | None` | no |\n| `subscript` | `bool | None` | no |\n| `superscript` | `bool | None` | no |\n| `underline` | `bool | None` | no |\n\n### InsertParagraph\n\n`InsertParagraph(at: str, position: str, as_: str | None = None, style: str | None = None, with_: str | Inline | Quote | Term | None = None)`\n\nInsert a new paragraph before or after an anchor: paragraph id/alias (`at`) or body-level table number (`table:N` from markup); `with` is its text, `style` its style, and `as` names the new paragraph id (a `$name` alias).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `position` | `str` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n| `style` | `str | None` | no |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term | None` | no |\n\n### InsertTable\n\n`InsertTable(at: str, columns: int, position: str, rows: int, as_: str | None = None)`\n\nInsert a rectangular table before/after paragraph at, with rows and columns in 1..100. Direct mode only. Optional as creates a plan-local table alias for later formatting and structural edits.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `columns` | `int` | yes |\n| `position` | `str` | yes |\n| `rows` | `int` | yes |\n| `as_` (schema key `as`) | `str | None` | no |\n\n### ReplaceEquation\n\n`ReplaceEquation(at: str, mathml: str, display: bool | None = None, equation: int | None = None)`\n\nReplace a current equation using presentation MathML. Read await docx_read(path).equations for at and equation (1-based). Omit equation only when the paragraph has one. Display mode is preserved by default. Settle existing revisions before editing their equations.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `mathml` | `str` | yes |\n| `display` | `bool | None` | no |\n| `equation` | `int | None` | no |\n\n### ReplaceParagraph\n\n`ReplaceParagraph(at: str, with_: str | Inline | Quote | Term)`\n\nReplace the entire paragraph at `at` with `with`.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n\n### ReplaceText\n\n`ReplaceText(at: str, select: str, with_: str | Inline | Quote | Term, occurrence: int | None = None)`\n\nReplace an exact occurrence of `select` in the paragraph at `at` with `with`; `occurrence` picks the nth match (1-based).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `str` | yes |\n| `select` | `str` | yes |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `occurrence` | `int | None` | no |\n\n### ReviseText\n\n`ReviseText(edits: list, at: str | None = None, occurrence: int | None = None, within: str | None = None)`\n\nSeveral exact replacements inside one bounded scope; prefer the chainable `Revise(within, at=None, occurrence=None).replace(select, with_, occurrence=None, all=False)` builder. Scope: `within` (a phrase unique in paragraph `at`, or in the whole document when `at` is omitted; `occurrence` picks a repeated one), else the paragraph `at`, else the whole document. Each edit must match exactly once in the scope unless it sets `occurrence` or `all`. All edits resolve against the scope as it stands when the operation starts, must not overlap, and become separate minimal tracked changes.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `edits` | `list` | yes |\n| `at` | `str | None` | no |\n| `occurrence` | `int | None` | no |\n| `within` | `str | None` | no |\n\n### RevisionSettle\n\n`RevisionSettle(action: str, target: str)`\n\nAccept or reject tracked changes: `target` is a decimal revision id from `await docx_read(path, kind="revisions")` or `all`; `action` is `accept` or `reject`. Prefer the `AcceptRevision(target)` / `RejectRevision(target)` shorthands. Settling `all` also settles tracked changes made by earlier operations in the same plan, and later selectors address the settled text.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `action` | `str` | yes |\n| `target` | `str` | yes |\n\n### SetEvenAndOddHeaders\n\n`SetEvenAndOddHeaders(even_and_odd: bool)`\n\nEnable or disable distinct even-page headers/footers (`even_and_odd`); when true, `kind="even"` chrome applies to even pages.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `even_and_odd` | `bool` | yes |\n\n### SetFirstPageMode\n\n`SetFirstPageMode(enabled: bool, section: int | None = None)`\n\nEnable/disable first-page stories in a section (default 1) without removing stored stories. Tracked mode records a section-property snapshot; settle pending section changes before editing again.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `enabled` | `bool` | yes |\n| `section` | `int | None` | no |\n\n### SetFooter\n\n`SetFooter(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section footer chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetHeader\n\n`SetHeader(with_: str | Inline | Quote | Term, kind: str | None = None, section: int | None = None)`\n\nSet section header chrome from inner HTML (`with`); optional `section` (default 1) and `kind` (default/even/first).\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `with_` (schema key `with`) | `str | Inline | Quote | Term` | yes |\n| `kind` | `str | None` | no |\n| `section` | `int | None` | no |\n\n### SetList\n\n`SetList(at: list, format: str | None = None, level: int | None = None, levels: list | None = None, num_id: int | None = None, remove: bool | None = None, start: int | None = None)`\n\nAssign explicitly selected paragraphs to a new list (format defaults to decimal), continue an existing num_id, or remove membership with remove=True. level is 0..8; start is positive and creates an isolated restarted instance. Optional levels defines 1..9 per-level format/label/start/restart_after, signed indent_left/indent_right/first_line_indent and marker_bold/marker_italic/marker_font/marker_color for a new list. Label placeholders reference this or ancestor levels (%1..%9). Existing definitions are never restyled. Membership changes are tracked; settle pending paragraph changes first. Definitions remain after rejection for safe reference restoration.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `at` | `list` | yes |\n| `format` | `str | None` | no |\n| `level` | `int | None` | no |\n| `levels` | `list | None` | no |\n| `num_id` | `int | None` | no |\n| `remove` | `bool | None` | no |\n| `start` | `int | None` | no |\n\n### SetPageMargins\n\n`SetPageMargins(bottom: float | None = None, footer: float | None = None, gutter: float | None = None, header: float | None = None, left: float | None = None, right: float | None = None, section: int | None = None, top: float | None = None)`\n\nSet selected nonnegative page margins in points for a section (default 1): top/right/bottom/left/header/footer/gutter. Omitted values are preserved. Like existing header/footer setters, margin changes are direct even in tracked plans.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `bottom` | `float | None` | no |\n| `footer` | `float | None` | no |\n| `gutter` | `float | None` | no |\n| `header` | `float | None` | no |\n| `left` | `float | None` | no |\n| `right` | `float | None` | no |\n| `section` | `int | None` | no |\n| `top` | `float | None` | no |\n\n### SetSectionLayout\n\n`SetSectionLayout(break_type: str | None = None, column_separator: bool | None = None, column_spacing: float | None = None, column_widths: list | None = None, columns: int | None = None, height: float | None = None, orientation: str | None = None, page_number_continue: bool | None = None, page_number_format: str | None = None, page_number_start: int | None = None, page_size: str | None = None, section: int | None = None, width: float | None = None)`\n\nSelectively set section layout (section defaults to 1): page_size letter/legal/a4/a3/a5 or paired width/height in points; orientation portrait/landscape normalizes dimensions. Columns 1..45 with column_spacing, column_widths and column_separator; break_type nextPage/continuous/oddPage/evenPage/nextColumn; page_number_format, page_number_start or page_number_continue=true. Omission preserves properties; tracking snapshots section properties while preserving story relationships. Pending property changes must be settled first.\n\n| Field | Type | Required |\n| --- | --- | --- |\n| `break_type` | `str | None` | no |\n| `column_separator` | `bool | None` | no |\n| `column_spacing` | `float | None` | no |\n| `column_widths` | `list | None` | no |\n| `columns` | `int | None` | no |\n| `height` | `float | None` | no |\n| `orientation` | `str | None` | no |\n| `page_number_continue` | `bool | None` | no |\n| `page_number_format` | `str | None` | no |\n| `page_number_start` | `int | None` | no |\n| `page_size` | `str | None` | no |\n| `section` | `int | None` | no |\n| `width` | `float | None` | no |\n\n# END GENERATED OPERATION DOCS\n\n## Scoped revisions\n\n`Revise(within=None, at=None, occurrence=None)` builds one `ReviseText`\noperation; chain `.replace(select, with_, occurrence=None, all=False)` for each\nchange. The scope bounds every `select`, so short selectors stay unambiguous\nin long documents and each change becomes a minimal tracked change:\n\n    # unique phrase, no paragraph id needed:\n    Revise("the tenant shall pay rent within thirty days").replace("thirty", "sixty").replace("rent", "the rent")\n    Revise(at="2673269E").replace("Tenant", "Lessee", all=True)  # whole paragraph\n    Revise("Section 4(b)", at="2673269E", occurrence=2).replace("4(b)", "4(c)")\n    Revise().replace("Acme Corp.", "Acme, Inc.", all=True)       # whole document\n\n`within` must occur exactly once in its paragraph (`at`) or document unless\n`occurrence` picks one. Each `select` must occur exactly once in the scope\nunless it passes `occurrence` or `all=True`. All selectors resolve against the\nscope as it stands when the operation starts, so later replacements never see\nearlier ones; overlapping selections are rejected.\n\n`AcceptRevision(target)` and `RejectRevision(target)` build `RevisionSettle`\noperations; `target` is a revision id from `await docx_read(path, kind="revisions")`\nor `"all"`. Put settle operations first: `"all"` also settles tracked changes\nmade earlier in the same plan.\n\nEvery operation dataclass has `to_dict()`, omitting optional fields whose\nvalue is `None`; `Plan.to_dict()` returns `{"author": ..., "change_mode": ..., "ops": [...]}`.\n\nTracked plain-text replacements automatically compute word-level redlines in\nReplaceText, ReviseText, and ReplaceParagraph. Unchanged words retain their\nformatting; adjacent changed words form one deletion followed by one insertion.\nRich replacements retain whole-selection tracking to apply their formatting.\n\n## Host functions\n\n- `await docx_create(path: str, html: str)`\n- `await docx_read(path: str, view: str = "markup", kind: str = "document") -> ReadResult | dict` — complete HTML\n  markup and a current equations-address listing (at, equation, display, editable) by default (`kind="document"`); `kind="comments"`, `"styles"`, `"revisions"`, or `"assets"` returns the\n  core listing object (and a second positional of `comments`/`styles`/`revisions` is treated as `kind`).\n- `await docx_find(path: str, query: str, ignore_case: bool = False) -> list` — core find match\n  records verbatim (`{index, id?, text, style?, number?}` per matching paragraph; `id` is\n  the canonical uppercase paragraph address)\n- `await docx_help(topic: str | None = None) -> str`\n- `await docx_review(path: str, plan: Plan) -> ReviewResult | None` — validates the complete plan and returns `commit_key` plus bounded per-operation `edits` with affected markup context; returns `None` when validation is blocked\n- `await docx_commit(commit_key: str)` — commits the immutable reviewed plan; the key owns the\n  target file and plan\nReview does not write the target. Review and commit must happen in separate later\nPython calls; changing the plan requires a new review.\n\n## Discovering paragraphs\n\n`docx_find` plus `docx_read` are the supported discovery workflow:\nfind returns core match records to locate paragraphs, and reads return\nstructural markup. Operations stay addressed\nby the markup-view paragraph `id`:\n\n    matches = await docx_find("contract.docx", "Payment is due within")\n    for m in matches:\n        print(m["id"], m["text"])\n    markup = (await docx_read("contract.docx")).markup\n\nReading `view="final"` or `view="original"` is allowed for analysis, but\nreview plans remain source-bound to the exact bytes and paragraph ids of the\ncurrent `markup` view.\n\n## Computing operations with regex\n\n`re` is pre-imported and `ReadResult.markup` is an ordinary string, so you can\ninspect it and build operations in Python loops. Return the full ReadResult or\nprint its full markup and semantic metadata when reading; prefer complete document\ncontext. Named DOCX style IDs appear in data-docx-style and map one-to-one to\nReadResult.styles (resolved CSS keyed by style ID). Presentation rules appear\nin data-docx-css and map to ReadResult.css. Both catalogs are omitted from the\ndefault display; inspect result.styles or result.css to read their definitions;\nwhen authoring a fragment, use equivalent inline formatting rather than copying\nan unresolved class. Image aliases map to canonical assets in ReadResult.assets.\nReadResult.selection_space describes comment selectors; ReadResult.selections\nprovides exact text for paragraphs where generated content or revisions make\nHTML text ambiguous:\n\n\n    original = (await docx_read("contract.docx")).markup\n    ops = []\n    for m in re.finditer(r\'<p id="([0-9A-F]{8})"[^>]*>([^<]*?)</p>\', original):\n        if "Payment is due within" in m.group(2):\n            ops.append(ReplaceText(at=m.group(1), select=m.group(2),\n                                   with_=re.sub(r\'within \\d+ days\', \'within 45 days\', m.group(2))))\n    plan = Plan(author="Pi", operations=ops)\n    review = await docx_review("contract.docx", plan)\n    if review is not None:\n        for edit in review.edits:\n            print(edit["index"], edit["context"])\n        # ...later python call...\n        await docx_commit(review.commit_key)\n\n`select` must match the paragraph\'s current visible text exactly; on a document\nwith pending tracked changes, grep the `view="final"` projection instead.\n\n## Example\n\n    original = (await docx_read("contract.docx")).markup\n    plan = Plan(author="Pi", change_mode="track", operations=[\n        ReplaceText(at="2673269E", select="thirty days", with_="sixty days"),\n        FormatText(at="2673269E", select="sixty days", bold=True),\n    ])\n    review = await docx_review("contract.docx", plan)\n    # Inspect review.edits before committing in a later Python call.\n    if review is not None:\n        print(review.commit_key)\n\n\nUse await quote_find(source, query) to obtain the paragraph id and exact source text.\nCreate Quote(source, at, select, occurrence=1, style="double"), where select is one contiguous,\nverbatim source span. Adapt it with .omit(exact_source_text) and\n.bracket(exact_source_text, replacement). Adaptation selectors always refer to\nthe original span; overlaps fail. Finish with await quote_validate(q). Only the host\nconstructs QuoteResult.text, including curly double quotation marks by default\n(style="single" or style="none" are also available). Its provenance binds the source SHA-256, paragraph\nSHA-256, paragraph id, offsets, original span, and every adaptation.\n\nRaw quotation marks in ordinary authored text are lint errors. For a\nnon-quotational mention such as the word quotation, use\nawait term_render(Term("quotation")); its quote marks are host-created and its\nprovenance is classified as kind="term" rather than a source quotation.\nFor authored document content, prefer Inline([plain_text, Term(...), Quote(...)]).\nawait inline_validate() automatically lints every plain-text part before the host\nrenders structured nodes. The default policy is error; comment must be chosen\nexplicitly and returns warning spans that require protected comment bubbles.\nIn the plan REPL\'s flagged quotation mode, pass Quote, Term, or Inline directly\nto an operation with_ field. docx_review resolves the node and binds its source;\ncopying QuoteResult.text into a plain string loses that provenance boundary.\n\nExample:\nq = Quote("source.docx", at="89ABCDEF", select="The tenant must promptly pay the charge.")\nq.omit(" promptly")\nq.bracket("tenant", "Tenant")\nvalidated = await quote_validate(q)\nprint(validated.text)\nprint(validated.provenance)\n'