echr-py 0.2.2__tar.gz → 0.2.5__tar.gz

{echr_py-0.2.2 → echr_py-0.2.5}/CITATION.cff

@@ -5,8 +5,8 @@ type: software
 authors:
   - family-names: Ridi
     given-names: Niccolo
-version: 0.2.2
-date-released: 2026-08-21
+version: 0.2.5
+date-released: 2026-10-08
 license: MIT
 repository-code: "https://github.com/niccoloridi/echr-py"
 url: "https://github.com/niccoloridi/echr-py"

{echr_py-0.2.2/echr_py.egg-info → echr_py-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echr-py
-Version: 0.2.2
+Version: 0.2.5
 Summary: Pythonic acquisition of HUDOC and HUDOC-EXEC metadata and source documents for ECtHR research.
 Author-email: Niccolo Ridi <niccoloridi@gmail.com>
 License-Expression: MIT
@@ -102,7 +102,7 @@ Dynamic: license-file
   <a href="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml"><img src="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/python-3.11%E2%80%933.14-3776AB.svg" alt="Python 3.11–3.14">
   <a href="https://github.com/niccoloridi/echr-py/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT license"></a>
-  <img src="https://img.shields.io/badge/version-0.2.2-blue.svg" alt="Version 0.2.2">
+  <img src="https://img.shields.io/badge/version-0.2.5-blue.svg" alt="Version 0.2.5">
 </p>
 
 `echr-py` is a research engineering toolkit for the case law of the European
@@ -112,10 +112,6 @@ Court of Human Rights. It connects public
 research artifacts through Python, a command-line interface, and the Model
 Context Protocol (MCP).
 
-The distribution and primary command are now named `echr-py`. The established
-`hudoc_py` Python import and the legacy `hudoc-py` command remain available for
-backward compatibility.
-
 It is designed for work where provenance matters. A result can retain the exact
 HUDOC document, language version, section, paragraph, individual opinion,
 footnote, citation span, cited procedural document, cited-paragraph pinpoint,
@@ -344,6 +340,17 @@ echr-py versions download \
 The acquisition manifest records each language-specific item ID, rendition
 type, requested-format outcome, HTTP status, path, byte length, and SHA-256.
 
+### DOCX structure, opt-in
+
+HUDOC's HTML is generated from the Registry's Word files and keeps only hashed
+formatting classes. The DOCX keeps the template's named styles (`Ju_H_Head`,
+`Ju_Para`, `Ju_Quot`, `Ju_Judges`, `Opi_H_Head`, `Opi_Para`), present from the
+first judgment of 1961 onward. `--docx-structure` (or `docx_structure=True`)
+reads them into an advisory `DocxStructure` with sections, numbered paragraphs,
+quotations, the bench, separate opinions and footnotes, and reports where it
+agrees with the HTML segmentation. HTML stays canonical for offsets, citation
+loci and benchmarks. See [docs/text-segmentation.md](https://github.com/niccoloridi/echr-py/blob/main/docs/text-segmentation.md#docx-structure-opt-in-advisory).
+
 ## Local lexical, dense, and hybrid retrieval
 
 Build a portable paragraph index from any acquired corpus:
@@ -495,7 +502,7 @@ without cloning the repository:
 
 ```bash
 claude mcp add --scope user --transport stdio echr-py -- \
-  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.2' echr-py mcp
+  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.5' echr-py mcp
 claude mcp get echr-py
 ```
 
@@ -555,7 +562,7 @@ study jobs are an explicit opt-in.
 
 | Command group | Purpose |
 | --- | --- |
-| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition |
+| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition; `--docx-structure` adds the advisory Registry-style structure |
 | `versions …`, `corpus …` | Language versions and reproducible corpora |
 | `local …`, `embeddings …` | Offline browsing and paragraph retrieval |
 | `gui` | Optional local Streamlit corpus browser |
@@ -563,7 +570,7 @@ study jobs are an explicit opt-in.
 | `graph metrics|export|html|gexf` | Network metrics and portable graph output |
 | `study validate|plan|run|status|resume|export` | Bounded optional dataset studies |
 | `exec …` | HUDOC-EXEC record discovery, download, and source conversion |
-| `mcp` | Read-only MCP server by default; bounded jobs are opt-in |
+| `mcp` | Read-only MCP server by default; bounded jobs are opt-in; `--call-log PATH` records every tool call (tool, arguments, returned item IDs and ECLIs, version, time) as a replayable JSONL log |
 
 ```bash
 echr-py --help
@@ -635,6 +642,21 @@ cd echr-py
 python -m pip install -e ".[all,dev]"
 ```
 
+### Names
+
+The distribution and primary command are `echr-py`. The Python import is
+`hudoc_py`, and the earlier `hudoc-py` command still works; both remain
+available so existing code and scripts keep running.
+
+```python
+import hudoc_py            # import name
+```
+
+```bash
+echr-py --version          # primary command
+hudoc-py --version         # legacy alias, same program
+```
+
 ## Documentation
 
 - [Worked examples](https://github.com/niccoloridi/echr-py/blob/main/docs/examples.md)

{echr_py-0.2.2 → echr_py-0.2.5}/README.md

@@ -14,7 +14,7 @@
   <a href="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml"><img src="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/python-3.11%E2%80%933.14-3776AB.svg" alt="Python 3.11–3.14">
   <a href="https://github.com/niccoloridi/echr-py/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT license"></a>
-  <img src="https://img.shields.io/badge/version-0.2.2-blue.svg" alt="Version 0.2.2">
+  <img src="https://img.shields.io/badge/version-0.2.5-blue.svg" alt="Version 0.2.5">
 </p>
 
 `echr-py` is a research engineering toolkit for the case law of the European
@@ -24,10 +24,6 @@ Court of Human Rights. It connects public
 research artifacts through Python, a command-line interface, and the Model
 Context Protocol (MCP).
 
-The distribution and primary command are now named `echr-py`. The established
-`hudoc_py` Python import and the legacy `hudoc-py` command remain available for
-backward compatibility.
-
 It is designed for work where provenance matters. A result can retain the exact
 HUDOC document, language version, section, paragraph, individual opinion,
 footnote, citation span, cited procedural document, cited-paragraph pinpoint,
@@ -256,6 +252,17 @@ echr-py versions download \
 The acquisition manifest records each language-specific item ID, rendition
 type, requested-format outcome, HTTP status, path, byte length, and SHA-256.
 
+### DOCX structure, opt-in
+
+HUDOC's HTML is generated from the Registry's Word files and keeps only hashed
+formatting classes. The DOCX keeps the template's named styles (`Ju_H_Head`,
+`Ju_Para`, `Ju_Quot`, `Ju_Judges`, `Opi_H_Head`, `Opi_Para`), present from the
+first judgment of 1961 onward. `--docx-structure` (or `docx_structure=True`)
+reads them into an advisory `DocxStructure` with sections, numbered paragraphs,
+quotations, the bench, separate opinions and footnotes, and reports where it
+agrees with the HTML segmentation. HTML stays canonical for offsets, citation
+loci and benchmarks. See [docs/text-segmentation.md](https://github.com/niccoloridi/echr-py/blob/main/docs/text-segmentation.md#docx-structure-opt-in-advisory).
+
 ## Local lexical, dense, and hybrid retrieval
 
 Build a portable paragraph index from any acquired corpus:
@@ -407,7 +414,7 @@ without cloning the repository:
 
 ```bash
 claude mcp add --scope user --transport stdio echr-py -- \
-  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.2' echr-py mcp
+  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.5' echr-py mcp
 claude mcp get echr-py
 ```
 
@@ -467,7 +474,7 @@ study jobs are an explicit opt-in.
 
 | Command group | Purpose |
 | --- | --- |
-| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition |
+| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition; `--docx-structure` adds the advisory Registry-style structure |
 | `versions …`, `corpus …` | Language versions and reproducible corpora |
 | `local …`, `embeddings …` | Offline browsing and paragraph retrieval |
 | `gui` | Optional local Streamlit corpus browser |
@@ -475,7 +482,7 @@ study jobs are an explicit opt-in.
 | `graph metrics|export|html|gexf` | Network metrics and portable graph output |
 | `study validate|plan|run|status|resume|export` | Bounded optional dataset studies |
 | `exec …` | HUDOC-EXEC record discovery, download, and source conversion |
-| `mcp` | Read-only MCP server by default; bounded jobs are opt-in |
+| `mcp` | Read-only MCP server by default; bounded jobs are opt-in; `--call-log PATH` records every tool call (tool, arguments, returned item IDs and ECLIs, version, time) as a replayable JSONL log |
 
 ```bash
 echr-py --help
@@ -547,6 +554,21 @@ cd echr-py
 python -m pip install -e ".[all,dev]"
 ```
 
+### Names
+
+The distribution and primary command are `echr-py`. The Python import is
+`hudoc_py`, and the earlier `hudoc-py` command still works; both remain
+available so existing code and scripts keep running.
+
+```python
+import hudoc_py            # import name
+```
+
+```bash
+echr-py --version          # primary command
+hudoc-py --version         # legacy alias, same program
+```
+
 ## Documentation
 
 - [Worked examples](https://github.com/niccoloridi/echr-py/blob/main/docs/examples.md)

{echr_py-0.2.2 → echr_py-0.2.5/echr_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echr-py
-Version: 0.2.2
+Version: 0.2.5
 Summary: Pythonic acquisition of HUDOC and HUDOC-EXEC metadata and source documents for ECtHR research.
 Author-email: Niccolo Ridi <niccoloridi@gmail.com>
 License-Expression: MIT
@@ -102,7 +102,7 @@ Dynamic: license-file
   <a href="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml"><img src="https://github.com/niccoloridi/echr-py/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/python-3.11%E2%80%933.14-3776AB.svg" alt="Python 3.11–3.14">
   <a href="https://github.com/niccoloridi/echr-py/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT license"></a>
-  <img src="https://img.shields.io/badge/version-0.2.2-blue.svg" alt="Version 0.2.2">
+  <img src="https://img.shields.io/badge/version-0.2.5-blue.svg" alt="Version 0.2.5">
 </p>
 
 `echr-py` is a research engineering toolkit for the case law of the European
@@ -112,10 +112,6 @@ Court of Human Rights. It connects public
 research artifacts through Python, a command-line interface, and the Model
 Context Protocol (MCP).
 
-The distribution and primary command are now named `echr-py`. The established
-`hudoc_py` Python import and the legacy `hudoc-py` command remain available for
-backward compatibility.
-
 It is designed for work where provenance matters. A result can retain the exact
 HUDOC document, language version, section, paragraph, individual opinion,
 footnote, citation span, cited procedural document, cited-paragraph pinpoint,
@@ -344,6 +340,17 @@ echr-py versions download \
 The acquisition manifest records each language-specific item ID, rendition
 type, requested-format outcome, HTTP status, path, byte length, and SHA-256.
 
+### DOCX structure, opt-in
+
+HUDOC's HTML is generated from the Registry's Word files and keeps only hashed
+formatting classes. The DOCX keeps the template's named styles (`Ju_H_Head`,
+`Ju_Para`, `Ju_Quot`, `Ju_Judges`, `Opi_H_Head`, `Opi_Para`), present from the
+first judgment of 1961 onward. `--docx-structure` (or `docx_structure=True`)
+reads them into an advisory `DocxStructure` with sections, numbered paragraphs,
+quotations, the bench, separate opinions and footnotes, and reports where it
+agrees with the HTML segmentation. HTML stays canonical for offsets, citation
+loci and benchmarks. See [docs/text-segmentation.md](https://github.com/niccoloridi/echr-py/blob/main/docs/text-segmentation.md#docx-structure-opt-in-advisory).
+
 ## Local lexical, dense, and hybrid retrieval
 
 Build a portable paragraph index from any acquired corpus:
@@ -495,7 +502,7 @@ without cloning the repository:
 
 ```bash
 claude mcp add --scope user --transport stdio echr-py -- \
-  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.2' echr-py mcp
+  "$(command -v uvx)" --from 'echr-py[mcp]==0.2.5' echr-py mcp
 claude mcp get echr-py
 ```
 
@@ -555,7 +562,7 @@ study jobs are an explicit opt-in.
 
 | Command group | Purpose |
 | --- | --- |
-| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition |
+| `search`, `count`, `fetch-case`, `smart-fetch` | HUDOC metadata and document acquisition; `--docx-structure` adds the advisory Registry-style structure |
 | `versions …`, `corpus …` | Language versions and reproducible corpora |
 | `local …`, `embeddings …` | Offline browsing and paragraph retrieval |
 | `gui` | Optional local Streamlit corpus browser |
@@ -563,7 +570,7 @@ study jobs are an explicit opt-in.
 | `graph metrics|export|html|gexf` | Network metrics and portable graph output |
 | `study validate|plan|run|status|resume|export` | Bounded optional dataset studies |
 | `exec …` | HUDOC-EXEC record discovery, download, and source conversion |
-| `mcp` | Read-only MCP server by default; bounded jobs are opt-in |
+| `mcp` | Read-only MCP server by default; bounded jobs are opt-in; `--call-log PATH` records every tool call (tool, arguments, returned item IDs and ECLIs, version, time) as a replayable JSONL log |
 
 ```bash
 echr-py --help
@@ -635,6 +642,21 @@ cd echr-py
 python -m pip install -e ".[all,dev]"
 ```
 
+### Names
+
+The distribution and primary command are `echr-py`. The Python import is
+`hudoc_py`, and the earlier `hudoc-py` command still works; both remain
+available so existing code and scripts keep running.
+
+```python
+import hudoc_py            # import name
+```
+
+```bash
+echr-py --version          # primary command
+hudoc-py --version         # legacy alias, same program
+```
+
 ## Documentation
 
 - [Worked examples](https://github.com/niccoloridi/echr-py/blob/main/docs/examples.md)

{echr_py-0.2.2 → echr_py-0.2.5}/echr_py.egg-info/SOURCES.txt

@@ -91,6 +91,7 @@ hudoc_py/main/queries.py
 hudoc_py/main/url.py
 hudoc_py/mcp/__init__.py
 hudoc_py/mcp/__main__.py
+hudoc_py/mcp/calllog.py
 hudoc_py/mcp/install.py
 hudoc_py/mcp/server.py
 hudoc_py/models/__init__.py
@@ -98,6 +99,7 @@ hudoc_py/models/case.py
 hudoc_py/models/citation.py
 hudoc_py/models/common.py
 hudoc_py/models/document.py
+hudoc_py/models/docx_structure.py
 hudoc_py/models/exec_case.py
 hudoc_py/models/exec_document.py
 hudoc_py/models/version.py
@@ -123,6 +125,7 @@ hudoc_py/text/__init__.py
 hudoc_py/text/composition.py
 hudoc_py/text/conversion.py
 hudoc_py/text/dispositive.py
+hudoc_py/text/docx_structure.py
 hudoc_py/text/judges.py
 hudoc_py/text/opinions.py
 hudoc_py/text/segmentation.py

{echr_py-0.2.2 → echr_py-0.2.5}/hudoc_py/__init__.py

@@ -37,7 +37,7 @@ from ._sync import (
 from .main.dsl import Q
 from .models import Case, CaseCollection, Document, Sections
 
-__version__ = "0.2.2"
+__version__ = "0.2.5"
 
 __all__ = [
     "__version__",

{echr_py-0.2.2 → echr_py-0.2.5}/hudoc_py/_aio.py

@@ -7,6 +7,7 @@ These coroutines are the canonical implementation; the sync facade in
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Iterable
 from pathlib import Path
 from typing import Any
 
@@ -14,7 +15,11 @@ import aiohttp
 
 from . import config
 from .main.client import AsyncHudocClient
-from .main.downloader import DOWNLOAD_HEADERS, fetch_document_docx, fetch_document_html
+from .main.downloader import (
+    download_headers,
+    fetch_document_docx,
+    fetch_document_html,
+)
 from .main.dsl import Q
 from .main.queries import resolve_sort
 from .models import Case, CaseCollection
@@ -134,7 +139,7 @@ async def hydrate_texts(
         if case.text_source_itemid != case.itemid:
             counts["fallback_used"] += 1
 
-    async with aiohttp.ClientSession(headers=DOWNLOAD_HEADERS) as session:
+    async with aiohttp.ClientSession(headers=download_headers()) as session:
         await asyncio.gather(*(_one(session, c) for c in collection))
     return counts
 
@@ -216,6 +221,7 @@ async def smart_fetch(
     rich_sections: bool = False,
     french_fallback: bool = True,
     concurrency: int = config.HUDOC_CONCURRENCY,
+    docx_structure: bool = False,
     **filters: Any,
 ) -> CaseCollection:
     """Search, keep the ``top`` matches, and fetch their texts concurrently.
@@ -245,6 +251,8 @@ async def smart_fetch(
             french_fallback=french_fallback,
             concurrency=concurrency,
         )
+    if docx_structure and collection:
+        await hydrate_docx_structures(collection, concurrency=concurrency)
 
     return collection
 
@@ -261,6 +269,7 @@ async def fetch_case(
     french_fallback: bool = True,
     rescue: bool = False,
     docx_out: str | Path | None = None,
+    docx_structure: bool = False,
 ) -> Case | None:
     """Fetch metadata (and optionally full text) for a single case.
 
@@ -295,7 +304,7 @@ async def fetch_case(
         case = Case.model_validate(rows[0])
 
         if with_text and case.itemid:
-            async with aiohttp.ClientSession(headers=DOWNLOAD_HEADERS) as session:
+            async with aiohttp.ClientSession(headers=download_headers()) as session:
                 loaded = await _fetch_case_text(
                     session,
                     case,
@@ -320,12 +329,43 @@ async def fetch_case(
                             french_fallback=True,
                         )
 
-    if docx_out is not None and case.itemid:
-        await fetch_docx(case.itemid, out=docx_out)
+    if (docx_out is not None or docx_structure) and case.itemid:
+        data = await fetch_docx(case.itemid, out=docx_out)
+        if docx_structure:
+            attach_docx_structure(case, data)
 
     return case
 
 
+def attach_docx_structure(case: Case, data: bytes | None) -> None:
+    """Set ``case.docx_structure`` from DOCX bytes (an empty, diagnosed structure when absent)."""
+    from .models.docx_structure import DocxStructure
+    from .text.docx_structure import build_docx_structure
+
+    if data is None:
+        case.docx_structure = DocxStructure(
+            itemid=case.itemid, sha256="", byte_count=0, diagnostics=["docx_unavailable"]
+        )
+        return
+    case.docx_structure = build_docx_structure(data, itemid=case.itemid)
+
+
+async def hydrate_docx_structures(
+    cases: Iterable[Case], *, concurrency: int = config.HUDOC_CONCURRENCY
+) -> int:
+    """Fetch each case's DOCX and attach its structure; returns the number attached."""
+    semaphore = asyncio.Semaphore(max(1, concurrency))
+    targets = [c for c in cases if c.itemid]
+
+    async def one(case: Case) -> None:
+        async with semaphore:
+            data = await fetch_docx(case.itemid)  # type: ignore[arg-type]
+            attach_docx_structure(case, data)
+
+    await asyncio.gather(*(one(c) for c in targets))
+    return sum(1 for c in targets if c.docx_structure is not None and c.docx_structure.byte_count)
+
+
 async def fetch_docx(itemid: str, *, out: str | Path | None = None) -> bytes | None:
     """Fetch a document's raw DOCX bytes; optionally write them to ``out``.
 
@@ -333,7 +373,7 @@ async def fetch_docx(itemid: str, *, out: str | Path | None = None) -> bytes | N
     DOCX is a separate binary payload from the HTML body and is deliberately
     not stored on ``Case.text``.
     """
-    async with aiohttp.ClientSession(headers=DOWNLOAD_HEADERS) as session:
+    async with aiohttp.ClientSession(headers=download_headers()) as session:
         data = await fetch_document_docx(session, itemid)
     if data is not None and out is not None:
         Path(out).write_bytes(data)
@@ -342,7 +382,7 @@ async def fetch_docx(itemid: str, *, out: str | Path | None = None) -> bytes | N
 
 async def fetch_text(itemid: str, *, format: str = "text") -> str | None:
     """Fetch and convert a single document's body."""
-    async with aiohttp.ClientSession(headers=DOWNLOAD_HEADERS) as session:
+    async with aiohttp.ClientSession(headers=download_headers()) as session:
         html = await fetch_document_html(session, itemid)
     if html is None:
         return None

{echr_py-0.2.2 → echr_py-0.2.5}/hudoc_py/_sync.py

@@ -65,6 +65,7 @@ def smart_fetch(
     rich_sections: bool = False,
     french_fallback: bool = True,
     concurrency: int = config.HUDOC_CONCURRENCY,
+    docx_structure: bool = False,
     **filters: Any,
 ) -> CaseCollection:
     """Search, keep the ``top`` matches, and fetch their texts concurrently."""
@@ -80,6 +81,7 @@ def smart_fetch(
             rich_sections=rich_sections,
             french_fallback=french_fallback,
             concurrency=concurrency,
+            docx_structure=docx_structure,
             **filters,
         )
     )
@@ -97,6 +99,7 @@ def fetch_case(
     french_fallback: bool = True,
     rescue: bool = False,
     docx_out: str | Path | None = None,
+    docx_structure: bool = False,
 ) -> Case | None:
     return _run(
         _aio.fetch_case(
@@ -110,6 +113,7 @@ def fetch_case(
             french_fallback=french_fallback,
             rescue=rescue,
             docx_out=docx_out,
+            docx_structure=docx_structure,
         )
     )
 

{echr_py-0.2.2 → echr_py-0.2.5}/hudoc_py/bilingual/__init__.py

@@ -33,6 +33,7 @@ from .rescue import (
     find_french_sibling,
     rescue_candidates,
     rescue_french,
+    sibling_conflicts,
 )
 
 
@@ -70,6 +71,7 @@ __all__ = [
     "ReconcileStats",
     "ReconcileInvariantError",
     "rescue_french",
+    "sibling_conflicts",
     "rescue_candidates",
     "find_french_sibling",
     "apply_rescue_mapping",

{echr_py-0.2.2 → echr_py-0.2.5}/hudoc_py/bilingual/corpus.py

@@ -31,9 +31,10 @@ from pydantic import BaseModel, Field, field_validator
 
 from .. import config
 from .._aio import _fetch_case_text, search
-from ..main.downloader import DOWNLOAD_HEADERS
+from ..main.downloader import download_headers
 from ..main.dsl import Q
 from ..models.case import Case, CaseCollection
+from ..models.common import Sections
 from ..utils.jsonl import append_jsonl, append_jsonl_many, iter_jsonl, load_processed_ids
 from .reconcile import ExtraSiblingPolicy, ReconcileStats, reconcile
 from .rescue import RescueStats, rescue_french
@@ -51,6 +52,7 @@ class CorpusReport(BaseModel):
     language_texts: dict[str, int] | None = None
     citations: dict[str, Any] | None = None
     rich_tables: dict[str, int] | None = None
+    docx_structures: dict[str, int] | None = None
     selection: dict[str, int] | None = None
     out_dir: str = ""
 
@@ -184,12 +186,15 @@ def _save_language_versions(cases: list[Case], entries: list[SelectionEntry], pa
 
     ownership = _language_version_ownership(entries)
     rows = [
-        {**case.model_dump(mode="json", exclude={"text", "sections"}), **ownership[case.itemid]}
+        {
+            **case.model_dump(mode="json", exclude={"text", "sections", "docx_structure"}),
+            **ownership[case.itemid],
+        }
         for case in cases
         if case.itemid in ownership
     ]
     columns = [
-        *[name for name in Case.model_fields if name not in {"text", "sections"}],
+        *[name for name in Case.model_fields if name not in {"text", "sections", "docx_structure"}],
         "primary_itemid",
         "selection_ecli",
         "selected_language",
@@ -369,6 +374,7 @@ async def build_corpus(
     text_format: str = "text",
     rescue: bool = True,
     save_docx: bool = False,
+    docx_structure: bool = False,
     resolve_case_citations: bool = False,
     citation_authority: str | Path | None = None,
     citation_overrides: str | Path | None = None,
@@ -378,6 +384,9 @@ async def build_corpus(
     concurrency: int = config.HUDOC_CONCURRENCY,
     **filters: Any,
 ) -> CorpusReport:
+    # The DOCX agreement report needs the HTML segmentation, which only the rich
+    # split persists; requesting the DOCX layer therefore implies rich sections.
+    rich_sections = rich_sections or docx_structure
     """Build a reconciled, text-hydrated corpus under ``out_dir``.
 
     The default search covers both languages and all six doctypes, so ENG/FRE
@@ -464,8 +473,8 @@ async def build_corpus(
             failures_path=failures_path,
         )
 
-    # 5. Optional raw DOCX download.
-    if save_docx:
+    # 5. Optional raw DOCX download (forced on when the DOCX structure layer is requested).
+    if save_docx or docx_structure:
         from ..main.downloader import AsyncDocumentDownloader
 
         downloader = AsyncDocumentDownloader(
@@ -516,6 +525,16 @@ async def build_corpus(
         write_resolution_artifacts(citation_result, citation_dir)
         report.citations = citation_result.report.model_dump(mode="json")
 
+    # 8. Optional advisory DOCX structure layer: one record per case with the
+    # Registry-style structure and its agreement with the HTML segmentation.
+    if docx_structure:
+        persisted_sections = (
+            out / "language-sections.jsonl" if language_version_cases else out / "sections.jsonl"
+        )
+        report.docx_structures = _write_docx_structures(
+            result.cases, out, sections_path=persisted_sections
+        )
+
     (out / "report.json").write_text(report.model_dump_json(indent=2) + "\n", encoding="utf-8")
     from .bundle import generate_corpus_manifest
 
@@ -560,7 +579,7 @@ async def _hydrate_to_jsonl(
             return case, False
         return case, True
 
-    async with aiohttp.ClientSession(headers=DOWNLOAD_HEADERS) as session:
+    async with aiohttp.ClientSession(headers=download_headers()) as session:
         results = await asyncio.gather(*(_one(session, c) for c in todo))
     for case, ok in results:
         if not ok:
@@ -609,7 +628,7 @@ def _save_parquet(cases: list[Case], path: Path, *, drop_text: bool) -> None:
     rows = [c.model_dump(mode="json") for c in cases]
     df = pd.DataFrame(rows) if rows else pd.DataFrame(columns=list(Case.model_fields))
     if drop_text:
-        df = df.drop(columns=[c for c in ("text", "sections") if c in df.columns])
+        df = df.drop(columns=[c for c in ("text", "sections", "docx_structure") if c in df.columns])
     path.parent.mkdir(parents=True, exist_ok=True)
     df.to_parquet(path, index=False)
 
@@ -627,3 +646,65 @@ def load_cases(path: str | Path) -> CaseCollection:
 
 
 __all__ = ["build_corpus", "CorpusReport", "load_cases", "load_selection", "SelectionEntry"]
+
+
+def _load_persisted_sections(path: Path) -> dict[str, Sections]:
+    """Read ``sections.jsonl`` (or ``language-sections.jsonl``) back into ``Sections`` by item ID."""
+    from ..utils.jsonl import iter_jsonl
+
+    if not path.exists():
+        return {}
+    restored: dict[str, Sections] = {}
+    for record in iter_jsonl(path):
+        itemid = str(record.get("itemid") or "")
+        if itemid and isinstance(record.get("sections"), dict) and itemid not in restored:
+            restored[itemid] = Sections.model_validate(record["sections"])
+    return restored
+
+
+def _write_docx_structures(
+    cases: list[Case], out: Path, *, sections_path: Path | None = None
+) -> dict[str, int]:
+    """Parse the DOCX files saved under ``docs/docx`` and write ``docx_structure.jsonl``.
+
+    Sections for the agreement report come from the in-memory case when it was
+    hydrated in this run, and otherwise from the persisted ``sections.jsonl`` so
+    resumed builds report agreement for every case.
+    """
+    import json
+
+    from ..text.docx_structure import build_docx_structure, compare_docx_structure
+
+    persisted = _load_persisted_sections(sections_path) if sections_path is not None else {}
+    docx_dir = out / "docs" / "docx"
+    counts = {"cases": 0, "with_docx": 0, "sections_agree": 0, "opinions_agree": 0}
+    with (out / "docx_structure.jsonl").open("w", encoding="utf-8") as handle:
+        for case in cases:
+            if not case.itemid:
+                continue
+            counts["cases"] += 1
+            path = docx_dir / f"{case.itemid}.docx"
+            record: dict[str, Any] = {
+                "itemid": case.itemid,
+                "docx_path": str(path.relative_to(out)) if path.exists() else None,
+            }
+            if path.exists():
+                structure = build_docx_structure(path.read_bytes(), itemid=case.itemid)
+                case.docx_structure = structure
+                counts["with_docx"] += 1
+                record["structure"] = structure.model_dump(mode="json")
+                sections = case.sections or persisted.get(case.itemid)
+                if sections is not None:
+                    agreement = compare_docx_structure(
+                        case
+                        if case.sections is not None
+                        else case.model_copy(update={"sections": sections}),
+                        structure,
+                    )
+                    record["agreement"] = agreement.model_dump(mode="json")
+                    counts["sections_agree"] += int(agreement.sections_agree)
+                    counts["opinions_agree"] += int(agreement.opinion_counts_agree)
+            else:
+                record["structure"] = None
+            handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+    return counts