docs: extend all 18 AGENTS.md files with comprehensive context, code examples, and recipes

apps/storybook/AGENTS.md

@@ -1,24 +1,135 @@
-# apps/storybook — Centralized Storybook
+# apps/storybook -- Centralized Storybook
 
-Pulls stories from `packages/ui/src/**/*.stories.tsx`. Uses `@storybook/react-vite` with `@tailwindcss/vite` plugin.
+## Purpose
 
-## Development
+Centralized Storybook instance that pulls and renders all stories from `packages/ui`. Provides a visual development environment, component documentation, and MCP integration for AI agents.
+
+## Port: 6006
 
 ```bash
-pnpm dev --filter @repo/storybook  # Starts on port 6006
+pnpm dev --filter @repo/storybook   # http://localhost:6006
 ```
 
 ## Configuration
 
-- `.storybook/main.ts` — Framework config, story globs, Tailwind vite plugin
-- `.storybook/preview.ts` — Global CSS import, control matchers
+### `.storybook/main.ts`
+
+```typescript
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  framework: "@storybook/react-vite",
+  stories: ["../../../packages/ui/src/**/*.stories.@(ts|tsx)"],
+  addons: ["@storybook/addon-essentials"],
+  docs: {
+    autodocs: "tag",
+  },
+  async viteFinal(config) {
+    const { mergeConfig } = await import("vite");
+    const tailwindPlugin = await import("@tailwindcss/vite");
+
+    return mergeConfig(config, {
+      plugins: [tailwindPlugin.default()],
+    });
+  },
+};
+```
+
+Key configuration details:
+- **`stories`** glob reaches into `packages/ui/src/` to find all `.stories.tsx` files
+- **`viteFinal`** adds the `@tailwindcss/vite` plugin so Tailwind v4 classes render correctly in stories
+- **`autodocs: "tag"`** generates documentation pages for stories tagged with `"autodocs"`
+- **`@storybook/addon-essentials`** includes Controls, Actions, Backgrounds, Viewport, Docs
+
+### `.storybook/preview.ts`
+
+```typescript
+import type { Preview } from "@storybook/react";
+import "../../../packages/ui/src/styles/globals.css";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+```
+
+Key details:
+- Imports `globals.css` from `@repo/ui` so all Tailwind v4 `@theme` tokens are available
+- Control matchers auto-detect color and date props for appropriate editor widgets
 
 ## Story Organization
 
-Stories are organized by Atomic Design level via title:
-- `"Atoms/Button"`, `"Molecules/FormField"`, `"Organisms/DataTable"`
+Stories are organized by Atomic Design level via the `title` field in story metadata. The title determines the sidebar hierarchy in Storybook.
 
-## MCP
+### Story Title Convention
 
-When running, Storybook MCP is available at `http://localhost:6006/mcp`.
-Install `@storybook/addon-mcp` to enable.
+| Level | Title format | Example | Sidebar path |
+|---|---|---|---|
+| Atom | `"Atoms/{ComponentName}"` | `"Atoms/Button"` | Atoms > Button |
+| Molecule | `"Molecules/{ComponentName}"` | `"Molecules/FormField"` | Molecules > FormField |
+| Organism | `"Organisms/{ComponentName}"` | `"Organisms/DataTable"` | Organisms > DataTable |
+| Template | `"Templates/{ComponentName}"` | `"Templates/DashboardLayout"` | Templates > DashboardLayout |
+
+### Existing Stories
+
+| Story title | Component | Location in `@repo/ui` |
+|---|---|---|
+| `Atoms/Button` | Button (5 variants: Default, Secondary, Destructive, Outline, Ghost) | `src/atoms/button/button.stories.tsx` |
+| `Atoms/Input` | Input (Default, Disabled) | `src/atoms/input/input.stories.tsx` |
+| `Molecules/FormField` | FormField (Default, WithDescription, WithError) | `src/molecules/form-field/form-field.stories.tsx` |
+
+## MCP Integration
+
+When Storybook is running, the MCP (Model Context Protocol) endpoint is available at:
+
+```
+http://localhost:6006/mcp
+```
+
+### Available MCP tools:
+
+- **`list-all-documentation`** -- Lists all documented components and their stories
+- **`get-documentation`** -- Gets detailed documentation for a specific component (props, variants, usage)
+- **`run-story-tests`** -- Runs visual tests on stories to validate rendering
+
+### Installing addon-mcp
+
+If `@storybook/addon-mcp` is not already installed:
+
+```bash
+npx storybook add @storybook/addon-mcp
+```
+
+This adds the addon to `.storybook/main.ts` and enables the MCP endpoint.
+
+### Using MCP in workflows
+
+Always query MCP before creating new UI components:
+
+1. **Before creating:** `list-all-documentation` to check if a similar component exists
+2. **Before extending:** `get-documentation` to understand existing props and variants
+3. **After creating:** `run-story-tests` to validate the new story renders correctly
+
+## Dependencies
+
+| Dependency | Purpose |
+|---|---|
+| `@repo/ui` | Source of all component stories |
+| `@storybook/react-vite` | Storybook framework using Vite bundler |
+| `@storybook/addon-essentials` | Controls, Actions, Docs, Backgrounds, Viewport |
+| `@tailwindcss/vite` | Vite plugin for Tailwind CSS v4 |
+| `storybook` | Storybook core CLI and dev server |
+| `tailwindcss` | Tailwind CSS v4 engine |
+| `vite` | Build tool / dev server |
+| `react` / `react-dom` | React 19 runtime |
+
+## Cross-References
+
+- **Component source:** `packages/ui/` -- see `packages/ui/AGENTS.md`
+- **Tailwind tokens:** `packages/ui/src/styles/globals.css`