docx-editor

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

1. Call docx_inspect before editing an unfamiliar document. Keep sourceSha256, feature/security inventory, and capability report.
2. Call docx_read for only the relevant stories/blocks. Use returned paragraph IDs, paths, hashes, bookmarks, controls, or strict text anchors.
3. Call docx_render when pagination, layout, tables, images, headers/footers, or formatting matter. Keep page selections small.
4. Call docx_edit with dryRun: true; use exact preconditions and expected counts. Resolve ambiguity rather than broadening an edit.
5. Call docx_edit with dryRun: false and expectedSourceSha256 to create a staged revision. This tool must not receive a destination.
6. Call docx_validate and docx_diff against source and staged paths. Render focused before/after pages for visually sensitive operations.
7. Call docx_commit to a new .docx path by default.
8. 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.