@maz-ui/mcp 5.2.0-beta.0 → 5.3.0

package/docs/agents/claude-rule.md

@@ -1,66 +1,33 @@
 # maz-ui
 
-This project is built with **maz-ui** and its ecosystem. Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.
+This project is built with **maz-ui** and its ecosystem. Reuse what it provides instead of re-implementing it: UI elements, helpers, icons and styles you need usually already exist.
 
 ### Look it up before you write it
 
-- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete"), `get_component_api`, `find_icons`, `get_theme_tokens`, `get_doc`, `review_code`.
-- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
+- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete"), `get_component_api`, `find_icons`, `get_theme_tokens`, `get_doc` (icons, helpers, themes, translations, plugins, forms), `review_code`.
+- Otherwise the version-matched docs in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
 
 Never guess an API: only use documented props, events, slots and imports.
 
-### Which package for what
+### Rules
 
-`maz-ui` (components, composables, directives, plugins), `@maz-ui/themes` (brand colors, fonts, dark mode), `@maz-ui/icons` (icons, logos, flags), `@maz-ui/utils` (helpers), `@maz-ui/translations` (texts of the components), `@maz-ui/nuxt` (Nuxt module).
-
-### Components
-
-- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not `<button>`), `MazLink`, `MazInput`, `MazSelect`, `MazCheckbox`, `MazDialog`, `MazDrawer`, `MazPopover`, `MazDropdown`, `MazTabs`, `MazTable`, `MazCard`, `MazAvatar`, `MazBadge`, `MazAlert`, `MazDatePicker`, `MazInputPhoneNumber`, `MazDropzone`, `MazPagination`...
-- Prop values are typed: colors are `primary | secondary | accent | info | success | warning | destructive | contrast | transparent` (plus `surface` on some components), sizes `mini | xs | sm | md | lg | xl`.
-- A button with only an icon needs an `aria-label`.
-
-### Feedback, overlays and forms
-
-- `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
-- These composables need their plugin. Vue: `app.use(ToastPlugin)` from `maz-ui/plugins/toast` (`DialogPlugin`, `WaitPlugin`, `AosPlugin` likewise). Nuxt: `mazUi: { plugins: { toast: true } }`, off by default like the directives (`mazUi.directives.vTooltip`, or import the directive).
-- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
-
-### Icons
-
-Use `@maz-ui/icons`, never inline SVG nor another icon library. Pick the format by usage:
-
-- **Icon props** (`<MazBtn :start-icon>`, `<MazIcon :icon>`...): the raw SVG string, the lightest, `@maz-ui/icons/raw/MazTrash`.
-- **Directly in a template**: the component, `@maz-ui/icons/static/MazTrash`, then `<MazTrash class="size-5 text-muted" />` (size and color from the text: `1em`, `currentColor`).
-- **Not visible at first render** (`v-if`, menus, dialogs, tabs): the lazy component, `@maz-ui/icons/lazy/MazTrash`. Never for icons visible on load: each one is an extra request.
-- `<img>` or CSS only for multicolor icons (flags, logos): `@maz-ui/icons/svg/<name>.svg`, the text color does not apply there.
-
-### Helpers
-
-Use `@maz-ui/utils/helpers/<name>` and the maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `capitalize`, `normalizeString`, `getCookie` / `setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...
-
-### Texts and languages
-
-The texts built in the components come from `@maz-ui/translations`: change the language with `useTranslations().setLocale('fr')` and customize the texts in its options, not in every component.
+- `Maz*` components instead of native elements or hand-made widgets (`MazBtn` not `<button>`, `MazInput`, `MazSelect`, `MazDialog`, `MazCard`...). A button with only an icon needs an `aria-label`.
+- Icons from `@maz-ui/icons` (`find_icons`), never inline SVG nor another icon library.
+- `@maz-ui/utils` and the maz-ui composables instead of lodash, VueUse or hand-written helpers. `useToast()` for notifications, `useDialog()` for confirmations (they need their plugin).
+- Theme (brand colors, dark mode) through a `@maz-ui/themes` preset and `useTheme()`, never by hand.
 
 ### Styling with Tailwind
 
-The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:
+Only use theme tokens (`bg-surface text-foreground border-divider`, `bg-primary text-primary-foreground`, `text-muted`...). `get_theme_tokens` lists the maz-ui tokens and the ones of the project; when a value is missing, add a token to the project `@theme`.
 
-- **Project tokens first**: the Tailwind entry of the project adds its own `@theme` tokens, variants and utilities, and the `definePreset` file sets the brand values. `get_theme_tokens` lists both (or read these files). When a value is missing, add a token to the project `@theme` instead of an arbitrary value.
-- Colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`, `contrast` (each with `-foreground` and `-50` to `-950`), `surface`, `foreground`, `muted`, `divider`, `overlay`, `bg-container`, `bg-input`. Example: `bg-surface text-foreground border-divider`.
 - Never the default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`, `text-black`) nor hard-coded colors (`#fff`, `rgb()`, `bg-[#...]`). Theme colors already adapt to dark mode: no `dark:` color overrides.
-- Radius `rounded-*`, shadows `shadow-sm` to `shadow-xl` and `shadow-elevation`, spacing scale (`p-4`, `gap-2`), breakpoints `mob-*`, `tab-*`, `lap-*` (plus `sm` to `2xl`), utilities `flex-center`, `padded-container`.
-- **No `maz:` prefix** in this project: it is internal to the maz-ui library.
-- In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
-
-### Theme
-
-Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`definePreset`), not from overrides scattered in CSS. Use `useTheme()` for dark mode and presets (`toggleDarkMode`, `setColorMode`, `updateTheme`), never toggle the `dark` class or store the mode yourself.
+- **No `maz:` prefix**: it is internal to the maz-ui library.
+- In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`.
 
 ### Imports
 
-- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `maz-ui/directives/vTooltip`, `maz-ui/plugins/toast`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/raw/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
-- With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them. Icons are not: import them. The theme and the translations are set in the `mazUi` options of `nuxt.config`, not with the `MazUi` Vue plugin.
+- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/raw/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
+- With `@maz-ui/nuxt`, components and composables are auto-imported (icons are not).
 
 ### Before you finish
 

package/docs/components/maz-alert.md

@@ -227,7 +227,7 @@ You can use either title, content, or both.
 
 - `title` (`string`): Title of the alert.
 - `content` (`string`): Content of the alert.
-- `icon` (`string | IconComponent`): Icon of the alert - can be a component or icon name string.
+- `icon` (`any`): Icon of the alert - can be a component or icon name string.
 - `hide-icon` (`boolean`, default: `false`): Hide the icon.
 - `color` (`MazAlertColor`, default: `"info"`): Color of the alert. Values: `'success'`, `'warning'`, `'destructive'`, `'info'`, `'primary'`, `'secondary'`, `'accent'`, `'contrast'` (non exhaustive).
 - `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.

package/docs/components/maz-bottom-sheet.md

@@ -217,7 +217,7 @@ The bottom sheet is a modal `dialog` labelled by its `title` and described by it
 
 - `model-value` (`boolean`, `v-model`): Modal's model value.
 - `title` (`string`): Title of the bottom sheet in the header.
-- `icon` (`MazIconLike`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
+- `icon` (`any`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
 - `max-width` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``, default: `"40rem"`): Bottom sheet's max-width, applied from the tablet breakpoint and up (full-width below).
 - `hide-close-button` (`boolean`, default: `false`): Remove the close button in the header.
 - `hide-header` (`boolean`, default: `false`): Remove the whole header.

package/docs/components/maz-btn.md

@@ -406,9 +406,9 @@ When `to` attribute is provided, the component automatically becomes a `<RouterL
 - `loading` (`boolean`, default: `false`): Enable the button loader.
 - `disabled` (`boolean`, default: `false`): Disable the button.
 - `fab` (`boolean`, default: `false`): If true, the button will have a fab style.
-- `icon` (`MazIconLike`): The icon to display in the fab variant. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) for the common case, or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, flipIconForRtl, …).
-- `start-icon` (`MazIconLike`): The icon to display on the inline-start edge (left in LTR, right in RTL). Accepts a bare value or a full `MazIconProps` object.
-- `end-icon` (`MazIconLike`): The icon to display on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `icon` (`any`): The icon to display in the fab variant. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) for the common case, or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, flipIconForRtl, …).
+- `start-icon` (`any`): The icon to display on the inline-start edge (left in LTR, right in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `end-icon` (`any`): The icon to display on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `padding` (`boolean`, default: `true`): Apply the padding of the button, set it to `false` to remove it.
 - `justify` (`"center" | "end" | "start" | "space-between" | "space-around" | "space-evenly"`, default: `"center"`): Choose how the elements are aligned in the button.
 - `active` (`boolean`, default: `false`): If true, the button will have an active state.

package/docs/components/maz-card.md

@@ -288,7 +288,7 @@ type MazGalleryImage =
 
 ### Props
 
-- `orientation` (`"row" | "column" | "column-reverse" | "row-reverse"`, default: `"column"`): Card variant: Must be `column | row | row-reverse | column-reverse`.
+- `orientation` (`"row" | "column" | "row-reverse" | "column-reverse"`, default: `"column"`): Card variant: Must be `column | row | row-reverse | column-reverse`.
 - `href` (`string`): Make card a link (footer area excluded).
 - `to` (`string | et | X`): Make card a link with a router-link or nuxt-link (footer area excluded).
 - `href-target` (`string`, default: `"_self"`): Target option of link: Muse be one of `_blank | _self | _parent | _top | framename`.

package/docs/components/maz-container.md

@@ -226,8 +226,8 @@ Use the `header` slot to fully customize the header, or use `title`, `icon-start
 - `rounded-size` (`MazRoundedSize`, default: `'md'`): Size of the rounded. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
 - `transparent` (`boolean`, default: `false`): Remove background color.
 - `overflow-hidden` (`boolean`, default: `true`): Hide overflow.
-- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the header (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
-- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the header (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`any`): Icon displayed on the inline-start edge of the header (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `end-icon` (`any`): Icon displayed on the inline-end edge of the header (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.
 - `block` (`boolean`, default: `false`): Display the container in full width.
 - `content-class` (`string`): Additional class to add to the content wrapper.

package/docs/components/maz-dropdown.md

@@ -376,7 +376,7 @@ The trigger button exposes the menu state (`aria-haspopup="menu"`, `aria-expande
 - `menu-panel-class` (`ClassValue`): Additional CSS classes to apply to the dropdown menu panel Useful for customizing the dropdown appearance (background, border, etc.).
 - `menu-panel-style` (`StyleValue`): Inline styles to apply to the dropdown menu panel Useful for custom styling. You may use `!important` to override default styles.
 - `block` (`boolean`, default: `false`): Makes the dropdown button expand to full width of its container.
-- `dropdown-icon` (`MazIconLike`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `dropdown-icon` (`any`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
 - `dropdown-icon-animation` (`boolean`, default: `true`): Controls whether the dropdown icon rotates when the dropdown is opened.
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the dropdown button.
 - `transition` (`string`, default: `"scale-pop"`): Transition to use when the dropdown is opened or closed. Values: `'scale-pop'`, `'scale-fade'`, `'string'` (non exhaustive).

package/docs/components/maz-dropzone.md

@@ -355,8 +355,8 @@ Customize the upload request using `uploadUrl`, `requestOptions` and `transformB
 
 ### Events
 
-- `@add` (payload: `value: File`): Event emitted when a file is added to the dropzone
 - `@error` (payload: `values: { files: File[] | null; event: DragEvent | null; code: MazDropzoneErrorCode; }`): Event emitted when an error occurs
+- `@add` (payload: `value: File`): Event emitted when a file is added to the dropzone
 - `@drop` (payload: `values: { files: File[] | null; event: DragEvent; }`): Event emitted when files are dropped in the dropzone
 - `@update:modelValue` (payload: `value: MazDropzoneFileData[]`)
 - `@enter` (payload: `values: { files: File[] | null; event: DragEvent; }`): Event emitted when dragged files enter the dropzone

package/docs/components/maz-icon.md

@@ -191,8 +191,8 @@ Source: [Heroicons](https://heroicons.com/) - see also the [icon set page](../ec
 
 ### Props
 
-- `icon` (`MazIconValue`): The icon to render. Accepts: - A Vue component (e.g. `import { MazStar } from '@maz-ui/icons/static/MazStar'`) - A URL or `data:` URI to a `.svg` file (`'/icons/star.svg'`, `'data:image/svg+xml,…'`) - A raw SVG string (`'<svg viewBox="0 0 24 24">…</svg>'`) The component detects the format and renders accordingly.
-- `fallback` (`MazIconValue`, default: `MazQuestionMarkCircle`): Fallback icon used when: - `icon` is not provided - `icon` is a URL that fails to load or returns invalid SVG Same shape as `icon`. Defaults to the imported `MazQuestionMarkCircle` if neither `icon` nor `fallback` resolves to anything renderable.
+- `icon` (`any`): The icon to render. Accepts: - A Vue component (e.g. `import { MazStar } from '@maz-ui/icons/static/MazStar'`) - A URL or `data:` URI to a `.svg` file (`'/icons/star.svg'`, `'data:image/svg+xml,…'`) - A raw SVG string (`'<svg viewBox="0 0 24 24">…</svg>'`) The component detects the format and renders accordingly.
+- `fallback` (`any`, default: `MazQuestionMarkCircle`): Fallback icon used when: - `icon` is not provided - `icon` is a URL that fails to load or returns invalid SVG Same shape as `icon`. Defaults to the imported `MazQuestionMarkCircle` if neither `icon` nor `fallback` resolves to anything renderable.
 - `size` (`MazIconSize`): Predefined keyword (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) or any CSS length.
 - `title` (`string`): Sets a `<title>` element inside the SVG for screen-reader accessibility.
 - `svg-attributes` (`Record<string, string | number>`): Extra attributes to merge onto the rendered `<svg>` root.

package/docs/components/maz-input.md

@@ -310,8 +310,8 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
 - `debounce` (`number | boolean`, default: `false`): Enables input debouncing to limit the frequency of value updates. When true, uses 500ms delay. When a number, uses that value as delay in milliseconds.
 - `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.
 - `border-active` (`boolean`, default: `false`): When true, shows the colored border immediately instead of only on focus.
-- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
-- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`any`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
+- `end-icon` (`any`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `rounded-size` (`MazRoundedSize`, default: `'md'`): Controls the border radius of the input component. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
 - `block` (`boolean`): Makes the input expand to the full width of its container.
 - `name` (`string`): The name of the input field. Used for form submission and validation.

package/docs/components/maz-link.md

@@ -134,8 +134,8 @@ If no `to` or `href` is provided, the component will be a `button` by default. Y
 - `underline` (`boolean`, default: `false`): Add an underline to the link.
 - `underline-hover` (`boolean`, default: `true`): Add an underline only on hover.
 - `auto-external` (`boolean`, default: `true`): Add an external icon to the link if target is '_blank'.
-- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control.
-- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`any`): Icon displayed on the inline-start edge (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control.
+- `end-icon` (`any`): Icon displayed on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `disabled` (`boolean`, default: `false`): The disabled state of the link if the component is a button.
 
 ### Slots

package/docs/components/maz-select-country.md

@@ -475,7 +475,7 @@ This ensures consistent internationalization across your application while provi
 - `translations` (`Partial<{ searchPlaceholder: string; }>`, default: `MazUiTranslationsNestedSchema['selectCountry']`): Translations.
 - `hint` (`string`): Hint message displayed.
 - `options` (`Option[]`): Options.
-- `display-names-options` (`DisplayNamesOptions`, default: `{ type: "region", languageDisplay: "standard", fallback: "code", style: "long" }`): Display name type.
+- `display-names-options` (`DisplayNamesOptions`, default: `{ type: "region", languageDisplay: "standard", fallback: "code", style: "long", }`): Display name type.
 - `codes-type` (`CodesType`, default: `defined by displayNamesOptions.type (if 'region', 'country' is used, otherwise 'iso')`): Codes type. Values: `'iso'`, `'bcp'`, `'country'`, `'all'` (non exhaustive).
 - `open` (`boolean`, default: `false`): Open the select.
 - `model-value` (`Option["code"]`, `v-model`): The value of the select.

package/docs/components/maz-sidebar-menu-button.md

@@ -22,7 +22,7 @@ Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
 
 - `to` (`string | Record<string, unknown>`): Route for router-link navigation.
 - `href` (`string`): URL for anchor navigation.
-- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
 - `label` (`string`): Label text.
 - `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
 - `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.

package/docs/components/maz-sidebar-menu-sub.md

@@ -21,7 +21,7 @@ Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
 ### Props
 
 - `label` (`string`): Label for the sub-menu trigger button.
-- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
 - `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
 
 ### Slots

package/docs/components/maz-sidebar.md

@@ -455,7 +455,7 @@ Customize the sidebar width using these CSS custom properties (also settable via
 
 - `to` (`string | Record<string, unknown>`): Route for router-link navigation.
 - `href` (`string`): URL for anchor navigation.
-- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
 - `label` (`string`): Label text.
 - `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
 - `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.
@@ -482,7 +482,7 @@ Customize the sidebar width using these CSS custom properties (also settable via
 ### Props
 
 - `label` (`string`): Label for the sub-menu trigger button.
-- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
 - `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
 
 ### Slots

package/docs/ecosystem/node/index.md

@@ -49,5 +49,5 @@ logger.success('Done')
 
 ## Requirements
 
-- Node.js >= 22.12.0
+- Node.js 22.23.4+, 24.22.1+ or 26.12.1+ (the releases with the October 2026 security fixes)
 - ESM only - published as `"type": "module"`.

package/docs/ecosystem/node/setup-agents.md

@@ -41,11 +41,12 @@ The content comes from the `docs/agents` folder of the `maz-ui` package installe
 Guarantees:
 
 - A file it did not generate is never overwritten (it is reported as `skip`).
-- Generated rules edited by hand are kept and no longer updated (`skip`): their header records a checksum of the content. A formatter that only changes the whitespace does not count as an edit. Delete the file (or the `AGENTS.md` section) to get the rules of a new version.
+- Generated rules edited by hand are kept and no longer updated (`skip`): their header records a checksum of the content, `paths:` frontmatter included. A formatter that only changes the whitespace does not count as an edit. Delete the file (or the `AGENTS.md` section) to get the rules of a new version.
 - In `AGENTS.md`, only the delimited section is managed: your content stays as is.
 - MCP config files are edited in place, keeping their formatting and comments. When a server already runs `@maz-ui/mcp` under another name, nothing is added.
 - An existing entry of the maz-ui MCP server only gets a better command (the installed `@maz-ui/mcp`, a newer pinned version) and keeps its other fields (`env`...). A command written by hand (with `--docs`, for example) is never changed.
 - In a monorepo, rules written by a newer maz-ui and a newer pinned `@maz-ui/mcp` are never downgraded by an app with an older version. Files are written atomically: apps started together never read a half-written file.
+- The Claude rule is scoped with a `paths:` frontmatter, so that Claude Code only loads it when it reads or edits a file of the workspaces that depend on maz-ui (see Scope of the Claude rule), instead of at every session.
 - Without `CLAUDE.md` in the project, Claude Code reads `AGENTS.md`: the Claude rule is then skipped to avoid loading the rules twice.
 - Running it again is idempotent: unchanged files are reported as `unchanged`.
 
@@ -72,6 +73,8 @@ setupAgents({
   mcpVersion: '5.1.0',
   // Command of the MCP server, default: mcpServerCommand(rootDir, mcpVersion, tool)
   mcpServer: undefined,
+  // Scope of the Claude rule: 'auto' (default), 'all' (always loaded) or globs relative to rootDir
+  paths: 'auto',
   // Tool whose agents are configured, default: MAZ_UI_AGENTS_TOOL
   tool: undefined,
   // Rules of the tool, required with another tool than maz-ui, default: the agent docs of docsDir
@@ -79,6 +82,22 @@ setupAgents({
 })
 ```
 
+## Scope of the Claude rule
+
+Without a `paths:` frontmatter, Claude Code loads a rule at every session, in every folder. `setupAgents` writes the frontmatter before the managed header (it must be the first thing of the file) and lists the globs in `result.claudeRulePaths`:
+
+- `paths: 'auto'` (default): the workspaces of the monorepo (`pnpm-workspace.yaml`, or `workspaces` of `package.json`) whose `package.json` depends on one of the `packages` of the tool (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`), with the `ruleGlobs` of the tool inside each: `apps/pwa/**/*.{vue,ts,tsx,css,scss}`. A single package project, or a project where no dependency is found, gets the `ruleGlobs` of the tool for the whole project. A tool without `packages` is never scoped.
+- `paths: 'all'`: no frontmatter, the rule is always loaded.
+- `paths: ['apps/web/**', 'packages/ui/**']`: your globs, used as is.
+
+The frontmatter is rewritten at every run from the project and the options, as long as the file was not edited: the checksum of the header covers the frontmatter and the rules, so an edit of either (your own `paths:`, an added rule) is detected and the file is kept. A rule written before the frontmatter existed, or with a checksum of the rules alone, is updated.
+
+In `'auto'` mode:
+
+- Workspaces excluded by a negated pattern (`!apps/legacy` in `pnpm-workspace.yaml` or `workspaces`) are left out, with the folders below them.
+- The characters `[ ] { } ( ) * ? !` of a folder name are escaped in the globs.
+- When the globs would expand to more than 1000 patterns (the budget of Claude Code for braces), the rule falls back to the `ruleGlobs` of the tool for the whole project.
+
 ## Use it for another tool
 
 `setupAgents` configures maz-ui by default, but any package that ships an MCP server and rules for AI agents can reuse it with the `tool` option, and get the same guarantees. Its rules are passed with `agentDocs`, since they do not come from the maz-ui docs. For example, [relizy](https://relizy.dev) runs it in `relizy mcp init`:
@@ -96,8 +115,16 @@ const tool: AgentsTool = {
   mcpArgs: ['mcp'],
   // Written in the header of the generated rules
   generatedBy: '`relizy mcp init`',
+  // Marker written in the header of the generated content, default: `Managed by relizy` (`Managed by <name>`)
+  marker: 'Managed by relizy',
   // Line under the title of the rules, default: `> relizy <version> is installed: these rules match this version.`
+  // Use `false` to write no note
   versionNote: version => `> relizy ${version} is installed: these rules match this version.`,
+  // Packages (or bins) of former MCP servers: an entry that references one of them is replaced by the entry of the tool, default: none
+  legacyMcpPackages: ['relizy-legacy-mcp'],
+  // Scope of the Claude rule: the workspaces that depend on these packages, and the files of the rule inside them
+  packages: ['relizy'],
+  ruleGlobs: ['relizy.config.*', '**/CHANGELOG.md'],
 }
 
 setupAgents({
@@ -123,6 +150,16 @@ setupAgents({
 
 Each tool only manages its own files, section and server entry: maz-ui and relizy can be set up in the same project, and removing one (`remove: true` with its `tool`) keeps the other. `mcpServerCommand`, `installsMcpPackage`, `readManagedVersion` and `isEditedManagedContent` also take the tool as last argument.
 
+Set `marker` to keep recognizing files generated under a different marker than the name of the tool (e.g. `'Managed by @acme/mcp'` for a tool named `acme`): the header, the owned files and the version are all read from it. With `legacyMcpPackages`, an entry of the MCP config files (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) that references a former package is replaced in place by the entry of the tool, only when the tool has no entry yet. `remove` never touches it.
+
+## Lightweight entry
+
+`@maz-ui/node/agents` exports `setupAgents` and its helpers without the rest of the package: it does not load `consola` nor `figlet` (logger and banner), and its types do not reference them. Use it in tools that only configure agents.
+
+```ts
+import { setupAgents } from '@maz-ui/node/agents'
+```
+
 ## Command of the MCP server
 
 ```ts

package/docs/ecosystem/nuxt.md

@@ -16,7 +16,7 @@ url: "https://maz-ui.com/ecosystem/nuxt"
 
 **Tip: Model Context Protocol (MCP)**
 
-In development, the module connects the AI coding agents detected in the project (Claude Code, Cursor, Copilot...) to the maz-ui [MCP server](./mcp.md), which gives them the docs and rules of the installed maz-ui. See AI Agents.
+In development, the module can connect the AI coding agents detected in the project (Claude Code, Cursor, Copilot...) to the maz-ui [MCP server](./mcp.md), which gives them the docs and rules of the installed maz-ui (opt-in with `agents: { mcp: true }`). See AI Agents.
 
 Check out the documentation of [@maz-ui/mcp](./mcp.md)
 
@@ -190,7 +190,7 @@ export default defineNuxtConfig({
       vZoomImg: true,
     },
 
-    // AI coding agents (default: { rules: false, mcp: true }, false to disable)
+    // AI coding agents (default: { rules: false, mcp: false }, true to enable everything)
     agents: { rules: true, mcp: true },
   }
 })
@@ -440,7 +440,7 @@ Connect your AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex, Winds
 
 ```ts
 const agents = {
-  // Register the maz-ui MCP server in .mcp.json, .cursor/mcp.json, .vscode/mcp.json (default: true)
+  // Register the maz-ui MCP server in .mcp.json, .cursor/mcp.json, .vscode/mcp.json (default: false)
   // Its instructions give the maz-ui rules to the agents
   mcp: true,
   // Also write the rules in .claude/rules/maz-ui.md and in AGENTS.md, for agents without MCP (default: false)

package/docs/guide/ai-agents.md

@@ -68,20 +68,21 @@ npx @maz-ui/mcp init --remove                                  # remove everythi
 
 Run it again after upgrading maz-ui: the rules follow the installed version.
 
-### Nuxt: connected by default
+### Nuxt: opt-in
 
-With [`@maz-ui/nuxt`](../ecosystem/nuxt.md), the agents detected in the project are connected to the maz-ui MCP server when you start the dev server: the module only adds the `maz-ui` entry to their MCP config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). The instructions of the MCP server already give the maz-ui rules to the agents, so no rule file is written by default.
+With [`@maz-ui/nuxt`](../ecosystem/nuxt.md), set `agents.mcp: true` to connect the agents detected in the project to the maz-ui MCP server when you start the dev server: the module adds the `maz-ui` entry to their MCP config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). The instructions of the MCP server already give the maz-ui rules to the agents. Nothing is written by default.
 
 ```ts
 export default defineNuxtConfig({
   modules: ['@maz-ui/nuxt'],
   mazUi: {
-    // default: { rules: false, mcp: true }
+    // default: { rules: false, mcp: false }
     agents: {
+      mcp: true, // register the maz-ui MCP server
       rules: true, // also write .claude/rules/maz-ui.md and the AGENTS.md section
       targets: ['claude', 'agents-md'], // default: the detected agents
     },
-    // or disable it: agents: false
+    // or enable everything: agents: true
   },
 })
 ```

package/docs/guide/migration-v5.md

@@ -82,7 +82,7 @@ The MCP server is read-only - it ships docs, not code edits - so the assistant s
 
 ## Migration checklist
 
-1. Bump **Node to ≥ 22.12** and confirm your audience has modern browsers (see below).
+1. Bump **Node to 22.23.4+, 24.22.1+ or 26.12.1+** and confirm your audience has modern browsers (see below).
 2. If your **custom CSS** uses `hsl(var(--maz-<color>))`, simplify to `var(--maz-<color>)`.
 3. Rename `import 'maz-ui/styles'` to `import 'maz-ui/style.css'` (and `maz-ui/aos-styles` → `maz-ui/aos.css`).
 4. Replace any `rounded-size="base"` with `rounded-size="md"` (or drop the prop - the new default is visually identical).
@@ -101,7 +101,7 @@ The MCP server is read-only - it ships docs, not code edits - so the assistant s
 ### Node
 
 ```bash
-node -v   # must be >= 22.12
+node -v   # must be ^22.23.4, ^24.22.1 or >=26.12.1
 ```
 
 ### Browser support