dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,38 @@
+# Footnotes and endnotes
+
+**Goal.** Attach a reference note at exactly one place in the text, and keep the note body in the notes part rather than in the body.
+
+Notes live outside the flow: `word/footnotes.xml` (or `word/endnotes.xml`) holds the text, and a `w:footnoteReference w:id="N"` run in the body points at it. The part also needs the separator notes (ids -1 and 0) or Word repairs the file.
+
+## Insert a note
+
+Put a marker where the reference belongs, then convert it:
+
+```bash
+"<python>" "<skill>/scripts/insert_note.py" "<file.docx>" --kind footnote --text "Source: ledger extract, June." --out "<file-notes.docx>"
+```
+
+The marker defaults to `[[NOTE]]`; change it with `--marker`. The script creates the notes part (with separator and continuation-separator entries) if it does not exist, allocates the next free id, splits the surrounding run so only the marker is replaced by the reference, and styles the note text with `FootnoteText` and the reference with `FootnoteReference`. `--kind endnote` writes to the endnotes part instead.
+
+## Report
+
+```bash
+"<python>" "<skill>/scripts/footnotes_report.py" "<file.docx>"
+```
+
+Lists each note's text, how many references point at it, and which references dangle or which notes are orphaned. Orphans appear when content is copied between documents; dangling references appear when a note is deleted but its marker stays.
+
+## Renumbering
+
+Note ids are numbers, but Word displays them sequentially by position, so inserting a note in the middle renumbers the rest automatically. Do not try to keep ids in display order — keep them unique.
+
+## Verify
+
+Render the page with the note and read the note area: the marker should sit immediately after the word it annotates, with no space before it, and the note text should match. Also check the last page — an endnote section that lands after the signature block is a layout defect.
+
+## Pitfalls
+
+- A footnote reference inside a table cell is allowed; inside a header it is not.
+- Copying a paragraph with `python-docx` copies the reference but not the note body — recreate the note in the target document.
+- Deleting note text without deleting the reference leaves a broken document that opens with a repair prompt.
+- Field instructions are not allowed in the note separator; keep the built-in separator notes untouched.

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

@@ -0,0 +1,48 @@
+# Forms and content controls
+
+**Goal.** Fill or create a structured field — a name, a date, a choice — as a real content control, so the value is labelled in the XML instead of being plain text between two labels.
+
+A content control is `w:sdt` with `w:sdtPr` (tag, alias, id, type) and `w:sdtContent`. The tag is the machine name; the alias is what Word shows in the properties panel.
+
+## List what exists
+
+```bash
+"<python>" "<skill>/scripts/content_controls.py" list "<file.docx>"
+```
+
+Reports each control's part, tag, alias, id, type and current text, across the body, headers and footers. `--no_headers_footers` limits it to the body.
+
+## Create
+
+```bash
+"<python>" "<skill>/scripts/content_controls.py" create "<file.docx>" \
+  --placeholder "Client name" --tag client_name --alias "Client name" --out "<file-form.docx>"
+```
+
+The script wraps the paragraph containing the placeholder text (or appends a new one) in a `w:sdt`, so the field is a drop-in replacement for a typed placeholder line. `--json` prints the created control instead of a summary.
+
+## Fill
+
+```bash
+"<python>" "<skill>/scripts/content_controls.py" set "<file-form.docx>" \
+  --set client_name="Northwind" --set period="Q2 FY26" --out "<file-filled.docx>"
+```
+
+`--set TAG=VALUE` matches on the tag. The command exits 1 and lists `missing_tags` when a tag is not present — that is the check for a scripted fill, so a typo does not silently write nothing.
+
+## Design
+
+- One control per value; do not put a whole table into one control.
+- Tag in `snake_case`, alias in the user's words.
+- A choice control lists its options in `w:sdtPr`; a date control has `w:date` with a format. Plain text is the default and the safest thing to generate.
+- Leave the surrounding labels in the body text; the alias is visible only in Word's properties panel.
+
+## Verify
+
+`content_controls.py list` after filling: tags present with the expected text. Then render — a control's content is normal text on the page, so the visual check is that nothing shifted and the filled value fits its line.
+
+## Pitfalls
+
+- Deleting an `sdt` wrapper while trying to "clear" a field deletes the value and the structure; set the text instead.
+- Two controls with the same tag make `--set` ambiguous; the script updates the first and reports the rest.
+- A content control cannot span two paragraphs without `w:sdtContent` holding both — keep one value per paragraph when generating.

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

@@ -0,0 +1,55 @@
+# Headings and numbering
+
+**Goal.** A single outline a reader can follow and Word can turn into a TOC: no skipped levels, no headings faked with bold text, consistent spacing.
+
+Heading level comes from the paragraph style (`Heading 1`…`Heading 9`, `Title` uses outline level 0), not from size or weight. `heading_audit.py` reads that structure and flags the common breakages.
+
+## Audit
+
+```bash
+"<python>" "<skill>/scripts/heading_audit.py" "<file.docx>" --max_findings 20
+```
+
+Findings:
+
+- `skipped_level` — a level 3 heading directly under a level 1. Fix by inserting the missing level or by promoting the deeper heading.
+- `empty_heading` — a heading with no text; a stale outline entry that will appear in the TOC as a blank line.
+- `manual_formatting` — a real heading that also carries direct bold or a large font size; the style already does that, so the extra formatting fights restyling.
+- `heading_not_styled` — body text that looks like a heading (bold, 13pt+) but is styled `Normal`. This is the expensive one: the TOC misses it and every later style change misses it.
+
+## Fix
+
+Prefer styles over direct formatting. `style_normalize.py --clear_paragraph_format --enforce_heading_spacing` strips direct run formatting and sets standard space-before/after on headings:
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-fixed.docx>" --clear_paragraph_format --enforce_heading_spacing
+```
+
+For a heading that is only bold text, promote it to the right style rather than making it bolder:
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+d = Document(r"<file.docx>")
+for p in d.paragraphs:
+    if p.text.strip() == "<exact heading text>":
+        p.style = d.styles["Heading 1"]
+d.save(r"<file-fixed.docx>")
+PY
+```
+
+## Numbered headings
+
+Numbering is a numbering definition attached to the heading style, not text like `1.2`. Two consequences: a typed number keeps lying after an insert, and a numbered outline needs `numPr` on the style with an `abstractNum` that uses `%1.%2` level text. When a document must have numbered sections and the original numbering is lost, restore the style's `numPr` rather than typing numbers into the headings.
+
+Lists are the same machinery at body level: `List Number` restarts only when the numbering definition says so, which is why two separate numbered lists sometimes continue each other.
+
+## Verify
+
+`heading_audit.py` should exit 0, then render and read the page: heading hierarchy visible, no orphaned heading at the bottom of a page (`keepNext`), and the same spacing before every heading of a level.
+
+## Pitfalls
+
+- Changing a heading's style does not change its text, but it can change its size and colour — re-render.
+- A heading inside a table cell still counts for the outline, which is rarely wanted; use a bold paragraph there.
+- Copying a heading from another document brings a direct-formatting payload with it; run the audit afterwards.

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

@@ -0,0 +1,63 @@
+# Images and figures
+
+**Goal.** Pictures that are described for screen readers, sized for the page, and captioned consistently.
+
+An inline picture is a `w:drawing` containing `wp:inline` (or `wp:anchor` for a floating one), with the picture relationship in `a:blip r:embed` and the display size in `wp:extent` (EMU). Alt text lives in `wp:docPr @descr`.
+
+## Audit
+
+```bash
+"<python>" "<skill>/scripts/images_audit.py" "<file.docx>" --max_rows 20
+```
+
+For every image: the part it sits in, its name, the media file behind it, its size in inches, and the alt text. Findings are `missing_alt` and `oversized` (wider than the text block). The workable check is "does the alt text describe what a reader loses if the picture is gone".
+
+## Fix alt text
+
+```bash
+"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --fix_image_alt from_filename --out "<file-fixed.docx>"
+```
+
+That writes the file name when no description exists — better than nothing, not as good as real text. For real descriptions, set `descr` yourself; decorative images get an empty description and `title`, while informative images get a sentence:
+
+```bash
+"<python>" - <<'PY'
+import sys
+from pathlib import Path
+sys.path.insert(0, r"<skill>/scripts")
+import docx_kit as kit
+d = kit.Docx(r"<file.docx>")
+for doc_pr in d.xml("word/document.xml").iter(kit.q("docPr", kit.WP)):
+    if doc_pr.get("name") == "Picture 3":
+        doc_pr.set("descr", "Bar chart: revenue by region, EMEA ahead of APAC.")
+out = Path(r"<file-fixed.docx>")
+d.save(out)
+print("saved", out)
+PY
+```
+
+## Insert
+
+```bash
+"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
+```
+
+```json
+{ "type": "image", "path": "<absolute.png>", "width": 5.5 }
+```
+
+Width is in inches; the height follows the aspect ratio. An image wider than the text block gets clipped or shrinks unpredictably — 5.5in is a safe full-width figure on Letter with 1in margins.
+
+## Figures
+
+Caption a picture the same way as a table (`tasks/captions_crossrefs.md`): `captions_and_crossrefs.py --figures` adds `Figure N` with a `SEQ` field and a `figN` bookmark. Keep the caption in the same block so the figure and its caption do not separate across a page break.
+
+## Verify
+
+Render and read the page: the image is not stretched, not blurry beyond the source resolution, not clipped at the margin, and its caption sits under it. Add alt text as a separate check — the render cannot show it.
+
+## Pitfalls
+
+- Cropping in Word is not lossy for the file but changes the displayed extent; alt text and size checks still apply.
+- A floating image (`wp:anchor`) can overlap text at any zoom level; prefer inline for documents that will be edited.
+- Replacing an image file in `word/media` in place keeps the relationship but not the dimensions — the extent is stored separately.

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

@@ -0,0 +1,43 @@
+# Merge documents
+
+**Goal.** Put one document after another and keep both looking the same — styles, numbering, images, hyperlinks — instead of pasting content that loses half of it.
+
+Concatenating packages by hand fails on the details: style ids collide, `numId` values point at the wrong list, media parts need new names and relationships, and `r:id` values are document-scoped. Word also requires one `sectPr` at the end of the body, so the appended content has to land before it.
+
+## Append
+
+```bash
+"<python>" "<skill>/scripts/merge_docx_append.py" "<base.docx>" "<addition.docx>" --out "<merged.docx>"
+```
+
+What it carries across: body content (minus the addition's final `sectPr`), media parts renamed under `word/media` with fresh relationships and content types, style definitions referenced by the copied content (following `basedOn`/`next`/`link`), numbering definitions rebuilt with fresh ids and every `w:numId` rewritten, and hyperlink relationships recreated as external relationships.
+
+Drawings are refused by default: a floating image or a text box carries anchor geometry tied to the original page. Pass `--allow_drawings` when the user accepts that the layout may shift, then check that page carefully.
+
+## Merge into a template
+
+The usual job is "put these sections into the house template". Apply the template first, then append, so the appended content inherits the template's style ids:
+
+```bash
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
+"<python>" "<skill>/scripts/merge_docx_append.py" "<draft-styled.docx>" "<section2.docx>" --out "<merged.docx>"
+```
+
+Then normalize direct formatting so the merged content matches:
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<merged.docx>" --out "<merged-final.docx>" --clear_paragraph_format
+```
+
+## Verify
+
+- Page count should equal the sum of the inputs, unless a page break changed.
+- Headers and footers come from the base document; say so if the addition had its own.
+- Render and read the join: the page where the second document starts often shows a stray page break or a heading that lost its style.
+- `style_lint.py` on the merged file catches undefined style references imported from the addition.
+
+## Pitfalls
+
+- Footnotes and comments in the addition are not merged; port them deliberately if they must survive.
+- `w:id` values for bookmarks and comments can collide across documents; the merge keeps ids and names as they were.
+- A landscape section in the addition is not carried over — section properties were dropped with the `sectPr`.

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

@@ -0,0 +1,38 @@
+# Internal navigation
+
+**Goal.** Let a reader jump around a long document — from a contents list to a section, and back — without relying on the TOC field being recalculated.
+
+A hyperlink to a place inside the document is `w:hyperlink w:anchor="bookmark"`; the target is a `w:bookmarkStart`/`w:bookmarkEnd` pair with that name. Both live in the body, so an export to PDF keeps the links.
+
+## Build a navigation set
+
+```bash
+"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2 \
+  --toc_title "Contents"
+```
+
+What it does, in order:
+
+1. Bookmarks every heading as `nav_h1`, `nav_h2`, … using its outline level.
+2. Inserts a `Contents` heading and a quick-link bar (one link per heading) at the top.
+3. Indents each contents entry by 360 twips per level so the hierarchy is visible.
+4. Appends a small `Back to contents` link after each heading.
+5. Bookmarks the top, the contents list and the bottom (`nav_top`, `nav_toc`, `nav_bottom`).
+
+Flags: `--no_quicklinks` skips the horizontal bar, `--no_back_to_toc` skips the per-heading back link, `--no_top_bottom` skips the two edge targets.
+
+The script reports `missing` when a link target could not be created — read that list, because a link without a bookmark is dead in Word and looks fine in a render.
+
+## Static versus field-driven
+
+`internal_nav.py` writes literal entries: it costs a rebuild when headings change, and it always looks the same in every renderer. `insert_toc.py` writes a live `TOC` field: it updates itself but needs a recalculation before it shows anything useful. A document that will be edited repeatedly wants the field; a document going out as a PDF export wants the static list.
+
+## Verify
+
+Render, then click through the pages you can see: entry indentation, that the contents heading is styled as a heading, and that `Back to contents` did not push a paragraph onto a new page. Dead anchors do not show in a screenshot — check `bookmarkStart` names against the `w:anchor` values when the script reports a miss.
+
+## Pitfalls
+
+- Bookmarks must be unique per document; re-running the script on its own output creates `nav_h1` twice, so start from the original.
+- A hyperlink anchor is case-sensitive.
+- Link styling comes from the `Hyperlink` character style; if links look like body text, the style is missing, not the link.

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

@@ -0,0 +1,45 @@
+# Privacy: metadata and residue
+
+**Goal.** A file that carries only the content the user meant to send: no author name, no tracked review history, no comments, no template identity, no editing session ids.
+
+`.docx` stores more than the text: `docProps/core.xml` (author, last modifier, title, keywords, description), `docProps/app.xml` (company, manager, template), `docProps/custom.xml`, `word/comments.xml`, revision data and per-author `w:rsid` attributes.
+
+## Scrub metadata
+
+```bash
+"<python>" "<skill>/scripts/privacy_scrub.py" "<file.docx>" --out "<file-clean.docx>"
+```
+
+Clears creator, last-modified-by, keywords, description, subject, title, category, company, manager and application; resets the revision counter; drops `docProps/custom.xml` and its relationships and content-type override; strips `w:rsid*` attributes, `w:proofErr` and `w:lastRenderedPageBreak` across the Word parts.
+
+`--keep_title` leaves the title in place when the title is real content the user wants.
+
+## The rest of the residue
+
+| Residue | Command |
+|---|---|
+| Comments and their authors | `comments_strip.py` |
+| Tracked changes and reviewer names | `accept_tracked_changes.py --mode accept` (or reject) |
+| Watermarks naming the old client | `watermark_audit_remove.py --mode remove` |
+| Emails and phone numbers in the text | `redact_docx.py` |
+
+Run them in that order — scrub metadata, resolve markup, then redact the text that survived.
+
+## Check before delivery
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" parts '<file-clean.docx>'
+"<python>" "<skill>/scripts/docx_kit.py" xml '<file-clean.docx>' docProps/core.xml
+```
+
+`parts` shows whether `docProps/custom.xml` or `word/comments.xml` still exist; the core part shows what a recipient would see in File > Info. Both are cheap and both catch the mistake the scripts did not.
+
+## Verify
+
+Metadata is not visible in a page render. Verify with the commands above, and render to be sure the document still looks right after the scrub — clearing `w:lastRenderedPageBreak` can change where a viewer chooses to break a long line.
+
+## Pitfalls
+
+- Author names also appear in comment and revision entries, not only in core properties.
+- `docProps/app.xml` names the editing application; it is regenerated on next save by whatever app opens the file.
+- Removing revision ids does not undo content — the text is still there.

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

@@ -0,0 +1,41 @@
+# Restrict editing
+
+**Goal.** Stop a reviewer from changing the body while still letting them comment or track changes — the "send for review" state, not encryption.
+
+Editing restrictions live in `w:documentProtection` inside `word/settings.xml`. The modes are `readOnly`, `comments`, `trackedChanges`, `forms`, plus `enforcement` to switch the restriction on. This is a guardrail against accidental edits; it does not encrypt content and a determined reader can remove it.
+
+## Set a mode
+
+```bash
+"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode comments --out "<file-review.docx>"
+"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode readOnly --no_enforce --out "<file-open.docx>"
+```
+
+Modes and aliases: `off`/`none`, `readOnly`/`read_only`, `comments`/`comment`, `trackedChanges`/`tracked_changes`, `forms`/`form`. `--no_enforce` writes the setting without switching it on, which is useful when the opening dialog should be avoided.
+
+`--hash` also writes a password hash (SHA-512, 100000 spins; `--salt`, `--spin_count` to change it). Be honest with the user: the hash deters casual edits, it is not encryption, and losing the password means the restriction has to be stripped from the XML.
+
+## Which mode to pick
+
+| Intent | Mode |
+|---|---|
+| Review comments only, no text edits | `comments` |
+| All edits should be tracked | `trackedChanges` |
+| Fill a form, nothing else | `forms` |
+| View only | `readOnly` |
+
+## Remove
+
+```bash
+"<python>" "<skill>/scripts/set_protection.py" "<file-protected.docx>" --mode off --out "<file-open.docx>"
+```
+
+## Verify
+
+`docx_kit.py xml '<file.docx>' word/settings.xml | grep documentProtection` shows the element and its enforcement attribute. Then open behaviour matters, not the page — render will not show a restriction. Say which mode you applied, and that removing it needs the same script or Word's Review pane.
+
+## Pitfalls
+
+- Protected documents that also contain tracked changes and comments often prompt on open; apply the restriction last.
+- `forms` mode without form fields leaves a document nobody can edit usefully.
+- Protection marked with a hash cannot be turned off in Word without the password, but `--mode off` still clears it — that is why it is a guardrail, not security.

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.