@maz-ui/mcp 5.1.0-beta.0 → 5.1.0-beta.1

package/docs/components/maz-table-title.md

@@ -1,12 +1,12 @@
 ---
 title: "MazTableTitle"
-description: "MazTableTitle is a building block of MazTable."
+description: "Header cell of MazTable, when you write the header by hand."
 package: "maz-ui"
 ---
 
 # MazTableTitle
 
-> MazTableTitle is a building block of MazTable.
+> Header cell of MazTable, when you write the header by hand.
 
 - Package: `maz-ui`
 - Import: `import MazTableTitle from 'maz-ui/components/MazTableTitle'`

package/docs/components/maz-table-virtualizer.md

@@ -1,12 +1,12 @@
 ---
 title: "MazTableVirtualizer"
-description: "MazTableVirtualizer component."
+description: "Renderless provider loaded on demand by MazTable to virtualize long lists of rows."
 package: "maz-ui"
 ---
 
 # MazTableVirtualizer
 
-> MazTableVirtualizer component.
+> Renderless provider loaded on demand by MazTable to virtualize long lists of rows.
 
 - Package: `maz-ui`
 - Import: `import MazTableVirtualizer from 'maz-ui/components/MazTableVirtualizer'`

package/docs/components/maz-tabs-bar.md

@@ -1,12 +1,12 @@
 ---
 title: "MazTabsBar"
-description: "MazTabsBar is a building block of MazTabs."
+description: "Bar of tab buttons of MazTabs."
 package: "maz-ui"
 ---
 
 # MazTabsBar
 
-> MazTabsBar is a building block of MazTabs.
+> Bar of tab buttons of MazTabs.
 
 - Package: `maz-ui`
 - Import: `import MazTabsBar from 'maz-ui/components/MazTabsBar'`

package/docs/components/maz-tabs-content-item.md

@@ -1,12 +1,12 @@
 ---
 title: "MazTabsContentItem"
-description: "MazTabsContentItem is a building block of MazTabs."
+description: "Panel of MazTabs displayed when its tab is active."
 package: "maz-ui"
 ---
 
 # MazTabsContentItem
 
-> MazTabsContentItem is a building block of MazTabs.
+> Panel of MazTabs displayed when its tab is active.
 
 - Package: `maz-ui`
 - Import: `import MazTabsContentItem from 'maz-ui/components/MazTabsContentItem'`

package/docs/components/maz-tabs-content.md

@@ -1,12 +1,12 @@
 ---
 title: "MazTabsContent"
-description: "MazTabsContent is a building block of MazTabs."
+description: "Container of the tab panels of MazTabs."
 package: "maz-ui"
 ---
 
 # MazTabsContent
 
-> MazTabsContent is a building block of MazTabs.
+> Container of the tab panels of MazTabs.
 
 - Package: `maz-ui`
 - Import: `import MazTabsContent from 'maz-ui/components/MazTabsContent'`

package/docs/components/maz-ui-provider.md

@@ -1,12 +1,12 @@
 ---
 title: "MazUiProvider"
-description: "MazUiProvider component."
+description: "Component alternative to the MazUi plugin: provides the theme, the translations and the default props of maz-ui to its subtree (lazy loaded pages, scoped themes)."
 package: "maz-ui"
 ---
 
 # MazUiProvider
 
-> MazUiProvider component.
+> Component alternative to the MazUi plugin: provides the theme, the translations and the default props of maz-ui to its subtree (lazy loaded pages, scoped themes).
 
 - Package: `maz-ui`
 - Import: `import MazUiProvider from 'maz-ui/components/MazUiProvider'`

package/docs/composables/use-aos.md

@@ -1,13 +1,13 @@
 ---
 title: "useAos"
-description: "Vue composable for handling aos plugin in your components"
+description: "Vue composable to access the AOS plugin instance (animations on scroll) in your components, to refresh or trigger the animations"
 package: "maz-ui"
 url: "https://maz-ui.com/composables/use-aos"
 ---
 
 # useAos
 
-> Vue composable for handling aos plugin in your components
+> Vue composable to access the AOS plugin instance (animations on scroll) in your components, to refresh or trigger the animations
 
 - Package: `maz-ui`
 - Import: `import { useAos } from 'maz-ui/composables/useAos'`

package/docs/composables/use-breakpoints.md

@@ -1,11 +1,11 @@
 ---
-title: "useWindowSize"
+title: "useBreakpoints"
 description: "This composable extends the functionality of the useWindowSize composable to manage responsive breakpoints"
 package: "maz-ui"
 url: "https://maz-ui.com/composables/use-breakpoints"
 ---
 
-# useWindowSize
+# useBreakpoints
 
 > This composable extends the functionality of the useWindowSize composable to manage responsive breakpoints
 

package/docs/composables/use-toast.md

@@ -1,13 +1,13 @@
 ---
 title: "useToast"
-description: "Vue composable for handling toast plugin in your components"
+description: "Vue composable to display toast notifications (info, success, warning, error, with actions and buttons) from your components, through the toast plugin"
 package: "maz-ui"
 url: "https://maz-ui.com/composables/use-toast"
 ---
 
 # useToast
 
-> Vue composable for handling toast plugin in your components
+> Vue composable to display toast notifications (info, success, warning, error, with actions and buttons) from your components, through the toast plugin
 
 - Package: `maz-ui`
 - Import: `import { useToast } from 'maz-ui/composables/useToast'`

package/docs/composables/use-user-visibility.md

@@ -1,13 +1,13 @@
 ---
-title: "user-visibility"
-description: "Plugin to see and manage the user page visibility"
+title: "useUserVisibility"
+description: "Vue composable to know whether the user is looking at the page (Page Visibility API), with an optional delay before considering them away"
 package: "maz-ui"
 url: "https://maz-ui.com/composables/use-user-visibility"
 ---
 
-# user-visibility
+# useUserVisibility
 
-> Plugin to see and manage the user page visibility
+> Vue composable to know whether the user is looking at the page (Page Visibility API), with an optional delay before considering them away
 
 - Package: `maz-ui`
 - Import: `import { useUserVisibility } from 'maz-ui/composables/useUserVisibility'`

package/docs/composables/use-wait.md

@@ -1,13 +1,13 @@
 ---
 title: "useWait"
-description: "Vue composable for handling wait plugins"
+description: "Vue composable to manage loading states (start, stop, check) in your components, through the wait plugin and the MazFullscreenLoader"
 package: "maz-ui"
 url: "https://maz-ui.com/composables/use-wait"
 ---
 
 # useWait
 
-> Vue composable for handling wait plugins
+> Vue composable to manage loading states (start, stop, check) in your components, through the wait plugin and the MazFullscreenLoader
 
 - Package: `maz-ui`
 - Import: `import { useWait } from 'maz-ui/composables/useWait'`

package/docs/directives/fullscreen-img.md

@@ -1,13 +1,13 @@
 ---
-title: "v-fullscreen-img"
-description: "Displays images fullscreen on click"
+title: "vFullscreenImg"
+description: "vFullscreenImg is a Vue directive that opens an image in fullscreen on click, with zoom and navigation between the images of a group"
 package: "maz-ui"
 url: "https://maz-ui.com/directives/fullscreen-img"
 ---
 
-# v-fullscreen-img
+# vFullscreenImg
 
-> Displays images fullscreen on click
+> vFullscreenImg is a Vue directive that opens an image in fullscreen on click, with zoom and navigation between the images of a group
 
 - Package: `maz-ui`
 - Import: `import { vFullscreenImg } from 'maz-ui/directives/vFullscreenImg'`

package/docs/ecosystem/icons/icon-set.md

@@ -1,13 +1,13 @@
 ---
-title: "IconSet"
-description: ""
+title: "Icon Set"
+description: "Search and copy the 860+ icons of @maz-ui/icons, with the naming convention and the static, lazy and raw imports of each icon"
 package: "@maz-ui/icons"
 url: "https://maz-ui.com/ecosystem/icons/icon-set"
 ---
 
-# IconSet
+# Icon Set
 
-> 
+> Search and copy the 860+ icons of @maz-ui/icons, with the naming convention and the static, lazy and raw imports of each icon
 
 - Package: `@maz-ui/icons`
 - Web: https://maz-ui.com/ecosystem/icons/icon-set

package/docs/ecosystem/icons/index.md

@@ -1,13 +1,13 @@
 ---
-title: "Icons"
-description: ""
+title: "@maz-ui/icons"
+description: "The @maz-ui/icons package provides 860+ SVG icons (interface icons, brand logos, country flags) as tree-shakable Vue components, lazy components or raw SVG strings"
 package: "@maz-ui/icons"
 url: "https://maz-ui.com/ecosystem/icons/"
 ---
 
-# Icons
+# @maz-ui/icons
 
-> 
+> The @maz-ui/icons package provides 860+ SVG icons (interface icons, brand logos, country flags) as tree-shakable Vue components, lazy components or raw SVG strings
 
 - Package: `@maz-ui/icons`
 - Import: `import { MazCheck } from '@maz-ui/icons/static/MazCheck'` or `import { MazIconsResolver } from '@maz-ui/icons/resolvers'`

package/docs/ecosystem/mcp.md

@@ -23,7 +23,7 @@ It registers the server and writes the maz-ui rules for the agents of your proje
 | `search_docs` | Find what maz-ui provides for a need, described in plain words ("user avatar with initials", "confirm before delete", "debounce search") or by name. Understands the vocabulary of other libraries ("modal", "snackbar", "combobox") |
 | `get_component_api` | Exact API of up to 10 components: props with types, defaults and accepted values, `v-model`, events with payload, slots with bindings, exposed methods |
 | `find_icons` | Icons of `@maz-ui/icons` by meaning ("delete", "settings", "france flag") with their imports |
-| `get_theme_tokens` | Every Tailwind class and CSS variable of the maz-ui theme: colors, radius, shadows, spacing, breakpoints, fonts, z-index, utilities |
+| `get_theme_tokens` | The theme of your project (preset values, `@theme` tokens, variants, utilities, read from your files) and every Tailwind class and CSS variable of the maz-ui theme: colors, radius, shadows, spacing, breakpoints, fonts, z-index, utilities |
 | `get_doc` | Any documentation page by id or name (`components/maz-btn`, `useToast`, `guide/tailwind`), whole or by sections |
 | `list_docs` | Catalog of the components, composables, directives, plugins, helpers, packages and guides |
 | `get_setup_guide` | Installation steps for Vue or Nuxt, with or without Tailwind |

package/docs/ecosystem/nuxt.md

@@ -447,17 +447,21 @@ const agents = {
   rules: false,
   // 'claude' | 'agents-md' | 'cursor' | 'vscode' (default: the detected agents)
   targets: ['claude', 'agents-md'],
+  // Folder where the files are written, relative to the Nuxt app (default: the root of the workspace)
+  dir: '../..',
 }
 // agents: true enables mcp and rules, agents: false disables everything
 ```
 
+In a monorepo, the files are written at the **root of the workspace** (`workspaceDir` of Nuxt), where your agents start, not in the Nuxt app: a single `.mcp.json` serves every app. Set `dir` to choose another folder.
+
 The module runs in development only (never in CI nor in tests), only for the agents it detects in the project (`.claude/`, `CLAUDE.md`, `.mcp.json`, `.cursor/`, `.vscode/mcp.json`, `.github/copilot-instructions.md`, `AGENTS.md`, `.codex/`, `.windsurf/`...), and keeps the files up to date when you upgrade maz-ui:
 
 - `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`: a `maz-ui` server entry, added only when no maz-ui MCP server is already registered
 - with `rules: true`, `.claude/rules/maz-ui.md`: a Claude Code rule (skipped when Claude reads `AGENTS.md`, i.e. without `CLAUDE.md`)
 - with `rules: true`, `AGENTS.md`: a section delimited by `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`, read by Codex, Cursor, Copilot, Windsurf...
 
-It never overwrites a file it does not own: your `CLAUDE.md`, your own rules and the other MCP servers are left untouched. Commit the generated files to share them with your team. See the [AI agents guide](../guide/ai-agents.md) for details.
+It never overwrites a file it does not own: your `CLAUDE.md`, your own rules and the other MCP servers are left untouched, and an existing `maz-ui` server entry (for example pinned to a version) is kept as is. Commit the generated files to share them with your team (check that `.claude/` is not in your `.gitignore`). See the [AI agents guide](../guide/ai-agents.md) for details.
 
 ## Advanced Theming
 

package/docs/ecosystem/translations.md

@@ -1,13 +1,13 @@
 ---
 title: "Translations (i18n)"
-description: "Internationalization for Maz-UI components."
+description: "Internationalization of the maz-ui components with @maz-ui/translations: built-in locales, custom messages, lazy loading and runtime locale switching with useTranslations"
 package: "@maz-ui/translations"
 url: "https://maz-ui.com/ecosystem/translations"
 ---
 
 # Translations (i18n)
 
-> Internationalization for Maz-UI components.
+> Internationalization of the maz-ui components with @maz-ui/translations: built-in locales, custom messages, lazy loading and runtime locale switching with useTranslations
 
 - Package: `@maz-ui/translations`
 - Import: `import { useTranslations } from '@maz-ui/translations'` or `import { fr } from '@maz-ui/translations'`

package/docs/ecosystem/utils/country-code-to-unicode-flag.md

@@ -1,11 +1,11 @@
 ---
-title: "country-code-to-unicode-flag"
+title: "countryCodeToUnicodeFlag"
 description: "Convert country code in unicode flag"
 package: "@maz-ui/utils"
 url: "https://maz-ui.com/ecosystem/utils/country-code-to-unicode-flag"
 ---
 
-# country-code-to-unicode-flag
+# countryCodeToUnicodeFlag
 
 > Convert country code in unicode flag
 

package/docs/guide/ai-agents.md

@@ -81,7 +81,7 @@ export default defineNuxtConfig({
 })
 ```
 
-It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own.
+It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own. In a monorepo, it writes at the root of the workspace, where the agents start (`agents.dir` to choose another folder).
 
 ### Without any file in the project
 
@@ -122,7 +122,7 @@ The MCP server gives agents tools that work with the needs they have, and verify
 | `search_docs` | Find what maz-ui provides for a need ("confirm before delete", "phone input", "debounce search") |
 | `get_component_api` | Exact props, values, events, slots of up to 10 components |
 | `find_icons` | Icons by meaning ("delete", "settings", "france flag") with their imports |
-| `get_theme_tokens` | Every Tailwind class and CSS variable of the theme |
+| `get_theme_tokens` | The theme of your project (preset, `@theme` tokens, variants, utilities) and every Tailwind class and CSS variable of maz-ui |
 | `get_doc` | Any page of the docs, or only some sections |
 | `list_docs` | The whole catalog |
 | `get_setup_guide` | Installation in a Vue or Nuxt app, with or without Tailwind |
@@ -193,7 +193,7 @@ This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz
 
 Before creating a component, composable, helper, icon or style, check what maz-ui offers:
 
-- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes), `get_doc`, `review_code`.
+- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes of the project and of maz-ui), `get_doc`, `review_code`.
 - **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, resolve `maz-ui` from the app package). Read the relevant page before using an API.
 
 Never guess an API: only use props, events, slots and imports that are documented.
@@ -215,7 +215,9 @@ Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-wri
 
 ### Styling with Tailwind
 
-The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`). Only use its tokens:
+The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:
+
+- **Project tokens first**: the Tailwind entry of the project (the CSS file that imports `maz-ui/tailwindcss/theme.css`) adds its own `@theme` tokens (fonts, animations, colors...), `@custom-variant` and `@utility`, and the `definePreset` file sets the brand values of the maz-ui tokens. `get_theme_tokens` lists both; without the MCP server, read these files. When a value is missing, add a token to the project `@theme` and use its class 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`, plus `bg-container` and `bg-input`. Example: `bg-surface text-foreground border-divider`, `bg-primary text-primary-foreground`, `text-muted`.
 - Never use 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: do not add `dark:` color overrides.

package/docs/guide/tailwind.md

@@ -273,6 +273,28 @@ Toggle the mode with `useTheme()` (`toggleDarkMode()`, `setColorMode('dark' | 'l
 
 ## Extending the theme
 
+### How the layers fit together
+
+Your theme is built from three layers, from the most global to the most specific:
+
+1. **The preset** (`definePreset` of `@maz-ui/themes`) gives the **values**: it emits runtime CSS variables (`--maz-primary`, `--maz-font-family`, `--maz-rounded-md`, `--maz-motion-fast`...) for the light and dark modes.
+2. **The maz-ui theme** (`maz-ui/tailwindcss/theme.css`) gives the **class names**: it maps each Tailwind token to a preset variable (`--color-primary: var(--maz-primary)`, `--font-display: var(--maz-font-display-stack)`). `bg-primary` or `font-display` therefore follow the active preset and color mode, without rebuild.
+3. **Your Tailwind entry** gives the **project tokens**: everything you declare after the maz-ui imports (`@theme`, `@custom-variant`, `@utility`) adds classes next to the maz-ui ones.
+
+| You want | Put it in | You get |
+| --- | --- | --- |
+| Brand colors, fonts, radius, shadows, motion, spacing | the preset (`colors`, `foundation`, `scales`) | the same maz-ui classes with your values, components included |
+| Background of cards and inputs, button font weight | the preset (`components`) | `bg-container`, `bg-input`, `MazBtn` |
+| A color outside the maz-ui roles (chart series, category) | `@theme { --color-* }` | `bg-<name>`, `text-<name>`... |
+| An animation | `@theme { --animate-* }` + `@keyframes` | `animate-<name>` |
+| A variant (short screens, a state) | `@custom-variant` | `<name>:` |
+| A reusable group of declarations | `@utility` | `<name>` |
+| The width of `padded-container` | `--maz-container-max-width` in your base layer | Container width |
+
+**Warning: Redefining a maz-ui token**
+
+A token you redefine in your `@theme` (`--color-primary`, `--font-sans`, `--radius-md`...) replaces the maz-ui mapping: the class keeps your literal value and **stops following the preset** (preset switch, light and dark values). Change brand values in the preset instead; redefine a token only when you need it, for example to give a literal font name to `@nuxt/fonts` (see Fonts).
+
 ### Brand colors: use a preset
 
 Your brand colors, radius, fonts and spacing belong to a theme preset: every maz-ui component **and** every Tailwind utility (`bg-primary`, `rounded-md`, `font-sans`...) then use them, in light and dark modes.
@@ -321,7 +343,7 @@ For a color outside the maz-ui roles (a chart series, a product category), decla
 
 ### Fonts
 
-The font utilities read the preset (`foundation.font-family`, `font-display-stack`, `font-mono-stack`). You can also override them in your Tailwind entry, after the maz-ui import:
+The font utilities read the preset: `font-sans` uses `foundation.font-family`, `font-display` uses `font-display-stack` and `font-mono` uses `font-mono-stack`. You can also redefine them in your Tailwind entry, after the maz-ui import (keep the same stacks as the preset, the classes no longer follow it):
 
 ```css
 @theme {
@@ -466,6 +488,8 @@ Tailwind v4 processes each SFC `<style>` block in isolation: a block that uses `
 
 Every class and variable of this page is available to AI coding agents, generated from the sources of the installed version: the `get_theme_tokens` tool of the [maz-ui MCP server](../ecosystem/mcp.md), and `node_modules/maz-ui/docs/reference/tailwind-tokens.md`. See [AI agents](./ai-agents.md).
 
+`get_theme_tokens` also reads **your** theme: the Tailwind entries of the project (CSS files with `@theme`, `@custom-variant`, `@utility` or a `tailwindcss` import) and the `definePreset` calls, in every app of a monorepo. Agents get your preset values, your tokens with their comments (`animate-rise`, `font-display`, `short:`...), the tokens that redefine a maz-ui one and the setup problems (missing maz-ui import). A comment above a token in your `@theme` is a good place to say when to use it.
+
 ## Migrating from Tailwind v3
 
 Run the official upgrade tool first, it handles most of the v3 to v4 transition (renamed utilities, `tailwind.config.js` to CSS-first configuration):