feat: add AGENTS.md for all packages and apps (9 files)

packages/ui/AGENTS.md

@@ -0,0 +1,59 @@
+# @repo/ui — Atomic Design Component Library
+
+shadcn/ui + Tailwind CSS v4 + Atomic Design. Components organized by level with co-located stories.
+
+## Atomic Classification Guide
+
+| Level | Definition | Examples |
+|---|---|---|
+| Atom | Single element, can't break down further | Button, Input, Label, Badge, Separator |
+| Molecule | 2-3 atoms, single responsibility | FormField, SearchBar, Tooltip, Select |
+| Organism | Complex section, self-contained | DataTable, Dialog, Header, Sidebar, Card |
+| Template | Page layout, content-agnostic | DashboardLayout, AuthLayout |
+| Page | Template + real data | **LIVES IN apps/, NOT HERE** |
+
+## Import Rules
+
+| Level | Can import from | NEVER import from |
+|---|---|---|
+| Atoms | lib/, hooks/, styles/ | molecules/, organisms/, templates/ |
+| Molecules | atoms/, lib/, hooks/ | organisms/, templates/ |
+| Organisms | atoms/, molecules/, lib/, hooks/ | templates/ |
+| Templates | atoms/, molecules/, organisms/, lib/, hooks/ | (top level) |
+
+## Component Rules
+
+- **Atoms:** No margins/positioning, no state, no business logic
+- **Molecules:** Single responsibility, minimal controlled state
+- **Organisms:** Can have internal state and sub-components
+- **Templates:** Use children/slots, NEVER hard-code content
+- **All:** Co-locate `.stories.tsx` next to component
+
+## shadcn/ui Workflow
+
+1. `pnpm dlx shadcn@latest add [component]` — lands in atoms/ by default
+2. Check classification guide above
+3. If not atom → move to correct directory
+4. Create `.stories.tsx` with title: `"{Level}/{ComponentName}"`
+5. Update level's `index.ts` barrel
+
+## Story Template
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { MyComponent } from "./my-component.js";
+
+const meta = {
+  title: "{Level}/{ComponentName}",
+  component: MyComponent,
+  tags: ["autodocs"],
+} satisfies Meta<typeof MyComponent>;
+export default meta;
+```
+
+## Storybook MCP
+
+Before creating UI components, query Storybook MCP:
+- `list-all-documentation` — check for existing components
+- `get-documentation` — understand props/variants
+- After creating: `run-story-tests` to validate