docs: full SKILL/docs audit — changeset tier, dry_run, occurrence, exception sections (ISSUES.md #55) (#69)

Docs-only sync of README, docs/{api,index,quickstart}, and skills/docx/SKILL to the current API surface (changeset tier, dry_run, occurrence, count_matches, session status, new exception sections). Every claim verified against source; multi-reviewer + red-team pass fixed a stale-ref changeset example, an OOXML→XML accuracy nit, and batch_edit result-naming consistency.

Author: pablospe

README.md

@@ -23,8 +23,8 @@ Pure Python library for Word document track changes and comments, without requir
 - **Cross-Boundary Editing**: Find and replace text spanning multiple XML elements and revision boundaries
 - **Mixed-State Editing**: Atomic decomposition for text spanning `<w:ins>`/`<w:del>` boundaries
 - **Comments**: Add, reply, resolve, and delete comments
-- **Revision Management**: List, accept, and reject tracked changes
-- **Session Mode**: Optional persistent kernel (`docx-session start/exec/eval/stop`) keeps documents open across many small commands — ideal for AI agents (`pip install "docx-editor[session]"`)
+- **Revision Management**: List, accept, and reject tracked changes at three granularities — individual revisions, groups (one logical edit), and changesets (one whole `batch_edit`/`batch_rewrite` call); `EditResult` and `Revision` objects carry `group_id` and `changeset_id`
+- **Session Mode**: Optional persistent kernel (`docx-session start/exec/eval/status/stop`) keeps documents open across many small commands — ideal for AI agents (`pip install "docx-editor[session]"`)
 - **Cross-Platform**: Works on Linux, macOS, and Windows
 - **No Dependencies**: Only requires `defusedxml` for secure XML parsing
 
@@ -89,6 +89,9 @@ with Document.open("contract.docx", author=author) as doc:
     doc.replace("net", "gross", paragraph=r)  # chain without list_paragraphs()
     doc.delete("obsolete text", paragraph="P5#d4e5")
     doc.insert_after("Section 5", " (as amended)", paragraph="P3#b2c4")
+    # Repeated text? Pass occurrence= (0-based) to pick which match; omitting it
+    # requires a unique match, else AmbiguousTextError.
+    doc.replace("the", "The", paragraph="P4#c5d6", occurrence=2)
 
     # Rewrite entire paragraph (automatic word-level diff)
     doc.rewrite_paragraph("P2#f3c1",
@@ -152,6 +155,10 @@ with Document.open("contract.docx", author="Editor") as doc:
     doc.save()
 ```
 
+Pass `dry_run=True` to validate every operation up front without touching the
+document — `doc.batch_edit(ops, dry_run=True)` returns a list of
+`EditValidationResult` instead of applying the edits.
+
 ### Saving into synced folders
 
 `docx-editor` is safe to use inside cloud-synced folders (OneDrive, Dropbox,

docs/api.md

@@ -134,7 +134,7 @@ Return one paragraph as a structured `ParagraphInfo` record — the single-item
 
 **Returns:** `ParagraphInfo` (index, hash-anchored ref, full untruncated text) for the paragraph at `index`.
 
-**Raises:** [`ParagraphIndexError`](#exceptions) if `index` is out of range (`< 1` or greater than `paragraph_count()`).
+**Raises:** [`ParagraphIndexError`](#paragraphindexerror) if `index` is out of range (`< 1` or greater than `paragraph_count()`).
 
 **Example:**
 
@@ -154,7 +154,7 @@ Return the paragraphs surrounding `ref`, in document order — the "show me the
 
 **Returns:** List of `ParagraphInfo` records (index, ref, full text) — identical to what `list_paragraphs_structured()` would emit for the same span.
 
-**Raises:** `ValueError` if `ref` is malformed or `window < 0`; [`ParagraphIndexError`](#exceptions) / [`HashMismatchError`](#exceptions) for an out-of-range or stale `ref`.
+**Raises:** `ValueError` if `ref` is malformed or `window < 0`; [`ParagraphIndexError`](#paragraphindexerror) / [`HashMismatchError`](#hashmismatcherror) for an out-of-range or stale `ref`.
 
 **Example:**
 
@@ -246,7 +246,7 @@ Find text in the document, including text spanning XML element boundaries.
 
 **Returns:** [`SearchResult`](#searchresult), or None if not found
 
-**Raises:** `ValueError` if `text` is empty or `paragraph` is malformed; [`ParagraphIndexError`](#exceptions) / [`HashMismatchError`](#exceptions) for an out-of-range or stale `paragraph`.
+**Raises:** `ValueError` if `text` is empty or `paragraph` is malformed; [`ParagraphIndexError`](#paragraphindexerror) / [`HashMismatchError`](#hashmismatcherror) for an out-of-range or stale `paragraph`.
 
 **Example:**
 
@@ -275,7 +275,7 @@ what a follow-up edit needs.
 
 **Returns:** list of [`SearchResult`](#searchresult), empty when nothing matches (no-match is not an error for an enumeration API)
 
-**Raises:** `ValueError` if `text` is empty or `paragraph` is malformed; [`ParagraphIndexError`](#exceptions) / [`HashMismatchError`](#exceptions) for an out-of-range or stale `paragraph`.
+**Raises:** `ValueError` if `text` is empty or `paragraph` is malformed; [`ParagraphIndexError`](#paragraphindexerror) / [`HashMismatchError`](#hashmismatcherror) for an out-of-range or stale `paragraph`.
 
 **Example:**
 
@@ -585,7 +585,7 @@ List all tracked changes in the document.
 
 **Returns:** List of Revision objects
 
-**Raises:** The `paragraph` ref is validated exactly like in the edit methods — `ValueError` (malformed ref), [`ParagraphIndexError`](#exceptions) (index out of range), [`HashMismatchError`](#exceptions) (stale hash).
+**Raises:** The `paragraph` ref is validated exactly like in the edit methods — `ValueError` (malformed ref), [`ParagraphIndexError`](#paragraphindexerror) (index out of range), [`HashMismatchError`](#hashmismatcherror) (stale hash).
 
 **Example:**
 
@@ -916,6 +916,10 @@ from docx_editor import Revision
 | `author` | str | The revision author |
 | `date` | datetime or None | When the revision was made |
 | `text` | str | The inserted or deleted text |
+| `paragraph_ref` | str or None | Hash-anchored reference (`"P{i}#{hash}"`) of the containing paragraph; None when the revision sits outside any `<w:p>` (e.g. a `<w:trPr>` row marker) |
+| `occurrence` | int or None | 0-based occurrence index of `text` within the containing paragraph, counted in the view where the revision's text lives (the visible view for insertions, the original pre-revision view for deletions). For insertions it plugs directly into the `occurrence=` parameter of the anchor APIs; None whenever targeting-by-text does not apply (empty text, a host insertion partly consumed by a nested deletion, or a nested deletion) |
+| `nested_under` | int or None | id of the nearest enclosing revision (e.g. a foreign deletion inside another author's pending insertion), else None |
+| `contains_ids` | tuple[int, ...] | ids of the revisions nested inside this one, in document order (empty tuple when none) |
 | `group_id` | int or None | Revision group this revision belongs to (see [`accept_group()`](#accept_groupgroup_id)): recorded for this session's edits, inferred by reconstruction for revisions already in the file; None only for ungroupable revisions (missing author/date, outside any paragraph, duplicated id, or a mid-session split half of a foreign insertion) |
 | `group_source` | str or None | Provenance of `group_id`: `"recorded"` (created through this open Document) or `"inferred"` (reconstructed at parse time from same-paragraph contiguity + identical author and date); None iff `group_id` is None |
 | `changeset_id` | int or None | Changeset (one whole call) this revision's group belongs to (see [`accept_changeset()`](#accept_changesetchangeset_id) / [`reject_changeset()`](#reject_changesetchangeset_id)) — the `(author, date)` class over groups; None iff `group_id` is None |
@@ -1161,6 +1165,41 @@ except AmbiguousTextError as e:
                 occurrence=r.paragraph_occurrence)
 ```
 
+### `HashMismatchError`
+
+Raised when a `paragraph` ref's hash no longer matches the paragraph's current
+content — the paragraph changed (usually by an earlier edit) since the ref was
+listed, so the ref is stale. Structured fields: `paragraph_index` (1-based),
+`expected_hash` (the hash in the stale ref), `actual_hash` (the paragraph's
+current hash), and `paragraph_preview` (the current text). Recover by retrying
+with the fresh ref `P{paragraph_index}#{actual_hash}`, or re-list paragraphs.
+
+```python
+from docx_editor.exceptions import HashMismatchError
+
+try:
+    doc.replace("old", "new", paragraph="P2#f3c1")
+except HashMismatchError as e:
+    doc.replace("old", "new", paragraph=f"P{e.paragraph_index}#{e.actual_hash}")
+```
+
+### `ParagraphIndexError`
+
+Raised when a paragraph index is out of range — `< 1` or greater than
+`paragraph_count()` (for example `get_paragraph(0)`). Structured fields:
+`index` (the offending index) and `total_paragraphs` (how many the document
+has). Clamp to `1..total_paragraphs` and retry, or call `list_paragraphs()`
+to pick a valid ref.
+
+```python
+from docx_editor.exceptions import ParagraphIndexError
+
+try:
+    para = doc.get_paragraph(index)
+except ParagraphIndexError as e:
+    para = doc.get_paragraph(max(1, min(e.index, e.total_paragraphs)))
+```
+
 ### `BatchOperationError`
 
 The only exception `batch_edit()` / `batch_rewrite()` raise for a failing
@@ -1214,6 +1253,18 @@ Raised by `Document.open()` when the source file does not exist. Structured fiel
 from docx_editor.exceptions import DocumentNotFoundError
 ```
 
+### `InvalidDocumentError`
+
+Raised by `Document.open()` when the source path is not a valid `.docx` — wrong
+suffix, a directory, an empty/truncated file, not a ZIP, missing
+`word/document.xml`, or malformed XML. Structured field: `path` (the source
+path). Not an in-loop retry: the message names which check failed; fix or
+re-export the input file.
+
+```python
+from docx_editor.exceptions import InvalidDocumentError
+```
+
 ### `DocumentClosedError`
 
 Raised when any operation is attempted on a `Document` after `close()`. Closing discards the workspace (unless `cleanup=False`), so the object cannot keep serving reads or edits — reopen the source to continue. Structured field: `path` (the source path of the closed document).

docs/index.md

@@ -11,7 +11,7 @@ Pure Python library for Word document track changes and comments, without requir
 - **Paragraph Rewrite**: rewrite a paragraph and generate tracked changes from the diff
 - **Track Changes**: Replace, delete, and insert text with revision tracking
 - **Comments**: Add, reply, resolve, and delete comments
-- **Revision Management**: List, accept, and reject tracked changes
+- **Revision Management**: Accept/reject tracked changes at three granularities — individual revisions, groups (one logical edit), and changesets (one whole `batch_edit`/`batch_rewrite` call)
 - **Cross-Boundary Editing**: Find and replace text spanning multiple XML elements
 - **Cross-Platform**: Works on Linux, macOS, and Windows
 - **No Dependencies**: Only requires `defusedxml` for secure XML parsing
@@ -38,6 +38,8 @@ with Document.open("contract.docx", author="Legal Team") as doc:
     # P2#f3c1| Payment is due within 30 days...
 
     # Edit methods require a paragraph ref and return the updated ref.
+    # Pass occurrence= (0-based) to disambiguate repeated text; omitting it
+    # requires a unique match, else AmbiguousTextError.
     ref = doc.replace("30 days", "60 days", paragraph="P2#f3c1")
     ref = doc.insert_after("Payment", " terms", paragraph=ref)
     doc.delete("obsolete text", paragraph="P5#d4e5")

docs/quickstart.md

@@ -72,6 +72,8 @@ with Document.open("contract.docx") as doc:
 
 Use the `P{index}#{hash}` part as the `paragraph=` argument. Edit methods return a new paragraph ref after the hash changes, so keep the returned value when chaining edits in the same paragraph.
 
+When the search text appears more than once in the target paragraph, pass `occurrence=` (0-based, so `occurrence=1` is the second match) to `replace()`, `delete()`, `insert_after()`, `insert_before()`, and `add_comment()`. Omitting it requires a unique match — otherwise the call raises `AmbiguousTextError`.
+
 ## Track Changes
 
 ### Replace Text
@@ -83,7 +85,7 @@ with Document.open("contract.docx") as doc:
     doc.save()
 ```
 
-This creates a tracked deletion of `30 days` and a tracked insertion of `60 days`.
+This creates a tracked deletion of `30` and a tracked insertion of `60`. `replace()` trims the common prefix and suffix and tracks only the differing words, so the unchanged surrounding word (` days`) is left intact rather than deleted and re-inserted.
 
 ### Delete Text
 
@@ -130,6 +132,18 @@ with Document.open("contract.docx") as doc:
     doc.save()
 ```
 
+To validate a batch before applying it, pass `dry_run=True`. This checks every operation up front and returns a list of `EditValidationResult` objects (each with `valid` and `error`) without modifying the document:
+
+```python
+with Document.open("contract.docx") as doc:
+    results = doc.batch_edit([
+        EditOperation.replace("30 days", "60 days", paragraph="P2#f3c1"),
+        EditOperation.delete("obsolete clause", paragraph="P5#d4e5"),
+    ], dry_run=True)
+    for r in results:
+        print(r.index, r.valid, r.error)
+```
+
 ## Comments
 
 ### Add a Comment
@@ -199,6 +213,28 @@ doc.accept_revision(revision_id=1)
 doc.reject_revision(revision_id=1)
 ```
 
+### Accept or Reject a Group or Changeset
+
+Revisions form three nested tiers: an individual **revision**, the **group** of revisions from one logical edit (e.g. a single `replace()` or `rewrite_paragraph()`), and the **changeset** of all groups from one whole call (`batch_edit()` / `batch_rewrite()`). Accept or reject a whole tier in one call:
+
+```python
+from docx_editor import EditOperation
+
+# Every edit method returns an EditResult carrying group_id and changeset_id.
+result = doc.rewrite_paragraph("P3#b2c4", "Section 5 has been revised in full.")
+doc.accept_group(result.group_id)           # resolve one logical edit as a unit
+
+# One batch_edit is one changeset that may span several groups (edit paragraphs
+# the rewrite above didn't touch, so their refs are still fresh):
+new_refs = doc.batch_edit([
+    EditOperation.replace("30 days", "60 days", paragraph="P2#f3c1"),
+    EditOperation.delete("obsolete clause", paragraph="P5#d4e5"),
+])
+doc.reject_changeset(new_refs[0].changeset_id)  # undo the whole batch in one call
+```
+
+Every `Revision` also carries `group_id`/`group_source` and `changeset_id`/`changeset_source` — the source is `"recorded"` for edits made in this session and `"inferred"` for revisions reconstructed when an existing document is reopened. Group and changeset ids are renumbered each time the document is opened, so always resolve them with an id from the current session's `EditResult` or `list_revisions()`.
+
 ### Accept or Reject All
 
 ```python