docx

# DOCX creation, editing, and analysis

## Overview

A .docx file is a ZIP archive containing XML files.

## Generating Reports (Recommended for research reports)

For structured reports with cover page, TOC, tables, images, and references, use the pre-built template. The DOCX generator accepts the **same JSON schema** as the PDF generator, so one `report_data.json` can produce both formats.

### Step 1: Copy the generator script

```bash
cp /builtin-skills/docx/scripts/generate_report.js ./generate_report.js
```

### Step 2: Build `report_data.json`

**Two phases: write section text files, then assemble into JSON.**

**Phase 1 — Write each section as a plain text file** using `write_file`:

For each major section, `read_file` the relevant research data, then `write_file` the section content directly:
```
read_file("research_data/literature.md")           # refresh data in context
write_file("sections/sec_01_intro.txt", "...")      # write section content
write_file("sections/sec_02_mutations.txt", "...")   # next section
...
```
Each section file should be 1,000-2,000+ words with specific data, citations, and analysis.

**NEVER write a Python script that contains section text as string literals.** The section content goes directly into .txt files via `write_file`, not into Python code. Do NOT write scripts named "generate_sections", "create_content", "build_report" etc. that embed text in Python strings. If a sandbox script fails twice, switch to direct `write_file` calls.

**Writing style — academic research report (CRITICAL):**
- Write continuous flowing prose. Each paragraph: 8–10 sentences following the pattern: topic sentence → supporting evidence with specific data → analysis/comparison → transition to next point.
- Use in-text citations [1], [2] when referencing data. These render as blue superscript in the DOCX. Do NOT add a "References" list at the end of each chapter — all references go in ONE final `references` section.
- Synthesize across sources: "Study A [1] reported X, while Study B [2] found Y, suggesting that Z."
- Use academic connectives: "Furthermore", "In contrast", "These findings indicate", "Notably", "Taken together".
- NEVER use numbered-point structure (e.g. "1. Topic Title\n\nParagraph. 2. Topic Title\n\nParagraph."). Instead, use `##` subheadings for structure and prose paragraphs for content. The template's `renderText` correctly renders `##`/`###` as formatted subheadings.
- Bullet lists: max 5% of section, only for short enumerations (e.g. 4-5 drug names).

**Language (CRITICAL):**
- All report content (title, subtitle, section headings, body text, chart labels, table headers, cover metadata) MUST be written in the **user's configured language** as specified in the system prompt's `## Language` section.
- If the user's language is Chinese (`zh`), write the entire report in Chinese; if English (`en`), write in English. Do NOT mix languages unless quoting a proper noun or technical term that has no standard translation.

**Verification (before generating DOCX):**
Run a one-liner to count chars per section:
```
python3 -c "import os,glob; [print(f'{f}: {len(open(f).read())} chars') for f in sorted(glob.glob('sections/*.txt'))]; total=sum(len(open(f).read()) for f in glob.glob('sections/*.txt')); print(f'TOTAL: {total} chars, ~{total//500} pages')"
```
If total is under target, do ONE revision: `read_file` data again, then `write_file` to rewrite the thinnest 1-2 sections. Then proceed — no looping.

**Phase 2 — Assemble into JSON** using a standard assembler script:

```python
import json, glob, os

SECTIONS_DIR = "sections"
TITLE = "Report Title"
SUBTITLE = "Subtitle"

# Section config: (file_pattern, heading_number, heading_text)
SECTION_MAP = [
    ("sec_01_*.txt", "1.", "Introduction"),
    ("sec_02_*.txt", "2.", "Background"),
    ("sec_03_*.txt", "3.", "Analysis"),
    ("sec_04_*.txt", "4.", "Discussion"),
    ("sec_05_*.txt", "5.", "Conclusion"),
]

data = {
    "title": TITLE, "subtitle": SUBTITLE,
    "short_title": TITLE[:40], "report_type": "Research Report",
    "toc": True, "sections": [],
    "cover_meta": [["Report Type", "Research Report"]],
}

for pattern, num, heading in SECTION_MAP:
    matches = sorted(glob.glob(os.path.join(SECTIONS_DIR, pattern)))
    if not matches:
        continue
    body = open(matches[0], encoding="utf-8").read().strip()
    data["sections"].append({"type": "heading", "level": 1, "number": num, "text": heading})
    data["sections"].append({"type": "text", "body": body})

# Add references section at end
data["sections"].append({"type": "heading", "level": 1, "text": "References"})
data["sections"].append({"type": "references", "items": []})

with open("report_data.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
print(f"Generated report_data.json ({len(data['sections'])} sections)")
```

**Adding charts**: Generate chart images separately using matplotlib, then include via the `image` section type.

**CRITICAL — CJK font config (MUST include when chart has Chinese/Japanese/Korean text):**
```python
import matplotlib
matplotlib.use("Agg")
matplotlib.rcParams["font.sans-serif"] = [
    "WenQuanYi Micro Hei", "SimHei", "Noto Sans CJK SC",
    "Arial Unicode MS", "sans-serif",
]
matplotlib.rcParams["axes.unicode_minus"] = False
import matplotlib.pyplot as plt

# ... generate chart ...
plt.savefig("figures/chart.png", dpi=180, bbox_inches="tight")
plt.close()
```
Without this config, Chinese text in charts will appear as garbled boxes (□□□).

Then in the assembler:
```python
data["sections"].append({"type": "text", "body": analysis_text})
data["sections"].append({"type": "image", "path": "figures/chart.png", "caption": "Figure 1: ..."})
```

### Step 3: Generate the DOCX

```bash
python3 build_report_data.py   # outputs report_data.json
node generate_report.js report_data.json output_report.docx
```

### Supported section types

| Type | Required Fields | Optional Fields |
|-----