docs: add content controls page, examples, and demo (IT-1046) (#3265)

* docs: add content controls page, examples, and demo (IT-1046)

Customer asked whether SuperDoc supports composable reusable sections and "smart fields" — placeholders that update everywhere when edited centrally. Both map cleanly to Word content controls (OOXML SDT), and the surface is fully wired in the Document API. Ships two narrow examples plus a composed runtime demo, plus a conceptual docs page so the Document API surface gets the same hand-written narrative the Editor extensions already have.

- examples/document-api/content-controls/smart-fields/ and reusable-section/ each teach one pattern in isolation, copy-pasteable.
- demos/contract-templates/ is a composed workflow that detects stale section versions and applies updates in place. Not yet gallery-ready (homepage: false) pending the lock-mutation fix.
- apps/docs/document-api/features/content-controls.mdx is a new home for hand-written feature narratives, slotted under a new Features sidebar group inside Document API. Frames Template Builder and the raw Document API as two valid paths.
- Document API path is fully editor.doc.*. The same operation set runs headless via the Node SDK and CLI.

Follow-ups: SD-3123 (locked-SDT mutations silently no-op via the legacy command path), SD-3124 (filter-rejected transactions report false success), SD-3125 (imported-controls example with a Word-authored fixture).

* docs: replace content-control examples with one canonical tagged-inline-text (IT-1046)

The first pass shipped two examples (smart-fields, reusable-section) that read as demo decompositions: same primitives as demos/contract-templates, ~200 lines each, with markdown seeds and panel chrome. They didn't earn their place against the demo.

Replaced with one tight example, modelled on examples/editor/custom-ui/selection-capture: smallest readable form of the canonical create-find-update loop, with a README that distinguishes setup mutations from the teaching surface (selectByTag + text.setValue). Sets the template that future content-control examples copy.

- examples/document-api/content-controls/tagged-inline-text/ is the new single example.
- Old smart-fields/, reusable-section/, and the parent README.md removed.
- features/content-controls.mdx Next steps cards updated to point at the new example.
- Manifest and README rows replaced.

* docs: add examples/demos contributor guidance and align styles (IT-1046)

Captures the conventions IT-1046 produced so future contributors don't rediscover them. Examples and demos each get a scoped AGENTS.md (with a CLAUDE.md symlink for compat) defining what belongs in each surface, the cross-surface Document API placement rule, and the "don't ship known-bug or unverified paths" rule that drove the lockMode: 'unlocked' choice in the tagged-inline-text example.

- examples/README.md and demos/README.md rewritten with clear definitions, contributor checklists, and homepage-readiness criteria.
- examples/AGENTS.md (+ CLAUDE.md symlink) covers Document API placement, setup-vs-teaching separation, and verification rules.
- demos/AGENTS.md (+ CLAUDE.md symlink) covers composed-workflow criteria and source-vs-live demo distinction.
- demos/README.md adds contract-templates to the curated demos table.
- demos/contract-templates/README.md calls out its demo status and links back to the tagged-inline-text example.
- tagged-inline-text/README.md notes the lockMode: 'unlocked' choice and points at SD-3123.
- Both style.css files now read from --sd-* tokens with fallbacks, so examples and demos pick up the host SuperDoc theme.

* docs: rewrite content-controls limits sections in customer voice (IT-1046)

Replaces internal-status framing with API guidance. Removes references to engine internals, legacy paths, known bugs, and 'not yet' language.

- Lock modes: behavior table, then concrete guidance for programmatic use.
- Data binding: describe what the API supports and what to drive instead.
- Replacing content: scope replaceContent to plain text and point at doc.insert + contentControls.wrap for richer fragments.

* docs: correct rich-fragment wrap guidance (IT-1046)

contentControls.wrap takes an existing SDT target, not a selection range. Use create.contentControl with an at: SelectionTarget to wrap an inserted range.

Author: caio-pizzol

apps/docs/docs.json

@@ -165,8 +165,12 @@
                 "group": "Document API",
                 "pages": [
                   "document-api/overview",
-                  "document-api/reference/index",
                   "document-api/common-workflows",
+                  {
+                    "group": "Features",
+                    "pages": ["document-api/features/content-controls"]
+                  },
+                  "document-api/reference/index",
                   "document-api/available-operations",
                   "document-api/migration"
                 ]
@@ -292,6 +296,10 @@
     "dismissible": true
   },
   "redirects": [
+    {
+      "source": "/document-api/content-controls",
+      "destination": "/document-api/features/content-controls"
+    },
     {
       "source": "/editor/proofing/overview",
       "destination": "/editor/spell-check/overview"

apps/docs/document-api/features/content-controls.mdx

@@ -0,0 +1,167 @@
+---
+title: Content controls
+sidebarTitle: Content controls
+description: Attach stable, Word-compatible identity to regions of a document and update them programmatically.
+keywords: "content controls, SDT, structured document tags, smart fields, reusable sections, template fields, document automation"
+---
+
+Content controls are Word's native primitive for **stable, identity-bearing regions** inside a document. They survive Word round-trips, carry app-defined metadata in a `tag` string, and can be discovered, updated, locked, or replaced from any surface that drives SuperDoc: the browser editor, the Node SDK, the CLI, an MCP tool, an AI agent.
+
+In OOXML they are `w:sdt` elements (structured document tags). SuperDoc exposes the full surface under `editor.doc.contentControls.*` and `editor.doc.create.contentControl`.
+
+## Two patterns to start
+
+### Smart fields: one value, every occurrence
+
+Wrap every occurrence of a template variable in an inline text content control sharing the same `tag`. Select by tag, then push the same value to each matching control.
+
+```ts
+// Wrap once, at template-authoring time.
+editor.doc.create.contentControl({
+  kind: 'inline',
+  controlType: 'text',
+  at: range,
+  tag: 'customer',
+  alias: 'Customer',
+  lockMode: 'unlocked',
+});
+
+// Push a new value. Every occurrence with tag === 'customer' updates.
+const { items } = editor.doc.contentControls.selectByTag({ tag: 'customer' });
+for (const { target } of items) {
+  editor.doc.contentControls.text.setValue({ target, value: 'Acme Therapeutics' });
+}
+```
+
+Smallest copy-pasteable form: [`examples/document-api/content-controls/tagged-inline-text`](https://github.com/superdoc-dev/superdoc/tree/main/examples/document-api/content-controls/tagged-inline-text).
+
+### Reusable sections: tagged blocks that know their version
+
+Encode `{ sectionId, version }` in the `tag` of a block content control. The app reads the live version from `contentControls.list` and offers an in-place update when the document falls behind the section library.
+
+```ts
+// Wrap a section paragraph as a block content control with a structured tag.
+editor.doc.create.contentControl({
+  kind: 'block',
+  controlType: 'text',
+  at: range,
+  tag: JSON.stringify({ kind: 'reusableSection', sectionId: 'limitation-liability', version: 'v1' }),
+  alias: 'Limitation of liability (v1)',
+  lockMode: 'unlocked',
+});
+
+// On reopen: list sections, parse their tags, compare versions.
+const { items } = editor.doc.contentControls.list({});
+for (const control of items) {
+  const meta = parseTag(control.properties?.tag); // your helper
+  if (meta?.kind === 'reusableSection' && meta.version !== latestVersionFromLibrary(meta.sectionId)) {
+    // Swap content, bump version in tag.
+    editor.doc.contentControls.replaceContent({ target: control.target, content: newBody, format: 'text' });
+    editor.doc.contentControls.patch({
+      target: control.target,
+      tag: JSON.stringify({ ...meta, version: 'v2' }),
+      alias: 'Limitation of liability (v2)',
+    });
+  }
+}
+```
+
+Composed runtime: [`demos/contract-templates`](https://github.com/superdoc-dev/superdoc/tree/main/demos/contract-templates).
+
+## Why `tag`, not `nodeId`
+
+Two channels of identity exist on a content control:
+
+| Channel | Source | Stable across loads | Stable through Word edits |
+|---|---|---|---|
+| `nodeId` | SuperDoc-assigned at parse time | Best-effort | No |
+| `tag` | App-defined, written to OOXML `<w:tag w:val="...">` | Yes | Yes (Word preserves the SDT and its tag) |
+
+Use `nodeId` for in-session targeting. Use `tag` for durable identity that survives DOCX round-trips, including documents edited in Word and reopened. JSON-encode the `tag` when you need to carry structured metadata (kind, version, owner, group).
+
+## Cross-surface: same operations everywhere
+
+Document API content controls are not editor-specific. The same operation IDs are available on every surface that drives SuperDoc.
+
+| Surface | Binding |
+|---|---|
+| Browser editor | `editor.doc.contentControls.*` |
+| Node SDK | bound document handle methods |
+| CLI | `superdoc` commands |
+| MCP / AI tools | tool wrappers around the same operation IDs |
+
+A field updated by your backend job, a clause swapped by an agent, and a value typed by a user in the editor all hit the same engine.
+
+## When to use Template Builder vs Document API
+
+Two valid paths. Both build on Word content controls.
+
+| Use [Template Builder](/solutions/template-builder/introduction) when | Use Document API content controls when |
+|---|---|
+| You're building in React and want a packaged authoring component | You're on vanilla JS, Vue, Angular, or any non-React stack |
+| You want the `{{` trigger menu, field sidebar, linked field groups, and DOCX export wired up out of the box | You need a custom UX (your own field menu, your own sidebar) |
+| Owner/signer field types and inline custom field creation match your workflow | You're operating headless: server-side jobs, AI agents, CLI scripts |
+| You want a shorter path to a working template authoring UI | You need runtime updates against existing tagged regions (smart fields, version-aware section swaps) |
+
+The two paths are not mutually exclusive. A common pattern is Template Builder for authoring, Document API for runtime updates on the authored document.
+
+## Operation reference at a glance
+
+| Concept | Operation |
+|---|---|
+| Create a control around a range | `editor.doc.create.contentControl` |
+| Wrap an existing range | `editor.doc.contentControls.wrap` |
+| Find by tag | `editor.doc.contentControls.selectByTag` |
+| Find by alias | `editor.doc.contentControls.selectByTitle` |
+| List all controls | `editor.doc.contentControls.list` |
+| Inspect one | `editor.doc.contentControls.get` |
+| Update text value | `editor.doc.contentControls.text.setValue` |
+| Replace whole content | `editor.doc.contentControls.replaceContent` |
+| Patch metadata (tag, alias, appearance) | `editor.doc.contentControls.patch` |
+| Set lock mode | `editor.doc.contentControls.setLockMode` |
+| Delete (with content) | `editor.doc.contentControls.delete` |
+| Unwrap (keep content) | `editor.doc.contentControls.unwrap` |
+| Read `sdtPr` directly | `editor.doc.contentControls.getRawProperties` |
+| Edit `sdtPr` directly | `editor.doc.contentControls.patchRawProperties` |
+
+Typed sub-APIs exist for `text.*`, `date.*`, `checkbox.*`, `choiceList.*` (combo/dropdown), `repeatingSection.*`, and `group.*`. See the [reference index](/document-api/reference/content-controls/index) for the full catalog.
+
+## Lock modes
+
+Set `lockMode` when you create a control to govern which changes are allowed.
+
+| Mode | Behavior |
+|---|---|
+| `unlocked` | Content and properties can be updated through the Document API. |
+| `sdtLocked` | The wrapper is preserved through user edits. |
+| `contentLocked` | The content can't be modified through the editor surface. |
+| `sdtContentLocked` | Both wrapper and content are preserved. |
+
+For controls your app drives with `text.setValue`, `replaceContent`, or `patch`, use `lockMode: 'unlocked'`.
+
+## Data binding
+
+Content controls can carry an OOXML `<w:dataBinding>` link to a custom XML data part. Read and write the binding metadata with `contentControls.getBinding`, `setBinding`, and `clearBinding`. The binding survives DOCX round-trips.
+
+For runtime synchronization with backing data, drive the control directly with `text.setValue` or `replaceContent`.
+
+## Replacing content
+
+`contentControls.replaceContent` accepts plain text. For richer fragments (paragraphs with formatting, tables, lists), use `doc.insert` to place the content, then `create.contentControl({ at: range, ... })` to wrap the inserted range with a tag.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Tagged inline text example" icon="text-cursor-input" href="https://github.com/superdoc-dev/superdoc/tree/main/examples/document-api/content-controls/tagged-inline-text">
+    The smallest content-control workflow. `create.contentControl` + `selectByTag` + `text.setValue`.
+  </Card>
+  <Card title="Contract templates demo" icon="file-text" href="https://github.com/superdoc-dev/superdoc/tree/main/demos/contract-templates">
+    Smart fields and versioned sections composed into one runtime app.
+  </Card>
+  <Card title="Template Builder" icon="layout-template" href="/solutions/template-builder/introduction">
+    Ready-made React authoring component for content-control templates.
+  </Card>
+  <Card title="Reference: all operations" icon="code" href="/document-api/reference/content-controls/index">
+    Every `contentControls.*` operation with input, output, and failure codes.
+  </Card>
+</CardGroup>

demos/AGENTS.md

@@ -0,0 +1,33 @@
+# Demos
+
+Demos are composed product workflows and showcase surfaces. They answer what someone can build with SuperDoc, not just how one API call works.
+
+If the work only teaches one primitive or one integration pattern, put it in `examples/` instead.
+
+## What belongs here
+
+- Multiple SuperDoc features working together in a realistic workflow.
+- Product-shaped UI, fake backend state, library data, or scenario copy when it helps the workflow make sense.
+- A README that explains the scenario, the features being composed, how to run it, and related examples or docs.
+- An entry in `demos/manifest.json`.
+
+Set `homepage: true` only when the demo is gallery-ready: verified locally, clear enough for users, and backed by the metadata or assets the homepage expects. Use `homepage: false` for source demos that are useful but not ready for the gallery.
+
+## UI baseline
+
+- Import `superdoc/style.css` before local CSS when the demo renders SuperDoc.
+- Use the SuperDoc token contract (`--sd-*`) or local aliases that resolve to those tokens. Avoid Vite starter purple and one-off palettes unless the demo is intentionally showing theming.
+- Product demos should feel precise and functional: flat surfaces, clear hierarchy, restrained whitespace, 1px borders, 4-8px radii, SuperDoc blue for primary actions.
+- Do not use marketing gradients in product UI. `brand.md` reserves gradients for marketing heroes and landing pages.
+- Show the working product surface first. Avoid landing-page heroes unless the demo is specifically a marketing page.
+
+## Source demos vs live demos
+
+This monorepo owns source demos. Some live demos at `demos.superdoc.dev` live in the separate `superdoc-dev/demos` repository. Do not assume every source demo has a `liveUrl`, thumbnail, or deployed counterpart.
+
+## Verification
+
+- Run the package build for each touched demo workspace.
+- Browser-smoke workflows when the change affects UI, document state, import/export, or a customer-recordable flow.
+- Do not commit generated `dist/` output or `node_modules/`.
+- Treat stale README, AGENTS, and CLAUDE instructions as bugs; see `../comment-policy.md`.

demos/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

demos/README.md

@@ -1,9 +1,21 @@
 # SuperDoc Demos
 
-Source-only demos used by the [SuperDoc demo gallery](https://superdoc.dev). A demo composes multiple SuperDoc features into a workflow. If you want the smallest copy-pasteable path for one feature, use [`examples/`](../examples/) instead.
+Source-only demos used by the [SuperDoc demo gallery](https://superdoc.dev).
+
+Demos answer: "What can I build with SuperDoc?"
+
+A demo composes multiple SuperDoc features into a workflow, often with realistic UI, fake backend data, product copy, gallery metadata, or a video-ready scenario. If you want the smallest copy-pasteable path for one primitive, use [`examples/`](../examples/) instead.
 
 The machine-readable index lives in [`manifest.json`](./manifest.json).
 
+## Demos vs examples
+
+Use `demos/` when the point is the workflow: contract templates, grading papers, Slack redlining, browser extensions, Word add-ins, and similar product-shaped experiences.
+
+Use `examples/` when the point is the API call or integration pattern. Examples can overlap with demos, but the example should remove the product story and show the smallest useful code path.
+
+Before marking a demo as homepage-ready, make sure it has been verified locally, has a clear README, and has the gallery metadata or assets the homepage expects. Leave `homepage: false` while a demo is useful for source review but not ready for the gallery.
+
 ## Source demos vs live demos
 
 This monorepo's `demos/` folder is the source showcase surface. Demos here run locally from workspace builds and are smoke-tested against the current repository state.
@@ -14,6 +26,7 @@ Live demos that run at `demos.superdoc.dev` live in the separate `superdoc-dev/d
 
 | Demo | Category | Notes |
 |------|----------|-------|
+| [contract-templates](./contract-templates) | Editor | Content-controls workflow with smart fields, versioned clauses, and update detection |
 | [custom-ui](./custom-ui) | Editor | Full Custom UI reference workspace |
 | [grading-papers](./grading-papers) | Editor | Product workflow for paper review |
 | [slack-redlining](./slack-redlining) | AI | Slack and AI redlining workflow |

demos/contract-templates/README.md

@@ -0,0 +1,40 @@
+# Contract templates
+
+A runtime workflow that uses Word content controls to manage smart fields and versioned clauses inside a document. Single-page, no backend, no framework.
+
+This is a demo: it shows a composed contract-template workflow. For the smallest copy-pasteable content-control primitive, see the [tagged inline text example](../../examples/document-api/content-controls/tagged-inline-text).
+
+## What this shows
+
+Two flows of the same primitive, composed into one app:
+
+1. **Smart fields.** Inline content controls share a `tag` value (`{ kind: 'smartField', key: 'customerName' }`) across every occurrence. Select by tag, then push the same value to each matching control with `contentControls.text.setValue`.
+2. **Versioned reusable sections.** A block content control carries `{ kind: 'reusableSection', sectionId, version }` in its `tag`. The app reads the live version from `contentControls.list` after every change. When the section in the document falls behind the section library, an "update available" CTA appears. Updating is `replaceContent` + `patch`.
+
+Every mutation goes through `editor.doc.*`. The same operation set runs headless via the Node SDK and CLI.
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Edit a smart-field value on the right, click **Apply fields**, watch every occurrence update. The seed section ships as v1; the library has v2. The **Apply update** CTA appears because they diverge. Click it, the section swaps, the CTA disappears.
+
+## Related work
+
+If you need a **ready-made React component for authoring templates** with content controls (trigger `{{` to insert fields, linked field groups, owner/signer field types, export to .docx), see [`@superdoc-dev/template-builder`](https://docs.superdoc.dev/solutions/template-builder/introduction). This demo focuses on the *runtime* side: an app filling and updating already-tagged regions. Template Builder focuses on the *authoring* side.
+
+## Honest limits
+
+- The demo uses `lockMode: 'unlocked'` for every content control. The OOXML spec says `sdtLocked` leaves content editable, but the current adapter routes content and attr updates through `editor.commands.updateStructuredContentById`, which rewrites the whole SDT wrapper. The lock plugin reads that as wrapper damage and silently filters the transaction for `sdtLocked` and `sdtContentLocked` SDTs. Result: programmatic `text.setValue`, `replaceContent`, `patch`, and `setLockMode` return success but do not persist on locked SDTs. Tracked as a follow-up engine bug; the demo sidesteps it.
+- `contentControls.replaceContent` is plain-text in the current adapter. Rich-content swap (formatting, tables) is not first-class today. Sections in this demo are kept plain.
+- `contentControls.setBinding` writes `<w:dataBinding>` and round-trips through DOCX, but SuperDoc does not yet evaluate XPath against `customXml/` parts. The metadata channel works; the live binding engine does not.
+
+## See also
+
+- [Tagged inline text example](../../examples/document-api/content-controls/tagged-inline-text)
+- [Document API > Content controls](https://docs.superdoc.dev/document-api/features/content-controls)
+- [Document API > Reference > Content controls](https://docs.superdoc.dev/document-api/reference/content-controls/index)
+- [Solutions > Template Builder](https://docs.superdoc.dev/solutions/template-builder/introduction)

demos/contract-templates/index.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SuperDoc: content controls</title>
+  </head>
+  <body>
+    <div class="app">
+      <section class="editor-area">
+        <div id="editor"></div>
+      </section>
+      <aside class="sidebar">
+        <section class="panel">
+          <h2>Smart fields</h2>
+          <p class="hint">Tagged inline content controls. <code>selectByTag</code> + <code>text.setValue</code> fan one value to every occurrence.</p>
+          <label>
+            <span>Customer</span>
+            <input id="field-customerName" />
+          </label>
+          <label>
+            <span>Jurisdiction</span>
+            <input id="field-jurisdiction" />
+          </label>
+          <label>
+            <span>Effective date</span>
+            <input id="field-effectiveDate" />
+          </label>
+          <button class="btn primary" id="apply-fields" type="button">Apply fields</button>
+        </section>
+
+        <section class="panel">
+          <h2>Reusable section</h2>
+          <p class="hint">Block content control with <code>{sectionId, version}</code> in its tag. <code>replaceContent</code> + <code>patch</code> swap the content and the version.</p>
+          <div class="meta">
+            <span>In document</span>
+            <strong id="section-version">v1</strong>
+          </div>
+          <div class="meta">
+            <span>Library</span>
+            <strong>v2</strong>
+          </div>
+          <div class="banner" id="update-banner" hidden>
+            <span class="banner-text">Update available.</span>
+            <button class="btn primary" id="apply-update" type="button">Apply v2</button>
+          </div>
+        </section>
+
+        <p class="status" id="status">Loading</p>
+      </aside>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

demos/contract-templates/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@superdoc-demos/contract-templates",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "pnpm --filter superdoc build",
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "superdoc": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vite": "catalog:"
+  }
+}