winter-super-cli 2026.5.15

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/fields_update.md

@@ -0,0 +1,66 @@
+# Task: Fields + update behavior (TOC / page # / refs)
+
+## Goal
+Avoid "looks wrong" renders that are actually **stale Word fields**.
+
+Common fields:
+- `PAGE` — current page number
+- `NUMPAGES` — total page count
+- `TOC` — table of contents
+- `REF` / `PAGEREF` — cross references (often "see page X")
+
+## When this matters
+- PDF/PNG render shows placeholders (e.g., TOC looks empty, refs show wrong page, page numbers all “1”).
+- The doc was modified programmatically (python-docx / OOXML patch) and then exported without a field refresh.
+- LibreOffice vs Word disagree.
+
+## What to do
+### 1) Scan for fields
+Run a quick field inventory:
+
+```bash
+python scripts/fields_report.py /mnt/data/input.docx
+```
+
+If you see `TOC`, `REF`, `PAGEREF`, `NUMPAGES`, or `PAGE`, plan for a field refresh step.
+
+### 2) Render and inspect
+
+```bash
+python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out
+```
+
+Inspect all `page-*.png` at 100% zoom.
+
+### 3) If anything is wrong: update fields in a GUI editor
+**Fast checklist (Word):**
+1. Open the DOCX in **Microsoft Word**
+2. `Ctrl+A` (select all)
+3. `F9` (Update Fields)
+4. Save
+5. Re-render with `render_docx.py`
+
+LibreOffice (GUI) can also update fields, but Word is the reference implementation.
+
+## Deterministic rendering workaround (when you can't update fields)
+If your goal is **stable PNG regression testing** (not perfect Word semantics), you can
+*materialize* some field results into literal text so headless renders won't omit them:
+
+```bash
+# Replace REF/PAGEREF blocks with their currently cached visible text
+python scripts/flatten_ref_fields.py input.docx --out ref_flattened.docx
+
+# Materialize SEQ/REF results (e.g., caption numbers / cross-refs)
+python scripts/fields_materialize.py ref_flattened.docx --out fields_materialized.docx
+```
+
+Notes:
+- This does **not** refresh TOC/PAGE/NUMPAGES; those still typically require Word/LO GUI.
+- Always render and visually verify after materialization.
+
+## Render → PNG review checklist (fields)
+- Page numbers increment correctly (footer/header)
+- Total page count (`NUMPAGES`) matches the rendered page count
+- TOC entries exist, have correct indentation, and page numbers match headings
+- Cross references (`REF`/`PAGEREF`) resolve (no "Error! Reference source not found.")
+- No placeholder text like “(TOC will populate...)” remains

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/fixtures_edge_cases.md

@@ -0,0 +1,42 @@
+# Repro Fixtures for Edge Cases (Tracked Changes, Watermarks)
+
+## Goal
+Generate small deterministic `.docx` fixtures that exercise known tricky OOXML patterns so you can test helper scripts without hand-editing XML.
+
+## Why this is useful
+- Tracked changes and watermarks are frequently the source of "looks wrong" issues.
+- Reproducing them manually is slow and error-prone.
+- A standard fixture makes smoke tests and future debugging much faster.
+
+## Generate fixtures
+```bash
+python scripts/make_fixtures.py --outdir fixtures
+```
+Produces:
+- `fixtures/tracked_changes_fixture.docx`
+- `fixtures/watermark_fixture.docx`
+
+Or generate a single fixture:
+```bash
+python scripts/make_fixtures.py --outdir fixtures --only tracked
+python scripts/make_fixtures.py --outdir fixtures --only watermark
+```
+
+## How to use fixtures
+### Tracked changes
+```bash
+python scripts/accept_tracked_changes.py fixtures/tracked_changes_fixture.docx --mode report
+python scripts/accept_tracked_changes.py fixtures/tracked_changes_fixture.docx --mode accept --out accepted.docx
+python render_docx.py accepted.docx --output_dir out_accepted
+```
+
+### Watermarks
+```bash
+python scripts/watermark_audit_remove.py fixtures/watermark_fixture.docx --mode report
+python scripts/watermark_audit_remove.py fixtures/watermark_fixture.docx --mode remove --contains DRAFT --out no_watermark.docx
+python scripts/render_and_diff.py fixtures/watermark_fixture.docx no_watermark.docx --outdir diff_watermark
+```
+
+## Render → PNG review checklist
+- Tracked-changes fixture: redlines appear in the original, and are gone in the accepted output
+- Watermark fixture: `report` finds watermark-like VML; removal yields zero hits; headers remain intact

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/footnotes_endnotes.md

@@ -0,0 +1,52 @@
+# True Footnotes / Endnotes (OOXML parts, numbering, refs)
+
+## Goal
+Add or audit **true** footnotes/endnotes in a `.docx` and verify they render correctly.
+
+## What footnotes/endnotes are (OOXML)
+Footnotes and endnotes are **not** "text in the footer." They live in separate parts:
+- `word/footnotes.xml`
+- `word/endnotes.xml`
+
+And the body refers to them using references:
+- `w:footnoteReference w:id="N"`
+- `w:endnoteReference w:id="N"`
+
+The note parts also contain required separators (`w:id=-1` and `w:id=0`).
+
+## Audit
+Use the reporter to see what a doc contains:
+```bash
+python scripts/footnotes_report.py input.docx
+```
+
+## Insert a note (minimal helper)
+This repo includes `insert_note.py` which patches OOXML to insert a note.
+
+1. Add a marker into the document where you want the reference:
+- `[[FN]]` for a footnote
+- `[[EN]]` for an endnote
+
+2. Insert the note:
+```bash
+python scripts/insert_note.py input.docx --kind footnote --marker "[[FN]]" --text "Footnote text" --out with_fn.docx
+python scripts/insert_note.py input.docx --kind endnote  --marker "[[EN]]" --text "Endnote text"  --out with_en.docx
+```
+
+3. Render → PNG review:
+```bash
+python render_docx.py with_fn.docx --output_dir out_fn
+```
+
+## Render → PNG review checklist
+- Footnote/endnote marker appears in the body where expected
+- Footnote text appears at page bottom (footnotes) or note section (endnotes)
+- Numbering is correct (no duplicates, starts at 1)
+- Long notes wrap nicely (no overlap/clipping)
+
+## Pitfalls
+- Some consumers are strict about separator entries in footnotes.xml/endnotes.xml.
+- If the marker appears but note text doesn't, run `footnotes_report.py` to confirm:
+  - reference IDs exist in `document.xml`
+  - note IDs exist in `footnotes.xml`/`endnotes.xml`
+- For high-stakes deliverables, verify in Microsoft Word in addition to LO rendering.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/forms_content_controls.md

@@ -0,0 +1,49 @@
+# Task: Forms / content controls (SDTs)
+
+## When to use
+Use this when the user wants a **fillable DOCX template** (fields, dropdowns, checkboxes) or when you need to **populate** an existing template that contains Word content controls.
+
+`python-docx` does not support SDTs. Use the helper script:
+- `scripts/content_controls.py`
+
+This task doc focuses on **plain-text SDTs** (the most common case for templates).
+
+## Golden path
+1. **Make placeholders visible (authoring step)**
+   - Write placeholders like `{{NAME}}`, `{{DATE}}`, `{{EMAIL}}` in the DOCX where values should go.
+   - If you control authoring, keep each placeholder contiguous (a single token).
+
+2. **Wrap placeholders into SDTs**
+```bash
+python scripts/content_controls.py /mnt/data/template.docx wrap_placeholders \
+  --output /mnt/data/template_sdt.docx
+```
+
+3. **Populate SDTs by tag**
+```bash
+python scripts/content_controls.py /mnt/data/template_sdt.docx fill \
+  --set NAME="Ada Lovelace" \
+  --set EMAIL="ada@example.com" \
+  --output /mnt/data/filled.docx
+```
+
+4. **Render for QA**
+```bash
+python render_docx.py /mnt/data/filled.docx --output_dir /mnt/data/out_forms
+```
+Inspect `page-<N>.png` at 100% zoom.
+
+## Listing / debugging
+List all SDTs (tag, alias, visible text, part location):
+```bash
+python scripts/content_controls.py /mnt/data/template_sdt.docx list --json
+```
+
+## Pitfalls / lessons learned
+- **Markers split across runs:** if Word splits `{{NAME}}` into multiple runs (common when styling is applied mid-token), the wrapper may miss it. Fix by retyping the placeholder so it is one contiguous token.
+- **SDTs in footnotes/comments:** this helper patches document.xml + headers/footers. If a template uses SDTs in other parts, you may need a custom patch.
+- **Rich content controls** (dropdown, checkbox, date picker): those require additional SDT properties/parts. This bundle does not attempt full fidelity.
+
+## Deliverables
+- Deliver **only the final DOCX** requested by the user.
+- PNGs / optional PDFs are for internal QA only unless explicitly requested.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/headings_numbering.md

@@ -0,0 +1,44 @@
+# Task: Heading hierarchy + multilevel numbering (H1/H2/H3)
+
+## Goal
+Produce structured documents that are consistent, readable, and TOC-friendly.
+
+## Rules of thumb
+1. **Use paragraph styles**, not direct formatting.
+   - Good: `p.style = doc.styles["Heading 1"]`
+   - Bad: make text 16pt bold in a Normal paragraph and hope it behaves like a heading.
+2. Keep heading hierarchy consistent: don’t jump from Heading 1 → Heading 3 unless the document truly skips a level.
+3. Numbered headings are *not* the same thing as bullet lists. If you need Word’s multilevel numbering, use a template where the numbering definitions already exist (DOTX), or accept that it’s brittle to generate from scratch.
+
+## Minimal python-docx patterns
+
+### Set heading styles
+```python
+from docx import Document
+
+doc = Document()
+doc.add_paragraph("Executive Summary", style="Heading 1")
+doc.add_paragraph("Background", style="Heading 2")
+doc.add_paragraph("Prior Work", style="Heading 3")
+doc.save("out.docx")
+```
+
+### Avoid direct formatting
+If you must adjust typography, do it by editing the style definitions (template) rather than changing every paragraph.
+
+## Validate structure quickly
+```bash
+python scripts/heading_audit.py /mnt/data/input.docx
+```
+
+## Render → PNG review checklist (headings)
+- Heading sizes/weights are consistent across the document
+- Spacing before/after headings is consistent
+- Indentation is consistent (especially for numbered headings)
+- No "fake headings" (big bold Normal text) are used for actual sections
+- TOC (if present) reflects heading hierarchy correctly
+
+## Common pitfalls
+- Mixing manual numbering (“1. ” typed in text) with TOC-generated numbering
+- Using Normal paragraphs with bold/size changes instead of Heading styles
+- Having different documents disagree on what Heading 1/2/3 look like (solve with templates)

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/images_figures.md

@@ -0,0 +1,35 @@
+# Task: Images/figures placement + anchoring pitfalls
+
+## Goal
+Keep images and captions where you expect across Word/LibreOffice/PDF exports.
+
+## Key reality
+Image placement is the #1 LO-vs-Word mismatch.
+
+## Inline vs floating
+- **Inline** (`wp:inline`): behaves like a big character in the text flow. Most reliable for automation.
+- **Floating/anchored** (`wp:anchor`): supports text wrapping, precise positioning, and "keep with paragraph" effects — also most likely to render differently between apps.
+
+## Recommendations
+1. Prefer **inline** images for automation unless you truly need wrap-around.
+2. Use high-resolution sources and let Word scale down (avoid scaling up low-DPI images).
+3. Keep a caption in a separate paragraph immediately after the image.
+
+## Audit
+```bash
+python scripts/images_audit.py /mnt/data/input.docx
+```
+
+If you see `anchor` rows, treat as high-risk and inspect renders closely.
+
+## Render → PNG review checklist (images)
+- Images appear on the intended page(s)
+- No overlap with text, tables, or margins
+- Captions remain adjacent to their figures
+- Images aren’t blurry/pixelated (zoom to 200% to check)
+- No unexpected cropping/stretching
+
+## Common pitfalls
+- Floating images shifting pages after small text edits
+- Wrap modes causing overlap in LibreOffice exports
+- Copy/pasted images with huge DPI metadata leading to surprising sizes

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/multi_doc_merge.md

@@ -0,0 +1,31 @@
+# Merge DOCXs (Append Body Content)
+
+## Goal
+Append the body content of one `.docx` to another **while preserving OOXML fidelity** better than text-only copying.
+
+This helper is intentionally scoped:
+- **Preserves** paragraphs, runs, tables, numbering, and most formatting *inside the body*.
+- **Does not** merge headers/footers/section settings across documents (it keeps the base document's section settings).
+- **Does not** copy relationships for images/objects by default (safe). You can enable a looser mode if you know both docs are text-only.
+
+## Append doc B to doc A
+```bash
+python scripts/merge_docx_append.py base.docx append.docx --out merged.docx
+```
+
+## Allow drawings/images (optional, less safe)
+If you know both documents have compatible relationships and you are okay with best-effort behavior:
+```bash
+python scripts/merge_docx_append.py base.docx append.docx --out merged.docx --allow_drawings
+```
+
+## Verify
+Always render and inspect:
+```bash
+python render_docx.py merged.docx --output_dir out_merged
+```
+
+## Pitfalls
+- If `append.docx` contains images or embedded objects, merging body XML alone is **not sufficient** unless you also merge relationships and binary parts. This script defaults to **refusing** drawings unless `--allow_drawings` is set.
+- If styles/numbers in `append.docx` rely on definitions absent from `base.docx`, Word may substitute defaults.
+- If either document contains tracked changes or comments, merge first *then* run the tracked-changes / comments tasks.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/navigation_internal_links.md

@@ -0,0 +1,62 @@
+# Task: Internal navigation links (Top/Bottom/TOC + jump links)
+
+## Goal
+Create deterministic **internal hyperlinks** inside a DOCX so readers can quickly jump:
+- TOC entry → section
+- section header → back to TOC
+- quick links → Top / Bottom
+- quick links → Figure/Table caption numbers (when bookmarks exist)
+
+This is especially useful for long reports, specs, or demo/QA artifacts.
+
+## Key idea
+Word internal links are `w:hyperlink w:anchor="<bookmarkName>"`.
+
+This bundle provides `scripts/internal_nav.py` to add:
+- `TOC` bookmark + a **static** TOC section (no Word field required)
+- `Top` / `Bottom` bookmarks
+- bookmarks on headings (either `Heading 1/2/3` styles **or** `w:outlineLvl`)
+- "Back to TOC" links on each heading
+- a quick-links bar (Top/Bottom/TOC + figN/tblN if present)
+
+## Workflow
+
+### Option A: Deterministic (headless-safe) static TOC + links
+
+1) Ensure your document has "headings".
+
+Prefer real heading styles (`Heading 1/2/3`). If the document doesn't use heading styles, a practical alternative is setting `w:outlineLvl` on the heading paragraphs (outline level 0 == top-level). This can be done via OOXML patching.
+
+2) (Optional) Add figure/table caption bookmarks first
+
+If you want jump links for figures/tables, run:
+
+```bash
+python scripts/captions_and_crossrefs.py /mnt/data/in.docx /mnt/data/with_caps.docx --figures --tables --bookmarks
+```
+
+3) Add navigation
+
+```bash
+python scripts/internal_nav.py /mnt/data/with_caps.docx --out /mnt/data/with_nav.docx
+```
+
+4) Render and verify
+
+```bash
+python render_docx.py /mnt/data/with_nav.docx --output_dir /mnt/data/out_nav
+```
+
+Verify:
+- TOC entries jump to the intended headings
+- each heading has a working "Back to TOC" link
+- Top/Bottom work
+- figN/tblN links appear if bookmarks exist
+
+### Option B: Word-native TOC field (requires a field update)
+
+If you need a true Word TOC with page numbers, use `tasks/toc_workflow.md`.
+
+## Deliverables
+- Internal navigation is part of the final DOCX.
+- Rendered PNGs (and optional PDFs) are **internal QA only** unless the user explicitly asks for them.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/privacy_scrub_metadata.md

@@ -0,0 +1,24 @@
+# Privacy Scrub (Remove Personal Metadata)
+
+## Goal
+Produce a `.docx` suitable for external sharing by removing common personal /
+machine metadata:
+- Core properties: creator, lastModifiedBy
+- Custom properties: docProps/custom.xml (if present)
+- Word revision session IDs (rsid* attributes) in story parts
+
+This does **not** remove semantic content (text/images) and does not redact PII in the content. For content redaction, use `redact_docx.py`.
+
+## Scrub a doc
+```bash
+python scripts/privacy_scrub.py input.docx --out scrubbed.docx
+```
+
+## Verify
+```bash
+python render_docx.py scrubbed.docx --output_dir out_scrubbed
+```
+
+## Pitfalls
+- Some viewers may cache author info outside the file; always check the resulting `docProps/core.xml` if this is high-stakes.
+- If you need to keep custom properties (e.g., templates), do not run this.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/protection_restrict_editing.md

@@ -0,0 +1,36 @@
+# Restrict Editing / Make Read-Only (Document Protection)
+
+## Goal
+Set Word's **document protection** flags in `settings.xml` so a `.docx` opens as:
+- read-only, or
+- comments-only, or
+- tracked-changes-only, or
+- forms-only
+
+This is useful for:
+- shipping a template that should not be casually modified
+- forcing reviewers to comment instead of edit
+
+## Set protection mode
+```bash
+python scripts/set_protection.py input.docx --mode readOnly --out protected.docx
+python scripts/set_protection.py input.docx --mode comments --out comments_only.docx
+python scripts/set_protection.py input.docx --mode trackedChanges --out tc_only.docx
+python scripts/set_protection.py input.docx --mode forms --out forms_only.docx
+```
+
+## Remove protection
+```bash
+python scripts/set_protection.py input.docx --mode off --out unprotected.docx
+```
+
+## Verification
+Render to PNGs (layout should be unchanged):
+```bash
+python render_docx.py protected.docx --output_dir out_protected
+```
+
+## Pitfalls
+- Protection is enforced by Word; some viewers may ignore it.
+- Password protection is intentionally not implemented (high complexity, low ROI).
+- Some docs may not have `word/settings.xml`; this helper creates it.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/read_review.md

@@ -0,0 +1,60 @@
+# Task: Read / review an existing DOCX
+
+## What to review
+- Layout: page breaks, margins, clipping/overlap
+- Typography: heading hierarchy, font consistency, line spacing
+- Tables/figures: alignment, legibility, truncation
+- Redlines: do tracked insertions/deletions show up?
+- Comments: do they exist (structurally), even if they don’t render?
+
+## Primary method: DOCX → PNG(s) (internally via PDF)
+
+### Preferred: use the packaged renderer
+This is the “golden path” because it handles the container-safe LibreOffice profile + HOME automatically and normalizes output names to `page-<N>.png`.
+
+```bash
+python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out
+# If debugging LibreOffice:
+python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out --verbose
+# Optional: also write <input_stem>.pdf to --output_dir (for debugging/archival):
+python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out --emit_pdf
+```
+
+### Manual method (only if debugging)
+Use a unique LibreOffice profile + writable HOME (containers are prone to profile permission/locking issues):
+
+```bash
+OUTDIR=/mnt/data/out
+INPUT=/mnt/data/input.docx
+BASENAME=$(basename "$INPUT" .docx)
+LO_PROFILE=/mnt/data/.lo_profile_${BASENAME}_$$
+mkdir -p "$OUTDIR" "$LO_PROFILE"
+
+HOME="$LO_PROFILE" soffice --headless -env:UserInstallation=file://"$LO_PROFILE" \
+  --convert-to pdf --outdir "$OUTDIR" "$INPUT"
+
+# Manual naming: produces "$OUTDIR/$BASENAME-1.png", "$OUTDIR/$BASENAME-2.png", ...
+pdftoppm -png "$OUTDIR/$BASENAME.pdf" "$OUTDIR/$BASENAME"
+```
+
+### Success criteria
+- Page images exist for each page
+- Spot-check page count and representative pages
+
+**Note:** LibreOffice sometimes prints scary-looking stderr (e.g., `error : Unknown IO error`) even when output is correct. Prefer file existence + visual inspection over stderr content.
+
+### Visually inspect every page
+Focus on:
+- clipped/overlapping text
+- tables that wrap unexpectedly
+- inconsistent fonts/sizes
+- misplaced headers/footers
+
+## Notes on redlines vs comments
+- **Tracked changes** (insertions/deletions) often show up in PDF renders.
+- **Comments frequently do NOT show up in PDF/image renders** (especially via headless LibreOffice).
+  - Rendering is not proof of comments.
+  - To verify comments, do a structural check (see `ooxml/comments.md`) or use `pandoc --track-changes=all` to confirm comment markup is present.
+
+## If the doc is huge
+Render and inspect key pages first (title, TOC, sections with tables, appendices), then spot-check.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/redaction_anonymization.md

@@ -0,0 +1,57 @@
+# Task: Redaction / anonymization (layout-preserving)
+
+## When to use
+Use this when the user wants to remove or anonymize sensitive information while keeping the document usable and visually stable:
+- remove emails, names, IDs
+- anonymize customer/company names
+- produce a shareable version of a report
+
+This bundle provides `scripts/redact_docx.py`, which redacts by editing OOXML text nodes while attempting to preserve layout:
+- default mode replaces matches with a fixed-length mask (`█` repeated), so line breaks and pagination drift less
+
+## Golden path
+1. Create a copy of the input DOCX (don’t mutate the only copy).
+2. Run `redact_docx.py` with carefully scoped patterns.
+3. Render to PNGs and inspect the redacted areas.
+4. Ensure no sensitive info remains (spot-check and use text search).
+
+## Run it
+### Mask common patterns (examples)
+```bash
+python scripts/redact_docx.py /mnt/data/input.docx \
+  --output /mnt/data/redacted.docx \
+  --pattern "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}" \
+  --pattern "\b\d{3}[-. ]\d{3}[-. ]\d{4}\b"
+```
+
+### Replace with a stable token (length-preserving)
+If you want a visible label but still preserve length, repeat/truncate the label to the match length:
+```bash
+python scripts/redact_docx.py /mnt/data/input.docx \
+  --output /mnt/data/redacted.docx \
+  --pattern "Acme Corp" \
+  --replacement "[REDACTED]" \
+  --preserve_length
+```
+
+### Include comments (optional)
+```bash
+python scripts/redact_docx.py /mnt/data/input.docx \
+  --output /mnt/data/redacted.docx \
+  --pattern "secret" \
+  --include_comments
+```
+
+## Pitfalls (learned the hard way)
+- **Regex too broad:** you can accidentally redact normal prose. Prefer specific patterns.
+- **Matches spanning paragraphs:** this tool only redacts *within a single paragraph* (`w:p`). Keep patterns local.
+- **Non-text content:** images of text, embedded objects, charts, and tracked changes deletions may contain sensitive info. Masking text nodes won’t remove those.
+
+## QA checklist
+- Render and visually inspect pages that contain redactions.
+- Use a text-search pass to confirm strings are gone.
+- Confirm headers/footers and footnotes/endnotes were redacted (this script patches them by default).
+
+## Deliverables
+- Deliver **only the final DOCX** requested by the user.
+- PNGs / optional PDFs are internal QA only unless explicitly requested.

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/tasks/sections_layout.md

@@ -0,0 +1,62 @@
+# Task: Section breaks + mixed page layout (portrait/landscape, margins, page size)
+
+## Goal
+Safely handle documents with mixed layouts without breaking headers/footers.
+
+## Key concept: sections
+In DOCX, page layout is controlled by **sections**. A section defines:
+- page size
+- orientation (portrait/landscape)
+- margins
+- header/footer settings and linkage
+
+If anything looks wrong after an edit (suddenly landscape pages, header disappears, etc.), suspect sections.
+
+## How to audit
+```bash
+python scripts/section_audit.py /mnt/data/input.docx
+```
+
+Look for:
+- multiple sections
+- orientation changes
+- headers/footers linked to previous when you expected them not to be
+
+## Creating a landscape section with python-docx (pattern)
+```python
+from docx import Document
+from docx.enum.section import WD_SECTION
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.section import WD_ORIENT
+
+doc = Document()
+doc.add_paragraph("Portrait page")
+
+sec2 = doc.add_section(WD_SECTION.NEW_PAGE)
+sec2.orientation = WD_ORIENT.LANDSCAPE
+sec2.page_width, sec2.page_height = sec2.page_height, sec2.page_width
+doc.add_paragraph("Landscape page")
+
+doc.save("out.docx")
+```
+
+## Header/footer linkage gotcha
+Each new section can inherit header/footer via **Link to Previous**.
+If you need a different header/footer, you must break the linkage.
+In Word UI: Header/Footer tools → toggle "Link to Previous".
+
+python-docx exposes `section.header.is_linked_to_previous` and `section.footer.is_linked_to_previous`.
+
+## Render → PNG review checklist (sections)
+- Landscape pages are actually landscape (and only the intended ones)
+- Margins look consistent with expectations
+- Header/footer appears on all pages where expected
+- "Different first page" behaves as intended
+- Odd/even headers are correct (if enabled)
+
+## Common pitfalls
+- Forgetting to swap width/height after setting landscape
+- Editing only the first section’s header/footer and assuming it applies to later sections
+- A continuous section break changing margins unexpectedly
+
+**Renderer note:** when a document mixes page sizes/orientations, `render_docx.py` computes DPI from the first section. If you care about exact pixel sizes, pass an explicit `--dpi`.