{"id":"11d09192-931f-4e0d-be07-62c28b7c286a","entityType":"agent","slug":"clawhub-yhlorra-yh-minimax-docx","name":"MiniMax DOCX","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yhlorra-yh-minimax-docx","canonicalPath":"/agent/clawhub-yhlorra-yh-minimax-docx","generatedAt":"2026-10-10T01:03:35.613Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":null},"description":"Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... Skill: MiniMax DOCX Owner: yhlorra Summary: Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-03-25T13:43:06.824Z | user Initial publish Archive index: Archive v1.0.0: 67 files, 362368 bytes Files: assets/styles/academic_styles.xml (7658b), assets/styles/corpo","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.5K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1722rfrg89fk95t1dwm4vqdyx83j73f:yh-minimax-docx","sourceUrl":"https://clawhub.ai/yhlorra/yh-minimax-docx","homepage":"https://clawhub.ai/yhlorra/skills/yh-minimax-docx","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yhlorra/yh-minimax-docx","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yhlorra/skills/yh-minimax-docx","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":null},"stars":null,"forks":null,"downloads":2465,"packageName":null,"latestVersion":"1.0.0","tractionLabel":"2.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:39:08.917Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T14:39:08.918Z","lastCrawledAt":"2026-10-09T14:39:08.917Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T14:39:08.917Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.0","createdAt":"2026-03-25T13:43:06.824Z","changelog":"Initial publish","fileCount":67,"zipByteSize":362368}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1722rfrg89fk95t1dwm4vqdyx83j73f:yh-minimax-docx","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T01:03:35.610Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yhlorra-yh-minimax-docx/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":null},"readme":"Skill: MiniMax DOCX\n\nOwner: yhlorra\n\nSummary: Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit...\n\nTags: latest:1.0.0\n\nVersion history:\n\nv1.0.0 | 2026-03-25T13:43:06.824Z | user\n\nInitial publish\n\nArchive index:\n\nArchive v1.0.0: 67 files, 362368 bytes\n\nFiles: assets/styles/academic_styles.xml (7658b), assets/styles/corporate_styles.xml (8808b), assets/styles/default_styles.xml (12773b), references/cjk_typography.md (12284b), references/cjk_university_template_guide.md (8085b), references/comments_guide.md (6721b), references/design_good_bad_examples.md (31660b), references/design_principles.md (28460b), references/openxml_element_order.md (11238b), references/openxml_encyclopedia_part1.md (144517b), references/openxml_encyclopedia_part2.md (97285b), references/openxml_encyclopedia_part3.md (125207b), references/openxml_namespaces.md (5643b), references/openxml_units.md (2441b), references/scenario_a_create.md (8125b), references/scenario_b_edit_content.md (8242b), references/scenario_c_apply_template.md (18864b), references/track_changes_guide.md (5523b), references/troubleshooting.md (19469b), references/typography_guide.md (10391b), references/xsd_validation_guide.md (5226b), scripts/doc_to_docx.sh (912b), scripts/docx_preview.sh (873b), scripts/dotnet/MiniMaxAIDocx.Cli/Program.cs (609b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/AnalyzeCommand.cs (6318b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/ApplyTemplateCommand.cs (13313b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/CreateCommand.cs (14854b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/DiffCommand.cs (6252b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/EditContentCommand.cs (20267b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/FixOrderCommand.cs (4603b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/MergeRunsCommand.cs (4916b), scripts/dotnet/MiniMaxAIDocx.Core/Commands/ValidateCommand.cs (4321b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/CommentSynchronizer.cs (6645b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/ElementOrder.cs (4235b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/NamespaceConstants.cs (3626b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/RunMerger.cs (2711b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/StyleAnalyzer.cs (3080b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/TrackChangesHelper.cs (3131b), scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/UnitConverter.cs (1080b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs (39707b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs (44402b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs (46367b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs (49233b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples.cs (79203b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/CharacterFormattingSamples.cs (48191b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/DocumentCreationSamples.cs (54478b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/FieldAndTocSamples.cs (27557b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/FootnoteAndCommentSamples.cs (31513b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/HeaderFooterSamples.cs (37109b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/ImageSamples.cs (41108b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/ListAndNumberingSamples.cs (35978b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/ParagraphFormattingSamples.cs (58036b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/StyleSystemSamples.cs (67068b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/TableSamples.cs (52934b), scripts/dotnet/MiniMaxAIDocx.Core/Samples/TrackChangesSamples.cs (27375b), scripts/dotnet/MiniMaxAIDocx.Core/Typography/CjkHelper.cs (1239b), scripts/dotnet/MiniMaxAIDocx.Core/Typography/FontDefaults.cs (922b), scripts/dotnet/MiniMaxAIDocx.Core/Typography/PageSizes.cs (999b), scripts/dotnet/MiniMaxAIDocx.Core/Validation/BusinessRuleValidator.cs (9453b), scripts/dotnet/MiniMaxAIDocx.Core/Validation/GateCheckValidator.cs (6100b), scripts/dotnet/MiniMaxAIDocx.Core/Validation/ValidationResult.cs (674b), scripts/dotnet/MiniMaxAIDocx.Core/Validation/XsdValidator.cs (2244b), scripts/env_check.sh (7293b), scripts/setup.sh (16985b), skill-card.md (2760b), SKILL.md (16092b), _meta.json (134b)\n\nFile v1.0.0:SKILL.md\n\n---\r\nname: minimax-docx\r\nlicense: MIT\r\nmetadata:\r\n version: \"1.0.0\"\r\n category: document-processing\r\n author: MiniMaxAI\r\n sources:\r\n - \"ECMA-376 Office Open XML File Formats\"\r\n - \"GB/T 9704-2012 Layout Standard for Official Documents\"\r\n - \"IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides\"\r\n - \"Springer LNCS / Nature / HBR Document Templates\"\r\ndescription: >\r\n Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET).\r\n Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing\r\n documents, (C) apply template formatting with XSD validation gate-check.\r\n MUST use this skill whenever the user wants to produce, modify, or format a Word document —\r\n including when they say \"write a report\", \"draft a proposal\", \"make a contract\",\r\n \"fill in this form\", \"reformat to match this template\", or any task whose final output\r\n is a .docx file. Even if the user doesn't mention \"docx\" explicitly, if the task\r\n implies a printable/formal document, use this skill.\r\ntriggers:\r\n - Word\r\n - docx\r\n - document\r\n - 文档\r\n - Word文档\r\n - 报告\r\n - 合同\r\n - 公文\r\n - 排版\r\n - 套模板\r\n---\r\n\r\n# minimax-docx\r\n\r\nCreate, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).\r\n\r\n## Setup\r\n\r\n**First time:** `bash scripts/setup.sh` (or `powershell scripts/setup.ps1` on Windows, `--minimal` to skip optional deps).\r\n\r\n**First operation in session:** `scripts/env_check.sh` — do not proceed if `NOT READY`. (Skip on subsequent operations within the same session.)\r\n\r\n## Quick Start: Direct C# Path\r\n\r\nWhen the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:\r\n\r\n```csharp\r\n// File: scripts/dotnet/task.csx (or a new .cs in a Console project)\r\n// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx\r\n#r \"nuget: DocumentFormat.OpenXml, 3.2.0\"\r\n\r\nusing DocumentFormat.OpenXml;\r\nusing DocumentFormat.OpenXml.Packaging;\r\nusing DocumentFormat.OpenXml.Wordprocessing;\r\n\r\nusing var doc = WordprocessingDocument.Create(\"output.docx\", WordprocessingDocumentType.Document);\r\nvar mainPart = doc.AddMainDocumentPart();\r\nmainPart.Document = new Document(new Body());\r\n\r\n// --- Your logic here ---\r\n// Read the relevant Samples/*.cs file FIRST for tested patterns.\r\n// See Samples/ table in References section below.\r\n```\r\n\r\n**Before writing any C#, read the relevant `Samples/*.cs` file** — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.\r\n\r\n## CLI shorthand\r\n\r\nAll CLI commands below use `$CLI` as shorthand for:\r\n```bash\r\ndotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --\r\n```\r\n\r\n## Pipeline routing\r\n\r\nRoute by checking: does the user have an input .docx file?\r\n\r\n```\r\nUser task\r\n├─ No input file → Pipeline A: CREATE\r\n│ signals: \"write\", \"create\", \"draft\", \"generate\", \"new\", \"make a report/proposal/memo\"\r\n│ → Read references/scenario_a_create.md\r\n│\r\n└─ Has input .docx\r\n ├─ Replace/fill/modify content → Pipeline B: FILL-EDIT\r\n │ signals: \"fill in\", \"replace\", \"update\", \"change text\", \"add section\", \"edit\"\r\n │ → Read references/scenario_b_edit_content.md\r\n │\r\n └─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY\r\n signals: \"reformat\", \"apply template\", \"restyle\", \"match this format\", \"套模板\", \"排版\"\r\n ├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)\r\n └─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE\r\n (use template as base, replace example content with user content)\r\n → Read references/scenario_c_apply_template.md\r\n```\r\n\r\nIf the request spans multiple pipelines, run them sequentially (e.g., Create then Format-Apply).\r\n\r\n## Pre-processing\r\n\r\nConvert `.doc` → `.docx` if needed: `scripts/doc_to_docx.sh input.doc output_dir/`\r\n\r\nPreview before editing (avoids reading raw XML): `scripts/docx_preview.sh document.docx`\r\n\r\nAnalyze structure for editing scenarios: `$CLI analyze --input document.docx`\r\n\r\n## Scenario A: Create\r\n\r\nRead `references/scenario_a_create.md`, `references/typography_guide.md`, and `references/design_principles.md` first. Pick an aesthetic recipe from `Samples/AestheticRecipeSamples.cs` that matches the document type — do not invent formatting values. For CJK, also read `references/cjk_typography.md`.\r\n\r\n**Choose your path:**\r\n- **Simple** (plain text, minimal formatting): use CLI — `$CLI create --type report --output out.docx --config content.json`\r\n- **Structural** (custom styles, multi-section, TOC, images, complex tables): write C# directly. Read the relevant `Samples/*.cs` first.\r\n\r\nCLI options: `--type` (report|letter|memo|academic), `--title`, `--author`, `--page-size` (letter|a4|legal|a3), `--margins` (standard|narrow|wide), `--header`, `--footer`, `--page-numbers`, `--toc`, `--content-json`.\r\n\r\nThen run the **validation pipeline** (below).\r\n\r\n## Scenario B: Edit / Fill\r\n\r\nRead `references/scenario_b_edit_content.md` first. Preview → analyze → edit → validate.\r\n\r\n**Choose your path:**\r\n- **Simple** (text replacement, placeholder fill): use CLI subcommands.\r\n- **Structural** (add/reorganize sections, modify styles, manipulate tables, insert images): write C# directly. Read `references/openxml_element_order.md` and the relevant `Samples/*.cs`.\r\n\r\nAvailable CLI edit subcommands:\r\n- `replace-text --find \"X\" --replace \"Y\"`\r\n- `fill-placeholders --data '{\"key\":\"value\"}'`\r\n- `fill-table --data table.json`\r\n- `insert-section`, `remove-section`, `update-header-footer`\r\n\r\n```bash\r\n$CLI edit replace-text --input in.docx --output out.docx --find \"OLD\" --replace \"NEW\"\r\n$CLI edit fill-placeholders --input in.docx --output out.docx --data '{\"name\":\"John\"}'\r\n```\r\n\r\nThen run the **validation pipeline**. Also run diff to verify minimal changes:\r\n```bash\r\n$CLI diff --before in.docx --after out.docx\r\n```\r\n\r\n## Scenario C: Apply Template\r\n\r\nRead `references/scenario_c_apply_template.md` first. Preview and analyze both source and template.\r\n\r\n```bash\r\n$CLI apply-template --input source.docx --template template.docx --output out.docx\r\n```\r\n\r\nFor complex template operations (multi-template merge, per-section headers/footers, style merging), write C# directly — see Critical Rules below for required patterns.\r\n\r\nRun the **validation pipeline**, then the **hard gate-check**:\r\n```bash\r\n$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd\r\n```\r\nGate-check is a **hard requirement**. Do NOT deliver until it passes. If it fails: diagnose, fix, re-run.\r\n\r\nAlso diff to verify content preservation: `$CLI diff --before source.docx --after out.docx`\r\n\r\n## Validation pipeline\r\n\r\nRun after every write operation. For Scenario C the full pipeline is **mandatory**; for A/B it is **recommended** (skip only if the operation was trivially simple).\r\n\r\n```bash\r\n$CLI merge-runs --input doc.docx # 1. consolidate runs\r\n$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd # 2. XSD structure\r\n$CLI validate --input doc.docx --business # 3. business rules\r\n```\r\n\r\nIf XSD fails, auto-repair and retry:\r\n```bash\r\n$CLI fix-order --input doc.docx\r\n$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd\r\n```\r\n\r\nIf XSD still fails, fall back to business rules + preview:\r\n```bash\r\n$CLI validate --input doc.docx --business\r\nscripts/docx_preview.sh doc.docx\r\n# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct\r\n```\r\n\r\nFinal preview: `scripts/docx_preview.sh doc.docx`\r\n\r\n## Critical rules\r\n\r\nThese prevent file corruption — OpenXML is strict about element ordering.\r\n\r\n**Element order** (properties always first):\r\n\r\n| Parent | Order |\r\n|--------|-------|\r\n| `w:p` | `pPr` → runs |\r\n| `w:r` | `rPr` → `t`/`br`/`tab` |\r\n| `w:tbl`| `tblPr` → `tblGrid` → `tr` |\r\n| `w:tr` | `trPr` → `tc` |\r\n| `w:tc` | `tcPr` → `p` (min 1 ``) |\r\n| `w:body` | block content → `sectPr` (LAST child) |\r\n\r\n**Direct format contamination:** When copying content from a source document, inline `rPr` (fonts, color) and `pPr` (borders, shading, spacing) override template styles. Always strip direct formatting — keep only `pStyle` reference and `t` text. Clean tables too (including `pPr/rPr` inside cells).\r\n\r\n**Track changes:** `` uses ``, never ``. `` uses ``, never ``.\r\n\r\n**Font size:** `w:sz` = points × 2 (12pt → `sz=\"24\"`). Margins/spacing in DXA (1 inch = 1440, 1cm ≈ 567).\r\n\r\n**Heading styles MUST have OutlineLevel:** When defining heading styles (Heading1, ThesisH1, etc.), always include `new OutlineLevel { Val = N }` in `StyleParagraphProperties` (H1→0, H2→1, H3→2). Without this, Word sees them as plain styled text — TOC and navigation pane won't work.\r\n\r\n**Multi-template merge:** When given multiple template files (font, heading, breaks), read `references/scenario_c_apply_template.md` section \"Multi-Template Merge\" FIRST. Key rules:\r\n- Merge styles from all templates into one styles.xml. Structure (sections/breaks) comes from the breaks template.\r\n- Each content paragraph must appear exactly ONCE — never duplicate when inserting section breaks.\r\n- NEVER insert empty/blank paragraphs as padding or section separators. Output paragraph count must equal input. Use section break properties (`w:sectPr` inside `w:pPr`) and style spacing (`w:spacing` before/after) for visual separation.\r\n- Insert oddPage section breaks before EVERY chapter heading, not just the first. Even if a chapter has dual-column content, it MUST start with oddPage; use a second continuous break after the heading for column switching.\r\n- Dual-column chapters need THREE section breaks: (1) oddPage in preceding para's pPr, (2) continuous+cols=2 in the chapter HEADING's pPr, (3) continuous+cols=1 in the last body para's pPr to revert.\r\n- Copy `titlePg` settings from the breaks template for EACH section. Abstract and TOC sections typically need `titlePg=true`.\r\n\r\n**Multi-section headers/footers:** Templates with 10+ sections (e.g., Chinese thesis) have DIFFERENT headers/footers per section (Roman vs Arabic page numbers, different header text per zone). Rules:\r\n- Use C-2 Base-Replace: copy the TEMPLATE as output base, then replace body content. This preserves all sections, headers, footers, and titlePg settings automatically.\r\n- NEVER recreate headers/footers from scratch — copy template header/footer XML byte-for-byte.\r\n- NEVER add formatting (borders, alignment, font size) not present in the template header XML.\r\n- Non-cover sections MUST have header/footer XML files (at least empty header + page number footer).\r\n- See `references/scenario_c_apply_template.md` section \"Multi-Section Header/Footer Transfer\".\r\n\r\n## References\r\n\r\nLoad as needed — don't load all at once. Pick the most relevant files for the task.\r\n\r\n**The C# samples and design references below are the project's knowledge base (\"encyclopedia\").** When writing OpenXML code, ALWAYS read the relevant sample file first — it contains compilable, SDK-version-verified patterns that prevent common errors. When making aesthetic decisions, read the design principles and recipe files — they encode tested, harmonious parameter sets from authoritative sources (IEEE, ACM, APA, Nature, etc.), not guesses.\r\n\r\n### Scenario guides (read first for each pipeline)\r\n\r\n| File | When |\r\n|------|------|\r\n| `references/scenario_a_create.md` | Pipeline A: creating from scratch |\r\n| `references/scenario_b_edit_content.md` | Pipeline B: editing existing content |\r\n| `references/scenario_c_apply_template.md` | Pipeline C: applying template formatting |\r\n\r\n### C# code samples (compilable, heavily commented — read when writing code)\r\n\r\n| File | Topic |\r\n|------|-------|\r\n| `Samples/DocumentCreationSamples.cs` | Document lifecycle: create, open, save, streams, doc defaults, settings, properties, page setup, multi-section |\r\n| `Samples/StyleSystemSamples.cs` | Styles: Normal/Heading chain, character/table/list styles, DocDefaults, latentStyles, CJK 公文, APA 7th, import, resolve inheritance |\r\n| `Samples/CharacterFormattingSamples.cs` | RunProperties: fonts, size, bold/italic, all underlines, color, highlight, strike, sub/super, caps, spacing, shading, border, emphasis marks |\r\n| `Samples/ParagraphFormattingSamples.cs` | ParagraphProperties: justification, indentation, line/paragraph spacing, keep/widow, outline level, borders, tabs, numbering, bidi, frame |\r\n| `Samples/TableSamples.cs` | Tables: borders, grid, cell props, margins, row height, header repeat, merge (H+V), nested, floating, three-line 三线表, zebra striping |\r\n| `Samples/HeaderFooterSamples.cs` | Headers/footers: page numbers, \"Page X of Y\", first/even/odd, logo image, table layout, 公文 \"-X-\", per-section |\r\n| `Samples/ImageSamples.cs` | Images: inline, floating, text wrapping, border, alt text, in header/table, replace, SVG fallback, dimension calc |\r\n| `Samples/ListAndNumberingSamples.cs` | Numbering: bullets, multi-level decimal, custom symbols, outline→headings, legal, Chinese 一/（一）/1./(1), restart/continue |\r\n| `Samples/FieldAndTocSamples.cs` | Fields: TOC, SimpleField vs complex field, DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF, TOC styles |\r\n| `Samples/FootnoteAndCommentSamples.cs` | Footnotes, endnotes, comments (4-file system), bookmarks, hyperlinks (internal + external) |\r\n| `Samples/TrackChangesSamples.cs` | Revisions: insertions (w:t), deletions (w:delText!), formatting changes, accept/reject all, move tracking |\r\n| `Samples/AestheticRecipeSamples.cs` | 13 aesthetic recipes from authoritative sources: ModernCorporate, AcademicThesis, ExecutiveBrief, ChineseGovernment (GB/T 9704), MinimalModern, IEEE Conference, ACM sigconf, APA 7th, MLA 9th, Chicago/Turabian, Springer LNCS, Nature, HBR — each with exact values from official style guides |\r\n\r\nNote: `Samples/` path is relative to `scripts/dotnet/MiniMaxAIDocx.Core/`.\r\n\r\n### Markdown references (read when you need specifications or design rules)\r\n\r\n| File | When |\r\n|------|------|\r\n| `references/openxml_element_order.md` | XML element ordering rules (prevents corruption) |\r\n| `references/openxml_units.md` | Unit conversion: DXA, EMU, half-points, eighth-points |\r\n| `references/openxml_encyclopedia_part1.md` | Detailed C# encyclopedia: document creation, styles, character & paragraph formatting |\r\n| `references/openxml_encyclopedia_part2.md` | Detailed C# encyclopedia: page setup, tables, headers/footers, sections, doc properties |\r\n| `references/openxml_encyclopedia_part3.md` | Detailed C# encyclopedia: TOC, footnotes, fields, track changes, comments, images, math, numbering, protection |\r\n| `references/typography_guide.md` | Font pairing, sizes, spacing, page layout, table design, color schemes |\r\n| `references/cjk_typography.md` | CJK fonts, 字号 sizes, RunFonts mapping, GB/T 9704 公文 standard |\r\n| `references/cjk_university_template_guide.md` | Chinese university thesis templates: numeric styleIds (1/2/3 vs Heading1), document zone structure (cover→abstract→TOC→body→references), font expectations, common mistakes |\r\n| `references/design_principles.md` | **Aesthetic foundations**: 6 design principles (white space, contrast/scale, proximity, alignment, repetition, hierarchy) — teaches WHY, not just WHAT |\r\n| `references/design_good_bad_examples.md` | **Good vs Bad comparisons**: 10 categories of typography mistakes with OpenXML values, ASCII mockups, and fixes |\r\n| `references/track_changes_guide.md` | Revision marks deep dive |\r\n| `references/troubleshooting.md` | **Symptom-driven fixes**: 13 common problems indexed by what you SEE (headings wrong, images missing, TOC broken, etc.) — search by symptom, find the fix |\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7ay31t8b2nm3fjytaw0f9hqh8001cc\",\n \"slug\": \"yh-minimax-docx\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1774446186824\n}\n\nFile v1.0.0:references/cjk_typography.md\n\n# CJK Typography & Mixed-Script Guide\r\n\r\nRules for Chinese, Japanese, and Korean text in DOCX documents.\r\n\r\n## Table of Contents\r\n\r\n1. [Font Selection](#font-selection)\r\n2. [Font Size Names (CJK)](#font-size-names)\r\n3. [RunFonts Mapping](#runfonts-mapping)\r\n4. [Punctuation & Line Breaking](#punctuation--line-breaking)\r\n5. [Paragraph Indentation](#paragraph-indentation)\r\n6. [Line Spacing for CJK](#line-spacing)\r\n7. [Chinese Government Standard (GB/T 9704)](#gbt-9704)\r\n8. [Mixed CJK + Latin Best Practices](#mixed-script)\r\n9. [OpenXML Quick Reference](#openxml-quick-reference)\r\n\r\n---\r\n\r\n## Font Selection\r\n\r\n### Recommended CJK Fonts\r\n\r\n| Language | Serif (正文) | Sans (标题) | Notes |\r\n|----------|-------------|-------------|-------|\r\n| **Simplified Chinese** | 宋体 (SimSun) | 微软雅黑 (Microsoft YaHei) | YaHei for screen, SimSun for print |\r\n| **Simplified Chinese** | 仿宋 (FangSong) | 黑体 (SimHei) | Government documents |\r\n| **Traditional Chinese** | 新細明體 (PMingLiU) | 微軟正黑體 (Microsoft JhengHei) | Taiwan standard |\r\n| **Japanese** | MS 明朝 (MS Mincho) | MS ゴシック (MS Gothic) | Classic pairing |\r\n| **Japanese** | 游明朝 (Yu Mincho) | 游ゴシック (Yu Gothic) | Modern, Windows 10+ |\r\n| **Korean** | 바탕 (Batang) | 맑은 고딕 (Malgun Gothic) | Standard pairing |\r\n\r\n### Government Document Fonts (公文)\r\n\r\n| Element | Font | Size |\r\n|---------|------|------|\r\n| 标题 (title) | 小标宋 (FZXiaoBiaoSong-B05S) | 二号 (22pt) |\r\n| 一级标题 | 黑体 (SimHei) | 三号 (16pt) |\r\n| 二级标题 | 楷体_GB2312 (KaiTi_GB2312) | 三号 (16pt) |\r\n| 三级标题 | 仿宋_GB2312 加粗 | 三号 (16pt) |\r\n| 正文 (body) | 仿宋_GB2312 (FangSong_GB2312) | 三号 (16pt) |\r\n| 附注/页码 | 宋体 (SimSun) | 四号 (14pt) |\r\n\r\n---\r\n\r\n## Font Size Names\r\n\r\nCJK uses named sizes. Map to points and `w:sz` half-point values:\r\n\r\n| 字号 | Points | `w:sz` | Common Use |\r\n|------|--------|--------|------------|\r\n| 初号 | 42pt | 84 | Display title |\r\n| 小初 | 36pt | 72 | Large title |\r\n| 一号 | 26pt | 52 | Chapter heading |\r\n| 小一 | 24pt | 48 | Major heading |\r\n| 二号 | 22pt | 44 | Document title (公文) |\r\n| 小二 | 18pt | 36 | Western H1 equivalent |\r\n| 三号 | 16pt | 32 | CJK heading / 公文 body |\r\n| 小三 | 15pt | 30 | Sub-heading |\r\n| 四号 | 14pt | 28 | CJK subheading |\r\n| 小四 | 12pt | 24 | Standard body (CJK) |\r\n| 五号 | 10.5pt | 21 | Compact CJK body |\r\n| 小五 | 9pt | 18 | Footnotes |\r\n| 六号 | 7.5pt | 15 | Fine print |\r\n\r\n---\r\n\r\n## RunFonts Mapping\r\n\r\nOpenXML uses four font slots to handle multilingual text:\r\n\r\n```xml\r\n\r\n w:hAnsi=\"Calibri\" \r\n w:eastAsia=\"SimSun\" \r\n w:cs=\"Arial\" \r\n/>\r\n```\r\n\r\n**Word's character classification logic:**\r\n\r\n1. Character is in CJK range → uses `w:eastAsia` font\r\n2. Character is in complex script range → uses `w:cs` font\r\n3. Character is basic Latin (ASCII) → uses `w:ascii` font\r\n4. Everything else → uses `w:hAnsi` font\r\n\r\n**Key**: `w:eastAsia` is the **only** way to set CJK fonts. Setting just `w:ascii` will NOT affect CJK characters. Mixed text within a single run auto-switches fonts at the character level — no need for separate runs.\r\n\r\n### Document Defaults\r\n\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n`w:lang w:eastAsia` helps Word resolve ambiguous characters (e.g., punctuation shared between CJK and Latin).\r\n\r\n---\r\n\r\n## Punctuation & Line Breaking\r\n\r\n### Full-Width vs Half-Width\r\n\r\nCJK text uses full-width punctuation:\r\n\r\n| Type | CJK | Latin |\r\n|------|-----|-------|\r\n| Period | 。(U+3002) | . |\r\n| Comma | ，(U+FF0C) 、(U+3001) | , |\r\n| Colon | ：(U+FF1A) | : |\r\n| Semicolon | ；(U+FF1B) | ; |\r\n| Quotes | 「」『』 or \"\"'' | \"\" '' |\r\n| Parentheses | （）(U+FF08/09) | () |\r\n\r\nIn mixed text, use the punctuation style of the **surrounding language context**.\r\n\r\n### OpenXML Controls\r\n\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n### Kinsoku Rules (禁則処理)\r\n\r\nPrevents certain characters from appearing at the start or end of a line:\r\n- **Cannot start a line**: `）」』】〉》。、，！？；：` and closing brackets\r\n- **Cannot end a line**: `（「『【〈《` and opening brackets\r\n\r\nWord applies these automatically when `w:kinsoku` is enabled.\r\n\r\n### Line Breaking\r\n\r\n- CJK characters can break between **any two characters** (no word boundaries needed)\r\n- Latin words within CJK text still follow word-boundary breaking\r\n- `w:wordWrap w:val=\"false\"` enables CJK-style breaking (break anywhere)\r\n\r\n---\r\n\r\n## Paragraph Indentation\r\n\r\n### Chinese Standard: 2-Character Indent\r\n\r\nChinese body text conventionally uses a 2-character first-line indent:\r\n\r\n```xml\r\n \r\n```\r\n\r\nPreferred over `w:firstLine` with fixed DXA because `firstLineChars` scales with font size.\r\n\r\n| Indent | Value |\r\n|--------|-------|\r\n| 1 character | `w:firstLineChars=\"100\"` |\r\n| 2 characters | `w:firstLineChars=\"200\"` |\r\n| 3 characters | `w:firstLineChars=\"300\"` |\r\n\r\n---\r\n\r\n## Line Spacing\r\n\r\n- CJK characters are taller than Latin characters at the same point size\r\n- Default `1.0` line spacing may feel cramped with CJK text\r\n- Recommended: `1.15–1.5` for mixed CJK+Latin, `1.0` with fixed 28pt for 公文\r\n\r\n### Auto Spacing\r\n\r\n```xml\r\n\r\n \r\n \r\n\r\n```\r\n\r\nAdds ~¼ em spacing between CJK and non-CJK characters automatically. **Recommended: always enable.**\r\n\r\n---\r\n\r\n## GB/T 9704\r\n\r\nChinese government document standard (党政机关公文格式). These are **strict requirements**, not suggestions.\r\n\r\n### Page Setup\r\n\r\n| Parameter | Value | OpenXML |\r\n|-----------|-------|---------|\r\n| Page size | A4 (210×297mm) | Width=11906, Height=16838 |\r\n| Top margin | 37mm | 2098 DXA |\r\n| Bottom margin | 35mm | 1984 DXA |\r\n| Left margin | 28mm | 1588 DXA |\r\n| Right margin | 26mm | 1474 DXA |\r\n| Characters/line | 28 | |\r\n| Lines/page | 22 | |\r\n| Line spacing | Fixed 28pt | `line=\"560\"` lineRule=\"exact\" |\r\n\r\n### Document Structure\r\n\r\n```\r\n┌─────────────────────────────────┐\r\n│ 发文机关标志 (红头) │ ← 小标宋 or 红色大字\r\n│ ══════════════════ (红线) │ ← Red #FF0000, 2pt\r\n├─────────────────────────────────┤\r\n│ 发文字号: X机发〔2025〕X号 │ ← 仿宋 三号, centered\r\n│ │\r\n│ 标题 (Title) │ ← 小标宋 二号, centered\r\n│ │ 可分多行，回行居中\r\n│ 主送机关: │ ← 仿宋 三号\r\n│ │\r\n│ 正文 (Body)... │ ← 仿宋_GB2312 三号\r\n│ 一、一级标题 │ ← 黑体 三号\r\n│ （一）二级标题 │ ← 楷体 三号\r\n│ 1. 三级标题 │ ← 仿宋 三号 加粗\r\n│ (1) 四级标题 │ ← 仿宋 三号\r\n│ │\r\n│ 附件: 1. xxx │ ← 仿宋 三号\r\n│ │\r\n│ 发文机关署名 │ ← 仿宋 三号\r\n│ 成文日期 │ ← 仿宋 三号, 小写中文数字\r\n├─────────────────────────────────┤\r\n│ ══════════════════ (版记线) │\r\n│ 抄送: xxx │ ← 仿宋 四号\r\n│ 印发机关及日期 │ ← 仿宋 四号\r\n└─────────────────────────────────┘\r\n```\r\n\r\n### Numbering System\r\n\r\n```\r\n一、 ← 黑体 (SimHei), no indentation\r\n（一） ← 楷体 (KaiTi), indented 2 chars\r\n1. ← 仿宋加粗 (FangSong Bold), indented 2 chars\r\n(1) ← 仿宋 (FangSong), indented 2 chars\r\n```\r\n\r\n### Colors\r\n\r\n| Element | Color | Requirement |\r\n|---------|-------|-------------|\r\n| All body text | Black #000000 | Mandatory |\r\n| 红头 (agency name) | Red #FF0000 | Mandatory |\r\n| 红线 (separator) | Red #FF0000 | Mandatory |\r\n| 公章 (official seal) | Red | Mandatory |\r\n\r\n### Page Numbers\r\n\r\n- Position: bottom center\r\n- Format: `-X-` (dash-number-dash)\r\n- Font: 宋体 四号 (SimSun 14pt, `sz=\"28\"`)\r\n- No page number on cover page if present\r\n\r\n---\r\n\r\n## Mixed Script\r\n\r\n### Font Size Harmony\r\n\r\nCJK characters appear larger than Latin characters at the same point size. Compensation:\r\n\r\n- If body is Calibri 11pt, pair with CJK at 11pt (same size — CJK looks slightly larger but acceptable)\r\n- If precise visual match needed, CJK can be set 0.5–1pt smaller\r\n- In practice, same point size is standard — don't over-optimize\r\n\r\n### Bold and Italic\r\n\r\n- **Chinese/Japanese have no true italic.** Word synthesizes a slant which looks poor\r\n- Use **bold** for emphasis in CJK text\r\n- Use 着重号 (emphasis dots) for traditional emphasis: `` on RunProperties\r\n\r\n---\r\n\r\n## OpenXML Quick Reference\r\n\r\n### Set EastAsia Font (C#)\r\n\r\n```csharp\r\nnew Run(\r\n new RunProperties(\r\n new RunFonts { EastAsia = \"SimSun\", Ascii = \"Calibri\", HighAnsi = \"Calibri\" },\r\n new FontSize { Val = \"32\" } // 三号 = 16pt = sz 32\r\n ),\r\n new Text(\"这是正文内容\")\r\n);\r\n```\r\n\r\n### Document Defaults (C#)\r\n\r\n```csharp\r\nnew DocDefaults(new RunPropertiesDefault(new RunPropertiesBaseStyle(\r\n new RunFonts {\r\n Ascii = \"Calibri\", HighAnsi = \"Calibri\",\r\n EastAsia = \"Microsoft YaHei\"\r\n },\r\n new Languages { Val = \"en-US\", EastAsia = \"zh-CN\" }\r\n)));\r\n```\r\n\r\n### 公文 Style Definitions (C#)\r\n\r\n```csharp\r\n// Title style — 小标宋 二号 centered\r\nnew Style(\r\n new StyleName { Val = \"GongWen Title\" },\r\n new BasedOn { Val = \"Normal\" },\r\n new StyleRunProperties(\r\n new RunFonts { EastAsia = \"FZXiaoBiaoSong-B05S\" },\r\n new FontSize { Val = \"44\" }, // 二号 = 22pt\r\n new Bold()\r\n ),\r\n new StyleParagraphProperties(\r\n new Justification { Val = JustificationValues.Center },\r\n new SpacingBetweenLines { Line = \"560\", LineRule = LineSpacingRuleValues.Exact }\r\n )\r\n) { Type = StyleValues.Paragraph, StyleId = \"GongWenTitle\" };\r\n\r\n// Body style — 仿宋_GB2312 三号\r\nnew Style(\r\n new StyleName { Val = \"GongWen Body\" },\r\n new StyleRunProperties(\r\n new RunFonts { EastAsia = \"FangSong_GB2312\", Ascii = \"FangSong_GB2312\" },\r\n new FontSize { Val = \"32\" } // 三号 = 16pt\r\n ),\r\n new StyleParagraphProperties(\r\n new SpacingBetweenLines { Line = \"560\", LineRule = LineSpacingRuleValues.Exact }\r\n )\r\n) { Type = StyleValues.Paragraph, StyleId = \"GongWenBody\" };\r\n```\r\n\r\n### Emphasis Dots (着重号)\r\n\r\n```csharp\r\nnew RunProperties(new Emphasis { Val = EmphasisMarkValues.Dot });\r\n```\r\n\r\n### East Asian Text Layout\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\n\nFile v1.0.0:references/cjk_university_template_guide.md\n\n# Chinese University Thesis Template Guide (中国高校论文模板指南)\r\n\r\n## Why This Guide Exists\r\n\r\nChinese university thesis templates (.docx) have structural patterns that differ significantly\r\nfrom Western templates. Agents that assume Western conventions (Heading1/Heading2/Normal) will\r\nfail repeatedly. This guide documents the ACTUAL patterns found in Chinese templates.\r\n\r\n## Common StyleId Patterns\r\n\r\n### Pattern A: Numeric IDs (most common in Chinese Word templates)\r\n\r\n| Style Purpose | styleId | w:name | w:basedOn |\r\n|--------------|---------|--------|-----------|\r\n| Normal body | `a` | \"Normal\" | — |\r\n| Default paragraph font | `a0` | \"Default Paragraph Font\" | — |\r\n| Heading 1 (章标题) | `1` | \"heading 1\" | `a` |\r\n| Heading 2 (节标题) | `2` | \"heading 2\" | `a` |\r\n| Heading 3 (小节标题) | `3` | \"heading 3\" | `a` |\r\n| TOC 1 | `11` | \"toc 1\" | `a` |\r\n| TOC 2 | `21` | \"toc 2\" | `a` |\r\n| TOC 3 | `31` | \"toc 3\" | `a` |\r\n| Header | `a3` | \"header\" | `a` |\r\n| Footer | `a4` | \"footer\" | `a` |\r\n| Table of Contents heading | `10` | \"TOC Heading\" | `1` |\r\n\r\n### Pattern B: English IDs (less common, usually from international templates)\r\nStandard Heading1/Heading2/Heading3/Normal — these follow the Western pattern.\r\n\r\n### Pattern C: Mixed (some Chinese, some English)\r\nSome templates define custom styles with Chinese names:\r\n| Style Purpose | styleId | w:name |\r\n|--------------|---------|--------|\r\n| 论文标题 | `lunwenbiaoti` | \"论文标题\" |\r\n| 章标题 | `zhangbiaoti` | \"章标题\" |\r\n| 正文 | `zhengwen` | \"正文\" |\r\n\r\n### How to Identify Which Pattern\r\n\r\n```bash\r\n# Extract all styleIds from the template\r\n$CLI analyze --input template.docx --styles-only\r\n\r\n# Or manually:\r\n# unzip template.docx word/styles.xml\r\n# Search for w:styleId= in the extracted file\r\n```\r\n\r\nLook at the first few styleIds. If you see `1`, `2`, `3`, `a`, `a0` → Pattern A.\r\nIf you see `Heading1`, `Normal` → Pattern B.\r\n\r\n## Standard Thesis Structure\r\n\r\nChinese university theses follow a highly standardized structure:\r\n\r\n```\r\n┌─────────────────────────────────────┐\r\n│ 封面 (Cover Page) │ ← Usually 1-2 pages\r\n│ - 校名、校徽 │\r\n│ - 论文题目 (title) │\r\n│ - 作者、导师、院系、日期 │\r\n├─────────────────────────────────────┤\r\n│ 学术诚信承诺书 / 独创性声明 │ ← 1 page\r\n│ (Academic Integrity Declaration) │\r\n├─────────────────────────────────────┤\r\n│ 中文摘要 (Chinese Abstract) │ ← 1-2 pages\r\n│ - \"摘 要\" heading │\r\n│ - Abstract body │\r\n│ - \"关键词：\" line │\r\n├─────────────────────────────────────┤\r\n│ 英文摘要 (English Abstract) │ ← 1-2 pages\r\n│ - \"ABSTRACT\" heading │\r\n│ - Abstract body │\r\n│ - \"Keywords:\" line │\r\n├─────────────────────────────────────┤\r\n│ 目录 (Table of Contents) │ ← 1-3 pages\r\n│ - Often inside SDT block │\r\n│ - Static example entries │\r\n│ - TOC field code │\r\n├─────────────────────────────────────┤\r\n│ 正文 (Body) │ ← Main content\r\n│ 第1章 绪论 │\r\n│ 1.1 研究背景 │\r\n│ 1.2 研究目的和意义 │\r\n│ 第2章 文献综述 │\r\n│ ... │\r\n│ 第N章 结论与展望 │\r\n├─────────────────────────────────────┤\r\n│ 参考文献 (References) │ ← Styled differently\r\n├─────────────────────────────────────┤\r\n│ 致谢 (Acknowledgments) │ ← Optional\r\n├─────────────────────────────────────┤\r\n│ 附录 (Appendices) │ ← Optional\r\n└─────────────────────────────────────┘\r\n```\r\n\r\n## Identifying Zone Boundaries in Templates\r\n\r\nTemplates contain EXAMPLE content that must be replaced. Here's how to find the zones:\r\n\r\n### Zone A (Front matter) — KEEP from template\r\n- Starts at: paragraph 0\r\n- Ends at: the paragraph BEFORE the first chapter heading\r\n- Contains: cover, declaration, abstracts, TOC\r\n- How to detect end: search for first paragraph with style `1` (or Heading1) containing \"第1章\" or \"绪论\"\r\n\r\n### Zone B (Body content) — REPLACE with user content\r\n- Starts at: first chapter heading (\"第1章...\")\r\n- Ends at: \"参考文献\" heading (inclusive) or last body paragraph before acknowledgments\r\n- How to detect:\r\n ```python\r\n for i, el in enumerate(body_elements):\r\n text = get_text(el)\r\n style = get_style(el)\r\n if style in ('1', 'Heading1') and ('第1章' in text or '绪论' in text):\r\n zone_b_start = i\r\n if '参考文献' in text:\r\n zone_b_end = i\r\n ```\r\n\r\n### Zone C (Back matter) — KEEP from template (or remove)\r\n- Starts after: 参考文献\r\n- Contains: 致谢, 附录, final sectPr\r\n\r\n## Font Expectations in Chinese Thesis Templates\r\n\r\n| Element | Font | Size (字号) | Size (pt) | w:sz |\r\n|---------|------|------------|-----------|------|\r\n| 论文标题 | 华文中宋 or 黑体 | 二号 or 小二 | 22pt or 18pt | 44 or 36 |\r\n| 章标题 (H1) | 黑体 | 三号 | 16pt | 32 |\r\n| 节标题 (H2) | 黑体 | 四号 | 14pt | 28 |\r\n| 小节标题 (H3) | 黑体 | 小四 | 12pt | 24 |\r\n| 正文 | 宋体 | 小四 | 12pt | 24 |\r\n| 页眉 | 宋体 | 五号 | 10.5pt | 21 |\r\n| 页脚/页码 | 宋体 | 五号 | 10.5pt | 21 |\r\n| 表格内容 | 宋体 | 五号 | 10.5pt | 21 |\r\n| 参考文献条目 | 宋体 | 五号 | 10.5pt | 21 |\r\n\r\n## RunFonts for CJK Body Text\r\n\r\n```xml\r\n\r\n```\r\n\r\nFor headings:\r\n```xml\r\n\r\n```\r\n\r\nIMPORTANT: When cleaning direct formatting, ALWAYS preserve w:eastAsia.\r\nRemoving it causes Chinese text to fall back to the wrong font.\r\n\r\n## Common Mistakes with Chinese Templates\r\n\r\n1. **Searching for `Heading1`** — Chinese templates use `1`, not `Heading1`\r\n2. **Clearing all rFonts** — Must keep eastAsia font declarations\r\n3. **Assuming \"第1章\" is the first paragraph** — It's typically paragraph 100+ after cover/abstract/TOC\r\n4. **Ignoring SDT blocks in TOC** — The TOC is wrapped in an SDT, not just field codes\r\n5. **Wrong line spacing** — Chinese theses typically use fixed 20pt (line=\"400\") or 22pt (line=\"440\"), not the 28pt used in government documents\r\n6. **Missing section breaks** — Each zone (abstract, TOC, body) usually has its own sectPr for different headers/footers\r\n\r\n## Style Mapping Quick Reference\r\n\r\nWhen source document uses Western IDs and template uses Chinese numeric IDs:\r\n\r\n```json\r\n{\r\n \"Heading1\": \"1\",\r\n \"Heading2\": \"2\",\r\n \"Heading3\": \"3\",\r\n \"Heading4\": \"3\",\r\n \"Normal\": \"a\",\r\n \"BodyText\": \"a\",\r\n \"ListParagraph\": \"a\",\r\n \"Caption\": \"a\",\r\n \"TOC1\": \"11\",\r\n \"TOC2\": \"21\",\r\n \"TOC3\": \"31\"\r\n}\r\n```\r\n\r\nWhen source uses Chinese numeric IDs and template uses Western IDs — reverse the mapping.\n\nFile v1.0.0:references/comments_guide.md\n\n# Comments System Guide (4-File Architecture)\r\n\r\n## Overview\r\n\r\nWord comments require coordination across **four XML files** plus references in `document.xml`, `[Content_Types].xml`, and `document.xml.rels`.\r\n\r\n---\r\n\r\n## The Four Comment Files\r\n\r\n### 1. `word/comments.xml` — Main Comment Content\r\n\r\nContains the actual comment text:\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n This needs clarification.\r\n \r\n \r\n \r\n\r\n```\r\n\r\nKey attributes: `w:id` (unique integer), `w:author`, `w:date` (ISO 8601), `w:initials`.\r\n\r\n### 2. `word/commentsExtended.xml` — W15 Extensions\r\n\r\nLinks comments to paragraphs and tracks resolved status:\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n- `w15:paraId` — matches the `w14:paraId` of the comment's paragraph in `comments.xml`\r\n- `w15:done` — `\"0\"` = open, `\"1\"` = resolved\r\n\r\n### 3. `word/commentsIds.xml` — Persistent ID Mapping\r\n\r\nProvides durable IDs that survive copy/paste across documents:\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n- `w16cid:paraId` — same as `w15:paraId`\r\n- `w16cid:durableId` — globally unique identifier (8-digit hex)\r\n\r\n### 4. `word/commentsExtensible.xml` — W16 Extensions\r\n\r\nModern comment extensions (used in newer Word versions):\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n---\r\n\r\n## Document.xml References\r\n\r\nComments are anchored in document content using three elements:\r\n\r\n```xml\r\n\r\n \r\n This text has a comment.\r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n- `w:commentRangeStart` — marks where the commented text begins\r\n- `w:commentRangeEnd` — marks where the commented text ends\r\n- `w:commentReference` — the visible comment marker (superscript number), placed in a run after the range end\r\n\r\nThe `w:id` on all three must match the `w:id` in `comments.xml`.\r\n\r\n---\r\n\r\n## Content Types Registration\r\n\r\nAdd to `[Content_Types].xml`:\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n```\r\n\r\n---\r\n\r\n## Relationship Registration\r\n\r\nAdd to `word/_rels/document.xml.rels`:\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n```\r\n\r\n---\r\n\r\n## Step-by-Step: Adding a New Comment\r\n\r\n1. **Choose a unique comment ID** (scan existing `w:id` values, use max + 1)\r\n2. **Generate a paraId** (8-character hex, e.g., `\"1A2B3C4D\"`) and durableId (8-digit hex)\r\n3. **Add to `comments.xml`**: Create `w:comment` element with content\r\n4. **Add to `commentsExtended.xml`**: Create `w15:commentEx` with `paraId`, `done=\"0\"`\r\n5. **Add to `commentsIds.xml`**: Create `w16cid:commentId` with `paraId` and `durableId`\r\n6. **Add to `commentsExtensible.xml`**: Create `w16cex:commentExtensible` with `durableId` and `dateUtc`\r\n7. **Add to `document.xml`**: Insert `w:commentRangeStart`, `w:commentRangeEnd`, and `w:commentReference` around target text\r\n8. **Verify `[Content_Types].xml`** and `document.xml.rels` have entries for all 4 files\r\n\r\n---\r\n\r\n## Step-by-Step: Adding a Reply\r\n\r\nReplies are comments whose paragraph's `w14:paraId` links to a parent comment:\r\n\r\n1. Create a new `w:comment` in `comments.xml` with a new `w:id`\r\n2. In `commentsExtended.xml`, add `w15:commentEx` with:\r\n - `w15:paraId` = new paragraph ID\r\n - `w15:paraIdParent` = the `paraId` of the comment being replied to\r\n - `w15:done=\"0\"`\r\n3. Add entries in `commentsIds.xml` and `commentsExtensible.xml`\r\n4. In `document.xml`, the reply does NOT need its own range markers — it shares the parent's range\r\n\r\n```xml\r\n\r\n\r\n```\r\n\r\n---\r\n\r\n## Step-by-Step: Resolving a Comment\r\n\r\nSet `w15:done=\"1\"` on the comment's `w15:commentEx` entry:\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n```\r\n\r\nThis marks the comment (and all its replies) as resolved. The comment remains visible but appears grayed out in Word.\r\n\r\n---\r\n\r\n## Minimum Viable Comment\r\n\r\nAt minimum, a working comment requires:\r\n1. `comments.xml` with the `w:comment` element\r\n2. `document.xml` with range markers and reference\r\n3. Relationship in `document.xml.rels`\r\n4. Content type in `[Content_Types].xml`\r\n\r\nThe extended files (`commentsExtended`, `commentsIds`, `commentsExtensible`) are optional but recommended for full compatibility with modern Word.\n\nFile v1.0.0:references/design_good_bad_examples.md\n\n# GOOD vs BAD Document Design — Concrete OpenXML Examples\r\n\r\nA side-by-side reference showing common design mistakes and their fixes, with exact OpenXML parameter values. Use this to develop an intuitive sense of what makes a document look professional versus amateur.\r\n\r\nFormat: Each comparison shows the **BAD** version first (the mistake), then the **GOOD** version (the fix), with OpenXML markup and a short explanation.\r\n\r\n---\r\n\r\n## 1. Font Size Disasters\r\n\r\n### 1a. No Hierarchy — Everything the Same Size\r\n\r\n**BAD: Body=12pt, H1=12pt bold**\r\n```\r\n┌──────────────────────────────────┐\r\n│ INTRODUCTION │ ← 12pt bold... same visual weight\r\n│ This is the body text of the │ ← 12pt regular\r\n│ report. It discusses findings │\r\n│ from the quarterly review. │\r\n│ METHODOLOGY │ ← Where does the section start?\r\n│ We collected data from three │\r\n│ sources across the enterprise. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n\r\n\r\n\r\n```\r\n\r\n**GOOD: Modular scale — body=11pt, H3=13pt, H2=16pt, H1=20pt**\r\n```\r\n┌──────────────────────────────────┐\r\n│ │\r\n│ Introduction │ ← 20pt, clearly a title\r\n│ │\r\n│ This is the body text of the │ ← 11pt, comfortable reading size\r\n│ report. It discusses findings │\r\n│ from the quarterly review. │\r\n│ │\r\n│ Methodology │ ← 20pt, section break is obvious\r\n│ │\r\n│ We collected data from three │\r\n│ sources across the enterprise. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** A clear size progression (ratio ~1.25x per step) lets readers instantly identify structure without reading a word.\r\n\r\n---\r\n\r\n### 1b. Too Much Contrast — Children's Book Look\r\n\r\n**BAD: H1=28pt with body=10pt (ratio 2.8x)**\r\n```\r\n┌──────────────────────────────────┐\r\n│ │\r\n│ QUARTERLY REPORT │ ← 28pt, dominates the page\r\n│ │\r\n│ This is body text set very small │ ← 10pt, straining to read\r\n│ and the contrast with the title │\r\n│ makes it feel like a poster. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n \r\n \r\n```\r\n\r\n**GOOD: H1=20pt with body=11pt (ratio ~1.8x)**\r\n```xml\r\n \r\n \r\n```\r\n**Why better:** A heading-to-body ratio between 1.5x and 2.0x reads as \"structured\" rather than \"shouting.\"\r\n\r\n---\r\n\r\n## 2. Spacing Crimes\r\n\r\n### 2a. Wall of Text — No Paragraph or Line Spacing\r\n\r\n**BAD: Single line spacing, 0pt between paragraphs**\r\n```\r\n┌──────────────────────────────────┐\r\n│The findings indicate a strong │\r\n│correlation between training hours│\r\n│and performance metrics. │\r\n│Further analysis revealed that │ ← No gap — where does the new\r\n│departments with higher budgets │ paragraph start?\r\n│achieved better outcomes in all │\r\n│measured categories. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n \r\n\r\n```\r\n\r\n**GOOD: 1.15x line spacing, 8pt after each paragraph**\r\n```\r\n┌──────────────────────────────────┐\r\n│The findings indicate a strong │\r\n│correlation between training │ ← Slightly more air between lines\r\n│hours and performance metrics. │\r\n│ │ ← 8pt gap signals new paragraph\r\n│Further analysis revealed that │\r\n│departments with higher budgets │\r\n│achieved better outcomes in all │\r\n│measured categories. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n \r\n\r\n```\r\n**Why better:** Line spacing gives each line room to breathe; paragraph spacing separates ideas without wasting a full blank line.\r\n\r\n---\r\n\r\n### 2b. Floating Headings — Same Space Above and Below\r\n\r\n**BAD: 12pt before and 12pt after heading**\r\n```\r\n┌──────────────────────────────────┐\r\n│ ...end of previous section. │\r\n│ │ ← 12pt gap\r\n│ Section Two │ ← Heading floats in the middle\r\n│ │ ← 12pt gap\r\n│ Start of section two content. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n\r\n```\r\n\r\n**GOOD: 24pt before, 8pt after heading**\r\n```\r\n┌──────────────────────────────────┐\r\n│ ...end of previous section. │\r\n│ │\r\n│ │ ← 24pt gap — clear section break\r\n│ Section Two │ ← Heading is close to its content\r\n│ │ ← 8pt gap\r\n│ Start of section two content. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n\r\n```\r\n**Why better:** Proximity principle: a heading belongs to the text that follows it, so more space above and less space below anchors it to its content.\r\n\r\n---\r\n\r\n### 2c. Wasteful Gaps — Huge Spacing Everywhere\r\n\r\n**BAD: 24pt after every paragraph, including body text**\r\n```\r\n┌──────────────────────────────────┐\r\n│ First paragraph of text here. │\r\n│ │\r\n│ │ ← 24pt gap after every paragraph\r\n│ │\r\n│ Second paragraph of text here. │\r\n│ │\r\n│ │\r\n│ │\r\n│ Third paragraph. │ ← Document looks mostly white space\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n \r\n```\r\n\r\n**GOOD: Proportional spacing — body=8pt, H2=6pt after, H1=10pt after**\r\n```xml\r\n\r\n \r\n\r\n \r\n\r\n \r\n```\r\n**Why better:** Spacing should vary by element role, creating a visual rhythm rather than uniform gaps.\r\n\r\n---\r\n\r\n## 3. Margin Mistakes\r\n\r\n### 3a. Cramped Margins — Text Running to the Edge\r\n\r\n**BAD: 0.5in margins all around**\r\n```\r\n┌────────────────────────────────────────────────┐\r\n│Text starts almost at the paper edge and runs │\r\n│all the way across making extremely long lines │\r\n│that are hard to track from end back to start. │\r\n│The eye loses its place on every line return. │\r\n└────────────────────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n\r\n```\r\n\r\n**GOOD: 1in margins (standard)**\r\n```xml\r\n\r\n\r\n```\r\n**Why better:** Optimal line length is 60-75 characters. At 11pt Calibri, 6.5in width achieves roughly 70 characters per line.\r\n\r\n---\r\n\r\n### 3b. Over-Padded Margins — Looks Like the Content is Hiding\r\n\r\n**BAD: 2in margins on a short document**\r\n```xml\r\n\r\n\r\n```\r\n\r\n**GOOD: 1in standard, or 1.25in for formal documents**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** Margins should frame the content, not overwhelm it. 1-1.25in works for virtually all business and academic documents.\r\n\r\n---\r\n\r\n## 4. Table Ugliness\r\n\r\n### 4a. Prison Grid — Full Borders on Every Cell\r\n\r\n**BAD: Every cell with 1pt borders on all four sides**\r\n```\r\n┌───────┬───────┬───────┬───────┐\r\n│ Name │ Dept │ Score │ Grade │\r\n├───────┼───────┼───────┼───────┤\r\n│ Alice │ Eng │ 92 │ A │\r\n├───────┼───────┼───────┼───────┤\r\n│ Bob │ Sales │ 85 │ B │\r\n├───────┼───────┼───────┼───────┤\r\n│ Carol │ Eng │ 78 │ C+ │\r\n└───────┴───────┴───────┴───────┘\r\n```\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n**GOOD: Three-line table (三线表) — top thick, header-bottom medium, table-bottom thick**\r\n```\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ← 1.5pt top border\r\n Name Dept Score Grade\r\n────────────────────────────────── ← 0.75pt header separator\r\n Alice Eng 92 A\r\n Bob Sales 85 B\r\n Carol Eng 78 C+\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ← 1.5pt bottom border\r\n```\r\n```xml\r\n\r\n \r\n\r\n \r\n\r\n\r\n\r\n\r\n\r\n\r\n \r\n```\r\n**Why better:** Removing inner borders lets the eye scan data freely. Three lines provide structure without visual clutter.\r\n\r\n---\r\n\r\n### 4b. Text Touching Borders — No Cell Padding\r\n\r\n**BAD: Zero cell margins**\r\n```\r\n┌──────────┬──────────┐\r\n│Name │Department│ ← Text cramped against borders\r\n├──────────┼──────────┤\r\n│Alice │Engineering│\r\n└──────────┴──────────┘\r\n```\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n**GOOD: 0.08in vertical, 0.12in horizontal padding**\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n**Why better:** Padding gives text breathing room inside cells, making every value easier to read.\r\n\r\n---\r\n\r\n### 4c. Invisible Headers — Header Row Same Style as Data\r\n\r\n**BAD: Header row indistinguishable from data**\r\n```xml\r\n\r\n\r\n```\r\n\r\n**GOOD: Bold header text, subtle background fill, bottom border**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** Distinct header styling lets readers instantly locate column meanings, especially in long tables that span pages. The `w:tblHeader` element ensures the header row repeats on every page.\r\n\r\n---\r\n\r\n## 5. Font Pairing Failures\r\n\r\n### 5a. Visual Chaos — Too Many Fonts\r\n\r\n**BAD: 4+ fonts in one document**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n\r\n**GOOD: One font family with weight variation, or two complementary families**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** Limiting to one or two font families creates visual coherence. Vary by size and weight, not by font.\r\n\r\n---\r\n\r\n### 5b. Mismatched Personality — Comic Sans Meets Times New Roman\r\n\r\n**BAD:**\r\n```xml\r\n \r\n \r\n```\r\n\r\n**GOOD: Fonts with compatible character**\r\n```xml\r\n \r\n \r\n```\r\n**Why better:** Paired fonts should share a similar level of formality and geometric character. Comic Sans is playful/informal; Times New Roman is formal/traditional. They clash.\r\n\r\n---\r\n\r\n### 5c. Everything Bold — Nothing Stands Out\r\n\r\n**BAD: Bold on body, headings, captions, everything**\r\n```xml\r\n \r\n \r\n \r\n```\r\n\r\n**GOOD: Bold reserved for headings and key terms only**\r\n```xml\r\n \r\n \r\n \r\n \r\n \r\n```\r\n**Why better:** When everything is emphasized, nothing is emphasized. Bold should be a signal, not a default.\r\n\r\n---\r\n\r\n## 6. Color Abuse\r\n\r\n### 6a. Rainbow Headings\r\n\r\n**BAD: Each heading level a different bright color**\r\n```xml\r\n \r\n \r\n \r\n```\r\n\r\n**GOOD: Single accent color for headings, black or dark gray for body**\r\n```xml\r\n\r\n \r\n \r\n \r\n\r\n\r\n```\r\n**Why better:** A single accent color establishes brand consistency. Multiple bright colors compete for attention and look unprofessional.\r\n\r\n---\r\n\r\n### 6b. Low Contrast — Light Gray on White\r\n\r\n**BAD: #CCCCCC text on white background**\r\n```xml\r\n\r\n\r\n```\r\n\r\n**GOOD: #333333 text on white**\r\n```xml\r\n\r\n\r\n```\r\n**Why better:** Sufficient contrast is not just an accessibility requirement; it makes text physically easier to read for everyone, especially in printed documents.\r\n\r\n---\r\n\r\n### 6c. Bright Body Text\r\n\r\n**BAD: Body text in a saturated color**\r\n```xml\r\n \r\n```\r\n\r\n**GOOD: Color reserved for headings and inline accents only**\r\n```xml\r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** Colored body text causes eye fatigue over long reading. Reserve color for elements that need to attract attention (headings, links, warnings).\r\n\r\n---\r\n\r\n## 7. List Formatting Issues\r\n\r\n### 7a. Bullet at the Margin — No Indent\r\n\r\n**BAD: List items start at the left margin**\r\n```\r\n┌──────────────────────────────────┐\r\n│Here is a paragraph of text. │\r\n│• First item │ ← Bullet at margin, no indent\r\n│• Second item │\r\n│• Third item │\r\n│Next paragraph continues here. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n\r\n```\r\n\r\n**GOOD: 0.25in left indent with hanging indent for the bullet**\r\n```\r\n┌──────────────────────────────────┐\r\n│Here is a paragraph of text. │\r\n│ • First item │ ← Indented, clearly a list\r\n│ • Second item │\r\n│ • Third item │\r\n│Next paragraph continues here. │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\nFor nested lists, increment by 360 twips per level:\r\n```xml\r\n\r\n \r\n\r\n \r\n```\r\n**Why better:** Indentation visually separates lists from body text and makes nesting levels clear.\r\n\r\n---\r\n\r\n### 7b. List Items with Full Paragraph Spacing\r\n\r\n**BAD: List items have the same 8-10pt spacing as body paragraphs**\r\n```\r\n┌──────────────────────────────────┐\r\n│ • First item │\r\n│ │ ← 10pt gap — looks like separate\r\n│ • Second item │ paragraphs, not a list\r\n│ │\r\n│ • Third item │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n \r\n```\r\n\r\n**GOOD: Tight spacing between list items (2-4pt)**\r\n```\r\n┌──────────────────────────────────┐\r\n│ • First item │\r\n│ • Second item │ ← 2pt gap — cohesive list\r\n│ • Third item │\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n \r\n\r\n\r\n```\r\n**Why better:** Tight spacing groups list items as a single unit, matching how readers expect a list to behave.\r\n\r\n---\r\n\r\n## 8. Header/Footer Problems\r\n\r\n### 8a. Header Text Too Large — Competes with Body\r\n\r\n**BAD: Header in 12pt, same as body**\r\n```\r\n┌──────────────────────────────────┐\r\n│ Quarterly Report - Q3 2025 │ ← 12pt header, same as body\r\n│──────────────────────────────────│\r\n│ Introduction │\r\n│ This is the body text... │ ← 12pt body — header distracts\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n \r\n```\r\n\r\n**GOOD: Header in 9pt, gray color, subtle**\r\n```\r\n┌──────────────────────────────────┐\r\n│ Quarterly Report - Q3 2025 │ ← 9pt, gray — present but quiet\r\n│──────────────────────────────────│\r\n│ Introduction │\r\n│ This is the body text... │ ← Body stands out as primary\r\n└──────────────────────────────────┘\r\n```\r\n```xml\r\n\r\n\r\n \r\n \r\n\r\n\r\n \r\n \r\n \r\n\r\n```\r\n**Why better:** Headers are reference information, not primary content. They should be legible but visually subordinate.\r\n\r\n---\r\n\r\n### 8b. No Page Numbers on a Long Document\r\n\r\n**BAD: 20-page document with no page numbers**\r\n```xml\r\n\r\n```\r\n\r\n**GOOD: Page numbers in footer, right-aligned or centered**\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n PAGE \r\n \r\n \r\n \r\n \r\n \r\n 1\r\n \r\n \r\n \r\n \r\n\r\n```\r\n**Why better:** Page numbers are essential for navigation in any document over ~3 pages. Readers need to reference specific pages, and printed documents need an ordering mechanism.\r\n\r\n---\r\n\r\n## 9. CJK-Specific Mistakes\r\n\r\n### 9a. Using Italic for Chinese Emphasis\r\n\r\n**BAD: Italic applied to Chinese text**\r\n```xml\r\n\r\n \r\n \r\n \r\n\r\n```\r\nCJK glyphs have no true italic form. The renderer applies a synthetic slant that looks broken and ugly — characters appear to lean awkwardly.\r\n\r\n**GOOD: Use bold or emphasis dots (着重号) for Chinese emphasis**\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n```\r\n**Why better:** Chinese typography has its own emphasis traditions. Bold and emphasis dots are native CJK conventions; italic is a Latin-script concept that does not translate.\r\n\r\n---\r\n\r\n### 9b. Latin Font for Chinese Characters\r\n\r\n**BAD: Only ASCII font set, no EastAsia font specified**\r\n```xml\r\n\r\n \r\n \r\n\r\n\r\n```\r\n\r\n**GOOD: Explicit EastAsia font alongside ASCII font**\r\n```xml\r\n\r\n \r\n \r\n\r\n```\r\nFor formal/academic Chinese documents:\r\n```xml\r\n\r\n \r\n \r\n\r\n```\r\n**Why better:** Setting `w:eastAsia` ensures Chinese characters render in a font designed for CJK glyphs, with correct stroke widths, spacing, and metrics.\r\n\r\n---\r\n\r\n### 9c. English Line Spacing for Dense CJK Text\r\n\r\n**BAD: 1.15x line spacing for Chinese body text**\r\n```xml\r\n \r\n```\r\nCJK characters are taller and denser than Latin letters. At 1.15x, lines of Chinese text feel cramped and hard to read.\r\n\r\n**GOOD: 1.5x line spacing or fixed 28pt for CJK body at 12pt (小四)**\r\n```xml\r\n\r\n \r\n\r\n\r\n \r\n```\r\nFor 公文 (government documents) at 三号/16pt body:\r\n```xml\r\n \r\n```\r\n**Why better:** CJK characters occupy a full em square with no ascenders/descenders providing natural gaps. Extra line spacing compensates, improving readability of dense text blocks.\r\n\r\n---\r\n\r\n## 10. Overall Document Feel\r\n\r\n### Student Homework vs Professional Document\r\n\r\n**BAD: \"Student homework\" — every setting is Word's default, no intentional choices**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n\r\n**GOOD: Intentional design at every level**\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n\r\n\r\n```\r\n**Why better:** Professional documents result from deliberate, consistent choices across all design dimensions. Each element reinforces the same visual language. The reader may not consciously notice good typography, but they feel the difference in credibility and readability.\r\n\r\n---\r\n\r\n## Quick Reference: Safe Defaults\r\n\r\nA cheat sheet of values that produce a professional result for most Western business documents:\r\n\r\n| Element | Value | OpenXML |\r\n|---------|-------|---------|\r\n| Body font | Calibri 11pt | `w:sz=\"22\"` |\r\n| H1 | Calibri Light 20pt | `w:sz=\"40\"` |\r\n| H2 | Calibri Light 16pt | `w:sz=\"32\"` |\r\n| H3 | Calibri 13pt bold | `w:sz=\"26\"`, `w:b` |\r\n| Body color | #333333 | `w:color=\"333333\"` |\r\n| Heading color | #1F4E79 | `w:color=\"1F4E79\"` |\r\n| Line spacing | 1.15x | `w:line=\"276\" w:lineRule=\"auto\"` |\r\n| Para spacing after | 8pt | `w:after=\"160\"` |\r\n| H1 spacing | 24pt before, 10pt after | `w:before=\"480\" w:after=\"200\"` |\r\n| H2 spacing | 16pt before, 6pt after | `w:before=\"320\" w:after=\"120\"` |\r\n| Margins | 1in all around | `w:pgMar` all `\"1440\"` |\r\n| Table cell padding | 0.08in / 0.12in | `w:w=\"115\"` / `w:w=\"173\"` |\r\n| Header/footer size | 9pt gray | `w:sz=\"18\" w:color=\"808080\"` |\r\n| List indent | 0.25in per level | `w:left=\"360\" w:hanging=\"360\"` |\r\n| List item spacing | 2pt after | `w:after=\"40\"` |\r\n\r\nFor CJK documents, adjust: body font to SimSun/YaHei, line spacing to 1.5x (`w:line=\"360\"`), and set `w:eastAsia` on all `w:rFonts`.\n\nFile v1.0.0:references/design_principles.md\n\n# Design Principles for Document Typography\r\n\r\nWHY certain typographic choices look good -- the perceptual and psychological\r\nreasons behind professional document design. Use this to make judgment calls\r\nwhen exact specs are not provided.\r\n\r\n## Table of Contents\r\n\r\n1. [White Space & Breathing Room](#1-white-space--breathing-room)\r\n2. [Contrast & Scale](#2-contrast--scale)\r\n3. [Proximity & Grouping](#3-proximity--grouping)\r\n4. [Alignment & Grid](#4-alignment--grid)\r\n5. [Repetition & Consistency](#5-repetition--consistency)\r\n6. [Visual Hierarchy & Flow](#6-visual-hierarchy--flow)\r\n\r\n---\r\n\r\n## 1. White Space & Breathing Room\r\n\r\n### Why It Works\r\n\r\nThe human eye does not read continuously. It jumps in saccades, fixating on\r\nsmall clusters of words. White space provides landing zones for these fixations\r\nand gives the reader's peripheral vision a \"frame\" that makes each text block\r\nfeel manageable. When a page is packed to the edges, every glance returns more\r\ntext than working memory can buffer, triggering fatigue and avoidance.\r\n\r\nResearch on content density consistently shows:\r\n\r\n- **60-70% content coverage** feels comfortable and professional.\r\n- **80%+** starts to feel dense and bureaucratic.\r\n- **90%+** feels oppressive -- the reader unconsciously rushes or skips.\r\n- **Below 50%** feels wasteful or pretentious (unless intentional, like poetry).\r\n\r\nWider margins also carry cultural signals. Academic and luxury documents use\r\ngenerous margins (1.25-1.5 inches). Internal memos and drafts use narrower\r\nmargins (0.75-1.0 inches). The margin width tells the reader how much care\r\nwent into the document before they read a single word.\r\n\r\nLine spacing has a direct physiological basis: the eye must track back to the\r\nstart of the next line after each line break. If lines are too close, the eye\r\n\"slips\" to the wrong line. If too far apart, the eye loses its sense of\r\ncontinuity. The sweet spot is 120-145% of the font size.\r\n\r\n**Rule of thumb: when in doubt, add more space, not less.**\r\n\r\n### Good Example\r\n\r\n```\r\nMargins: 1 inch (1440 twips) all sides for business documents.\r\nLine spacing: 1.15 (276 twips at 240 twips-per-line = 115%).\r\nParagraph spacing after: 8pt (160 twips) between body paragraphs.\r\n```\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n \r\n\r\n```\r\n\r\nThis produces a page where content occupies roughly 65% of the area. The\r\nreader sees clear top/bottom breathing room, and paragraphs are distinct\r\nwithout feeling disconnected.\r\n\r\n```\r\n Page layout (good):\r\n +----------------------------------+\r\n | 1\" margin |\r\n | +------------------------+ |\r\n | | Heading | |\r\n | | | |\r\n | | Body text here with | |\r\n | | comfortable spacing | |\r\n | | between lines. | |\r\n | | | | <- visible gap between paragraphs\r\n | | Another paragraph of | |\r\n | | body text follows. | |\r\n | | | |\r\n | +------------------------+ |\r\n | 1\" margin |\r\n +----------------------------------+\r\n```\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n\r\n\r\n\r\n \r\n\r\n```\r\n\r\nThis fills ~85% of the page. Text runs edge-to-edge with no visual rest stops.\r\nThe reader sees a wall of text.\r\n\r\n```\r\n Page layout (bad):\r\n +----------------------------------+\r\n | Heading |\r\n | Body text crammed right up to |\r\n | the margins with no spacing |\r\n | between lines or paragraphs. |\r\n | Another paragraph starts here |\r\n | and the reader cannot tell where |\r\n | one idea ends and another begins |\r\n | because everything blurs into a |\r\n | single dense block of text. |\r\n +----------------------------------+\r\n```\r\n\r\n### Quick Test\r\n\r\n1. Zoom out to 50% in your document viewer. If you cannot see clear \"channels\"\r\n of white between text blocks, the spacing is too tight.\r\n2. Print a test page. Hold it at arm's length. The text area should look like\r\n a rectangle floating in white, not filling the page.\r\n3. Check: is the line spacing value at least 264 (`w:line` for 1.1x) for body\r\n text? If it is 240 (single), it is too tight for anything over 10pt.\r\n\r\n---\r\n\r\n## 2. Contrast & Scale\r\n\r\n### Why It Works\r\n\r\nThe brain processes visual hierarchy through relative difference, not absolute\r\nsize. A 20pt heading above 11pt body text creates a clear \"this is important\"\r\nsignal. But if every heading is 20pt and every sub-heading is 19pt, the brain\r\ncannot distinguish them -- they merge into the same level.\r\n\r\nThe key insight is **modular scale**: font sizes that grow by a consistent\r\nratio. This mirrors natural proportions and feels harmonious for the same\r\nreason musical intervals do.\r\n\r\nCommon scales and their character:\r\n\r\n| Ratio | Name | Character | Example progression (from 11pt) |\r\n|-------|----------------|---------------------------------|---------------------------------|\r\n| 1.200 | Minor third | Subtle, refined | 11 → 13.2 → 15.8 → 19.0 |\r\n| 1.250 | Major third | Balanced, professional | 11 → 13.75 → 17.2 → 21.5 |\r\n| 1.333 | Perfect fourth | Strong, authoritative | 11 → 14.7 → 19.5 → 26.0 |\r\n| 1.414 | Augmented 4th | Dramatic, presentation-style | 11 → 15.6 → 22.0 → 31.1 |\r\n\r\nFor most business documents, 1.25 (major third) works best:\r\n\r\n```\r\nBody = 11pt (w:sz=\"22\")\r\nH3 = 13pt (w:sz=\"26\") -- 11 * 1.25 ≈ 13.75, round to 13\r\nH2 = 16pt (w:sz=\"32\") -- 13 * 1.25 ≈ 16.25, round to 16\r\nH1 = 20pt (w:sz=\"40\") -- 16 * 1.25 = 20\r\n```\r\n\r\nBeyond size, **weight contrast** creates hierarchy without consuming vertical\r\nspace. Regular (400) vs Bold (700) is visible at any size. Semi-bold (600) vs\r\nRegular is subtle and best avoided unless you also vary size or color.\r\n\r\n**Color contrast** adds a third dimension. Dark blue headings (#1F3864) against\r\nsofter dark gray body text (#333333) signals \"heading\" without needing a huge\r\nsize jump. Pure black (#000000) body text is harsher than necessary on white\r\nbackgrounds -- #333333 or #2D2D2D reduces glare without losing legibility.\r\n\r\n### Good Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\n```\r\n Visual hierarchy (good):\r\n\r\n [████████████████████] <- H1: 20pt bold navy (clearly dominant)\r\n (generous space)\r\n [██████████████] <- H2: 16pt bold navy (distinct step down)\r\n (moderate space)\r\n [████████████] <- H3: 13pt bold navy (smaller but still bold)\r\n [░░░░░░░░░░░░░░░░░░░░░░] <- Body: 11pt regular gray\r\n [░░░░░░░░░░░░░░░░░░░░░░]\r\n [░░░░░░░░░░░░░░░░░░░░░░]\r\n```\r\n\r\nEach level is visually distinct from its neighbors. You can identify the\r\nhierarchy even in peripheral vision.\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\nProblems:\r\n- H3 (12pt bold) and body (12pt regular) differ only by weight -- too subtle.\r\n- H1 (14pt) to H2 (13pt) is a 1pt step -- invisible at reading distance.\r\n- Everything is pure black so color provides no differentiating signal.\r\n- The ratio between levels is ~1.07, far too flat.\r\n\r\n### Quick Test\r\n\r\n1. **The squint test**: blur your eyes or step back from the screen. Can you\r\n count the number of heading levels? If two levels merge, their contrast\r\n is insufficient.\r\n2. **Ratio check**: divide each heading size by the next smaller size. If any\r\n ratio is below 1.15, the levels will look too similar.\r\n3. **Color check**: do headings look distinct from body text when you glance\r\n at the page? If everything is the same color, you are relying solely on\r\n size/weight, which limits your hierarchy to ~3 effective levels.\r\n\r\n---\r\n\r\n## 3. Proximity & Grouping\r\n\r\n### Why It Works\r\n\r\nThe Gestalt principle of proximity: items that are close together are perceived\r\nas belonging to the same group. In document typography, this means a heading\r\nmust be **closer to the content it introduces** than to the content above it.\r\n\r\nIf a heading sits equidistant between two paragraphs, it looks orphaned -- the\r\nreader's eye does not know if it belongs to the text above or below. The fix\r\nis asymmetric spacing: **large space before the heading, small space after**.\r\n\r\nThe recommended ratio is 2:1 or 3:1 (space-before : space-after).\r\n\r\nThis same principle applies to:\r\n- **List items**: spacing between items should be less than spacing between\r\n paragraphs. Items in a list are a group and should visually cluster.\r\n- **Captions**: a figure caption should be close to its figure, not floating\r\n in the middle between the figure and the next paragraph.\r\n- **Table titles**: the title sits close above the table, with more space\r\n separating the title from preceding text.\r\n\r\n### Good Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\n```\r\n Proximity (good):\r\n\r\n ...end of previous section text.\r\n <- 18pt gap (w:before=\"360\")\r\n ## Section Heading\r\n <- 6pt gap (w:after=\"120\")\r\n First paragraph of new section\r\n continues here with content.\r\n <- 8pt gap (w:after=\"160\")\r\n Second paragraph follows.\r\n\r\n The heading clearly \"belongs to\" the text below it.\r\n```\r\n\r\n```\r\n List grouping (good):\r\n\r\n Consider these factors:\r\n - First item <- 2pt gap between items\r\n - Second item <- items cluster as a group\r\n - Third item\r\n <- 8pt gap after list\r\n The next paragraph starts here.\r\n```\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\n```\r\n Proximity (bad):\r\n\r\n ...end of previous section text.\r\n <- 12pt gap\r\n ## Section Heading\r\n <- 12pt gap (same!)\r\n First paragraph of new section.\r\n\r\n The heading floats between sections. It is unclear what it belongs to.\r\n```\r\n\r\n```\r\n List grouping (bad):\r\n\r\n Consider these factors:\r\n <- 10pt gap\r\n - First item\r\n <- 10pt gap (same as paragraphs)\r\n - Second item\r\n <- 10pt gap\r\n - Third item\r\n <- 10pt gap\r\n Next paragraph.\r\n\r\n The list does not feel like a group. Each item looks like a\r\n separate paragraph that happens to have a bullet.\r\n```\r\n\r\n### Quick Test\r\n\r\n1. **Cover test**: cover the heading text. Looking only at the whitespace,\r\n can you tell which block of text the heading belongs to? If the gaps above\r\n and below are equal, the answer is \"no.\"\r\n2. **Number check**: `w:before` on headings should be at least 2x `w:after`.\r\n Common good values: before=360 / after=120, or before=240 / after=80.\r\n3. **List check**: `w:after` on list items should be less than half of\r\n `w:after` on body paragraphs. If body uses 160, list items should use\r\n 40-60.\r\n\r\n---\r\n\r\n## 4. Alignment & Grid\r\n\r\n### Why It Works\r\n\r\nAlignment creates invisible lines that the eye follows down the page. When\r\nelements share the same left edge, the reader perceives order and intention.\r\nWhen elements are slightly misaligned (off by a few twips), the page looks\r\nsloppy even if the reader cannot consciously identify why.\r\n\r\n**Left-align vs Justify:**\r\n\r\n- **Left-aligned** (ragged right) is best for English and other Latin-script\r\n languages. The uneven right edge actually helps reading because each line\r\n has a unique silhouette, making it easier for the eye to find the next line.\r\n Justified text forces uneven word spacing that creates distracting \"rivers\"\r\n of white running vertically through paragraphs.\r\n\r\n- **Justified** is best for CJK text. Chinese, Japanese, and Korean characters\r\n are monospaced by design -- each occupies the same cell in an invisible grid.\r\n Justification preserves this grid perfectly. Ragged right in CJK text breaks\r\n the grid and looks untidy.\r\n\r\n**Indentation rule:** Use first-line indent OR paragraph spacing to separate\r\nparagraphs -- never both. They serve the same purpose (marking paragraph\r\nboundaries). Using both wastes space and creates visual stutter.\r\n\r\n- Western convention: paragraph spacing (no indent) is more modern.\r\n- CJK convention: first-line indent of 2 characters is standard.\r\n- Academic convention: first-line indent of 0.5 inch is traditional.\r\n\r\n### Good Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n```\r\n English paragraph separation (good -- spacing, no indent):\r\n\r\n This is the first paragraph with some text\r\n that wraps to a second line naturally.\r\n\r\n This is the second paragraph. The gap above\r\n clearly marks the boundary.\r\n\r\n\r\n CJK paragraph separation (good -- indent, no spacing):\r\n\r\n 第一段正文内容从这里开始，使用两个字符\r\n 的首行缩进来标记段落边界。\r\n 第二段紧跟其后，没有段间距，但首行缩进\r\n 清晰地标识了新段落的开始。\r\n```\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n\r\n```\r\n\r\nProblems:\r\n- Justified English text with narrow columns creates uneven word gaps.\r\n- Using both first-line indent AND paragraph spacing is redundant.\r\n- Left-aligned CJK breaks the character grid that CJK readers expect.\r\n- CJK with spacing-based separation looks like translated western layout.\r\n\r\n### Quick Test\r\n\r\n1. **River test**: in justified English text, squint and look for vertical\r\n white streaks running through the paragraph. If you see them, switch to\r\n left-align or increase the column width.\r\n2. **Double signal check**: does the document use BOTH first-line indent AND\r\n paragraph spacing? If yes, remove one. Choose indent for CJK/academic,\r\n spacing for modern western.\r\n3. **Tab alignment**: if you use tabs for columns, do all tab stops across\r\n the document use the same positions? Inconsistent tab stops create jagged\r\n invisible grid lines.\r\n\r\n---\r\n\r\n## 5. Repetition & Consistency\r\n\r\n### Why It Works\r\n\r\nConsistency is a trust signal. When a reader sees that every H2 looks the same,\r\nevery table follows the same pattern, and every page number sits in the same\r\nspot, they unconsciously trust that the document was crafted with care. A single\r\ninconsistency -- one H2 that is 15pt instead of 14pt, one table with different\r\nborders -- breaks that trust and makes the reader question the content.\r\n\r\nConsistency also reduces cognitive load. Once the reader learns \"bold dark blue\r\n= section heading,\" they stop spending mental effort on identifying structure\r\nand focus entirely on content. Every inconsistency forces them to re-evaluate:\r\n\"Is this a different kind of heading, or did someone just forget to apply the\r\nstyle?\"\r\n\r\nThe implementation rule is simple: **use named styles, not direct formatting.**\r\nIf you define Heading2 as a style and apply it everywhere, consistency is\r\nautomatic. If you manually set font size, bold, and color on each heading\r\nindividually, inconsistency is inevitable.\r\n\r\n### Good Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n Market Analysis\r\n\r\n```\r\n\r\nWhen using a table style, define it once and reference it for every table:\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n\r\n```\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n Market Analysis\r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n Financial Overview\r\n \r\n\r\n```\r\n\r\nProblems:\r\n- No style references -- everything is direct formatting.\r\n- Second H2 has different size (30 vs 32), color, and spacing.\r\n- If there are 20 headings, each could drift slightly differently.\r\n- Changing the design later means editing every heading individually.\r\n\r\n### Quick Test\r\n\r\n1. **Style audit**: does every paragraph reference a `w:pStyle`? If you find\r\n paragraphs with only direct formatting and no style, that is a consistency\r\n risk.\r\n2. **Search for variance**: search the XML for all `w:sz` values used with\r\n `w:b` (bold). If you find three different sizes for what should be the same\r\n heading level, there is an inconsistency.\r\n3. **Table check**: do all tables in the document reference the same\r\n `w:tblStyle`? If some tables have manual border definitions while others\r\n use a style, the document will look patchy.\r\n4. **Page numbers**: check that header/footer content is defined in the\r\n default section properties and inherited by all sections, not redefined\r\n inconsistently in each section.\r\n\r\n---\r\n\r\n## 6. Visual Hierarchy & Flow\r\n\r\n### Why It Works\r\n\r\nA well-designed document guides the reader's eye in a predictable path:\r\ntitle at the top, subtitle below it, section headings as signposts, body text\r\nas the main content, footnotes and captions as supporting details. This flow\r\nmirrors reading priority -- the most important information is the most visually\r\nprominent.\r\n\r\nEach level in the hierarchy must be **distinguishable from its adjacent\r\nlevels**. It is not enough for H1 to differ from body text; H1 must also\r\nclearly differ from H2, and H2 from H3. If any two adjacent levels are too\r\nsimilar, the hierarchy collapses at that point.\r\n\r\nEffective hierarchy uses **multiple simultaneous signals**:\r\n\r\n| Level | Size | Weight | Color | Spacing above |\r\n|----------|-------|---------|---------|---------------|\r\n| Title | 26pt | Bold | #1F3864 | 0 (top) |\r\n| Subtitle | 15pt | Regular | #4472C4 | 4pt |\r\n| H1 | 20pt | Bold | #1F3864 | 24pt |\r\n| H2 | 16pt | Bold | #1F3864 | 18pt |\r\n| H3 | 13pt | Bold | #1F3864 | 12pt |\r\n| Body | 11pt | Regular | #333333 | 0pt |\r\n| Caption | 9pt | Italic | #666666 | 4pt |\r\n| Footnote | 9pt | Regular | #666666 | 0pt |\r\n\r\nNotice how each level differs from its neighbors on at least two dimensions\r\n(size + weight, or size + color, or weight + style). Single-dimension\r\ndifferences are fragile and can be missed.\r\n\r\n**Section breaks** create rhythm in long documents. A page break before each\r\nmajor section (H1) gives the reader a mental reset. Within sections, consistent\r\nheading + body patterns create a predictable cadence that makes long documents\r\nless intimidating.\r\n\r\n### Good Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n```\r\n Visual flow (good):\r\n\r\n +----------------------------------+\r\n | |\r\n | ANNUAL REPORT 2025 | <- Title: 26pt bold navy centered\r\n | Acme Corporation | <- Subtitle: 15pt regular blue\r\n | |\r\n | |\r\n +----------------------------------+\r\n\r\n +----------------------------------+\r\n | |\r\n | 1. Executive Summary | <- H1: 20pt bold navy (page break)\r\n | |\r\n | Body text introducing the | <- Body: 11pt regular gray\r\n | main findings of the year. |\r\n | |\r\n | 1.1 Revenue Highlights | <- H2: 16pt bold navy\r\n | |\r\n | Revenue grew by 23% year | <- Body\r\n | over year, driven by... |\r\n | |\r\n | Figure 1: Revenue Growth | <- Caption: 9pt italic gray\r\n | |\r\n +----------------------------------+\r\n\r\n Each level is immediately identifiable. The eye flows naturally\r\n from title -> heading -> body -> caption.\r\n```\r\n\r\n### Bad Example\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n\r\n\r\n\r\n\r\n```\r\n\r\nProblems:\r\n- H1 at 14pt is too close to body at 11pt (ratio 1.27 -- acceptable in\r\n isolation but with black color matching body, the hierarchy is weak).\r\n- Caption is indistinguishable from body text.\r\n- No page breaks means major sections bleed into each other with no\r\n visual rhythm.\r\n- Everything is black, so color provides zero hierarchy signal.\r\n\r\n### Quick Test\r\n\r\n1. **The squint test**: blur your eyes while looking at a full page. You\r\n should see 3-4 distinct \"weight levels\" of gray. If the page looks like\r\n one uniform shade, the hierarchy is too flat.\r\n2. **The scan test**: flip through pages quickly. Can you identify section\r\n boundaries in under one second per page? If yes, the visual hierarchy is\r\n working. If pages blur together, you need stronger differentiation at H1.\r\n3. **Adjacent level test**: for each heading level, check that it differs\r\n from the next level on at least 2 of: size, weight, color, style (italic).\r\n Single-dimension differences get lost.\r\n4. **Rhythm test**: in a document over 10 pages, do major sections (H1) start\r\n on new pages? If not, long documents will feel like an undifferentiated\r\n stream. Add `w:pageBreakBefore` to Heading1.\r\n\r\n---\r\n\r\n## Summary: Decision Checklist\r\n\r\nWhen you are unsure about a typographic choice, run through these checks:\r\n\r\n| Principle | Question | If No... |\r\n|-----------|----------|----------|\r\n| White Space | Does the page have at least 30% white space? | Increase margins or spacing |\r\n| Contrast | Can I count heading levels by squinting? | Increase size ratios (target 1.25x) |\r\n| Proximity | Does each heading clearly belong to text below it? | Make space-before > space-after (2:1) |\r\n| Alignment | Is English left-aligned and CJK justified? | Switch alignment mode |\r\n| Repetition | Do all same-level elements use the same style? | Replace direct formatting with styles |\r\n| Hierarchy | Can I see the document structure at arm's length? | Add more differentiation signals |\r\n\r\n**When two principles conflict, prioritize in this order:**\r\n\r\n1. **Readability** (white space, line spacing) -- always wins\r\n2. **Hierarchy** (contrast, scale) -- readers must find what they need\r\n3. **Consistency** (repetition) -- builds trust\r\n4. **Aesthetics** (alignment, grouping) -- the finishing touch\n\nFile v1.0.0:references/openxml_element_order.md\n\n# OpenXML Child Element Ordering Rules\r\n\r\nElement ordering in OpenXML is defined by the XSD schema. Incorrect ordering produces invalid documents that Word may refuse to open or silently repair (potentially losing data).\r\n\r\n> **Key rule**: Properties elements (`*Pr`) must always be the **first child** of their parent.\r\n\r\n---\r\n\r\n## w:document\r\n\r\n```\r\nChildren in order:\r\n1. w:background [0..1] — page background color/fill\r\n2. w:body [0..1] — document content container\r\n```\r\n\r\n---\r\n\r\n## w:body\r\n\r\n```\r\nChildren in order (repeating group):\r\n1. w:p [0..*] — paragraph\r\n2. w:tbl [0..*] — table\r\n3. w:sdt [0..*] — structured document tag (content control)\r\n4. w:sectPr [0..1] — LAST child: final section properties\r\n```\r\n\r\nNote: `w:p`, `w:tbl`, and `w:sdt` are interleaved in document order. The only strict rule is that `w:sectPr` must be the **last child** of `w:body`.\r\n\r\n---\r\n\r\n## w:p (Paragraph)\r\n\r\n```\r\nChildren in order:\r\n1. w:pPr [0..1] — paragraph properties (MUST be first)\r\n\r\nThen any mix of (interleaved in document order):\r\n- w:r [0..*] — run\r\n- w:hyperlink [0..*] — hyperlink wrapper\r\n- w:ins [0..*] — tracked insertion\r\n- w:del [0..*] — tracked deletion\r\n- w:bookmarkStart [0..*] — bookmark anchor start\r\n- w:bookmarkEnd [0..*] — bookmark anchor end\r\n- w:commentRangeStart [0..*] — comment range start\r\n- w:commentRangeEnd [0..*] — comment range end\r\n- w:proofErr [0..*] — proofing error marker\r\n- w:fldSimple [0..*] — simple field\r\n- w:sdt [0..*] — inline content control\r\n- w:smartTag [0..*] — smart tag\r\n```\r\n\r\n**Practical note**: After `w:pPr`, the remaining children appear in document reading order. Runs, hyperlinks, bookmarks, and comment ranges intermix freely based on their position in the text.\r\n\r\n---\r\n\r\n## w:pPr (Paragraph Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:pStyle [0..1] — paragraph style reference\r\n2. w:keepNext [0..1] — keep with next paragraph\r\n3. w:keepLines [0..1] — keep lines together\r\n4. w:pageBreakBefore [0..1] — page break before paragraph\r\n5. w:framePr [0..1] — text frame properties\r\n6. w:widowControl [0..1] — widow/orphan control\r\n7. w:numPr [0..1] — numbering properties\r\n8. w:suppressLineNumbers [0..1]\r\n9. w:pBdr [0..1] — paragraph borders\r\n10. w:shd [0..1] — shading\r\n11. w:tabs [0..1] — tab stops\r\n12. w:suppressAutoHyphens [0..1]\r\n13. w:kinsoku [0..1] — CJK kinsoku settings\r\n14. w:wordWrap [0..1]\r\n15. w:overflowPunct [0..1]\r\n16. w:topLinePunct [0..1]\r\n17. w:autoSpaceDE [0..1]\r\n18. w:autoSpaceDN [0..1]\r\n19. w:bidi [0..1] — right-to-left paragraph\r\n20. w:adjustRightInd [0..1]\r\n21. w:snapToGrid [0..1]\r\n22. w:spacing [0..1] — line and paragraph spacing\r\n23. w:ind [0..1] — indentation\r\n24. w:contextualSpacing [0..1]\r\n25. w:mirrorIndents [0..1]\r\n26. w:suppressOverlap [0..1]\r\n27. w:jc [0..1] — justification (left/center/right/both)\r\n28. w:textDirection [0..1]\r\n29. w:textAlignment [0..1]\r\n30. w:outlineLvl [0..1] — outline level\r\n31. w:divId [0..1]\r\n32. w:rPr [0..1] — run properties for paragraph mark\r\n33. w:sectPr [0..1] — section break (section ends at this paragraph)\r\n34. w:pPrChange [0..1] — tracked paragraph property change\r\n```\r\n\r\n---\r\n\r\n## w:r (Run)\r\n\r\n```\r\nChildren in order:\r\n1. w:rPr [0..1] — run properties (MUST be first)\r\n\r\nThen any of (one per run, typically):\r\n- w:t [0..*] — text content\r\n- w:br [0..*] — break (line, page, column)\r\n- w:tab [0..*] — tab character\r\n- w:cr [0..*] — carriage return\r\n- w:sym [0..*] — symbol character\r\n- w:drawing [0..*] — DrawingML object (images)\r\n- w:pict [0..*] — VML picture (legacy)\r\n- w:fldChar [0..*] — complex field character\r\n- w:instrText [0..*] — field instruction text\r\n- w:delText [0..*] — deleted text (inside w:del)\r\n- w:footnoteReference [0..*]\r\n- w:endnoteReference [0..*]\r\n- w:commentReference [0..*]\r\n- w:lastRenderedPageBreak [0..*]\r\n```\r\n\r\n---\r\n\r\n## w:rPr (Run Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:rStyle [0..1] — character style reference\r\n2. w:rFonts [0..1] — font specification\r\n3. w:b [0..1] — bold\r\n4. w:bCs [0..1] — complex script bold\r\n5. w:i [0..1] — italic\r\n6. w:iCs [0..1] — complex script italic\r\n7. w:caps [0..1] — all capitals\r\n8. w:smallCaps [0..1] — small capitals\r\n9. w:strike [0..1] — strikethrough\r\n10. w:dstrike [0..1] — double strikethrough\r\n11. w:outline [0..1]\r\n12. w:shadow [0..1]\r\n13. w:emboss [0..1]\r\n14. w:imprint [0..1]\r\n15. w:noProof [0..1] — suppress proofing\r\n16. w:snapToGrid [0..1]\r\n17. w:vanish [0..1] — hidden text\r\n18. w:color [0..1] — text color\r\n19. w:spacing [0..1] — character spacing\r\n20. w:w [0..1] — character width scaling\r\n21. w:kern [0..1] — font kerning\r\n22. w:position [0..1] — vertical position (raise/lower)\r\n23. w:sz [0..1] — font size (half-points)\r\n24. w:szCs [0..1] — complex script font size\r\n25. w:highlight [0..1] — text highlight color\r\n26. w:u [0..1] — underline\r\n27. w:effect [0..1] — text effect (animated)\r\n28. w:bdr [0..1] — run border\r\n29. w:shd [0..1] — run shading\r\n30. w:vertAlign [0..1] — superscript/subscript\r\n31. w:rtl [0..1] — right-to-left\r\n32. w:cs [0..1] — complex script\r\n33. w:lang [0..1] — language\r\n34. w:rPrChange [0..1] — tracked run property change\r\n```\r\n\r\n---\r\n\r\n## w:tbl (Table)\r\n\r\n```\r\nChildren in order:\r\n1. w:tblPr [1..1] — table properties (REQUIRED, must be first)\r\n2. w:tblGrid [1..1] — column width definitions (REQUIRED)\r\n3. w:tr [1..*] — table row(s)\r\n```\r\n\r\n---\r\n\r\n## w:tblPr (Table Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:tblStyle [0..1] — table style reference\r\n2. w:tblpPr [0..1] — table positioning\r\n3. w:tblOverlap [0..1]\r\n4. w:bidiVisual [0..1] — right-to-left table\r\n5. w:tblStyleRowBandSize [0..1]\r\n6. w:tblStyleColBandSize [0..1]\r\n7. w:tblW [0..1] — preferred table width\r\n8. w:jc [0..1] — table alignment\r\n9. w:tblCellSpacing [0..1]\r\n10. w:tblInd [0..1] — table indent from margin\r\n11. w:tblBorders [0..1] — table borders\r\n12. w:shd [0..1] — table shading\r\n13. w:tblLayout [0..1] — fixed or autofit\r\n14. w:tblCellMar [0..1] — default cell margins\r\n15. w:tblLook [0..1] — conditional formatting flags\r\n16. w:tblCaption [0..1] — accessibility caption\r\n17. w:tblDescription [0..1] — accessibility description\r\n18. w:tblPrChange [0..1] — tracked table property change\r\n```\r\n\r\n---\r\n\r\n## w:tr (Table Row)\r\n\r\n```\r\nChildren in order:\r\n1. w:trPr [0..1] — row properties (must be first)\r\n2. w:tc [1..*] — table cell(s)\r\n```\r\n\r\n---\r\n\r\n## w:trPr (Table Row Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:cnfStyle [0..1] — conditional formatting\r\n2. w:divId [0..1]\r\n3. w:gridBefore [0..1] — grid columns before first cell\r\n4. w:gridAfter [0..1] — grid columns after last cell\r\n5. w:wBefore [0..1]\r\n6. w:wAfter [0..1]\r\n7. w:cantSplit [0..1] — don't split row across pages\r\n8. w:trHeight [0..1] — row height\r\n9. w:tblHeader [0..1] — repeat as header row\r\n10. w:tblCellSpacing [0..1]\r\n11. w:jc [0..1] — row alignment\r\n12. w:hidden [0..1]\r\n13. w:ins [0..1] — tracked row insertion\r\n14. w:del [0..1] — tracked row deletion\r\n15. w:trPrChange [0..1] — tracked row property change\r\n```\r\n\r\n---\r\n\r\n## w:tc (Table Cell)\r\n\r\n```\r\nChildren in order:\r\n1. w:tcPr [0..1] — cell properties (must be first)\r\n2. w:p [1..*] — paragraph(s) — at least one required\r\n3. w:tbl [0..*] — nested table(s)\r\n```\r\n\r\n---\r\n\r\n## w:tcPr (Table Cell Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:cnfStyle [0..1]\r\n2. w:tcW [0..1] — cell width\r\n3. w:gridSpan [0..1] — horizontal merge (column span)\r\n4. w:hMerge [0..1] — legacy horizontal merge\r\n5. w:vMerge [0..1] — vertical merge\r\n6. w:tcBorders [0..1] — cell borders\r\n7. w:shd [0..1] — cell shading\r\n8. w:noWrap [0..1]\r\n9. w:tcMar [0..1] — cell margins\r\n10. w:textDirection [0..1]\r\n11. w:tcFitText [0..1]\r\n12. w:vAlign [0..1] — vertical alignment\r\n13. w:hideMark [0..1]\r\n14. w:tcPrChange [0..1] — tracked cell property change\r\n```\r\n\r\n---\r\n\r\n## w:sectPr (Section Properties)\r\n\r\n```\r\nChildren in order:\r\n1. w:headerReference [0..*] — header references (type: default/first/even)\r\n2. w:footerReference [0..*] — footer references\r\n3. w:endnotePr [0..1]\r\n4. w:footnotePr [0..1]\r\n5. w:type [0..1] — section break type (nextPage/continuous/evenPage/oddPage)\r\n6. w:pgSz [0..1] — page size\r\n7. w:pgMar [0..1] — page margins\r\n8. w:paperSrc [0..1]\r\n9. w:pgBorders [0..1] — page borders\r\n10. w:lnNumType [0..1] — line numbering\r\n11. w:pgNumType [0..1] — page numbering\r\n12. w:cols [0..1] — column definitions\r\n13. w:formProt [0..1]\r\n14. w:vAlign [0..1] — vertical alignment of page\r\n15. w:noEndnote [0..1]\r\n16. w:titlePg [0..1] — different first page header/footer\r\n17. w:textDirection [0..1]\r\n18. w:bidi [0..1]\r\n19. w:rtlGutter [0..1]\r\n20. w:docGrid [0..1] — document grid\r\n21. w:sectPrChange [0..1] — tracked section property change\r\n```\r\n\r\n---\r\n\r\n## w:hdr (Header) / w:ftr (Footer)\r\n\r\n```\r\nChildren (same structure as w:body content):\r\n1. w:p [0..*] — paragraph(s)\r\n2. w:tbl [0..*] — table(s)\r\n3. w:sdt [0..*] — content controls\r\n```\r\n\r\nHeaders and footers are essentially mini-documents. They follow the same content model as `w:body` but without a final `w:sectPr`.\n\nFile v1.0.0:references/openxml_encyclopedia_part1.md\n\n# OpenXML SDK 3.x Complete Reference Encyclopedia\r\n\r\n**Target:** DocumentFormat.OpenXml 3.x / .NET 8+ / C# 12\r\n**Last Updated:** 2026-03-22\r\n\r\nThis document serves as an exhaustive reference for building DOCX files with the OpenXML SDK. Every code block is ready to copy-paste.\r\n\r\n---\r\n\r\n## Namespace Aliases Used Throughout\r\n\r\n```csharp\r\nusing DocumentFormat.OpenXml;\r\nusing DocumentFormat.OpenXml.Packaging;\r\nusing DocumentFormat.OpenXml.Wordprocessing;\r\n```\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Document Creation Skeleton](#1-document-creation-skeleton)\r\n2. [Style System Deep Dive](#2-style-system-deep-dive)\r\n3. [Character Formatting (RunProperties)](#3-character-formatting-runproperties--exhaustive)\r\n4. [Paragraph Formatting (ParagraphProperties)](#4-paragraph-formatting-paragraphproperties--exhaustive)\r\n\r\n---\r\n\r\n## 1. Document Creation Skeleton\r\n\r\n### 1.1 Complete Flow: Create to Save\r\n\r\n```csharp\r\n// =============================================================================\r\n// DOCUMENT CREATION SKELETON\r\n// =============================================================================\r\n// This is the minimal complete flow for creating a valid DOCX from scratch.\r\n// Follow these steps in order: Create -> AddParts -> AddContent -> Save.\r\n//\r\n// Key insight: WordprocessingDocument.Create() adds MainDocumentPart automatically,\r\n// but all other parts (Styles, Settings, Numbering, Theme) must be added manually.\r\n\r\n// --- STEP 1: CREATE THE PACKAGE ---\r\n// The file path can be absolute or relative. WordprocessingDocumentType.Document\r\n// is the standard choice for .docx files (vs. Template, MacroEnabled, etc.)\r\nstring outputPath = \"C:\\\\Docs\\\\MyDocument.docx\";\r\n\r\nusing var doc = WordprocessingDocument.Create(\r\n outputPath, // File path\r\n WordprocessingDocumentType.Document, // Document type enum\r\n new DocumentOptions // Optional: AutoSave, etc.\r\n {\r\n AutoSave = false // true = flush changes automatically\r\n });\r\n\r\n// --- STEP 2: GET OR CREATE THE MAIN DOCUMENT PART ---\r\n// When you call Create(), MainDocumentPart is automatically created and linked.\r\n// You access it via .MainDocumentPart (not .AddMainDocumentPart, which would add\r\n// a SECOND main part — illegal). For a fresh document, just use .MainDocumentPart.\r\nvar mainPart = doc.MainDocumentPart!;\r\nvar body = mainPart.Document.Body!; // Body is created automatically with the part\r\n\r\n// --- STEP 3: ADD ADDITIONAL PARTS ---\r\n// These are OPTIONAL but recommended for a complete document:\r\n// - StyleDefinitionsPart: required for styles\r\n// - NumberingDefinitionsPart: required for bullets/numbers\r\n// - DocumentSettingsPart: zoom, proof state, tab stops, compatibility\r\n// - ThemePart: color/theme information\r\n// Parts are created fresh and linked via relationships.\r\n\r\n// Example: Add styles part (covered in Section 2)\r\nvar stylesPart = mainPart.AddNewPart();\r\nstylesPart.Styles = new Styles();\r\nstylesPart.Styles.Save();\r\n\r\n// Example: Add settings part (covered in 1.4)\r\nvar settingsPart = mainPart.AddNewPart();\r\nsettingsPart.Settings = new Settings();\r\nsettingsPart.Settings.Save();\r\n\r\n// --- STEP 4: ADD CONTENT TO BODY ---\r\n// Body accepts: Paragraph (w:p), Table (w:tbl), Structured Document Tag (w:sdt)\r\n// Content is added in document order (no need for explicit index).\r\n// IMPORTANT: SectionProperties (w:sectPr) MUST be the last child of body.\r\nbody.Append(new Paragraph(\r\n new Run(new Text(\"Hello, World!\"))));\r\n\r\n// --- STEP 5: SET SECTION PROPERTIES (PAGE LAYOUT) ---\r\n// sectPr defines page size, margins, headers/footers, columns, etc.\r\n// It must be the last child of body. If missing, Word uses defaults (Letter/A4, 1\" margins).\r\nvar sectPr = new SectionProperties();\r\n\r\n// Page Size: Width/Height in DXA (1 inch = 1440 DXA)\r\n// Letter: 12240 x 15840 DXA (8.5\" x 11\")\r\n// A4: 11906 x 16838 DXA (210mm x 297mm)\r\nsectPr.Append(new PageSize\r\n{\r\n Width = 12240u, // 8.5 inches\r\n Height = 15840u // 11 inches\r\n});\r\n\r\n// Page Margins: all four margins in DXA\r\n// Note: Top+Bottom margins + HeaderDistance = distance from page edge to text\r\nsectPr.Append(new PageMargin\r\n{\r\n Top = 1440, // 1 inch\r\n Bottom = 1440, // 1 inch\r\n Left = 1440u, // 1 inch (uint required)\r\n Right = 1440u, // 1 inch\r\n Header = 720u, // 0.5 inch from page edge to header\r\n Footer = 720u // 0.5 inch from page edge to footer\r\n});\r\n\r\n// Attach sectPr to body (must be last)\r\nbody.Append(sectPr);\r\n\r\n// --- STEP 6: SAVE ---\r\n// Because we use `using`, Dispose() is called automatically when the block exits.\r\n// Dispose() saves the file. If you forget `using`, call doc.Save() explicitly.\r\n```\r\n\r\n### 1.2 Opening an Existing Document\r\n\r\n```csharp\r\n// =============================================================================\r\n// OPENING EXISTING DOCUMENTS\r\n// =============================================================================\r\n// Open() has multiple overloads:\r\n// 1. Open(string path, bool isEditable, AutoSave)\r\n// 2. Open(Stream, bool isEditable, AutoSave)\r\n// 3. Open(string path, bool isEditable, OpenSettings)\r\n//\r\n// isEditable=true means open for read/write. false = read-only.\r\n// isEditable=false is faster (shared locks avoided) but throws if file is read-only.\r\n\r\n// --- OPEN FOR EDITING (READ/WRITE) ---\r\nstring inputPath = \"C:\\\\Docs\\\\Existing.docx\";\r\nusing var editDoc = WordprocessingDocument.Open(\r\n inputPath,\r\n isEditable: true, // Required for modification\r\n new OpenSettings\r\n {\r\n AutoSave = true // Automatically save on Dispose\r\n });\r\n\r\nvar body = editDoc.MainDocumentPart!.Document.Body!;\r\n// ... make changes ...\r\n// No explicit Save() needed if AutoSave = true\r\n\r\n// --- OPEN AS READ-ONLY (FASTER) ---\r\nusing var readOnlyDoc = WordprocessingDocument.Open(\r\n inputPath,\r\n isEditable: false, // Read-only mode\r\n new OpenSettings\r\n {\r\n // MarkupDeclarationProcess options\r\n });\r\n\r\n// --- OPEN FROM STREAM ---\r\nbyte[] fileBytes = File.ReadAllBytes(inputPath);\r\nusing var streamDoc = WordprocessingDocument.Open(\r\n new MemoryStream(fileBytes),\r\n isEditable: true,\r\n new OpenSettings { AutoSave = false });\r\n\r\n// After editing, you MUST copy the stream back to file if AutoSave=false:\r\n// streamDoc.MainDocumentPart.Document.Save();\r\n// File.WriteAllBytes(outputPath, streamStream.ToArray());\r\n\r\n// --- OPEN FROM HTTP RESPONSE (WEB SCENARIO) ---\r\nusing var httpClient = new HttpClient();\r\nvar response = await httpClient.GetAsync(\"https://example.com/document.docx\");\r\nusing var webStream = await response.Content.ReadAsStreamAsync();\r\nusing var webDoc = WordprocessingDocument.Open(webStream, isEditable: true);\r\n```\r\n\r\n### 1.3 Stream-Based Creation (MemoryStream for Web)\r\n\r\n```csharp\r\n// =============================================================================\r\n// STREAM-BASED DOCUMENT CREATION\r\n// =============================================================================\r\n// Use MemoryStream when you want to:\r\n// 1. Generate a document in memory before sending to a client\r\n// 2. Avoid touching the filesystem (ASP.NET Core scenarios)\r\n// 3. Return a document from an API endpoint\r\n//\r\n// CRITICAL: The stream MUST be seekable when you call .Open().\r\n// After WordprocessingDocument.Create(), the stream position is at the beginning.\r\n// If you write to the stream BEFORE creating the document, seek to 0 first.\r\n\r\n// --- CREATE IN MEMORY ---\r\nMemoryStream memStream = new MemoryStream();\r\n\r\n// Create directly on a stream (no file path involved)\r\nusing (var doc = WordprocessingDocument.Create(\r\n memStream,\r\n WordprocessingDocumentType.Document,\r\n new DocumentOptions { AutoSave = false }))\r\n{\r\n var mainPart = doc.MainDocumentPart!;\r\n mainPart.Document = new Document(new Body());\r\n mainPart.Document.Body!.Append(new Paragraph(\r\n new Run(new Text(\"Generated in memory\"))));\r\n mainPart.Document.Save(); // Save to the underlying stream\r\n}\r\n// At this point, memStream contains the complete DOCX\r\n\r\n// --- SEND TO HTTP RESPONSE (ASP.NET Core) ---\r\n// In an API controller:\r\n[HttpGet(\"download\")]\r\npublic async Task DownloadDocument()\r\n{\r\n var memStream = new MemoryStream();\r\n\r\n using (var doc = WordprocessingDocument.Create(\r\n memStream,\r\n WordprocessingDocumentType.Document))\r\n {\r\n var mainPart = doc.MainDocumentPart!;\r\n mainPart.Document = new Document(new Body());\r\n mainPart.Document.Body!.Append(new Paragraph(\r\n new Run(new Text(\"Download me!\"))));\r\n mainPart.Document.Save();\r\n }\r\n\r\n memStream.Position = 0; // IMPORTANT: Reset position for reading\r\n return File(memStream,\r\n \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\r\n \"GeneratedDocument.docx\");\r\n}\r\n\r\n// --- CREATE FROM TEMPLATE IN MEMORY ---\r\n// Useful for mail-merge style operations\r\nMemoryStream templateStream = new MemoryStream();\r\nFile.WriteAllBytes(\"template.docx\", templateStream.ToArray()); // Save a template first\r\n\r\nusing var templateSource = new MemoryStream(File.ReadAllBytes(\"template.docx\"));\r\nusing var mergedDoc = (WordprocessingDocument)templateSource.Clone();\r\n\r\n// Clone() creates an editable copy. Don't forget to set position:\r\nmergedDoc.MainDocumentPart!.Document.Body!.Append(new Paragraph(\r\n new Run(new Text(\"Added content\"))));\r\n```\r\n\r\n### 1.4 Adding All Standard Parts\r\n\r\n```csharp\r\n// =============================================================================\r\n// ADDING ALL STANDARD DOCUMENT PARTS\r\n// =============================================================================\r\n// A complete document should have:\r\n// 1. MainDocumentPart (auto-created)\r\n// 2. StyleDefinitionsPart\r\n// 3. NumberingDefinitionsPart\r\n// 4. DocumentSettingsPart\r\n// 5. ThemePart (optional)\r\n// 6. Custom parts (headers, footers, comments, etc.)\r\n\r\n// --- COMPLETE SETUP METHOD ---\r\npublic static void CreateCompleteDocument(string path)\r\n{\r\n using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);\r\n var mainPart = doc.MainDocumentPart!;\r\n\r\n // Initialize document\r\n mainPart.Document = new Document(new Body());\r\n var body = mainPart.Document.Body!;\r\n\r\n // Add all parts\r\n AddStylesPart(mainPart);\r\n AddNumberingPart(mainPart);\r\n AddSettingsPart(mainPart);\r\n AddThemePart(mainPart);\r\n AddHeadersAndFooters(mainPart);\r\n\r\n // Add sample content\r\n AddSampleContent(body);\r\n\r\n // Section properties MUST be last\r\n body.Append(CreateSectionProperties());\r\n\r\n mainPart.Document.Save();\r\n}\r\n\r\n// --- STYLES PART ---\r\n// See Section 2 for detailed style creation\r\nprivate static void AddStylesPart(MainDocumentPart mainPart)\r\n{\r\n var stylesPart = mainPart.AddNewPart();\r\n var styles = new Styles();\r\n\r\n // DocDefaults: document-wide defaults for run and paragraph properties\r\n // These apply when no explicit style or direct formatting overrides them\r\n styles.Append(new DocDefaults(\r\n new RunPropertiesDefault(\r\n new RunPropertiesBaseStyle(\r\n new RunFonts { Ascii = \"Calibri\", HighAnsi = \"Calibri\" },\r\n new FontSize { Val = \"22\" }, // 22 half-points = 11pt\r\n new FontSizeComplexScript { Val = \"22\" }\r\n )\r\n ),\r\n new ParagraphPropertiesDefault(\r\n new ParagraphPropertiesBaseStyle(\r\n new SpacingBetweenLines { After = \"200\", Line = \"276\", LineRule = LineSpacingRuleValues.Auto }\r\n )\r\n )\r\n ));\r\n\r\n // Default Normal style\r\n styles.Append(new Style(\r\n new StyleName { Val = \"Normal\" },\r\n new PrimaryStyle()\r\n )\r\n { Type = StyleValues.Paragraph, StyleId = \"Normal\", Default = true });\r\n\r\n stylesPart.Styles = styles;\r\n stylesPart.Styles.Save();\r\n}\r\n\r\n// --- NUMBERING PART ---\r\n// Required for bulleted and numbered lists\r\nprivate static void AddNumberingPart(MainDocumentPart mainPart)\r\n{\r\n var numberingPart = mainPart.AddNewPart();\r\n var numbering = new Numbering();\r\n\r\n // AbstractNum defines the list format (bullet, number, multilevel)\r\n// Creates a bullet list definition with 3 levels\r\n var abstractNum = new AbstractNum { AbstractNumberId = 1 };\r\n\r\n // Level 0: Bullet (dot)\r\n abstractNum.Append(new Level(\r\n new StartNumberingValue { Val = 1 },\r\n new NumberingFormat { Val = NumberFormatValues.Bullet },\r\n new LevelText { Val = \"•\" },\r\n new LevelJustification { Val = LevelJustificationValues.Left },\r\n new PreviousParagraphProperties(\r\n new Indentation { Left = \"720\", Hanging = \"360\" }) // 720 DXA indent, 360 DXA hanging\r\n )\r\n { LevelIndex = 0 });\r\n\r\n // Level 1: Dash\r\n abstractNum.Append(new Level(\r\n new StartNumberingValue { Val = 1 },\r\n new NumberingFormat { Val = NumberFormatValues.Bullet },\r\n new LevelText { Val = \"–\" },\r\n new LevelJustification { Val = LevelJustificationValues.Left },\r\n new PreviousParagraphProperties(\r\n new Indentation { Left = \"1440\", Hanging = \"360\" })\r\n )\r\n { LevelIndex = 1 });\r\n\r\n // Level 2: Circle\r\n abstractNum.Append(new Level(\r\n new StartNumberingValue { Val = 1 },\r\n new NumberingFormat { Val = NumberFormatValues.Bullet },\r\n new LevelText { Val = \"◦\" },\r\n new LevelJustification { Val = LevelJustificationValues.Left },\r\n new PreviousParagraphProperties(\r\n new Indentation { Left = \"2160\", Hanging = \"360\" })\r\n )\r\n { LevelIndex = 2 });\r\n\r\n numbering.Append(abstractNum);\r\n\r\n // NumberingInstance links to AbstractNum and assigns a numId\r\n numbering.Append(new NumberingInstance(\r\n new AbstractNumId { Val = 1 }\r\n )\r\n { NumberID = 1 });\r\n\r\n numberingPart.Numbering = numbering;\r\n numberingPart.Numbering.Save();\r\n}\r\n\r\n// --- SETTINGS PART ---\r\n// Contains document-level settings: zoom, proof state, default tab stop, etc.\r\nprivate static void AddSettingsPart(MainDocumentPart mainPart)\r\n{\r\n var settingsPart = mainPart.AddNewPart();\r\n var settings = new Settings();\r\n\r\n // Zoom: document zoom percentage (default 100%)\r\n // Val is a percentage value (e.g., \"100\" = 100%)\r\n settings.Append(new Zoom { Val = \"100\", Percent = true, SnapToGrid = true });\r\n\r\n // ProofState: spelling/grammar check state\r\n // Val combines bits: 1=grammar, 2=spelling, 3=both\r\n settings.Append(new ProofState { Val = ProofingStateValues.Clean });\r\n\r\n // Default tab stop interval in DXA\r\n // Word inserts tab stops every 720 DXA (0.5 inch) by default\r\n settings.Append(new DefaultTabStop { Val = 720 });\r\n\r\n // Character spacing control: automatically adjust character spacing\r\n // to maintain consistent line spacing (similar to InDesign)\r\n settings.Append(new CharacterSpacingControl { Val = CharacterSpacingValues.CompressPunctuation });\r\n\r\n // Compatibility settings: controls how Word handles certain formatting\r\n // to ensure compatibility with different Word versions\r\n settings.Append(new Compatibility(\r\n new UseFELayout(), // Use formatted East Asian layout\r\n new UseAsianDigraphicLineBreakRules(), // CJK line breaking rules\r\n new AllowSpaceOfSameStyleInTable(), // Table cell spacing\r\n new DoNotUseIndentAsPercentageForTabStops(), // Legacy tab behavior\r\n new ProportionalOtherIndents(), // Proportional indents\r\n new LayoutTableRawTextInTable() // Raw text in layout tables\r\n ));\r\n\r\n // Revision tracking view settings\r\n settings.Append(new RevisionView { DocPart = false, Formatting = true, Ink = true, Markup = true });\r\n\r\n settingsPart.Settings = settings;\r\n settingsPart.Settings.Save();\r\n}\r\n\r\n// --- THEME PART ---\r\n// Defines color scheme, font scheme, and format scheme for the document theme\r\nprivate static void AddThemePart(MainDocumentPart mainPart)\r\n{\r\n var themePart = mainPart.AddNewPart();\r\n var theme = new Theme(\r\n new ThemeElements(\r\n // Color scheme: 10 predefined theme colors\r\n new ColorScheme(\r\n new Dark1Color(new Color { Val = \"000000\" }),\r\n new Light1Color(new Color { Val = \"FFFFFF\" }),\r\n new Dark2Color(new Color { Val = \"1F497D\" }),\r\n new Light2Color(new Color { Val = \"EEECE1\" }),\r\n new Accent1Color(new Color { Val = \"4F81BD\" }),\r\n new Accent2Color(new Color { Val = \"C0504D\" }),\r\n new Accent3Color(new Color { Val = \"9BBB59\" }),\r\n new Accent4Color(new Color { Val = \"8064A2\" }),\r\n new Accent5Color(new Color { Val = \"4BACC6\" }),\r\n new Accent6Color(new Color { Val = \"F79646\" }),\r\n new Hyperlink(new Color { Val = \"0000FF\" }),\r\n new FollowedHyperlinkColor(new Color { Val = \"800080\" })\r\n ),\r\n // Font scheme: major (headings) and minor (body) fonts\r\n new FontScheme(\r\n new MajorFont { Val = \"Calibri Light\" },\r\n new MinorFont { Val = \"Calibri\" }\r\n ),\r\n // Format scheme: default fill and effect styles\r\n new FormatScheme(\r\n new FillStyleList(\r\n new FillStyle { Fill = new PatternFill { PatternType = PatternValues.Solid } }\r\n ),\r\n new LineStyleList(\r\n new LineStyle { Val = LineValues.Single }\r\n )\r\n )\r\n ),\r\n new ThemeName { Val = \"Office Theme\" },\r\n new ThemeNames(\r\n new LanguageBasedString { Val = \"en-US\", LanguageId = \"x-none\" }\r\n )\r\n );\r\n\r\n themePart.Theme = theme;\r\n themePart.Theme.Save();\r\n}\r\n\r\n// --- HEADERS AND FOOTERS ---\r\nprivate static void AddHeadersAndFooters(MainDocumentPart mainPart)\r\n{\r\n // Header\r\n var headerPart = mainPart.AddNewPart();\r\n headerPart.Header = new Header(\r\n new Paragraph(\r\n new ParagraphProperties(\r\n new Justification { Val = JustificationValues.Right }),\r\n new Run(\r\n new RunProperties(\r\n new RunFonts { Ascii = \"Calibri Light\", HighAnsi = \"Calibri Light\" },\r\n new Italic(),\r\n new FontSize { Val = \"20\" } // 10pt\r\n ),\r\n new Text(\"Document Header\"))\r\n ));\r\n var headerId = mainPart.GetIdOfPart(headerPart);\r\n\r\n // Footer\r\n var footerPart = mainPart.AddNewPart();\r\n footerPart.Footer = new Footer(\r\n new Paragraph(\r\n new ParagraphProperties(\r\n new Justification { Val = JustificationValues.Center }),\r\n new Run(new Text(\"Page \") { Space = SpaceProcessingModeValues.Preserve }),\r\n new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),\r\n new Run(new FieldCode(\" PAGE \") { Space = SpaceProcessingModeValues.Preserve }),\r\n new Run(new FieldChar { FieldCharType = FieldCharValues.End }),\r\n new Run(new Text(\" of \") { Space = SpaceProcessingModeValues.Preserve }),\r\n new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }),\r\n new Run(new FieldCode(\" NUMPAGES \") { Space = SpaceProcessingModeValues.Preserve }),\r\n new Run(new FieldChar { FieldCharType = FieldCharValues.End })\r\n ));\r\n var footerId = mainPart.GetIdOfPart(footerPart);\r\n\r\n // Reference IDs in section properties\r\n // (added in CreateSectionProperties below)\r\n}\r\n\r\n// --- SECTION PROPERTIES (COMPLETE) ---\r\nprivate static SectionProperties CreateSectionProperties()\r\n{\r\n var sectPr = new SectionProperties();\r\n\r\n // Header/Footer references (must come before page size/margins)\r\n var mainPart = doc.MainDocumentPart; // Note: in real code, pass as parameter\r\n sectPr.Append(new HeaderReference\r\n {\r\n Type = HeaderFooterValues.Default,\r\n Id = mainPart!.GetIdOfPart(mainPart.HeaderParts.First())\r\n });\r\n sectPr.Append(new FooterReference\r\n {\r\n Type = HeaderFooterValues.Default,\r\n Id = mainPart.GetIdOfPart(mainPart.FooterParts.First())\r\n });\r\n\r\n // Page size\r\n sectPr.Append(new PageSize { Width = 12240u, Height = 15840u });\r\n\r\n // Page margins\r\n sectPr.Append(new PageMargin\r\n {\r\n Top = 1440,\r\n Bottom = 1440,\r\n Left = 1440u,\r\n Right = 1440u,\r\n Header = 720u,\r\n Footer = 720u\r\n });\r\n\r\n // Page numbering format\r\n sectPr.Append(new PageNumberType { Start = 1, Format = NumberFormatValues.Decimal });\r\n\r\n // Column settings (default: 1 column)\r\n sectPr.Append(new Columns { ColumnCount = 1, EqualWidth = true });\r\n\r\n // Paper source (printer tray)\r\n // sectPr.Append(new PaperSource { Tray = 1, Paper = 7 });\r\n\r\n return sectPr;\r\n}\r\n```\r\n\r\n### 1.5 Unit Systems Reference\r\n\r\n```csharp\r\n// =============================================================================\r\n// UNIT SYSTEMS IN OPENXML\r\n// =============================================================================\r\n// Understanding units is critical. Wrong unit = wrong formatting.\r\n//\r\n// DXA (Twentieths of a DXA) - \"Standard Document Unit\"\r\n// 1 DXA = 1/20th of a point\r\n// 1 inch = 1440 DXA\r\n// 1 cm = 567 DXA (approx)\r\n// Used for: margins, indents, spacing, tab stops, column widths\r\n//\r\n// Half-Points (sz) - Font Size\r\n// Value is in half-points (1/2 point increments)\r\n// 24 = 12pt, 28 = 14pt, 36 = 18pt, 48 = 24pt\r\n// Used for: FontSize.Val, FontSizeComplexScript.Val\r\n//\r\n// Points (pt) - Direct Measurements\r\n// Standard typographic point (72 per inch)\r\n// Used for: some line spacing values, border widths\r\n//\r\n// EMU (English Metric Units) - Drawing Objects\r\n// 1 inch = 914400 EMU\r\n// Used for: drawing object sizes, shapes, images\r\n//\r\n// STARS (Special Twips Advanced Right-Left) - CJK Indentation\r\n// Used for: FirstLineChars, HangingChars (special FirstLine/Hanging for CJK)\r\n// Converts character counts to DXA based on font metrics\r\n//\r\n// LINE SPACING SPECIAL VALUES:\r\n// Line = \"240\" with LineRule = Auto = single spacing (default)\r\n// Line = \"480\" with LineRule = Auto = double spacing\r\n// Line = \"360\" with LineRule = Auto = 1.5 spacing\r\n// Line = \"240\" with LineRule = Exact = exactly 12pt\r\n// Line = \"288\" with LineRule = AtLeast = at least 14.4pt (grows with content)\r\n\r\n// --- CONVERSION HELPER METHODS ---\r\npublic static class OpenXmlUnits\r\n{\r\n // DXA conversions\r\n public static int InchesToDxa(double inches) => (int)(inches * 1440);\r\n public static int CmToDxa(double cm) => (int)(cm * 567.0);\r\n public static int PtToDxa(double pt) => (int)(pt * 20);\r\n public static double DxaToInches(int dxa) => dxa / 1440.0;\r\n public static double DxaToCm(int dxa) => dxa / 567.0;\r\n public static double DxaToPt(int dxa) => dxa / 20.0;\r\n\r\n // EMU conversions (for drawings)\r\n public static long InchesToEmu(double inches) => (long)(inches * 914400);\r\n public static long CmToEmu(double cm) => (long)(cm * 360000);\r\n public static double EmuToInches(long emu) => emu / 914400.0;\r\n\r\n // Half-point conversions (font sizes)\r\n public static int PtToHalfPt(double pt) => (int)(pt * 2);\r\n public static int FontSizeToSz(double ptSize) => (int)(ptSize * 2);\r\n public static double SzToPt(int sz) => sz / 2.0;\r\n\r\n // Line spacing\r\n public static int SingleSpacing => 240;\r\n public static int DoubleSpacing => 480;\r\n public static int OneAndHalfSpacing => 360;\r\n public static int LineSpacingPt(double pt) => (int)(pt * 20); // Convert to DXA\r\n}\r\n\r\n// Example usage:\r\nvar marginInInches = OpenXmlUnits.DxaToInches(1440); // 1.0\r\nvar fontSizeInSz = OpenXmlUnits.FontSizeToSz(12.0); // 24\r\nvar indentInDxa = OpenXmlUnits.InchesToDxa(0.5); // 720\r\n```\r\n\r\n---\r\n\r\n## 2. Style System Deep Dive\r\n\r\n### 2.1 Style Types and Structure\r\n\r\n```csharp\r\n// =============================================================================\r\n// STYLE TYPES OVERVIEW\r\n// =============================================================================\r\n// OpenXML defines 4 style types (StyleValues enum):\r\n// 1. Paragraph (w:p) - controls paragraph-level formatting\r\n// 2. Character (w:r) - controls inline/run-level formatting\r\n// 3. Table (w:tbl) - controls table-level formatting\r\n// 4. Numbering (w:num) - NOT a style type, but a separate numbering system\r\n//\r\n// Key insight: A style can be BOTH paragraph and character style (linked style).\r\n// The \"linkedStyle\" element links a paragraph style to a character style.\r\n\r\n// --- MINIMAL PARAGRAPH STYLE ---\r\n// A paragraph style controls: pPr (paragraph properties) and optionally rPr\r\nStyle minimalParaStyle = new Style(\r\n new StyleName { Val = \"MyParagraphStyle\" },\r\n new PrimaryStyle() // Primary styles appear in Style gallery\r\n)\r\n{\r\n Type = StyleValues.Paragraph,\r\n StyleId = \"MyParagraphStyle\"\r\n};\r\n\r\n// --- MINIMAL CHARACTER STYLE ---\r\n// A character style controls: rPr only (no pPr)\r\nStyle minimalCharStyle = new Style(\r\n new StyleName { Val = \"MyCharacterStyle\" },\r\n new PrimaryStyle()\r\n)\r\n{\r\n Type = StyleValues.Character,\r\n StyleId = \"MyCharacterStyle\"\r\n};\r\n\r\n// Character style with run properties (fonts, size, bold, etc.)\r\nStyle charStyleWithFormatting = new Style(\r\n new StyleName { Val = \"Emphasis\" },\r\n new PrimaryStyle(),\r\n new StyleRunProperties(\r\n new Italic(),\r\n new Color { Val = \"C00000\" } // Dark red\r\n )\r\n)\r\n{\r\n Type = StyleValues.Character,\r\n StyleId = \"Emphasis\"\r\n};\r\n\r\n// --- LINKED STYLE (Paragraph + Character) ---\r\n// A linked style combines both: it can be applied to a paragraph OR a run.\r\n// This is how Word's \"Heading 1\" works — applies to paragraphs, but you can\r\n// also select text within a heading and apply the same style as character formatting.\r\nStyle linkedStyle = new Style(\r\n new StyleName { Val = \"LinkedStyle\" },\r\n new PrimaryStyle(),\r\n new LinkedStyle { Val = \"LinkedStyleChar\" }, // Links to character style\r\n new StyleParagraphProperties(\r\n new SpacingBetweenLines { After = \"120\" }\r\n ),\r\n new StyleRunProperties(\r\n new Bold(),\r\n new FontSize { Val = \"24\" }\r\n )\r\n)\r\n{\r\n Type = StyleValues.Paragraph,\r\n StyleId = \"LinkedStyle\"\r\n};\r\n\r\n// Corresponding character style (normally same name + \"Char\" suffix by convention)\r\nStyle linkedStyleChar = new Style(\r\n new StyleName { Val = \"LinkedStyle Char\" }, // Word convention: adds \" Char\"\r\n new PrimaryStyle(),\r\n new StyleRunProperties(\r\n new Bold(),\r\n new FontSize { Val = \"24\" }\r\n )\r\n)\r\n{\r\n Type = StyleValues.Character,\r\n StyleId = \"LinkedStyleChar\"\r\n};\r\n\r\n// --- TABLE STYLE ---\r\nStyle tableStyle = new Style(\r\n new StyleName { Val = \"MyTableStyle\" },\r\n new PrimaryStyle(),\r\n new StyleTableProperties(\r\n new TableWidth { Width = \"5000\", Type = TableWidthUnitValues.Pct }, // 50% width\r\n new TableBorders(\r\n new TopBorder { Val = BorderValues.Single, Size = 4, Color = \"000000\" },\r\n new BottomBorder { Val = BorderValues.Single, Size = 4, Color = \"000000\" },\r\n new LeftBorder { Val = BorderValues.Single, Size = 4, Color = \"000000\" },\r\n new RightBorder { Val = BorderValues.Single, Size = 4, Color = \"000000\" },\r\n new InsideHorizontalBorder { Val = BorderValues.Single, Size = 2, Color = \"CCCCCC\" },\r\n new InsideVerticalBorder { Val = BorderValues.Single, Size = 2, Color = \"CCCCCC\" }\r\n ),\r\n new TableCellMarginDefault(\r\n new TopMargin { Width = \"0\", Type = TableWidthUnitValues.DXA },\r\n new StartMargin { Width = \"108\", Type = TableWidthUnitValues.DXA },\r\n new BottomMargin { Width = \"0\", Type = TableWidthUnitValues.DXA },\r\n new EndMargin { Width = \"108\", Type = TableWidthUnitValues.DXA }\r\n )\r\n )\r\n)\r\n{\r\n Type = StyleValues.Table,\r\n StyleId = \"MyTableStyle\"\r\n};\r\n```\r\n\r\n### 2.2 DocDefaults and Document-Wide Defaults\r\n\r\n```csharp\r\n// =============================================================================\r\n// DOCDEFAULTS: DOCUMENT-WIDE DEFAULTS\r\n// =============================================================================\r\n// DocDefaults lives inside Styles and provides fallback values when:\r\n// 1. No explicit style is applied\r\n// 2. No direct formatting is applied\r\n// It contains RunPropertiesDefault and/or ParagraphPropertiesDefault.\r\n//\r\n// CRITICAL: DocDefaults applies to the entire document. Any explicit style\r\n// or direct formatting will override it.\r\n\r\n// --- COMPLETE DOCDEFAULTS SETUP ---\r\nvar docDefaults = new DocDefaults(\r\n // Run properties defaults: default font, size, language for all runs\r\n new RunPropertiesDefault(\r\n new RunPropertiesBaseStyle(\r\n // RunFonts: which font to use for each script\r\n // Word will fall back through these: ASCII -> HighAnsi -> EastAsia -> ComplexScript\r\n // Always specify at minimum Ascii and HighAnsi\r\n new RunFonts\r\n {\r\n Ascii = \"Calibri\", // Western/Latin font (primary)\r\n HighAnsi = \"Calibri\", // Latin characters (often same as Ascii)\r\n EastAsia = \"SimSun\", // East Asian font (CJK)\r\n ComplexScript = \"Arial\", // Complex scripts (Arabic, Hebrew, Thai)\r\n ASCIITheme = ThemeFontValues.Minor,\r\n HighAnsiTheme = ThemeFontValues.Minor,\r\n EastAsiaTheme = ThemeFontValues.Minor,\r\n ComplexScriptTheme = ThemeFontValues.Minor\r\n },\r\n // FontSize: in HALF-POINTS (24 = 12pt, 22 = 11pt, 20 = 10pt)\r\n new FontSize { Val = \"22\" }, // 11pt for body\r\n new FontSizeComplexScript { Val = \"22\" },\r\n // Languages: required for proper hyphenation and spell checking\r\n new Languages { Val = \"en-US\" }, // Default language\r\n new Languages { EastAsia = \"zh-CN\", Val = \"en-US\" } // Can set multiple\r\n )\r\n ),\r\n // Paragraph properties defaults: default spacing, etc.\r\n new ParagraphPropertiesDefault(\r\n new ParagraphPropertiesBaseStyle(\r\n // SpacingBetweenLines: default paragraph spacing\r\n // After = \"200\" = 200 DXA = 10pt after each paragraph\r\n new SpacingBetweenLines\r\n {\r\n After = \"200\",\r\n Line = \"276\",\r\n LineRule = LineSpacingRuleValues.Auto // Auto = 1.15x line height\r\n }\r\n )\r\n )\r\n);\r\n\r\n// --- LAYOUT LUNCTIONS (LATENT STYLES) ---\r\n// Latent styles are hidden styles that exist in Word but aren't in styles.xml.\r\n// They provide fast-access defaults for formatting (e.g., Normal, Heading 1-6, etc.)\r\n// when the user hasn't explicitly customized them.\r\n//\r\n// DocDefaults can define LatentStyleCountOverride to adjust count,\r\n// but true latent styles are controlled by Normal.dotm (Word's global template).\r\nStyles CreateStylesWithDocDefaults()\r\n{\r\n var styles = new Styles();\r\n\r\n // DocDefaults with run and paragraph properties defaults\r\n styles.Append(new DocDefaults(\r\n new RunPropertiesDefault(\r\n new RunPropertiesBaseStyle(\r\n new RunFonts { Ascii = \"Calibri\", HighAnsi = \"Calibri\" },\r\n new FontSize { Val = \"22\" },\r\n new Languages { Val = \"en-US\" }\r\n )\r\n ),\r\n new ParagraphPropertiesDefault(\r\n new ParagraphPropertiesBaseStyle(\r\n new SpacingBetweenLines { After = \"160\", Line = \"276\", LineRule = LineSpacingRuleValues.Auto }\r\n )\r\n )\r\n ));\r\n\r\n // LatentStyles: override defaults for built-in latent styles\r\n // These control Word's \"fast-styles\" like Heading 1-6 before they're customized\r\n styles.Append(new LatentStyles(\r\n new Count { Val = 159 }, // Total latent style count\r\n new FirstLineChars { Val = 352 }, // Default first line char count\r\n new HorizontalOverflow { Val = HorizontalOverflowValues.Overflow },\r\n new VerticalOverflow { Val = VerticalOverflowValues.Overflow },\r\n new KoreanSpaceAdjust","readmeExcerpt":"Skill: MiniMax DOCX Owner: yhlorra Summary: Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-03-25T13:43:06.824Z | user Initial publish Archive index: Archive v1.0.0: 67 files, 362368 bytes Files: assets/styles/academic_styles.xml (7658b), assets/styles/corpo","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"File v1.0.0:references/cjk_university_template_guide.md\n\n# Chinese University Thesis Template Guide (中国高校论文模板指南)\r\n\r\n## Why This Guide Exists\r\n\r\nChinese university thesis templates (.docx) have structural patterns that differ significantly\r\nfrom Western templates. Agents that assume Western conventions (Heading1/Heading2/Normal) will\r\nfail repeatedly. This guide documents the ACTUAL patterns found in Chinese templates.\r\n\r\n## Common StyleId Patterns\r\n\r\n### Pattern A: Numeric IDs (most common in Chinese Word templates)\r\n\r\n| Style Purpose | styleId | w:name | w:basedOn |\r\n|--------------|---------|--------|-----------|\r\n| Normal body | `a` | \"Normal\" | — |\r\n| Default paragraph font | `a0` | \"Default Paragraph Font\" | — |\r\n| Heading 1 (章标题) | `1` | \"heading 1\" | `a` |\r\n| Heading 2 (节标题) | `2` | \"heading 2\" | `a` |\r\n| Heading 3 (小节标题) | `3` | \"heading 3\" | `a` |\r\n| TOC 1 | `11` | \"toc 1\" | `a` |\r\n| TOC 2 | `21` | \"toc 2\" | `a` |\r\n| TOC 3 | `31` | \"toc 3\" | `a` |\r\n| Header | `a3` | \"header\" | `a` |\r\n| Footer | `a4` | \"footer\" | `a` |\r\n| Table of Contents heading | `10` | \"TOC Heading\" | `1` |\r\n\r\n### Pattern B: English IDs (less common, usually from international templates)\r\nStandard Heading1/Heading2/Heading3/Normal — these follow the Western pattern.\r\n\r\n### Pattern C: Mixed (some Chinese, some English)\r\nSome templates define custom styles with Chinese names:\r\n| Style Purpose | styleId | w:name |\r\n|--------------|---------|--------|\r\n| 论文标题 | `lunwenbiaoti` | \"论文标题\" |\r\n| 章标题 | `zhangbiaoti` | \"章标题\" |\r\n| 正文 | `zhengwen` | \"正文\" |\r\n\r\n### How to Identify Which Pattern"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: minimax-docx\r\nlicense: MIT\r\nmetadata:\r\n version: \"1.0.0\"\r\n category: document-processing\r\n author: MiniMaxAI\r\n sources:\r\n - \"ECMA-376 Office Open XML File Formats\"\r\n - \"GB/T 9704-2012 Layout Standard for Official Documents\"\r\n - \"IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides\"\r\n - \"Springer LNCS / Nature / HBR Document Templates\"\r\ndescription: >\r\n Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET).\r\n Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing\r\n documents, (C) apply template formatting with XSD validation gate-check.\r\n MUST use this skill whenever the user wants to produce, modify, or format a Word document —\r\n including when they say \"write a report\", \"draft a proposal\", \"make a contract\",\r\n \"fill in this form\", \"reformat to match this template\", or any task whose final output\r\n is a .docx file. Even if the user doesn't mention \"docx\" explicitly, if the task\r\n implies a printable/formal document, use this skill.\r\ntriggers:\r\n - Word\r\n - docx\r\n - document\r\n - 文档\r\n - Word文档\r\n - 报告\r\n - 合同\r\n - 公文\r\n - 排版\r\n - 套模板\r\n---\r\n\r\n# minimax-docx\r\n\r\nCreate, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).\r\n\r\n## Setup\r\n\r\n**First time:** `bash scripts/setup.sh` (or `powershell scripts/setup.ps1` on Windows, `--minimal` to skip optional deps).\r\n\r\n**First operation in session:** `scripts/env_check.sh` — do not proceed if `NOT READY`. (Skip on subsequent operations within the same session.)\r\n\r\n## Quick Start: Direct C# Path\r\n\r\nWhen the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:\r\n\r\n```csharp\r\n// File: scripts/dotnet/task.csx (or a new .cs in a Console project)\r\n// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx\r\n#r \"nuget: DocumentFormat.OpenXml, 3.2.0\"\r\n\r\nusing DocumentFormat.OpenXml;\r\nusing DocumentFormat.OpenXml.Packaging;\r\nusing DocumentFormat.OpenXml.Wordprocessing;\r\n\r\nusing var doc = WordprocessingDocument.Create(\"output.docx\", WordprocessingDocumentType.Document);\r\nvar mainPart = doc.AddMainDocumentPart();\r\nmainPart.Document = new Document(new Body());\r\n\r\n// --- Your logic here ---\r\n// Read the relevant Samples/*.cs file FIRST for tested patterns.\r\n// See Samples/ table in References section below.\r\n```\r\n\r\n**Before writing any C#, read the relevant `Samples/*.cs` file** — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.\r\n\r\n## CLI shorthand\r\n\r\nAll CLI commands below use `$CLI` as shorthand for:\r\n```bash\r\ndotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --\r\n```\r\n\r\n## Pipeline routing\r\n\r\nRoute by checking: does the user have an input .docx file?\r\n\r\n```\r\nUser task\r\n├─ No input file → Pipeline A: CREATE\r\n│ s"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7ay31t8b2nm3fjytaw0f9hqh8001cc\",\n \"slug\": \"yh-minimax-docx\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1774446186824\n}"},{"path":"references/cjk_typography.md","content":"# CJK Typography & Mixed-Script Guide\r\n\r\nRules for Chinese, Japanese, and Korean text in DOCX documents.\r\n\r\n## Table of Contents\r\n\r\n1. [Font Selection](#font-selection)\r\n2. [Font Size Names (CJK)](#font-size-names)\r\n3. [RunFonts Mapping](#runfonts-mapping)\r\n4. [Punctuation & Line Breaking](#punctuation--line-breaking)\r\n5. [Paragraph Indentation](#paragraph-indentation)\r\n6. [Line Spacing for CJK](#line-spacing)\r\n7. [Chinese Government Standard (GB/T 9704)](#gbt-9704)\r\n8. [Mixed CJK + Latin Best Practices](#mixed-script)\r\n9. [OpenXML Quick Reference](#openxml-quick-reference)\r\n\r\n---\r\n\r\n## Font Selection\r\n\r\n### Recommended CJK Fonts\r\n\r\n| Language | Serif (正文) | Sans (标题) | Notes |\r\n|----------|-------------|-------------|-------|\r\n| **Simplified Chinese** | 宋体 (SimSun) | 微软雅黑 (Microsoft YaHei) | YaHei for screen, SimSun for print |\r\n| **Simplified Chinese** | 仿宋 (FangSong) | 黑体 (SimHei) | Government documents |\r\n| **Traditional Chinese** | 新細明體 (PMingLiU) | 微軟正黑體 (Microsoft JhengHei) | Taiwan standard |\r\n| **Japanese** | MS 明朝 (MS Mincho) | MS ゴシック (MS Gothic) | Classic pairing |\r\n| **Japanese** | 游明朝 (Yu Mincho) | 游ゴシック (Yu Gothic) | Modern, Windows 10+ |\r\n| **Korean** | 바탕 (Batang) | 맑은 고딕 (Malgun Gothic) | Standard pairing |\r\n\r\n### Government Document Fonts (公文)\r\n\r\n| Element | Font | Size |\r\n|---------|------|------|\r\n| 标题 (title) | 小标宋 (FZXiaoBiaoSong-B05S) | 二号 (22pt) |\r\n| 一级标题 | 黑体 (SimHei) | 三号 (16pt) |\r\n| 二级标题 | 楷体_GB2312 (KaiTi_GB2312) | 三号 (16pt) |\r\n| 三级标题 | 仿宋_GB2312 加粗 | 三号 (16pt) |\r\n| 正文 (body) | 仿宋_GB2312 (FangSong_GB2312) | 三号 (16pt) |\r\n| 附注/页码 | 宋体 (SimSun) | 四号 (14pt) |\r\n\r\n---\r\n\r\n## Font Size Names\r\n\r\nCJK uses named sizes. Map to points and `w:sz` half-point values:\r\n\r\n| 字号 | Points | `w:sz` | Common Use |\r\n|------|--------|--------|------------|\r\n| 初号 | 42pt | 84 | Display title |\r\n| 小初 | 36pt | 72 | Large title |\r\n| 一号 | 26pt | 52 | Chapter heading |\r\n| 小一 | 24pt | 48 | Major heading |\r\n| 二号 | 22pt | 44 | Document title (公文) |\r\n| 小二 | 18pt | 36 | Western H1 equivalent |\r\n| 三号 | 16pt | 32 | CJK heading / 公文 body |\r\n| 小三 | 15pt | 30 | Sub-heading |\r\n| 四号 | 14pt | 28 | CJK subheading |\r\n| 小四 | 12pt | 24 | Standard body (CJK) |\r\n| 五号 | 10.5pt | 21 | Compact CJK body |\r\n| 小五 | 9pt | 18 | Footnotes |\r\n| 六号 | 7.5pt | 15 | Fine print |\r\n\r\n---\r\n\r\n## RunFonts Mapping\r\n\r\nOpenXML uses four font slots to handle multilingual text:\r\n\r\n```xml\r\n\r\n w:hAnsi=\"Calibri\" \r\n w:eastAsia=\"SimSun\" \r\n w:cs=\"Arial\" \r\n/>\r\n```\r\n\r\n**Word's character classification logic:**\r\n\r\n1. Character is in CJK range → uses `w:eastAsia` font\r\n2. Character is in complex script range → uses `w:cs` font\r\n3. Character is basic Latin (ASCII) → uses `w:ascii` font\r\n4. Everything else → uses `w:hAnsi` font\r\n\r\n**Key**: `w:eastAsia` is the **only** way to "},{"path":"references/cjk_university_template_guide.md","content":"# Chinese University Thesis Template Guide (中国高校论文模板指南)\r\n\r\n## Why This Guide Exists\r\n\r\nChinese university thesis templates (.docx) have structural patterns that differ significantly\r\nfrom Western templates. Agents that assume Western conventions (Heading1/Heading2/Normal) will\r\nfail repeatedly. This guide documents the ACTUAL patterns found in Chinese templates.\r\n\r\n## Common StyleId Patterns\r\n\r\n### Pattern A: Numeric IDs (most common in Chinese Word templates)\r\n\r\n| Style Purpose | styleId | w:name | w:basedOn |\r\n|--------------|---------|--------|-----------|\r\n| Normal body | `a` | \"Normal\" | — |\r\n| Default paragraph font | `a0` | \"Default Paragraph Font\" | — |\r\n| Heading 1 (章标题) | `1` | \"heading 1\" | `a` |\r\n| Heading 2 (节标题) | `2` | \"heading 2\" | `a` |\r\n| Heading 3 (小节标题) | `3` | \"heading 3\" | `a` |\r\n| TOC 1 | `11` | \"toc 1\" | `a` |\r\n| TOC 2 | `21` | \"toc 2\" | `a` |\r\n| TOC 3 | `31` | \"toc 3\" | `a` |\r\n| Header | `a3` | \"header\" | `a` |\r\n| Footer | `a4` | \"footer\" | `a` |\r\n| Table of Contents heading | `10` | \"TOC Heading\" | `1` |\r\n\r\n### Pattern B: English IDs (less common, usually from international templates)\r\nStandard Heading1/Heading2/Heading3/Normal — these follow the Western pattern.\r\n\r\n### Pattern C: Mixed (some Chinese, some English)\r\nSome templates define custom styles with Chinese names:\r\n| Style Purpose | styleId | w:name |\r\n|--------------|---------|--------|\r\n| 论文标题 | `lunwenbiaoti` | \"论文标题\" |\r\n| 章标题 | `zhangbiaoti` | \"章标题\" |\r\n| 正文 | `zhengwen` | \"正文\" |\r\n\r\n### How to Identify Which Pattern\r\n\r\n```bash\r\n# Extract all styleIds from the template\r\n$CLI analyze --input template.docx --styles-only\r\n\r\n# Or manually:\r\n# unzip template.docx word/styles.xml\r\n# Search for w:styleId= in the extracted file\r\n```\r\n\r\nLook at the first few styleIds. If you see `1`, `2`, `3`, `a`, `a0` → Pattern A.\r\nIf you see `Heading1`, `Normal` → Pattern B.\r\n\r\n## Standard Thesis Structure\r\n\r\nChinese university theses follow a highly standardized structure:\r\n\r\n```\r\n┌─────────────────────────────────────┐\r\n│ 封面 (Cover Page) │ ← Usually 1-2 pages\r\n│ - 校名、校徽 │\r\n│ - 论文题目 (title) │\r\n│ - 作者、导师、院系、日期 │\r\n├─────────────────────────────────────┤\r\n│ 学术诚信承诺书 / 独创性声明 │ ← 1 page\r\n│ (Academic Integrity Declaration) │\r\n├─────────────────────────────────────┤\r\n│ 中文摘要 (Chinese Abstract) │ ← 1-2 pages\r\n│ - \"摘 要\" heading │\r\n│ - Abstract body │\r\n│ - \"关键词：\" line │\r\n├─────────────────────────────────────┤\r\n│ 英文摘要 (English Abstract) │ ← 1-2 pages\r\n│ - \"ABSTRACT\" heading │\r\n│ - Abstract body │\r\n│ - \"Keywords:\" line │\r\n├─────────────────────────────────────┤\r\n│ 目录 (Table of Contents) │ ← 1-3 pages\r\n│ - Often inside SDT block │\r\n│ - Static example entries │\r\n│ - TOC field code │\r\n├────────────────────────────────────"},{"path":"references/comments_guide.md","content":"# Comments System Guide (4-File Architecture)\r\n\r\n## Overview\r\n\r\nWord comments require coordination across **four XML files** plus references in `document.xml`, `[Content_Types].xml`, and `document.xml.rels`.\r\n\r\n---\r\n\r\n## The Four Comment Files\r\n\r\n### 1. `word/comments.xml` — Main Comment Content\r\n\r\nContains the actual comment text:\r\n\r\n```xml\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n This needs clarification.\r\n \r\n \r\n \r\n\r\n```\r\n\r\nKey attributes: `w:id` (unique integer), `w:author`, `w:date` (ISO 8601), `w:initials`.\r\n\r\n### 2. `word/commentsExtended.xml` — W15 Extensions\r\n\r\nLinks comments to paragraphs and tracks resolved status:\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n- `w15:paraId` — matches the `w14:paraId` of the comment's paragraph in `comments.xml`\r\n- `w15:done` — `\"0\"` = open, `\"1\"` = resolved\r\n\r\n### 3. `word/commentsIds.xml` — Persistent ID Mapping\r\n\r\nProvides durable IDs that survive copy/paste across documents:\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n- `w16cid:paraId` — same as `w15:paraId`\r\n- `w16cid:durableId` — globally unique identifier (8-digit hex)\r\n\r\n### 4. `word/commentsExtensible.xml` — W16 Extensions\r\n\r\nModern comment extensions (used in newer Word versions):\r\n\r\n```xml\r\n\r\n\r\n \r\n\r\n```\r\n\r\n---\r\n\r\n## Document.xml References\r\n\r\nComments are anchored in document content using three elements:\r\n\r\n```xml\r\n\r\n \r\n This text has a comment.\r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n- `w:commentRangeStart` — marks where the commented text begins\r\n- `w:commentRangeEnd` — marks where the commented text ends\r\n- `w:commentReference` — the visible comment m"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... Skill: MiniMax DOCX Owner: yhlorra Summary: Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-03-25T13:43:06.824Z | user Initial publish Archive index: Archive v1.0.0: 67 files, 362368 bytes Files: assets/styles/academic_styles.xml (7658b), assets/styles/corpo","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":917,"uniquenessScore":62,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T14:39:08.918Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:03:35.613Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}