docx-processing-lawvable

# DOCX Live Editor

Edit Word documents with live preview and track changes in VS Code via [SuperDoc extension](https://github.com/lawvable/superdoc-vscode-extension/tree/feat/programmatic-command-api).

## How It Works

1. Write custom command to `path/to/.superdoc/{docname}.json`
2. Extension executes and overwrites file with response
3. Changes appear live in SuperDoc webview.

**State:** `"command"` field = pending | `"success"` field = response ready

## Prerequisites

1. **SuperDoc extension installed.** Verify:
    ```bash
    code --profile "Lawvable" --list-extensions | grep -i superdoc
    ```

2. **Document must be open** in VS Code before editing:
    ```bash
    code --profile "Lawvable" path/to/doc.docx
    ```

3. **Create new blank document:**
    ```bash
    code --open-url "vscode://superdoc.superdoc-vscode-extension/create?path=./new-document.docx"
    ```
    Path can be relative or absolute. `.docx` extension added automatically if missing.

**If `code` command not found:** Use full path `/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code` instead.

## File Structure

The `.superdoc/` folder must be **in the same directory** as the DOCX file. The JSON file uses the same basename as the DOCX:

```
project/
├── contract.docx              ← document at root
├── .superdoc/
│   └── contract.json          ← commands for contract.docx
└── subfolder/
    ├── report.docx            ← document in subfolder
    └── .superdoc/
        └── report.json        ← commands for subfolder/report.docx
```

## Workflow

**CRITICAL RULES:**
- NEVER send the next command until you receive `{"success": ...}` from the previous one
- If response shows the raw command JSON instead of a result, the document is NOT active — re-open it first

### Command Pattern
Write command, poll until response contains `"success"`, then read:
```bash
echo '{"command":"...","args":{...}}' > path/to/.superdoc/doc.json && until grep -q '"success"' path/to/.superdoc/doc.json; do sleep 0.1; done && cat path/to/.superdoc/doc.json
```

### Step 1: Clarify Author (once per session)
Before making any edits, ALWAYS use `AskUserQuestion` to ask whether changes should be attributed to the user (ask their name) or the agent. If the user wants their name, pass `"author":{"name":"Their Name"}` in **every** `replaceText`, `insertContent`, `insertTable`, and `addComment` command.

### Step 2: Read First (and verify document is active)
```bash
mkdir -p path/to/.superdoc && echo '{"command":"getText","args":{"format":"text"}}' > path/to/.superdoc/doc.json && until grep -q '"success"' path/to/.superdoc/doc.json; do sleep 0.1; done && cat path/to/.superdoc/doc.json
```

**Verifying document is active:** The response MUST contain `{"success": true, "result": ...}`. If you see:
- The raw command JSON back → document not open, re-open with `code --profile "Lawvable" path/to/doc.docx`
- `{"success": false, "error": "No active editor"}` → document not focused, re-open it

Do NOT proceed to Step 3 until you get a successful response with document content.

### Step 3: Make Edit
```bash
echo '{"command":"replaceText","args":{"search":"2024","replacement":"2025"}}' > path/to/.superdoc/doc.json && until grep -q '"success"' path/to/.superdoc/doc.json; do sleep 0.1; done && cat path/to/.superdoc/doc.json
```

### Step 4: Trust the Response

**Do NOT re-verify edits with `getText`.** The command response `{"success": true, "replacedCount": N}` is the source of truth.

**Why:** With track changes enabled, `getText` returns both deleted AND inserted text concatenated (e.g., `"LawvableJamie"` instead of `"Jamie"`). This is expected — the deleted text is visually struck through but still present in plain text extraction.

### Multi-Edit Pattern
Repeat Steps 2-4 for each edit. Each as a separate bash call.

## When to Use Which Command (Track Changes Guide)

**Key principle:** Use `replaceText` only when you're CHANGING existing text. Use `insertContent` when you're ADDING new text.

| Task | Command | Track Changes Display |
|------|---------|----------------------|
| Change a value | `replaceText` | ~~2024~~ <u>2025</u> |
| Fill a placeholder | `replaceText` | ~~[NAME]~~ <u>John</u> |
| Fix a typo | `replaceText` | ~~teh~~ <u>the</u> |
| Change a word | `replaceText` | ~~shall~~ <u>must</u> |
| **Add a word to sentence** | `insertContent` | existing text<u> added word</u> |
| Add a new paragraph | `insertContent` | <u>entire new paragraph</u> |
| Add a new section | `insertContent` | <u>entire new section</u> |
| Add disclaimer | `insertContent` | <u>disclaimer text</u> |
| Add review comment | `addComment` | (comment balloon, no track change) |

## Search & Best Practices

Search extracts **plain text only**, ignoring all formatting:
- ✅ Matches across bold/normal, track changes, paragraphs
- ✅ Whitespace flexible (extra spaces/tabs/line breaks OK)
- Returns **first** occurrence. Use `occurrence` parameter for nth match, or include more context to make pattern unique.

**Use unique phrases (5+ words):**
- ❌ `"the"` or `"Agreement"` (too common)
- ✅ `"agrees to pay the sum of"` or `"Section 3.2 Confidentiality"`

**Don't worry about formatting in search** - matches across bold, track changes, etc.

**Use `occurrence` for ambiguous matches** (1-indexed):
```json
{"command":"replaceText","args":{"search":"the","replacement":"that","occurrence":3}}
```

**For insertions, find unique anchor text nearby.**

## Commands

### `getText` - Read Document Content

```json
// Get both text and HTML (default)
{"command":"getText","args":{}}

// Get only plain text (fewer tokens)
{"command":"getText","args":{"format":"text"}}

// Get only HTML (preserves structure)
{"command":"getText","args":{"format":"html"}}
```

**Formats:** `text` (plain text with paragraph breaks), `html` (full HTML), `both` (default)

### `getNodes` - Get Document Structure

Get all nodes of a specific type with their positions. Useful for understanding document structure before making edits.

```json
// Get all paragraphs (use to identify section titles for TOC)
{"command":"getNodes","args":{"type":"paragraph"}}

// Get all tables
{"command":"getNodes","args":{"type":"table"}}
```

**Valid types:** `paragraph`, `table`, `tableRow`, `tableCell`, `bulletList`, `orderedList`, `listItem`, `image`, `blockquote`

**Returns:**
```json
{
  "nodes": [
    {"index": 0, "type": "paragraph", "from": 0, "to": 31, "text": "Non-Disclosure Agreement", "textLength": 24},
    {"index": 1, "type": "paragraph", "from": 227, "to": 241, "text": "Background", "textLength": 10},
    {"index": 2, "type": "paragraph", "from": 586, "to": 601, "text": "Definitions", "textLength": 11, "marker": "1."}
  ],
  "count": 3
}
```

### `replaceText` - Find and Replace (DELETION + INSERTION)

**Use when:** Changing existing text to something different. The found text is DELETED and replaced.
**Track changes effect:** Shows as ~~deleted text~~ + <u>new text</u> (strikethrough + underline).
**Scope:** Replaces ALL occurrences by default. Use `occurrence` parameter to replace only the Nth match.

```json
// Change a value: "2024" → "2025"
{"command":"replaceText","args":{"search":"2024","replacement":"2025"}}

// Change a placeholder: "[ORG_NAME]" → "Lawvable"
{"command":"replaceText","args":{"search":"[ORG_NAME]","replacement":"Lawvable"}}

// Change a word: "shall" → "must"
{"command":"replaceText","args":{"search":"shall","replacement":"must","occurrence":1}}

// Add formatting to existing text (text is replaced with formatted version)
{"command":"replaceText","args":{"search":"Important Notice","replacement":"<strong>Important Notice</strong>"}}
```

### `insertContent` - Insert New Content (INSERTION ONLY)

**Use when:** Adding new text/elements while keeping the anchor text intact. The anchor text STAYS, new content is added before/after.
**Track changes effect:** Shows as <u>new text</u> only (underline, no strikethrough).

**CRITICAL:** When you need to ADD words to a sentence without changing existing words, you MUST use `insertContent`, NOT `replaceText`. Using `replaceText` will show the entire sentence as deleted and rewritten, which clutters the track changes view.

```json
// CORRECT: Add a word after existing text - shows only the addition as tracked
// Original: "The party agrees to pay"  →  Result: "The party agrees to pay promptly"
{"command":"insertContent","args":{"content":" promptly","position":{"after":"agrees to pay"}}}

// WRONG: Using replaceText to add a word - shows entire phrase as deleted + rewritten
// This would show: "~~agrees to pay~~" + "agrees to pay promptly" (ugly track changes!)
// {"command":"replaceText","args":{"search":"agrees to pay","replacement":"agrees to pay promptly"}}

// Add a new section after a heading
{"command":"insertContent","args":{"content":"<h2>New Section</h2><p>Content here.</p>","position":{"after":"Introduction"}}}

// Add a disclaimer before signatures
{"command":"insertContent","args":{"content":"<p>By signing below, parties confirm agreement.</p>","position":{"before":"Signatures"}}}

// Add a clause after a section
{"command":"insertContent","args":{"content":"<p>Additional clause text.</p>","position":{"after":"Section 2."},"author":{"name":"Jane Smith"}}}
```

### `insertTable` - Create a Table

```json
// Insert 3x4 table after specific text
{"command":"insertTable","args":{"rows":3,"cols":4,"position":{"after":"Introduction"}}}

// Insert 2x2 table (default) before specific text
{"command":"insertTable","args":{"position":{"before":"Signatures"}}}

// Pre-populated table with headers and data (dimensions inferred)
{"command":"insertTable","args":{"data":[["Name","Role"],["Alice","Engineer"]],"position":{"after":"Team:"}}}

// Cells support HTML formatting
{"command":"insertTable","args":{"data":[["<strong>Header</strong>"],["Value"]]}}

// With custom author for track changes
{"command":"insertTable","args":{"rows":2,"cols":3,"author":{"name":"John"}}}
```

**Parameters:**
- `rows`, `cols` - Dimensions (default: 2, or inferred from `data`)
- `data` - 2D array of cell contents (row-major). Supports plain text or HTML. Empty strings for blank cells.
- `position` - `{"after": "text"}` or `{"before": "text"}` for anchor-based positioning
- `author` - Optional author for track changes attribution

### `addComment` - Add Comment to Text

```json
// Add a comment on specific text
{"command":"addComment","args":{"search":"confidential information","comment":"This clause needs legal review"}}

// Comment on nth occurrence
{"command":"addComment","args":{"search":"Party","comment":"Verify party name","occurrence":2}}
```

**Parameters:**
- `search` (required) - Text to find and attach comment to
- `comment` (required) - The comment text
- `occurrence` - Which match (1-indexed), defaults to first
- `author` - Optional `{name, email}` for attribution

### `formatText` - Apply Formatting

Apply text styling, paragraph properties, and heading conversion. **Not tracked** (applied directly for performance).

```json
// Multiple text formats on entire document
{"command":"formatText","args":{"fontFamily":"Arial","fontSize":"12pt","color":"#333333","scope":"document"}}

// Bold + highlight on specific range (use getNodes to find positions)
{"command":"formatText","args":{"bold":true,"highlight":"#FFEB3B","scope":{"from":100,"to":200}}}

// Remove formatting (false removes, omit leaves unchanged)
{"command":"formatText","args":{"bold":false,"highlight":false,"scope":{"from":100,"to":200}}}

// Add hyperlink to text range
{"command":"formatText","args":{"link":"https://example.com","scope":{"from":100,"to":120}}}

// Remove hyperlink
{"command":"formatText","args":{"link":false,"scope":{"from":100,"to":120}}}

// Set line height on entire document
{"command":"formatText","args":{"lineHeight":"1.5","scope":"document"}}

// Set spacing + indent
{"command":"formatText","args":{"spacingBefore":"12pt","spacingAfter":"6pt","indent":36,"scope":"document"}}

// Align text right (use with scope from getNodes)
{"command":"formatText","args":{"textAlign":"right","scope":{"from":0,"to":25}}}
```

**Text-level parameters:**
- `fontFamily` - Font name (e.g., "Arial", "Times New Roman")
- `fontSize` - Size with unit (e.g., "12pt", "14px")
- `color` - Text color as CSS (e.g., "#ff0000", "red")
- `highlight` - Background color, or `false` to remove
- `bold`, `italic`, `underline`, `strikethrough` - `true` to apply, `false` to remove, omit to leave unchanged
- `link` - URL string to create hyperlink, or `false` to remove

**Block-level parameters:**
- `textAlign` - Paragraph alignment: `left`, `center`, `right`, `justify`
- `lineHeight` - Line spacing (e.g., "1.0", "1.5", "2.0")
- `indent` - Left indentation in points (e.g., 36 for 0.5", 72 for 1"). Use 0 to remove.
- `spacingBefore` - Space before paragraph (e.g., "12pt", "6pt")
- `spacingAfter` - Space after paragraph (e.g., "12pt", "6pt")

**Scope:** `"document"` for entire doc, or `{"from": N, "to": M}` for range. Use `getNodes` to find positions.

### `insertTableOfContents` - Create TOC with Bookmarks

Insert a proper table of contents with internal navigation links. You identify the heading entries (position + level), the command handles bookmarks and TOC node creation.

**Workflow:**
1. Use `getNodes` with type `paragraph` to get all paragraph positions
2. Identify which paragraphs are section titles (by text content, bold styling, numbering, etc.). Numbered paragraphs include a `marker` field (e.g., `"marker": "1."`) — the TOC automatically prepends it to the entry text.
3. Pass their positions and heading levels to `insertTableOfContents`

```json
// TOC matching document font (always pass style with fontFamily + fontSize)
{"command":"insertTableOfContents","args":{"entries":[{"level":1,"from":227,"to":241},{"level":2,"from":586,"to":601}],"position":{"after":"Non-Disclosure Agreement"},"style":{"fontFamily":"Arial","fontSize":"10pt"}}}

// Custom title
{"command":"insertTableOfContents","args":{"entries":[{"level":2,"from":229,"to":243}],"style":{"fontFamily":"Arial","fontSize":"10pt"},"title":"Contents"}}

// No title
{"command":"insertTableOfContents","args":{"entries":[{"level":2,"from":229,"to":243}],"style":{"fontFamily":"Arial","fontSize":"10pt"},"title":""}}
```

**Parameters:**
- `entries` (required) - Array of `{level: 1-6, from: N, to: M}`. Positions from `getNodes` output. The command reads the text automatically.
- `position` - `{"after": "text"}` or `{"before": "text"}` (default: beginning of document)
- `title` - TOC title (default: "Table of Contents", `""` for none)
- `style` (required) - `{fontFamily, fontSize}` to match the document's font conventions. **ALWAYS detect the document's font family and size** from `getText` with `html` format and pass them here. Bold and black (#000000) are applied by default. The title is automatically 2pt larger than entries. Optional: `color` to override the default black.
- `author` - Optional author for track changes attribution

The command inserts invisible bookmarks at each heading and creates TOC entries with internal links pointing to them. All entries are automatically left-indented based on their `level` (0.5" per level). The existing text and styling are not modified.

### `deleteTableOfContents` - Remove TOC

Delete the table of contents from the document.

```json
// Remove TOC only
{"command":"deleteTableOfContents","args":{}}

// Remove TOC and its bookmarks
{"command":"deleteTableOfContents","args":{"removeBookmarks":true}}
```

### `undo` / `redo` - History Navigation

```json
// Undo the last action
{"command":"undo","args":{}}

// Redo the last undone action
{"command":"redo","args":{}}
```

**Returns:** `{"success": true}` if action was undone/redone, `{"success": false}` if nothing to undo/redo.

### `acceptAllChanges` / `rejectAllChanges` - Finalize Track Changes

Accept or reject all tracked changes in the document. Use after edits are complete and reviewed.

```json
// Accept all tracked changes (removes strikethroughs, keeps insertions)
{"command":"acceptAllChanges","args":{}}

// Reject all tracked changes (removes insertions, restores deleted text)
{"command":"rejectAllChanges","args":{}}
```

**Note:** After accepting all changes, `getText` will return clean text without the deleted content concatenated.

## Header/Footer Editing

Edit document headers and footers by switching editing mode. While in header/footer mode, all commands (`getText`, `replaceText`, `insertContent`, etc.) operate on the header/footer content instead of the body.

### `focusHeader` / `focusFooter` - Enter Header/Footer Mode

```json
{"command":"focusHeader","args":{}}
{"command":"focusFooter","args":{}}
```

### `exitHeaderFooter` - Return to Body Mode

```json
{"command":"exitHeaderFooter","args":{}}
```

### Header/Footer Workflow

```bash
# 1. Focus header
echo '{"command":"focusHeader","args":{}}' > .superdoc/doc.json && until grep -q '"success"' .superdoc/doc.json; do sleep 0.1; done && cat .superdoc/doc.json

# 2. Read current header content
echo '{"command":"getText","args":{"format":"text"}}' > .superdoc/doc.json && until grep -q '"success"' .superdoc/doc.json; do sleep 0.1; done && cat .superdoc/doc.json

# 3. Insert content (no position needed for empty header/footer)
echo '{"command":"insertContent","args":{"content":"<p>CONFIDENTIAL</p>"}}' > .superdoc/doc.json && until grep -q '"success"' .superdoc/doc.json; do sleep 0.1; done && cat .superdoc/doc.json

# 4. Exit back to body
echo '{"command":"exitHeaderFooter","args":{}}' > .superdoc/doc.json && until grep -q '"success"' .superdoc/doc.json; do sleep 0.1; done && cat .superdoc/doc.json
```

**Notes:**
- Header/footer must be defined in the DOCX structure (cannot create new ones, but can edit empty ones)
- For empty headers/footers, `insertContent` without a `position` argument inserts at the start
- Always `exitHeaderFooter` when done to return to body editing

## HTML Formatting

| Format | HTML |
|--------|------|
| Headings | `<h1>`, `<h2>`, `<h3>` |
| Paragraph | `<p>Text</p>` |
| Bold/Italic/Underline | `<strong>`, `<em>`, `<u>` |
| Color | `<span style="color: red">text</span>` |
| Lists | `<ul><li>...</li></ul>`, `<ol><li>...</li></ol>` |
| Link | `<a href="url">text</a>` |

**Adding a link to existing text:**

Use `formatText` with `link` parameter and position scope:
```json
// Step 1: Get paragraph positions
{"command":"getNodes","args":{"type":"paragraph"}}

// Step 2: Apply link to the target range
{"command":"formatText","args":{"link":"https://example.com","scope":{"from":218,"to":230}}}
```

**Important:** Replacement strings are only parsed as HTML if they **start with `<tag>` and end with `</tag>`**. Including text before/after (e.g., `(<a>text</a>)`) treats the entire string as literal text.

**Creating lists with `insertContent`:**
```json
// Bullet list
{"command":"insertContent","args":{"content":"<ul><li>First</li><li>Second</li></ul>","position":{"after":"Key points:"}}}

// Numbered list with nested items and formatting
{"command":"insertContent","args":{"content":"<ol><li><strong>Step one</strong><ul><li>Sub-item</li></ul></li><li>Step two</li></ol>","position":{"after":"Instructions:"}}}
```

## Bulk Editing (Multiple Documents)

When edits target multiple documents, iterate sequentially — open each document, make the edits, verify, then move to the next. Do NOT use subagents; sequential iteration is simpler and avoids race conditions.

**Pattern:**
```
for each document:
    1. Open: code --profile "Lawvable" path/to/doc.docx
    2. Read: getText
    3. Edit: replaceText / insertContent
    4. Verify response shows success
```

Keep documents open in tabs — no need to close between edits.

## Troubleshooting

- **Command not executing / raw JSON returned**: Document not open. Re-open with `code --profile "Lawvable" path/to/doc.docx` and retry.
- **`code` command not found**: Use full path `/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code` instead.
- **"Text not found" error**: Use `getText` first to see actual content, then include more surrounding context in search string.
- **Corrupted replacement**: Commands sent without waiting for responses. Always wait for `{"success": ...}` before sending the next command.