| name | docx-editor |
| description | Safely inspect, search, render, edit, diff, validate, and commit Microsoft Word DOCX files with the dedicated docx_* tools. Use for DOCX/DOTX/DOCM/DOTM document work; enforces dry-run-first edits, active-content refusal, preservation checks, and save-as by default. |
| license | MIT |
| compatibility | Requires @firstpick/pi-extension-docx. Mutation requires its Open XML .NET sidecar; rendering requires ONLYOFFICE Desktop Editors or LibreOffice plus LiteParse. |
DOCX editor
Required workflow
- Call
docx_inspect before editing an unfamiliar document. Keep sourceSha256, feature/security inventory, and capability report.
- Call
docx_read for only the relevant stories/blocks. Use returned paragraph IDs, paths, hashes, bookmarks, controls, or strict text anchors.
- Call
docx_render when pagination, layout, tables, images, headers/footers, or formatting matter. Keep page selections small.
- Call
docx_edit with dryRun: true; use exact preconditions and expected counts. Resolve ambiguity rather than broadening an edit.
- Call
docx_edit with dryRun: false and expectedSourceSha256 to create a staged revision. This tool must not receive a destination.
- Call
docx_validate and docx_diff against source and staged paths. Render focused before/after pages for visually sensitive operations.
- Call
docx_commit to a new .docx path by default.
- Overwrite the source only when the user explicitly asked, hashes still agree, every gate passes, and interactive confirmation is available. Require a recovery path in the result.
Safety rules
- Never use built-in text
edit or write on DOCX/DOCM/DOTX/DOTM.
- Never execute macros, OLE, fields, links, DDE, or attached templates. Never claim they were executed or refreshed.
- Treat
.docm/.dotm, active content, and signatures as read/render only. Do not bypass SIGNED_DOCUMENT or ACTIVE_CONTENT_BLOCKED.
- Do not mutate raw XML, XPath, arbitrary ZIP parts, or page-number selectors.
- Do not silently convert formats. Legacy/template conversion must create a new
.docx and report losses.
- Stop on
LOSSY_OPERATION, protected-part changes, unavailable mandatory engines, validation failures, source/destination conflicts, or ambiguous selectors.
- Keep hidden/deleted metadata out of model-visible output unless the user explicitly asks to inspect it.
Verification
A successful tool return is not enough. Confirm source and staged/output hashes, declared changed parts, protected-part stability, Open XML validation, independent reopen, semantic diff, and required render checks. Report renderer/font warnings and any host gate that was not run.
