pilcrow-docx 0.1.1__tar.gz

pilcrow_docx-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include docs *.md
+recursive-include tests *.py
+include scripts/bump_version.py

pilcrow_docx-0.1.1/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: pilcrow-docx
+Version: 0.1.1
+Summary: Readable DOCX companion diffs for ordinary Git workflows
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: defusedxml<1,>=0.7.1
+
+# Pilcrow
+
+Pilcrow makes Word text changes reviewable in GitHub Desktop. Keep editing the
+`.docx`; export readable companion files and commit both through your normal Git
+workflow. **The DOCX is authoritative.** The prose is a generated review artifact,
+not an editable replacement or a round-trip format.
+
+This is an independent, small Python implementation, conceptually inspired by the
+companion-file approach of stet. No source or tests were copied from that project.
+
+## Install locally
+
+Requires Python 3.10 or later. Git is needed for repository discovery and the Git
+workflow. Word is not required to export. From this project's directory:
+
+```sh
+python -m pip install .
+pilcrow --help
+```
+
+Use `python3` instead of `python` on systems where needed. A virtual environment
+is recommended (`python -m venv .venv`); activate it before installing:
+
+- macOS/Linux: `source .venv/bin/activate`
+- Windows PowerShell: `.venv\Scripts\Activate.ps1`
+- Windows Command Prompt: `.venv\Scripts\activate.bat`
+
+If activation is unavailable, invoke `.venv/bin/python` or
+`.venv\Scripts\python.exe` directly with `-m pip install .`, then `-m pilcrow`.
+For development, use `python -m pip install -e .`.
+
+Pilcrow uses Python's ZIP reader and `defusedxml` for XML parsing. There is no Word
+process, cloud service, AI connection, watcher, or background service. Extraction
+never writes to the DOCX.
+
+## Baseline, then review a change
+
+In **your document repository**, choose an explicit scope. For example:
+
+```sh
+pilcrow export --all --root .
+pilcrow check --all --root .
+```
+
+Or select documents (paths are relative to your current directory):
+
+```sh
+pilcrow export "report.docx" "chapters/Methods and results.docx" --root .
+```
+
+Outputs retain the complete source-relative filename:
+
+```text
+report.docx
+chapters/Methods and results.docx
+.pilcrow/report.docx.prose.md
+.pilcrow/report.docx.meta.json
+.pilcrow/chapters/Methods and results.docx.prose.md
+.pilcrow/chapters/Methods and results.docx.meta.json
+```
+
+1. Export a baseline. In GitHub Desktop, review and commit the DOCX and its two
+   companion files together. Do not put `.pilcrow/` in `.gitignore`.
+2. Edit and save the DOCX in Word, or use a separate document-editing tool.
+3. Run the same `pilcrow export` command again.
+4. In Desktop's **Changes** view, select the `.prose.md` file to read the text diff;
+   inspect `.meta.json` for review/coverage changes. The DOCX may still say binary
+   changed. Review formatting/images in Word when relevant.
+5. Commit the DOCX and both companions together through Desktop, then push and
+   branch normally. Desktop's **History** view can show committed companion diffs.
+
+Pilcrow never stages, commits, pushes, switches branches, or merges. No direct
+DOCX text converter is installed. The CLI and an ordinary Git diff have been
+tested; **the Microsoft Word / GitHub Desktop GUI workflow has not been tested in
+this Linux environment**. See [manual validation](docs/manual-validation.md).
+See an [actual generated prose and Git diff example](docs/example.md).
+Old commits without companions will not gain prose diffs automatically; there is
+no backfill or history rewriting.
+
+## Scope and discovery
+
+- `--root` defaults to the **current directory**, never an automatically detected
+  repository top. It controls both discovery and the location of `.pilcrow/`.
+  Use the same root each time. From a subdirectory, pass `--root ..` deliberately
+  if the output belongs at the parent. Explicit paths remain relative to the
+  current directory, not to `--root`.
+- Supply paths **or** `--all`. No arguments does not silently scan the machine.
+  Passing a directory as a document is an error; use `--all --root directory`.
+- Inside Git, `--all` uses `git ls-files` for tracked and nonignored untracked
+  files within the selected root. Tracked files remain included even if an ignore
+  rule matches. An explicitly selected ignored DOCX is allowed.
+- Outside Git, `--all` recursively walks the selected directory. Git ignore rules
+  only apply inside a Git worktree; there is no separate ignore syntax.
+- Both modes exclude Word lock files (`~$…`), `.pilcrow`, `.git`, `.venv`, `venv`,
+  `env`, `node_modules`, `__pycache__`, `.tox`, `.nox`, `build`, and `dist`.
+  Extension matching is case-insensitive. Unicode and spaces are supported.
+- Symlink files/paths are rejected; directory walking does not follow symlink
+  directories. Submodule documents are not recursively discovered from the parent
+  repository: select a root inside the submodule.
+- `--all` reports orphan companions after source deletion/rename. Remove the old
+  companion files manually if the deletion was intentional and commit those
+  deletions together. Export never automatically deletes review history files.
+  Explicit-file mode checks only selected inputs, not unrelated orphans.
+
+## Check before committing
+
+```sh
+pilcrow check --all --root .
+```
+
+`check` is read-only, even when files are missing. It recomputes expected prose and
+metadata and compares bytes, tolerating ZIP order/compression, run boundaries,
+save timestamps, and other ignored Word metadata. It does not use a DOCX-byte hash.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Successful export, or companions match the supported normalized view |
+| 1 | Missing/stale companions in `check`, or orphan companions in either command |
+| 2 | Invalid selection, unreadable/malformed input, unsafe path, or write failure |
+
+Errors identify the file; remaining selected documents are processed after a
+per-document error. Retry after Word has finished saving if a file is temporarily
+unreadable or changes during extraction. A fresh result means **no supported
+prose/review changes detected**, never that the complete document is identical.
+Warnings appear on stderr and in metadata even for fresh results. Known coverage
+limitations do not themselves cause a nonzero exit.
+
+Writes use a temporary file and atomic replacement in the destination directory.
+Byte-identical outputs keep their existing modification times. Each file is
+atomic, **not the whole pair or batch**: if interrupted between files, run `check`
+and export again. Avoid concurrent exports into the same root.
+
+## Branches and conflicts
+
+Opt in to conservative merge rules once, from your document repository root:
+
+```sh
+pilcrow setup --root .
+```
+
+This appends a managed block to `.gitattributes`, preserving other rules. Repeating
+it is harmless. Review and commit the file through Desktop. Rules mark DOCX and
+all `.pilcrow/` files `-merge` (Git's binary merge driver), and companion files as
+`text eol=lf`. Both-sided modifications conflict instead of automatically merging
+prose into a document that never existed. Normal one-sided changes still merge.
+More-specific nested attributes can override these rules; inspect with
+`git check-attr merge -- "report.docx" ".pilcrow/report.docx.prose.md"` if needed.
+
+When branches conflict:
+
+1. Preserve copies of both versions of the DOCX outside the conflicted path.
+2. Choose the authoritative version or reconcile the documents manually in Word.
+   If using Git commands to select a side, make sure you understand that side in
+   the current merge/rebase. Pilcrow does not make this choice.
+3. Put the resolved DOCX at its repository path. Regenerate its companions, even
+   if Git did not flag them as conflicted. Never independently accept a merged
+   prose artifact as the Word document.
+4. Run `pilcrow check --all --root .`. Inspect the resulting text and Word file,
+   then mark resolutions and commit using your normal Git workflow.
+
+Git commit identity attributes a snapshot, not every contributor between saves.
+For basic snapshot attribution:
+
+```sh
+git blame -- ".pilcrow/report.docx.prose.md"
+```
+
+Word tracked-change authors (included in review metadata) are separate from Git
+authors. Neither proves an edit came from an AI. Companion metadata can contain
+comment authors and deleted text: review it before sharing, just as you would the
+DOCX. No automatic OOXML merging or sentence-lineage system is provided.
+
+## Coverage and maintenance
+
+See [coverage, normalization, and backlog](docs/limitations.md). The prose retains
+common headings, list indentation, tables, notes, headers, and footers. Tracked
+insertions/move destinations are included and deletions/move sources omitted.
+Complex tracked structure/layout is limited and reported. Images, equations,
+text boxes, and embedded objects are not rendered. Formatting-only edits can
+leave both companions unchanged and still matter in Word.
+
+Run the generated-fixture suite:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+The implementation has four small modules: `prose.py` (segmentation), `extract.py`
+(OOXML coverage), `files.py` (scope and writes), and `cli.py` (commands). Tests
+include temporary Git repositories and failure cases. Generated fixtures do not
+establish complete Microsoft Word compatibility. No real/private document corpus
+was available for this implementation.
+
+## Releases
+
+Every push to `main` runs `.github/workflows/publish.yml`. Release runs are queued
+and each checks out the current `main`, including previous release version bumps.
+The workflow increments the patch version in `pyproject.toml` and
+`src/pilcrow/__init__.py`, builds and validates the distributions, runs the test
+suite, and verifies the installed CLI version. It then commits the version bump, pushes
+the commit and tag atomically, and creates a GitHub release with the wheel and
+source archive. Release commits use `chore(release): ... [skip ci]` to avoid loops.
+If `main` advances during a build, the push fails safely before publishing; the
+queued run checks out the newer `main`.
+
+A separate job uploads those same release files to PyPI using Trusted Publishing.
+Configure the PyPI publisher for owner `omertekin2002`, repository `Pilcrow`,
+workflow `publish.yml`, and GitHub environment `pypi`. No PyPI API token is needed.
+If only the PyPI upload fails, fix its configuration and use **Re-run failed jobs**
+on that workflow run to retry the existing release without bumping the version.

pilcrow_docx-0.1.1/README.md

@@ -0,0 +1,210 @@
+# Pilcrow
+
+Pilcrow makes Word text changes reviewable in GitHub Desktop. Keep editing the
+`.docx`; export readable companion files and commit both through your normal Git
+workflow. **The DOCX is authoritative.** The prose is a generated review artifact,
+not an editable replacement or a round-trip format.
+
+This is an independent, small Python implementation, conceptually inspired by the
+companion-file approach of stet. No source or tests were copied from that project.
+
+## Install locally
+
+Requires Python 3.10 or later. Git is needed for repository discovery and the Git
+workflow. Word is not required to export. From this project's directory:
+
+```sh
+python -m pip install .
+pilcrow --help
+```
+
+Use `python3` instead of `python` on systems where needed. A virtual environment
+is recommended (`python -m venv .venv`); activate it before installing:
+
+- macOS/Linux: `source .venv/bin/activate`
+- Windows PowerShell: `.venv\Scripts\Activate.ps1`
+- Windows Command Prompt: `.venv\Scripts\activate.bat`
+
+If activation is unavailable, invoke `.venv/bin/python` or
+`.venv\Scripts\python.exe` directly with `-m pip install .`, then `-m pilcrow`.
+For development, use `python -m pip install -e .`.
+
+Pilcrow uses Python's ZIP reader and `defusedxml` for XML parsing. There is no Word
+process, cloud service, AI connection, watcher, or background service. Extraction
+never writes to the DOCX.
+
+## Baseline, then review a change
+
+In **your document repository**, choose an explicit scope. For example:
+
+```sh
+pilcrow export --all --root .
+pilcrow check --all --root .
+```
+
+Or select documents (paths are relative to your current directory):
+
+```sh
+pilcrow export "report.docx" "chapters/Methods and results.docx" --root .
+```
+
+Outputs retain the complete source-relative filename:
+
+```text
+report.docx
+chapters/Methods and results.docx
+.pilcrow/report.docx.prose.md
+.pilcrow/report.docx.meta.json
+.pilcrow/chapters/Methods and results.docx.prose.md
+.pilcrow/chapters/Methods and results.docx.meta.json
+```
+
+1. Export a baseline. In GitHub Desktop, review and commit the DOCX and its two
+   companion files together. Do not put `.pilcrow/` in `.gitignore`.
+2. Edit and save the DOCX in Word, or use a separate document-editing tool.
+3. Run the same `pilcrow export` command again.
+4. In Desktop's **Changes** view, select the `.prose.md` file to read the text diff;
+   inspect `.meta.json` for review/coverage changes. The DOCX may still say binary
+   changed. Review formatting/images in Word when relevant.
+5. Commit the DOCX and both companions together through Desktop, then push and
+   branch normally. Desktop's **History** view can show committed companion diffs.
+
+Pilcrow never stages, commits, pushes, switches branches, or merges. No direct
+DOCX text converter is installed. The CLI and an ordinary Git diff have been
+tested; **the Microsoft Word / GitHub Desktop GUI workflow has not been tested in
+this Linux environment**. See [manual validation](docs/manual-validation.md).
+See an [actual generated prose and Git diff example](docs/example.md).
+Old commits without companions will not gain prose diffs automatically; there is
+no backfill or history rewriting.
+
+## Scope and discovery
+
+- `--root` defaults to the **current directory**, never an automatically detected
+  repository top. It controls both discovery and the location of `.pilcrow/`.
+  Use the same root each time. From a subdirectory, pass `--root ..` deliberately
+  if the output belongs at the parent. Explicit paths remain relative to the
+  current directory, not to `--root`.
+- Supply paths **or** `--all`. No arguments does not silently scan the machine.
+  Passing a directory as a document is an error; use `--all --root directory`.
+- Inside Git, `--all` uses `git ls-files` for tracked and nonignored untracked
+  files within the selected root. Tracked files remain included even if an ignore
+  rule matches. An explicitly selected ignored DOCX is allowed.
+- Outside Git, `--all` recursively walks the selected directory. Git ignore rules
+  only apply inside a Git worktree; there is no separate ignore syntax.
+- Both modes exclude Word lock files (`~$…`), `.pilcrow`, `.git`, `.venv`, `venv`,
+  `env`, `node_modules`, `__pycache__`, `.tox`, `.nox`, `build`, and `dist`.
+  Extension matching is case-insensitive. Unicode and spaces are supported.
+- Symlink files/paths are rejected; directory walking does not follow symlink
+  directories. Submodule documents are not recursively discovered from the parent
+  repository: select a root inside the submodule.
+- `--all` reports orphan companions after source deletion/rename. Remove the old
+  companion files manually if the deletion was intentional and commit those
+  deletions together. Export never automatically deletes review history files.
+  Explicit-file mode checks only selected inputs, not unrelated orphans.
+
+## Check before committing
+
+```sh
+pilcrow check --all --root .
+```
+
+`check` is read-only, even when files are missing. It recomputes expected prose and
+metadata and compares bytes, tolerating ZIP order/compression, run boundaries,
+save timestamps, and other ignored Word metadata. It does not use a DOCX-byte hash.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Successful export, or companions match the supported normalized view |
+| 1 | Missing/stale companions in `check`, or orphan companions in either command |
+| 2 | Invalid selection, unreadable/malformed input, unsafe path, or write failure |
+
+Errors identify the file; remaining selected documents are processed after a
+per-document error. Retry after Word has finished saving if a file is temporarily
+unreadable or changes during extraction. A fresh result means **no supported
+prose/review changes detected**, never that the complete document is identical.
+Warnings appear on stderr and in metadata even for fresh results. Known coverage
+limitations do not themselves cause a nonzero exit.
+
+Writes use a temporary file and atomic replacement in the destination directory.
+Byte-identical outputs keep their existing modification times. Each file is
+atomic, **not the whole pair or batch**: if interrupted between files, run `check`
+and export again. Avoid concurrent exports into the same root.
+
+## Branches and conflicts
+
+Opt in to conservative merge rules once, from your document repository root:
+
+```sh
+pilcrow setup --root .
+```
+
+This appends a managed block to `.gitattributes`, preserving other rules. Repeating
+it is harmless. Review and commit the file through Desktop. Rules mark DOCX and
+all `.pilcrow/` files `-merge` (Git's binary merge driver), and companion files as
+`text eol=lf`. Both-sided modifications conflict instead of automatically merging
+prose into a document that never existed. Normal one-sided changes still merge.
+More-specific nested attributes can override these rules; inspect with
+`git check-attr merge -- "report.docx" ".pilcrow/report.docx.prose.md"` if needed.
+
+When branches conflict:
+
+1. Preserve copies of both versions of the DOCX outside the conflicted path.
+2. Choose the authoritative version or reconcile the documents manually in Word.
+   If using Git commands to select a side, make sure you understand that side in
+   the current merge/rebase. Pilcrow does not make this choice.
+3. Put the resolved DOCX at its repository path. Regenerate its companions, even
+   if Git did not flag them as conflicted. Never independently accept a merged
+   prose artifact as the Word document.
+4. Run `pilcrow check --all --root .`. Inspect the resulting text and Word file,
+   then mark resolutions and commit using your normal Git workflow.
+
+Git commit identity attributes a snapshot, not every contributor between saves.
+For basic snapshot attribution:
+
+```sh
+git blame -- ".pilcrow/report.docx.prose.md"
+```
+
+Word tracked-change authors (included in review metadata) are separate from Git
+authors. Neither proves an edit came from an AI. Companion metadata can contain
+comment authors and deleted text: review it before sharing, just as you would the
+DOCX. No automatic OOXML merging or sentence-lineage system is provided.
+
+## Coverage and maintenance
+
+See [coverage, normalization, and backlog](docs/limitations.md). The prose retains
+common headings, list indentation, tables, notes, headers, and footers. Tracked
+insertions/move destinations are included and deletions/move sources omitted.
+Complex tracked structure/layout is limited and reported. Images, equations,
+text boxes, and embedded objects are not rendered. Formatting-only edits can
+leave both companions unchanged and still matter in Word.
+
+Run the generated-fixture suite:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+The implementation has four small modules: `prose.py` (segmentation), `extract.py`
+(OOXML coverage), `files.py` (scope and writes), and `cli.py` (commands). Tests
+include temporary Git repositories and failure cases. Generated fixtures do not
+establish complete Microsoft Word compatibility. No real/private document corpus
+was available for this implementation.
+
+## Releases
+
+Every push to `main` runs `.github/workflows/publish.yml`. Release runs are queued
+and each checks out the current `main`, including previous release version bumps.
+The workflow increments the patch version in `pyproject.toml` and
+`src/pilcrow/__init__.py`, builds and validates the distributions, runs the test
+suite, and verifies the installed CLI version. It then commits the version bump, pushes
+the commit and tag atomically, and creates a GitHub release with the wheel and
+source archive. Release commits use `chore(release): ... [skip ci]` to avoid loops.
+If `main` advances during a build, the push fails safely before publishing; the
+queued run checks out the newer `main`.
+
+A separate job uploads those same release files to PyPI using Trusted Publishing.
+Configure the PyPI publisher for owner `omertekin2002`, repository `Pilcrow`,
+workflow `publish.yml`, and GitHub environment `pypi`. No PyPI API token is needed.
+If only the PyPI upload fails, fix its configuration and use **Re-run failed jobs**
+on that workflow run to retry the existing release without bumping the version.

pilcrow_docx-0.1.1/docs/example.md

@@ -0,0 +1,48 @@
+# Example review artifact
+
+Generated from a small test fixture in a temporary Git repository. This shows
+text-diff readability, not validation in Word or Desktop.
+
+```text
+# Study results
+
+Dr. Kaya measured 3.14 units.
+The treatment did not improve the outcome.
+The control was unchanged.
+
+- Review the result.
+
+[Table]
+
+[Row]
+
+[Cell]
+
+Treatment
+
+[Cell]
+
+12 participants
+
+[/Row]
+
+[/Table]
+```
+
+After changing one sentence, ordinary `git diff` produced:
+
+```diff
+diff --git a/.pilcrow/research.docx.prose.md b/.pilcrow/research.docx.prose.md
+index 7f199a2..c8bf275 100644
+--- a/.pilcrow/research.docx.prose.md
++++ b/.pilcrow/research.docx.prose.md
+@@ -1,7 +1,7 @@
+ # Study results
+
+ Dr. Kaya measured 3.14 units.
+-The treatment improved the outcome.
++The treatment did not improve the outcome.
+ The control was unchanged.
+
+ - Review the result.
+```

pilcrow_docx-0.1.1/docs/limitations.md

@@ -0,0 +1,109 @@
+# Coverage and design choices
+
+Version 0.1 is a partial prose view. This is neither a visual comparison nor a
+lossless Word-to-Markdown converter. There is no import path from prose to DOCX.
+Only conventional Transitional OOXML packages with `word/document.xml` are
+accepted. Strict OOXML, encrypted Office files, legacy `.doc`, and both single-file
+Word XML dialects are unsupported. They must not be relabeled `.docx`.
+
+## Supported view
+
+| Content | v1 behavior |
+| --- | --- |
+| Paragraphs | Runs joined without artificial spaces; blank line between nonempty paragraphs |
+| Headings | Outline level, inherited paragraph styles, and conventional Heading1–9 style IDs; capped at six Markdown levels |
+| Lists | Item and indentation boundaries from direct/inherited `numPr`; generic `-` marker; automatic numbers/bullet glyphs are not reconstructed and trigger a warning |
+| Tables | Explicit table, row, and cell markers, including empty cells; nested tables and content-control wrappers; grid spans/vertical merge markers retained, no rendered grid/layout |
+| Footnotes/endnotes | Related parts with reference markers; separator notes omitted; IDs retained, so renumbering can produce diffs |
+| Headers/footers | Related parts shown as separate sections by part name; no page/section placement mapping |
+| Tracked text | Include `ins` and `moveTo`, omit `del` and `moveFrom`; separate kind, author, and text records, without dates or revision IDs |
+| Comments | Text and author in metadata; anchors, dates, threaded replies, rich formatting, and resolved state not compared |
+| Hyperlinks | Accepted visible text in prose; label and destination in metadata, without fetching the URL |
+| Fields/citations | Saved display text in prose; normalized instruction fingerprint and first command token in metadata; never recalculate fields or manage Zotero |
+| Text boxes, drawings, images, embedded objects, equations | Omission warnings and placeholders for common inline constructs; no rendering, OCR, object execution, or asset-content comparison |
+| Bold/italic, fonts, colors, other styles, pagination/layout | Not compared; always disclosed in coverage warning |
+
+Tracked text inclusion is an **accept-insertions/omit-deletions view**, not Word's
+complete Accept All Changes implementation. Paragraph-mark deletion, list/table
+revisions, tracked formatting, moves expressed in unusual structures, and nesting
+can differ from Word's result. These constructs are reported where detected;
+review them in Word. Deleted table rows are omitted. Comment text is plain text;
+hyperlinks/fields inside comments are not separately interpreted.
+
+Hidden text is included and triggers a visibility warning; formatting is not used
+to decide what Word would display. Unknown Word/XML constructs trigger conservative warnings. Extra package parts
+are listed as unrendered; their bytes are not hashed. Some save-only parts
+(`docProps`, settings, font tables, theme, numbering definitions) are deliberately
+ignored. List values and layout can therefore change without a companion update.
+Unsupported assets can change while warning text remains identical. The `partial-prose`
+coverage marker and CLI wording apply even when there are no specific warnings.
+No claim of a complete/unchanged document is made. This is a modest coverage report,
+not an audit of every OOXML relationship or layout semantic.
+
+Metadata contains only schema/view/coverage, warnings, review text/authors, link
+destinations, and field fingerprints. Field fingerprints avoid huge Zotero JSON
+payloads but only say a normalized code changed, not what that change means.
+Arrays follow document traversal order; related parts and warnings sort
+lexically. Internal part paths come from the package; no machine paths, save
+counters, revision dates, or export timestamps are added. Hyperlink destinations
+are retained literally and may themselves contain sensitive or local paths.
+
+## Normalization and sentence lines
+
+- UTF-8, LF endings, terminal newline. Unicode, punctuation, numbers, and negations
+  are retained. No stemming, case folding, Unicode composition, or spellchecking.
+- Word run boundaries and run formatting do not introduce text boundaries.
+- After joining runs, whitespace (including tabs and nonbreaking spaces) collapses
+  to ordinary single spaces; leading/trailing paragraph whitespace is removed.
+  Explicit Word line breaks create separate lines. XML source newlines are spaces.
+  Empty paragraphs are omitted. Thus spacing and blank-paragraph layout changes
+  are intentionally not reviewed. Nonbreaking and soft hyphen characters remain.
+- Sentence breaks occur at `.`, `!`, or `?` followed by whitespace; closing quotes
+  or brackets stay with the sentence. A small English abbreviation list and
+  single-letter/initialism heuristic suppress common false splits. Decimals such
+  as `3.14` have no whitespace and stay intact. Question/exclamation sentences and
+  ordinary Unicode text are retained.
+- This is English-oriented, not universal sentence detection. Unknown abbreviations
+  can split too soon; an abbreviation at sentence end can suppress a valid split.
+  CJK text without whitespace stays on one line. Citation punctuation, initials,
+  ellipses, and unusual scientific notation may need later tuning. An incorrect
+  split changes line boundaries, not the underlying words.
+- Heading text stays on one line. Each list item starts with `-`; subsequent
+  sentences are indented. Table cells contain normal sentence/paragraph text.
+  There are no per-sentence positional IDs or automatic counters.
+- The `.md` is optimized for the ordinary text diff, not faithful Markdown rendering:
+  literal Markdown metacharacters in Word are not escaped, and table/unsupported
+  markers can coincide with literal document text.
+
+## Operational limits
+
+Packages are limited to 4096 entries, 64 MiB total uncompressed, and 16 MiB per
+part to bound memory. Large image-heavy documents may exceed these deliberately
+conservative defaults. Duplicate ZIP entries and XML entity expansion are rejected.
+Output/source symlink paths are rejected to avoid writing through unexpected
+paths. Export checks source stat information before/after reading; it is not a
+cross-process lock. Save completely before export, and rerun after a concurrent
+save. No watcher retries or transactional multi-document snapshot is provided.
+
+The output mapping preserves directory paths and the `.docx` extension. It does
+not solve case-colliding filenames on case-insensitive filesystems; repositories
+shared with Windows/macOS should avoid filenames differing only by case.
+Git discovery requires an available working Git installation. A selected file
+that disappears is an error; discovery treats deleted tracked files as absent and
+reports any existing companions as orphans. Empty discovery can succeed with
+“No DOCX documents selected”; verify the scope when that is unexpected.
+
+## Revisit with real documents
+
+1. Validate real Word saves on Windows/macOS and Desktop's companion diffs, including
+   save-without-editing and Zotero documents, before claiming GUI compatibility.
+2. Tune sentence segmentation against collaborators' languages and abbreviation
+   conventions; keep fixtures for every regression.
+3. Decide whether list values, comment anchors, field-code previews, or image hashes
+   justify more metadata. Avoid a dump of all OOXML.
+4. Improve tracked structural revisions, note-reference validation, complex tables,
+   and relationship/path canonicalization only as actual documents require it.
+5. Consider opt-in textconv and refresh-only watching after the primary workflow is
+   reliable. Desktop executable discovery needs its own validation.
+6. If Word XML is wanted later, build a distinct dialect-detecting adapter. Do not
+   treat arbitrary XML as Word input. Automatic document merging stays separate.

pilcrow_docx-0.1.1/docs/manual-validation.md

@@ -0,0 +1,40 @@
+# Validate with Word and GitHub Desktop
+
+Automated tests use generated ZIP/XML fixtures and a temporary Git repository.
+They validate extraction and ordinary Git diffs, not Microsoft Word rendering or
+GitHub Desktop itself. Neither Word nor Desktop was available for this validation;
+no real document corpus was provided. Run this checklist on a copy of a document
+you are allowed to share. Do not use the only copy of important work.
+
+1. Put the copy in a disposable Git repository opened in Desktop. Install Pilcrow
+   in your Python environment, then export with `pilcrow export --all --root .`.
+   Read stderr and `.meta.json` warnings. Confirm headings, paragraphs, list items,
+   and table cells are understandable in `.prose.md`.
+2. Commit the DOCX and companions in Desktop. Export again: the companions should
+   remain unchanged. Run `pilcrow check --all --root .`: expect exit 0.
+3. Open/save/close the file in Word **without editing**. Export again. The DOCX may
+   change as a package, but ordinary prose and review metadata should stay stable.
+   Investigate any companion churn; keep a sanitized reproducible case if possible.
+4. Change one sentence in a multi-sentence paragraph, save, and run `check`: expect
+   exit 1. Export, select the companion in Desktop Changes, and verify that only
+   the affected sentence changes. Confirm the original DOCX still opens normally.
+5. Add a heading, a list item, a two-cell table row, a note, and a hyperlink. Export
+   and review boundaries. Change only the hyperlink URL: inspect the metadata diff.
+6. Insert/delete text with Track Changes on, add a comment, then export. Prose
+   should include inserted text and omit deleted text. Review text/authors should
+   appear in metadata. Inspect complex tracked structures in Word directly.
+7. Make a bold-only change and change an image. Export. No prose update is required;
+   coverage warnings should still make the limitation clear. Inspect in Word.
+8. If using Zotero/fields, update citations/bibliography in Word before saving.
+   Confirm saved display text appears in prose and code changes can affect the
+   field fingerprints. Pilcrow does not refresh or verify the bibliography.
+9. Commit the edited DOCX and companions together. Select the companion in Desktop
+   History and inspect the committed difference. Confirm branch/index/history
+   remain under your control.
+10. In the disposable repository only, try two branches with changes to the same
+    document after committing `pilcrow setup` rules. Merge through your usual
+    workflow. Choose/reconcile the DOCX, regenerate companions, check, and complete
+    the merge. Never resolve Word content by editing only the companion.
+
+Record OS, Word version, Desktop version, Python version, and sanitized symptoms
+for failures. These manual results are needed before extending compatibility claims.

pilcrow_docx-0.1.1/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pilcrow-docx"
+version = "0.1.1"
+description = "Readable DOCX companion diffs for ordinary Git workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["defusedxml>=0.7.1,<1"]
+
+[project.scripts]
+pilcrow = "pilcrow.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]