maz-ui 5.2.0 → 5.3.0

package/dist/resolvers/MazDirectivesResolver.js

@@ -1,5 +1,5 @@
 import { capitalize } from "@maz-ui/utils/helpers/capitalize";
-//#region src/resolvers/MazDirectivesResolver.ts
+// src/resolvers/MazDirectivesResolver.ts
 var vRegex = /^v/;
 function MazDirectivesResolver(options) {
 	return {
@@ -14,5 +14,4 @@ function MazDirectivesResolver(options) {
 		}
 	};
 }
-//#endregion
 export { MazDirectivesResolver };

package/dist/resolvers/MazModulesResolver.js

@@ -1,5 +1,5 @@
 import { capitalize } from "@maz-ui/utils/helpers/capitalize";
-//#region src/resolvers/MazModulesResolver.ts
+// src/resolvers/MazModulesResolver.ts
 var composablesMap = {
 	useInjectStrict: !0,
 	useAos: !0,
@@ -85,5 +85,4 @@ function MazModulesResolver(options) {
 		};
 	};
 }
-//#endregion
 export { MazModulesResolver };

package/dist/resolvers/index.js

@@ -1,4 +1,4 @@
-import { MazModulesResolver } from "./MazModulesResolver.js";
-import { MazDirectivesResolver } from "./MazDirectivesResolver.js";
 import { MazComponentsResolver } from "./MazComponentsResolver.js";
+import { MazDirectivesResolver } from "./MazDirectivesResolver.js";
+import { MazModulesResolver } from "./MazModulesResolver.js";
 export { MazComponentsResolver, MazDirectivesResolver, MazModulesResolver };

package/dist/tailwindcss/variables/breakpoints.js

@@ -1,4 +1,4 @@
-//#region src/tailwindcss/variables/breakpoints.ts
+// src/tailwindcss/variables/breakpoints.ts
 var screens = {
 	"mob-s": "320px",
 	"mob-m": "425px",
@@ -18,5 +18,4 @@ function getNumericScreensFromTailwind(inputScreens) {
 	for (let [key, value] of Object.entries(inputScreens)) breakpoints[key] = Number.parseInt(value, 10);
 	return breakpoints;
 }
-//#endregion
 export { getNumericScreensFromTailwind, screens };

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-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-dropdown.md

@@ -385,8 +385,8 @@ The trigger button exposes the menu state (`aria-haspopup="menu"`, `aria-expande
 - `close-on-escape` (`boolean`, default: `true`): Close popover when pressing Escape key.
 - `aria-labelledby` (`string`): ARIA labelledby attribute for accessibility.
 - `aria-describedby` (`string`): ARIA describedby attribute for accessibility.
-- `offset` (`number`, default: `8`): Distance between trigger and popover in pixels.
 - `aria-label` (`string`): ARIA label for the popover.
+- `offset` (`number`, default: `8`): Distance between trigger and popover in pixels.
 - `prefer-position` (`MazPopoverPreferPosition`, default: `"bottom-start"`): Preferred position of the popover relative to trigger when auto position is used - Preferred position of the popover relative to trigger. Values: `'auto'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`, `'left-start'`, `'left-end'`, `'right-start'`, `'right-end'` (non exhaustive).
 - `fallback-position` (`MazPopoverFallbackPosition`, default: `auto`): Fallback position of the popover relative to trigger when prefer position is not visible - Fallback position of the popover relative to trigger. Values: `'auto'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`, `'left-start'`, `'left-end'`, `'right-start'`, `'right-end'` (non exhaustive).
 - `announce-changes` (`boolean`, default: `false`): Announce content changes to screen readers.

package/docs/components/maz-input-number.md

@@ -61,7 +61,7 @@ You can remove the buttons with the props `hide-buttons`
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the input number component.
 - `hide-buttons` (`boolean`, default: `false`): Whether to hide the increment and decrement buttons or not.
 - `text-center` (`boolean`, default: `true`): Whether to center the text inside the input or not.
-- `inputmode` (`"text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
+- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
 - `block` (`boolean`): The input will be displayed in full width.
 - `error` (`boolean`, default: `false`): Will display the input in error state.
 - `hint` (`string`): The hint text to display below the input.

package/docs/components/maz-input-phone-number.md

@@ -518,7 +518,7 @@ interface MazInputPhoneNumberData {
 - `block` (`boolean`, default: `false`): The input will be displayed in full width.
 - `orientation` (`"row" | "col" | "responsive"`, default: `"responsive"`): Orientation of the inputs in the component.
 - `country-select-attributes` (`Record<string, unknown>`, default: `{ name: "country", autocomplete: "off", style: { width: "14rem", }, }`): Meta attributes of the country input.
-- `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
+- `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
 - `assistive-text` (`string`): Helper text displayed below the input to provide additional context or validation feedback.
 - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
 

package/docs/components/maz-input.md

@@ -305,7 +305,7 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
 - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
 - `input-classes` (`string`): Additional CSS classes to apply specifically to the input wrapper element.
 - `border` (`boolean`, default: `true`): Controls whether the input has a visible border. Set to false for borderless inputs.
-- `inputmode` (`"text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
+- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Controls the height and text size of the input component.
 - `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.

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

@@ -475,15 +475,15 @@ 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.
 - `block` (`boolean`): The input will be displayed in full width.
 - `disabled` (`boolean`): Disable the component.
 - `required` (`boolean`): Make the input required in the form.
-- `label` (`string`): The label of the select.
 - `placeholder` (`string`): The placeholder of the select.
+- `label` (`string`): The label of the select.
 - `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
 - `transition` (`string`, default: `'scale-fade'`): The transition name of the panel list options.
 - `prefer-position` (`MazPopoverPreferPosition`, default: `'bottom-start'`): The prefer position of the list.

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