[P1] Expose extract_media so docx to markdown keeps embedded images #48

Links

• Epic: Tracking: gaps surfaced by an agent-driven document workflow (from #40) #44
• Origin: @pbarone's inbound workflow
• Evidence: docs/audits/2026-08-agent-workflow-audit.md → Finding 5

Problem

Converting a Word document to markdown silently loses every embedded image. Pandoc writes image references but does not write the image files unless --extract-media is passed, and the server does not expose it.

$ pandoc img.docx -t markdown
![alt text](media/rId9.png){...}     ← this file is never created

$ pandoc img.docx -t markdown --extract-media=./media
$ ls media/media
rId9.png                             ← now it exists

Why it matters

An agent converting an inbound Word document receives broken image links with no error and no warning. It cannot detect that content is missing, so it reasons over an incomplete document and does not know it.

Before designing the fix

• Commit a representative .docx fixture with real embedded images. The current reproduction used a synthetic one-pixel PNG and is not independently re-runnable
• Decide where extracted files land, and who owns cleanup
• Decide implicit vs explicit, see below

Acceptance criteria

• docx containing images converts to markdown with the image files present on disk
• When media is dropped and extraction was not requested, the tool result says so, so the model can react
• Test driven from the committed fixture
• README and CHEATSHEET document it in the inbound conversion workflow

Open design question

Implicit extraction is correct by default but writes files the caller did not request. Explicit is predictable but leaves the silent-loss default in place for anyone who does not know to ask.

Note on the API: adding an optional parameter is not a breaking change. additionalProperties: false rejects properties clients send that we do not know; adding a new optional property to the published schema is additive. The contract concern is about removing or renaming, not adding.