athena-python-docx 0.20.0__tar.gz → 0.21.1__tar.gz

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/CLAUDE.md

@@ -25,35 +25,35 @@ Before adding or modifying any API surface:
 
 Run `uv run pytest tests/test_python_docx_api_parity.py -v -s` to verify parity.
 
-### Intentionally omitted (Superdoc SDK limitations)
+### Intentionally omitted (current SDK limitations)
 
-These standard python-docx members don't apply to a Superdoc-backed SDK:
+These standard python-docx members don't apply to a DOCX Studio-backed SDK:
 
 - `Paragraph._p`, `Run._r` — XML element access (no local XML)
 - `Document.part`, `Paragraph.part`, `Run.part` — package part access
 - `Document.core_properties.last_modified_by` — we use Keryx attribution instead
-- `Document.settings` — Word app settings (not surfaced by Superdoc)
-- `InlineShape.chart` — charts (Phase 2+)
+- `Document.settings` — Word app settings (not surfaced by DOCX Studio)
+- `InlineShape.chart` — charts are not currently surfaced by the SDK.
 - `Comment.add_paragraph` / `Comment.add_table` /
   `Comment.iter_inner_content` / `Comment.paragraphs` /
-  `Comment.tables` — SuperDoc models a comment as a single text body,
+  `Comment.tables` — DOCX Studio models a comment as a single text body,
   not a `BlockItemContainer`. Use `Comment.text` instead. The
   paragraph/table-bearing surface raises `CommentsNotImplementedError`.
 - **`_Cell.add_table(rows, cols)`** — surface preserved for parity
   (signature matches python-docx, no `width` kwarg) but raises
   :class:`docx.errors.NestedTableNotSupportedError` (subclass of
-  `NotImplementedError`) at runtime since 0.11.2. SuperDoc 1.8.1 has
-  no anchor or content-fragment shape that places a new table inside
-  an existing `tableCell` — `create.table` rejects cell-inner
+  `NotImplementedError`) at runtime since 0.11.2. The current
+  docx-editor command surface has no anchor or content-fragment shape
+  that places a new table inside an existing `tableCell` — `create.table` rejects cell-inner
   paragraph anchors with `INVALID_TARGET`, and the `doc.insert`
   workaround used by `_Cell.add_paragraph` doesn't generalize
   because the apps/api `Insert` schema doesn't yet forward
-  `nestingPolicy: {tables: "allow"}` and the SuperDoc table-content
+  `nestingPolicy: {tables: "allow"}` and the DOCX editor table-content
   fragment shape isn't documented. Tracked at
-  `docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md` § 13.
+  `docx-studio/DOCX_STUDIO_LIMITATIONS.md` § 13.
 - **`docx.oxml.*`** — the entire raw-OOXML module tree (``ns.qn``,
   ``OxmlElement``, ``CT_*`` classes, etc.) is unavailable because the
-  SDK is HTTP-only against a SuperDoc Y.Doc; there is no local lxml
+  SDK is HTTP-only against a DOCX Studio Y.Doc; there is no local lxml
   tree to manipulate. As of 0.8.0, ``docx.oxml`` is a real stub
   package that raises a typed
   :class:`docx.oxml.OxmlNotAvailableError` (subclass of
@@ -64,25 +64,21 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
   generic ``ModuleNotFoundError: No module named 'docx.oxml'`` and
   agents had to retry to discover the gap.
 
-### Phase-3b upstream-blocked surface
+### Known partially supported surface
 
 These are *shipped at the surface* but partially or fully no-op at
-runtime, pending SuperDoc SDK changes outside this repo. The
-upstream constraints have been verified against
-[SuperDoc's published docs](https://docs.superdoc.dev/document-api/reference/styles/apply)
-and the bundled TypeScript types in
-`node_modules/@superdoc-dev/sdk/dist/generated/client.d.ts`. See
-`docx-studio/PYTHON_DOCX_PARITY_GAPS.md` § *What unblocks the
-remaining work* for the exact wire-op shape needed to unblock each.
+runtime, pending additional docx-editor command support. Behavior should be
+pinned by focused tests and documented in
+`docx-studio/DOCX_STUDIO_LIMITATIONS.md`.
 
 - **24 setters on `BaseStyle` / `CharacterStyle` / `ParagraphStyle`**
   (`name`, `style_id`, `hidden`, `locked`, `priority`, `quick_style`,
   `unhide_when_used`, `base_style`, `next_paragraph_style`) emit
   `PendingStyleMutationWarning` and stash on `_overrides`.
-  SuperDoc 1.7's `doc.styles.apply` is constrained to
+  The current `doc.styles.apply` command surface is constrained to
   `target.scope: "docDefaults"` — no per-style metadata variant.
   Behavior pinned by `tests/test_style_setters_contract.py` (11
-  tests); when SuperDoc lands a metadata op, those tests will need
+  tests); when docx-editor lands a metadata op, those tests will need
   to flip to assert real bus calls.
 - **`Styles.latent_styles`** returns an empty `_LatentStyles` —
   `DocInfoResult.styles` only surfaces `paragraphStyles[]` (a flat
@@ -123,25 +119,24 @@ not file-backed. Each is documented in the relevant docstring.
   and silently falls back to ``Normal Table`` (no borders, no
   header fill, no banding). Custom user-defined style names pass
   through unchanged. Whether Word actually renders a Word 2013+
-  style after resolution also depends on SuperDoc's exported
+  style after resolution also depends on the exported
   ``styles.xml`` containing the matching ``<w:style w:type="table">``
-  definition — at SuperDoc 1.8.1 the exported ``styles.xml`` only
-  carries the Word 2007 set, so Word 2013+ styleIds resolve in the
-  ``<w:tblStyle>`` element but still fall back to ``Normal Table``
-  until SuperDoc upstream ships an expanded ``styles.xml``.
+  definition. If the exported ``styles.xml`` only carries the Word 2007
+  set, Word 2013+ styleIds resolve in the ``<w:tblStyle>`` element but
+  still fall back to ``Normal Table`` until the export path ships an
+  expanded ``styles.xml``.
 
 - **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=, docx=, agora_base_url=)`**
   classmethod. Stock python-docx returns a blank in-memory document
-  for `Document(None)`; we can't fabricate a SuperDocument asset
+  for `Document(None)`; we can't fabricate a Word document asset
   client-side, so net-new asset creation is a separate factory that
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
   - **`docx=path`** mirrors the upstream `Document(docx="template.docx")`
-    constructor kwarg: when provided, the local `.docx` is uploaded to
-    agora's `/api/super-docs/create-from-upload` and used as the seed
-    for the new SuperDocument. The bytes are mirrored to S3 server-side
-    so subsequent template-asset reuse is fast. Without `docx=`, the
-    default Athena template is applied as today.
+    constructor kwarg: when provided, the SDK creates a normal Word
+    document asset through Agora's docx-studio bridge, then imports the
+    local `.docx` into that asset. Without `docx=`, the default Athena
+    template is applied as today.
   - **`agora_base_url=`** is a transport-detail kwarg only required when
     the SDK can't derive the agora host from `base_url` (or from
     `$ATHENA_AGORA_BASE_URL`). The default substitution rule replaces
@@ -169,14 +164,14 @@ not file-backed. Each is documented in the relevant docstring.
   When a path or stream IS supplied, the SDK cannot fulfill the
   implied "write bytes to this target" contract, so the call raises
   loudly rather than silently flushing — agents must use Olympus's
-  Export DOCX (which goes through the SuperDoc session that already
+  Export DOCX (which goes through the DOCX Studio session that already
   has the bytes) instead of expecting a local file.
 
 - **`Document.track_revisions: bool`** — when `True`, all subsequent
   mutations are recorded as tracked revisions instead of direct edits.
   python-docx upstream has no top-level toggle (the closest is
   hand-edited `<w:trackChanges/>` on `Document.settings.element`).
-  We expose this as a Document-level property because every SuperDoc
+  We expose this as a Document-level property because every DOCX Studio
   mutation accepts a per-call `changeMode` envelope field. The
   python-docx-parity alias `Document.settings.track_revisions` reads
   and writes the same flag so call sites that walk `doc.settings`
@@ -189,10 +184,10 @@ not file-backed. Each is documented in the relevant docstring.
   because the upstream package has no track-changes API at all.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
-  None`** — author identity threaded through to SuperDoc on session-
+  None`** — author identity threaded through to DOCX Studio on session-
   open for tracked-change attribution. python-docx's
   `Document.core_properties.last_modified_by` is the closest upstream
-  surface; we use the SuperDoc-native fields directly because SuperDoc
+  surface; we use the DOCX Studio-native fields directly because DOCX Studio
   bakes them into the change records.
 
 - **`Document.revisions: Revisions`** — collection of tracked changes
@@ -200,7 +195,7 @@ not file-backed. Each is documented in the relevant docstring.
   `accept(id)`, `reject(id)`. Per-revision `Revision.accept()` /
   `Revision.reject()` resolve a single change. python-docx upstream
   has zero track-changes API, so this entire surface is an Athena
-  extension wired to SuperDoc's `doc.trackChanges.{list,get,decide}`.
+  extension wired to DOCX Studio's `doc.trackChanges.{list,get,decide}`.
 
 ### Athena extensions for most-requested upstream features (v0.11.0+)
 
@@ -218,7 +213,7 @@ Issue numbers reference `python-openxml/python-docx`.
   tooltip=None) -> Hyperlink`** — appends a hyperlinked run.
   python-docx surfaces `Hyperlink` as read-only; PR #74 has been open
   since 2014 and is the single most-requested missing feature. Routes
-  through `CreateHyperlink` (SuperDoc `doc.hyperlinks.create`). Returns
+  through `CreateHyperlink` (DOCX Studio `doc.hyperlinks.create`). Returns
   the same `Hyperlink` class the read path already exposes. Also
   available as `Run.add_hyperlink` for convenience.
 
@@ -298,7 +293,7 @@ Issue numbers reference `python-openxml/python-docx`.
   metadata. python-docx PR #1530 is in flight but unreleased; the
   feature has been requested for years. Routes through
   `SetImageAltText` / `SetImageDecorative` (already wired in
-  SuperDoc).
+  DOCX Studio).
 
 - **`InlineShape.anchor(*, wrap="square", position_x_pt=,
   position_y_pt=, relative_from_x=, relative_from_y=,
@@ -375,13 +370,13 @@ Issue numbers reference `python-openxml/python-docx`.
   include_revisions=False) -> bytes`** — render to PDF via the
   Daytona-hosted LibreOffice. python-docx issue #113 was closed as
   wontfix upstream but the request keeps recurring. Routes through
-  `ExportPDF` (SuperDoc handles the actual conversion).
+  `ExportPDF` (DOCX Studio handles the actual conversion).
 
 - **`Document.clear()`** (0.14.0+) — empty the document body so subsequent
   writes start from a clean slate. python-docx has no equivalent (it
   operates on local files where the caller can simply construct a new
   ``Document``). Iterates every top-level paragraph and table cell and
-  empties their text content. Block structure is preserved (SuperDoc has
+  empties their text content. Block structure is preserved (DOCX Studio has
   no wire op to delete blocks today), so post-clear the doc holds N
   empty paragraphs rather than collapsing to a single one — for a truly
   empty body, call ``Document.create()`` to mint a fresh asset instead.
@@ -389,6 +384,69 @@ Issue numbers reference `python-openxml/python-docx`.
   cleanup loops, which left horizontal-rule and scratch-content artifacts
   in the document during failed-run recoveries.
 
+- **`Paragraph.add_citation(source, *, anchor=None, excerpt=None,
+  display_value=None) -> str`** + **`Paragraph.clear_citations()`** +
+  **`Document.add_citation(source, *, destination_anchor, anchor=None,
+  ...)`** + **`Document.remove_citation(citation_id)`** (0.20.0+) —
+  SDK-native Athena citations. This is the programmatic equivalent of
+  the user selecting DOCX text and choosing "Use selection as citation
+  destination/source" in Olympus: it writes the canonical document
+  citation record into the document's ``citations`` Y.Array and applies
+  the citation-blue highlight to the destination paragraph/range. It is
+  not a live link and does not overwrite destination text.
+
+  Use citations as evidence, not as generic source mentions.
+  ``Paragraph.add_citation(...)`` highlights the whole paragraph in Athena, so
+  make the destination unit match the evidence: a metric cell/table row for a
+  number, one short sentence for a claim, or one short paragraph only when the
+  same source supports the full paragraph. If only a few words or numbers in a
+  long paragraph are supported, split that claim into its own sentence,
+  paragraph, or table row before citing it. Do not add duplicate citations to
+  every rendered line when one citation on the semantic claim/table row is
+  sufficient.
+  Use a mention/reference instead when you only need to point at a related
+  source without claiming evidentiary support. For PDFs, prefer a tight page
+  text anchor or a page anchor with an ``excerpt`` containing the exact
+  phrase/number being supported, not just a broad section title.
+
+  Prefer a canonical citation string when the source/anchor is already known
+  as a Spaces URL, or when the source type is not modeled by the DOCX SDK
+  (video/audio time ranges, browser sessions, external URLs, etc.). Typed
+  ``AssetReference`` + anchor objects are still useful convenience helpers for
+  common Athena assets such as spreadsheets and PDFs, but they are not the only
+  valid source form.
+
+  Common agent pattern after writing a supported claim:
+
+  ```python
+  from docx import Document
+  from docx._references import AssetReference, SheetRangeAnchor
+
+  doc = Document("asset_word")
+  p = doc.add_paragraph("The combined assessment identified 20,049 total vulnerabilities.")
+
+  # Preferred generic path: pass a canonical Spaces URL or https URL.
+  citation_id = p.add_citation(
+      "/dashboard/spaces/?asset_ids=asset_spreadsheet&type=spreadsheet"
+      "&anchor=sheet_range&sheet_id=0&range=B2%3AB8",
+      excerpt="20,049 total vulnerabilities",
+      display_value="Vulnerability total",
+  )
+
+  # Typed helper path: still fine when the SDK has the source/anchor dataclasses.
+  citation_id = p.add_citation(
+      AssetReference(id="asset_spreadsheet"),
+      anchor=SheetRangeAnchor(sheet_id=0, range="B2:B8"),
+      excerpt="20,049 total vulnerabilities",
+      display_value="Vulnerability total",
+  )
+  doc.save()
+  ```
+
+  Use ``Document.add_citation(..., destination_anchor=PmNodeAnchor(...))``
+  only when you already have a DOCX editor anchor id. For normal writing,
+  cite the ``Paragraph`` proxy you just created or found.
+
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
   ``.docx`` bytes, optionally writing to ``path``. Closes the gap
@@ -397,16 +455,13 @@ Issue numbers reference `python-openxml/python-docx`.
   harnesses and CI workflows need a programmatic .docx export to
   diff against ``python-docx`` output that doesn't require a
   human-driven Olympus UI action. Routes through ``ExportDocx`` →
-  apps/api → SuperDoc's official ``doc.save({out: <tmp>})`` (the
-  recommended backend export path per the SuperDoc team — Document
-  API, not the browser-side ``editor.exportDocx`` shim). apps/api
+  apps/api's backend export path. apps/api
   writes the session state to a temp ``.docx``, reads bytes back,
   base64-encodes for the wire, and unlinks the temp in a
   ``finally`` block. The SDK decodes and writes to ``path``.
   ``include_revisions=True`` raises ``DocxError`` pre-flight:
-  ``@superdoc-dev/sdk@1.8.1``'s ``DocSaveParams`` has no
-  ``includeRevisions`` field, so honoring the flag isn't possible
-  through ``doc.save({out})``.
+  the current backend export path has no ``includeRevisions`` support,
+  so honoring the flag isn't possible yet.
 
   Template seeding: ``Document.create()`` (no ``docx=``) already
   produces an exportable asset because ``POST /docs/empty`` seeds
@@ -420,7 +475,7 @@ Issue numbers reference `python-openxml/python-docx`.
 Format ops on cell-inner paragraphs (`paragraph.alignment`,
 `paragraph.style`, every `paragraph_format` setter, and
 `paragraph.add_hyperlink`) used to cascade-fail the entire HTTP
-batch. SuperDoc 1.8.1's
+batch. The current docx-editor applier's
 ``SetParagraphAlignment``/``SetParagraphStyle``/``SetParagraphIndentation``/``SetParagraphSpacing``/``CreateHyperlink``
 reject cell-inner block targets with ``BlockNotFoundError``, and the
 applier's all-or-nothing batch model meant one cell-paragraph
@@ -434,7 +489,7 @@ instead of forwarding the broken command. The format op is dropped,
 the surrounding batch survives, and the workaround pointer (
 ``cell.text = 'value'`` to materialize, then ``cell.paragraphs[0]``
 for the addressable proxy) is in the warning text. Tracked at
-``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 13.
+``docx-studio/DOCX_STUDIO_LIMITATIONS.md`` § 13.
 
 **0.11.5 follow-up: post-export OOXML rewrite.** When the parent
 table was created via ``Document.add_table`` in this session
@@ -444,7 +499,7 @@ OOXML-shaped props (``alignment``, ``style``, ``left_twips``,
 :class:`docx._postproc.PostExportOps` collector). ``Document.export_docx``
 applies them via an OOXML rewrite of ``word/document.xml`` before
 returning bytes — so the **exported ``.docx`` carries the formatting
-the agent asked for** even though SuperDoc never accepted the wire
+the agent asked for** even though DOCX Studio never accepted the wire
 op. Live-session state is unchanged (Olympus collaborators don't
 see the formatting until export). Template-seeded tables where
 ``_doc_index`` is ``None`` still warn-and-skip (no stable OOXML
@@ -463,7 +518,7 @@ helper pattern —
 
 — used to silently drop both the ``Hello world`` text AND the bold
 format because ``Paragraph.add_run`` on a cell-inner paragraph
-returned a stub Run with collapsed range, and SuperDoc 1.8.1
+returned a stub Run with collapsed range, and the docx-editor applier
 rejected the wire-level ``doc.insert`` against the cell-inner
 paragraph's blockId with ``Block <id> not found``. The 0.13.0 fix
 adds a ``_cell`` back-reference to every cell-inner Paragraph proxy
@@ -473,7 +528,7 @@ called on a cell-inner paragraph with non-empty text AND the
 back-ref is set, the SDK ships ``doc.insert(target=cell,
 placement="insideEnd", content=paragraph-fragment-with-text)``
 instead — the SAME wire path ``_Cell.add_paragraph(text)`` already
-uses. SuperDoc collapses the new paragraph into the cell's single
+uses. DOCX Studio collapses the new paragraph into the cell's single
 template paragraph as an inline run; the exported DOCX expands each
 non-empty inline run into its own ``<w:p>``. The returned Run is
 real (non-collapsed range) and carries the new exported-paragraph
@@ -500,10 +555,10 @@ of dropping it silently at the wire layer. The post-export rewrite
 walks every ``<w:r>`` in the targeted cell paragraph and injects
 ``<w:rPr>`` carrying the props — so ``cell.text = "Total"; cell.
 paragraphs[0].runs[0].bold = True`` produces a bold ``Total`` in
-the exported ``.docx`` even though SuperDoc never committed the
+the exported ``.docx`` even though DOCX Studio never committed the
 format wire op. Apply-to-all-runs semantics: the rewrite targets
 every ``<w:r>`` in the cell paragraph, because run-level addressing
-inside a cell isn't recoverable after SuperDoc collapses cell-
+inside a cell isn't recoverable after DOCX Studio collapses cell-
 inner inserts. Multi-run cell paragraphs with partial-run
 formatting are a documented limitation — agents should use one
 run per format intent.
@@ -526,7 +581,7 @@ rels entry so the rels file doesn't grow unboundedly. Behavior
 pinned by ``tests/test_postproc_cell_run_format_rewrite.py``.
 
 Live Olympus rendering still won't show cell-inner formatting or
-hyperlinks until SuperDoc lands the corresponding wire ops —
+hyperlinks until DOCX Studio lands the corresponding wire ops —
 ``Document.export_docx`` is the source of truth for the
 deliverable until then.
 
@@ -541,7 +596,7 @@ deliverable until then.
   workaround pointer and avoids re-issuing the slow query.
 - **`Table._fresh_node_info` rotation tracking.** Each ``Table``
   created via ``Document.add_table`` records its document-order
-  position as ``_doc_index``. When SuperDoc rotates the table's
+  position as ``_doc_index``. When DOCX Studio rotates the table's
   nodeId between saves, the fallback resolves the rotated address
   by position instead of always picking the last ``doc.find`` item.
   Pre-0.11.4 the "take the last" heuristic silently mapped N
@@ -560,18 +615,18 @@ deliverable until then.
   every other field kind) now emits ``at.segments`` with
   ``[{blockId, start, end}]`` instead of the ``{kind: "selection",
   start, end}`` cursor envelope used by other create-ops.
-  SuperDoc's ``doc.fields.insert`` rejects the cursor form with
-  ``SuperDocCliError: fields insert:at.segments is required``;
+  DOCX Studio's ``doc.fields.insert`` rejects the cursor form with
+  ``DocxStudioCommandError: fields insert:at.segments is required``;
   pre-0.11.4 the call took down the whole batch on every flush.
 
 ### 0.11.5 — `REF` field round-trip preservation (post-export rewrite)
 
-SuperDoc 1.23.1 / SDK 1.8.1 strips ``REF`` field codes
+The DOCX editor import/export path can strip ``REF`` field codes
 (``<w:fldChar>`` / ``<w:instrText REF …>`` / result-runs / end
 ``<w:fldChar>``) on import. On the Paul Weiss Purchase Agreement
 this loses all 301 cross-references — readers see chains of empty
 commas instead of "Section 3.02(b)" cross-refs. Tracked at
-``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md`` § 18.
+``docx-studio/DOCX_STUDIO_LIMITATIONS.md`` § 18.
 
 As of 0.11.5, ``Document.create(docx=template.docx)`` scans the
 local template bytes with a stdlib zipfile + xml.etree parser and
@@ -590,7 +645,7 @@ same Python process that called ``Document.create(docx=...)`` also
 calls ``export_docx``. Cross-process flows (agent A creates, agent
 B exports) need agora-side persistence (separate follow-up). (2)
 Paragraph-wholesale replacement preserves the source paragraph but
-overwrites any SuperDoc in-paragraph edits — for round-trip
+overwrites any DOCX Studio in-paragraph edits — for round-trip
 preservation (the primary use case) this is exactly right. (3) Only
 top-level body paragraphs are scanned; cell-inner REFs aren't
 captured (rare for legal cross-references).
@@ -619,9 +674,9 @@ routing, `add_picture` native size + aspect ratio, `WD_BUILTIN_STYLE`
 and `CoreProperties` validation. These are not deviations — they close
 gaps. The items below are the **residual intentional deviations** that
 remain because matching upstream would break the asset-backed/HTTP
-architecture or a SuperDoc constraint:
+architecture or a DOCX Studio constraint:
 
-- **`WD_*` enum `.value` is the SuperDoc wire string, not the MS Word
+- **`WD_*` enum `.value` is the DOCX Studio wire string, not the MS Word
   integer constant.** `WD_ALIGN_PARAGRAPH.CENTER.value == "center"`
   (upstream: `1`); `int(member)` / `member == 1` / `WD_*(1)` therefore
   differ. The string value is load-bearing — every command serializes
@@ -637,7 +692,7 @@ architecture or a SuperDoc constraint:
   stripped before the (otherwise byte-identical) upstream slice parse.
   A strict superset — every value upstream accepts parses identically.
 
-- **`_Cell.vertical_alignment` setter accepts the four SuperDoc wire
+- **`_Cell.vertical_alignment` setter accepts the four DOCX Studio wire
   tokens** (`"top"`/`"center"`/`"bottom"`/`"both"`) in addition to
   `WD_ALIGN_VERTICAL` members. Upstream rejects all plain strings; this
   is an ergonomic superset (typos like `"middle"` still raise
@@ -661,19 +716,19 @@ architecture or a SuperDoc constraint:
 
 - **`Document.add_table(rows, cols)` requires `rows >= 1` and
   `cols >= 1`.** Upstream allows a 0-row/0-col grid you later populate,
-  but SuperDoc's ProseMirror table node can't represent one; the SDK
+  but DOCX Studio's ProseMirror table node can't represent one; the SDK
   raises eagerly rather than failing opaquely on the wire.
 
-- **`Comment.comment_id` returns `str`, not `int`.** SuperDoc uses
+- **`Comment.comment_id` returns `str`, not `int`.** DOCX Studio uses
   non-numeric entity ids (`"c-42"`), so the upstream `int` contract
-  can't be honored. Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+  can't be honored. Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
 
 - **`Section` dimension setters and `ParagraphFormat.line_spacing_rule
   = None` warn-and-preserve on a clear** rather than raising (upstream
-  accepts `None` to clear, but SuperDoc's merging mutation ops have no
+  accepts `None` to clear, but DOCX Studio's merging mutation ops have no
   single-attribute clear). They emit a `Pending…ClearWarning` and leave
   the value intact instead of destructively clearing the whole block.
-  Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+  Tracked in `DOCX_STUDIO_LIMITATIONS.md`.
 
 ### If you need a deviation
 
@@ -699,13 +754,13 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   (a `SessionError`) carrying `http_status` and an optional
   `retry_after_seconds` parsed from the server's `Retry-After` header.
   Agent code can catch this typed error to back off at the agent level
-  vs. treating it as a script bug. The legacy `transport="direct"`
-  (embedded Superdoc CLI + y-websocket from Python) was removed in
-  0.5.0; agent pods no longer embed Superdoc.
+  vs. treating it as a script bug. The former `transport="direct"`
+  (embedded DOCX Studio CLI + y-websocket from Python) was removed in
+  0.5.0; agent pods no longer embed DOCX Studio.
 - **Transparent batching (0.7.0+):** Create* commands
   (`CreateParagraph`, `CreateHeading`, `CreateTable`, `CreateImage`)
   ALWAYS pre-mint a client-side UUID (`client_node_id`) and defer
-  through the buffer. The applier resolves UUIDs to real SuperDoc
+  through the buffer. The applier resolves UUIDs to real DOCX Studio
   ids via per-batch `clientIdMap` on flush, and the buffer rewrites
   each proxy's `_node_id` in-place. Net result: 30 `add_paragraph`
   calls = 1 HTTP request, with no explicit `batch()` context manager

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/DOCX_EXEC_LAB.md

@@ -1,7 +1,7 @@
 # DocX Execution Lab
 
 `scripts/docx_exec_lab.py` is a headless runner for quickly testing
-`athena-python-docx` snippets against Athena SuperDocument assets. It
+`athena-python-docx` snippets against Athena Word document assets. It
 shortens the debug loop by running local SDK code directly against a
 chosen DOCX Studio API, capturing stdout/stderr/errors/timings, and
 optionally exporting the result to `.docx` for assertions.
@@ -85,10 +85,10 @@ uv run python scripts/docx_exec_lab.py \
   --export-docx
 ```
 
-## Local UI With SuperDoc Embed
+## Local UI With DOCX Editor Embed
 
 The lab also includes a local-only HTML UI that wraps the same headless
-runner and iframes Olympus's existing SuperDoc embed route.
+runner and iframes Olympus's existing DOCX editor embed route.
 
 ```bash
 cd docx-studio/python-sdk
@@ -107,7 +107,7 @@ Defaults:
 The UI accepts an `asset_id`, Python code, and optional assertions. The
 right pane can mint an editable embed token through staging Agora and
 iframe the returned `https://staging-app.athenaintel.com/embed/{token}`
-URL, so changes render in the real Olympus/SuperDoc viewer.
+URL, so changes render in the real Olympus DOCX editor viewer.
 
 If the staging Agora URL differs, pass:
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.20.0
-Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
+Version: 0.21.1
+Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>
 License-Expression: MIT
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
+Requires-Dist: athena-references>=0.1.0
 Requires-Dist: requests>=2.28
 Requires-Dist: urllib3>=1.26.6
 Provides-Extra: dev
@@ -20,14 +21,11 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: python-docx>=1.1; extra == 'dev'
 Requires-Dist: responses>=0.24; extra == 'dev'
 Requires-Dist: ruff>=0.3; extra == 'dev'
-Provides-Extra: fidelity
-Requires-Dist: httpx>=0.27; extra == 'fidelity'
-Requires-Dist: superdoc-sdk>=1.8.0; extra == 'fidelity'
 Description-Content-Type: text/markdown
 
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -35,7 +33,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -74,15 +72,14 @@ headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
 Python snippet with this checkout of `athena-python-docx`, captures
 stdout/stderr/errors/timings, and can export the resulting `.docx` for
 text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
-an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/README.md

@@ -1,6 +1,6 @@
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -8,7 +8,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -47,15 +47,14 @@ headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
 Python snippet with this checkout of `athena-python-docx`, captures
 stdout/stderr/errors/timings, and can export the resulting `.docx` for
 text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
-an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/docx/__init__.py

@@ -1,12 +1,12 @@
 """athena-python-docx — drop-in replacement for python-docx.
 
-Calls translate into Superdoc SDK operations against a Keryx Y.Doc.
+Calls translate into DOCX Studio SDK operations against a Keryx Y.Doc.
 See CLAUDE.md for the API parity contract.
 """
 
 from __future__ import annotations
 
-__version__ = "0.20.0"
+__version__ = "0.21.1"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.20.0 → athena_python_docx-0.21.1}/docx/_buffer.py

@@ -8,7 +8,7 @@ ships as one HTTP request instead of N.
 Create* commands are deferred because the SDK pre-mints a client-side
 UUID for every new node (see ``Document._mint_client_node_id``). The
 proxy returned to the caller is stamped with that UUID; the applier
-resolves UUIDs to real SuperDoc ids via ``clientIdMap`` and echoes the
+resolves UUIDs to real DOCX Studio ids via ``clientIdMap`` and echoes the
 mapping back, at which point the buffer rewrites each proxy's
 ``_node_id``. This makes batching invisible at the call site — user
 code looks like python-docx, runs at python-docx-batched speed.
@@ -49,7 +49,7 @@ def _apply_proxy_id_rewrites(
     proxy_id_refs: "dict[str, list[tuple[object, str]]]",
 ) -> None:
     """Walk ``results`` and rewrite registered proxy ids from client UUIDs
-    to the real SuperDoc ids the applier echoed back.
+    to the real DOCX Studio ids the applier echoed back.
 
     Shared by the success path in :meth:`CommandBuffer.flush` /
     :meth:`_eager_flush_with` AND by the **partial-failure recovery
@@ -287,7 +287,7 @@ class CommandBuffer:
 
     Create* commands defer because the SDK pre-mints a client-side UUID
     (``client_node_id`` / ``client_entity_id``); the applier translates
-    the UUID to a real SuperDoc id in a per-batch ``clientIdMap`` and
+    the UUID to a real DOCX Studio id in a per-batch ``clientIdMap`` and
     echoes the mapping back so the SDK can rewrite each proxy's
     ``_node_id`` on flush.
     """
@@ -385,7 +385,7 @@ class CommandBuffer:
     def set_user(self, name: str | None, email: str | None = None) -> None:
         """Set the batch-level user identity.
 
-        Sent on every commands request envelope. SuperDoc honors the
+        Sent on every commands request envelope. DOCX Studio honors the
         identity at session-open time only — subsequent batches against
         a pooled session ignore the value, but the payload is still
         included so a fresh session picks it up.
@@ -415,7 +415,7 @@ class CommandBuffer:
         ``client_entity_id`` — appends to the queue, resets the idle
         timer, and returns ``None``. Caller MUST NOT rely on the return
         value of a buffered mutation. For deferred Creates, the
-        applier resolves the client UUID to a real SuperDoc id via
+        applier resolves the client UUID to a real DOCX Studio id via
         ``clientIdMap`` on flush and the buffer rewrites each registered
         proxy's ``_node_id`` in-place.
         """