@heylemon/lemonade 0.0.3 → 0.0.5

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.3",
-  "commit": "8e50eaf2ca7f01fbb0397deb3de3cb00f2708c6a",
-  "builtAt": "2026-02-20T05:09:41.173Z"
+  "version": "0.0.5",
+  "commit": "e4c8970d613551e3b0086ba6e128b5624c5f2155",
+  "builtAt": "2026-02-20T05:39:04.795Z"
 }

package/dist/canvas-host/a2ui/.bundle.hash

@@ -1 +1 @@
-5ec7ab3a52d725f743100ac38ce0d8c9672f04988280eeecd179252ba58b11dd
+0084b5bec47a901a88b379363f5f31530feeb541ab85d15e5f944c012ebbef96

package/dist/slack/monitor/allow-list.js

@@ -21,6 +21,7 @@ export function resolveSlackAllowListMatch(params) {
     }
     const id = params.id?.toLowerCase();
     const name = params.name?.toLowerCase();
+    const email = params.email?.toLowerCase();
     const slug = normalizeSlackSlug(name);
     const candidates = [
         { value: id, source: "id" },
@@ -29,6 +30,7 @@ export function resolveSlackAllowListMatch(params) {
         { value: name, source: "name" },
         { value: name ? `slack:${name}` : undefined, source: "prefixed-name" },
         { value: slug, source: "slug" },
+        { value: email, source: "email" },
     ];
     for (const candidate of candidates) {
         if (!candidate.value)

package/dist/slack/monitor/context.js

@@ -98,7 +98,8 @@ export function createSlackMonitorContext(params) {
             });
             const profile = info.user?.profile;
             const name = profile?.display_name || profile?.real_name || info.user?.name || undefined;
-            const entry = { name };
+            const email = profile?.email || undefined;
+            const entry = { name, email };
             userCache.set(userId, entry);
             return entry;
         }

package/dist/slack/monitor/message-handler/prepare.js

@@ -96,24 +96,26 @@ export async function prepareSlackMessage(params) {
             return null;
         }
         if (ctx.dmPolicy !== "open") {
+            const dmSender = await ctx.resolveUserName(directUserId);
+            const dmSenderEmail = dmSender?.email ?? undefined;
             const allowMatch = resolveSlackAllowListMatch({
                 allowList: allowFromLower,
                 id: directUserId,
+                email: dmSenderEmail,
             });
             const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
             if (!allowMatch.allowed) {
-                // Check if sender is an approved guest (responses only, no tools)
                 const guestMatch = resolveSlackAllowListMatch({
                     allowList: guestFromLower,
                     id: directUserId,
+                    email: dmSenderEmail,
                 });
                 if (guestMatch.allowed) {
                     isGuestSender = true;
                     logVerbose(`slack: guest sender ${directUserId} allowed (responses only, no tools)`);
                 }
                 else if (ctx.dmPolicy === "pairing" || ctx.dmPolicy === "allowlist") {
-                    const sender = await ctx.resolveUserName(directUserId);
-                    const senderName = sender?.name ?? undefined;
+                    const senderName = dmSender?.name ?? undefined;
                     const { created } = await upsertChannelPairingRequest({
                         channel: "slack",
                         id: directUserId,
@@ -226,6 +228,7 @@ export async function prepareSlackMessage(params) {
         allowList: allowFromLower,
         id: senderId,
         name: senderName,
+        email: sender?.email,
     }).allowed;
     const channelUsersAllowlistConfigured = isRoom && Array.isArray(channelConfig?.users) && channelConfig.users.length > 0;
     const channelCommandAuthorized = isRoom && channelUsersAllowlistConfigured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heylemon/lemonade",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "AI gateway CLI for Lemon - local AI assistant with integrations",
   "publishConfig": {
     "access": "restricted"

package/skills/docx/SKILL.md

@@ -1,30 +1,11 @@
 ---
 name: docx
-description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of \"Word doc\", \"word document\", \".docx\", or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a \"report\", \"memo\", \"letter\", \"template\", or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
 # DOCX creation, editing, and analysis
 
-## IMPORTANT: Save to Desktop
-
-**Always save created `.docx` files to `~/Desktop/`** (e.g. `~/Desktop/document.docx`). Never save to the agent workspace or hidden directories — the user needs easy access to the file.
-
-## CRITICAL: Integration Priority
-
-### 1. `lemon-docs` CLI (For Google Docs)
-If user wants a Google Doc (shareable, collaborative), use `lemon-docs`:
-- `lemon-docs create "Title"` - Create a new Google Doc
-- `lemon-docs read <id>` - Read a document
-
-### 2. Local DOCX (For Files)
-If user wants a local `.docx` file, or `lemon-docs` is not connected, use the local creation methods below.
-
-### 3. Browser (LAST RESORT)
-Only if `lemon-docs` CLI fails AND user explicitly requests Google Docs in browser.
-
----
-
 ## Overview
 
 A .docx file is a ZIP archive containing XML files.
@@ -67,14 +48,14 @@ pdftoppm -jpeg -r 150 document.pdf page
 To produce a clean document with all tracked changes accepted (requires LibreOffice):
 
 ```bash
-python scripts/accept_changes.py input.docx ~/Desktop/output.docx
+python scripts/accept_changes.py input.docx output.docx
 ```
 
 ---
 
 ## Creating New Documents
 
-Generate .docx files with JavaScript. Install: `npm install -g docx`
+Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
 
 ### Setup
 ```javascript
@@ -87,6 +68,12 @@ const doc = new Document({ sections: [{ children: [/* content */] }] });
 Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
 ```
 
+### Validation
+After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
+```bash
+python scripts/office/validate.py doc.docx
+```
+
 ### Page Size
 
 ```javascript
@@ -113,6 +100,16 @@ sections: [{
 | US Letter | 12,240 | 15,840 | 9,360 |
 | A4 (default) | 11,906 | 16,838 | 9,026 |
 
+**Landscape orientation:** docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
+```javascript
+size: {
+  width: 12240,   // Pass SHORT edge as width
+  height: 15840,  // Pass LONG edge as height
+  orientation: PageOrientation.LANDSCAPE  // docx-js swaps them in the XML
+},
+// Content width = 15840 - left margin - right margin (uses the long edge)
+```
+
 ### Styles (Override Built-in Headings)
 
 Use Arial as the default font (universally supported). Keep titles black for readability.
@@ -184,8 +181,8 @@ const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
 const borders = { top: border, bottom: border, left: border, right: border };
 
 new Table({
-  width: { size: 100, type: WidthType.PERCENTAGE }, // Always set table width
-  columnWidths: [4680, 4680], // Set at table level (DXA: 1440 = 1 inch)
+  width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
+  columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
   rows: [
     new TableRow({
       children: [
@@ -204,13 +201,9 @@ new Table({
 
 **Table width calculation:**
 
-Use `WidthType.PERCENTAGE` for simplicity, or `WidthType.DXA` for precise control:
+Always use `WidthType.DXA` — `WidthType.PERCENTAGE` breaks in Google Docs.
 
 ```javascript
-// Option 1: Percentage (recommended - automatically fits content area)
-width: { size: 100, type: WidthType.PERCENTAGE }
-
-// Option 2: DXA (precise control)
 // Table width = sum of columnWidths = content width
 // US Letter with 1" margins: 12240 - 2880 = 9360 DXA
 width: { size: 9360, type: WidthType.DXA },
@@ -218,6 +211,7 @@ columnWidths: [7000, 2360]  // Must sum to table width
 ```
 
 **Width rules:**
+- **Always use `WidthType.DXA`** — never `WidthType.PERCENTAGE` (incompatible with Google Docs)
 - Table width must equal the sum of `columnWidths`
 - Cell `width` must match corresponding `columnWidth`
 - Cell `margins` are internal padding - they reduce content area, not add to cell width
@@ -276,11 +270,12 @@ sections: [{
 ### Critical Rules for docx-js
 
 - **Set page size explicitly** - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
+- **Landscape: pass portrait dimensions** - docx-js swaps width/height internally; pass short edge as `width`, long edge as `height`, and set `orientation: PageOrientation.LANDSCAPE`
 - **Never use `\n`** - use separate Paragraph elements
 - **Never use unicode bullets** - use `LevelFormat.BULLET` with numbering config
 - **PageBreak must be in Paragraph** - standalone creates invalid XML
 - **ImageRun requires `type`** - always specify png/jpg/etc
-- **Always set table `width`** - use `{ size: 100, type: WidthType.PERCENTAGE }` for full width
+- **Always set table `width` with DXA** - never use `WidthType.PERCENTAGE` (breaks in Google Docs)
 - **Tables need dual widths** - `columnWidths` array AND cell `width`, both must match
 - **Table width = sum of columnWidths** - for DXA, ensure they add up exactly
 - **Always add cell margins** - use `margins: { top: 80, bottom: 80, left: 120, right: 120 }` for readable padding

package/skills/docx/scripts/accept_changes.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Accept all tracked changes in a DOCX file using LibreOffice.
 
 Requires LibreOffice (soffice) to be installed.
@@ -14,7 +13,6 @@ from office.soffice import get_soffice_env
 
 logger = logging.getLogger(__name__)
 
-# LibreOffice profile directory for macro storage
 LIBREOFFICE_PROFILE = "/tmp/libreoffice_docx_profile"
 MACRO_DIR = f"{LIBREOFFICE_PROFILE}/user/basic/Standard"
 
@@ -39,15 +37,6 @@ def accept_changes(
     input_file: str,
     output_file: str,
 ) -> tuple[None, str]:
-    """Accept all tracked changes in a DOCX file and save to output file.
-
-    Args:
-        input_file: Path to input DOCX file with tracked changes
-        output_file: Path to output DOCX file (will be created/overwritten)
-
-    Returns:
-        (None, message) - message indicates success or failure
-    """
     input_path = Path(input_file)
     output_path = Path(output_file)
 
@@ -57,18 +46,15 @@ def accept_changes(
     if not input_path.suffix.lower() == ".docx":
         return None, f"Error: Input file is not a DOCX file: {input_file}"
 
-    # Copy input file to output file location
     try:
         output_path.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(input_path, output_path)
     except Exception as e:
         return None, f"Error: Failed to copy input file to output location: {e}"
 
-    # Setup LibreOffice macro
     if not _setup_libreoffice_macro():
         return None, "Error: Failed to setup LibreOffice macro"
 
-    # Run LibreOffice with macro to accept changes
     cmd = [
         "soffice",
         "--headless",
@@ -88,7 +74,6 @@ def accept_changes(
             env=get_soffice_env(),
         )
     except subprocess.TimeoutExpired:
-        # Timeout is expected - LibreOffice may hang after completing
         return (
             None,
             f"Successfully accepted all tracked changes: {input_file} -> {output_file}",
@@ -104,14 +89,12 @@ def accept_changes(
 
 
 def _setup_libreoffice_macro() -> bool:
-    """Setup LibreOffice macro for accepting tracked changes."""
     macro_dir = Path(MACRO_DIR)
     macro_file = macro_dir / "Module1.xba"
 
     if macro_file.exists() and "AcceptAllTrackedChanges" in macro_file.read_text():
         return True
 
-    # Initialize LibreOffice if needed (use custom profile)
     if not macro_dir.exists():
         subprocess.run(
             [

package/skills/docx/scripts/comment.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Add comments to DOCX documents.
 
 Usage:
@@ -32,7 +31,6 @@ NS = {
     "w16cex": "http://schemas.microsoft.com/office/word/2018/wordml/cex",
 }
 
-# XML template for comment content in comments.xml
 COMMENT_XML = """\
 <w:comment w:id="{id}" w:author="{author}" w:date="{date}" w:initials="{initials}">
   <w:p w14:paraId="{para_id}" w14:textId="77777777">
@@ -51,7 +49,6 @@ COMMENT_XML = """\
   </w:p>
 </w:comment>"""
 
-# Output templates for marker placement instructions
 COMMENT_MARKER_TEMPLATE = """
 Add to document.xml (markers must be direct children of w:p, never inside w:r):
   <w:commentRangeStart w:id="{cid}"/>
@@ -69,42 +66,36 @@ Nest markers inside parent {pid}'s markers (markers must be direct children of w
 
 
 def _generate_hex_id() -> str:
-    """Random 8-char hex ID (satisfies paraId < 0x80000000, durableId < 0x7FFFFFFF)."""
     return f"{random.randint(0, 0x7FFFFFFE):08X}"
 
 
-# Smart quotes to re-encode after DOM serialization (DOM decodes entities to Unicode)
 SMART_QUOTE_ENTITIES = {
-    "\u201c": "&#x201C;",  # Left double quote
-    "\u201d": "&#x201D;",  # Right double quote
-    "\u2018": "&#x2018;",  # Left single quote
-    "\u2019": "&#x2019;",  # Right single quote
+    "\u201c": "&#x201C;",  
+    "\u201d": "&#x201D;",  
+    "\u2018": "&#x2018;",  
+    "\u2019": "&#x2019;",  
 }
 
 
 def _encode_smart_quotes(text: str) -> str:
-    """Re-encode smart quotes as XML entities after DOM serialization."""
     for char, entity in SMART_QUOTE_ENTITIES.items():
         text = text.replace(char, entity)
     return text
 
 
 def _append_xml(xml_path: Path, root_tag: str, content: str) -> None:
-    """Append content as child of root element."""
     dom = defusedxml.minidom.parseString(xml_path.read_text(encoding="utf-8"))
     root = dom.getElementsByTagName(root_tag)[0]
     ns_attrs = " ".join(f'xmlns:{k}="{v}"' for k, v in NS.items())
     wrapper_dom = defusedxml.minidom.parseString(f"<root {ns_attrs}>{content}</root>")
-    for child in wrapper_dom.documentElement.childNodes:  # type: ignore
+    for child in wrapper_dom.documentElement.childNodes:  
         if child.nodeType == child.ELEMENT_NODE:
             root.appendChild(dom.importNode(child, True))
-    # Re-encode smart quotes that DOM decoded to Unicode
     output = _encode_smart_quotes(dom.toxml(encoding="UTF-8").decode("utf-8"))
     xml_path.write_text(output, encoding="utf-8")
 
 
 def _find_para_id(comments_path: Path, comment_id: int) -> str | None:
-    """Find para_id for a comment ID."""
     dom = defusedxml.minidom.parseString(comments_path.read_text(encoding="utf-8"))
     for c in dom.getElementsByTagName("w:comment"):
         if c.getAttribute("w:id") == str(comment_id):
@@ -115,7 +106,6 @@ def _find_para_id(comments_path: Path, comment_id: int) -> str | None:
 
 
 def _get_next_rid(rels_path: Path) -> int:
-    """Get the next available rId number from document.xml.rels."""
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
     max_rid = 0
     for rel in dom.getElementsByTagName("Relationship"):
@@ -129,7 +119,6 @@ def _get_next_rid(rels_path: Path) -> int:
 
 
 def _has_relationship(rels_path: Path, target: str) -> bool:
-    """Check if a relationship with given target exists."""
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
     for rel in dom.getElementsByTagName("Relationship"):
         if rel.getAttribute("Target") == target:
@@ -138,7 +127,6 @@ def _has_relationship(rels_path: Path, target: str) -> bool:
 
 
 def _has_content_type(ct_path: Path, part_name: str) -> bool:
-    """Check if a content type override with given part name exists."""
     dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
     for override in dom.getElementsByTagName("Override"):
         if override.getAttribute("PartName") == part_name:
@@ -147,19 +135,17 @@ def _has_content_type(ct_path: Path, part_name: str) -> bool:
 
 
 def _ensure_comment_relationships(unpacked_dir: Path) -> None:
-    """Ensure word/_rels/document.xml.rels has comment relationships."""
     rels_path = unpacked_dir / "word" / "_rels" / "document.xml.rels"
     if not rels_path.exists():
         return
 
     if _has_relationship(rels_path, "comments.xml"):
-        return  # Already has comment relationships
+        return  
 
     dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
     root = dom.documentElement
     next_rid = _get_next_rid(rels_path)
 
-    # Add relationship elements
     rels = [
         (
             "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments",
@@ -184,25 +170,23 @@ def _ensure_comment_relationships(unpacked_dir: Path) -> None:
         rel.setAttribute("Id", f"rId{next_rid}")
         rel.setAttribute("Type", rel_type)
         rel.setAttribute("Target", target)
-        root.appendChild(rel)  # type: ignore
+        root.appendChild(rel)  
         next_rid += 1
 
     rels_path.write_bytes(dom.toxml(encoding="UTF-8"))
 
 
 def _ensure_comment_content_types(unpacked_dir: Path) -> None:
-    """Ensure [Content_Types].xml has comment content types."""
     ct_path = unpacked_dir / "[Content_Types].xml"
     if not ct_path.exists():
         return
 
     if _has_content_type(ct_path, "/word/comments.xml"):
-        return  # Already has comment content types
+        return  
 
     dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
     root = dom.documentElement
 
-    # Add Override elements
     overrides = [
         (
             "/word/comments.xml",
@@ -226,7 +210,7 @@ def _ensure_comment_content_types(unpacked_dir: Path) -> None:
         override = dom.createElement("Override")
         override.setAttribute("PartName", part_name)
         override.setAttribute("ContentType", content_type)
-        root.appendChild(override)  # type: ignore
+        root.appendChild(override)  
 
     ct_path.write_bytes(dom.toxml(encoding="UTF-8"))
 
@@ -239,14 +223,6 @@ def add_comment(
     initials: str = "C",
     parent_id: int | None = None,
 ) -> tuple[str, str]:
-    """Add comment to unpacked DOCX.
-
-    Args:
-        text: Comment text, pre-escaped for XML (e.g., &amp; &#x2019;).
-
-    Returns:
-        (para_id, message) tuple.
-    """
     word = Path(unpacked_dir) / "word"
     if not word.exists():
         return "", f"Error: {word} not found"
@@ -254,12 +230,10 @@ def add_comment(
     para_id, durable_id = _generate_hex_id(), _generate_hex_id()
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
-    # comments.xml
     comments = word / "comments.xml"
     first_comment = not comments.exists()
     if first_comment:
         shutil.copy(TEMPLATE_DIR / "comments.xml", comments)
-        # Add relationships and content types for comment files
         _ensure_comment_relationships(Path(unpacked_dir))
         _ensure_comment_content_types(Path(unpacked_dir))
     _append_xml(
@@ -271,11 +245,10 @@ def add_comment(
             date=ts,
             initials=initials,
             para_id=para_id,
-            text=text,  # Model provides pre-escaped XML content
+            text=text,  
         ),
     )
 
-    # commentsExtended.xml
     ext = word / "commentsExtended.xml"
     if not ext.exists():
         shutil.copy(TEMPLATE_DIR / "commentsExtended.xml", ext)
@@ -295,7 +268,6 @@ def add_comment(
             f'<w15:commentEx w15:paraId="{para_id}" w15:done="0"/>',
         )
 
-    # commentsIds.xml
     ids = word / "commentsIds.xml"
     if not ids.exists():
         shutil.copy(TEMPLATE_DIR / "commentsIds.xml", ids)
@@ -305,7 +277,6 @@ def add_comment(
         f'<w16cid:commentId w16cid:paraId="{para_id}" w16cid:durableId="{durable_id}"/>',
     )
 
-    # commentsExtensible.xml
     extensible = word / "commentsExtensible.xml"
     if not extensible.exists():
         shutil.copy(TEMPLATE_DIR / "commentsExtensible.xml", extensible)

package/skills/docx/scripts/office/helpers/merge_runs.py

@@ -14,14 +14,6 @@ import defusedxml.minidom
 
 
 def merge_runs(input_dir: str) -> tuple[int, str]:
-    """Merge adjacent runs in document.xml.
-
-    Args:
-        input_dir: Path to unpacked DOCX directory
-
-    Returns:
-        (merge_count, message)
-    """
     doc_xml = Path(input_dir) / "word" / "document.xml"
 
     if not doc_xml.exists():
@@ -31,14 +23,11 @@ def merge_runs(input_dir: str) -> tuple[int, str]:
         dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
         root = dom.documentElement
 
-        # Clean up elements that block merging
         _remove_elements(root, "proofErr")
         _strip_run_rsid_attrs(root)
 
-        # Find all containers that have runs
         containers = {run.parentNode for run in _find_elements(root, "r")}
 
-        # Merge runs in each container
         merge_count = 0
         for container in containers:
             merge_count += _merge_runs_in(container)
@@ -50,11 +39,9 @@ def merge_runs(input_dir: str) -> tuple[int, str]:
         return 0, f"Error: {e}"
 
 
-# --- Element helpers ---
 
 
 def _find_elements(root, tag: str) -> list:
-    """Find all elements matching tag name (with or without namespace)."""
     results = []
 
     def traverse(node):
@@ -70,7 +57,6 @@ def _find_elements(root, tag: str) -> list:
 
 
 def _get_child(parent, tag: str):
-    """Get first child element matching tag name."""
     for child in parent.childNodes:
         if child.nodeType == child.ELEMENT_NODE:
             name = child.localName or child.tagName
@@ -80,7 +66,6 @@ def _get_child(parent, tag: str):
 
 
 def _get_children(parent, tag: str) -> list:
-    """Get all direct child elements matching tag name."""
     results = []
     for child in parent.childNodes:
         if child.nodeType == child.ELEMENT_NODE:
@@ -91,7 +76,6 @@ def _get_children(parent, tag: str) -> list:
 
 
 def _is_adjacent(elem1, elem2) -> bool:
-    """Check if two elements are adjacent (only whitespace between them)."""
     node = elem1.nextSibling
     while node:
         if node == elem2:
@@ -104,34 +88,28 @@ def _is_adjacent(elem1, elem2) -> bool:
     return False
 
 
-# --- Cleanup functions ---
 
 
 def _remove_elements(root, tag: str):
-    """Remove all elements matching tag name."""
     for elem in _find_elements(root, tag):
         if elem.parentNode:
             elem.parentNode.removeChild(elem)
 
 
 def _strip_run_rsid_attrs(root):
-    """Remove rsid attributes from all run elements."""
     for run in _find_elements(root, "r"):
         for attr in list(run.attributes.values()):
             if "rsid" in attr.name.lower():
                 run.removeAttribute(attr.name)
 
 
-# --- Merge functions ---
 
 
 def _merge_runs_in(container) -> int:
-    """Merge adjacent runs with identical formatting in a container element."""
     merge_count = 0
     run = _first_child_run(container)
 
     while run:
-        # Absorb adjacent runs with same formatting
         while True:
             next_elem = _next_element_sibling(run)
             if next_elem and _is_run(next_elem) and _can_merge(run, next_elem):
@@ -148,7 +126,6 @@ def _merge_runs_in(container) -> int:
 
 
 def _first_child_run(container):
-    """Get the first run child of a container."""
     for child in container.childNodes:
         if child.nodeType == child.ELEMENT_NODE and _is_run(child):
             return child
@@ -156,7 +133,6 @@ def _first_child_run(container):
 
 
 def _next_element_sibling(node):
-    """Get the next element sibling, skipping text/whitespace nodes."""
     sibling = node.nextSibling
     while sibling:
         if sibling.nodeType == sibling.ELEMENT_NODE:
@@ -166,25 +142,21 @@ def _next_element_sibling(node):
 
 
 def _next_sibling_run(node):
-    """Get the next sibling that is a run element."""
     sibling = node.nextSibling
     while sibling:
         if sibling.nodeType == sibling.ELEMENT_NODE:
             if _is_run(sibling):
                 return sibling
-            # Skip non-run elements (bookmarks, etc.) but keep looking
         sibling = sibling.nextSibling
     return None
 
 
 def _is_run(node) -> bool:
-    """Check if node is a run element."""
     name = node.localName or node.tagName
     return name == "r" or name.endswith(":r")
 
 
 def _can_merge(run1, run2) -> bool:
-    """Check if two runs have identical formatting."""
     rpr1 = _get_child(run1, "rPr")
     rpr2 = _get_child(run2, "rPr")
 
@@ -192,11 +164,10 @@ def _can_merge(run1, run2) -> bool:
         return False
     if rpr1 is None:
         return True
-    return rpr1.toxml() == rpr2.toxml()  # type: ignore
+    return rpr1.toxml() == rpr2.toxml()  
 
 
 def _merge_run_content(target, source):
-    """Move content from source run to target run (excluding rPr)."""
     for child in list(source.childNodes):
         if child.nodeType == child.ELEMENT_NODE:
             name = child.localName or child.tagName
@@ -205,10 +176,8 @@ def _merge_run_content(target, source):
 
 
 def _consolidate_text(run):
-    """Merge adjacent <w:t> elements within a run."""
     t_elements = _get_children(run, "t")
 
-    # Work backwards to safely remove elements
     for i in range(len(t_elements) - 1, 0, -1):
         curr, prev = t_elements[i], t_elements[i - 1]
 
@@ -222,7 +191,6 @@ def _consolidate_text(run):
             else:
                 prev.appendChild(run.ownerDocument.createTextNode(merged))
 
-            # Preserve whitespace if needed
             if merged.startswith(" ") or merged.endswith(" "):
                 prev.setAttribute("xml:space", "preserve")
             elif prev.hasAttribute("xml:space"):