skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/converters/skills/md-to-docx/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: md-to-docx
+description: Turn a Markdown draft into a Word document (.docx) that someone outside engineering can open, edit and track changes in, with real Heading styles so the navigation pane and table of contents work, live hyperlinks, numbered and bulleted lists, tables, code blocks, embedded images and optional brand fonts and colours, and a warning for everything that could not be carried over. Use when the user wants a Markdown file as a Word doc, says "send this as a .docx", "convert to Word", "legal needs it in Word", or "make this editable for the client".
+---
+
+# md-to-docx
+
+You turn a Markdown file into a `.docx` that opens cleanly in Word, Pages, Google Docs and
+LibreOffice. The script does the mechanical conversion with the Python standard library, so
+there is nothing to install. Your job is the part around it: get the Markdown into a shape that
+converts well, run the script, and tell the user exactly what did not survive. Drafts often come
+from `guide-builder` or
+`release-notes`; a `brand.json` from `brand-kit` makes the document match the user's decks.
+
+## How to respond
+
+1. **Ask once for what's missing.** You need the Markdown (a path, or text in the chat to save
+   to a file). Ask in one message, with defaults:
+
+   > To make the Word file, I need:
+   > 1. **The Markdown:** a file path, or paste it. *(required)*
+   > 2. **Brand:** a `brand.json` from brand-kit, for heading font, body font and heading colour.
+   >    *Default: Calibri and dark blue.*
+   > 3. **Page size:** `letter` or `a4`. *Default: letter; use a4 for UK, EU, India and Australia readers.*
+
+   Don't ask about anything else. A title comes from the front matter or the first `#` heading.
+
+2. **Prepare the Markdown before converting.** Fix what would convert badly, in a copy, and
+   list each change for the user:
+   - One `#` heading at the top, then `##` and `###`. Skipped levels (`#` then `###`) put a hole in
+     Word's navigation pane.
+   - Raw HTML, footnotes and Mermaid blocks don't convert. Rewrite an HTML table as a pipe table,
+     move a footnote's text into the sentence or a "Notes" section, and render each diagram to PNG
+     with `mermaid-render` (PNG output needs mermaid-cli installed), then embed the PNG as a
+     Markdown image with alt text.
+   - Lists nested deeper than two levels are flattened. Restructure them into a sub-heading
+     and a list.
+   - Image paths must be relative to the Markdown file and point at PNG or JPEG files.
+   - If the text came from an agent, run `output-hygiene` first so invisible characters and
+     "Generated with" trailers don't end up in a file that gets forwarded.
+
+3. **Convert.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_docx.py" draft.md -o draft.docx --brand ./brand/brand.json
+   # Other IDEs (from the skill folder)
+   python3 scripts/md_to_docx.py draft.md -o draft.docx --brand ./brand/brand.json
+   ```
+
+   Options: `--title "..."` sets the title in File > Properties; `--page a4`; `--hr page-break`
+   turns each `---` into a page break instead of a thin rule.
+
+4. **Read every `WARN` line and act on it.** Each one names a line number and what was dropped
+   or changed. Fix the source and rerun when the fix is yours to make (a missing image path, an
+   HTML block you can rewrite). Report the rest to the user in plain words: *"The footnote on line
+   36 was dropped; I moved its text into the Notes section."* Never hand over a file with
+   unexplained warnings.
+
+5. **Check that it opens.** On a Mac, `textutil -convert txt draft.docx -stdout` reads the
+   text back; `qlmanage -t draft.docx` renders a preview image. Elsewhere, open it in LibreOffice
+   or Word. Report the script's summary line: headings, tables, images and links counted.
+
+6. **Hand over the file with three lines:** where it is, what was dropped or changed, and what to
+   do in Word: *References > Table of Contents* inserts a TOC from the headings.
+
+**Non-interactive runs** (subagent, CI, headless): with no Markdown there is nothing to convert.
+Emit `BLOCKED: need the Markdown file or text to convert` and write nothing. A missing brand
+or page size uses the defaults, with an `[assumption]` line at the top of your report.
+
+## What converts, and what doesn't
+
+| Markdown | In Word |
+|---|---|
+| `#` to `####` | Heading 1 to 4 (built-in styles: navigation pane and TOC work). `#####` and `######` become Heading 4, with a warning |
+| `**bold**`, `*italic*`, `~~strike~~`, `` `code` `` | Bold, italic, strikethrough, monospace on a grey background |
+| Inline links, `<https://…>`, bare URLs, `[text][ref]` | Clickable hyperlinks. A link to `#heading-slug` jumps to that heading |
+| `-` / `1.` lists, one nested level, `- [ ]` tasks | Word bullets and numbering (a numbered list keeps its starting number), ☐ / ☒ boxes |
+| Pipe tables | A bordered table with a shaded, bold header row that repeats on each page; column alignment kept |
+| Fenced or indented code | One shaded monospace block, line breaks and indentation kept |
+| `> quote` | Indented italic Quote style with a left rule |
+| `---` | A thin rule, or a page break with `--hr page-break` |
+| Image with a local PNG or JPEG path | The image embedded at its real size (from its DPI), shrunk to fit the page, alt text kept |
+| **Dropped, with a warning** | Raw HTML (tags removed, text kept; `<br>` is honoured), footnotes, remote / missing / non-PNG-JPEG images, nesting past two levels, YAML front matter (its `title:` is used), Mermaid (kept as code) |
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): how each construct maps to Word XML, the brand.json fields read, and why some things are dropped
+- [`scripts/md_to_docx.py`](scripts/md_to_docx.py): the converter (stdlib only, Python 3.9+)
+- [`examples/q3-support-review.md`](examples/q3-support-review.md): worked example, a support review with a table, an image and warnings, converted with a brand
+
+## Quality bar
+
+- **Headings are real Word headings.** The navigation pane shows the outline, and *Insert Table of Contents* works without restyling.
+- **Every link is clickable** and every in-document `#anchor` link jumps to its heading.
+- **Nothing is lost silently.** Each `WARN` line is either fixed in the source and gone on rerun, or reported to the user with what it means.
+- **Facts are untouched.** You restructure Markdown (heading levels, footnotes into text) but never change a number, a name or a date in it.
+- **Images are embedded**, not linked, so the file still works when it's emailed.
+- **The file opens.** You checked it with textutil, Quick Look, LibreOffice or Word, not just that the script exited 0.
+
+## When to use this skill
+
+- ✅ A Markdown draft that a reviewer, client, legal or HR team needs to edit in Word with tracked changes
+- ✅ Release notes, a design doc or a report that has to go out as a `.docx` attachment
+- ✅ A branded Word version of a document, using the same `brand.json` as the decks
+
+## When NOT to use this skill
+
+- ❌ Slides; use `deck-builder`
+- ❌ A web page or a file to open in a browser; use `md-to-html`
+- ❌ The other direction, a Word file or PDF back to Markdown; use `file-to-markdown`
+- ❌ Tables that need to be sorted, filtered or summed; use `md-to-xlsx`
+- ❌ Writing the document itself; draft it first with `guide-builder` or the skill for that document, then convert
+
+## Anti-patterns to avoid
+
+- ❌ **Handing over the .docx with warnings unread.** "Converted!" while a footnote and two images were dropped is how a reviewer finds the gap in front of a client.
+- ❌ **Bold lines instead of headings.** `**Background**` on its own line is not a heading, so Word's navigation pane and TOC skip it. Make it `## Background`.
+- ❌ **Linking images by URL.** Remote images are not fetched. Download them next to the Markdown first.
+- ❌ **Pasting HTML tables into the Markdown.** They are dropped. Rewrite them as pipe tables.
+- ❌ **Editing the facts while restructuring.** Changing a heading level is formatting; rounding "3.4 hours" to "about 3 hours" is not.
+- ❌ **Converting a Markdown file of slide bullets.** One-line bullets under headings make a thin document. If it's a talk, it's a deck.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/converters/skills/md-to-docx/evals/eval_queries.json

@@ -0,0 +1,10 @@
+[
+  { "query": "Convert README-for-legal.md to a Word document", "should_trigger": true },
+  { "query": "The client can't open Markdown, can you send the design doc as a .docx?", "should_trigger": true },
+  { "query": "Make this markdown report editable in Word with our brand fonts", "should_trigger": true },
+  { "query": "Export these release notes to docx so HR can track changes", "should_trigger": true },
+  { "query": "Turn this markdown outline into a PowerPoint deck", "should_trigger": false },
+  { "query": "Convert the onboarding guide into a single HTML page I can email", "should_trigger": false },
+  { "query": "Turn this Word file the client sent back into Markdown", "should_trigger": false },
+  { "query": "Put these markdown tables into an Excel spreadsheet", "should_trigger": false }
+]

skilldrop_cli/data/packs/converters/skills/md-to-docx/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "md-to-docx",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Northwind Legal wants our vendor onboarding policy as a Word doc so they can track changes. It's in docs/vendor-onboarding.md: a # title, ## sections, a numbered approval process with sub-steps, a pipe table of approval limits ($5,000 / $50,000 / unlimited), a footnote citing the finance policy, and a Mermaid flowchart of the approval path. Use ./brand/brand.json and A4 paper.",
+      "assertions": [
+        "Runs md_to_docx.py with --brand ./brand/brand.json and --page a4, writing a .docx",
+        "Deals with the Mermaid flowchart before converting: renders it to PNG with mermaid-render and embeds it, or says plainly that it stays as code",
+        "Moves the footnote's text into the body or a Notes section instead of letting it drop silently",
+        "Reports every WARN line the script printed, each with what was done about it",
+        "Keeps the approval limits ($5,000 / $50,000 / unlimited) and every other fact exactly as in the source",
+        "Checks the file opens (textutil, Quick Look, LibreOffice or Word) and reports the script's summary counts",
+        "Tells the user the headings drive Word's navigation pane and table of contents"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Convert this to Word for the Acme client, they don't use Markdown: <a 40-line Markdown status report pasted in the chat, with **Background** and **Next steps** as bold lines instead of headings, an HTML <table>, and an image linked from https://cdn.example.com/chart.png>",
+      "assertions": [
+        "Saves the pasted text to a .md file before converting",
+        "Turns the bold-line pseudo-headings into ## headings so Word sees them as headings",
+        "Rewrites the HTML table as a pipe table rather than letting it drop",
+        "Says the remote image is not embedded and asks for, or downloads, a local copy",
+        "Does not invent content, numbers or dates that are not in the pasted report"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/converters/skills/md-to-docx/evals/files/1/brand/brand.json

@@ -0,0 +1,80 @@
+{
+  "$comment": "brand-kit output. deck-builder and marketing-flyer read this file; any field left out is asked for or defaulted by them. Paths are relative to this file. Every value carries where it came from in `sources`.",
+  "name": "Northwind Health",
+  "tagline": "Care that comes to you",
+  "logo": {
+    "primary": "logo.png",
+    "on_dark": "logo-white.png",
+    "mark": "mark.png",
+    "notes": "Keep clear space equal to the height of the N on every side. Never place the full-colour logo on the green."
+  },
+  "colors": {
+    "primary": "#0E5A46",
+    "secondary": "#3D7F6B",
+    "accent": "#F2A541",
+    "background": "#FFFFFF",
+    "text": "#1F2A28",
+    "extra": [
+      {
+        "name": "Mist",
+        "hex": "#E8F1EE",
+        "use": "panel backgrounds"
+      }
+    ]
+  },
+  "fonts": {
+    "heading": {
+      "family": "Georgia",
+      "fallback": "serif",
+      "weight": 700
+    },
+    "body": {
+      "family": "Arial",
+      "fallback": "sans-serif",
+      "weight": 400
+    }
+  },
+  "voice": {
+    "tone": "Warm, plain, confident. Short sentences.",
+    "use": [
+      "members",
+      "care team",
+      "near you"
+    ],
+    "avoid": [
+      "patients",
+      "cutting-edge",
+      "solutions"
+    ]
+  },
+  "imagery": {
+    "style": "Real people in daylight, community settings, no stock handshakes.",
+    "do": [
+      "natural light",
+      "diverse ages"
+    ],
+    "dont": [
+      "clinical close-ups",
+      "illustrated icons as hero images"
+    ]
+  },
+  "templates": {
+    "pptx": "northwind-master.potx"
+  },
+  "contact": {
+    "website": "northwindhealth.example",
+    "email": "hello@northwindhealth.example",
+    "phone": "",
+    "address": ""
+  },
+  "legal": {
+    "footer": "\u00a9 2026 Northwind Health",
+    "disclaimer": ""
+  },
+  "sources": {
+    "colors": "brand guidelines PDF, page 4 [explicit]",
+    "fonts": "brand guidelines PDF, page 6 [explicit]",
+    "voice": "website About page [inferred]",
+    "logo": "files supplied by the user [explicit]"
+  }
+}

skilldrop_cli/data/packs/converters/skills/md-to-docx/evals/files/1/docs/vendor-onboarding.md

@@ -0,0 +1,42 @@
+# Vendor onboarding policy
+
+Northwind Health onboards a vendor only after the checks below are complete.[^1]
+
+## Scope
+
+This policy covers every supplier paid more than $1,000 in a year, including software subscriptions.
+
+## Approval process
+
+1. The requester opens a vendor request.
+   1. Attach the quote.
+   2. Name the budget owner.
+2. Security reviews the vendor questionnaire.
+   1. A vendor that handles member data needs a SOC 2 Type II report.
+3. Finance approves within the limits below.
+4. Legal signs the contract.
+
+## Approval limits
+
+| Role | Limit | Second approver |
+|:-----|------:|:----------------|
+| Team lead | $5,000 | none |
+| Director | $50,000 | Finance partner |
+| CFO | unlimited | CEO above $500,000 |
+
+## Approval path
+
+```mermaid
+flowchart TD
+    A[Request opened] --> B{Handles member data?}
+    B -->|Yes| C[Security review]
+    B -->|No| D[Finance approval]
+    C --> D
+    D --> E[Legal signs]
+```
+
+## Exceptions
+
+An emergency purchase under $5,000 may be approved after the fact within **five working days**.
+
+[^1]: Finance policy FIN-012, section 4.

skilldrop_cli/data/packs/converters/skills/md-to-docx/examples/q3-support-review-input.md

@@ -0,0 +1,54 @@
+---
+title: Northwind Support — Q3 Review
+author: Support Operations
+---
+
+# Northwind Support: Q3 review
+
+Prepared for the **Acme account team**. This review covers July to September and the
+*three* changes we propose for Q4. Raw numbers live in the [support dashboard](https://dashboard.northwind.example/support).
+
+## Summary
+
+- First-response time fell from 6.1 to 3.4 hours
+- Backlog is down 18%, mostly in the EMEA queue
+  - EMEA: 412 → 301 open tickets
+  - APAC: unchanged at 155
+- [x] Chatbot hand-off rule shipped in August
+- [ ] Weekend rota still not agreed
+
+## Tickets by region
+
+| Region | Opened | Closed | Median first response |
+|:-------|-------:|-------:|:---------------------:|
+| EMEA   | 2,140  | 2,251  | 3.1 h                 |
+| NA     | 1,876  | 1,840  | 3.6 h                 |
+| APAC   | 932    | 932    | 3.9 h                 |
+
+![Closed tickets by region, Q3](tickets-by-region.png)
+
+## Proposals for Q4
+
+1. Agree the weekend rota by 15 October.
+2. Move APAC triage into the shared queue.
+3. Retire the legacy `support@` alias; see [the alias section](#retiring-the-alias).
+
+> Customers said the chatbot hand-off was the biggest improvement this year.
+> — from the September survey[^1]
+
+### Retiring the alias
+
+The forwarding rule to remove:
+
+```text
+match: to == "support@northwind.example"
+action: forward -> queue/general
+```
+
+<div class="callout">Draft — not yet reviewed by Legal.</div>
+
+---
+
+Questions go to the support ops channel.
+
+[^1]: 214 responses, 31% response rate.

skilldrop_cli/data/packs/converters/skills/md-to-docx/examples/q3-support-review.md

@@ -0,0 +1,80 @@
+# Worked example: a support review in Markdown becomes a branded Word file
+
+## Input given to the skill
+
+> Acme's account team wants our Q3 support review as a Word doc so they can comment on it.
+> It's in `q3-support-review-input.md`. Use our brand kit in `./brand/`.
+
+The source is [`q3-support-review-input.md`](q3-support-review-input.md), with its chart
+[`tickets-by-region.png`](tickets-by-region.png) next to it. It has YAML front matter, a nested
+list, task boxes, a right-aligned table, an image, a numbered list with an in-document link, a
+blockquote, a code block, one raw HTML `<div>` and a footnote. The brand is brand-kit's
+Northwind template: Georgia headings, Arial body, primary `#0E5A46`.
+
+---
+
+## What the agent did
+
+**First run, to see what doesn't convert:**
+
+```
+$ python3 scripts/md_to_docx.py q3-support-review-input.md -o q3-support-review.docx --brand ./brand/brand.json
+WARN line 1: YAML front matter dropped (lines 1-4); its title is used as the document title
+WARN line 48: raw HTML block dropped
+WARN line 54: footnote definition dropped (footnotes are not supported)
+WARN line 36: footnote reference [^1] dropped
+wrote q3-support-review.docx (5 headings, 5 paragraphs, 2 lists, 1 table, 1 code block, 1 image, 2 links, 1 quote, page letter; brand: Georgia / Arial)
+  title: Northwind Support — Q3 Review
+4 warning(s): the items above were dropped or changed; tell the user before sharing
+```
+
+**Fixed the source in a copy** (`q3-support-review-fixed.md`), changing formatting only:
+
+```diff
+- > — from the September survey[^1]
++ > — from the September survey (214 responses, 31% response rate)
+- <div class="callout">Draft — not yet reviewed by Legal.</div>
++ > **Draft:** not yet reviewed by Legal.
+- [^1]: 214 responses, 31% response rate.
+```
+
+**Second run:**
+
+```
+$ python3 scripts/md_to_docx.py q3-support-review-fixed.md -o q3-support-review.docx --brand ./brand/brand.json
+WARN line 1: YAML front matter dropped (lines 1-4); its title is used as the document title
+wrote q3-support-review.docx (5 headings, 6 paragraphs, 2 lists, 1 table, 1 code block, 1 image, 2 links, 2 quotes, page letter; brand: Georgia / Arial)
+  title: Northwind Support — Q3 Review
+1 warning(s): the items above were dropped or changed; tell the user before sharing
+```
+
+The remaining warning is expected: the front matter isn't content, and its title went into
+File > Properties.
+
+**Checked it opens:**
+
+```
+$ textutil -convert txt q3-support-review.docx -stdout | head -4
+Northwind Support: Q3 review
+Prepared for the Acme account team. This review covers July to September and the three changes we propose for Q4. Raw numbers live in the support dashboard.
+Summary
+	•	First-response time fell from 6.1 to 3.4 hours
+```
+
+A Quick Look preview (`qlmanage -t`) shows green Georgia headings and Arial body text. The table
+has a shaded header row and right-aligned numbers, and the 480 × 240 px chart (stored at 144
+DPI) is centred at 3.3 × 1.7 in. The numbered proposals run 1 to 3, the "support dashboard" and
+"the alias section" links are blue and underlined, and the quote is indented and italic.
+
+---
+
+## Reply to the user
+
+> Here's the Word file: `q3-support-review.docx` (Letter, Northwind brand).
+>
+> **Changed so nothing was lost:** the survey footnote is now in brackets after the quote, and
+> the "Draft, not yet reviewed by Legal" box is a quote line, because Word can't take the HTML
+> box. No numbers or wording changed.
+>
+> **In Word:** the five headings show in the navigation pane. To add a contents page, use
+> *References > Table of Contents*. The link to "the alias section" jumps to that heading.

skilldrop_cli/data/packs/converters/skills/md-to-docx/manifest.json

@@ -0,0 +1,52 @@
+{
+  "name": "md-to-docx",
+  "version": "0.1.2",
+  "description": "Turn a Markdown draft into a Word document (.docx) that someone outside engineering can open, edit and track changes in, with real Heading styles so the navigation pane and table of contents work, live hyperlinks, numbered and bulleted lists, tables, code blocks, embedded images and optional brand fonts and colours, and a warning for everything that could not be carried over. Use when the user wants a Markdown file as a Word doc, says \"send this as a .docx\", \"convert to Word\", \"legal needs it in Word\", or \"make this editable for the client\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brand-kit",
+    "deck-builder",
+    "file-to-markdown",
+    "guide-builder",
+    "md-to-html",
+    "md-to-xlsx",
+    "mermaid-render",
+    "output-hygiene",
+    "release-notes"
+  ],
+  "handoff": [
+    {
+      "to": "mermaid-render",
+      "when": "the Markdown contains Mermaid diagram blocks",
+      "purpose": "Render each diagram to PNG so it can be embedded in the Word file instead of appearing as code.",
+      "fallback": "If mermaid-render is absent, leave the block as code, tell the user the diagram did not convert, and suggest exporting it to PNG from mermaid.live."
+    },
+    {
+      "to": "output-hygiene",
+      "when": "the Markdown was written by an agent and is going to someone outside the team",
+      "purpose": "Strip invisible characters and generated-by trailers before they are frozen into a Word file.",
+      "fallback": "If output-hygiene is absent, remove any 'Generated with' line and trailing chat closer by hand before converting."
+    }
+  ],
+  "tags": [
+    "word",
+    "docx",
+    "markdown",
+    "convert",
+    "document",
+    "export"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
+  "model": {
+    "tier": "standard",
+    "rationale": "A stdlib script does the conversion; the model restructures the Markdown so it converts cleanly (heading levels, footnotes, HTML), reads each warning and explains the losses. Bounded editing, no open-ended generation."
+  }
+}

skilldrop_cli/data/packs/converters/skills/md-to-docx/reference.md

@@ -0,0 +1,89 @@
+# md-to-docx reference
+
+How `scripts/md_to_docx.py` maps Markdown to Word, so you can predict the output and explain a
+warning without reading the script.
+
+## The package it writes
+
+A `.docx` is a zip of XML parts. The script writes these and nothing else:
+
+| Part | What it holds |
+|---|---|
+| `word/document.xml` | The body: paragraphs, runs, tables, drawings, bookmarks |
+| `word/styles.xml` | Normal, Heading 1 to 4, Title, Quote, List Paragraph, Source Code, Hyperlink, Table Grid |
+| `word/numbering.xml` | One bullet definition, plus one numbering definition per numbered list, so each list starts at its own number |
+| `word/settings.xml` | Tab stops and compatibility mode (Word 2013 and later) |
+| `word/_rels/document.xml.rels` | Links to styles, numbering, each hyperlink target and each image |
+| `word/media/imageN.png` / `.jpeg` | The embedded images, byte for byte |
+| `docProps/core.xml` | Title, created and modified time |
+
+## Headings
+
+Heading styles use Word's built-in style names (`heading 1` to `heading 4`) and carry an
+outline level. That is what makes the navigation pane, *References > Table of Contents* and
+"Heading" in the styles gallery work. A custom style that only looks like a heading does none of
+this. Each heading also gets a bookmark named from its GitHub-style slug, so a link to `#retiring-the-alias`
+becomes an internal link. A link to an anchor with no matching heading is kept as plain text, with a warning.
+
+Title order: `--title`, then `title:` in YAML front matter, then the first `#` heading, then the
+file name. The title goes into File > Properties; it doesn't add a line to the page.
+
+## Lists
+
+- A line is a list item when it starts with `-`, `*`, `+`, or a number followed by `.` or `)`.
+- An item indented two or more spaces beyond the first item's marker is level 2. Anything deeper
+  is flattened to level 2 with a warning: Word handles deep nesting, but a reader of a converted
+  report rarely does.
+- Level 1 numbers as `1.`, level 2 as `a.`. Bullets are `•` then `o`.
+- A numbered list that starts at `3.` starts at 3 in Word.
+- A code block or table inside a list item is written as plain text in the item, with a warning.
+  Move it out of the list.
+
+## Tables
+
+The first row is the header: bold, shaded `F2F2F2`, and marked to repeat at the top of each page.
+Alignment comes from the separator row (`:---` left, `---:` right, `:---:` centre). Columns are
+equal width at first; Word's autofit adjusts them when the reader edits. A row with more or fewer
+cells than the header is padded or cut, with a warning naming the row.
+
+## Images
+
+PNG and JPEG only. Size comes from the pixel dimensions and the DPI stored in the file (PNG
+`pHYs`, JPEG JFIF). Without a stored DPI, 96 is assumed. An image wider than the text column
+(6.5 in on Letter, 6.27 in on A4, with 1 in margins) is scaled down with its aspect ratio kept.
+A paragraph that is only an image is centred. The alt text is stored as the picture description,
+which screen readers read.
+
+Not embedded, with a warning, and the alt text written in brackets instead: `http(s)://` and
+`data:` images, missing files, GIF, SVG and WebP. Convert SVG to PNG first.
+
+## Brand
+
+`--brand` reads these brand.json fields from brand-kit, and ignores the rest:
+
+| brand.json | Used for | Default |
+|---|---|---|
+| `fonts.heading.family` | Heading 1 to 4 and Title | Calibri |
+| `fonts.body.family` | Normal text, lists, tables | Calibri |
+| `colors.primary` | Heading colour | `#1F3864` |
+| `colors.text` | Body text colour | `#222222` |
+
+A colour that isn't a 6-digit hex code is ignored, with a warning. Fonts are named, not
+embedded: a reader without the font sees Word's substitute. Brand fonts that are web-only
+(Google Fonts not installed locally) fall back on the reader's machine, so tell the user.
+
+## What is dropped, and why
+
+| Construct | Why it's dropped | What to do instead |
+|---|---|---|
+| Raw HTML blocks | No dependable mapping from arbitrary HTML to Word | Rewrite as Markdown; HTML tables as pipe tables |
+| Inline HTML tags | Same | The text is kept; `<br>` becomes a line break |
+| Footnotes `[^1]` | Word footnotes need a separate part and are rarely worth it in a converted draft | Fold the note into the sentence, or a "Notes" section |
+| Mermaid blocks | Rendering needs a browser engine | Render to PNG with mermaid-render, then embed the image |
+| Nesting past 2 levels | Flattened to keep the document readable | Split with a sub-heading |
+| YAML front matter | Not content | Its `title:` is used as the document title |
+
+## Exit codes
+
+`0` written (warnings may be printed); `1` bad input: file not found, not UTF-8, empty, binary,
+output not ending in `.docx`, output folder missing, or brand.json not valid JSON.