docs: brand voice + terminology sweep, hide legacy AI pages, rename Custom UI demo (SD-2873)

Final pass over the docs surface to align with brand.md voice and
the new IA terminology.

Terminology:
- 'Bring Your Own UI' / 'BYO UI' to 'Custom UI' across 12+ mdx files,
  llms.txt, llms-full.txt, code comments in packages/super-editor and
  packages/superdoc.
- Rename the Custom UI demo: demos/bring-your-own-ui to demos/custom-ui.
  Update package.json name, playwright port mapping key, README, and
  GitHub URL references in mdx.

Brand voice:
- Em-dash sweep across hand-written mdx (skip auto-generated files
  under document-api/reference and the gen:docs marker block in
  document-engine/sdks.mdx). 'X — Y' becomes 'X. Y' or 'X (Y)' or
  'X: Y' depending on context.
- Wrap frontmatter description values that contain colons in double
  quotes so YAML parses correctly (caught by mintlify validate).
- Touch up grammatical regressions where the colon substitution read
  worse than the em-dash (theming.mdx, document-engine/overview.mdx,
  getting-started/{ai,import-export}.mdx).

Legacy hides (kept reachable for inbound links, removed from search):
- document-engine/ai-agents/* (7 pages) and getting-started/ai-agents.mdx
  add hidden: true frontmatter. Redirects already point /ai/* and
  /getting-started/ai at the new homes; this stops the old pages from
  surfacing in search results.

Notes:
- Auto-generated content (Document API reference, sdks.mdx marker
  block) still has em-dashes. Filing a follow-up for the generator.
- demos/custom-ui/ folder renamed cleanly (no backward-compat shim
  per direction). Old GitHub URLs that pointed at demos/bring-your-own-ui
  will 404; trade-off accepted.

Author: caio-pizzol

apps/docs/advanced/headless-toolbar-examples.mdx

@@ -8,7 +8,7 @@ keywords: "toolbar examples, vue toolbar, svelte toolbar, custom toolbar example
 Framework-agnostic patterns built on `createHeadlessToolbar()`. Pick the one closest to your stack.
 
 <Note>
-**On React?** Reach for [Bring Your Own UI › Toolbar and commands](/editor/custom-ui/toolbar-and-commands) instead. The typed React surface (`useSuperDocCommand`, `ui.commands.register`) re-renders one button per command, ships with selection / comments / track-changes hooks, and works with any design system (shadcn, MUI, Mantine, Tailwind). The headless examples below are for non-React stacks.
+**On React?** Reach for [Custom UI › Toolbar and commands](/editor/custom-ui/toolbar-and-commands) instead. The typed React surface (`useSuperDocCommand`, `ui.commands.register`) re-renders one button per command, ships with selection / comments / track-changes hooks, and works with any design system (shadcn, MUI, Mantine, Tailwind). The headless examples below are for non-React stacks.
 </Note>
 
 ## Vue + Vuetify
@@ -141,7 +141,7 @@ Replace `<example-name>` with `vue-vuetify`, `svelte-shadcn`, or `vanilla`.
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Bring Your Own UI (React)" icon="atom" href="/editor/custom-ui/toolbar-and-commands">
+  <Card title="Custom UI (React)" icon="atom" href="/editor/custom-ui/toolbar-and-commands">
     The recommended path for React apps. Typed hooks, custom commands, selection-aware buttons.
   </Card>
   <Card title="Headless toolbar API reference" icon="code" href="/advanced/headless-toolbar">

apps/docs/advanced/headless-toolbar.mdx

@@ -9,7 +9,7 @@ Build your own toolbar UI. SuperDoc provides the state and commands — you rend
 
 ## Using React?
 
-`superdoc/headless-toolbar` is the framework-agnostic substrate. **For new React apps, reach for `useSuperDocCommand` from `superdoc/ui/react` instead.** It re-renders one button per command (not the whole toolbar) and ships alongside companion hooks for selection, comments, and tracked changes. See [Bring Your Own UI › Toolbar and commands](/editor/custom-ui/toolbar-and-commands).
+`superdoc/headless-toolbar` is the framework-agnostic substrate. **For new React apps, reach for `useSuperDocCommand` from `superdoc/ui/react` instead.** It re-renders one button per command (not the whole toolbar) and ships alongside companion hooks for selection, comments, and tracked changes. See [Custom UI › Toolbar and commands](/editor/custom-ui/toolbar-and-commands).
 
 `superdoc/headless-toolbar` stays supported for existing integrations and framework-agnostic toolbar-only use cases. Both paths read from the same internal substrate.
 

apps/docs/advanced/supereditor/overview.mdx

@@ -9,7 +9,7 @@ SuperEditor is the low-level DOCX editing engine that powers SuperDoc. Most apps
 
 ## Pick the right layer
 
-**Use SuperDoc + Bring Your Own UI for custom React UI.** `<SuperDocEditor>` (or `new SuperDoc(...)`) plus `superdoc/ui/react` gives you typed hooks for toolbar, comments, tracked changes, selection, and document control. See [Bring Your Own UI](/editor/custom-ui/overview).
+**Use SuperDoc + Custom UI for custom React UI.** `<SuperDocEditor>` (or `new SuperDoc(...)`) plus `superdoc/ui/react` gives you typed hooks for toolbar, comments, tracked changes, selection, and document control. See [Custom UI](/editor/custom-ui/overview).
 
 **Use the Document API for document mutations.** [`editor.doc.*`](/document-api/overview) is the stable, request/response surface that's identical on server, client, and AI agents. It's the recommended path for any insert / replace / format / comment / tracked-change operation.
 
@@ -22,7 +22,7 @@ SuperEditor is the low-level DOCX editing engine that powers SuperDoc. Most apps
 - You're building a custom extension that taps into ProseMirror plugins or schemas.
 - You explicitly need engine internals the higher layers don't surface.
 
-For a typical React DOCX editor with a custom UI, you don't need this page — start at [Bring Your Own UI](/editor/custom-ui/overview).
+For a typical React DOCX editor with a custom UI, you don't need this page — start at [Custom UI](/editor/custom-ui/overview).
 
 ## Quick start
 

apps/docs/ai/agents/best-practices.mdx

@@ -1,15 +1,15 @@
 ---
 title: Best practices
 sidebarTitle: Best practices
-description: Get better results from LLM document editing — prompting, tool call patterns, and workflow tips
+description: "Get better results from LLM document editing: prompting, tool call patterns, and workflow tips"
 keywords: "llm best practices, ai document editing, prompt engineering, superdoc tools, tool calling, document automation"
 ---
 
 These patterns help your LLM agent produce reliable, efficient document edits.
 
 ## Use the bundled system prompt
 
-`getSystemPrompt()` returns a tested prompt that teaches the model how to use SuperDoc tools — targeting, workflow order, and multi-action tools. Load it once and pass it as the system message.
+`getSystemPrompt()` returns a tested prompt that teaches the model how to use SuperDoc tools: targeting, workflow order, and multi-action tools. Load it once and pass it as the system message.
 
 ```typescript
 import { getSystemPrompt } from '@superdoc-dev/sdk';
@@ -32,15 +32,15 @@ You edit `.docx` files using SuperDoc intent tools. Be efficient and minimize to
 
 ## Workflow
 
-1. **Read** — Use `superdoc_get_content` to understand the document.
-2. **Search** — Use `superdoc_search` to find stable handles or block addresses.
-3. **Edit** — Use the focused tool that matches the job:
+1. **Read**: Use `superdoc_get_content` to understand the document.
+2. **Search**: Use `superdoc_search` to find stable handles or block addresses.
+3. **Edit**: Use the focused tool that matches the job:
    - `superdoc_edit` for insert, replace, delete, undo, redo
    - `superdoc_format` for inline or paragraph formatting
    - `superdoc_create` for paragraphs and headings
    - `superdoc_comment` for comment threads
    - `superdoc_track_changes` for review decisions
-4. **Batch only when useful** — Use `superdoc_mutations` for preview/apply or atomic multi-step edits.
+4. **Batch only when useful**: Use `superdoc_mutations` for preview/apply or atomic multi-step edits.
 
 ## Rules
 
@@ -55,17 +55,17 @@ You edit `.docx` files using SuperDoc intent tools. Be efficient and minimize to
 
 A typical edit takes 3-5 tool calls:
 
-1. `superdoc_get_content` — understand what's in the document
-2. `superdoc_search` — find the exact location (returns stable handles/addresses)
-3. Edit tool (`superdoc_edit`, `superdoc_format`, etc.) — apply the change using targets from search
+1. `superdoc_get_content`: understand what's in the document
+2. `superdoc_search`: find the exact location (returns stable handles/addresses)
+3. Edit tool (`superdoc_edit`, `superdoc_format`, etc.): apply the change using targets from search
 
 This matters because handles from search results point to the exact right location. If the model guesses a block address instead of searching for it, edits land in the wrong place.
 
 ## Minimize tool calls
 
 Instruct the LLM to plan all edits before calling tools. A well-structured prompt like "Find the termination clause and rewrite it to allow 30-day notice" should take 3-5 calls, not 15.
 
-Batch multiple changes only when atomic execution is genuinely helpful — use `superdoc_mutations` for that.
+Batch multiple changes only when atomic execution is genuinely helpful: use `superdoc_mutations` for that.
 
 ## Prefer markdown insert for multi-block creation
 
@@ -79,9 +79,9 @@ When you need to create multiple headings and paragraphs in one operation, use `
 }
 ```
 
-After inserting, apply formatting in a single `superdoc_mutations` batch using `format.apply` steps — one step per block or range. This reduces a workflow that might otherwise take 40+ calls down to 4: read, search, insert, format.
+After inserting, apply formatting in a single `superdoc_mutations` batch using `format.apply` steps: one step per block or range. This reduces a workflow that might otherwise take 40+ calls down to 4: read, search, insert, format.
 
-## Use focused tools — `superdoc_mutations` is an escape hatch
+## Use focused tools: `superdoc_mutations` is an escape hatch
 
 For straightforward edits, use the focused intent tools (`superdoc_edit`, `superdoc_format`, `superdoc_create`, `superdoc_list`, `superdoc_comment`). They validate arguments, give clear errors, and are easier for models to call correctly.
 
@@ -92,14 +92,14 @@ Reach for `superdoc_mutations` only when you need:
 
 ## Feed errors back
 
-`dispatchSuperDocTool` returns structured errors. Pass them back as tool results — most models self-correct on the next turn.
+`dispatchSuperDocTool` returns structured errors. Pass them back as tool results: most models self-correct on the next turn.
 
 ```typescript
 try {
   const result = await dispatchSuperDocTool(doc, toolCall.function.name, JSON.parse(toolCall.function.arguments));
   messages.push({ role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(result) });
 } catch (err: any) {
-  // Return the error as a tool result — the model will see it and adjust
+  // Return the error as a tool result: the model will see it and adjust
   messages.push({ role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify({ error: err.message }) });
 }
 ```
@@ -110,9 +110,9 @@ Don't hardcode formatting values. Read them from the document's existing content
 
 **Body text:** Read `fontFamily`, `fontSize`, and `color` from non-empty paragraphs with `alignment: "justify"` or `alignment: "left"`. Set `bold: false` for body paragraphs.
 
-Many DOCX documents report `underline: true` on all blocks due to style inheritance. This is a DOCX artifact — not intentional formatting. Do not carry it forward when inserting new paragraphs.
+Many DOCX documents report `underline: true` on all blocks due to style inheritance. This is a DOCX artifact: not intentional formatting. Do not carry it forward when inserting new paragraphs.
 
-**Headings:** Read from existing heading blocks in the document. Scale `fontSize` up relative to body text. Headings are typically bold and sometimes centered — confirm against what's already in the document rather than assuming.
+**Headings:** Read from existing heading blocks in the document. Scale `fontSize` up relative to body text. Headings are typically bold and sometimes centered: confirm against what's already in the document rather than assuming.
 
 ```typescript
 // Get content first, find a representative body paragraph
@@ -173,7 +173,7 @@ These prompts have been tested against the SuperDoc tool set. Use them as inspir
 - "Apply yellow highlight to every sentence that contains an indemnification obligation."
 - "Replace all references to 'Contractor' with 'Service Provider' and make each replacement italic with tracked changes enabled."
 - "Underline every sentence that references payment terms or late fees."
-- "Insert CONFIDENTIAL — DO NOT DISTRIBUTE at the very top of the document and make it bold, red, 14pt."
+- "Insert CONFIDENTIAL: DO NOT DISTRIBUTE at the very top of the document and make it bold, red, 14pt."
 - "Scan the document for inconsistent capitalization of defined terms and fix them with tracked changes enabled."
 
 ### Formatting and structure
@@ -200,7 +200,7 @@ These prompts have been tested against the SuperDoc tool set. Use them as inspir
 
 ## Related
 
-- [LLM tools](/ai/agents/llm-tools) — tool catalog and SDK functions
-- [How to use](/ai/agents/integrations) — step-by-step integration guide
-- [Debugging](/ai/agents/debugging) — troubleshoot tool call failures
-- [Document API](/document-api/overview) — the operation set behind the tools
+- [LLM tools](/ai/agents/llm-tools): tool catalog and SDK functions
+- [How to use](/ai/agents/integrations): step-by-step integration guide
+- [Debugging](/ai/agents/debugging): troubleshoot tool call failures
+- [Document API](/document-api/overview): the operation set behind the tools

apps/docs/ai/agents/debugging.mdx

@@ -1,7 +1,7 @@
 ---
 title: Debugging
 sidebarTitle: Debugging
-description: Troubleshoot LLM tool calls — logging, error shapes, and common failure modes
+description: "Troubleshoot LLM tool calls: logging, error shapes, and common failure modes"
 keywords: "llm debugging, tool call errors, superdoc tools, ai document editing, troubleshooting, document api"
 ---
 
@@ -13,8 +13,8 @@ Every LLM tool call maps to a [Document API](/document-api/overview) operation u
 
 This gives you a clear debugging strategy:
 
-1. **Test the Document API directly.** Call the underlying SDK method with the same arguments. If it works, the operation is fine — the problem is in the prompt or the tool schema.
-2. **If the API call fails,** the issue is in the operation itself — check arguments, targets, and document state.
+1. **Test the Document API directly.** Call the underlying SDK method with the same arguments. If it works, the operation is fine: the problem is in the prompt or the tool schema.
+2. **If the API call fails,** the issue is in the operation itself: check arguments, targets, and document state.
 3. **If the API call succeeds but the LLM tool call fails,** the model is calling the tool incorrectly. Fix the prompt, add examples, or check the tool schema.
 
 ```typescript
@@ -55,29 +55,29 @@ for (const toolCall of choice.message.tool_calls) {
 ```
 
 What to look for in logs:
-- **Tool name** — is the model calling the right tool?
-- **Arguments** — are required fields present? Is the `action` correct?
-- **Targets** — are handles/addresses from a recent search, or did the model guess?
-- **Result** — did the operation return data or an error?
+- **Tool name**: is the model calling the right tool?
+- **Arguments**: are required fields present? Is the `action` correct?
+- **Targets**: are handles/addresses from a recent search, or did the model guess?
+- **Result**: did the operation return data or an error?
 
 ## Error shapes
 
 `dispatchSuperDocTool` throws errors in two categories:
 
-**Validation errors** — bad arguments before the operation runs:
+**Validation errors**: bad arguments before the operation runs:
 ```json
 { "error": "Missing required parameter: action" }
 { "error": "Unknown action 'bold' for tool superdoc_format. Valid actions: inline, set_style, set_alignment, set_indentation, set_spacing" }
 { "error": "Parameter 'target' is required for action 'replace'" }
 ```
 
-**Execution errors** — the operation ran but failed:
+**Execution errors**: the operation ran but failed:
 ```json
 { "error": "Target not found: no node matches the given handle" }
 { "error": "Invalid address: block at index 42 does not exist" }
 ```
 
-Both types are returned as strings in `err.message`. Pass them back as tool results — the model usually self-corrects.
+Both types are returned as strings in `err.message`. Pass them back as tool results: the model usually self-corrects.
 
 ## Common failure modes
 
@@ -88,7 +88,7 @@ Both types are returned as strings in `err.message`. Pass them back as tool resu
 | Edits land in the wrong place | Model invented a block address | Use `superdoc_search` to get fresh handles |
 | Infinite tool call loop | Model never reaches a stopping point | Add a max iterations guard (see below) |
 | Model doesn't use tools at all | Tools not passed to the API call | Verify `chooseTools()` result is in the `tools` param |
-| "Missing required parameter" | Model forgot `action` or another field | Check the tool schema — add examples to the prompt |
+| "Missing required parameter" | Model forgot `action` or another field | Check the tool schema: add examples to the prompt |
 | Collaboration edits not appearing | SDK not in the same collab room | Verify the collaboration URL and documentId match |
 | Operation works via API but fails via tool | Model passes wrong argument types/names | Log the parsed arguments and compare to the API signature |
 
@@ -130,13 +130,13 @@ while (iterations++ < MAX_ITERATIONS) {
 }
 
 if (iterations >= MAX_ITERATIONS) {
-  console.warn('[agent] Hit max iterations — stopping');
+  console.warn('[agent] Hit max iterations: stopping');
 }
 ```
 
 ## Related
 
-- [LLM tools](/ai/agents/llm-tools) — tool catalog and SDK functions
-- [How to use](/ai/agents/integrations) — step-by-step integration guide
-- [Best practices](/ai/agents/best-practices) — prompting and workflow tips
-- [Document API](/document-api/overview) — the underlying operations that tools call
+- [LLM tools](/ai/agents/llm-tools): tool catalog and SDK functions
+- [How to use](/ai/agents/integrations): step-by-step integration guide
+- [Best practices](/ai/agents/best-practices): prompting and workflow tips
+- [Document API](/document-api/overview): the underlying operations that tools call