@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/docx/docs/router.md

@@ -0,0 +1,122 @@
+# Task router
+
+Choose exactly one route. Dispatch first, then go straight to the matching task guide. Do not start
+with backend preference, evidence classes, or validation profiles.
+
+## Fast path
+
+### Generation-first routes
+
+1. **User wants a new formal Word deliverable** -> `CREATE_DOCX`
+2. **User wants current content put into a template / institutional style system** -> `APPLY_TEMPLATE`
+
+For these two routes, stop routing once the intent is clear. Go directly to the task guide. The task
+guide will decide recipe family, backend, and acceptance in that order.
+
+### Everything else
+
+- read meaning -> `READ_CONTENT`
+- inspect Word / OpenXML internals -> `READ_STRUCTURE`
+- inspect what pages actually look like -> `READ_RENDERED`
+- mutate an existing DOCX in place -> `EDIT_FILL_DOCX`
+- fix visible defects -> `REPAIR_LAYOUT`
+- compare two DOCX files -> `COMPARE_TWO_DOCX`
+
+## Router
+
+```text
+User asks for a DOCX task
+|
++-- Is the main goal to produce or restyle a formal Word deliverable?
+|   |
+|   +-- Yes
+|   |   |
+|   |   +-- No source DOCX must remain “the same document”
+|   |   |   -> CREATE_DOCX
+|   |   |
+|   |   +-- Source content survives but template / institutional visual system is the point
+|   |       -> APPLY_TEMPLATE
+|   |
+|   +-- No
+|       |
+|       +-- User wants to read / summarize / quote / search / extract
+|       |   -> READ_CONTENT
+|       |
+|       +-- User wants styles / sections / numbering / TOC / comments / revisions / template internals
+|       |   -> READ_STRUCTURE
+|       |
+|       +-- User wants page truth / visual mismatch / blank pages / overflow / cover / TOC layout
+|       |   -> READ_RENDERED or REPAIR_LAYOUT
+|       |
+|       +-- User wants to change the content but keep this DOCX as the same document
+|       |   -> EDIT_FILL_DOCX
+|       |
+|       +-- User gives two DOCX files and wants differences explained
+|           -> COMPARE_TWO_DOCX
+```
+
+## Route-level environment gate
+
+After selecting a route, run the matching gate level before proceeding.
+
+| Route              | Gate level |
+|--------------------|------------|
+| READ_CONTENT       | read       |
+| READ_STRUCTURE     | read       |
+| READ_RENDERED      | render     |
+| COMPARE_TWO_DOCX   | read       |
+| CREATE_DOCX        | full       |
+| APPLY_TEMPLATE     | full       |
+| EDIT_FILL_DOCX     | full       |
+| REPAIR_LAYOUT      | full       |
+
+```bash
+# macOS / Linux / WSL
+bash <skill_dir>/scripts/env_check.sh --level <gate_level>
+```
+
+```powershell
+# Windows
+powershell -ExecutionPolicy Bypass -File <skill_dir>\scripts\env_check.ps1 -Level <Read|Render|Full>
+```
+
+Do not run the full gate before route selection. The loader already ran the read gate; only
+escalate to render or full when the selected route requires it.
+
+## Route boundaries
+
+### CREATE_DOCX
+Use when there is no source DOCX to preserve as a document object. Markdown / HTML / LaTeX /
+business brief source still belongs here after normalization.
+
+### APPLY_TEMPLATE
+Use when the user’s real ask is “make this content become that document system”. This includes school
+templates, 公文格式, house style, and multi-section institutional layouts.
+
+### EDIT_FILL_DOCX
+Use when the source DOCX stays the same document and the user wants content mutation. If the real
+source is Markdown / LaTeX and the DOCX is just a stale render, do not edit in place; regenerate.
+
+### READ_CONTENT
+Use for meaning. Do not answer TOC, section, numbering, or page-layout questions here.
+
+### READ_STRUCTURE
+Use for Word/OpenXML truth. This is the default diagnosis route before template-sensitive mutation.
+
+### READ_RENDERED
+Use when the user asks what the pages actually look like. Rendered pages judge correctness; XML only
+explains causes.
+
+### REPAIR_LAYOUT
+Use when the complaint is visual and the goal is correction, not just inspection.
+
+### COMPARE_TWO_DOCX
+Use when the user asks for a before/after or source/template difference analysis.
+
+## Common misroutes
+
+- “帮我写个 Word 报告” is **not** READ_CONTENT
+- “套成学校模板” is **not** plain EDIT_FILL_DOCX
+- “这份文档为什么看起来不对” is **not** automatically READ_STRUCTURE — it may be READ_RENDERED or REPAIR_LAYOUT
+- “改这份 Word 的几段内容” is **not** CREATE_DOCX
+- “这两个 docx 差在哪” is **not** ordinary READ_CONTENT

package/server/assets/skills/docx/docs/tables-and-numbering.md

@@ -0,0 +1,27 @@
+# Tables and numbering
+
+These are high-risk structures. Treat them as such.
+
+## Tables
+
+Local row fill is safe only when:
+- row topology is simple
+- no relationship insertion is required
+- no complex vertical/horizontal merge logic has to be rebuilt
+
+Escalate to `D` or `S` when:
+- merged cells matter
+- repeated header rows matter
+- shading/borders/grid logic must be preserved precisely
+- template transfer contaminates cell-local paragraph/run formatting
+
+## Numbering
+
+Numbering is not just visible numerals. It is a graph between `num` and `abstractNum` definitions.
+
+Local patching is unsafe when:
+- numbering definitions must be rebuilt or remapped
+- section restarts interact with page-number systems
+- heading numbering and TOC behavior must stay aligned
+
+Use the bundled references and validators in this skill when numbering changes are part of the task.

package/server/assets/skills/docx/docs/task-apply-template.md

@@ -0,0 +1,141 @@
+# Task: APPLY_TEMPLATE
+
+Use this task family when source content should survive but the visual or institutional template
+system changes.
+
+## Fast path
+
+For template work, do not treat the job as a generic forensic waterfall. Use this order:
+
+1. choose template mode
+2. align the target visual system to the style family / recipe layer
+3. read just the structure needed to execute that mode safely
+4. choose backend `D` or `S`
+5. write the output
+6. run strict rendered acceptance
+
+If the template mode is obvious, real template work should begin after step 3.
+
+### Canonical dispatch
+
+```text
+Need this content to become that template system
+-> choose template mode
+-> align recipe family
+-> read only the structure required by that mode
+-> default to D
+-> escalate to S only if structural transfer clearly exceeds CLI surface
+-> write
+-> run strict post-write rendered acceptance
+```
+
+The generation core that must stay active here is:
+
+- `<skill_dir>/references/scenario_c_apply_template.md`
+- `<skill_dir>/references/typography_guide.md`
+- `<skill_dir>/references/design_principles.md`
+- `<skill_dir>/references/cjk_typography.md` when CJK / 公文 / thesis formatting is involved
+- `<skill_dir>/scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.cs`
+
+Template work is not “style by vibes”. Use these to anchor the visual system before backend work.
+
+## Required inputs
+
+- source `.docx` or text-native source, depending on template mode
+- template `.docx`
+- a template mode decision
+
+## Quick alignment chooser
+
+Use this table first. Only read deeper references after you have the nearest alignment family.
+
+| If the template looks like... | Start here |
+| --- | --- |
+| school / thesis / dissertation template | `AcademicThesis` family + institutional structure preservation |
+| 公文 / Chinese government / strong CJK official template | `ChineseGovernment` + `cjk_typography.md` |
+| corporate / branded business template | `ModernCorporate` / `ExecutiveBrief` |
+| reference sample with no structural authority | nearest family by visual intent, then treat as `reference_style_only` |
+
+## Style family / recipe alignment
+
+After template mode is chosen, align the template target to a recipe family instead of inventing raw
+values from scratch:
+
+| Situation | Alignment rule |
+| --- | --- |
+| school / thesis / institutional template | preserve the template’s structural zones, then align heading / body / spacing expectations to the nearest academic or institutional recipe family |
+| 公文 / government / strong CJK template | `ChineseGovernment` + `cjk_typography.md` is the baseline; template XML can override only where the template explicitly proves it |
+| corporate / branded template | align to `ModernCorporate` / `ExecutiveBrief` / closest recipe, then preserve template-specific colors / sections / headers |
+| reference-style-only template | treat the template as style intent, map it to the nearest recipe family, then generate through `D` or `S` |
+
+Once alignment is chosen, preserve template-proven structure first and use recipe values for the parts
+the template does not specify clearly.
+
+## Template modes
+
+### `reference_style_only`
+Source is text-native, but the final formal DOCX still must be produced through `D` after
+normalization into a document plan / structured config. Treat the template as style intent, not as a
+pandoc route.
+
+### `overlay_styles`
+Source is DOCX and the template mainly supplies style system, not structural zones.
+
+### `base_replace`
+Template is the skeleton. Output starts from the template and replaces example content with source
+content.
+
+### `institutional_multi_section`
+Template controls cover / TOC / abstract / body / page numbers / titlePg / per-section
+headers/footers. This is the strictest mode.
+
+If `institutional_multi_section` is chosen, recipe alignment still matters for typography and spacing,
+but structure preservation outranks cosmetic simplification.
+
+## Only if needed before writing
+
+- read source/template structure only to the extent required by the chosen template mode
+- inspect template rendered output only when structure alone cannot explain the template’s visual system
+- do not open output rendered workflow before the write step; rendered acceptance comes after write
+
+Template work without the needed structure read is blind. Template work without post-write rendered
+verification is unfinished.
+
+## Backend decision
+
+### Default to D when
+- source is text-native but has been normalized into a document plan / structured config and the
+  template mainly supplies style intent
+- source is DOCX and template carries institutional or multi-section structure
+- source is DOCX and even “style overlay” still needs in-place preservation
+
+### Escalate to S when
+- the template transfer is structurally beyond D
+
+Backend choice happens after template mode + recipe alignment, not before them.
+
+If both `D` and `S` are plausible, prefer `D` first and escalate to `S` only when the structural
+transfer clearly exceeds CLI surface.
+
+If you are hesitating between `D` and `S`, that is not a reason to stop. Start from `D` unless a
+specific structural transfer requirement rules it out.
+
+## Hard no
+
+- Never apply a structural template by pretending it is only a reference-doc style transfer.
+- Never deliver template work without rendered acceptance.
+- Never assume placeholders are stable; validate anchors first if the template uses anchors.
+- Never skip recipe alignment and improvise typography values from memory.
+
+## Deep references
+
+Reuse the bundled template knowledge under:
+- `<skill_dir>/references/scenario_c_apply_template.md`
+- `<skill_dir>/references/typography_guide.md`
+- `<skill_dir>/references/design_principles.md`
+- `<skill_dir>/references/cjk_typography.md`
+- `<skill_dir>/scripts/dotnet/MiniMaxAIDocx.Core/Samples/*.cs`
+
+## After writing
+
+Run `strict` acceptance from `acceptance.md`.

package/server/assets/skills/docx/docs/task-compare-two-docx.md

@@ -0,0 +1,48 @@
+# Task: COMPARE_TWO_DOCX
+
+Use this task family when the user provides two DOCX files and wants the differences explained.
+
+## Required inputs
+
+- `before.docx`
+- `after.docx`
+- optional compare focus; if omitted, assume full compare
+
+Allowed focuses:
+- `content_only`
+- `structure_only`
+- `rendered_only`
+- `full`
+
+## Evidence profile
+
+Default evidence: **content + structure + rendered**.
+
+## Output contract
+
+Always separate the result into:
+
+### Content differences
+- changed text, headings, tables, notes, or clauses
+
+### Structure differences
+- changed styles, sections, numbering, headers/footers, fields, comments/revisions, direct formatting
+
+### Rendered differences
+- changed page count, blank pages, page numbers, header/footer appearance, overflow, cover/TOC/body layout
+
+Then classify risk:
+- content risk
+- structure risk
+- purely visual risk
+- highest-risk difference
+
+## Execution notes
+
+- use read-content techniques for content diff
+- use `diff_docx_structure.py` for structure diff
+- use rendered inspection when page truth matters
+
+## Acceptance profile
+
+`forensic`

package/server/assets/skills/docx/docs/task-create.md

@@ -0,0 +1,124 @@
+# Task: CREATE_DOCX
+
+Use this task family when there is no source DOCX that must remain “the same document”.
+
+## Fast path
+
+For creation, do not start with evidence or backend theory. Use this order:
+
+1. normalize the source into a document plan / structured config
+2. choose the style family / recipe layer
+3. choose backend `D` or `S`
+4. write the DOCX
+5. run acceptance
+
+If the user intent is obvious, you should be able to start real generation work after step 2.
+
+### Canonical dispatch
+
+```text
+Need a new formal DOCX
+-> normalize source
+-> match recipe family from quick chooser
+-> default to D
+-> escalate to S only if the graph clearly exceeds CLI surface
+-> write
+-> run post-write acceptance
+```
+
+The generation core that preserves old benchmark quality is:
+
+- `<skill_dir>/references/scenario_a_create.md`
+- `<skill_dir>/references/typography_guide.md`
+- `<skill_dir>/references/design_principles.md`
+- `<skill_dir>/references/cjk_typography.md` when CJK / 公文 / mixed-script quality matters
+- `<skill_dir>/scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples*.cs`
+
+These files are not optional background. They are the recipe layer. Pick a family from them before
+inventing any formatting values.
+
+## Required inputs
+
+At least one of:
+- Markdown / LaTeX / HTML / RST source (must be normalized into a document plan / structured config before write)
+- structured config (JSON sections / headings / tables / images / page setup)
+- business brief that can be turned into a document plan
+- optional template DOCX if style transfer or institutional formatting is needed
+
+## Quick recipe chooser
+
+Use this table first. Only read deeper references after you have a first-match family.
+
+| If the user asks for... | Start here |
+| --- | --- |
+| report / proposal / executive brief / polished business document | `ModernCorporate` or `ExecutiveBrief` |
+| thesis / paper / journal-like / academic deliverable | `AcademicThesis` or the nearest citation-style recipe |
+| 公文 / Chinese official / strong CJK formal output | `ChineseGovernment` + `cjk_typography.md` |
+| branded but not institutionally templated document | nearest business recipe, then refine with `design_principles.md` |
+
+## Style family / recipe selection
+
+Choose the nearest recipe family before backend arbitration:
+
+| User intent | Recipe family / source |
+| --- | --- |
+| business report / proposal / executive brief | `AestheticRecipeSamples` -> `ModernCorporate`, `ExecutiveBrief`, `MinimalModern`; spacing / page defaults from `typography_guide.md` |
+| academic paper / thesis / journal-like output | `AcademicThesis`, `APA`, `MLA`, `Chicago`, `Springer`, `Nature`; hierarchy and spacing from `design_principles.md` |
+| 公文 / Chinese institutional document / strong CJK output | `ChineseGovernment` + `cjk_typography.md` |
+| brand / house style without a structural template | nearest recipe family first, then refine with `design_principles.md` / `typography_guide.md` |
+
+If the user gives exact institutional formatting through a template DOCX, reconsider whether the real
+route is `APPLY_TEMPLATE`.
+
+Once a family is chosen, use the corresponding recipe/sample values as the default. Do not freestyle
+font size, spacing, or page geometry from memory.
+
+## Only if needed before writing
+
+- read source content only if the source is ambiguous and must be normalized into a document plan
+- read template structure only if an optional reference template is influencing creation choices
+- do not open rendered workflow before writing; rendered truth is normally the post-write gate
+
+## Sub-modes
+
+### CREATE-D
+Source is structured config (or normalized text-native input) and fits builtin dotnet CLI creation.
+
+### CREATE-S
+Output needs custom OpenXML structure beyond the CLI surface.
+
+### CREATE-H
+Source is only a business brief. First produce a document plan, then pick D or S.
+
+`CREATE-H` still must choose a recipe family before backend.
+
+## Backend decision
+
+### Default to D when
+- source is structured config
+- source started as Markdown / LaTeX / HTML / RST but has been normalized into a document plan or structured config
+- output is an institutional or section-aware DOCX that the CLI surface already supports
+
+### Escalate to S when
+- the output structure is beyond the builtin dotnet CLI surface
+
+Backend choice happens after recipe choice, not before it.
+
+If both `D` and `S` are plausible, prefer `D` first and escalate to `S` only when the required graph
+is clearly beyond CLI surface.
+
+If you are hesitating between `D` and `S`, that is not a reason to stop. Start from `D` unless a
+specific structure requirement rules it out.
+
+## Hard no
+
+- Do not force D just because the builtin runtime is .NET-based.
+- Do not treat text-native source as permission to route CREATE into pandoc; for formal CREATE_DOCX,
+  normalize first, then write through `D` or `S`.
+- Do not skip recipe selection and jump straight into OpenXML values from memory.
+
+## After writing
+
+- ordinary creation -> run `normal` acceptance from `acceptance.md`
+- multi-section / layout-sensitive creation -> run `strict` acceptance from `acceptance.md`
+- if strict applies, rendered acceptance is mandatory after write

package/server/assets/skills/docx/docs/task-edit-fill.md

@@ -0,0 +1,69 @@
+# Task: EDIT_FILL_DOCX
+
+Use this task family when the source DOCX remains the same document object and the user wants
+content-level mutation.
+
+## Required inputs
+
+- one source `.docx`
+- an edit instruction that can be normalized into operations such as:
+  - replace text
+  - fill anchor
+  - insert block
+  - fill table rows
+  - remove block
+  - update header/footer text
+
+## Evidence profile
+
+Default evidence: **content + structure**.
+Add rendered truth when:
+- the complaint is already visual
+- the mutation touches section-sensitive areas
+- the mutation affects headers/footers, TOC, numbering, or large tables
+
+## Sub-modes
+
+### Text replacement
+Simple content replacement while preserving formatting boundaries.
+
+### Placeholder fill
+Fill anchors after atomicity verification.
+
+### Block insert
+Insert new content relative to a heading, anchor, or exact paragraph locator.
+
+### Table expansion
+Clone or fill rows while preserving table-local style behavior.
+
+### Structural edit
+Section, header/footer, TOC, or numbering work. This is still edit/fill as a task family, but it is
+no longer a low-risk local patch.
+
+## Backend selection
+
+### Pick X when
+- the operation is deterministic, local, and low-topology
+- examples: anchor validation, merge-runs preview, local anchor fill, direct-format stripping,
+  a constrained local replace
+
+### Pick D when
+- the edit needs builtin CLI support or preservation guarantees
+- examples: replace-text, fill-placeholders, header/footer update, CLI-supported edits
+
+### Pick S when
+- the edit requires byte-level graph control outside both X and D
+
+### Pick D or S after regeneration normalization
+- if “edit” actually means “regenerate from the real Markdown / LaTeX source”, do not treat that as a
+  pandoc edit path; reclassify into CREATE_DOCX or the regeneration path, normalize first, then pick `D`
+  or `S`
+
+## Hard no
+
+- Never use P to edit a Word-authored DOCX in place.
+- Never use X for section topology, header/footer graph edits, numbering rebuilds, or relationship rewrites.
+
+## Acceptance profile
+
+`normal`, escalating to rendered verification when visual risk exists.

package/server/assets/skills/docx/docs/task-read-content.md

@@ -0,0 +1,148 @@
+# Task: READ_CONTENT
+
+Use this task family when the user wants to know what the DOCX says, not how Word structures it and
+not whether the pages look correct.
+
+## Required inputs
+
+- one source `.docx`
+- the user's reading goal: summarize, quote, search, extract, retrieve, or locate content
+
+## Evidence profile
+
+Default evidence: **content truth** only.
+
+Escalate out of this task if the user's real question is about:
+- TOC or numbering -> `READ_STRUCTURE`
+- styles or section topology -> `READ_STRUCTURE`
+- layout or page truth -> `READ_RENDERED`
+
+## Execution path
+
+The bundled extractor is the default. It walks `word/document.xml`, the document
+relationships, `footnotes.xml`, `endnotes.xml`, `comments.xml`, every
+`header*.xml` / `footer*.xml`, and resolves `mc:AlternateContent` so drawing
+text isn't double-counted. It is stdlib-only — no `python-docx`, `pandoc`, or
+`dotnet` required.
+
+### Option A — bundled extractor (default)
+
+```bash
+python3 <skill_dir>/scripts/extract_docx_text.py <input.docx>
+```
+
+What you get out of the box (text mode):
+
+- paragraphs in reading order
+- hyperlinks rendered inline as ``label (→ target)`` (external URLs from
+  ``word/_rels/document.xml.rels``; internal anchors as ``#bookmark``)
+- footnote markers ``[fn:N]`` and endnote markers ``[en:N]`` inline, with the
+  footnote / endnote bodies listed in a trailing ``FOOTNOTES`` / ``ENDNOTES``
+  section
+- comment markers ``[cmt:N]`` inline, with author + date + text in a trailing
+  ``COMMENTS`` section
+- tables rendered row-by-row as ``cell | cell | cell`` lines (one table row =
+  one line, never collapsed into a single string)
+- text inside drawing shapes / VML text boxes listed in a ``TEXT BOXES``
+  section (so the body text isn't polluted with anchored shape text)
+- a ``WARNINGS`` section that loudly reports what was deliberately dropped (e.g.
+  tracked deletions when ``--revisions accept`` is in effect)
+
+Track-changes read policy is selectable:
+
+- ``--revisions accept`` (default) — keep insertions, drop deletions
+- ``--revisions reject`` — drop insertions, keep deletions
+- ``--revisions raw`` — keep both, no warning
+
+Optional flags (default behaviour shown above):
+
+- ``--include-headers`` / ``--include-footers`` — section-attributed header /
+  footer text (``section=N role=default|first|even`` per part)
+- ``--no-footnotes`` / ``--no-endnotes`` / ``--no-comments`` /
+  ``--no-textboxes`` / ``--no-hyperlinks`` — drop a side channel; a warning is
+  emitted when the body actually referenced it
+- ``--no-comment-markers`` — drop the inline ``[cmt:N]`` markers but keep the
+  comments section
+
+### Option A.json — structured content truth
+
+```bash
+python3 <skill_dir>/scripts/extract_docx_text.py <input.docx> --format json
+```
+
+Use this when you need a machine-readable view (RAG, audit, diff). Schema:
+
+| Key | Meaning |
+|------|---------|
+| ``file`` | absolute input path |
+| ``options`` | options actually applied |
+| ``body`` | ordered list of ``paragraph`` / ``table`` blocks |
+| ``body[].runs`` | per-run text + ``revision`` (none/ins/del) + hyperlink key |
+| ``body[].hyperlinks`` | per-paragraph hyperlinks (text + target + anchor + tooltip) |
+| ``body[].footnoteRefs`` / ``endnoteRefs`` / ``commentRefs`` | ids referenced from the paragraph |
+| ``footnotes`` / ``endnotes`` / ``comments`` | full text of each side-channel entry, with author / date for comments |
+| ``hyperlinks`` | every external hyperlink in document order |
+| ``textboxes`` | text from drawing shapes / text boxes |
+| ``headers`` / ``footers`` | per-section, per-role part text |
+| ``revisions`` | ``{policy, rawInsertions, rawDeletions, retainedInsertions, retainedDeletions}`` |
+| ``warnings`` | anything we deliberately did not silently drop |
+
+### Option A.markdown — Markdown digest
+
+```bash
+python3 <skill_dir>/scripts/extract_docx_text.py <input.docx> --format markdown
+```
+
+Light heading + table + footnote / comment Markdown. Use this when feeding the
+content downstream into a Markdown-native reviewer.
+
+### Option B — pandoc to Markdown
+
+```bash
+pandoc -f docx -t markdown <input.docx>
+```
+
+Use this when you specifically need pandoc's heading / list / image embedding
+behaviour and `pandoc` is already available. Note that pandoc collapses several
+of the side channels (text boxes, comment ranges, header/footer attribution),
+so it is not a substitute for Option A.
+
+## Output contract
+
+Return:
+
+- the requested summary / quote / search result
+- enough local context to show where the text came from (paragraph index, table
+  cell address, "footnote N", "comment by Alice", "header section 0", etc.)
+- the ``warnings`` block if anything was deliberately dropped — never silently
+  hide it from the user
+- no invented structural claims unless you also ran `READ_STRUCTURE`
+
+## Acceptance profile
+
+`light`
+
+## Coverage matrix
+
+| Content channel | Status | Notes |
+|-----------------|--------|-------|
+| paragraphs | ✅ | reading-order, style id + style name |
+| tables | ✅ | structured rows × cells × paragraphs (json) and one row per line (text) |
+| hyperlinks | ✅ | text + external target via rels; internal anchors as ``#name`` |
+| footnotes | ✅ | inline ``[fn:N]`` + body |
+| endnotes | ✅ | inline ``[en:N]`` + body |
+| comments | ✅ | inline ``[cmt:N]`` + author / date / body |
+| track changes | ✅ | selectable policy: accept / reject / raw |
+| headers / footers | ✅ | opt-in (`--include-headers` / `--include-footers`); per section + role |
+| text boxes / shape text | ✅ | listed under ``TEXT BOXES``; mc:AlternateContent collapsed first |
+| field codes (`fldSimple`, `instrText`) | partial | instructions captured under ``fields``; the *result* run is captured as visible text |
+| embedded objects / OLE | not surfaced | escalate to ``READ_STRUCTURE`` to inspect |
+| numbering / list level meaning | not surfaced | escalate to ``READ_STRUCTURE`` |
+| images / pictures | not surfaced | escalate to ``READ_RENDERED`` |
+| equations / OMML | not surfaced | content truth keeps the surrounding text only |
+
+## Common mistake
+
+Do not answer “why is the TOC wrong” or “what section owns this header” from extracted text alone.
+Do not silently drop tracked deletions when answering "what does this document say" — pick a
+policy and report it.