n8n-nodes-adeu 2.4.0 → 3.0.0

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/README.md CHANGED
@@ -6,11 +6,15 @@
6
6
  An [n8n](https://n8n.io) community node for **[Adeu](https://adeu.ai)** — the AI-native Virtual DOM for Microsoft Word.
7
7
 
8
8
  > **🆕 New in this release:**
9
- > - **`Extract Outline`** — a new operation returning a token-cheap structural map (headings + page numbers + table flags) for navigating large documents.
9
+ > - **`Extract Outline`** — a new operation returning a token-cheap structural map (headings + page numbers + table flags) for navigating large documents. Each heading also carries `end_page`, the last page it owns, so you can read a whole section with one `page`–`end_page` range instead of guessing.
10
+ > - **`Apply Text Revision`** — a new operation that takes the **complete** revised clean text of a document and writes the difference against its own clean view as native Word tracked changes, for when an LLM rewrote the document wholesale and no per-change anchors are left.
10
11
  > - **`Page` parameter on `Extract Markdown`** — fetch only one page of a paginated projection instead of the whole document.
11
12
  > - **`match_mode` and `regex` on `modify` edits** — `Apply Edits` now supports targeted multi-occurrence writes. Set `match_mode: "all"` to replace every occurrence, `"first"` to anchor to the first hit silently, or omit/`"strict"` to fail on ambiguity. Set `regex: true` to interpret `target_text` as an ES2022 RegExp (with `$1`, `$2` capture-group references in `new_text`).
13
+ > - **`Allow Partial Application` on `Apply Edits`** — opt-in salvage batches: valid edits are applied and saved, the item's `status` reads `"partial"`, and rejected edits come back in `stats.failed` for an agent to fix and resubmit.
12
14
  >
13
15
  > **Existing workflows must hand-update their `$fromAI` expressions** to expose the new fields — n8n caches `$fromAI` expressions per workflow and does not retroactively update them on package upgrades.
16
+ >
17
+ > The shipped example workflows in `examples/` are kept in sync with these recipes — re-import them after upgrading rather than hand-patching an old copy.
14
18
 
15
19
  This node bridges the gap between Large Language Models (LLMs) and Microsoft Word. It translates complex OpenXML (`.docx`) files into token-efficient Markdown, allows AI models to reason over legal or technical text, and translates the AI's JSON output back into **native Word Tracked Changes and Comments** — all completely in-process, without your documents ever leaving the n8n runtime.
16
20
 
@@ -54,6 +58,9 @@ Restart your n8n instance after installation.
54
58
  - **Structural Outline**: Lightweight headings-and-pages map of any document, with table/footnote flags per section.
55
59
  - **Pagination**: Drill into a single page of a large document instead of blasting the full body into LLM context.
56
60
  - **Native Redlining**: Apply `modify`, `accept`, `reject`, and `reply` actions directly to the OOXML tree.
61
+ - **Whole-Text Revision**: Hand back the complete revised clean text and let the engine diff it against the document and write the tracked changes, behind a post-apply verification gate.
62
+ - **Structured Diffs**: emit a diff as a ready-to-apply `DocumentChange` array, not just text.
63
+ - **Salvage Batches**: Optionally keep the changes that validate and get every failure reported with its 0-based index, instead of an all-or-nothing rejection.
57
64
  - **Targeted Multi-Occurrence Writes**: `match_mode` (`strict`/`first`/`all`) and `regex` support for surgical or sweeping replacements.
58
65
  - **Document Sanitization**: Strip metadata, auto-accept markup, and apply read-only locks before sending to counterparties.
59
66
 
@@ -61,7 +68,7 @@ Restart your n8n instance after installation.
61
68
 
62
69
  ## ⚙️ Operations
63
70
 
64
- The node exposes one resource (**Document**) with six operations:
71
+ The node exposes one resource (**Document**) with seven operations:
65
72
 
66
73
  ### 1. Extract Markdown
67
74
  Projects a `.docx` file into LLM-friendly Markdown.
@@ -70,6 +77,7 @@ Projects a `.docx` file into LLM-friendly Markdown.
70
77
  - **Clean View toggle**:
71
78
  - `False` (Raw View): Shows all pending tracked changes via CriticMarkup. Best for resolving counterparty edits.
72
79
  - `True` (Clean View): Simulates an "Accept All" state, hiding markup. Best for generating net-new redlines on a clean baseline.
80
+ - **Include Appendix** (boolean, default `true`): whether to append the Structural Appendix (defined terms, cross-reference anchors, potential typos). Turn it off to save context when you only need body text.
73
81
  - **🆕 Page parameter**: Optional 1-based page number. When `0` (default), the full document is returned. When `>= 1`, only that page's content is returned and the JSON includes `{ page, total_pages, has_next, has_prev, tracked_change_count }`. Pages are ~19,000-character chunks of the projected body; the Structural Appendix is appended to every page. Use **Extract Outline** first to discover how many pages exist.
74
82
 
75
83
  ### 2. Extract Outline 🆕
@@ -81,6 +89,7 @@ Returns a token-cheap structural map of the document — essentially a table of
81
89
  "level": 2,
82
90
  "text": "Confidentiality",
83
91
  "page": 1,
92
+ "end_page": 3,
84
93
  "style": "Heading 2",
85
94
  "has_table": false,
86
95
  "footnote_ids": ["fn-1", "fn-3"]
@@ -89,6 +98,7 @@ Returns a token-cheap structural map of the document — essentially a table of
89
98
  - `level` (1–6): Heading depth.
90
99
  - `text`: Heading text with markdown/CriticMarkup stripped.
91
100
  - `page`: Which Extract Markdown page this heading lands on.
101
+ - `end_page`: Last Extract Markdown page this heading owns — the page before the next heading of the same or shallower level (equal to `page` for single-page sections). Use `page`–`end_page` to read a whole section without guessing.
92
102
  - `style`: Word style name (e.g. `Heading 1`, `Title`) or `(heuristic)` for headings detected purely by typography.
93
103
  - `has_table`: Whether the section directly contains a Word table (does not bubble up to ancestor headings).
94
104
  - `footnote_ids`: Footnote/endnote markers scoped to this section, in document order, e.g. `fn-1`, `en-2`.
@@ -98,7 +108,8 @@ Returns a token-cheap structural map of the document — essentially a table of
98
108
  Applies a JSON array of `DocumentChange` operations back to the Word document as tracked changes and comments.
99
109
  - **Input**: `.docx` binary + a `changes` JSON array (read from an upstream node or defined inline).
100
110
  - **Output**: A new redlined `.docx` binary + JSON application stats with per-edit reports (status, occurrences modified, heading path, pages affected, CriticMarkup context, post-accept preview).
101
- - **Atomic Batch Validation**: Adeu pre-validates the *entire* array of edits before touching the document. If even one edit is invalid (e.g., target text not found, ambiguous match), the engine safely rejects the entire batch to prevent partial or corrupted document states.
111
+ - **Atomic Batch Validation** (default): Adeu pre-validates the *entire* array of edits before touching the document. If even one edit is invalid (e.g., target text not found, ambiguous match), the engine safely rejects the entire batch to prevent partial or corrupted document states.
112
+ - **Allow Partial Application** (opt-in salvage mode, default `false`): Set this boolean on the node to keep the edits that validate and report the ones that fail instead of rejecting the whole batch. See **Transactional Batches** below.
102
113
 
103
114
  #### 🆕 Targeted Multi-Occurrence Writes (`match_mode` + `regex`)
104
115
  The `modify` edit type now supports two optional fields:
@@ -128,25 +139,72 @@ The `modify` edit type now supports two optional fields:
128
139
  ```
129
140
 
130
141
  #### 🔍 Transactional Batches (Self-Correction for AI Agents)
131
- `Apply Edits` is all-or-nothing: if any single edit fails validation (target text not found, ambiguous match, read-only target, overlapping another author's change), the engine throws a `BatchValidationError` atomically and the document is left untouched. The error message names the failing edit and explains why it failed, so an agent can correct just that edit and re-call — no separate preview round trip is needed.
132
-
133
- ### 4. Generate Diff
134
- Produces a sub-word level `@@ Word Patch @@` diff between two versions of a document.
135
- - **Input**: Two `.docx` binaries on the same item (e.g., `data` and `data2`).
136
- - **Output**: JSON `{ diff, originalFileName, modifiedFileName }`.
137
-
138
- ### 5. Finalize Document
142
+ By default (`Allow Partial Application` off), `Apply Edits` is all-or-nothing: if any single edit fails validation (target text not found, ambiguous match, read-only target, overlapping another author's change), the engine throws a `BatchValidationError` atomically and the document is left untouched. The error message names the failing edit and explains why it failed, so an agent can correct just that edit and re-call — no separate preview round trip is needed.
143
+
144
+ - **Failure blame**: When a batch is rejected, the thrown error's description names each failing change by its 0-based index and repeats the two-call recovery protocol (re-apply the batch without the failing changes, then fix those separately in a small batch).
145
+ - **Author impersonation warning**: `stats.author_impersonation_warning` is set when the `Author` you configured matches an author who already has pending revisions in the document — a redline that would be indistinguishable from theirs in Word's review pane.
146
+ - **Stale ids**: If an `accept`/`reject`/`reply` names an id that no longer exists, the error lists the ids the document actually has and tells you to re-run **Extract Markdown**, because ids shift between document states.
147
+
148
+ #### 🩹 Salvage Mode (`Allow Partial Application`) 🆕
149
+ Turning the node's **Allow Partial Application** boolean on deliberately suspends that transactional guarantee for the call:
150
+
151
+ - Every edit that validates **is applied and saved** — nothing is rolled back because a later edit failed.
152
+ - The output item's top-level `status` reads `"partial"` instead of `"ok"`, so a downstream **If** node can branch on it without digging into `stats`.
153
+ - `stats.failed` lists each rejected edit as `{ index, reason, error }`, where `index` is the edit's **0-based** position in the array you submitted. `stats.edits_applied` / `stats.edits_skipped` give the totals.
154
+ - Failed edits (and `accept`/`reject`/`reply` actions whose `target_id` is stale) no longer throw, so the node does **not** halt — the redlined `.docx` binary is still produced from the edits that landed.
155
+ - Malformed batches are still rejected outright, even in salvage mode: pre-flight shape errors on review actions (an empty `reply` text, two contradictory resolutions of the same `target_id`) fail the whole call, because they signal a broken batch rather than an edit that missed its anchor.
156
+
157
+ Use it for AI Agent loops that will read `stats.failed`, fix the rejected edits, and resubmit them against the returned draft (pass `redlinedBinaryId` back in as `Source Binary ID`). Do **not** use it where a half-applied redline could be shipped as final — leave the default off and let the batch fail loudly instead.
158
+
159
+ ### 4. Apply Text Revision 🆕
160
+ Applies a whole revised document text as tracked changes.
161
+ - **Input**: `.docx` binary + `Revised Text` — the **complete** clean text of the document.
162
+ - **Author** (default `Adeu AI`): author name attached to every tracked change produced by this revision.
163
+ - **Output Binary Property** (default `data`): property name on the outgoing item to receive the redlined `.docx` file.
164
+ - **Output**: A new redlined `.docx` binary on `Output Binary Property` + JSON `{ fileName, author, stats, reasoning?, redlinedBinaryId? }`. Both trailing keys are conditional: `reasoning` is echoed back verbatim whenever the **Reasoning** field is non-empty (the `$fromAI` recipe below binds it, so agent calls normally receive it) and is omitted when it is blank; `redlinedBinaryId` is present only under AI Agent tool execution, for cumulative multi-turn editing.
165
+ - **How to produce `Revised Text`**: Call **Extract Markdown** with `Clean View` on and `Page` `0`, edit that text, and send all of it back. The engine diffs it against the document's own clean view and writes the difference as native Word tracked changes.
166
+ - **Refusals (nothing is applied)**:
167
+ - CriticMarkup tags (`{++ ++}`, `{-- --}`, `{>> <<}`) in the text — the tool compares against the clean view, so markup would land as literal prose.
168
+ - A single page of a paginated extract — everything absent from the text would be applied as a tracked deletion.
169
+ - A revision deleting more than 50% of the characters (75% under 2,000 characters), unless `Allow Major Deletions` is on.
170
+ - **Verification gate**: after applying, the engine re-reads the document's clean text and compares it with what you sent. If they differ, the operation fails and **no** binary is returned — structure such as headings, table rows, and footnotes cannot be removed by text replacement.
171
+ - **Apply Edits vs Apply Text Revision**: use Apply Edits when you have targeted changes with anchors; use Apply Text Revision when an LLM rewrote the document wholesale and you no longer have per-change anchors.
172
+
173
+ ### 5. Generate Diff
174
+ Produces a sub-word level `@@ Word Patch @@` diff, a unified diff, or structured changes between two versions of a document.
175
+ - **Input**: two `.docx` binaries. Each side has its own source: `Original Document Source` / `Original Source Node Name` / `Original Binary Property` (default `data`) and `Modified Document Source` / `Modified Source Node Name` / `Modified Binary Property` (default `data2`). In `From Connected Input` mode the two binary property names must differ.
176
+ - **Clean View** (boolean, default `true`, unlike Extract Markdown's `false`): compare the Accept-All view of both documents. Set `false` to diff the CriticMarkup projection and audit the tracked changes themselves.
177
+ - **Diff Format** (default `Word Patch`):
178
+ - `Word Patch` (`wordPatch`) — Adeu `@@ Word Patch @@` sub-word text diff. Output JSON `{ originalFileName, modifiedFileName, cleanView, diffFormat, diff, warnings? }`.
179
+ - `Unified Diff` (`unified`) — Git-style unified text diff, same output shape.
180
+ - `Structured Changes (JSON)` (`structuredChanges`) — a JSON array of `DocumentChange` objects that transform original into modified, returned on `changes` (**not** `diff`) so it can be piped straight into **Apply Edits**. Output JSON `{ originalFileName, modifiedFileName, cleanView, diffFormat, changes, warnings? }`.
181
+ - **Identical documents**: both text formats return an explicit `No textual differences found between the documents.` body rather than an empty string.
182
+ - **Media warning**: a text diff cannot see image bytes, so when embedded media differ the `warnings` array is populated and the warning text is prefixed onto `diff`.
183
+
184
+ ### 6. Finalize
139
185
  Prepares a document for signature or external distribution.
186
+ - **Input**: `.docx` binary.
187
+ - **Output**: A new finalized `.docx` binary on `Output Binary Property` (default `data`) + JSON `{ fileName, sanitizeMode, report, reasoning? }`.
188
+ - **Reasoning**: Optional audit-only text explaining why the document is being finalized now. Never forwarded to the engine.
140
189
  - **Modes**:
141
- - `Full`: Strips all metadata and requires all tracked changes/comments to be resolved (or auto-accepted).
142
- - `Keep Markup`: Strips metadata but preserves visible tracked changes. Allows you to override the `Author` name (e.g., change "Adeu AI" to "My Law Firm").
190
+ - `Full`: Strips all metadata and requires all tracked changes/comments to be resolved (or auto-accepted via `Accept All Tracked Changes`). If `acceptAll` is `false` and pending changes exist, the operation **throws** rather than producing a file.
191
+ - `Keep Markup`: Strips metadata but preserves visible tracked changes and comments. Allows you to override the `Author` name via `Author Override` (e.g., change "Adeu AI" to "My Law Firm").
143
192
  - `Baseline`: Only strips background noise (RSIDs, proof errors) without touching metadata.
144
- - **Protection**: Can inject a native Word "Read-Only" lock into the document settings.
193
+ - **Accept All Tracked Changes**: (boolean, default `false`) only shows and applies under `Sanitize Mode: full`.
194
+ - **Author Override**: (string, optional) only shows and applies under `Sanitize Mode: keep-markup`.
195
+ - **Protection**: Can inject a native Word "Read-Only" lock into the document settings (`none` or `read_only`).
145
196
 
146
- ### 6. Hydrate Tool Output (The "Hydration" Note)
197
+ ### 7. Hydrate Tool Output (The "Hydration" Note)
147
198
  Because n8n's AI Agent tool wrapper intercepts and **strips all binary data** from tool outputs, files generated inside an AI loop cannot reach downstream nodes directly.
148
- - **What it does**: This operation is placed immediately downstream of the AI Agent on the main workflow execution line. It reads the stashed metadata pointer left by the last execution of `apply_edits`, retrieves the raw file stream directly from n8n's secure binary storage, and attaches a fresh binary buffer onto the outgoing item.
149
- - **Output Path Construction**: It supports an optional output path template (e.g., `C:\path\to\folder\{baseName}_{timestamp}.docx`) to resolve path strings inside TypeScript. This avoids expression-parsing and escape issues when configuring downstream Write File nodes on Windows.
199
+ - **What it does**: This operation is placed immediately downstream of the AI Agent on the main workflow execution line. It reads the stashed metadata pointer (`adeu_last_redlined`) left by the last execution of a redline operation (`Apply Edits` or `Apply Text Revision`), retrieves the raw file stream directly from n8n's secure binary storage, and attaches a fresh binary buffer onto the outgoing item.
200
+ - **Parameters**:
201
+ - **Static Data Key** (default `adeu_last_redlined`): key in workflow global static data to read the stashed binary metadata pointer from.
202
+ - **Output Binary Property** (default `data`): property name on the outgoing item to receive the hydrated binary.
203
+ - **On Missing** (`Emit Empty` | `Throw`, default `Emit Empty`): `Emit Empty` emits `{ hydrated: false }` with no binary so a downstream **If** node can gate the write; `Throw` raises a `NodeOperationError` (for deterministic pipelines where the stash must be present).
204
+ - **Clear After Read** (boolean, default `true`): deletes the stash entry after successful hydration so it cannot leak into the next run.
205
+ - **Output Path Template** (optional string): template to compute the final write path on disk, returned on the output JSON as `outputPath`. Supports placeholders: `{baseName}` (filename with extension stripped), `{timestamp}` (ISO 8601 with `:` and `.` replaced by `-`), `{fileName}` (full filename), and `{ext}` (e.g. `.docx`).
206
+ - **Output**: JSON `{ hydrated: true, fileName, sourceBinaryId, mimeType, outputPath? }` (or `{ hydrated: false }` when missing under `Emit Empty`) + hydrated binary on `Output Binary Property`.
207
+ - **Note**: This operation is never used as an AI Agent tool, so it has no `$fromAI` recipes — configure it in the node editor.
150
208
 
151
209
  ---
152
210
 
@@ -194,9 +252,9 @@ To use the **Apply Edits** operation, your LLM must output a JSON array of objec
194
252
  When an AI Agent applies edits, receives feedback, and needs to make *another* round of changes, loading from the original node name (e.g., `'Read Binary File'`) would discard the modifications just made. To allow the model to chain consecutive edits seamlessly, the node utilizes an **explicit state pointer pipeline**:
195
253
 
196
254
  1. **First Tool Call**: The LLM loads from the baseline. It sets `Source_Node_Name` to the canvas node (e.g., `'Read Binary File'`) and leaves `Source_Binary_Id` blank.
197
- 2. **Intermediate Output**: The `apply_edits` tool applies changes and returns a unique `redlinedBinaryId` (representing the immutable state of that edit) back in the JSON payload to the LLM.
255
+ 2. **Intermediate Output**: The redline tools (`Apply Edits` and `Apply Text Revision`) apply changes and return a unique `redlinedBinaryId` (representing the immutable state of that edit) back in the JSON payload to the LLM.
198
256
  3. **Subsequent Tool Calls**: If the LLM needs to make further changes on top of its prior work, it must set `Source_Binary_Id` to the ID string returned by the previous call. The node's backend dynamically detects this ID, bypasses the upstream node name, and pulls the intermediate document directly from storage to apply the new changes cumulatively.
199
- 4. **Handoff**: On every successful execution, the node overwrites a global static pointer (`adeu_last_redlined`) with the newest ID. When the AI Agent finishes its entire chat turn, the downstream `Hydrate Tool Output` node reads this pointer to output the final, fully-cumulative document.
257
+ 4. **Handoff**: On every successful execution of a redline operation (`Apply Edits` or `Apply Text Revision`), the node overwrites a global static pointer (`adeu_last_redlined`) with the newest ID. When the AI Agent finishes its entire chat turn, the downstream `Hydrate Tool Output` node reads this pointer to output the final, fully-cumulative document.
200
258
 
201
259
  ---
202
260
 
@@ -237,6 +295,15 @@ To achieve the highest batch success rate when prompting models like Gemini, GPT
237
295
 
238
296
  ## 🤖 AI Agent Tool Setup: `$fromAI` Recipes
239
297
 
298
+ ### How the tool node is created
299
+
300
+ This package ships exactly one node class. Because it declares `usableAsTool: true`, n8n generates the AI-tool variant itself at load time: it appends `Tool` to the node's name, empties its main input, and gives it a single `ai_tool` output. There is **no** source file, no separate export, and nothing to install for the tool version. Consequences worth knowing:
301
+
302
+ - In an exported workflow JSON the two legal `type` values are `n8n-nodes-adeu.adeu` (main line) and `n8n-nodes-adeu.adeuTool` (connected to an AI Agent's `ai_tool` port). Both are `typeVersion: 1`.
303
+ - n8n also injects two parameters that exist only on the tool variant: **Tool Description** (`descriptionType`, `auto` | `manual`, default `auto`) and **Description** (`toolDescription`). Leave `descriptionType` on `auto` and the model receives only a stub like *"Apply tracked changes to document in Adeu"*. Set it to **Set Manually** and write a real description — the tool description is what makes the model choose the right tool at all, and it is separate from the per-parameter `$fromAI` descriptions below.
304
+ - Every tool node must keep at least one `$fromAI()` binding. Google Gemini rejects a tool with zero dynamic parameters outright ("Google Gemini requires at least one dynamic parameter when using tools").
305
+ - `Hydrate Tool Output` is the exception: it is never a tool. It runs on the main line after the Agent.
306
+
240
307
  When wiring this node into an AI Agent as a tool, n8n auto-generates `$fromAI()` expressions for AI-bindable fields. The **second argument** of `$fromAI` is the only per-parameter schema description the LLM actually receives — but n8n does **not** propagate node-source `description` metadata into that slot. Auto-generated stubs look like:
241
308
 
242
309
  ```
@@ -257,8 +324,13 @@ Some fields are **plumbing** — they configure which input/output port the node
257
324
 
258
325
  - **`Document Source`** (`fromInput` vs `fromNode`) — workflow topology decision.
259
326
  - **`Input Binary Property`** — wiring decision; downstream of the source node, not per-call.
260
- - **`Output Binary Property`** (Apply Edits, Finalize Document) — names where the outgoing binary lands on the workflow item. Downstream nodes need this fixed; an LLM picking `output_data` one call and `result` the next would break the pipeline. Default `'data'` is almost always correct.
327
+ - **`Output Binary Property`** (Apply Edits, Apply Text Revision, Finalize) — names where the outgoing binary lands on the workflow item. Downstream nodes need this fixed; an LLM picking `output_data` one call and `result` the next would break the pipeline. Default `'data'` is almost always correct.
261
328
  - **`Edits Source`** (Apply Edits) — controls whether the node reads the changes array from the `Changes (JSON)` field on the node itself (`defineBelow`) or from a property on the upstream item (`fromInputJson`). For AI Agent workflows, **set this to `Define Below` in the editor**. This is what activates the `Changes (JSON)` field as the LLM's entry point — the recipe in the Apply Edits section below populates that field via `$fromAI`, and the LLM hands its generated `Changes_JSON` string directly to the tool as a call argument. The `fromInputJson` branch is only for deterministic pipelines where an upstream non-AI node has pre-populated a `changes` property on the item.
329
+ - **`Allow Partial Application`** (Apply Edits) — decides whether a flawed batch is rejected wholesale or half-applied. That is your risk policy for the workflow, not a per-call choice; an LLM that can switch it on will switch it on to make its own errors disappear. Leave it `false` unless the workflow is an agent loop that resubmits the failures.
330
+ - **`Allow Major Deletions`** (Apply Text Revision) — decides whether a revision deleting >50% of the document is allowed. That is your risk policy for the workflow, not a per-call choice. Leave it `false` unless whole-document truncation is intended.
331
+ - **`Original Binary Property`** / **`Modified Binary Property`** (Generate Diff) — wiring, same reasoning as `Input Binary Property`.
332
+ - **`Static Data Key`**, **`On Missing`**, **`Clear After Read`**, **`Output Path Template`** (Hydrate Tool Output) — the whole operation is main-line only.
333
+ - **`Tool Description`** / **`Description`** (`descriptionType` / `toolDescription`) — these describe the tool *to* the model; binding them to the model is circular.
262
334
 
263
335
  AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that's why `fromNode` exists: it resolves the binary from a named upstream node (e.g. `Read Binary File`, `Gmail Trigger`) at execution time. The trigger source is `$fromAI`-bindable below because a system prompt can legitimately offer the LLM a choice between multiple binary-producing nodes.
264
336
 
@@ -281,6 +353,11 @@ AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that
281
353
  ={{ $fromAI('Clean_View', `Boolean. Set false (default) to surface all pending tracked changes as CriticMarkup tags {++ins++}, {--del--}, {>>comment<<} — use when reviewing counterparty edits or any document with pending markup. Set true to project the document as if all tracked changes were accepted (simulates Accept All) — use only when generating net-new redlines against a clean baseline.`, 'boolean', false) }}
282
354
  ```
283
355
 
356
+ **Include Appendix:**
357
+ ```
358
+ ={{ $fromAI('Include_Appendix', `Boolean, default true. Whether to append the Structural Appendix — the list of defined terms, cross-reference anchors, and likely typos found in the document. Keep true when you need to reason about definitions or internal references. Set false only to save context when you want body text alone.`, 'boolean', true) }}
359
+ ```
360
+
284
361
  **Page** 🆕:
285
362
  ```
286
363
  ={{ $fromAI('Page', `Optional 1-based integer page number to retrieve only one page of the projected document. Set to 0 (default) for the full document body — use 0 for short documents (under ~10 pages). For long documents, call extract_outline first to discover total_pages and which headings live on which page, then call this tool again with Page set to the page you need. Pages are ~19,000-character chunks; the Structural Appendix is appended to every page. If you request a page beyond total_pages the tool will error.`, 'number', 0) }}
@@ -326,7 +403,7 @@ AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that
326
403
 
327
404
  **Changes (JSON):**
328
405
  ```
329
- ={{ $fromAI('Changes_JSON', `JSON-encoded string containing an array of DocumentChange objects. Each object is one of: {"type":"modify","target_text":"<verbatim from source>","new_text":"<replacement>","comment":"<optional>","match_mode":"<optional 'strict' (default) | 'first' | 'all'>","regex":<optional boolean default false>} | {"type":"accept","target_id":"Chg:12","comment":"<optional>"} | {"type":"reject","target_id":"Chg:12","comment":"<optional>"} | {"type":"reply","target_id":"Com:45","text":"<reply>"} | {"type":"insert_row","target_text":"<cell text anchoring row>","position":"above" or "below","cells":["col1","col2"]} | {"type":"delete_row","target_text":"<cell text anchoring row>"}. MODIFY EXTENDED: set match_mode='all' to replace every occurrence of target_text in linear document order (returns occurrences_modified in the per-edit report); set match_mode='first' to silently anchor to the first hit; omit or use 'strict' (default) to fail on ambiguous matches so you can self-correct with more context. Set regex=true to interpret target_text as an ES2022 RegExp pattern; new_text may reference capture groups via $1, $2 etc. Combine match_mode='all' with regex=true for global pattern-based replacements. RULES: target_text must be copied VERBATIM from the source including punctuation/whitespace/case (unless regex=true) and must uniquely anchor one location under match_mode='strict'; never include CriticMarkup tags like {++ or {-- in new_text — the engine applies tracking automatically; use Chg:N and Com:N IDs exactly as surfaced by extract_markdown; the entire array must be a single JSON-encoded string. Atomic batch: if any single edit is invalid the whole array is rejected with an error telling you which edit failed — use that to self-correct on the next call.`, 'string') }}
406
+ ={{ $fromAI('Changes_JSON', `JSON-encoded string containing an array of DocumentChange objects. Each object is one of: {"type":"modify","target_text":"<verbatim from source>","new_text":"<replacement>","comment":"<optional>","match_mode":"<optional 'strict' (default) | 'first' | 'all'>","regex":<optional boolean default false>} | {"type":"accept","target_id":"Chg:12","comment":"<optional>"} | {"type":"reject","target_id":"Chg:12","comment":"<optional>"} | {"type":"reply","target_id":"Com:45","text":"<reply>"} | {"type":"insert_row","target_text":"<cell text anchoring row>","position":"above" or "below","cells":["col1","col2"]} | {"type":"delete_row","target_text":"<cell text anchoring row>"}. MODIFY EXTENDED: set match_mode='all' to replace every occurrence of target_text in linear document order (returns occurrences_modified in the per-edit report); set match_mode='first' to silently anchor to the first hit; omit or use 'strict' (default) to fail on ambiguous matches so you can self-correct with more context. Set regex=true to interpret target_text as an ES2022 RegExp pattern; new_text may reference capture groups via $1, $2 etc. Combine match_mode='all' with regex=true for global pattern-based replacements. RULES: target_text must be copied VERBATIM from the source including punctuation/whitespace/case (unless regex=true) and must uniquely anchor one location under match_mode='strict'; never include CriticMarkup tags like {++ or {-- in new_text — the engine applies tracking automatically; use Chg:N and Com:N IDs exactly as surfaced by extract_markdown; the entire array must be a single JSON-encoded string. Atomic batch: if any single edit is invalid the whole array is rejected with an error telling you which edit failed — use that to self-correct on the next call. (If the node has 'Allow Partial Application' enabled, the valid edits are applied instead and the rejected ones come back in stats.failed with their 0-based index — fix those and resubmit them against the returned draft.)`, 'string') }}
330
407
  ```
331
408
 
332
409
  **Return Markdown Output:**
@@ -336,6 +413,35 @@ AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that
336
413
 
337
414
  ---
338
415
 
416
+ ### Apply Text Revision 🆕
417
+
418
+ **Reasoning** (fill this FIRST):
419
+ ```
420
+ ={{ $fromAI('Reasoning', `State your reasoning for this revision BEFORE providing the revised text: what you intend to change, why the changes are being made, and which sections or clauses are affected. Always write this field first. This text is captured for audit only and does not alter engine behavior. One to three sentences is enough.`, 'string', '') }}
421
+ ```
422
+
423
+ **Source Node Name** (when `Document Source` is `From Another Node`):
424
+ ```
425
+ ={{ $fromAI('Source_Node_Name', `Exact name of the workflow node that produced the .docx binary (string, case-sensitive). Must match the node label in the canvas exactly. If your system prompt specifies which node holds the document, always use that name.`, 'string', 'Read Binary File') }}
426
+ ```
427
+
428
+ **Source Binary ID** (when `Document Source` is `From Another Node`):
429
+ ```
430
+ ={{ $fromAI('Source_Binary_Id', `Optional string. If you are doing consecutive revisions on the same document during this conversation, pass the 'redlinedBinaryId' from the previous tool output here to continue editing the updated draft. Leave blank on your first tool call.`, 'string', '') }}
431
+ ```
432
+
433
+ **Author:**
434
+ ```
435
+ ={{ $fromAI('Author', `Author name attached to every tracked change this revision produces (string, e.g. 'AI Reviewer' or 'Acme Legal AI'). Appears in Word's review pane as the author of each redline.`, 'string', 'Adeu AI') }}
436
+ ```
437
+
438
+ **Revised Text:**
439
+ ```
440
+ ={{ $fromAI('Revised_Text', `The COMPLETE revised clean text of the document. Read it first with Extract Markdown using Clean View on and Page 0 (whole document), edit that text, then send all of it back — the engine diffs this against the document's clean view and turns the difference into tracked changes. Never include CriticMarkup tags like {++ or {-- in the text — they are rejected. Never send a single page of a paginated extract — everything missing from this text is applied as a tracked deletion. A revision deleting more than 50% of the characters (75% under 2,000 characters) is refused unless Allow Major Deletions is on. After applying, the engine verifies that the document's clean text matches this value; if they differ, the operation fails.`, 'string') }}
441
+ ```
442
+
443
+ ---
444
+
339
445
  ### Generate Diff
340
446
 
341
447
  **Original Source Node Name** (when `Original Document Source` is `From Another Node`):
@@ -353,9 +459,14 @@ AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that
353
459
  ={{ $fromAI('Clean_View', `Boolean. Set true (recommended default) to compare the Accept All clean view of both documents — diffs reflect final content as if all tracked changes were accepted. Set false to diff the raw CriticMarkup-projected text including pending change markers — useful for auditing tracked-change differences themselves.`, 'boolean', true) }}
354
460
  ```
355
461
 
462
+ **Diff Format:**
463
+ ```
464
+ ={{ $fromAI('Diff_Format', `One of 'wordPatch', 'unified', or 'structuredChanges'. 'wordPatch' (default) returns an Adeu @@ Word Patch @@ sub-word text diff on the 'diff' field — best for reading and explaining what changed. 'unified' returns a Git-style unified text diff on 'diff'. 'structuredChanges' returns a JSON array of DocumentChange objects on the 'changes' field instead of 'diff' — use it when you intend to feed the difference straight into apply_edits rather than describe it.`, 'string', 'wordPatch') }}
465
+ ```
466
+
356
467
  ---
357
468
 
358
- ### Finalize Document
469
+ ### Finalize
359
470
 
360
471
  **Reasoning** (fill this FIRST):
361
472
  ```
@@ -398,15 +509,31 @@ AI Agents cannot pass binary `.docx` data through JSON arguments anyway — that
398
509
 
399
510
  ---
400
511
 
512
+ ## 📂 Example Workflows
513
+
514
+ Two importable workflows ship in [`examples/`](./examples). Neither can be run outside n8n: download the JSON, then in n8n use **Workflows → Import from File**.
515
+
516
+ **`Sequential_workflow.json` — deterministic two-turn redline.**
517
+ Manual Trigger → Read/Write Files (read) → Adeu *Extract Markdown* (Clean View on) → Code (build Gemini payload) → HTTP Request → Code (parse the `DocumentChange` array) → Adeu *Apply Edits* (`Edits Source: From Input JSON`) → Adeu *Extract Markdown* (raw view, reading from the previous Adeu node by name) → Code → HTTP Request → Code → Adeu *Apply Edits* (`accept`/`reply` actions) → Read/Write Files (write). No AI Agent, no tool nodes — this is the pattern to copy when you want a repeatable pipeline instead of an agent. **Before running:** set the two file paths and your Gemini API key and model id.
518
+
519
+ **`AI_Agent_workflow.json` — conversational agent with three tools.**
520
+ Chat Trigger → Read/Write Files (read) → Set (*Restore Chat Context*, because the file-read node drops `chatInput`/`sessionId`) → AI Agent, with `extract_outline`, `extract_markdown` and `apply_edits` on the `ai_tool` port and a Gemini chat model plus a buffer-window memory attached. After the Agent: Adeu *Hydrate Tool Output* → If (`{{ $json.hydrated }}`) → Read/Write Files (write). **Before running:** set the input file path, the output directory in `Output Path Template`, and pick your Gemini credential and model.
521
+
522
+ **What the examples deliberately do not cover:** `Apply Text Revision`, `Generate Diff`, and `Finalize`. Their `$fromAI` recipes above are complete; wire them the same way as the three tools in the agent example (`Document Source: From Another Node`, `descriptionType: Set Manually`).
523
+
524
+ **Node names are load-bearing.** The agent example's tools resolve the document with `Source_Node_Name: 'Read Binary File'`. Rename that node on the canvas and every tool call fails until you update the `$fromAI` default and the system message. The tool names the model sees are the canvas node names themselves.
525
+
526
+ ---
527
+
401
528
  ## 🛠️ Error Handling & Troubleshooting
402
529
 
403
- Because Adeu enforces **Atomic Batch Validation**, any error in the LLM's JSON will throw a `NodeApiError` and halt the node. The error message will tell you exactly which edit failed and why.
530
+ Because Adeu enforces **Atomic Batch Validation** by default, any error in the LLM's JSON will throw a `NodeApiError` and halt the node. The error message will tell you exactly which edit failed and why. (With **Allow Partial Application** enabled the node does not halt: the valid edits are saved, `status` reads `"partial"`, and the same messages arrive in `stats.failed` keyed by 0-based edit index — the causes below read the same either way.)
404
531
 
405
532
  * **"Target text not found"**: The LLM hallucinated a word, altered the spacing, or the text doesn't exist in the baseline document.
406
533
  * **"Ambiguous match"**: The LLM used a `target_text` (like "the Company") that appears multiple times. The error details will show you the exact occurrences. Advise the LLM to either include more surrounding context (e.g., "the Company shall indemnify") or use `match_mode: "all"` if the intent is to replace every occurrence.
407
534
  * **"Modification targets an active insertion..."**: The LLM tried to `modify` text that another author is currently tracking. Adeu explicitly blocks this to maintain virtual DOM integrity and clean redline threading. You must `accept` or `reject` that prior change first. (Editing plain text that merely sits under another author's *comment* is allowed — the comment anchor survives the tracked change.)
408
535
  * **"...would sweep through a comment range from another author..."**: A `match_mode: "all"` bulk replacement crossed a colleague's comment range. Blind fan-outs are blocked to protect foreign annotations; target the commented text deliberately with `match_mode: "strict"` or `"first"`, or scope the edit outside the comment.
409
536
  * **"Read-only elements"**: The LLM tried to modify structural items like cross-references or footnotes.
410
- * **"Page N exceeds total_pages"**: The LLM requested a page beyond what the document has. Have it call `Extract Outline` first to discover the page count.
537
+ * **"Requested page N exceeds total_pages (M). Call extractOutline to discover the page count first."**: The LLM requested a page beyond what the document has. Have it call `Extract Outline` first to discover the page count.
411
538
 
412
- **Tip**: If you are running bulk processing workflows, you can enable n8n's **"Continue On Fail"** setting on the `Apply Edits` node. If the LLM generates a flawed batch, n8n will catch the error, output an `{ "error": "..." }` JSON object for that specific document, and continue processing the rest of the files in your queue.
539
+ **Tip**: If you are running bulk processing workflows, you can enable n8n's **"Continue On Fail"** setting on the `Apply Edits` node. If the LLM generates a flawed batch, n8n will catch the error, output an `{ "error": "..." }` JSON object for that specific document, and continue processing the rest of the files in your queue. If you would rather keep the good edits from a flawed batch than lose the document entirely, enable **Allow Partial Application** instead (see *Salvage Mode* above) — you then get a redlined file plus `stats.failed` rather than an error object.