skilldrop-cli 1.1.3 → 1.2.0

package/catalogue.json

@@ -109,7 +109,6 @@
       "skills": [
         "audience-profile",
         "slide-outliner",
-        "deck-builder",
         "exec-summary",
         "decision-log",
         "guide-builder",
@@ -131,12 +130,10 @@
       ]
     },
     "create-on-brand-collateral": {
-      "for": "Marketers · designers · anyone making a deck or flyer",
-      "description": "Make collateral that looks like it came from your team: capture the brand once, then build decks and print-ready flyers with your logo, colours and fonts.",
+      "for": "Marketers · designers · anyone making a deck",
+      "description": "Make collateral that looks like it came from your team: capture the brand once, then build decks with your logo, colours and fonts.",
       "skills": [
         "brand-kit",
-        "deck-builder",
-        "marketing-flyer",
         "slide-outliner"
       ]
     },
@@ -149,9 +146,7 @@
         "output-hygiene",
         "file-to-markdown",
         "md-to-docx",
-        "md-to-html",
         "md-to-xlsx",
-        "mermaid-render",
         "md-to-pptx",
         "md-to-confluence"
       ]
@@ -218,6 +213,10 @@
     "tech-comparison-matrix": { "in": "0.16.13", "why": "On evals it was never revised against, the agent without it did as well, and its weighted totals were wrong in 4 of 8 runs." },
     "db-schema-design": { "in": "0.16.13", "why": "On evals it was never revised against, the agent without it met as many checks (73% against 71%) and got types, time zones and constraints right unprompted." },
     "metric-definition": { "in": "0.16.13", "why": "On evals it was never revised against, the agent without it did everything the skill teaches unprompted and won 13 of 16 blind verdicts." },
-    "contribution-wizard": { "in": "0.16.13", "why": "It prescribed a skill layout this catalogue no longer uses and imposed it on other repos. To add a skill to skilldrop, follow AGENTS.md and run validate.py." }
+    "contribution-wizard": { "in": "0.16.13", "why": "It prescribed a skill layout this catalogue no longer uses and imposed it on other repos. To add a skill to skilldrop, follow AGENTS.md and run validate.py." },
+    "md-to-html": { "in": "1.2.0", "why": "On its held-out evals, in each of two trials and with both blind judges, the agent without it made the better page: the skill's script showed raw HTML as text and its security policy blocked embeds, and it adds no rule the agent breaks." },
+    "mermaid-render": { "in": "1.2.0", "why": "On its held-out evals, in each of two trials and with both blind judges, the agent without it fixed the same diagrams, ran the Mermaid CLI itself and said plainly what it had not rendered; the skill adds no rule it breaks." },
+    "marketing-flyer": { "in": "1.2.0", "why": "On its held-out evals, in each of two trials and with both blind judges, the agent without it built the whole flyer with placeholders where the skill stopped or used a generic template; it adds no rule the agent breaks." },
+    "deck-builder": { "in": "1.2.0", "why": "On its held-out evals the agent without it built the better deck in each of two trials; rebuilt rule-first, with its script able to run, it still lost on fresh evals (judges 2 and 1 of 4; 69% of checks against 81%).", "instead": "md-to-pptx" }
   }
 }

package/model-routing.json

@@ -234,10 +234,6 @@
       "tier": "light",
       "rationale": "Extracts decisions/owners/dates from notes. Pattern extraction; escalate on long transcripts via large-input rule."
     },
-    "deck-builder": {
-      "tier": "standard",
-      "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning."
-    },
     "delivery-metrics-report": {
       "tier": "standard",
       "rationale": "A stdlib script computes every number; the model maps columns, checks data quality and interprets weekly trends against fixed DORA definitions, which is bounded judgment."
@@ -335,10 +331,6 @@
       "tier": "standard",
       "rationale": "Methodology synthesis against a fixed decision tree and pitfall catalog. Grading-method and metric choices need judgment but are bounded; escalate via ambiguous-input on novel task types."
     },
-    "marketing-flyer": {
-      "tier": "standard",
-      "rationale": "Writes short copy to fit and fills a spec for a deterministic builder. Bounded generation."
-    },
     "mcp-pairing": {
       "tier": "standard",
       "rationale": "Matching a loop's stages to the context each needs and the narrowest access that provides it is bounded judgment over a short checklist."
@@ -351,10 +343,6 @@
       "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."
     },
-    "md-to-html": {
-      "tier": "light",
-      "rationale": "A deterministic stdlib script does the conversion; the model picks options, fixes a few unsupported Markdown constructs and relays the script's warnings. Little judgment."
-    },
     "md-to-pptx": {
       "tier": "light",
       "rationale": "Mechanical conversion done by its script; the model only checks the outline maps to slides and reports what was dropped."
@@ -363,10 +351,6 @@
       "tier": "standard",
       "rationale": "A stdlib script types and writes the cells; the model shapes tables from the source (headings, units, one header row), decides whether formulas are safe to enable, and checks the per-sheet type counts against the data. Bounded, mostly mechanical judgment."
     },
-    "mermaid-render": {
-      "tier": "standard",
-      "rationale": "The script lints and renders deterministically, but fixing a broken diagram means reading the author's intent and rewriting syntax without changing nodes, edges or labels, and knowing when to ask instead."
-    },
     "migration-plan": {
       "tier": "standard",
       "rationale": "Phased plan synthesis with a strong template. Ordering judgment is bounded by the expand/migrate/contract pattern; escalate via ambiguous-input on contested, high-stakes cutovers."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/ai-engineering/skills/ai-usage-report/examples/weekly-engineering-team.md

@@ -8,7 +8,7 @@ A small synthetic event log demonstrating the three views — including graceful
 timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
 2026-05-19T09:14:23Z,alice@acme.example,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
 2026-05-19T09:14:55Z,alice@acme.example,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
-2026-05-19T09:18:02Z,alice@acme.example,deck-builder,sess-001,1,2026-05-19T14:30:00Z,success
+2026-05-19T09:18:02Z,alice@acme.example,slide-outliner,sess-001,1,2026-05-19T14:30:00Z,success
 2026-05-19T10:01:11Z,bob@acme.example,cursor,sess-014,0,,success
 2026-05-19T10:01:30Z,bob@acme.example,cursor,sess-015,0,,success
 2026-05-19T10:02:11Z,bob@acme.example,cursor,sess-016,0,,success

package/packs/ai-engineering/skills/ai-usage-report/templates/usage-event-schema.md

@@ -8,7 +8,7 @@ Input to `ai-usage-report` is a CSV or JSONL file. Each row / each JSON object i
 |---|---|---|
 | `timestamp` | ISO 8601 datetime | e.g. `2026-05-21T14:32:11Z` |
 | `user` | string | Stable identifier — email, handle, or employee ID. Use the same value for the same person across events. |
-| `tool` | string | What was invoked — e.g. `claude-code`, `cursor`, `copilot`, or a specific skill name like `deck-builder` |
+| `tool` | string | What was invoked — e.g. `claude-code`, `cursor`, `copilot`, or a specific skill name like `slide-outliner` |
 
 If any of these three is missing, the script exits with an error. They are the minimum needed to compute a volume report.
 
@@ -51,7 +51,7 @@ When a column is omitted, the report includes a *"Where signals are missing"* se
 timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
 2026-05-21T09:14:23Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
 2026-05-21T09:14:55Z,alice@acme.example,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
-2026-05-21T09:18:02Z,alice@acme.example,deck-builder,sess-001,1,2026-05-21T14:30:00Z,success
+2026-05-21T09:18:02Z,alice@acme.example,slide-outliner,sess-001,1,2026-05-21T14:30:00Z,success
 2026-05-21T10:01:11Z,bob@acme.example,cursor,sess-014,0,,success
 2026-05-21T10:01:30Z,bob@acme.example,cursor,sess-014,0,,success
 2026-05-21T14:22:08Z,carol@acme.example,claude-code,sess-029,1,2026-05-22T08:11:00Z,success

package/packs/converters/pack.json

@@ -1,7 +1,7 @@
 {
-  "description": "Turn Markdown into Word, Excel and HTML files that people outside engineering can open, turn their files back into Markdown, and render diagrams to images. Standard-library Python scripts, with nothing to install.",
+  "description": "Turn Markdown into Word, Excel, PowerPoint and Confluence files that people outside engineering can open, and turn their files back into Markdown. Standard-library Python scripts, with nothing to install.",
   "display_name": "Converters",
-  "keywords": ["convert", "markdown", "word", "docx", "excel", "xlsx", "html", "mermaid"],
+  "keywords": ["convert", "markdown", "word", "docx", "excel", "xlsx", "powerpoint", "confluence"],
   "links": {
     "documentation": "https://sananthanarayan.github.io/skilldrop/packs/converters/"
   },
@@ -20,10 +20,9 @@
   },
   "requires": ["core"],
   "journey": {
-    "when": "Your draft is in Markdown, but the people who need it work in Word, Excel or a browser, or they sent you their files and you want to work on them as Markdown.",
+    "when": "Your draft is in Markdown, but the people who need it work in Word, Excel, PowerPoint or Confluence, or they sent you their files and you want to work on them as Markdown.",
     "you_bring": [
       "the Markdown draft, or the Word, PDF, Excel or HTML files you were sent",
-      "any Mermaid diagrams the draft contains",
       "a brand.json from brand-kit, if the Word file should be in your brand",
       "who it is for, and whether they edit it, calculate with it or only read it"
     ],
@@ -39,11 +38,6 @@
         "you_do": "Run it on the finished draft before it leaves the team.",
         "you_get": "The draft with invisible characters and generated-by trailers stripped, and machine-sounding lines flagged with rewrites."
       },
-      {
-        "skill": "mermaid-render",
-        "you_do": "If the draft has Mermaid diagrams, render them.",
-        "you_get": "Each diagram checked for the errors that stop it rendering, then an SVG or PNG per diagram to embed in the Word or HTML version (PNG and SVG need mermaid-cli installed)."
-      },
       {
         "skill": "md-to-docx",
         "you_do": "Convert the draft for readers who will edit or comment in Word.",
@@ -54,11 +48,6 @@
         "skill": "md-to-xlsx",
         "you_do": "Convert the tables for readers who will filter or total them.",
         "you_get": "A .xlsx with one sheet per table, typed numbers, dates and percentages, and formulas off unless you ask."
-      },
-      {
-        "skill": "md-to-html",
-        "you_do": "Convert the draft for readers who only need to read it in a browser.",
-        "you_get": "One self-contained, print-friendly HTML file with images embedded, so it still works when emailed."
       }
     ],
     "you_end_with": "The same content in the format each reader uses, with nothing dropped silently, and a Markdown source you can keep editing."

package/packs/converters/skills/file-to-markdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-to-markdown
-description: Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file, email (.eml or Outlook .msg) or PDF into clean Markdown that keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes, and reports everything it dropped (images, charts, comments, formulas, tracked changes), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json, .eml, .msg or .pdf and says "read this", "turn this into markdown", "extract the text", or wants it critiqued or briefed.
+description: Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file, email (.eml or Outlook .msg) or PDF into clean Markdown. It keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes. It saves embedded images beside the Markdown and links them, shows tracked changes as pending rather than accepted, and reports everything else it dropped (charts, comments, formulas), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json, .eml, .msg or .pdf and says "read this", "turn this into markdown", "extract the text", or wants it critiqued or briefed.
 ---
 
 # file-to-markdown
@@ -9,7 +9,7 @@ You turn the files people actually send (a Word draft, last quarter's deck, a bu
 a saved web page) into Markdown an agent can read reliably. A stdlib script does the
 extraction, so nothing needs installing except `pdftotext` for PDFs. The Markdown is rarely
 the end product: it is the input to `doc-critique` (review it), `brief-intake` (structure it),
-or a rewrite that goes back out through `md-to-docx` or `md-to-html`.
+or a rewrite that goes back out through `md-to-docx`.
 
 ## How to respond
 
@@ -19,7 +19,7 @@ or a rewrite that goes back out through `md-to-docx` or `md-to-html`.
 - **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
 - **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
 - **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** Put the converted text in front of the user: write the file, and say what did not convert, with counts.
+- **For this skill:** Put the converted text in front of the user: write the file, and say what did not convert, with counts. Never settle what the source leaves open: a tracked change stays pending, and a figure the source contradicts is not copied silently into something meant to be pasted.
 
 1. **Ask once for anything missing.** Usually only the file is needed:
 
@@ -36,12 +36,14 @@ or a rewrite that goes back out through `md-to-docx` or `md-to-html`.
    python3 scripts/to_markdown.py input.docx -o input.md
    ```
 
-   `-o -` writes to stdout. `--max-rows 200` caps each sheet of an `.xlsx`.
+   `-o -` writes to stdout. `--max-rows 200` caps each sheet of an `.xlsx`. Images embedded in a
+   `.docx` or `.pptx` are saved to `<name>-images/` beside the output and linked where they sat,
+   with their alt text; to stdout there is nowhere to save them, so they are counted as dropped.
 
    | Input | What comes through |
    |---|---|
-   | `.docx` | Headings by style (Title, Heading 1–6, outline level), bulleted and numbered lists with nesting, tables, bold, italic, hyperlinks |
-   | `.pptx` | One `## Slide N: title` section per slide, bullets with levels, tables, speaker notes as a quote |
+   | `.docx` | Headings by style (Title, Heading 1–6, outline level), bulleted and numbered lists with nesting, tables, bold, italic, hyperlinks, embedded images; tracked changes as `{++added++}` and `{--removed--}` |
+   | `.pptx` | One `## Slide N: title` section per slide, bullets with levels, tables, pictures, speaker notes as a quote |
    | `.xlsx` | One table per sheet, shared strings, numbers as stored, dates as `YYYY-MM-DD`, cached formula values |
    | `.html` | Headings, lists, tables, links, code blocks, quotes; scripts, styles and nav menus dropped |
    | `.csv` / `.tsv` | One table, delimiter detected |
@@ -63,13 +65,24 @@ or a rewrite that goes back out through `md-to-docx` or `md-to-html`.
    refuses and names the format to save as. On macOS, `textutil -convert docx file.doc`
    handles `.doc` and `.rtf`, though it writes no heading styles, so check the levels.
 
-5. **Report what was dropped, every time.** The script prints three kinds of line to stderr:
-   `converted …` (what was kept), `dropped …` (images, charts, comments, footnotes, formulas,
-   tracked changes, headers and footers), and `note: …` (headings inferred from font size,
+5. **Keep pending changes pending.** A tracked insertion or deletion comes through in
+   CriticMarkup, `{++added++}` and `{--removed--}`, because nobody has accepted it yet. Say
+   how many there are and that they are pending. When a comment or the request settles one
+   ("use 48, as Kim's comment says"), make that one edit and say so; leave the rest marked.
+
+6. **Don't copy a contradiction into a deliverable.** When the source contradicts itself (a
+   total that doesn't add up, a figure stated two ways), say so with both numbers. If the
+   request is for something to paste or publish ("just the table"), leave the contradicted
+   cell or row out, or mark it, and say which in one line. A Markdown copy for reading keeps it
+   as stored, flagged.
+
+7. **Report what was dropped, every time.** The script prints three kinds of line to stderr:
+   `converted …` (what was kept), `dropped …` (charts, comments, footnotes, formulas, headers
+   and footers, and images when there was nowhere to save them), and `note: …` (headings inferred from font size,
    merged cells, truncated sheets). Put them at the top of the reply in plain words: "The
    deck has 4 charts that are not in the Markdown; their numbers are missing from what I read."
 
-6. **Then do the next step the user asked for.** When a critique or brief depends on a chart
+8. **Then do the next step the user asked for.** When a critique or brief depends on a chart
    or comment that was dropped, say so in that output too. Don't let it read as complete.
 
 **Non-interactive runs** (subagent, CI, headless): convert with the defaults and prefix the
@@ -88,6 +101,9 @@ missing, emit `BLOCKED: need <the file | pdftotext on PATH>` and stop.
 - **Nothing is added.** The Markdown holds only what the file holds: no summaries, no invented headings, no filled-in empty cells.
 - **Speaker notes stay attached to their slide,** because that is often where the real argument is.
 - **Numbers are copied as stored.** No rounding, no currency symbols added; dates converted only when the cell is formatted as a date.
+- **Images come through as files.** An embedded image is saved and linked where it sat, with its alt text, not reduced to a caption.
+- **Tracked changes stay pending.** They are marked, counted and said to be unaccepted; only one the user or a comment settles is applied, and the reply says so.
+- **A contradiction isn't pasted silently.** Both figures are named, and a deliverable meant for pasting leaves it out or marks it.
 - **Inferred structure is flagged.** When headings come from font size instead of styles, the reply says to check the levels.
 
 ## When to use this skill
@@ -100,7 +116,6 @@ missing, emit `BLOCKED: need <the file | pdftotext on PATH>` and stop.
 ## When NOT to use this skill
 
 - ❌ Going the other way, Markdown to Word; use `md-to-docx`
-- ❌ Markdown to a web page; use `md-to-html`
 - ❌ Markdown tables into a workbook; use `md-to-xlsx`
 - ❌ Messy notes, a Slack thread or a transcript that are already text; use `brief-intake` directly
 - ❌ A document that is already Markdown and needs reviewing; use `doc-critique` directly
@@ -110,6 +125,8 @@ missing, emit `BLOCKED: need <the file | pdftotext on PATH>` and stop.
 - ❌ **Summarising instead of converting.** The user asked for the document; give them the document, then summarise if asked.
 - ❌ **Hiding the dropped list** below the Markdown, or leaving it out because "it's only images". A chart is often the slide's whole point.
 - ❌ **Reading a PDF as raw bytes** when `pdftotext` is missing. Ask the user to install it or export the PDF to .docx.
+- ❌ **Writing an unaccepted tracked change as the text.** It reads as agreed when it isn't.
+- ❌ **Pasting a total you've just said is wrong** into the table the user will publish.
 - ❌ **Treating inferred headings as fact.** A bold, large line in an unstyled document might be a pull quote.
 - ❌ **Critiquing a deck from its Markdown** without saying the charts and images were not seen.
 - ❌ **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.

package/packs/converters/skills/file-to-markdown/evals/evals.json

@@ -49,6 +49,36 @@
         "It does not invent varieties, numbers, donors or notes that are not in the file",
         "The reply is the table plus at most a couple of short lines, with no long explanation, and it delivers without asking questions first"
       ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-27",
+      "prompt": "Our procurement lead just forwarded supplier_agreement_v3.docx and it still has Legal's markup in it. Can you turn it into Markdown for our Confluence page, and tell me which bits haven't actually been agreed yet? Please don't accept anything on my behalf.",
+      "assertions": [
+        "Writes a Markdown file with 'Master Supply Agreement' as the top heading and the five numbered sections ('1. Payment terms' through '5. Price schedule') as subheadings. The three supplier obligations are a bulleted list, 'EUR 250,000' is bold and 'gross negligence' is italic.",
+        "Renders the price schedule as a Markdown table with the header Part number | Unit price | Minimum order quantity and the rows VP-110 / EUR 42.00 / 500 and VP-220 / EUR 57.50 / 250. Keeps 'supplier portal' as a Markdown link to https://supplier.example.com/terms.",
+        "Shows the payment-terms change as pending rather than accepted: the deleted '30' and the inserted '60' are both visible and marked as a proposed change by J. Okafor. It does not present the clause as simply 'payable within 60 days' as if it were agreed.",
+        "Shows the deleted sentence 'No termination fee applies.' (M. Lindqvist) as a pending deletion that is still visible and marked, not silently dropped. Shows the ISO 9001 obligation bullet as a pending insertion by J. Okafor, not as an agreed obligation.",
+        "Surfaces R. Achterberg's comment on the EUR 250,000 liability cap (asking to raise it to EUR 500,000, marked 'Not agreed yet') as an open item, either inline or in a notes or dropped-items list.",
+        "Answers the question directly with a short list of what is not yet agreed: exactly three tracked changes (30 to 60 days; the inserted ISO 9001 obligation; the deleted termination-fee sentence) and one open comment on the liability cap. It accepts or rejects none of them and leaves supplier_agreement_v3.docx unchanged.",
+        "Saves the embedded logo image as an image file next to the Markdown (for example in a sibling folder) and links it from the Markdown with a relative image link.",
+        "Invents nothing that is not in the document: no extra clauses, parties, prices, dates, authors or comments. Names, figures and the portal URL match the file exactly."
+      ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-27",
+      "prompt": "can u turn the offsite deck + numbers into md for the board pack. sarah says the notes are where the real story is. offsite_q3.pptx and numbers.xlsx, need it today thx",
+      "assertions": [
+        "Produces Markdown covering both files. The three slide titles 'Q3 Offsite: Where We Landed', 'Revenue by region' and 'APAC launch' appear in that order as headings, each with its bullets, and each slide's speaker notes are kept and clearly labelled as notes under the right slide.",
+        "Converts both worksheets, each identified by its name: Regions as a Markdown table (EMEA 120 / 110, North America 140 / 130, LATAM 160 / 150, Total row) and Assumptions (FX rate GBP/EUR 1.17; Source: Finance close 10 Oct 2026).",
+        "Reports that the bar chart on slide 2 is not reproduced as a chart, either as a dropped item or as a text summary. Any figures it gives for the chart are exactly the values cached in it (EMEA 120, North America 140, LATAM 160), and no chart values are made up.",
+        "Flags that the Regions Total in B5 is the formula =SUM(B2:B4) with a stored value of 410, while the three rows sum to 420 (120+140+160). It treats the total as stale or inconsistent rather than silently showing 410 or quietly correcting it to 420. The Plan total of 390 does match its rows.",
+        "Warns the user, beyond just copying the notes, that the slide 3 notes say the £250k APAC first-year target must not go into the board pack (finance hasn't signed it off; say 'target under review'). It neither leaves £250k in board-pack-ready output without a warning nor deletes it silently.",
+        "Relays the 'real story' from the slide 2 notes, since the user pointed to them: North America beat plan only because of the one-off Kestrel Sports order (£35k), and without it NA is at 105 against a plan of 130.",
+        "Invents nothing that is not in the files: no extra slides, regions, APAC actuals, prior-quarter LATAM figures, chart values or names beyond those present.",
+        "Is the right size for a rushed request. It delivers the Markdown file(s) straight away with a brief summary of the flagged issues, not a long essay or a rewritten board pack, and does not hold up the work with clarifying questions."
+      ]
     }
   ]
 }

package/packs/converters/skills/file-to-markdown/examples/mixed-inputs.md

@@ -11,7 +11,7 @@ actually printed.
 
 ## `acme-brief.docx`
 
-A Word brief with Title and Heading styles, bulleted and numbered lists, a hyperlink, a table, an image, a comment and a tracked change.
+A Word brief with Title and Heading styles, bulleted and numbered lists, a hyperlink, a table, an image, a comment and a tracked change. It is in [`inputs/`](inputs/acme-brief.docx).
 
 ```bash
 python3 scripts/to_markdown.py acme-brief.docx -o acme-brief.md
@@ -20,45 +20,51 @@ python3 scripts/to_markdown.py acme-brief.docx -o acme-brief.md
 stderr:
 
 ```text
-converted acme-brief.docx -> acme-brief.md: 4 headings, 5 list items, 1 tables
-dropped (not in the Markdown): 1 comments, 1 images, 1 tracked deletions (left out), 1 tracked insertions (kept as text)
+converted acme-brief.docx -> acme-brief.md: 4 headings, 5 list items, 1 images saved, 1 tables, 1 tracked deletions shown as {-- --}, 1 tracked insertions shown as {++ ++}
+dropped (not in the Markdown): 1 comments
+note: tracked changes are pending, not accepted: {++added++} and {--removed--} mark them. Accept or reject them in Word to settle the text
 ```
 
+The image is saved as `acme-brief-images/image1.png` and linked where it sat. The tracked change
+stays pending.
+
 Markdown:
 
 ````markdown
 # Acme migration brief
 
-# Background
+## Background
 
 We are moving **three services** to the new platform, *starting in November*. See the [project page](https://acme.example/migration).
 
-## Goals
+### Goals
 
 - Cut hosting cost
 - Retire the 2014 cluster
    - Including the batch jobs
 
-## Steps
+### Steps
 
 1. Inventory services
 2. Pilot with billing
 
 Architecture sketch:
 
-| Risk | Owner | Due |
+![Architecture sketch](acme-brief-images/image1.png)
+
+| **Risk** | **Owner** | **Due** |
 |---|---|---|
 | Vendor lock-in | Priya | 2026-11-01 |
 | Data residency \| EU | Tom | 2026-12-15 |
 
 Open question: who signs off the cutover?
 
-Kept text new wording
+Kept text {--old wording--}{++new wording++}
 ````
 
 ## `northwind-roadmap.pptx`
 
-A three-slide deck with a title slide, bullets at two levels, a picture, a chart and speaker notes on slide 2.
+A three-slide deck with a title slide, bullets at two levels, a picture and speaker notes on slide 2. It is in [`inputs/`](inputs/northwind-roadmap.pptx).
 
 ```bash
 python3 scripts/to_markdown.py northwind-roadmap.pptx -o northwind-roadmap.md
@@ -67,8 +73,8 @@ python3 scripts/to_markdown.py northwind-roadmap.pptx -o northwind-roadmap.md
 stderr:
 
 ```text
-converted northwind-roadmap.pptx -> northwind-roadmap.md: 3 slides, 1 slides with speaker notes
-dropped (not in the Markdown): 1 images, 1 charts
+converted northwind-roadmap.pptx -> northwind-roadmap.md: 3 slides, 1 images saved, 1 slides with speaker notes
+dropped: nothing detected
 ```
 
 Markdown:
@@ -84,6 +90,8 @@ Product review, 12 October
   - Cut setup time from 3 days to 4 hours
 - Usage-based billing
 
+![Shipped features](northwind-roadmap-images/image1.png)
+
 > **Speaker notes:** Mention the two pilot customers by segment, not by name.
 >
 > Pause for questions here.
@@ -241,7 +249,7 @@ Markdown:
 
 ## `ops-review.pdf`
 
-A two-page PDF printed from Chrome: the `md-to-html` example's output, so it has a title,
+A two-page PDF printed from Chrome, from an HTML page of the same report, so it has a title,
 a nested list, a table, a chart image, a Mermaid diagram kept as text, and a code block.
 
 ```bash
@@ -296,10 +304,10 @@ one page and continues on the next loses its header row to the previous page.
 ## What to tell the user (for the first three files)
 
 > I converted all three. Before we review, here is what is **not** in the Markdown:
-> - **Brief:** one embedded image (the architecture sketch) and one reviewer comment. A tracked
->   change was shown as accepted: "old wording" removed, "new wording" kept.
-> - **Deck:** the picture on slide 2 and the chart on slide 3 ("Adoption"). Slide 3's numbers
->   are missing from what I read; send the chart data if the review should cover it.
+> - **Brief:** one reviewer comment. Its image is saved beside the Markdown and linked. One
+>   tracked change is still pending ("old wording" deleted, "new wording" inserted), so it is
+>   marked, not accepted: say which way it should go.
+> - **Deck:** nothing. Its picture is saved and linked, and slide 2's speaker notes are kept.
 > - **Workbook:** the chart, and the two SUM formulas. Their last calculated values (16500 and
 >   17250.5) are in the table, but the formulas themselves are not.
 >

package/packs/converters/skills/file-to-markdown/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "file-to-markdown",
-  "version": "0.3.2",
-  "description": "Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file, email (.eml or Outlook .msg) or PDF into clean Markdown that keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes, and reports everything it dropped (images, charts, comments, formulas, tracked changes), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json, .eml, .msg or .pdf and says \"read this\", \"turn this into markdown\", \"extract the text\", or wants it critiqued or briefed.",
+  "version": "0.4.0",
+  "description": "Convert a Word document, PowerPoint deck, Excel workbook, web page, CSV, JSON, text file, email (.eml or Outlook .msg) or PDF into clean Markdown. It keeps headings, lists, tables, links, bold and italic, slide titles and speaker notes. It saves embedded images beside the Markdown and links them, shows tracked changes as pending rather than accepted, and reports everything else it dropped (charts, comments, formulas), so the content can be read, reviewed or fed to another skill. Use when the user hands over a .docx, .pptx, .xlsx, .html, .csv, .json, .eml, .msg or .pdf and says \"read this\", \"turn this into markdown\", \"extract the text\", or wants it critiqued or briefed.",
   "entrypoint": "SKILL.md",
   "deps": {
     "npm": [],
@@ -15,7 +15,6 @@
     "brief-intake",
     "doc-critique",
     "md-to-docx",
-    "md-to-html",
     "md-to-xlsx"
   ],
   "handoff": [