refactor: consolidate guidance and add glob-based docs

.github/AGENTS.md

@@ -1,36 +1,14 @@
-# ComfyUI Frontend - Claude Review Context
+# PR Review Context
 
-This file provides additional context for the automated PR review system.
-
-## Quick Reference
-
-### PrimeVue Component Migrations
-
-When reviewing, flag these deprecated components:
-- `Dropdown` → Use `Select` from 'primevue/select'
-- `OverlayPanel` → Use `Popover` from 'primevue/popover'
-- `Calendar` → Use `DatePicker` from 'primevue/datepicker'
-- `InputSwitch` → Use `ToggleSwitch` from 'primevue/toggleswitch'
-- `Sidebar` → Use `Drawer` from 'primevue/drawer'
-- `Chips` → Use `AutoComplete` with multiple enabled and typeahead disabled
-- `TabMenu` → Use `Tabs` without panels
-- `Steps` → Use `Stepper` without panels
-- `InlineMessage` → Use `Message` component
-
-### API Utilities Reference
-
-- `api.apiURL()` - Backend API calls (/prompt, /queue, /view, etc.)
-- `api.fileURL()` - Static file access (templates, extensions)
-- `$t()` / `i18n.global.t()` - Internationalization
-- `DOMPurify.sanitize()` - HTML sanitization
+Context for automated PR review system.
 
 ## Review Scope
 
-This automated review performs comprehensive analysis including:
+This automated review performs comprehensive analysis:
 - Architecture and design patterns
 - Security vulnerabilities
 - Performance implications
 - Code quality and maintainability
 - Integration concerns
 
-For implementation details, see `.claude/commands/comprehensive-pr-review.md`.
+For implementation details, see `.claude/commands/comprehensive-pr-review.md`.

.github/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- A rose by any other name would smell as sweet,
+     But Claude insists on files named for its own conceit. -->
+@AGENTS.md

.storybook/AGENTS.md

@@ -1,197 +1,28 @@
-# Storybook Development Guidelines for Claude
+# Storybook Guidelines
 
-## Quick Commands
+## Commands
 
-- `pnpm storybook`: Start Storybook development server
-- `pnpm build-storybook`: Build static Storybook
-- `pnpm test:unit`: Run unit tests (includes Storybook components)
+- `pnpm storybook`: Development server
+- `pnpm build-storybook`: Production build
 
-## Development Workflow for Storybook
+## Story Structure
 
-1. **Creating New Stories**:
-   - Place `*.stories.ts` files alongside components
-   - Follow the naming pattern: `ComponentName.stories.ts`
-   - Use realistic mock data that matches ComfyUI schemas
+Place `*.stories.ts` alongside components. See `docs/guidance/storybook.md` for patterns.
 
-2. **Testing Stories**:
-   - Verify stories render correctly in Storybook UI
-   - Test different component states and edge cases
-   - Ensure proper theming and styling
+## Mock Data
 
-3. **Code Quality**:
-   - Run `pnpm typecheck` to verify TypeScript
-   - Run `pnpm lint` to check for linting issues
-   - Follow existing story patterns and conventions
+Use realistic ComfyUI schemas (node definitions, components).
 
-## Story Creation Guidelines
+## Available Context
 
-### Basic Story Structure
-
-```typescript
-import type { Meta, StoryObj } from '@storybook/vue3'
-import ComponentName from './ComponentName.vue'
-
-const meta: Meta<typeof ComponentName> = {
-  title: 'Category/ComponentName',
-  component: ComponentName,
-  parameters: {
-    layout: 'centered' // or 'fullscreen', 'padded'
-  }
-}
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-export const Default: Story = {
-  args: {
-    // Component props
-  }
-}
-```
-
-### Mock Data Patterns
-
-For ComfyUI components, use realistic mock data:
-
-```typescript
-// Node definition mock
-const mockNodeDef = {
-  input: {
-    required: {
-      prompt: ["STRING", { multiline: true }]
-    }
-  },
-  output: ["CONDITIONING"],
-  output_is_list: [false],
-  category: "conditioning"
-}
-
-// Component instance mock
-const mockComponent = {
-  id: "1",
-  type: "CLIPTextEncode",
-  // ... other properties
-}
-```
-
-### Common Story Variants
-
-Always include these story variants when applicable:
-
-- **Default**: Basic component with minimal props
-- **WithData**: Component with realistic data
-- **Loading**: Component in loading state
-- **Error**: Component with error state
-- **LongContent**: Component with edge case content
-- **Empty**: Component with no data
-
-### Storybook-Specific Code Patterns
-
-#### Store Access
-```typescript
-// In stories, access stores through the setup function
-export const WithStore: Story = {
-  render: () => ({
-    setup() {
-      const store = useMyStore()
-      return { store }
-    },
-    template: '<MyComponent :data="store.data" />'
-  })
-}
-```
-
-#### Event Testing
-```typescript
-export const WithEvents: Story = {
-  args: {
-    onUpdate: fn() // Use Storybook's fn() for action logging
-  }
-}
-```
-
-## Configuration Notes
-
-### Vue App Setup
-The Storybook preview is configured with:
-- Pinia stores initialized
-- PrimeVue with ComfyUI theme
-- i18n internationalization
-- All necessary CSS imports
-
-### Build Configuration
-- Vite integration with proper alias resolution
-- Manual chunking for better performance
-- TypeScript support with strict checking
-- CSS processing for Vue components
+Stories have access to:
+- All ComfyUI stores
+- PrimeVue with ComfyUI theming
+- i18n system
+- CSS variables and styling
 
 ## Troubleshooting
 
-### Common Issues
-
-1. **Import Errors**: Verify `@/` alias is working correctly
-2. **Missing Styles**: Ensure CSS imports are in `preview.ts`
+1. **Import Errors**: Verify `@/` alias works
+2. **Missing Styles**: Check CSS imports in `preview.ts`
 3. **Store Errors**: Check store initialization in setup
-4. **Type Errors**: Use proper TypeScript types for story args
-
-### Debug Commands
-
-```bash
-# Check TypeScript issues
-pnpm typecheck
-
-# Lint Storybook files
-pnpm lint .storybook/
-
-# Build to check for production issues
-pnpm build-storybook
-```
-
-## File Organization
-
-```
-.storybook/
-├── main.ts          # Core configuration
-├── preview.ts       # Global setup and decorators
-├── README.md        # User documentation
-└── CLAUDE.md        # This file - Claude guidelines
-
-src/
-├── components/
-│   └── MyComponent/
-│       ├── MyComponent.vue
-│       └── MyComponent.stories.ts
-```
-
-## Integration with ComfyUI
-
-### Available Context
-
-Stories have access to:
-- All ComfyUI stores (widgetStore, colorPaletteStore, etc.)
-- PrimeVue components with ComfyUI theming
-- Internationalization system
-- ComfyUI CSS variables and styling
-
-### Testing Components
-
-When testing ComfyUI-specific components:
-1. Use realistic node definitions and data structures
-2. Test with different node types (sampling, conditioning, etc.)
-3. Verify proper CSS theming and dark/light modes
-4. Check component behavior with various input combinations
-
-### Performance Considerations
-
-- Use manual chunking for large dependencies
-- Minimize bundle size by avoiding unnecessary imports
-- Leverage Storybook's lazy loading capabilities
-- Profile build times and optimize as needed
-
-## Best Practices
-
-1. **Keep Stories Focused**: Each story should demonstrate one specific use case
-2. **Use Descriptive Names**: Story names should clearly indicate what they show
-3. **Document Complex Props**: Use JSDoc comments for complex prop types
-4. **Test Edge Cases**: Create stories for unusual but valid use cases
-5. **Maintain Consistency**: Follow established patterns in existing stories

.storybook/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- Though standards bloom in open fields so wide,
+     Anthropic walks a path of lonely pride. -->
+@AGENTS.md

AGENTS.md

@@ -1,5 +1,7 @@
 # Repository Guidelines
 
+See @docs/guidance/*.md for file-type-specific conventions (auto-loaded by glob).
+
 ## Project Structure & Module Organization
 
 - Source: `src/`
@@ -46,6 +48,21 @@ The project uses **Nx** for build orchestration and task management
 - `pnpm lint` / `pnpm lint:fix`: Lint (ESLint)
 - `pnpm format` / `pnpm format:check`: Prettier
 - `pnpm typecheck`: Vue TSC type checking
+- `pnpm storybook`: Start Storybook development server
+
+## Development Workflow
+
+1. Make code changes
+2. Run relevant tests
+3. Run `pnpm typecheck`, `pnpm lint`, `pnpm format`
+4. Check if README updates are needed
+5. Consider docs.comfy.org updates for user-facing changes
+
+## Git Conventions
+
+- Use `prefix:` format: `feat:`, `fix:`, `test:`
+- Add "Fixes #n" to PR descriptions
+- Never mention Claude/AI in commits
 
 ## Coding Style & Naming Conventions
 

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

browser_tests/AGENTS.md

@@ -1,17 +1,15 @@
 # E2E Testing Guidelines
 
-## Browser Tests
-- Test user workflows
-- Use Playwright fixtures
-- Follow naming conventions
-
 ## Best Practices
-- Check assets/ for test data
+
+- Test user workflows with Playwright fixtures
+- Check `assets/` for test data
 - Prefer specific selectors
 - Test across viewports
 
 ## Testing Process
+
 After code changes:
 1. Create browser tests as appropriate
 2. Run tests until passing
-3. Then run typecheck, lint, format
+3. Then run typecheck, lint, format

browser_tests/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- In gardens where the agents freely play,
+     One stubborn flower turns the other way. -->
+@AGENTS.md

docs/guidance/playwright.md

@@ -0,0 +1,33 @@
+---
+globs:
+  - '**/*.spec.ts'
+---
+
+# Playwright E2E Test Conventions
+
+See `docs/testing/*.md` for detailed patterns.
+
+## Best Practices
+
+- Follow [Playwright Best Practices](https://playwright.dev/docs/best-practices)
+- Do NOT use `waitForTimeout` - use Locator actions and retrying assertions
+- Prefer specific selectors (role, label, test-id)
+- Test across viewports
+
+## Test Tags
+
+Tags are respected by config:
+- `@mobile` - Mobile viewport tests
+- `@2x` - High DPI tests
+
+## Test Data
+
+- Check `browser_tests/assets/` for test data and fixtures
+- Use realistic ComfyUI workflows for E2E tests
+
+## Running Tests
+
+```bash
+pnpm test:browser                 # Run all E2E tests
+pnpm test:browser -- --ui         # Interactive UI mode
+```