docx

Work with Microsoft Word .docx files. The format is OOXML, a zip container holding XML parts (word/document.xml, styles.xml, numbering.xml, headers, footers, relationships). Treat structure as primary; rendered text is a view.

Decide the path first

Pick one path up front. The right path depends only on what is on disk before you start.

You have	Goal	Path
Existing .docx	Read text/structure	A. Inspect
Existing .docx	Modify content while keeping styles	B. Edit-in-place
Nothing or a brief	Build a new doc	C. Create from scratch

If the user hands you a doc and asks for changes, default to path B and treat the input as the visual style baseline. Only choose path C when the user says "start fresh" or there is no input.

---

Path A: Inspect

Dump structure as JSON for inspection without mutating anything.

python {baseDir}/scripts/inspect_docx.py /path/to/doc.docx

Output schema:

{
  "paragraphs": [{"index": 0, "text": "...", "style": "Heading 1"}, ...],
  "tables": [[["row0,col0", "row0,col1"], ...], ...],
  "sections": 1,
  "has_tracked_changes": false
}

Use this whenever you need to see what is in the doc before deciding how to edit. The output is stable and machine-readable, diff two inspect outputs to verify a round-trip preserved everything you intended.

---

Path B: Edit in place

Two sub-strategies; pick by how invasive the edit is.

B1. Run-level text replacement (preferred)

When the change is "swap this string" or "fill these placeholders": mutate runs in place. This preserves all theme/style/font settings.

python {baseDir}/scripts/edit_docx.py input.docx ops.json --out output.docx

ops.json is a list of operations:

[
  {"op": "replace_run", "para": 0, "run": 0, "text": "Q3 Review"},
  {"op": "replace_text", "find": "{{CLIENT}}", "with": "Acme Corp"}
]