devlyn-cli 0.5.2 → 0.5.4

package/optional-skills/dokkit/IMAGE-SOURCING.md

@@ -0,0 +1,127 @@
+# Image Sourcing
+
+Strategies for sourcing images to fill template fields requiring photos, logos, signatures, or illustrations.
+
+## Image Types
+
+| image_type | Description | Auto-generate? |
+|-----------|-------------|----------------|
+| `photo` | ID/profile pictures | No — user-provided only |
+| `logo` | Company logos | No — user-provided only |
+| `signature` | Signature fields | NEVER — must be user-provided |
+| `figure` | Illustrations, diagrams | Yes — auto-generated during fill |
+
+## Sourcing Priority
+
+### 1. Check Ingested Sources
+Search `.dokkit/sources/` for image files (PNG, JPG, JPEG, BMP, TIFF):
+- Match by field's `image_type` and source metadata
+- Set `image_source: "ingested"` and `image_file` to the path
+
+### 2. User-Provided File
+Via `/dokkit modify "use <file>"`:
+- Search `.dokkit/sources/`, then project root
+- Copy to `.dokkit/images/`
+
+### 3. AI Generation
+```bash
+python scripts/source_images.py generate \
+  --prompt "인포그래픽: AI 감정 케어 플랫폼 4단계 로드맵" \
+  --preset infographic \
+  --output-dir .dokkit/images/ \
+  --project-dir . \
+  --lang ko
+```
+Parse `__RESULT__` JSON from stdout: `{"image_id": "...", "file_path": "...", "source_type": "generated"}`
+
+#### Language Options (`--lang`)
+
+| Value | Behavior | Example |
+|---|---|---|
+| `ko` | **Default.** All text in Korean only. English strictly forbidden. | 제목, 라벨, 설명 모두 한국어 |
+| `en` | All text in English only. | Titles, labels, descriptions in English |
+| `ko+en` | Mixed. Titles in Korean, technical terms may use English. | 제목은 한국어, Node.js 등 기술 용어는 영어 허용 |
+| `ja` | All text in Japanese only. | 日本語のみ |
+| `<code>` | Any ISO 639-1 code. | `zh`, `es`, `fr`, `de`, `pt` |
+| `<a>+<b>` | Mixed: primary + secondary language. | `ko+ja`, `en+ko` |
+
+#### Presets
+
+| Preset | Style | Default Aspect Ratio |
+|---|---|---|
+| `technical_illustration` | Clean diagrams, labeled components | 16:9 |
+| `infographic` | Icon-based, corporate color palette | 16:9 |
+| `photorealistic` | High-quality, natural lighting | 4:3 |
+| `concept` | Abstract/modern, business proposal style | 1:1 |
+| `chart` | Clean data visualization | 16:9 |
+
+Use `--aspect-ratio 16:9` to override. Use `--no-enhance` to skip preset style injection (language instruction still applies).
+
+**Model**: `gemini-3-pro-image-preview` (nano-banana). Best for accurate text rendering in non-Latin scripts.
+
+### 4. Web Search
+```bash
+python scripts/source_images.py search \
+  --query "company logo example" \
+  --output-dir .dokkit/images/
+```
+Parse `__RESULT__` JSON: `{"image_id": "...", "file_path": "...", "source_type": "searched"}`
+(Note: search is not yet implemented — directs user to provide images manually.)
+
+## Prompt Templates by Image Type
+
+| image_type | Suggested prompt |
+|-----------|-----------------|
+| photo | "Professional ID photo, white background, formal attire" |
+| logo | "Clean company logo, transparent background, modern design" |
+| signature | **NEVER generate** — signatures must be user-provided |
+| figure | Derive from field label and section context |
+
+## Section Content Image Generation
+
+For `image_opportunities` in `section_content` fields — auto-generated during `/dokkit fill` (decorative/explanatory, not identity-sensitive).
+
+### Prompt Templates by Content Type
+
+| content_type | preset | Prompt guidance |
+|---|---|---|
+| diagram | `technical_illustration` | "Technical architecture/system diagram showing [concept]. Clean lines, labeled components." |
+| flowchart | `technical_illustration` | "Process flowchart showing [steps]. Left-to-right flow, clear arrows, numbered steps." |
+| data | `infographic` | "Data visualization showing [metric/trend]. Clean chart style, professional colors." |
+| concept | `technical_illustration` | "Conceptual illustration of [idea]. Abstract/modern style, suitable for business proposal." |
+| infographic | `infographic` | "Infographic comparing [items]. Icon-based, clean layout, corporate color palette." |
+
+### Dimension Defaults
+
+HWPML units: 1/7200 inch (~283.46 units/mm). ~77% of A4 text width = 36,000 units.
+
+| content_type | HWPML w x h | Approx mm | EMU cx x cy |
+|---|---|---|---|
+| diagram | 36,000 x 24,000 | 127x85 | 4,572,000 x 3,048,000 |
+| flowchart | 36,000 x 24,000 | 127x85 | 4,572,000 x 3,048,000 |
+| data | 36,000 x 20,000 | 127x71 | 4,572,000 x 2,540,000 |
+| concept | 28,000 x 28,000 | 99x99 | 3,556,000 x 3,556,000 |
+| infographic | 36,000 x 24,000 | 127x85 | 4,572,000 x 3,048,000 |
+
+## Default Cell-Level Dimensions
+
+| image_type | Width (mm) | Height (mm) | Width (EMU) | Height (EMU) |
+|-----------|-----------|------------|------------|-------------|
+| photo | 35 | 45 | 1,260,000 | 1,620,000 |
+| logo | 50 | 50 | 1,800,000 | 1,800,000 |
+| signature | 40 | 15 | 1,440,000 | 540,000 |
+| figure | 100 | 75 | 3,600,000 | 2,700,000 |
+
+Conversion: 1 mm = 36,000 EMU. For HWPX, use HWPML unit system.
+
+## Rules
+
+- Signatures MUST be user-provided — never generate or search
+- Never auto-generate/download images without user approval EXCEPT section content images (auto-generated during fill)
+- Ingested images can be inserted automatically
+- Prefer user-provided over generated
+- Image format must be PNG or JPG (compatible with both DOCX and HWPX)
+
+## References
+
+See `references/image-xml-patterns.md` for complete DOCX/HWPX image element structures, registration patterns, and the `build_hwpx_pic_element()` function.

package/optional-skills/dokkit/INGESTION.md

@@ -0,0 +1,65 @@
+# Ingestion Knowledge
+
+Parsing strategies and format routing for converting source documents into the dual-file format (Markdown content + JSON sidecar).
+
+## Format Routing
+
+| Format | Parser | Command |
+|--------|--------|---------|
+| PDF | Docling | `python -m docling <file> --to md` |
+| DOCX | Docling | `python -m docling <file> --to md` |
+| PPTX | Docling | `python -m docling <file> --to md` |
+| HTML | Docling | `python -m docling <file> --to md` |
+| CSV | Docling | `python -m docling <file> --to md` |
+| MD | Direct copy | Read and process as-is |
+| XLSX | Custom | `python .claude/skills/dokkit/scripts/parse_xlsx.py` |
+| HWPX | Custom | `python .claude/skills/dokkit/scripts/parse_hwpx.py` |
+| JSON | Custom | Read, format as structured markdown |
+| TXT | Custom | Read, wrap as markdown |
+| PNG/JPG | Gemini Vision | `python .claude/skills/dokkit/scripts/parse_image_with_gemini.py` |
+
+## Docling Usage
+
+Primary parser for most formats:
+
+```bash
+python -m docling <input-file> --to md --output <output-dir>
+```
+
+After Docling runs:
+1. Read the markdown output
+2. Extract key-value pairs from the content
+3. Build the JSON sidecar with metadata
+4. Move files to `.dokkit/sources/`
+
+If Docling is not installed, show an explicit error with install instructions: `pip install docling`. Do NOT silently fall back to a different parser.
+
+## Custom Parser Output Format
+
+All custom parsers output JSON to stdout:
+```json
+{
+  "content_md": "# Document Title\n\nExtracted content...",
+  "metadata": {
+    "file_name": "original.xlsx",
+    "file_type": "xlsx",
+    "parse_date": "2026-02-07T12:00:00Z",
+    "key_value_pairs": { "Name": "John", "Date": "2026-01-15" },
+    "sections": ["Sheet1", "Sheet2"]
+  }
+}
+```
+
+## Key-Value Extraction
+
+After parsing, scan content for structured data:
+- Table cells with label-value patterns (e.g., "Name: John Doe")
+- Form fields with values
+- Metadata headers
+- Labeled sections
+
+Store in the JSON sidecar's `key_value_pairs` field for fast lookup during template filling.
+
+## References
+
+See `references/supported-formats.md` for detailed format specifications.

package/optional-skills/dokkit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: dokkit
+description: >
+  Document template filling system for DOCX and HWPX formats.
+  Ingests source documents, analyzes templates, detects fillable fields,
+  fills them surgically using source data, reviews with confidence scoring,
+  and exports completed documents. Supports Korean and English templates.
+  Subcommands: init, sources, preview, ingest, fill, fill-doc, modify, review, export.
+  Use when user says "fill template", "fill document", "ingest", "dokkit".
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+argument-hint: "<subcommand> [arguments]"
+context:
+  - type: file
+    path: ${CLAUDE_SKILL_DIR}/COMMANDS.md
+---
+
+# Dokkit — Document Template Filling System
+
+Surgical document filling for DOCX and HWPX templates using ingested source data. One command with 9 subcommands covering the full document filling lifecycle.
+
+## Subcommands
+
+| Subcommand | Arguments | Type | Description |
+|------------|-----------|------|-------------|
+| `init` | `[--force] [--keep-sources]` | Inline | Initialize or reset workspace |
+| `sources` | — | Inline | Display ingested sources dashboard |
+| `preview` | — | Inline | Generate PDF preview via LibreOffice |
+| `ingest` | `<file1> [file2] ...` | Agent | Parse source documents into workspace |
+| `fill` | `<template.docx\|hwpx>` | Agent | End-to-end: analyze, fill, review, auto-fix, export |
+| `fill-doc` | `<template.docx\|hwpx>` | Agent | Analyze template and fill fields only |
+| `modify` | `"<instruction>"` | Agent | Apply targeted changes to filled document |
+| `review` | `[section\|approve]` | Agent | Review with per-field confidence annotations |
+| `export` | `<docx\|hwpx\|pdf>` | Agent | Export filled document to format |
+
+## Routing
+
+Parse `$ARGUMENTS` to determine the subcommand:
+
+1. Extract `$1` as the subcommand name
+2. Pass remaining arguments (`$2`, `$3`, ...) to the subcommand
+3. If `$1` is empty or unrecognized, display the subcommand table above with usage examples
+
+Full workflows for each subcommand are in COMMANDS.md (auto-loaded via context).
+
+<example>
+- `/dokkit ingest docs/resume.pdf docs/transcript.xlsx` — ingest two sources
+- `/dokkit fill docs/template.hwpx` — end-to-end fill pipeline
+- `/dokkit modify "Change the phone number to 010-1234-5678"` — targeted change
+- `/dokkit export pdf` — export as PDF
+</example>
+
+## Architecture
+
+### Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| **dokkit-ingestor** | opus | Parse source docs into `.dokkit/sources/` (.md + .json pairs) |
+| **dokkit-analyzer** | opus | Analyze templates, detect fields, map to sources. Writes `analysis.json`. READ-ONLY on templates. |
+| **dokkit-filler** | opus | Surgical XML modification using analysis.json. Three modes: fill, modify, review. |
+| **dokkit-exporter** | sonnet | Repackage ZIP archives, PDF conversion via LibreOffice. |
+
+### Workspace
+
+All agents communicate via the `.dokkit/` filesystem:
+
+```
+.dokkit/
+├── state.json          # Single source of truth for session state
+├── sources/            # Ingested content (.md + .json pairs)
+├── analysis.json       # Template analysis output (from analyzer)
+├── images/             # Sourced images for template filling
+├── template_work/      # Unpacked template XML (working copy)
+└── output/             # Exported filled documents
+```
+
+### State Protocol
+
+Read `.dokkit/state.json` before any operation. Write state changes atomically: read current → update fields → write back → validate.
+
+```
+init → state created (empty)
+ingest → source added to sources[]
+fill/fill-doc → template set, analysis created, filled_document created
+modify → filled_document updated
+review approve → filled_document.status = "finalized"
+export → export entry added to exports[]
+```
+
+Validate after every write: `python ${CLAUDE_SKILL_DIR}/scripts/validate_state.py .dokkit/state.json`
+
+### Knowledge Files
+
+Agent-facing knowledge bases in this skill directory:
+
+| File | Purpose | Agents |
+|------|---------|--------|
+| `STATE.md` | State schema and management protocol | All |
+| `INGESTION.md` | Format routing and parsing strategies | dokkit-ingestor |
+| `ANALYSIS.md` | Field detection, confidence scoring, output schema | dokkit-analyzer |
+| `FILLING.md` | XML surgery rules, matching strategy, image insertion | dokkit-analyzer, dokkit-filler |
+| `DOCX-XML.md` | Open XML structure for DOCX documents | dokkit-analyzer, dokkit-filler |
+| `HWPX-XML.md` | OWPML structure for HWPX documents | dokkit-analyzer, dokkit-filler |
+| `IMAGE-SOURCING.md` | Image generation, search, and insertion patterns | dokkit-filler |
+| `EXPORT.md` | Document compilation and format conversion | dokkit-exporter |
+
+Deep reference material in `references/`:
+- `state-schema.md` — Complete state.json schema
+- `supported-formats.md` — Detailed format specifications
+- `docx-structure.md`, `docx-field-patterns.md` — DOCX patterns
+- `hwpx-structure.md`, `hwpx-field-patterns.md` — HWPX patterns (10 detection patterns)
+- `field-detection-patterns.md` — Advanced heuristics (9 DOCX + 6 HWPX)
+- `section-range-detection.md` — Dynamic range detection for section_content
+- `section-image-interleaving.md` — Image interleaving algorithm
+- `image-opportunity-heuristics.md` — AI image opportunity detection
+- `image-xml-patterns.md` — Image element structures (DOCX + HWPX)
+
+Scripts in `scripts/`:
+- `validate_state.py` — State validation
+- `parse_xlsx.py`, `parse_hwpx.py`, `parse_image_with_gemini.py` — Custom parsers
+- `detect_fields.py`, `detect_fields_hwpx.py` — Field detection
+- `validate_docx.py`, `validate_hwpx.py` — Document validation
+- `compile_hwpx.py` — HWPX repackaging
+- `export_pdf.py` — PDF conversion
+
+## Rules
+
+<rules>
+- Display errors clearly with actionable guidance. Never silently fall back to defaults.
+- Original template is never modified — copies go to `.dokkit/template_work/`.
+- Analyzer is read-only on templates. Only the filler modifies XML.
+- Confidence levels: high, medium, low (not numeric scores).
+- Signatures must be user-provided — never auto-generate them.
+- Validate state after every write with `scripts/validate_state.py`.
+- Inline commands (init, sources, preview) execute directly — do NOT spawn agents.
+- Agent-delegated commands spawn the appropriate agent(s) sequentially.
+</rules>
+
+## Known Pitfalls
+
+Critical issues discovered through production use:
+
+1. **HWPX namespace stripping**: Python ET strips unused namespace declarations. Restore ALL 14 original xmlns on EVERY root element after any `tree.write()`. Applies to section0.xml, content.hpf, header.xml.
+2. **HWPX subList cell wrapping**: ~65% of cells wrap content in `<hp:subList>/<hp:p>`. Check for subList before writing content.
+3. **table_content "Pre-filled" bug**: Never set `mapped_value` to placeholder strings for `table_content` fields. Use `mapped_value: null` with `action: "preserve"`.
+4. **HWPX cellAddr rowAddr corruption**: After row insert/delete, re-index ALL `rowAddr` values. Duplicate rowAddr causes silent data loss.
+5. **HWPX `<hp:pic>` inside `<hp:run>`**: Pic as sibling of run renders invisible. Must be `<hp:run><hp:pic>...<hp:t/></hp:run>`.
+6. **HWPML units**: 1/7200 inch, NOT hundredths of mm. 1mm ~ 283.46 units. A4 text width ~ 46,648 units.
+7. **rowSpan stripping**: When cloning rows with rowSpan>1, divide cellSz height by rowSpan.
+8. **HWPX pic element order**: offset, orgSz, curSz, flip, rotationInfo, renderingInfo, imgRect, imgClip, inMargin, imgDim, hc:img, sz, pos, outMargin.
+9. **HWPX post-write safety**: After ET write: (a) restore namespaces, (b) fix XML declaration to double quotes with `standalone="yes"`, (c) remove newline between `?>` and `<root>`.
+10. **compile_hwpx.py skip .bak**: Backup files must be excluded from ZIP repackaging.

package/optional-skills/dokkit/STATE.md

@@ -0,0 +1,60 @@
+# State Management
+
+Protocol for reading and writing `.dokkit/state.json`. All agents follow this protocol.
+
+## Workspace Structure
+
+```
+.dokkit/
+├── state.json          # Single source of truth for session state
+├── sources/            # Ingested source content
+│   ├── <name>.md       # Extracted content (LLM-optimized markdown)
+│   └── <name>.json     # Structured metadata sidecar
+├── analysis.json       # Template analysis output (from analyzer)
+├── images/             # Sourced images
+├── template_work/      # Unpacked template XML (working copy)
+│   ├── word/           # (DOCX) or Contents/ (HWPX)
+│   └── ...
+└── output/             # Exported filled documents
+    └── filled_<name>.<ext>
+```
+
+## Reading State
+
+Read `.dokkit/state.json` before any operation. Check:
+- `sources` array for available context
+- `template` for current template info
+- `analysis` for field mapping data
+- `filled_document` for current document status
+
+## Writing State
+
+After any mutation:
+1. Read current state.json (avoid overwriting concurrent changes)
+2. Update only the relevant fields
+3. Write the full state back
+4. Validate: `python .claude/skills/dokkit/scripts/validate_state.py .dokkit/state.json`
+
+## State Transitions
+
+```
+/dokkit init → state created (empty)
+/dokkit ingest → source added to sources[]
+/dokkit fill or fill-doc → template set, analysis created, filled_document created
+/dokkit modify → filled_document updated
+/dokkit review approve → filled_document.status = "finalized"
+/dokkit export → export entry added to exports[]
+```
+
+## Validation
+
+The validator checks:
+- Schema conformance
+- Required fields present
+- Valid status values
+- Source file references exist
+- No orphaned entries
+
+## References
+
+See `references/state-schema.md` for the complete schema definition.

package/optional-skills/dokkit/references/docx-field-patterns.md

@@ -0,0 +1,151 @@
+# DOCX Field Detection Patterns
+
+## Pattern 1: Placeholder Text
+
+```xml
+<!-- Text like {{name}} or <<name>> in a run -->
+<w:r>
+  <w:rPr>
+    <w:rFonts w:ascii="Arial" w:hAnsi="Arial"/>
+    <w:sz w:val="20"/>
+  </w:rPr>
+  <w:t>{{full_name}}</w:t>  <!-- REPLACE this text content -->
+</w:r>
+```
+
+**Action**: Replace the text content of `<w:t>` while preserving `<w:rPr>`.
+
+## Pattern 2: Empty Table Cell
+
+```xml
+<w:tr>
+  <w:tc>
+    <w:p><w:r><w:t>Name</w:t></w:r></w:p>  <!-- Label cell -->
+  </w:tc>
+  <w:tc>
+    <w:p/>  <!-- Empty cell → FILL THIS -->
+  </w:tc>
+</w:tr>
+```
+
+**Action**: Insert `<w:r><w:t>value</w:t></w:r>` into the empty `<w:p>`. Copy `<w:rPr>` from the label cell's run to match formatting.
+
+## Pattern 3: Underline Placeholder
+
+```xml
+<w:r>
+  <w:rPr>
+    <w:u w:val="single"/>
+  </w:rPr>
+  <w:t xml:space="preserve">          </w:t>  <!-- Spaces with underline -->
+</w:r>
+```
+
+**Action**: Replace the spaces in `<w:t>` with the actual value. Keep `<w:u>` in `<w:rPr>`.
+
+## Pattern 4: Content Control
+
+```xml
+<w:sdt>
+  <w:sdtPr>
+    <w:alias w:val="Company Name"/>
+    <w:tag w:val="company"/>
+    <w:showingPlcHdr/>  <!-- Indicates placeholder is showing -->
+  </w:sdtPr>
+  <w:sdtContent>
+    <w:p>
+      <w:r>
+        <w:rPr><w:rStyle w:val="PlaceholderText"/></w:rPr>
+        <w:t>Click here to enter text.</w:t>
+      </w:r>
+    </w:p>
+  </w:sdtContent>
+</w:sdt>
+```
+
+**Action**: Replace the run inside `<w:sdtContent>` with a new run containing the value. Remove `<w:showingPlcHdr/>` from `<w:sdtPr>`. Remove the placeholder style from `<w:rPr>`.
+
+## Pattern 5: Instruction Text
+
+```xml
+<w:r>
+  <w:rPr>
+    <w:color w:val="808080"/>  <!-- Gray text -->
+    <w:i/>                      <!-- Italic -->
+  </w:rPr>
+  <w:t>(enter your name)</w:t>
+</w:r>
+```
+
+**Action**: Replace text content. Change `<w:rPr>` to remove gray color and italic (or copy from a nearby filled field).
+
+## Pattern 6: Writing Tip Box (작성 팁)
+
+Single-cell tables with dashed borders containing `※` guidance text. These are NOT fillable — they must be **deleted**.
+
+```xml
+<w:tbl>
+  <w:tblPr>
+    <w:tblBorders>
+      <w:top w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:left w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:bottom w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+      <w:right w:val="dashed" w:sz="4" w:space="0" w:color="auto"/>
+    </w:tblBorders>
+  </w:tblPr>
+  <w:tr>
+    <w:tc>
+      <w:p>
+        <w:r>
+          <w:rPr><w:color w:val="FF0000"/></w:rPr>
+          <w:t>※ 작성 팁: 구체적인 사업 목표를 기재하세요.</w:t>
+        </w:r>
+      </w:p>
+    </w:tc>
+  </w:tr>
+</w:tbl>
+```
+
+**Identifying traits**:
+- Single row, single cell (`<w:tr>` has one `<w:tc>`)
+- `<w:tblBorders>` with `w:val="dashed"` on all sides
+- Text starts with `※` or contains `작성 팁`, `작성요령`
+- Often has red `<w:color w:val="FF0000"/>` styling
+
+**Action**: Flag as `field_type: "tip_box"`, `action: "delete"`. Delete the entire `<w:tbl>` element.
+
+## Color Warning for Copied Formatting
+
+When copying `<w:rPr>` from template guide text or instruction text (Patterns 2 and 5), **always check for red color**:
+
+```xml
+<!-- DANGER: This rPr has red color from guide text -->
+<w:rPr>
+  <w:color w:val="FF0000"/>  <!-- REMOVE THIS -->
+  <w:i/>                      <!-- REMOVE THIS (from guide text) -->
+  <w:sz w:val="20"/>          <!-- KEEP -->
+</w:rPr>
+```
+
+**Rule**: After copying rPr from any template text, check for `<w:color>` elements. If the value is `FF0000`, `FF0000FF`, or any red shade, **remove the `<w:color>` element** (defaults to black). Also remove `<w:i/>` if it came from guide text.
+
+## Safe Modification Template
+
+```python
+import xml.etree.ElementTree as ET
+
+ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
+ET.register_namespace("w", ns["w"])
+
+tree = ET.parse("word/document.xml")
+
+# Find and replace placeholder text
+for t_elem in tree.iter("{%s}t" % ns["w"]):
+    if t_elem.text and "{{" in t_elem.text:
+        placeholder = t_elem.text  # e.g., "{{name}}"
+        field_name = placeholder.strip("{}").strip("<>")
+        if field_name in field_values:
+            t_elem.text = field_values[field_name]
+
+tree.write("word/document.xml", xml_declaration=True, encoding="UTF-8")
+```

package/optional-skills/dokkit/references/docx-structure.md

@@ -0,0 +1,58 @@
+# DOCX XML Structure Reference
+
+## Unpacking a DOCX
+
+```bash
+# Unzip to inspect
+mkdir -p .dokkit/template_work
+cd .dokkit/template_work
+unzip -o /path/to/template.docx
+```
+
+## Reading document.xml
+
+The main content is in `word/document.xml`. Parse with any XML parser.
+
+### Python Example
+```python
+import xml.etree.ElementTree as ET
+
+ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
+tree = ET.parse("word/document.xml")
+root = tree.getroot()
+
+# Find all paragraphs
+for p in root.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p"):
+    texts = []
+    for t in p.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t"):
+        if t.text:
+            texts.append(t.text)
+    print("".join(texts))
+```
+
+## Repackaging a DOCX
+
+After modifying XML, repackage as a valid DOCX:
+
+```python
+import zipfile
+import os
+
+def repackage_docx(work_dir, output_path):
+    """Repackage modified XML files into a valid DOCX."""
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+        for root, dirs, files in os.walk(work_dir):
+            for file in files:
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, work_dir)
+                zf.write(file_path, arcname)
+```
+
+## Critical Rules for DOCX Surgery
+
+1. **Never remove `<w:rPr>` elements** — they contain all formatting
+2. **Preserve `xml:space="preserve"`** on `<w:t>` elements with leading/trailing spaces
+3. **Keep `<w:pPr>` intact** — paragraph formatting must not change
+4. **Maintain bookmark pairs** — `<w:bookmarkStart>` must have matching `<w:bookmarkEnd>`
+5. **Don't modify `<w:sectPr>`** — section properties control page layout
+6. **Preserve table cell merge attributes** — `<w:vMerge>` and `<w:gridSpan>`