docs(demos+examples): cover advertised entries with missing READMEs (round 2, SD-3217)

demos/chrome-extension/README.md

@@ -0,0 +1,28 @@
+# Chrome extension demo
+
+A Chrome extension that opens DOCX files from the user's drive in a SuperDoc-powered tab. The wrapper directory holds the gallery metadata (`demo-config.json`, thumbnail, video); the actual extension package lives at [`chrome-extension/`](./chrome-extension/) one level down.
+
+## What this shows
+
+- A SuperDoc-driven editor mounted inside a browser extension surface.
+- File ingestion through the extension's file-picker, opened as a regular DOCX.
+- A self-contained extension manifest that you can adapt to your own deployment.
+
+## Run it
+
+Build and load the extension package, then open a DOCX from the extension's popup. Full setup steps live in the extension package's own README:
+
+- [`chrome-extension/README.md`](./chrome-extension/README.md)
+
+## When to reach for it
+
+- You're shipping document editing as a browser extension and want a starting point for the install flow + tab handoff.
+- You're prototyping a "open in editor" entry point from another web surface.
+
+## When not
+
+- You want to embed SuperDoc on a normal web page. Use [`examples/getting-started/`](../../examples/getting-started/) instead; an extension shell is the wrong substrate.
+
+## Docs
+
+[SuperDoc overview](https://docs.superdoc.dev/getting-started/introduction).

examples/advanced/headless-toolbar/README.md

@@ -0,0 +1,38 @@
+# Headless toolbar variants
+
+Five reference implementations of a custom toolbar driven by SuperDoc's headless `HeadlessToolbarController`. Each variant binds the same controller to a different framework + design-system pair so consumers can pick the one closest to their stack as a starting point.
+
+The point of "headless" here is: SuperDoc supplies the toolbar state (active items, command dispatch, dynamic enablement), the consumer supplies the rendering. No built-in CSS, no opinionated component library.
+
+## Variants
+
+| Variant | Stack | What it shows |
+|---|---|---|
+| [`vanilla`](./vanilla) | Plain JS + plain DOM | Smallest possible binding. Useful if you're integrating into a non-React/Vue/Svelte surface. |
+| [`react-mui`](./react-mui) | React + Material UI | Render the headless state through MUI's `<Toolbar>` and friends. |
+| [`react-shadcn`](./react-shadcn) | React + shadcn/ui | Same React pattern with shadcn primitives. |
+| [`svelte-shadcn`](./svelte-shadcn) | Svelte + shadcn-svelte | Svelte-flavored binding. |
+| [`vue-vuetify`](./vue-vuetify) | Vue + Vuetify | Vue binding driven by Vuetify components. |
+
+## Run a variant
+
+Each variant is a standalone workspace with its own `package.json` and `dev` script. From the variant directory:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## When to reach for it
+
+- You're shipping a toolbar that needs to match your existing design system, and the built-in toolbar's chrome doesn't fit.
+- You want to expose the same actions across multiple toolbar surfaces (main toolbar, mobile sub-toolbar, command palette) and need them all driven from one source of truth.
+
+## When not
+
+- You're happy with the default toolbar. Use [`examples/editor/built-in-ui/toolbar`](../../editor/built-in-ui/toolbar) instead; it's the smallest setup.
+- You only need to add or remove a few default actions. The configurable-toolbar pattern at [`examples/editor/custom-ui/configurable-toolbar`](../../editor/custom-ui/configurable-toolbar) is lighter than going fully headless.
+
+## Docs
+
+[Headless toolbar](https://docs.superdoc.dev/editor/custom-ui/toolbar-and-commands).

examples/ai/redlining/README.md

@@ -0,0 +1,36 @@
+# AI redlining (browser)
+
+A React example that opens a DOCX in SuperDoc, sends the document text to an LLM for a structured set of suggestions, then applies each suggestion as a tracked change so the reviewer accepts or rejects it.
+
+## What this teaches
+
+- Driving SuperDoc in `documentMode: 'suggesting'` so AI-generated edits land as tracked changes attributed to a configured user.
+- Calling an LLM with a `{ find, replace, comment }` schema and turning that schema into editor mutations.
+- Wiring the built-in comments panel alongside tracked changes so each suggestion can carry rationale text.
+
+## Run it
+
+```bash
+pnpm install
+cp .env.example .env  # set VITE_OPENAI_API_KEY
+pnpm dev
+```
+
+Open the local URL Vite prints. Upload a DOCX, then click the AI review button.
+
+### Required env
+
+- `VITE_OPENAI_API_KEY`: an OpenAI API key with access to the model the example calls. Without it the AI review button is non-functional. Replace with your own provider if you're not on OpenAI.
+
+## When to reach for it
+
+- You're prototyping AI-assisted document review in the browser and want a reference for the suggestion-to-tracked-change pipeline.
+- You're deciding between client-side and server-side AI redlining; this is the browser flavor.
+
+## When not
+
+- You want server-side AI redlining (no browser, no user-facing review surface). Use [`examples/document-engine/ai-redlining`](../../document-engine/ai-redlining) instead.
+
+## Docs
+
+[AI overview](https://docs.superdoc.dev/ai/overview).

examples/document-engine/ai-redlining/README.md

@@ -0,0 +1,42 @@
+# AI redlining (server-side)
+
+A headless Node script that opens a DOCX, sends its text to an LLM for review, applies the returned suggestions as tracked changes through the Document API, and writes the redlined DOCX back to disk. No browser, no editor UI, no user interaction.
+
+## What this teaches
+
+- Opening a DOCX headlessly via `Editor.open(buffer, { documentMode: 'suggesting' })`.
+- Calling an LLM with a `{ find, replace, comment }` schema and applying each suggestion as a tracked change attributed to a configured author.
+- Exporting the resulting DOCX with the tracked changes preserved, ready for a reviewer to open in SuperDoc or Word.
+
+## Run it
+
+```bash
+pnpm install
+cp .env.example .env  # set OPENAI_API_KEY
+pnpm start
+```
+
+Pass an input path and an output path:
+
+```bash
+pnpm start -- input.docx redlined.docx
+```
+
+A sample DOCX (`sample.docx`) is included for first-run smoke testing.
+
+### Required env
+
+- `OPENAI_API_KEY`: an OpenAI API key with access to the model the script calls. Without it the script exits early with a clear error. Replace the provider call if you're not on OpenAI.
+
+## When to reach for it
+
+- You're running AI redlining server-side (background job, ingestion pipeline) and the reviewer opens the redlined file later.
+- You want a reference for the Editor.open headless entry point and the tracked-change application loop.
+
+## When not
+
+- You're shipping AI redlining in the browser with a live reviewer. Use [`examples/ai/redlining`](../../ai/redlining) instead.
+
+## Docs
+
+[AI overview](https://docs.superdoc.dev/ai/overview), [Document Engine SDKs](https://docs.superdoc.dev/document-engine/sdks).

examples/document-engine/diffing/README.md

@@ -0,0 +1,31 @@
+# Document diffing
+
+A Vue example that compares two DOCX files side by side, highlighting insertions and deletions as tracked changes on the right pane while keeping the left pane as the original.
+
+## What this teaches
+
+- Driving SuperDoc's diff surface from two DOCX inputs (no editor instance hosting the diff).
+- Rendering the diff result as tracked changes so reviewers see familiar review semantics.
+- A reset / re-compare flow without re-mounting the editor.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the local URL Vite prints. Pick two DOCX files, click **Compare documents**.
+
+## When to reach for it
+
+- You're shipping a "compare two versions" surface in your product.
+- You want to evaluate SuperDoc's diff output quality before committing to it.
+
+## When not
+
+- You want server-side diffing without rendering. The Document Engine SDK exposes the same diff primitives headlessly; see the [Document Engine SDKs](https://docs.superdoc.dev/document-engine/sdks).
+
+## Docs
+
+[Document Engine: diffing](https://docs.superdoc.dev/document-engine/diffing).

examples/editor/built-in-ui/comments/README.md

@@ -0,0 +1,31 @@
+# Built-in comments UI
+
+The smallest setup that turns on SuperDoc's built-in comments panel and lets the current user create, resolve, and reply to threaded comments without writing any UI yourself.
+
+## What this teaches
+
+- Enabling the `comments` module on a `SuperDoc` instance.
+- Wiring the comments panel to a sibling DOM container so threads render outside the document canvas.
+- Setting the active user (`name`, `email`) so new comments are attributed correctly.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the local URL Vite prints, then select text and click the comment affordance.
+
+## When to reach for it
+
+- You want comments shipped quickly with SuperDoc's default UI.
+- You're evaluating whether the built-in panel covers your review workflow before deciding whether to build a custom one.
+
+## When not
+
+- You need a custom comments UI (your own sidebar, panel, popovers). Use [`superdoc/ui/react`](https://docs.superdoc.dev/editor/custom-ui/comments) plus the `editor.doc.comments.*` Document API instead. The custom-UI demo at [`demos/custom-ui`](../../../../demos/custom-ui) is the worked composed example.
+
+## Docs
+
+[Built-in UI: comments](https://docs.superdoc.dev/editor/built-in-ui/comments).

examples/editor/built-in-ui/toolbar/README.md

@@ -0,0 +1,31 @@
+# Built-in toolbar UI
+
+The smallest setup that mounts SuperDoc's built-in toolbar above the editor canvas, with the default set of formatting actions and no custom command registration.
+
+## What this teaches
+
+- Enabling the `toolbar` module on `SuperDoc` and binding it to a sibling DOM container.
+- The default toolbar surface: text formatting, lists, undo/redo, alignment, and so on.
+- How the toolbar reads and writes editor state through the same engine the editor uses.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the local URL Vite prints.
+
+## When to reach for it
+
+- You want a working toolbar without writing one.
+- You're evaluating whether the default toolbar covers your needs before deciding to build a custom one.
+
+## When not
+
+- You need a custom toolbar (your own buttons, your own design system, command grouping, dropdowns). Use the headless toolbar or `ui.commands.*` instead. See [`examples/editor/custom-ui/configurable-toolbar`](../../custom-ui/configurable-toolbar) and [`examples/advanced/headless-toolbar`](../../../advanced/headless-toolbar).
+
+## Docs
+
+[Built-in UI: toolbar](https://docs.superdoc.dev/editor/built-in-ui/toolbar).

examples/editor/built-in-ui/track-changes/README.md

@@ -0,0 +1,31 @@
+# Built-in track changes UI
+
+The smallest setup that turns on SuperDoc's built-in tracked-changes review surface: insertions and deletions are marked, and the built-in panel surfaces an accept / reject flow without any custom UI.
+
+## What this teaches
+
+- Switching the editor into `documentMode: 'suggesting'` so edits land as tracked changes.
+- Enabling the built-in review panel and binding the active user so suggestions are attributed correctly.
+- Letting users accept or reject suggestions with no extra wiring.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the local URL Vite prints. Edit text to produce tracked changes; the panel renders the accept/reject controls.
+
+## When to reach for it
+
+- You want tracked changes shipped quickly with SuperDoc's default UI.
+- You're evaluating the default review experience before deciding whether to build a custom one.
+
+## When not
+
+- You need a custom review surface (your own sidebar, custom diff rendering, batch accept/reject UI). Use [`superdoc/ui/react`](https://docs.superdoc.dev/editor/custom-ui/track-changes) plus `editor.doc.trackChanges.*` instead. The composed reference workspace at [`demos/custom-ui`](../../../../demos/custom-ui) shows the custom-UI pattern.
+
+## Docs
+
+[Built-in UI: track changes](https://docs.superdoc.dev/editor/built-in-ui/track-changes).

examples/editor/theming/README.md

@@ -0,0 +1,31 @@
+# Editor theming
+
+A working example of theming the SuperDoc editor with custom CSS variables, including a runtime theme switcher across multiple named themes.
+
+## What this teaches
+
+- Overriding SuperDoc's `--sd-*` token contract from a consumer stylesheet to restyle toolbar, canvas, comments, and the review panel together.
+- Defining several themes as plain JS objects and toggling between them at runtime.
+- Where the SuperDoc token surface starts (the imported `superdoc/style.css`) and how to layer your own tokens on top without forking.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open the local URL Vite prints. Use the theme switcher to flip between the bundled themes.
+
+## When to reach for it
+
+- You're customizing SuperDoc's look to match an existing product brand or design system.
+- You want a reference for which `--sd-*` tokens are safe to override.
+
+## When not
+
+- You need to restyle individual document content (paragraph styles, run formatting). That's the style cascade on the document itself, not the editor chrome; use the Document API style operations instead.
+
+## Docs
+
+[Theming](https://docs.superdoc.dev/editor/theming/overview).

examples/getting-started/nextjs/README.md

@@ -0,0 +1,32 @@
+# SuperDoc in a Next.js app
+
+A minimal Next.js (App Router) starter that renders a SuperDoc editor on the client.
+
+## What this teaches
+
+- Mounting SuperDoc inside a Next.js client component.
+- Loading a DOCX from `public/` at runtime (no build-time bundling of the document).
+- Keeping the editor SSR-safe: the SuperDoc render path is browser-only, so the component is gated to client-side rendering.
+
+## Run it
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open http://localhost:3000.
+
+## When to reach for it
+
+- You're starting a new Next.js + SuperDoc project and want the smallest working integration.
+- You need a reference for the SSR boundary (where `'use client'` belongs, how to skip server rendering for the editor).
+
+## When not
+
+- You're building a non-Next React app. Use [`getting-started/react`](../react) instead; it's smaller and framework-neutral.
+- You need server-side document mutations. SuperDoc's runtime is client-side; the Document Engine SDK/CLI is the server-side path.
+
+## Docs
+
+[Frameworks: Next.js](https://docs.superdoc.dev/getting-started/frameworks/nextjs).