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

package/docs/ecosystem/mcp.md

@@ -0,0 +1,165 @@
+---
+title: "MCP server"
+description: "The maz-ui MCP server gives AI coding agents the version-matched knowledge of maz-ui and its ecosystem - search by need, exact component APIs, icons, Tailwind theme tokens, setup guides and code review."
+package: "@maz-ui/mcp"
+url: "https://maz-ui.com/ecosystem/mcp"
+---
+
+# MCP server
+
+> The maz-ui MCP server gives AI coding agents the version-matched knowledge of maz-ui and its ecosystem - search by need, exact component APIs, icons, Tailwind theme tokens, setup guides and code review.
+
+- Package: `@maz-ui/mcp`
+- Web: https://maz-ui.com/ecosystem/mcp
+
+**Tip: Start with `npx @maz-ui/mcp init`**
+
+It registers the server and writes the maz-ui rules for the agents of your project. See [AI agents](../guide/ai-agents.md) for the complete picture (rules, version-matched docs, Claude Code plugin, code review in CI).
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `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` | 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 |
+| `review_code` | Review files or code against the installed maz-ui: unknown props or values, unknown icons, native elements and libraries maz-ui already covers, default Tailwind palette, `maz:` prefix... |
+
+Every tool is read-only. The server also gives agents instructions on when to use them, so they look maz-ui up before writing code.
+
+### Prompts
+
+| Prompt | Purpose |
+| --- | --- |
+| `build` | Implement a feature with the maz-ui ecosystem (search, APIs, icons, tokens, review) |
+| `audit` | Find and fix what re-implements maz-ui in existing files |
+| `setup` | Install and configure maz-ui in the project |
+
+In Claude Code, they are available as `/maz-ui:build`, `/maz-ui:audit` and `/maz-ui:setup`.
+
+## Version-matched docs
+
+The server serves the documentation of the **maz-ui version installed in your project** (`node_modules/maz-ui/docs`), found from the directory it is started in (monorepos: the root, then `apps/*` and `packages/*`). Without maz-ui installed, it serves the docs bundled with `@maz-ui/mcp` (latest release).
+
+To force a folder, pass `--docs <dir>` or set `MAZ_UI_DOCS_DIR`.
+
+## Configuration
+
+`npx @maz-ui/mcp init` writes the configuration of Claude Code, Cursor and VS Code for you. To configure an agent by hand, start the server with `npx -y @maz-ui/mcp@latest`.
+
+### Claude Code
+
+```bash
+# for every project, without any file in them
+claude mcp add maz-ui --scope user -- npx -y @maz-ui/mcp@latest
+# or for this project only (written in .mcp.json, shared with your team)
+claude mcp add maz-ui --scope project -- npx -y @maz-ui/mcp@latest
+```
+
+Or in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "maz-ui": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@maz-ui/mcp@latest"]
+    }
+  }
+}
+```
+
+The [Claude Code plugin](../guide/ai-agents.md#claude-code-plugin) includes the server.
+
+### Cursor
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "maz-ui": {
+      "command": "npx",
+      "args": ["-y", "@maz-ui/mcp@latest"]
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "maz-ui": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@maz-ui/mcp@latest"]
+    }
+  }
+}
+```
+
+### Codex
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.maz-ui]
+command = "npx"
+args = ["-y", "@maz-ui/mcp@latest"]
+```
+
+### Windsurf, Claude Desktop, Cline, Zed...
+
+Add the same `command` and `args` to the MCP configuration of the client (`mcpServers` key):
+
+```json
+{
+  "mcpServers": {
+    "maz-ui": {
+      "command": "npx",
+      "args": ["-y", "@maz-ui/mcp@latest"]
+    }
+  }
+}
+```
+
+## Command line
+
+The package is also a CLI:
+
+```bash
+npx @maz-ui/mcp                   # start the MCP server (stdio)
+npx @maz-ui/mcp init              # configure the AI agents of the project
+npx @maz-ui/mcp review <paths...> # review files against maz-ui (CI)
+npx @maz-ui/mcp search <query>    # search the docs from the terminal
+npx @maz-ui/mcp --help
+```
+
+See [Code review in CI](../guide/ai-agents.md#code-review-in-ci) for the review options and rules.
+
+## Programmatic API
+
+```ts
+import { createMazUiMcpServer, loadKnowledge, reviewCode } from '@maz-ui/mcp'
+
+const knowledge = loadKnowledge({ cwd: process.cwd() })
+const findings = reviewCode('<template><MazBtn color="red" /></template>', {
+  knowledge,
+  filename: 'Example.vue',
+})
+```
+
+## Debugging
+
+```bash
+npx @modelcontextprotocol/inspector npx -y @maz-ui/mcp@latest
+```

package/docs/{src/ecosystem → ecosystem}/node/exec-promise.md

@@ -1,11 +1,17 @@
 ---
-title: execPromise
-description: Promise-based wrapper around `child_process.exec` with structured stdout/stderr/error logging, package-scoped prefixes, and per-call log silencing.
+title: "execPromise"
+description: "Promise-based wrapper around `child_process.exec` with structured stdout/stderr/error logging, package-scoped prefixes, and per-call log silencing."
+package: "@maz-ui/node"
+url: "https://maz-ui.com/ecosystem/node/exec-promise"
 ---
 
-# {{ $frontmatter.title }}
+# execPromise
 
-{{ $frontmatter.description }}
+> Promise-based wrapper around `child_process.exec` with structured stdout/stderr/error logging, package-scoped prefixes, and per-call log silencing.
+
+- Package: `@maz-ui/node`
+- Import: `import { execPromise } from '@maz-ui/node'`
+- Web: https://maz-ui.com/ecosystem/node/exec-promise
 
 ## Usage
 
@@ -46,7 +52,7 @@ interface ExecPromiseOptions {
 | Option        | Type          | Default     | Description                                                                       |
 | ------------- | ------------- | ----------- | --------------------------------------------------------------------------------- |
 | `logger`      | `CustomLogger` | built-in    | Custom logger (must expose `log`, `error`, `info`, `warn`, `debug` methods).      |
-| `packageName` | `string`      | —           | Prepended to logs as `[name]: ` — useful when many commands share a logger.       |
+| `packageName` | `string`      | - | Prepended to logs as `[name]: ` - useful when many commands share a logger.       |
 | `noSuccess`   | `boolean`     | `false`     | Skip the `info` line printed when the command finishes successfully.              |
 | `noStdout`    | `boolean`     | `false`     | Don't pipe stdout to the logger (still returned in the promise result).           |
 | `noStderr`    | `boolean`     | `false`     | Don't pipe stderr to the logger (still returned in the promise result).           |
@@ -84,4 +90,4 @@ await execPromise('npm test', {
 ## Notes
 
 - `execPromise` uses Node's `child_process.exec`, which buffers all output in memory. For commands that produce very large streams, prefer `child_process.spawn` directly.
-- `stdout`/`stderr` are still returned in the promise result even when `noStdout`/`noStderr` are set — the flags only affect logging.
+- `stdout`/`stderr` are still returned in the promise result even when `noStdout`/`noStderr` are set - the flags only affect logging.

package/docs/ecosystem/node/index.md

@@ -0,0 +1,53 @@
+---
+title: "@maz-ui/node"
+description: "Lightweight Node.js utilities - promise-based shell execution, an opinionated consola-backed logger, and a banner printer for CLIs."
+package: "@maz-ui/node"
+url: "https://maz-ui.com/ecosystem/node/"
+---
+
+# @maz-ui/node
+
+> Lightweight Node.js utilities - promise-based shell execution, an opinionated consola-backed logger, and a banner printer for CLIs.
+
+- Package: `@maz-ui/node`
+- Web: https://maz-ui.com/ecosystem/node/
+
+`@maz-ui/node` powers the CLIs and build scripts inside the maz-ui ecosystem. It's intentionally tiny: an `exec` wrapper that returns a real `Promise`, a colourful logger built on [consola](https://github.com/unjs/consola), and a banner helper using [figlet](https://github.com/patorjk/figlet.js).
+
+## Installation
+
+```bash [pnpm]
+pnpm add @maz-ui/node
+```
+
+```bash [npm]
+npm install @maz-ui/node
+```
+
+```bash [yarn]
+yarn add @maz-ui/node
+```
+
+## Basic usage
+
+```ts
+import { execPromise, logger, printBanner } from '@maz-ui/node'
+
+printBanner({ name: 'my-cli', version: '1.0.0' })
+
+logger.info('Running tests…')
+await execPromise('npm test', { packageName: 'tests' })
+logger.success('Done')
+```
+
+## What's inside
+
+- [`execPromise`](./exec-promise.md) - Promise-based `child_process.exec` with structured logging.
+- [`logger` / `createLogger`](./logger.md) - consola-backed logger with semantic log levels and helpers (`box`, `divider`, `brand`, …).
+- [`printBanner`](./print-banner.md) - ASCII-art banner printer (figlet) with versioning, dividers and clearing.
+- [`setupAgents`](./setup-agents.md) - Configure the AI coding agents of a project for maz-ui (rules and MCP server), as `npx @maz-ui/mcp init` does.
+
+## Requirements
+
+- Node.js >= 22.12.0
+- ESM only - published as `"type": "module"`.

package/docs/{src/ecosystem → ecosystem}/node/logger.md

@@ -1,11 +1,17 @@
 ---
-title: logger / createLogger
-description: Opinionated [consola](https://github.com/unjs/consola)-backed logger with semantic levels, status helpers (`success`, `ready`, `fail`), and formatting helpers (`box`, `divider`, `brand`).
+title: "logger / createLogger"
+description: "Opinionated [consola](https://github.com/unjs/consola)-backed logger with semantic levels, status helpers (`success`, `ready`, `fail`), and formatting helpers (`box`, `divider`, `brand`)."
+package: "@maz-ui/node"
+url: "https://maz-ui.com/ecosystem/node/logger"
 ---
 
-# {{ $frontmatter.title }}
+# logger / createLogger
 
-{{ $frontmatter.description }}
+> Opinionated [consola](https://github.com/unjs/consola)-backed logger with semantic levels, status helpers (`success`, `ready`, `fail`), and formatting helpers (`box`, `divider`, `brand`).
+
+- Package: `@maz-ui/node`
+- Import: `import { logger } from '@maz-ui/node'`
+- Web: https://maz-ui.com/ecosystem/node/logger
 
 The default `logger` is a singleton ready to use; `createLogger` builds a fresh instance with its own level and reporters.
 
@@ -44,7 +50,7 @@ function createLogger(options?: LoggerOptions): Logger
 type LoggerOptions = Partial<ConsolaOptions>
 ```
 
-`LoggerOptions` is forwarded directly to [consola's `createConsola()`](https://github.com/unjs/consola#instance-options) — see consola docs for every accepted field (tag, reporters, formatOptions, …).
+`LoggerOptions` is forwarded directly to [consola's `createConsola()`](https://github.com/unjs/consola#instance-options) - see consola docs for every accepted field (tag, reporters, formatOptions, …).
 
 ## API
 
@@ -113,7 +119,7 @@ logger.error('No longer printed')
 | Method       | Output                                                              |
 | ------------ | ------------------------------------------------------------------- |
 | `box(msg)`   | Renders the message inside a bordered box.                          |
-| `brand(msg)` | Prints in bright blue — used by `printBanner`.                      |
+| `brand(msg)` | Prints in bright blue - used by `printBanner`.                      |
 | `divider(c)` | Prints a separator line that adapts to the terminal width.          |
 | `eot()`      | Prints a blank line (end-of-transmission marker).                   |
 | `break(n)`   | Prints `n` blank lines (default: 1).                                |

package/docs/{src/ecosystem → ecosystem}/node/print-banner.md

@@ -1,11 +1,19 @@
 ---
-title: printBanner
-description: Print an ASCII-art banner via figlet with optional version, dividers and clearing — handy for CLI entry points.
+title: "printBanner"
+description: "Print an ASCII-art banner via figlet with optional version, dividers and clearing - handy for CLI entry points."
+package: "@maz-ui/node"
+url: "https://maz-ui.com/ecosystem/node/print-banner"
 ---
 
-# {{ $frontmatter.title }}
+# printBanner
 
-Print an ASCII-art banner (via [figlet](https://github.com/patorjk/figlet.js)) with optional version, dividers and clearing — handy for CLI entry points.
+> Print an ASCII-art banner via figlet with optional version, dividers and clearing - handy for CLI entry points.
+
+- Package: `@maz-ui/node`
+- Import: `import { printBanner } from '@maz-ui/node'`
+- Web: https://maz-ui.com/ecosystem/node/print-banner
+
+Print an ASCII-art banner (via [figlet](https://github.com/patorjk/figlet.js)) with optional version, dividers and clearing - handy for CLI entry points.
 
 ## Usage
 

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

@@ -0,0 +1,102 @@
+---
+title: "setupAgents"
+description: "Configure the AI coding agents of a project for maz-ui - version-matched rules for Claude Code and AGENTS.md, and the maz-ui MCP server in the agent configs - without touching the files you own."
+package: "@maz-ui/node"
+url: "https://maz-ui.com/ecosystem/node/setup-agents"
+---
+
+# setupAgents
+
+> Configure the AI coding agents of a project for maz-ui - version-matched rules for Claude Code and AGENTS.md, and the maz-ui MCP server in the agent configs - without touching the files you own.
+
+- Package: `@maz-ui/node`
+- Import: `import { setupAgents } from '@maz-ui/node'`
+- Web: https://maz-ui.com/ecosystem/node/setup-agents
+
+`setupAgents` is the engine of [`npx @maz-ui/mcp init`](../mcp.md) and of the `agents` option of the [Nuxt module](../nuxt.md#ai-agents). Use it directly to integrate the setup in your own tooling (a project generator, a postinstall script...). See the [AI agents guide](../../guide/ai-agents.md) for what it brings to your agents.
+
+## Quick start
+
+```ts
+import { setupAgents } from '@maz-ui/node'
+
+const { changes } = setupAgents({ rootDir: process.cwd() })
+
+for (const change of changes) {
+  console.log(change.action, change.file)
+}
+```
+
+## What it writes
+
+The content comes from the `docs/agents` folder of the `maz-ui` package installed in `rootDir`, so the rules always match the installed version.
+
+| Target | Files |
+| --- | --- |
+| `claude` | `.claude/rules/maz-ui.md` (a Claude Code rule, loaded on top of your `CLAUDE.md`) and the `maz-ui` server in `.mcp.json` |
+| `agents-md` | A section between `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->` in `AGENTS.md` (Codex, Cursor, Copilot, Windsurf, Zed...) |
+| `cursor` | The `maz-ui` server in `.cursor/mcp.json` |
+| `vscode` | The `maz-ui` server in `.vscode/mcp.json` (GitHub Copilot) |
+
+Guarantees:
+
+- A file it did not generate is never overwritten (it is reported as `skip`).
+- 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.
+- 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`.
+
+## Options
+
+```ts
+import { setupAgents } from '@maz-ui/node'
+
+setupAgents({
+  rootDir: process.cwd(),
+  // Agents to configure, default: the agents detected in the project
+  targets: ['claude', 'agents-md', 'cursor', 'vscode'],
+  // Write the rules (Claude Code rule, AGENTS.md section), default: true
+  rules: true,
+  // Register the maz-ui MCP server, default: true
+  mcp: true,
+  // Compute the changes without writing anything
+  dryRun: false,
+  // Remove everything setupAgents added
+  remove: false,
+  // Folder of the maz-ui agent docs, default: node_modules/maz-ui/docs
+  docsDir: undefined,
+  // Command of the MCP server, default: npx -y @maz-ui/mcp@latest
+  mcpServer: { command: 'npx', args: ['-y', '@maz-ui/mcp@latest'] },
+})
+```
+
+## Result
+
+```ts
+import { setupAgents } from '@maz-ui/node'
+
+const result = setupAgents({ rootDir: process.cwd(), dryRun: true })
+
+result.version // version of the installed maz-ui
+result.targets // configured agents
+result.changes // [{ file: '.mcp.json', action: 'create' | 'update' | 'remove' | 'unchanged' | 'skip', reason?: string }]
+```
+
+## Detecting the agents
+
+```ts
+import { detectAgentTargets } from '@maz-ui/node'
+
+detectAgentTargets(process.cwd()) // ['claude', 'agents-md']
+```
+
+| Target | Detected from |
+| --- | --- |
+| `claude` | `.claude/`, `CLAUDE.md`, `CLAUDE.local.md`, `.mcp.json` |
+| `cursor` | `.cursor/`, `.cursorrules` |
+| `vscode` | `.vscode/mcp.json`, `.github/copilot-instructions.md`, `.github/instructions/` |
+| `agents-md` | `AGENTS.md`, `GEMINI.md`, `.codex/`, `.windsurf/`, `.devin/`, `.windsurfrules`, or any of `cursor` and `vscode` |
+
+## Errors
+
+`setupAgents` throws when the rules are requested and `maz-ui` is not installed in `rootDir` (or its parent folders), or when the installed version does not ship the agent docs: upgrade maz-ui to the latest version. With `rules: false`, only the MCP server is registered and the docs are not needed.

package/docs/{src/ecosystem → ecosystem}/nuxt.md

@@ -1,20 +1,25 @@
 ---
-title: Install maz-ui with Nuxt
-description: The ultimate Nuxt module for Maz-UI - zero-config setup with auto-imports, theming, internationalization and powerful features out of the box
+title: "Install maz-ui with Nuxt"
+description: "The ultimate Nuxt module for Maz-UI - zero-config setup with auto-imports, theming, internationalization and powerful features out of the box"
+package: "@maz-ui/nuxt"
+url: "https://maz-ui.com/ecosystem/nuxt"
 ---
 
-# {{ $frontmatter.title }}
+# Install maz-ui with Nuxt
+
+> The ultimate Nuxt module for Maz-UI - zero-config setup with auto-imports, theming, internationalization and powerful features out of the box
+
+- Package: `@maz-ui/nuxt`
+- Web: https://maz-ui.com/ecosystem/nuxt
 
 **Maz-UI Nuxt Module** provides zero-configuration setup, intelligent auto-imports, powerful theming capabilities and internationalization.
 
-::: tip Model Context Protocol (MCP)
+**Tip: Model Context Protocol (MCP)**
 
-A MCP server is available to connect your IA agents to the documentation and implement Maz-UI easily.
+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.
 
 Check out the documentation of [@maz-ui/mcp](./mcp.md)
 
-:::
-
 ## Why Choose Maz-UI for Nuxt?
 
 - **Zero Configuration** - Works out of the box with sensible defaults
@@ -26,10 +31,6 @@ Check out the documentation of [@maz-ui/mcp](./mcp.md)
 
 ## Installation
 
-<NpmBadge package="@maz-ui/nuxt" />
-
-::: code-group
-
 ```bash [pnpm]
 pnpm add @maz-ui/nuxt
 ```
@@ -46,8 +47,6 @@ yarn add @maz-ui/nuxt
 pnpx nuxt@latest module add @maz-ui/nuxt
 ```
 
-:::
-
 Add the module to your `nuxt.config.ts`:
 
 ```ts
@@ -75,7 +74,7 @@ const { toggleDarkMode, isDark } = useTheme()
 </script>
 
 <template>
-  <div class="maz:bg-surface p-8 maz:text-foreground">
+  <div class="bg-surface p-8 text-foreground">
     <!-- Components are auto-imported -->
     <MazBtn color="primary" @click="start">
       Start timer ({{ remainingTime }}ms)
@@ -190,6 +189,9 @@ export default defineNuxtConfig({
       vFullscreenImg: true,
       vZoomImg: true,
     },
+
+    // AI coding agents (default: { rules: false, mcp: true }, false to disable)
+    agents: { rules: true, mcp: true },
   }
 })
 ```
@@ -268,7 +270,7 @@ const theme = {
   darkClass: 'dark',
 
   // Class added to <html> when colorMode === 'light' (default: 'light')
-  // Mirror of darkClass — used to force `color-scheme: only light`.
+  // Mirror of darkClass - used to force `color-scheme: only light`.
   lightClass: 'light',
 
   // Persist the active preset name in the `maz-preset` cookie so the
@@ -295,7 +297,7 @@ const defaults = {
 }
 ```
 
-See the [Global component defaults guide](/guide/global-defaults) for the full list of globalizable props.
+See the [Global component defaults guide](../guide/global-defaults.md) for the full list of globalizable props.
 
 ### Country Flags
 
@@ -312,7 +314,7 @@ export default defineNuxtConfig({
 })
 ```
 
-Nothing is added to your build unless `flags` is `'local'`. See [MazSelectCountry](/components/maz-select-country#flags-source) for the details (Content Security Policy, PWA precache).
+Nothing is added to your build unless `flags` is `'local'`. See [MazSelectCountry](../components/maz-select-country.md#flags-source) for the details (Content Security Policy, PWA precache).
 
 ## Theme Strategies Explained
 
@@ -432,6 +434,35 @@ const directives = {
 }
 ```
 
+### AI Agents
+
+Connect your AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex, Windsurf...) to maz-ui, version-matched with the installed maz-ui, so they use its components, composables, icons, helpers and theme tokens instead of re-implementing them:
+
+```ts
+const agents = {
+  // Register the maz-ui MCP server in .mcp.json, .cursor/mcp.json, .vscode/mcp.json (default: true)
+  // 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)
+  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, 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
 
 ### Custom Theme Creation
@@ -488,9 +519,9 @@ export default defineNuxtConfig({
 })
 ```
 
-::: tip Subtree Overrides with MazUiProvider
+**Tip: Subtree Overrides with MazUiProvider**
+
 You can use [`MazUiProvider`](../guide/maz-ui-provider.md) within a Nuxt app to override theme or translations in a specific subtree, while the module handles global defaults.
-:::
 
 ## Troubleshooting