maz-ui 5.0.0 → 5.1.0-beta.0

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` | 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/ecosystem/node/exec-promise.md

@@ -0,0 +1,93 @@
+---
+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"
+---
+
+# execPromise
+
+> 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
+
+```ts
+import { execPromise, logger } from '@maz-ui/node'
+
+try {
+  const { stdout } = await execPromise('npm --version')
+  logger.log('npm version:', stdout.trim())
+}
+catch (error) {
+  logger.error('Command failed', error)
+}
+```
+
+## API
+
+```ts
+function execPromise(
+  command: string,
+  options?: ExecPromiseOptions,
+): Promise<{ stdout: string, stderr: string }>
+
+interface ExecPromiseOptions {
+  logger?: CustomLogger
+  packageName?: string
+  noSuccess?: boolean
+  noStdout?: boolean
+  noStderr?: boolean
+  noError?: boolean
+  logLevel?: LogLevel
+  cwd?: string
+}
+```
+
+### Options
+
+| 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.       |
+| `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).           |
+| `noError`     | `boolean`     | `false`     | Don't log errors before rejecting.                                                |
+| `logLevel`    | `LogLevel`    | unchanged   | Temporarily sets the default logger's level for this call.                        |
+| `cwd`         | `string`      | `process.cwd()` | Working directory for the command.                                                |
+
+The returned promise **resolves** with `{ stdout, stderr }` on success and **rejects** with the exec error on failure.
+
+## Examples
+
+Run a build silently, only reporting success/failure:
+
+```ts
+await execPromise('npm run build', {
+  packageName: 'build',
+  noStdout: true,
+  noStderr: true,
+})
+```
+
+Use a custom logger for an isolated subsystem:
+
+```ts
+import { createLogger, execPromise } from '@maz-ui/node'
+
+const ciLogger = createLogger({ level: 2 })
+
+await execPromise('npm test', {
+  logger: ciLogger,
+  packageName: 'tests',
+})
+```
+
+## 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.

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/ecosystem/node/logger.md

@@ -0,0 +1,152 @@
+---
+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"
+---
+
+# logger / createLogger
+
+> 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.
+
+## Quick start
+
+```ts
+import { logger } from '@maz-ui/node'
+
+logger.info('Build started')
+logger.success('All checks passed')
+logger.warn('Deprecated flag used')
+logger.error('Build failed', errorObject)
+```
+
+## Default instance
+
+```ts
+import { logger } from '@maz-ui/node'
+```
+
+A pre-configured `Logger` with `level: 'default'` (numeric 3). Suitable for most scripts.
+
+## Custom instances
+
+```ts
+import { createLogger } from '@maz-ui/node'
+
+const dev = createLogger({ level: 4 }) // debug
+const ci = createLogger({ level: 2 }) // normal
+const silent = createLogger({ level: Number.NEGATIVE_INFINITY })
+```
+
+```ts
+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, …).
+
+## API
+
+```ts
+interface Logger {
+  // Core
+  log(message, ...args): void
+  info(message, ...args): void
+  warn(message, ...args): void
+  error(message, ...args): void
+  debug(message, ...args): void
+  trace(message, ...args): void
+  verbose(message, ...args): void
+  silent(message, ...args): void
+  fatal(message, ...args): void
+
+  // Status
+  start(message, ...args): void
+  ready(message, ...args): void
+  success(message, ...args): void
+  fail(message, ...args): void
+
+  // Formatting
+  box(message, ...args): void
+  brand(message: string): void
+  divider(character?: string): void
+  eot(): void
+  break(count?: number): void
+  clear(): void
+
+  // Reporters
+  addReporter(reporter: ConsolaReporter): void
+  removeReporter(reporter: ConsolaReporter): void
+
+  // Level control
+  setLevel(level: LogLevel): void
+  getLevel(): number
+}
+```
+
+### Log levels
+
+`setLevel()` accepts a semantic name. Anything below the active level is suppressed.
+
+| Level       | Numeric           | Description                  |
+| ----------- | ----------------- | ---------------------------- |
+| `'silent'`  | `-Infinity`       | No logs displayed            |
+| `'error'`   | `0`               | Fatal and error only         |
+| `'warning'` | `1`               | Warnings and above           |
+| `'normal'`  | `2`               | Normal logs and above        |
+| `'default'` | `3` (default)     | Informational logs           |
+| `'debug'`   | `4`               | Debug logs and above         |
+| `'trace'`   | `5`               | All logs including trace     |
+| `'verbose'` | `Infinity`        | Maximum verbosity            |
+
+```ts
+logger.setLevel('debug')
+logger.debug('Now visible')
+
+logger.setLevel('silent')
+logger.error('No longer printed')
+```
+
+### Formatting helpers
+
+| Method       | Output                                                              |
+| ------------ | ------------------------------------------------------------------- |
+| `box(msg)`   | Renders the message inside a bordered box.                          |
+| `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).                                |
+
+## Examples
+
+Build script with mixed levels:
+
+```ts
+import { createLogger, execPromise } from '@maz-ui/node'
+
+const log = createLogger({ level: 3 })
+
+log.box('🚀 Build starting')
+log.divider()
+
+await execPromise('npm install', { logger: log, packageName: 'setup' })
+log.ready('Dependencies installed')
+
+await execPromise('npm run build', { logger: log, packageName: 'build' })
+log.success('Build complete')
+```
+
+Switch verbosity from an env flag:
+
+```ts
+const log = createLogger({
+  level: process.env.CI ? 2 : 4,
+})
+```

package/docs/ecosystem/node/print-banner.md

@@ -0,0 +1,101 @@
+---
+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"
+---
+
+# printBanner
+
+> 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
+
+```ts
+import { printBanner } from '@maz-ui/node'
+
+printBanner({
+  name: 'maz-cli',
+  version: 'v1.0.0',
+})
+```
+
+Renders:
+
+```text
+███╗   ███╗ █████╗ ███████╗     ██████╗██╗     ██╗
+████╗ ████║██╔══██╗╚══███╔╝    ██╔════╝██║     ██║
+██╔████╔██║███████║  ███╔╝     ██║     ██║     ██║
+██║╚██╔╝██║██╔══██║ ███╔╝      ██║     ██║     ██║
+██║ ╚═╝ ██║██║  ██║███████╗    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝     ╚═════╝╚══════╝╚═╝
+
+v1.0.0
+```
+
+## API
+
+```ts
+function printBanner(args: {
+  name: string
+  version?: string
+  options?: FigletOptions & {
+    clear?: boolean
+    divider?: boolean
+    breakBefore?: boolean
+    breakAfter?: boolean
+  }
+}): void
+```
+
+| Parameter | Type      | Description                                  |
+| --------- | --------- | -------------------------------------------- |
+| `name`    | `string`  | Text rendered as ASCII art (required).       |
+| `version` | `string`  | Optional version line printed under the banner. |
+| `options` | `object`  | Figlet options + extras (see below).         |
+
+### Options
+
+| Option             | Type      | Default        | Description                                                              |
+| ------------------ | --------- | -------------- | ------------------------------------------------------------------------ |
+| `clear`            | `boolean` | `true`         | Clear the terminal screen before printing.                               |
+| `divider`          | `boolean` | `false`        | Print a separator line after the banner.                                 |
+| `breakBefore`      | `boolean` | `true`         | Print a blank line before the banner.                                    |
+| `breakAfter`       | `boolean` | `true`         | Print a blank line after the banner.                                     |
+| `font`             | `string`  | `'ANSI Shadow'` | Any [figlet font name](https://github.com/patorjk/figlet.js#fonts).      |
+| `horizontalLayout` | `string`  | `'full'`       | Figlet horizontal layout: `'default'`, `'full'`, `'fitted'`, …            |
+
+All standard [`figlet` options](https://github.com/patorjk/figlet.js#api) are forwarded.
+
+## Examples
+
+Minimal banner:
+
+```ts
+printBanner({ name: 'maz-cli' })
+```
+
+Banner with divider, no screen clearing:
+
+```ts
+printBanner({
+  name: 'maz-cli',
+  version: 'v1.0.0',
+  options: { clear: false, divider: true },
+})
+```
+
+Custom font:
+
+```ts
+printBanner({
+  name: 'Hi!',
+  options: { font: 'Standard', horizontalLayout: 'fitted' },
+})
+```

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.