@monkey-mini-app/dsh-mini-app 0.1.0 → 0.1.4

package/skills/monkey-mini-app/references/catalog.md

@@ -1,99 +1,236 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
-
-# @monkey-mini-app/ui catalog
-
-Import from `@monkey-mini-app/ui`. Host loads `@monkey-mini-app/ui/globals.css` + `UiProvider`.
-Open `contracts/<slug>.md` for **props + related types** + examples.
-
-## Layout & blocks
-
-| component | when | types | contract |
-|---|---|---|---|
-| `ActivityFeed` | — | `TimelineItem` | [docs](contracts/activity-feed.md) |
-| `AppShell` | Root layout for a mini-app page | — | [docs](contracts/app-shell.md) |
-| `AttachmentGallery` | — | `GalleryFile` | [docs](contracts/attachment-gallery.md) |
-| `CommentThread` | — | `Comment` | [docs](contracts/comment-thread.md) |
-| `DescriptionList` | — | — | [docs](contracts/description-list.md) |
-| `DetailPanel` | Master-detail after row/card click | — | [docs](contracts/detail-panel.md) |
-| `DonutChart` | — | `ChartConfig` `Slice` | [docs](contracts/donut-chart.md) |
-| `EnvBadge` | — | — | [docs](contracts/env-badge.md) |
-| `FileTree` | — | `TreeNode` | [docs](contracts/file-tree.md) |
-| `FilterBar` | Above DataGrid or any filtered list | — | [docs](contracts/filter-bar.md) |
-| `Gauge` | — | — | [docs](contracts/gauge.md) |
-| `NotificationCenter` | — | `NotificationItem` | [docs](contracts/notification-center.md) |
-| `PageHeader` | Top of a page inside AppShell main | — | [docs](contracts/page-header.md) |
-| `ProgressRing` | — | — | [docs](contracts/progress-ring.md) |
-| `RadarChart` | — | `ChartConfig` | [docs](contracts/radar-chart.md) |
-| `RequestInspector` | — | — | [docs](contracts/request-inspector.md) |
-| `RunTimeline` | — | `TimelineItem` | [docs](contracts/run-timeline.md) |
-| `Scrollspy` | — | — | [docs](contracts/scrollspy.md) |
-| `SeverityChip` | — | — | [docs](contracts/severity-chip.md) |
-| `Sparkline` | — | — | [docs](contracts/sparkline.md) |
-| `StackedBarChart` | — | `ChartConfig` | [docs](contracts/stacked-bar-chart.md) |
-| `StatCard` | Dashboard metric strip | — | [docs](contracts/stat-card.md) |
-| `StatusBadge` | pass \| fail \| blocked \| flaky \| running \| pending cells and chips | — | [docs](contracts/status-badge.md) |
-| `Terminal` | — | — | [docs](contracts/terminal.md) |
-| `TestStepList` | — | `TestStep` | [docs](contracts/test-step-list.md) |
-| `TrendCard` | — | `TrendPoint` | [docs](contracts/trend-card.md) |
-
-## Products
-
-| component | when | types | contract |
-|---|---|---|---|
-| `CodeBlock` | — | — | [docs](contracts/code-block.md) |
-| `CodeEditor` | — | — | [docs](contracts/code-editor.md) |
-| `DataGrid` | Any list/table of rows — prefer over raw Table* | `SearchVariant` `DataGridColumnMeta` `DataGridFeatures` | [docs](contracts/data-grid.md) |
-| `DiffViewer` | — | — | [docs](contracts/diff-viewer.md) |
-| `EventCalendar` | Scheduling, on-call, release windows | `CalendarView` `CalendarEvent` | [docs](contracts/event-calendar.md) |
-| `FileDropzone` | — | — | [docs](contracts/file-dropzone.md) |
-| `Gantt` | — | `GanttTask` | [docs](contracts/gantt.md) |
-| `JiraWiki` | Jira description / comment body | `JiraWikiClassNames` | [docs](contracts/jira-wiki.md) |
-| `JqlInput` | Issue search / saved filters | `JqlSuggestItem` | [docs](contracts/jql-input.md) |
-| `JsonViewer` | — | — | [docs](contracts/json-viewer.md) |
-| `Kanban` | Issue/workflow boards | `KanbanComment` `KanbanCard` `KanbanColumn` | [docs](contracts/kanban.md) |
-| `KanbanIssuePanel` | — | `KanbanCard` `KanbanComment` | [docs](contracts/kanban-issue-panel.md) |
-| `LogViewer` | — | — | [docs](contracts/log-viewer.md) |
-| `Markdown` | — | — | [docs](contracts/markdown.md) |
-| `MarkdownEditor` | — | `MarkdownEditorMode` | [docs](contracts/markdown-editor.md) |
-| `RichTextEditor` | — | — | [docs](contracts/rich-text-editor.md) |
-| `SortableList` | — | `SortableItem` | [docs](contracts/sortable-list.md) |
-| `Stepper` | — | `Step` | [docs](contracts/stepper.md) |
-| `Timeline` | — | `TimelineItem` | [docs](contracts/timeline.md) |
-| `TreeView` | — | `TreeNode` | [docs](contracts/tree-view.md) |
-
-## Composites (inputs)
-
-| component | when | types | contract |
-|---|---|---|---|
-| `Autocomplete` | — | — | [docs](contracts/autocomplete.md) |
-| `Cascader` | — | `CascaderNode` | [docs](contracts/cascader.md) |
-| `ColorPicker` | — | — | [docs](contracts/color-picker.md) |
-| `ConfirmDialog` | — | — | [docs](contracts/confirm-dialog.md) |
-| `Copyable` | — | — | [docs](contracts/copyable.md) |
-| `CurrencyInput` | — | — | [docs](contracts/currency-input.md) |
-| `DatePicker` | — | — | [docs](contracts/date-picker.md) |
-| `DateRangePicker` | Filters needing from/to calendar days | — | [docs](contracts/date-range-picker.md) |
-| `DateTimePicker` | — | — | [docs](contracts/date-time-picker.md) |
-| `DateTimeRangePicker` | — | `DateTimeRange` | [docs](contracts/date-time-range-picker.md) |
-| `DurationInput` | — | — | [docs](contracts/duration-input.md) |
-| `MiniCalendar` | — | — | [docs](contracts/mini-calendar.md) |
-| `NumberField` | — | — | [docs](contracts/number-field.md) |
-| `PasswordField` | — | — | [docs](contracts/password-field.md) |
-| `PhoneInput` | — | — | [docs](contracts/phone-input.md) |
-| `Rating` | — | — | [docs](contracts/rating.md) |
-| `RelativeDatePicker` | — | `RelativePreset` | [docs](contracts/relative-date-picker.md) |
-| `SearchInput` | — | — | [docs](contracts/search-input.md) |
-| `SliderRange` | — | — | [docs](contracts/slider-range.md) |
-| `TagInput` | — | — | [docs](contracts/tag-input.md) |
-| `TimePicker` | `value` is `HH:mm` (24h). | — | [docs](contracts/time-picker.md) |
-| `TimeRangePicker` | — | `TimeRange` | [docs](contracts/time-range-picker.md) |
-| `TimeWheel` | — | `TimePickerProps` | [docs](contracts/time-wheel.md) |
-| `TimezoneSelect` | — | `ZoneInfo` | [docs](contracts/timezone-select.md) |
-| `Transfer` | — | `TransferItem` | [docs](contracts/transfer.md) |
-| `UserPicker` | — | `UserOption` | [docs](contracts/user-picker.md) |
-
-## L1 primitives
-
-Button, Input, Textarea, Select, Combobox, Checkbox, Switch, RadioGroup, Slider, Label, Field, Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, DropdownMenu, ContextMenu, Tabs, Accordion, Card, Badge, Avatar, Breadcrumb, Pagination, Progress, Skeleton, Spinner, Empty, Alert, Separator, ScrollArea, Resizable, Sidebar, Command, Calendar, Table, Chart, Toast, …
-
-Use L1 to glue products. Prefer composites for dates/inputs.
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Mini-app UI catalog
+
+Import components, `useApp`, `Icon` and `Illu*` from `@monkey-mini-app/ui` — the only UI specifier allowed in `ui.tsx` (besides `react` and relative `./lib`).
+The host wraps the iframe with the theme provider + CSS; do not add a Provider yourself.
+Open `contracts/<slug>.md` for **props + parts** + examples.
+
+**Grouped by what you are building** (family, declared as `@family` JSDoc on the component).
+`type` is the engineering layer: `component` = L1 base others are built from (often compound —
+check the parts), `block` = opinionated preset, `composite` = form control, `product` = whole feature.
+Inherited HTML/ARIA props (`className`, `style`, `onClick`, `aria-*`) are never listed — every component takes them.
+
+## Layout & structure
+
+Shell / split / scroll containers and display atoms — they arrange, they don't interact.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `AppShell` | block | — | Root layout for a mini-app page | [docs](contracts/app-shell.md) |
+| `DashboardShell` | block | — | Page shape: metrics up top, charts below, optional activity rail — ops overviews, monitor walls | [docs](contracts/dashboard-shell.md) |
+| `DescriptionList` | block | — | Detail/inspector panel of a selected row — the default “show one record” view. | [docs](contracts/description-list.md) |
+| `FormSheet` | block | — | Page shape: focused create/edit over a list — new record, edit record, wizard-less config | [docs](contracts/form-sheet.md) |
+| `ListDetail` | block | — | Page shape: click a row, then read or edit that one record beside the list — orders, tickets, contacts, log lines | [docs](contracts/list-detail.md) |
+| `PageHeader` | block | — | Top of a page inside AppShell main | [docs](contracts/page-header.md) |
+| `SettingsSplit` | block | — | Page shape: a settings page, integration config, or a long report with anchored sections | [docs](contracts/settings-split.md) |
+| `TablePage` | block | — | Page shape: one wide filterable table is the product — inventories, ledgers, saved views | [docs](contracts/table-page.md) |
+| `WizardShell` | block | — | Page shape: create / import / onboarding, one step at a time with validation per step | [docs](contracts/wizard-shell.md) |
+| `AspectRatio` | component | `AspectRatio` | Keeping an image/video/embed from shifting the layout while loading. | [docs](contracts/aspect-ratio.md) |
+| `Avatar` | component | `Avatar` `AvatarBadge` +4 | User initials/photo next to a name in rows, comments, pickers. | [docs](contracts/avatar.md) |
+| `Collapsible` | component | `Collapsible` `CollapsibleContent` +1 | A single disclosure (advanced options). Several stacked → `Accordion`. | [docs](contracts/collapsible.md) |
+| `Item` | component | `Item` `ItemActions` +8 | A uniform list row when `DataGrid` is too heavy. | [docs](contracts/item.md) |
+| `Kbd` | component | `Kbd` `KbdGroup` | Documenting ⌘K-style shortcuts in help panels. | [docs](contracts/kbd.md) |
+| `Marker` | component | `Marker` `MarkerContent` +1 | Small state markers inside a sentence or legend. | [docs](contracts/marker.md) |
+| `Resizable` | component | `ResizableHandle` `ResizablePanel` +1 | Master-detail or editor + preview inside the app body. | [docs](contracts/resizable.md) |
+| `ScrollArea` | component | `ScrollArea` `ScrollBar` | A bounded panel (list in a card). Whole-page scroll → plain div. | [docs](contracts/scroll-area.md) |
+| `Separator` | component | `Separator` | Grouping inside panels. | [docs](contracts/separator.md) |
+
+## Navigation
+
+Menus, sidebars, palettes, tabs, pagination, scroll-spy.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `Scrollspy` | block | — | Long settings/report page with jump links. | [docs](contracts/scrollspy.md) |
+| `Breadcrumb` | component | `Breadcrumb` `BreadcrumbEllipsis` +5 | Deep mini-app views; usually one level is enough — prefer `Tabs`/`AppShell` nav. | [docs](contracts/breadcrumb.md) |
+| `Command` | component | `Command` `CommandDialog` +7 | Jump between views/actions inside one app. | [docs](contracts/command.md) |
+| `ContextMenu` | component | `ContextMenu` `ContextMenuCheckboxItem` +13 | Row/canvas operations. Trigger-button actions → `DropdownMenu`. | [docs](contracts/context-menu.md) |
+| `DropdownMenu` | component | `DropdownMenu` `DropdownMenuCheckboxItem` +13 | Row `MoreHorizontal` actions. Free-form panel content → `Popover`. | [docs](contracts/dropdown-menu.md) |
+| `Menubar` | component | `Menubar` `MenubarCheckboxItem` +14 | Rarely right for a panel-width mini-app — prefer `Tabs` / `DropdownMenu`. | [docs](contracts/menubar.md) |
+| `NavigationMenu` | component | `NavigationMenu` `NavigationMenuContent` +6 | Not for mini-apps with one screen — use `Tabs` or `AppShell` sidebar. | [docs](contracts/navigation-menu.md) |
+| `Pagination` | component | `Pagination` `PaginationContent` +5 | Only when you page by hand; `DataGrid` does this itself. | [docs](contracts/pagination.md) |
+| `Sidebar` | component | `Sidebar` `SidebarContent` +21 | Many sections in one app; `AppShell` already wires one for you. | [docs](contracts/sidebar.md) |
+| `Tabs` | component | `Tabs` `TabsContent` +2 | Board vs table, or settings sections. Navigation between routes/pages → keep it in your own state. | [docs](contracts/tabs.md) |
+
+## Surface
+
+Elevates content above the page: card, dialog, sheet, drawer, popover, tooltip, accordion.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `KanbanIssuePanel` | product | — | Board + click-to-edit issue. Pair with `Kanban`'s selected card. | [docs](contracts/kanban-issue-panel.md) |
+| `DetailPanel` | block | — | Master-detail after row/card click | [docs](contracts/detail-panel.md) |
+| `ConfirmDialog` | composite | — | Any destructive action. Needs a form inside → compose `Dialog` yourself. | [docs](contracts/confirm-dialog.md) |
+| `Accordion` | component | `Accordion` `AccordionContent` +2 | Collapsible groups in settings/details. | [docs](contracts/accordion.md) |
+| `AlertDialog` | component | `AlertDialog` `AlertDialogAction` +10 | Deleting/irreversible actions that must be answered. | [docs](contracts/alert-dialog.md) |
+| `Bubble` | component | `Bubble` `BubbleContent` +2 | Conversational UI (assistant turns). Records/logs → `ActivityFeed` / `Message`. | [docs](contracts/bubble.md) |
+| `Card` | component | `Card` `CardAction` +5 | The default container for a block of related UI. | [docs](contracts/card.md) |
+| `Dialog` | component | `Dialog` `DialogClose` +8 | Focused edit/confirm flow. Needs no focus takeover → `Sheet`. Destructive yes/no → `ConfirmDialog`. Size it with `width` on `DialogContent`: the base caps at `sm:max-w-sm`, so a `max-w-*` in `className` loses at ≥sm. | [docs](contracts/dialog.md) |
+| `Drawer` | component | `Drawer` `DrawerClose` +9 | Mobile-ish bottom sheet on narrow panels. Desktop detail → `Sheet`. | [docs](contracts/drawer.md) |
+| `HoverCard` | component | `HoverCard` `HoverCardContent` +1 | Peek a user/issue without navigating. Needs a decision → `Dialog`. | [docs](contracts/hover-card.md) |
+| `Message` | component | `Message` `MessageAvatar` +4 | Assistant/user turns. Timestamped log rows → `LogViewer`. | [docs](contracts/message.md) |
+| `Popover` | component | `Popover` `PopoverContent` +4 | Small editor/filter anchored to a control. Menus of commands → `DropdownMenu`. | [docs](contracts/popover.md) |
+| `Sheet` | component | `Sheet` `SheetClose` +6 | Detail/edit panel that keeps the list visible — the usual master-detail pattern. Size it with `width` on `SheetContent`: the panel carries its own `data-[side=right]:sm:max-w-sm` / `data-[side=left]:sm:max-w-sm`, so a `max-w-*` in `className` loses at ≥sm (inline style or `!max-w-*` also work). | [docs](contracts/sheet.md) |
+| `Tooltip` | component | `Tooltip` `TooltipContent` +2 | Explaining an icon-only button. Never put an action in it. | [docs](contracts/tooltip.md) |
+
+## Form
+
+Inputs, selects, toggles, buttons and actions — anything the user edits.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `FileDropzone` | product | — | Getting a local File into the app (then upload via `ctx.http` in the api layer). | [docs](contracts/file-dropzone.md) |
+| `JqlInput` | product | — | Issue search / saved filters. Needs a real field list: pass `fields`. | [docs](contracts/jql-input.md) |
+| `Autocomplete` | composite | — | Free text allowed but known values should be suggested. Strict pick-list → `Select`. | [docs](contracts/autocomplete.md) |
+| `Cascader` | composite | — | Hierarchical codes (region → site → line). Flat tree → `TreeView`. | [docs](contracts/cascader.md) |
+| `ColorPicker` | composite | — | Theme/label colour config. Never for secrets. | [docs](contracts/color-picker.md) |
+| `CurrencyInput` | composite | — | Money fields; keeps the raw string out of your state. | [docs](contracts/currency-input.md) |
+| `NumberField` | composite | — | Any number the user edits — keeps NaN out of your state. | [docs](contracts/number-field.md) |
+| `PasswordField` | composite | — | Typing a token/password into your own state. **Never** persist it to storage. | [docs](contracts/password-field.md) |
+| `PhoneInput` | composite | — | CN/mobile numbers. | [docs](contracts/phone-input.md) |
+| `Rating` | composite | — | Feedback/score capture, 1–max. | [docs](contracts/rating.md) |
+| `SearchInput` | composite | — | Filter-as-you-type against `DataGrid`/lists — use `onDebouncedChange` for network calls. | [docs](contracts/search-input.md) |
+| `SliderRange` | composite | — | min/max numeric filters. | [docs](contracts/slider-range.md) |
+| `TagInput` | composite | — | Labels/owners where free values are allowed (`Transfer` when choosing from a fixed pool). | [docs](contracts/tag-input.md) |
+| `Transfer` | composite | — | Selecting many items from a known pool (assign users to a shift). | [docs](contracts/transfer.md) |
+| `UserPicker` | composite | — | Assignee/owner fields; you supply the user list. | [docs](contracts/user-picker.md) |
+| `Button` | component | `Button` | Every click target. `variant="destructive"` for delete, `size="icon*"` for icon-only (add aria-label). | [docs](contracts/button.md) |
+| `ButtonGroup` | component | `ButtonGroup` `ButtonGroupSeparator` +1 | 2–5 mutually related actions (view switch, alignment). Tabs of content → `Tabs`. | [docs](contracts/button-group.md) |
+| `Checkbox` | component | `Checkbox` | Multi-select rows / opt-in. | [docs](contracts/checkbox.md) |
+| `Combobox` | component | `Combobox` `ComboboxChip` +13 | When you need full control of the popover list. Simple suggestion box → `Autocomplete`. | [docs](contracts/combobox.md) |
+| `Field` | component | `Field` `FieldContent` +8 | Any form row that must read well and stay accessible. | [docs](contracts/field.md) |
+| `Input` | component | `Input` | Plain text. Numbers → `NumberField`; secrets → `PasswordField`; search → `SearchInput`. | [docs](contracts/input.md) |
+| `InputGroup` | component | `InputGroup` `InputGroupAddon` +4 | Search/url/amount fields with adornments; keep validation in `NumberField` etc. | [docs](contracts/input-group.md) |
+| `Label` | component | `Label` | Always bind `htmlFor` — bare text labels are not accessible. | [docs](contracts/label.md) |
+| `NativeSelect` | component | `NativeSelect` `NativeSelectOptGroup` +1 | Short option lists where a plain select is enough and `Select` is overkill. | [docs](contracts/native-select.md) |
+| `Questionnaire` | component | `Questionnaire` `QuestionnaireActions` +13 | Structured ask-the-user blocks; you persist the answers. | [docs](contracts/questionnaire.md) |
+| `RadioGroup` | component | `RadioGroup` `RadioGroupItem` | 2–5 mutually exclusive options. Many options → `Select`. | [docs](contracts/radio-group.md) |
+| `Select` | component | `Select` `SelectContent` +8 | Closed set of options (searchable/large → `Autocomplete` or `DataGrid` filter). | [docs](contracts/select.md) |
+| `Slider` | component | `Slider` | One numeric value. Range → `SliderRange`. | [docs](contracts/slider.md) |
+| `Switch` | component | `Switch` | Immediate on/off settings (submit-on-toggle). | [docs](contracts/switch.md) |
+| `Textarea` | component | `Textarea` | Notes/prompts. Code → `CodeEditor`; markdown → `MarkdownEditor`. | [docs](contracts/textarea.md) |
+| `Toggle` | component | `Toggle` | Binary formatting switch (bold, filters on). | [docs](contracts/toggle.md) |
+| `ToggleGroup` | component | `ToggleGroup` `ToggleGroupItem` | Multiple independent on/off buttons; exclusive selection → `Tabs`/`ButtonGroup`. | [docs](contracts/toggle-group.md) |
+
+## Data & tables
+
+Rows, grids, boards, trees, sortable lists and their filters.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `DataGrid` | product | — | Any list/table of rows — prefer over raw Table* | [docs](contracts/data-grid.md) |
+| `Kanban` | product | — | Issue/workflow boards | [docs](contracts/kanban.md) |
+| `SortableList` | product | — | Priority queues / column order. Read-only ordered events → `Timeline`. | [docs](contracts/sortable-list.md) |
+| `TreeView` | product | — | Any hierarchy without file semantics. Files → `FileTree`. | [docs](contracts/tree-view.md) |
+| `EnvTable` | block | — | Settings / deploy preview / secrets display | [docs](contracts/env-table.md) |
+| `FileTree` | block | — | Repo/zip contents where selection matters. Plain nested list → `TreeView`. | [docs](contracts/file-tree.md) |
+| `FilterBar` | block | — | Above DataGrid or any filtered list | [docs](contracts/filter-bar.md) |
+| `TestStepList` | block | — | QA cases, checklists that get executed and graded. | [docs](contracts/test-step-list.md) |
+| `Table` | component | `Table` `TableBody` +6 | Only when you need full control of cells. Otherwise use `DataGrid` (sorting/filter/paging/CSV built in). | [docs](contracts/table.md) |
+
+## Chart & data
+
+Stat / KPI cards, charts, gauges, sparklines, git graph.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `CommitGraph` | product | — | App history, release notes, git timeline views | [docs](contracts/commit-graph.md) |
+| `DonutChart` | block | — | Part-of-whole (≤6 slices): storage usage, status split. More categories → `StackedBarChart`. | [docs](contracts/donut-chart.md) |
+| `Gauge` | block | — | A single health/capacity number that needs a zone (SLO, disk). Series over time → `Sparkline`. | [docs](contracts/gauge.md) |
+| `RadarChart` | block | — | Comparing an item across 4–8 dimensions (scores, coverage). | [docs](contracts/radar-chart.md) |
+| `Sparkline` | block | — | Trend inside a table row or KPI card. | [docs](contracts/sparkline.md) |
+| `StackedBarChart` | block | — | Comparing several series across categories (pass/fail per day). Single ratio → `DonutChart`; trend → `Sparkline`. | [docs](contracts/stacked-bar-chart.md) |
+| `StatCard` | block | — | Dashboard metric strip | [docs](contracts/stat-card.md) |
+| `TrendCard` | block | — | Metric + direction over time. Metric only → `StatCard`. | [docs](contracts/trend-card.md) |
+| `Chart` | component | `ChartContainer` `ChartLegend` +4 | Only when no `*Chart` block fits — then you own the series. Prefer `DonutChart` / `StackedBarChart` / `Sparkline` / `Gauge` / `RadarChart`. | [docs](contracts/chart.md) |
+
+## Feedback & status
+
+Status/severity badges, progress, skeleton, spinner, alerts, empty states, toasts.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `Stepper` | product | — | Wizard/progress of an ordered process. Time axis → `RunTimeline`. | [docs](contracts/stepper.md) |
+| `StepperItem` | product | — | As a child of `Stepper` only — status is `default \| active \| completed` (lowercase). | [docs](contracts/stepper-item.md) |
+| `EnvBadge` | block | — | prd / stg / dev markers in headers and tables. | [docs](contracts/env-badge.md) |
+| `NotificationCenter` | block | — | Inbox/alert panel. Audit log (read-only, with time) → `ActivityFeed`. | [docs](contracts/notification-center.md) |
+| `ProgressRing` | block | — | One percent-done value in a tight space (card corner, table cell). | [docs](contracts/progress-ring.md) |
+| `SeverityChip` | block | — | P0–P4, blocker/critical columns. Run outcome → `StatusBadge`. | [docs](contracts/severity-chip.md) |
+| `StatusBadge` | block | — | pass \| fail \| blocked \| flaky \| running \| pending cells and chips | [docs](contracts/status-badge.md) |
+| `Alert` | component | `Alert` `AlertAction` +2 | Explaining a failed state in place. Transient → `toast()`. | [docs](contracts/alert.md) |
+| `Badge` | component | `Badge` | Static tags/counts. Status → `StatusBadge`, severity → `SeverityChip`. | [docs](contracts/badge.md) |
+| `Empty` | component | `Empty` `EmptyContent` +4 | Any list/panel with no rows — pair media with an `Illu*`. | [docs](contracts/empty.md) |
+| `Progress` | component | `Progress` `ProgressIndicator` +3 | Full-width scan/import progress. Compact circle → `ProgressRing`. | [docs](contracts/progress.md) |
+| `Skeleton` | component | `Skeleton` | First paint while `call()` is pending — match the real layout's size. | [docs](contracts/skeleton.md) |
+| `Spinner` | component | `Spinner` | Inside a button while `call()` is pending. Known % → `Progress`. | [docs](contracts/spinner.md) |
+| `Toast` | component | `Toast` `ToastAction` +8 | Confirm/save failures. The host already mounts the provider — call `toast(...)`. | [docs](contracts/toast.md) |
+
+## Calendar & date
+
+Calendars, date/time pickers and ranges, durations, timezones, scheduling views.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `EventCalendar` | product | — | Scheduling, on-call, release windows | [docs](contracts/event-calendar.md) |
+| `Gantt` | product | — | Plans/schedules with start+end per row. Ordered events → `Timeline`. | [docs](contracts/gantt.md) |
+| `DatePicker` | composite | — | Filtering or storing one day. With a clock → `DateTimePicker`. | [docs](contracts/date-picker.md) |
+| `DateRangePicker` | composite | — | Filters needing from/to calendar days | [docs](contracts/date-range-picker.md) |
+| `DateTimePicker` | composite | — | Scheduling moments, not days. | [docs](contracts/date-time-picker.md) |
+| `DateTimeRangePicker` | composite | — | Run windows, on-call shifts. | [docs](contracts/date-time-range-picker.md) |
+| `DurationInput` | composite | — | Timeouts/estimates where you store minutes but type human units. | [docs](contracts/duration-input.md) |
+| `MiniCalendar` | composite | — | Inside a popover or sidebar. Full page with events → `EventCalendar`. | [docs](contracts/mini-calendar.md) |
+| `RelativeDatePicker` | composite | — | Dashboard filters where “last 7 days” beats two calendars. | [docs](contracts/relative-date-picker.md) |
+| `TimePicker` | composite | — | Clock-only fields. `value` is a string, not a Date. | [docs](contracts/time-picker.md) |
+| `TimeRangePicker` | composite | — | Daily windows (maintenance 02:00–04:00). | [docs](contracts/time-range-picker.md) |
+| `TimeWheel` | composite | — | Inside a time picker where tapping a list beats typing. Prefer `TimePicker` for a normal field. | [docs](contracts/time-wheel.md) |
+| `TimezoneSelect` | composite | — | Pair with `DateTimePicker` when data is UTC. | [docs](contracts/timezone-select.md) |
+| `Calendar` | component | `Calendar` `CalendarDayButton` | An inline calendar inside your own layout. As a field with input → `DatePicker`. | [docs](contracts/calendar.md) |
+
+## Realtime
+
+Live feeds, timelines, logs and consoles.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `LogViewer` | product | — | Streaming / CLI-style log output | [docs](contracts/log-viewer.md) |
+| `Timeline` | product | — | Statuses/history without durations. Durations → `RunTimeline`. | [docs](contracts/timeline.md) |
+| `ActivityFeed` | block | — | Read-only “who did what when” — commits, deploys, agent runs. For steps with status use `RunTimeline`. | [docs](contracts/activity-feed.md) |
+| `CommentThread` | block | — | Issue/ticket discussion, review comments. Editing a comment is your job, not the component's. | [docs](contracts/comment-thread.md) |
+| `RunTimeline` | block | — | CI/agent/job phases on a time axis. Plain ordered events → `Timeline`. | [docs](contracts/run-timeline.md) |
+| `Terminal` | block | — | Showing a command + its output verbatim. Timestamped levels/scrolling → `LogViewer`. | [docs](contracts/terminal.md) |
+| `MessageScroller` | component | `MessageScroller` `MessageScrollerButton` +4 | Streaming chat output. Logs by timestamp → `LogViewer`. | [docs](contracts/message-scroller.md) |
+
+## Rich text
+
+Markdown / rich-text render and edit, wiki markup.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `JiraWiki` | product | — | Jira description / comment body | [docs](contracts/jira-wiki.md) |
+| `Markdown` | product | — | Model output, README-ish bodies. Children must be a string. | [docs](contracts/markdown.md) |
+| `MarkdownEditor` | product | — | Authoring md bodies. Read-only render → `Markdown`. | [docs](contracts/markdown-editor.md) |
+| `RichTextEditor` | product | — | Notes/descriptions you store as **HTML**. Markdown → `MarkdownEditor`; code → `CodeEditor`. Sanitize server-side before rendering elsewhere. | [docs](contracts/rich-text-editor.md) |
+
+## Discovery & inspect
+
+Inspect, compare and browse artefacts: diff, JSON, code, requests, attachments.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `CodeBlock` | product | — | Showing a snippet/command. Editable → `CodeEditor`. | [docs](contracts/code-block.md) |
+| `CodeEditor` | product | — | Editing config/scripts in-app. Do not `import @codemirror/*` or add it to package.json. | [docs](contracts/code-editor.md) |
+| `DiffViewer` | product | — | Comparing two versions of text. Pass `original` + `modified` strings. | [docs](contracts/diff-viewer.md) |
+| `JsonViewer` | product | — | API responses/config. Plain text with wrapping → `CodeBlock`. | [docs](contracts/json-viewer.md) |
+| `AttachmentGallery` | block | — | A record has N files/images and you show them as tiles, not a table. | [docs](contracts/attachment-gallery.md) |
+| `RequestInspector` | block | — | Debugging one API call: method, url, bodies. Multiple calls streaming → `LogViewer`. | [docs](contracts/request-inspector.md) |
+| `Copyable` | composite | — | IDs, hashes, URLs, tokens the user pastes elsewhere. | [docs](contracts/copyable.md) |
+| `Attachment` | component | `Attachment` `AttachmentAction` +7 | One selected file inside a form. A grid of many → `AttachmentGallery`. | [docs](contracts/attachment.md) |
+
+## Animation
+
+Entrance / exit / layout motion: reveal, stagger, animated presence.
+
+| component | type | parts | when | contract |
+|---|---|---|---|---|
+| `Reveal` | block | — | A card, row, or section appearing on first paint or after a filter change. Not for a hover/press response (one property: use a Tailwind `transition`) and not for animating an element out (use `AnimatePresence`). | [docs](contracts/reveal.md) |

package/skills/monkey-mini-app/references/contracts/accordion.md

@@ -0,0 +1,30 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Accordion (L1 primitive)
+
+Vertically expanding sections.
+
+**when** Collapsible groups in settings/details.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/accordion.tsx` · family: Surface · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Accordion` | `disabled?` `hiddenUntilFound?` `keepMounted?` `loopFocus?` `multiple?` `onValueChange?` `orientation?` `render?` `value?` |
+| `AccordionContent` | `hiddenUntilFound?` `keepMounted?` `render?` |
+| `AccordionItem` | `disabled?` `onOpenChange?` `render?` `value?` |
+| `AccordionTrigger` | `nativeButton?` `render?` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+<Accordion type="single"><AccordionItem value="s1"><AccordionTrigger>高级</AccordionTrigger><AccordionContent>…</AccordionContent></AccordionItem></Accordion>
+```

package/skills/monkey-mini-app/references/contracts/activity-feed.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # ActivityFeed
 
+Chronological activity list (avatar + text + time).
+
+**when** Read-only “who did what when” — commits, deploys, agent runs. For steps with status use `RunTimeline`.
+
 `import { ActivityFeed, TimelineItem } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/blocks/activity-feed.tsx` · blocks
+`packages/ui/src/blocks/activity-feed.tsx` · family: Realtime · type: block
 
 ## Props
 
@@ -22,3 +26,9 @@
 | `id` | `string` | ✓ |  |
 | `time` | `string \| undefined` |  |  |
 | `title` | `string` | ✓ |  |
+
+## Example
+
+```tsx
+<ActivityFeed items={[{ id: "1", title: "部署完成", time: "10:24" }]} />
+```

package/skills/monkey-mini-app/references/contracts/alert-dialog.md

@@ -0,0 +1,38 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# AlertDialog (L1 primitive)
+
+Blocking confirm modal (no click-outside dismiss).
+
+**when** Deleting/irreversible actions that must be answered.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/alert-dialog.tsx` · family: Surface · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `AlertDialog` | `actionsRef?` `defaultOpen?` `defaultTriggerId?` `handle?` `onOpenChange?` `onOpenChangeComplete?` `open?` `triggerId?` |
+| `AlertDialogAction` | `focusableWhenDisabled?` `nativeButton?` `render?` `size?=default/xs/sm/lg/icon/icon-xs/icon-sm/icon-lg` `variant?=link/default/outline/secondary/ghost/destructive` |
+| `AlertDialogCancel` | `nativeButton?` `render?` `size?=default/xs/sm/lg/icon/icon-xs/icon-sm/icon-lg` `variant?=link/default/outline/secondary/ghost/destructive` |
+| `AlertDialogContent` | `finalFocus?` `initialFocus?` `render?` `size?=default/sm` |
+| `AlertDialogDescription` | `render?` |
+| `AlertDialogFooter` | — |
+| `AlertDialogHeader` | — |
+| `AlertDialogMedia` | — |
+| `AlertDialogOverlay` | `forceRender?` `render?` |
+| `AlertDialogPortal` | `container?` `keepMounted?` `render?` |
+| `AlertDialogTitle` | `render?` |
+| `AlertDialogTrigger` | `handle?` `nativeButton?` `payload?` `render?` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+<AlertDialog open={ask} onOpenChange={setAsk}><AlertDialogContent><AlertDialogTitle>确定删除？</AlertDialogTitle><AlertDialogAction onClick={del}>删除</AlertDialogAction></AlertDialogContent></AlertDialog>
+```

package/skills/monkey-mini-app/references/contracts/alert.md

@@ -0,0 +1,38 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Alert (L1 primitive)
+
+Inline message block (info/warning/error).
+
+**when** Explaining a failed state in place. Transient → `toast()`.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { Alert, AlertAction, AlertDescription, AlertTitle } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/alert.tsx` · family: Feedback & status · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Alert` | `variant?=default/destructive` |
+| `AlertAction` | — |
+| `AlertDescription` | — |
+| `AlertTitle` | — |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Skeleton
+
+```tsx
+<Alert variant="destructive"><AlertTitle>拉取失败</AlertTitle><AlertDescription>上游 502，已用缓存</AlertDescription></Alert>
+```
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[alert-01.tsx](../examples/alert/alert-01.tsx)** — Alert — Inline, non-blocking notice inside a page or panel — title + description, colours follow the semantic theme. Use for 'saved', '2 checks failed'; reach for Toast for transient confirmations and Dialog when the user must acknowledge.

package/skills/monkey-mini-app/references/contracts/app-shell.md

@@ -1,4 +1,4 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # AppShell
 
@@ -8,7 +8,7 @@ App frame: optional sidebar + header + main.
 
 `import { AppShell } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/blocks/app-shell.tsx` · blocks
+`packages/ui/src/blocks/app-shell.tsx` · family: Layout & structure · type: block
 
 ## Props
 

package/skills/monkey-mini-app/references/contracts/aspect-ratio.md

@@ -0,0 +1,25 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# AspectRatio (L1 primitive)
+
+**when** Keeping an image/video/embed from shifting the layout while loading.
+
+`import { AspectRatio } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/aspect-ratio.tsx` · family: Layout & structure · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `AspectRatio` | `ratio` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[aspect-ratio-01.tsx](../examples/aspect-ratio/aspect-ratio-01.tsx)** — AspectRatio — A media/skeleton placeholder that must keep a fixed ratio (16/9 here) while its container resizes — prevents layout shift when images or embeds load late.

package/skills/monkey-mini-app/references/contracts/attachment-gallery.md

@@ -1,10 +1,14 @@
-<!-- generated by scripts/generate-skill.mjs — do not edit -->
+<!-- generated by scripts/gen/skill — do not edit -->
 
 # AttachmentGallery
 
+Thumbnail grid of files with open/copy.
+
+**when** A record has N files/images and you show them as tiles, not a table.
+
 `import { AttachmentGallery, GalleryFile } from "@monkey-mini-app/ui"`
 
-`packages/ui/src/blocks/attachment-gallery.tsx` · blocks
+`packages/ui/src/blocks/attachment-gallery.tsx` · family: Discovery & inspect · type: block
 
 ## Props
 
@@ -20,3 +24,9 @@
 |---|---|:---:|---|
 | `name` | `string` | ✓ |  |
 | `url` | `string \| undefined` |  |  |
+
+## Example
+
+```tsx
+<AttachmentGallery files={[{ name: "log.txt", url: "https://…" }]} />
+```

package/skills/monkey-mini-app/references/contracts/attachment.md

@@ -0,0 +1,35 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Attachment (L1 primitive)
+
+**when** One selected file inside a form. A grid of many → `AttachmentGallery`.
+
+Compound: compose the parts below — **do not invent part names**.
+
+`import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, AttachmentTrigger } from "@monkey-mini-app/ui"`
+
+`packages/ui/src/components/attachment.tsx` · family: Discovery & inspect · type: component · primitive
+
+## Parts
+
+| part | own props |
+|---|---|
+| `Attachment` | `orientation?=vertical/horizontal` `size?=default/xs/sm` `state?=error/idle/uploading/processing/done` |
+| `AttachmentAction` | `focusableWhenDisabled?` `nativeButton?` `render?` `size?=default/xs/sm/lg/icon/icon-xs/icon-sm/icon-lg` `variant?=link/default/outline/secondary/ghost/destructive` |
+| `AttachmentActions` | — |
+| `AttachmentContent` | — |
+| `AttachmentDescription` | — |
+| `AttachmentGroup` | — |
+| `AttachmentMedia` | `variant?=image/icon` |
+| `AttachmentTitle` | — |
+| `AttachmentTrigger` | `render?` |
+
+_Inherited HTML/ARIA props (`className`, `style`, `id`, `onClick`, `aria-*`, …) omitted — every component takes them._
+
+## Examples
+
+Runnable files under `references/examples/` — portable by construction (`react` +
+`@monkey-mini-app/ui` + relatives), so copy the closest one into `ui.tsx` / `ui/`.
+Pick by **scenario**, then open the file you need.
+
+- **[attachment-01.tsx](../examples/attachment/attachment-01.tsx)** — Attachment — A file chip in a list — icon, name, meta line and a remove affordance; the shape used for uploaded files or chat attachments.