@clawpify/skills 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/clawpify/SKILL.md CHANGED
@@ -1,134 +1,37 @@
1
1
  ---
2
2
  name: clawpify
3
3
  description: Query and manage Shopify stores via GraphQL Admin API. Use for products, orders, customers, inventory, discounts, and all Shopify data operations.
4
- dependencies:
5
- - Tool: shopify_graphql (from MCP server or custom function)
6
4
  ---
7
5
 
8
6
  # Shopify GraphQL Admin API
9
7
 
10
- A comprehensive skill for interacting with Shopify's GraphQL Admin API. This skill enables Claude to query and manage all aspects of Shopify store data.
11
-
12
- ## When to Use This Skill
13
-
14
- Use this skill when the user asks about:
15
- - Products (list, search, create, update, delete)
16
- - Orders (view, cancel, fulfill)
17
- - Customers (list, create, update)
18
- - Inventory (check levels, adjust quantities)
19
- - Discounts (create codes, manage promotions)
20
- - Any other Shopify store operations
21
-
22
- ## Critical Operations Requiring Permission
23
-
24
- IMPORTANT: Before executing any of the following operations, you MUST ask for explicit user permission:
25
-
26
- - Refunds: Create refunds (permanent financial transactions)
27
- - Order Cancellations: Cancel orders (may trigger refunds)
28
- - Gift Card Deactivation: Permanently disable gift cards
29
- - Inventory Adjustments: Modify stock levels
30
- - Product Deletions: Permanently remove products
31
- - Discount Activations: Change pricing for customers
32
-
33
- Always show what will be changed and wait for user confirmation.
34
-
35
8
  ## How to Use
36
9
 
37
- 1. Use the `shopify_graphql` tool to execute queries
38
- 2. Check for `errors` (GraphQL issues) and `userErrors` (validation issues)
39
- 3. Use pagination with `first`/`after` for large result sets
10
+ 1. Use `load_skill_reference` to load the relevant reference FIRST
11
+ 2. Use `shopify_graphql` to execute queries based on the loaded reference
12
+ 3. Check for `errors` and `userErrors` in responses
40
13
  4. Format all IDs as: `gid://shopify/Resource/123`
41
14
 
42
- ## Available References
43
-
44
- For detailed patterns and examples, refer to the reference documents:
45
- - products.md - Products and variants management
46
- - orders.md - Order operations
47
- - customers.md - Customer management
48
- - inventory.md - Inventory and locations
49
- - discounts.md - Discount codes and promotions
50
- - collections.md - Product collections
51
- - fulfillments.md - Order fulfillment and shipping
52
- - refunds.md - Process refunds
53
- - draft-orders.md - Draft order creation
54
- - gift-cards.md - Gift card management
55
- - webhooks.md - Event subscriptions
56
- - locations.md - Store locations
57
- - marketing.md - Marketing activities
58
- - markets.md - Multi-market setup
59
- - menus.md - Navigation menus
60
- - metafields.md - Custom data fields
61
- - pages.md - Store pages
62
- - blogs.md - Blog management
63
- - files.md - File uploads
64
- - shipping.md - Shipping configuration
65
- - shop.md - Store information
66
- - subscriptions.md - Subscription management
67
- - translations.md - Content translations
68
- - segments.md - Customer segments
69
- - bulk-operations.md - Bulk data operations
70
-
71
- ## Quick Examples
72
-
73
- ### List Recent Orders
74
- ```graphql
75
- query {
76
- orders(first: 10, sortKey: CREATED_AT, reverse: true) {
77
- nodes {
78
- id
79
- name
80
- totalPriceSet {
81
- shopMoney { amount currencyCode }
82
- }
83
- customer { displayName }
84
- }
85
- }
86
- }
87
- ```
88
-
89
- ### Search Products
90
- ```graphql
91
- query {
92
- products(first: 10, query: "title:*shirt* AND status:ACTIVE") {
93
- nodes {
94
- id
95
- title
96
- status
97
- }
98
- }
99
- }
100
- ```
15
+ ## Critical Operations Requiring Permission
101
16
 
102
- ### Check Inventory
103
- ```graphql
104
- query GetInventory($id: ID!) {
105
- inventoryItem(id: $id) {
106
- id
107
- inventoryLevels(first: 5) {
108
- nodes {
109
- quantities(names: ["available"]) {
110
- name
111
- quantity
112
- }
113
- location { name }
114
- }
115
- }
116
- }
117
- }
118
- ```
17
+ IMPORTANT: Before executing any of the following, you MUST ask for explicit user permission:
119
18
 
120
- ## Error Handling
19
+ - Refunds, order cancellations, gift card deactivation
20
+ - Inventory adjustments, product deletions, discount activations
121
21
 
122
- Always check responses:
123
- - `errors` array = GraphQL syntax issues
124
- - `userErrors` in mutations = validation problems
22
+ Always show what will be changed and wait for confirmation.
125
23
 
126
- ## Best Practices
24
+ ## Available References
127
25
 
128
- 1. Request only needed fields to optimize response size
129
- 2. Use pagination for lists that may grow
130
- 3. Check userErrors in all mutation responses
131
- 4. Ask permission before dangerous operations
132
- 5. Format results clearly for the user
133
- 6. Use bulk operations for large data exports/imports
134
- 7. Handle rate limits with exponential backoff
26
+ Load the reference for your domain using `load_skill_reference` before writing queries:
27
+
28
+ **Store**: [shop](reference/shop.md) | [locations](reference/locations.md) | [markets](reference/markets.md)
29
+ **Catalog**: [products](reference/products.md) | [collections](reference/collections.md) | [inventory](reference/inventory.md)
30
+ **Sales**: [orders](reference/orders.md) | [draft-orders](reference/draft-orders.md) | [fulfillments](reference/fulfillments.md) | [refunds](reference/refunds.md)
31
+ **Customers**: [customers](reference/customers.md) | [segments](reference/segments.md) | [gift-cards](reference/gift-cards.md)
32
+ **Pricing**: [discounts](reference/discounts.md) | [subscriptions](reference/subscriptions.md)
33
+ **Content**: [pages](reference/pages.md) | [blogs](reference/blogs.md) | [menus](reference/menus.md) | [translations](reference/translations.md) | [files](reference/files.md)
34
+ **Custom data**: [metafields](reference/metafields.md)
35
+ **Automation**: [webhooks](reference/webhooks.md) | [bulk-operations](reference/bulk-operations.md)
36
+ **Growth**: [marketing](reference/marketing.md) | [shipping](reference/shipping.md)
37
+ **Documents**: [docx](reference/docx.md) | [pdf](reference/pdf.md) | [pdf-forms](reference/pdf-forms.md) | [pdf-reference](reference/pdf-reference.md) | [pptx](reference/pptx.md) | [pptx-editing](reference/pptx-editing.md) | [pptx-creating](reference/pptx-creating.md) | [xlsx](reference/xlsx.md)
@@ -0,0 +1,471 @@
1
+ # DOCX creation, editing, and analysis
2
+
3
+ ## Overview
4
+
5
+ A .docx file is a ZIP archive containing XML files.
6
+
7
+ ## Quick Reference
8
+
9
+ | Task | Approach |
10
+ |------|----------|
11
+ | Read/analyze content | `pandoc` or unpack for raw XML |
12
+ | Create new document | Use `docx-js` - see Creating New Documents below |
13
+ | Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |
14
+
15
+ ### Converting .doc to .docx
16
+
17
+ Legacy `.doc` files must be converted before editing:
18
+
19
+ ```bash
20
+ python scripts/office/soffice.py --headless --convert-to docx document.doc
21
+ ```
22
+
23
+ ### Reading Content
24
+
25
+ ```bash
26
+ # Text extraction with tracked changes
27
+ pandoc --track-changes=all document.docx -o output.md
28
+
29
+ # Raw XML access
30
+ python scripts/office/unpack.py document.docx unpacked/
31
+ ```
32
+
33
+ ### Converting to Images
34
+
35
+ ```bash
36
+ python scripts/office/soffice.py --headless --convert-to pdf document.docx
37
+ pdftoppm -jpeg -r 150 document.pdf page
38
+ ```
39
+
40
+ ### Accepting Tracked Changes
41
+
42
+ To produce a clean document with all tracked changes accepted (requires LibreOffice):
43
+
44
+ ```bash
45
+ python scripts/accept_changes.py input.docx output.docx
46
+ ```
47
+
48
+
49
+ ## Creating New Documents
50
+
51
+ Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
52
+
53
+ ### Setup
54
+ ```javascript
55
+ const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
56
+ Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
57
+ TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
58
+ VerticalAlign, PageNumber, PageBreak } = require('docx');
59
+
60
+ const doc = new Document({ sections: [{ children: [/* content */] }] });
61
+ Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
62
+ ```
63
+
64
+ ### Validation
65
+ After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
66
+ ```bash
67
+ python scripts/office/validate.py doc.docx
68
+ ```
69
+
70
+ ### Page Size
71
+
72
+ ```javascript
73
+ // CRITICAL: docx-js defaults to A4, not US Letter
74
+ // Always set page size explicitly for consistent results
75
+ sections: [{
76
+ properties: {
77
+ page: {
78
+ size: {
79
+ width: 12240, // 8.5 inches in DXA
80
+ height: 15840 // 11 inches in DXA
81
+ },
82
+ margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
83
+ }
84
+ },
85
+ children: [/* content */]
86
+ }]
87
+ ```
88
+
89
+ **Common page sizes (DXA units, 1440 DXA = 1 inch):**
90
+
91
+ | Paper | Width | Height | Content Width (1" margins) |
92
+ |-------|-------|--------|---------------------------|
93
+ | US Letter | 12,240 | 15,840 | 9,360 |
94
+ | A4 (default) | 11,906 | 16,838 | 9,026 |
95
+
96
+ **Landscape orientation:** docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
97
+ ```javascript
98
+ size: {
99
+ width: 12240, // Pass SHORT edge as width
100
+ height: 15840, // Pass LONG edge as height
101
+ orientation: PageOrientation.LANDSCAPE // docx-js swaps them in the XML
102
+ },
103
+ // Content width = 15840 - left margin - right margin (uses the long edge)
104
+ ```
105
+
106
+ ### Styles (Override Built-in Headings)
107
+
108
+ Use Arial as the default font (universally supported). Keep titles black for readability.
109
+
110
+ ```javascript
111
+ const doc = new Document({
112
+ styles: {
113
+ default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
114
+ paragraphStyles: [
115
+ // IMPORTANT: Use exact IDs to override built-in styles
116
+ { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
117
+ run: { size: 32, bold: true, font: "Arial" },
118
+ paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
119
+ { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
120
+ run: { size: 28, bold: true, font: "Arial" },
121
+ paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
122
+ ]
123
+ },
124
+ sections: [{
125
+ children: [
126
+ new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }),
127
+ ]
128
+ }]
129
+ });
130
+ ```
131
+
132
+ ### Lists (NEVER use unicode bullets)
133
+
134
+ ```javascript
135
+ // ❌ WRONG - never manually insert bullet characters
136
+ new Paragraph({ children: [new TextRun("• Item")] }) // BAD
137
+ new Paragraph({ children: [new TextRun("\u2022 Item")] }) // BAD
138
+
139
+ // ✅ CORRECT - use numbering config with LevelFormat.BULLET
140
+ const doc = new Document({
141
+ numbering: {
142
+ config: [
143
+ { reference: "bullets",
144
+ levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
145
+ style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
146
+ { reference: "numbers",
147
+ levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
148
+ style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
149
+ ]
150
+ },
151
+ sections: [{
152
+ children: [
153
+ new Paragraph({ numbering: { reference: "bullets", level: 0 },
154
+ children: [new TextRun("Bullet item")] }),
155
+ new Paragraph({ numbering: { reference: "numbers", level: 0 },
156
+ children: [new TextRun("Numbered item")] }),
157
+ ]
158
+ }]
159
+ });
160
+
161
+ // ⚠️ Each reference creates INDEPENDENT numbering
162
+ // Same reference = continues (1,2,3 then 4,5,6)
163
+ // Different reference = restarts (1,2,3 then 1,2,3)
164
+ ```
165
+
166
+ ### Tables
167
+
168
+ **CRITICAL: Tables need dual widths** - set both `columnWidths` on the table AND `width` on each cell. Without both, tables render incorrectly on some platforms.
169
+
170
+ ```javascript
171
+ // CRITICAL: Always set table width for consistent rendering
172
+ // CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds
173
+ const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
174
+ const borders = { top: border, bottom: border, left: border, right: border };
175
+
176
+ new Table({
177
+ width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
178
+ columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
179
+ rows: [
180
+ new TableRow({
181
+ children: [
182
+ new TableCell({
183
+ borders,
184
+ width: { size: 4680, type: WidthType.DXA }, // Also set on each cell
185
+ shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLID
186
+ margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)
187
+ children: [new Paragraph({ children: [new TextRun("Cell")] })]
188
+ })
189
+ ]
190
+ })
191
+ ]
192
+ })
193
+ ```
194
+
195
+ **Table width calculation:**
196
+
197
+ Always use `WidthType.DXA` — `WidthType.PERCENTAGE` breaks in Google Docs.
198
+
199
+ ```javascript
200
+ // Table width = sum of columnWidths = content width
201
+ // US Letter with 1" margins: 12240 - 2880 = 9360 DXA
202
+ width: { size: 9360, type: WidthType.DXA },
203
+ columnWidths: [7000, 2360] // Must sum to table width
204
+ ```
205
+
206
+ **Width rules:**
207
+ - **Always use `WidthType.DXA`** — never `WidthType.PERCENTAGE` (incompatible with Google Docs)
208
+ - Table width must equal the sum of `columnWidths`
209
+ - Cell `width` must match corresponding `columnWidth`
210
+ - Cell `margins` are internal padding - they reduce content area, not add to cell width
211
+ - For full-width tables: use content width (page width minus left and right margins)
212
+
213
+ ### Images
214
+
215
+ ```javascript
216
+ // CRITICAL: type parameter is REQUIRED
217
+ new Paragraph({
218
+ children: [new ImageRun({
219
+ type: "png", // Required: png, jpg, jpeg, gif, bmp, svg
220
+ data: fs.readFileSync("image.png"),
221
+ transformation: { width: 200, height: 150 },
222
+ altText: { title: "Title", description: "Desc", name: "Name" } // All three required
223
+ })]
224
+ })
225
+ ```
226
+
227
+ ### Page Breaks
228
+
229
+ ```javascript
230
+ // CRITICAL: PageBreak must be inside a Paragraph
231
+ new Paragraph({ children: [new PageBreak()] })
232
+
233
+ // Or use pageBreakBefore
234
+ new Paragraph({ pageBreakBefore: true, children: [new TextRun("New page")] })
235
+ ```
236
+
237
+ ### Table of Contents
238
+
239
+ ```javascript
240
+ // CRITICAL: Headings must use HeadingLevel ONLY - no custom styles
241
+ new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })
242
+ ```
243
+
244
+ ### Headers/Footers
245
+
246
+ ```javascript
247
+ sections: [{
248
+ properties: {
249
+ page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch
250
+ },
251
+ headers: {
252
+ default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] })
253
+ },
254
+ footers: {
255
+ default: new Footer({ children: [new Paragraph({
256
+ children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
257
+ })] })
258
+ },
259
+ children: [/* content */]
260
+ }]
261
+ ```
262
+
263
+ ### Critical Rules for docx-js
264
+
265
+ - **Set page size explicitly** - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
266
+ - **Landscape: pass portrait dimensions** - docx-js swaps width/height internally; pass short edge as `width`, long edge as `height`, and set `orientation: PageOrientation.LANDSCAPE`
267
+ - **Never use `\n`** - use separate Paragraph elements
268
+ - **Never use unicode bullets** - use `LevelFormat.BULLET` with numbering config
269
+ - **PageBreak must be in Paragraph** - standalone creates invalid XML
270
+ - **ImageRun requires `type`** - always specify png/jpg/etc
271
+ - **Always set table `width` with DXA** - never use `WidthType.PERCENTAGE` (breaks in Google Docs)
272
+ - **Tables need dual widths** - `columnWidths` array AND cell `width`, both must match
273
+ - **Table width = sum of columnWidths** - for DXA, ensure they add up exactly
274
+ - **Always add cell margins** - use `margins: { top: 80, bottom: 80, left: 120, right: 120 }` for readable padding
275
+ - **Use `ShadingType.CLEAR`** - never SOLID for table shading
276
+ - **TOC requires HeadingLevel only** - no custom styles on heading paragraphs
277
+ - **Override built-in styles** - use exact IDs: "Heading1", "Heading2", etc.
278
+ - **Include `outlineLevel`** - required for TOC (0 for H1, 1 for H2, etc.)
279
+
280
+
281
+ ## Editing Existing Documents
282
+
283
+ **Follow all 3 steps in order.**
284
+
285
+ ### Step 1: Unpack
286
+ ```bash
287
+ python scripts/office/unpack.py document.docx unpacked/
288
+ ```
289
+ Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (`“` etc.) so they survive editing. Use `--merge-runs false` to skip run merging.
290
+
291
+ ### Step 2: Edit XML
292
+
293
+ Edit files in `unpacked/word/`. See XML Reference below for patterns.
294
+
295
+ **Use "Claude" as the author** for tracked changes and comments, unless the user explicitly requests use of a different name.
296
+
297
+ **Use the Edit tool directly for string replacement. Do not write Python scripts.** Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.
298
+
299
+ **CRITICAL: Use smart quotes for new content.** When adding text with apostrophes or quotes, use XML entities to produce smart quotes:
300
+ ```xml
301
+ <!-- Use these entities for professional typography -->
302
+ <w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>
303
+ ```
304
+ | Entity | Character |
305
+ |--------|-----------|
306
+ | `&#x2018;` | ‘ (left single) |
307
+ | `&#x2019;` | ’ (right single / apostrophe) |
308
+ | `&#x201C;` | “ (left double) |
309
+ | `&#x201D;` | ” (right double) |
310
+
311
+ **Adding comments:** Use `comment.py` to handle boilerplate across multiple XML files (text must be pre-escaped XML):
312
+ ```bash
313
+ python scripts/comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;"
314
+ python scripts/comment.py unpacked/ 1 "Reply text" --parent 0 # reply to comment 0
315
+ python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author" # custom author name
316
+ ```
317
+ Then add markers to document.xml (see Comments in XML Reference).
318
+
319
+ ### Step 3: Pack
320
+ ```bash
321
+ python scripts/office/pack.py unpacked/ output.docx --original document.docx
322
+ ```
323
+ Validates with auto-repair, condenses XML, and creates DOCX. Use `--validate false` to skip.
324
+
325
+ **Auto-repair will fix:**
326
+ - `durableId` >= 0x7FFFFFFF (regenerates valid ID)
327
+ - Missing `xml:space="preserve"` on `<w:t>` with whitespace
328
+
329
+ **Auto-repair won't fix:**
330
+ - Malformed XML, invalid element nesting, missing relationships, schema violations
331
+
332
+ ### Common Pitfalls
333
+
334
+ - **Replace entire `<w:r>` elements**: When adding tracked changes, replace the whole `<w:r>...</w:r>` block with `<w:del>...<w:ins>...` as siblings. Don't inject tracked change tags inside a run.
335
+ - **Preserve `<w:rPr>` formatting**: Copy the original run's `<w:rPr>` block into your tracked change runs to maintain bold, font size, etc.
336
+
337
+
338
+ ## XML Reference
339
+
340
+ ### Schema Compliance
341
+
342
+ - **Element order in `<w:pPr>`**: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`, `<w:rPr>` last
343
+ - **Whitespace**: Add `xml:space="preserve"` to `<w:t>` with leading/trailing spaces
344
+ - **RSIDs**: Must be 8-digit hex (e.g., `00AB1234`)
345
+
346
+ ### Tracked Changes
347
+
348
+ **Insertion:**
349
+ ```xml
350
+ <w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
351
+ <w:r><w:t>inserted text</w:t></w:r>
352
+ </w:ins>
353
+ ```
354
+
355
+ **Deletion:**
356
+ ```xml
357
+ <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
358
+ <w:r><w:delText>deleted text</w:delText></w:r>
359
+ </w:del>
360
+ ```
361
+
362
+ **Inside `<w:del>`**: Use `<w:delText>` instead of `<w:t>`, and `<w:delInstrText>` instead of `<w:instrText>`.
363
+
364
+ **Minimal edits** - only mark what changes:
365
+ ```xml
366
+ <!-- Change "30 days" to "60 days" -->
367
+ <w:r><w:t>The term is </w:t></w:r>
368
+ <w:del w:id="1" w:author="Claude" w:date="...">
369
+ <w:r><w:delText>30</w:delText></w:r>
370
+ </w:del>
371
+ <w:ins w:id="2" w:author="Claude" w:date="...">
372
+ <w:r><w:t>60</w:t></w:r>
373
+ </w:ins>
374
+ <w:r><w:t> days.</w:t></w:r>
375
+ ```
376
+
377
+ **Deleting entire paragraphs/list items** - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add `<w:del/>` inside `<w:pPr><w:rPr>`:
378
+ ```xml
379
+ <w:p>
380
+ <w:pPr>
381
+ <w:numPr>...</w:numPr> <!-- list numbering if present -->
382
+ <w:rPr>
383
+ <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
384
+ </w:rPr>
385
+ </w:pPr>
386
+ <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
387
+ <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
388
+ </w:del>
389
+ </w:p>
390
+ ```
391
+ Without the `<w:del/>` in `<w:pPr><w:rPr>`, accepting changes leaves an empty paragraph/list item.
392
+
393
+ **Rejecting another author's insertion** - nest deletion inside their insertion:
394
+ ```xml
395
+ <w:ins w:author="Jane" w:id="5">
396
+ <w:del w:author="Claude" w:id="10">
397
+ <w:r><w:delText>their inserted text</w:delText></w:r>
398
+ </w:del>
399
+ </w:ins>
400
+ ```
401
+
402
+ **Restoring another author's deletion** - add insertion after (don't modify their deletion):
403
+ ```xml
404
+ <w:del w:author="Jane" w:id="5">
405
+ <w:r><w:delText>deleted text</w:delText></w:r>
406
+ </w:del>
407
+ <w:ins w:author="Claude" w:id="10">
408
+ <w:r><w:t>deleted text</w:t></w:r>
409
+ </w:ins>
410
+ ```
411
+
412
+ ### Comments
413
+
414
+ After running `comment.py` (see Step 2), add markers to document.xml. For replies, use `--parent` flag and nest markers inside the parent's.
415
+
416
+ **CRITICAL: `<w:commentRangeStart>` and `<w:commentRangeEnd>` are siblings of `<w:r>`, never inside `<w:r>`.**
417
+
418
+ ```xml
419
+ <!-- Comment markers are direct children of w:p, never inside w:r -->
420
+ <w:commentRangeStart w:id="0"/>
421
+ <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
422
+ <w:r><w:delText>deleted</w:delText></w:r>
423
+ </w:del>
424
+ <w:r><w:t> more text</w:t></w:r>
425
+ <w:commentRangeEnd w:id="0"/>
426
+ <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
427
+
428
+ <!-- Comment 0 with reply 1 nested inside -->
429
+ <w:commentRangeStart w:id="0"/>
430
+ <w:commentRangeStart w:id="1"/>
431
+ <w:r><w:t>text</w:t></w:r>
432
+ <w:commentRangeEnd w:id="1"/>
433
+ <w:commentRangeEnd w:id="0"/>
434
+ <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
435
+ <w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>
436
+ ```
437
+
438
+ ### Images
439
+
440
+ 1. Add image file to `word/media/`
441
+ 2. Add relationship to `word/_rels/document.xml.rels`:
442
+ ```xml
443
+ <Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>
444
+ ```
445
+ 3. Add content type to `[Content_Types].xml`:
446
+ ```xml
447
+ <Default Extension="png" ContentType="image/png"/>
448
+ ```
449
+ 4. Reference in document.xml:
450
+ ```xml
451
+ <w:drawing>
452
+ <wp:inline>
453
+ <wp:extent cx="914400" cy="914400"/> <!-- EMUs: 914400 = 1 inch -->
454
+ <a:graphic>
455
+ <a:graphicData uri=".../picture">
456
+ <pic:pic>
457
+ <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
458
+ </pic:pic>
459
+ </a:graphicData>
460
+ </a:graphic>
461
+ </wp:inline>
462
+ </w:drawing>
463
+ ```
464
+
465
+
466
+ ## Dependencies
467
+
468
+ - **pandoc**: Text extraction
469
+ - **docx**: `npm install -g docx` (new documents)
470
+ - **LibreOffice**: PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
471
+ - **Poppler**: `pdftoppm` for images