dimcode-darwin-x64 0.1.2-beta.1 → 0.1.2

package/bin/skills-assets/docx/references/scenario_b_edit_content.md

@@ -1,295 +0,0 @@
-# Scenario B: Editing / Filling Content in Existing DOCX
-
-## Core Principle
-
-**"First, do no harm."** When editing an existing document, minimize changes. Touch only what needs to change. Preserve all formatting, styles, relationships, and structure that are not directly involved in the edit.
-
----
-
-## When to Use
-
-- Replacing placeholder text (`{{name}}`, `$DATE$`, `[PLACEHOLDER]`)
-- Updating specific paragraphs or table cells
-- Filling in form fields
-- Adding or removing paragraphs in a known location
-- Inserting tracked changes for review workflows
-
-Do NOT use when: the user wants to change the look/style of the entire document (→ Scenario C) or create from scratch (→ Scenario A).
-
----
-
-## Workflow
-
-```
-1. Preview   → CLI: analyze <input.docx>
-2. Analyze   → Understand structure: sections, styles, headings, tables
-3. Identify  → Locate exact edit targets (paragraph index, table index, placeholder text)
-4. Edit      → Apply surgical changes via CLI or direct XML
-5. Validate  → CLI: validate <output.docx>
-6. Diff      → Compare before/after to verify only intended changes were made
-```
-
----
-
-## When to Use API vs Direct XML
-
-### Use CLI Edit Command When:
-- Replacing placeholder text (e.g., `{{fieldName}}` → actual value)
-- Filling table data from JSON
-- Updating document properties (title, author)
-- Simple text insertions or deletions
-
-### Use Direct XML Manipulation When:
-- Text spans multiple runs with different formatting (run-boundary issues)
-- Adding complex structures (nested tables, multi-image layouts)
-- Manipulating Track Changes markup
-- Modifying header/footer content
-- Adjusting section properties
-
----
-
-## Placeholder Patterns
-
-The CLI natively supports `{{fieldName}}` placeholders:
-
-```bash
-# Replace all {{placeholders}} from a JSON map
-dotnet run ... edit input.docx --fill-placeholders data.json --output filled.docx
-```
-
-Where `data.json`:
-```json
-{
-  "companyName": "Acme Corp",
-  "date": "March 21, 2026",
-  "amount": "$15,000.00",
-  "recipientName": "Jane Smith"
-}
-```
-
-Other placeholder formats (`$FIELD$`, `[PLACEHOLDER]`) require text replacement:
-```bash
-dotnet run ... edit input.docx --replace "$DATE$" "March 21, 2026" --output updated.docx
-```
-
----
-
-## Text Replacement Strategies
-
-### Simple Replacement
-
-When the entire search text is within a single `w:r` (run):
-
-```xml
-<!-- Before -->
-<w:r>
-  <w:rPr><w:b /></w:rPr>
-  <w:t>{{companyName}}</w:t>
-</w:r>
-
-<!-- After — formatting preserved -->
-<w:r>
-  <w:rPr><w:b /></w:rPr>
-  <w:t>Acme Corp</w:t>
-</w:r>
-```
-
-Direct replacement. The run's `w:rPr` is untouched.
-
-### Complex Replacement (Split Runs)
-
-When the search text is split across multiple runs (common when Word applies spell-check or formatting mid-text):
-
-```xml
-<!-- "{{companyName}}" split into 3 runs -->
-<w:r><w:rPr><w:b /></w:rPr><w:t>{{company</w:t></w:r>
-<w:r><w:rPr><w:b /><w:i /></w:rPr><w:t>Na</w:t></w:r>
-<w:r><w:rPr><w:b /></w:rPr><w:t>me}}</w:t></w:r>
-```
-
-Strategy:
-1. Concatenate text across runs to find the match
-2. Place the replacement text in the **first** run (preserving its `w:rPr`)
-3. Remove the text from subsequent runs (or remove the runs entirely if empty)
-
-```xml
-<!-- After -->
-<w:r><w:rPr><w:b /></w:rPr><w:t>Acme Corp</w:t></w:r>
-```
-
-**Rule**: Always preserve the formatting of the first run in the match.
-
----
-
-## Table Editing
-
-### By Index
-
-Tables are 0-indexed in document order:
-
-```bash
-dotnet run ... edit input.docx --table-index 0 --table-data data.json --output updated.docx
-```
-
-### By Header Matching
-
-Find a table by its header row content:
-
-```bash
-dotnet run ... edit input.docx --table-match "Name,Amount,Date" --table-data data.json
-```
-
-### Table Data JSON Format
-
-```json
-{
-  "rows": [
-    ["Alice Johnson", "$5,000", "2026-03-15"],
-    ["Bob Smith", "$3,200", "2026-03-18"]
-  ],
-  "appendRows": true
-}
-```
-
-- `appendRows: true` — add rows after existing data
-- `appendRows: false` (default) — replace all data rows (keeps header row)
-
-### Direct XML Table Editing
-
-To modify a specific cell, locate it by row/column index:
-
-```xml
-<!-- Row 2 (0-indexed), Column 1 -->
-<w:tr>  <!-- tr[2] -->
-  <w:tc>...</w:tc>
-  <w:tc>  <!-- tc[1] — target cell -->
-    <w:p>
-      <w:r><w:t>Old Value</w:t></w:r>
-    </w:p>
-  </w:tc>
-</w:tr>
-```
-
-Replace the `w:t` content. Do NOT modify `w:tcPr` (cell properties) or `w:tblPr` (table properties).
-
----
-
-## Track Changes Guidance
-
-### When to Add Revision Marks
-- User explicitly requests tracked changes
-- Document already has tracking enabled (`w:trackChanges` in settings)
-- Collaborative review workflow
-
-### When NOT to Add Revision Marks
-- Form filling / placeholder replacement (these are "completing" the document, not "revising" it)
-- Direct edits where the user wants a clean result
-- Batch data filling operations
-
-### Adding Tracked Changes
-
-See `references/track_changes_guide.md` for full XML examples.
-
-Quick reference — inserting text with tracking:
-```xml
-<w:ins w:id="1" w:author="Editor" w:date="2026-03-21T10:00:00Z">
-  <w:r>
-    <w:t>New text here</w:t>
-  </w:r>
-</w:ins>
-```
-
-Deleting text with tracking:
-```xml
-<w:del w:id="2" w:author="Editor" w:date="2026-03-21T10:00:00Z">
-  <w:r>
-    <w:delText>Removed text</w:delText>  <!-- MUST use delText, not t -->
-  </w:r>
-</w:del>
-```
-
----
-
-## Common Pitfalls
-
-### 1. Breaking Run Boundaries
-
-**Problem**: Replacing text that spans runs by naively modifying individual runs destroys inline formatting.
-
-**Fix**: Concatenate run text, find match boundaries, consolidate into the first run, remove consumed runs.
-
-### 2. Hyperlink Content
-
-**Problem**: Replacing text inside a `w:hyperlink` element without preserving the hyperlink wrapper removes the link.
-
-```xml
-<w:hyperlink r:id="rId5">
-  <w:r>
-    <w:rPr><w:rStyle w:val="Hyperlink" /></w:rPr>
-    <w:t>Click here</w:t>  <!-- Only replace this text -->
-  </w:r>
-</w:hyperlink>
-```
-
-**Fix**: Only modify the `w:t` inside the hyperlink's run. Never remove or replace the `w:hyperlink` element itself.
-
-### 3. Tracked Change Context
-
-**Problem**: Replacing text that is inside a `w:ins` or `w:del` element without understanding the revision context creates invalid markup.
-
-**Fix**: If the target text is inside a revision mark, either:
-- Replace within the revision context (preserving the `w:ins`/`w:del` wrapper)
-- Or delete the old revision and create a new one
-
-### 4. Style Preservation
-
-**Problem**: Adding new paragraphs without specifying a style causes them to inherit `Normal`, which may not match the surrounding context.
-
-**Fix**: When inserting paragraphs, copy the `w:pStyle` from an adjacent paragraph of the same type.
-
-### 5. Numbering Continuity
-
-**Problem**: Inserting a new list item breaks numbering sequence.
-
-**Fix**: Ensure the new paragraph has the same `w:numId` and `w:ilvl` as adjacent list items. If continuing a sequence, set `w:numPr` to match.
-
-### 6. XML Special Characters
-
-**Problem**: User content contains `&`, `<`, `>`, `"`, `'` — these must be escaped in XML.
-
-**Fix**: Always XML-escape user-provided text before inserting into `w:t` elements:
-- `&` → `&amp;`
-- `<` → `&lt;`
-- `>` → `&gt;`
-- `"` → `&quot;`
-- `'` → `&apos;`
-
-### 7. Whitespace Preservation
-
-**Problem**: Leading/trailing spaces in `w:t` are stripped by XML parsers.
-
-**Fix**: Add `xml:space="preserve"` attribute:
-```xml
-<w:t xml:space="preserve"> text with leading space</w:t>
-```
-
----
-
-## Diff Verification
-
-After editing, always compare the before and after states:
-
-```bash
-# Structural diff — shows only changed elements
-dotnet run ... diff original.docx modified.docx
-
-# Text-only diff — shows content changes
-dotnet run ... diff original.docx modified.docx --text-only
-```
-
-Verify:
-- Only intended text changed
-- No styles were modified
-- No relationships were added/removed unexpectedly
-- Table structure intact (same number of rows/columns unless intentionally changed)
-- Images and other media unchanged