pod
Other formats agents might prefer:
markdownjsonllms.txt

Agent? You probably want markdown or json, or Pod over MCP.

Reported issues for Safe Docx

Pod holds 21 of 60 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to Safe Docx.

Most discussed

Submit SafeDocX to Cline MCP Marketplace

Task

Submit SafeDocX (@usejunior/docx-mcp) to the Cline MCP Marketplace for discovery by Cline/VS Code users.

Steps

  1. Prepare a 400x400 logo image
  2. Open an issue at cline/mcp-marketplace with:
    • Repo URL: https://github.com/UseJunior/safe-docx
    • Package: @usejunior/docx-mcp
    • Description: MCP server for reading, editing, and comparing Word documents with tracked changes. For Claude, Gemini CLI, Cursor, and any MCP client. MIT

Read the thread · 2026-05-04 · closed · 3 comments

CLI compare aborts with OpaquePassthroughError (w:sdt placement) on a document compare_documents handles fine

Summary

On one real document (a ~430 KB, ~1,000-paragraph form package), safe-docx compare aborts with an uncaught OpaquePassthroughError, while compare_documents compares the same pair successfully and writes a redline Word opens.

OpaquePassthroughError: Opaque passthrough: w:sdt placement is outside inline-run and direct body-block support
    at validateSdtNamespaceOwnership (packages/docx-compare/dist/baselines/atomizer/opaquePassthrough.js:482:19)
    at atomizeTree (pack

[Read the thread](https://github.com/UseJunior/safe-docx/issues/650) · 2026-07-26 · closed · 2 comments

### Add opt-in include_footnotes to read_file for single-call body + footnotes retrieval

# Add opt-in `include_footnotes` to `read_file` for single-call body + footnotes retrieval

## Problem

Today `read_file` returns the contents of `word/document.xml` — body paragraphs with inline footnote-reference markers `[^N]`. Footnotes themselves live in `word/footnotes.xml` and require a separate `get_footnotes` call. To fully reconstruct a document an agent must:

1. Call `read_file(format="json")` to get body paragraphs with `[^N]` markers.
2. Call `get_footnotes()` to get footnote bodie

[Read the thread](https://github.com/UseJunior/safe-docx/issues/207) · 2026-05-15 · closed · 2 comments

### Make tracked changes the canonical representation for the supported surface

## Context

Core edit primitives in `packages/docx-core/src/primitives/document.ts` are direct DOM mutations today; tracked-change output is reconstructed later by `compareDocuments(...)` in `packages/docx-mcp/src/tools/save.ts`. That reconstruction wraps deltas in fresh `w:ins`/`w:del` with the session's author/date, **destroying any pre-existing reviewer metadata**.

The reframe: SafeDocX today is *re-authoring* tracked changes. After this issue lands, it *co-authors*.

## Proposal

For every 

[Read the thread](https://github.com/UseJunior/safe-docx/issues/120) · 2026-05-03 · closed · 2 comments

### compare_documents: wire the optional Lean integrity certificate through MCP and CLI

## Summary

`docs/trust-and-conformance.md` says `compare_documents` accepts `verify_document_integrity=true`, but the MCP tool schema and implementation do not expose or forward that option. The library-level comparator supports `leanXmlVerifier`, while normal MCP and CLI comparison paths cannot request a certificate.

This is both a documentation defect and a missing production integration.

## Current behavior

- `CompareOptions.leanXmlVerifier` exists and defaults to disabled.
- `compareDocu

[Read the thread](https://github.com/UseJunior/safe-docx/issues/715) · 2026-07-29 · closed · 1 comment

### docx-mcp: no formatting-convention check for inserted runs — a new defined term can land off-convention and pass every gate

## Summary

When an edit introduces a new construct that the document already formats by convention — an inline defined term, a proviso, a cross-reference — nothing compares the inserted run's properties against how that construct is formatted everywhere else. The edit is well-formed, round-trips, and renders. It is simply inconsistent, and no gate can see that.

Depends on #686 (there is currently nowhere for such a warning to be returned).

## Concrete failure class

A replacement introduced a

[Read the thread](https://github.com/UseJunior/safe-docx/issues/687) · 2026-07-27 · closed · 1 comment

### Project SafeDocX capability evidence from the neutral registry

## Summary

Add a reproducible SafeDocX projection of the canonical capability registry introduced by open-agreements/docx-platform-tests#51. The projection must distinguish implementation claims from neutral capability definitions and tie each claimed support axis to executable local evidence.

## Scope

- Pin the upstream registry version and commit used by SafeDocX.
- Represent SafeDocX status per capability axis without duplicating neutral definitions.
- Require exact evidence references for

[Read the thread](https://github.com/UseJunior/safe-docx/issues/601) · 2026-07-22 · closed · 1 comment

### spec-coverage: WARN on high .openspec tag density unless an explicit coverage-rationale annotation is present

## Problem

A single test carrying many `.openspec('[ID] …')` tags is a tag-stuffing smell — one assertion claiming to discharge several distinct scenarios. But it is sometimes **legitimate**: the Lean bridge test in `lean-spec-bridge.test.ts` genuinely maps a cluster of `[LEAN-RT-*]`/`[LEAN-FBA-*]` scenarios to one property/fixture test by accepted convention. Today that legitimacy is **invisible** — a reviewer can't distinguish "deliberately maps a related cluster" from "stuffed N tags to hit 

[Read the thread](https://github.com/UseJunior/safe-docx/issues/515) · 2026-06-20 · closed · 1 comment

## Most recent

### Introduce a shared typed InlineSpan representation for rich text

## Problem

`safe-docx` currently represents inline formatting in several overlapping forms:

- `formatting_tags.ts` emits an HTML-shaped `tagged_text` string.
- `serialize_markdown.ts` and `serialize_html.ts` independently translate that representation.
- `tag_parser.ts` parses an allowlisted tag syntax into `ReplacementPart[]` for edits.
- `AddRunProps` and `ReplacementPart` are the typed structures that ultimately drive OOXML changes.

The string representations duplicate tokenization and for

[Read the thread](https://github.com/UseJunior/safe-docx/issues/958) · 2026-08-29 · open · 0 comments

### replace_text: surface a warning when an embedded object is preserved outside the replaced range

## Problem

PR #869 (fixes #739) makes `replaceParagraphTextRange()` preserve embedded objects (`w:drawing`/`w:pict`/`w:object`) caught in a replaced text range as live runs instead of silently destroying them. The preservation can reposition an object (a mixed text+object run is split so the object lands before the tracked deletion / replacement text), and the caller currently gets **no signal** that an embedded object was touched at all.

`replace_text` responses do carry a runtime `warnings` 

[Read the thread](https://github.com/UseJunior/safe-docx/issues/870) · 2026-08-16 · open · 0 comments

### docx-core: extract_revisions never visits w:trPr — row-level revisions invisible to pre-operation inspection

A caller who wants to know whether a document carries table-row revisions before running `acceptChanges`/`rejectChanges` has no way to find out: `extractRevisions` never visits `w:trPr`, so row-level revision markers and row-level property changes are invisible to the one inspection surface the library offers.

## Behavior

`packages/docx-core/src/primitives/extract_revisions.ts` scans paragraph-scoped content. `REVISION_WRAPPER_LOCALS` (`ins`, `del`, `moveFrom`, `moveTo`) is matched against par

[Read the thread](https://github.com/UseJunior/safe-docx/issues/868) · 2026-08-16 · open · 0 comments

### docx-release-verifier: comment integrity passes when IDs are duplicated identically across all four collections

## Summary

`commentIntegrity` in `packages/docx-release-verifier/src/archive.ts` compares comment ID lists by membership and total length, not by multiplicity. A tracked DOCX whose comment IDs are duplicated *identically* across all four sides — `commentRangeStart`, `commentRangeEnd`, `commentReference`, and the `w:comment` definitions — satisfies every consistency check and returns a required `pass`.

This is the sibling of #858. That issue fixed the empty-set vacuous pass; this is the same he

[Read the thread](https://github.com/UseJunior/safe-docx/issues/863) · 2026-08-15 · closed · 0 comments

### Bench note: Word-oracle redline results for compareDocuments at 7bd35c8 (PR 854) — and thank you

Thank you for shipping a real headless `compareDocuments` path, and for [PR 854](https://github.com/UseJunior/safe-docx/pull/854). We benchmarked **the merge commit** `7bd35c876493f2725b095f0190c28d2644962c78`, not published `@usejunior/docx-compare@0.19.1` (that tarball is 2026-07-24 and predates the field-husk retraction).

We called the library once per pair:

```ts
compareDocuments(original, revised, { engine: "atomizer", author: "safe-docx" })

No reconstruction of fields, no accept/rej

Read the thread · 2026-08-15 · open · external user · 0 comments

docx-compare: DOCX_COMPARISON_DEBUG diagnostics corrupt MCP stdio, and the #809 stdio test does not pin the console.log race

Follow-up from the post-merge Codex peer review of PR #812 (squash 2faf570), which removed the obsolete process-global console.log suppression around compare_documents (issue #809). The review landed after the merge and found two real gaps, both re-verified by execution in a fresh worktree off origin/main @ e511bbe.

Finding 1 (P1): DOCX_COMPARISON_DEBUG still corrupts the MCP stdio protocol

packages/docx-compare/src/baselines/atomizer/debug.ts emits enabled diagnostics via `co

Read the thread · 2026-08-12 · closed · 0 comments

fix(docx-mcp): remove obsolete process-global console.log suppression that can permanently silence stdout under concurrent compares

Summary

packages/docx-mcp/src/tools/compare_documents.ts still carries runWithoutConsoleLog (lines 19–28), a workaround that swapped the process-global console.log for a no-op around each compareDocuments call to keep library debug output off the stdio JSON-RPC stream. The output it suppressed — the unconditional [DEBUG] atomizeTree: … emit in packages/docx-compare/src/atomizer.ts — was removed by #785 (issue #783, merged as 8035dce). The workaround is now obsolete, and it was

Read the thread · 2026-08-11 · closed · 0 comments

fix(docx-compare): published compare bins default to rebuild while MCP and safe-docx CLIs use inplace, and requested mode is reported as actual

Summary

Two related defects in the shipped @usejunior/docx-compare CLI (docx-comparison / safe-docx-compare bins, published at 0.19.1), verified on origin/main @ 6ee04703:

  1. Divergent default reconstruction mode across shipped front doors. The docx-compare bins and the library API default to rebuild, while the MCP compare_documents tool and the safe-docx/safedocx CLIs default to inplace. Same input, same engine, different output fidelity depending on which front doo

Read the thread · 2026-08-11 · closed · 0 comments

fix(docx-mcp): accept -o/--output for the compare redline path

Problem

safe-docx compare accepts its redline destination only positionally:

compare <original> <revised> [output]

The rest of the CLI does not work that way. parseToolFlags maps -o and --output to the output path for the tool commands (packages/docx-mcp/src/cli/flag_parser.ts:39), and the top-level help advertises exactly that shape for edit:

  compare <original> <revised> [output]       Compare two DOCX files and write redline output
  edit <file> [--replace 

[Read the thread](https://github.com/UseJunior/safe-docx/issues/782) · 2026-08-04 · closed · 0 comments

### feat(docx-core): add scoped field evaluation and field-aware comparison

## Parent

Follow-up to #761.

## Why

Safe Docx already preserves supported complex-field structures and distinguishes substantive TOC entry edits from volatile cached page-number changes. It does not evaluate Word fields, so cross-references can remain stale after edits and comparison cannot always distinguish an authored field change from a recalculated result.

Legal documents rely heavily on REF, SEQ, PAGEREF, TOC, PAGE, and NUMPAGES. The product needs an explicit field semantics layer with

[Read the thread](https://github.com/UseJunior/safe-docx/issues/762) · 2026-07-29 · closed · 0 comments

### docs(site): publish an evidence-backed capabilities page

## Why

The public website currently presents Safe Docx mainly as a tool inventory. Prospective users evaluate document systems in terms of recognizable Word capabilities: paragraphs, tables, tracked changes, fields and TOCs, comments, headers/footers, footnotes/endnotes, formats, and export behavior.

A capability-oriented page would make the implemented surface easier to understand while preserving Safe Docx's evidence-backed trust model. It must distinguish **read**, **edit**, **compare/redli

[Read the thread](https://github.com/UseJunior/safe-docx/issues/761) · 2026-07-29 · open · 0 comments

### docx-mcp: replace_text drops validator warnings on success and has no warnings field

## Summary

`replace_text` returns no `warnings` field, and the only validator on its path structurally discards warnings whenever the edit succeeds. An edit can therefore be accepted, round-trip cleanly, and render correctly while a validator had something to say about it that nobody ever sees.

## Evidence

`preflightAiRevisionMutation` returns early on success, so `validation.warnings` is unreachable:

```ts
const validation = await previewDoc.validateAiRevisions(session.aiAuthor, touched);
i

[Read the thread](https://github.com/UseJunior/safe-docx/issues/686) · 2026-07-27 · closed · 0 comments

### No editing surface for headers and footers: cannot read, edit, create or attach a footer part

## Summary

Headers and footers are not reachable from any tool. `read_file` does not return
them, and no editing tool writes them. A running footer cannot be read, edited,
created, or attached to a section.

The case that sent me to raw XML: a block of appendix pages inherited the running
footer of the section that follows them, so four pages carried the wrong caption.
Doing it by hand meant all of:

1. write `word/footerN.xml`
2. add a `footer` relationship to `word/_rels/document.xml.rels`
3.

[Read the thread](https://github.com/UseJunior/safe-docx/issues/655) · 2026-07-26 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/UseJunior/safe-docx/issues).