docs: document stable block addressing for headless workflows (SD-2069) (#2234)

* docs: document stable block addressing for headless workflows

SD-2069: The Document API already resolves paraId-first (stable across
loads) over sdBlockId (volatile), but nothing in the docs told users
this. Add node addressing docs, cross-session workflow example, warn
about sdBlockId volatility in Block Node docs, and reference Document
API from the AI Agents page.

* chore: clarify stability of paraId

Author: caio-pizzol

apps/docs/document-api/common-workflows.mdx

@@ -131,6 +131,52 @@ if (caps.global.trackChanges.enabled) {
 }
 ```
 
+## Cross-session block addressing
+
+When you load a DOCX, close the editor, and load the same file again, `sdBlockId` values change — they're regenerated on every open. The Document API's `find` operation returns addresses whose `nodeId` prefers DOCX-native `paraId`, which is usually stable when reopening the same unchanged DOCX.
+
+This pattern is common in headless pipelines: extract block references in one session, then apply edits in another.
+
+```ts
+import { Editor } from 'superdoc/super-editor';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const docx = await readFile('./contract.docx');
+
+// Session 1: extract block addresses
+const editor1 = await Editor.open(docx);
+const result = editor1.doc.find({
+  select: { type: 'node', nodeType: 'paragraph' },
+  includeNodes: true,
+});
+
+// Save addresses — for DOCX-imported blocks, nodeId uses paraId when available
+const addresses = result.items.map((item) => ({
+  address: item.address,
+  text: item.node?.text,
+}));
+await writeFile('./blocks.json', JSON.stringify(addresses));
+editor1.destroy();
+
+// Session 2: load the same file again and apply edits
+const editor2 = await Editor.open(docx);
+const saved = JSON.parse(await readFile('./blocks.json', 'utf-8'));
+
+// Addresses from session 1 usually resolve when reloading the same unchanged DOCX
+for (const { address } of saved) {
+  const node = editor2.doc.getNode(address); // works across sessions
+}
+editor2.destroy();
+```
+
+<Info>
+`nodeId` stability depends on the ID source. For DOCX-imported content, `nodeId` comes from `paraId` when available and is best-effort stable across loads. For nodes created at runtime, it falls back to `sdBlockId`, which is volatile.
+</Info>
+
+<Warning>
+No ID is guaranteed to survive all Microsoft Word round-trips. Re-extract addresses after major external edits or transformations, since Word (or other tools) may rewrite paragraph IDs and SuperDoc may rewrite duplicate IDs on import.
+</Warning>
+
 ## Dry-run preview
 
 Pass `dryRun: true` to validate an operation without applying it:

apps/docs/document-api/overview.mdx

@@ -17,3 +17,33 @@ Document API is in <strong>alpha</strong> and subject to breaking changes while
 - Work with predictable inputs and outputs defined per operation.
 - Check capabilities up front and branch safely when features are unavailable.
 
+## Node addressing
+
+Every block in a document has a `nodeId` — a string that uniquely identifies it. When you call `find` or `getNodeById`, addresses use this ID:
+
+```json
+{
+  "kind": "block",
+  "nodeType": "paragraph",
+  "nodeId": "3A2B1C0D"
+}
+```
+
+### Stable IDs across loads
+
+For DOCX documents, `nodeId` is derived from the file's native `w14:paraId` attribute. In practice, this is usually stable when you reopen the same unchanged DOCX across separate editor sessions, machines, or headless CLI pipelines.
+
+For nodes created at runtime (not imported from DOCX), `nodeId` falls back to `sdBlockId`, a UUID generated when the editor opens. This fallback is volatile and changes on every load.
+
+| ID source | Stable across loads? | When used |
+|-----------|---------------------|-----------|
+| `paraId` (from DOCX) | Best effort (usually stable for unchanged DOCX blocks) | Paragraphs, tables, rows, cells imported from DOCX |
+| `sdBlockId` (runtime) | No (session-scoped) | Nodes created programmatically before first export |
+
+<Tip>
+If you need to reference blocks across separate editor sessions, use `editor.doc.find()` to get addresses — don't read `node.attrs.sdBlockId` directly. The Document API resolves `paraId` first for DOCX-imported content.
+</Tip>
+
+<Warning>
+No block ID is guaranteed to survive all Microsoft Word round-trips or external document rewrites. Word and other tools may regenerate `w14:paraId` during structural changes (for example split/merge/rebuild operations), and SuperDoc may rewrite duplicate IDs on import to keep block targeting deterministic.
+</Warning>

apps/docs/getting-started/ai-agents.mdx

@@ -80,6 +80,56 @@ const redlined = await editor.exportDocx();
 ```
 </CodeGroup>
 
+## Programmatic block access
+
+For multi-step workflows — extract block references, send them to an LLM, then apply edits — use the [Document API](/document-api/overview). It returns stable block addresses that work across separate editor sessions:
+
+<CodeGroup>
+```javascript Usage
+// Find all paragraphs and their text
+const result = editor.doc.find({
+  select: { type: 'node', nodeType: 'paragraph' },
+  includeNodes: true,
+});
+
+// Each item has an address with a best-effort stable nodeId
+const blocks = result.items.map((item) => ({
+  id: item.address.nodeId,     // usually stable across loads for unchanged DOCX content
+  type: item.address.nodeType,
+  text: item.node?.text,
+}));
+
+// Send blocks to LLM, get back edits, apply them
+```
+
+```javascript Full Example
+import { readFile } from 'node:fs/promises';
+import { Editor } from 'superdoc/super-editor';
+
+const docx = await readFile('./contract.docx');
+const editor = await Editor.open(docx);
+
+// Find all paragraphs and their text
+const result = editor.doc.find({
+  select: { type: 'node', nodeType: 'paragraph' },
+  includeNodes: true,
+});
+
+// Each item has an address with a best-effort stable nodeId
+const blocks = result.items.map((item) => ({
+  id: item.address.nodeId,     // usually stable across loads for unchanged DOCX content
+  type: item.address.nodeType,
+  text: item.node?.text,
+}));
+
+// Send blocks to LLM, get back edits, apply them
+```
+</CodeGroup>
+
+<Info>
+Block addresses from `doc.find()` prefer DOCX-native IDs (`paraId`) for imported blocks. This is the best available cross-session anchor, but no ID is guaranteed to survive all Word round-trips. Don't read `node.attrs.sdBlockId` directly — it's regenerated on every load.
+</Info>
+
 ## LLM quick reference
 
 Point your AI assistant at these URLs for SuperDoc context:
@@ -92,6 +142,14 @@ https://docs.superdoc.dev/llms-full.txt   // Complete documentation
 ## Next steps
 
 <CardGroup cols={2}>
+  <Card
+    title="Document API"
+    icon="book"
+    href="/document-api/overview"
+  >
+    Stable block addressing, find/replace, and programmatic edits
+  </Card>
+
   <Card
     title="SuperEditor API"
     icon="code"
@@ -108,14 +166,6 @@ https://docs.superdoc.dev/llms-full.txt   // Complete documentation
     Content formats, export options, and round-trip behavior
   </Card>
 
-  <Card
-    title="AI Redlining (Browser)"
-    icon="github"
-    href="https://github.com/superdoc-dev/superdoc/tree/main/examples/features/ai-redlining"
-  >
-    React app: upload a DOCX, LLM reviews it, tracked changes in the UI
-  </Card>
-
   <Card
     title="AI Redlining (Headless)"
     icon="github"

apps/docs/snippets/extensions/block-node.mdx

@@ -124,10 +124,14 @@ Every block-level node (paragraphs, headings, etc.) automatically receives a uni
 3. **Collaborative editing** - Reference blocks consistently across clients
 4. **Programmatic updates** - Update document structure via APIs
 
+<Warning>
+`sdBlockId` is regenerated on every document load. If you need cross-session block references (e.g., headless CLI pipelines, multi-step AI workflows), use the [Document API](/document-api/overview) instead. `editor.doc.find()` returns addresses whose `nodeId` prefers DOCX-native `paraId` for imported blocks. This is best-effort stable, not a permanent global ID: Word or other tools can rewrite IDs during structural changes, and SuperDoc may rewrite duplicates on import.
+</Warning>
+
 ## Use case
 
 - **Document APIs** - Build REST APIs that manipulate specific blocks
 - **Collaboration** - Track who edited which blocks in real-time
 - **Comments & Annotations** - Attach metadata to specific blocks
 - **Version Control** - Diff documents at the block level
-- **Templates** - Replace placeholder blocks with dynamic content
+- **Templates** - Replace placeholder blocks with dynamic content