Docx

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Design requiremnet

Deliver studio-quality Word documents with deep thought on content, functionality, and styling. Users often don't explicitly request advanced features (covers, TOC, backgrounds, back covers, footnotes, charts)—deeply understand needs and proactively extend. The document must have 1.3x line spacing and have charts centered horizontally.

Available color（choose one）

• "Ink & Zen" Color Palette (Wabi-Sabi Style)

The design uses a grayscale "Ink" palette to differentiate from standard business blue/morandi styles. Primary (Titles)：#0B1220 Body Text：#0F172A Secondary (Subtitles)：#2B2B2B Accent (UI / Decor)：#9AA6B2 Table Header / Subtle Background：#F1F5F9

• Wilderness Oasis": Sage & Deep Forest

Primary (Titles): #1A1F16 (Deep Forest Ink) Body Text: #2D3329 (Dark Moss Gray) Secondary (Subtitles): #4A5548 (Neutral Olive) Accent (UI/Decor): #94A3B8 (Steady Silver) Table/Background: #F8FAF7 (Ultra-Pale Mint White)

• "Terra Cotta Afterglow": Warm Clay & Greige

Commonly utilized by top-tier consulting firms and architectural studios, this scheme warms up the gray scale to create a tactile sensation similar to premium cashmere. Primary (Titles): #26211F (Deep Charcoal Espresso) Body Text: #3D3735 (Dark Umber Gray) Secondary (Subtitles): #6B6361 (Warm Greige) Accent (UI/Decor): #C19A6B (Terra Cotta Gold / Muted Ochre) Table/Background: #FDFCFB (Off-White / Paper Texture)

• "Midnight Code": High-Contrast Slate & Silver

Ideal for cutting-edge technology, AI ventures, or digital transformation projects. This palette carries a slight "electric" undertone that provides superior visual penetration. Primary (Titles): #020617 (Midnight Black) Body Text: #1E293B (Deep Slate Blue) Secondary (Subtitles): #64748B (Cool Blue-Gray) Accent (UI/Decor): #94A3B8 (Steady Silver) Table/Background: #F8FAFC (Glacial Blue-White)

Chinese plot PNG method\\

If using Python to generate PNGs containing Chinese characters, note that Matplotlib defaults to the DejaVu Sans font which lacks Chinese support; since the environment already has the SimHei font installed, you should set it as the default by configuring:

matplotlib.font_manager.fontManager.addfont('/usr/share/fonts/truetype/chinese/SimHei.ttf') plt.rcParams['font.sans-serif'] = ['SimHei'] plt.rcParams['axes.unicode_minus'] = False

Specialized Element Styling

• Table Borders: Use a "Single" line style with a size of 12 and the Primary Ink color. Internal vertical borders should be set to Nil (invisible) to create a clean, modern horizontal-only look.
• CRITICAL: Table Cell Margins - ALL tables MUST set margins property at the Table level to prevent text from touching borders. This is mandatory for professional document quality.

Alignment and Typography

CJK body: justify + 2-char indent. English: left. Table numbers: right. Headings: no indent. For both languages, Must use a line spacing of 1.3x (250 twips). Do not use single line spacing !!!

CRITICAL: Chinese Quotes in JavaScript/TypeScript Code

MANDATORY: When writing JavaScript/TypeScript code for docx-js, ALL Chinese quotation marks (""", ''') inside strings MUST be escaped as Unicode escape sequences:

• Left double quote "\u201c" (")
• Right double quote "\u201d" (")
• Left single quote "\u2018" (')
• Right single quote "\u2019" (')

Example - INCORRECT (will cause syntax error):

new TextRun({
  text: "他说"你好""  // ERROR: Chinese quotes break JS syntax
})

Example - CORRECT:

new TextRun({
  text: '他说\u201c你好\u201d' // Correct: escaped Unicode
})

Alternative - Use template literals:

new TextRun({
  text: `他说"你好"` // Also works: template literals allow Chinese quotes
})

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below.

Creating New Document

Use "Creating a new Word document" workflow.

Editing Existing Document

• Your own document + simple changes

Use "Basic OOXML editing" workflow

• Someone else's document

Use "Redlining workflow" (recommended default)

• Legal, academic, business, or government docs

Use "Redlining workflow" (required)

Reading and analyzing content

Note: For .doc (legacy format), first convert with libreoffice --convert-to docx file.doc.

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_directory>

Key file structures

• word/document.xml - Main document contents
• word/comments.xml - Comments referenced in document.xml
• word/media/ - Embedded images and media files
• Tracked changes use <w:ins> (insertions) and <w:del> (deletions) tags

Creating a new Word document

When creating a new Word document from scratch, use docx-js, but use bun instead of node to implement it. which allows you to create Word documents using JavaScript/TypeScript.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read `docx-js.md` (~560 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation. 2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below) 3. Export as .docx using Packer.toBuffer()

TOC (Table of Contents)

If the document has more than three sections, generate a table of contents.

Implementation: Use docx-js TableOfContents component to create a live TOC that auto-populates from document headings.

CRITICAL: For TOC to work correctly:

• All document headings MUST use HeadingLevel (e.g., HeadingLevel.HEADING_1)
• Do NOT add custom styles to heading paragraphs
• Place TOC before the actual heading content so it can scan them

Hint requirement: A hint paragraph MUST be added immediately after the TOC component with these specifications:

• Position: Immediately after the TOC component
• Alignment: Center-aligned
• Color: Gray (e.g., "999999")
• Font size: 18 (9pt)
• Language: Matches user conversation language
• Text content: Inform the user to right-click the TOC and select "Update Field" to show correct page numbers

TOC Placeholders (Required Post-Processing)

REQUIRED: After generating the DOCX file, you MUST add placeholder TOC entries that appear on first open (before the user updates the TOC). This prevents showing an empty TOC initially.

Implementation: Always run the add_toc_placeholders.py script after generating the DOCX file:

python skills/docx/scripts/add_toc_placeholders.py document.docx \
  --entries '[{"level":1,"text":"Chapter 1 Overview","page":"1"},{"level":2,"text":"Section 1.1 Details","page":"1"}]'

Note: The script supports up to 3 TOC levels for placeholder entries.

Entry format:

• level: Heading level (1, 2, or 3)
• text: The heading text
• page: Estimated page number (will be corrected when TOC is updated)

Auto-generating entries: You can extract the actual headings from the document structure to generate accurate entries. Match the heading text and hierarchy from your document content.

Benefits:

• Users see TOC content immediately on first open
• Placeholders are automatically replaced when user updates the TOC
• Improves perceived document quality and user experience

Document Formatting Rules

Page Break Restrictions Page breaks are ONLY allowed in these specific locations:

• Between cover page and table of contents (if TOC exists)
• Between cover page and main content (if NO TOC exists)
• Between table of contents and main content (if TOC exists)

All content after the table of contents must flow continuously WITHOUT page breaks.

Text and Paragraph Rules

• Complete sentences before starting a new line — do not break sentences across lines
• Use single, consistent style for each complete sentence
• Only start a new paragraph when the current paragraph is logically complete

List and Bullet Point Formatting

• Use left-aligned formatting (NOT justified alignment)
• Insert a line break after each list item
• Never place multiple items on the same line (justification stretches text)

Editing an existing Word document

Note: For .doc (legacy format), first convert with libreoffice --convert-to docx file.doc.

When editing an existing Word document, use the Document library (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read `ooxml.md` (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for the Document library API and XML patterns for directly editing document files. 2. Unpack the document: python ooxml/scripts/unpack.py <office_file> <output_directory> 3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md) 4. Pack the final document: python ooxml/scripts/pack.py <input_directory> <office_file>

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

Adding Comments (批注)

Comments (批注) allow you to add annotations to documents without modifying the actual content. This is useful for review feedback, explanations, or questions about specific parts of a document.

Recommended Method: Using python-docx (简单推荐)

The simplest and most reliable way to add comments is using the python-docx library:

from docx import Document

# Open the document
doc = Document('input.docx')

# Find paragraphs and add comments
for para in doc.paragraphs:
    if "关键词" in para.text:  # Find paragraphs containing specific text
        doc.add_comment(
            runs=[para.runs[0]],  # Specify the text to comment on
            text="批注内容",
            author="Z.ai"          # Set comment author as Z.ai
        )

# Save the document
doc.save('output.docx')

Key points:

• Install: pip install python-docx or bun add python-docx
• Works directly on .docx files (no need to unpack/pack)
• Simple API, reliable results
• Comments appear in Word's comment pane with Z.ai as author

Common patterns:

from docx import Document

doc = Document('document.docx')

# Add comment to first paragraph
if doc.paragraphs:
    first_para = doc.paragraphs[0]
    doc.add_comment(
        runs=[first_para.runs[0]] if first_para.runs else [],
        text="Review this introduction",
        author="Z.ai"
    )

# Add comment to specific paragraph by index
target_para = doc.paragraphs[5]  # 6th paragraph
doc.add_comment(
    runs=[target_para.runs[0]],
    text="This section needs clarification",
    author="Z.ai"
)

# Add comments based on text search
for para in doc.paragraphs:
    if "important" in para.text.lower():
        doc.add_comment(
            runs=[para.runs[0]],
            text="Flagged for review",
            author="Z.ai"
        )

doc.save('output.docx')

Alternative Method: Using OOXML (Advanced)

For complex scenarios requiring low-level XML manipulation, you can use the OOXML workflow. This method is more complex but provides finer control.

Note: This method requires unpacking/packing documents and may encounter validation issues. Use python-docx unless you specifically need low-level XML control.

OOXML Workflow

1. Unpack the document: python ooxml/scripts/unpack.py <file.docx> <output_dir>

2. Create and run a Python script:

from scripts.document import Document

# Initialize with Z.ai as the author
doc = Document('unpacked', author="Z.ai", initials="Z")

# Add comment on a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
doc.add_comment(start=para, end=para, text="This needs clarification")

# Save changes
doc.save()

3. Pack the document: python ooxml/scripts/pack.py <unpacked_dir> <output.docx>

When to use OOXML method:

• You need to work with tracked changes simultaneously
• You need fine-grained control over XML structure
• You're already working with unpacked documents
• You need to manipulate comments in complex ways

When to use python-docx method (recommended):

• Adding comments is your primary task
• You want simple, reliable code
• You're working with complete .docx files
• You don't need low-level XML access

Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. CRITICAL: For complete tracked changes, you must implement ALL changes systematically.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

Principle: Minimal, Precise Edits When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the <w:r> element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

Tracked changes workflow

1. Get markdown representation: Convert document to markdown with tracked changes preserved:

   pandoc --track-changes=all path-to-file.docx -o current.md

2. Identify and group changes: Review the document and identify ALL changes needed, organizing them into logical batches:

Location methods (for finding changes in XML):

• Section/heading numbers (e.g., "Section 3.2", "Article IV")
• Paragraph identifiers if numbered
• Grep patterns with unique surrounding text
• Document structure (e.g., "first paragraph", "signature block")
• DO NOT use markdown line numbers - they don't map to XML structure

Batch organization (group 3-10 related changes per batch):

• By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
• By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
• By complexity: Start with simple text replacements, then tackle complex structural changes
• Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"

3. Read documentation and unpack:

• MANDATORY - READ ENTIRE FILE: Read `ooxml.md` (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
• Unpack the document: python ooxml/scripts/unpack.py <file.docx> <dir>
• Note the suggested RSID: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.

4. Implement changes in batches: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:

• Makes debugging easier (smaller batch = easier to isolate errors)
• Allows incremental progress
• Maintains efficiency (batch size of 3-10 changes works well)

Suggested batch groupings:

• By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
• By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
• By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")

For each batch of related changes:

a. Map text to XML: Grep for text in word/document.xml to verify how text is split across <w:r> elements.

b. Create and run script: Use get_node to find nodes, implement changes, then doc.save(). See "Document Library" section in ooxml.md for patterns.

Note: Always grep word/document.xml immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.

5. Pack the document: After all batches are complete, convert the unpacked directory back to .docx:

   python ooxml/scripts/pack.py unpacked reviewed-document.docx

6. Final verification: Do a comprehensive check of the complete document:

• Convert final document to markdown:

     pandoc --track-changes=all reviewed-document.docx -o verification.md

• Verify ALL changes were applied correctly:

     grep "original phrase" verification.md  # Should NOT find it
     grep "replacement phrase" verification.md  # Should find it

• Check that no unintended changes were introduced

Converting Documents to Images

To visually analyze Word documents, convert them to images using a two-step process:

1. Convert DOCX to PDF:

   soffice --headless --convert-to pdf document.docx

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 document.pdf page

This creates files like page-1.jpg, page-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• page: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for DOCX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (install if not available):

• pandoc: sudo apt-get install pandoc (for text extraction)
• docx: bun add docx (for creating new documents)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

Changelog

[Added Comment Feature - python-docx Method] - 2026-01-29

Added

• 批注功能 (Comment Feature): 使用python-docx的简单可靠方案
• 推荐方法: scripts/add_comment_simple.py - 使用python-docx直接操作.docx文件
• 完整示例: scripts/examples/add_comments_pythondocx.py - 展示各种使用场景
• SKILL.md: 更新为推荐python-docx方法
• ooxml.md: 保留OOXML方法作为高级选项
• COMMENTS_UPDATE.md: 详细的功能更新说明

Features

• ✅ 简单易用：无需解压/打包文档
• ✅ 批注人自动设置为"Z.ai"
• ✅ 经过实际验证：在Word中正常显示
• ✅ 支持多种定位方式：文本搜索、段落索引、条件判断等
• ✅ 代码简洁：比OOXML方法简单得多

Method Comparison

Recommended: python-docx

from docx import Document
doc = Document('input.docx')
doc.add_comment(runs=[para.runs[0]], text="批注", author="Z.ai")
doc.save('output.docx')

Alternative: OOXML (Advanced)

from scripts.document import Document
doc = Document('unpacked', author="Z.ai")
para = doc["word/document.xml"].get_node(tag="w:p", contains="text")
doc.add_comment(start=para, end=para, text="批注")
doc.save()

Usage Examples

推荐方法（python-docx）

# 安装依赖
pip install python-docx

# 使用简单脚本
python scripts/add_comment_simple.py input.docx output.docx

# 使用完整示例
python scripts/examples/add_comments_pythondocx.py document.docx reviewed.docx

高级方法（OOXML）

# 解压、处理、打包
python ooxml/scripts/unpack.py document.docx unpacked
python scripts/add_comment.py unpacked 10 "批注内容"
python ooxml/scripts/pack.py unpacked output.docx

Testing

• ✅ python-docx方法经过实际验证
• ✅ 批注在Microsoft Word中正常显示
• ✅ 作者正确显示为"Z.ai"
• ✅ 支持各种定位方式
• ✅ 代码简洁可靠

Documentation

• SKILL.md: 推荐python-docx方法，保留OOXML作为高级选项
• COMMENTS_UPDATE.md: 详细说明两种方法的区别
• 新增python-docx示例脚本
• 保留OOXML示例供高级用户使用

Why python-docx is Recommended

1. 简单: 无需解压/打包文档 2. 可靠: 经过实际验证，在Word中正常工作 3. 直接: 直接操作.docx文件，一步到位 4. 维护性: 代码简洁，易于理解和修改 5. 兼容性: 使用标准库，兼容性好

OOXML方法适合：

• 需要低级XML控制
• 需要同时处理tracked changes
• 需要批注回复等复杂功能
• 已经在使用解压文档的工作流

DOCX Library Tutorial

Generate .docx files with JavaScript/TypeScript.

Important: Read this entire document before starting. Critical formatting rules and common pitfalls are covered throughout - skipping sections may result in corrupted files or rendering issues.

Setup

Assumes docx is already installed globally If not installed: first try bun add docx, then npm install -g docx

const {
  Document,
  Packer,
  Paragraph,
  TextRun,
  Table,
  TableRow,
  TableCell,
  ImageRun,
  Media,
  Header,
  Footer,
  AlignmentType,
  PageOrientation,
  LevelFormat,
  ExternalHyperlink,
  InternalHyperlink,
  TableOfContents,
  HeadingLevel,
  BorderStyle,
  WidthType,
  TabStopType,
  TabStopPosition,
  UnderlineType,
  ShadingType,
  VerticalAlign,
  SymbolRun,
  PageNumber,
  FootnoteReferenceRun,
  Footnote,
  PageBreak
} = require('docx')

// Create & Save
const doc = new Document({
  sections: [
    {
      children: [
        /* content */
      ]
    }
  ]
})
Packer.toBuffer(doc).then((buffer) => fs.writeFileSync('doc.docx', buffer)) // Node.js
Packer.toBlob(doc).then((blob) => {
  /* download logic */
}) // Browser

Delivery Standard

Generic styling and mediocre aesthetics = mediocre delivery.

Deliver studio-quality Word documents with deep thought on content, functionality, and styling. Users often don't explicitly request advanced features (covers, TOC, backgrounds, back covers, footnotes, charts)—deeply understand needs and proactively extend.

The following formatting standards are to be strictly applied without exception:

• Line Spacing: The entire document must use 1.3x line spacing.
• Chart/Figure Placement: All charts, graphs, and figures must be explicitly centered horizontally on the page.

new Table({
  alignment: AlignmentType.CENTER,
  rows: [
    new TableRow({
      children: [
        new TableCell({
          children: [
            new Paragraph({
              text: 'centered text',
              alignment: AlignmentType.CENTER
            })
          ],
          verticalAlign: VerticalAlign.CENTER,
          shading: { fill: colors.tableBg },
          borders: cellBorders
        })
      ]
    })
  ]
})

• The text in charts must have left/right/up/bottom margin.
• Image Handling：Preserve aspect ratio\\: Never adjust image aspect ratio. Must insert according to the original ratio.
• Do not use background shading to all table section headers.

Compliance with these specifications is mandatory.

Language Consistency

Document language = User conversation language (including filename, body text, headings, headers, TOC hints, chart labels, and all other text).

Headers and Footers - REQUIRED BY DEFAULT

Most documents MUST include headers and footers. The specific style (alignment, format, content) should match the document's overall design.

• Header: Typically document title, company name, or chapter name
• Footer: Typically page numbers (format flexible: "X / Y", "Page X", "— X —", etc.)
• Cover/Back cover: Use TitlePage setting to hide header/footer on first page

Fonts

If the user do not require specific fonts, you must follow the fonts rule belowing:

For Chinese:

• Microsoft YaHei, located at /usr/share/fonts/truetype/chinese/msyh.ttf
• SimHei, located at /usr/share/fonts/truetype/chinese/SimHei.ttf
• Code blocks: SarasaMonoSC, located at /usr/share/fonts/truetype/chinese/SarasaMonoSC-Regular.ttf
• Formulas / symbols: DejaVuSans, located at /usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf
• For body text and formulas, use Paragraph instead of Preformatted.

For English

• Times New Roman, located at /usr/share/fonts/truetype/english/Times-New-Roman.ttf
• Calibri,located at /usr/share/fonts/truetype/english/calibri-regular.ttf

Spacing & Paragraph Alignment

Task: Apply the following formatting rules to the provided text for a professional bilingual (Chinese/English) layout.

Paragraph & Indentation:

Chinese Body: First-line indent of 2 characters (420 twips). English Body: No first-line indent; use block format (space between paragraphs). Alignment: Justified (Both) for all body text; Centered for Titles and Table Headers.

Line & Paragraph Spacing（keep in mind）

Line Spacing: Set to 1.3 (250 twips) lines for both languages. Heading 1: 600 twips before, 300 twips after.

Mixed-Language Kerning:

Insert a standard half-width space between Chinese characters and English words/numbers (e.g., "共 20 个 items").

Punctuation:

Use full-width punctuation for Chinese text and half-width punctuation for English text.

Professional Elements (Critical)

Produce documents that surpass user expectations by proactively incorporating high-end design elements without being prompted. Quality Benchmark: Visual excellence reflecting the standards of a top-tier designer in 2025.

Cover & Visual:

• Double-Sided Branding: All formal documents (proposals, reports, contracts, bids) and creative assets (invitations, greeting cards) must include both a standalone front and back cover.
• Internal Accents: Body pages may include subtle background elements to enhance the overall aesthetic depth.

Structure:

• Navigation: For any document with three or more sections, include a Table of Contents (TOC) immediately followed by a "refresh hint."

Data Presentation:

• Visual Priority: Use professional charts to illustrate trends or comparisons rather than plain text lists.
• Table Aesthetics: Apply light gray headers or the "three-line" professional style; strictly avoid the default Word blue.

Links & References:

• Interactive Links: All URLs must be formatted as clickable, active hyperlinks.
• Cross-Referencing: Number all figures and tables systematically (e.g., "see Figure 1") and use internal cross-references.
• Academic/Legal Rigor: For research or data-heavy documents, implement clickable in-text citations paired with accurate footnotes or endnotes.

TOC Refresh Hint

Because Word TOCs utilize field codes, page numbers may become unaligned during generation. You must append the following gray hint text after the TOC to guide the user: Note: This Table of Contents is generated via field codes. To ensure page number accuracy after editing, please right-click the TOC and select "Update Field."

Outline Adherence

• User provides outline: Follow strictly, no additions, deletions, or reordering
• No outline provided: Use standard structure
• Academic: Introduction → Literature Review → Methodology → Results → Discussion → Conclusion.
• Business: Executive Summary → Analysis → Recommendations.
• Technical: Overview → Principles → Implementation → Examples → FAQ.

Scene Completeness

Anticipate the functional requirements of the specific scenario. Examples include, but are not limited to:

• Exam paper → Include name/class/ID fields, point allocations for every question, and a dedicated grading table.
• Contract → Provide signature and seal blocks for all parties, date placeholders, contract ID numbers, and an attachment list.
• Meeting minutes → List attendees and absentees, define action items with assigned owners, and note the next meeting time.

Design Philosophy

Color Scheme

Low saturation tones, avoid Word default blue and matplotlib default high saturation.

Flexibly choose color schemes based on document scenario:

Color scheme must be consistent within the same document.

highlighting

Use low saturation color schemes for font highlighting.

Layout

White space (margins, paragraph spacing), clear hierarchy (H1 > H2 > body), proper padding (text shouldn't touch borders).

Pagination Control

Word uses flow layout, not fixed pages.

Alignment and Typography (keep in mind!!!)

CJK body: justify + 2-char indent. English: left. Table numbers: right. Headings: no indent. For both languages, Must use a line spacing of 1.3x (250 twips). Do not use single line spacing !!!

Table Formatting（Very inportant）

• A caption must be added immediately after the table, keep in mind!
• The entire table must be centered horizontally on the page. keep in mind!

Cell Formatting (Inside the Table)

Left/Right Cell Margin: Set to at least 120-200 twips (approximately the width of one character). Up/Down Cell Margin: Set to at least 100 twips Text Alignment(must follow !!!):

• Horizontal Alignment: Center-aligned. This creates a clean vertical axis through the table column.
• Vertical Alignment: Center-aligned. Text must be positioned exactly in the middle of the cell's height to prevent it from "floating" too close to the top or bottom borders.
• Cell Margins (Padding):

Left/Right: Set to 120–200 twips (approx. 0.2–0.35 cm). This ensures text does not touch the borders, maintaining legibility. Top/Bottom: Set to at least 60–100 twips to provide a consistent vertical buffer around the text.

Page break

There must be page break between cover page and the content, between table of content and the content also, should NOT put cover page and content in a single page.

Page Layout & Margins (A4 Standard)

The layout uses a 1440 twip (1 inch) margin for content, with specialized margins for the cover.

Text & Formatting

// IMPORTANT: Never use \n for line breaks - always use separate Paragraph elements
// ❌ WRONG: new TextRun("Line 1\nLine 2")
// ✅ CORRECT: new Paragraph({ children: [new TextRun("Line 1")] }), new Paragraph({ children: [new TextRun("Line 2")] })

// First-line indent for body paragraphs
// IMPORTANT: Chinese documents typically use 2-character indent (about 480 DXA for 12pt SimSun)
new Paragraph({
  indent: { firstLine: 480 }, // 2-character first-line indent for Chinese body text
  children: [
    new TextRun({
      text: 'This is the main text (Chinese). The first line is indented by two characters.',
      font: 'SimSun'
    })
  ]
})

// Basic text with all formatting options
new Paragraph({
  alignment: AlignmentType.CENTER,
  spacing: { before: 200, after: 200 },
  indent: { left: 720, right: 720, firstLine: 480 }, // Can combine with left/right indent
  children: [
    new TextRun({ text: 'Bold', bold: true }),
    new TextRun({ text: 'Italic', italics: true }),
    new TextRun({ text: 'Underlined', underline: { type: UnderlineType.DOUBLE, color: 'FF0000' } }),
    new TextRun({ text: 'Colored', color: 'FF0000', size: 28, font: 'Times New Roman' }), // Times New Roman (system font)
    new TextRun({ text: 'Highlighted', highlight: 'yellow' }),
    new TextRun({ text: 'Strikethrough', strike: true }),
    new TextRun({ text: 'x2', superScript: true }),
    new TextRun({ text: 'H2O', subScript: true }),
    new TextRun({ text: 'SMALL CAPS', smallCaps: true }),
    new SymbolRun({ char: '2022', font: 'Symbol' }), // Bullet •
    new SymbolRun({ char: '00A9', font: 'Arial' }) // Copyright © - Arial for symbols
  ]
})

Styles & Professional Formatting

const doc = new Document({
  styles: {
    default: { document: { run: { font: 'Times New Roman', size: 24 } } }, // 12pt default (system font)
    paragraphStyles: [
      // Document title style - override built-in Title style
      {
        id: 'Title',
        name: 'Title',
        basedOn: 'Normal',
        run: { size: 56, bold: true, color: '000000', font: 'Times New Roman' },
        paragraph: { spacing: { before: 240, after: 120 }, alignment: AlignmentType.CENTER }
      },
      // IMPORTANT: Override built-in heading styles by using their exact IDs
      {
        id: 'Heading1',
        name: 'Heading 1',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 32, bold: true, color: '000000', font: 'Times New Roman' }, // 16pt
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 }
      }, // outlineLevel enables TOC generation if needed
      {
        id: 'Heading2',
        name: 'Heading 2',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 28, bold: true, color: '000000', font: 'Times New Roman' }, // 14pt
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 }
      },
      // Custom styles use your own IDs
      {
        id: 'myStyle',
        name: 'My Style',
        basedOn: 'Normal',
        run: { size: 28, bold: true, color: '000000' },
        paragraph: { spacing: { after: 120 }, alignment: AlignmentType.CENTER }
      }
    ],
    characterStyles: [
      {
        id: 'myCharStyle',
        name: 'My Char Style',
        run: { color: 'FF0000', bold: true, underline: { type: UnderlineType.SINGLE } }
      }
    ]
  },
  sections: [
    {
      properties: { page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } },
      children: [
        new Paragraph({ heading: HeadingLevel.TITLE, children: [new TextRun('Document Title')] }), // Uses overridden Title style
        new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('Heading 1')] }), // Uses overridden Heading1 style
        new Paragraph({ style: 'myStyle', children: [new TextRun('Custom paragraph style')] }),
        new Paragraph({
          children: [
            new TextRun('Normal with '),
            new TextRun({ text: 'custom char style', style: 'myCharStyle' })
          ]
        })
      ]
    }
  ]
})

Font Management Strategy (CRITICAL):

ALWAYS prioritize system-installed fonts for reliability, performance, and cross-platform compatibility:

1. System fonts FIRST (no download, immediate availability):

• English: Times New Roman (professional standard)
• Chinese: SimSun/宋体 (formal document standard)
• Universal fallbacks: Arial, Calibri, Helvetica

2. Avoid custom font downloads unless absolutely necessary for specific branding 3. Test font availability before deployment

Professional Font Combinations (System Fonts Only):

• Times New Roman (Headers) + Times New Roman (Body) - Classic, professional, universally supported
• Arial (Headers) + Arial (Body) - Clean, modern, universally supported
• Times New Roman (Headers) + Arial (Body) - Classic serif headers with modern body

Chinese Document Font Guidelines (System Fonts):

• Body text: Use SimSun/宋体 - the standard system font for Chinese formal documents
• Headings: Use SimHei/黑体 - bold sans-serif for visual hierarchy
• Default size: 12pt (size: 24) for body, 14-16pt for headings
• CRITICAL: SimSun for body text, SimHei ONLY for headings - never use SimHei for entire document

// English document style configuration (Times New Roman)
const doc = new Document({
  styles: {
    default: { document: { run: { font: 'Times New Roman', size: 24 } } }, // 12pt for body
    paragraphStyles: [
      {
        id: 'Heading1',
        name: 'Heading 1',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 32, bold: true, font: 'Times New Roman' }, // 16pt for H1
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 }
      },
      {
        id: 'Heading2',
        name: 'Heading 2',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 28, bold: true, font: 'Times New Roman' }, // 14pt for H2
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 }
      }
    ]
  }
})

// Chinese document style configuration (SimSun/SimHei)
const doc = new Document({
  styles: {
    default: { document: { run: { font: 'SimSun', size: 24 } } }, // SimSun 12pt for body
    paragraphStyles: [
      {
        id: 'Heading1',
        name: 'Heading 1',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 32, bold: true, font: 'SimHei' }, // SimHei 16pt for H1
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 }
      },
      {
        id: 'Heading2',
        name: 'Heading 2',
        basedOn: 'Normal',
        next: 'Normal',
        quickFormat: true,
        run: { size: 28, bold: true, font: 'SimHei' }, // SimHei 14pt for H2
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 }
      }
    ]
  }
})

Key Styling Principles:

• ALWAYS use system-installed fonts (Times New Roman for English, SimSun for Chinese)
• Override built-in styles: Use exact IDs like "Heading1", "Heading2", "Heading3" to override Word's built-in heading styles
• HeadingLevel constants: HeadingLevel.HEADING_1 uses "Heading1" style, HeadingLevel.HEADING_2 uses "Heading2" style, etc.
• outlineLevel: Set outlineLevel: 0 for H1, outlineLevel: 1 for H2, etc. (optional, only needed if TOC will be added)
• Use custom styles instead of inline formatting for consistency
• Set a default font using styles.default.document.run.font - Times New Roman for English, SimSun for Chinese
• Establish visual hierarchy with different font sizes (titles > headers > body)
• Add proper spacing with before and after paragraph spacing
• Use colors sparingly: Default to black (000000) and shades of gray for titles and headings (heading 1, heading 2, etc.)
• Set consistent margins (1440 = 1 inch is standard)

Lists (ALWAYS USE PROPER LISTS - NEVER USE UNICODE BULLETS)

⚠️ CRITICAL: Numbered List References - Read This Before Creating Lists!

Each independently numbered list MUST use a UNIQUE reference name

Rules:

• Same reference = continues numbering (1,2,3 → 4,5,6)
• Different reference = restarts at 1 (1,2,3 → 1,2,3)

When to use a new reference?

• ✓ Numbered lists under new headings/sections
• ✓ Any list that needs independent numbering
• ✗ Subsequent items of the same list (keep using same reference)

Reference naming suggestions:

• list-section-1, list-section-2, list-section-3
• list-chapter-1, list-chapter-2
• list-requirements, list-constraints (name based on content)

// ❌ WRONG: All lists use the same reference
numbering: {
  config: [
    { reference: "my-list", levels: [...] }  // Only one config
  ]
}
// Result:
// Chapter 1
//   1. Item A
//   2. Item B
// Chapter 2
//   3. Item C    ← WRONG! Should start from 1
//   4. Item D

// ✅ CORRECT: Each list uses different reference
numbering: {
  config: [
    { reference: "list-chapter-1", levels: [...] },
    { reference: "list-chapter-2", levels: [...] },
    { reference: "list-chapter-3", levels: [...] }
  ]
}
// Result:
// Chapter 1
//   1. Item A
//   2. Item B
// Chapter 2
//   1. Item C    ✓ CORRECT! Restarts from 1
//   2. Item D
// Chapter 3
//   1. Item E    ✓ CORRECT! Restarts from 1
//   2. Item F

Basic List Syntax

// Bullets - ALWAYS use the numbering config, NOT unicode symbols
// CRITICAL: Use LevelFormat.BULLET constant, NOT the string "bullet"
const doc = new Document({
  numbering: {
    config: [
      {
        reference: 'bullet-list',
        levels: [
          {
            level: 0,
            format: LevelFormat.BULLET,
            text: '•',
            alignment: AlignmentType.LEFT,
            style: { paragraph: { indent: { left: 720, hanging: 360 } } }
          }
        ]
      },
      {
        reference: 'first-numbered-list',
        levels: [
          {
            level: 0,
            format: LevelFormat.DECIMAL,
            text: '%1.',
            alignment: AlignmentType.LEFT,
            style: { paragraph: { indent: { left: 720, hanging: 360 } } }
          }
        ]
      },
      {
        reference: 'second-numbered-list', // Different reference = restarts at 1
        levels: [
          {
            level: 0,
            format: LevelFormat.DECIMAL,
            text: '%1.',
            alignment: AlignmentType.LEFT,
            style: { paragraph: { indent: { left: 720, hanging: 360 } } }
          }
        ]
      }
    ]
  },
  sections: [
    {
      children: [
        // Bullet list items
        new Paragraph({
          numbering: { reference: 'bullet-list', level: 0 },
          children: [new TextRun('First bullet point')]
        }),
        new Paragraph({
          numbering: { reference: 'bullet-list', level: 0 },
          children: [new TextRun('Second bullet point')]
        }),
        // Numbered list items
        new Paragraph({
          numbering: { reference: 'first-numbered-list', level: 0 },
          children: [new TextRun('First numbered item')]
        }),
        new Paragraph({
          numbering: { reference: 'first-numbered-list', level: 0 },
          children: [new TextRun('Second numbered item')]
        }),
        // ⚠️ CRITICAL: Different reference = INDEPENDENT list that restarts at 1
        // Same reference = CONTINUES previous numbering
        new Paragraph({
          numbering: { reference: 'second-numbered-list', level: 0 },
          children: [new TextRun('Starts at 1 again (because different reference)')]
        })
      ]
    }
  ]
})

// ⚠️ CRITICAL: NEVER use unicode bullets - they create fake lists that don't work properly
// new TextRun("• Item")           // WRONG
// new SymbolRun({ char: "2022" }) // WRONG
// ✅ ALWAYS use numbering config with LevelFormat.BULLET for real Word lists

Tables

// Complete table with margins, borders, headers, and bullet points
const tableBorder = { style: BorderStyle.SINGLE, size: 1, color: 'CCCCCC' }
const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder }

new Table({
  columnWidths: [4680, 4680], // ⚠️ CRITICAL: Set column widths at table level - values in DXA (twentieths of a point)
  // ⚠️ MANDATORY: margins MUST be set to prevent text touching borders
  margins: { top: 100, bottom: 100, left: 180, right: 180 }, // Minimum comfortable padding
  rows: [
    new TableRow({
      tableHeader: true,
      children: [
        new TableCell({
          borders: cellBorders,
          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
          // ⚠️ CRITICAL: Always use ShadingType.CLEAR to prevent black backgrounds in Word.
          shading: { fill: 'D5E8F0', type: ShadingType.CLEAR },
          verticalAlign: VerticalAlign.CENTER,
          children: [
            new Paragraph({
              alignment: AlignmentType.CENTER,
              children: [new TextRun({ text: 'Header', bold: true, size: 22 })]
            })
          ]
        }),
        new TableCell({
          borders: cellBorders,
          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
          shading: { fill: 'D5E8F0', type: ShadingType.CLEAR },
          children: [
            new Paragraph({
              alignment: AlignmentType.CENTER,
              children: [new TextRun({ text: 'Bullet Points', bold: true, size: 22 })]
            })
          ]
        })
      ]
    }),
    new TableRow({
      children: [
        new TableCell({
          borders: cellBorders,
          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
          children: [new Paragraph({ children: [new TextRun('Regular data')] })]
        }),
        new TableCell({
          borders: cellBorders,
          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
          children: [
            new Paragraph({
              numbering: { reference: 'bullet-list', level: 0 },
              children: [new TextRun('First bullet point')]
            }),
            new Paragraph({
              numbering: { reference: 'bullet-list', level: 0 },
              children: [new TextRun('Second bullet point')]
            })
          ]
        })
      ]
    })
  ]
})

IMPORTANT: Table Width & Borders

• Use BOTH columnWidths: [width1, width2, ...] array AND width: { size: X, type: WidthType.DXA } on each cell
• Values in DXA (twentieths of a point): 1440 = 1 inch, Letter usable width = 9360 DXA (with 1" margins)
• Apply borders to individual TableCell elements, NOT the Table itself

Precomputed Column Widths (Letter size with 1" margins = 9360 DXA total):

• 2 columns: columnWidths: [4680, 4680] (equal width)
• 3 columns: columnWidths: [3120, 3120, 3120] (equal width)

Links & Navigation

// TOC example
// new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" }),
//
// CRITICAL: If adding TOC, use HeadingLevel only, NOT custom styles
// ❌ WRONG: new Paragraph({ heading: HeadingLevel.HEADING_1, style: "customHeader", children: [new TextRun("Title")] })
// ✅ CORRECT: new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] })

// REQUIRED: After generating the DOCX, add TOC placeholders for first-open experience
// Always run: python skills/docx/scripts/add_toc_placeholders.py document.docx --entries '[...]'
// This adds placeholder entries that appear before the user updates the TOC (modifies file in-place)
// Extract headings from your document to generate accurate entries

// External link
new Paragraph({
  children: [new ExternalHyperlink({
    children: [new TextRun({ text: "Google", style: "Hyperlink" })],
    link: "https://www.google.com"
  })]
}),

// Internal link & bookmark
new Paragraph({
  children: [new InternalHyperlink({
    children: [new TextRun({ text: "Go to Section", style: "Hyperlink" })],
    anchor: "section1"
  })]
}),
new Paragraph({
  children: [new TextRun("Section Content")],
  bookmark: { id: "section1", name: "section1" }
}),

Use new Paragraph({ children: [new PageBreak()] }) at the start of the next section to ensure TOC is isolated.

Images & Media

// Basic image with sizing & positioning
// CRITICAL: Always specify 'type' parameter - it's REQUIRED for ImageRun
new Paragraph({
  alignment: AlignmentType.CENTER,
  children: [
    new ImageRun({
      type: 'png', // NEW REQUIREMENT: Must specify image type (png, jpg, jpeg, gif, bmp, svg)
      data: fs.readFileSync('image.png'),
      transformation: { width: 200, height: 150, rotation: 0 }, // rotation in degrees
      altText: { title: 'Logo', description: 'Company logo', name: 'Name' } // IMPORTANT: All three fields are required
    })
  ]
})

Page Breaks

// Manual page break
;(new Paragraph({ children: [new PageBreak()] }),
  // Page break before paragraph
  new Paragraph({
    pageBreakBefore: true,
    children: [new TextRun('This starts on a new page')]
  }))

// ⚠️ CRITICAL: NEVER use PageBreak standalone - it will create invalid XML that Word cannot open
// ❌ WRONG: new PageBreak()
// ✅ CORRECT: new Paragraph({ children: [new PageBreak()] })

Cover Page

If the document has a cover page, the cover content should be centered both horizontally and vertically.

Important notes for cover pages:

• Horizontal centering: Use alignment: AlignmentType.CENTER on all cover page paragraphs
• Vertical centering: Use spacing: { before: XXXX } on elements to visually center content (adjust based on page height)
• Separate section: Create a dedicated section for the cover page to separate it from main content
• Page break: Use new Paragraph({ children: [new PageBreak()] }) at the start of the next section to ensure cover is isolated

Headers/Footers & Page Setup

const doc = new Document({
  sections: [
    {
      properties: {
        page: {
          margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1440 = 1 inch
          size: { orientation: PageOrientation.LANDSCAPE },
          pageNumbers: { start: 1, formatType: 'decimal' } // "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"
        }
      },
      headers: {
        default: new Header({
          children: [
            new Paragraph({
              alignment: AlignmentType.RIGHT,
              children: [new TextRun('Header Text')]
            })
          ]
        })
      },
      footers: {
        default: new Footer({
          children: [
            new Paragraph({
              alignment: AlignmentType.CENTER,
              children: [
                new TextRun('Page '),
                new TextRun({ children: [PageNumber.CURRENT] }),
                new TextRun(' of '),
                new TextRun({ children: [PageNumber.TOTAL_PAGES] })
              ]
            })
          ]
        })
      },
      children: [
        /* content */
      ]
    }
  ]
})

Tabs

new Paragraph({
  tabStops: [
    { type: TabStopType.LEFT, position: TabStopPosition.MAX / 4 },
    { type: TabStopType.CENTER, position: TabStopPosition.MAX / 2 },
    { type: TabStopType.RIGHT, position: (TabStopPosition.MAX * 3) / 4 }
  ],
  children: [new TextRun('Left\tCenter\tRight')]
})

Constants & Quick Reference

• Underlines: SINGLE, DOUBLE, WAVY, DASH
• Borders: SINGLE, DOUBLE, DASHED, DOTTED
• Numbering: DECIMAL (1,2,3), UPPER_ROMAN (I,II,III), LOWER_LETTER (a,b,c)
• Tabs: LEFT, CENTER, RIGHT, DECIMAL
• Symbols: "2022" (•), "00A9" (©), "00AE" (®), "2122" (™), "00B0" (°), "F070" (✓), "F0FC" (✗)

Critical Issues & Common Mistakes

• CRITICAL for cover pages: If the document has a cover page, the cover content should be centered both horizontally (AlignmentType.CENTER) and vertically (use spacing.before to adjust)
• CRITICAL: PageBreak must ALWAYS be inside a Paragraph - standalone PageBreak creates invalid XML that Word cannot open
• ALWAYS use ShadingType.CLEAR for table cell shading - Never use ShadingType.SOLID (causes black background).
• Measurements in DXA (1440 = 1 inch) | Each table cell needs ≥1 Paragraph | If TOC is added, it requires HeadingLevel styles only
• CRITICAL: ALWAYS use system-installed fonts - Times New Roman for English, SimSun for Chinese - NEVER download custom fonts unless absolutely necessary
• ALWAYS use custom styles with appropriate system fonts for professional appearance and proper visual hierarchy
• ALWAYS set a default font using styles.default.document.run.font - Times New Roman for English, SimSun for Chinese
• CRITICAL for Chinese documents: Use SimSun for body text, SimHei ONLY for headings - NEVER use SimHei for entire document
• CRITICAL for Chinese body text: Add first-line indent with indent: { firstLine: 480 } (approximately 2 characters for 12pt font)
• ALWAYS use columnWidths array for tables + individual cell widths for compatibility
• NEVER use unicode symbols for bullets - always use proper numbering configuration with LevelFormat.BULLET constant (NOT the string "bullet")
• NEVER use \n for line breaks anywhere - always use separate Paragraph elements for each line
• ALWAYS use TextRun objects within Paragraph children - never use text property directly on Paragraph
• CRITICAL for images: ImageRun REQUIRES type parameter - always specify "png", "jpg", "jpeg", "gif", "bmp", or "svg"
• CRITICAL for bullets: Must use LevelFormat.BULLET constant, not string "bullet", and include text: "•" for the bullet character
• CRITICAL for numbering: Each numbering reference creates an INDEPENDENT list. Same reference = continues numbering (1,2,3 then 4,5,6). Different reference = restarts at 1 (1,2,3 then 1,2,3). Use unique reference names for each separate numbered section!
• CRITICAL for TOC: When using TableOfContents, headings must use HeadingLevel ONLY - do NOT add custom styles to heading paragraphs or TOC will break.
• CRITICAL for Tables: Set columnWidths array + individual cell widths, apply borders to cells not table
• MANDATORY for Tables: ALWAYS set margins at Table level - this prevents text from touching borders and is required for professional quality. NEVER omit this property.
• Set table margins at TABLE level for consistent cell padding (avoids repetition per cell)

Office Open XML Technical Reference

Important: Read this entire document before starting. This document covers:

• Technical Guidelines - Schema compliance rules and validation requirements
• Document Content Patterns - XML patterns for headings, lists, tables, formatting, etc.
• Document Library (Python) - Recommended approach for OOXML manipulation with automatic infrastructure setup
• Tracked Changes (Redlining) - XML patterns for implementing tracked changes

Technical Guidelines

Schema Compliance

• Element ordering in `<w:pPr>`: <w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>
• Whitespace: Add xml:space='preserve' to <w:t> elements with leading/trailing spaces
• Unicode: Escape characters in ASCII content: " becomes “
• Character encoding reference: Curly quotes "" become “”, apostrophe ' becomes ’, em-dash — becomes —
• Tracked changes: Use <w:del> and <w:ins> tags with w:author="GLM" outside <w:r> elements
• Critical: <w:ins> closes with </w:ins>, <w:del> closes with </w:del> - never mix
• RSIDs must be 8-digit hex: Use values like 00AB1234 (only 0-9, A-F characters)
• trackRevisions placement: Add <w:trackRevisions/> after <w:proofState> in settings.xml
• Images: Add to word/media/, reference in document.xml, set dimensions to prevent overflow

Document Content Patterns

Basic Structure

<w:p>
  <w:r><w:t>Text content</w:t></w:r>
</w:p>

Headings and Styles

<w:p>
  <w:pPr>
    <w:pStyle w:val="Title"/>
    <w:jc w:val="center"/>
  </w:pPr>
  <w:r><w:t>Document Title</w:t></w:r>
</w:p>

<w:p>
  <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
  <w:r><w:t>Section Heading</w:t></w:r>
</w:p>

Text Formatting

<!-- Bold -->
<w:r><w:rPr><w:b/><w:bCs/></w:rPr><w:t>Bold</w:t></w:r>
<!-- Italic -->
<w:r><w:rPr><w:i/><w:iCs/></w:rPr><w:t>Italic</w:t></w:r>
<!-- Underline -->
<w:r><w:rPr><w:u w:val="single"/></w:rPr><w:t>Underlined</w:t></w:r>
<!-- Highlight -->
<w:r><w:rPr><w:highlight w:val="yellow"/></w:rPr><w:t>Highlighted</w:t></w:r>

Lists

<!-- Numbered list -->
<w:p>
  <w:pPr>
    <w:pStyle w:val="ListParagraph"/>
    <w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr>
    <w:spacing w:before="240"/>
  </w:pPr>
  <w:r><w:t>First item</w:t></w:r>
</w:p>

<!-- Restart numbered list at 1 - use different numId -->
<w:p>
  <w:pPr>
    <w:pStyle w:val="ListParagraph"/>
    <w:numPr><w:ilvl w:val="0"/><w:numId w:val="2"/></w:numPr>
    <w:spacing w:before="240"/>
  </w:pPr>
  <w:r><w:t>New list item 1</w:t></w:r>
</w:p>

<!-- Bullet list (level 2) -->
<w:p>
  <w:pPr>
    <w:pStyle w:val="ListParagraph"/>
    <w:numPr><w:ilvl w:val="1"/><w:numId w:val="1"/></w:numPr>
    <w:spacing w:before="240"/>
    <w:ind w:left="900"/>
  </w:pPr>
  <w:r><w:t>Bullet item</w:t></w:r>
</w:p>

Tables

<w:tbl>
  <w:tblPr>
    <w:tblStyle w:val="TableGrid"/>
    <w:tblW w:w="0" w:type="auto"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="4675"/><w:gridCol w:w="4675"/>
  </w:tblGrid>
  <w:tr>
    <w:tc>
      <w:tcPr><w:tcW w:w="4675" w:type="dxa"/></w:tcPr>
      <w:p><w:r><w:t>Cell 1</w:t></w:r></w:p>
    </w:tc>
    <w:tc>
      <w:tcPr><w:tcW w:w="4675" w:type="dxa"/></w:tcPr>
      <w:p><w:r><w:t>Cell 2</w:t></w:r></w:p>
    </w:tc>
  </w:tr>
</w:tbl>

Layout

<!-- Page break before new section (common pattern) -->
<w:p>
  <w:r>
    <w:br w:type="page"/>
  </w:r>
</w:p>
<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
  </w:pPr>
  <w:r>
    <w:t>New Section Title</w:t>
  </w:r>
</w:p>

<!-- Centered paragraph -->
<w:p>
  <w:pPr>
    <w:spacing w:before="240" w:after="0"/>
    <w:jc w:val="center"/>
  </w:pPr>
  <w:r><w:t>Centered text</w:t></w:r>
</w:p>

<!-- Font change - paragraph level (applies to all runs) -->
<w:p>
  <w:pPr>
    <w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/></w:rPr>
  </w:pPr>
  <w:r><w:t>Monospace text</w:t></w:r>
</w:p>

<!-- Font change - run level (specific to this text) -->
<w:p>
  <w:r>
    <w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/></w:rPr>
    <w:t>This text is Courier New</w:t>
  </w:r>
  <w:r><w:t> and this text uses default font</w:t></w:r>
</w:p>

File Updates

When adding content, update these files:

`word/_rels/document.xml.rels`:

<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/>
<Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image1.png"/>

`[Content_Types].xml`:

<Default Extension="png" ContentType="image/png"/>
<Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>

Images

CRITICAL: Calculate dimensions to prevent page overflow and maintain aspect ratio.

<!-- Minimal required structure -->
<w:p>
  <w:r>
    <w:drawing>
      <wp:inline>
        <wp:extent cx="2743200" cy="1828800"/>
        <wp:docPr id="1" name="Picture 1"/>
        <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
          <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
            <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
              <pic:nvPicPr>
                <pic:cNvPr id="0" name="image1.png"/>
                <pic:cNvPicPr/>
              </pic:nvPicPr>
              <pic:blipFill>
                <a:blip r:embed="rId5"/>
                <!-- Add for stretch fill with aspect ratio preservation -->
                <a:stretch>
                  <a:fillRect/>
                </a:stretch>
              </pic:blipFill>
              <pic:spPr>
                <a:xfrm>
                  <a:ext cx="2743200" cy="1828800"/>
                </a:xfrm>
                <a:prstGeom prst="rect"/>
              </pic:spPr>
            </pic:pic>
          </a:graphicData>
        </a:graphic>
      </wp:inline>
    </w:drawing>
  </w:r>
</w:p>

Links (Hyperlinks)

IMPORTANT: All hyperlinks (both internal and external) require the Hyperlink style to be defined in styles.xml. Without this style, links will look like regular text instead of blue underlined clickable links.

External Links:

<!-- In document.xml -->
<w:hyperlink r:id="rId5">
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>Link Text</w:t>
  </w:r>
</w:hyperlink>

<!-- In word/_rels/document.xml.rels -->
<Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
              Target="https://www.example.com/" TargetMode="External"/>

Internal Links:

<!-- Link to bookmark -->
<w:hyperlink w:anchor="myBookmark">
  <w:r>
    <w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
    <w:t>Link Text</w:t>
  </w:r>
</w:hyperlink>

<!-- Bookmark target -->
<w:bookmarkStart w:id="0" w:name="myBookmark"/>
<w:r><w:t>Target content</w:t></w:r>
<w:bookmarkEnd w:id="0"/>

Hyperlink Style (required in styles.xml):

<w:style w:type="character" w:styleId="Hyperlink">
  <w:name w:val="Hyperlink"/>
  <w:basedOn w:val="DefaultParagraphFont"/>
  <w:uiPriority w:val="99"/>
  <w:unhideWhenUsed/>
  <w:rPr>
    <w:color w:val="467886" w:themeColor="hyperlink"/>
    <w:u w:val="single"/>
  </w:rPr>
</w:style>

Document Library (Python)

Use the Document class from scripts/document.py for all tracked changes and comments. It automatically handles infrastructure setup (people.xml, RSIDs, settings.xml, comment files, relationships, content types). Only use direct XML manipulation for complex scenarios not supported by the library.

Working with Unicode and Entities:

• Searching: Both entity notation and Unicode characters work - contains="“Company" and contains="\u201cCompany" find the same text
• Replacing: Use either entities (“) or Unicode (\u201c) - both work and will be converted appropriately based on the file's encoding (ascii → entities, utf-8 → Unicode)

Initialization

Find the docx skill root (directory containing scripts/ and ooxml/):

# Search for document.py to locate the skill root
# Note: /mnt/skills is used here as an example; check your context for the actual location
find /mnt/skills -name "document.py" -path "*/docx/scripts/*" 2>/dev/null | head -1
# Example output: /mnt/skills/docx/scripts/document.py
# Skill root is: /mnt/skills/docx

Run your script with PYTHONPATH set to the docx skill root:

PYTHONPATH=/mnt/skills/docx python your_script.py

In your script, import from the skill root:

from scripts.document import Document, DocxXMLEditor

# Basic initialization (automatically creates temp copy and sets up infrastructure)
doc = Document('unpacked')

# Customize author and initials
doc = Document('unpacked', author="John Doe", initials="JD")

# Enable track revisions mode
doc = Document('unpacked', track_revisions=True)

# Specify custom RSID (auto-generated if not provided)
doc = Document('unpacked', rsid="07DC5ECB")

Creating Tracked Changes

CRITICAL: Only mark text that actually changes. Keep ALL unchanged text outside <w:del>/<w:ins> tags. Marking unchanged text makes edits unprofessional and harder to review.

Attribute Handling: The Document class auto-injects attributes (w:id, w:date, w:rsidR, w:rsidDel, w16du:dateUtc, xml:space) into new elements. When preserving unchanged text from the original document, copy the original <w:r> element with its existing attributes to maintain document integrity.

Method Selection Guide:

• Adding your own changes to regular text: Use replace_node() with <w:del>/<w:ins> tags, or suggest_deletion() for removing entire <w:r> or <w:p> elements
• Partially modifying another author's tracked change: Use replace_node() to nest your changes inside their <w:ins>/<w:del>
• Completely rejecting another author's insertion: Use revert_insertion() on the <w:ins> element (NOT suggest_deletion())
• Completely rejecting another author's deletion: Use revert_deletion() on the <w:del> element to restore deleted content using tracked changes

# Minimal edit - change one word: "The report is monthly" → "The report is quarterly"
# Original: <w:r w:rsidR="00AB12CD"><w:rPr><w:rFonts w:ascii="Calibri"/></w:rPr><w:t>The report is monthly</w:t></w:r>
node = doc["word/document.xml"].get_node(tag="w:r", contains="The report is monthly")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:r w:rsidR="00AB12CD">{rpr}<w:t>The report is </w:t></w:r><w:del><w:r>{rpr}<w:delText>monthly</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>quarterly</w:t></w:r></w:ins>'
doc["word/document.xml"].replace_node(node, replacement)

# Minimal edit - change number: "within 30 days" → "within 45 days"
# Original: <w:r w:rsidR="00XYZ789"><w:rPr><w:rFonts w:ascii="Calibri"/></w:rPr><w:t>within 30 days</w:t></w:r>
node = doc["word/document.xml"].get_node(tag="w:r", contains="within 30 days")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:r w:rsidR="00XYZ789">{rpr}<w:t>within </w:t></w:r><w:del><w:r>{rpr}<w:delText>30</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>45</w:t></w:r></w:ins><w:r w:rsidR="00XYZ789">{rpr}<w:t> days</w:t></w:r>'
doc["word/document.xml"].replace_node(node, replacement)

# Complete replacement - preserve formatting even when replacing all text
node = doc["word/document.xml"].get_node(tag="w:r", contains="apple")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:del><w:r>{rpr}<w:delText>apple</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>banana orange</w:t></w:r></w:ins>'
doc["word/document.xml"].replace_node(node, replacement)

# Insert new content (no attributes needed - auto-injected)
node = doc["word/document.xml"].get_node(tag="w:r", contains="existing text")
doc["word/document.xml"].insert_after(node, '<w:ins><w:r><w:t>new text</w:t></w:r></w:ins>')

# Partially delete another author's insertion
# Original: <w:ins w:author="Jane Smith" w:date="..."><w:r><w:t>quarterly financial report</w:t></w:r></w:ins>
# Goal: Delete only "financial" to make it "quarterly report"
node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"})
# IMPORTANT: Preserve w:author="Jane Smith" on the outer <w:ins> to maintain authorship
replacement = '''<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
  <w:r><w:t>quarterly </w:t></w:r>
  <w:del><w:r><w:delText>financial </w:delText></w:r></w:del>
  <w:r><w:t>report</w:t></w:r>
</w:ins>'''
doc["word/document.xml"].replace_node(node, replacement)

# Change part of another author's insertion
# Original: <w:ins w:author="Jane Smith"><w:r><w:t>in silence, safe and sound</w:t></w:r></w:ins>
# Goal: Change "safe and sound" to "soft and unbound"
node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "8"})
replacement = f'''<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
  <w:r><w:t>in silence, </w:t></w:r>
</w:ins>
<w:ins>
  <w:r><w:t>soft and unbound</w:t></w:r>
</w:ins>
<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
  <w:del><w:r><w:delText>safe and sound</w:delText></w:r></w:del>
</w:ins>'''
doc["word/document.xml"].replace_node(node, replacement)

# Delete entire run (use only when deleting all content; use replace_node for partial deletions)
node = doc["word/document.xml"].get_node(tag="w:r", contains="text to delete")
doc["word/document.xml"].suggest_deletion(node)

# Delete entire paragraph (in-place, handles both regular and numbered list paragraphs)
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph to delete")
doc["word/document.xml"].suggest_deletion(para)

# Add new numbered list item
target_para = doc["word/document.xml"].get_node(tag="w:p", contains="existing list item")
pPr = tags[0].toxml() if (tags := target_para.getElementsByTagName("w:pPr")) else ""
new_item = f'<w:p>{pPr}<w:r><w:t>New item</w:t></w:r></w:p>'
tracked_para = DocxXMLEditor.suggest_paragraph(new_item)
doc["word/document.xml"].insert_after(target_para, tracked_para)
# Optional: add spacing paragraph before content for better visual separation
# spacing = DocxXMLEditor.suggest_paragraph('<w:p><w:pPr><w:pStyle w:val="ListParagraph"/></w:pPr></w:p>')
# doc["word/document.xml"].insert_after(target_para, spacing + tracked_para)

Adding Comments

Comments are added with the author name "Z.ai" by default. Initialize the Document with custom author if needed:

# Initialize with Z.ai as author (recommended)
doc = Document('unpacked', author="Z.ai", initials="Z")

# Add comment spanning two existing tracked changes
# Note: w:id is auto-generated. Only search by w:id if you know it from XML inspection
start_node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
end_node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "2"})
doc.add_comment(start=start_node, end=end_node, text="Explanation of this change")

# Add comment on a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
doc.add_comment(start=para, end=para, text="Comment on this paragraph")

# Add comment on newly created tracked change
# First create the tracked change
node = doc["word/document.xml"].get_node(tag="w:r", contains="old")
new_nodes = doc["word/document.xml"].replace_node(
    node,
    '<w:del><w:r><w:delText>old</w:delText></w:r></w:del><w:ins><w:r><w:t>new</w:t></w:r></w:ins>'
)
# Then add comment on the newly created elements
# new_nodes[0] is the <w:del>, new_nodes[1] is the <w:ins>
doc.add_comment(start=new_nodes[0], end=new_nodes[1], text="Changed old to new per requirements")

# Reply to existing comment
doc.reply_to_comment(parent_comment_id=0, text="I agree with this change")

Rejecting Tracked Changes

IMPORTANT: Use revert_insertion() to reject insertions and revert_deletion() to restore deletions using tracked changes. Use suggest_deletion() only for regular unmarked content.

# Reject insertion (wraps it in deletion)
# Use this when another author inserted text that you want to delete
ins = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"})
nodes = doc["word/document.xml"].revert_insertion(ins)  # Returns [ins]

# Reject deletion (creates insertion to restore deleted content)
# Use this when another author deleted text that you want to restore
del_elem = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "3"})
nodes = doc["word/document.xml"].revert_deletion(del_elem)  # Returns [del_elem, new_ins]

# Reject all insertions in a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
nodes = doc["word/document.xml"].revert_insertion(para)  # Returns [para]

# Reject all deletions in a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
nodes = doc["word/document.xml"].revert_deletion(para)  # Returns [para]

Inserting Images

CRITICAL: The Document class works with a temporary copy at doc.unpacked_path. Always copy images to this temp directory, not the original unpacked folder.

from PIL import Image
import shutil, os

# Initialize document first
doc = Document('unpacked')

# Copy image and calculate full-width dimensions with aspect ratio
media_dir = os.path.join(doc.unpacked_path, 'word/media')
os.makedirs(media_dir, exist_ok=True)
shutil.copy('image.png', os.path.join(media_dir, 'image1.png'))
img = Image.open(os.path.join(media_dir, 'image1.png'))
width_emus = int(6.5 * 914400)  # 6.5" usable width, 914400 EMUs/inch
height_emus = int(width_emus * img.size[1] / img.size[0])

# Add relationship and content type
rels_editor = doc['word/_rels/document.xml.rels']
next_rid = rels_editor.get_next_rid()
rels_editor.append_to(rels_editor.dom.documentElement,
    f'<Relationship Id="{next_rid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image1.png"/>')
doc['[Content_Types].xml'].append_to(doc['[Content_Types].xml'].dom.documentElement,
    '<Default Extension="png" ContentType="image/png"/>')

# Insert image
node = doc["word/document.xml"].get_node(tag="w:p", line_number=100)
doc["word/document.xml"].insert_after(node, f'''<w:p>
  <w:r>
    <w:drawing>
      <wp:inline distT="0" distB="0" distL="0" distR="0">
        <wp:extent cx="{width_emus}" cy="{height_emus}"/>
        <wp:docPr id="1" name="Picture 1"/>
        <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
          <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
            <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
              <pic:nvPicPr><pic:cNvPr id="1" name="image1.png"/><pic:cNvPicPr/></pic:nvPicPr>
              <pic:blipFill><a:blip r:embed="{next_rid}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill>
              <pic:spPr><a:xfrm><a:ext cx="{width_emus}" cy="{height_emus}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr>
            </pic:pic>
          </a:graphicData>
        </a:graphic>
      </wp:inline>
    </w:drawing>
  </w:r>
</w:p>''')

Getting Nodes

# By text content
node = doc["word/document.xml"].get_node(tag="w:p", contains="specific text")

# By line range
para = doc["word/document.xml"].get_node(tag="w:p", line_number=range(100, 150))

# By attributes
node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})

# By exact line number (must be line number where tag opens)
para = doc["word/document.xml"].get_node(tag="w:p", line_number=42)

# Combine filters
node = doc["word/document.xml"].get_node(tag="w:r", line_number=range(40, 60), contains="text")

# Disambiguate when text appears multiple times - add line_number range
node = doc["word/document.xml"].get_node(tag="w:r", contains="Section", line_number=range(2400, 2500))

Saving

# Save with automatic validation (copies back to original directory)
doc.save()  # Validates by default, raises error if validation fails

# Save to different location
doc.save('modified-unpacked')

# Skip validation (debugging only - needing this in production indicates XML issues)
doc.save(validate=False)

Direct DOM Manipulation

For complex scenarios not covered by the library:

# Access any XML file
editor = doc["word/document.xml"]
editor = doc["word/comments.xml"]

# Direct DOM access (defusedxml.minidom.Document)
node = doc["word/document.xml"].get_node(tag="w:p", line_number=5)
parent = node.parentNode
parent.removeChild(node)
parent.appendChild(node)  # Move to end

# General document manipulation (without tracked changes)
old_node = doc["word/document.xml"].get_node(tag="w:p", contains="original text")
doc["word/document.xml"].replace_node(old_node, "<w:p><w:r><w:t>replacement text</w:t></w:r></w:p>")

# Multiple insertions - use return value to maintain order
node = doc["word/document.xml"].get_node(tag="w:r", line_number=100)
nodes = doc["word/document.xml"].insert_after(node, "<w:r><w:t>A</w:t></w:r>")
nodes = doc["word/document.xml"].insert_after(nodes[-1], "<w:r><w:t>B</w:t></w:r>")
nodes = doc["word/document.xml"].insert_after(nodes[-1], "<w:r><w:t>C</w:t></w:r>")
# Results in: original_node, A, B, C

Tracked Changes (Redlining)

Use the Document class above for all tracked changes. The patterns below are for reference when constructing replacement XML strings.

Validation Rules

The validator checks that the document text matches the original after reverting GLM's changes. This means:

• NEVER modify text inside another author's `<w:ins>` or `<w:del>` tags
• ALWAYS use nested deletions to remove another author's insertions
• Every edit must be properly tracked with <w:ins> or <w:del> tags

Tracked Change Patterns

CRITICAL RULES:

1. Never modify the content inside another author's tracked changes. Always use nested deletions. 2. XML Structure: Always place <w:del> and <w:ins> at paragraph level containing complete <w:r> elements. Never nest inside <w:r> elements - this creates invalid XML that breaks document processing.

Text Insertion:

<w:ins w:id="1" w:author="GLM" w:date="2025-07-30T23:05:00Z" w16du:dateUtc="2025-07-31T06:05:00Z">
  <w:r w:rsidR="00792858">
    <w:t>inserted text</w:t>
  </w:r>
</w:ins>

Text Deletion:

<w:del w:id="2" w:author="GLM" w:date="2025-07-30T23:05:00Z" w16du:dateUtc="2025-07-31T06:05:00Z">
  <w:r w:rsidDel="00792858">
    <w:delText>deleted text</w:delText>
  </w:r>
</w:del>

Deleting Another Author's Insertion (MUST use nested structure):

<!-- Nest deletion inside the original insertion -->
<w:ins w:author="Jane Smith" w:id="16">
  <w:del w:author="GLM" w:id="40">
    <w:r><w:delText>monthly</w:delText></w:r>
  </w:del>
</w:ins>
<w:ins w:author="GLM" w:id="41">
  <w:r><w:t>weekly</w:t></w:r>
</w:ins>

Restoring Another Author's Deletion:

<!-- Leave their deletion unchanged, add new insertion after it -->
<w:del w:author="Jane Smith" w:id="50">
  <w:r><w:delText>within 30 days</w:delText></w:r>
</w:del>
<w:ins w:author="GLM" w:id="51">
  <w:r><w:t>within 30 days</w:t></w:r>
</w:ins>