Overhaul UI Customization docs: new structure, reference tree, and AI plugin integration

.mintignore

@@ -1,12 +1,22 @@
-# Files excluded from the Mintlify docs build (gitignore syntax).
-# scripts/ holds the skills-sync pipeline + reference artifacts (e.g.
-# reference-artifacts/format-guide.md) — internal tooling, not docs pages.
-# Its template syntax (<optional ...**bold**...>) is not valid MDX and breaks
-# the build, so exclude the whole directory.
-scripts/
+# Exclude from Mintlify processing (.gitignore syntax).
+# See https://www.mintlify.com/docs/organize/mintignore
+#
+# Note: node_modules and .claude are ignored by default in recent Mintlify
+# versions, but list them explicitly so older CLIs stay quiet.
 
-# Internal release-notes pipeline artifacts and agent logs — not docs pages.
-# These contain raw text/JSX-like snippets that aren't valid MDX and break the
-# build (e.g. "Could not parse import/exports with acorn").
+# Dependencies / tooling
+node_modules/
+scripts/
 .pipeline-scratch/
 .claude/
+.cursor/
+.agents/
+.git/
+.github/
+
+# Scratch / temp docs that aren't published pages
+temp-release-notes*.mdx
+WIREFRAME_VARIABLES_TEMPLATE.md
+SKILLS_SYNC_PIPELINE.md
+CLAUDE.md
+README.md

api-reference/sdk/api/api-methods.mdx

@@ -3890,7 +3890,7 @@ Reset the state of Velt Button components.
 - Params: (optional) [VeltResetButtonStateConfig](/api-reference/sdk/models/data-models#veltresetbuttonstateconfig)
 - Returns: `void`
 - React Hook: `n/a`
-- [Full Documentation →](/ui-customization/custom-action-component#reset-velt-button-state)
+- [Full Documentation →](/ui-customization/patterns-and-tips#reset-a-veltbuttonwireframe-after-app-logic-runs)
 
 
 

api-reference/sdk/models/data-models.mdx

@@ -2619,11 +2619,11 @@ class ReactionMetadata extends BaseMetadata {
 
 ### Comment Dialog Primitives
 
-Types for the 92+ primitive components used to build custom comment dialog interfaces. See [Comment Dialog Primitives Overview](/ui-customization/features/async/comments/comment-dialog/primitives) for usage examples.
+Types for the 92+ primitive components used to build custom comment dialog interfaces. See [`Primitive components`](/ui-customization/reference/primitives) for the complete component list and [`Primitives`](/ui-customization/primitives) for usage guidance.
 
 #### CommentDialogCommonProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#common-inputs)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Base props inherited by all Comment Dialog primitive components.
 
@@ -2637,7 +2637,7 @@ Base props inherited by all Comment Dialog primitive components.
 
 #### CommentDialogContextWrapperProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcontextwrapper)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for the VeltCommentDialogContextWrapper component.
 
@@ -2651,7 +2651,7 @@ Props for the VeltCommentDialogContextWrapper component.
 
 #### ThreadCardProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcard)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogThreadCard with priority-based comment lookup.
 
@@ -2665,7 +2665,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### CommentIndexProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcardavatar)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for thread card sub-components that require a comment index.
 
@@ -2677,7 +2677,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### ComposerProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposer)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogComposer with placeholder and edit mode options.
 
@@ -2697,7 +2697,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### ComposerInputProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposerinput)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogComposerInput.
 
@@ -2709,7 +2709,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### StatusDropdownItemProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogstatusdropdowncontentitem)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogStatusDropdownContentItem with priority-based status lookup.
 
@@ -2723,7 +2723,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### PriorityDropdownItemProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogprioritydropdowncontentitem)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogPriorityDropdownContentItem with priority-based priority lookup.
 
@@ -2737,7 +2737,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### OptionsDropdownProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogoptionsdropdown)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogOptionsDropdown with feature enable flags.
 
@@ -2761,7 +2761,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### CustomAnnotationItemProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcustomannotationdropdowntriggerlistitem)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for custom annotation dropdown items.
 
@@ -2774,7 +2774,7 @@ Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonpr
 
 #### ReplyAvatarsListItemProps
 
-## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogreplyavatarslistitem)
+Related docs: [`Primitives`](/ui-customization/primitives) for implementation guidance and [`Primitive components`](/ui-customization/reference/primitives) for the exported component list.
 
 Props for VeltCommentDialogReplyAvatarsListItem.
 
@@ -4581,7 +4581,7 @@ Defines the time window and activity cap for a single batching scope.
 
 ### Notification Primitives
 
-Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-panel/primitives) for usage examples.
+Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-panel/primitives) for usage examples and [`Primitives catalog`](/ui-customization/reference/primitives) for the complete component list.
 
 #### NotificationsPrimitiveCommonProps
 [Usage Examples →](/ui-customization/features/async/notifications/notifications-panel/primitives#common-inputs)

async-collaboration/comments-sidebar/v1/customize-behavior.mdx

@@ -5,7 +5,7 @@ title: "Customize Behavior"
 # Custom filtering, sorting and grouping
   - Here is the overview on how it works:
     - Enable custom actions in the comments sidebar.
-    - Add [Velt Button Wireframe](/ui-customization/custom-action-component) to the sidebar wireframe.
+    - Add the Velt button wireframe to the sidebar wireframe. See [Bridge a wireframe button to your app logic](/ui-customization/patterns-and-tips#bridge-a-wireframe-button-to-your-app-logic-the-onclick-escape-hatch).
     - Handle click events and lifecycle events to apply custom filtering, sorting, and grouping logic.
     - Update sidebar data.
   - Here are the steps to implement it:
@@ -42,7 +42,7 @@ title: "Customize Behavior"
   </Step>
 
   <Step title="Add Velt Buttons and handle click events">
-    - Learn more about how to setup [Velt Button Wireframe](/ui-customization/custom-action-component).
+    - Learn more about how to set up a [wireframe button for app logic](/ui-customization/patterns-and-tips#bridge-a-wireframe-button-to-your-app-logic-the-onclick-escape-hatch).
     - Set default state using the `active` prop.
     - Handle `veltButtonClick` event to implement custom filtering, sorting, and grouping logic. It returns [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent).
 
@@ -609,7 +609,7 @@ Default: `true`
 - Enabling this mode also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and trigger a callback. Learn more about it [here](#oncommentnavigationbuttonclick).
 
 <Warning>
-  If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/wireframes#header) and the [focused thread wireframe](/ui-customization/features/async/comments/comment-sidebar-structure-v2).
+  If you had previously used a wireframe for the comment dialog, you will need to add the navigation button wireframe and the focused thread wireframe. See the [`Component catalog`](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) and [`Wireframe components`](/ui-customization/reference/wireframe-components) for the current slot names.
 </Warning>
 
 <Tabs>

async-collaboration/comments-sidebar/v2/customize-behavior.mdx

@@ -196,7 +196,7 @@ Default: `[]`
 
 A **path predicate** is a rule that keeps only comments whose value at a given field path matches. For example, `{ path: 'from.userId', value: '1.1' }` keeps comments authored by the user with id `1.1`. The `value` is a literal (there is no `@me` token), and paths auto-flatten nested arrays (e.g. `comments.taggedUserContacts.contact.userId`).
 
-Each dropdown is rendered by the filter-dropdown primitive ([`VeltCommentSidebarV2FilterDropdown`](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown) / `velt-comment-sidebar-filter-dropdown-v2`).
+Each dropdown is rendered by the filter-dropdown primitive (`VeltCommentSidebarV2FilterDropdown` / `velt-comment-sidebar-filter-dropdown-v2`). See [`Primitive components`](/ui-customization/reference/primitives) for the current primitive list.
 
 The examples below show one dropdown per `type`.
 
@@ -331,7 +331,7 @@ To match several paths in one quick filter, give an action a list of `conditions
 </Tabs>
 
 <Note>
-Prefer configuring dropdowns through `minimalFilters` as shown above. If you need to place or restyle a dropdown directly in your own markup, you can set these same inputs on the filter-dropdown primitive — see [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives#veltcommentsidebarv2filterdropdown).
+Prefer configuring dropdowns through `minimalFilters` as shown above. If you need to place or restyle a dropdown directly in your own markup, you can set these same inputs on the filter-dropdown primitive — see [`Primitives`](/ui-customization/primitives) and [`Primitive components`](/ui-customization/reference/primitives).
 </Note>
 
 #### defaultMinimalFilter
@@ -1350,5 +1350,5 @@ commentElement.toggleCommentSidebar();
 </Tabs>
 
 <Note>
-For V2 customization, see [Comment Sidebar V2 Wireframes](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-wireframes) and [Comment Sidebar V2 Primitives](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives). The sidebar is shadow-DOM isolated by default.
+For V2 wireframe and primitive customization, start with the [`Component catalog`](/ui-customization/reference/component-catalog#sidebar-slot-trees), then use [`Wireframe components`](/ui-customization/reference/wireframe-components) for the complete slot tree and [`Primitive components`](/ui-customization/reference/primitives) for the primitive list. The sidebar is shadow-DOM isolated by default.
 </Note>

async-collaboration/comments-sidebar/v2/setup.mdx

@@ -42,4 +42,4 @@ export default function App() {
 
 For V2 props reference, see [`VeltCommentsSidebarV2Props`](/api-reference/sdk/models/data-models#veltcommentssidebarv2props).
 
-For V2 wireframe customization, see [Comment Sidebar V2 Wireframes](/ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-wireframes).
+For V2 wireframe customization, start with the [`Component catalog`](/ui-customization/reference/component-catalog#sidebar-slot-trees), then use [`Wireframe components`](/ui-customization/reference/wireframe-components) for the complete slot tree.

async-collaboration/comments/customize-behavior.mdx

@@ -905,7 +905,7 @@ Programmatically submit a comment from a composer. Enables custom buttons or key
 
 - Params: [`SubmitCommentRequest`](/api-reference/sdk/models/data-models#submitcommentrequest)
 - Returns: `void`
-- See also: [Comment Composer targetComposerElementId](/ui-customization/features/async/comments/standalone-components/comment-composer#target-composer-element-id)
+- See also: [Comment Composer targetComposerElementId](/async-collaboration/comments/standalone-components/comment-composer/customize-behavior)
 
 <Tabs>
 <Tab title="React / Next.js">
@@ -9349,4 +9349,3 @@ subscription?.unsubscribe()
 ```
 </Tab>
 </Tabs>
-

async-collaboration/comments/standalone-components/comment-composer/overview.mdx

@@ -8,6 +8,6 @@ The Comment Standalone Composer enables you to add comments anywhere in your app
 - [Comment Data APIs](/async-collaboration/comments/customize-behavior#getcommentannotations): Fetch and submit comment data.
 - [Comment Thread](/async-collaboration/comments/standalone-components/comment-thread/overview): Render comment threads using fetched data.
 - [Comment Pin](/async-collaboration/comments/standalone-components/comment-pin/overview): Display and position comment pins based on fetched data.
-- [Comment Dialog Primitives](/ui-customization/features/async/comments/comment-dialog/primitives): Use 115+ granular components for maximum customization flexibility.
+- [Primitive components](/ui-customization/reference/primitives): Use granular components for maximum customization flexibility.
 
 By combining these components, you can create custom comment interfaces such as sidebars, overlays, popovers, or inline comments. This approach offers greater flexibility and control over your comment system's design and functionality.

async-collaboration/comments/standalone-components/comment-thread/overview.mdx

@@ -8,7 +8,7 @@ sidebarTitle: "Overview"
   - your own version of the `Comments Sidebar` component
 
 - This component does not add any additional functionality. It is just used to render existing comment data.
-- This is a thin wrapper around the [Comment Dialog component](/ui-customization/features/async/comments/comment-dialog/wireframes).
+- This is a thin wrapper around the Comment Dialog component. See the [`Component catalog`](/ui-customization/reference/component-catalog#veltcommentdialogwireframe-slot-tree) and [`Wireframe components`](/ui-customization/reference/wireframe-components) for customization guidance.
 - Get the Comment Annotations data using the APIs.
 - Use this component to render the Comment Annotations data.