dsh-office-kit 0.1.0 → 0.3.0

package/assets/skills/office-documents/tasks/read_review.md

@@ -0,0 +1,50 @@
+# Read and review a file
+
+**Goal.** Understand an existing document before touching it: what it contains, how it is structured, and what is wrong with it.
+
+## Read the content
+
+```bash
+"<python>" "<cli>" docx read --input "<file.docx>"
+```
+
+Returns the title, author, paragraphs with their styles, headings, tables, image and equation counts, and page dimensions. Use it as the first look, including for files you produced earlier in the session.
+
+## Read the structure
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" parts '<file.docx>'    # every package part and its size
+"<python>" "<skill>/scripts/docx_kit.py" text '<file.docx>'     # paragraphs with style and outline level
+"<python>" "<skill>/scripts/docx_kit.py" xml '<file.docx>' word/document.xml
+```
+
+`parts` tells you which features exist at all (a `comments.xml` means the file carries comments; its absence means none, even if the user says otherwise). `text` is faster than reading raw XML when you only need the words and their heading levels.
+
+## Audit what is there
+
+| Question | Command |
+|---|---|
+| Are headings consistent and styled? | `heading_audit.py` |
+| Is the prose styled directly instead of by style? | `style_lint.py` |
+| Are images described, sized sensibly? | `images_audit.py` |
+| Is the page setup sane? | `section_audit.py` |
+| Are there fields, TOC entries, cross-references? | `fields_report.py` |
+| Are there footnotes or endnotes? | `footnotes_report.py` |
+| What comments exist, and on what text? | `comments_extract.py` |
+
+Every audit script prints JSON and exits non-zero when it found something, so the exit code alone tells you whether the document needs attention. Read the `findings` array rather than the exit code when you need the reason.
+
+## Review for the user
+
+When the job is "review this document" rather than "change it":
+
+1. Read the text, not just the audits. Point out the argument, not only the formatting.
+2. Separate defects (broken table, skipped heading level, missing alt text) from style preferences.
+3. Cite locations by section heading and paragraph text — Word has no stable page numbers.
+4. Offer the fix as a concrete next action, with the command that performs it.
+
+## Pitfalls
+
+- `docx read` shows the body only; headers, footers, footnotes and comments need `docx_kit.py xml` or the dedicated report scripts.
+- Tracked changes are visible as plain text in a read; use `accept_tracked_changes.py --mode report` to see what is proposed.
+- A field's displayed text is a cached result. `fields_report.py` shows the instruction, which is the truth.

package/assets/skills/office-documents/tasks/redaction_anonymization.md

@@ -0,0 +1,42 @@
+# Redaction and anonymisation
+
+**Goal.** Remove personal data — addresses, phone numbers, names, account references — from a document before it leaves the organisation, in the text and in the places text hides.
+
+Text lives in `w:t` (and `w:delText` for deletions, `w:instrText` for field instructions). A redaction that only rewrites paragraphs via `python-docx` misses headers, footers, footnotes and comments.
+
+## Redact
+
+```bash
+"<python>" "<skill>/scripts/redact_docx.py" "<file.docx>" "<file-redacted.docx>" --emails --phones
+"<python>" "<skill>/scripts/redact_docx.py" "<file.docx>" "<file-redacted.docx>" --pattern "ACCT-\d{6}" --replacement "<account>"
+```
+
+- Default run covers emails and phone numbers; add `--pattern` (repeatable) for account numbers, case ids, postcodes.
+- `--mask_char *` keeps the shape of the value visible (`***@***.com` style), `--replacement` swaps in a token, `--no_preserve_length` stops padding to the original length.
+- `--include_comments` also rewrites `word/comments.xml`; without it, comments keep the original text.
+- Applied to body, every header and footer, footnotes and endnotes.
+
+Matching happens per text run, because merging runs would destroy the surrounding formatting. A value split across runs (bolded digits inside a phone number) is not found — an acceptable trade only if you check the result; when the file mixes formatting inside the sensitive value, flatten that paragraph first (`tasks/style_lint_normalize.md`).
+
+## Redaction versus anonymisation
+
+Redaction removes the value; anonymisation replaces it consistently. If the same account number appears four times and the argument depends on it matching, replace all occurrences with the same token rather than `[redacted]` every time — `--replacement "<account-A>"` per pattern does that.
+
+## Check the whole file
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" text '<file-redacted.docx>' --part word/footnotes.xml
+"<python>" "<skill>/scripts/docx_kit.py" xml '<file-redacted.docx>' word/document.xml | grep -c "example.com"
+```
+
+A grep over dumped XML is the honest check: run it for each sensitive term, across the document, header, footer, footnote and comment parts.
+
+## Verify
+
+Render, then read the pages the data appeared on. A redaction that changed the line length enough to shift the layout is worth a look; a redaction that left a `<w:t>` intact shows up in the grep, not the page.
+
+## Pitfalls
+
+- Field results and field instructions can both contain data; the script rewrites `w:t` and `w:delText` only.
+- Images are not scanned — a screenshot of a spreadsheet is not redacted by any text pass. Say so plainly.
+- Charts store category labels in `word/charts/*.xml`; inspect those parts when a chart carried the sensitive data.

package/assets/skills/office-documents/tasks/sections_layout.md

@@ -0,0 +1,54 @@
+# Sections and page layout
+
+**Goal.** Page size, orientation, margins, columns, headers and footers that are deliberate at every point in the document, including after a mid-document change.
+
+Page setup lives in a `w:sectPr` element. The last one sits at the end of the body; earlier ones sit inside the last paragraph of the section they end (`w:pPr/w:sectPr`). That is why adding a landscape page means adding a section break before and after, not changing one global setting.
+
+## Audit
+
+```bash
+"<python>" "<skill>/scripts/section_audit.py" "<file.docx>"
+```
+
+Per section: width and height in inches, orientation derived from them, every margin, column count, section start type, header and footer parts referenced, `titlePg` (different first page) and any explicit page-number start.
+
+Findings worth fixing: `mixed_page_sizes` (sections that disagree, usually a template artefact), `narrow_text_column` (left plus right margin eats most of the width), `portrait_wider_than_letter`.
+
+## Common changes
+
+| Wanted | Route |
+|---|---|
+| New document defaults | `docx create` spec: `page_size`, `orientation`, `top_margin`/`bottom_margin`/`left_margin`/`right_margin` in inches |
+| A landscape page inside a portrait document | two section breaks with a landscape section between them |
+| Different first page header | set `titlePg` on the section and fill `first_page_header` |
+| Continuous section change (e.g. narrower margins) | `w:type val="continuous"` on the new section |
+
+Landscape and columns are section properties, so a snippet is often faster than a flag:
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+from docx.enum.section import WD_ORIENT, WD_SECTION
+d = Document(r"<file.docx>")
+s = d.add_section(WD_SECTION.NEW_PAGE)
+s.orientation = WD_ORIENT.LANDSCAPE
+s.page_width, s.page_height = s.page_height, s.page_width
+d.save(r"<file-edited.docx>")
+PY
+```
+
+Swap the width and height explicitly: setting the orientation alone does not swap them.
+
+## Headers and footers
+
+A header is `word/headerN.xml` referenced from `w:headerReference`. Headers inherit from the previous section unless the section sets `headerReference` itself. Page numbers go in the footer as a `PAGE` field, page counts as `NUMPAGES`; `docx_ooxml_patch.py --add-page-numbers` writes one.
+
+## Verify
+
+Render and flip through every page, including the ones after a section break: header content, page numbers, orientation, margins. A section break that leaves an empty page is the classic defect — check for a stray empty paragraph carrying the break.
+
+## Pitfalls
+
+- `w:pgSz` is width then height; a portrait page taller than wide is normal, a "landscape" 11×8.5 that still says portrait in the panel means only the size changed.
+- `titlePg` without filling the first-page header leaves page one with a blank header, not with the normal one.
+- Deleting a section break merges two sections and keeps the earlier section's settings; edit before deleting.

package/assets/skills/office-documents/tasks/style_lint_normalize.md

@@ -0,0 +1,44 @@
+# Styles: lint and normalize
+
+**Goal.** Formatting that comes from styles, not from pressing bold on each run, so the document can be restyled, exported and understood later.
+
+A paragraph carries a `pStyle` reference; a run carries an `rStyle` plus direct formatting (`w:b`, `w:i`, `w:sz`, `w:color`). Direct formatting wins over the style, which is why a "make all body text 11pt" request fails on the runs someone bolded and resized by hand.
+
+## Lint
+
+```bash
+"<python>" "<skill>/scripts/style_lint.py" "<file.docx>" --json "<report.json>"
+```
+
+Findings: undefined style references, headings carrying their own paragraph or run formatting, empty runs, manual bullets (`•` typed into text instead of a list style), double spaces, trailing spaces, body sizes that appear once or twice against the dominant size, tables without a style.
+
+Exit code 1 means findings; the JSON has the counts and examples, which is what you want when the number is large.
+
+## Normalize
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-clean.docx>" \
+  --clear_paragraph_format --enforce_heading_spacing
+```
+
+- `--clear_paragraph_format` strips everything from each run's `rPr` except `rStyle`, `rtl` and `lang`, and drops the paragraph-mark run properties. The style then controls the look.
+- `--enforce_heading_spacing` sets space-before/space-after per heading level and `keepNext`, so a heading cannot sit alone at the bottom of a page.
+
+Run this before applying a template; a template cannot win against direct formatting.
+
+## What "correct" looks like
+
+- Body text 11–12pt from `Normal`; headings from `Heading 1`–`Heading 3` with no direct bold or size.
+- Bold used for emphasis inside a sentence, via a character style or a single `w:b` run — not for whole paragraphs that are really headings.
+- Lists from `List Bullet` / `List Number`, never typed bullet characters.
+- One table style per document, usually `Table Grid`.
+
+## Verify
+
+Re-run `style_lint.py` (counts should drop), then render: clearing direct formatting can change the visual hierarchy when a document faked emphasis with size. Compare the rendered page with the original before you claim the clean-up is neutral.
+
+## Pitfalls
+
+- Clearing `rPr` removes field-result formatting too; re-run the field-related scripts afterwards if the number must be bold.
+- A style referenced but not defined falls back to `Normal` silently — the lint is the only warning you get.
+- `w:rsid` and proofing attributes are noise, not style; `privacy_scrub.py` removes them when the file leaves the organisation.

package/assets/skills/office-documents/tasks/tables_spreadsheets.md

@@ -0,0 +1,64 @@
+# Tables and spreadsheets
+
+**Goal.** A table that fits the page, repeats its header row across pages, and survives an edit without cells drifting out of alignment.
+
+A table's geometry is three things that must agree: the grid (`w:tblGrid`, one `w:gridCol` per column), the table width (`w:tblW`), and each cell width (`w:tcW`). When they disagree Word shows a table wider than the text block or columns that jump on the first edit.
+
+## Create
+
+```bash
+"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
+```
+
+```json
+{
+  "type": "table",
+  "headers": ["Region", "Revenue", "Growth"],
+  "rows": [["EMEA", "4.1M", "12%"], ["APAC", "3.2M", "9%"]],
+  "style": "Table Grid"
+}
+```
+
+Header cells are bold. For a document with the header repeating on every page, follow up with the a11y fix, which writes `w:tblHeader` on row 1:
+
+```bash
+"<python>" "<skill>/scripts/a11y_audit.py" "<out.docx>" --fix_table_headers first_row --out "<out-fixed.docx>"
+```
+
+## Inspect and fix geometry
+
+```bash
+"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>"
+"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>" --fix --out "<file-fixed.docx>"
+```
+
+The audit reports `tblW`, layout mode, every grid column in twips and the sum, plus the narrowest and widest cell. `--fix` writes a fixed-layout table at the text width (page width minus margins), rescales the grid proportionally and rewrites each `tcW` including `gridSpan`.
+
+Text width on Letter with 1in margins is 9360 twips — that is the number a full-width table should total.
+
+## Convert
+
+```bash
+"<python>" "<skill>/scripts/docx_table_to_csv.py" "<file.docx>" --table_index 0 --out "<table.csv>"
+"<python>" "<skill>/scripts/xlsx_to_docx_table.py" "<book.xlsx>" --sheet Revenue --out "<table.docx>" --title "Revenue by region"
+```
+
+The first flattens a Word table (expanding horizontal spans, repeating vertically merged values) for data work. The second imports a worksheet as a Word table with a bold header row and `w:tblHeader`, which is the route for "put this spreadsheet in the report" — not a screenshot and not an embedded object.
+
+## Design
+
+- Bold header row, light grey `#D9D9D9` borders, no shading inside the body.
+- Numeric columns right-aligned; text left-aligned. Thousands separators in the cells themselves.
+- Two or three columns of prose at most; a wide table wants landscape, and that means a section break (`tasks/sections_layout.md`), not a smaller font.
+- Caption above the table (`tasks/captions_crossrefs.md`), and keep it with the table.
+- Avoid vertical merges: they look fine in the file and confuse every downstream reader.
+
+## Verify
+
+Render and look at the page the table lands on: nothing spills past the right margin, header row intact, no split row across pages, and the last column not truncated. A table that fits in the XML but overflows the page is a real defect, and only the render shows it.
+
+## Pitfalls
+
+- A table inside a table cell inherits the cell width; check the outer table first.
+- `autofit` is a request, not a guarantee — fixed layout plus explicit widths is the only thing that renders the same everywhere.
+- Cell margins default to 108 twips left/right; that is padding, not missing width.

package/assets/skills/office-documents/tasks/templates_style_packs.md

@@ -0,0 +1,53 @@
+# Templates and style packs
+
+**Goal.** Make a new or existing document look like the house template, without copying the template's content into it.
+
+A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, and the body is empty. Copying the body would import placeholder text; what you actually need is the styles part, the numbering definitions they reference, and the theme.
+
+## Ask before guessing
+
+Do not invent a house style. Get from the user: heading fonts and sizes, body font and size, accent colour, margins, table style, and whether a logo or cover page is required. `references/template-elicitation.md` has the question set that produces a spec.
+
+## Apply a template
+
+```bash
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
+```
+
+The script merges the template's style definitions by `styleId` (replacing same-id definitions, appending missing ones, taking the template's `docDefaults`), and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched, so the content survives and the look changes.
+
+Then normalize so direct formatting does not override the template:
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx>" --clear_paragraph_format
+```
+
+## Restyle without a template
+
+When the user describes the style instead of supplying a file, set it on the styles rather than on runs:
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+from docx.shared import Pt, RGBColor
+d = Document(r"<draft.docx>")
+normal = d.styles["Normal"]
+normal.font.name = "Calibri"
+normal.font.size = Pt(11)
+for level, size in ((1, 18), (2, 14), (3, 12)):
+    style = d.styles[f"Heading {level}"]
+    style.font.size = Pt(size)
+    style.font.color.rgb = RGBColor(0, 0, 0)
+d.save(r"<draft-styled.docx>")
+PY
+```
+
+## Verify
+
+Render and compare against the template's own preview page by page: heading sizes, body leading, margins, table borders. A style page that looks right in a style list but wrong on the page usually means a direct-formatting run left over — run the lint.
+
+## Pitfalls
+
+- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py` to find undefined references.
+- Themes (`word/theme/theme1.xml`) carry fonts and accent colours; a style that names a theme font changes when the theme does.
+- Keeping the template's `numbering.xml` without its `abstractNum` ids produces lists that all share one counter.

package/assets/skills/office-documents/tasks/toc_workflow.md

@@ -0,0 +1,39 @@
+# Table of contents
+
+**Goal.** Put a navigable contents list at the front of the document, built from heading styles rather than typed by hand.
+
+The TOC is a `TOC` field. Word fills it in when it recalculates; the file stores the last result. A hand-typed list looks identical in a screenshot and then goes wrong on the first edit.
+
+## Insert
+
+```bash
+"<python>" "<skill>/scripts/insert_toc.py" "<file.docx>" --out "<file-toc.docx>" --levels 1-3
+```
+
+The script looks for a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`). If there is none it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and adds a short cached hint so the page is not blank before recalculation.
+
+Check that every heading you want in the list uses a heading style: `heading_audit.py` finds headings formatted by hand, which the TOC will silently skip.
+
+## Rebuild after edits
+
+If headings changed, the cached list is stale. Either ask the user to update the field in Word (right-click → Update Field), or regenerate: strip the old field with `fields_materialize.py`? — no, that freezes it. Instead delete the field paragraphs and run `insert_toc.py` again. Freezing a TOC is almost never what a reader wants.
+
+## Static contents list
+
+Sometimes the requirement really is a fixed list — a PDF export that will not be recalculated, or a template with a hand-built contents page. `internal_nav.py` builds one: a heading plus hyperlink entries to every heading, with optional back-links.
+
+```bash
+"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2
+```
+
+See `tasks/navigation_internal_links.md`.
+
+## Verify
+
+Render the first pages and read them. A TOC that shows one line of grey hint text means the field never recalculated in that renderer; a TOC that shows the old headings means the document was rendered before the field updated. Say which one happened instead of claiming the TOC is correct.
+
+## Pitfalls
+
+- TOC entries come from outline levels, not from text that merely looks like a heading.
+- A TOC inside a header or a text box does not work; it belongs in the body.
+- Level 4+ headings are excluded unless you widen `--levels`.

package/assets/skills/office-documents/tasks/verify_render.md

@@ -0,0 +1,50 @@
+# Visual verification
+
+**Goal.** See the pages before the user does. A document that parses and a document that looks right are different claims.
+
+## Render
+
+```bash
+"<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
+```
+
+Writes a PDF and one PNG per page, and prints their paths plus the renderer it used (Word via COM, or LibreOffice). Use the same command through `render_docx.py` when you want the JSON report and page list:
+
+```bash
+"<python>" "<skill>/render_docx.py" "<file.docx>" --output_dir "<render-dir>" --dpi 150
+```
+
+## Inspect
+
+Open every PNG with `read_image` and check, in this order:
+
+1. **Hierarchy** — does the page show the structure the user asked for, at a glance?
+2. **Fit** — nothing past the right margin, no clipped table column, no text over a watermark.
+3. **Breaks** — no heading alone at the bottom, no orphaned caption, no half-empty page before a section break.
+4. **Text** — the words that were meant to change did change, and nothing else moved.
+5. **Glyphs** — dashes, quotes, CJK, currency symbols and maths render, not as boxes.
+6. **Header and footer** — present, correct, not repeated on a first page that should not have it.
+
+## When no renderer exists
+
+The runtime reports `renderers.libreoffice: null` and no Office installation. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
+
+In that state:
+
+- Verify structure with `docx read`, `docx_kit.py parts|text|xml` and the audit scripts.
+- Tell the user plainly that layout was not visually verified, and offer to install Microsoft Office, WPS Office, or LibreOffice instead of describing a page you did not see.
+- Do not claim a file "looks good" from XML evidence alone.
+
+## After any script edit
+
+Re-render. Package-valid is not page-valid: a caption inserted before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible to the XML and obvious in the image.
+
+## Comparing revisions
+
+`render_and_diff.py` renders two files and writes a heatmapped difference page. Read the diff images yourself; a ratio is not a conclusion.
+
+## Pitfalls
+
+- Different renderers paginate differently. Compare like with like, and do not promise Word-perfect pagination from a LibreOffice render.
+- A render fails silently into a blank page when a font is missing; a blank page is a finding, not a rendering bug.
+- Render into a fresh directory; stale PNGs from an earlier run are the classic false pass.

package/assets/skills/office-documents/tasks/watermarks_background.md

@@ -0,0 +1,35 @@
+# Watermarks and background text
+
+**Goal.** A diagonal DRAFT / CONFIDENTIAL mark behind the page content, and the ability to find and remove one that a template left behind.
+
+A Word watermark is not a document feature with its own element: it is a VML shape (`v:shape` with `v:textpath`) in a header part, positioned behind the text. That is why it disappears if the header is replaced, and why it can appear on some pages and not others when sections have their own headers.
+
+## Add
+
+```bash
+"<python>" "<skill>/scripts/watermark_add.py" "<file.docx>" --out "<file-draft.docx>" --text "DRAFT"
+```
+
+Writes the shape into the default header, light grey, rotated -45°, behind the body. The script refuses to add a second watermark when it finds one — remove the old one first, or you get two overlapping marks.
+
+For a per-page mark across a document with several sections, each section's header needs the shape; that is a loop over sections, not one insertion.
+
+## Find and remove
+
+```bash
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode report
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx>"
+```
+
+The report lists the text of every VML text path and the part it lives in, and exits 1 when any watermark exists. `--contains` narrows to a substring, which is the case "the template says Company Confidential and it should not". Remove deletes the enclosing paragraph from the header.
+
+## Verify
+
+Render and read the pages: the mark sits behind the text (not over it), stays inside the page, and appears on every page the user expects. A watermark that vanishes on page two means that section has a different header.
+
+## Pitfalls
+
+- A watermark in a "different first page" header only shows on page one.
+- Removing the header paragraph can leave an empty header that adds vertical space; check the top margin on the rendered page.
+- An image watermark is an `v:imagedata` shape, not a text path — the report will not name it, so inspect the header XML when the visual mark is a logo.
+- Watermarks are not security. See `tasks/protection_restrict_editing.md` for what actually restricts editing.

package/assets/skills/office-documents/troubleshooting/libreoffice_headless.md

@@ -0,0 +1,47 @@
+# Rendering setup and failures
+
+## First: does this machine render
+
+```bash
+"<python>" "<cli>" status
+```
+
+Look at `renderers.libreoffice` and `microsoft_office`. Both null means `docx render` will fail — not with a corrupt file, but with `no document renderer found`. That is a setup problem, not a document problem.
+
+## LibreOffice
+
+Install LibreOffice (Windows: winget `TheDocumentFoundation.LibreOffice`), then check:
+
+```bash
+soffice --headless --version
+```
+
+If the binary is not on `PATH`, the runtime cannot find it; either add its `program` directory to `PATH` or install into the default location the runtime probes. On Windows, `soffice.com` is the console wrapper — use that one, not `soffice.exe`, when a script needs to wait for exit.
+
+## Microsoft Office
+
+When Word is installed, the CLI can drive it through COM and does not need LibreOffice. Office must be activated and able to launch without a first-run dialog; a pending activation or a modal "sign in" blocks the render forever.
+
+## Common failures
+
+| Message | Cause | Fix |
+|---|---|---|
+| `no document renderer found` | Neither installed / not on PATH | Install one, re-check `status` |
+| Render hangs | A dialog is waiting in the headless process | Kill the leftover process, add the `--headless --norestore` flags the CLI uses |
+| Blank pages | Missing font | Install the font or substitute it |
+| Text shifted | Font substitution | Compare with a render from the same renderer the user will use |
+| `soffice already running` | A user profile lock from a crashed run | Remove the stale lock file under the LibreOffice user profile, or wait for the old process to exit |
+
+## Working without a renderer
+
+Structure, text and metadata are all verifiable headlessly (`docx read`, the audit scripts, `docx_kit.py parts|text|xml`). Layout is not. In that state:
+
+1. Do the structural verification.
+2. Tell the user that page layout was not visually checked, and why.
+3. Offer the install, or ask them to open the file and say what looks wrong.
+
+Never describe a page you did not render.
+
+## Keep renders disposable
+
+Render into a fresh temp directory each time (`--out-dir`). A stale PNG from a previous run reads as a pass and is the most common false confirmation.

package/assets/skills/office-documents/troubleshooting/run_splitting.md

@@ -0,0 +1,36 @@
+# Splitting a long job
+
+A twenty-section document is not one command. Splitting it into bounded steps keeps each change verifiable and stops one failure from hiding inside a large edit.
+
+## One step per structural change
+
+1. **Plan** — the outline (headings and what each section must establish), written down before any file work.
+2. **Skeleton** — create the file with the outline only: heading blocks, no body text.
+3. **Content, in batches** — a batch per top-level section, appended with `append_blocks.py`.
+4. **Numbers** — captions, cross-references, TOC once the structure is final, never while sections are still moving.
+5. **Verify** — render, inspect, fix.
+
+## Why this order
+
+- Captions and TOC are fields over structure; running them after every batch means renumbering noise and a TOC that points at deleted headings.
+- A batch of one section is small enough to redo when the layout is wrong.
+- The skeleton proves the heading hierarchy before the text makes it expensive to change.
+
+## Batch boundaries
+
+- One section per file: `section-01.docx`, `section-02.docx`, then `merge_docx_append.py`. This is the only sane way to draft in parallel or across sessions.
+- Keep a `manifest.json` listing section files in order. Merging is then mechanical and the order is not remembered from chat.
+- Merge before numbering, not after.
+
+## When a batch fails
+
+Do not patch a large edit inside a large document. Discard the failed batch's output, fix the batch, re-apply it to the previous good file. Keep the previous good file until the batch is verified.
+
+## Context hygiene
+
+- Long sessions lose the document design. Keep the plan and the design defaults (page size, font sizes, table borders) in a file in the workspace and re-read it, rather than trusting recollection.
+- When the user changes a decision mid-job (page size, heading style), record it at the point they said it, and apply it to batches already written.
+
+## Smoke test after the join
+
+`examples/end_to_end_smoke_test.md` is the checklist to run on the merged file before it becomes a deliverable.