storybookjs · kylegach · Apr 17, 2026 · Apr 16, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/docs/_snippets/ai-setup-output.md b/docs/_snippets/ai-setup-output.md
@@ -0,0 +1,11 @@
+```shell renderer="common" language="js" packageManager="npm"
+npx storybook ai setup --output storybook-setup.md
+```
+
+```shell renderer="common" language="js" packageManager="pnpm"
+pnpm exec storybook ai setup --output storybook-setup.md
+```
+
+```shell renderer="common" language="js" packageManager="yarn"
+yarn exec storybook ai setup --output storybook-setup.md
+```
diff --git a/docs/ai/best-practices.mdx b/docs/ai/best-practices.mdx
@@ -137,3 +137,4 @@ import { Meta } from '@storybook/addon-docs/blocks';
 - [MCP server API](./mcp/api.mdx)
 - [Sharing your MCP server](./mcp/sharing.mdx)
 - [Manifests](./manifests.mdx)
+- [Agentic setup](./setup.mdx)
diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx
@@ -90,3 +90,4 @@ These manifests are automatically generated and updated as you work on your Stor
 - [Sharing your MCP server](./mcp/sharing.mdx)
 - [Best practices for using Storybook with AI](./best-practices.mdx)
 - [Manifests](./manifests.mdx)
+- [Agentic setup](./setup.mdx)
diff --git a/docs/ai/manifests.mdx b/docs/ai/manifests.mdx
@@ -298,3 +298,4 @@ import { Meta } from '@storybook/addon-docs/blocks';
 - [MCP server API](./mcp/api.mdx)
 - [Sharing your MCP server](./mcp/sharing.mdx)
 - [Best practices for using Storybook with AI](./best-practices.mdx)
+- [Agentic setup](./setup.mdx)
diff --git a/docs/ai/mcp/api.mdx b/docs/ai/mcp/api.mdx
@@ -78,3 +78,4 @@ The testing toolset includes the [`run-story-tests`](./overview.mdx#run-story-te
 - [Sharing your MCP server](./sharing.mdx)
 - [Best practices for using Storybook with AI](../best-practices.mdx)
 - [Manifests](../manifests.mdx)
+- [Agentic setup](../setup.mdx)
diff --git a/docs/ai/mcp/overview.mdx b/docs/ai/mcp/overview.mdx
@@ -175,3 +175,4 @@ The docs toolset relies on the [manifests](../manifests.mdx) generated by Storyb
 - [Sharing your MCP server](./sharing.mdx)
 - [Best practices for using Storybook with AI](../best-practices.mdx)
 - [Manifests](../manifests.mdx)
+- [Agentic setup](../setup.mdx)
diff --git a/docs/ai/mcp/sharing.mdx b/docs/ai/mcp/sharing.mdx
@@ -75,3 +75,4 @@ export async function handleRequest(request: Request): Promise<Response> {
 - [MCP server API](./api.mdx)
 - [Best practices for using Storybook with AI](../best-practices.mdx)
 - [Manifests](../manifests.mdx)
+- [Agentic setup](../setup.mdx)
diff --git a/docs/ai/setup.mdx b/docs/ai/setup.mdx
@@ -0,0 +1,83 @@
+---
+title: Agentic setup
+sidebar:
+  order: 4
+---
+
+<Callout variant="info" icon="🧪">
+
+Storybook's agentic setup is currently only available for projects using the [React](?renderer=react) renderer with the [Vite](../builders/vite.mdx) builder. Support for additional renderers and builders will follow.
+
+The API may change in future releases. We welcome feedback and contributions to help improve this feature.
+
+</Callout>
+
+<If renderer={['react']}>
+
+Getting Storybook wired up to an existing application (configuring providers, mocking side effects, and writing the first few real stories) is the kind of repetitive, project-specific work that AI agents are well suited for. The **agentic setup** flow uses the [`storybook ai setup`](../api/cli-options.mdx#ai) command to generate a detailed, project-aware instruction set that an AI agent can follow to make Storybook fully functional in your project.
+
+The command analyzes your Storybook configuration (framework, renderer, builder, language, addons) and produces a Markdown prompt containing step-by-step instructions tailored to your project, covering everything from configuring your preview file to writing and verifying stories. See [what the generated prompt covers](#what-the-generated-prompt-covers) for the full list of steps.
+
+## Starting from `storybook init`
+
+When an agent runs [`storybook init`](../api/cli-options.mdx#init) to add Storybook to a new project, the output instructs the agent to continue with `storybook ai setup`. No extra prompting is needed; the agent will pick up the agentic setup flow automatically.
+
+If Storybook is already installed, you can kick off the flow yourself using one of the two approaches below.
+
+## Agent-initiated setup
+
+In this flow, you ask your agent to run `storybook ai setup`. For example:
+
+```txt
+Use Storybook's agentic setup command to configure Storybook for this project and write some initial stories.
+```
+
+The agent will run the command from your project root, read the generated prompt from stdout, and follow the steps in order: analyzing your codebase, updating `preview.tsx`, and writing stories. After each story, it runs Vitest to verify that the story renders and fixes any failures before moving on.
+
+This flow works best when your agent has access to a terminal in your project (most modern coding agents do). No flags or additional configuration is required. The generated instructions are self-contained.
+
+## User-initiated setup
+
+If you'd rather drive the process yourself, you can run the command manually and hand the output to any agent, even one that can't execute shell commands.
+
+1. From your project root, run:
+
+   <CodeSnippets path="ai-setup-output.md" />
+
+   This writes the instructions to `storybook-setup.md` instead of printing them to your terminal. Omit `--output` to print to stdout and pipe it elsewhere.
+
+2. Open the generated file and paste its contents into your agent's chat, or attach it as context. The prompt is designed to be self-contained: it references your specific `configDir`, framework, and renderer, and links back to the relevant Storybook docs in Markdown form.
+
+3. Let the agent work through the steps. You can review each change as the agent applies it.
+
+Use this flow when you want tighter control over what the agent does, when you're working with an agent that doesn't have shell access, or when you want to save the prompt to reuse across projects.
+
+## What the generated prompt covers
+
+Regardless of how the flow is initiated, the generated Markdown prompt walks the agent through the same ordered steps:
+
+1. **Analyze the codebase:** read providers, global CSS, portals, and data-fetching patterns.
+2. **Configure the [preview](../configure/story-rendering.mdx):** set up [decorators](../writing-stories/decorators.mdx), global styles, and any framework-level providers in `preview.tsx`.
+3. **Support portals:** ensure portal roots exist in the Storybook preview DOM.
+4. **Mock side effects:** intercept [network requests](../writing-stories/mocking-data-and-modules/mocking-network-requests.mdx) (via MSW), storage, timers, and navigation at the preview level rather than per-story.
+5. **Write [stories](../writing-stories/index.mdx):** copy real usage patterns from the app, [tagging](../writing-stories/tags.mdx) generated stories with `ai-generated` and `needs-work` so you can review them later.
+6. **Add [play functions](../writing-stories/play-function.mdx):** implement interaction tests for the most important flows.
+7. **Cover additional patterns:** expand coverage across the components the agent has already touched.
+8. **Verify:** run [Vitest](../writing-tests/integrations/vitest-addon/index.mdx) against every new story to confirm it renders, and run the type checker.
+
+<Callout variant="info">
+
+The command snapshots your `preview` file so that subsequent runs of `storybook dev`, `storybook build`, and `storybook doctor` can detect progress the agent made and report it via telemetry. If you'd prefer not to share this data, pass `--disable-telemetry` (see [telemetry](../configure/telemetry.mdx)).
+
+</Callout>
+
+## Next steps
+
+Once the agent has completed the setup:
+
+- Connect the [Storybook MCP server](./mcp/overview.mdx) to your agent so it can continue reading manifests, generating stories, and running tests against your live Storybook.
+- Review the stories tagged `ai-generated` and `needs-work`, and remove those tags once you've validated each one.
+- Follow the [best practices](./best-practices.mdx) to make your stories and documentation maximally useful to both humans and agents.
+
+</If>
+{/* End supported renderers */}
diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx
@@ -280,6 +280,49 @@ Options include:
 | `--package-manager`             | Sets the package manager to use when running the health check.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook doctor --package-manager pnpm` |
 | `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook doctor --debug`                                                                                                |
 
+### `ai`
+
+Helpers for AI agents. The `ai` command exposes subcommands that generate AI-friendly instructions for automating Storybook tasks. See the [agentic setup docs](../ai/setup.mdx) for a full walkthrough.
+
+```shell
+storybook ai [options] [command]
+```
+
+Options include:
+
+| Option                | Description                                                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `-h`, `--help`        | Output usage information.<br />`storybook ai --help`                                                                     |
+| `-o`, `--output <path>` | Write the prompt output to a file instead of printing it to stdout.<br />`storybook ai setup --output storybook-setup.md` |
+
+#### `ai setup`
+
+Generates a detailed, project-aware Markdown prompt that instructs an AI agent to configure Storybook in your project and write initial stories for real components. The prompt is built from your detected Storybook configuration (framework, renderer, builder, language, addons) and covers analyzing the codebase, configuring the preview, mocking side effects, writing stories, and verifying them with Vitest.
+
+<Callout variant="info">
+
+`storybook ai setup` is currently only available for projects using the React renderer with the Vite builder.
+
+</Callout>
-<Callout variant="info">
-  `storybook ai setup` is currently only available for projects using the React renderer with the Vite builder.
-</Callout>
+<Callout variant="info">
+  `storybook ai setup` is intended for projects using the React renderer with the Vite builder.
+  If your project uses a different setup, behavior may be limited while support is expanded.
+</Callout>
-<Callout variant="info">
-  `storybook ai setup` is currently only available for projects using the React renderer with the Vite builder.
-</Callout>
+<Callout variant="info">
+  `storybook ai setup` is intended for projects using the React renderer with the Vite builder.
+  If your project uses a different setup, behavior may be limited while support is expanded.
+</Callout>
+
+```shell
+storybook ai setup [options]
+```
+
+Options include:
+
+| Option                          | Description                                                                                                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `-h`, `--help`                  | Output usage information.<br />`storybook ai setup --help`                                                                                                               |
+| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.<br />`storybook ai setup -c .storybook`                                                                                               |
+| `--package-manager <type>`      | Force package manager to use when detecting project information.<br />Available package managers include `npm`, `yarn`, and `pnpm`.<br />`storybook ai setup --package-manager pnpm` |
+| `--disable-telemetry`           | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).<br />`storybook ai setup --disable-telemetry`                     |
+| `--debug`                       | Outputs more logs in the CLI to assist debugging.<br />`storybook ai setup --debug`                                                                                      |
+| `--loglevel [level]`            | Controls level of logging.<br />Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.<br />`storybook ai setup --loglevel warn`              |
+| `--logfile [path]`              | Write debug logs to a file.<br />`storybook ai setup --logfile ./sb.log`                                                                                                 |
+
+When run without `--output`, the generated prompt is printed to stdout. This is how AI agents typically consume it, by running the command directly and reading the result. When run with `--output`, the prompt is written to the given file path so you can paste or attach it to an agent that doesn't have shell access. See the [agentic setup](../ai/setup.mdx#user-initiated-setup) docs for details on both flows.
+
 ### `info`
 
 Reports useful debugging information about your environment. Helpful in providing information when opening an issue or a discussion.