# Velt Comments Best Practices
|v1.0.0|Velt|January 2026
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Velt tasks.
|IMPORTANT: VeltProvider requires the `authProvider` prop for authentication. Do NOT use the deprecated `useIdentify` hook. Pattern: `<VeltProvider apiKey={KEY} authProvider={{ user: { userId, organizationId, name, email }, retryConfig: { retryCount: 3, retryDelay: 1000 }, generateToken: async () => { /* fetch from /api/velt/token */ } }}>`. See velt-setup-best-practices for details.
|root: ./rules

## 1. Core Setup — CRITICAL
|react/core:{core-authentication.md,core-document-setup.md}
|shared/core:{core-provider-setup.md}

## 2. Comment Modes — HIGH
|react/mode:{mode-canvas.md,mode-chart-chartjs.md,mode-chart-custom.md,mode-chart-nivo.md,mode-chart-highcharts.md,mode-ace.md,mode-codemirror-comments.md,mode-lexical.md,mode-plate.md,mode-quill.md,mode-slatejs.md,mode-tiptap.md}
|shared/mode:{mode-lottie-player.md,mode-video-player-custom.md,mode-freestyle.md,mode-inline-comments.md,mode-page.md,mode-popover.md,mode-video-player-prebuilt.md,mode-stream.md,mode-text.md}

## 3. Standalone Components — MEDIUM-HIGH
|react/standalone:{standalone-comment-pin.md}
|shared/standalone:{standalone-comment-composer.md,standalone-comment-thread.md}

## 4. Comment Surfaces — MEDIUM-HIGH
|shared/surface:{surface-sidebar.md,surface-sidebar-button.md,surface-sidebar-v2.md}

## 5. UI Customization — MEDIUM
|shared/ui:{ui-comment-bubble.md,ui-comment-dialog.md,ui-v2-primitives.md,ui-autocomplete-primitives.md,ui-wireframes.md}

## 6. Data Model — MEDIUM
|react/data:{data-filtering-grouping.md,data-comment-annotations.md}
|shared/data:{data-context-metadata.md,data-agent-fields-query.md,data-activity-action-types.md,data-comment-annotation-data-provider.md,data-trigger-activities.md,data-annotation-crud.md,data-comment-crud.md,data-read-status.md,data-composer-api.md,data-types-reference.md}

## 7. Debugging & Testing — LOW-MEDIUM
|react/debug:{debug-common-issues.md,debug-verification.md}

## 8. Moderation & Permissions — LOW
|shared/permissions:{permissions-private-mode.md,permissions-comment-interaction-events.md,permissions-anonymous-user-data-provider.md,permissions-visibility-option-dropdown.md,permissions-comment-save-triggered-event.md,permissions-comment-saved-event.md}

## 9. Attachments & Reactions — MEDIUM
|shared/attach:{attach-download-control.md}

## 10. Configuration — MEDIUM
|shared/config:{config-mentions-contacts.md,config-status-priority.md,config-reactions.md,config-attachments.md,config-text-formatting.md,config-navigation.md,config-dom-controls.md,config-sidebar-management.md,config-ui-behavior.md,config-moderation.md}

## 11. Events — MEDIUM
|shared/events:{events-comment-lifecycle.md}

## 12. REST API — HIGH
|shared/rest:{rest-comment-annotations-api.md,rest-comments-api.md}