@docyrus/docyrus 0.0.15 → 0.0.17

package/resources/pi-agent/skills/docyrus-app-ui-design/references/preferred-components-catalog.md

@@ -0,0 +1,242 @@
+# Preferred Components Catalog
+
+Complete reference of all 158 available components across shadcn, diceui, animate-ui, docyrus, and reui libraries.
+
+## Table of Contents
+
+1. [shadcn Components (43)](#shadcn-components-43)
+2. [diceui Components (41)](#diceui-components-41)
+3. [animate-ui Components (21)](#animate-ui-components-21)
+4. [docyrus Components (51)](#docyrus-components-51)
+5. [reui Components (2)](#reui-components-2)
+
+---
+
+## shadcn Components (43)
+
+Core UI components for building accessible, well-designed interfaces.
+
+| Component | Description | Install Command | Docs |
+|-----------|-------------|-----------------|------|
+| Accordion | A vertically stacked set of interactive headings that each reveal a section of content. | `pnpm dlx shadcn@latest add accordion` | docs/components/shadcn-accordion.md |
+| Alert | Displays a callout for user attention. | `pnpm dlx shadcn@latest add alert` | docs/components/shadcn-alert.md |
+| Aspect Ratio | Displays content within a desired ratio. | `pnpm dlx shadcn@latest add aspect-ratio` | docs/components/shadcn-aspect-ratio.md |
+| Avatar | An image element with a fallback for representing the user. | `pnpm dlx shadcn@latest add avatar` | docs/components/shadcn-avatar.md |
+| Badge | Displays a badge or a component that looks like a badge. | `pnpm dlx shadcn@latest add badge` | docs/components/shadcn-badge.md |
+| Breadcrumb | Displays the path to the current resource using a hierarchy of links. | `pnpm dlx shadcn@latest add breadcrumb` | docs/components/shadcn-breadcrumb.md |
+| Button | Displays a button or a component that looks like a button. | `pnpm dlx shadcn@latest add button` | docs/components/shadcn-button.md |
+| Button Group | A container that groups related buttons together with consistent styling. | `pnpm dlx shadcn@latest add button-group` | docs/components/shadcn-button-group.md |
+| Calendar | A calendar component that allows users to select a date or a range of dates. | `pnpm dlx shadcn@latest add calendar` | docs/components/shadcn-calendar.md |
+| Card | Displays a card with header, content, and footer. | `pnpm dlx shadcn@latest add card` | docs/components/shadcn-card.md |
+| Carousel | Displays multiple items in a scrollable container with motion and swipe gestures, commonly used for product galleries or image showcases. | `pnpm dlx shadcn@latest add carousel` | docs/components/shadcn-carousel.md |
+| Chart | A collection of ready-to-use chart components built using Recharts that turn raw data into visual insights. | `pnpm dlx shadcn@latest add chart` | docs/components/shadcn-chart.md |
+| Collapsible | An interactive component that expands and collapses a panel of content, often used to organize information like FAQs or advanced settings. | `pnpm dlx shadcn@latest add collapsible` | docs/components/shadcn-collapsible.md |
+| Command | A React command palette component for fast search and execution of actions using keyboard shortcuts. | `pnpm dlx shadcn@latest add command` | docs/components/shadcn-command.md |
+| Context Menu | Displays a menu of actions or functions, typically triggered by a right-click or long-press. | `pnpm dlx shadcn@latest add context-menu` | docs/components/shadcn-context-menu.md |
+| Date Picker | A date picker component with range and presets. | `pnpm dlx shadcn@latest add popover calendar` | — |
+| Direction | A provider component that sets the text direction for your application. | `pnpm dlx shadcn@latest add direction` | docs/components/shadcn-direction.md |
+| Drawer | A sliding panel that appears from the side or bottom of the screen, commonly used for navigation menus, settings, or additional content, especially on mobile. | `pnpm dlx shadcn@latest add drawer` | docs/components/shadcn-drawer.md |
+| Empty | Used to display an empty state when there is no content or data to show, providing context and guiding user action. | `pnpm dlx shadcn@latest add empty` | docs/components/shadcn-empty.md |
+| Field | Field components combine labels, inputs, error messages, and helper text into complete form field units. | `pnpm dlx shadcn@latest add field` | docs/components/shadcn-field.md |
+| Input | Displays a form input field or a component that looks like an input field. | `pnpm dlx shadcn@latest add input` | docs/components/shadcn-input.md |
+| Input Group | Display additional information or actions to an input or textarea. | `pnpm dlx shadcn@latest add input-group` | docs/components/shadcn-input-group.md |
+| Input OTP | Accessible component designed to collect one-time password codes with individual input fields for each digit. | `pnpm dlx shadcn@latest add input-otp` | docs/components/shadcn-input-otp.md |
+| Item | A versatile component for displaying content with media, title, description, and actions, often used in lists. | `pnpm dlx shadcn@latest add item` | docs/components/shadcn-item.md |
+| Kbd | Display a keyboard key or group of keys. | `pnpm dlx shadcn@latest add kbd` | docs/components/shadcn-kbd.md |
+| Label | Renders an accessible label associated with controls. | `pnpm dlx shadcn@latest add label` | docs/components/shadcn-label.md |
+| Menubar | A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. | `pnpm dlx shadcn@latest add menubar` | docs/components/shadcn-menubar.md |
+| Native Select | A styled native HTML select element with consistent design system integration. | `pnpm dlx shadcn@latest add native-select` | docs/components/shadcn-native-select.md |
+| Navigation Menu | A React component for website navigation with dropdowns, mega menus, and organized content sections. | `pnpm dlx shadcn@latest add navigation-menu` | docs/components/shadcn-navigation-menu.md |
+| Pagination | Pagination provides next/previous buttons and page numbers to navigate through long lists or tables. | `pnpm dlx shadcn@latest add pagination` | docs/components/shadcn-pagination.md |
+| Progress | Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. | `pnpm dlx shadcn@latest add progress` | docs/components/shadcn-progress.md |
+| Resizable | Accessible resizable panel groups and layouts with keyboard support for creating dynamic split views, editors, and dashboards. | `pnpm dlx shadcn@latest add resizable` | docs/components/shadcn-resizable.md |
+| Scroll Area | Augments native scroll functionality for custom, cross-browser styling | `pnpm dlx shadcn@latest add scroll-area` | docs/components/shadcn-scroll-area.md |
+| Select | Displays a list of options for the user to pick from—triggered by a button. | `pnpm dlx shadcn@latest add select` | docs/components/shadcn-select.md |
+| Separator | Visually or semantically separates content. | `pnpm dlx shadcn@latest add separator` | docs/components/shadcn-separator.md |
+| Subtopic | The short description for the 'shadcn Subtopic' component is not available in the provided context. | `pnpm dlx shadcn@latest add subtopic` | — |
+| Skeleton | Displays a placeholder while content is loading. | `pnpm dlx shadcn@latest add skeleton` | docs/components/shadcn-skeleton.md |
+| Slider | Input where the user selects a value from within a given range. | `pnpm dlx shadcn@latest add slider` | docs/components/shadcn-slider.md |
+| Sonner | Displays modern, opinionated, non-intrusive toast notifications for feedback. | `pnpm dlx shadcn@latest add sonner` | docs/components/shadcn-sonner.md |
+| Spinner | An indicator that can be used to show a loading state. | `pnpm dlx shadcn@latest add spinner` | docs/components/shadcn-spinner.md |
+| Table | A responsive component used for displaying simple, structured data like invoices or feature comparisons. | `pnpm dlx shadcn@latest add table` | docs/components/shadcn-table.md |
+| Textarea | Handles multi-line text input, ideal for messages, descriptions, or comments. | `pnpm dlx shadcn@latest add textarea` | docs/components/shadcn-textarea.md |
+| Typography | Styles for headings, paragraphs, lists, and captions. | `pnpm dlx shadcn@latest add typography` | docs/components/shadcn-typography.md |
+
+---
+
+## diceui Components (41)
+
+Advanced, specialized components for complex UI patterns.
+
+| Component | Description | Install Command | Docs |
+|-----------|-------------|-----------------|------|
+| Action Bar | A floating action bar that appears at the bottom or top of the viewport to display contextual actions for selected items. | `pnpm dlx shadcn@latest add "@diceui/action-bar"` | docs/components/action-bar.mdx |
+| Badge Overflow | Displays a list of badges in confined space, using an overflow badge to show a count of hidden badges. | `pnpm dlx shadcn@latest add @diceui/badge-overflow` | docs/components/badge-overflow.mdx |
+| Checkbox Group | A list of options where one or more choices can be selected. | `pnpm dlx shadcn@latest add @diceui/checkbox-group` | docs/components/checkbox-group.mdx |
+| Circular Progress | A widget that shows progress along a circle. | `pnpm dlx shadcn@latest add @diceui/circular-progress` | docs/components/circular-progress.mdx |
+| Color Picker | A compact component providing a wide color spectrum and predefined palette for precise color selection. | `pnpm add @diceui/color-picker` | docs/components/color-picker.mdx |
+| Color Swatch | A color swatch component that displays a color value with optional transparency support. | `pnpm dlx shadcn@latest add "https://diceui.com/r/color-swatch"` | docs/components/color-swatch.mdx |
+| Combobox | A combobox component combines an input field and a dropdown list, allowing users to search, filter, and select from a predefined set of choices. | `pnpm dlx shadcn@latest add @diceui/combobox` | docs/components/combobox.mdx |
+| Compare Slider | Used to compare two images or components side-by-side with a draggable divider. | `pnpm dlx shadcn@latest add "https://diceui.com/r/compare-slider"` | docs/components/compare-slider.mdx |
+| Data Grid | A high-performance editable data grid component with virtualization, keyboard navigation, and comprehensive cell editing capabilities. | `pnpm dlx shadcn@latest add "@diceui/data-table"` | docs/components/data-grid.mdx |
+| Data Table | A powerful and flexible data table component for displaying, filtering, sorting, and paginating tabular data. | `pnpm dlx shadcn@latest add "@diceui/data-table"` | docs/components/data-table.mdx |
+| Editable | An accessible inline editable component for editing text content in place. | `pnpm dlx shadcn@latest add "@diceui/editable"` | docs/components/editable.mdx |
+| File Upload | A comprehensive file upload component built on top of shadcn-ui with drag-and-drop functionality, file preview, progress indicators, and multiple file support. | `pnpm dlx shadcn@latest add "https://diceui.com/r/file-upload"` | docs/components/file-upload.mdx |
+| Gauge | A component that displays a single numeric value in a specified range, often using a dial or arc to show progress. | `pnpm dlx shadcn@latest add "@diceui/gauge"` | docs/components/gauge.mdx |
+| Kanban | A drag and drop kanban board component for organizing items into columns. | `pnpm dlx shadcn@latest add @diceui/kanban` | docs/components/kanban.mdx |
+| Key Value | A dynamic input component for managing key-value pairs with paste support and validation | `pnpm dlx shadcn@latest add @diceui/key-value` | docs/components/key-value.mdx |
+| Listbox | Displays a list of selectable options for single or multiple selection. | `pnpm dlx shadcn@latest add @diceui/listbox` | docs/components/listbox.mdx |
+| Mask Input | An input component that formats user input with predefined patterns. | `pnpm dlx shadcn@latest add @diceui/mask-input` | docs/components/mask-input.mdx |
+| Masonry | A grid layout component that places elements in optimal position based on available vertical space. | `pnpm dlx shadcn@latest add "https://diceui.com/r/masonry"` | docs/components/masonry.mdx |
+| Map Input | I do not have enough information to provide a short description for the "Map Input" component within the context provided. | `pnpm dlx shadcn@latest add "https://diceui.com/r/map-input"` | — |
+| Media Player | Integrates a consistent and accessible video or audio playback experience. | `pnpm dlx shadcn@latest add "https://diceui.com/r/media-player"` | docs/components/media-player.mdx |
+| Mention | Allows mentioning items in a list by a trigger character. | `pnpm dlx shadcn@latest add @diceui/mention` | docs/components/mention.mdx |
+| Phone Input | An accessible phone input component with automatic country detection and international phone number formatting. | `pnpm dlx shadcn@latest add @diceui/phone-input` | docs/components/phone-input.mdx |
+| QR Code | A flexible QR code component for generating and displaying QR codes with customization options. | `pnpm dlx shadcn@latest add "@diceui/qr-code"` | docs/components/qr-code.mdx |
+| Rating | Enables users to apply a rating to an item or experience. | `pnpm dlx shadcn@latest add "https://diceui.com/r/rating"` | docs/components/rating.mdx |
+| Relative Time Card | A hover card that displays relative time relative to local time with timezone information. | `pnpm dlx shadcn@latest add "https://diceui.com/r/relative-time-card"` | docs/components/relative-time-card.mdx |
+| Responsive Dialog | A dialog component that automatically switches between a centered dialog on desktop and a bottom drawer on mobile. | `pnpm dlx shadcn@latest add @diceui/responsive-dialog` | docs/components/responsive-dialog.mdx |
+| Scroll Spy | Dynamically highlights navigation links to indicate the current visible section in the viewport during page scroll. | `pnpm dlx shadcn@latest add @diceui/scroll-spy` | docs/components/scroll-spy.mdx |
+| Scroller | A scrollable container with automatic navigation buttons that appear when content overflows. | `pnpm dlx shadcn@latest add @diceui/scroller` | docs/components/scroller.mdx |
+| Segmented Input | A linear set of two or more segments, each of which functions as a button or toggle for related choices. | `pnpm dlx shadcn@latest add "https://diceui.com/r/segmented-input"` | docs/components/segmented-input.mdx |
+| Selection Toolbar | I do not have a description for the "Selection Toolbar" component in the provided document. | `pnpm dlx shadcn@latest add "@diceui/action-bar"` | docs/components/action-bar.mdx |
+| Sortable | A drag and drop sortable component for reordering items. | `pnpm dlx shadcn@latest add @diceui/sortable` | docs/components/sortable.mdx |
+| Speed Dial | A floating action button that expands to reveal a set of related actions, providing quick access to frequently used functions in a compact interface. | `pnpm dlx shadcn@latest add "@diceui/speed-dial"` | docs/components/speed-dial.mdx |
+| Stack | The main stack container that handles layout and masking of child elements. | `pnpm dlx shadcn@latest add "https://diceui.com/r/stack"` | docs/components/stack.mdx |
+| Stat | Used to show numbers and data in a block. | `pnpm dlx shadcn@latest add "https://diceui.com/r/stat"` | docs/components/stat.mdx |
+| Status | Displays a status indicator icon. | `pnpm dlx shadcn@latest add "https://diceui.com/r/status"` | docs/components/status.mdx |
+| Stepper | A component that guides users through a multi-step process with clear visual progress indicators. | `pnpm dlx shadcn@latest add @diceui/stepper` | docs/components/stepper.mdx |
+| Swap | A component that swaps between two states with click or hover activation modes. | `pnpm dlx shadcn@latest add "https://diceui.com/r/swap"` | docs/components/swap.mdx |
+| Tags Input | A component that allows users to add tags to an input field. | `pnpm dlx shadcn@latest add @diceui/tags-input` | docs/components/tags-input.mdx |
+| Time Picker | Allow users to select specific times for scheduling events or setting appointments. | `pnpm dlx shadcn@latest add "https://diceui.com/r/time-picker"` | docs/components/time-picker.mdx |
+| Timeline | Timeline is a flexible family of components for displaying events, steps, or progress in a vertical or horizontal layout. | `pnpm dlx shadcn@latest add @diceui/timeline` | docs/components/timeline.mdx |
+| Tour | Displays a multi-step component used for interactive tutorials or onboarding new features. | `pnpm dlx shadcn@latest add @diceui/tour` | docs/components/tour.mdx |
+
+---
+
+## animate-ui Components (21)
+
+Animated components with smooth transitions and interactions.
+
+| Component | Description | Install Command | Docs |
+|-----------|-------------|-----------------|------|
+| Alert Dialog | A modal dialog that interrupts the user with important content and expects a response. | `pnpm dlx shadcn@latest add @animate-ui/alert-dialog` | docs/components/animate-ui/alert-dialog.md |
+| Avatar Group | An animated avatar group that displays overlapping user images and smoothly shifts each avatar forward on hover to highlight it. | `pnpm dlx shadcn@latest add @animate-ui/avatar-group` | docs/components/animate-ui/avatar-group.md |
+| Checkbox | A control that allows the user to toggle between checked and not checked. | `pnpm dlx shadcn@latest add @animate-ui/checkbox` | docs/components/animate-ui/checkbox.md |
+| Dialog | A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. | `pnpm dlx shadcn@latest add @animate-ui/dialog` | docs/components/animate-ui/dialog.md |
+| Dropdown Menu | Displays a menu to the user — such as a set of actions or functions — triggered by a button. | `pnpm dlx shadcn@latest add @animate-ui/dropdown-menu` | docs/components/animate-ui/dropdown-menu.md |
+| Files | A component that allows you to display a list of files and folders. | `pnpm dlx shadcn@latest add @animate-ui/file-tree` | docs/components/animate-ui/file-tree.md |
+| Flip Card | A 3D animated card component that flips to reveal content on the back. | `pnpm dlx shadcn@latest add @animate-ui/flip-card` | docs/components/animate-ui/flip-card.md |
+| Management Bar | A management bar that combines pagination, action buttons, and a call-to-action for streamlined item handling. | `pnpm dlx shadcn@latest add @animate-ui/floating-bar` | docs/components/animate-ui/floating-bar.md |
+| Hover Card | For sighted users to preview content available behind a link. | `pnpm dlx shadcn@latest add @animate-ui/hover-card` | docs/components/animate-ui/hover-card.md |
+| Pin List | A playful list for pinning and unpinning items, with smooth animated transitions as items move between groups. | `pnpm dlx shadcn@latest add @animate-ui/pin-list` | docs/components/animate-ui/pin-list.md |
+| Popover | Displays rich content in a portal, triggered by a button. | `pnpm dlx shadcn@latest add @animate-ui/popover` | docs/components/animate-ui/popover.md |
+| Preview Link Card | Displays a preview image of a link when hovered. | `pnpm dlx shadcn@latest add @animate-ui/preview-link` | docs/components/animate-ui/preview-link.md |
+| Radial Menu | A circular context menu built with Base UI, displaying actions in a clean radial layout with full keyboard support and smooth interaction. | `pnpm dlx shadcn@latest add @animate-ui/radial-menu` | docs/components/animate-ui/radial-menu.md |
+| Radio Group | A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. | `pnpm dlx shadcn@latest add @animate-ui/radio-group` | docs/components/animate-ui/radio-group.md |
+| Sheet | Extends the Dialog component to display content that complements the main content of the screen. | `pnpm dlx shadcn@latest add @animate-ui/sheet` | docs/components/animate-ui/sheet.md |
+| Sidebar | A composable, themeable and customizable sidebar component. Created by Shadcn and animated by Animate UI. | `pnpm dlx shadcn@latest add @animate-ui/sidebar` | docs/components/animate-ui/sidebar.md |
+| Switch | A control that allows the user to toggle between checked and not checked. | `pnpm dlx shadcn@latest add @animate-ui/switch` | docs/components/animate-ui/switch.md |
+| Tabs | A set of layered sections of content—known as tab panels—that are displayed one at a time. | `pnpm dlx shadcn@latest add @animate-ui/tabs` | docs/components/animate-ui/tabs.md |
+| Toggle Group | A set of two-state buttons that can be toggled on or off. | `pnpm dlx shadcn@latest add @animate-ui/toggle-group` | docs/components/animate-ui/toggle-group.md |
+| Toggle | A two-state button that can be either on or off. | `pnpm dlx shadcn@latest add @animate-ui/toggle` | docs/components/animate-ui/toggle.md |
+| Tooltip | A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. | `pnpm dlx shadcn@latest add @animate-ui/tooltip` | docs/components/animate-ui/tooltip.md |
+
+---
+
+## docyrus Components (51)
+
+Docyrus-specific components for data handling, forms, dialogs, editing, scheduling, chat, AI agents, and business logic.
+
+| Component | Description | Install Command | Docs |
+|-----------|-------------|-----------------|------|
+| Awesome Dialog | Advanced dialog system with three container modes (modal, sheet, drawer), side positioning, size presets, pattern backgrounds, fullscreen/minimize/resize support, and global dialog management via GlobalDialogProvider. The primary dialog system for item creation forms and small item detail views. | `pnpm dlx @docyrus/cli add @docyrus/ui-awesome-dialog` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/awesome-dialog/llms.txt) |
+| Awesome Card | A card with a hatched-stripe header and an inset content area, perfect for displaying stats and metrics. | `pnpm dlx @docyrus/cli add @docyrus/ui-awesome-card` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/awesome-card/llms.txt) |
+| Awesome Stats | Data-driven metric cards with grid, flex, and animated tabs layouts. Supports sparkline/bar/area mini-charts, comparison deltas, drag-and-drop reordering, Intl.NumberFormat value formatting, and AwesomeCard styling mode. | `pnpm dlx @docyrus/cli add @docyrus/ui-awesome-stats` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/awesome-stats/llms.txt) |
+| Avatar Select | Avatar Select component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-avatar-select` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/avatar-select/llms.txt) |
+| Avatar Thumbnail | Avatar Thumbnail component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-avatar-thumbnail` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/avatar-thumbnail/llms.txt) |
+| Calendar | Advanced calendar with month/week/day/agenda views, drag-and-drop event management, multi-user support, and loading states. | `pnpm dlx @docyrus/cli add @docyrus/ui-calendar` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/calendar/llms.txt) |
+| Comments Panel | Comment discussion panel with threaded conversations, mention input, and editor support. | `pnpm dlx @docyrus/cli add @docyrus/ui-comments-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/comments-panel/llms.txt) |
+| Confirmation Button | Button with built-in confirmation dialog for destructive or important actions. | `pnpm dlx @docyrus/cli add @docyrus/ui-confirmation-button` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/confirmation-button/llms.txt) |
+| Contact Activity Panel | Contact-centric activity timeline showing calls, meetings, emails, tasks, chats, and record changes. Supports threaded replies, emoji reactions, file attachments, @mentions, and entity linking. Filter by activity type with animated transitions. | `pnpm dlx @docyrus/cli add @docyrus/ui-contact-activity-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/contact-activity-panel/llms.txt) |
+| Create Record Dialog | Quick-create popover dialog for new records with subject/description inputs, inline mention triggers, selector fields (header and footer), AI actions, footer toggles, and create-more support. Designed for fast item creation without a full form. | `pnpm dlx @docyrus/cli add @docyrus/ui-create-record-dialog` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/create-record-dialog/llms.txt) |
+| Data Grid | A virtualized, editable spreadsheet-like data grid with sorting, filtering, grouping, cell selection, and keyboard navigation. Supports grid/gallery/card display modes. | `pnpm dlx @docyrus/cli add @docyrus/ui-data-grid` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/data-grid/llms.txt) |
+| Data Grid View Select | View selector companion for Data Grid. Supports dropdown, horizontal-tabs, and vertical-tabs variants. Manages saved views with sort, filter (query builder), column visibility, grouping, and view CRUD operations. | `pnpm dlx @docyrus/cli add @docyrus/ui-data-grid-view-select` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/data-grid-view-select/llms.txt) |
+| Data Table Filter | A composable filter bar for data tables with text, number, date, option, and multi-option column types. | `pnpm dlx @docyrus/cli add @docyrus/ui-data-table-filter` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/data-table-filter/llms.txt) |
+| Date Time Picker | Date Time Picker component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-date-time-picker` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/date-time-picker/llms.txt) |
+| Date Time Range Picker | Select start and end date/time pairs with sm/default/lg size variants. Integrates with react-hook-form. | `pnpm dlx @docyrus/cli add @docyrus/ui-date-time-range-picker` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/date-time-range-picker/llms.txt) |
+| Day Picker | Day Picker component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-day-picker` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/day-picker/llms.txt) |
+| Delete Confirm Dialog | Delete Confirm Dialog component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-delete-confirm-dialog` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/delete-confirm-dialog/llms.txt) |
+| Docyrus Agent | AI agent interface with three modes: chat (conversational), action-panel (parameter-based actions), and trigger (floating button that opens dialog). Supports Vercel AI SDK messages, file attachments, action execution with typed params, agent profiles, and source documents. | `pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-agent` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/docyrus-agent/llms.txt) |
+| Docyrus Icon | Docyrus Icon component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-icon` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/docyrus-icon/llms.txt) |
+| Duration Select | Duration Select component with multiple variants and sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-duration-select` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/duration-select/llms.txt) |
+| Editable Record Detail | Complete inline record editor with field-level change tracking, floating ActionBar showing pending changes, save/cancel with diff preview, and TanStack Form compatible API. Use for detail views where users edit individual fields without opening a full form. | `pnpm dlx @docyrus/cli add @docyrus/ui-editable-record-detail` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/editable-record-detail/llms.txt) |
+| Editable Value | Single-field inline editor that renders DynamicValue in display mode and switches to DynamicFormField on click. Supports inline, popover, and instant-save field types with automatic save/cancel behavior. | `pnpm dlx @docyrus/cli add @docyrus/ui-editable-value` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/editable-value/llms.txt) |
+| Email Composer | Email composition component with To/Cc/Bcc recipient fields (chip-based input with validation), subject line, rich-text body with formatting toolbar (bold, italic, underline, strikethrough, links, lists), file attachments display, and send/discard actions. Supports default/outline/minimal variants and sm/default/lg sizes. | `pnpm dlx @docyrus/cli add @docyrus/ui-email-composer` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/email-composer/llms.txt) |
+| File Attachment Panel | File management panel with upload zone, file list/grid views, and empty state handling. | `pnpm dlx @docyrus/cli add @docyrus/ui-file-attachment-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/file-attachment-panel/llms.txt) |
+| Form Fields | Dynamic form field system powered by TanStack Form. 47 field types with automatic dispatch via DynamicFormField. | `pnpm dlx @docyrus/cli add @docyrus/ui-form-fields` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/form-fields/llms.txt) |
+| Gantt | Gantt chart visualization for project timelines, task dependencies, and scheduling. | `pnpm dlx @docyrus/cli add @docyrus/ui-gantt` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/gantt/llms.txt) |
+| Image Editor | Advanced image editor with cropping, adjustments, and transformation tools. | `pnpm dlx @docyrus/cli add @docyrus/ui-image-editor` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/image-editor/llms.txt) |
+| Kanban | Drag-and-drop kanban board with sortable columns and cards. Built on dnd-kit with keyboard navigation, multi-container support, collision detection, and drag overlay. Compound components: Kanban, KanbanBoard, KanbanColumn, KanbanCard, KanbanCardHandle, KanbanOverlay. | `pnpm dlx @docyrus/cli add @docyrus/ui-kanban` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/kanban/llms.txt) |
+| Log Activity Form | Capture activities (calls, emails, meetings, tasks, status updates, comments) with rich Plate editor, mention users, calendar event linking, status tracking, and follow-up dates. Specialized sections for each activity type. | `pnpm dlx @docyrus/cli add @docyrus/ui-log-activity-form` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/log-activity-form/llms.txt) |
+| Map | Map visualization component built on Leaflet for displaying geographic data and locations. | `pnpm dlx @docyrus/cli add @docyrus/ui-map` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/map/llms.txt) |
+| Mega Select | Large grid-based item selector with category tabs, search, detail panel, and keyboard navigation. Supports thin/default/large/full sizes and default/elevated/flat variants. Ideal for template pickers, product catalogs, or any rich selection UI with icons, images, colors, and descriptions. | `pnpm dlx @docyrus/cli add @docyrus/ui-mega-select` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/mega-select/llms.txt) |
+| Morph Popover | Morphing popover that smoothly transitions between trigger and content states. | `pnpm dlx @docyrus/cli add @docyrus/ui-morph-popover` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/morph-popover/llms.txt) |
+| Notification Stack | Stacked notification cards with animation for displaying multiple notifications. | `pnpm dlx @docyrus/cli add @docyrus/ui-notification-stack` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/notification-stack/llms.txt) |
+| Notifications Panel | Full notification panel for managing and displaying user notifications. | `pnpm dlx @docyrus/cli add @docyrus/ui-notifications-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/notifications-panel/llms.txt) |
+| Pivot Grid | Sophisticated pivot table with 3-level row/column hierarchies, subtotals, grand totals, drilldown to raw data, pinning, resizing, conditional cell coloring via JSONata, and export to CSV/Excel/PDF. Built on TanStack Table + TanStack Virtual. | `pnpm dlx @docyrus/cli add @docyrus/ui-pivot-grid` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/pivot-grid/llms.txt) |
+| Place Autocomplete | Location autocomplete input with address search and selection. | `pnpm dlx @docyrus/cli add @docyrus/ui-place-autocomplete` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/place-autocomplete/llms.txt) |
+| Pricing Engine Panel | Full pricing/quoting engine with editable line items table, product catalog integration, category hierarchy, per-line and global discounts, multi-VAT rate support, currency with secondary currency and exchange rates, net/gross view modes, totals/VAT summary, description and terms sections, and save/draft actions. Variants: default/bordered/compact. | `pnpm dlx @docyrus/cli add @docyrus/ui-pricing-engine-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/pricing-engine-panel/llms.txt) |
+| Query Builder | Visual query builder for constructing filter conditions with drag-and-drop, rule numbers, and depth control. | `pnpm dlx @docyrus/cli add @docyrus/ui-query-builder` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/query-builder/llms.txt) |
+| Radio Group | Radio group with "default" (simple list) and "card" (selectable cards) variants. Options support icons, descriptions, and color accents. Grid layout with configurable column count (1-4). | `pnpm dlx @docyrus/cli add @docyrus/ui-radio-group` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/radio-group/llms.txt) |
+| Record Activity Panel | Activity log panel for displaying record history and audit trail. | `pnpm dlx @docyrus/cli add @docyrus/ui-record-activity-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/record-activity-panel/llms.txt) |
+| Record Delete Confirm Dialog | Domain-specific delete confirmation with record context. | `pnpm dlx @docyrus/cli add @docyrus/ui-record-delete-confirm-dialog` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/record-delete-confirm-dialog/llms.txt) |
+| Record Sharing | Record sharing panel with bitmask permission system (Read/Write/Comment/Share/Delete), permission presets (Can View/Comment/Edit/Share/Full Access), search for users/teams/roles/tenants, and per-entity permission management. Trigger variants: button or avatar-group. | `pnpm dlx @docyrus/cli add @docyrus/ui-record-sharing` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/record-sharing/llms.txt) |
+| Resource Scheduler Panel | Horizontal timeline resource scheduler with configurable presets (hour/day/week/month/year), drag-and-drop event moving and resizing, resource list with custom TanStack Table columns, today indicator, event popovers, and event bar variants (solid/outlined/subtle). | `pnpm dlx @docyrus/cli add @docyrus/ui-resource-scheduler-panel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/resource-scheduler-panel/llms.txt) |
+| Schema Repeater | Dynamic list manager for structured data entries with customizable input types per column. Ideal for filter rule builders, key-value editors, and repeating field groups. | `pnpm dlx @docyrus/cli add @docyrus/ui-schema-repeater` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/schema-repeater/llms.txt) |
+| Search Input | Dedicated search input component with search icon and clear button. | `pnpm dlx @docyrus/cli add @docyrus/ui-search-input` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/search-input/llms.txt) |
+| Simple Markdown Editor | Lightweight markdown editor powered by overtype with configurable toolbar, auto-resize, word/character stats, spellcheck, and resizable handle. Variants: default/muted. Sizes: sm/default/lg. Exposes imperative ref for focus/blur/getValue/setValue. | `pnpm dlx @docyrus/cli add @docyrus/ui-simple-markdown-editor` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/simple-markdown-editor/llms.txt) |
+| Stepper | Multi-step progress indicator with 6 visual variants (default, outline, dots, dashed, gradient, minimal), horizontal/vertical orientations, three sizes, non-linear navigation, alternative label positioning, custom icons, and animated connectors. | `pnpm dlx @docyrus/cli add @docyrus/ui-stepper` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/stepper/llms.txt) |
+| Team Chat Channel | Full-featured team chat component with rich text posts (Plate editor), threaded replies, emoji reactions, file attachments, link previews, entity mentions (@-trigger linked to data sources), hashtags, post editing/deletion, and real-time-ready callbacks. | `pnpm dlx @docyrus/cli add @docyrus/ui-team-chat-channel` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/team-chat-channel/llms.txt) |
+| Time Slot Scheduler | Appointment booking scheduler with columns view (multi-day time grid) and month calendar view. Manages slot capacity, reservations, unavailable ranges, timezone selection, weekend toggle, min/max date bounds, and slot popover with reservation details. Ideal for booking pages and availability scheduling. | `pnpm dlx @docyrus/cli add @docyrus/ui-time-slot-scheduler` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/time-slot-scheduler/llms.txt) |
+| Tree View | Tree/hierarchy visualization component for displaying nested data structures. | `pnpm dlx @docyrus/cli add @docyrus/ui-tree-view` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/tree-view/llms.txt) |
+| Value Renderers | Read-only value display system for table cells, detail views, and kanban cards. 44 renderer types with automatic dispatch via DynamicValue. | `pnpm dlx @docyrus/cli add @docyrus/ui-value-renderers` | [llms.txt](https://alpha-ui.docy.app/docs/web/components/value-renderers/llms.txt) |
+
+---
+
+## reui Components (2)
+
+Utility components for specialized file and sorting operations.
+
+| Component | Description | Install Command | Docs |
+|-----------|-------------|-----------------|------|
+| File Upload | Allows users to transfer files from their devices to a web application. | `pnpm dlx shadcn@latest add @reui/file-upload-default` | docs/components/reui-file-upload.md |
+| Sortable | Allows reordering of items within a list or grid using drag-and-drop functionality. | `pnpm dlx shadcn@latest add @reui/sortable` | docs/components/reui-sortable.md |
+
+---
+
+## Docyrus UI Guide Documentation
+
+Fetch these llms.txt endpoints for detailed guidance on installation, theming, and patterns:
+
+| Guide | Description | Docs |
+|-------|-------------|------|
+| Components Overview | Production-ready UI components built with React, TypeScript, Tailwind CSS v4, and CVA variants. | [llms.txt](https://alpha-ui.docy.app/docs/web/components/llms.txt) |
+| Installation | How to install and set up Docyrus UI components in your project. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/installation/llms.txt) |
+| Theming | Customize the look and feel of Docyrus UI components with CSS variables and the theme generator. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/theming/llms.txt) |
+| Distributions | Component distributions and core libraries that power Docyrus UI web components. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/distributions/llms.txt) |
+| Examples & Recipes | Practical multi-component patterns and recipes for common UI scenarios. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/examples/llms.txt) |
+| Troubleshooting | Common issues and solutions when using Docyrus UI web components. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/troubleshooting/llms.txt) |
+| Releases | Latest releases and updates for Docyrus UI web components. | [llms.txt](https://alpha-ui.docy.app/docs/web/guide/releases/llms.txt) |
+
+---
+
+## Component Count Summary
+
+- **shadcn**: 43 components
+- **diceui**: 41 components
+- **animate-ui**: 21 components
+- **docyrus**: 51 components
+- **reui**: 2 components
+
+**Total**: 158 components

package/resources/pi-agent/skills/docyrus-apps/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: docyrus-apps
+description: App commands. Archive an app, List apps (/v1/apps), Permanently delete an app, Restore an archived app. Run `docyrus apps --help` for usage details.
+command: docyrus apps
+---
+
+# docyrus apps delete
+
+Archive an app
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--appId` | `string` |  | App ID |
+| `--appSlug` | `string` |  | App slug |
+
+---
+
+# docyrus apps list
+
+List apps (/v1/apps)
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--appType` | `string` |  | Optional app type filter |
+
+---
+
+# docyrus apps permanent-delete
+
+Permanently delete an app
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--appId` | `string` |  | App ID |
+| `--appSlug` | `string` |  | App slug |
+
+---
+
+# docyrus apps restore
+
+Restore an archived app
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--appId` | `string` |  | App ID |
+| `--appSlug` | `string` |  | App slug |

package/resources/pi-agent/skills/docyrus-architect/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: docyrus-architect
+description: Use the Docyrus Architect MCP tools to manage data sources, fields, enums, apps, custom queries, and query data in the Docyrus platform. Use when the user asks to create, update, delete, or query data sources, fields, enum options, apps, or custom query templates via the docyrus-architect MCP server. Also use when building reports, dashboards, or performing data analysis that requires querying Docyrus data sources or running custom SQL templates with filters, aggregations, formulas, pivots, or child queries.
+---
+
+# Docyrus Architect
+
+Guide for using `docyrus-architect` MCP tools to manage and query data sources in Docyrus.
+
+## Tool Overview
+
+### Discovery Tools
+- `get_apps` — List tenant apps. Use before `create_data_source` to find the target `tenantAppId`.
+- `get_data_source_list` — Search data sources by name/description or app ID.
+- `get_data_source_list_with_fields` — Same as above but includes field names and types.
+- `get_data_source_metadata` — Get full metadata (fields with IDs, types, slugs, enums, relations) for a data source. **Always call this before querying** to discover field slugs and relation targets.
+- `get_enums_by_field_id` — Get enum options for select/status/tagSelect fields.
+- `read_current_user` / `read_tenant_user` — Get user info.
+
+### Data Source CRUD
+- `create_data_source` — Create a new data source (table). Default fields auto-created: `id`, `autonumber_id`, `name`, `record_owner`, `created_on`, `created_by`, `last_modified_by`, `last_modified_on`.
+- `create_data_sources_batch` — Create multiple data sources with fields and enum options in a single atomic transaction. Supports cross-referencing data sources within the batch by slug for `field-relation` types. Max 20 data sources per batch.
+- `update_data_source` — Update data source properties.
+- `delete_data_source` — Delete a data source and all its data.
+
+### Field Management
+- `create_fields` — Batch create fields. Set `relationDataSourceId` for `field-relation` types.
+- `update_fields` — Batch update fields. Non-CUSTOM fields get customization records.
+- `delete_fields` — Batch delete fields by ID.
+
+### Enum Management
+- `create_enums` — Create enum options for select/tagSelect/status fields. Pass `fieldId` for field-specific enums or `enumSetId` for shared enum sets.
+- `update_enums` — Update enum option name/slug/color/icon.
+- `delete_enums` — Delete enum options.
+
+### OpenAPI Spec
+- `regenerate_openapi_spec` — Regenerate and upload the tenant's OpenAPI spec after data source or field changes. Accepts optional `dataSourceSlugs` (string array) to limit scope; omit to include all data sources. Returns the `publicUrl` of the uploaded spec. **Call this after any `create_data_source`, `update_data_source`, `delete_data_source`, `create_fields`, `update_fields`, or `delete_fields` operation** to keep the spec in sync.
+
+### Query & Compute
+- `query_data_source` — Read data with filtering, sorting, aggregation, formulas, pivots, child queries. **See [references/data-source-query-guide.md](references/data-source-query-guide.md) for complete query syntax.**
+- `evaluate_jsonata` — Test JSONata expressions. Use for validating computed field formulas.
+
+### Custom Queries
+- `get_custom_queries` — List non-archived custom queries for the tenant.
+- `get_custom_query_by_id` — Read full custom query definition (`name`, `description`, `query`, `filters`).
+- `create_custom_query` — Create a saved SQL template using Handlebars variables and optional filter definitions.
+- `update_custom_query` — Update selected fields of an existing custom query (partial update).
+- `delete_custom_query` — Soft-delete (archive) a custom query.
+- `run_custom_query` — Execute a saved custom query with runtime filters, pagination offset, and optional simulate mode.
+
+## Common Workflows
+
+### Create a Data Source with Fields and Enums
+
+**Single data source approach:**
+1. Call `get_apps` to find the target app ID
+2. Call `create_data_source` with title (plural), name (singular), slug (singular snake_case)
+3. Call `create_fields` with all custom fields (default fields already exist)
+4. For select/tagSelect/status fields, call `create_enums` with the field ID from step 3
+5. Call `regenerate_openapi_spec` to update the OpenAPI spec
+
+**Batch approach (recommended for multiple data sources):**
+1. Call `get_apps` to find the target app ID (optional, defaults to "Default Customizations App")
+2. Call `create_data_sources_batch` with an array of data source definitions (max 20)
+   - Each data source includes `title`, `name`, `slug`, and `fields` array
+   - Fields can include inline `enumOptions` for select/status/tagSelect fields
+   - Use slug references for `relationDataSourceId` to reference other data sources in the same batch
+   - All data sources, fields, and enums are created in a single atomic transaction
+3. Call `regenerate_openapi_spec` to update the OpenAPI spec
+
+### Query Data
+
+1. Call `get_data_source_metadata` to discover field slugs, types, and relations
+2. Call `query_data_source` with appropriate columns, filters, and sorting
+3. For advanced queries (aggregations, formulas, pivots, child queries), read [references/data-source-query-guide.md](references/data-source-query-guide.md)
+
+### Modify Existing Data Source
+
+1. Call `get_data_source_metadata` to see current fields
+2. Use `create_fields` / `update_fields` / `delete_fields` as needed
+3. For enum changes, use `get_enums_by_field_id` first, then `create_enums` / `update_enums` / `delete_enums`
+4. Call `regenerate_openapi_spec` to update the OpenAPI spec
+
+### Manage a Custom Query Lifecycle
+
+1. Call `get_custom_queries` to find an existing query or confirm naming
+2. Call `create_custom_query` with `name`, `query`, and optional `description`/`filters`
+3. Call `get_custom_query_by_id` to verify the saved template and filter definitions
+4. Use `update_custom_query` for targeted edits (rename, revise SQL template, update filter definitions)
+5. Use `delete_custom_query` only when archival is explicitly requested
+
+### Run and Debug a Custom Query
+
+1. Call `get_custom_query_by_id` first to inspect SQL template and available filter slugs
+2. Build runtime `filters` with `rules[].field` values that match the query's filter slugs
+3. Call `run_custom_query` with `simulate: true` for complex or untrusted queries to inspect plan output
+4. Call `run_custom_query` with `simulate: false` (or omitted) to fetch real data
+5. Use `offset` for pagination and expect a max of 50,000 rows per execution
+
+## Key Rules
+
+### Data Source Creation
+- `title` is plural (e.g., "Sales Orders"), `name` is singular (e.g., "Sales Order"), `slug` is singular snake_case (e.g., "sales_order")
+- Use `defaultEditFormTarget: "tab"` for complex forms, `"side"` for simple ones
+- Enable `pluginActivityView` for CRM-type data sources (leads, contacts, deals)
+- Enable `pluginComments` for collaborative data sources
+- Enable `pluginFile` when users need to attach files to records
+- Enable `pluginDocyment` when users need rich text documents per record
+
+### Field Types
+- `field-relation` requires `relationDataSourceId` — the ID (UUID) of the related data source, or in batch operations, the slug of another data source in the same batch
+- `field-list` is a virtual field showing child records (one-to-many) — not stored in DB
+- `field-select` / `field-tagSelect` / `field-status` need enum options:
+  - In `create_fields`: call `create_enums` after field creation
+  - In `create_data_sources_batch`: include inline `enumOptions` array in the field definition
+- `field-formula` uses JSONata expressions — test with `evaluate_jsonata` first
+- `field-inlineData` stores array of objects, `field-inlineForm` stores single nested object
+- Field `slug` must be snake_case matching `^[a-z][a-z0-9_]*$`
+- Enum option `slug` must be snake_case matching `^[a-z][a-z0-9_]*$` (auto-generated from name if not provided)
+
+### Batch Operations
+- `create_data_sources_batch` creates up to 20 data sources in a single transaction
+- Within a batch, reference other data sources using their `slug` for `relationDataSourceId`
+- For external data sources (created outside the batch), use the UUID for `relationDataSourceId`
+- Data source slugs must be unique within the batch (validation error otherwise)
+- Inline enum options are defined per-field using the `enumOptions` array
+- Each enum option in `enumOptions` can specify: `name`, `slug`, `color`, `icon`, `sortOrder`
+- If a batch operation fails, all changes are rolled back (atomic transaction)
+- Use batch operations when creating related data sources to avoid multiple API calls and ensure consistency
+
+### Querying
+- Use `dataSourceId` (UUID) to identify which data source to query
+- `columns` is a comma-separated string of field slugs, not an array
+- For aggregations, always use `id` field for `count` calculations
+- Relation expansion: `relation_field(sub_field1, sub_field2)` selects nested columns
+- Spread operator: `...relation_field(alias:sub_field)` flattens into root object
+- Filter on related fields: `rel_{{relation_slug}}/{{field_slug}}`
+- Date filters have shortcut operators like `today`, `this_month`, `last_30_days`
+
+### query_data_source Required Parameters
+All parameters are required in the MCP tool schema (most accept `null`):
+- `dataSourceId`: string (required, non-null)
+- `columns`: string | null
+- `filters`: object | null
+- `filterKeyword`: string | null
+- `orderBy`: array | null
+- `limit`: number | null (default: 1000)
+- `offset`: number | null
+- `fullCount`: boolean | null
+- `recordId`: string | null (fetch single record by ID)
+- `calculations`: array | null
+- `distinctColumns`: array | null
+- `formulas`: array | null
+- `childQueries`: array | null
+- `pivot`: object | null
+
+### Custom Query Rules
+- Treat custom query `query` content as a Handlebars SQL template, not static SQL.
+- Use built-in context variables in templates when relevant: `TENANT_ID`, `TENANT_SCHEMA`, `USER_ID`, `USER_EMAIL`, `USER_FIRSTNAME`, `USER_LASTNAME`, `USER_FULLNAME`.
+- Use `{{filter FILTERS.<slug> <column_expression>}}` for optional runtime filtering. If no runtime value is provided, the helper resolves to `1=1`.
+- Keep `filters` definitions in `create_custom_query` / `update_custom_query` aligned with template usage:
+  - template usage: `FILTERS.<slug>`
+  - runtime rule field: `<slug>`
+  - filter definition slug: `<slug>`
+- Prefer `simulate: true` before running expensive queries to inspect `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` output.
+- Respect runtime limits on `run_custom_query`: 50,000 row cap, 15s timeout for normal execution, 30s timeout for simulate mode.
+- Use `delete_custom_query` as an archival action (soft delete), not permanent deletion.
+- For JSONB-backed simple data sources, access custom fields with `(table_alias."data"->>'field-uuid')::type`.
+
+## References
+
+- **[Data Source Query Guide](references/data-source-query-guide.md)** — Up-to-date reference for `query_data_source` including columns, filters, orderBy, pagination, calculations, formulas, pivots, child queries, and operator details.
+- **[Formula Design Guide (LLM)](references/formula-design-guide-llm.md)** — Up-to-date guide for designing formula payloads used in query requests.
+- **[Custom Query Guide](references/custom-query-guide.md)** — Full lifecycle and execution reference for `get_custom_queries`, `get_custom_query_by_id`, `create_custom_query`, `update_custom_query`, `delete_custom_query`, and `run_custom_query`.