docs(agents): add per-package AGENTS.md for all core-* packages

packages/core-ui/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — core-ui
+
+Design-system primitives organized by Atomic Design. Only **generic components** (atoms, molecules, generic organisms) live here. Feature-specific components live in their respective feature packages.
+
+## Responsibilities
+
+- **Atoms** — Single HTML elements: Button, Input, Label, Card
+- **Molecules** — Combinations: FormField (Label + Input), Badge, Avatar
+- **Generic Organisms** — Reusable complex layouts: Modal, Tabs, NavigationMenu, CommandPalette
+- **Templates** — Page layouts: AuthLayout, DashboardLayout, LandingLayout
+- **Utilities** — `cn()` for className merging, design tokens, Tailwind config
+
+## Feature-specific boundary
+
+Feature-specific organisms (e.g., `ArticleCard`, `ArticleList`, `HeaderNavMenu`) live in their feature's `ui/` folder, NOT here. This boundary keeps `core-ui` framework-agnostic and reusable.
+
+## Must NOT import
+
+- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`
+
+## Public exports
+
+From `package.json`:
+- `.` — all atoms, molecules, organisms, templates
+
+Example usage:
+```typescript
+import { Button, Input, Label } from "@repo/core-ui";
+import { FormField } from "@repo/core-ui";
+import { Modal, Tabs } from "@repo/core-ui";
+```
+
+## Test conventions
+
+- Tests colocated: `src/atoms/button/button.tsx` → `src/atoms/button/button.test.tsx`
+- Vitest environment: `jsdom` (React component testing)
+- Alias: `@/` resolves to `src/`
+- Run: `pnpm test --filter @repo/core-ui`
+- Storybook stories colocated: `src/atoms/button/button.stories.tsx`
+
+## Structure
+
+```
+src/
+  atoms/
+    {name}/
+      {name}.tsx             # Component
+      {name}.test.tsx        # Tests
+      {name}.stories.tsx     # Storybook story
+      index.ts               # Barrel export
+  molecules/
+    {name}/
+      ...
+  organisms/
+    {name}/
+      ...
+  templates/
+    {name}/
+      ...
+  lib/
+    utils.ts                 # cn() and helpers
+  index.ts                   # Re-exports everything
+```