dsh-office-kit 0.4.1 → 0.4.3

package/assets/skills/office-documents/ooxml/hyperlinks_and_fields.md

@@ -1,6 +1,6 @@
 # Hyperlinks and fields
 
-A hyperlink and a field are both "a run that looks like text but is a pointer", and both break in the same way: the visible result is cached, so editing the text does not update anything.
+A hyperlink and a field are both "a run that looks like text but is a pointer", and both break the same way: the visible result is cached, so editing the text updates nothing.
 
 ## Hyperlinks
 
@@ -10,11 +10,11 @@ A hyperlink and a field are both "a run that looks like text but is a pointer",
 </w:hyperlink>
 ```
 
-- The target is a relationship in `word/_rels/document.xml.rels` with `TargetMode="External"` for a URL, or a bare relative path for a file inside the package.
+- The target is a relationship in `word/_rels/document.xml.rels`: `TargetMode="External"` for a URL, a bare relative path for a file inside the package.
 - An internal link uses `w:anchor="bookmarkName"` and no relationship at all.
-- `w:hyperlink` is a wrapper around runs; a link that spans paragraphs is not legal — put one link per paragraph.
+- `w:hyperlink` wraps runs; a link spanning paragraphs is not legal — one link per paragraph.
 
-A link whose relationship is missing renders as blue underlined text that goes nowhere. That is also what a copy-paste between documents produces.
+A link whose relationship is missing renders as blue underlined text that goes nowhere. Copy-paste between documents produces the same thing.
 
 ## Simple fields
 
@@ -24,7 +24,7 @@ A link whose relationship is missing renders as blue underlined text that goes n
 </w:fldSimple>
 ```
 
-The `w:t` inside is a cache, not the truth. Change the text and the next field update overwrites it.
+The `w:t` inside is a cache, not the truth: change the text and the next field update overwrites it.
 
 ## Complex fields
 
@@ -36,13 +36,13 @@ The `w:t` inside is a cache, not the truth. Change the text and the next field u
 <w:r><w:fldChar w:fldCharType="end"/></w:r>
 ```
 
-The begin/instrText/separate/result/end sequence must stay in that order inside one paragraph. Word shows the result between `separate` and `end`, or recomputes on open when `w:updateFields` is set in `settings.xml`:
+The begin/instrText/separate/result/end sequence keeps that order inside one paragraph. Word shows the result between `separate` and `end`, or recomputes on open when `settings.xml` sets:
 
 ```xml
 <w:updateFields w:val="true"/>
 ```
 
-Setting it makes Word prompt or update on open. A viewer that ignores it (a PDF export, some libraries) keeps showing the cache — which is why a document delivered as PDF can show "1" for every page number.
+That makes Word prompt or update on open. A viewer that ignores it (PDF export, some libraries) keeps the cache — which is why a document delivered as PDF can show "1" for every page number.
 
 ## Which field for which job
 
@@ -57,9 +57,9 @@ Setting it makes Word prompt or update on open. A viewer that ignores it (a PDF
 ## Editing fields safely
 
 - To freeze a result, replace the whole field span with a plain run (`fields_materialize.py`, `flatten_ref_fields.py`).
-- To renumber, update the cached result and leave the instruction alone; do not delete the begin/end markers.
-- `w:instrText` is where the instruction lives — a search-and-replace over `w:t` will not find `TOC`.
-- Bookmarks referenced by `REF` must exist (`w:bookmarkStart`/`w:bookmarkEnd` with matching `w:id`); a missing bookmark shows "Error! Reference source not found."
+- To renumber, update the cached result and leave the instruction alone; never delete the begin/end markers.
+- The instruction lives in `w:instrText`, so a search-and-replace over `w:t` will not find `TOC`.
+- Bookmarks referenced by `REF` must exist (`w:bookmarkStart` / `w:bookmarkEnd` with matching `w:id`); a missing bookmark shows "Error! Reference source not found.".
 
 ## See also
 

package/assets/skills/office-documents/ooxml/rels_and_content_types.md

@@ -1,6 +1,6 @@
 # Relationships and content types
 
-A `.docx` is a zip of parts, and every relationship between parts is declared twice: once as a relationship entry, once as a content type. Miss either and the file either loses the feature or refuses to open.
+A `.docx` is a zip of parts, and every relationship between parts is declared twice: once as a relationship entry, once as a content type. Miss either and the file loses the feature or refuses to open.
 
 ## The two registries
 
@@ -10,7 +10,7 @@ _rels/.rels                  # package -> document, core props
 word/_rels/document.xml.rels # document -> styles, numbering, media, header, footer, comments, hyperlinks
 ```
 
-`[Content_Types].xml` has `<Default Extension="xml" ContentType="..."/>` for extension defaults and `<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>` for parts that do not follow an extension rule.
+`[Content_Types].xml` uses `<Default Extension="xml" ContentType="..."/>` for extension defaults and `<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>` for parts that do not follow an extension rule.
 
 A relationship:
 
@@ -20,7 +20,7 @@ A relationship:
   Target="comments.xml"/>
 ```
 
-`Id` is scoped to the part that owns the `.rels` file, so `rId5` in the document and `rId5` in a header are unrelated. `Target` is relative to the owner directory unless it is absolute (`/word/media/image1.png`) or external (`TargetMode="External"`, used for hyperlinks).
+`Id` is scoped to the part that owns the `.rels` file, so `rId5` in the document and `rId5` in a header are unrelated. `Target` is relative to the owner directory unless absolute (`/word/media/image1.png`) or external (`TargetMode="External"`, used for hyperlinks).
 
 ## What breaks
 
@@ -32,13 +32,13 @@ A relationship:
 | Broken link | Relationship removed but `r:id` left in the body |
 | Lost image | Media copied without a new relationship id |
 
-Ids must be unique within a `.rels` part. When adding one, read the existing ids and take `max+1`; reusing an id silently rewires an unrelated reference.
+Ids are unique within a `.rels` part. Read the existing ids and take `max+1`; reusing an id silently rewires an unrelated reference.
 
 ## The parts that exist only when used
 
-`word/comments.xml`, `word/footnotes.xml`, `word/endnotes.xml`, `word/headerN.xml`, `word/footerN.xml`, `word/numbering.xml`, `docProps/custom.xml` — none are required, and each needs three pieces when added: the part, the override, the relationship. Removing one means removing all three (or Word reports corruption).
+`word/comments.xml`, `word/footnotes.xml`, `word/endnotes.xml`, `word/headerN.xml`, `word/footerN.xml`, `word/numbering.xml`, `docProps/custom.xml` — none are required, and each needs three pieces when added: part, override, relationship. Removing one means removing all three, or Word reports corruption.
 
-Headers and footers are referenced from the section properties, not from the document root:
+Headers and footers are referenced from the section properties, not the document root:
 
 ```xml
 <w:sectPr>
@@ -59,4 +59,4 @@ Headers and footers are referenced from the section properties, not from the doc
 
 ## Rebuild rather than regenerate
 
-When a package is broken, unzipping it, fixing the two registries and rezipping with `[Content_Types].xml` first (stored, not deflated) usually recovers it. The kit writes that order on save for this reason.
+When a package is broken, unzip it, fix the two registries and rezip with `[Content_Types].xml` first (stored, not deflated). The kit writes that order on save for this reason.

package/assets/skills/office-documents/ooxml/tracked_changes.md

@@ -1,6 +1,6 @@
 # Tracked changes
 
-Tracked changes are markup, not a diff. The file contains both the old and the new text, wrapped in elements that say which is which, plus enough metadata for Word to show reviewer names and accept or reject each edit.
+Tracked changes are markup, not a diff. The file holds both old and new text, wrapped in elements that say which is which, plus enough metadata for Word to show reviewer names and accept or reject each edit.
 
 ## The elements
 
@@ -13,7 +13,7 @@ Tracked changes are markup, not a diff. The file contains both the old and the n
 | `w:delText` | The deleted characters — not `w:t` |
 | `w:delInstrText` | A deleted field instruction |
 
-Each carries `w:id`, `w:author`, `w:date`. Ids must be unique within the document; reusing one makes Word show the wrong reviewer.
+Each carries `w:id`, `w:author` and `w:date`. Ids are unique within the document; reusing one makes Word show the wrong reviewer.
 
 A deletion is a `w:del` containing runs with `w:delText`, not a run with a strikethrough:
 
@@ -28,21 +28,21 @@ A deletion is a `w:del` containing runs with `w:delText`, not a run with a strik
 
 ## Tracking has to be on
 
-`<w:trackRevisions/>` in `word/settings.xml` makes *Word* track subsequent edits. It does not affect markup already in the file. Write the markup directly when you are generating the change; turn tracking on when the user will continue editing.
+`<w:trackRevisions/>` in `word/settings.xml` makes *Word* track subsequent edits; it does not affect markup already in the file. Write the markup directly when generating a change; turn tracking on when the user will continue editing.
 
 ## Accepting and rejecting
 
-- **Accept** — keep `w:ins` content and unwrap it; delete `w:del` entirely; for moves keep `w:moveTo`.
-- **Reject** — delete `w:ins` content; keep `w:del` content and convert `w:delText` back to `w:t` (unwrap the `w:del`).
-- Either way, remove the revision containers afterwards; leaving an empty `w:ins` shows a stray marker.
-- Format-change elements have no accept/reject choice in the content sense: accepted means the new properties stay, rejected means the old ones are restored.
+- **Accept** — keep `w:ins` content and unwrap it, delete `w:del` entirely, and for moves keep `w:moveTo`.
+- **Reject** — delete `w:ins` content, keep `w:del` content and convert `w:delText` back to `w:t` (unwrap the `w:del`).
+- Either way, remove the revision containers afterwards; an empty `w:ins` shows a stray marker.
+- Format-change elements are not content: accepting keeps the new properties, rejecting restores the old ones.
 
 ## Where tracking hides
 
-- Inside headers, footers, footnotes, endnotes, table cells, text boxes.
-- Table-level changes: `w:trPr/w:ins` for an inserted row, `w:tcPr/w:cellIns` for a cell.
-- Paragraph-level: a paragraph mark inserted or deleted uses `w:rPr/w:ins` in `w:pPr`, so "delete this paragraph" is not a `w:del` around the paragraph.
-- Comments are separate markup; a comment can survive its being accepted.
+- Inside headers, footers, footnotes, endnotes, table cells and text boxes.
+- Table level: `w:trPr/w:ins` for an inserted row, `w:tcPr/w:cellIns` for a cell.
+- Paragraph level: an inserted or deleted paragraph mark uses `w:rPr/w:ins` in `w:pPr`, so "delete this paragraph" is not a `w:del` around the paragraph.
+- Comments are separate markup; a comment can survive its text being accepted.
 
 ## Reading markup without a renderer
 
@@ -50,4 +50,4 @@ A deletion is a `w:del` containing runs with `w:delText`, not a run with a strik
 "<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode report
 ```
 
-The report lists insertions and deletions with authors and the text on each side. That is the honest way to answer "what changed" when there is no rendered view, and it is also how you confirm a generated change landed as markup rather than as plain text.
+The report lists insertions and deletions with authors and the text on each side — the honest answer to "what changed" with no rendered view, and the way to confirm a generated change landed as markup rather than as plain text.

package/assets/skills/office-documents/references/docx-structure.md

@@ -19,9 +19,7 @@ word/comments.xml, footnotes.xml, endnotes.xml   optional
 
 ## The body
 
-`word/document.xml` is a sequence of block-level elements: `w:p` (paragraph), `w:tbl` (table), `w:sdt` (content control), and finally one `w:sectPr` per section (the last one sits in the body, earlier ones inside a paragraph's `pPr`).
-
-A paragraph is:
+`word/document.xml` is a sequence of block elements — `w:p` (paragraph), `w:tbl` (table), `w:sdt` (content control) — plus one `w:sectPr` per section: the last sits in the body, earlier ones inside a paragraph's `pPr`.
 
 ```xml
 <w:p>
@@ -39,9 +37,9 @@ A paragraph is:
 </w:p>
 ```
 
-Everything a reader sees is a run inside a paragraph; everything that makes it look different from its style is direct formatting in `pPr`/`rPr`. Direct formatting is why `style_normalize.py` exists.
+Everything a reader sees is a run inside a paragraph; everything that makes it differ from its style is direct formatting in `pPr`/`rPr`, which is why `style_normalize.py` exists (`tasks/style_lint_normalize.md`).
 
-A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widths) + `w:tr` > `w:tc` > `w:p`. A cell always contains at least one paragraph.
+A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widths) + `w:tr` > `w:tc` > `w:p`. Every cell holds at least one paragraph.
 
 ## Units
 
@@ -52,31 +50,31 @@ A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widt
 | eighth-point | border widths (`w:sz` on borders) | 8 per point |
 | EMU (914400/in) | drawing extents | 914400 per inch |
 
-A Letter page is 12240×15840 twips. Text width = page width − left − right margins (default 9360 twips with 1in margins).
+A Letter page is 12240×15840 twips. Text width = page width − left − right margins (9360 twips at 1in margins).
 
 ## Styles
 
-`w:style` with `w:type` of `paragraph`, `character`, `table` or `numbering`. Attributes: `w:styleId` (the internal name), `w:name` (the UI name), `w:basedOn`, `w:next`, `w:link`, plus `w:pPr`/`w:rPr`.
+`w:style` with `w:type` of `paragraph`, `character`, `table` or `numbering`; attributes `w:styleId` (internal name), `w:name` (UI name), `w:basedOn`, `w:next`, `w:link`, plus `w:pPr` / `w:rPr`.
 
-- `Normal` is the root; `Heading1`..`Heading9` drive the outline level and the TOC.
-- Outline level can also be set explicitly with `w:outlineLvl` (0-based) in `pPr`; a paragraph can look like a heading without being one, and the TOC will not see it.
+- `Normal` is the root; `Heading1`..`Heading9` drive outline level and the TOC.
+- `w:outlineLvl` (0-based) in `pPr` sets an outline level explicitly: a paragraph can look like a heading without being one, and the TOC will not see it.
 - Latent styles do not exist in the file until used; a document may reference `Heading3` while `styles.xml` has no definition for it.
 
 ## Numbering
 
-`word/numbering.xml` holds `w:abstractNum` (the list definition, per level: format, text, indentation) and `w:num` (`w:numId` → `w:abstractNumId`, optionally overridden). A paragraph joins a list with `w:numPr` referencing a `numId`. Two paragraphs with the same `numId` share a counter.
+`word/numbering.xml` holds `w:abstractNum` (list definition: per level its format, text and indentation) and `w:num` (`w:numId` → `w:abstractNumId`, optionally overridden). A paragraph joins a list with `w:numPr` referencing a `numId`; two paragraphs with the same `numId` share a counter.
 
 ## Sections
 
-`w:sectPr` carries page size (`w:pgSz`), margins (`w:pgMar`), orientation (implied by width vs height, or `w:orient`), columns, and the header/footer references. A document with one section has one `sectPr`; a new section is a paragraph whose `pPr` contains the *previous* section's `sectPr`.
+`w:sectPr` carries page size (`w:pgSz`), margins (`w:pgMar`), orientation (implied by width vs height, or `w:orient`), columns and header/footer references. A single-section document has one `sectPr`; a new section is a paragraph whose `pPr` contains the *previous* section's `sectPr`.
 
 ## Fields
 
-Simple (`w:fldSimple`) and complex (`fldChar` begin/separate/end with `w:instrText`). The visible text is a cache. `w:updateFields` in `settings.xml` asks the editor to refresh on open. See `ooxml/hyperlinks_and_fields.md`.
+Simple (`w:fldSimple`) and complex (`fldChar` begin/separate/end with `w:instrText`). The visible text is a cache; `w:updateFields` in `settings.xml` asks the editor to refresh on open. See `ooxml/hyperlinks_and_fields.md`.
 
 ## Revision markup
 
-`w:ins`, `w:del` (with `w:delText`), `w:moveFrom`/`w:moveTo`, `w:rPrChange`/`w:pPrChange`, each with author and date. See `ooxml/tracked_changes.md`.
+`w:ins`, `w:del` (with `w:delText`), `w:moveFrom` / `w:moveTo`, `w:rPrChange` / `w:pPrChange`, each with author and date. See `ooxml/tracked_changes.md`.
 
 ## Minimum valid package
 

package/assets/skills/office-documents/references/template-elicitation.md

@@ -1,19 +1,17 @@
 # Eliciting a template
 
-A user who says "use our house style" has a file somewhere. Getting it is worth one question; guessing produces a document that has to be redone.
+A user who says "use our house style" has a file somewhere. One question gets it; guessing produces a document that has to be redone.
 
 ## Ask for the artefact, not the description
 
-Description ("blue headings, maybe 11pt") produces a different document every time. The artefact (`house-template.dotx`, an old `.docx` of the same kind, a PDF of the last report) carries the actual styles, margins and fonts.
-
-One sentence is enough:
+A description ("blue headings, maybe 11pt") produces a different document every time. The artefact (`house-template.dotx`, an old `.docx` of the same kind, a PDF of the last report) carries the actual styles, margins and fonts.
 
 > Is there an existing document in this style I should match? Send the file (`.dotx`, or any `.docx` in that style) and I will follow it exactly.
 
-If they have no file, ask for two or three specifics that cannot be guessed and choose the rest from `SKILL.md` defaults:
+With no file, ask for two or three specifics that cannot be guessed and take the rest from `SKILL.md` defaults:
 
-- page size and margins, if their organisation is not US Letter,
-- the heading/body typeface and sizes,
+- page size and margins, if the organisation is not US Letter,
+- heading and body typeface and sizes,
 - anything required by policy (logo in the header, classification mark in the footer).
 
 ## Read the template before using it
@@ -24,7 +22,7 @@ If they have no file, ask for two or three specifics that cannot be guessed and
 "<python>" "<skill>/scripts/section_audit.py" "<template.docx>"
 ```
 
-From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading3`, `Title`, `Caption`, `Quote`, `ListParagraph`. From the section audit, record page size, margins, header/footer text and whether the first page is different.
+From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading3`, `Title`, `Caption`, `Quote`, `ListParagraph`. From the section audit, record page size, margins, header and footer text, and whether the first page is different.
 
 ## Apply it
 
@@ -32,18 +30,18 @@ From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading
 "<python>" "<skill>/scripts/apply_template_styles.py" --template "<template.docx>" --target "<draft.docx>" --out "<styled.docx>"
 ```
 
-This merges style definitions (and numbering) by id — the body content is untouched, so anything written with direct formatting keeps it. Follow with:
+Merges style definitions (and numbering) by id; the body content is untouched, so anything written with direct formatting keeps it. Then:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<styled.docx>" --out "<styled-final.docx>" --clear_paragraph_format --enforce_heading_spacing
+"<python>" "<skill>/scripts/style_normalize.py" "<styled.docx>" --out "<styled-final.docx" --clear_paragraph_format --enforce_heading_spacing
 ```
 
-Now the text picks up the template's look instead of the draft's.
+The text now picks up the template's look instead of the draft's.
 
 ## When the template is a PDF or an image
 
-Extract structure, not styles: heading hierarchy, section order, table layout, caption convention, margin proportions. Then reproduce them with named styles in a generated document. Say which parts were matched approximately — a PDF does not tell you the font size of a heading, only how it looks.
+Extract structure, not styles: heading hierarchy, section order, table layout, caption convention, margin proportions. Reproduce them with named styles in a generated document. Say which parts were matched approximately — a PDF does not reveal a heading's font size, only how it looks.
 
 ## When there is no template and no details
 
-Fall back to the defaults in `SKILL.md` (Letter, 1in margins, 11–12pt body, black headings, `#D9D9D9` table borders) and state the assumption in one line with the delivered file. Do not stall on a question the user may not care about.
+Fall back to the `SKILL.md` defaults (Letter, 1in margins, 11–12pt body, black headings, `#D9D9D9` table borders) and state the assumption in one line with the delivered file. Do not stall on a question the user may not care about.

package/assets/skills/office-documents/references/writing-quality.md

@@ -1,49 +1,49 @@
 # Writing quality
 
-Content quality is the part of a document the format cannot fix. These are the rules to apply while drafting, before any rendering.
+Content quality is the part of a document the format cannot fix. Apply these rules while drafting, before any rendering.
 
 ## Structure before prose
 
-- Every heading states a claim the reader can disagree with ("Services carried the quarter", not "Services"). A heading that only names a topic is a missed opportunity to be clear.
+- Every heading states a claim the reader can disagree with ("Services carried the quarter", not "Services").
 - A section that cannot be summarised in one sentence is two sections.
-- Three levels of heading is the practical maximum; a fourth usually means the content should be a table or an appendix.
-- Nothing between a heading and its first paragraph. No label line, no restated title.
+- Three heading levels is the practical maximum; a fourth means the content wants a table or an appendix.
+- Nothing between a heading and its first paragraph — no label line, no restated title.
 
 ## Paragraphs
 
-- One idea per paragraph, first sentence carries it.
-- 3–6 sentences is the comfortable range; a 1600-word paragraph is a formatting defect even if the prose is good.
-- No em-dash pile-ups, no "furthermore/moreover" chains, no sentence that only announces the next sentence.
-- The last paragraph of a section says what it meant, not that it is finished.
+- One idea per paragraph, carried by the first sentence.
+- 3–6 sentences is comfortable; a 1600-word paragraph is a formatting defect even when the prose is good.
+- No em-dash pile-ups, no "furthermore/moreover" chains, no sentence that only announces the next one.
+- The last paragraph of a section says what the section meant, not that it is finished.
 
 ## Lists and tables
 
 - Bullets for parallel items of equal weight; never for a sequence (that is a numbered list).
-- If items have two attributes, a table beats a bulleted list with parentheticals.
-- Table headers are nouns, units in the header ("Revenue ($m)"), numbers right-aligned.
+- Items with two attributes belong in a table, not a bulleted list with parentheticals.
+- Table headers are nouns with units ("Revenue ($m)"); numbers right-aligned.
 - Every table earns its caption; a table without a purpose is a screenshot of data.
 
 ## Voice
 
-- Active unless the actor is unknown or unimportant; "We found", not "It was found".
+- Active unless the actor is unknown or unimportant: "We found", not "It was found".
 - Present tense for findings, past for actions taken.
-- No unsupported superlatives. "18% growth" beats "strong growth"; if a number is unknown, say so rather than adding an adverb.
-- Define an acronym once, then use it. Never define it twice in different places.
+- No unsupported superlatives: "18% growth" beats "strong growth"; if the number is unknown, say so instead of adding an adverb.
+- Define an acronym once, then use it; never redefine it elsewhere.
 
 ## Numbers
 
-- Consistent precision. Do not mix "12.4%" and "8%" in one table unless the source did.
+- Consistent precision: do not mix "12.4%" and "8%" in one table unless the source did.
 - Percentages below 1 take a leading zero (0.4%, not .4%).
-- State the period and the currency in the table or its caption, not in the surrounding prose.
-- A number in prose must match the number in the table; rendering does not catch this, re-reading does.
+- State period and currency in the table or its caption, not in surrounding prose.
+- A prose number must match the table number; rendering does not catch this, re-reading does.
 
 ## What to cut
 
-- Opening paragraphs that explain that the document will explain something.
-- Closing paragraphs that thank the reader.
+- Opening paragraphs explaining that the document will explain something.
+- Closing paragraphs thanking the reader.
 - Bold on every second phrase: emphasis used everywhere is emphasis used nowhere.
-- Sentences that begin "It is important to note that".
+- Sentences beginning "It is important to note that".
 
 ## Where this connects
 
-`references/docx-structure.md` covers how the structure is expressed in Word — styles, captions, table layout. `tasks/verify_render.md` covers checking the result on a page. Neither replaces reading the text once with the question "would a busy reader get the point from the headings alone?"
+`references/docx-structure.md` covers how structure is expressed in Word — styles, captions, table layout. `tasks/verify_render.md` covers checking the result on a page. Neither replaces reading the text once asking whether a busy reader would get the point from the headings alone.

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

@@ -1,8 +1,6 @@
 # Accessibility
 
-**Goal.** A document a screen reader can navigate: real headings, described images, tables with a header row, no fake emphasis carrying meaning.
-
-The accessibility tree in Word comes from structure, not appearance. Bold text announces as bold; a `Heading 1` announces as a heading and appears in the navigation pane. Alt text lives in `wp:docPr @descr`.
+Accessibility comes from structure, not appearance: bold announces as bold, `Heading 1` announces as a heading and appears in the navigation pane. Alt text lives in `wp:docPr @descr`.
 
 ## Audit
 
@@ -10,36 +8,32 @@ The accessibility tree in Word comes from structure, not appearance. Bold text a
 "<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --out_json "<report.json>"
 ```
 
-Checks: images without a description or title, tables without a repeating header row, heading levels that jump, empty headings, links whose text is only "click here" / "here" / "link", and a missing core title.
-
-Exit code 1 means at least one finding; `--out_json` writes the same report for a larger pass.
+Checks images without description or title, tables without a repeating header row, heading levels that jump, empty headings, link text that is only "click here", "here" or "link", and a missing core title. Exit 1 means at least one finding.
 
-## Fix the mechanical parts
+## Mechanical fixes
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" \
-  --fix_image_alt from_filename --fix_table_headers first_row \
-  --out "<file-a11y.docx>"
+"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --fix_image_alt from_filename --fix_table_headers first_row --out "<file-a11y.docx"
 ```
 
-Both fixes are honest placeholders: the file name as alt text is better than an empty description, and a header row that repeats across pages helps a reader who lands mid-table. Neither substitutes for real text.
+These are honest placeholders, not substitutes for real text.
 
-## Fix the parts that need judgement
+## Judgement fixes
 
-- **Alt text.** Describe what the reader would lose without the picture: "Bar chart: revenue by region, EMEA 4.1M ahead of APAC 3.2M." Decorative rules and dividers get an empty description.
-- **Link text.** "Download the Q2 ledger" instead of "click here".
-- **Reading order.** Decorative text boxes and floating images insert themselves at awkward places in the reading order; convert to inline if the flow matters.
-- **Colour.** Meaning carried only by colour (red = bad) fails for a colour-blind reader; add a word.
-- **Tables for layout.** A layout table announces as a data table. Restructure into paragraphs if the content is not tabular.
+- **Alt text** describes what the reader loses, e.g. "Bar chart: revenue by region, EMEA 4.1M ahead of APAC 3.2M". Decorative rules and dividers get an empty description.
+- **Link text** names the destination: "Download the Q2 ledger", not "click here".
+- **Reading order:** decorative text boxes and floating images land awkwardly; convert them to inline.
+- **Colour alone** (red = bad) fails colour-blind readers; add a word.
+- **Layout tables** announce as data tables; restructure them as paragraphs.
 
-Long documents also want a TOC (`tasks/toc_workflow.md`), which is the screen-reader equivalent of the navigation pane, and language tags so a screen reader pronounces correctly.
+Longer documents also want a TOC (`tasks/toc_workflow.md`) and language tags.
 
 ## Verify
 
-Re-run the audit to zero findings, then render and read the page: heading hierarchy visible, alt text is not visible (it is metadata), table header row distinct. If a screen reader is available, open the document and navigate by heading — that is the true test.
+Re-run the audit to zero findings and render. Heading hierarchy is visible; alt text is metadata and stays invisible; the header row must be distinct. With a screen reader available, navigate by heading.
 
 ## Pitfalls
 
-- Alt text on a decorative image is worse than none; an empty description plus `title` marks it decorative.
-- A table header row is `w:tblHeader` on the row, not a bold first row.
-- Images inside a table cell still need descriptions.
+- Alt text on a decorative image is worse than none: use an empty description plus `title` to mark it decorative.
+- A header row is `w:tblHeader` on the row, not a bold first row.
+- Images inside table cells still need descriptions.

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

@@ -1,49 +1,46 @@
-# Captions and cross-references
+# Captions and numbered cross-references
 
-**Goal.** Number figures and tables automatically and refer to them from the prose without typing a number that will drift.
-
-Two parts: a caption paragraph with a `SEQ` field (`SEQ Table \* ARABIC`), and a bookmark around it that the prose reaches with a `REF` field. Without the bookmark a `REF` has nothing to point at.
+A caption is a paragraph with a `SEQ` field (`SEQ Table \* ARABIC`) plus a bookmark; the prose reaches that bookmark with a `REF` field. Without the bookmark a `REF` has no target.
 
 ## Add captions
 
 ```bash
-"<python>" "<skill>/scripts/captions_and_crossrefs.py" "<file.docx>" "<file-captioned.docx>" \
-  --tables --figures --bookmarks --caption_text "Source: finance ledger"
+"<python>" "<skill>/scripts/captions_and_crossrefs.py" "<file.docx>" "<file-captioned.docx>" --tables --figures --bookmarks --caption_text "Source: finance ledger"
 ```
 
-- `--tables` adds `Table N` under each table, `--figures` adds `Figure N` under each picture. With neither flag, both run.
-- Captions use the `Caption` style and sit inside the same visual block as the object, so a page break cannot orphan them.
-- `--bookmarks` names the captions `tbl1`, `tbl2`, `fig1`, … so cross-references have targets.
-- `--materialize` writes literal numbers instead of `SEQ` fields; use it for a frozen PDF export, not for a document that will change.
-- `--caption_text` appends a fixed note after the number.
+- `--tables` adds `Table N` under each table; `--figures` adds `Figure N` under each picture.
+- Neither flag runs both.
+- `--bookmarks` names them `tbl1`, `tbl2`, `fig1`, … — the `tblN`/`figN` pattern `insert_ref_fields.py` expects.
+- `--materialize` writes literal numbers: for a frozen PDF export, not for a document that will change.
+- `--caption_text` appends a fixed note.
 
-The bookmarks the script creates (`tblN`, `figN`) are what `insert_ref_fields.py` expects by default.
+Captions use the `Caption` style and stay in the same visual block as the object, so a page break cannot orphan them.
 
-## Add cross-references
+## Cross-reference
 
-Write placeholders in your content, then convert them:
+Write `[[REF:tbl1]]` placeholders in the prose, then:
 
 ```bash
-"<python>" "<skill>/scripts/insert_ref_fields.py" "<file.docx>" "<file-refs.docx>"
+"<python>" "<skill>/scripts/insert_ref_fields.py" "<file.docx>" "<file-refs.docx"
 ```
 
-`[[REF:tbl1]]` becomes a `REF tbl1 \h` field, which renumbers when the table moves. `--pattern` accepts your own regular expression as long as it has a named group `bookmark`; `--prefix` prepends text such as `Table ` to each result.
+That produces a `REF tbl1 \h` field, so the number follows the table. `--pattern` accepts your own regex with the named group `bookmark`; `--prefix` prepends text such as `Table `.
 
-If the reference should read "Table 2" rather than just "2", set the `REF` field's `\n` behaviour off and include the label in the prose — a field cannot know whether its target is a table or a figure.
+If a reference should read "Table 2" rather than "2", set the REF field's `\n` behaviour off and put the label in the prose: a field cannot know whether it points at a table or a figure.
 
-## Order of operations
+## Order
 
-1. Add or restructure tables and figures.
-2. Run `captions_and_crossrefs.py` (creates captions and bookmarks).
-3. Run `insert_ref_fields.py` (turns placeholders into fields).
-4. Re-render: caption positions and numbering are a layout decision.
+1. Add or restructure the tables and figures.
+2. Run `captions_and_crossrefs.py`.
+3. Run `insert_ref_fields.py`.
+4. Re-render.
 
 ## Verify
 
-`fields_report.py`: one `SEQ` per caption, one `REF` per reference, no `REF` left with an empty result. Then read the rendered page — a caption above a table instead of below, or a caption separated from its object by a page break, is the usual defect.
+Run `fields_report.py`: one SEQ per caption, one REF per reference, and no REF with an empty result. Then render. The usual defects are a caption above its table, or a caption separated from it by a page break.
 
 ## Pitfalls
 
-- Renumbering happens on field update. Two captions claim `Table 2` until Word recalculates.
-- A caption added by hand with the number typed in will not renumber; use the script or a `SEQ` field.
-- Bookmarks must be unique; copying a caption copies its bookmark name and breaks the reference.
+- Numbering changes on field update, so two captions can claim `Table 2` until Word recalculates.
+- A hand-typed caption number never renumbers.
+- Bookmarks must be unique: copying a caption copies its bookmark name and breaks the reference.

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

@@ -1,49 +1,44 @@
-# Tracked changes
+# Proposed and tracked changes
 
-**Goal.** Propose edits as tracked changes so a reviewer can accept or reject them, or clean up a file that arrives full of markup.
+A tracked edit is markup: an insertion wraps runs in `w:ins`, a deletion wraps `w:delText` in `w:del`, a move is `w:moveFrom`/`w:moveTo` paired by `w:name`, and a formatting change is `w:rPrChange`/`w:pPrChange`. `w:trackRevisions` in `word/settings.xml` makes Word record new edits.
 
-A tracked edit is markup, not text: an insertion is `w:ins` wrapping runs, a deletion is `w:del` wrapping `w:delText`, and formatting changes are `w:rPrChange` / `w:pPrChange`. The setting `w:trackRevisions` in `word/settings.xml` makes Word record new edits the same way.
-
-## Propose an edit
+## Propose
 
 ```bash
-"<python>" "<skill>/scripts/add_tracked_replacements.py" "<file.docx>" --out "<file-tracked.docx>" \
-  --author "Review" --replace "18%=21%" --replace "flat=steady"
+"<python>" "<skill>/scripts/add_tracked_replacements.py" "<file.docx>" --out "<file-tracked.docx>" --author "Review" --replace "18%=21%" --replace "flat=steady"
 ```
 
-Each `--replace` is `OLD=NEW`; the script splits runs at the match so only the changed characters are marked, keeps the surrounding formatting, and turns on `trackRevisions`. Quote the `--author` the reviewer should see.
+Each `--replace` is `OLD=NEW`. The script splits runs at the match so only the changed characters are marked, keeps the surrounding formatting, and turns on `trackRevisions`. Quote the `--author` the reviewer should see.
 
-Limit: one replacement per pattern per paragraph, and a match split across runs is still found because the split is computed on paragraph text. Reword the pattern if the paragraph repeats the phrase.
+Limit: one replacement per pattern per paragraph. A match split across runs is still found because the split is computed on paragraph text; reword if a paragraph repeats the phrase.
 
-## Inspect what is proposed
+## Inspect
 
 ```bash
 "<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode report
 "<python>" "<skill>/scripts/docx_kit.py" xml "<file.docx>" word/document.xml
 ```
 
-The report counts insertions, deletions, move pairs and format changes. Use `docx_kit.py xml` when you need to know exactly which words change.
+The report counts insertions, deletions, move pairs and format changes.
 
 ## Accept or reject
 
 ```bash
-"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode accept --out "<file-accepted.docx>"
-"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode reject --out "<file-rejected.docx>"
+"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode accept --out "<file-accepted.docx"
+"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode reject --out "<file-rejected.docx"
 ```
 
-Accept keeps inserted text and drops deleted text; reject does the reverse and restores `w:delText` as ordinary text. Format-only changes are discarded either way. `--keep_tracking_on` leaves `trackRevisions` enabled, so the next person's edits are also recorded.
-
-## Before delivery
+Accept keeps inserted text and drops deleted text; reject reverses that and restores `w:delText` as ordinary text. Format-only changes are discarded either way. `--keep_tracking_on` leaves `trackRevisions` enabled.
 
-Rendered pages contain no markup, so a document can look finished while still carrying redlines. Always check `--mode report` on a file you are about to send, and accept or reject explicitly.
+Before delivery: rendered pages contain no markup, so a file can look finished while carrying redlines. Always run `--mode report` on a file about to be sent, then accept or reject explicitly.
 
 ## Verify
 
-After accepting, `docx_kit.py text` should show the new wording and no `w:ins`/`w:del` should remain in `word/document.xml`. Render and read the affected page.
+After accepting, `docx_kit.py text` shows the new wording and `word/document.xml` contains no `w:ins`/`w:del`. Render the affected page.
 
 ## Pitfalls
 
-- `w:del` contains `w:delText`, not `w:t`; a text extraction that only looks at `w:t` silently loses deletions.
-- Tables, headers and footnotes can each carry their own tracked changes — the script covers every text part, but a hand edit in one part can miss another.
-- Accepting a move pair (`w:moveFrom`/`w:moveTo`) as two unrelated edits duplicates content; the script treats them as a pair.
-- Comments are not tracked changes. See `comments_manage.md`.
+- `w:del` contains `w:delText`, not `w:t`; extraction that reads only `w:t` loses deletions.
+- Tables, headers and footnotes can each carry tracked changes. The script covers every text part; a hand edit can miss one.
+- Accepting a move pair as two unrelated edits duplicates content. The script treats them as a pair.
+- Comments are not tracked changes; see `comments_manage.md`.