From c27f4c7800f1e17354a95c85f345083eaf97a2cc Mon Sep 17 00:00:00 2001
From: yannbf <yannbf@gmail.com>
Date: Tue, 28 Apr 2026 23:10:38 +0200
Subject: [PATCH 01/24] Prompt: Run vitest less times, improve play functions

---
 code/lib/cli-storybook/src/ai/index.ts  |  85 ++--
 code/lib/cli-storybook/src/ai/prompt.ts | 539 +++++++++++++++++++++++-
 code/lib/cli-storybook/src/ai/types.ts  |   3 +-
 scripts/eval/prompts/optimized-tests.md | 299 +++++++++++++
 4 files changed, 863 insertions(+), 63 deletions(-)
 create mode 100644 scripts/eval/prompts/optimized-tests.md

diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index 20cd4884ae4e..0df8f549e709 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -22,54 +22,46 @@ import type { ProjectInfo, AiSetupOptions } from './types.ts';
 export async function aiSetup(options: AiSetupOptions): Promise<void> {
   const { configDir: userConfigDir, packageManager: packageManagerName, output } = options;
 
-  let projectInfo: ProjectInfo;
+  let projectInfo: ProjectInfo | undefined;
 
   try {
     const data = await getStorybookData({
       configDir: userConfigDir,
       packageManagerName: packageManagerName as PackageManagerName | undefined,
     });
-    const majorVersion = data.versionInstalled
-      ? parseMajorVersion(data.versionInstalled)
-      : undefined;
 
-    if (!data.frameworkPackage || !data.rendererPackage || !data.builderPackage) {
-      logger.error(
-        'Could not detect framework, renderer, or builder from your Storybook config. Make sure you are running this command from your project root, or specify --config-dir.'
-      );
-      return;
-    }
+    if (data.frameworkPackage && data.rendererPackage && data.builderPackage) {
+      const majorVersion = data.versionInstalled
+        ? parseMajorVersion(data.versionInstalled)
+        : undefined;
 
-    const projectTypeService = new ProjectTypeService(data.packageManager);
-    const detectedLanguage = await projectTypeService.detectLanguage();
-    const language = detectedLanguage === SupportedLanguage.TYPESCRIPT ? 'ts' : 'js';
+      const projectTypeService = new ProjectTypeService(data.packageManager);
+      const detectedLanguage = await projectTypeService.detectLanguage();
+      const language = detectedLanguage === SupportedLanguage.TYPESCRIPT ? 'ts' : 'js';
 
-    projectInfo = {
-      storybookVersion: data.versionInstalled,
-      majorVersion,
-      framework: data.frameworkPackage,
-      rendererPackage: data.rendererPackage,
-      renderer: data.renderer,
-      builderPackage: data.builderPackage,
-      addons: data.addons ?? [],
-      configDir: data.configDir,
-      storiesPaths: data.storiesPaths,
-      hasCsfFactoryPreview: data.hasCsfFactoryPreview,
-      language,
-    };
-  } catch (err: unknown) {
-    logger.error(
-      `Failed to read Storybook configuration: ${err instanceof Error ? err.message : String(err)}`
-    );
-    logger.log(
-      'Make sure you are running this command from your project root, or specify --config-dir.'
-    );
-    return;
+      projectInfo = {
+        storybookVersion: data.versionInstalled,
+        majorVersion,
+        framework: data.frameworkPackage,
+        rendererPackage: data.rendererPackage,
+        renderer: data.renderer,
+        builderPackage: data.builderPackage,
+        addons: data.addons ?? [],
+        configDir: data.configDir,
+        storiesPaths: data.storiesPaths,
+        packageManager: packageManagerName,
+        language,
+      };
+    }
+  } catch {
+    // No Storybook project (or unreadable config) — fall through and emit
+    // the generic prompt without a project metadata section.
   }
 
   if (
-    projectInfo.rendererPackage !== '@storybook/react' ||
-    projectInfo.builderPackage !== '@storybook/builder-vite'
+    projectInfo &&
+    (projectInfo.rendererPackage !== '@storybook/react' ||
+      projectInfo.builderPackage !== '@storybook/builder-vite')
   ) {
     logger.log(
       'AI-assisted setup is currently only available for projects using the React renderer with Vite builder. Detected renderer: ' +
@@ -86,16 +78,17 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
   await telemetry('ai-setup', {
     cliOptions: {
       output: output ? 'file' : undefined,
-      configDir: projectInfo.configDir,
+      configDir: projectInfo?.configDir,
       packageManager: packageManagerName,
     },
-    project: {
-      framework: projectInfo.framework,
-      renderer: projectInfo.rendererPackage,
-      builder: projectInfo.builderPackage,
-      language: projectInfo.language,
-      hasCsfFactoryPreview: projectInfo.hasCsfFactoryPreview,
-    },
+    project: projectInfo
+      ? {
+          framework: projectInfo.framework,
+          renderer: projectInfo.rendererPackage,
+          builder: projectInfo.builderPackage,
+          language: projectInfo.language,
+        }
+      : undefined,
   });
 
   // Snapshot the preview file baseline and cache the pending setup record.
@@ -103,7 +96,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
   // collect evidence of what the agent accomplished — but only via telemetry
   // (the `ai-setup-evidence` event). Skip the snapshot + cache write when
   // telemetry is disabled so there's nobody to read it.
-  if (isTelemetryModuleEnabled()) {
+  if (projectInfo && isTelemetryModuleEnabled()) {
     const resolvedConfigDir = resolve(projectInfo.configDir);
     const previewSnapshot = await snapshotPreviewFile(resolvedConfigDir);
     const sessionId = await getSessionId();
@@ -121,7 +114,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     await writeFile(outputPath, markdownOutput, 'utf-8');
     logger.log(`Prompt written to ${outputPath}`);
   } else {
-    logger.log(markdownOutput);
+    console.log(markdownOutput);
   }
 }
 
diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/prompt.ts
index 55d9a5a2b52b..7031193fdbc2 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/prompt.ts
@@ -1,25 +1,530 @@
+import { SupportedRenderer } from 'storybook/internal/types';
 import { dedent } from 'ts-dedent';
 
-import type { ProjectInfo } from './types.ts';
-import { getPrompts } from './setup-prompts/index.ts';
+import type { AiPrompt, ProjectInfo } from './types.ts';
+
+/**
+ * Builds a markdown-format docs URL with renderer and language query parameters.
+ * Appending .md to any Storybook docs URL returns clean markdown with code examples.
+ */
+export function getDocsMarkdownUrl(
+  path: string,
+  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
+): string {
+  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
+  const versionSegment = majorVersion ? `/${majorVersion}` : '';
+  const params = new URLSearchParams();
+  if (renderer) {
+    params.set('renderer', renderer);
+  }
+  params.set('language', language);
+  const query = params.toString();
+  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
+}
+
+const DEFAULT_PROJECT_INFO: ProjectInfo = {
+  storybookVersion: undefined,
+  majorVersion: undefined,
+  framework: null,
+  rendererPackage: null,
+  renderer: SupportedRenderer.REACT,
+  builderPackage: null,
+  addons: [],
+  configDir: '.storybook',
+  storiesPaths: [],
+  language: 'ts',
+};
+
+function withDefaults(projectInfo?: ProjectInfo): ProjectInfo {
+  return projectInfo ?? DEFAULT_PROJECT_INFO;
+}
+
+export function getPrompts(projectInfo?: ProjectInfo): {
+  prompts: AiPrompt[];
+} {
+  return {
+    prompts: [
+      {
+        name: 'setup',
+        description: 'Set up Storybook for success',
+        instructions: getSetupInstructions(withDefaults(projectInfo)),
+      },
+    ],
+  };
+}
+
+function ext(language: 'ts' | 'js', jsx: boolean): string {
+  if (language === 'ts') {
+    return jsx ? 'tsx' : 'ts';
+  }
+  return jsx ? 'jsx' : 'js';
+}
+
+function installCommand(packageManager: string | undefined, deps: string, dev = false): string {
+  switch (packageManager) {
+    case 'yarn':
+    case 'yarn1':
+    case 'yarn2':
+      return `yarn add ${dev ? '--dev ' : ''}${deps}`;
+    case 'pnpm':
+      return `pnpm add ${dev ? '-D ' : ''}${deps}`;
+    case 'bun':
+      return `bun add ${dev ? '-d ' : ''}${deps}`;
+    case 'npm':
+      return `npm install ${dev ? '--save-dev ' : ''}${deps}`;
+    default:
+      return `<your-package-manager> add ${dev ? '-D ' : ''}${deps}`;
+  }
+}
+
+function packageManagerRule(packageManager: string | undefined): string {
+  if (packageManager) {
+    return `**Use \`${packageManager}\` for every install** (detected from this project's lockfile).`;
+  }
+  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
+}
+
+function getSetupInstructions(projectInfo: ProjectInfo): string {
+  const { configDir, language, packageManager } = projectInfo;
+  const tsx = ext(language, true);
+  const ts = ext(language, false);
+  const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
+
+  const mswInstall = installCommand(packageManager, 'msw msw-storybook-addon mockdate', true);
 
-function getProjectOverview(projectInfo: ProjectInfo): string {
   return dedent`
-    ## Project Info
-
-    | Property | Value |
-    |----------|-------|
-    | Version | ${projectInfo.storybookVersion || 'unknown'} |
-    | Renderer | ${projectInfo.rendererPackage || 'unknown'} |
-    | Framework | ${projectInfo.framework || 'unknown'} |
-    | Builder | ${projectInfo.builderPackage || 'unknown'} |
-    | Config Dir | \`${projectInfo.configDir}\` |
-    | CSF Format | ${projectInfo.hasCsfFactoryPreview ? 'CSF Factory' : 'CSF3'} |
-    | Addons | ${projectInfo.addons.length > 0 ? projectInfo.addons.join(', ') : 'none'} |
+    Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
+
+    ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Concrete substitutions, no exceptions:
+        - List a directory → \`Glob('src/components/*')\`, not \`ls src/components\`.
+        - Search a string → \`Grep('pattern', { path: 'src' })\`, not \`grep -rn ...\` or \`find ... | xargs grep\`.
+        - Read a file → \`Read('path/to/file')\`, not \`cat\`/\`head\`/\`tail\`.
+        - Bulk-edit many files → multiple \`Edit\` calls (or \`Edit\` with \`replace_all\`), not \`sed -i\`.
+    2. **Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.
+    3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
+    4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
+    5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+    6. ${packageManagerRule(packageManager)}
+    7. **Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.
+    8. **Stop when the success criteria are met** — don't keep polishing.
+
+    ## Plan (do not skip steps, but keep each step lean)
+
+    ### Step 1 — Discover the runtime (≤12 reads)
+
+    Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+    ### Step 2 — Build the shared preview
+
+    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
+
+    The complete shape should look like this (merge the new pieces into what's already there):
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+
+    ### Step 3 — Portals (in a decorator, not preview-body.html)
+
+    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
+
+    ### Step 4 — MSW handlers (only what stories will hit)
+
+    Use \`msw-storybook-addon\`. Install with:
+
+    \`\`\`bash
+    ${mswInstall}
+    npx msw init ./public --save
+    \`\`\`
+
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = {
+      products: [
+        http.get('https://api.example.com/products', () =>
+          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+        ),
+      ],
+    };
+    \`\`\`
+
+    ### Step 5 — Write up to 10 story files (in one batch)
+
+    The deliverable for this step is **two things, both required**:
+
+    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck: Story = {
+      args: { children: 'Submit' },
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button', { name: /submit/i });
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+
+    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
+
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}
+
+    ### Step 7 — Verify in one batch, then iterate only on failures
+
+    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    npx vitest --project storybook run
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager ?? '<pm>'} run typecheck\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
+
+    ### Step 8 — Clean up
+
+    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+    ## Done when
+
+    - **Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+    - Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.
+    - \`npx vitest --project storybook run\` passes for the new files.
+    - The project's TypeScript check passes for changed files.
+    - The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+    ## Reference (only fetch if stuck)
+
+    - Docs index: https://storybook.js.org/llms.txt
+    - Writing stories: ${docsUrl('writing-stories')}
+    - Decorators: ${docsUrl('writing-stories/decorators')}
+    - Play functions: ${docsUrl('writing-stories/play-function')}
+    - Vitest integration: ${docsUrl('writing-tests/vitest-plugin')}
+
+    Append \`?codeOnly=true\` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
+  `;
+}
+
+function getPreviewExample(projectInfo: ProjectInfo): string {
+  const { configDir, language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      import MockDate from 'mockdate';
+      import { initialize, mswLoader } from 'msw-storybook-addon';
+      import { SessionProvider } from '../src/contexts/SessionContext';
+      import { mswHandlers } from './msw-handlers';
+
+      initialize({ onUnhandledRequest: 'bypass' });
+
+      const preview = {
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+        loaders: [mswLoader],
+        parameters: { msw: { handlers: mswHandlers } },
+        async beforeEach() {
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    import MockDate from 'mockdate';
+    import { initialize, mswLoader } from 'msw-storybook-addon';
+    import { SessionProvider } from '../src/contexts/SessionContext';
+    import { mswHandlers } from './msw-handlers';
+
+    initialize({ onUnhandledRequest: 'bypass' });
+
+    const preview: Preview = {
+      decorators: [
+        (Story) => (
+          <SessionProvider>
+            <Story />
+          </SessionProvider>
+        ),
+      ],
+      loaders: [mswLoader],
+      parameters: { msw: { handlers: mswHandlers } },
+      async beforeEach() {
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+
+function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+
+  return dedent`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return <Story />;
+    }
+    \`\`\`
+  `;
+}
+
+function getMainConfigExample(projectInfo: ProjectInfo): string {
+  const { configDir, framework, rendererPackage, language } = projectInfo;
+  const ts = ext(language, false);
+  const typeImport = framework || rendererPackage || '@storybook/react';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
   `;
 }
 
-export async function generateMarkdownOutput(projectInfo: ProjectInfo): Promise<{
+function getStoryExample(projectInfo: ProjectInfo): string {
+  const { language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      import { expect } from 'storybook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from 'storybook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+
+function getInteractionPlayExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+  const typeAnnotation = language === 'ts' ? ': Story' : '';
+
+  return dedent`
+    \`\`\`${tsx}
+    export const FilledForm${typeAnnotation} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
+
+function getProjectOverview(projectInfo: ProjectInfo): string {
+  const rows: Array<[string, string]> = [
+    ['Version', projectInfo.storybookVersion || 'unknown'],
+    ['Renderer', projectInfo.rendererPackage || 'unknown'],
+    ['Framework', projectInfo.framework || 'unknown'],
+    ['Builder', projectInfo.builderPackage || 'unknown'],
+    ['Config Dir', `\`${projectInfo.configDir}\``],
+    ['Language', projectInfo.language === 'ts' ? 'TypeScript' : 'JavaScript'],
+  ];
+
+  if (projectInfo.packageManager) {
+    rows.push(['Package Manager', projectInfo.packageManager]);
+  }
+
+  rows.push(['Addons', projectInfo.addons.length > 0 ? projectInfo.addons.join(', ') : 'none']);
+
+  const tableRows = rows.map(([key, value]) => `| ${key} | ${value} |`).join('\n');
+
+  return ['## Project Info', '', '| Property | Value |', '|----------|-------|', tableRows].join(
+    '\n'
+  );
+}
+
+export async function generateMarkdownOutput(projectInfo?: ProjectInfo): Promise<{
   markdown: string;
 }> {
   const { prompts: aiPrompts } = await getPrompts(projectInfo);
@@ -30,7 +535,9 @@ export async function generateMarkdownOutput(projectInfo: ProjectInfo): Promise<
     # Storybook Setup
   `);
 
-  sections.push(getProjectOverview(projectInfo));
+  if (projectInfo) {
+    sections.push(getProjectOverview(projectInfo));
+  }
 
   for (const aiPrompt of aiPrompts) {
     sections.push(aiPrompt.instructions);
diff --git a/code/lib/cli-storybook/src/ai/types.ts b/code/lib/cli-storybook/src/ai/types.ts
index 93a3ea88aabd..7c54bd88d042 100644
--- a/code/lib/cli-storybook/src/ai/types.ts
+++ b/code/lib/cli-storybook/src/ai/types.ts
@@ -20,9 +20,10 @@ export interface ProjectInfo {
   addons: string[];
   configDir: string;
   storiesPaths: string[];
-  hasCsfFactoryPreview: boolean;
   /** Whether the project uses TypeScript ('ts') or JavaScript ('js'), inferred from the main config file extension. */
   language: 'ts' | 'js';
+  /** Detected package manager name (npm, yarn, pnpm, bun), if known. */
+  packageManager?: string;
 }
 
 /**
diff --git a/scripts/eval/prompts/optimized-tests.md b/scripts/eval/prompts/optimized-tests.md
new file mode 100644
index 000000000000..2f5f8d3d5601
--- /dev/null
+++ b/scripts/eval/prompts/optimized-tests.md
@@ -0,0 +1,299 @@
+# Storybook Setup
+
+## Project Info
+
+| Property | Value |
+|----------|-------|
+| Version | 10.4.0-alpha.10 |
+| Renderer | @storybook/react |
+| Framework | @storybook/react-vite |
+| Builder | @storybook/builder-vite |
+| Config Dir | `.storybook` |
+| Language | TypeScript |
+| Package Manager | yarn |
+| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
+
+Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
+
+## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Concrete substitutions, no exceptions:
+    - List a directory → `Glob('src/components/*')`, not `ls src/components`.
+    - Search a string → `Grep('pattern', { path: 'src' })`, not `grep -rn ...` or `find ... | xargs grep`.
+    - Read a file → `Read('path/to/file')`, not `cat`/`head`/`tail`.
+    - Bulk-edit many files → multiple `Edit` calls (or `Edit` with `replace_all`), not `sed -i`.
+2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
+3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
+4. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
+5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+6. **Use `yarn` for every install** (detected from this project's lockfile).
+7. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
+8. **Stop when the success criteria are met** — don't keep polishing.
+
+## Plan (do not skip steps, but keep each step lean)
+
+### Step 1 — Discover the runtime (≤12 reads)
+
+Identify, in this order, using Glob/Grep first then targeted Reads:
+
+- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
+- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
+- `App.tsx` — top-level layout, router usage, providers it consumes
+- providers / context files — what they expose
+- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
+- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
+- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
+- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
+- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+### Step 2 — Build the shared preview
+
+Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
+
+The complete shape should look like this (merge the new pieces into what's already there):
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+import MockDate from 'mockdate';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { SessionProvider } from '../src/contexts/SessionContext';
+import { mswHandlers } from './msw-handlers';
+
+initialize({ onUnhandledRequest: 'bypass' });
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <SessionProvider>
+        <Story />
+      </SessionProvider>
+    ),
+  ],
+  loaders: [mswLoader],
+  parameters: { msw: { handlers: mswHandlers } },
+  async beforeEach() {
+    localStorage.setItem('theme', 'dark');
+    MockDate.set('2024-04-01T12:00:00Z');
+  },
+};
+
+export default preview;
+```
+
+Rules for the preview:
+
+- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
+- Use `mockdate` only when render output depends on the date.
+- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
+
+### Step 3 — Portals (in a decorator, not preview-body.html)
+
+If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
+
+```tsx
+// Add this entry to the `decorators` array of your preview config:
+(Story) => {
+  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+    if (!document.getElementById(id)) {
+      const el = document.createElement('div');
+      el.id = id;
+      document.body.appendChild(el);
+    }
+  }
+  return <Story />;
+}
+```
+
+Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
+
+### Step 4 — MSW handlers (only what stories will hit)
+
+Use `msw-storybook-addon`. Install with:
+
+```bash
+yarn add --dev msw msw-storybook-addon mockdate
+npx msw init ./public --save
+```
+
+Make sure `.storybook/main.ts` serves `./public`:
+
+```ts
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = { staticDirs: ['../public'] };
+export default config;
+```
+
+Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+```ts
+// .storybook/msw-handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const mswHandlers = {
+  products: [
+    http.get('https://api.example.com/products', () =>
+      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+    ),
+  ],
+};
+```
+
+### Step 5 — Write up to 10 story files (in one batch)
+
+The deliverable for this step is **two things, both required**:
+
+1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
+2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
+
+Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Smoke check — one is enough per file
+export const Primary: Story = {
+  args: { children: 'Order now' },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+  },
+};
+
+// Variant-only stories: no play needed
+export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+export const Large: Story = { args: { children: 'Checkout', large: true } };
+export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+```
+
+Story rules:
+
+- Start every meta with `tags: ['ai-generated', 'needs-work']`.
+- Show all imports explicitly.
+- Don't add a custom `title`.
+- Don't build large story-specific harnesses — fix preview instead.
+- Don't create new app components.
+
+**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
+
+```tsx
+export const CssCheck: Story = {
+  args: { children: 'Submit' },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole('button', { name: /submit/i });
+    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+  },
+};
+```
+
+### Step 6 — Add `play` functions only where they prove something non-trivial
+
+**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
+
+Write a `play` when it can verify:
+
+- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
+- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+- **accessibility** that the component is responsible for (correct role/label exposure)
+
+**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
+- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
+- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
+- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
+
+If none of those apply, skip the `play` and rely on the render itself.
+
+Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
+
+- `Primary` — keep one smoke `play` (one is enough for the file).
+- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
+
+(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
+
+Imports & play context — get this right or vitest will fail in subtle ways:
+
+- `expect` and `waitFor` come from `'storybook/test'` — import those.
+- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
+- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
+
+```tsx
+export const FilledForm: Story = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+  },
+};
+```
+
+### Step 7 — Verify in one batch, then iterate only on failures
+
+**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+```bash
+npx vitest --project storybook run
+```
+
+Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn run typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
+
+For each failure:
+
+1. Read the error.
+2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
+4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave `'needs-work'` and move on.
+
+**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
+
+### Step 8 — Clean up
+
+Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+## Done when
+
+- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
+- `npx vitest --project storybook run` passes for the new files.
+- The project's TypeScript check passes for changed files.
+- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+## Reference (only fetch if stuck)
+
+- Docs index: https://storybook.js.org/llms.txt
+- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
+- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
+- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
+- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
+
+Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
\ No newline at end of file

From 5583710134f6aada3133a4564caec35991f2eac7 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Wed, 29 Apr 2026 13:09:49 +0200
Subject: [PATCH 02/24] Prettify package manager name to help show Yarn 1 vs
 Berry

---
 .../js-package-manager/JsPackageManager.ts    | 27 +++++++++++++++++++
 code/lib/cli-storybook/src/ai/index.ts        |  3 ++-
 .../src/commands/PreflightCheckCommand.ts     | 14 ++--------
 3 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/code/core/src/common/js-package-manager/JsPackageManager.ts b/code/core/src/common/js-package-manager/JsPackageManager.ts
index 31b434654b42..6e9453f202f0 100644
--- a/code/core/src/common/js-package-manager/JsPackageManager.ts
+++ b/code/core/src/common/js-package-manager/JsPackageManager.ts
@@ -37,6 +37,33 @@ type PackageJsonWithIndent = PackageJsonWithDepsAndDevDeps & {
   [indentSymbol]?: any;
 };
 
+/** Human-friendly labels for each package manager type */
+const PACKAGE_MANAGER_LABEL: Record<PackageManagerName, string> = {
+  [PackageManagerName.NPM]: 'npm',
+  [PackageManagerName.YARN1]: 'Yarn Classic (v1)',
+  [PackageManagerName.YARN2]: 'Yarn Berry',
+  [PackageManagerName.PNPM]: 'pnpm',
+  [PackageManagerName.BUN]: 'Bun',
+};
+
+function isValidPackageManagerName(name: string): name is PackageManagerName {
+  return Object.hasOwn(PACKAGE_MANAGER_LABEL, name);
+}
+
+/**
+ * Prints a package manager's name in a way that's easier to compute by humans and agents.
+ * @param packageManager The package manager's internal name (e.g. "yarn1")
+ * @return A human-friendly name for the package manager (e.g. "Yarn Classic (v1)")
+ */
+export function getPrettyPackageManagerName(packageManager: string | undefined): string {
+  if (!packageManager) {
+    return 'unknown package manager';
+  }
+  return isValidPackageManagerName(packageManager)
+    ? PACKAGE_MANAGER_LABEL[packageManager]
+    : packageManager;
+}
+
 /**
  * Extract package name and version from input
  *
diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index 0df8f549e709..fcd21559dfd6 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -2,6 +2,7 @@ import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
 import type { PackageManagerName } from 'storybook/internal/common';
+import { getPrettyPackageManagerName } from 'storybook/internal/common';
 import { cache } from 'storybook/internal/common';
 import { logger } from 'storybook/internal/node-logger';
 import {
@@ -49,7 +50,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
         addons: data.addons ?? [],
         configDir: data.configDir,
         storiesPaths: data.storiesPaths,
-        packageManager: packageManagerName,
+        packageManager: getPrettyPackageManagerName(packageManagerName),
         language,
       };
     }
diff --git a/code/lib/create-storybook/src/commands/PreflightCheckCommand.ts b/code/lib/create-storybook/src/commands/PreflightCheckCommand.ts
index e6d06b5ef091..b4bedeb5f763 100644
--- a/code/lib/create-storybook/src/commands/PreflightCheckCommand.ts
+++ b/code/lib/create-storybook/src/commands/PreflightCheckCommand.ts
@@ -3,6 +3,7 @@ import {
   type JsPackageManager,
   JsPackageManagerFactory,
   PackageManagerName,
+  getPrettyPackageManagerName,
   invalidateProjectRootCache,
 } from 'storybook/internal/common';
 import { CLI_COLORS, deprecate, logger } from 'storybook/internal/node-logger';
@@ -18,15 +19,6 @@ export interface PreflightCheckResult {
   isEmptyProject: boolean;
 }
 
-/** Human-friendly labels for each package manager type */
-const PACKAGE_MANAGER_LABEL: Record<PackageManagerName, string> = {
-  [PackageManagerName.NPM]: 'npm',
-  [PackageManagerName.YARN1]: 'Yarn Classic (v1)',
-  [PackageManagerName.YARN2]: 'Yarn Berry',
-  [PackageManagerName.PNPM]: 'pnpm',
-  [PackageManagerName.BUN]: 'Bun',
-};
-
 /**
  * Command for running preflight checks before Storybook initialization
  *
@@ -72,9 +64,7 @@ export class PreflightCheckCommand {
       force: options.packageManager,
     });
 
-    logger.info(
-      `Package manager: ${PACKAGE_MANAGER_LABEL[packageManager.type] ?? packageManager.type}`
-    );
+    logger.info(`Package manager: ${getPrettyPackageManagerName(packageManager.type)}`);
 
     // Install base project dependencies if we scaffolded a new project
     if (isEmptyDirProject && !options.skipInstall) {

From b7b99616a67ee32d037c82147b58d7efe6de0c4c Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <Sidnioulz@users.noreply.github.com>
Date: Wed, 29 Apr 2026 17:06:18 +0200
Subject: [PATCH 03/24] Avoid using console.log for stdout writes

---
 code/lib/cli-storybook/src/ai/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index fcd21559dfd6..5448b39b6e3e 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -115,7 +115,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     await writeFile(outputPath, markdownOutput, 'utf-8');
     logger.log(`Prompt written to ${outputPath}`);
   } else {
-    console.log(markdownOutput);
+    process.stdout.write(`${markdownOutput}\n`);
   }
 }
 

From 426a2ecef7354d338419bf0e4ccd7efeb1befbfc Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Wed, 29 Apr 2026 19:24:10 +0200
Subject: [PATCH 04/24] Address PR feedback

---
 code/lib/cli-storybook/src/ai/index.ts       |  87 +--
 code/lib/cli-storybook/src/ai/prompt.ts      |  42 +-
 docs/configure/integration/eslint-plugin.mdx |  30 +-
 scripts/eval/prompts/optimized-tests.md      |   9 +-
 scripts/eval/prompts/rac-prompt.md           | 558 +++++++++++++++++++
 5 files changed, 638 insertions(+), 88 deletions(-)
 create mode 100644 scripts/eval/prompts/rac-prompt.md

diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index 5448b39b6e3e..501953c30cf1 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -23,7 +23,7 @@ import type { ProjectInfo, AiSetupOptions } from './types.ts';
 export async function aiSetup(options: AiSetupOptions): Promise<void> {
   const { configDir: userConfigDir, packageManager: packageManagerName, output } = options;
 
-  let projectInfo: ProjectInfo | undefined;
+  let projectInfo: ProjectInfo;
 
   try {
     const data = await getStorybookData({
@@ -31,38 +31,47 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
       packageManagerName: packageManagerName as PackageManagerName | undefined,
     });
 
-    if (data.frameworkPackage && data.rendererPackage && data.builderPackage) {
-      const majorVersion = data.versionInstalled
-        ? parseMajorVersion(data.versionInstalled)
-        : undefined;
-
-      const projectTypeService = new ProjectTypeService(data.packageManager);
-      const detectedLanguage = await projectTypeService.detectLanguage();
-      const language = detectedLanguage === SupportedLanguage.TYPESCRIPT ? 'ts' : 'js';
-
-      projectInfo = {
-        storybookVersion: data.versionInstalled,
-        majorVersion,
-        framework: data.frameworkPackage,
-        rendererPackage: data.rendererPackage,
-        renderer: data.renderer,
-        builderPackage: data.builderPackage,
-        addons: data.addons ?? [],
-        configDir: data.configDir,
-        storiesPaths: data.storiesPaths,
-        packageManager: getPrettyPackageManagerName(packageManagerName),
-        language,
-      };
+    if (!data.frameworkPackage || !data.rendererPackage || !data.builderPackage) {
+      logger.error(
+        'Could not detect framework, renderer, or builder from your Storybook config. Make sure you are running this command from your project root, or specify --config-dir.'
+      );
+      return;
     }
-  } catch {
-    // No Storybook project (or unreadable config) — fall through and emit
-    // the generic prompt without a project metadata section.
+
+    const majorVersion = data.versionInstalled
+      ? parseMajorVersion(data.versionInstalled)
+      : undefined;
+
+    const projectTypeService = new ProjectTypeService(data.packageManager);
+    const detectedLanguage = await projectTypeService.detectLanguage();
+    const language = detectedLanguage === SupportedLanguage.TYPESCRIPT ? 'ts' : 'js';
+
+    projectInfo = {
+      storybookVersion: data.versionInstalled,
+      majorVersion,
+      framework: data.frameworkPackage,
+      rendererPackage: data.rendererPackage,
+      renderer: data.renderer,
+      builderPackage: data.builderPackage,
+      addons: data.addons ?? [],
+      configDir: data.configDir,
+      storiesPaths: data.storiesPaths,
+      packageManager: getPrettyPackageManagerName(packageManagerName),
+      language,
+    };
+  } catch (err) {
+    logger.error(
+      `Failed to read Storybook configuration: ${err instanceof Error ? err.message : String(err)}`
+    );
+    logger.log(
+      'Make sure you are running this command from your project root, or specify --config-dir.'
+    );
+    return;
   }
 
   if (
-    projectInfo &&
-    (projectInfo.rendererPackage !== '@storybook/react' ||
-      projectInfo.builderPackage !== '@storybook/builder-vite')
+    projectInfo.rendererPackage !== '@storybook/react' ||
+    projectInfo.builderPackage !== '@storybook/builder-vite'
   ) {
     logger.log(
       'AI-assisted setup is currently only available for projects using the React renderer with Vite builder. Detected renderer: ' +
@@ -73,23 +82,21 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     return;
   }
 
-  const result = await generateMarkdownOutput(projectInfo);
+  const result = await generateMarkdownOutput('Storybook Setup', projectInfo);
   const markdownOutput = result.markdown;
 
   await telemetry('ai-setup', {
     cliOptions: {
       output: output ? 'file' : undefined,
-      configDir: projectInfo?.configDir,
+      configDir: projectInfo.configDir,
       packageManager: packageManagerName,
     },
-    project: projectInfo
-      ? {
-          framework: projectInfo.framework,
-          renderer: projectInfo.rendererPackage,
-          builder: projectInfo.builderPackage,
-          language: projectInfo.language,
-        }
-      : undefined,
+    project: {
+      framework: projectInfo.framework,
+      renderer: projectInfo.rendererPackage,
+      builder: projectInfo.builderPackage,
+      language: projectInfo.language,
+    },
   });
 
   // Snapshot the preview file baseline and cache the pending setup record.
@@ -97,7 +104,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
   // collect evidence of what the agent accomplished — but only via telemetry
   // (the `ai-setup-evidence` event). Skip the snapshot + cache write when
   // telemetry is disabled so there's nobody to read it.
-  if (projectInfo && isTelemetryModuleEnabled()) {
+  if (isTelemetryModuleEnabled()) {
     const resolvedConfigDir = resolve(projectInfo.configDir);
     const previewSnapshot = await snapshotPreviewFile(resolvedConfigDir);
     const sessionId = await getSessionId();
diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/prompt.ts
index 7031193fdbc2..3b25b7349a7b 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/prompt.ts
@@ -22,24 +22,7 @@ export function getDocsMarkdownUrl(
   return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
 }
 
-const DEFAULT_PROJECT_INFO: ProjectInfo = {
-  storybookVersion: undefined,
-  majorVersion: undefined,
-  framework: null,
-  rendererPackage: null,
-  renderer: SupportedRenderer.REACT,
-  builderPackage: null,
-  addons: [],
-  configDir: '.storybook',
-  storiesPaths: [],
-  language: 'ts',
-};
-
-function withDefaults(projectInfo?: ProjectInfo): ProjectInfo {
-  return projectInfo ?? DEFAULT_PROJECT_INFO;
-}
-
-export function getPrompts(projectInfo?: ProjectInfo): {
+export function getPrompts(projectInfo: ProjectInfo): {
   prompts: AiPrompt[];
 } {
   return {
@@ -47,7 +30,7 @@ export function getPrompts(projectInfo?: ProjectInfo): {
       {
         name: 'setup',
         description: 'Set up Storybook for success',
-        instructions: getSetupInstructions(withDefaults(projectInfo)),
+        instructions: getSetupInstructions(projectInfo),
       },
     ],
   };
@@ -97,11 +80,11 @@ function getSetupInstructions(projectInfo: ProjectInfo): string {
 
     ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
-    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Concrete substitutions, no exceptions:
-        - List a directory → \`Glob('src/components/*')\`, not \`ls src/components\`.
-        - Search a string → \`Grep('pattern', { path: 'src' })\`, not \`grep -rn ...\` or \`find ... | xargs grep\`.
-        - Read a file → \`Read('path/to/file')\`, not \`cat\`/\`head\`/\`tail\`.
-        - Bulk-edit many files → multiple \`Edit\` calls (or \`Edit\` with \`replace_all\`), not \`sed -i\`.
+    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+        - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
+        - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
+        - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
+        - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.
     2. **Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.
     3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
     4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
@@ -524,7 +507,10 @@ function getProjectOverview(projectInfo: ProjectInfo): string {
   );
 }
 
-export async function generateMarkdownOutput(projectInfo?: ProjectInfo): Promise<{
+export async function generateMarkdownOutput(
+  title: string,
+  projectInfo: ProjectInfo
+): Promise<{
   markdown: string;
 }> {
   const { prompts: aiPrompts } = await getPrompts(projectInfo);
@@ -532,12 +518,10 @@ export async function generateMarkdownOutput(projectInfo?: ProjectInfo): Promise
   const sections: string[] = [];
 
   sections.push(dedent`
-    # Storybook Setup
+    # ${title}
   `);
 
-  if (projectInfo) {
-    sections.push(getProjectOverview(projectInfo));
-  }
+  sections.push(getProjectOverview(projectInfo));
 
   for (const aiPrompt of aiPrompts) {
     sections.push(aiPrompt.instructions);
diff --git a/docs/configure/integration/eslint-plugin.mdx b/docs/configure/integration/eslint-plugin.mdx
index 1e20b0ce2714..9990fe924ecc 100644
--- a/docs/configure/integration/eslint-plugin.mdx
+++ b/docs/configure/integration/eslint-plugin.mdx
@@ -39,10 +39,10 @@ For more details on why this line is required in the `.eslintignore` file, refer
 If you are using [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new), add this to your configuration file:
 
 ```js title="eslint.config.js"
-import { defineConfig, globalIgnores } from 'eslint/config';
+import { defineConfig, globalIgnores } from "eslint/config";
 
 export default defineConfig([
-  globalIgnores(['!.storybook'], 'Include Storybook Directory'),
+  globalIgnores(["!.storybook"], "Include Storybook Directory"),
   // ...
 ]);
 ```
@@ -91,12 +91,12 @@ Optionally, you can override, add to, or disable individual rules. You likely do
 Use the `eslint.config.js` file to configure rules using the [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new). This is the default in ESLint v9, but can be used starting from ESLint v8.57.0. [ESLint docs](https://eslint.org/docs/latest/use/configure/configuration-files-new).
 
 ```js title="eslint.config.js"
-import storybook from 'eslint-plugin-storybook';
+import storybook from "eslint-plugin-storybook";
 // Replace the eslint/config package with @eslint/config-helpers if you're using an older version of ESLint.
-import { defineConfig } from 'eslint/config';
+import { defineConfig } from "eslint/config";
 
 export default defineConfig([
-  ...storybook.configs['flat/recommended'],
+  ...storybook.configs["flat/recommended"],
   // Add more configuration options and generic rulesets here, such as js.configs.recommended
 ]);
 ```
@@ -104,13 +104,13 @@ export default defineConfig([
 In case you are using utility functions from tools like `tseslint`, you might need to register the plugin a little differently:
 
 ```ts title="eslint.config.ts"
-import storybook from 'eslint-plugin-storybook';
-import somePlugin from 'some-plugin';
-import tseslint from 'typescript-eslint';
+import storybook from "eslint-plugin-storybook";
+import somePlugin from "some-plugin";
+import tseslint from "typescript-eslint";
 
 export default tseslint.config(
   somePlugin,
-  storybook.configs['flat/recommended'], // notice that it is not destructured
+  storybook.configs["flat/recommended"], // notice that it is not destructured
 );
 ```
 
@@ -119,19 +119,19 @@ export default tseslint.config(
 Optionally, you can override, add, or disable individual rules. You likely don't want these settings to be applied to every file, so ensure that you add a flat config section in your `eslint.config.js` file that applies the overrides only to your story files.
 
 ```js title="eslint.config.js"
-import storybook from 'eslint-plugin-storybook';
-import { defineConfig } from 'eslint/config';
+import storybook from "eslint-plugin-storybook";
+import { defineConfig } from "eslint/config";
 
 export default defineConfig([
-  ...storybook.configs['flat/recommended'],
+  ...storybook.configs["flat/recommended"],
   {
     // 👇 This should match the `stories` property in .storybook/main.js|ts
-    files: ['**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)'],
+    files: ["**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)"],
     rules: {
       // 👇 Enable this rule
-      'storybook/csf-component': 'error',
+      "storybook/csf-component": "error",
       // 👇 Disable this rule
-      'storybook/default-exports': 'off',
+      "storybook/default-exports": "off",
     },
   },
 ]);
diff --git a/scripts/eval/prompts/optimized-tests.md b/scripts/eval/prompts/optimized-tests.md
index 2f5f8d3d5601..5d604a8c79ec 100644
--- a/scripts/eval/prompts/optimized-tests.md
+++ b/scripts/eval/prompts/optimized-tests.md
@@ -18,10 +18,11 @@ Your goal is to make Storybook fully functional in this project: configure `.sto
 ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
 1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Concrete substitutions, no exceptions:
-    - List a directory → `Glob('src/components/*')`, not `ls src/components`.
-    - Search a string → `Grep('pattern', { path: 'src' })`, not `grep -rn ...` or `find ... | xargs grep`.
-    - Read a file → `Read('path/to/file')`, not `cat`/`head`/`tail`.
-    - Bulk-edit many files → multiple `Edit` calls (or `Edit` with `replace_all`), not `sed -i`.
+    - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
+    - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
+    - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
+    - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
+
 2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
 3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
 4. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
diff --git a/scripts/eval/prompts/rac-prompt.md b/scripts/eval/prompts/rac-prompt.md
new file mode 100644
index 000000000000..a9583e5d04f3
--- /dev/null
+++ b/scripts/eval/prompts/rac-prompt.md
@@ -0,0 +1,558 @@
+# Storybook Setup
+
+## Project Info
+
+| Property                                                           | Value                                              |
+| ------------------------------------------------------------------ | -------------------------------------------------- |
+| Version                                                            | 10.4.0-alpha.10                                    |
+| Renderer                                                           | @storybook/react                                   |
+| Framework                                                          | @storybook/react-vite                              |
+| Builder                                                            | @storybook/builder-vite                            |
+| Config Dir                                                         | `.storybook`                                       |
+| CSF Format                                                         | CSF3                                               |
+| Addons                                                             | @chromatic-com/storybook, @storybook/addon-vitest, |
+| @storybook/addon-a11y, @storybook/addon-docs, @storybook/addon-mcp |                                                    |
+
+Attention: The following instructions must be followed in order to
+successfully set up Storybook in this project. Do not skip steps or
+attempt to do them out of order.
+
+Your goal is to make Storybook fully functional in this project by
+analyzing the codebase,
+configuring the preview with the right decorators, and writing stories
+for some components.
+
+After each created story, run Vitest to verify it renders.
+If the test fails, read the error, fix the issue, and re-run until it
+passes before moving on.
+
+- Copy real patterns from the codebase
+- Keep the app code unchanged
+- Put the default setup in `.storybook/preview.tsx`
+- Keep app mocking and runtime setup in `.storybook/preview.tsx`, not
+in the stories
+
+### Storybook Documentation Reference
+
+Use the following references to look up Storybook APIs, concepts, or
+examples:
+
+- Full docs index: https://storybook.js.org/llms.txt
+- See code snippets only with codeOnly=true param e.g.
+https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts&codeOnly=true
+
+Key documentation pages for this task:
+- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
+- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
+- Args: https://storybook.js.org/docs/10/writing-stories/args.md?renderer=react&language=ts
+- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
+- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
+
+Fetch these URLs directly when you need guidance on Storybook APIs or
+patterns.
+
+### Step 1: Analyze the codebase
+
+Read enough of the app to understand the full runtime environment
+before writing any stories.
+
+Do not stop at `main.tsx` or `App.tsx`.
+Follow imports into providers, pages, hooks, and shared components
+until you know:
+
+- which providers exist
+- which CSS files are injected
+- which queries fetch data
+- which browser-state reads happen
+- which portals and portal roots exist
+- which pages and components show the real usage patterns
+
+Example of what to copy:
+
+```tsx
+// src/main.tsx
+import "./index.css";
+import App from "./App";
+import { SessionProvider } from "./contexts/SessionContext";
+
+createRoot(document.getElementById("root")!).render(
+<SessionProvider>
+<App />
+</SessionProvider>,
+);
+```
+
+That means Storybook should copy:
+
+- the `index.css` import
+- the `SessionProvider`
+- the same provider order
+
+Example of tracing the app deeper:
+
+```tsx
+// src/App.tsx
+function App() {
+const { products, loadMoreProducts } = useProducts();
+const { currentUser, signOut } = useSession();
+// ...
+}
+```
+
+```ts
+// src/hooks/useProducts.ts
+const response = await fetch(apiBaseUrl + "/products?page=1");
+```
+
+```ts
+// src/hooks/useTheme.ts
+const savedTheme = localStorage.getItem("theme");
+```
+
+That means the default Storybook setup should discover and prepare:
+
+- provider state
+- MSW handlers for queries
+- browser-state values that are actually read during render
+
+### Step 2: Build one default app environment in preview
+
+Set up Storybook once so most stories work without story-specific
+setup.
+
+Start with the smallest faithful environment:
+
+- the real provider tree
+- the real root CSS
+- seeded browser state if the app reads it during render
+- MSW for network/data queries
+
+It is fine to seed browser state such as `localStorage`,
+`sessionStorage`, and cookies when the app reads them during render.
+Seed only the specific app-owned keys and values you need.
+Do not clear all `localStorage`, `sessionStorage`, or cookies, and do
+not reset Storybook's own state.
+Do not mock or redefine the browser runtime itself.
+The stories run in Vitest browser mode, so the real browser
+environment should already exist.
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import MockDate from 'mockdate';
+import '../src/index.css'; // import global styles
+import { SessionProvider } from '../src/contexts/SessionContext';
+
+const preview: Preview = {
+decorators: [
+(Story) => (
+<SessionProvider>
+<Story />
+</SessionProvider>
+),
+],
+async beforeEach() {
+localStorage.setItem('theme', 'dark');
+localStorage.setItem('sidebar:open', 'true');
+MockDate.set('2024-04-01T12:00:00Z');
+},
+};
+
+export default preview;
+```
+
+Use this same idea for:
+
+- providers
+- root CSS
+- browser state
+- dates, and if the app logic depends on them during render then
+always use `mockdate`
+
+Example with the `mockdate` package:
+
+```tsx
+import type { Preview } from '@storybook/react-vite';
+import MockDate from 'mockdate';
+
+const preview: Preview = {
+async beforeEach() {
+MockDate.set('2024-04-01T12:00:00Z');
+},
+};
+
+export default preview;
+```
+
+### Step 3: Support portals with preview-body.html
+
+If the app uses portals, copy that setup into Storybook too.
+
+Look for patterns like:
+
+- `createPortal(...)`
+- modal, dialog, drawer, popover, tooltip, toast, or dropdown portal
+components
+- hard-coded roots such as `#portal-root`, `#modal-root`,
+`#drawer-root`, or `#toast-root`
+
+Example of what to copy:
+
+```tsx
+// real component
+return createPortal(<ModalContent />,
+document.getElementById("portal-root")!);
+```
+
+That means Storybook should create the same portal root in
+`.storybook/preview-body.html`:
+
+```html
+<!-- .storybook/preview-body.html -->
+<div id="portal-root"></div>
+```
+
+If the app uses multiple portal roots, create all of them there:
+
+```html
+<!-- .storybook/preview-body.html -->
+<div id="modal-root"></div>
+<div id="drawer-root"></div>
+<div id="toast-root"></div>
+```
+
+If a library portals directly to `document.body`, do not add extra
+roots for it.
+Make sure the copied page shell, CSS, and layout still allow overlays,
+fixed positioning, and z-index stacking to render correctly.
+
+### Step 4: Mock side effects globally
+
+All network/data queries should be handled by the default Storybook
+environment.
+
+- Always use `msw-storybook-addon` for query mocking.
+- If you introduce MSW, run `npx msw init ./public --save` to create
+the worker file.
+- Make sure Storybook serves `./public` as a static dir so
+`mockServiceWorker.js` is available.
+- Do not mock `fetch` directly.
+- Network/data queries should return deterministic mock data.
+- If you need to change dependencies, first check the lockfile and use
+that package manager for the change.
+
+Example of copying a real fetch pattern into shared handlers:
+
+```ts
+// real app hook
+const response = await fetch(
+apiBaseUrl +
+"/products?" +
+new URLSearchParams({
+page: "1",
+sort: "featured",
+}),
+);
+```
+
+```ts
+// .storybook/msw-handlers.ts
+import { http, HttpResponse } from "msw";
+
+export const mswHandlers = {
+products: [
+http.get("https://api.example.com/products",
+() =>
+HttpResponse.json({
+items: [
+{
+id: "product-1",
+name: "Example product",
+description: "Mock product description",
+imageUrl:
+"https://images.example.com/product.jpg",
+price: 42,
+},
+],
+}),
+),
+],
+};
+```
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { mswHandlers } from './msw-handlers';
+
+initialize({
+onUnhandledRequest: 'bypass',
+});
+
+const preview: Preview = {
+loaders: [mswLoader],
+parameters: {
+msw: {
+handlers: mswHandlers,
+},
+},
+};
+
+export default preview;
+```
+
+```ts
+// .storybook/main.ts
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+staticDirs: ["../public"],
+};
+
+export default config;
+```
+
+Keep these mocks global.
+Do not put fetch mocks in individual stories.
+Only add handlers for requests that the shared preview setup or the
+stories actually use.
+Do not add catch-all handlers that can hide unrelated failures.
+If the defaults are not enough, improve the shared default setup
+instead.
+Seed browser state when needed, but do not mock `window`, `document`,
+`navigator`, observers, or similar runtime APIs.
+The only exception is `mockdate` when date-based rendering exists.
+
+### Step 5: Write stories
+
+Try to find around 10 good candidate components for story files.
+Write colocated stories for top-level components, from low-level
+reusable components up to page components.
+Write up to 10 story files, or fewer only if the codebase clearly has
+fewer meaningful targets.
+
+The stories should use JSX copied from real usage patterns in:
+
+- pages
+- app shells
+- routes
+- tests
+- existing feature code
+
+As a rule of thumb, each story file should have around 3 story exports
+when the component or page has enough meaningful states.
+It can have more when the real usage supports it, up to 10 story
+exports in one file.
+
+Always show all imports explicitly in story and preview files.
+Do not rely on omitted or implied imports in examples or generated
+code.
+
+#### Story tags
+
+Every story meta must include the `ai-generated` tag to identify
+AI-created stories:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { SomeComponent } from './SomeComponent';
+
+const meta = {
+component: SomeComponent,
+tags: ['ai-generated'],
+} satisfies Meta<typeof SomeComponent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+render: () => <SomeComponent variant="primary" disabled={false} />,
+play: async ({ canvas }) => {
+await expect(canvas.getByRole('button')).toBeVisible();
+},
+};
+```
+
+If a story could not be fully fixed after the self-healing loop (the
+test still fails
+or the rendering is incomplete), add the `needs-work` tag alongside
+`ai-generated`:
+
+```ts
+const meta = {
+component: SomeComponent,
+tags: ['ai-generated', 'needs-work'],
+} satisfies Meta<typeof SomeComponent>;
+```
+
+Keep app mocking and runtime setup in preview, not in the stories.
+Do not build large story-specific harnesses.
+Do not write story files for subcomponents, hooks, contexts, or
+helpers.
+Do not create new application components.
+Do not add a custom `title`.
+Do not stop after only a few easy targets if the codebase has more
+meaningful components or pages available.
+
+### Step 6: Write a play function for every story
+
+Every named story export must have a `play` function.
+The `play` function is not optional, even for simple stories.
+
+The purpose of the `play` function is to prove that the story actually
+works in the copied Storybook environment:
+
+- the story renders something real and non-empty
+- the decorators provide the needed context
+- the CSS is applied well enough for the intended state to be visible
+- the MSW mocks or seeded browser state are actually being used
+- important interactions, async loading states, and portals behave
+correctly
+
+Use `play` functions to verify behavior, not just to click around.
+A story without assertions is incomplete.
+
+Use tools from `storybook/test` such as:
+
+- `expect`
+- `waitFor`
+
+Prefer `canvas` and `userEvent` from the `play` context.
+Do not destructure `canvasElement` just to create `const canvas =
+within(canvasElement)`.
+Do not import `userEvent` from `storybook/test`; use `userEvent` from
+the `play` context instead.
+Only use `canvasElement.ownerDocument` when you need to query outside
+the canvas, such as for portals.
+
+Example:
+
+```tsx
+import type { StoryObj } from "@storybook/react-vite";
+
+export const FilledForm: Story = {
+play: async ({ canvas, userEvent }) => {
+const emailInput = canvas.getByLabelText("email", {
+selector: "input",
+});
+
+await userEvent.type(emailInput, "example-email@email.com", {
+delay: 100,
+});
+
+const passwordInput = canvas.getByLabelText("password", {
+selector: "input",
+});
+
+await userEvent.type(passwordInput, "ExamplePassword", {
+delay: 100,
+});
+
+const submitButton = canvas.getByRole("button");
+await userEvent.click(submitButton);
+},
+};
+```
+
+The assertions should match the real pattern you copied:
+
+- for provider-backed stories, assert the provider-dependent UI
+appears correctly
+- for mocked-data stories, wait for the mocked data to appear and
+assert on it
+- for CSS-sensitive states, assert on visibility, text layout,
+class-driven states, or meaningful computed styles
+- for routing or navigation stories, assert the routed state or
+navigation outcome
+- for portal stories, query from `canvasElement.ownerDocument` when
+the UI renders outside the canvas
+
+Examples of useful checks:
+
+- a themed button has the expected label and is visibly enabled or
+disabled
+- a modal opened through a decorator or provider is visible in the
+portal root
+- mocked API data appears in the page instead of a loading spinner
+forever
+- a selected tab actually shows the selected panel
+- a toast, alert, or badge has the expected accessible text and visual
+state
+- a CSS class or computed style confirms the real state that matters
+
+### Step 7: Cover the patterns you found
+
+Write stories for the real patterns in the codebase, for example:
+
+- a low-level reusable component in real JSX usage
+- a provider-backed component
+- a browser-state-backed component
+- a fetched-data component
+- a real page component
+
+Use `App.tsx` to inspect the real provider tree and usage patterns,
+but do not make a story for `App` when the codebase has actual page
+components.
+
+Example page story:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { ProductPage } from './ProductPage';
+
+const meta = {
+component: ProductPage,
+tags: ['ai-generated'],
+} satisfies Meta<typeof ProductPage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+render: () => <ProductPage />,
+play: async ({ canvas }) => {
+await expect(
+canvas.getByRole('heading', { name: /products/i }),
+).toBeVisible();
+},
+};
+```
+
+### Step 8: Verify both rendering and types
+
+As you work, verify the stories with Vitest:
+
+```bash
+npx vitest --project storybook <path-to-story-file>
+```
+
+Also verify types so you catch missing required props, broken imports,
+and preview typing issues. Run the same TypeScript command the project
+itself uses.
+
+```bash
+<project-specific-typescript-command>
+```
+
+After verification passes, review every changed file and remove
+anything that is not needed for the final solution, especially debug
+fixes, overly broad mocks, unnecessary dependencies, and eval
+artifacts.
+
+Keep iterating until:
+
+- every story you wrote passes
+- every story you wrote has a meaningful passing `play` function
+- the changed stories and preview setup pass the project's real
+TypeScript check
+- the rendered output looks sensible
+- the default global mocked environment is strong enough that stories
+do not need manual fetch overrides
+- stories no longer fail because the shared preview setup and story
+JSX are fixed
+- all passing stories have `tags: ['ai-generated']` in their meta
+- any stories that still need work have `tags: ['ai-generated',
+'needs-work']` in their meta

From ee0c5e1a8427c889542582eb57fb27c15d76fe5c Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <Sidnioulz@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:27:35 +0200
Subject: [PATCH 05/24] Apply suggestion from @Sidnioulz

---
 code/lib/cli-storybook/src/ai/prompt.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/prompt.ts
index 3b25b7349a7b..630f03ece738 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/prompt.ts
@@ -29,7 +29,7 @@ export function getPrompts(projectInfo: ProjectInfo): {
     prompts: [
       {
         name: 'setup',
-        description: 'Set up Storybook for success',
+        description: 'Configure Storybook for your codebase and write sample stories',
         instructions: getSetupInstructions(projectInfo),
       },
     ],

From 712228e5b2259cdab816784a2ba7085f2c5dac1a Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Wed, 29 Apr 2026 21:59:24 +0200
Subject: [PATCH 06/24] Improve package manager code handling in ai setup

---
 .../src/common/js-package-manager/BUNProxy.ts |  8 ++++
 .../js-package-manager/JsPackageManager.ts    |  6 +++
 .../src/common/js-package-manager/NPMProxy.ts |  8 ++++
 .../common/js-package-manager/PNPMProxy.ts    |  8 ++++
 .../common/js-package-manager/Yarn1Proxy.ts   |  8 ++++
 .../common/js-package-manager/Yarn2Proxy.ts   |  8 ++++
 code/lib/cli-storybook/src/ai/index.ts        |  9 +++--
 code/lib/cli-storybook/src/ai/prompt.ts       | 37 ++++++-------------
 code/lib/cli-storybook/src/ai/types.ts        |  7 +++-
 scripts/eval/prompts/optimized-tests.md       | 11 +++---
 10 files changed, 72 insertions(+), 38 deletions(-)

diff --git a/code/core/src/common/js-package-manager/BUNProxy.ts b/code/core/src/common/js-package-manager/BUNProxy.ts
index 47b8ffeab333..897ab8a28784 100644
--- a/code/core/src/common/js-package-manager/BUNProxy.ts
+++ b/code/core/src/common/js-package-manager/BUNProxy.ts
@@ -75,6 +75,14 @@ export class BUNProxy extends JsPackageManager {
     return executeCommand({ command: 'bun', args: ['init'] });
   }
 
+  getCommandName(): string {
+    return 'npm';
+  }
+
+  getInstallCommand(deps: string[], dev: boolean): string {
+    return `bun add ${dev ? '-D ' : ''}${deps.join(' ')}`;
+  }
+
   getRunStorybookCommand(): string {
     return 'bun run storybook';
   }
diff --git a/code/core/src/common/js-package-manager/JsPackageManager.ts b/code/core/src/common/js-package-manager/JsPackageManager.ts
index 6e9453f202f0..61a75385c4a5 100644
--- a/code/core/src/common/js-package-manager/JsPackageManager.ts
+++ b/code/core/src/common/js-package-manager/JsPackageManager.ts
@@ -136,6 +136,12 @@ export abstract class JsPackageManager {
     this.primaryPackageJson = this.#getPrimaryPackageJson();
   }
 
+  /** Returns the name of the command to invoke this package manager. */
+  abstract getCommandName(): string;
+
+  /** Installs package dependencies. */
+  abstract getInstallCommand(deps: string[], dev?: boolean): string;
+
   /** Runs arbitrary package scripts (as a string for display). */
   abstract getRunCommand(command: string): string;
 
diff --git a/code/core/src/common/js-package-manager/NPMProxy.ts b/code/core/src/common/js-package-manager/NPMProxy.ts
index 8aee0ee4408e..521da495cc25 100644
--- a/code/core/src/common/js-package-manager/NPMProxy.ts
+++ b/code/core/src/common/js-package-manager/NPMProxy.ts
@@ -72,6 +72,14 @@ export class NPMProxy extends JsPackageManager {
 
   installArgs: string[] | undefined;
 
+  getCommandName(): string {
+    return 'npm';
+  }
+
+  getInstallCommand(deps: string[], dev: boolean): string {
+    return `npm install ${dev ? '-D ' : ''}${deps.join(' ')}`;
+  }
+
   getRunCommand(command: string): string {
     return `npm run ${command}`;
   }
diff --git a/code/core/src/common/js-package-manager/PNPMProxy.ts b/code/core/src/common/js-package-manager/PNPMProxy.ts
index db0ce442bc38..1b47f92ba115 100644
--- a/code/core/src/common/js-package-manager/PNPMProxy.ts
+++ b/code/core/src/common/js-package-manager/PNPMProxy.ts
@@ -49,6 +49,14 @@ export class PNPMProxy extends JsPackageManager {
     return existsSync(pnpmWorkspaceYaml);
   }
 
+  getCommandName(): string {
+    return 'pnpm';
+  }
+
+  getInstallCommand(deps: string[], dev: boolean): string {
+    return `pnpm add ${dev ? '-D ' : ''}${deps.join(' ')}`;
+  }
+
   getRunCommand(command: string): string {
     return `pnpm run ${command}`;
   }
diff --git a/code/core/src/common/js-package-manager/Yarn1Proxy.ts b/code/core/src/common/js-package-manager/Yarn1Proxy.ts
index ef078ded5ec9..ee22c848d6a6 100644
--- a/code/core/src/common/js-package-manager/Yarn1Proxy.ts
+++ b/code/core/src/common/js-package-manager/Yarn1Proxy.ts
@@ -46,10 +46,18 @@ export class Yarn1Proxy extends JsPackageManager {
     return this.installArgs;
   }
 
+  getCommandName(): string {
+    return 'yarn';
+  }
+
   getRunCommand(command: string): string {
     return `yarn ${command}`;
   }
 
+  getInstallCommand(deps: string[], dev: boolean): string {
+    return `yarn add ${dev ? '-D ' : ''}${deps.join(' ')}`;
+  }
+
   getPackageCommand(args: string[]): string {
     const [command, ...rest] = args;
     return `yarn exec ${command} -- ${rest.join(' ')}`;
diff --git a/code/core/src/common/js-package-manager/Yarn2Proxy.ts b/code/core/src/common/js-package-manager/Yarn2Proxy.ts
index ba4f25bd1a67..14e55c50be5c 100644
--- a/code/core/src/common/js-package-manager/Yarn2Proxy.ts
+++ b/code/core/src/common/js-package-manager/Yarn2Proxy.ts
@@ -90,10 +90,18 @@ export class Yarn2Proxy extends JsPackageManager {
     return this.installArgs;
   }
 
+  getCommandName(): string {
+    return 'yarn';
+  }
+
   getRunCommand(command: string): string {
     return `yarn ${command}`;
   }
 
+  getInstallCommand(deps: string[], dev: boolean): string {
+    return `yarn add ${dev ? '-D ' : ''}${deps.join(' ')}`;
+  }
+
   getPackageCommand(args: string[]): string {
     return `yarn exec ${args.join(' ')}`;
   }
diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index 501953c30cf1..cdf5b24844a8 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -21,14 +21,14 @@ import { generateMarkdownOutput } from './prompt.ts';
 import type { ProjectInfo, AiSetupOptions } from './types.ts';
 
 export async function aiSetup(options: AiSetupOptions): Promise<void> {
-  const { configDir: userConfigDir, packageManager: packageManagerName, output } = options;
+  const { configDir: userConfigDir, packageManager, output } = options;
 
   let projectInfo: ProjectInfo;
 
   try {
     const data = await getStorybookData({
       configDir: userConfigDir,
-      packageManagerName: packageManagerName as PackageManagerName | undefined,
+      packageManagerName: packageManager as PackageManagerName | undefined,
     });
 
     if (!data.frameworkPackage || !data.rendererPackage || !data.builderPackage) {
@@ -56,7 +56,8 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
       addons: data.addons ?? [],
       configDir: data.configDir,
       storiesPaths: data.storiesPaths,
-      packageManager: getPrettyPackageManagerName(packageManagerName),
+      packageManager: data.packageManager,
+      packageManagerName: getPrettyPackageManagerName(data.packageManager.type),
       language,
     };
   } catch (err) {
@@ -89,7 +90,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     cliOptions: {
       output: output ? 'file' : undefined,
       configDir: projectInfo.configDir,
-      packageManager: packageManagerName,
+      packageManager: projectInfo.packageManager.type,
     },
     project: {
       framework: projectInfo.framework,
diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/prompt.ts
index 630f03ece738..af430c41a4d4 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/prompt.ts
@@ -1,4 +1,3 @@
-import { SupportedRenderer } from 'storybook/internal/types';
 import { dedent } from 'ts-dedent';
 
 import type { AiPrompt, ProjectInfo } from './types.ts';
@@ -43,37 +42,23 @@ function ext(language: 'ts' | 'js', jsx: boolean): string {
   return jsx ? 'jsx' : 'js';
 }
 
-function installCommand(packageManager: string | undefined, deps: string, dev = false): string {
-  switch (packageManager) {
-    case 'yarn':
-    case 'yarn1':
-    case 'yarn2':
-      return `yarn add ${dev ? '--dev ' : ''}${deps}`;
-    case 'pnpm':
-      return `pnpm add ${dev ? '-D ' : ''}${deps}`;
-    case 'bun':
-      return `bun add ${dev ? '-d ' : ''}${deps}`;
-    case 'npm':
-      return `npm install ${dev ? '--save-dev ' : ''}${deps}`;
-    default:
-      return `<your-package-manager> add ${dev ? '-D ' : ''}${deps}`;
-  }
-}
-
-function packageManagerRule(packageManager: string | undefined): string {
-  if (packageManager) {
-    return `**Use \`${packageManager}\` for every install** (detected from this project's lockfile).`;
+function packageManagerRule(packageManagerName: string | undefined): string {
+  if (packageManagerName) {
+    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
   }
   return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
 }
 
 function getSetupInstructions(projectInfo: ProjectInfo): string {
-  const { configDir, language, packageManager } = projectInfo;
+  const { configDir, language, packageManager, packageManagerName } = projectInfo;
   const tsx = ext(language, true);
   const ts = ext(language, false);
   const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
 
-  const mswInstall = installCommand(packageManager, 'msw msw-storybook-addon mockdate', true);
+  const mswInstall = packageManager.getInstallCommand(
+    ['msw', 'msw-storybook-addon', 'mockdate'],
+    true
+  );
 
   return dedent`
     Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
@@ -89,7 +74,7 @@ function getSetupInstructions(projectInfo: ProjectInfo): string {
     3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
     4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
     5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-    6. ${packageManagerRule(packageManager)}
+    6. ${packageManagerRule(packageManagerName)}
     7. **Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.
     8. **Stop when the success criteria are met** — don't keep polishing.
 
@@ -249,7 +234,7 @@ function getSetupInstructions(projectInfo: ProjectInfo): string {
     npx vitest --project storybook run
     \`\`\`
 
-    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager ?? '<pm>'} run typecheck\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
 
     For each failure:
 
@@ -495,7 +480,7 @@ function getProjectOverview(projectInfo: ProjectInfo): string {
   ];
 
   if (projectInfo.packageManager) {
-    rows.push(['Package Manager', projectInfo.packageManager]);
+    rows.push(['Package Manager', projectInfo.packageManagerName || 'unknown']);
   }
 
   rows.push(['Addons', projectInfo.addons.length > 0 ? projectInfo.addons.join(', ') : 'none']);
diff --git a/code/lib/cli-storybook/src/ai/types.ts b/code/lib/cli-storybook/src/ai/types.ts
index 7c54bd88d042..bc4914a6f7b3 100644
--- a/code/lib/cli-storybook/src/ai/types.ts
+++ b/code/lib/cli-storybook/src/ai/types.ts
@@ -1,3 +1,4 @@
+import type { JsPackageManager } from 'storybook/internal/common';
 import type { SupportedRenderer } from 'storybook/internal/types';
 
 export interface AiSetupOptions {
@@ -22,8 +23,10 @@ export interface ProjectInfo {
   storiesPaths: string[];
   /** Whether the project uses TypeScript ('ts') or JavaScript ('js'), inferred from the main config file extension. */
   language: 'ts' | 'js';
-  /** Detected package manager name (npm, yarn, pnpm, bun), if known. */
-  packageManager?: string;
+  /** Detected package manager (npm, yarn, pnpm, bun), if known. */
+  packageManager: JsPackageManager;
+  /** Pretty name of the detected package manager, if known. */
+  packageManagerName?: string;
 }
 
 /**
diff --git a/scripts/eval/prompts/optimized-tests.md b/scripts/eval/prompts/optimized-tests.md
index 5d604a8c79ec..6a5a1f12859f 100644
--- a/scripts/eval/prompts/optimized-tests.md
+++ b/scripts/eval/prompts/optimized-tests.md
@@ -10,24 +10,23 @@
 | Builder | @storybook/builder-vite |
 | Config Dir | `.storybook` |
 | Language | TypeScript |
-| Package Manager | yarn |
+| Package Manager | Yarn Berry |
 | Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
 
 Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
 
 ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
-1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Concrete substitutions, no exceptions:
+1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
     - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
     - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
     - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
     - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
-
 2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
 3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
 4. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
 5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-6. **Use `yarn` for every install** (detected from this project's lockfile).
+6. **Use `Yarn Berry` for every install** (detected from this project's lockfile).
 7. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
 8. **Stop when the success criteria are met** — don't keep polishing.
 
@@ -118,7 +117,7 @@ Add this decorator to the `decorators` array of your preview config. Skip this s
 Use `msw-storybook-addon`. Install with:
 
 ```bash
-yarn add --dev msw msw-storybook-addon mockdate
+yarn add -D msw msw-storybook-addon mockdate
 npx msw init ./public --save
 ```
 
@@ -266,7 +265,7 @@ export const FilledForm: Story = {
 npx vitest --project storybook run
 ```
 
-Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn run typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
+Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
 
 For each failure:
 

From ec3426415b4f9ec67c6160d0aa47bbca22e3bdcb Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 10:14:52 +0200
Subject: [PATCH 07/24] Mock package manager in AI tests

---
 code/lib/cli-storybook/src/ai/index.test.ts | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/code/lib/cli-storybook/src/ai/index.test.ts b/code/lib/cli-storybook/src/ai/index.test.ts
index d483b5833cef..706bd5960f6c 100644
--- a/code/lib/cli-storybook/src/ai/index.test.ts
+++ b/code/lib/cli-storybook/src/ai/index.test.ts
@@ -42,7 +42,19 @@ vi.mock('../automigrate/helpers/mainConfigFile.ts', () => ({
     configDir: '/proj/.storybook',
     storiesPaths: [],
     hasCsfFactoryPreview: false,
-    packageManager: {},
+    packageManager: {
+      type: 'npm',
+      version: '9.5.0',
+      getCommandName(): string {
+        return 'npm';
+      },
+      getInstallCommand(deps: string[], dev: boolean): string {
+        return `npm install ${dev ? '-D ' : ''}${deps.join(' ')}`;
+      },
+      getRunCommand(command: string): string {
+        return `npm run ${command}`;
+      },
+    },
   }),
 }));
 

From 21af0fa4944e6a4e98287246c2a693f191527e0d Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 10:31:34 +0200
Subject: [PATCH 08/24] reformat this file AGAIN

---
 docs/configure/integration/eslint-plugin.mdx | 30 ++++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/configure/integration/eslint-plugin.mdx b/docs/configure/integration/eslint-plugin.mdx
index 9990fe924ecc..1e20b0ce2714 100644
--- a/docs/configure/integration/eslint-plugin.mdx
+++ b/docs/configure/integration/eslint-plugin.mdx
@@ -39,10 +39,10 @@ For more details on why this line is required in the `.eslintignore` file, refer
 If you are using [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new), add this to your configuration file:
 
 ```js title="eslint.config.js"
-import { defineConfig, globalIgnores } from "eslint/config";
+import { defineConfig, globalIgnores } from 'eslint/config';
 
 export default defineConfig([
-  globalIgnores(["!.storybook"], "Include Storybook Directory"),
+  globalIgnores(['!.storybook'], 'Include Storybook Directory'),
   // ...
 ]);
 ```
@@ -91,12 +91,12 @@ Optionally, you can override, add to, or disable individual rules. You likely do
 Use the `eslint.config.js` file to configure rules using the [flat config style](https://eslint.org/docs/latest/use/configure/configuration-files-new). This is the default in ESLint v9, but can be used starting from ESLint v8.57.0. [ESLint docs](https://eslint.org/docs/latest/use/configure/configuration-files-new).
 
 ```js title="eslint.config.js"
-import storybook from "eslint-plugin-storybook";
+import storybook from 'eslint-plugin-storybook';
 // Replace the eslint/config package with @eslint/config-helpers if you're using an older version of ESLint.
-import { defineConfig } from "eslint/config";
+import { defineConfig } from 'eslint/config';
 
 export default defineConfig([
-  ...storybook.configs["flat/recommended"],
+  ...storybook.configs['flat/recommended'],
   // Add more configuration options and generic rulesets here, such as js.configs.recommended
 ]);
 ```
@@ -104,13 +104,13 @@ export default defineConfig([
 In case you are using utility functions from tools like `tseslint`, you might need to register the plugin a little differently:
 
 ```ts title="eslint.config.ts"
-import storybook from "eslint-plugin-storybook";
-import somePlugin from "some-plugin";
-import tseslint from "typescript-eslint";
+import storybook from 'eslint-plugin-storybook';
+import somePlugin from 'some-plugin';
+import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
   somePlugin,
-  storybook.configs["flat/recommended"], // notice that it is not destructured
+  storybook.configs['flat/recommended'], // notice that it is not destructured
 );
 ```
 
@@ -119,19 +119,19 @@ export default tseslint.config(
 Optionally, you can override, add, or disable individual rules. You likely don't want these settings to be applied to every file, so ensure that you add a flat config section in your `eslint.config.js` file that applies the overrides only to your story files.
 
 ```js title="eslint.config.js"
-import storybook from "eslint-plugin-storybook";
-import { defineConfig } from "eslint/config";
+import storybook from 'eslint-plugin-storybook';
+import { defineConfig } from 'eslint/config';
 
 export default defineConfig([
-  ...storybook.configs["flat/recommended"],
+  ...storybook.configs['flat/recommended'],
   {
     // 👇 This should match the `stories` property in .storybook/main.js|ts
-    files: ["**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)"],
+    files: ['**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)'],
     rules: {
       // 👇 Enable this rule
-      "storybook/csf-component": "error",
+      'storybook/csf-component': 'error',
       // 👇 Disable this rule
-      "storybook/default-exports": "off",
+      'storybook/default-exports': 'off',
     },
   },
 ]);

From 97ca530b782c6c7bc0e2b6a38d78602f52644f20 Mon Sep 17 00:00:00 2001
From: yannbf <yannbf@gmail.com>
Date: Thu, 30 Apr 2026 10:56:13 +0200
Subject: [PATCH 09/24] fix types

---
 .../core-server/server-channel/telemetry-channel.test.ts  | 2 +-
 .../src/core-server/server-channel/telemetry-channel.ts   | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/code/core/src/core-server/server-channel/telemetry-channel.test.ts b/code/core/src/core-server/server-channel/telemetry-channel.test.ts
index d3c664818ddc..3236de948d93 100644
--- a/code/core/src/core-server/server-channel/telemetry-channel.test.ts
+++ b/code/core/src/core-server/server-channel/telemetry-channel.test.ts
@@ -24,7 +24,7 @@ describe('telemetry-channel', () => {
         },
       } as any;
 
-      initTelemetryChannel(channel, { disableTelemetry: false } as any);
+      initTelemetryChannel(channel);
 
       const payload = {
         trigger: 'interaction' as const,
diff --git a/code/core/src/core-server/server-channel/telemetry-channel.ts b/code/core/src/core-server/server-channel/telemetry-channel.ts
index c6acbf575ebb..0a3b4cafaa9b 100644
--- a/code/core/src/core-server/server-channel/telemetry-channel.ts
+++ b/code/core/src/core-server/server-channel/telemetry-channel.ts
@@ -1,11 +1,11 @@
 import type { Channel } from 'storybook/internal/channels';
 import {
-  AI_PROMPT_NUDGE,
   PREVIEW_INITIALIZED,
   SHARE_ISOLATE_MODE,
   SHARE_POPOVER_OPENED,
   SHARE_STORY_LINK,
   SIDEBAR_FILTER_CHANGED,
+  AI_PROMPT_NUDGE,
 } from 'storybook/internal/core-events';
 import { type InitPayload, telemetry } from 'storybook/internal/telemetry';
 import { type CacheEntry, getLastEvents } from 'storybook/internal/telemetry';
@@ -52,10 +52,10 @@ export function initTelemetryChannel(channel: Channel) {
   channel.on(SHARE_ISOLATE_MODE, async () => {
     telemetry('share', { action: 'isolate-mode-opened' });
   });
-  channel.on(AI_PROMPT_NUDGE, async ({ id, origin }: { id: string; origin: string }) => {
-    telemetry('ai-prompt-nudge', { id, origin });
-  });
   channel.on(SIDEBAR_FILTER_CHANGED, (payload) => {
     telemetry('sidebar-filter', payload);
   });
+  channel.on(AI_PROMPT_NUDGE, async ({ id, origin }: { id: string; origin: string }) => {
+    telemetry('ai-prompt-nudge', { id, origin });
+  });
 }

From 08b6cd256db3d93067a6778a7ac6b5ba0842945e Mon Sep 17 00:00:00 2001
From: yannbf <yannbf@gmail.com>
Date: Thu, 30 Apr 2026 11:40:17 +0200
Subject: [PATCH 10/24] use the new prompt format

---
 code/lib/cli-storybook/src/ai/index.ts        |   3 +-
 code/lib/cli-storybook/src/ai/prompt.ts       | 477 +-----------------
 .../src/ai/setup-prompts/index.ts             |   7 +-
 .../src/ai/setup-prompts/optimized-tests.ts   | 470 +++++++++++++++++
 code/lib/cli-storybook/src/ai/types.ts        |   2 +
 5 files changed, 482 insertions(+), 477 deletions(-)
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts

diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index cdf5b24844a8..8c0761dec538 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -59,6 +59,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
       packageManager: data.packageManager,
       packageManagerName: getPrettyPackageManagerName(data.packageManager.type),
       language,
+      hasCsfFactoryPreview: data.hasCsfFactoryPreview,
     };
   } catch (err) {
     logger.error(
@@ -83,7 +84,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     return;
   }
 
-  const result = await generateMarkdownOutput('Storybook Setup', projectInfo);
+  const result = await generateMarkdownOutput(projectInfo);
   const markdownOutput = result.markdown;
 
   await telemetry('ai-setup', {
diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/prompt.ts
index af430c41a4d4..0f079f731883 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/prompt.ts
@@ -1,473 +1,7 @@
 import { dedent } from 'ts-dedent';
 
-import type { AiPrompt, ProjectInfo } from './types.ts';
-
-/**
- * Builds a markdown-format docs URL with renderer and language query parameters.
- * Appending .md to any Storybook docs URL returns clean markdown with code examples.
- */
-export function getDocsMarkdownUrl(
-  path: string,
-  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
-): string {
-  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
-  const versionSegment = majorVersion ? `/${majorVersion}` : '';
-  const params = new URLSearchParams();
-  if (renderer) {
-    params.set('renderer', renderer);
-  }
-  params.set('language', language);
-  const query = params.toString();
-  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
-}
-
-export function getPrompts(projectInfo: ProjectInfo): {
-  prompts: AiPrompt[];
-} {
-  return {
-    prompts: [
-      {
-        name: 'setup',
-        description: 'Configure Storybook for your codebase and write sample stories',
-        instructions: getSetupInstructions(projectInfo),
-      },
-    ],
-  };
-}
-
-function ext(language: 'ts' | 'js', jsx: boolean): string {
-  if (language === 'ts') {
-    return jsx ? 'tsx' : 'ts';
-  }
-  return jsx ? 'jsx' : 'js';
-}
-
-function packageManagerRule(packageManagerName: string | undefined): string {
-  if (packageManagerName) {
-    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
-  }
-  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
-}
-
-function getSetupInstructions(projectInfo: ProjectInfo): string {
-  const { configDir, language, packageManager, packageManagerName } = projectInfo;
-  const tsx = ext(language, true);
-  const ts = ext(language, false);
-  const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
-
-  const mswInstall = packageManager.getInstallCommand(
-    ['msw', 'msw-storybook-addon', 'mockdate'],
-    true
-  );
-
-  return dedent`
-    Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
-
-    ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
-
-    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-        - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
-        - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
-        - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
-        - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.
-    2. **Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.
-    3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
-    4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
-    5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-    6. ${packageManagerRule(packageManagerName)}
-    7. **Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.
-    8. **Stop when the success criteria are met** — don't keep polishing.
-
-    ## Plan (do not skip steps, but keep each step lean)
-
-    ### Step 1 — Discover the runtime (≤12 reads)
-
-    Identify, in this order, using Glob/Grep first then targeted Reads:
-
-    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
-    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
-    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
-    - providers / context files — what they expose
-    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
-    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
-    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
-    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
-    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-    ### Step 2 — Build the shared preview
-
-    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
-
-    The complete shape should look like this (merge the new pieces into what's already there):
-
-    ${getPreviewExample(projectInfo)}
-
-    Rules for the preview:
-
-    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
-    - Use \`mockdate\` only when render output depends on the date.
-    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
-
-    ### Step 3 — Portals (in a decorator, not preview-body.html)
-
-    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
-
-    ${getPortalDecoratorExample(projectInfo)}
-
-    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
-
-    ### Step 4 — MSW handlers (only what stories will hit)
-
-    Use \`msw-storybook-addon\`. Install with:
-
-    \`\`\`bash
-    ${mswInstall}
-    npx msw init ./public --save
-    \`\`\`
-
-    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
-
-    ${getMainConfigExample(projectInfo)}
-
-    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-    \`\`\`${ts}
-    // ${configDir}/msw-handlers.${ts}
-    import { http, HttpResponse } from 'msw';
-
-    export const mswHandlers = {
-      products: [
-        http.get('https://api.example.com/products', () =>
-          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-        ),
-      ],
-    };
-    \`\`\`
-
-    ### Step 5 — Write up to 10 story files (in one batch)
-
-    The deliverable for this step is **two things, both required**:
-
-    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
-    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
-
-    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-    ${getStoryExample(projectInfo)}
-
-    Story rules:
-
-    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
-    - Show all imports explicitly.
-    - Don't add a custom \`title\`.
-    - Don't build large story-specific harnesses — fix preview instead.
-    - Don't create new app components.
-
-    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
-
-    \`\`\`${tsx}
-    export const CssCheck: Story = {
-      args: { children: 'Submit' },
-      play: async ({ canvas }) => {
-        const button = canvas.getByRole('button', { name: /submit/i });
-        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-      },
-    };
-    \`\`\`
-
-    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
-
-    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
-
-    Write a \`play\` when it can verify:
-
-    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
-    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-    - **accessibility** that the component is responsible for (correct role/label exposure)
-
-    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
-    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
-    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
-    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
-
-    If none of those apply, skip the \`play\` and rely on the render itself.
-
-    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
-
-    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
-    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
-
-    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
-
-    Imports & play context — get this right or vitest will fail in subtle ways:
-
-    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
-    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
-    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
-
-    ${getInteractionPlayExample(projectInfo)}
-
-    ### Step 7 — Verify in one batch, then iterate only on failures
-
-    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-    \`\`\`bash
-    npx vitest --project storybook run
-    \`\`\`
-
-    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
-
-    For each failure:
-
-    1. Read the error.
-    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
-    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
-
-    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
-
-    ### Step 8 — Clean up
-
-    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
-
-    ## Done when
-
-    - **Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
-    - Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.
-    - \`npx vitest --project storybook run\` passes for the new files.
-    - The project's TypeScript check passes for changed files.
-    - The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
-
-    ## Reference (only fetch if stuck)
-
-    - Docs index: https://storybook.js.org/llms.txt
-    - Writing stories: ${docsUrl('writing-stories')}
-    - Decorators: ${docsUrl('writing-stories/decorators')}
-    - Play functions: ${docsUrl('writing-stories/play-function')}
-    - Vitest integration: ${docsUrl('writing-tests/vitest-plugin')}
-
-    Append \`?codeOnly=true\` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
-  `;
-}
-
-function getPreviewExample(projectInfo: ProjectInfo): string {
-  const { configDir, language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      // ${configDir}/preview.${tsx}
-      import '../src/index.css';
-      import MockDate from 'mockdate';
-      import { initialize, mswLoader } from 'msw-storybook-addon';
-      import { SessionProvider } from '../src/contexts/SessionContext';
-      import { mswHandlers } from './msw-handlers';
-
-      initialize({ onUnhandledRequest: 'bypass' });
-
-      const preview = {
-        decorators: [
-          (Story) => (
-            <SessionProvider>
-              <Story />
-            </SessionProvider>
-          ),
-        ],
-        loaders: [mswLoader],
-        parameters: { msw: { handlers: mswHandlers } },
-        async beforeEach() {
-          localStorage.setItem('theme', 'dark');
-          MockDate.set('2024-04-01T12:00:00Z');
-        },
-      };
-
-      export default preview;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    // ${configDir}/preview.${tsx}
-    import type { Preview } from '${typeImport}';
-    import '../src/index.css';
-    import MockDate from 'mockdate';
-    import { initialize, mswLoader } from 'msw-storybook-addon';
-    import { SessionProvider } from '../src/contexts/SessionContext';
-    import { mswHandlers } from './msw-handlers';
-
-    initialize({ onUnhandledRequest: 'bypass' });
-
-    const preview: Preview = {
-      decorators: [
-        (Story) => (
-          <SessionProvider>
-            <Story />
-          </SessionProvider>
-        ),
-      ],
-      loaders: [mswLoader],
-      parameters: { msw: { handlers: mswHandlers } },
-      async beforeEach() {
-        localStorage.setItem('theme', 'dark');
-        MockDate.set('2024-04-01T12:00:00Z');
-      },
-    };
-
-    export default preview;
-    \`\`\`
-  `;
-}
-
-function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-
-  return dedent`
-    \`\`\`${tsx}
-    // Add this entry to the \`decorators\` array of your preview config:
-    (Story) => {
-      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-        if (!document.getElementById(id)) {
-          const el = document.createElement('div');
-          el.id = id;
-          document.body.appendChild(el);
-        }
-      }
-      return <Story />;
-    }
-    \`\`\`
-  `;
-}
-
-function getMainConfigExample(projectInfo: ProjectInfo): string {
-  const { configDir, framework, rendererPackage, language } = projectInfo;
-  const ts = ext(language, false);
-  const typeImport = framework || rendererPackage || '@storybook/react';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`js
-      // ${configDir}/main.js
-      const config = { staticDirs: ['../public'] };
-      export default config;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${ts}
-    // ${configDir}/main.${ts}
-    import type { StorybookConfig } from '${typeImport}';
-
-    const config: StorybookConfig = { staticDirs: ['../public'] };
-    export default config;
-    \`\`\`
-  `;
-}
-
-function getStoryExample(projectInfo: ProjectInfo): string {
-  const { language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      import { expect } from 'storybook/test';
-      import { Button } from './Button';
-
-      const meta = {
-        component: Button,
-        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-      };
-
-      export default meta;
-
-      // Smoke check — one is enough per file
-      export const Primary = {
-        args: { children: 'Order now' },
-        play: async ({ canvas }) => {
-          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-        },
-      };
-
-      // Variant-only stories: no play needed
-      export const Clear = { args: { children: 'Cancel', clear: true } };
-      export const Large = { args: { children: 'Checkout', large: true } };
-      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    import type { Meta, StoryObj } from '${typeImport}';
-    import { expect } from 'storybook/test';
-    import { Button } from './Button';
-
-    const meta = {
-      component: Button,
-      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-    } satisfies Meta<typeof Button>;
-
-    export default meta;
-    type Story = StoryObj<typeof meta>;
-
-    // Smoke check — one is enough per file
-    export const Primary: Story = {
-      args: { children: 'Order now' },
-      play: async ({ canvas }) => {
-        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-      },
-    };
-
-    // Variant-only stories: no play needed
-    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-    export const Large: Story = { args: { children: 'Checkout', large: true } };
-    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-    \`\`\`
-  `;
-}
-
-function getInteractionPlayExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-  const typeAnnotation = language === 'ts' ? ': Story' : '';
-
-  return dedent`
-    \`\`\`${tsx}
-    export const FilledForm${typeAnnotation} = {
-      play: async ({ canvas, userEvent }) => {
-        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-      },
-    };
-    \`\`\`
-  `;
-}
+import { getPrompts } from './setup-prompts/index.ts';
+import type { ProjectInfo } from './types.ts';
 
 function getProjectOverview(projectInfo: ProjectInfo): string {
   const rows: Array<[string, string]> = [
@@ -492,10 +26,7 @@ function getProjectOverview(projectInfo: ProjectInfo): string {
   );
 }
 
-export async function generateMarkdownOutput(
-  title: string,
-  projectInfo: ProjectInfo
-): Promise<{
+export async function generateMarkdownOutput(projectInfo: ProjectInfo): Promise<{
   markdown: string;
 }> {
   const { prompts: aiPrompts } = await getPrompts(projectInfo);
@@ -503,7 +34,7 @@ export async function generateMarkdownOutput(
   const sections: string[] = [];
 
   sections.push(dedent`
-    # ${title}
+    # Storybook Setup
   `);
 
   sections.push(getProjectOverview(projectInfo));
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
index ab8d1a7c3905..ed780fa3324f 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
@@ -1,12 +1,12 @@
 import type { AiPrompt, ProjectInfo } from '../types.ts';
 
-import * as patternCopyPlay from './pattern-copy-play.ts';
+import * as optimizedTests from './optimized-tests.ts';
 
 /**
  * Main prompt used currently in `npx storybook ai setup` command. If you promote a new prompt to be default, move this to the FORMERLY_USED_PROMPTS object below.
  */
 const CURRENTLY_USED_PROMPT: Record<string, (projectInfo: ProjectInfo) => string> = {
-  'pattern-copy-play': patternCopyPlay.instructions,
+  'optimized-tests': optimizedTests.instructions,
 };
 
 /**
@@ -16,6 +16,7 @@ const CURRENTLY_USED_PROMPT: Record<string, (projectInfo: ProjectInfo) => string
  */
 const FORMERLY_USED_PROMPTS: Record<string, () => Promise<(projectInfo: ProjectInfo) => string>> = {
   setup: async () => (await import('./setup.ts')).instructions,
+  'pattern-copy-play': async () => (await import('./pattern-copy-play.ts')).instructions,
 };
 
 export type PromptName = string;
@@ -30,7 +31,7 @@ export const PROMPT_NAMES: PromptName[] = [
  * The single prompt variant that ships to real users. Running
  * `npx storybook ai setup` without any overrides always produces this prompt.
  */
-export const DEFAULT_PROMPT_NAME: PromptName = 'pattern-copy-play';
+export const DEFAULT_PROMPT_NAME: PromptName = 'optimized-tests';
 
 /**
  * Internal env var read only by `getPrompts`. The eval harness sets this
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
new file mode 100644
index 000000000000..5ad50780e1cd
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
@@ -0,0 +1,470 @@
+/**
+ * Prompt variant: `optimized-tests`
+ *
+ * - Created: 2026-04-28 (eval iteration 3, experimental — successor to
+ *   `pattern-copy-play` focused on tighter rules-of-engagement, MSW setup,
+ *   and a stricter "smoke plays must prove something" policy in Step 6).
+ * - Status: experimental — not the default. Selected only when the eval
+ *   harness sets `EVAL_SETUP_PROMPT=optimized-tests`.
+ * - Reference eval results:
+ *   https://github.com/search?q=is:pr label:"prompt:optimized-tests" org:storybook-tmp&type=pullrequests
+ *
+ * Update this header when iterating: bump the iteration number and link the
+ * latest eval run so reviewers can compare variants without spelunking git.
+ */
+import { dedent } from 'ts-dedent';
+
+import type { ProjectInfo } from '../types.ts';
+
+/**
+ * Builds a markdown-format docs URL with renderer and language query parameters.
+ * Appending .md to any Storybook docs URL returns clean markdown with code examples.
+ */
+function getDocsMarkdownUrl(
+  path: string,
+  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
+): string {
+  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
+  const versionSegment = majorVersion ? `/${majorVersion}` : '';
+  const params = new URLSearchParams();
+  if (renderer) {
+    params.set('renderer', renderer);
+  }
+  params.set('language', language);
+  const query = params.toString();
+  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
+}
+
+function ext(language: 'ts' | 'js', jsx: boolean): string {
+  if (language === 'ts') {
+    return jsx ? 'tsx' : 'ts';
+  }
+  return jsx ? 'jsx' : 'js';
+}
+
+function packageManagerRule(packageManagerName: string | undefined): string {
+  if (packageManagerName) {
+    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
+  }
+  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
+}
+
+function getPreviewExample(projectInfo: ProjectInfo): string {
+  const { configDir, language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      import MockDate from 'mockdate';
+      import { initialize, mswLoader } from 'msw-storybook-addon';
+      import { SessionProvider } from '../src/contexts/SessionContext';
+      import { mswHandlers } from './msw-handlers';
+
+      initialize({ onUnhandledRequest: 'bypass' });
+
+      const preview = {
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+        loaders: [mswLoader],
+        parameters: { msw: { handlers: mswHandlers } },
+        async beforeEach() {
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    import MockDate from 'mockdate';
+    import { initialize, mswLoader } from 'msw-storybook-addon';
+    import { SessionProvider } from '../src/contexts/SessionContext';
+    import { mswHandlers } from './msw-handlers';
+
+    initialize({ onUnhandledRequest: 'bypass' });
+
+    const preview: Preview = {
+      decorators: [
+        (Story) => (
+          <SessionProvider>
+            <Story />
+          </SessionProvider>
+        ),
+      ],
+      loaders: [mswLoader],
+      parameters: { msw: { handlers: mswHandlers } },
+      async beforeEach() {
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+
+function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+
+  return dedent`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return <Story />;
+    }
+    \`\`\`
+  `;
+}
+
+function getMainConfigExample(projectInfo: ProjectInfo): string {
+  const { configDir, framework, rendererPackage, language } = projectInfo;
+  const ts = ext(language, false);
+  const typeImport = framework || rendererPackage || '@storybook/react';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
+  `;
+}
+
+function getStoryExample(projectInfo: ProjectInfo): string {
+  const { language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      import { expect } from 'storybook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from 'storybook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+
+function getInteractionPlayExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+  const typeAnnotation = language === 'ts' ? ': Story' : '';
+
+  return dedent`
+    \`\`\`${tsx}
+    export const FilledForm${typeAnnotation} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
+
+export function instructions(projectInfo: ProjectInfo): string {
+  const { configDir, language, packageManager, packageManagerName } = projectInfo;
+  const tsx = ext(language, true);
+  const ts = ext(language, false);
+  const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
+
+  const mswInstall = packageManager.getInstallCommand(
+    ['msw', 'msw-storybook-addon', 'mockdate'],
+    true
+  );
+
+  return dedent`
+    Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
+
+    ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+        - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
+        - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
+        - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
+        - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.
+    2. **Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.
+    3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
+    4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
+    5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+    6. ${packageManagerRule(packageManagerName)}
+    7. **Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.
+    8. **Stop when the success criteria are met** — don't keep polishing.
+
+    ## Plan (do not skip steps, but keep each step lean)
+
+    ### Step 1 — Discover the runtime (≤12 reads)
+
+    Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+    ### Step 2 — Build the shared preview
+
+    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
+
+    The complete shape should look like this (merge the new pieces into what's already there):
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+
+    ### Step 3 — Portals (in a decorator, not preview-body.html)
+
+    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
+
+    ### Step 4 — MSW handlers (only what stories will hit)
+
+    Use \`msw-storybook-addon\`. Install with:
+
+    \`\`\`bash
+    ${mswInstall}
+    npx msw init ./public --save
+    \`\`\`
+
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = {
+      products: [
+        http.get('https://api.example.com/products', () =>
+          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+        ),
+      ],
+    };
+    \`\`\`
+
+    ### Step 5 — Write up to 10 story files (in one batch)
+
+    The deliverable for this step is **two things, both required**:
+
+    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck: Story = {
+      args: { children: 'Submit' },
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button', { name: /submit/i });
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+
+    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
+
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}
+
+    ### Step 7 — Verify in one batch, then iterate only on failures
+
+    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    npx vitest --project storybook run
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
+
+    ### Step 8 — Clean up
+
+    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+    ## Done when
+
+    - **Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+    - Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.
+    - \`npx vitest --project storybook run\` passes for the new files.
+    - The project's TypeScript check passes for changed files.
+    - The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+    ## Reference (only fetch if stuck)
+
+    - Docs index: https://storybook.js.org/llms.txt
+    - Writing stories: ${docsUrl('writing-stories')}
+    - Decorators: ${docsUrl('writing-stories/decorators')}
+    - Play functions: ${docsUrl('writing-stories/play-function')}
+    - Vitest integration: ${docsUrl('writing-tests/vitest-plugin')}
+
+    Append \`?codeOnly=true\` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
+  `;
+}
diff --git a/code/lib/cli-storybook/src/ai/types.ts b/code/lib/cli-storybook/src/ai/types.ts
index bc4914a6f7b3..cb0a44c171fc 100644
--- a/code/lib/cli-storybook/src/ai/types.ts
+++ b/code/lib/cli-storybook/src/ai/types.ts
@@ -27,6 +27,8 @@ export interface ProjectInfo {
   packageManager: JsPackageManager;
   /** Pretty name of the detected package manager, if known. */
   packageManagerName?: string;
+  /** Whether the project's preview file uses the CSF Factory format. */
+  hasCsfFactoryPreview: boolean;
 }
 
 /**

From 81f0911e629b5ad08eb4509ec7c3a20046fe5f6a Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Wed, 29 Apr 2026 21:24:00 +0200
Subject: [PATCH 11/24] Add setup instructions for local monorepo deps

---
 .../utils}/get-monorepo-type.test.ts          |   4 +-
 .../utils}/get-monorepo-type.ts               |   0
 code/core/src/telemetry/ai-setup-utils.ts     |   2 +-
 .../src/telemetry/storybook-metadata.test.ts  |   4 +-
 code/core/src/telemetry/storybook-metadata.ts |   2 +-
 code/core/src/telemetry/types.ts              |   2 +-
 scripts/eval/prompts/monorepo.md              | 300 ++++++++++++++++++
 7 files changed, 307 insertions(+), 7 deletions(-)
 rename code/core/src/{telemetry => shared/utils}/get-monorepo-type.test.ts (89%)
 rename code/core/src/{telemetry => shared/utils}/get-monorepo-type.ts (100%)
 create mode 100644 scripts/eval/prompts/monorepo.md

diff --git a/code/core/src/telemetry/get-monorepo-type.test.ts b/code/core/src/shared/utils/get-monorepo-type.test.ts
similarity index 89%
rename from code/core/src/telemetry/get-monorepo-type.test.ts
rename to code/core/src/shared/utils/get-monorepo-type.test.ts
index 2539bedec21c..5d665f879171 100644
--- a/code/core/src/telemetry/get-monorepo-type.test.ts
+++ b/code/core/src/shared/utils/get-monorepo-type.test.ts
@@ -5,7 +5,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import { getMonorepoType, monorepoConfigs } from './get-monorepo-type.ts';
 
-vi.mock('node:fs', async () => import('../../../__mocks__/fs.ts'));
+vi.mock('node:fs', async () => import('../../../../__mocks__/fs.ts'));
 
 vi.mock('storybook/internal/common', async (importOriginal) => {
   return {
@@ -23,7 +23,7 @@ const checkMonorepoType = ({ monorepoConfigFile, isYarnWorkspace = false }: any)
     mockFiles[join('root', monorepoConfigFile)] = '{}';
   }
 
-  vi.mocked<typeof import('../../../__mocks__/fs')>(fs as any).__setMockFiles(mockFiles);
+  vi.mocked<typeof import('../../../../__mocks__/fs.ts')>(fs as any).__setMockFiles(mockFiles);
 
   return getMonorepoType();
 };
diff --git a/code/core/src/telemetry/get-monorepo-type.ts b/code/core/src/shared/utils/get-monorepo-type.ts
similarity index 100%
rename from code/core/src/telemetry/get-monorepo-type.ts
rename to code/core/src/shared/utils/get-monorepo-type.ts
diff --git a/code/core/src/telemetry/ai-setup-utils.ts b/code/core/src/telemetry/ai-setup-utils.ts
index 198a6221492e..79948e004424 100644
--- a/code/core/src/telemetry/ai-setup-utils.ts
+++ b/code/core/src/telemetry/ai-setup-utils.ts
@@ -5,7 +5,7 @@ import { readFile } from 'node:fs/promises';
 
 import { findConfigFile } from 'storybook/internal/common';
 import { detectAgent } from './detect-agent.ts';
-import { isTelemetryModuleEnabled, telemetry } from './index.ts';
+import { telemetry } from './index.ts';
 import type { EventType } from './types.ts';
 import type { IndexEntry, StoryIndex } from 'storybook/internal/types';
 
diff --git a/code/core/src/telemetry/storybook-metadata.test.ts b/code/core/src/telemetry/storybook-metadata.test.ts
index 8429bfbb329e..90ce24afef26 100644
--- a/code/core/src/telemetry/storybook-metadata.test.ts
+++ b/code/core/src/telemetry/storybook-metadata.test.ts
@@ -18,7 +18,7 @@ import { type Settings, globalSettings } from '../cli/globalSettings.ts';
 import { detectAgent } from './detect-agent.ts';
 import { getApplicationFileCount } from '../telemetry/get-application-file-count.ts';
 import { analyzeEcosystemPackages } from '../telemetry/get-known-packages.ts';
-import { getMonorepoType } from '../telemetry/get-monorepo-type.ts';
+import { getMonorepoType } from '../shared/utils/get-monorepo-type.ts';
 import { getPackageManagerInfo } from '../telemetry/get-package-manager-info.ts';
 import { getPortableStoriesFileCount } from '../telemetry/get-portable-stories-usage.ts';
 import {
@@ -37,7 +37,7 @@ vi.mock('./detect-agent.ts', () => ({
   detectAgent: vi.fn().mockReturnValue(undefined),
 }));
 vi.mock(import('./package-json.ts'), { spy: true });
-vi.mock(import('./get-monorepo-type.ts'), { spy: true });
+vi.mock(import('../shared/utils/get-monorepo-type.ts'), { spy: true });
 vi.mock(import('./get-framework-info.ts'), { spy: true });
 vi.mock(import('./get-package-manager-info.ts'), { spy: true });
 vi.mock(import('./get-portable-stories-usage.ts'), { spy: true });
diff --git a/code/core/src/telemetry/storybook-metadata.ts b/code/core/src/telemetry/storybook-metadata.ts
index 3cbe341bb270..bb1a3413272d 100644
--- a/code/core/src/telemetry/storybook-metadata.ts
+++ b/code/core/src/telemetry/storybook-metadata.ts
@@ -24,7 +24,7 @@ import { getChromaticVersionSpecifier } from './get-chromatic-version.ts';
 import { getFrameworkInfo } from './get-framework-info.ts';
 import { getHasRouterPackage } from './get-has-router-package.ts';
 import { analyzeEcosystemPackages } from './get-known-packages.ts';
-import { getMonorepoType } from './get-monorepo-type.ts';
+import { getMonorepoType } from '../shared/utils/get-monorepo-type.ts';
 import { getPackageManagerInfo } from './get-package-manager-info.ts';
 import { getPortableStoriesFileCount } from './get-portable-stories-usage.ts';
 import { getActualPackageVersion, getActualPackageVersions } from './package-json.ts';
diff --git a/code/core/src/telemetry/types.ts b/code/core/src/telemetry/types.ts
index 37b0d372a7de..9137526a30bf 100644
--- a/code/core/src/telemetry/types.ts
+++ b/code/core/src/telemetry/types.ts
@@ -4,7 +4,7 @@ import type { DetectResult } from 'package-manager-detector';
 
 import type { AgentInfo } from './detect-agent.ts';
 import type { KnownPackagesList } from './get-known-packages.ts';
-import type { MonorepoType } from './get-monorepo-type.ts';
+import type { MonorepoType } from '../shared/utils/get-monorepo-type.ts';
 
 export type EventType =
   | 'boot'
diff --git a/scripts/eval/prompts/monorepo.md b/scripts/eval/prompts/monorepo.md
new file mode 100644
index 000000000000..dcd05ba11109
--- /dev/null
+++ b/scripts/eval/prompts/monorepo.md
@@ -0,0 +1,300 @@
+# Storybook Setup
+
+## Project Info
+
+| Property | Value |
+|----------|-------|
+| Version | 10.4.0-alpha.10 |
+| Renderer | @storybook/react |
+| Framework | @storybook/react-vite |
+| Builder | @storybook/builder-vite |
+| Config Dir | `.storybook` |
+| Language | TypeScript |
+| Package Manager | unknown package manager |
+| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
+
+Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
+
+## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+      - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
+      - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
+      - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
+      - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
+2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
+3. **Nx monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.
+4. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
+5. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
+6. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+7. **Use `unknown package manager` for every install** (detected from this project's lockfile).
+8. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
+9. **Stop when the success criteria are met** — don't keep polishing.
+
+## Plan (do not skip steps, but keep each step lean)
+
+### Step 1 — Discover the runtime (≤12 reads)
+
+Identify, in this order, using Glob/Grep first then targeted Reads:
+
+- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
+- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
+- `App.tsx` — top-level layout, router usage, providers it consumes
+- providers / context files — what they expose
+- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
+- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
+- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
+- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
+- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+### Step 2 — Build the shared preview
+
+Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
+
+The complete shape should look like this (merge the new pieces into what's already there):
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+import MockDate from 'mockdate';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { SessionProvider } from '../src/contexts/SessionContext';
+import { mswHandlers } from './msw-handlers';
+
+initialize({ onUnhandledRequest: 'bypass' });
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <SessionProvider>
+        <Story />
+      </SessionProvider>
+    ),
+  ],
+  loaders: [mswLoader],
+  parameters: { msw: { handlers: mswHandlers } },
+  async beforeEach() {
+    localStorage.setItem('theme', 'dark');
+    MockDate.set('2024-04-01T12:00:00Z');
+  },
+};
+
+export default preview;
+```
+
+Rules for the preview:
+
+- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
+- Use `mockdate` only when render output depends on the date.
+- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
+
+### Step 3 — Portals (in a decorator, not preview-body.html)
+
+If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
+
+```tsx
+// Add this entry to the `decorators` array of your preview config:
+(Story) => {
+  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+    if (!document.getElementById(id)) {
+      const el = document.createElement('div');
+      el.id = id;
+      document.body.appendChild(el);
+    }
+  }
+  return <Story />;
+}
+```
+
+Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
+
+### Step 4 — MSW handlers (only what stories will hit)
+
+Use `msw-storybook-addon`. Install with:
+
+```bash
+<your-package-manager> add -D msw msw-storybook-addon mockdate
+npx msw init ./public --save
+```
+
+Make sure `.storybook/main.ts` serves `./public`:
+
+```ts
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = { staticDirs: ['../public'] };
+export default config;
+```
+
+Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+```ts
+// .storybook/msw-handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const mswHandlers = {
+  products: [
+    http.get('https://api.example.com/products', () =>
+      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+    ),
+  ],
+};
+```
+
+### Step 5 — Write up to 10 story files (in one batch)
+
+The deliverable for this step is **two things, both required**:
+
+1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
+2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
+
+Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Smoke check — one is enough per file
+export const Primary: Story = {
+  args: { children: 'Order now' },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+  },
+};
+
+// Variant-only stories: no play needed
+export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+export const Large: Story = { args: { children: 'Checkout', large: true } };
+export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+```
+
+Story rules:
+
+- Start every meta with `tags: ['ai-generated', 'needs-work']`.
+- Show all imports explicitly.
+- Don't add a custom `title`.
+- Don't build large story-specific harnesses — fix preview instead.
+- Don't create new app components.
+
+**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
+
+```tsx
+export const CssCheck: Story = {
+  args: { children: 'Submit' },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole('button', { name: /submit/i });
+    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+  },
+};
+```
+
+### Step 6 — Add `play` functions only where they prove something non-trivial
+
+**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
+
+Write a `play` when it can verify:
+
+- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
+- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+- **accessibility** that the component is responsible for (correct role/label exposure)
+
+**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
+- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
+- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
+- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
+
+If none of those apply, skip the `play` and rely on the render itself.
+
+Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
+
+- `Primary` — keep one smoke `play` (one is enough for the file).
+- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
+
+(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
+
+Imports & play context — get this right or vitest will fail in subtle ways:
+
+- `expect` and `waitFor` come from `'storybook/test'` — import those.
+- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
+- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
+
+```tsx
+export const FilledForm: Story = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+  },
+};
+```
+
+### Step 7 — Verify in one batch, then iterate only on failures
+
+**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+```bash
+npx vitest --project storybook run
+```
+
+Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `unknown package manager run typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
+
+For each failure:
+
+1. Read the error.
+2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
+4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave `'needs-work'` and move on.
+
+**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
+
+### Step 8 — Clean up
+
+Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+## Done when
+
+- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
+- `npx vitest --project storybook run` passes for the new files.
+- The project's TypeScript check passes for changed files.
+- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+## Reference (only fetch if stuck)
+
+- Docs index: https://storybook.js.org/llms.txt
+- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
+- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
+- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
+- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
+
+Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.

From 0de626f38dfb76fcd4d7d7c25ea0859f32daf521 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 11:40:56 +0200
Subject: [PATCH 12/24] Monorepo prompt with relaxed limits

---
 .../eval/prompts/monorepo-relaxed-limits.md   | 301 ++++++++++++++++++
 1 file changed, 301 insertions(+)
 create mode 100644 scripts/eval/prompts/monorepo-relaxed-limits.md

diff --git a/scripts/eval/prompts/monorepo-relaxed-limits.md b/scripts/eval/prompts/monorepo-relaxed-limits.md
new file mode 100644
index 000000000000..44bb93a01499
--- /dev/null
+++ b/scripts/eval/prompts/monorepo-relaxed-limits.md
@@ -0,0 +1,301 @@
+# Storybook Setup
+
+## Project Info
+
+| Property | Value |
+|----------|-------|
+| Version | 10.4.0-alpha.11 |
+| Renderer | @storybook/react |
+| Framework | @storybook/react-vite |
+| Builder | @storybook/builder-vite |
+| Config Dir | `.storybook` |
+| Language | TypeScript |
+| Package Manager | Yarn Berry |
+| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
+
+Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
+
+## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+      - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
+      - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
+      - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
+      - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
+2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
+3. **Nx monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.
+4. **Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: `index.html`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).
+5. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
+6. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+7. **Use `Yarn Berry` for every install** (detected from this project's lockfile).
+8. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
+9. **Stop when the success criteria are met** — don't keep polishing.
+
+## Plan (do not skip steps, but keep each step lean)
+
+### Step 1 — Discover the runtime (≤12 reads)
+
+Identify, in this order, using Glob/Grep first then targeted Reads:
+
+- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
+- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
+- `App.tsx` — top-level layout, router usage, providers it consumes
+- providers / context files — what they expose
+- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
+- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
+- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
+- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
+- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+### Step 2 — Build the shared preview
+
+Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
+
+The complete shape should look like this (merge the new pieces into what's already there):
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+import MockDate from 'mockdate';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { SessionProvider } from '../src/contexts/SessionContext';
+import { mswHandlers } from './msw-handlers';
+
+initialize({ onUnhandledRequest: 'bypass' });
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <SessionProvider>
+        <Story />
+      </SessionProvider>
+    ),
+  ],
+  loaders: [mswLoader],
+  parameters: { msw: { handlers: mswHandlers } },
+  async beforeEach() {
+    localStorage.setItem('theme', 'dark');
+    MockDate.set('2024-04-01T12:00:00Z');
+  },
+};
+
+export default preview;
+```
+
+Rules for the preview:
+
+- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
+- Use `mockdate` only when render output depends on the date.
+- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
+
+### Step 3 — Portals (in a decorator, not preview-body.html)
+
+If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
+
+```tsx
+// Add this entry to the `decorators` array of your preview config:
+(Story) => {
+  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+    if (!document.getElementById(id)) {
+      const el = document.createElement('div');
+      el.id = id;
+      document.body.appendChild(el);
+    }
+  }
+  return <Story />;
+}
+```
+
+Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
+
+### Step 4 — MSW handlers (only what stories will hit)
+
+Use `msw-storybook-addon`. Install with:
+
+```bash
+yarn add -D msw msw-storybook-addon mockdate
+npx msw init ./public --save
+```
+
+Make sure `.storybook/main.ts` serves `./public`:
+
+```ts
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = { staticDirs: ['../public'] };
+export default config;
+```
+
+Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+```ts
+// .storybook/msw-handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const mswHandlers = {
+  products: [
+    http.get('https://api.example.com/products', () =>
+      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+    ),
+  ],
+};
+```
+
+### Step 5 — Write up to 10 story files (in one batch)
+
+The deliverable for this step is **two things, both required**:
+
+1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
+2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
+
+Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Smoke check — one is enough per file
+export const Primary: Story = {
+  args: { children: 'Order now' },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+  },
+};
+
+// Variant-only stories: no play needed
+export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+export const Large: Story = { args: { children: 'Checkout', large: true } };
+export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+```
+
+Story rules:
+
+- Start every meta with `tags: ['ai-generated', 'needs-work']`.
+- Show all imports explicitly.
+- Don't add a custom `title`.
+- Don't build large story-specific harnesses — fix preview instead.
+- Don't create new app components.
+
+**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
+
+```tsx
+export const CssCheck: Story = {
+  args: { children: 'Submit' },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole('button', { name: /submit/i });
+    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+  },
+};
+```
+
+### Step 6 — Add `play` functions only where they prove something non-trivial
+
+**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
+
+Write a `play` when it can verify:
+
+- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
+- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+- **accessibility** that the component is responsible for (correct role/label exposure)
+
+**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
+- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
+- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
+- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
+
+If none of those apply, skip the `play` and rely on the render itself.
+
+Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
+
+- `Primary` — keep one smoke `play` (one is enough for the file).
+- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
+
+(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
+
+Imports & play context — get this right or vitest will fail in subtle ways:
+
+- `expect` and `waitFor` come from `'storybook/test'` — import those.
+- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
+- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
+
+```tsx
+export const FilledForm: Story = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+  },
+};
+```
+
+### Step 7 — Verify in one batch, then iterate only on failures
+
+**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+```bash
+npx vitest --project storybook run
+```
+
+Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
+
+For each failure:
+
+1. Read the error.
+2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
+4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave `'needs-work'` tag to inform the user.
+5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
+
+**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
+
+### Step 8 — Clean up
+
+Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+## Done when
+
+- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
+- `npx vitest --project storybook run` passes for the new files.
+- The project's TypeScript check passes for changed files.
+- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+## Reference (only fetch if stuck)
+
+- Docs index: https://storybook.js.org/llms.txt
+- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
+- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
+- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
+- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
+
+Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.

From a48040deb1f91225dde3b8a5a9cf3e0a52d7805b Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 14:07:58 +0200
Subject: [PATCH 13/24] refactor prompts

---
 code/lib/cli-storybook/src/ai/index.ts        |   4 +-
 .../src/ai/setup-prompts/index.ts             |  31 +-
 .../src/ai/setup-prompts/monorepo.ts          | 451 ++++++++++++++
 .../src/ai/setup-prompts/optimized-tests.ts   |  42 +-
 .../src/ai/setup-prompts/pattern-copy-play.ts |  25 +-
 .../src/ai/setup-prompts/relaxed-limits.ts    | 452 ++++++++++++++
 .../src/ai/setup-prompts/setup.ts             |   5 +-
 code/lib/cli-storybook/src/ai/types.ts        |  10 -
 .../src/ai/utils/docs-markdown-url.ts         |  20 +
 code/lib/cli-storybook/src/ai/utils/ext.ts    |   6 +
 .../{prompt.ts => utils/project-overview.ts}  |  27 +-
 .../src/ai/utils/type-import-source.ts        |   5 +
 .../eval/prompts/monorepo-relaxed-limits.md   | 301 ----------
 scripts/eval/prompts/monorepo.md              | 300 ----------
 scripts/eval/prompts/optimized-tests.md       | 299 ----------
 scripts/eval/prompts/rac-prompt.md            | 558 ------------------
 16 files changed, 964 insertions(+), 1572 deletions(-)
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
 create mode 100644 code/lib/cli-storybook/src/ai/utils/docs-markdown-url.ts
 create mode 100644 code/lib/cli-storybook/src/ai/utils/ext.ts
 rename code/lib/cli-storybook/src/ai/{prompt.ts => utils/project-overview.ts} (56%)
 create mode 100644 code/lib/cli-storybook/src/ai/utils/type-import-source.ts
 delete mode 100644 scripts/eval/prompts/monorepo-relaxed-limits.md
 delete mode 100644 scripts/eval/prompts/monorepo.md
 delete mode 100644 scripts/eval/prompts/optimized-tests.md
 delete mode 100644 scripts/eval/prompts/rac-prompt.md

diff --git a/code/lib/cli-storybook/src/ai/index.ts b/code/lib/cli-storybook/src/ai/index.ts
index 8c0761dec538..f1371c2ce921 100644
--- a/code/lib/cli-storybook/src/ai/index.ts
+++ b/code/lib/cli-storybook/src/ai/index.ts
@@ -17,7 +17,7 @@ import { SupportedLanguage } from 'storybook/internal/types';
 import { ProjectTypeService } from '../../../create-storybook/src/services/ProjectTypeService.ts';
 
 import { getStorybookData } from '../automigrate/helpers/mainConfigFile.ts';
-import { generateMarkdownOutput } from './prompt.ts';
+import { getAiSetupMarkdownOutput } from './setup-prompts/index.ts';
 import type { ProjectInfo, AiSetupOptions } from './types.ts';
 
 export async function aiSetup(options: AiSetupOptions): Promise<void> {
@@ -84,7 +84,7 @@ export async function aiSetup(options: AiSetupOptions): Promise<void> {
     return;
   }
 
-  const result = await generateMarkdownOutput(projectInfo);
+  const result = await getAiSetupMarkdownOutput(projectInfo);
   const markdownOutput = result.markdown;
 
   await telemetry('ai-setup', {
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
index ed780fa3324f..e2e10593349e 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
@@ -1,6 +1,8 @@
-import type { AiPrompt, ProjectInfo } from '../types.ts';
+import dedent from 'ts-dedent';
+import type { ProjectInfo } from '../types.ts';
 
 import * as optimizedTests from './optimized-tests.ts';
+import { getProjectOverview } from '../utils/project-overview.ts';
 
 /**
  * Main prompt used currently in `npx storybook ai setup` command. If you promote a new prompt to be default, move this to the FORMERLY_USED_PROMPTS object below.
@@ -11,10 +13,13 @@ const CURRENTLY_USED_PROMPT: Record<string, (projectInfo: ProjectInfo) => string
 
 /**
  * Names of variants registered behind `EVAL_SETUP_PROMPT`. Loaded on demand
- * from sibling files so the bundler can code-split them away from the
+ * from sibling files so the bundler can code|-split them away from the
  * default-only path that real users hit.
  */
 const FORMERLY_USED_PROMPTS: Record<string, () => Promise<(projectInfo: ProjectInfo) => string>> = {
+  monorepo: async () => (await import('./monorepo.ts')).instructions,
+  'optimized-tests': async () => (await import('./optimized-tests.ts')).instructions,
+  'relaxed-limits': async () => (await import('./relaxed-limits.ts')).instructions,
   setup: async () => (await import('./setup.ts')).instructions,
   'pattern-copy-play': async () => (await import('./pattern-copy-play.ts')).instructions,
 };
@@ -53,17 +58,23 @@ function resolvePromptName(): PromptName {
   return DEFAULT_PROMPT_NAME;
 }
 
-export async function getPrompts(projectInfo: ProjectInfo): Promise<{ prompts: AiPrompt[] }> {
+export async function getAiSetupPrompt(projectInfo: ProjectInfo): Promise<string> {
   const name = resolvePromptName();
   const builder = CURRENTLY_USED_PROMPT[name] ?? (await FORMERLY_USED_PROMPTS[name]());
 
+  return builder(projectInfo);
+}
+
+export async function getAiSetupMarkdownOutput(projectInfo: ProjectInfo): Promise<{
+  markdown: string;
+}> {
   return {
-    prompts: [
-      {
-        name,
-        description: 'Set up Storybook for success',
-        instructions: builder(projectInfo),
-      },
-    ],
+    markdown: dedent`
+    # Storybook Setup
+
+    ${getProjectOverview(projectInfo)}
+
+    ${await getAiSetupPrompt(projectInfo)}
+  `,
   };
 }
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts b/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
new file mode 100644
index 000000000000..f261abe3a684
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
@@ -0,0 +1,451 @@
+import { dedent } from 'ts-dedent';
+
+import type { ProjectInfo } from '../types.ts';
+import { getMonorepoType } from '../../../../../core/src/shared/utils/get-monorepo-type.ts';
+import { ext } from '../utils/ext.ts';
+import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
+
+function packageManagerRule(packageManagerName: string | undefined): string {
+  if (packageManagerName) {
+    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
+  }
+  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
+}
+
+function monorepoRules(): string | undefined {
+  const monorepoType = getMonorepoType();
+  if (monorepoType) {
+    return `**${monorepoType} monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
+  }
+}
+
+function readBudgetRules(): string | undefined {
+  return `**Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.`;
+}
+
+function getPreviewExample(projectInfo: ProjectInfo): string {
+  const { configDir, language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      import MockDate from 'mockdate';
+      import { initialize, mswLoader } from 'msw-storybook-addon';
+      import { SessionProvider } from '../src/contexts/SessionContext';
+      import { mswHandlers } from './msw-handlers';
+
+      initialize({ onUnhandledRequest: 'bypass' });
+
+      const preview = {
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+        loaders: [mswLoader],
+        parameters: { msw: { handlers: mswHandlers } },
+        async beforeEach() {
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    import MockDate from 'mockdate';
+    import { initialize, mswLoader } from 'msw-storybook-addon';
+    import { SessionProvider } from '../src/contexts/SessionContext';
+    import { mswHandlers } from './msw-handlers';
+
+    initialize({ onUnhandledRequest: 'bypass' });
+
+    const preview: Preview = {
+      decorators: [
+        (Story) => (
+          <SessionProvider>
+            <Story />
+          </SessionProvider>
+        ),
+      ],
+      loaders: [mswLoader],
+      parameters: { msw: { handlers: mswHandlers } },
+      async beforeEach() {
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+
+function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+
+  return dedent`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return <Story />;
+    }
+    \`\`\`
+  `;
+}
+
+function getMainConfigExample(projectInfo: ProjectInfo): string {
+  const { configDir, framework, rendererPackage, language } = projectInfo;
+  const ts = ext(language, false);
+  const typeImport = framework || rendererPackage || '@storybook/react';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
+  `;
+}
+
+function getStoryExample(projectInfo: ProjectInfo): string {
+  const { language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      import { expect } from 'storybook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from 'storybook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+
+function getInteractionPlayExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+  const typeAnnotation = language === 'ts' ? ': Story' : '';
+
+  return dedent`
+    \`\`\`${tsx}
+    export const FilledForm${typeAnnotation} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
+
+export function instructions(projectInfo: ProjectInfo): string {
+  const { configDir, language, packageManager, packageManagerName } = projectInfo;
+  const tsx = ext(language, true);
+  const ts = ext(language, false);
+  const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
+
+  const mswInstall = packageManager.getInstallCommand(
+    ['msw', 'msw-storybook-addon', 'mockdate'],
+    true
+  );
+
+  return dedent`
+    Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
+
+    ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+${[
+  `**Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+      - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
+      - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
+      - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
+      - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.`,
+
+  `**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`,
+  monorepoRules(),
+  readBudgetRules(),
+  `**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.`,
+  `**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`,
+  packageManagerRule(packageManagerName),
+  `**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`,
+  `**Stop when the success criteria are met** — don't keep polishing.`,
+]
+  .filter(Boolean)
+  .map((rule, index) => `${index + 1}. ${rule}`)
+  .join('\n')}
+
+    ## Plan (do not skip steps, but keep each step lean)
+
+    ### Step 1 — Discover the runtime (≤12 reads)
+
+    Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+    ### Step 2 — Build the shared preview
+
+    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
+
+    The complete shape should look like this (merge the new pieces into what's already there):
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+
+    ### Step 3 — Portals (in a decorator, not preview-body.html)
+
+    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
+
+    ### Step 4 — MSW handlers (only what stories will hit)
+
+    Use \`msw-storybook-addon\`. Install with:
+
+    \`\`\`bash
+    ${mswInstall}
+    npx msw init ./public --save
+    \`\`\`
+
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = {
+      products: [
+        http.get('https://api.example.com/products', () =>
+          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+        ),
+      ],
+    };
+    \`\`\`
+
+    ### Step 5 — Write up to 10 story files (in one batch)
+
+    The deliverable for this step is **two things, both required**:
+
+    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck: Story = {
+      args: { children: 'Submit' },
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button', { name: /submit/i });
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+
+    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
+
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}
+
+    ### Step 7 — Verify in one batch, then iterate only on failures
+
+    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    npx vitest --project storybook run
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
+
+    ### Step 8 — Clean up
+
+    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+    ## Done when
+
+    - **Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+    - Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.
+    - \`npx vitest --project storybook run\` passes for the new files.
+    - The project's TypeScript check passes for changed files.
+    - The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+    ## Reference (only fetch if stuck)
+
+    - Docs index: https://storybook.js.org/llms.txt
+    - Writing stories: ${docsUrl('writing-stories')}
+    - Decorators: ${docsUrl('writing-stories/decorators')}
+    - Play functions: ${docsUrl('writing-stories/play-function')}
+    - Vitest integration: ${docsUrl('writing-tests/vitest-plugin')}
+
+    Append \`?codeOnly=true\` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
+  `;
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
index 5ad50780e1cd..e73b2462e7b7 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
@@ -1,46 +1,8 @@
-/**
- * Prompt variant: `optimized-tests`
- *
- * - Created: 2026-04-28 (eval iteration 3, experimental — successor to
- *   `pattern-copy-play` focused on tighter rules-of-engagement, MSW setup,
- *   and a stricter "smoke plays must prove something" policy in Step 6).
- * - Status: experimental — not the default. Selected only when the eval
- *   harness sets `EVAL_SETUP_PROMPT=optimized-tests`.
- * - Reference eval results:
- *   https://github.com/search?q=is:pr label:"prompt:optimized-tests" org:storybook-tmp&type=pullrequests
- *
- * Update this header when iterating: bump the iteration number and link the
- * latest eval run so reviewers can compare variants without spelunking git.
- */
 import { dedent } from 'ts-dedent';
 
 import type { ProjectInfo } from '../types.ts';
-
-/**
- * Builds a markdown-format docs URL with renderer and language query parameters.
- * Appending .md to any Storybook docs URL returns clean markdown with code examples.
- */
-function getDocsMarkdownUrl(
-  path: string,
-  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
-): string {
-  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
-  const versionSegment = majorVersion ? `/${majorVersion}` : '';
-  const params = new URLSearchParams();
-  if (renderer) {
-    params.set('renderer', renderer);
-  }
-  params.set('language', language);
-  const query = params.toString();
-  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
-}
-
-function ext(language: 'ts' | 'js', jsx: boolean): string {
-  if (language === 'ts') {
-    return jsx ? 'tsx' : 'ts';
-  }
-  return jsx ? 'jsx' : 'js';
-}
+import { ext } from '../utils/ext.ts';
+import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
 
 function packageManagerRule(packageManagerName: string | undefined): string {
   if (packageManagerName) {
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/pattern-copy-play.ts b/code/lib/cli-storybook/src/ai/setup-prompts/pattern-copy-play.ts
index a8abe0493f15..bd40075c0c1d 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/pattern-copy-play.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/pattern-copy-play.ts
@@ -13,29 +13,8 @@
 import { dedent } from 'ts-dedent';
 
 import type { ProjectInfo } from '../types.ts';
-
-/**
- * Builds a markdown-format docs URL with renderer and language query parameters.
- * Appending .md to any Storybook docs URL returns clean markdown with code examples.
- */
-function getDocsMarkdownUrl(
-  path: string,
-  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
-): string {
-  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
-  const versionSegment = majorVersion ? `/${majorVersion}` : '';
-  const params = new URLSearchParams();
-  if (renderer) {
-    params.set('renderer', renderer);
-  }
-  params.set('language', language);
-  const query = params.toString();
-  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
-}
-
-function getTypeImportSource(projectInfo: ProjectInfo): string {
-  return projectInfo.framework || projectInfo.rendererPackage || '@storybook/react';
-}
+import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
+import { getTypeImportSource } from '../utils/type-import-source.ts';
 
 function getDocsReferenceSection(projectInfo: ProjectInfo): string {
   const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
new file mode 100644
index 000000000000..00a9ce85ae7f
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
@@ -0,0 +1,452 @@
+import { dedent } from 'ts-dedent';
+
+import type { ProjectInfo } from '../types.ts';
+import { getMonorepoType } from '../../../../../core/src/shared/utils/get-monorepo-type.ts';
+import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
+import { ext } from '../utils/ext.ts';
+
+function packageManagerRule(packageManagerName: string | undefined): string {
+  if (packageManagerName) {
+    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
+  }
+  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
+}
+
+function monorepoRules(): string | undefined {
+  const monorepoType = getMonorepoType();
+  if (monorepoType) {
+    return `**${monorepoType} monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
+  }
+}
+
+function readBudgetRules(): string | undefined {
+  return `**Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: \`index.html\`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).`;
+}
+
+function getPreviewExample(projectInfo: ProjectInfo): string {
+  const { configDir, language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      import MockDate from 'mockdate';
+      import { initialize, mswLoader } from 'msw-storybook-addon';
+      import { SessionProvider } from '../src/contexts/SessionContext';
+      import { mswHandlers } from './msw-handlers';
+
+      initialize({ onUnhandledRequest: 'bypass' });
+
+      const preview = {
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+        loaders: [mswLoader],
+        parameters: { msw: { handlers: mswHandlers } },
+        async beforeEach() {
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    import MockDate from 'mockdate';
+    import { initialize, mswLoader } from 'msw-storybook-addon';
+    import { SessionProvider } from '../src/contexts/SessionContext';
+    import { mswHandlers } from './msw-handlers';
+
+    initialize({ onUnhandledRequest: 'bypass' });
+
+    const preview: Preview = {
+      decorators: [
+        (Story) => (
+          <SessionProvider>
+            <Story />
+          </SessionProvider>
+        ),
+      ],
+      loaders: [mswLoader],
+      parameters: { msw: { handlers: mswHandlers } },
+      async beforeEach() {
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+
+function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+
+  return dedent`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return <Story />;
+    }
+    \`\`\`
+  `;
+}
+
+function getMainConfigExample(projectInfo: ProjectInfo): string {
+  const { configDir, framework, rendererPackage, language } = projectInfo;
+  const ts = ext(language, false);
+  const typeImport = framework || rendererPackage || '@storybook/react';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
+  `;
+}
+
+function getStoryExample(projectInfo: ProjectInfo): string {
+  const { language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      import { expect } from 'storybook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from 'storybook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+
+function getInteractionPlayExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+  const typeAnnotation = language === 'ts' ? ': Story' : '';
+
+  return dedent`
+    \`\`\`${tsx}
+    export const FilledForm${typeAnnotation} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
+
+export function instructions(projectInfo: ProjectInfo): string {
+  const { configDir, language, packageManager, packageManagerName } = projectInfo;
+  const tsx = ext(language, true);
+  const ts = ext(language, false);
+  const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
+
+  const mswInstall = packageManager.getInstallCommand(
+    ['msw', 'msw-storybook-addon', 'mockdate'],
+    true
+  );
+
+  return dedent`
+    Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
+
+    ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+${[
+  `**Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+      - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
+      - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
+      - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
+      - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.`,
+
+  `**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`,
+  monorepoRules(),
+  readBudgetRules(),
+  `**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.`,
+  `**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`,
+  packageManagerRule(packageManagerName),
+  `**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`,
+  `**Stop when the success criteria are met** — don't keep polishing.`,
+]
+  .filter(Boolean)
+  .map((rule, index) => `${index + 1}. ${rule}`)
+  .join('\n')}
+
+    ## Plan (do not skip steps, but keep each step lean)
+
+    ### Step 1 — Discover the runtime (≤12 reads)
+
+    Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+    ### Step 2 — Build the shared preview
+
+    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
+
+    The complete shape should look like this (merge the new pieces into what's already there):
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+
+    ### Step 3 — Portals (in a decorator, not preview-body.html)
+
+    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
+
+    ### Step 4 — MSW handlers (only what stories will hit)
+
+    Use \`msw-storybook-addon\`. Install with:
+
+    \`\`\`bash
+    ${mswInstall}
+    npx msw init ./public --save
+    \`\`\`
+
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = {
+      products: [
+        http.get('https://api.example.com/products', () =>
+          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+        ),
+      ],
+    };
+    \`\`\`
+
+    ### Step 5 — Write up to 10 story files (in one batch)
+
+    The deliverable for this step is **two things, both required**:
+
+    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck: Story = {
+      args: { children: 'Submit' },
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button', { name: /submit/i });
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+
+    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
+
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}
+
+    ### Step 7 — Verify in one batch, then iterate only on failures
+
+    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    npx vitest --project storybook run
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave \`'needs-work'\` tag to inform the user.
+    5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
+
+    ### Step 8 — Clean up
+
+    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+    ## Done when
+
+    - **Exactly one \`CssCheck\` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+    - Every story file you wrote that vitest confirmed passing has had \`'needs-work'\` stripped, leaving \`tags: ['ai-generated']\`. Anything still failing keeps \`['ai-generated', 'needs-work']\`.
+    - \`npx vitest --project storybook run\` passes for the new files.
+    - The project's TypeScript check passes for changed files.
+    - The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+    ## Reference (only fetch if stuck)
+
+    - Docs index: https://storybook.js.org/llms.txt
+    - Writing stories: ${docsUrl('writing-stories')}
+    - Decorators: ${docsUrl('writing-stories/decorators')}
+    - Play functions: ${docsUrl('writing-stories/play-function')}
+    - Vitest integration: ${docsUrl('writing-tests/vitest-plugin')}
+
+    Append \`?codeOnly=true\` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
+  `;
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/setup.ts b/code/lib/cli-storybook/src/ai/setup-prompts/setup.ts
index 916028087d38..f22a75fe38ff 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/setup.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/setup.ts
@@ -13,10 +13,7 @@
 import { dedent } from 'ts-dedent';
 
 import type { ProjectInfo } from '../types.ts';
-
-function getTypeImportSource(projectInfo: ProjectInfo): string {
-  return projectInfo.framework || projectInfo.rendererPackage || '@storybook/react';
-}
+import { getTypeImportSource } from '../utils/type-import-source.ts';
 
 function getPreviewDecoratorExample(projectInfo: ProjectInfo): string {
   const configDir = projectInfo.configDir;
diff --git a/code/lib/cli-storybook/src/ai/types.ts b/code/lib/cli-storybook/src/ai/types.ts
index cb0a44c171fc..8cbc7033b8ae 100644
--- a/code/lib/cli-storybook/src/ai/types.ts
+++ b/code/lib/cli-storybook/src/ai/types.ts
@@ -30,13 +30,3 @@ export interface ProjectInfo {
   /** Whether the project's preview file uses the CSF Factory format. */
   hasCsfFactoryPreview: boolean;
 }
-
-/**
- * Represents a skill category that can be expanded in the future.
- * Each skill provides a name, description, and instructions for agents.
- */
-export interface AiPrompt {
-  name: string;
-  description: string;
-  instructions: string;
-}
diff --git a/code/lib/cli-storybook/src/ai/utils/docs-markdown-url.ts b/code/lib/cli-storybook/src/ai/utils/docs-markdown-url.ts
new file mode 100644
index 000000000000..bd28cb503bb4
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/utils/docs-markdown-url.ts
@@ -0,0 +1,20 @@
+import type { ProjectInfo } from '../types.ts';
+
+/**
+ * Builds a markdown-format docs URL with renderer and language query parameters.
+ * Appending .md to any Storybook docs URL returns clean markdown with code examples.
+ */
+export function getDocsMarkdownUrl(
+  path: string,
+  projectInfo?: Pick<ProjectInfo, 'majorVersion' | 'renderer' | 'language'>
+): string {
+  const { majorVersion, renderer = 'react', language = 'ts' } = projectInfo ?? {};
+  const versionSegment = majorVersion ? `/${majorVersion}` : '';
+  const params = new URLSearchParams();
+  if (renderer) {
+    params.set('renderer', renderer);
+  }
+  params.set('language', language);
+  const query = params.toString();
+  return `https://storybook.js.org/docs${versionSegment}/${path}.md${query ? `?${query}` : ''}`;
+}
diff --git a/code/lib/cli-storybook/src/ai/utils/ext.ts b/code/lib/cli-storybook/src/ai/utils/ext.ts
new file mode 100644
index 000000000000..8e38d41a05d0
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/utils/ext.ts
@@ -0,0 +1,6 @@
+export function ext(language: 'ts' | 'js', jsx: boolean): string {
+  if (language === 'ts') {
+    return jsx ? 'tsx' : 'ts';
+  }
+  return jsx ? 'jsx' : 'js';
+}
diff --git a/code/lib/cli-storybook/src/ai/prompt.ts b/code/lib/cli-storybook/src/ai/utils/project-overview.ts
similarity index 56%
rename from code/lib/cli-storybook/src/ai/prompt.ts
rename to code/lib/cli-storybook/src/ai/utils/project-overview.ts
index 0f079f731883..55b13175cbaf 100644
--- a/code/lib/cli-storybook/src/ai/prompt.ts
+++ b/code/lib/cli-storybook/src/ai/utils/project-overview.ts
@@ -1,9 +1,6 @@
-import { dedent } from 'ts-dedent';
+import type { ProjectInfo } from '../types.ts';
 
-import { getPrompts } from './setup-prompts/index.ts';
-import type { ProjectInfo } from './types.ts';
-
-function getProjectOverview(projectInfo: ProjectInfo): string {
+export function getProjectOverview(projectInfo: ProjectInfo): string {
   const rows: Array<[string, string]> = [
     ['Version', projectInfo.storybookVersion || 'unknown'],
     ['Renderer', projectInfo.rendererPackage || 'unknown'],
@@ -25,23 +22,3 @@ function getProjectOverview(projectInfo: ProjectInfo): string {
     '\n'
   );
 }
-
-export async function generateMarkdownOutput(projectInfo: ProjectInfo): Promise<{
-  markdown: string;
-}> {
-  const { prompts: aiPrompts } = await getPrompts(projectInfo);
-
-  const sections: string[] = [];
-
-  sections.push(dedent`
-    # Storybook Setup
-  `);
-
-  sections.push(getProjectOverview(projectInfo));
-
-  for (const aiPrompt of aiPrompts) {
-    sections.push(aiPrompt.instructions);
-  }
-
-  return { markdown: sections.join('\n\n') };
-}
diff --git a/code/lib/cli-storybook/src/ai/utils/type-import-source.ts b/code/lib/cli-storybook/src/ai/utils/type-import-source.ts
new file mode 100644
index 000000000000..194d0eccc76d
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/utils/type-import-source.ts
@@ -0,0 +1,5 @@
+import type { ProjectInfo } from '../types.ts';
+
+export function getTypeImportSource(projectInfo: ProjectInfo): string {
+  return projectInfo.framework || projectInfo.rendererPackage || '@storybook/react';
+}
diff --git a/scripts/eval/prompts/monorepo-relaxed-limits.md b/scripts/eval/prompts/monorepo-relaxed-limits.md
deleted file mode 100644
index 44bb93a01499..000000000000
--- a/scripts/eval/prompts/monorepo-relaxed-limits.md
+++ /dev/null
@@ -1,301 +0,0 @@
-# Storybook Setup
-
-## Project Info
-
-| Property | Value |
-|----------|-------|
-| Version | 10.4.0-alpha.11 |
-| Renderer | @storybook/react |
-| Framework | @storybook/react-vite |
-| Builder | @storybook/builder-vite |
-| Config Dir | `.storybook` |
-| Language | TypeScript |
-| Package Manager | Yarn Berry |
-| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
-
-Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
-
-## Rules of engagement (follow strictly — these are time budgets, not suggestions)
-
-1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-      - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
-      - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
-      - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
-      - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
-2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
-3. **Nx monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.
-4. **Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: `index.html`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).
-5. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
-6. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-7. **Use `Yarn Berry` for every install** (detected from this project's lockfile).
-8. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
-9. **Stop when the success criteria are met** — don't keep polishing.
-
-## Plan (do not skip steps, but keep each step lean)
-
-### Step 1 — Discover the runtime (≤12 reads)
-
-Identify, in this order, using Glob/Grep first then targeted Reads:
-
-- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
-- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
-- `App.tsx` — top-level layout, router usage, providers it consumes
-- providers / context files — what they expose
-- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
-- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
-- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
-- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
-- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-### Step 2 — Build the shared preview
-
-Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
-
-The complete shape should look like this (merge the new pieces into what's already there):
-
-```tsx
-// .storybook/preview.tsx
-import type { Preview } from '@storybook/react-vite';
-import '../src/index.css';
-import MockDate from 'mockdate';
-import { initialize, mswLoader } from 'msw-storybook-addon';
-import { SessionProvider } from '../src/contexts/SessionContext';
-import { mswHandlers } from './msw-handlers';
-
-initialize({ onUnhandledRequest: 'bypass' });
-
-const preview: Preview = {
-  decorators: [
-    (Story) => (
-      <SessionProvider>
-        <Story />
-      </SessionProvider>
-    ),
-  ],
-  loaders: [mswLoader],
-  parameters: { msw: { handlers: mswHandlers } },
-  async beforeEach() {
-    localStorage.setItem('theme', 'dark');
-    MockDate.set('2024-04-01T12:00:00Z');
-  },
-};
-
-export default preview;
-```
-
-Rules for the preview:
-
-- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
-- Use `mockdate` only when render output depends on the date.
-- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
-
-### Step 3 — Portals (in a decorator, not preview-body.html)
-
-If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
-
-```tsx
-// Add this entry to the `decorators` array of your preview config:
-(Story) => {
-  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-    if (!document.getElementById(id)) {
-      const el = document.createElement('div');
-      el.id = id;
-      document.body.appendChild(el);
-    }
-  }
-  return <Story />;
-}
-```
-
-Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
-
-### Step 4 — MSW handlers (only what stories will hit)
-
-Use `msw-storybook-addon`. Install with:
-
-```bash
-yarn add -D msw msw-storybook-addon mockdate
-npx msw init ./public --save
-```
-
-Make sure `.storybook/main.ts` serves `./public`:
-
-```ts
-// .storybook/main.ts
-import type { StorybookConfig } from '@storybook/react-vite';
-
-const config: StorybookConfig = { staticDirs: ['../public'] };
-export default config;
-```
-
-Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-```ts
-// .storybook/msw-handlers.ts
-import { http, HttpResponse } from 'msw';
-
-export const mswHandlers = {
-  products: [
-    http.get('https://api.example.com/products', () =>
-      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-    ),
-  ],
-};
-```
-
-### Step 5 — Write up to 10 story files (in one batch)
-
-The deliverable for this step is **two things, both required**:
-
-1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
-2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
-
-Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect } from 'storybook/test';
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// Smoke check — one is enough per file
-export const Primary: Story = {
-  args: { children: 'Order now' },
-  play: async ({ canvas }) => {
-    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-  },
-};
-
-// Variant-only stories: no play needed
-export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-export const Large: Story = { args: { children: 'Checkout', large: true } };
-export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-```
-
-Story rules:
-
-- Start every meta with `tags: ['ai-generated', 'needs-work']`.
-- Show all imports explicitly.
-- Don't add a custom `title`.
-- Don't build large story-specific harnesses — fix preview instead.
-- Don't create new app components.
-
-**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
-
-```tsx
-export const CssCheck: Story = {
-  args: { children: 'Submit' },
-  play: async ({ canvas }) => {
-    const button = canvas.getByRole('button', { name: /submit/i });
-    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-  },
-};
-```
-
-### Step 6 — Add `play` functions only where they prove something non-trivial
-
-**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
-
-Write a `play` when it can verify:
-
-- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
-- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-- **accessibility** that the component is responsible for (correct role/label exposure)
-
-**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
-- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
-- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
-- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
-
-If none of those apply, skip the `play` and rely on the render itself.
-
-Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
-
-- `Primary` — keep one smoke `play` (one is enough for the file).
-- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
-
-(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
-
-Imports & play context — get this right or vitest will fail in subtle ways:
-
-- `expect` and `waitFor` come from `'storybook/test'` — import those.
-- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
-- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
-
-```tsx
-export const FilledForm: Story = {
-  play: async ({ canvas, userEvent }) => {
-    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-  },
-};
-```
-
-### Step 7 — Verify in one batch, then iterate only on failures
-
-**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-```bash
-npx vitest --project storybook run
-```
-
-Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
-
-For each failure:
-
-1. Read the error.
-2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
-4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave `'needs-work'` tag to inform the user.
-5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
-
-**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
-
-### Step 8 — Clean up
-
-Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
-
-## Done when
-
-- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
-- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
-- `npx vitest --project storybook run` passes for the new files.
-- The project's TypeScript check passes for changed files.
-- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
-
-## Reference (only fetch if stuck)
-
-- Docs index: https://storybook.js.org/llms.txt
-- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
-- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
-- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
-- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
-
-Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
diff --git a/scripts/eval/prompts/monorepo.md b/scripts/eval/prompts/monorepo.md
deleted file mode 100644
index dcd05ba11109..000000000000
--- a/scripts/eval/prompts/monorepo.md
+++ /dev/null
@@ -1,300 +0,0 @@
-# Storybook Setup
-
-## Project Info
-
-| Property | Value |
-|----------|-------|
-| Version | 10.4.0-alpha.10 |
-| Renderer | @storybook/react |
-| Framework | @storybook/react-vite |
-| Builder | @storybook/builder-vite |
-| Config Dir | `.storybook` |
-| Language | TypeScript |
-| Package Manager | unknown package manager |
-| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
-
-Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
-
-## Rules of engagement (follow strictly — these are time budgets, not suggestions)
-
-1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-      - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
-      - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
-      - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
-      - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
-2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
-3. **Nx monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.
-4. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
-5. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
-6. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-7. **Use `unknown package manager` for every install** (detected from this project's lockfile).
-8. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
-9. **Stop when the success criteria are met** — don't keep polishing.
-
-## Plan (do not skip steps, but keep each step lean)
-
-### Step 1 — Discover the runtime (≤12 reads)
-
-Identify, in this order, using Glob/Grep first then targeted Reads:
-
-- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
-- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
-- `App.tsx` — top-level layout, router usage, providers it consumes
-- providers / context files — what they expose
-- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
-- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
-- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
-- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
-- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-### Step 2 — Build the shared preview
-
-Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
-
-The complete shape should look like this (merge the new pieces into what's already there):
-
-```tsx
-// .storybook/preview.tsx
-import type { Preview } from '@storybook/react-vite';
-import '../src/index.css';
-import MockDate from 'mockdate';
-import { initialize, mswLoader } from 'msw-storybook-addon';
-import { SessionProvider } from '../src/contexts/SessionContext';
-import { mswHandlers } from './msw-handlers';
-
-initialize({ onUnhandledRequest: 'bypass' });
-
-const preview: Preview = {
-  decorators: [
-    (Story) => (
-      <SessionProvider>
-        <Story />
-      </SessionProvider>
-    ),
-  ],
-  loaders: [mswLoader],
-  parameters: { msw: { handlers: mswHandlers } },
-  async beforeEach() {
-    localStorage.setItem('theme', 'dark');
-    MockDate.set('2024-04-01T12:00:00Z');
-  },
-};
-
-export default preview;
-```
-
-Rules for the preview:
-
-- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
-- Use `mockdate` only when render output depends on the date.
-- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
-
-### Step 3 — Portals (in a decorator, not preview-body.html)
-
-If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
-
-```tsx
-// Add this entry to the `decorators` array of your preview config:
-(Story) => {
-  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-    if (!document.getElementById(id)) {
-      const el = document.createElement('div');
-      el.id = id;
-      document.body.appendChild(el);
-    }
-  }
-  return <Story />;
-}
-```
-
-Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
-
-### Step 4 — MSW handlers (only what stories will hit)
-
-Use `msw-storybook-addon`. Install with:
-
-```bash
-<your-package-manager> add -D msw msw-storybook-addon mockdate
-npx msw init ./public --save
-```
-
-Make sure `.storybook/main.ts` serves `./public`:
-
-```ts
-// .storybook/main.ts
-import type { StorybookConfig } from '@storybook/react-vite';
-
-const config: StorybookConfig = { staticDirs: ['../public'] };
-export default config;
-```
-
-Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-```ts
-// .storybook/msw-handlers.ts
-import { http, HttpResponse } from 'msw';
-
-export const mswHandlers = {
-  products: [
-    http.get('https://api.example.com/products', () =>
-      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-    ),
-  ],
-};
-```
-
-### Step 5 — Write up to 10 story files (in one batch)
-
-The deliverable for this step is **two things, both required**:
-
-1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
-2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
-
-Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect } from 'storybook/test';
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// Smoke check — one is enough per file
-export const Primary: Story = {
-  args: { children: 'Order now' },
-  play: async ({ canvas }) => {
-    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-  },
-};
-
-// Variant-only stories: no play needed
-export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-export const Large: Story = { args: { children: 'Checkout', large: true } };
-export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-```
-
-Story rules:
-
-- Start every meta with `tags: ['ai-generated', 'needs-work']`.
-- Show all imports explicitly.
-- Don't add a custom `title`.
-- Don't build large story-specific harnesses — fix preview instead.
-- Don't create new app components.
-
-**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
-
-```tsx
-export const CssCheck: Story = {
-  args: { children: 'Submit' },
-  play: async ({ canvas }) => {
-    const button = canvas.getByRole('button', { name: /submit/i });
-    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-  },
-};
-```
-
-### Step 6 — Add `play` functions only where they prove something non-trivial
-
-**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
-
-Write a `play` when it can verify:
-
-- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
-- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-- **accessibility** that the component is responsible for (correct role/label exposure)
-
-**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
-- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
-- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
-- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
-
-If none of those apply, skip the `play` and rely on the render itself.
-
-Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
-
-- `Primary` — keep one smoke `play` (one is enough for the file).
-- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
-
-(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
-
-Imports & play context — get this right or vitest will fail in subtle ways:
-
-- `expect` and `waitFor` come from `'storybook/test'` — import those.
-- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
-- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
-
-```tsx
-export const FilledForm: Story = {
-  play: async ({ canvas, userEvent }) => {
-    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-  },
-};
-```
-
-### Step 7 — Verify in one batch, then iterate only on failures
-
-**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-```bash
-npx vitest --project storybook run
-```
-
-Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `unknown package manager run typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
-
-For each failure:
-
-1. Read the error.
-2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
-4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave `'needs-work'` and move on.
-
-**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
-
-### Step 8 — Clean up
-
-Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
-
-## Done when
-
-- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
-- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
-- `npx vitest --project storybook run` passes for the new files.
-- The project's TypeScript check passes for changed files.
-- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
-
-## Reference (only fetch if stuck)
-
-- Docs index: https://storybook.js.org/llms.txt
-- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
-- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
-- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
-- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
-
-Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
diff --git a/scripts/eval/prompts/optimized-tests.md b/scripts/eval/prompts/optimized-tests.md
deleted file mode 100644
index 6a5a1f12859f..000000000000
--- a/scripts/eval/prompts/optimized-tests.md
+++ /dev/null
@@ -1,299 +0,0 @@
-# Storybook Setup
-
-## Project Info
-
-| Property | Value |
-|----------|-------|
-| Version | 10.4.0-alpha.10 |
-| Renderer | @storybook/react |
-| Framework | @storybook/react-vite |
-| Builder | @storybook/builder-vite |
-| Config Dir | `.storybook` |
-| Language | TypeScript |
-| Package Manager | Yarn Berry |
-| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
-
-Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
-
-## Rules of engagement (follow strictly — these are time budgets, not suggestions)
-
-1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-    - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
-    - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
-    - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
-    - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
-2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
-3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
-4. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
-5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-6. **Use `Yarn Berry` for every install** (detected from this project's lockfile).
-7. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
-8. **Stop when the success criteria are met** — don't keep polishing.
-
-## Plan (do not skip steps, but keep each step lean)
-
-### Step 1 — Discover the runtime (≤12 reads)
-
-Identify, in this order, using Glob/Grep first then targeted Reads:
-
-- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
-- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
-- `App.tsx` — top-level layout, router usage, providers it consumes
-- providers / context files — what they expose
-- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
-- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
-- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
-- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
-- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-### Step 2 — Build the shared preview
-
-Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
-
-The complete shape should look like this (merge the new pieces into what's already there):
-
-```tsx
-// .storybook/preview.tsx
-import type { Preview } from '@storybook/react-vite';
-import '../src/index.css';
-import MockDate from 'mockdate';
-import { initialize, mswLoader } from 'msw-storybook-addon';
-import { SessionProvider } from '../src/contexts/SessionContext';
-import { mswHandlers } from './msw-handlers';
-
-initialize({ onUnhandledRequest: 'bypass' });
-
-const preview: Preview = {
-  decorators: [
-    (Story) => (
-      <SessionProvider>
-        <Story />
-      </SessionProvider>
-    ),
-  ],
-  loaders: [mswLoader],
-  parameters: { msw: { handlers: mswHandlers } },
-  async beforeEach() {
-    localStorage.setItem('theme', 'dark');
-    MockDate.set('2024-04-01T12:00:00Z');
-  },
-};
-
-export default preview;
-```
-
-Rules for the preview:
-
-- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
-- Use `mockdate` only when render output depends on the date.
-- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
-
-### Step 3 — Portals (in a decorator, not preview-body.html)
-
-If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
-
-```tsx
-// Add this entry to the `decorators` array of your preview config:
-(Story) => {
-  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-    if (!document.getElementById(id)) {
-      const el = document.createElement('div');
-      el.id = id;
-      document.body.appendChild(el);
-    }
-  }
-  return <Story />;
-}
-```
-
-Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
-
-### Step 4 — MSW handlers (only what stories will hit)
-
-Use `msw-storybook-addon`. Install with:
-
-```bash
-yarn add -D msw msw-storybook-addon mockdate
-npx msw init ./public --save
-```
-
-Make sure `.storybook/main.ts` serves `./public`:
-
-```ts
-// .storybook/main.ts
-import type { StorybookConfig } from '@storybook/react-vite';
-
-const config: StorybookConfig = { staticDirs: ['../public'] };
-export default config;
-```
-
-Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-```ts
-// .storybook/msw-handlers.ts
-import { http, HttpResponse } from 'msw';
-
-export const mswHandlers = {
-  products: [
-    http.get('https://api.example.com/products', () =>
-      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-    ),
-  ],
-};
-```
-
-### Step 5 — Write up to 10 story files (in one batch)
-
-The deliverable for this step is **two things, both required**:
-
-1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
-2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
-
-Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect } from 'storybook/test';
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// Smoke check — one is enough per file
-export const Primary: Story = {
-  args: { children: 'Order now' },
-  play: async ({ canvas }) => {
-    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-  },
-};
-
-// Variant-only stories: no play needed
-export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-export const Large: Story = { args: { children: 'Checkout', large: true } };
-export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-```
-
-Story rules:
-
-- Start every meta with `tags: ['ai-generated', 'needs-work']`.
-- Show all imports explicitly.
-- Don't add a custom `title`.
-- Don't build large story-specific harnesses — fix preview instead.
-- Don't create new app components.
-
-**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
-
-```tsx
-export const CssCheck: Story = {
-  args: { children: 'Submit' },
-  play: async ({ canvas }) => {
-    const button = canvas.getByRole('button', { name: /submit/i });
-    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-  },
-};
-```
-
-### Step 6 — Add `play` functions only where they prove something non-trivial
-
-**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
-
-Write a `play` when it can verify:
-
-- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
-- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-- **accessibility** that the component is responsible for (correct role/label exposure)
-
-**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
-- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
-- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
-- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
-
-If none of those apply, skip the `play` and rely on the render itself.
-
-Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
-
-- `Primary` — keep one smoke `play` (one is enough for the file).
-- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
-
-(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
-
-Imports & play context — get this right or vitest will fail in subtle ways:
-
-- `expect` and `waitFor` come from `'storybook/test'` — import those.
-- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
-- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
-
-```tsx
-export const FilledForm: Story = {
-  play: async ({ canvas, userEvent }) => {
-    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-  },
-};
-```
-
-### Step 7 — Verify in one batch, then iterate only on failures
-
-**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-```bash
-npx vitest --project storybook run
-```
-
-Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `yarn typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
-
-For each failure:
-
-1. Read the error.
-2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
-4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave `'needs-work'` and move on.
-
-**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
-
-### Step 8 — Clean up
-
-Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
-
-## Done when
-
-- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
-- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
-- `npx vitest --project storybook run` passes for the new files.
-- The project's TypeScript check passes for changed files.
-- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
-
-## Reference (only fetch if stuck)
-
-- Docs index: https://storybook.js.org/llms.txt
-- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
-- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
-- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
-- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
-
-Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.
\ No newline at end of file
diff --git a/scripts/eval/prompts/rac-prompt.md b/scripts/eval/prompts/rac-prompt.md
deleted file mode 100644
index a9583e5d04f3..000000000000
--- a/scripts/eval/prompts/rac-prompt.md
+++ /dev/null
@@ -1,558 +0,0 @@
-# Storybook Setup
-
-## Project Info
-
-| Property                                                           | Value                                              |
-| ------------------------------------------------------------------ | -------------------------------------------------- |
-| Version                                                            | 10.4.0-alpha.10                                    |
-| Renderer                                                           | @storybook/react                                   |
-| Framework                                                          | @storybook/react-vite                              |
-| Builder                                                            | @storybook/builder-vite                            |
-| Config Dir                                                         | `.storybook`                                       |
-| CSF Format                                                         | CSF3                                               |
-| Addons                                                             | @chromatic-com/storybook, @storybook/addon-vitest, |
-| @storybook/addon-a11y, @storybook/addon-docs, @storybook/addon-mcp |                                                    |
-
-Attention: The following instructions must be followed in order to
-successfully set up Storybook in this project. Do not skip steps or
-attempt to do them out of order.
-
-Your goal is to make Storybook fully functional in this project by
-analyzing the codebase,
-configuring the preview with the right decorators, and writing stories
-for some components.
-
-After each created story, run Vitest to verify it renders.
-If the test fails, read the error, fix the issue, and re-run until it
-passes before moving on.
-
-- Copy real patterns from the codebase
-- Keep the app code unchanged
-- Put the default setup in `.storybook/preview.tsx`
-- Keep app mocking and runtime setup in `.storybook/preview.tsx`, not
-in the stories
-
-### Storybook Documentation Reference
-
-Use the following references to look up Storybook APIs, concepts, or
-examples:
-
-- Full docs index: https://storybook.js.org/llms.txt
-- See code snippets only with codeOnly=true param e.g.
-https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts&codeOnly=true
-
-Key documentation pages for this task:
-- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
-- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
-- Args: https://storybook.js.org/docs/10/writing-stories/args.md?renderer=react&language=ts
-- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
-- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
-
-Fetch these URLs directly when you need guidance on Storybook APIs or
-patterns.
-
-### Step 1: Analyze the codebase
-
-Read enough of the app to understand the full runtime environment
-before writing any stories.
-
-Do not stop at `main.tsx` or `App.tsx`.
-Follow imports into providers, pages, hooks, and shared components
-until you know:
-
-- which providers exist
-- which CSS files are injected
-- which queries fetch data
-- which browser-state reads happen
-- which portals and portal roots exist
-- which pages and components show the real usage patterns
-
-Example of what to copy:
-
-```tsx
-// src/main.tsx
-import "./index.css";
-import App from "./App";
-import { SessionProvider } from "./contexts/SessionContext";
-
-createRoot(document.getElementById("root")!).render(
-<SessionProvider>
-<App />
-</SessionProvider>,
-);
-```
-
-That means Storybook should copy:
-
-- the `index.css` import
-- the `SessionProvider`
-- the same provider order
-
-Example of tracing the app deeper:
-
-```tsx
-// src/App.tsx
-function App() {
-const { products, loadMoreProducts } = useProducts();
-const { currentUser, signOut } = useSession();
-// ...
-}
-```
-
-```ts
-// src/hooks/useProducts.ts
-const response = await fetch(apiBaseUrl + "/products?page=1");
-```
-
-```ts
-// src/hooks/useTheme.ts
-const savedTheme = localStorage.getItem("theme");
-```
-
-That means the default Storybook setup should discover and prepare:
-
-- provider state
-- MSW handlers for queries
-- browser-state values that are actually read during render
-
-### Step 2: Build one default app environment in preview
-
-Set up Storybook once so most stories work without story-specific
-setup.
-
-Start with the smallest faithful environment:
-
-- the real provider tree
-- the real root CSS
-- seeded browser state if the app reads it during render
-- MSW for network/data queries
-
-It is fine to seed browser state such as `localStorage`,
-`sessionStorage`, and cookies when the app reads them during render.
-Seed only the specific app-owned keys and values you need.
-Do not clear all `localStorage`, `sessionStorage`, or cookies, and do
-not reset Storybook's own state.
-Do not mock or redefine the browser runtime itself.
-The stories run in Vitest browser mode, so the real browser
-environment should already exist.
-
-```tsx
-// .storybook/preview.tsx
-import type { Preview } from '@storybook/react-vite';
-import MockDate from 'mockdate';
-import '../src/index.css'; // import global styles
-import { SessionProvider } from '../src/contexts/SessionContext';
-
-const preview: Preview = {
-decorators: [
-(Story) => (
-<SessionProvider>
-<Story />
-</SessionProvider>
-),
-],
-async beforeEach() {
-localStorage.setItem('theme', 'dark');
-localStorage.setItem('sidebar:open', 'true');
-MockDate.set('2024-04-01T12:00:00Z');
-},
-};
-
-export default preview;
-```
-
-Use this same idea for:
-
-- providers
-- root CSS
-- browser state
-- dates, and if the app logic depends on them during render then
-always use `mockdate`
-
-Example with the `mockdate` package:
-
-```tsx
-import type { Preview } from '@storybook/react-vite';
-import MockDate from 'mockdate';
-
-const preview: Preview = {
-async beforeEach() {
-MockDate.set('2024-04-01T12:00:00Z');
-},
-};
-
-export default preview;
-```
-
-### Step 3: Support portals with preview-body.html
-
-If the app uses portals, copy that setup into Storybook too.
-
-Look for patterns like:
-
-- `createPortal(...)`
-- modal, dialog, drawer, popover, tooltip, toast, or dropdown portal
-components
-- hard-coded roots such as `#portal-root`, `#modal-root`,
-`#drawer-root`, or `#toast-root`
-
-Example of what to copy:
-
-```tsx
-// real component
-return createPortal(<ModalContent />,
-document.getElementById("portal-root")!);
-```
-
-That means Storybook should create the same portal root in
-`.storybook/preview-body.html`:
-
-```html
-<!-- .storybook/preview-body.html -->
-<div id="portal-root"></div>
-```
-
-If the app uses multiple portal roots, create all of them there:
-
-```html
-<!-- .storybook/preview-body.html -->
-<div id="modal-root"></div>
-<div id="drawer-root"></div>
-<div id="toast-root"></div>
-```
-
-If a library portals directly to `document.body`, do not add extra
-roots for it.
-Make sure the copied page shell, CSS, and layout still allow overlays,
-fixed positioning, and z-index stacking to render correctly.
-
-### Step 4: Mock side effects globally
-
-All network/data queries should be handled by the default Storybook
-environment.
-
-- Always use `msw-storybook-addon` for query mocking.
-- If you introduce MSW, run `npx msw init ./public --save` to create
-the worker file.
-- Make sure Storybook serves `./public` as a static dir so
-`mockServiceWorker.js` is available.
-- Do not mock `fetch` directly.
-- Network/data queries should return deterministic mock data.
-- If you need to change dependencies, first check the lockfile and use
-that package manager for the change.
-
-Example of copying a real fetch pattern into shared handlers:
-
-```ts
-// real app hook
-const response = await fetch(
-apiBaseUrl +
-"/products?" +
-new URLSearchParams({
-page: "1",
-sort: "featured",
-}),
-);
-```
-
-```ts
-// .storybook/msw-handlers.ts
-import { http, HttpResponse } from "msw";
-
-export const mswHandlers = {
-products: [
-http.get("https://api.example.com/products",
-() =>
-HttpResponse.json({
-items: [
-{
-id: "product-1",
-name: "Example product",
-description: "Mock product description",
-imageUrl:
-"https://images.example.com/product.jpg",
-price: 42,
-},
-],
-}),
-),
-],
-};
-```
-
-```tsx
-// .storybook/preview.tsx
-import type { Preview } from '@storybook/react-vite';
-import { initialize, mswLoader } from 'msw-storybook-addon';
-import { mswHandlers } from './msw-handlers';
-
-initialize({
-onUnhandledRequest: 'bypass',
-});
-
-const preview: Preview = {
-loaders: [mswLoader],
-parameters: {
-msw: {
-handlers: mswHandlers,
-},
-},
-};
-
-export default preview;
-```
-
-```ts
-// .storybook/main.ts
-import type { StorybookConfig } from "@storybook/react-vite";
-
-const config: StorybookConfig = {
-staticDirs: ["../public"],
-};
-
-export default config;
-```
-
-Keep these mocks global.
-Do not put fetch mocks in individual stories.
-Only add handlers for requests that the shared preview setup or the
-stories actually use.
-Do not add catch-all handlers that can hide unrelated failures.
-If the defaults are not enough, improve the shared default setup
-instead.
-Seed browser state when needed, but do not mock `window`, `document`,
-`navigator`, observers, or similar runtime APIs.
-The only exception is `mockdate` when date-based rendering exists.
-
-### Step 5: Write stories
-
-Try to find around 10 good candidate components for story files.
-Write colocated stories for top-level components, from low-level
-reusable components up to page components.
-Write up to 10 story files, or fewer only if the codebase clearly has
-fewer meaningful targets.
-
-The stories should use JSX copied from real usage patterns in:
-
-- pages
-- app shells
-- routes
-- tests
-- existing feature code
-
-As a rule of thumb, each story file should have around 3 story exports
-when the component or page has enough meaningful states.
-It can have more when the real usage supports it, up to 10 story
-exports in one file.
-
-Always show all imports explicitly in story and preview files.
-Do not rely on omitted or implied imports in examples or generated
-code.
-
-#### Story tags
-
-Every story meta must include the `ai-generated` tag to identify
-AI-created stories:
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect } from 'storybook/test';
-import { SomeComponent } from './SomeComponent';
-
-const meta = {
-component: SomeComponent,
-tags: ['ai-generated'],
-} satisfies Meta<typeof SomeComponent>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-render: () => <SomeComponent variant="primary" disabled={false} />,
-play: async ({ canvas }) => {
-await expect(canvas.getByRole('button')).toBeVisible();
-},
-};
-```
-
-If a story could not be fully fixed after the self-healing loop (the
-test still fails
-or the rendering is incomplete), add the `needs-work` tag alongside
-`ai-generated`:
-
-```ts
-const meta = {
-component: SomeComponent,
-tags: ['ai-generated', 'needs-work'],
-} satisfies Meta<typeof SomeComponent>;
-```
-
-Keep app mocking and runtime setup in preview, not in the stories.
-Do not build large story-specific harnesses.
-Do not write story files for subcomponents, hooks, contexts, or
-helpers.
-Do not create new application components.
-Do not add a custom `title`.
-Do not stop after only a few easy targets if the codebase has more
-meaningful components or pages available.
-
-### Step 6: Write a play function for every story
-
-Every named story export must have a `play` function.
-The `play` function is not optional, even for simple stories.
-
-The purpose of the `play` function is to prove that the story actually
-works in the copied Storybook environment:
-
-- the story renders something real and non-empty
-- the decorators provide the needed context
-- the CSS is applied well enough for the intended state to be visible
-- the MSW mocks or seeded browser state are actually being used
-- important interactions, async loading states, and portals behave
-correctly
-
-Use `play` functions to verify behavior, not just to click around.
-A story without assertions is incomplete.
-
-Use tools from `storybook/test` such as:
-
-- `expect`
-- `waitFor`
-
-Prefer `canvas` and `userEvent` from the `play` context.
-Do not destructure `canvasElement` just to create `const canvas =
-within(canvasElement)`.
-Do not import `userEvent` from `storybook/test`; use `userEvent` from
-the `play` context instead.
-Only use `canvasElement.ownerDocument` when you need to query outside
-the canvas, such as for portals.
-
-Example:
-
-```tsx
-import type { StoryObj } from "@storybook/react-vite";
-
-export const FilledForm: Story = {
-play: async ({ canvas, userEvent }) => {
-const emailInput = canvas.getByLabelText("email", {
-selector: "input",
-});
-
-await userEvent.type(emailInput, "example-email@email.com", {
-delay: 100,
-});
-
-const passwordInput = canvas.getByLabelText("password", {
-selector: "input",
-});
-
-await userEvent.type(passwordInput, "ExamplePassword", {
-delay: 100,
-});
-
-const submitButton = canvas.getByRole("button");
-await userEvent.click(submitButton);
-},
-};
-```
-
-The assertions should match the real pattern you copied:
-
-- for provider-backed stories, assert the provider-dependent UI
-appears correctly
-- for mocked-data stories, wait for the mocked data to appear and
-assert on it
-- for CSS-sensitive states, assert on visibility, text layout,
-class-driven states, or meaningful computed styles
-- for routing or navigation stories, assert the routed state or
-navigation outcome
-- for portal stories, query from `canvasElement.ownerDocument` when
-the UI renders outside the canvas
-
-Examples of useful checks:
-
-- a themed button has the expected label and is visibly enabled or
-disabled
-- a modal opened through a decorator or provider is visible in the
-portal root
-- mocked API data appears in the page instead of a loading spinner
-forever
-- a selected tab actually shows the selected panel
-- a toast, alert, or badge has the expected accessible text and visual
-state
-- a CSS class or computed style confirms the real state that matters
-
-### Step 7: Cover the patterns you found
-
-Write stories for the real patterns in the codebase, for example:
-
-- a low-level reusable component in real JSX usage
-- a provider-backed component
-- a browser-state-backed component
-- a fetched-data component
-- a real page component
-
-Use `App.tsx` to inspect the real provider tree and usage patterns,
-but do not make a story for `App` when the codebase has actual page
-components.
-
-Example page story:
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect } from 'storybook/test';
-import { ProductPage } from './ProductPage';
-
-const meta = {
-component: ProductPage,
-tags: ['ai-generated'],
-} satisfies Meta<typeof ProductPage>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-render: () => <ProductPage />,
-play: async ({ canvas }) => {
-await expect(
-canvas.getByRole('heading', { name: /products/i }),
-).toBeVisible();
-},
-};
-```
-
-### Step 8: Verify both rendering and types
-
-As you work, verify the stories with Vitest:
-
-```bash
-npx vitest --project storybook <path-to-story-file>
-```
-
-Also verify types so you catch missing required props, broken imports,
-and preview typing issues. Run the same TypeScript command the project
-itself uses.
-
-```bash
-<project-specific-typescript-command>
-```
-
-After verification passes, review every changed file and remove
-anything that is not needed for the final solution, especially debug
-fixes, overly broad mocks, unnecessary dependencies, and eval
-artifacts.
-
-Keep iterating until:
-
-- every story you wrote passes
-- every story you wrote has a meaningful passing `play` function
-- the changed stories and preview setup pass the project's real
-TypeScript check
-- the rendered output looks sensible
-- the default global mocked environment is strong enough that stories
-do not need manual fetch overrides
-- stories no longer fail because the shared preview setup and story
-JSX are fixed
-- all passing stories have `tags: ['ai-generated']` in their meta
-- any stories that still need work have `tags: ['ai-generated',
-'needs-work']` in their meta

From 617d22db6d4ee71abf2d88032b55e05f5f12db95 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 17:40:20 +0200
Subject: [PATCH 14/24] Factorise prompt building blocks for faster
 experimentation

---
 .../src/ai/setup-prompts/monorepo.ts          | 467 +++---------------
 .../src/ai/setup-prompts/partials/examples.ts | 203 ++++++++
 .../src/ai/setup-prompts/partials/rules.ts    |  52 ++
 .../src/ai/setup-prompts/partials/steps.ts    | 269 ++++++++++
 .../src/ai/setup-prompts/partials/types.ts    |  11 +
 .../src/ai/setup-prompts/relaxed-limits.ts    | 462 ++---------------
 code/lib/cli-storybook/src/ai/types.ts        |  10 +
 .../cli-storybook/src/ai/utils/markdown.ts    |  24 +
 scripts/eval/lib/projects.ts                  |   8 +
 9 files changed, 690 insertions(+), 816 deletions(-)
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
 create mode 100644 code/lib/cli-storybook/src/ai/setup-prompts/partials/types.ts
 create mode 100644 code/lib/cli-storybook/src/ai/utils/markdown.ts

diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts b/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
index f261abe3a684..b73e3f3e8656 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/monorepo.ts
@@ -1,434 +1,85 @@
 import { dedent } from 'ts-dedent';
 
-import type { ProjectInfo } from '../types.ts';
-import { getMonorepoType } from '../../../../../core/src/shared/utils/get-monorepo-type.ts';
-import { ext } from '../utils/ext.ts';
+import type { ProjectInfo, SetupInstructionsContext } from '../types.ts';
 import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
-
-function packageManagerRule(packageManagerName: string | undefined): string {
-  if (packageManagerName) {
-    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
-  }
-  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
-}
-
-function monorepoRules(): string | undefined {
-  const monorepoType = getMonorepoType();
-  if (monorepoType) {
-    return `**${monorepoType} monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
-  }
-}
-
-function readBudgetRules(): string | undefined {
-  return `**Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.`;
-}
-
-function getPreviewExample(projectInfo: ProjectInfo): string {
-  const { configDir, language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      // ${configDir}/preview.${tsx}
-      import '../src/index.css';
-      import MockDate from 'mockdate';
-      import { initialize, mswLoader } from 'msw-storybook-addon';
-      import { SessionProvider } from '../src/contexts/SessionContext';
-      import { mswHandlers } from './msw-handlers';
-
-      initialize({ onUnhandledRequest: 'bypass' });
-
-      const preview = {
-        decorators: [
-          (Story) => (
-            <SessionProvider>
-              <Story />
-            </SessionProvider>
-          ),
-        ],
-        loaders: [mswLoader],
-        parameters: { msw: { handlers: mswHandlers } },
-        async beforeEach() {
-          localStorage.setItem('theme', 'dark');
-          MockDate.set('2024-04-01T12:00:00Z');
-        },
-      };
-
-      export default preview;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    // ${configDir}/preview.${tsx}
-    import type { Preview } from '${typeImport}';
-    import '../src/index.css';
-    import MockDate from 'mockdate';
-    import { initialize, mswLoader } from 'msw-storybook-addon';
-    import { SessionProvider } from '../src/contexts/SessionContext';
-    import { mswHandlers } from './msw-handlers';
-
-    initialize({ onUnhandledRequest: 'bypass' });
-
-    const preview: Preview = {
-      decorators: [
-        (Story) => (
-          <SessionProvider>
-            <Story />
-          </SessionProvider>
-        ),
-      ],
-      loaders: [mswLoader],
-      parameters: { msw: { handlers: mswHandlers } },
-      async beforeEach() {
-        localStorage.setItem('theme', 'dark');
-        MockDate.set('2024-04-01T12:00:00Z');
-      },
-    };
-
-    export default preview;
-    \`\`\`
-  `;
-}
-
-function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-
-  return dedent`
-    \`\`\`${tsx}
-    // Add this entry to the \`decorators\` array of your preview config:
-    (Story) => {
-      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-        if (!document.getElementById(id)) {
-          const el = document.createElement('div');
-          el.id = id;
-          document.body.appendChild(el);
-        }
-      }
-      return <Story />;
-    }
-    \`\`\`
-  `;
-}
-
-function getMainConfigExample(projectInfo: ProjectInfo): string {
-  const { configDir, framework, rendererPackage, language } = projectInfo;
-  const ts = ext(language, false);
-  const typeImport = framework || rendererPackage || '@storybook/react';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`js
-      // ${configDir}/main.js
-      const config = { staticDirs: ['../public'] };
-      export default config;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${ts}
-    // ${configDir}/main.${ts}
-    import type { StorybookConfig } from '${typeImport}';
-
-    const config: StorybookConfig = { staticDirs: ['../public'] };
-    export default config;
-    \`\`\`
-  `;
-}
-
-function getStoryExample(projectInfo: ProjectInfo): string {
-  const { language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      import { expect } from 'storybook/test';
-      import { Button } from './Button';
-
-      const meta = {
-        component: Button,
-        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-      };
-
-      export default meta;
-
-      // Smoke check — one is enough per file
-      export const Primary = {
-        args: { children: 'Order now' },
-        play: async ({ canvas }) => {
-          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-        },
-      };
-
-      // Variant-only stories: no play needed
-      export const Clear = { args: { children: 'Cancel', clear: true } };
-      export const Large = { args: { children: 'Checkout', large: true } };
-      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    import type { Meta, StoryObj } from '${typeImport}';
-    import { expect } from 'storybook/test';
-    import { Button } from './Button';
-
-    const meta = {
-      component: Button,
-      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-    } satisfies Meta<typeof Button>;
-
-    export default meta;
-    type Story = StoryObj<typeof meta>;
-
-    // Smoke check — one is enough per file
-    export const Primary: Story = {
-      args: { children: 'Order now' },
-      play: async ({ canvas }) => {
-        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-      },
-    };
-
-    // Variant-only stories: no play needed
-    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-    export const Large: Story = { args: { children: 'Checkout', large: true } };
-    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-    \`\`\`
-  `;
-}
-
-function getInteractionPlayExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-  const typeAnnotation = language === 'ts' ? ': Story' : '';
-
-  return dedent`
-    \`\`\`${tsx}
-    export const FilledForm${typeAnnotation} = {
-      play: async ({ canvas, userEvent }) => {
-        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-      },
-    };
-    \`\`\`
-  `;
-}
+import { ext } from '../utils/ext.ts';
+import { listRules, listSteps } from '../utils/markdown.ts';
+import {
+  buildPortalStep,
+  buildSharedPreviewStep,
+  cleanupStep,
+  discoveryStepStrict,
+  interactionPlayStep,
+  monorepoStep,
+  mswStep,
+  verifyStep,
+  writeStoriesStep,
+} from './partials/steps.ts';
+import {
+  batchTestsRule,
+  editOverWriteRule,
+  monorepoRule,
+  nodeModuleReadsRule,
+  noPolishRule,
+  packageManagerRule,
+  preferSharedFixesRule,
+  readBudgetRule,
+  toolsVsShellRule,
+} from './partials/rules.ts';
 
 export function instructions(projectInfo: ProjectInfo): string {
   const { configDir, language, packageManager, packageManagerName } = projectInfo;
   const tsx = ext(language, true);
   const ts = ext(language, false);
   const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
-
   const mswInstall = packageManager.getInstallCommand(
     ['msw', 'msw-storybook-addon', 'mockdate'],
     true
   );
 
+  const ctx: SetupInstructionsContext = {
+    configDir,
+    docsUrl,
+    mswInstall,
+    packageManager,
+    packageManagerName,
+    tsx,
+    ts,
+  };
+
   return dedent`
     Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
 
     ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
-${[
-  `**Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-      - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
-      - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
-      - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
-      - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.`,
-
-  `**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`,
-  monorepoRules(),
-  readBudgetRules(),
-  `**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.`,
-  `**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`,
-  packageManagerRule(packageManagerName),
-  `**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`,
-  `**Stop when the success criteria are met** — don't keep polishing.`,
-]
-  .filter(Boolean)
-  .map((rule, index) => `${index + 1}. ${rule}`)
-  .join('\n')}
+    ${listRules([
+      toolsVsShellRule(ctx),
+      nodeModuleReadsRule(ctx),
+      monorepoRule(ctx),
+      readBudgetRule(ctx),
+      editOverWriteRule(ctx),
+      batchTestsRule(ctx),
+      packageManagerRule(ctx),
+      preferSharedFixesRule(ctx),
+      noPolishRule(ctx),
+    ])}
 
     ## Plan (do not skip steps, but keep each step lean)
 
-    ### Step 1 — Discover the runtime (≤12 reads)
-
-    Identify, in this order, using Glob/Grep first then targeted Reads:
-
-    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
-    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
-    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
-    - providers / context files — what they expose
-    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
-    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
-    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
-    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
-    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-    ### Step 2 — Build the shared preview
-
-    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
-
-    The complete shape should look like this (merge the new pieces into what's already there):
-
-    ${getPreviewExample(projectInfo)}
-
-    Rules for the preview:
-
-    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
-    - Use \`mockdate\` only when render output depends on the date.
-    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
-
-    ### Step 3 — Portals (in a decorator, not preview-body.html)
-
-    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
-
-    ${getPortalDecoratorExample(projectInfo)}
-
-    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
-
-    ### Step 4 — MSW handlers (only what stories will hit)
-
-    Use \`msw-storybook-addon\`. Install with:
-
-    \`\`\`bash
-    ${mswInstall}
-    npx msw init ./public --save
-    \`\`\`
-
-    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
-
-    ${getMainConfigExample(projectInfo)}
-
-    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-    \`\`\`${ts}
-    // ${configDir}/msw-handlers.${ts}
-    import { http, HttpResponse } from 'msw';
-
-    export const mswHandlers = {
-      products: [
-        http.get('https://api.example.com/products', () =>
-          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-        ),
+    ${listSteps(
+      [
+        discoveryStepStrict(projectInfo, ctx),
+        monorepoStep(projectInfo, ctx),
+        buildSharedPreviewStep(projectInfo, ctx),
+        buildPortalStep(projectInfo, ctx),
+        mswStep(projectInfo, ctx),
+        writeStoriesStep(projectInfo, ctx),
+        interactionPlayStep(projectInfo, ctx),
+        verifyStep(projectInfo, ctx),
+        cleanupStep(projectInfo, ctx),
       ],
-    };
-    \`\`\`
-
-    ### Step 5 — Write up to 10 story files (in one batch)
-
-    The deliverable for this step is **two things, both required**:
-
-    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
-    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
-
-    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-    ${getStoryExample(projectInfo)}
-
-    Story rules:
-
-    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
-    - Show all imports explicitly.
-    - Don't add a custom \`title\`.
-    - Don't build large story-specific harnesses — fix preview instead.
-    - Don't create new app components.
-
-    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
-
-    \`\`\`${tsx}
-    export const CssCheck: Story = {
-      args: { children: 'Submit' },
-      play: async ({ canvas }) => {
-        const button = canvas.getByRole('button', { name: /submit/i });
-        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-      },
-    };
-    \`\`\`
-
-    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
-
-    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
-
-    Write a \`play\` when it can verify:
-
-    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
-    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-    - **accessibility** that the component is responsible for (correct role/label exposure)
-
-    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
-    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
-    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
-    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
-
-    If none of those apply, skip the \`play\` and rely on the render itself.
-
-    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
-
-    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
-    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
-
-    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
-
-    Imports & play context — get this right or vitest will fail in subtle ways:
-
-    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
-    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
-    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
-
-    ${getInteractionPlayExample(projectInfo)}
-
-    ### Step 7 — Verify in one batch, then iterate only on failures
-
-    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-    \`\`\`bash
-    npx vitest --project storybook run
-    \`\`\`
-
-    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
-
-    For each failure:
-
-    1. Read the error.
-    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
-    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
-
-    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
-
-    ### Step 8 — Clean up
-
-    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+      { level: 3 }
+    )}
 
     ## Done when
 
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
new file mode 100644
index 000000000000..5d9bd883a5d4
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
@@ -0,0 +1,203 @@
+import dedent from 'ts-dedent';
+import type { ProjectInfo } from '../../types.ts';
+import { ext } from '../../utils/ext.ts';
+
+export function getPreviewExample(projectInfo: ProjectInfo): string {
+  const { configDir, language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      // ${configDir}/preview.${tsx}
+      import '../src/index.css';
+      import MockDate from 'mockdate';
+      import { initialize, mswLoader } from 'msw-storybook-addon';
+      import { SessionProvider } from '../src/contexts/SessionContext';
+      import { mswHandlers } from './msw-handlers';
+
+      initialize({ onUnhandledRequest: 'bypass' });
+
+      const preview = {
+        decorators: [
+          (Story) => (
+            <SessionProvider>
+              <Story />
+            </SessionProvider>
+          ),
+        ],
+        loaders: [mswLoader],
+        parameters: { msw: { handlers: mswHandlers } },
+        async beforeEach() {
+          localStorage.setItem('theme', 'dark');
+          MockDate.set('2024-04-01T12:00:00Z');
+        },
+      };
+
+      export default preview;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    // ${configDir}/preview.${tsx}
+    import type { Preview } from '${typeImport}';
+    import '../src/index.css';
+    import MockDate from 'mockdate';
+    import { initialize, mswLoader } from 'msw-storybook-addon';
+    import { SessionProvider } from '../src/contexts/SessionContext';
+    import { mswHandlers } from './msw-handlers';
+
+    initialize({ onUnhandledRequest: 'bypass' });
+
+    const preview: Preview = {
+      decorators: [
+        (Story) => (
+          <SessionProvider>
+            <Story />
+          </SessionProvider>
+        ),
+      ],
+      loaders: [mswLoader],
+      parameters: { msw: { handlers: mswHandlers } },
+      async beforeEach() {
+        localStorage.setItem('theme', 'dark');
+        MockDate.set('2024-04-01T12:00:00Z');
+      },
+    };
+
+    export default preview;
+    \`\`\`
+  `;
+}
+
+export function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+
+  return dedent`
+    \`\`\`${tsx}
+    // Add this entry to the \`decorators\` array of your preview config:
+    (Story) => {
+      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          document.body.appendChild(el);
+        }
+      }
+      return <Story />;
+    }
+    \`\`\`
+  `;
+}
+
+export function getMainConfigExample(projectInfo: ProjectInfo): string {
+  const { configDir, framework, rendererPackage, language } = projectInfo;
+  const ts = ext(language, false);
+  const typeImport = framework || rendererPackage || '@storybook/react';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`js
+      // ${configDir}/main.js
+      const config = { staticDirs: ['../public'] };
+      export default config;
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${ts}
+    // ${configDir}/main.${ts}
+    import type { StorybookConfig } from '${typeImport}';
+
+    const config: StorybookConfig = { staticDirs: ['../public'] };
+    export default config;
+    \`\`\`
+  `;
+}
+
+export function getStoryExample(projectInfo: ProjectInfo): string {
+  const { language, framework, rendererPackage } = projectInfo;
+  const tsx = ext(language, true);
+  const typeImport = framework || rendererPackage || '@storybook/react-vite';
+
+  if (language === 'js') {
+    return dedent`
+      \`\`\`${tsx}
+      import { expect } from 'storybook/test';
+      import { Button } from './Button';
+
+      const meta = {
+        component: Button,
+        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+      };
+
+      export default meta;
+
+      // Smoke check — one is enough per file
+      export const Primary = {
+        args: { children: 'Order now' },
+        play: async ({ canvas }) => {
+          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+        },
+      };
+
+      // Variant-only stories: no play needed
+      export const Clear = { args: { children: 'Cancel', clear: true } };
+      export const Large = { args: { children: 'Checkout', large: true } };
+      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+      \`\`\`
+    `;
+  }
+
+  return dedent`
+    \`\`\`${tsx}
+    import type { Meta, StoryObj } from '${typeImport}';
+    import { expect } from 'storybook/test';
+    import { Button } from './Button';
+
+    const meta = {
+      component: Button,
+      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+    } satisfies Meta<typeof Button>;
+
+    export default meta;
+    type Story = StoryObj<typeof meta>;
+
+    // Smoke check — one is enough per file
+    export const Primary: Story = {
+      args: { children: 'Order now' },
+      play: async ({ canvas }) => {
+        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+      },
+    };
+
+    // Variant-only stories: no play needed
+    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+    export const Large: Story = { args: { children: 'Checkout', large: true } };
+    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+    \`\`\`
+  `;
+}
+
+export function getInteractionPlayExample(projectInfo: ProjectInfo): string {
+  const { language } = projectInfo;
+  const tsx = ext(language, true);
+  const typeAnnotation = language === 'ts' ? ': Story' : '';
+
+  return dedent`
+    \`\`\`${tsx}
+    export const FilledForm${typeAnnotation} = {
+      play: async ({ canvas, userEvent }) => {
+        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+      },
+    };
+    \`\`\`
+  `;
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
new file mode 100644
index 000000000000..12d20d4db02d
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
@@ -0,0 +1,52 @@
+import dedent from 'ts-dedent';
+import type { SetupInstructionsContext } from '../../types.ts';
+import { getMonorepoType } from '../../../../../../core/src/shared/utils/get-monorepo-type.ts';
+
+export function toolsVsShellRule(ctx: SetupInstructionsContext): string {
+  return dedent`**Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+    - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
+    - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
+    - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
+    - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.`;
+}
+
+export function nodeModuleReadsRule(ctx: SetupInstructionsContext): string {
+  return dedent`**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`;
+}
+
+export function monorepoRule(ctx: SetupInstructionsContext): string | undefined {
+  const monorepoType = getMonorepoType();
+  if (monorepoType) {
+    return `**${monorepoType} monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
+  }
+}
+
+export function packageManagerRule({ packageManagerName }: SetupInstructionsContext): string {
+  if (packageManagerName) {
+    return dedent`**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
+  }
+  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
+}
+
+export function editOverWriteRule({ configDir, tsx }: SetupInstructionsContext): string {
+  return dedent`**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.`;
+}
+
+export function batchTestsRule(ctx: SetupInstructionsContext): string {
+  return dedent`**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`;
+}
+
+export function readBudgetRule(ctx: SetupInstructionsContext): string | undefined {
+  return dedent`**Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: \`index.html\`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).`;
+}
+
+export function preferSharedFixesRule({
+  configDir,
+  tsx,
+}: SetupInstructionsContext): string | undefined {
+  return dedent`**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`;
+}
+
+export function noPolishRule(ctx: SetupInstructionsContext): string | undefined {
+  return dedent`**Stop when the success criteria are met** — don't keep polishing.`;
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
new file mode 100644
index 000000000000..f7d7d9e34f6d
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
@@ -0,0 +1,269 @@
+import dedent from 'ts-dedent';
+import type { ProjectInfo, SetupInstructionsContext as InstructionsContext } from '../../types.ts';
+import {
+  getInteractionPlayExample,
+  getMainConfigExample,
+  getPortalDecoratorExample,
+  getPreviewExample,
+  getStoryExample,
+} from './examples.ts';
+
+export function discoveryStepStrict(
+  projectInfo: ProjectInfo,
+  { tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'Discover the runtime (≤12 reads)',
+    body: dedent`
+      Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+  `,
+  };
+}
+
+export function discoveryStepRelaxed(
+  projectInfo: ProjectInfo,
+  { tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'Discover the runtime (≤40 reads)',
+    body: dedent`
+      Identify, in this order, using Glob/Grep first then targeted Reads:
+
+    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
+    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
+    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
+    - providers / context files — what they expose
+    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
+    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
+    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
+    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
+    - 1–20 real page or feature components (your story source-of-truth for JSX patterns)
+
+    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render? What surrounding context do components need to render?"*
+  `,
+  };
+}
+
+export function verifyStep(
+  projectInfo: ProjectInfo,
+  { packageManager, tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: `Verify in one batch, then iterate only on failures`,
+    body: dedent`**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+    \`\`\`bash
+    npx vitest --project storybook run
+    \`\`\`
+
+    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
+
+    For each failure:
+
+    1. Read the error.
+    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
+    4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave \`'needs-work'\` tag to inform the user.
+    5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
+
+    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.`,
+  };
+}
+
+export function cleanupStep(
+  projectInfo: ProjectInfo,
+  ctx: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: `Clean up`,
+    body: `Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.`,
+  };
+}
+
+export function monorepoStep(
+  projectInfo: ProjectInfo,
+  ctx: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'Monorepo preparation',
+    body: dedent`Build any local monorepo dependencies identified during discovery, and keep track of existing errors in the codebase unrelated to the package changes you'll make.`,
+  };
+}
+
+export function buildSharedPreviewStep(
+  projectInfo: ProjectInfo,
+  { configDir, tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'Build the shared preview',
+    body: dedent`    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
+
+    The complete shape should look like this (merge the new pieces into what's already there):
+
+    ${getPreviewExample(projectInfo)}
+
+    Rules for the preview:
+
+    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
+    - Use \`mockdate\` only when render output depends on the date.
+    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
+    `,
+  };
+}
+
+export function buildPortalStep(
+  projectInfo: ProjectInfo,
+  { configDir, tsx }: { configDir: string; tsx: string }
+): { title: string; body: string } {
+  return {
+    title: 'Portals (in a decorator, not \`preview-body.html\`)',
+    body: dedent`If you found \`createPortal(..., document.getElementById('foo'))\` in discovery, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
+
+    ${getPortalDecoratorExample(projectInfo)}
+
+    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.`,
+  };
+}
+
+export function mswStep(
+  projectInfo: ProjectInfo,
+  { configDir, mswInstall, ts }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'MSW handlers (only what stories will hit)',
+    body: `Use \`msw-storybook-addon\`. Install with:
+
+    \`\`\`bash
+    ${mswInstall}
+    npx msw init ./public --save
+    \`\`\`
+
+    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
+
+    ${getMainConfigExample(projectInfo)}
+
+    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+    \`\`\`${ts}
+    // ${configDir}/msw-handlers.${ts}
+    import { http, HttpResponse } from 'msw';
+
+    export const mswHandlers = {
+      products: [
+        http.get('https://api.example.com/products', () =>
+          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+        ),
+      ],
+    };
+    \`\`\`
+`,
+  };
+}
+
+export function writeStoriesStep(
+  projectInfo: ProjectInfo,
+  { tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: 'Write up to 10 story files (in one batch)',
+    body: dedent`
+
+    This step has **two required deliverables**:
+
+    a. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
+    b. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This step is not complete without it.
+
+    **Substep a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
+
+    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+    ${getStoryExample(projectInfo)}
+
+    Story rules:
+
+    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
+    - Show all imports explicitly.
+    - Don't add a custom \`title\`.
+    - Don't build large story-specific harnesses — fix preview instead.
+    - Don't create new app components.
+
+    **Substep b — add the single \`CssCheck\` story.** Before you finish this step, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. This step is not complete until the story exists.
+
+    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
+
+    \`\`\`${tsx}
+    export const CssCheck: Story = {
+      args: { children: 'Submit' },
+      play: async ({ canvas }) => {
+        const button = canvas.getByRole('button', { name: /submit/i });
+        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+      },
+    };
+    \`\`\`
+    `,
+  };
+}
+
+export function interactionPlayStep(
+  projectInfo: ProjectInfo,
+  { tsx }: InstructionsContext
+): { title: string; body: string } {
+  return {
+    title: `Add \`play\` functions only where they prove something non-trivial`,
+    body: dedent`
+    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
+
+    Write a \`play\` when it can verify:
+
+    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
+    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+    - **accessibility** that the component is responsible for (correct role/label exposure)
+
+    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
+    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
+    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
+    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
+
+    If none of those apply, skip the \`play\` and rely on the render itself.
+
+    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
+
+    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
+    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
+
+    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
+
+    Imports & play context — get this right or vitest will fail in subtle ways:
+
+    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
+    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
+    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
+
+    ${getInteractionPlayExample(projectInfo)}`,
+  };
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/types.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/types.ts
new file mode 100644
index 000000000000..005aaedb809c
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/types.ts
@@ -0,0 +1,11 @@
+import type { JsPackageManager } from 'storybook/internal/common';
+
+export interface InstructionsContext {
+  configDir: string;
+  docsUrl: (path: string) => string;
+  mswInstall: string;
+  packageManager: JsPackageManager;
+  packageManagerName: string | undefined;
+  tsx: string;
+  ts: string;
+}
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
index 00a9ce85ae7f..463f23289dda 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
@@ -1,435 +1,81 @@
 import { dedent } from 'ts-dedent';
 
-import type { ProjectInfo } from '../types.ts';
-import { getMonorepoType } from '../../../../../core/src/shared/utils/get-monorepo-type.ts';
+import type { ProjectInfo, SetupInstructionsContext } from '../types.ts';
 import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
 import { ext } from '../utils/ext.ts';
-
-function packageManagerRule(packageManagerName: string | undefined): string {
-  if (packageManagerName) {
-    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
-  }
-  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
-}
-
-function monorepoRules(): string | undefined {
-  const monorepoType = getMonorepoType();
-  if (monorepoType) {
-    return `**${monorepoType} monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.`;
-  }
-}
-
-function readBudgetRules(): string | undefined {
-  return `**Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: \`index.html\`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).`;
-}
-
-function getPreviewExample(projectInfo: ProjectInfo): string {
-  const { configDir, language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      // ${configDir}/preview.${tsx}
-      import '../src/index.css';
-      import MockDate from 'mockdate';
-      import { initialize, mswLoader } from 'msw-storybook-addon';
-      import { SessionProvider } from '../src/contexts/SessionContext';
-      import { mswHandlers } from './msw-handlers';
-
-      initialize({ onUnhandledRequest: 'bypass' });
-
-      const preview = {
-        decorators: [
-          (Story) => (
-            <SessionProvider>
-              <Story />
-            </SessionProvider>
-          ),
-        ],
-        loaders: [mswLoader],
-        parameters: { msw: { handlers: mswHandlers } },
-        async beforeEach() {
-          localStorage.setItem('theme', 'dark');
-          MockDate.set('2024-04-01T12:00:00Z');
-        },
-      };
-
-      export default preview;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    // ${configDir}/preview.${tsx}
-    import type { Preview } from '${typeImport}';
-    import '../src/index.css';
-    import MockDate from 'mockdate';
-    import { initialize, mswLoader } from 'msw-storybook-addon';
-    import { SessionProvider } from '../src/contexts/SessionContext';
-    import { mswHandlers } from './msw-handlers';
-
-    initialize({ onUnhandledRequest: 'bypass' });
-
-    const preview: Preview = {
-      decorators: [
-        (Story) => (
-          <SessionProvider>
-            <Story />
-          </SessionProvider>
-        ),
-      ],
-      loaders: [mswLoader],
-      parameters: { msw: { handlers: mswHandlers } },
-      async beforeEach() {
-        localStorage.setItem('theme', 'dark');
-        MockDate.set('2024-04-01T12:00:00Z');
-      },
-    };
-
-    export default preview;
-    \`\`\`
-  `;
-}
-
-function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-
-  return dedent`
-    \`\`\`${tsx}
-    // Add this entry to the \`decorators\` array of your preview config:
-    (Story) => {
-      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-        if (!document.getElementById(id)) {
-          const el = document.createElement('div');
-          el.id = id;
-          document.body.appendChild(el);
-        }
-      }
-      return <Story />;
-    }
-    \`\`\`
-  `;
-}
-
-function getMainConfigExample(projectInfo: ProjectInfo): string {
-  const { configDir, framework, rendererPackage, language } = projectInfo;
-  const ts = ext(language, false);
-  const typeImport = framework || rendererPackage || '@storybook/react';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`js
-      // ${configDir}/main.js
-      const config = { staticDirs: ['../public'] };
-      export default config;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${ts}
-    // ${configDir}/main.${ts}
-    import type { StorybookConfig } from '${typeImport}';
-
-    const config: StorybookConfig = { staticDirs: ['../public'] };
-    export default config;
-    \`\`\`
-  `;
-}
-
-function getStoryExample(projectInfo: ProjectInfo): string {
-  const { language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      import { expect } from 'storybook/test';
-      import { Button } from './Button';
-
-      const meta = {
-        component: Button,
-        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-      };
-
-      export default meta;
-
-      // Smoke check — one is enough per file
-      export const Primary = {
-        args: { children: 'Order now' },
-        play: async ({ canvas }) => {
-          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-        },
-      };
-
-      // Variant-only stories: no play needed
-      export const Clear = { args: { children: 'Cancel', clear: true } };
-      export const Large = { args: { children: 'Checkout', large: true } };
-      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    import type { Meta, StoryObj } from '${typeImport}';
-    import { expect } from 'storybook/test';
-    import { Button } from './Button';
-
-    const meta = {
-      component: Button,
-      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-    } satisfies Meta<typeof Button>;
-
-    export default meta;
-    type Story = StoryObj<typeof meta>;
-
-    // Smoke check — one is enough per file
-    export const Primary: Story = {
-      args: { children: 'Order now' },
-      play: async ({ canvas }) => {
-        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-      },
-    };
-
-    // Variant-only stories: no play needed
-    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-    export const Large: Story = { args: { children: 'Checkout', large: true } };
-    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-    \`\`\`
-  `;
-}
-
-function getInteractionPlayExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-  const typeAnnotation = language === 'ts' ? ': Story' : '';
-
-  return dedent`
-    \`\`\`${tsx}
-    export const FilledForm${typeAnnotation} = {
-      play: async ({ canvas, userEvent }) => {
-        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-      },
-    };
-    \`\`\`
-  `;
-}
+import { listRules, listSteps } from '../utils/markdown.ts';
+import {
+  buildPortalStep,
+  buildSharedPreviewStep,
+  cleanupStep,
+  discoveryStepRelaxed,
+  interactionPlayStep,
+  mswStep,
+  verifyStep,
+  writeStoriesStep,
+} from './partials/steps.ts';
+import {
+  batchTestsRule,
+  editOverWriteRule,
+  nodeModuleReadsRule,
+  noPolishRule,
+  packageManagerRule,
+  preferSharedFixesRule,
+  readBudgetRule,
+  toolsVsShellRule,
+} from './partials/rules.ts';
 
 export function instructions(projectInfo: ProjectInfo): string {
   const { configDir, language, packageManager, packageManagerName } = projectInfo;
   const tsx = ext(language, true);
   const ts = ext(language, false);
   const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
-
   const mswInstall = packageManager.getInstallCommand(
     ['msw', 'msw-storybook-addon', 'mockdate'],
     true
   );
 
+  const ctx: SetupInstructionsContext = {
+    configDir,
+    docsUrl,
+    mswInstall,
+    packageManager,
+    packageManagerName,
+    tsx,
+    ts,
+  };
+
   return dedent`
     Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
 
     ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
-${[
-  `**Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-      - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
-      - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
-      - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
-      - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.`,
-
-  `**Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.`,
-  monorepoRules(),
-  readBudgetRules(),
-  `**Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.`,
-  `**Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.`,
-  packageManagerRule(packageManagerName),
-  `**Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.`,
-  `**Stop when the success criteria are met** — don't keep polishing.`,
-]
-  .filter(Boolean)
-  .map((rule, index) => `${index + 1}. ${rule}`)
-  .join('\n')}
+    ${listRules([
+      toolsVsShellRule(ctx),
+      nodeModuleReadsRule(ctx),
+      readBudgetRule(ctx),
+      editOverWriteRule(ctx),
+      batchTestsRule(ctx),
+      packageManagerRule(ctx),
+      preferSharedFixesRule(ctx),
+      noPolishRule(ctx),
+    ])}
 
     ## Plan (do not skip steps, but keep each step lean)
 
-    ### Step 1 — Discover the runtime (≤12 reads)
-
-    Identify, in this order, using Glob/Grep first then targeted Reads:
-
-    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
-    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
-    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
-    - providers / context files — what they expose
-    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
-    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
-    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
-    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
-    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-    ### Step 2 — Build the shared preview
-
-    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
-
-    The complete shape should look like this (merge the new pieces into what's already there):
-
-    ${getPreviewExample(projectInfo)}
-
-    Rules for the preview:
-
-    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
-    - Use \`mockdate\` only when render output depends on the date.
-    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
-
-    ### Step 3 — Portals (in a decorator, not preview-body.html)
-
-    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
-
-    ${getPortalDecoratorExample(projectInfo)}
-
-    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
-
-    ### Step 4 — MSW handlers (only what stories will hit)
-
-    Use \`msw-storybook-addon\`. Install with:
-
-    \`\`\`bash
-    ${mswInstall}
-    npx msw init ./public --save
-    \`\`\`
-
-    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
-
-    ${getMainConfigExample(projectInfo)}
-
-    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-    \`\`\`${ts}
-    // ${configDir}/msw-handlers.${ts}
-    import { http, HttpResponse } from 'msw';
-
-    export const mswHandlers = {
-      products: [
-        http.get('https://api.example.com/products', () =>
-          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-        ),
+    ${listSteps(
+      [
+        discoveryStepRelaxed(projectInfo, ctx),
+        buildSharedPreviewStep(projectInfo, ctx),
+        buildPortalStep(projectInfo, ctx),
+        mswStep(projectInfo, ctx),
+        writeStoriesStep(projectInfo, ctx),
+        interactionPlayStep(projectInfo, ctx),
+        verifyStep(projectInfo, ctx),
+        cleanupStep(projectInfo, ctx),
       ],
-    };
-    \`\`\`
-
-    ### Step 5 — Write up to 10 story files (in one batch)
-
-    The deliverable for this step is **two things, both required**:
-
-    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
-    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
-
-    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-    ${getStoryExample(projectInfo)}
-
-    Story rules:
-
-    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
-    - Show all imports explicitly.
-    - Don't add a custom \`title\`.
-    - Don't build large story-specific harnesses — fix preview instead.
-    - Don't create new app components.
-
-    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
-
-    \`\`\`${tsx}
-    export const CssCheck: Story = {
-      args: { children: 'Submit' },
-      play: async ({ canvas }) => {
-        const button = canvas.getByRole('button', { name: /submit/i });
-        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-      },
-    };
-    \`\`\`
-
-    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
-
-    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
-
-    Write a \`play\` when it can verify:
-
-    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
-    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-    - **accessibility** that the component is responsible for (correct role/label exposure)
-
-    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
-    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
-    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
-    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
-
-    If none of those apply, skip the \`play\` and rely on the render itself.
-
-    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
-
-    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
-    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
-
-    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
-
-    Imports & play context — get this right or vitest will fail in subtle ways:
-
-    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
-    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
-    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
-
-    ${getInteractionPlayExample(projectInfo)}
-
-    ### Step 7 — Verify in one batch, then iterate only on failures
-
-    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-    \`\`\`bash
-    npx vitest --project storybook run
-    \`\`\`
-
-    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
-
-    For each failure:
-
-    1. Read the error.
-    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
-    4. Repeat until the file passes, then move on. Cap retries at ~5 per file — if it still fails, leave \`'needs-work'\` tag to inform the user.
-    5. When you keep failing on a story, play function, etc., do not substitute it for easier content that contributes less to codebase understanding.
-
-    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
-
-    ### Step 8 — Clean up
-
-    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+      { level: 3 }
+    )}
 
     ## Done when
 
diff --git a/code/lib/cli-storybook/src/ai/types.ts b/code/lib/cli-storybook/src/ai/types.ts
index 8cbc7033b8ae..c9663ae0d6ac 100644
--- a/code/lib/cli-storybook/src/ai/types.ts
+++ b/code/lib/cli-storybook/src/ai/types.ts
@@ -30,3 +30,13 @@ export interface ProjectInfo {
   /** Whether the project's preview file uses the CSF Factory format. */
   hasCsfFactoryPreview: boolean;
 }
+
+export interface SetupInstructionsContext {
+  configDir: string;
+  docsUrl: (path: string) => string;
+  mswInstall: string;
+  packageManager: JsPackageManager;
+  packageManagerName: string | undefined;
+  tsx: string;
+  ts: string;
+}
diff --git a/code/lib/cli-storybook/src/ai/utils/markdown.ts b/code/lib/cli-storybook/src/ai/utils/markdown.ts
new file mode 100644
index 000000000000..99c7d135445f
--- /dev/null
+++ b/code/lib/cli-storybook/src/ai/utils/markdown.ts
@@ -0,0 +1,24 @@
+import dedent from 'ts-dedent';
+
+export function listRules(rules: (string | undefined)[]): string {
+  return dedent`
+    ${rules
+      .filter(Boolean)
+      .map((s, i) => `${i + 1}. ${s}`)
+      .join('\n')}
+  `;
+}
+
+export function listSteps(
+  steps: { title: string; body: string }[],
+  options?: { level?: number }
+): string {
+  const level = options?.level ?? 2;
+  const prefix = '#'.repeat(level);
+  return dedent`
+    ${steps
+      .filter(Boolean)
+      .map((step, i) => `${prefix} Step ${i + 1} — ${step.title}\n\n${step.body}`)
+      .join('\n\n')}
+  `;
+}
diff --git a/scripts/eval/lib/projects.ts b/scripts/eval/lib/projects.ts
index c344304dae37..2df9f44b17d6 100644
--- a/scripts/eval/lib/projects.ts
+++ b/scripts/eval/lib/projects.ts
@@ -67,4 +67,12 @@ export const PROJECTS: Project[] = [
     githubSlug: 'storybook-tmp/bluesky',
     description: 'React Native + React app with highly complex providers setup',
   },
+  {
+    name: 'react-spectrum',
+    repo: 'https://github.com/storybook-tmp/react-spectrum',
+    branch: 'main',
+    githubSlug: 'storybook-tmp/react-spectrum',
+    projectDir: 'packages/react-aria-components',
+    description: 'React headless UI library in a Lerna monorepo with shared utils',
+  },
 ];

From a411b1f48d1d4f46974ce81c9f3b14f11baafaa5 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 17:41:38 +0200
Subject: [PATCH 15/24] Convert one more prompt

---
 .../src/ai/setup-prompts/optimized-tests.ts   | 444 +++---------------
 1 file changed, 55 insertions(+), 389 deletions(-)

diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
index e73b2462e7b7..ac80395fd469 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/optimized-tests.ts
@@ -1,415 +1,81 @@
 import { dedent } from 'ts-dedent';
 
-import type { ProjectInfo } from '../types.ts';
-import { ext } from '../utils/ext.ts';
+import type { ProjectInfo, SetupInstructionsContext } from '../types.ts';
 import { getDocsMarkdownUrl } from '../utils/docs-markdown-url.ts';
-
-function packageManagerRule(packageManagerName: string | undefined): string {
-  if (packageManagerName) {
-    return `**Use \`${packageManagerName}\` for every install** (detected from this project's lockfile).`;
-  }
-  return '**Detect the package manager once** from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm) and use it for every install in this trial.';
-}
-
-function getPreviewExample(projectInfo: ProjectInfo): string {
-  const { configDir, language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      // ${configDir}/preview.${tsx}
-      import '../src/index.css';
-      import MockDate from 'mockdate';
-      import { initialize, mswLoader } from 'msw-storybook-addon';
-      import { SessionProvider } from '../src/contexts/SessionContext';
-      import { mswHandlers } from './msw-handlers';
-
-      initialize({ onUnhandledRequest: 'bypass' });
-
-      const preview = {
-        decorators: [
-          (Story) => (
-            <SessionProvider>
-              <Story />
-            </SessionProvider>
-          ),
-        ],
-        loaders: [mswLoader],
-        parameters: { msw: { handlers: mswHandlers } },
-        async beforeEach() {
-          localStorage.setItem('theme', 'dark');
-          MockDate.set('2024-04-01T12:00:00Z');
-        },
-      };
-
-      export default preview;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    // ${configDir}/preview.${tsx}
-    import type { Preview } from '${typeImport}';
-    import '../src/index.css';
-    import MockDate from 'mockdate';
-    import { initialize, mswLoader } from 'msw-storybook-addon';
-    import { SessionProvider } from '../src/contexts/SessionContext';
-    import { mswHandlers } from './msw-handlers';
-
-    initialize({ onUnhandledRequest: 'bypass' });
-
-    const preview: Preview = {
-      decorators: [
-        (Story) => (
-          <SessionProvider>
-            <Story />
-          </SessionProvider>
-        ),
-      ],
-      loaders: [mswLoader],
-      parameters: { msw: { handlers: mswHandlers } },
-      async beforeEach() {
-        localStorage.setItem('theme', 'dark');
-        MockDate.set('2024-04-01T12:00:00Z');
-      },
-    };
-
-    export default preview;
-    \`\`\`
-  `;
-}
-
-function getPortalDecoratorExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-
-  return dedent`
-    \`\`\`${tsx}
-    // Add this entry to the \`decorators\` array of your preview config:
-    (Story) => {
-      for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
-        if (!document.getElementById(id)) {
-          const el = document.createElement('div');
-          el.id = id;
-          document.body.appendChild(el);
-        }
-      }
-      return <Story />;
-    }
-    \`\`\`
-  `;
-}
-
-function getMainConfigExample(projectInfo: ProjectInfo): string {
-  const { configDir, framework, rendererPackage, language } = projectInfo;
-  const ts = ext(language, false);
-  const typeImport = framework || rendererPackage || '@storybook/react';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`js
-      // ${configDir}/main.js
-      const config = { staticDirs: ['../public'] };
-      export default config;
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${ts}
-    // ${configDir}/main.${ts}
-    import type { StorybookConfig } from '${typeImport}';
-
-    const config: StorybookConfig = { staticDirs: ['../public'] };
-    export default config;
-    \`\`\`
-  `;
-}
-
-function getStoryExample(projectInfo: ProjectInfo): string {
-  const { language, framework, rendererPackage } = projectInfo;
-  const tsx = ext(language, true);
-  const typeImport = framework || rendererPackage || '@storybook/react-vite';
-
-  if (language === 'js') {
-    return dedent`
-      \`\`\`${tsx}
-      import { expect } from 'storybook/test';
-      import { Button } from './Button';
-
-      const meta = {
-        component: Button,
-        tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-      };
-
-      export default meta;
-
-      // Smoke check — one is enough per file
-      export const Primary = {
-        args: { children: 'Order now' },
-        play: async ({ canvas }) => {
-          await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-        },
-      };
-
-      // Variant-only stories: no play needed
-      export const Clear = { args: { children: 'Cancel', clear: true } };
-      export const Large = { args: { children: 'Checkout', large: true } };
-      export const WithIcon = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-      \`\`\`
-    `;
-  }
-
-  return dedent`
-    \`\`\`${tsx}
-    import type { Meta, StoryObj } from '${typeImport}';
-    import { expect } from 'storybook/test';
-    import { Button } from './Button';
-
-    const meta = {
-      component: Button,
-      tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
-    } satisfies Meta<typeof Button>;
-
-    export default meta;
-    type Story = StoryObj<typeof meta>;
-
-    // Smoke check — one is enough per file
-    export const Primary: Story = {
-      args: { children: 'Order now' },
-      play: async ({ canvas }) => {
-        await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
-      },
-    };
-
-    // Variant-only stories: no play needed
-    export const Clear: Story = { args: { children: 'Cancel', clear: true } };
-    export const Large: Story = { args: { children: 'Checkout', large: true } };
-    export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
-    \`\`\`
-  `;
-}
-
-function getInteractionPlayExample(projectInfo: ProjectInfo): string {
-  const { language } = projectInfo;
-  const tsx = ext(language, true);
-  const typeAnnotation = language === 'ts' ? ': Story' : '';
-
-  return dedent`
-    \`\`\`${tsx}
-    export const FilledForm${typeAnnotation} = {
-      play: async ({ canvas, userEvent }) => {
-        await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
-        await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
-        await expect(await canvas.findByText(/welcome/i)).toBeVisible();
-      },
-    };
-    \`\`\`
-  `;
-}
+import { ext } from '../utils/ext.ts';
+import { listRules, listSteps } from '../utils/markdown.ts';
+import {
+  buildPortalStep,
+  buildSharedPreviewStep,
+  cleanupStep,
+  discoveryStepStrict,
+  interactionPlayStep,
+  mswStep,
+  verifyStep,
+  writeStoriesStep,
+} from './partials/steps.ts';
+import {
+  batchTestsRule,
+  editOverWriteRule,
+  nodeModuleReadsRule,
+  noPolishRule,
+  packageManagerRule,
+  preferSharedFixesRule,
+  readBudgetRule,
+  toolsVsShellRule,
+} from './partials/rules.ts';
 
 export function instructions(projectInfo: ProjectInfo): string {
   const { configDir, language, packageManager, packageManagerName } = projectInfo;
   const tsx = ext(language, true);
   const ts = ext(language, false);
   const docsUrl = (path: string) => getDocsMarkdownUrl(path, projectInfo);
-
   const mswInstall = packageManager.getInstallCommand(
     ['msw', 'msw-storybook-addon', 'mockdate'],
     true
   );
 
+  const ctx: SetupInstructionsContext = {
+    configDir,
+    docsUrl,
+    mswInstall,
+    packageManager,
+    packageManagerName,
+    tsx,
+    ts,
+  };
+
   return dedent`
     Your goal is to make Storybook fully functional in this project: configure \`${configDir}/preview.${tsx}\` with the right decorators, add MSW for data, and write up to 10 colocated \`*.stories.${tsx}\` files. Add \`play\` functions only where they prove something non-trivial.
 
     ## Rules of engagement (follow strictly — these are time budgets, not suggestions)
 
-    1. **Discover with Glob/Grep/Read, not shell.** Never use \`ls\`, \`find\`, \`cat\`, \`head\`, \`tail\`, shell \`grep\`, \`sed\`, or \`node -e\` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
-        - List a directory → \`Glob('src/components/*')\` (alt names: \`search_files\`, \`file_search\`), not \`ls src/components\`.
-        - Search a string → \`Grep('pattern', { path: 'src' })\` (alt names: \`grep_search\`, \`search_files\`), not \`grep -rn ...\` or \`find ... | xargs grep\`.
-        - Read a file → \`Read('path/to/file')\` (alt names: \`read_file\`), not \`cat\`/\`head\`/\`tail\`.
-        - Bulk-edit many files → multiple \`Edit\` calls (alt names: \`apply_patch\`, \`replace_in_file\`, \`replace\`), or one \`Edit\` with \`replace_all\` (alt names: \`replace\` with \`allow_multiple\`), not \`sed -i\`.
-    2. **Never read or grep inside \`node_modules\`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not \`node_modules\`.
-    3. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
-    4. **Edit > Write.** For any file you've Read, use \`Edit\`. Use \`Write\` only for new files. The project already has a \`${configDir}/preview.${tsx}\` from \`storybook init\` — **Edit** it, do not overwrite.
-    5. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
-    6. ${packageManagerRule(packageManagerName)}
-    7. **Prefer fixing the shared \`${configDir}/preview.${tsx}\`** over story-local workarounds when multiple stories fail the same way.
-    8. **Stop when the success criteria are met** — don't keep polishing.
+    ${listRules([
+      toolsVsShellRule(ctx),
+      nodeModuleReadsRule(ctx),
+      readBudgetRule(ctx),
+      editOverWriteRule(ctx),
+      batchTestsRule(ctx),
+      packageManagerRule(ctx),
+      preferSharedFixesRule(ctx),
+      noPolishRule(ctx),
+    ])}
 
     ## Plan (do not skip steps, but keep each step lean)
 
-    ### Step 1 — Discover the runtime (≤12 reads)
-
-    Identify, in this order, using Glob/Grep first then targeted Reads:
-
-    - \`index.html\` — \`<link rel="stylesheet">\` tags, inline \`<style>\` blocks, fonts, and any \`<div id="...">\` mount or portal roots that aren't created by JS
-    - entry file (\`main.${tsx}\` / \`index.${tsx}\`) — providers wrapping \`<App />\`, root CSS imports
-    - \`App.${tsx}\` — top-level layout, router usage, providers it consumes
-    - providers / context files — what they expose
-    - root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from \`index.html\`)
-    - data hooks — \`fetch(...)\`, \`useQuery\`, \`axios\`, etc. (capture base URL + endpoints actually called during render)
-    - browser state actually read at render — \`localStorage\`/\`sessionStorage\`/cookie keys
-    - portal targets — \`createPortal(...)\` and the DOM ids it mounts to (e.g. \`#modal-root\`)
-    - 1–2 real page or feature components (your story source-of-truth for JSX patterns)
-
-    Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
-
-    ### Step 2 — Build the shared preview
-
-    Set up Storybook **once** so most stories work without per-story setup. **Edit the existing \`${configDir}/preview.${tsx}\`** (created by \`storybook init\`) — add to its existing config object, don't replace it.
-
-    The complete shape should look like this (merge the new pieces into what's already there):
-
-    ${getPreviewExample(projectInfo)}
-
-    Rules for the preview:
-
-    - Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
-    - If the app's CSS is loaded via \`<link>\` in \`index.html\` (rather than imported in JS), import the same file from preview so stories render with the same styles.
-    - Seed only the specific browser-state keys the app actually reads. Do **not** clear all of \`localStorage\`/\`sessionStorage\`/cookies, and do not reset Storybook's own state.
-    - Use \`mockdate\` only when render output depends on the date.
-    - Do not mock \`window\`, \`document\`, \`navigator\`, observers, or \`fetch\` directly.
-
-    ### Step 3 — Portals (in a decorator, not preview-body.html)
-
-    If you found \`createPortal(..., document.getElementById('foo'))\` in Step 1, **add a decorator in \`${configDir}/preview.${tsx}\` that creates the portal root** before the story renders. Do not use \`preview-body.html\`.
-
-    ${getPortalDecoratorExample(projectInfo)}
-
-    Add this decorator to the \`decorators\` array of your preview config. Skip this step entirely if portals only target \`document.body\`.
-
-    ### Step 4 — MSW handlers (only what stories will hit)
-
-    Use \`msw-storybook-addon\`. Install with:
-
-    \`\`\`bash
-    ${mswInstall}
-    npx msw init ./public --save
-    \`\`\`
-
-    Make sure \`${configDir}/main.${ts}\` serves \`./public\`:
-
-    ${getMainConfigExample(projectInfo)}
-
-    Put handlers in \`${configDir}/msw-handlers.${ts}\`. Cover only the endpoints your stories will exercise — no catch-alls.
-
-    \`\`\`${ts}
-    // ${configDir}/msw-handlers.${ts}
-    import { http, HttpResponse } from 'msw';
-
-    export const mswHandlers = {
-      products: [
-        http.get('https://api.example.com/products', () =>
-          HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
-        ),
+    ${listSteps(
+      [
+        discoveryStepStrict(projectInfo, ctx),
+        buildSharedPreviewStep(projectInfo, ctx),
+        buildPortalStep(projectInfo, ctx),
+        mswStep(projectInfo, ctx),
+        writeStoriesStep(projectInfo, ctx),
+        interactionPlayStep(projectInfo, ctx),
+        verifyStep(projectInfo, ctx),
+        cleanupStep(projectInfo, ctx),
       ],
-    };
-    \`\`\`
-
-    ### Step 5 — Write up to 10 story files (in one batch)
-
-    The deliverable for this step is **two things, both required**:
-
-    1. Up to 10 colocated \`*.stories.${tsx}\` files for meaningful targets in the codebase.
-    2. **Exactly one \`CssCheck\` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
-
-    **Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and \`App\` itself when real page components exist.
-
-    Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
-
-    **Tag every new story file with \`['ai-generated', 'needs-work']\` from the start.** You will remove \`'needs-work'\` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
-
-    ${getStoryExample(projectInfo)}
-
-    Story rules:
-
-    - Start every meta with \`tags: ['ai-generated', 'needs-work']\`.
-    - Show all imports explicitly.
-    - Don't add a custom \`title\`.
-    - Don't build large story-specific harnesses — fix preview instead.
-    - Don't create new app components.
-
-    **Step 5b — add the single \`CssCheck\` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a \`CssCheck\` export to that file. Exactly **one** \`CssCheck\` across the whole project — not one per file. Step 5 is not complete until this exists.
-
-    Why it's mandatory: \`toBeVisible\` passes on an unstyled component. A concrete \`getComputedStyle\` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
-
-    How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like \`bg-blue-600\`, a CSS variable from the theme), and assert the resolved \`getComputedStyle\` value:
-
-    \`\`\`${tsx}
-    export const CssCheck: Story = {
-      args: { children: 'Submit' },
-      play: async ({ canvas }) => {
-        const button = canvas.getByRole('button', { name: /submit/i });
-        // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
-        await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
-      },
-    };
-    \`\`\`
-
-    ### Step 6 — Add \`play\` functions only where they prove something non-trivial
-
-    **Do not put a \`play\` on every story.** A \`play\` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good \`play\` per file over five redundant ones.
-
-    Write a \`play\` when it can verify:
-
-    - an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
-    - **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
-    - a **portal** rendered into the right root (query via \`canvasElement.ownerDocument\`)
-    - a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
-    - **accessibility** that the component is responsible for (correct role/label exposure)
-
-    **Skip \`play\` entirely** when a story is just a static variant of the same component (different \`args\`, no new behavior). Repeating \`getByRole(...).toBeVisible()\` across \`Clear\`, \`Large\`, \`WithIcon\` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
-
-    **Smoke plays must prove something the render alone doesn't.** A play that does only \`await expect(canvas.getByRole('button')).toBeVisible()\` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
-
-    - an **aria attribute reflecting state** (\`aria-expanded\`, \`aria-disabled\`, \`aria-checked\`, \`aria-current\`)
-    - a **prop value rendered as text or attribute** (e.g. \`args.label\` appears in the DOM, \`href\` matches \`args.to\`)
-    - **async content arriving** (\`findBy*\`, \`waitFor\` — proves the loader/MSW handler actually resolved)
-    - a **portal mounting in the right root** (queried via \`canvasElement.ownerDocument.body\`)
-
-    If none of those apply, skip the \`play\` and rely on the render itself.
-
-    Concretely, in a \`Button.stories.${tsx}\` with \`Primary\`, \`Clear\`, \`Large\`, \`WithIcon\`:
-
-    - \`Primary\` — keep one smoke \`play\` (one is enough for the file).
-    - \`Clear\`, \`Large\`, \`WithIcon\` — **no \`play\`**. They're variant-only stories.
-
-    (The single \`CssCheck\` story for the whole project was added in Step 5 — don't add another one here.)
-
-    Imports & play context — get this right or vitest will fail in subtle ways:
-
-    - \`expect\` and \`waitFor\` come from \`'storybook/test'\` — import those.
-    - \`canvas\`, \`userEvent\`, and \`canvasElement\` come from the **play arguments**: \`async ({ canvas, userEvent, canvasElement }) => { ... }\`. **Do not** \`import { userEvent } from 'storybook/test'\` and **do not** write \`const canvas = within(canvasElement)\` — both are already provided.
-    - For **portal queries only**, query via \`canvasElement.ownerDocument.body\`. You may import \`within\` from \`'storybook/test'\` for that case (e.g. \`within(canvasElement.ownerDocument.body).findByTestId(...)\`). Don't use \`within\` for anything else.
-
-    ${getInteractionPlayExample(projectInfo)}
-
-    ### Step 7 — Verify in one batch, then iterate only on failures
-
-    **Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
-
-    \`\`\`bash
-    npx vitest --project storybook run
-    \`\`\`
-
-    Then run the project's TypeScript check (use the script from \`package.json\` — typically \`tsc --noEmit\` or \`${packageManager.getRunCommand('typecheck')}\`). Read the raw output once; don't pipe it through repeated \`grep\`/\`head\` invocations to slice it.
-
-    For each failure:
-
-    1. Read the error.
-    2. If multiple stories share the failure, fix the shared preview setup, not the stories.
-    3. Re-run vitest **only for the affected file(s)**: \`npx vitest --project storybook run path/to/Foo.stories.${tsx}\`.
-    4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave \`'needs-work'\` and move on.
-
-    **After a file passes**, edit its meta and remove \`'needs-work'\` so its tags become \`['ai-generated']\`. Files you couldn't fix keep \`['ai-generated', 'needs-work']\` — move on, don't loop forever.
-
-    ### Step 8 — Clean up
-
-    Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+      { level: 3 }
+    )}
 
     ## Done when
 

From 8a1186edb8056893b776411744807beea86d680f Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 18:39:28 +0200
Subject: [PATCH 16/24] fix invalid imports missed by IDE, and old prompt
 regression

---
 code/lib/cli-storybook/src/ai/setup-prompts/index.ts        | 2 +-
 .../cli-storybook/src/ai/setup-prompts/partials/examples.ts | 2 +-
 .../cli-storybook/src/ai/setup-prompts/partials/rules.ts    | 6 +++++-
 .../cli-storybook/src/ai/setup-prompts/partials/steps.ts    | 2 +-
 .../cli-storybook/src/ai/setup-prompts/relaxed-limits.ts    | 4 ++--
 code/lib/cli-storybook/src/ai/utils/markdown.ts             | 2 +-
 6 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
index e2e10593349e..becc106e1aff 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
@@ -1,4 +1,4 @@
-import dedent from 'ts-dedent';
+import { dedent } from 'ts-dedent';
 import type { ProjectInfo } from '../types.ts';
 
 import * as optimizedTests from './optimized-tests.ts';
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
index 5d9bd883a5d4..0665bad3e843 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/examples.ts
@@ -1,4 +1,4 @@
-import dedent from 'ts-dedent';
+import { dedent } from 'ts-dedent';
 import type { ProjectInfo } from '../../types.ts';
 import { ext } from '../../utils/ext.ts';
 
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
index 12d20d4db02d..02cd8a5a7fe8 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/rules.ts
@@ -1,4 +1,4 @@
-import dedent from 'ts-dedent';
+import { dedent } from 'ts-dedent';
 import type { SetupInstructionsContext } from '../../types.ts';
 import { getMonorepoType } from '../../../../../../core/src/shared/utils/get-monorepo-type.ts';
 
@@ -37,6 +37,10 @@ export function batchTestsRule(ctx: SetupInstructionsContext): string {
 }
 
 export function readBudgetRule(ctx: SetupInstructionsContext): string | undefined {
+  return dedent`**Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (\`index.html\`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.`;
+}
+
+export function readBudgetRuleRelaxed(ctx: SetupInstructionsContext): string | undefined {
   return dedent`**Read budget: ~40 files for discovery.** Before writing any code you may Read at most ~40 files: \`index.html\`, entry, App, providers, routing, root CSS, 1–2 hooks, 1 test, and spend the rest on components. You may read direct component dependencies essential to their understanding only after having read 20 components (or all components if fewer in the codebase).`;
 }
 
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts b/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
index f7d7d9e34f6d..8b18a432a65b 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/partials/steps.ts
@@ -1,4 +1,4 @@
-import dedent from 'ts-dedent';
+import { dedent } from 'ts-dedent';
 import type { ProjectInfo, SetupInstructionsContext as InstructionsContext } from '../../types.ts';
 import {
   getInteractionPlayExample,
diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
index 463f23289dda..eb7bca072429 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/relaxed-limits.ts
@@ -21,7 +21,7 @@ import {
   noPolishRule,
   packageManagerRule,
   preferSharedFixesRule,
-  readBudgetRule,
+  readBudgetRuleRelaxed,
   toolsVsShellRule,
 } from './partials/rules.ts';
 
@@ -53,7 +53,7 @@ export function instructions(projectInfo: ProjectInfo): string {
     ${listRules([
       toolsVsShellRule(ctx),
       nodeModuleReadsRule(ctx),
-      readBudgetRule(ctx),
+      readBudgetRuleRelaxed(ctx),
       editOverWriteRule(ctx),
       batchTestsRule(ctx),
       packageManagerRule(ctx),
diff --git a/code/lib/cli-storybook/src/ai/utils/markdown.ts b/code/lib/cli-storybook/src/ai/utils/markdown.ts
index 99c7d135445f..6f58e7117ee7 100644
--- a/code/lib/cli-storybook/src/ai/utils/markdown.ts
+++ b/code/lib/cli-storybook/src/ai/utils/markdown.ts
@@ -1,4 +1,4 @@
-import dedent from 'ts-dedent';
+import { dedent } from 'ts-dedent';
 
 export function listRules(rules: (string | undefined)[]): string {
   return dedent`

From 0bd1037b1cf3e7b763ff6120a67db27bd933e59a Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Thu, 30 Apr 2026 20:17:09 +0200
Subject: [PATCH 17/24] Ensure eval script uses local dispatcher rather than
 project SB CLI canary

---
 .../settings/Checklist/AiSetupBlock.tsx       |  4 +--
 .../shared/checklist-store/checklistData.tsx  |  4 +--
 code/core/src/shared/constants/ai-prompts.ts  |  5 ---
 code/core/src/shared/utils/ai-prompts.ts      |  7 ++++
 scripts/eval/eval.ts                          |  2 +-
 scripts/eval/lib/agents/config.ts             |  2 +-
 scripts/eval/lib/run-trial.test.ts            | 12 ++++---
 scripts/eval/lib/run-trial.ts                 | 22 +++++++-----
 scripts/eval/lib/utils.test.ts                |  2 +-
 scripts/eval/lib/utils.ts                     | 35 +++++++++++++++----
 10 files changed, 64 insertions(+), 31 deletions(-)
 delete mode 100644 code/core/src/shared/constants/ai-prompts.ts
 create mode 100644 code/core/src/shared/utils/ai-prompts.ts

diff --git a/code/core/src/manager/settings/Checklist/AiSetupBlock.tsx b/code/core/src/manager/settings/Checklist/AiSetupBlock.tsx
index b4f3e3033214..7bf8e3aeab8e 100644
--- a/code/core/src/manager/settings/Checklist/AiSetupBlock.tsx
+++ b/code/core/src/manager/settings/Checklist/AiSetupBlock.tsx
@@ -8,7 +8,7 @@ import { CheckIcon, UndoIcon } from '@storybook/icons';
 import { type API, useStorybookApi } from 'storybook/manager-api';
 import { styled } from 'storybook/theming';
 
-import { AI_SETUP_PROMPT } from '../../../shared/constants/ai-prompts.ts';
+import { getAiSetupPrompt } from '../../../shared/utils/ai-prompts.ts';
 import { useCopyButton } from '../../../shared/useCopyButton.ts';
 import type { ItemId } from '../../../shared/checklist-store/index.ts';
 import type { ChecklistItem } from '../../components/sidebar/useChecklist.ts';
@@ -61,7 +61,7 @@ const CopyButton = ({ api }: { api: API }) => {
         <CheckIcon /> Copied!
       </>
     ),
-    content: AI_SETUP_PROMPT,
+    content: getAiSetupPrompt(),
     onCopy: () => {
       api.emit(AI_PROMPT_NUDGE, { id: 'setup', origin: 'onboarding-guide-page' });
     },
diff --git a/code/core/src/shared/checklist-store/checklistData.tsx b/code/core/src/shared/checklist-store/checklistData.tsx
index c5c20525b6fc..9f97721fe859 100644
--- a/code/core/src/shared/checklist-store/checklistData.tsx
+++ b/code/core/src/shared/checklist-store/checklistData.tsx
@@ -35,7 +35,7 @@ import { ADDON_ID as ADDON_DOCS_ID } from '../../docs-tools/shared.ts';
 import { TourGuide } from '../../manager/components/TourGuide/TourGuide.tsx';
 import { LocationMonitor } from '../../manager/hooks/useLocation.ts';
 import type { initialState } from './checklistData.state.ts';
-import { AI_SETUP_PROMPT } from '../constants/ai-prompts.ts';
+import { getAiSetupPrompt } from '../utils/ai-prompts.ts';
 
 const CodeWrapper = styled.div(({ theme }) => ({
   alignSelf: 'stretch',
@@ -176,7 +176,7 @@ export const checklistData = {
           showOnGuidePage: false,
           action: {
             label: 'Copy prompt',
-            copyContent: AI_SETUP_PROMPT,
+            copyContent: getAiSetupPrompt(),
             onClick: ({ api }) => {
               api.emit(AI_PROMPT_NUDGE, { id: 'setup', origin: 'onboarding-checklist-side' });
             },
diff --git a/code/core/src/shared/constants/ai-prompts.ts b/code/core/src/shared/constants/ai-prompts.ts
deleted file mode 100644
index 0c1d6f904bd5..000000000000
--- a/code/core/src/shared/constants/ai-prompts.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-/**
- * Source of truth for AI prompts throughout the application.
- */
-
-export const AI_SETUP_PROMPT = `Run \`npx storybook ai setup\` and follow its instructions precisely.`;
diff --git a/code/core/src/shared/utils/ai-prompts.ts b/code/core/src/shared/utils/ai-prompts.ts
new file mode 100644
index 000000000000..212b0926bf69
--- /dev/null
+++ b/code/core/src/shared/utils/ai-prompts.ts
@@ -0,0 +1,7 @@
+/**
+ * Source of truth for AI prompts throughout the application.
+ */
+
+export function getAiSetupPrompt(executor = 'npx storybook') {
+  return `Run \`${executor} ai setup\` and follow its instructions precisely.`;
+}
diff --git a/scripts/eval/eval.ts b/scripts/eval/eval.ts
index c5e5230fcf0f..86b6e4441773 100644
--- a/scripts/eval/eval.ts
+++ b/scripts/eval/eval.ts
@@ -252,7 +252,7 @@ function inferAgent(model: string): AgentId {
 
 function buildManualCommand(variant: AgentVariant, promptPath: string, promptName: string): string {
   // EVAL_SETUP_PROMPT must be in the env the agent inherits, so that the
-  // agent's own `npx storybook ai setup` tool call picks the right variant.
+  // agent's own `node <dispatcher> ai setup` tool call picks the right variant.
   const envPrefix = `EVAL_SETUP_PROMPT=${promptName} `;
   const escapedPath = promptPath.replace(/'/g, `'\\''`);
   const promptArg = `"$(cat '${escapedPath}')"`;
diff --git a/scripts/eval/lib/agents/config.ts b/scripts/eval/lib/agents/config.ts
index 71ca3986b125..a62ab827299d 100644
--- a/scripts/eval/lib/agents/config.ts
+++ b/scripts/eval/lib/agents/config.ts
@@ -50,7 +50,7 @@ export interface AgentExecuteParams {
    * Extra env vars to forward to the agent's spawn. Merged on top of
    * `process.env` and under the driver's fixed entries (e.g.
    * `STORYBOOK_DISABLE_TELEMETRY`). Used by the harness to inject
-   * `EVAL_SETUP_PROMPT` so that the agent's own `npx storybook ai setup`
+   * `EVAL_SETUP_PROMPT` so that the agent's own `node <dispatcher> ai setup`
    * tool call resolves to the selected prompt variant.
    */
   env?: Record<string, string>;
diff --git a/scripts/eval/lib/run-trial.test.ts b/scripts/eval/lib/run-trial.test.ts
index 957492069b2d..8759aa7b02e1 100644
--- a/scripts/eval/lib/run-trial.test.ts
+++ b/scripts/eval/lib/run-trial.test.ts
@@ -37,6 +37,10 @@ vi.mock('./utils', async (importOriginal) => {
       evalBranch: 'test-branch',
       evalCommit: 'abc123',
     }),
+    resolveDispatcherPath: vi.fn().mockReturnValue('/repo/code/core/dist/bin/dispatcher.js'),
+    loadPrompt: vi.fn().mockReturnValue(
+      'Run `node /repo/code/core/dist/bin/dispatcher.js ai setup` and follow its instructions precisely.'
+    ),
   };
 });
 vi.mock('./agents/claude-code', () => ({
@@ -166,7 +170,7 @@ describe('runTrial pipeline', () => {
 
     const params = vi.mocked(claudeAgent.execute).mock.calls[0][0];
     expect(params).toMatchObject({
-      prompt: expect.stringContaining('npx storybook ai setup'),
+      prompt: expect.stringMatching(/node .+dispatcher\.js ai setup/),
       projectPath: TMP,
       variant: { agent: 'claude', model: 'sonnet-4.6', effort: 'high' },
       resultsDir: join(TMP, '.storybook', 'eval-results'),
@@ -175,8 +179,8 @@ describe('runTrial pipeline', () => {
     expect(params.logger).toBeDefined();
 
     expect(vi.mocked(x)).toHaveBeenCalledWith(
-      'npx',
-      ['storybook', 'ai', 'setup'],
+      'node',
+      ['/repo/code/core/dist/bin/dispatcher.js', 'ai', 'setup'],
       expect.objectContaining({
         nodeOptions: expect.objectContaining({
           cwd: TMP,
@@ -259,7 +263,7 @@ describe('runTrial pipeline', () => {
     expect(data).not.toHaveProperty('artifacts.screenshotOutput');
 
     const promptContent = readFileSync(join(resultsDir, 'prompt.md'), 'utf-8');
-    expect(promptContent).toContain('npx storybook ai setup');
+    expect(promptContent).toMatch(/node .+dispatcher\.js ai setup/);
 
     const setupPromptContent = readFileSync(join(resultsDir, 'setup-prompt.md'), 'utf-8');
     expect(setupPromptContent).toContain('Full project-aware instructions');
diff --git a/scripts/eval/lib/run-trial.ts b/scripts/eval/lib/run-trial.ts
index 03152c03a1c2..b98a7fbb388e 100644
--- a/scripts/eval/lib/run-trial.ts
+++ b/scripts/eval/lib/run-trial.ts
@@ -16,6 +16,7 @@ import {
   generateTrialId,
   getEvalResultsRelativePath,
   loadPrompt,
+  resolveDispatcherPath,
 } from './utils.ts';
 
 export interface TrialConfig {
@@ -66,8 +67,10 @@ export async function runTrial(config: TrialConfig, logger?: Logger): Promise<Ru
   );
 
   // 4. Load the nudge prompt the agent will receive. The agent itself runs
-  //    `npx storybook ai setup` as a tool call — mirroring what real users do
-  //    when they copy the "Set up Storybook with AI" prompt from the UI.
+  //    `node <repo>/code/core/dist/bin/dispatcher.js ai setup` as a tool call.
+  //    This mirrors the real user flow but pins execution to the local
+  //    Storybook checkout so the trial exercises in-tree changes rather than
+  //    whatever version the benchmark project has installed.
   const prompt = loadPrompt(promptName);
   await writeFile(join(workspace.resultsDir, 'prompt.md'), prompt);
 
@@ -188,11 +191,13 @@ export async function runTrial(config: TrialConfig, logger?: Logger): Promise<Ru
 }
 
 /**
- * Run `npx storybook ai setup` inside the prepared trial workspace and return
- * its stdout — the exact project-aware markdown the agent will receive from
- * the same CLI invocation. `EVAL_SETUP_PROMPT` selects the variant;
- * `STORYBOOK_DISABLE_TELEMETRY` keeps the harness's capture invocation out of
- * telemetry.
+ * Run the local Storybook dispatcher's `ai setup` command inside the prepared
+ * trial workspace and return its stdout — the exact project-aware markdown the
+ * agent will receive from the same CLI invocation. Resolves to
+ * `code/core/dist/bin/dispatcher.js` from this checkout so it tests in-tree
+ * changes (not the project's installed Storybook). `EVAL_SETUP_PROMPT` selects
+ * the variant; `STORYBOOK_DISABLE_TELEMETRY` keeps the harness's capture
+ * invocation out of telemetry.
  *
  * Failures (spawn errors, timeouts, non-zero exit) are logged and swallowed:
  * capturing the prompt content is bookkeeping, not the thing being measured,
@@ -204,7 +209,8 @@ export async function captureAiSetupMarkdown(
   log: Logger
 ): Promise<string> {
   try {
-    const result = await x('npx', ['storybook', 'ai', 'setup'], {
+    const dispatcher = resolveDispatcherPath();
+    const result = await x('node', [dispatcher, 'ai', 'setup'], {
       throwOnError: false,
       timeout: 60_000,
       nodeOptions: {
diff --git a/scripts/eval/lib/utils.test.ts b/scripts/eval/lib/utils.test.ts
index bb197efcfd98..3a1e51425245 100644
--- a/scripts/eval/lib/utils.test.ts
+++ b/scripts/eval/lib/utils.test.ts
@@ -113,7 +113,7 @@ describe('listPrompts', () => {
 describe('loadPrompt', () => {
   it('returns the nudge string the agent receives (not the resolved instructions)', () => {
     const prompt = loadPrompt(EXAMPLE_PROMPT_BASENAME);
-    expect(prompt).toContain('npx storybook ai setup');
+    expect(prompt).toMatch(/node .+code\/core\/dist\/bin\/dispatcher\.js ai setup/);
     expect(prompt).not.toContain('### Step 1');
   });
 
diff --git a/scripts/eval/lib/utils.ts b/scripts/eval/lib/utils.ts
index 94d6472fdc2d..fbba1b6e2e51 100644
--- a/scripts/eval/lib/utils.ts
+++ b/scripts/eval/lib/utils.ts
@@ -1,12 +1,13 @@
+import { existsSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import pc from 'picocolors';
 import { x } from 'tinyexec';
 
-import { AI_SETUP_PROMPT } from '../../../code/core/src/shared/constants/ai-prompts.ts';
 import {
   DEFAULT_PROMPT_NAME,
   PROMPT_NAMES,
 } from '../../../code/lib/cli-storybook/src/ai/setup-prompts/index.ts';
+import { getAiSetupPrompt } from '../../../code/core/src/shared/utils/ai-prompts.ts';
 
 export interface Logger {
   log: (msg: string) => void;
@@ -16,6 +17,7 @@ export interface Logger {
 }
 
 export const REPO_ROOT = resolve(import.meta.dirname, '..', '..', '..');
+export const DISPATCHER_PATH = resolve(REPO_ROOT, 'code/core/dist/bin/dispatcher.js');
 export const EVAL_ROOT = resolve(REPO_ROOT, '..', 'storybook-eval');
 export const REPOS_DIR = resolve(EVAL_ROOT, 'repos');
 export const TRIALS_DIR = resolve(EVAL_ROOT, 'trials');
@@ -151,18 +153,37 @@ export function formatTable(headers: string[], rows: string[][]): string {
 }
 
 /**
- * Returns the exact nudge string a real user copies from the Storybook UI —
- * "Run `npx storybook ai setup` and follow its instructions precisely." The
- * AGENT then runs `ai setup` itself as a tool call, mirroring the real user
- * flow. The harness selects a prompt variant via the `EVAL_SETUP_PROMPT` env
- * var on the agent's spawn (not here); this function only validates the name.
+ * Resolves the absolute path to the local Storybook dispatcher CLI entrypoint
+ * (`code/core/dist/bin/dispatcher.js`) and asserts it has been built. The eval
+ * runs Storybook from this local checkout — not from the benchmark project's
+ * installed `node_modules` — so changes under `code/` are exercised by the
+ * trial. Throws a contributor-friendly error if the dispatcher is missing.
+ */
+export function resolveDispatcherPath(): string {
+  if (!existsSync(DISPATCHER_PATH)) {
+    throw new Error(
+      `Storybook dispatcher not found at ${DISPATCHER_PATH}. ` +
+        `Run \`yarn task compile -s compile\` from the repo root before running the eval.`
+    );
+  }
+  return DISPATCHER_PATH;
+}
+
+/**
+ * Returns the nudge string the eval gives the agent. Mirrors the real user
+ * flow ("Run `<command>` and follow its instructions precisely.") but points
+ * at the local dispatcher so the trial exercises the Storybook code under
+ * `code/` rather than whatever version the benchmark project has installed.
+ * The harness selects a prompt variant via the `EVAL_SETUP_PROMPT` env var on
+ * the agent's spawn (not here); this function only validates the name.
  */
 export function loadPrompt(name: string): string {
   const available = listPrompts();
   if (!available.includes(name)) {
     throw new Error(`Prompt not found: ${name}\nAvailable: ${available.join(', ')}`);
   }
-  return AI_SETUP_PROMPT;
+  const dispatcher = resolveDispatcherPath();
+  return getAiSetupPrompt(`node ${dispatcher}`);
 }
 
 /** List available prompt names. Mirrors the builder registry in the CLI. */

From 5591c98a6ec368564a74763eaeb868df1e38e9cd Mon Sep 17 00:00:00 2001
From: Yann Braga <yannbf@gmail.com>
Date: Mon, 4 May 2026 13:37:04 +0200
Subject: [PATCH 18/24] Update
 code/core/src/common/js-package-manager/BUNProxy.ts

---
 code/core/src/common/js-package-manager/BUNProxy.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/core/src/common/js-package-manager/BUNProxy.ts b/code/core/src/common/js-package-manager/BUNProxy.ts
index 897ab8a28784..600f0a60e371 100644
--- a/code/core/src/common/js-package-manager/BUNProxy.ts
+++ b/code/core/src/common/js-package-manager/BUNProxy.ts
@@ -76,7 +76,7 @@ export class BUNProxy extends JsPackageManager {
   }
 
   getCommandName(): string {
-    return 'npm';
+    return 'bun';
   }
 
   getInstallCommand(deps: string[], dev: boolean): string {

From 4288044c89f4ca43012a8f0c9f925e400a227c86 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Mon, 4 May 2026 14:02:24 +0200
Subject: [PATCH 19/24] fix CI issues

---
 scripts/eval/collect-pr-data.test.ts | 2 ++
 scripts/eval/lib/run-trial.test.ts   | 8 +++++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/scripts/eval/collect-pr-data.test.ts b/scripts/eval/collect-pr-data.test.ts
index 30f876b4adc5..791ae44ee2c4 100644
--- a/scripts/eval/collect-pr-data.test.ts
+++ b/scripts/eval/collect-pr-data.test.ts
@@ -1,10 +1,12 @@
 import { DatabaseSync } from 'node:sqlite';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+const execFileMock = vi.fn();
 const execFileSyncMock = vi.fn();
 const openDatabases: DatabaseSync[] = [];
 
 vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
   execFileSync: execFileSyncMock,
 }));
 
diff --git a/scripts/eval/lib/run-trial.test.ts b/scripts/eval/lib/run-trial.test.ts
index 8759aa7b02e1..bb45fb9f977c 100644
--- a/scripts/eval/lib/run-trial.test.ts
+++ b/scripts/eval/lib/run-trial.test.ts
@@ -38,9 +38,11 @@ vi.mock('./utils', async (importOriginal) => {
       evalCommit: 'abc123',
     }),
     resolveDispatcherPath: vi.fn().mockReturnValue('/repo/code/core/dist/bin/dispatcher.js'),
-    loadPrompt: vi.fn().mockReturnValue(
-      'Run `node /repo/code/core/dist/bin/dispatcher.js ai setup` and follow its instructions precisely.'
-    ),
+    loadPrompt: vi
+      .fn()
+      .mockReturnValue(
+        'Run `node /repo/code/core/dist/bin/dispatcher.js ai setup` and follow its instructions precisely.'
+      ),
   };
 });
 vi.mock('./agents/claude-code', () => ({

From 8d9e3c803ce88018182aa000dabd06f3833a6574 Mon Sep 17 00:00:00 2001
From: Jeppe Reinhold <jeppe@reinhold.is>
Date: Mon, 4 May 2026 14:03:40 +0200
Subject: [PATCH 20/24] Fix coverage type

---
 code/addons/vitest/src/node/vitest-manager.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/addons/vitest/src/node/vitest-manager.ts b/code/addons/vitest/src/node/vitest-manager.ts
index b5a6a9eb56d4..edc1115a1d9b 100644
--- a/code/addons/vitest/src/node/vitest-manager.ts
+++ b/code/addons/vitest/src/node/vitest-manager.ts
@@ -61,7 +61,7 @@ export class VitestManager {
       '@storybook/addon-vitest/internal/coverage-reporter',
       {
         testManager: this.testManager,
-        coverageOptions: this.vitest?.config?.coverage as ResolvedCoverageOptions<'v8'> | undefined,
+        coverageOptions: this.vitest?.config?.coverage as ResolvedCoverageOptions | undefined,
       },
     ];
     const coverageOptions = (

From f1d8228020fad67de78798fa158b7803955f8cc8 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Wed, 29 Apr 2026 21:24:00 +0200
Subject: [PATCH 21/24] Add setup instructions for local monorepo deps

---
 scripts/eval/prompts/monorepo.md | 300 +++++++++++++++++++++++++++++++
 1 file changed, 300 insertions(+)
 create mode 100644 scripts/eval/prompts/monorepo.md

diff --git a/scripts/eval/prompts/monorepo.md b/scripts/eval/prompts/monorepo.md
new file mode 100644
index 000000000000..dcd05ba11109
--- /dev/null
+++ b/scripts/eval/prompts/monorepo.md
@@ -0,0 +1,300 @@
+# Storybook Setup
+
+## Project Info
+
+| Property | Value |
+|----------|-------|
+| Version | 10.4.0-alpha.10 |
+| Renderer | @storybook/react |
+| Framework | @storybook/react-vite |
+| Builder | @storybook/builder-vite |
+| Config Dir | `.storybook` |
+| Language | TypeScript |
+| Package Manager | unknown package manager |
+| Addons | @storybook/addon-onboarding, @storybook/addon-themes, @storybook/addon-docs, @storybook/addon-designs, @storybook/addon-vitest, @storybook/addon-a11y, storybook-addon-pseudo-states, @chromatic-com/storybook |
+
+Your goal is to make Storybook fully functional in this project: configure `.storybook/preview.tsx` with the right decorators, add MSW for data, and write up to 10 colocated `*.stories.tsx` files. Add `play` functions only where they prove something non-trivial.
+
+## Rules of engagement (follow strictly — these are time budgets, not suggestions)
+
+1. **Discover with Glob/Grep/Read, not shell.** Never use `ls`, `find`, `cat`, `head`, `tail`, shell `grep`, `sed`, or `node -e` for discovery or for editing files in bulk — these are slower per call and violate caching. Substitute bash commands for the specific tool names listed below, or available tools with the closest semantics:
+      - List a directory → `Glob('src/components/*')` (alt names: `search_files`, `file_search`), not `ls src/components`.
+      - Search a string → `Grep('pattern', { path: 'src' })` (alt names: `grep_search`, `search_files`), not `grep -rn ...` or `find ... | xargs grep`.
+      - Read a file → `Read('path/to/file')` (alt names: `read_file`), not `cat`/`head`/`tail`.
+      - Bulk-edit many files → multiple `Edit` calls (alt names: `apply_patch`, `replace_in_file`, `replace`), or one `Edit` with `replace_all` (alt names: `replace` with `allow_multiple`), not `sed -i`.
+2. **Never read or grep inside `node_modules`.** The imports shown in this prompt are correct — don't verify them by introspecting installed packages. If something seems off, re-read this prompt, not `node_modules`.
+3. **Nx monorepo.** Don't initially look for config or existing Storybook content in other packages. Start exploring from config and tooling local to the package where you are asked to set up Storybook. If it uses local monorepo dependencies, build all dependencies found during discovery before writing stories or running tests.
+4. **Read budget: ~12 files for discovery.** Before writing any code you may Read at most ~12 files (`index.html`, entry, App, providers, routing, root CSS, 2–3 representative pages/components, 1–2 hooks, 1 test). If you need more, summarize and move on.
+5. **Edit > Write.** For any file you've Read, use `Edit`. Use `Write` only for new files. The project already has a `.storybook/preview.tsx` from `storybook init` — **Edit** it, do not overwrite.
+6. **Batch the test loop.** Write **all** stories first, then run vitest **once** across everything. No per-file vitest runs until after that first batch run reveals failures.
+7. **Use `unknown package manager` for every install** (detected from this project's lockfile).
+8. **Prefer fixing the shared `.storybook/preview.tsx`** over story-local workarounds when multiple stories fail the same way.
+9. **Stop when the success criteria are met** — don't keep polishing.
+
+## Plan (do not skip steps, but keep each step lean)
+
+### Step 1 — Discover the runtime (≤12 reads)
+
+Identify, in this order, using Glob/Grep first then targeted Reads:
+
+- `index.html` — `<link rel="stylesheet">` tags, inline `<style>` blocks, fonts, and any `<div id="...">` mount or portal roots that aren't created by JS
+- entry file (`main.tsx` / `index.tsx`) — providers wrapping `<App />`, root CSS imports
+- `App.tsx` — top-level layout, router usage, providers it consumes
+- providers / context files — what they expose
+- root CSS — global styles, CSS variables, theme tokens (both JS-imported CSS **and** anything linked from `index.html`)
+- data hooks — `fetch(...)`, `useQuery`, `axios`, etc. (capture base URL + endpoints actually called during render)
+- browser state actually read at render — `localStorage`/`sessionStorage`/cookie keys
+- portal targets — `createPortal(...)` and the DOM ids it mounts to (e.g. `#modal-root`)
+- 1–2 real page or feature components (your story source-of-truth for JSX patterns)
+
+Stop reading once you can answer: *"What providers, CSS, browser state, and network calls must the preview supply for a typical page to render?"*
+
+### Step 2 — Build the shared preview
+
+Set up Storybook **once** so most stories work without per-story setup. **Edit the existing `.storybook/preview.tsx`** (created by `storybook init`) — add to its existing config object, don't replace it.
+
+The complete shape should look like this (merge the new pieces into what's already there):
+
+```tsx
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react-vite';
+import '../src/index.css';
+import MockDate from 'mockdate';
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { SessionProvider } from '../src/contexts/SessionContext';
+import { mswHandlers } from './msw-handlers';
+
+initialize({ onUnhandledRequest: 'bypass' });
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <SessionProvider>
+        <Story />
+      </SessionProvider>
+    ),
+  ],
+  loaders: [mswLoader],
+  parameters: { msw: { handlers: mswHandlers } },
+  async beforeEach() {
+    localStorage.setItem('theme', 'dark');
+    MockDate.set('2024-04-01T12:00:00Z');
+  },
+};
+
+export default preview;
+```
+
+Rules for the preview:
+
+- Use the **real** provider tree and the **real** root CSS import. Don't invent providers.
+- If the app's CSS is loaded via `<link>` in `index.html` (rather than imported in JS), import the same file from preview so stories render with the same styles.
+- Seed only the specific browser-state keys the app actually reads. Do **not** clear all of `localStorage`/`sessionStorage`/cookies, and do not reset Storybook's own state.
+- Use `mockdate` only when render output depends on the date.
+- Do not mock `window`, `document`, `navigator`, observers, or `fetch` directly.
+
+### Step 3 — Portals (in a decorator, not preview-body.html)
+
+If you found `createPortal(..., document.getElementById('foo'))` in Step 1, **add a decorator in `.storybook/preview.tsx` that creates the portal root** before the story renders. Do not use `preview-body.html`.
+
+```tsx
+// Add this entry to the `decorators` array of your preview config:
+(Story) => {
+  for (const id of ['modal-root', 'drawer-root', 'toast-root']) {
+    if (!document.getElementById(id)) {
+      const el = document.createElement('div');
+      el.id = id;
+      document.body.appendChild(el);
+    }
+  }
+  return <Story />;
+}
+```
+
+Add this decorator to the `decorators` array of your preview config. Skip this step entirely if portals only target `document.body`.
+
+### Step 4 — MSW handlers (only what stories will hit)
+
+Use `msw-storybook-addon`. Install with:
+
+```bash
+<your-package-manager> add -D msw msw-storybook-addon mockdate
+npx msw init ./public --save
+```
+
+Make sure `.storybook/main.ts` serves `./public`:
+
+```ts
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = { staticDirs: ['../public'] };
+export default config;
+```
+
+Put handlers in `.storybook/msw-handlers.ts`. Cover only the endpoints your stories will exercise — no catch-alls.
+
+```ts
+// .storybook/msw-handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const mswHandlers = {
+  products: [
+    http.get('https://api.example.com/products', () =>
+      HttpResponse.json({ items: [{ id: 'p1', name: 'Example', price: 42 }] })
+    ),
+  ],
+};
+```
+
+### Step 5 — Write up to 10 story files (in one batch)
+
+The deliverable for this step is **two things, both required**:
+
+1. Up to 10 colocated `*.stories.tsx` files for meaningful targets in the codebase.
+2. **Exactly one `CssCheck` story** added to one of those files (spec below). This is part of Step 5; the step is not done without it.
+
+**Step 5a — pick targets and write the files.** Pick ~10 meaningful targets from the real codebase (low-level reusable → page components). Skip subcomponents, hooks, contexts, helpers, and `App` itself when real page components exist.
+
+Each story file: ~3 exports for typical components, up to ~10 when warranted by real usage. Copy JSX patterns from real pages/routes/tests.
+
+**Tag every new story file with `['ai-generated', 'needs-work']` from the start.** You will remove `'needs-work'` only after vitest confirms the file passes. This way, anything not yet verified — including stories you ran out of time to fix — stays correctly marked.
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  tags: ['ai-generated', 'needs-work'], // strip 'needs-work' once vitest passes
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Smoke check — one is enough per file
+export const Primary: Story = {
+  args: { children: 'Order now' },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByRole('button', { name: /order now/i })).toBeVisible();
+  },
+};
+
+// Variant-only stories: no play needed
+export const Clear: Story = { args: { children: 'Cancel', clear: true } };
+export const Large: Story = { args: { children: 'Checkout', large: true } };
+export const WithIcon: Story = { args: { icon: 'cart', 'aria-label': 'food cart' } };
+```
+
+Story rules:
+
+- Start every meta with `tags: ['ai-generated', 'needs-work']`.
+- Show all imports explicitly.
+- Don't add a custom `title`.
+- Don't build large story-specific harnesses — fix preview instead.
+- Don't create new app components.
+
+**Step 5b — add the single `CssCheck` story.** Before you finish Step 5, pick **one** visually distinctive component from the files you just wrote and add a `CssCheck` export to that file. Exactly **one** `CssCheck` across the whole project — not one per file. Step 5 is not complete until this exists.
+
+Why it's mandatory: `toBeVisible` passes on an unstyled component. A concrete `getComputedStyle` value is the only proof that the shared preview actually loaded the app's CSS — without it, you have no idea whether your stories are rendering correctly.
+
+How: read a real styling value from the component's source (e.g. a hex color in styled-components, a Tailwind class like `bg-blue-600`, a CSS variable from the theme), and assert the resolved `getComputedStyle` value:
+
+```tsx
+export const CssCheck: Story = {
+  args: { children: 'Submit' },
+  play: async ({ canvas }) => {
+    const button = canvas.getByRole('button', { name: /submit/i });
+    // PrimaryButton uses bg-blue-600 — fails if Tailwind / global CSS did not load.
+    await expect(getComputedStyle(button).backgroundColor).toBe('rgb(37, 99, 235)');
+  },
+};
+```
+
+### Step 6 — Add `play` functions only where they prove something non-trivial
+
+**Do not put a `play` on every story.** A `play` is worth writing only when it asserts something the rendered output alone doesn't already prove. Prefer one good `play` per file over five redundant ones.
+
+Write a `play` when it can verify:
+
+- an **interaction** (form fill + submit, click → menu opens, tab change reveals panel)
+- **async data** actually arrived from MSW (waiting for mocked content to replace a spinner)
+- a **portal** rendered into the right root (query via `canvasElement.ownerDocument`)
+- a **CSS-driven state** that matters semantically (e.g. theme color, disabled styling, layout that confirms the global stylesheet loaded)
+- **accessibility** that the component is responsible for (correct role/label exposure)
+
+**Skip `play` entirely** when a story is just a static variant of the same component (different `args`, no new behavior). Repeating `getByRole(...).toBeVisible()` across `Clear`, `Large`, `WithIcon` etc. is redundant — the render itself already fails the test if the component throws or doesn't mount.
+
+**Smoke plays must prove something the render alone doesn't.** A play that does only `await expect(canvas.getByRole('button')).toBeVisible()` adds nothing — the render already failed if the button didn't mount. Acceptable smoke plays assert one of:
+
+- an **aria attribute reflecting state** (`aria-expanded`, `aria-disabled`, `aria-checked`, `aria-current`)
+- a **prop value rendered as text or attribute** (e.g. `args.label` appears in the DOM, `href` matches `args.to`)
+- **async content arriving** (`findBy*`, `waitFor` — proves the loader/MSW handler actually resolved)
+- a **portal mounting in the right root** (queried via `canvasElement.ownerDocument.body`)
+
+If none of those apply, skip the `play` and rely on the render itself.
+
+Concretely, in a `Button.stories.tsx` with `Primary`, `Clear`, `Large`, `WithIcon`:
+
+- `Primary` — keep one smoke `play` (one is enough for the file).
+- `Clear`, `Large`, `WithIcon` — **no `play`**. They're variant-only stories.
+
+(The single `CssCheck` story for the whole project was added in Step 5 — don't add another one here.)
+
+Imports & play context — get this right or vitest will fail in subtle ways:
+
+- `expect` and `waitFor` come from `'storybook/test'` — import those.
+- `canvas`, `userEvent`, and `canvasElement` come from the **play arguments**: `async ({ canvas, userEvent, canvasElement }) => { ... }`. **Do not** `import { userEvent } from 'storybook/test'` and **do not** write `const canvas = within(canvasElement)` — both are already provided.
+- For **portal queries only**, query via `canvasElement.ownerDocument.body`. You may import `within` from `'storybook/test'` for that case (e.g. `within(canvasElement.ownerDocument.body).findByTestId(...)`). Don't use `within` for anything else.
+
+```tsx
+export const FilledForm: Story = {
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.type(canvas.getByLabelText('email'), 'a@b.com', { delay: 50 });
+    await userEvent.click(canvas.getByRole('button', { name: /submit/i }));
+    await expect(await canvas.findByText(/welcome/i)).toBeVisible();
+  },
+};
+```
+
+### Step 7 — Verify in one batch, then iterate only on failures
+
+**Read this rule once before running anything:** the first vitest invocation must run **all** the new stories together. No single-file runs before the batch.
+
+```bash
+npx vitest --project storybook run
+```
+
+Then run the project's TypeScript check (use the script from `package.json` — typically `tsc --noEmit` or `unknown package manager run typecheck`). Read the raw output once; don't pipe it through repeated `grep`/`head` invocations to slice it.
+
+For each failure:
+
+1. Read the error.
+2. If multiple stories share the failure, fix the shared preview setup, not the stories.
+3. Re-run vitest **only for the affected file(s)**: `npx vitest --project storybook run path/to/Foo.stories.tsx`.
+4. Repeat until the file passes, then move on. Cap retries at ~2 per file — if it still fails, leave `'needs-work'` and move on.
+
+**After a file passes**, edit its meta and remove `'needs-work'` so its tags become `['ai-generated']`. Files you couldn't fix keep `['ai-generated', 'needs-work']` — move on, don't loop forever.
+
+### Step 8 — Clean up
+
+Before finishing, remove debug code, broad mocks added during diagnosis, unused deps, and eval artifacts.
+
+## Done when
+
+- **Exactly one `CssCheck` story exists** somewhere in the new stories, asserting a concrete computed style value read from the component's source (added at the end of Step 5).
+- Every story file you wrote that vitest confirmed passing has had `'needs-work'` stripped, leaving `tags: ['ai-generated']`. Anything still failing keeps `['ai-generated', 'needs-work']`.
+- `npx vitest --project storybook run` passes for the new files.
+- The project's TypeScript check passes for changed files.
+- The shared preview is strong enough that stories don't need per-story fetch/provider workarounds.
+
+## Reference (only fetch if stuck)
+
+- Docs index: https://storybook.js.org/llms.txt
+- Writing stories: https://storybook.js.org/docs/10/writing-stories.md?renderer=react&language=ts
+- Decorators: https://storybook.js.org/docs/10/writing-stories/decorators.md?renderer=react&language=ts
+- Play functions: https://storybook.js.org/docs/10/writing-stories/play-function.md?renderer=react&language=ts
+- Vitest integration: https://storybook.js.org/docs/10/writing-tests/vitest-plugin.md?renderer=react&language=ts
+
+Append `?codeOnly=true` to any docs URL for code-only snippets. Don't fetch unless a specific question can't be answered from this prompt.

From e91e71f86d6cce20f0864e1949d284c3de9fc0ab Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Mon, 4 May 2026 14:53:57 +0200
Subject: [PATCH 22/24] Agentic Setup: Update project list in tests

---
 scripts/eval/run-batch.test.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/scripts/eval/run-batch.test.ts b/scripts/eval/run-batch.test.ts
index 49ad2a712868..0ee0ee699e55 100644
--- a/scripts/eval/run-batch.test.ts
+++ b/scripts/eval/run-batch.test.ts
@@ -163,6 +163,7 @@ describe('buildBatchRunDescriptors', () => {
       { project: 'evergreen-ci', agent: 'claude', repetition: 1 },
       { project: 'excalidraw', agent: 'claude', repetition: 1 },
       { project: 'bluesky', agent: 'claude', repetition: 1 },
+      { project: 'react-aria', agent: 'claude', repetition: 1 },
       { project: 'mealdrop', agent: 'codex', repetition: 1 },
       { project: 'edgy', agent: 'codex', repetition: 1 },
       { project: 'wikitok', agent: 'codex', repetition: 1 },
@@ -170,6 +171,7 @@ describe('buildBatchRunDescriptors', () => {
       { project: 'evergreen-ci', agent: 'codex', repetition: 1 },
       { project: 'excalidraw', agent: 'codex', repetition: 1 },
       { project: 'bluesky', agent: 'codex', repetition: 1 },
+      { project: 'react-aria', agent: 'codex', repetition: 1 },
     ]);
   });
 });
@@ -201,6 +203,7 @@ describe('buildBatchVariants', () => {
       'evergreen-ci',
       'excalidraw',
       'bluesky',
+      'react-aria',
     ]);
   });
 

From 5a24a5cdda13bf0163aaaa80c0777caf3ed7de56 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Mon, 4 May 2026 15:06:30 +0200
Subject: [PATCH 23/24] Fix project name

---
 scripts/eval/run-batch.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/eval/run-batch.test.ts b/scripts/eval/run-batch.test.ts
index 0ee0ee699e55..d1384ca3b509 100644
--- a/scripts/eval/run-batch.test.ts
+++ b/scripts/eval/run-batch.test.ts
@@ -163,7 +163,7 @@ describe('buildBatchRunDescriptors', () => {
       { project: 'evergreen-ci', agent: 'claude', repetition: 1 },
       { project: 'excalidraw', agent: 'claude', repetition: 1 },
       { project: 'bluesky', agent: 'claude', repetition: 1 },
-      { project: 'react-aria', agent: 'claude', repetition: 1 },
+      { project: 'react-spectrum', agent: 'claude', repetition: 1 },
       { project: 'mealdrop', agent: 'codex', repetition: 1 },
       { project: 'edgy', agent: 'codex', repetition: 1 },
       { project: 'wikitok', agent: 'codex', repetition: 1 },
@@ -171,7 +171,7 @@ describe('buildBatchRunDescriptors', () => {
       { project: 'evergreen-ci', agent: 'codex', repetition: 1 },
       { project: 'excalidraw', agent: 'codex', repetition: 1 },
       { project: 'bluesky', agent: 'codex', repetition: 1 },
-      { project: 'react-aria', agent: 'codex', repetition: 1 },
+      { project: 'react-spectrum', agent: 'codex', repetition: 1 },
     ]);
   });
 });
@@ -203,7 +203,7 @@ describe('buildBatchVariants', () => {
       'evergreen-ci',
       'excalidraw',
       'bluesky',
-      'react-aria',
+      'react-spectrum',
     ]);
   });
 

From 69e3dc2c4ebd7522801d6bd1b51d4ac28f675f60 Mon Sep 17 00:00:00 2001
From: Steve Dodier-Lazaro <sidnioulz@gmail.com>
Date: Mon, 4 May 2026 15:30:52 +0200
Subject: [PATCH 24/24] Update default prompt

---
 .../cli-storybook/src/ai/setup-prompts/index.ts  | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
index becc106e1aff..1382eee4c561 100644
--- a/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
+++ b/code/lib/cli-storybook/src/ai/setup-prompts/index.ts
@@ -1,14 +1,20 @@
 import { dedent } from 'ts-dedent';
 import type { ProjectInfo } from '../types.ts';
 
-import * as optimizedTests from './optimized-tests.ts';
 import { getProjectOverview } from '../utils/project-overview.ts';
 
+/**
+ * The single prompt variant that ships to real users. Running
+ * `npx storybook ai setup` without any overrides always produces this prompt.
+ */
+import * as currentlyUsedPrompt from './pattern-copy-play.ts';
+export const DEFAULT_PROMPT_NAME: PromptName = 'pattern-copy-play';
+
 /**
  * Main prompt used currently in `npx storybook ai setup` command. If you promote a new prompt to be default, move this to the FORMERLY_USED_PROMPTS object below.
  */
 const CURRENTLY_USED_PROMPT: Record<string, (projectInfo: ProjectInfo) => string> = {
-  'optimized-tests': optimizedTests.instructions,
+  [DEFAULT_PROMPT_NAME]: currentlyUsedPrompt.instructions,
 };
 
 /**
@@ -32,12 +38,6 @@ export const PROMPT_NAMES: PromptName[] = [
   ...Object.keys(FORMERLY_USED_PROMPTS),
 ];
 
-/**
- * The single prompt variant that ships to real users. Running
- * `npx storybook ai setup` without any overrides always produces this prompt.
- */
-export const DEFAULT_PROMPT_NAME: PromptName = 'optimized-tests';
-
 /**
  * Internal env var read only by `getPrompts`. The eval harness sets this
  * before spawning `ai setup` to select a non-default prompt variant for A/B