Read a one-call document overview: paragraph/table/footnote/comment/revision counts, sections, and package parts. Documents open in Word are read live (same key names; live adds 'words' from Word's own ComputeStatistics counter plus track_revisions, and omits the part list). Read-only.

List every heading with its body paragraph index and level. Detects both heading systems: built-in Heading styles AND w:outlineLvl overrides (direct or style-inherited, the academic-template pattern on Normal-styled paragraphs); detected_via on each entry names which. Documents open in Word are read live (same flat-list shape). Read-only.

Read body paragraphs as [{index, text, style, ...}]; every paragraph reports its effective style, including the default (usually Normal). start/end slice by paragraph index (0-based, end EXCLUSIVE); contains filters to matching paragraphs. include_textboxes=True appends text-box content as labeled extra entries (source 'textbox', box_index addressing set_textbox_text) without touching body indices; file-mode only. Documents open in Word are read live with the same shape (live styles are Word's localized display names; file styles are style ids). Equations are invisible here (list_equations reads those).

Find text in paragraphs and table cells; returns locations + context. include_textboxes=True also searches text-box/shape content, returned as clearly-labeled extra matches (source 'textbox' with box_index) without affecting body match entries or paragraph indices; file-mode only. Documents open in Word are searched live (current in-memory state, same flat-list shape; live additionally reports matches inside content controls as labeled in_sdt entries, and caps at 500 matches with a trailing truncated sentinel entry).

List the styles defined in the document: id, name, type, based_on, plus each style's EXPLICITLY defined paragraph_formatting and character_formatting in the exact shape define_style accepts (template cloning is one read + one define). Inherited values are not synthesized; follow the based_on chain. Exact/atLeast line spacing and theme font/color references have no define_style representation and are omitted. Read-only.

Count words/characters/paragraphs, total and per heading section. Documents open in Word are counted live via Word's own statistics engine (ComputeStatistics, the status-bar number); file mode counts whitespace tokens, so the two can differ by a few words on identical content. Live per-section counts are best-effort mirrors of the file-mode logic. For journal counts that exclude references, captions, or other zones, use word_count_with_exclusions. Read-only.

Cross-check APA in-text citations against the reference list in both directions: cited-but-not-listed (serious) and listed-but-never-cited (review). Heuristic flagging: results are review candidates, not verdicts. Read-only.

Run a quick structural check: the package opens, footnotes/endnotes are consistent, and field begin/end markers balance. Returns {package_ok, notes, fields_balanced, field_begins, field_ends}. For the deep multi-check health report (relationships, orphan parts, undefined styles, bookmarks, images), use diagnose_document; for Word's own verdict use com_validate_opens_clean. Read-only.

Create a new blank .docx file, optionally setting the title core property. Refuses to overwrite an existing file (use copy_document with overwrite=True for that). Parent directories are created automatically. Populate the document afterward with insert_paragraphs, create_table, define_style, and other tools.

Copy a document byte-for-byte, e.g. to a new DTG-stamped filename before editing (create_snapshot names such a copy for you; this tool takes an explicit dest_path). Refuses an existing dest_path unless overwrite=True; an overwritten destination's previous content rotates into its .ks4w-backups prev slot first, so the overwrite is undoable via manage_backups restore.

Manage the automatic backups under the hidden .ks4w-backups/ folder next to each mutated document: two stable slots per document, prev (state before the most recent mutation) and anchor (session start). Snapshots from create_snapshot are permanent keepers this tool never touches.

action='list': slot files with sizes and mtimes, legacy .bak- files from the pre-v1.6 scheme, and orphaned slot folders whose source document is gone; give file_path for one document or directory for a folder.

action='restore': overwrite file_path with a backup; source is 'prev', 'anchor', or a legacy .bak- path. The current content rotates into prev FIRST, so a restore is itself undoable. Refuses documents open in Word; the payload is validated before the atomic replace.

action='purge': delete backups; scope: 'legacy', 'orphans', or 'slots'. dry_run defaults to TRUE (report only); dry_run=False deletes. Exact paths and sizes are reported either way.

Batch find/replace, safe across Word's fragmented runs. Each item: {find, replace, regex?}; scope: body | footnotes | headers | all. max_replacements aborts, changing nothing, when total matches would exceed it: set it for broad regexes (preview_replace dry-runs this tool and yields the count). track records each replacement as a tracked change by author. Siblings: replace_formatted replaces only text with specific formatting; replace_paragraph_text rewrites one whole paragraph by index. Live edits appear immediately as one Ctrl+Z step, unsaved until the user saves; the live result adds "live": true and skip counters, and literal finds beyond Word's ~255-char limit are handled automatically. Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live.

Insert paragraphs ({text, style?, formatting?}) at ONE position: after_index | before_index | after_anchor | at_end. Anchors match a paragraph's PLAIN text (write '&', never the XML entity '&') and must be unique; heading text recurs in body prose, so prefer index addressing for structural work. On a fresh document, index 0 addresses the implicit empty paragraph. inherit_format=True clones the anchor paragraph's direct formatting onto the inserted paragraphs (a reference entry matches its neighbors' hanging indent and font in one call); with before_index/at_end use copy_format_from= instead (mutually exclusive). Explicit per-item style/formatting wins; track records tracked insertions by author. Format cloning is file-mode only. Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live.

Delete body paragraphs start..end (0-based, INCLUSIVE; end defaults to start). Refuses ranges that cut through a field or carry a section break. Deleting every paragraph leaves one empty paragraph behind (a document always keeps one). track marks tracked deletions by author instead of removing (result key deleted_tracked). Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live.

Replace one paragraph's full text, keeping style and base formatting. IMPORTANT: paragraph indices SHIFT after insert/delete operations - pass expect (a substring the target paragraph currently contains) to refuse instead of silently hitting the wrong paragraph, and verify the returned replaced_text (the old text) matches what you meant to replace. For text-anchored replacement immune to index shifts, use search_and_replace; this tool is the natural fallback when a find string would exceed live search_and_replace's length limit (no limit here). Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live. Live edits leave the paragraph mark untouched (style and section breaks survive); paragraphs carrying tracked revisions are refused live - accept/reject first.

Insert a NEW heading paragraph (level 1-9; Heading styles auto-created if missing) positioned by after_index, after_anchor, or at_end. Anchors match plain paragraph text, and heading text recurs in body prose, so prefer after_index for structural work. To restyle an EXISTING paragraph use apply_style; to shift existing heading levels use change_heading_level. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a page break after body paragraph after_index (0-based). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Apply character formatting to a text range. formatting keys: bold, italic, underline, strike, font, size_pt, color, highlight, superscript, subscript, small_caps, all_caps, hidden, double_strike, char_spacing_pt, kerning_pt, position_pt, language, east_asian_language (BCP-47; ko/ja/zh go in east_asian_language, Word's East-Asian proofing slot; live maps tags to LCIDs, unmapped tags are file-mode only). Target: paragraph_index + find (substring), find alone (occurrence picks the match), or the whole paragraph. For a named character style use apply_character_style. Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live.

Set paragraph formatting on a batch of paragraphs (0-based indices). Keys: alignment, space_before_pt, space_after_pt, line_spacing, indent_left_pt, indent_right_pt, first_line_indent_pt, keep_with_next, outline_level. outline_level (0-8, 0 = top; null removes the override) sets w:outlineLvl without touching style or visual formatting: the way to give template headings (Normal-styled, direct-formatted) a place in Word's navigation pane and TOC harvesting, where apply_style would change their look. get_paragraph_format is the matching reader. Documents open in Word are edited live (shading, borders, and tab_stops are refused live; all other keys work). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save.

Apply a paragraph style (by id or name) to a batch of paragraphs, changing their full look; Heading1-9 are auto-created when missing. To give a paragraph an outline level WITHOUT changing its appearance use set_paragraph_format's outline_level; to promote/demote existing built-in headings use change_heading_level. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a bulleted or numbered list with real bullet/number glyphs (numbering.xml infrastructure created as needed). items: strings or {text, level} dicts (level 0-8 nests); kind: bullet | number. Each call is an independent list, so numbering restarts at 1. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Numbered and bulleted list paragraphs grouped by numbering instance, with each item's nesting level (0-based), numbering style (bullet or decimal/lowerLetter/lowerRoman/...), and text. Useful for verifying list restarts and nesting after insert_document or add_list. Read-only.

Change text case: transform is upper | lower | title | sentence. Target: paragraph indices, or every occurrence of find (case-insensitive). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

List tables with dimensions, merge flags, and header previews; the position is the 0-based table_index the other table tools take. Read-only.

Read one body-level table in full: every cell's text, the merge map (gridSpan for horizontal, vMerge for vertical), column widths, and the table style. table_index is 0-based in list_tables order. For tables nested inside a cell, use get_nested_table instead. Use set_cells/set_cells_block to write cell values. Read-only.

Create a table from 2D string data with single-line borders. To build a table from a CSV/JSON file, use import_table. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete a whole table (table_index from list_tables). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert rows before row at (at = row count appends), copying structure and formatting from an existing row (copy_format_from). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete rows start..end (inclusive). Vertical merges are re-rooted, not broken. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert grid columns before position at (at = column count appends). Merge-aware: inserting inside a merged cell widens it. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete grid columns (0-based list). Merge-aware: merged cells shrink, single cells are removed, the grid stays consistent. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Write many table cells in ONE call: edits = [{row, cell, text}]. Use this for any multi-cell edit instead of per-cell calls; set_cells_block writes a contiguous 2D block instead. track records tracked changes by author; the result reports cells_written. Live mode refuses vertically merged tables (the file-based path is merge-aware). Auto-backup in file mode: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Documents open in Word are edited live.

Write a 2D block of values starting at (origin_row, origin_cell); for scattered single-cell edits use set_cells. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Format table cells in bulk. targets: [{row, cell?}] ({row} alone = whole row); formatting: shading, bold, italic, alignment, valign, padding_pt. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Merge a rectangle of cells (grid coordinates, inclusive). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Split a merged cell back into single cells (horizontal and vertical). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set every grid column width in points (one value per grid column). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Apply a named table style: TableGrid (bordered) | PlainTable | BandedTable (alternating shading); definitions are injected when missing. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Sort data rows by a column (CELL index, 0-based). Refused when vertical merges make rows interdependent. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Split a table into two at a row (that row starts the new table). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Repeat the first N rows as the table header on every page. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Read a table nested inside a cell of a body-level table: rows, cells, text, and merge info, exactly like get_table but addressed by the host table_index, host row/cell, and nested_index (0 when the cell holds one nested table; higher for multiple). Use set_nested_cells to write. Read-only.

Write cells inside a NESTED table (edits = [{row, cell, text}]; the host cell is addressed by table_index/row/cell, nested_index picks among several). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every footnote in the document: id, the body paragraph where the reference appears (display position), and the note's full text. Use add_footnote/edit_footnote/delete_footnote to modify; validate_notes to check integrity. Read-only.

Every endnote in the document: id, the body paragraph where the reference appears (display position), and the note's full text. Use add_endnote/edit_endnote/delete_endnote to modify; validate_notes to check integrity. Read-only.

Add a footnote anchored after the occurrence-th match of anchor_text; creates all note infrastructure (parts, styles, superscript) if the document has none. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Add an endnote anchored after anchor_text (same mechanics as add_footnote). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Rewrite a footnote's text, addressed by note_id or 1-based display position (exactly one). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Rewrite an endnote's text, addressed by note_id or 1-based display position. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete a footnote: the definition AND the body reference mark, always both. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete an endnote: the definition AND the body reference mark. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Check footnote/endnote structural integrity: whether note definitions match their body references and whether orphan definitions exist. ok=true means no corruption; needs_cleanup=true means orphan note definitions were found (run cleanup_orphan_notes to purge them). Use list_footnotes/list_endnotes to see note contents. Read-only.

Remove footnote/endnote definitions no body reference points to. Content-deleting tools already do this automatically; use this for documents that arrived with orphans. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Bookmark a text range (the target add_cross_reference points at). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every user-visible bookmark: name, the paragraph index where it starts, and the bookmarked text. Bookmarks serve as targets for add_cross_reference and as stable anchors for navigation. Internal bookmarks (TOC, field-generated) are excluded. Read-only.

Insert a cross-reference field after anchor text. kind: 'page' (page number) or 'text' (the bookmarked text); Word computes the value on field update. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a numbered caption (SEQ field), 'Table N: text', above/below a table or at an anchor. label: Table | Figure | Equation. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Turn existing text (occurrence-th match of anchor_text) into an external hyperlink. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a Table of Contents (SDT-wrapped TOC field); levels like '1-3' picks heading depth. Page numbers appear after Word updates fields: automatically on next open (update_on_open) or immediately via com_refresh_fields. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Read every TOC-family field (main TOC, List of Tables, List of Figures) and its cached entries: title, page number, heading level. The cached text reflects the state at last field update; refresh with com_refresh_fields (requires Word) then re-read. Use insert_toc/ insert_caption_list/delete_toc to manage TOCs. Read-only.

Delete one TOC-family field by index (read_toc's tocs list order). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Toggle 'update all fields on next open' (one-shot; Word clears it after updating). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a List of Tables/Figures/Equations built from add_caption SEQ entries. label: Table | Figure | Equation; default title 'List of Xs'. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Convert footnotes to endnotes or back. direction: footnotes_to_endnotes | endnotes_to_footnotes; give note_id or position for ONE note, neither for ALL. Word renumbers automatically. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Add a Word-native bibliography source to the document store. tag = unique citation key; source_type: JournalArticle | Book | BookSection | Report | InternetSite | ...; authors/editors: [{last, first, middle?}] or [{corporate}]. Cite with insert_citation; render the list with insert_bibliography. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Bibliography sources stored in the document's XML source store: tag, type (JournalArticle, Book, ...), author, title, year, and all other fields. These feed insert_citation and insert_bibliography when using Word's native citation system (not Zotero/Mendeley/EndNote). Run detect_citation_system first on unfamiliar documents. Read-only.

Delete a bibliography source by tag (refused while cited unless force=True). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set the style Word-native CITATION and BIBLIOGRAPHY fields render in: APA | Chicago | MLA | IEEE | Turabian | Harvard - Anglia | GB7714 | GOST - Name Sort | GOST - Title Sort | ISO 690 - First Element and Date | ISO 690 - Numerical Reference | SIST02. Affects Word-native fields only: manager citations restyle in their own manager, plain-text citations take convert_citation_style. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a CITATION field for a stored source (tag from add_source / list_sources) after the occurrence-th anchor_text match; renders in the document citation style on field update (placeholder until then). pages, prefix/suffix, and the suppress flags shape the rendered cite. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert the BIBLIOGRAPHY field: Word generates the full styled reference list from the source store on field update. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Mark a location for the index (invisible XE field at the anchor). see='other entry' writes a cross-reference instead of a page number. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every XE index entry marked in the document: main text, sub-entry, see/see-also references, and the paragraph where each appears. Use mark_index_entry to add entries and insert_index to generate the compiled index. Read-only.

Insert the INDEX field compiling all XE entries with page numbers (generated when Word updates fields). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Move a heading and its ENTIRE section (content and tables until the next same-or-higher heading) before/after another heading or to the end. Sections are addressed by exact heading text; only headings are matched, so body prose repeating the words does not collide. Refuses moves that would cut fields or section breaks. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Headings with each section's body-element count, paragraph count, and table count: the planning aid for move_section (shows what will travel with each heading) and for insert_document/copy_table (shows body-item indices at section boundaries). Read-only.

Restyle this document to match a reference document: styles, theme, fonts, layout settings, optionally page geometry. This is also the import-styles-from-another-document tool: style definitions are remapped by name, unmatched styles preserved, content untouched. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set core document metadata (File > Info): title, author, subject, keywords, category, comments; only the parameters given change. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Create or replace a custom style (paragraph or character) with full formatting control; get_styles returns existing definitions in this exact input shape, so cloning a style is one read + one define. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Apply a named character style to a text range (occurrence-th match of find). For direct formatting without a style, use format_text. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set accessibility alt text for an image (image_index from list_images). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Add a text watermark behind the text on every page (all header parts; compatible with Word's own Remove Watermark command). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Remove watermark shapes from every header. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Restrict editing: edit = readOnly | comments | trackedChanges | forms. trackedChanges forces every edit by the recipient to be tracked (the send-to-committee mode). Password hashing is Word-compatible SHA-512; this is NOT encryption (com_save_with_password encrypts). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Lift the editing restriction set by set_document_protection. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Current document protection state: mode (none, readOnly, comments, trackedChanges, forms), whether a password is set, and whether formatting restrictions are active. Use set_document_protection to enable and remove_document_protection to disable. Read-only.

Every header and footer part across all sections: text content, whether it contains a PAGE-number field, and the part type (default, first page, even page). Use set_header/set_footer to write them and setup_chapter_headers for per-chapter running headers. Read-only.

Set a section's header text. ref_type: default | first | even. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set a section's footer text, optionally with a page-number field. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Add page numbers (PAGE field) to the header or footer; x_of_y renders 'Page N of M'. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set multi-column text layout for a section (equal widths, or explicit widths_pt per column; separator draws a line between columns). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set the page-number FORMAT per section: lowerRoman for front matter, decimal restarting at 1 for the body, upperRoman, letters, etc. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Set manuscript line numbering for a section (journal submissions). restart: continuous | newPage | newSection; remove=True clears it. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every section: page width/height, orientation (portrait/landscape), all margins, and header/footer part references. Use set_section_properties to change page geometry and add_section_break to create new sections. Read-only.

Set page size, orientation, and margins for one section. Every response carries the section's full state; call with no change parameters to read the current values. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a section break after a body paragraph: nextPage | continuous | evenPage | oddPage. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert an inline image (PNG/JPEG/GIF/BMP/TIFF), aspect ratio kept. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every inline image: index (use with resize_image, replace_image, set_image_alt_text), display size in points, native pixel dimensions, effective DPI, alt text, and the media part path. For print-quality checks, use check_image_resolution instead. Read-only.

Resize an inline image to width_pt, aspect ratio kept (image_index from list_images). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Swap an image's file, keeping placement and display size. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a native, theme-following Word chart built from data (no image rendering). chart_type: 'bar' (horizontal), 'column' (vertical), 'line', 'pie', or 'scatter'. data shapes: rows like import_table ([["", "S1", "S2"], ["Alpha", 4.3, 1.2], ...]; first row series names, first column categories), a dict {"categories": [...], "series": [{"name", "values"}]} (scatter: {"series": [{"name", "x", "y"}]}), or a .csv/.json file path. The chart part carries literal data caches AND a matching embedded workbook, so it renders everywhere and right-click > Edit Data works in Word. Size defaults to 6.0 x 3.5 in (width_pt/height_pt override); position with at most one of after_index/after_anchor/at_end (default document end); colors takes one hex per series (default: theme accents). Refused: other chart types (3D/area/doughnut/radar/...), ragged or non-numeric data, multi-series pie. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Replace the data of an existing bar/column/line/pie/scatter chart in place (chart_index from list_charts): literal caches, range formulas, and the embedded workbook are rewritten together, so rendering and Edit Data stay in sync; formatting and styles are preserved. data takes the same shapes as add_chart and must keep the existing series COUNT (point count may change); series_names renames. Refused with the reason named: chartex/modern, combo, 3D/area/doughnut/radar/surface/stock/bubble, multi-level categories, series-count changes, ragged data. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Enumerate every chart in the document body, in document order. Each entry reports index (use it with update_chart_data), chart part name, plot type (barChart/lineChart/pieChart/scatterChart/... or 'chartex' for modern charts like treemap/sunburst/waterfall), title, series names, point count, size in points, whether an embedded data workbook exists, and supported_for_update with a reason when updating is refused (chartex, combo, 3D/area/radar/..., multi-level categories). Read-only against the document.

Comments with authors, anchored text, threading, resolved state. Documents open in Word are read live (same entry shape; live ids are the comment's position, not the XML id).

Add a comment on a text range (threaded-comment infrastructure created as needed). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Add a threaded reply to an existing comment (comment_id from get_comments). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Mark a comment thread resolved, or reopen it with done=False. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete a comment and its replies, including all body markers. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every tracked change: type (insertion, deletion, move, format change), author, date, the affected text, and paragraph location. Filter by author to see one reviewer's edits. Use accept_revisions/ reject_revisions to resolve, or revision_summary/revision_analytics for aggregate views. Read-only.

Summarize tracked-change counts by author and type. For word-level analytics and per-section concentration use revision_analytics. Read-only.

Accept tracked changes: all of them, or one author's only. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Reject tracked changes: all of them, or one author's only. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Check whether Word is running and what state it is in: interactive_state (ready, busy if a dialog is open, blocked if a long operation is running, not_running), and a list of open documents with per-document dirty flag and autosave state. Use before live editing to confirm Word is responsive, or to discover which files are locked. No file_path needed. Read-only.

Insert text at the user's cursor position in the open document (main body text only; headers/footers/footnotes not supported). The cursor position is read once and never moved; the user's selection is untouched. newline=True ends the insertion with a paragraph break. Use insert_paragraphs for index-addressed insertion instead. Requires the document to be open in Word.

Scroll the user's Word window to show a location without selecting anything or moving their cursor (useful after a live edit to show the user what changed). Target by find text (first match) or body paragraph_index. The document must be open in Word. Read-only.

Turn track changes on or off on the open document. This is a persistent state change (the document remembers the setting), unlike the track flag on edit tools like search_and_replace which auto-restores. Returns the previous state so you can restore it later. The document must be open in Word.

Recovery tool: if a crashed live edit left the user's Word frozen (ScreenUpdating off), alerts suppressed, or an undo record open, a fresh attach fixes all three. Safe to run anytime; reports what it fixed.

Update every field in the document (TOC page numbers, PAGEREF, NUMPAGES, SEQ, cross-references) via an invisible Word instance, giving correct page numbers and computed values immediately. Use after insert_toc/insert_index/insert_caption_list for real page numbers, or after any edit that shifts pages. The source file is modified in place. Requires Word installed.

Export the document to PDF via an invisible Word instance with full fidelity (fields resolved, footnotes, TOC, headers/footers, images). pdf_path defaults to the source filename with .pdf extension in the same directory. The source .docx is never modified. Requires Word installed.

Word-native compare of two documents (e.g. two DTG versions of a draft): produces a NEW file where every difference is a tracked change, plus a revision summary. Inputs are untouched. Default output: _COMPARE.docx.

Concatenate whole documents in order into ONE new file via Word, full fidelity (styles, footnotes, numbering); section breaks between parts keep per-chapter headers/numbering possible. To insert a document INTO an existing one at a chosen position with style reconciliation, use insert_document; for a single table, copy_table.

Combine two reviewers' tracked changes into one document (both sets of revisions with their original attributions preserved). Use when two people edited copies of the same draft and you need a unified redline. For diffing two versions to discover what changed, use com_compare_documents instead. Output defaults beside the original. Requires Word installed.

Tell the user's running Word to SAVE a document it has open, so file-based tools can read the current state. Use before diagnose_document or any file-mode tool that needs the latest edits flushed to disk. Does nothing if Word is not running or the file is not open. Requires Word installed.

Tell the user's running Word to CLOSE an open document, releasing the file lock so file-based tools can edit it. Saves by default; pass save=False to discard unsaved changes. Use when switching from live editing to file-mode tools. Requires Word installed.

Word's own spelling and grammar error lists with surrounding context: each error, its type (spelling/grammar), the sentence containing it, and suggested corrections. Useful as a review aid before submission (note: proper nouns and technical terms appear as spelling errors). Requires Word installed; opens an invisible instance. Read-only.

Word's own readability statistics via COM: Flesch Reading Ease, Flesch-Kincaid Grade Level, word/sentence/paragraph counts, and averages. Requires Word installed; opens an invisible instance to compute the statistics. Read-only.

Save an ENCRYPTED copy requiring a password to open (real AES encryption applied by Word, unlike document protection which is an editing restriction). output_path defaults to the same file; a different path saves a new encrypted copy. Requires Word installed; opens an invisible instance to apply the encryption.

Run the definitive corruption check: open the file in an invisible Word instance and report clean/fail. The Word-verdict companion to validate_document / diagnose_document.

Check every REF/PAGEREF cross-reference against the bookmarks that actually exist: broken refs (target missing; renders as an error in Word), bookmarks nothing references (informational), and plain-text references like 'see Figure 3' that match no caption or heading number (heuristic review candidates). Paragraph indices included for every finding. Read-only.

Check that every body-level table and image has an adjacent caption paragraph with a SEQ number field, report the ones missing captions with locations, and flag mixed numbering conventions (sequential "Figure 3" vs chapter-relative "Figure 4.2") per label.

Prepare a manuscript for submission in one call: accept all tracked changes (every author), delete all comments including the comments-family parts, and scrub identifying metadata (author, last-modified-by, company; title kept unless keep_title=False). Content is never removed: footnotes, fields, and citations all stay. Refuses protected documents rather than delivering a half-clean file. Reports what was done, what was deliberately left (rsids), and what remains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Inventory every Zotero, EndNote, and Mendeley field in the body, footnotes, and endnotes: manager, kind (citation or bibliography), location, cached rendered text, and whether the field markers are still intact (broken pairs are reported loudly; they disconnect the citation from its manager). Mendeley/EndNote support is preservation-only: their fields survive edits, but this server cannot insert or generate them (Zotero insertion exists: insert_zotero_citation). Read-only.

Check reference-manager citations after an edit: counts by manager and kind plus an ok flag that goes False on any broken or stray field marker. Run it after editing a document containing Zotero, EndNote, or Mendeley citations (the latter two are preservation-only: fields survive edits, no insertion). Read-only.

Validate the document against a formatting ruleset (university dissertation guide, journal style sheet). Every rule key is optional; unknown keys are rejected with the allowed list. Example ruleset:

{"page": {"margins_pt": {"top": 72, "bottom": 72, "left": 90, "right": 72}, "tolerance_pt": 1, "size": "letter", "orientation": "portrait"}, "fonts": {"allowed": ["Times New Roman"], "body_size_pt": 12}, "line_spacing": {"body": 2.0}, "headings": {"max_skip": 0, "required_first_level": 1}, "page_numbering": [{"section": 0, "format": "lowerRoman"}, {"section": 1, "format": "decimal", "restart_at": 1}], "required_headings_in_order": ["Abstract", "Acknowledgments"]}

Returns {compliant, violations: [{rule, expected, found, location, severity}], unverified, rules_checked}. Fonts/sizes/spacing resolve through explicit formatting, the basedOn chain, and docDefaults; theme-indirected fonts land in 'unverified', never guessed. Read-only.

Brand-guide compliance: the same engine and ruleset schema as check_template_compliance, plus a colors rule:

{"fonts": {"allowed": ["Georgia", "Arial"]}, "colors": {"allowed_hex": ["1F4E79", "C00000"]}}

colors checks explicit run color values (w:color) in body text against the allowed palette; hex comparison ignores case and a leading '#'. Theme-indirected colors go to "unverified". Read-only.

Audit accessibility, read-only: heading hierarchy (skipped levels, empty headings, no Heading 1), images missing alt text, tables whose first row is not a repeating header, low-contrast text (explicit color vs explicit run background below WCAG 4.5:1; skipped, not guessed, when either side is absent), missing document title, and generic hyperlink text ('click here'). Each finding carries a location and a fix hint; the summary has per-category counts and a pass flag. fix_accessibility repairs opted-in categories.

Repair audit_accessibility findings, one opted-in category at a time (detection mirrors the audit, so audit -> fix -> audit shows the opted-in findings resolved). Every category defaults to OFF; with none enabled the call refuses. Each category reports fixed items, skipped items with reasons, and items needing human review.

alt_text_placeholders: images without alt text get a clearly marked placeholder (never an invented description), all listed for a human pass via set_image_alt_text. heading_skips: repairs skipped levels via heading_strategy 'promote' or 'demote_following'; nested/mixed patterns, custom-style headings, and any repair that would leave a skip or remove the only Heading 1 are refused with details. table_headers: sets w:tblHeader on flagged first rows, skipping single-row tables and empty or all-numeric first rows. doc_title: fills an EMPTY title from the first Heading 1, never overwriting.

dry_run=True returns the identical report without touching the file. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Effective print resolution of every image: native pixel size (PNG/JPEG/ GIF parsed from the part bytes) vs displayed size gives horizontal and vertical DPI; images below min_dpi are flagged with the actual numbers. EMF/WMF report "vector (not applicable)"; other formats report "unchecked ()". Publishers typically require 300 DPI for print figures. Read-only.

Find every {{name}} placeholder and legacy MERGEFIELD in a template (body, tables, headers/footers, footnotes), with counts and locations. The returned names are the keys fill_template and mail_merge expect.

Fill a template IN PLACE: replace every {{name}} with data[name] (safe across fragmented runs, first run's formatting kept) and set MERGEFIELDs to their values as plain text. missing: 'error' refuses and changes nothing if the template needs a key data lacks; 'skip' leaves those markers; 'empty' fills them with empty strings. To produce filled COPIES instead of editing in place, use mail_merge. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Mail merge: one filled .docx per data row, saved into output_dir. data_rows: a list of dicts, or a path to a .csv (header = placeholder names) or .json (array of objects). filename_pattern supports {row_index} (1-based) and any {column}. Refuses BEFORE writing anything on existing-file collisions, duplicate output names, or (missing='error') rows lacking values the template needs. The template is never modified.

Apply the same operations to MANY documents in one call (e.g. update a footer across 50 templates). operations: [{'tool': name, 'params': {...}}] with each tool's normal parameters minus file_path. Allowed tools: search_and_replace, insert_paragraphs, delete_paragraphs, replace_paragraph_text, format_text, set_paragraph_format, apply_style, set_header, set_footer, add_page_numbers, set_page_number_format, set_document_properties, set_cells, add_watermark, remove_watermark. Per file: all operations run, then one prev/anchor slot rotation and one atomic validated save; a failing operation leaves that file untouched, and stop_on_error=True skips remaining files (already-saved files keep their changes). Refuses files open in Word.

Every fillable form field in the document: legacy fields (FORMTEXT / FORMCHECKBOX / FORMDROPDOWN with name, value, options) and modern content controls (text, rich text, checkbox, dropdown/combo, date, with tag/alias and placeholder state), across the body and tables.

Set form-field values by name (legacy fields) or tag/alias (content controls): text fields take strings, checkboxes booleans, dropdowns only values from their options (refused otherwise). Duplicate field names are refused with locations. missing: 'error' refuses, changing nothing, if a key matches no field; 'skip' ignores and reports them. For SDT types this tool skips, use set_content_control_value. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Report unfilled form fields: empty text, placeholder text still showing, and (for names listed in required) unchecked checkboxes or fields missing from the document entirely. Without required, every field is checked.

Assemble long-document front matter in one call: the requested sequence is inserted at the START (existing content becomes the body), page breaks separate front-matter pages, and one section break lets page numbering switch (front lowerRoman, body decimal restarting at 1, by default).

spec = {"sections": [{"kind": "title_page", "lines": [...]}, {"kind": "blank_or_copyright", "lines": [...]}, {"kind": "abstract", "title": "Abstract", "text": "..."}, {"kind": "toc"}, {"kind": "list_of_figures"}, {"kind": "list_of_tables"}], "page_numbering": {"front": "lowerRoman", "body": "decimal", "body_restart_at": 1}}

Title-page lines are centered; the abstract gets a Heading-styled title. Refuses when front matter appears to exist (leading TOC, or a lowerRoman section) unless spec has "force": true. Reports what was inserted and which sections carry which numbering. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Put the current chapter title in the running header via a STYLEREF field referencing the Heading style of level: the standard Word mechanism, evaluated per page, no per-chapter section breaks needed. include_number adds the heading number (STYLEREF \n). scope 'auto' targets every section containing body headings of that level; pass a list of section indices to override. first_page_blank sets titlePg (no header on section-opening pages). Watermarks are preserved; other header content is replaced and reported, with the exact field codes written. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Read back the chapter-header state: which sections carry STYLEREF header fields (with the field codes), which heading levels each section contains, and which sections with chapter-level headings lack a STYLEREF header (the gaps setup_chapter_headers would fill).

Produce a one-call structural health report, read-only: content-type coverage, dangling relationships and orphan parts, field balance per story part, footnote/endnote integrity, references to undefined styles and numbering, content-control and bookmark sanity, duplicate revision ids, missing image targets, broken cross-references, and a per-part size profile. Never fails on a weird-but-openable document; every check degrades to a reported problem, and ok=false only for problems that render broken or lose content in Word. The deep companion to validate_document's quick check.

No live mode BY DESIGN: this reads the saved package's XML, stale while Word holds unsaved changes. Close the document first (com_close_open_document saves and closes), or use com_validate_opens_clean / live get_document_info.

Permanently REMOVE matched text (true redaction: the characters are replaced in the XML, not highlighted). targets: [{find, regex?}]. Runmap-safe: secrets fragmented across Word's split runs are removed as one match. Scrubs body incl. tables, headers/footers, footnotes/endnotes (per scope: body | headers | footnotes | all), and ALWAYS: comment text, document properties, hyperlink text/tooltips/URL targets, field instructions, cached field results, tracked-change deleted text. Reports per-class counts, what was NOT examined (images, charts, OLE; text drawn in an image is not redacted), and verified_clean from a full post-redaction re-scan. Zero-width regexes and empty finds are refused up front; any error leaves the file unchanged. Irreversible in the saved file: the prev backup slot is the undo. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Re-scan a document for the given patterns without changing anything: do they still appear ANYWHERE in the XML (visible text across fragmented runs, deleted tracked-change text, field instructions, attributes, metadata, hyperlink targets)? Use it to audit a third-party file or a file redacted elsewhere. clean=True covers every XML part; binary parts (images, OLE objects) are listed under not_examined, never silently trusted. Read-only.

BETA (heuristic): review the flagged-items list in the result rather than trusting silently. Audit a legal document's defined terms. Finds definitions («"Term" means», «"Term" shall mean», «(the "Term")», «(each, a "Term")»; defaults overridable via definition_patterns, each regex capturing the term as group 1) and reports, with paragraph indices: defined_never_used, defined_multiple_times, first_use_before_definition, and used_never_defined (a HEURISTIC list of capitalized recurring terms, filtered so sentence-start capitals are not flagged; treat as review candidates). Body-level paragraphs only. Read-only.

Convert a PDF to .docx via Word's built-in PDF reflow, in a dedicated invisible Word instance. Output defaults next to the PDF with a .docx extension; an existing output file is refused; the produced .docx is validated by a full package round-trip. Text-based PDFs convert well, complex layouts may reflow imperfectly, and scanned image PDFs yield little or no text (Word does not OCR; a near-zero word count triggers an explicit warning).

Insert a LaTeX equation as NATIVE Word math (editable in Word's equation editor, not an image). display=True: a block equation in its own paragraph, positioned by exactly one of after_index / after_anchor / at_end. display=False: inline immediately after anchor_text within that paragraph (occurrence picks the match), surrounding text untouched. Supports the standard academic repertoire: fractions, roots, sums/integrals with limits, matrices, cases, align* (aligned is rewritten automatically), Greek, operators, accents, sub/superscripts, \text{}. Unconvertible LaTeX raises a clear error; the document is NOT modified. Equations are invisible to get_text/find_text (search-and-replace is equation-safe); read them with list_equations. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

List every equation in the document (body, tables, footnotes, endnotes): index, display vs inline, location, and a plain-text approximation of the math. THIS is how equation content is read; equations are invisible to get_text and find_text because math runs sit outside the plain-text layer. The index is the handle delete_equation takes. Read-only.

Delete an equation by its list_equations index. A display equation's paragraph is removed with it when the paragraph holds nothing else (the usual case); an inline equation is removed from within its paragraph, surrounding text untouched. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Search the user's LOCAL Zotero library (read-only; the database is never modified). Every query word must match the title, a creator's last name, the year, or the publication name. Returns each match's Zotero item key (the handle insert_zotero_citation takes) plus type, title, creators, year, and publication. Attachments, notes, and trashed items are excluded. The database defaults to /Zotero/zotero.sqlite; pass db_path for a nonstandard data directory. Reads a point-in-time snapshot, so last-moment edits in a running Zotero may not appear yet.

Insert a REAL Zotero citation field (ADDIN ZOTERO_ITEM CSL_CITATION) after anchor_text, built exactly as the Zotero Word plugin builds it, so Zotero recognizes, refreshes, and bibliographs it. item_keys come from search_zotero_library; page becomes the locator; prefix/suffix attach to the cited item (single-item citations only; several keys refuse rather than guess). The visible text is a plain (Author, Year) PLACEHOLDER until the user clicks Refresh in Zotero's Word plugin. The Zotero database is only ever read. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Find text by its EFFECTIVE formatting: bold/italic/underline/strike (true/false), font, size_pt, color (hex), highlight, style (id or name); all criteria must hold together. Resolution follows Word (run properties, then character style, then paragraph-style chain, then document defaults); every match reports which level satisfied each criterion, so explicit and Heading-inherited bold are distinguishable. query=None returns every stretch with the formatting; a query (case-sensitive) returns only occurrences inside such stretches. scope: 'body' (tables included) or 'all' (adds footnotes/endnotes). Text-box content is EXCLUDED: read boxes via get_textbox_text or get_text include_textboxes. Theme references are counted, never guessed. replace_formatted is the mutation twin. Read-only.

Read EFFECTIVE paragraph formatting for body paragraphs start..end (inclusive; end defaults to start): alignment, space_before_pt, space_after_pt, line_spacing, indent_left_pt, indent_right_pt, first_line_indent_pt (negative = hanging), keep_with_next, widow_control, page_break_before. Resolution follows Word (own properties, then the style basedOn chain, then document defaults); every property reports value AND source ('explicit' | 'paragraph_style' | 'document_defaults' | 'word_default'), mirroring find_formatted's matched_via, so direct overrides and style inheritance are distinguishable. line_spacing carries its rule ('auto' = multiple; 'exact'/'atLeast' = points). Numbering-contributed indents are not resolved (flagged has_numbering). set_paragraph_format takes the same keys. Read-only.

The full reviewer matrix in one call: every comment thread with author, initials, date, the anchored text it targets, the comment text, replies nested under their parents, resolved flag, and a locator (paragraph index plus the heading path of the section it falls under). Summary gives per-author, open/resolved, and per-section counts. Built for processing committee feedback without re-reading comments piecemeal. Set include_resolved=False to drop resolved threads (the excluded count is reported). Read-only.

Merge the reviewer matrix across several documents (e.g. three committee members' copies of the same draft). Entries are keyed by (author, anchored text) with per-file provenance on every occurrence, and collisions (the same span commented on by two or more reviewers) are detected and listed. Copies should share the draft text; merging matches anchored spans verbatim. Read-only on every file.

Tracked-change analytics per author: insertion/deletion counts, words added and removed, move and format-change counts, the date range of each author's edits, and a per-section (heading-path) breakdown of where their changes concentrate. Includes the 10 heaviest body paragraphs by revision churn. Footnote/endnote revisions count under "[footnotes]"/"[endnotes]". Read-only.

Diff two saved drafts agent-readably, computed without Word: unchanged/modified/inserted/deleted paragraphs with indices in both documents, moved paragraphs (identical text at a new position), intra-paragraph change opcodes, per-section change summary, table changes (dimensions plus changed cells, compared positionally), footnote/endnote count deltas, and heading structure changes. Deliberately NOT a redline: use com_compare_documents for a Word-rendered tracked-changes comparison. Per-change detail is capped at detail_cap entries on huge diffs (counts stay complete). Read-only on both files.

Read the text inside every text box / shape text frame, per box, across the body, headers, and footers (modern drawings and legacy VML alike). Each box reports its text, paragraphs, part, anchoring body paragraph index (where determinable), and shape name. Use this instead of get_text for box content: the generic tools smear box text into the host paragraph (doubled by the mc:Fallback compatibility copy) with no boundary. box_index is the address set_textbox_text takes. Read-only.

Replace the text of one text box (box_index from get_textbox_text). Keeps the first paragraph's style and first run's formatting; '\n' splits into multiple paragraphs; the mc:Fallback compatibility copy is rewritten to match. Boxes holding non-text content (nested tables, images) are refused rather than flattened. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Dry-run search_and_replace; the file is NEVER modified. Same items ({find, replace, regex?}), scope (body | footnotes | headers | all), and matching engine (fragmented-run map, guarded regex, chained items), so the preview shows exactly what a real run would change: per-item counts, each match with paragraph index and ~60 chars of before/after context, the grand total, and the refusals a real run would hit. Review, then run search_and_replace with max_replacements set to the previewed total so any drift aborts instead of over-replacing.

Count words minus named zones: the number a journal actually wants. exclude any of: references, captions, footnotes, endnotes, block_quotes, tables, headings, front_matter, abstract (unknown names rejected with the allowed list). Returns total, per-zone excluded breakdown, and the included count; total = included + sum(excluded) always. Same whitespace tokenization as word_count's file mode; detected zone locations are reported for review. Read-only.

BETA (heuristic): review the flagged-items list in the result rather than trusting silently. Anonymize a manuscript for double-blind peer review, reversibly. Masks self-citations by the named authors ('Hurd (1999)' -> 'Author (1999)') keeping years and pages, rewrites their reference-list entries to 'Author (Year). [Details removed for peer review.]', and scrubs identifying metadata. Prose that identifies the author (Acknowledgments, 'my previous work', surnames outside citation syntax) is FLAGGED with locations, never auto-edited. Writes a reversal mapping JSON (default .anonymization.json, never overwritten) for deanonymize_document; KEEP IT PRIVATE. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Reverse anonymize_for_review using its mapping file (default .anonymization.json beside the document). Every recorded change is verified to still sit where the mapping says before anything is restored; if the document drifted since anonymization, NOTHING is restored and the refusal lists every mismatch. The mapping file is left on disk to delete once the restore is confirmed. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Export a body-level table (list_tables index) to CSV or JSON as a rows x grid-columns matrix. Merged cells keep their value in the anchor (top-left) position with empty strings in the covered positions; include_merges adds the merge topology as {row, col, rowspan, colspan} entries (inside the JSON document; as a report field alongside CSV). Nested tables are flattened into the host cell's text and flagged. output_path=None returns the data inline ('csv' string / 'data' rows) instead of writing a file; an existing output file is refused. The document itself is never modified.

Fill a table from data: a .csv path, a .json path (export_table's form or a bare row list), or an inline list of lists. Without table_index a NEW table is created (at_end/after_anchor, default end; has_header bolds and repeats the first row). With table_index the existing table's cell texts are OVERWRITTEN in place: data must exactly match rows x grid-columns (refused otherwise, listing both shapes); merged cells take their value at the anchor position; values in merge-covered positions are refused. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Extract every image in the document to files in output_dir, named by list_images index plus the original extension (image0.png, ...; prefix replaces 'image'). Media referenced only from headers/footers/notes gets the next indices with the referencing part reported. Each entry reports the output file, native pixel dimensions, and where the image appears (body paragraph/table index). Collisions with existing files are refused before anything is written. Read-only against the document.

Split a document into one standalone .docx per heading section, the inverse of com_merge_documents (no Word needed). Sections start at each heading of level (or higher) and carry everything to the next one; content before the first heading becomes 00_front_matter.docx when non-empty. Outputs carry the source's styles, numbering, settings, fonts, and themes; other sections' note definitions and image parts are stripped; every output is round-trip validated. filename_from: 'heading' gives 01_Heading Text.docx, 'index' gives 01.docx. The source file is never modified; existing output files are refused before anything is written.

Parse the manuscript's reference list (References / Bibliography / Works Cited heading) and in-text citations into a structured model. Read-only stage 1 of publication-style conversion.

Heuristic text parsing: every entry gets parse_confidence (full/partial/failed); failed entries are returned verbatim and will never be converted. Also reports in-text citations with positions (parenthetical, narrative, [n] bracket, superscript), whether the document uses Word-native or Zotero/Mendeley/EndNote citation FIELDS (which text conversion refuses to touch), and the detected citation system. style_hint (e.g. 'apa7', 'ieee', 'turabian') tightens parsing when the source style is known.

BETA (heuristic): review the flagged-items list in the result rather than trusting silently. Convert a manuscript's PLAIN-TEXT citations and reference list to a target publication style: apa7, chicago17-author-date, chicago17-notes (= Turabian), mla9, harvard, ieee, vancouver, asa.

Heuristic text conversion, not a citation processor: only fully-parsed reference entries and unambiguously-resolved citations are converted; everything else is left verbatim and flagged for human review. Supports author-date <-> numbered ([n] or Vancouver superscripts, numbered by first appearance), author-date -> Chicago notes (each citation becomes a REAL footnote), and notes -> author-date (only recognizably pure citation footnotes are harvested; mixed ones are flagged and left alone). Narrative citations keep the author's name; reference-list italics, ordering, heading, and hanging indents are handled. Documents using Word-native or Zotero/Mendeley/EndNote citation FIELDS are routed away (set_bibliography_style, or restyle in the manager); fields are never rewritten as text. Run detect_citation_system first on unfamiliar documents: mixing Word-native and Zotero/Mendeley/EndNote citations creates a bibliography no single manager maintains.

dry_run=True returns the complete change plan and leaves the file byte-identical; parse_references is the read-only stage 1. Any error during a real run leaves the original untouched. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Apply a style's page-level manuscript conventions where publicly well-defined: 'apa7' (= apa7-student: 1in margins, double spacing, page number top right, APA heading formats L1-L5), 'apa7-professional' (adds the running head; running_head or the title, flagged), 'mla9' (surname

• page header; author_last_name or the author metadata, flagged), 'chicago17' (= turabian: 12pt base, double-spaced body, single-spaced footnotes, page number bottom center). All three set a hanging indent on a found reference list. Anything contested (run-in headings, casing, indents near front matter) is NOT applied and is itemized in not_applied. IEEE/Vancouver/ASA/Harvard page formats are journal-template-specific and refused. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Recommended tool sequences for common multi-step tasks, with a one-line why per step. Call with no task to list the available tasks ('process-feedback', 'prepare-submission', 'format-citations', 'build-from-template', 'heavy-editing'); call with task='' for that task's step-by-step sequence and notes. Pure guidance: reads nothing, changes nothing.

Which citation system(s) the document uses: Word native (CITATION fields + sources store), Zotero (ADDIN ZOTERO_ITEM), Mendeley (ADDIN CSL_CITATION), EndNote (ADDIN EN.CITE), or plain typed text only. Counts per system across body, footnotes, and endnotes, plus a split_brain flag when more than one managed system is present (a split-brain bibliography: each manager only maintains its own fields). Run this BEFORE any citation work on an unfamiliar document.

Promote (delta=-1) or demote (delta=1) a heading, addressed by exact heading_text or by paragraph_index. subtree=True also shifts every subordinate heading beneath it (until the next same-or-higher heading) by the same delta, keeping the branch's shape. Refuses, changing nothing, if any affected heading would leave levels 1-9 (the blocker is named) or if a heading's level comes from an outlineLvl override or custom style rather than a built-in Heading style (adjust those via set_paragraph_format's outline_level). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a generic Word field right after after_anchor text (plain paragraph text, literal characters, not XML entities; occurrence picks which match when the anchor appears more than once). field_code examples: 'DATE', 'TIME @ "HH:mm"', 'FILENAME', 'NUMPAGES', 'PAGE', 'SEQ Exhibit * Arabic'. Codes are validated against an allowlist of known-safe fields (document info, page/date/time numbers, SEQ); anything that links out or executes is refused, naming the allowlist. The field is written dirty so Word computes the result on the next refresh; placeholder shows until then. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Every field in the body, headers, footers, footnotes, and endnotes: instruction code, field type (DATE, PAGE, SEQ, TOC, ...), the current cached result text, and location (part + body paragraph index where applicable). Covers complex (fldChar) and simple (fldSimple) fields; unclosed complex fields are flagged.

Save a DTG-stamped permanent copy of the document: YYYYMMDD_HHMM_.docx (an existing leading DTG in the name is replaced, not stacked), with an optional short label suffix. Snapshots are the PERMANENT keepers that complement the automatic prev/anchor backup slots: the slots rotate on every mutation, snapshots are never auto-pruned and manage_backups never touches them. Never overwrites (collisions get a numeric suffix); returns the created path. The source document is not modified.

Every content control (SDT) in the document body, including the types fill_form_fields skips: tag, alias, type (text / richtext / checkbox / dropdown / combo / date / picture / group / citation / bibliography / equation / gallery / repeating_section), current value, lock state, placeholder flag, and block/inline. The index is the addressing handle for set_content_control_value when tags are missing or duplicated.

Set one content control's value, addressed by tag or by list_content_controls index (exactly one). Text, rich-text, combo, and date controls take a string; checkboxes a boolean; dropdowns one of their options (refused otherwise, naming the options). Locked controls and unwritable types (gallery, repeating section, citation, bibliography, picture, group, equation) are refused with nothing changed. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert a new PLAIN-TEXT content control (inline SDT) right after after_anchor text (plain paragraph text, literal characters; occurrence picks which match when the anchor appears more than once), with a unique tag (refused if it exists) and optional alias and initial text. Plain text is the one control type this server can build safely; creating checkbox, dropdown, date, picture, gallery, or repeating controls is refused (list/fill still cover those when a template provides them). Fill it later via fill_form_fields or set_content_control_value by its tag. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Build a glossary section from the document's defined terms (same detection as check_defined_terms): a heading plus one alphabetized paragraph per term, term in bold, definition harvested from the defining sentence. Terms whose definition cannot be extracted cleanly get a [DEFINITION NEEDED] marker instead of a mangled fragment; the result lists them for manual completion. Placed at the body end by default, or after body paragraph after_index. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Insert the ENTIRE body of source_path into target_path at one position, with full resource reconciliation: the document-assembly tool for merging chapter files into one manuscript. com_merge_documents only concatenates whole files into a new one; copy_table transplants a single table.

Position (exactly one): after_index is a body ITEM index, counting paragraphs AND tables together in document order (unlike the paragraph-only indices elsewhere); insertion lands after that item. after_anchor matches a paragraph whose FULL plain text equals the anchor; several matches refuse and list every location, so recurring heading text cannot land content at the wrong spot (prefer after_index for structural work). at_end appends after the last body item.

Carried: tables, images, charts, hyperlinks, lists (fresh numbering), footnotes/endnotes (new ids), bookmarks (remapped, collisions renamed and reported), tracked changes, equations. Styles reconcile BY NAME (the target's formatting wins on a match; unmatched styles are cloned in with dependency chains). The source's section setup is never carried; mid-content section breaks and comment references are stripped and reported. OLE objects, ActiveX, subdocuments, and altChunks refuse the whole insertion, naming the blocker; nothing is half-applied.

formatting mirrors Word's paste modes on the carried copies: 'source' (default) keeps direct formatting; 'merge' keeps bold/italic/emphasis but strips direct font/size/color/spacing/indent overrides; 'destination' strips all direct formatting except structural properties. Returns per-resource counts, style remaps, bookmark renames, and the occupied body-item range. The source file is never modified. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Replace text ONLY where it carries specific EFFECTIVE formatting: the mutation twin of find_formatted, same criteria keys (bold/italic/underline/strike, font, size_pt, color, highlight, style), all required together, resolved the way Word resolves them. find=None replaces each entire matching stretch; with find (literal, case-sensitive), only occurrences wholly inside a matching stretch. Safe across fragmented runs; the replacement keeps the matched formatting. Result mirrors search_and_replace ({replaced, total}) plus per-replacement matched_via. No regex here (search_and_replace covers that); text boxes are never touched (set_textbox_text edits those). max_replacements aborts, changing nothing, past the cap. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Transplant ONE table from source_path into target_path: the single-element sibling of insert_document, reusing its resource reconciliation scoped to the table (styles matched BY NAME, target wins, unmatched cloned; fresh numbering; images/hyperlinks re-registered; footnote/endnote definitions under new ids; bookmarks remapped, collisions renamed).

table_index counts the SOURCE's top-level body tables (0-based, list_tables order; nested tables travel with their parent). Target position (exactly one): after_index is a body ITEM index counting paragraphs AND tables together (not the paragraph-only index other tools use); after_anchor matches a paragraph's FULL plain text, refusing with every location when it recurs; at_end appends. OLE/ActiveX/altChunks inside the table refuse the whole copy; nothing is half-applied. Returns row/column counts, the occupied body-item position, and per-resource counts. The source file is never modified. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.