KitchenSink4Word

Apply a batch of anchor-addressed edits in one call: one lock, backup, and validated save. Anchors come from get_document_view. Ops (each edit has "op"): replace {anchor, find, text, occurrence?} (omitted = every match); set_text {anchor, text}; insert {location, markdown} (headings, paragraphs, lists and pipe tables become real structures); delete {anchor or anchors}; move {anchor or anchors, location, allow_cross_section?} (verbatim relocation, file mode only; refuses a paragraph holding a section break, and a landing in another section unless allowed); set_style {anchor, style}; format {anchor, formatting, find?, occurrence?} (no find = whole paragraph, mark included); set_paragraph_format {anchor, format}; set_cell {anchor: "t:hex:rNcN", text}. The whole batch validates BEFORE anything mutates, against BATCH-START text (never reference text an earlier op creates); one stale anchor refuses it all (STALE_ANCHOR lists the failed ops). changed carries per-op results plus fresh anchors for inserted paragraphs, so batches chain without re-viewing. Ops run in order; keep deletes last. Edits are applied directly, so under track changes they warn rather than record a revision. Auto-backup in file mode; atomic validated save. A document open in Word is edited live as ONE undo step, rolled back on mid-batch failure; markdown lists/tables and move are file-mode only there.

Apply a named style. range={start,end} (locations or bare indices) applies a paragraph style to those paragraphs, changing their full look (Heading1-9 auto-created); target={search:{text, occurrence?}} applies a character style to the matched text instead. For an outline level without visual change use set_paragraph_format. Auto-backup (backup=False skips rotation); atomic validated save. Refuses documents open in Word. For batches, use apply_edits. Defining new named styles lives in the academic pack.

Copy a document byte-for-byte, e.g. to a new DTG-stamped filename before editing (manage_backups action='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. Split/merge and multi-document work live in the assembly pack.

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 (academic pack), and other tools. Template-driven builds live in the assembly pack.

Create a table from 2D string data with single-line borders and a bold repeating header row (header_row=False for none). location is the standard location object; omit it to append at the end; position 'after' only. Shading, column widths and repeat-header on an EXISTING table: format_cells and set_table_properties (media-forms). From a CSV or JSON file: import_table (protection-io pack). Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic save. Refuses documents open in Word.

Delete one document element that has no lifecycle tool of its own. type: equation | image | chart | bookmark | hyperlink | caption | reference_list | content_control. Address equations, images, charts by their list_elements index; reference_list (TOC, List of Tables/Figures, index) by its read order; bookmarks by name (markers go, the text stays; Word-internal underscore names refused); hyperlinks by target url in `id` and/or a location search on the link text (the link is unwrapped, display text kept, the relationship dropped once unshared; several matches without occurrence refuse loudly listing every candidate); captions by location (Caption-styled paragraphs only); content controls by tag or index (the whole control including content; locked controls refused). Deleting an image or chart also removes its media, chart, and embedded-workbook parts once nothing else references them. Objects with lifecycle tools stay there: notes in manage_note (academic pack), comments in manage_comment (review pack), sources in manage_source (references pack), tables in delete_table, paragraphs in delete_paragraphs. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

Delete body paragraphs by 0-based inclusive index (start, end; end defaults to start) or by range={start, end} location objects. Refuses ranges cutting a field or a section break; deleting every paragraph leaves one empty one behind. track records tracked deletions. expect_start/expect_end delete nothing unless that index still holds the given text. Auto-backup in file mode (backup=False skips rotation). Open documents edit live (serialized), unsaved until saved. For batches, use apply_edits.

Delete a whole table and its contents. table_index is the 0-based position among body-level tables in document order, as reported by list_elements(type='tables') or get_document_view; nested tables are removed with their host table. To clear cell values while keeping the grid, use set_cells instead. Auto-backup: prev/anchor slots in .ks4w-backups (backup=False skips rotation only); atomic validated save. Refuses documents open in Word.

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 healthy=false only for problems that render broken or lose content in Word. The deep companion to validate(checks=['core']). No live mode BY DESIGN: this reads the saved package's XML, stale while Word holds unsaved changes. Close the document first, or use com_validate_opens_clean (com-live pack) / live get_document_info. The full validate check battery lives in the academic pack.

Disable previously enabled tool packs for this session and reclaim their context; the lite core always stays on. Idempotent. The result reports the packs just disabled, the approximate tokens removed, and the remaining surface. packs takes the same names as enable_tools (its description carries the menu) or ['everything'].

Enable optional tool packs mid-session (sessions start lite). Idempotent; reports tokens added. packs = names below or ['everything']; disable_tools reverses it. Task map: cell merges, tables, images, forms -> media-forms; tracked changes, comments -> review; citations -> references; TOC, notes -> academic; document merge -> assembly; PDF, live Word -> com-live; redaction -> protection-io. Packs: - references (~2.9k): citations and bibliography: Word-native sources, bibliography styles, Zotero search/cite, parity checks, style conversion - review (~2.4k): tracked changes (read, accept/reject), comments (add, reply, resolve), reviewer reports, structured diff, anonymize - academic (~7.6k): notes, TOC, index, captions, cross-references, bookmarks, headers/footers, sections, styles, word counts, validation, submission prep, accessibility - assembly (~2.1k): multi-document work: insert/split documents, move sections, copy tables across files, templates, mail merge - media-forms (~5.6k): images, charts, equations, text boxes, hyperlinks, table structure (merge/split cells, rows, columns, sort), forms, content controls, field codes - com-live (~3.1k): drives the Word app: PDF import/export, compare/combine, proofing, readability, live editing of open documents - protection-io (~1.6k): protection, watermarks, redaction with verification, table CSV/JSON import/export

Find text in paragraphs and table cells; returns locations plus context. include_textboxes=True also searches text-box content as labeled matches; file-mode only. Pass formatting={...} (bold, font, size_pt, color, ...) to search by EFFECTIVE formatting: resolved through run, style chain, and defaults; query=None returns every formatted stretch; scope 'body' or 'all'; file-mode, no regex. Plain queries search open documents live (same shape, 500-match cap). Read-only. To read a known range, use get_text.

Apply character formatting or change case. formatting: bold, italic, underline, strike, font, size_pt, color, highlight and more (a wrong key lists all). case: upper|lower|title|sentence. Target: range={start,end}, find or both; one of formatting or case per call. find formats just that SUBSTRING: the run splits at the matched offsets, each fragment keeping its other formatting. A range without find takes whole paragraphs, mark included. Auto-backup; atomic save. Formatting is live-capable; case is file mode only.

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.

Read the document as an anchored markdown projection, the low-token alternative to get_text for orientation and bulk editing. One block per paragraph, prefixed [hex] with a stable anchor id (from w14:paraId, which survives edits elsewhere in the document); headings carry # prefixes, tables render as pipe tables under [t:hex] with cells addressed t:hex:rNcN (1-based). Anchors work in every location object ({"anchor": "hex"}) and in apply_edits ops. scope: {"outline": "3.2"} for one heading's section, or {"paragraphs": {"start": N, "end": M}} (end exclusive); omit for the whole document. detail: "structure" (headings and counts only), "text" (default), "full" (adds {++ins++}/{--del--} revision markers and [cN] comment refs with an author legend). include: {"tables": false} to skip tables, {"notes": "inline"} to append footnote/endnote text. Documents without paraIds get VOLATILE anchors (flagged in the header) that change with any edit; stamp_anchors=true writes real paraIds so anchors become durable. Stamping is the ONE mutation this tool can make and runs only when explicitly requested, with the normal backup and validated save; plain reads never modify the file. A document open in Word is read from its last saved state. To locate a string, use find_text; to enumerate collections, use list_elements.

List every heading with its paragraph index and level. Detects Heading styles AND w:outlineLvl overrides (direct or style-inherited); detected_via names which. detect_formatted=True adds a heuristic scan for direct-formatted headings (short bold, italic or centered; numbered captions excluded): CANDIDATES with an INFERRED level and a confidence. Detecting nothing returns a note plus flat structure counts. The indices feed the location object's paragraph and outline selectors. Read-only. TOC building: academic pack.

Report this server's build and environment: version, the active tool surface (tool count, approximate token bill, per-pack state), the packs enable_tools can load, what decided the startup surface and whether it is locked, whether the Word application tier can run here, whether path sandboxing is on, the host OS and Python, and the update-check state. Needs no document, opens no file, starts no Word. Paste-safe: no path, document name, or user name, so a bug report can carry it as it stands.

Read one table in full: every cell's text, the merge map, and column widths. table_index is 0-based among body-level tables in document order. has_merges=false returns rows of strings; has_merges=true returns {text, grid_span, vmerge} cells. For a nested table pass nested={row, cell, index} addressing the host cell (index picks among several, default 0). Write with set_cells; shade with format_cells; widths and repeat-header set_table_properties; reshape with modify_table_structure (media-forms pack). Read-only.

Read body paragraphs as [{index, text, style, ...}] with effective styles. start/end slice by paragraph index (0-based, end EXCLUSIVE); contains filters. include_textboxes=True appends text-box content as labeled extras, body indices untouched; textbox=true (or {"index": n}) returns ONLY text-box content, with the box_index set_textbox_text (media-forms pack) takes; file-mode only. Open documents read live, same shape. Equations read via list_elements type='equations'. Read-only. Orientation: get_document_view.

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', 'live-editing', 'comment-partner', 'migrate-from-v1', 'bulk-edit'); call with task='<name>' for that task's step-by-step sequence and notes. Pure guidance: reads nothing, changes nothing.

Insert a break after the located paragraph. type: page starts a new page; section_next / section_continuous / section_even / section_odd start a new SECTION (own headers, margins, numbering; see set_section_properties, academic pack). location picks the paragraph (omit for document end). 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 as needed). items: strings or {text, level} dicts (level 0-8 nests); kind: bullet | number. A call makes its own list, so numbering restarts at 1; continue_from (a num_id from list_elements) carries on an existing one and start_at restarts the new one at N. levels sets per-level formats: [{level, format, text, start, suffix, align, indent_pt, hanging_pt, font}], format one of decimal | lowerLetter | upperLetter | lowerRoman | upperRoman | bullet | none, text a label like '%1.%2.'. location picks the insertion point (omit for document end). Auto-backup to .ks4w-backups; atomic validated save. Refuses documents open in Word.

Insert paragraphs (items {text, style?, formatting?, heading_level?, paragraph_format?}) at a location object (omitted = document end). heading_level 1-9 makes it a heading (1 = outline 0). paragraph_format takes set_paragraph_format keys; it and inherit_format/copy_format_from (clone neighbor formatting minus outline level) are file mode only. track records insertions by author. Auto-backup; atomic save. Open documents edit live; a stale text-selector target refuses: save in Word, retry. Batches: apply_edits.

Enumerate any collection in one call. type: tables | images | charts | equations | bookmarks | sources | sections | section_blocks | footnotes | endnotes | fields | reference_fields | form_fields | content_controls | template_placeholders | index_entries | lists | toc. Returns {type, count, items}; the ids or indices returned are the handles the matching set_/delete_/manage_ tools take (list then act). Highlights per type: tables reports dimensions and the table_index other table tools take; images reports display size and the media target; charts reports series; equations reads math content; bookmarks excludes internal TOC bookmarks; fields covers complex and simple fields with cached results; reference_fields inventories Zotero, EndNote, and Mendeley fields and flags broken pairs; form_fields and content_controls cover legacy fields and SDTs; template_placeholders lists {{name}} and MERGEFIELD keys for fill_template and mail_merge (assembly pack); lists groups list paragraphs by numbering instance; toc returns TOC-family fields with cached entries (refresh via com_refresh_fields, com-live pack, then re-read). filter={"range": {start, end}, "name": "substring"} applies where meaningful; inapplicable filters refuse loudly. Read-only, file mode; close documents open in Word first. Tools for these elements live in packs; enable_tools lists them. To locate a string, find_text.

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). action='list': slot files with sizes and mtimes, legacy *.bak-* files, 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; the payload is validated before the atomic replace, and documents open in Word are refused. 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. action='snapshot': save a DTG-stamped permanent copy of file_path, YYYYMMDD_HHMM_<name>.docx (an existing leading DTG is replaced, not stacked), optional short label suffix, optional dest_dir. Snapshots are permanent keepers: the slots rotate on every mutation, snapshots are never auto-pruned and no purge scope touches them. Never overwrites (collisions get a numeric suffix); the source document is not modified.

Batch find/replace, safe across Word's fragmented runs. Each item: {find, replace, regex?}; scope: body | footnotes | headers | all. preview=true dry-runs the same engine without touching the file: per-item counts, each match with paragraph index and before/after context, the grand total, and the refusals a real run would hit; review, then rerun with max_replacements set to the previewed total so drift aborts instead of over-replacing. find_formatting={bold, italic, font, size_pt, color, highlight, style, ...} restricts replacement to text carrying that effective formatting (file mode only, no regex; an item without find replaces each entire matching stretch, and the replacement keeps the matched formatting). max_replacements aborts, changing nothing, when total matches would exceed it. track records each replacement as a tracked change by author. Sibling: set_paragraph_text rewrites one whole paragraph when a find string would be unwieldy. 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 (backup=False skips rotation); atomic validated save. Documents open in Word edit live, serialized; tracked replaces never re-match their own markup. For anchor-scoped edits, use apply_edits.

Write many table cells in one call. Modes: edits=[{row, cell, text}] for scattered cells, or block={origin:{row, cell}, values:[[...]]} for a 2D block. nested={row, cell, index} targets a nested table in that host cell (edits mode only). track records changes by author. Cell TEXT only: shading, bold and alignment are format_cells, widths and repeat-header set_table_properties (media-forms). Live (plain edits only) refuses vertical merges; file mode is merge-aware. Auto-backup; atomic save. Batches: apply_edits.

Set paragraph formatting on a batch: indices (0-based list) OR start/end (inclusive range), exactly one form. 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; null removes) never changes the look; it is off by one from heading_level 1-9. Auto-backup; atomic validated save. Open documents edited live (serialized; shading/borders/tab_stops refused live). For batches, use apply_edits.

Replace one paragraph's full text, keeping style and base formatting; address it with a location object ({paragraph: N}, {search: ...}, {outline: ...}). Indices shift after edits, so pass expect (a substring the target must contain) to refuse instead of hitting the wrong paragraph; verify the returned replaced_text. Auto-backup in file mode (backup=False skips rotation); atomic validated save. Edits go live on open documents (serialized); tracked-revision paragraphs refuse live. For batches, use apply_edits.