docx/
├── SKILL.md                      ← This file (entry point + reference)
├── references/
│   └── EditingGuide.md           → Complete Python editing tutorial (comments, track changes, 5-file sync)
├── scripts/
│   ├── docx                      → Unified entry (the only script to call)
│   ├── fix_element_order.py      → Auto-fix XML element ordering
│   ├── validate_docx.py          → Business rule validation
│   ├── generate_backgrounds.py       → Morandi style backgrounds
│   ├── generate_inkwash_backgrounds.py → Ink-wash style backgrounds
│   └── generate_chart.py         → matplotlib (only for heatmaps/3D/radar; simple charts must use native)
├── assets/
│   └── templates/
│       ├── KimiDocx.csproj       → Project file template (for creating new docs)
│       ├── Program.cs            → Program entry template
│       ├── Example.cs            → Complete example (cover+TOC+charts+back cover)
│       ├── CJKExample.cs         → CJK content patterns (quote escaping, fonts)
│       └── xml/                  → XML templates for comments infrastructure
└── validator/                    → OpenXML validator (pre-compiled binary, AI does not modify)

cd /app/.kimi/skills/kimi-docx/
./scripts/docx init

// Correct - get output path from command line arguments
string outputFile = args.Length > 0 ? args[0] : "/mnt/okcomputer/output/output.docx";

// Wrong - hardcoded path causes build failure
string outputFile = "my_document.docx";  // Script can't find file!

cd /app/.kimi/skills/kimi-docx/
./scripts/docx validate /mnt/okcomputer/output/report.docx

Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
...

(Hint: On first open, right-click the TOC and select "Update Field" to show correct page numbers)

AddInlineImage(body, mainPart, "/path/to/image.png", "Description", docPrId++);

// Example: H1 always starts on new page, stays with next paragraph
new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new PageBreakBefore(),
    new KeepNext(),
    new KeepLines()
)

// Allow row to break across pages (avoid large blank areas)
new TableRowProperties(
    new CantSplit { Val = false }  // false = can split
)

// Repeat header row on each page
new TableRowProperties(
    new TableHeader()
)

// Normal style must exist - all Heading styles use basedOn="Normal"
styles.Append(new Style(
    new StyleName { Val = "Normal" },
    new StyleParagraphProperties(
        new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
    ),
    new StyleRunProperties(
        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
        new FontSize { Val = "22" },
        new FontSizeComplexScript { Val = "22" }
    )
) { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });

// Correct - table must define grid
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableGrid(           // Required!
    new GridColumn { Width = "4680" },
    new GridColumn { Width = "4680" }
));
table.Append(new TableRow(...));

// Wrong - missing tblGrid, Word cannot open
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableRow(...));  // Adding rows directly

// Correct - gridCol and tcW match exactly
table.Append(new TableGrid(
    new GridColumn { Width = "3600" },  // First column
    new GridColumn { Width = "5400" }   // Second column
));

var row = new TableRow(
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "3600", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    ),
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "5400", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    )
);

// ❌ Wrong - Chinese quotes break compilation
new Text("请点击"确定"按钮")  // CS1003!

// ✓ Correct - use Unicode escapes
new Text("请点击\u201c确定\u201d按钮")

// ❌ WRONG - @"" verbatim string, \u NOT escaped, outputs literal "\u201c"
string text = @"她说\u201c你好\u201d";  // Outputs: 她说\u201c你好\u201d

// ✓ CORRECT - regular string, \u IS escaped
string text = "她说\u201c你好\u201d";   // Outputs: 她说"你好"

// ✓ For long text, use + concatenation
string para = "第一段内容，" +
              "她说\u201c这是引用\u201d，" +
              "继续写第二段。";

// 1. Create header part
var headerPart = mainPart.AddNewPart<HeaderPart>();
var headerId = mainPart.GetIdOfPart(headerPart);

headerPart.Header = new Header(
    new Paragraph(
        new ParagraphProperties(
            new ParagraphStyleId { Val = "Header" },
            new Justification { Val = JustificationValues.Center }
        ),
        new Run(new Text("Document Title"))
    )
);

// 2. Create footer part (with page numbers)
var footerPart = mainPart.AddNewPart<FooterPart>();
var footerId = mainPart.GetIdOfPart(footerPart);

var footerPara = new Paragraph(
    new ParagraphProperties(
        new Justification { Val = JustificationValues.Center }
    )
);
// PAGE field: Begin → FieldCode → Separate → Text → End
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" PAGE ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));  // Placeholder, updated on open
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPara.Append(new Run(new Text(" / ") { Space = SpaceProcessingModeValues.Preserve }));
// NUMPAGES field (same structure)
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" NUMPAGES ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPart.Footer = new Footer(footerPara);

// 3. Reference in SectionProperties
new SectionProperties(
    new HeaderReference { Type = HeaderFooterValues.Default, Id = headerId },
    new FooterReference { Type = HeaderFooterValues.Default, Id = footerId },
    new PageSize { Width = 11906, Height = 16838 },
    new PageMargin { Top = 1440, Right = 1440, Bottom = 1440, Left = 1440, Header = 720, Footer = 720 }
)

<!-- Required in footnotes.xml / endnotes.xml before user notes -->
<w:footnote w:type="separator" w:id="-1">
  <w:p><w:r><w:separator/></w:r></w:p>
</w:footnote>
<w:footnote w:type="continuationSeparator" w:id="0">
  <w:p><w:r><w:continuationSeparator/></w:r></w:p>
</w:footnote>
<!-- User notes start from id="1" -->

var relId = mainPart.AddHyperlinkRelationship(new Uri("https://example.com"), true).Id;
paragraph.Append(new Hyperlink(new Run(
    new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
    new Text("Click here")
)) { Id = relId })

from scripts.docx_lib.editing import (
    DocxContext,
    add_comment, reply_comment, resolve_comment, delete_comment,
    insert_paragraph, insert_text, propose_deletion,
    reject_insertion, restore_deletion, enable_track_changes
)

with DocxContext("input.docx", "output.docx") as ctx:
    # add_comment(ctx, para_text, comment, highlight=None)
    # - para_text: text to locate paragraph
    # - comment: comment content
    # - highlight: text to highlight (omit to highlight entire paragraph)
    add_comment(ctx, "M-SVI index", "Please define", highlight="M-SVI")
    insert_text(ctx, "The method", after="method", new_text=" and materials")

<w:r>
  <w:rPr>
    <w:rFonts w:ascii="Times New Roman" w:eastAsia="SimSun"/>
    <w:sz w:val="24"/>  <!-- 12pt = 24 half-points -->
    <w:b/><w:i/><w:u w:val="single"/>
    <w:color w:val="FF0000"/>
  </w:rPr>
  <w:t>text</w:t>
</w:r>

<!-- Insertion: <w:ins> wraps <w:r> -->
<w:ins w:id="1" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:t>text</w:t></w:r>
</w:ins>

<!-- Deletion: <w:del> wraps <w:r> (same pattern as ins!) -->
<w:del w:id="2" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:delText>text</w:delText></w:r>
</w:del>