How to Use IronWord with Claude Code

Add the IronWord NuGet package, version 2026.10.4, to RenewalLetters.csproj.
Then write one renewal letter in Program.cs.

Merge the first customer row of @Data/customers.csv into @Templates/renewal-letter.docx.
Save the letter to out/letters/NM-104233.docx.
Create that folder first, and pass the path to the save call.
Don't change the template file.

Next, open the saved letter in a new WordDocument and print these in order:

1. The body text.
2. The text of every table cell, row by row, with each cell cast to TableCell to read it.
3. The names of any merge fields still in the document, or "none".

My license key is in the IRONWORD_LICENSE_KEY environment variable.
Have the program read that variable itself and apply the key before the first IronWord call.
Don't print, echo or save the key anywhere.
Don't list environment variables to look for it either.
Tell me whether it's set and nothing more.

Add the IronWord NuGet package, version 2026.10.4, to RenewalLetters.csproj.
Then write one renewal letter in Program.cs.

Merge the first customer row of @Data/customers.csv into @Templates/renewal-letter.docx.
Save the letter to out/letters/NM-104233.docx.
Create that folder first, and pass the path to the save call.
Don't change the template file.

Next, open the saved letter in a new WordDocument and print these in order:

1. The body text.
2. The text of every table cell, row by row, with each cell cast to TableCell to read it.
3. The names of any merge fields still in the document, or "none".

My license key is in the IRONWORD_LICENSE_KEY environment variable.
Have the program read that variable itself and apply the key before the first IronWord call.
Don't print, echo or save the key anywhere.
Don't list environment variables to look for it either.
Tell me whether it's set and nothing more.

Create CLAUDE.md in the repository root and give it a section called Mail merge.
Every later session should find these rules in it:

- IronWord is the only DOCX library this project may use.
- The NuGet package is IronWord, at the version RenewalLetters.csproj references now.
- Look up IronWord member names in docs/IronWord.xml.
- Templates/ is read-only, and each letter starts from a new load of the template file.
- The license key rules from my first message, written out in full.
- A letter isn't finished until the saved file has been reopened and checked.

Copy docs/IronWord.xml now from the ironword folder of the local NuGet cache.
If the file isn't there, stop and say so.

Then add a subagent at .claude/agents/merge-auditor.md.
Give it the Read, Grep and Glob tools and no others.
Its job is to list every IronWord type and member used under Services/.
It should name each one that docs/IronWord.xml doesn't document.
IronSoftware.* types such as ITableCell are documented in other packages.
Have it list those separately, so it doesn't call them missing.

Create CLAUDE.md in the repository root and give it a section called Mail merge.
Every later session should find these rules in it:

- IronWord is the only DOCX library this project may use.
- The NuGet package is IronWord, at the version RenewalLetters.csproj references now.
- Look up IronWord member names in docs/IronWord.xml.
- Templates/ is read-only, and each letter starts from a new load of the template file.
- The license key rules from my first message, written out in full.
- A letter isn't finished until the saved file has been reopened and checked.

Copy docs/IronWord.xml now from the ironword folder of the local NuGet cache.
If the file isn't there, stop and say so.

Then add a subagent at .claude/agents/merge-auditor.md.
Give it the Read, Grep and Glob tools and no others.
Its job is to list every IronWord type and member used under Services/.
It should name each one that docs/IronWord.xml doesn't document.
IronSoftware.* types such as ITableCell are documented in other packages.
Have it list those separately, so it doesn't call them missing.

IronWord 2026.10.4 behaves this way in a mail merge:

- MailMerge.Execute(DataTable) merges the first row only.
- Merge each row into its own WordDocument, loaded fresh from the template file.
- A merge removes the fields it fills, so a second Execute on the same document changes nothing.
- Call ExecuteWithRegions before Execute.
- Execute removes any region it has no table for, because RemoveUnusedRegions defaults to true.
- That region's row then stays in the table with empty cells.
- A region table with no rows removes the region row and keeps the rest of the table.
- RemoveUnusedFields defaults to true, so a field with no matching key is deleted with no error.
- Compare GetFieldNames() with the data columns before merging.
- Field names match without regard to case unless CaseInsensitiveFieldNames is set to false.
- NullValueReplacement replaces DBNull values. An empty string merges as an empty string.
- WordDocument.ExtractText() returns body paragraphs only, joined with no separator.
- ExtractText() skips table cells, the header and the footer.
- Rows[i].Cells holds ITableCell values, which have no ExtractText().
- Cast each cell to TableCell before calling ExtractText() on it.
- GetFields() and GetFieldNames() don't see merge fields in the header.
- Save each letter with Save(outputPath).
- One troubleshooting page reports a header that SaveAs(outputPath) dropped and Save kept.
- Never call Save() with no argument. It overwrites the file the document was loaded from.

IronWord 2026.10.4 behaves this way in a mail merge:

- MailMerge.Execute(DataTable) merges the first row only.
- Merge each row into its own WordDocument, loaded fresh from the template file.
- A merge removes the fields it fills, so a second Execute on the same document changes nothing.
- Call ExecuteWithRegions before Execute.
- Execute removes any region it has no table for, because RemoveUnusedRegions defaults to true.
- That region's row then stays in the table with empty cells.
- A region table with no rows removes the region row and keeps the rest of the table.
- RemoveUnusedFields defaults to true, so a field with no matching key is deleted with no error.
- Compare GetFieldNames() with the data columns before merging.
- Field names match without regard to case unless CaseInsensitiveFieldNames is set to false.
- NullValueReplacement replaces DBNull values. An empty string merges as an empty string.
- WordDocument.ExtractText() returns body paragraphs only, joined with no separator.
- ExtractText() skips table cells, the header and the footer.
- Rows[i].Cells holds ITableCell values, which have no ExtractText().
- Cast each cell to TableCell before calling ExtractText() on it.
- GetFields() and GetFieldNames() don't see merge fields in the header.
- Save each letter with Save(outputPath).
- One troubleshooting page reports a header that SaveAs(outputPath) dropped and Save kept.
- Never call Save() with no argument. It overwrites the file the document was loaded from.

Build the batch in Services/LetterMerger.cs and Services/LetterAudit.cs.
Run both from Program.cs after the Quickstart letter.

LetterMerger reads @Data/customers.csv and @Data/coverages.csv.
For each customer it does this:

1. Loads Templates/renewal-letter.docx again.
2. Fills the Coverages region with that policy's rows, if any.
3. Fills the other fields from the customer row.
4. Saves out/letters/<PolicyNumber>.docx.

Before the first merge, it prints each template merge field with no column in either CSV.

LetterAudit opens each saved letter from disk and passes it when these all hold:

- Every customer value appears in the body text.
- The coverage table holds only that policy's rows, in CSV order.
- word/document.xml, read as a zip entry, has no merge field or MERGEFIELD instruction left.

For an empty customer value, check its whole sentence.
One case is the agent sentence with no phone number.

Two more columns don't count toward a pass:

- Header, from word/header1.xml: shows the policy number, still has the merge field, or is missing.
- Footer, from word/footer1.xml: matches the template's footer, changed, or is missing.

Write out/letter-audit.csv with one row per letter.
Print how many letters pass.
After the batch, run git status on Templates/ and tell me about any change.

Don't use a docx skill or rewrite any package XML by hand.
The audit can read parts as zip entries.
Keep fixing the merger until every letter passes.
If a header keeps its field, tell me whether any IronWord call reached it.
Then have the merge-auditor subagent review Services/.

Build the batch in Services/LetterMerger.cs and Services/LetterAudit.cs.
Run both from Program.cs after the Quickstart letter.

LetterMerger reads @Data/customers.csv and @Data/coverages.csv.
For each customer it does this:

1. Loads Templates/renewal-letter.docx again.
2. Fills the Coverages region with that policy's rows, if any.
3. Fills the other fields from the customer row.
4. Saves out/letters/<PolicyNumber>.docx.

Before the first merge, it prints each template merge field with no column in either CSV.

LetterAudit opens each saved letter from disk and passes it when these all hold:

- Every customer value appears in the body text.
- The coverage table holds only that policy's rows, in CSV order.
- word/document.xml, read as a zip entry, has no merge field or MERGEFIELD instruction left.

For an empty customer value, check its whole sentence.
One case is the agent sentence with no phone number.

Two more columns don't count toward a pass:

- Header, from word/header1.xml: shows the policy number, still has the merge field, or is missing.
- Footer, from word/footer1.xml: matches the template's footer, changed, or is missing.

Write out/letter-audit.csv with one row per letter.
Print how many letters pass.
After the batch, run git status on Templates/ and tell me about any change.

Don't use a docx skill or rewrite any package XML by hand.
The audit can read parts as zip entries.
Keep fixing the merger until every letter passes.
If a header keeps its field, tell me whether any IronWord call reached it.
Then have the merge-auditor subagent review Services/.

Add a RenewalLetters.Tests xUnit project that tests LetterMerger without writing any file.

Merge NM-104267 and NM-104288 in memory.
Assert the body text and every coverage table cell against the CSV rows.
Cover the policy with no coverage rows and the agent sentence with an empty phone number.

A few things about the setup:

- Split the merge from the save in LetterMerger if a test needs that.
- Leave the license key unset when the variable is missing.
- Put the test project in its own folder, with no solution file at the repository root.
- Keep RenewalLetters.csproj from compiling the files in that folder.
- Have the test project copy Templates/ and Data/ to its output folder.

Run dotnet test on the test project once, in a child process with no IRONWORD_LICENSE_KEY variable.
Show me the tests passing without a key.

Add a RenewalLetters.Tests xUnit project that tests LetterMerger without writing any file.

Merge NM-104267 and NM-104288 in memory.
Assert the body text and every coverage table cell against the CSV rows.
Cover the policy with no coverage rows and the agent sentence with an empty phone number.

A few things about the setup:

- Split the merge from the save in LetterMerger if a test needs that.
- Leave the license key unset when the variable is missing.
- Put the test project in its own folder, with no solution file at the repository root.
- Keep RenewalLetters.csproj from compiling the files in that folder.
- Have the test project copy Templates/ and Data/ to its output folder.

Run dotnet test on the test project once, in a child process with no IRONWORD_LICENSE_KEY variable.
Show me the tests passing without a key.