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

package/docs/guide/ai-agents.md

@@ -0,0 +1,239 @@
+---
+title: "AI agents"
+description: "Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review."
+package: "maz-ui"
+url: "https://maz-ui.com/guide/ai-agents"
+---
+
+# AI agents
+
+> Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review.
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/ai-agents
+
+## Why
+
+Left alone, coding agents rebuild what maz-ui already provides: native buttons instead of `MazBtn`, lodash instead of `@maz-ui/utils`, inline SVG instead of `@maz-ui/icons`, `bg-blue-500` instead of the theme colors. They also guess APIs from outdated training data.
+
+maz-ui gives them four things:
+
+| | What | Where |
+| --- | --- | --- |
+| **Rules** | How to use maz-ui in your project, loaded automatically by the agent | `.claude/rules/maz-ui.md`, `AGENTS.md` |
+| **Version-matched docs** | Agent-ready markdown of the installed version: guides, component APIs, icons, Tailwind tokens | `node_modules/maz-ui/docs/` |
+| **MCP server** | Search by need, exact component APIs, icons, theme tokens, setup guides, code review | `npx @maz-ui/mcp` |
+| **Code review** | Static checks against the real maz-ui APIs, in the agent loop and in CI | `review_code` tool, `npx @maz-ui/mcp review` |
+
+## Quick start
+
+Run this command at the root of your project:
+
+```bash
+npx @maz-ui/mcp init
+```
+
+It detects the agents you use and configures them, using the docs of the maz-ui version installed in the project:
+
+| Agent | Rules | MCP server |
+| --- | --- | --- |
+| Claude Code | `.claude/rules/maz-ui.md` (always loaded) | `.mcp.json` |
+| Cursor | `AGENTS.md` | `.cursor/mcp.json` |
+| GitHub Copilot (VS Code) | `AGENTS.md` | `.vscode/mcp.json` |
+| Codex, Windsurf, Zed, Gemini CLI... | `AGENTS.md` | global config of the agent (see [MCP](../ecosystem/mcp.md)) |
+
+When no agent is detected, it configures Claude Code and `AGENTS.md`. Commit the generated files: your whole team and your CI agents get them.
+
+**Tip: It never overwrites your own instructions**
+
+- Your `CLAUDE.md` is never touched: Claude Code loads `.claude/rules/maz-ui.md` on top of it.
+- In `AGENTS.md`, maz-ui only manages the section between `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`.
+- In the MCP config files, only the `maz-ui` entry is added, the formatting and comments of the file are preserved. An existing server running `@maz-ui/mcp` under another name is kept as is.
+- A file you created yourself with the same path is never overwritten.
+
+### Options
+
+```bash
+npx @maz-ui/mcp init --targets claude,agents-md,cursor,vscode  # choose the agents
+npx @maz-ui/mcp init --no-rules                                # MCP server only
+npx @maz-ui/mcp init --no-mcp                                  # rules only
+npx @maz-ui/mcp init --dry-run                                 # show the changes
+npx @maz-ui/mcp init --remove                                  # remove everything init added
+```
+
+Run it again after upgrading maz-ui: the rules follow the installed version.
+
+### Nuxt: connected by default
+
+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.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    // default: { rules: false, mcp: true }
+    agents: {
+      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
+  },
+})
+```
+
+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
+
+The MCP server carries the rules in its instructions: registering it once for your user is enough, in every project, without writing anything in them.
+
+- Claude Code: install the plugin, or run `claude mcp add maz-ui --scope user -- npx -y @maz-ui/mcp@latest`.
+- Cursor, Windsurf, Codex...: add the server to the global MCP config of the agent (see [MCP](../ecosystem/mcp.md#configuration)).
+
+Write the project files (`init`, the Nuxt option) when your whole team, or agents without MCP, need the rules.
+
+## Version-matched docs
+
+Each `maz-ui` release ships its documentation for agents in `node_modules/maz-ui/docs/`:
+
+```txt
+node_modules/maz-ui/docs/
+├── README.md                     # index of every page, start here
+├── rules.md                      # the rules below
+├── manifest.json                 # machine-readable index, component APIs, icons, tokens
+├── components/maz-btn.md         # usage, examples and full API of each component
+├── composables/  directives/  plugins/  guide/
+├── ecosystem/                    # themes, translations, icons, nuxt, utils, node...
+└── reference/
+    ├── tailwind-tokens.md        # every Tailwind class and CSS variable of the theme
+    └── icons.md                  # the 860+ icon names
+```
+
+The pages are the ones of this website, cleaned for agents: no live demos, every example as code, and the full API of each component (props with their accepted values, `v-model`, events, slots) generated from the TypeScript sources.
+
+Agents read the docs of **your** version, not what they remember from their training data. The MCP server serves the same files.
+
+## MCP server
+
+The MCP server gives agents tools that work with the needs they have, and verify their code:
+
+| Tool | Purpose |
+| --- | --- |
+| `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` | 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 |
+| `review_code` | Review files against the installed maz-ui |
+
+See [MCP](../ecosystem/mcp.md) for the configuration of each agent.
+
+## Claude Code plugin
+
+The maz-ui plugin bundles the MCP server, a `maz-ui` skill (rules and workflow) and a hook that reviews every `.vue`, `.ts` and `.css` file Claude edits, so it fixes maz-ui mistakes before you see them.
+
+```txt
+/plugin marketplace add LouisMazel/maz-ui
+/plugin install maz-ui@maz-ui
+```
+
+The plugin works in every project, `init` configures one project for your whole team: use both or either.
+
+## Code review in CI
+
+The checks of `review_code` are also available from the command line:
+
+```bash
+npx @maz-ui/mcp review "src/**/*.{vue,ts,css}"
+npx @maz-ui/mcp review app --min-severity warning --max-warnings 0
+npx @maz-ui/mcp review src --format json
+```
+
+The command exits with an error code when it finds errors (or more warnings than `--max-warnings`).
+
+| Rule | Severity | Detects |
+| --- | --- | --- |
+| `unknown-component` | error | `<MazButton>` (did you mean `MazBtn`?) |
+| `unknown-prop` | warning | A prop the component does not have (`colour`) |
+| `invalid-prop-value` | error | `color="red"` on a component that accepts `primary`, `secondary`... |
+| `boolean-prop-string` | error | `disabled="false"` (a truthy string) |
+| `unknown-model`, `unknown-event`, `unknown-slot` | error | `v-model:foo`, `@clik`, `<template #captions>` |
+| `unknown-icon` | error | An icon that does not exist in `@maz-ui/icons` |
+| `prefer-maz-component` | warning | `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`... |
+| `inline-svg` | warning | SVG icons written inline |
+| `prefer-ecosystem`, `prefer-utils` | warning / info | lodash, VueUse, toast, icon, tooltip, date picker... libraries that maz-ui already covers |
+| `theme-colors` | warning | Default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`) |
+| `hardcoded-color` | warning | `bg-[#1d90ff]`, `color: #fff` |
+| `internal-prefix` | error | The internal `maz:` prefix |
+| `tailwind-v3` | warning | `bg-opacity-50`, `flex-shrink-0`... |
+| `missing-reference` | error | `@apply` in a SFC style block without `@reference` |
+| `manual-dark-mode` | warning | Dark mode handled by hand instead of `useTheme()` |
+| `root-import`, `internal-import` | error | Runtime imports from `maz-ui` (types only) or from `src`/`dist` |
+| `nuxt-auto-import` | info | Imports that `@maz-ui/nuxt` already auto-imports |
+
+When something is intended, ignore it with a comment on the line above (`<!-- maz-ui-review-ignore prefer-maz-component -->`, `// maz-ui-review-ignore theme-colors`), or `maz-ui-review-ignore-file` for a whole file.
+
+## llms.txt
+
+The documentation is also published for agents that browse the web:
+
+- [maz-ui.com/llms.txt](https://maz-ui.com/llms.txt): index of every page
+- [maz-ui.com/llms-full.txt](https://maz-ui.com/llms-full.txt): the whole documentation in one file
+- Each page as markdown: `https://maz-ui.com/components/maz-btn.md`
+
+## The rules
+
+This is what `init`, the Nuxt option, the Claude Code plugin and the MCP server teach to your agents:
+
+This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz-ui/icons`, `@maz-ui/utils`, `@maz-ui/translations`, `@maz-ui/nuxt`). Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.
+
+### Look it up before you write it
+
+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 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.
+
+### Components
+
+- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not `<button>`), `MazInput`, `MazSelect`, `MazCheckbox`, `MazSwitch`, `MazTextarea`, `MazDialog`, `MazDialogConfirm`, `MazDrawer`, `MazBottomSheet`, `MazPopover`, `MazDropdown`, `MazTabs`, `MazTable`, `MazCard`, `MazAvatar`, `MazBadge`, `MazAlert`, `MazSkeleton`, `MazSpinner`, `MazDatePicker`, `MazInputPhoneNumber`, `MazDropzone`, `MazStepper`, `MazSidebar`, `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`.
+- Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
+- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
+
+### Icons
+
+Use `@maz-ui/icons` (860+ icons: `MazTrash`, `MazXMark`, `MazMagnifyingGlass`, `MazFlagFR`, `MazLogoVue`...). Never inline SVG or add another icon library. Pass icon components to icon props: `<MazBtn :start-icon="MazTrash">`.
+
+### Helpers and composables
+
+Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `capitalize`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `getCookie`/`setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...
+
+### 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:
+
+- **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.
+- 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 and its documentation.
+- 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.
+
+### Imports
+
+- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `maz-ui/directives/vTooltip`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/static/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.
+
+### Before you finish
+
+Run `review_code` (MCP) on the files you changed, or `npx @maz-ui/mcp review <files>`, and fix every finding.

package/docs/{src/guide → guide}/browser-support.md

@@ -1,9 +1,16 @@
 ---
-title: Browser support
-description: Maz-UI v5 browser compatibility matrix and the native CSS features it depends on.
+title: "Browser support"
+description: "Maz-UI v5 browser compatibility matrix and the native CSS features it depends on."
+package: "maz-ui"
+url: "https://maz-ui.com/guide/browser-support"
 ---
 
-# {{ $frontmatter.title }}
+# Browser support
+
+> Maz-UI v5 browser compatibility matrix and the native CSS features it depends on.
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/browser-support
 
 Maz-UI v5 is built on **Tailwind CSS v4**, which relies on modern native CSS features with no polyfill path. If your audience still uses older browsers, stay on Maz-UI v4.
 
@@ -28,32 +35,32 @@ Maz-UI v5 + Tailwind v4 uses the following native CSS features:
 
 Used for every alpha modifier (`bg-primary/50`, the custom `color-mix(in srgb, var(--X) 60%, transparent)` generated by the `@maz-ui/upgrade` package for `hsl(var(--X) / 60%)`, etc.).
 
-[Browser support · caniuse](https://caniuse.com/?search=color-mix) — supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+[Browser support · caniuse](https://caniuse.com/?search=color-mix) - supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
 
 ### `@property`
 
 Used internally by Tailwind v4 to declare typed custom properties with default values. Powers the `--tw-translate-x`, `--tw-rotate`, etc. that back transform utilities.
 
-[Browser support · caniuse](https://caniuse.com/?search=%40property) — supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+[Browser support · caniuse](https://caniuse.com/?search=%40property) - supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
 
 ### Native CSS nesting
 
 Used by Tailwind v4 internally and by Maz-UI utilities like `cap-f` (`&::first-letter`). v4 does not run a CSS-nesting preprocessor; the output relies on the browser parsing nested rules directly.
 
-[Browser support · caniuse](https://caniuse.com/css-nesting) — supported everywhere since Chromium 112 / Safari 16.5 / Firefox 117.
+[Browser support · caniuse](https://caniuse.com/css-nesting) - supported everywhere since Chromium 112 / Safari 16.5 / Firefox 117.
 
 ### `:has()` selector
 
 Used by a few Maz-UI utilities for parent-aware styling.
 
-[Browser support · caniuse](https://caniuse.com/css-has) — supported everywhere since Chromium 105 / Safari 15.4 / Firefox 121.
+[Browser support · caniuse](https://caniuse.com/css-has) - supported everywhere since Chromium 105 / Safari 15.4 / Firefox 121.
 
 ## Testing on older browsers
 
 If you need to support a browser older than the matrix above:
 
-1. **Stay on Maz-UI v4** — it keeps Tailwind v3 and targets Chromium 90+, Safari 14+, Firefox 90+.
-2. **Check your real audience** using your analytics tool before bumping to v5. "Support everything" is often outdated advice in 2026 — most teams can comfortably drop anything older than Chromium 111.
+1. **Stay on Maz-UI v4** - it keeps Tailwind v3 and targets Chromium 90+, Safari 14+, Firefox 90+.
+2. **Check your real audience** using your analytics tool before bumping to v5. "Support everything" is often outdated advice in 2026 - most teams can comfortably drop anything older than Chromium 111.
 
 ## Testing on the minimum versions
 
@@ -68,14 +75,14 @@ Then run your visual tests against that matrix in CI.
 
 ## What happens on unsupported browsers
 
-- **`color-mix` unsupported** — any utility that goes through an alpha modifier (`bg-primary/50`, the custom overlay colors in MazDialog / MazBackdrop) falls back to the base color with no transparency. Visual regression but not a crash.
-- **`@property` unsupported** — transform, translate, rotate, scale utilities don't animate smoothly because the custom properties aren't interpolatable without `@property`.
-- **Cascade layers unsupported** — the order of Maz-UI styles vs app styles becomes non-deterministic, so resets and utilities can override app styles (or vice versa) unpredictably.
+- **`color-mix` unsupported** - any utility that goes through an alpha modifier (`bg-primary/50`, the custom overlay colors in MazDialog / MazBackdrop) falls back to the base color with no transparency. Visual regression but not a crash.
+- **`@property` unsupported** - transform, translate, rotate, scale utilities don't animate smoothly because the custom properties aren't interpolatable without `@property`.
+- **Cascade layers unsupported** - the order of Maz-UI styles vs app styles becomes non-deterministic, so resets and utilities can override app styles (or vice versa) unpredictably.
 
 The safe recommendation is: detect at app boot and show an "unsupported browser" screen if you can't guarantee the minimum matrix.
 
 ## See also
 
-- [Migration v4 → v5](./migration-v5.md) — the full upgrade guide
-- [Tailwind v4 browser support](https://tailwindcss.com/blog/tailwindcss-v4#browser-support) — upstream notes
-- [Tailwind CSS integration](./tailwind.md) — how the design system plugs into your own Tailwind
+- [Migration v4 → v5](./migration-v5.md) - the full upgrade guide
+- [Tailwind v4 browser support](https://tailwindcss.com/blog/tailwindcss-v4#browser-support) - upstream notes
+- [Tailwind CSS integration](./tailwind.md) - how the design system plugs into your own Tailwind

package/docs/{src/guide → guide}/getting-started.md

@@ -1,81 +1,39 @@
 ---
-title: Getting Started
-description: Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library
-head:
-  - - meta
-    - name: keywords
-      content: vue ui library, vue components, nuxt ui, maz-ui installation, components, nuxt, vue, themes, translations, icons, mcp, maz-ui
+title: "Getting Started"
+description: "Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library"
+package: "maz-ui"
+url: "https://maz-ui.com/guide/getting-started"
 ---
 
-# {{ $frontmatter.title }}
+# Getting Started
 
-{{ $frontmatter.description }}
+> Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library
 
-::: tip **Why Maz-UI?**
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/getting-started
+
+**Tip: **Why Maz-UI?****
 
 - 🌱 **Tree-shaking** - Import only what you need
 - 🛠️ **TypeScript-first** - Full type safety out of the box
 - 🚀 **Performance** - Tree-shaking benefits and maximum optimization
-- 🎨 **Theming system** - Customizable themes and dark mode support (5 presets available) - [@maz-ui/themes](./themes.md)
+- 🎨 **Theming system** - Customizable themes and dark mode support (5 presets available) - [@maz-ui/themes](../ecosystem/themes.md)
 - 💨 **Optional Tailwind bridge** - Already have a Tailwind v4 setup? Expose your active maz-ui theme tokens (colors, radius, breakpoints, custom utilities) to your own Tailwind config - [Tailwind integration](./tailwind.md)
-- 🌐 **Internationalization** - Locale management and tree-shakable imports - [@maz-ui/translations](./translations.md)
-- 🎨 **Icon library** - Comprehensive collection of SVG icons designed for performance and flexibility (860+ icons) - [@maz-ui/icons](./icons.md)
-- 🧰 **Nuxt module** - Effortless Maz-UI integration with auto-imports - [@maz-ui/nuxt](./nuxt.md)
-- 🤖 **MCP** - Connect your AI agents to the documentation - [@maz-ui/mcp](./mcp.md)
+- 🌐 **Internationalization** - Locale management and tree-shakable imports - [@maz-ui/translations](../ecosystem/translations.md)
+- 🎨 **Icon library** - Comprehensive collection of SVG icons designed for performance and flexibility (860+ icons) - [@maz-ui/icons](../ecosystem/icons/index.md)
+- 🧰 **Nuxt module** - Effortless Maz-UI integration with auto-imports - [@maz-ui/nuxt](../ecosystem/nuxt.md)
+- 🤖 **AI agents** - Make Claude Code, Cursor, Copilot and Codex use maz-ui instead of re-implementing it - [AI agents](./ai-agents.md), [@maz-ui/mcp](../ecosystem/mcp.md)
 
-:::
+**Tip: Migrating from v4?**
 
-::: tip Migrating from v4?
 Run `npx @maz-ui/upgrade ./` to handle the mechanical part of the migration (CSS subpath imports, prop renames, CSS var renames, Nuxt config keys, custom preset color keys, and `package.json` version bumps). See the [v5 migration guide](./migration-v5.md) for the rest.
-:::
 
 ## Guides
 
 Start by choosing your framework:
 
-<div class="maz:flex maz:gap-4 maz:w-full maz:flex-col maz:tab-m:flex-row vp-raw">
-  <MazCard
-    href="/guide/vue"
-    class="maz:flex-1"
-    :gallery="{
-      images: ['/vue.png'],
-      height: 200,
-      width: '100%',
-    }"
-  >
-    <template #content-title>
-      <h3>
-        Vue Users Guide
-      </h3>
-    </template>
-    <template #footer>
-      <MazBtn color="contrast" href="/guide/vue">
-        Vue guide
-      </MazBtn>
-    </template>
-  </MazCard>
-  <MazCard
-    href="/ecosystem/nuxt"
-    class="maz:flex-1"
-    content-title="Nuxt Users Guide"
-    :gallery="{
-      images: ['/nuxt.png'],
-      height: 200,
-      width: '100%',
-    }"
-  >
-    <template #content-title>
-      <h3>
-        Nuxt Users Guide
-      </h3>
-    </template>
-    <template #footer>
-      <MazBtn color="contrast" href="/ecosystem/nuxt">
-        Nuxt guide
-      </MazBtn>
-    </template>
-  </MazCard>
-</div>
+- [Install maz-ui with Vue](./vue.md)
+- [Install maz-ui with Nuxt](../ecosystem/nuxt.md)
 
 ## Ecosystem Packages
 
@@ -94,13 +52,13 @@ npm install @maz-ui/themes
 **Features:**
 
 - 🎨 Native `light-dark()` + `color-scheme` + OKLCh scales via relative color syntax
-- 🌓 Smart dark mode — `class` or `media` strategies, with smooth transitions on toggle
+- 🌓 Smart dark mode - `class` or `media` strategies, with smooth transitions on toggle
 - ✨ Optional animated theme switch via View Transitions (`setColorMode(..., { animate: true })`)
 - ⚡ `runtime` and `buildtime` rendering strategies
 - 🍪 Active preset persisted across reloads (opt-out)
 - 🛡️ Full TypeScript support
 
-[→ View Theme Documentation](./themes.md)
+[→ View Theme Documentation](../ecosystem/themes.md)
 
 ---
 
@@ -121,7 +79,7 @@ npm install @maz-ui/translations
 - 📦 Tree-shakable imports
 - 🛠️ TypeScript support
 
-[→ View Translations Documentation](./translations.md)
+[→ View Translations Documentation](../ecosystem/translations.md)
 
 ---
 
@@ -143,19 +101,26 @@ npm install @maz-ui/icons
 - Multiple sizes and variants
 - Full TypeScript definitions
 
-[→ Browse Icon Library](./icons.md)
+[→ Browse Icon Library](../ecosystem/icons/index.md)
 
 ---
 
 ### @maz-ui/mcp
 
-**Maz-UI MCP server to connect your IA agents to the documentation**
+**Make your AI coding agents use maz-ui**
+
+```bash
+npx @maz-ui/mcp init
+```
 
 **Features:**
 
-- Connect your IA agents to the documentation
+- Rules for Claude Code, Cursor, GitHub Copilot, Codex... without touching your own instructions
+- MCP server: search by need, component APIs, icons, Tailwind theme tokens, docs of the installed version
+- Code review against the installed maz-ui, in the agent loop and in CI
+- Claude Code plugin and automatic setup with the Nuxt module
 
-[→ View MCP Documentation](./mcp.md)
+[→ View AI agents guide](./ai-agents.md)
 
 ## Performance Optimizations
 
@@ -219,78 +184,8 @@ import { debounce } from '@maz-ui/utils/helpers/debounce'
 import { formatCurrency } from '@maz-ui/utils/helpers/formatCurrency'
 ```
 
-::: tip Maximum Optimization
+**Tip: Maximum Optimization**
+
 **Direct imports** (e.g., `import MazBtn from 'maz-ui/components/MazBtn'`) are the most optimized approach as they bypass index files completely. This ensures the smallest possible bundle size and fastest build times.
-:::
 
 ## Next Steps
-
-<div class="next-steps">
-
-### Explore Components
-
-Browse the [component library](./../components/maz-btn.md) with live examples and API documentation.
-
-### Customize Themes
-
-Learn about [theming and customization](./themes.md) to match your brand.
-
-### Internationalization
-
-Learn about [internationalization](./translations.md) to support multiple languages.
-
-### Lazy Loading with MazUiProvider
-
-Use [`MazUiProvider`](./maz-ui-provider.md) to defer Maz-UI initialization to lazy-loaded pages for zero entry-bundle overhead.
-
-### Get Help
-
-Browse [GitHub discussions](https://github.com/LouisMazel/maz-ui/discussions) or open an issue on [GitHub](https://github.com/LouisMazel/maz-ui/issues).
-
-</div>
-
-<style scoped>
-@reference "../../.vitepress/theme/main.css";
-.hero-section {
-  @apply maz:rounded-md maz:p-8 maz:my-12 maz:from-primary-400 maz:to-secondary-700 maz:bg-linear-to-br;
-}
-
-.features-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-  gap: 2rem;
-  margin: 2rem 0;
-
-  h3 {
-    margin-top: 0;
-  }
-  ul {
-    margin-top: 0;
-  }
-}
-
-.next-steps {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-  gap: 1rem;
-  margin: 2rem 0;
-
-  h3 {
-    margin-top: 0;
-  }
-  p {
-    margin-top: 0;
-  }
-}
-
-@media (max-width: 768px) {
-  .hero-actions {
-    flex-direction: column;
-    align-items: center;
-  }
-
-  .hero-btn {
-    width: 200px;
-  }
-}
-</style>

package/docs/{src/guide → guide}/global-defaults.md

@@ -1,15 +1,16 @@
 ---
-title: Global component defaults
-description: Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module
-head:
-  - - meta
-    - name: keywords
-      content: maz-ui defaults, global props, default props, rounded size, component configuration, vue, nuxt
+title: "Global component defaults"
+description: "Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module"
+package: "maz-ui"
+url: "https://maz-ui.com/guide/global-defaults"
 ---
 
-# {{ $frontmatter.title }}
+# Global component defaults
 
-{{ $frontmatter.description }}
+> Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/global-defaults
 
 Instead of repeating the same prop on every instance (`<MazBtn rounded-size="lg" />` everywhere), you can set a default once and let every component pick it up.
 
@@ -93,10 +94,10 @@ defaults: {
 | `bordered`, `elevation`, `padding`, `transparent`, `overflowHidden` | `boolean` | `MazContainer` |
 | `bordered`, `elevation`, `padding`, `radius`, `scale`, `overflowHidden` | `boolean` | `MazCard` |
 
-::: tip Note
+**Tip: Note**
+
 Components whose `size` is a free CSS length (`MazSizeUnit`, e.g. `MazSpinner`, `MazAvatar`, `MazDrawer`, `MazSlider`, `MazCircularProgressBar`, `MazFullscreenLoader`) do not take the global `size` token - the value would not be valid for them. `MazAlert` and `MazTimeline` keep their own wider `roundedSize` scale; a `defaults.global.roundedSize` value still applies to them, and their extra steps (`2xl`, `3xl`) are reachable through their per-component entry.
-:::
 
 ## Relation to the theme system
 
-This is **not** a duplicate of [`@maz-ui/themes`](/ecosystem/themes). The theme system controls *what a token looks like* (the CSS value of `rounded-md`, `shadow-elevation`, colors…). Global defaults control *which prop value a component selects by default* (whether `MazBtn` defaults to `roundedSize="lg"`). Both work together: the theme defines what `lg` renders as, the defaults decide which step a component uses.
+This is **not** a duplicate of [`@maz-ui/themes`](../ecosystem/themes.md). The theme system controls *what a token looks like* (the CSS value of `rounded-md`, `shadow-elevation`, colors…). Global defaults control *which prop value a component selects by default* (whether `MazBtn` defaults to `roundedSize="lg"`). Both work together: the theme defines what `lg` renders as, the defaults decide which step a component uses.