diff --git a/.agents/skills/better-auth-best-practices/SKILL.md b/.agents/skills/better-auth-best-practices/SKILL.md
new file mode 100644
index 0000000..74195ce
--- /dev/null
+++ b/.agents/skills/better-auth-best-practices/SKILL.md
@@ -0,0 +1,192 @@
+---
+name: better-auth-best-practices
+description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.
+---
+
+# Better Auth Integration Guide
+
+## Documentation Version
+
+Use documentation that matches the Better Auth version installed in the project. APIs and plugin names can differ across maintained release lines.
+
+1. Prefer a version explicitly named by the user.
+2. Otherwise, inspect the resolved `better-auth` version in the lockfile, falling back to the package manifest when no lockfile is available.
+3. When the Better Auth MCP is available, call `get_doc` with `/llms.txt` to resolve that package version to a documentation identifier. Pass the identifier to every `search_docs` call and pass result paths to `get_doc` unchanged.
+4. Without MCP, start at [better-auth.com/llms.txt](https://better-auth.com/llms.txt) and follow the matching version index.
+5. Use the latest documentation only when the project version cannot be determined or the user explicitly asks about the latest release or an upgrade.
+
+When planning an upgrade, separate guidance for the currently installed version from guidance for the target version.
+
+---
+
+## Setup Workflow
+
+1. Install: `npm install better-auth`
+2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
+3. Create `auth.ts` with database + config
+4. Create route handler for your framework
+5. Run migrations:
+   - **Built-in adapter:** `npx auth@latest migrate`
+   - **Drizzle:** `npx auth@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
+   - **Prisma:** `npx auth@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
+6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
+
+---
+
+## Quick Reference
+
+### Environment Variables
+- `BETTER_AUTH_SECRET` - Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
+- `BETTER_AUTH_URL` - Base URL (e.g., `https://example.com`)
+
+Only define `baseURL`/`secret` in config if env vars are NOT set.
+
+### File Location
+CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
+
+### CLI Commands
+- `npx auth@latest migrate` - Apply schema (built-in adapter)
+- `npx auth@latest generate` - Generate schema for Prisma/Drizzle
+- `npx auth@latest mcp --cursor` - Add MCP to AI tools
+
+**Re-run after adding/changing plugins.**
+
+---
+
+## Core Config Options
+
+| Option | Notes |
+|--------|-------|
+| `appName` | Optional display name |
+| `baseURL` | Only if `BETTER_AUTH_URL` not set |
+| `basePath` | Default `/api/auth`. Set `/` for root. |
+| `secret` | Only if `BETTER_AUTH_SECRET` not set |
+| `database` | Required for most features. See adapters docs. |
+| `secondaryStorage` | Redis/KV for sessions & rate limits |
+| `emailAndPassword` | `{ enabled: true }` to activate |
+| `socialProviders` | `{ google: { clientId, clientSecret }, ... }` |
+| `plugins` | Array of plugins |
+| `trustedOrigins` | CSRF whitelist |
+
+---
+
+## Database
+
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance. For Postgres, also supports `postgres` (postgres.js) and `@neondatabase/serverless`.
+
+**ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
+
+**Drizzle provider values:** `"pg"` (PostgreSQL), `"mysql"` (MySQL), `"sqlite"` (SQLite). Must match the driver used.
+
+**Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
+
+---
+
+## Session Management
+
+**Storage priority:**
+1. If `secondaryStorage` defined → sessions go there (not DB)
+2. Set `session.storeSessionInDatabase: true` to also persist to DB
+3. No database + `cookieCache` → fully stateless mode
+
+**Cookie cache strategies:**
+- `compact` (default) - Base64url + HMAC. Smallest.
+- `jwt` - Standard JWT. Readable but signed.
+- `jwe` - Encrypted. Maximum security.
+
+**Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions).
+
+---
+
+## User & Account Config
+
+**User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default).
+
+**Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth).
+
+**Required for registration:** `email` and `name` fields.
+
+---
+
+## Email Flows
+
+- `emailVerification.sendVerificationEmail` - Must be defined for verification to work
+- `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers
+- `emailAndPassword.sendResetPassword` - Password reset email handler
+
+---
+
+## Security
+
+**In `advanced`:**
+- `useSecureCookies` - Force HTTPS cookies
+- `disableCSRFCheck` - ⚠️ Security risk
+- `disableOriginCheck` - ⚠️ Security risk  
+- `crossSubDomainCookies.enabled` - Share cookies across subdomains
+- `ipAddress.ipAddressHeaders` - Custom IP headers for proxies
+- `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false`
+
+**Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage").
+
+---
+
+## Hooks
+
+**Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`.
+
+**Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions.
+
+**Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`.
+
+---
+
+## Plugins
+
+**Import from dedicated paths for tree-shaking:**
+```
+import { twoFactor } from "better-auth/plugins/two-factor"
+```
+NOT `from "better-auth/plugins"`.
+
+**Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`.
+
+Client plugins go in `createAuthClient({ plugins: [...] })`.
+
+---
+
+## Client
+
+Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`.
+
+Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`.
+
+---
+
+## Type Safety
+
+Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`.
+
+For separate client/server projects: `createAuthClient<typeof auth>()`.
+
+---
+
+## Common Gotchas
+
+1. **Model vs table name** - Config uses ORM model name, not DB table name
+2. **Plugin schema** - Re-run CLI after adding plugins
+3. **Secondary storage** - Sessions go there by default, not DB
+4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
+5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
+6. **Change email flow** - Sends to current email first, then new email
+7. **Drizzle: db not initialized** - `drizzleAdapter(db, ...)` requires a `db` instance from `drizzle()`. See `create-auth` skill for setup examples (node-postgres, postgres.js, Neon).
+8. **Drizzle: missing drizzle.config.ts** - `drizzle-kit` commands require a `drizzle.config.ts` pointing to the generated schema file and DB credentials.
+
+---
+
+## Resources
+
+- [Docs](https://better-auth.com/docs)
+- [Options Reference](https://better-auth.com/docs/reference/options)
+- [LLMs.txt](https://better-auth.com/llms.txt)
+- [GitHub](https://github.com/better-auth/better-auth)
+- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
diff --git a/.agents/skills/clean-code-principles/AGENTS.md b/.agents/skills/clean-code-principles/AGENTS.md
new file mode 100644
index 0000000..b9b1035
--- /dev/null
+++ b/.agents/skills/clean-code-principles/AGENTS.md
@@ -0,0 +1,450 @@
+# Clean Code Principles - Agent Documentation
+
+**Version:** 1.0.2
+**Focus:** SOLID Principles, Core Principles (DRY, KISS, YAGNI), Design Patterns
+**Rules:** 23 (10 SOLID + 12 Core + 1 Pattern); 4 categories planned
+**License:** MIT
+
+---
+
+This skill provides comprehensive clean code principles, SOLID guidelines, and design patterns for building maintainable, scalable software.
+
+## Overview
+
+The clean-code-principles skill offers language-agnostic software design principles organized into 7 categories, from CRITICAL (SOLID, Core Principles) to LOW priority (Comments). Each rule provides bad/good examples, explanations, and practical guidance.
+
+## When to Use This Skill
+
+Activate this skill when:
+- Reviewing code architecture or design
+- Refactoring existing code
+- Making design decisions
+- Establishing coding standards
+- Teaching software design principles
+- Addressing technical debt
+- Improving code quality and maintainability
+
+## Trigger Phrases
+
+The skill activates on:
+- "review architecture"
+- "check code quality"
+- "SOLID principles"
+- "design patterns"
+- "clean code"
+- "refactoring advice"
+- "code smells"
+- "best practices"
+- "DRY principle"
+- "separation of concerns"
+
+## Skill Structure
+
+```
+clean-code-principles/
+├── SKILL.md              # Main skill definition
+├── AGENTS.md             # This file - agent documentation
+├── README.md             # User-facing documentation
+├── metadata.json         # Structured metadata and references
+└── rules/
+    ├── _sections.md      # Category definitions and organization
+    ├── _template.md      # Template for new rules
+    ├── solid-*.md        # SOLID principles (10 rules)
+    ├── core-*.md         # Core principles (12 rules)
+    └── pattern-*.md      # Design patterns (1 rule)
+```
+
+## Rule Categories
+
+### 1. SOLID Principles (CRITICAL - 10 rules)
+**Prefix:** `solid-`
+
+Five fundamental object-oriented design principles:
+- **S**ingle Responsibility: `solid-srp-class`, `solid-srp-function`
+- **O**pen/Closed: `solid-ocp-extension`, `solid-ocp-abstraction`
+- **L**iskov Substitution: `solid-lsp-contracts`, `solid-lsp-preconditions`
+- **I**nterface Segregation: `solid-isp-clients`, `solid-isp-interfaces`
+- **D**ependency Inversion: `solid-dip-abstractions`, `solid-dip-injection`
+
+**Use when:** Designing architecture, planning refactoring, discussing system design
+
+### 2. Core Principles (CRITICAL - 12 rules)
+**Prefix:** `core-`
+
+Fundamental coding practices:
+- **DRY** (Don't Repeat Yourself): 3 rules
+- **KISS** (Keep It Simple): 2 rules
+- **YAGNI** (You Aren't Gonna Need It): 2 rules
+- **Other**: Separation of Concerns, Composition Over Inheritance, Law of Demeter, Fail Fast, Encapsulation
+
+**Use when:** Daily coding, code reviews, addressing duplication or complexity
+
+### 3. Design Patterns (HIGH - 1 rule)
+**Prefix:** `pattern-`
+
+Common solutions to recurring problems:
+- Repository Pattern (data access abstraction)
+
+**Use when:** Solving architectural problems, abstracting infrastructure concerns
+
+### 4-7. Future Categories
+- **Code Organization** (`org-`): Module structure, boundaries
+- **Naming & Readability** (`name-`): Identifier naming conventions
+- **Functions & Methods** (`func-`): Function-level best practices
+- **Comments & Documentation** (`doc-`): Documentation guidelines
+
+## How to Use Rules
+
+### Accessing Rules
+
+1. **By ID:** Reference specific rules using their ID
+   ```
+   Check against solid-srp-class and core-dry
+   ```
+
+2. **By Category:** Apply all rules in a category
+   ```
+   Review this class against SOLID principles
+   ```
+
+3. **By Scenario:** Choose relevant rules for the context
+   ```
+   This has duplicated validation logic - check DRY rules
+   ```
+
+### Rule Format
+
+Each rule follows a consistent structure:
+
+```markdown
+---
+id: {rule-id}
+title: {Full Title}
+category: {category}
+priority: {critical|high|medium|low}
+tags: [{tags}]
+related: [{related-rule-ids}]
+---
+
+# {Rule Title}
+
+{One-sentence summary}
+
+## Bad Example
+{Anti-pattern code with problems listed}
+
+## Good Example
+{Correct implementation with benefits}
+
+## Why
+{5-7 benefits explaining the value}
+
+## When to Apply
+{Practical scenarios}
+```
+
+### Output Format
+
+When identifying violations, use:
+
+```
+file:line - [rule-id] Description of issue
+```
+
+Example:
+```
+src/services/UserService.ts:15 - [solid-srp-class] Class handles validation, persistence, and notifications
+src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
+src/models/Order.ts:28 - [core-kiss-simplicity] Overly complex abstraction for simple use case
+```
+
+## Agent Strategies
+
+### Strategy 1: Architecture Review
+
+**Goal:** Assess overall system design
+
+**Approach:**
+1. Start with SOLID principles (highest impact)
+2. Identify violations of SRP, DIP, OCP
+3. Check for proper separation of concerns
+4. Evaluate composition vs inheritance
+5. Assess interface design (ISP)
+
+**Output:** Prioritized list of architectural issues with rule references
+
+### Strategy 2: Code Quality Audit
+
+**Goal:** Find code quality issues in specific files
+
+**Approach:**
+1. Scan for duplication (DRY rules)
+2. Check complexity (KISS rules)
+3. Look for overengineering (YAGNI rules)
+4. Verify single responsibility
+5. Assess encapsulation
+
+**Output:** File-by-file findings with specific line references
+
+### Strategy 3: Refactoring Guidance
+
+**Goal:** Provide actionable refactoring steps
+
+**Approach:**
+1. Identify the primary issue (which rule violated)
+2. Reference the good example from that rule
+3. Suggest specific refactoring steps
+4. Mention related rules that may also help
+5. Prioritize changes by impact
+
+**Output:** Step-by-step refactoring plan with rule references
+
+### Strategy 4: Design Decision Support
+
+**Goal:** Help choose between design alternatives
+
+**Approach:**
+1. Analyze each option against relevant principles
+2. Consider YAGNI (simplest solution first)
+3. Evaluate against SOLID principles
+4. Check alignment with KISS
+5. Recommend based on principle adherence
+
+**Output:** Comparative analysis with principle-based recommendation
+
+### Strategy 5: Pattern Application
+
+**Goal:** Suggest appropriate design patterns
+
+**Approach:**
+1. Identify the problem being solved
+2. Check if any patterns apply
+3. Verify pattern aligns with SOLID principles
+4. Ensure pattern isn't overengineering (YAGNI)
+5. Provide implementation guidance
+
+**Output:** Pattern recommendation with integration guidance
+
+## Best Practices for Agents
+
+### Do:
+- Start with CRITICAL rules (SOLID, Core)
+- Provide specific line numbers when possible
+- Reference rule IDs in all findings
+- Explain WHY a rule matters, not just that it's violated
+- Give actionable refactoring suggestions
+- Consider the codebase context
+- Prioritize by impact (CRITICAL > HIGH > MEDIUM > LOW)
+- Show code examples from the rules
+- Mention related rules that apply together
+
+### Don't:
+- Don't cite every minor violation
+- Don't recommend patterns without clear need (YAGNI)
+- Don't ignore context (some violations may be acceptable)
+- Don't focus on LOW priority rules when CRITICAL issues exist
+- Don't provide fixes without explaining the principle
+- Don't recommend complex solutions for simple problems (KISS)
+- Don't suggest abstractions without concrete use cases (YAGNI)
+
+### Prioritization
+
+When multiple issues exist:
+1. **CRITICAL - SOLID violations:** Architecture-level problems
+2. **CRITICAL - Core violations:** Duplication, complexity, overengineering
+3. **HIGH - Pattern opportunities:** Where patterns genuinely help
+4. **MEDIUM - Naming/Functions:** Readability improvements
+5. **LOW - Documentation:** Comment and doc issues
+
+## Example Interactions
+
+### Example 1: Architecture Review
+
+**User:** "Review the architecture of this OrderService class"
+
+**Agent Approach:**
+1. Check class responsibilities against `solid-srp-class`
+2. Evaluate dependencies against `solid-dip-injection`
+3. Look for data access against `pattern-repository`
+4. Check for proper separation against `core-separation-concerns`
+
+**Agent Output:**
+```
+Architecture Review - OrderService
+
+CRITICAL Issues:
+1. [solid-srp-class] Class has multiple responsibilities:
+   - Order validation (should be separate validator)
+   - Direct database access (should use repository)
+   - Email sending (should be separate service)
+   - Payment processing (should be separate service)
+
+2. [solid-dip-abstractions] Direct dependency on concrete implementations:
+   - Instantiates MySQLDatabase directly (line 15)
+   - Creates StripePaymentGateway in constructor (line 18)
+
+3. [pattern-repository] Direct SQL queries in service layer:
+   - Lines 45-50: Raw SQL should be in repository
+
+Recommendations:
+1. Split into focused classes following SRP
+2. Inject dependencies through constructor (DIP)
+3. Create repository abstraction for data access
+4. Extract email and payment to separate services
+
+See: solid-srp-class.md, solid-dip-injection.md, pattern-repository.md
+```
+
+### Example 2: Code Quality Check
+
+**User:** "Check this validation function for code quality issues"
+
+**Agent Approach:**
+1. Check for duplication (`core-dry`)
+2. Check complexity (`core-kiss-simplicity`)
+3. Check function responsibility (`solid-srp-function`)
+
+**Agent Output:**
+```
+Code Quality Issues:
+
+utils/validation.ts:
+  Line 23 - [core-dry] Email regex duplicated from line 45 and validators/email.ts
+  Line 30 - [core-dry-extraction] Password validation logic should be extracted to reusable function
+  Line 50 - [solid-srp-function] Function validates both email AND password - split into two functions
+
+Suggested refactoring:
+1. Extract common regex patterns to constants file (core-dry-single-source)
+2. Create separate validateEmail() and validatePassword() functions (solid-srp-function)
+3. Import from shared validators module (core-dry-extraction)
+
+See: core-dry.md, core-dry-extraction.md, solid-srp-function.md
+```
+
+### Example 3: Design Decision
+
+**User:** "Should I use inheritance or composition for this User/Admin relationship?"
+
+**Agent Approach:**
+1. Apply `core-composition` principle
+2. Check LSP implications (`solid-lsp-contracts`)
+3. Consider YAGNI (`core-yagni-abstractions`)
+
+**Agent Output:**
+```
+Recommendation: Use Composition
+
+Analysis:
+1. [core-composition] Composition is preferred over inheritance for flexibility
+   - Admins can have additional capabilities without inheritance constraints
+   - Easier to test each capability independently
+   - Can mix different permission sets dynamically
+
+2. [solid-lsp-contracts] Inheritance risks LSP violations
+   - If Admin overrides User methods differently
+   - If Admin has different behavior expectations
+
+3. [core-yagni-abstractions] Start simple
+   - Don't create inheritance hierarchy unless you need polymorphism
+   - Compose from Permission and Role objects instead
+
+Suggested approach:
+```typescript
+class User {
+  constructor(
+    private permissions: PermissionSet,
+    private roleManager: RoleManager
+  ) {}
+}
+```
+
+See: core-composition.md, solid-lsp-contracts.md
+```
+
+## Integration with Other Skills
+
+This skill complements:
+- **refactoring**: Provides principles for refactoring decisions
+- **architecture-review**: Supplies SOLID and design principles
+- **code-review**: Offers quality criteria for reviews
+- **testing**: Promotes testable design (DIP, SRP)
+
+## Rule Reference Quick Guide
+
+### Most Common Rules
+
+**For duplication:**
+- `core-dry` - Main DRY principle
+- `core-dry-extraction` - How to extract duplicated code
+- `core-dry-single-source` - Configuration and constants
+
+**For complex code:**
+- `core-kiss-simplicity` - Avoid overengineering
+- `core-kiss-readability` - Optimize for readability
+- `core-yagni-features` - Don't build unused features
+- `core-yagni-abstractions` - Don't abstract prematurely
+
+**For class design:**
+- `solid-srp-class` - Single responsibility for classes
+- `solid-dip-injection` - Dependency injection
+- `core-separation-concerns` - Separate different concerns
+- `core-composition` - Favor composition over inheritance
+
+**For function design:**
+- `solid-srp-function` - Single responsibility for functions
+- `core-kiss-readability` - Clear, readable functions
+
+**For interfaces:**
+- `solid-isp-interfaces` - Small, focused interfaces
+- `solid-isp-clients` - Client-specific interfaces
+
+**For extensibility:**
+- `solid-ocp-extension` - Open for extension, closed for modification
+- `solid-ocp-abstraction` - Use abstractions for extension points
+
+**For inheritance:**
+- `solid-lsp-contracts` - Subtypes must honor contracts
+- `solid-lsp-preconditions` - Pre/postcondition rules
+- `core-composition` - Prefer composition
+
+**For data access:**
+- `pattern-repository` - Abstract data persistence
+
+## Metadata
+
+**Version:** 1.0.2
+**Rules:** 23 (10 SOLID, 12 Core, 1 Pattern)
+**Categories:** 7 (3 implemented, 4 planned)
+**Languages:** Language-agnostic (examples in TypeScript)
+**Last Updated:** 2026-03-07
+
+## Resources
+
+### Books
+- Clean Code (Robert C. Martin)
+- Design Patterns (Gang of Four)
+- Refactoring (Martin Fowler)
+- The Pragmatic Programmer (Hunt & Thomas)
+
+### Online
+- [Refactoring Guru](https://refactoring.guru/) - Design patterns and code smells
+- [Martin Fowler's Catalog](https://refactoring.com/catalog/) - Refactoring techniques
+- [Uncle Bob's Blog](https://blog.cleancoder.com/) - Software craftsmanship
+
+## Contributing New Rules
+
+When adding new rules:
+1. Use `rules/_template.md` as starting point
+2. Follow naming convention: `{prefix}-{concept}-{specificity}.md`
+3. Include YAML frontmatter with all required fields
+4. Provide clear bad/good examples
+5. Explain 5-7 benefits in "Why" section
+6. Add to `metadata.json` rules array
+7. Update category counts in `_sections.md`
+8. Reference related rules in frontmatter
+9. Keep examples language-agnostic (TypeScript preferred)
+10. Aim for 300-400 lines of content
+
+## License
+
+MIT License. This skill is provided as-is for educational and development purposes.
diff --git a/.agents/skills/clean-code-principles/README.md b/.agents/skills/clean-code-principles/README.md
new file mode 100644
index 0000000..5d982ff
--- /dev/null
+++ b/.agents/skills/clean-code-principles/README.md
@@ -0,0 +1,88 @@
+# Clean Code Principles
+
+Fundamental software design principles for writing maintainable, scalable code.
+
+**Version:** 1.0.2
+**Rules:** 23 (10 SOLID + 12 Core + 1 Pattern); 4 categories planned
+**License:** MIT
+
+---
+
+## Overview
+
+Language-agnostic guidelines covering SOLID principles, core coding principles (DRY, KISS, YAGNI), and design patterns. Examples are written in TypeScript but apply to any object-oriented or functional language.
+
+## Categories (23 rules implemented)
+
+### 1. SOLID Principles (Critical) — 10 rules
+Five fundamental object-oriented design principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.
+
+### 2. Core Principles (Critical) — 12 rules
+DRY (3 rules), KISS (2 rules), YAGNI (2 rules), Separation of Concerns, Composition over Inheritance, Law of Demeter, Fail Fast, Encapsulation.
+
+### 3. Design Patterns (High) — 1 rule
+Repository pattern for data access abstraction.
+
+### 4. Code Organization (High) — planned
+Feature folders, module boundaries, layered architecture, package cohesion, circular dependency prevention.
+
+### 5. Naming & Readability (Medium) — planned
+Meaningful names, consistent conventions, no magic numbers, domain language.
+
+### 6. Functions & Methods (Medium) — planned
+Small functions, single purpose, limited parameters, pure functions, command-query separation.
+
+### 7. Comments & Documentation (Low) — planned
+Self-documenting code, explain why not what, avoid noise, document public APIs.
+
+## Usage
+
+Ask Claude to:
+- "Review architecture" — triggers SOLID + Separation of Concerns analysis
+- "Check SOLID principles" — targeted SOLID review
+- "Check code quality" — DRY, KISS, YAGNI audit
+- "Suggest design patterns" — pattern recommendations
+- "Refactoring advice" — actionable improvements with rule references
+
+## Key Principles
+
+### SOLID
+| Principle | Rule | Summary |
+|-----------|------|---------|
+| **S**ingle Responsibility | `solid-srp-class`, `solid-srp-function` | One reason to change |
+| **O**pen/Closed | `solid-ocp-extension`, `solid-ocp-abstraction` | Open for extension, closed for modification |
+| **L**iskov Substitution | `solid-lsp-contracts`, `solid-lsp-preconditions` | Subtypes must be substitutable |
+| **I**nterface Segregation | `solid-isp-clients`, `solid-isp-interfaces` | Small, focused interfaces |
+| **D**ependency Inversion | `solid-dip-abstractions`, `solid-dip-injection` | Depend on abstractions |
+
+### Core
+
+| Principle | Rules | Summary |
+|-----------|-------|---------|
+| **DRY** | `core-dry`, `core-dry-extraction`, `core-dry-single-source` | Single source of truth |
+| **KISS** | `core-kiss-simplicity`, `core-kiss-readability` | Simplest solution that works |
+| **YAGNI** | `core-yagni-features`, `core-yagni-abstractions` | Build only what's needed |
+
+## Output Format
+
+When auditing code:
+
+```
+file:line - [rule-id] Description of issue
+```
+
+Example:
+```
+src/services/UserService.ts:15 - [solid-srp-class] Class handles validation, persistence, and email
+src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
+src/models/Order.ts:28 - [core-yagni-abstractions] Generic abstraction used in only one place
+```
+
+## References
+
+- **Clean Code** by Robert C. Martin — Foundation for clean code practices
+- **Design Patterns** by Gang of Four — Classic design pattern catalog
+- **Refactoring** by Martin Fowler — Improving code structure
+- **The Pragmatic Programmer** by Hunt & Thomas — Practical software wisdom
+- [Refactoring Guru](https://refactoring.guru/) — Design patterns and code smells
+- [Martin Fowler's Refactoring Catalog](https://refactoring.com/catalog/) — Comprehensive techniques
diff --git a/.agents/skills/clean-code-principles/SKILL.md b/.agents/skills/clean-code-principles/SKILL.md
new file mode 100644
index 0000000..97a463c
--- /dev/null
+++ b/.agents/skills/clean-code-principles/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: clean-code-principles
+description: SOLID principles, design patterns, DRY, KISS, and clean code fundamentals. Use when reviewing architecture, checking code quality, refactoring, or discussing design decisions. Triggers on "review architecture", "check code quality", "SOLID principles", "design patterns", or "clean code".
+license: MIT
+metadata:
+  author: AsyrafHussin
+  version: "1.0.2"
+---
+
+# Clean Code Principles
+
+Fundamental software design principles, SOLID, design patterns, and clean code practices. Language-agnostic guidelines for writing maintainable, scalable software.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing new features or systems
+- Reviewing code architecture
+- Refactoring existing code
+- Discussing design decisions
+- Improving code quality
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | SOLID Principles | CRITICAL | `solid-` |
+| 2 | Core Principles | CRITICAL | `core-` |
+| 3 | Design Patterns | HIGH | `pattern-` |
+| 4 | Code Organization | HIGH | `org-` |
+| 5 | Naming & Readability | MEDIUM | `name-` |
+| 6 | Functions & Methods | MEDIUM | `func-` |
+| 7 | Comments & Documentation | LOW | `doc-` |
+
+## Quick Reference
+
+### 1. SOLID Principles (CRITICAL)
+
+- `solid-srp` - Single Responsibility Principle
+- `solid-ocp` - Open/Closed Principle
+- `solid-lsp` - Liskov Substitution Principle
+- `solid-isp` - Interface Segregation Principle
+- `solid-dip` - Dependency Inversion Principle
+
+### 2. Core Principles (CRITICAL)
+
+- `core-dry` - Don't Repeat Yourself
+- `core-kiss` - Keep It Simple, Stupid
+- `core-yagni` - You Aren't Gonna Need It
+- `core-separation-of-concerns` - Separate different responsibilities
+- `core-composition-over-inheritance` - Favor composition
+- `core-law-of-demeter` - Principle of least knowledge
+- `core-fail-fast` - Detect and report errors early
+- `core-encapsulation` - Hide implementation details
+
+### 3. Design Patterns (HIGH)
+
+- `pattern-factory` - Factory pattern for object creation
+- `pattern-strategy` - Strategy pattern for algorithms
+- `pattern-repository` - Repository pattern for data access
+- `pattern-decorator` - Decorator pattern for behavior extension
+- `pattern-observer` - Observer pattern for event handling
+- `pattern-adapter` - Adapter pattern for interface conversion
+- `pattern-facade` - Facade pattern for simplified interfaces
+- `pattern-dependency-injection` - DI for loose coupling
+
+### 4. Code Organization (HIGH) — planned
+
+- `org-feature-folders` - Organize by feature, not layer
+- `org-module-boundaries` - Clear module boundaries
+- `org-layered-architecture` - Proper layer separation
+- `org-package-cohesion` - Related code together
+- `org-circular-dependencies` - Avoid circular imports
+
+### 5. Naming & Readability (MEDIUM) — planned
+
+- `name-meaningful` - Use intention-revealing names
+- `name-consistent` - Consistent naming conventions
+- `name-searchable` - Avoid magic numbers/strings
+- `name-avoid-encodings` - No Hungarian notation
+- `name-domain-language` - Use domain terminology
+
+### 6. Functions & Methods (MEDIUM) — planned
+
+- `func-small` - Keep functions small
+- `func-single-purpose` - Do one thing
+- `func-few-arguments` - Limit parameters
+- `func-no-side-effects` - Minimize side effects
+- `func-command-query` - Separate commands and queries
+
+### 7. Comments & Documentation (LOW) — planned
+
+- `doc-self-documenting` - Code should explain itself
+- `doc-why-not-what` - Explain why, not what
+- `doc-avoid-noise` - No redundant comments
+- `doc-api-docs` - Document public APIs
+
+## Essential Guidelines
+
+For detailed examples and explanations, see the rule files:
+
+- [core-dry.md](rules/core-dry.md) - Don't Repeat Yourself principle
+- [pattern-repository.md](rules/pattern-repository.md) - Repository pattern for data access
+
+### SOLID Principles (Summary)
+
+| Principle | Definition |
+|-----------|------------|
+| **S**ingle Responsibility | A class should have only one reason to change |
+| **O**pen/Closed | Open for extension, closed for modification |
+| **L**iskov Substitution | Subtypes must be substitutable for base types |
+| **I**nterface Segregation | Don't force clients to depend on unused interfaces |
+| **D**ependency Inversion | Depend on abstractions, not concretions |
+
+### Core Principles (Summary)
+
+| Principle | Definition |
+|-----------|------------|
+| **DRY** | Don't Repeat Yourself - single source of truth |
+| **KISS** | Keep It Simple - avoid over-engineering |
+| **YAGNI** | You Aren't Gonna Need It - build only what's needed |
+
+### Quick Examples
+
+```typescript
+// Single Responsibility - one class, one job
+class UserService {
+  constructor(
+    private validator: UserValidator,
+    private repository: UserRepository,
+  ) {}
+
+  createUser(data) {
+    this.validator.validate(data);
+    return this.repository.create(data);
+  }
+}
+
+// Dependency Inversion - depend on abstractions
+interface Repository<T> {
+  find(id: string): Promise<T | null>;
+  save(entity: T): Promise<T>;
+}
+
+class OrderService {
+  constructor(private repository: Repository<Order>) {}
+}
+
+// DRY - single source of truth
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const isValidEmail = (email: string) => EMAIL_REGEX.test(email);
+
+// Meaningful names over magic numbers
+const MINIMUM_AGE = 18;
+if (user.age >= MINIMUM_AGE) { }
+```
+
+## Output Format
+
+When auditing code, output findings in this format:
+
+```
+file:line - [principle] Description of issue
+```
+
+Example:
+```
+src/services/UserService.ts:15 - [solid-srp] Class handles validation, persistence, and notifications
+src/utils/helpers.ts:42 - [core-dry] Email validation duplicated from validators/email.ts
+src/models/Order.ts:28 - [name-meaningful] Variable 'x' should describe its purpose
+```
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/solid-srp-class.md
+rules/core-dry.md
+rules/pattern-repository.md
+```
+
+## References
+
+This skill is built on established software engineering principles:
+
+### Core Books
+- **Clean Code** by Robert C. Martin - Foundation for clean code practices
+- **Design Patterns** by Gang of Four - Classic design pattern catalog
+- **Refactoring** by Martin Fowler - Improving code structure
+- **The Pragmatic Programmer** by Hunt & Thomas - Practical wisdom
+
+### Online Resources
+- [Refactoring Guru](https://refactoring.guru/) - Design patterns and code smells
+- [Martin Fowler's Refactoring Catalog](https://refactoring.com/catalog/) - Comprehensive refactoring techniques
+- [Uncle Bob's Clean Coder Blog](https://blog.cleancoder.com/) - Software craftsmanship articles
+
+### Pattern Catalogs
+- [Refactoring Guru - Design Patterns](https://refactoring.guru/design-patterns)
+- [Martin Fowler - Enterprise Patterns](https://martinfowler.com/eaaCatalog/)
+
+## Metadata
+
+**Version:** 1.0.2
+**Status:** Active
+**Coverage:** 23 rules across 3 implemented categories (SOLID, Core Principles, Design Patterns); 4 planned
+**Last Updated:** 2026-03-07
+
+### Rule Statistics
+- SOLID Principles: 10 rules
+- Core Principles: 12 rules
+- Design Patterns: 1 rule
+
diff --git a/.agents/skills/clean-code-principles/rules/_sections.md b/.agents/skills/clean-code-principles/rules/_sections.md
new file mode 100644
index 0000000..7aa7cf7
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/_sections.md
@@ -0,0 +1,320 @@
+# Clean Code Principles - Rule Categories
+
+This document defines the organizational structure for clean code principles, ordered by priority and impact.
+
+## Category Overview
+
+| Priority | Category | Impact | Rule Count | Prefix |
+|----------|----------|--------|------------|--------|
+| 1 | SOLID Principles | CRITICAL | 10 | `solid-` |
+| 2 | Core Principles | CRITICAL | 12 | `core-` |
+| 3 | Design Patterns | HIGH | 1 | `pattern-` |
+| 4 | Code Organization | HIGH | 0 | `org-` |
+| 5 | Naming & Readability | MEDIUM | 0 | `name-` |
+| 6 | Functions & Methods | MEDIUM | 0 | `func-` |
+| 7 | Comments & Documentation | LOW | 0 | `doc-` |
+
+## 1. SOLID Principles (CRITICAL)
+
+**Priority:** CRITICAL
+**Impact:** Architectural foundation, affects entire codebase structure
+**Prefix:** `solid-`
+
+The five fundamental principles of object-oriented design that guide maintainable, scalable software architecture.
+
+### Rules
+
+#### Single Responsibility Principle (SRP)
+- `solid-srp-class` - A class should have only one reason to change
+- `solid-srp-function` - A function should do one thing and do it well
+
+#### Open/Closed Principle (OCP)
+- `solid-ocp-extension` - Open for extension, closed for modification
+- `solid-ocp-abstraction` - Use abstractions to enable extension
+
+#### Liskov Substitution Principle (LSP)
+- `solid-lsp-contracts` - Subtypes must honor base type contracts
+- `solid-lsp-preconditions` - Cannot strengthen preconditions or weaken postconditions
+
+#### Interface Segregation Principle (ISP)
+- `solid-isp-clients` - Client-specific interfaces, not general-purpose
+- `solid-isp-interfaces` - Small, cohesive interfaces
+
+#### Dependency Inversion Principle (DIP)
+- `solid-dip-abstractions` - Depend on abstractions, not concretions
+- `solid-dip-injection` - Inject dependencies from outside
+
+**Key Concepts:**
+- Architectural soundness
+- Maintainability at scale
+- Testability through design
+- Flexibility for change
+- Reduced coupling
+
+**When to Apply:**
+- Designing new features or systems
+- Refactoring existing architecture
+- Addressing technical debt
+- Improving testability
+- Planning for future extensibility
+
+---
+
+## 2. Core Principles (CRITICAL)
+
+**Priority:** CRITICAL
+**Impact:** Daily coding practices, code quality foundation
+**Prefix:** `core-`
+
+Fundamental principles that apply to every line of code you write, regardless of paradigm or language.
+
+### Rules
+
+#### DRY (Don't Repeat Yourself)
+- `core-dry` - Every piece of knowledge should have a single representation
+- `core-dry-extraction` - Extract duplicated code into reusable functions
+- `core-dry-single-source` - Single source of truth for configuration and data
+
+#### KISS (Keep It Simple, Stupid)
+- `core-kiss-simplicity` - Choose the simplest solution that works
+- `core-kiss-readability` - Optimize for readability over cleverness
+
+#### YAGNI (You Aren't Gonna Need It)
+- `core-yagni-features` - Don't implement features before they're needed
+- `core-yagni-abstractions` - Don't create abstractions prematurely
+
+#### Other Core Principles
+- `core-separation-concerns` - Different concerns in different modules
+- `core-composition` - Favor composition over inheritance
+- `core-law-demeter` - Only talk to immediate friends
+- `core-fail-fast` - Detect and report errors early
+- `core-encapsulation` - Hide implementation details
+
+**Key Concepts:**
+- Code duplication elimination
+- Simplicity over complexity
+- Lean development
+- Modularity
+- Information hiding
+
+**When to Apply:**
+- Writing any new code
+- Code reviews
+- Refactoring sessions
+- Bug fixes
+- Performance optimization
+
+---
+
+## 3. Design Patterns (HIGH)
+
+**Priority:** HIGH
+**Impact:** Solves recurring problems with proven solutions
+**Prefix:** `pattern-`
+
+Common design patterns that provide tested solutions to recurring software design problems.
+
+### Rules
+
+- `pattern-repository` - Abstraction for data access layer
+- `pattern-factory` - Object creation without specifying exact class (planned)
+- `pattern-strategy` - Encapsulate algorithms for runtime selection (planned)
+- `pattern-decorator` - Add behavior without modifying objects (planned)
+- `pattern-observer` - Define one-to-many dependencies (planned)
+- `pattern-adapter` - Make incompatible interfaces work together (planned)
+- `pattern-facade` - Simplified interface to complex subsystems (planned)
+
+**Key Concepts:**
+- Proven solutions
+- Common vocabulary
+- Design reusability
+- Best practices codified
+- Language-agnostic approaches
+
+**When to Apply:**
+- Solving common architectural problems
+- Improving code structure
+- Reducing coupling between components
+- Making systems more testable
+- Communicating design intent
+
+---
+
+## 4. Code Organization (HIGH)
+
+**Priority:** HIGH
+**Impact:** Project structure, module boundaries, discoverability
+**Prefix:** `org-`
+
+Principles for organizing code into modules, packages, and directories for maintainability and scalability.
+
+### Rules (Planned)
+
+- `org-feature-folders` - Organize by feature, not by layer
+- `org-module-boundaries` - Clear boundaries between modules
+- `org-layered-architecture` - Proper separation of layers
+- `org-package-cohesion` - Keep related code together
+- `org-circular-dependencies` - Avoid circular imports
+
+**Key Concepts:**
+- Feature-based organization
+- Module boundaries
+- Layer separation
+- Dependency direction
+- Discoverability
+
+**When to Apply:**
+- Starting new projects
+- Restructuring existing codebases
+- Scaling applications
+- Onboarding new team members
+- Managing microservices
+
+---
+
+## 5. Naming & Readability (MEDIUM)
+
+**Priority:** MEDIUM
+**Impact:** Code comprehension, maintenance speed
+**Prefix:** `name-`
+
+Conventions and principles for naming variables, functions, classes, and other identifiers.
+
+### Rules (Planned)
+
+- `name-meaningful` - Use intention-revealing names
+- `name-consistent` - Follow consistent naming conventions
+- `name-searchable` - Avoid magic numbers and strings
+- `name-avoid-encodings` - No Hungarian notation
+- `name-domain-language` - Use ubiquitous domain language
+
+**Key Concepts:**
+- Intention revelation
+- Consistency
+- Searchability
+- Domain terminology
+- Avoid abbreviations
+
+**When to Apply:**
+- Creating new identifiers
+- Refactoring unclear names
+- Code reviews
+- Domain modeling
+- API design
+
+---
+
+## 6. Functions & Methods (MEDIUM)
+
+**Priority:** MEDIUM
+**Impact:** Code readability, testability at function level
+**Prefix:** `func-`
+
+Principles for writing clean, focused functions and methods.
+
+### Rules (Planned)
+
+- `func-small` - Keep functions small and focused
+- `func-single-purpose` - Do one thing only
+- `func-few-arguments` - Limit function parameters
+- `func-no-side-effects` - Minimize or document side effects
+- `func-command-query` - Separate commands from queries
+
+**Key Concepts:**
+- Small functions
+- Single purpose
+- Few parameters
+- Pure functions when possible
+- Predictable behavior
+
+**When to Apply:**
+- Writing new functions
+- Refactoring long methods
+- Improving testability
+- Code reviews
+- Performance optimization
+
+---
+
+## 7. Comments & Documentation (LOW)
+
+**Priority:** LOW
+**Impact:** Code maintainability, knowledge transfer
+**Prefix:** `doc-`
+
+Guidelines for when and how to use comments and documentation effectively.
+
+### Rules (Planned)
+
+- `doc-self-documenting` - Write code that explains itself
+- `doc-why-not-what` - Comments should explain why, not what
+- `doc-avoid-noise` - No redundant or obvious comments
+- `doc-api-docs` - Document public APIs and interfaces
+
+**Key Concepts:**
+- Self-documenting code
+- Intent over implementation
+- Avoid redundancy
+- Public API documentation
+- Living documentation
+
+**When to Apply:**
+- Complex business logic
+- Non-obvious algorithms
+- Public APIs
+- Architectural decisions
+- Workarounds and hacks
+
+---
+
+## Rule Naming Convention
+
+All rules follow a consistent naming pattern:
+
+```
+{prefix}-{concept}-{specificity}
+```
+
+Examples:
+- `solid-srp-class` - SOLID principle, SRP concept, class level
+- `core-dry-extraction` - Core principle, DRY concept, extraction technique
+- `pattern-repository` - Design pattern category, repository pattern
+
+## Priority Levels Explained
+
+- **CRITICAL**: Core architectural and coding principles. Violations significantly impact maintainability, testability, and scalability.
+- **HIGH**: Important patterns and organizational principles. Violations complicate future development.
+- **MEDIUM**: Best practices that improve code quality. Violations make code harder to read and maintain.
+- **LOW**: Nice-to-have practices. Violations have minimal impact but reduce clarity.
+
+## Impact Assessment
+
+- **CRITICAL Impact**: Affects entire system architecture, multiple teams, long-term maintainability
+- **HIGH Impact**: Affects module design, team productivity, medium-term maintainability
+- **MEDIUM Impact**: Affects code readability, individual developer productivity
+- **LOW Impact**: Affects code clarity, documentation quality
+
+## Usage Guidelines
+
+1. Start with SOLID and Core Principles - these are non-negotiable
+2. Apply Design Patterns when solving specific architectural problems
+3. Use Code Organization principles when structuring projects
+4. Follow Naming & Readability guidelines for all new code
+5. Apply Function principles during refactoring and new development
+6. Add Comments only when necessary to explain complex logic
+
+## Cross-References
+
+Rules often relate to each other. The `related` field in each rule's frontmatter indicates:
+- Rules that commonly apply together
+- Rules that solve similar problems
+- Rules that complement each other
+- Rules that provide context or prerequisites
+
+## Evolution
+
+This categorization will evolve as:
+- New rules are added
+- Patterns emerge from practice
+- Team feedback is incorporated
+- Language-specific adaptations are needed
diff --git a/.agents/skills/clean-code-principles/rules/_template.md b/.agents/skills/clean-code-principles/rules/_template.md
new file mode 100644
index 0000000..d7c3c06
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/_template.md
@@ -0,0 +1,211 @@
+---
+id: {prefix}-{concept}-{specificity}
+title: {Full Descriptive Title}
+category: {solid-principles|core-principles|design-patterns|code-organization|naming-readability|functions-methods|comments-documentation}
+priority: {critical|high|medium|low}
+tags: [{tag1}, {tag2}, {tag3}, {tag4}]
+related: [{rule-id-1}, {rule-id-2}, {rule-id-3}]
+---
+
+# {Rule Title}
+
+{One or two sentence summary explaining the principle and why it matters. Should be clear and actionable.}
+
+## Bad Example
+
+```typescript
+// Anti-pattern: {Brief description of what's wrong}
+
+{Code example demonstrating the violation}
+
+// Problems:
+// 1. {Specific issue 1}
+// 2. {Specific issue 2}
+// 3. {Specific issue 3}
+```
+
+**Why This Is Wrong:**
+- {Consequence 1}
+- {Consequence 2}
+- {Consequence 3}
+
+## Good Example
+
+```typescript
+// Correct approach: {Brief description of the solution}
+
+{Code example demonstrating proper implementation}
+
+// Benefits:
+// 1. {Benefit 1}
+// 2. {Benefit 2}
+// 3. {Benefit 3}
+```
+
+**Alternative Approach (Optional):**
+
+```typescript
+// Another valid solution: {When this might be preferred}
+
+{Alternative code example if applicable}
+```
+
+## Why
+
+Explanation of the principle and its benefits:
+
+1. **{Benefit Category 1}**: {Detailed explanation}
+
+2. **{Benefit Category 2}**: {Detailed explanation}
+
+3. **{Benefit Category 3}**: {Detailed explanation}
+
+4. **{Benefit Category 4}**: {Detailed explanation}
+
+5. **{Benefit Category 5}**: {Detailed explanation}
+
+6. **{Benefit Category 6}**: {Detailed explanation}
+
+7. **{Benefit Category 7}**: {Detailed explanation}
+
+## When to Apply
+
+- {Situation 1}
+- {Situation 2}
+- {Situation 3}
+- {Situation 4}
+
+## When NOT to Apply (Optional)
+
+```typescript
+// Acceptable exception: {Scenario where the rule can be relaxed}
+
+{Code example of acceptable violation with clear reasoning}
+
+// This is acceptable because:
+// - {Reason 1}
+// - {Reason 2}
+```
+
+## Common Mistakes (Optional)
+
+### Mistake 1: {Common misunderstanding}
+
+```typescript
+// ❌ Wrong
+{Code showing mistake}
+
+// ✅ Correct
+{Code showing correction}
+```
+
+### Mistake 2: {Another common issue}
+
+```typescript
+// ❌ Wrong
+{Code showing mistake}
+
+// ✅ Correct
+{Code showing correction}
+```
+
+## Testing Implications (Optional)
+
+How this principle affects testing:
+
+```typescript
+// Test example showing improved testability
+{Test code demonstrating benefits}
+```
+
+## Real-World Example (Optional)
+
+{Brief description of how this applies in production scenarios}
+
+```typescript
+// Production scenario: {Description}
+{Realistic code example}
+```
+
+## Related Principles
+
+- **{Related Rule 1}**: {Brief explanation of relationship}
+- **{Related Rule 2}**: {Brief explanation of relationship}
+- **{Related Rule 3}**: {Brief explanation of relationship}
+
+## Further Reading (Optional)
+
+- {Resource title} - {URL or reference}
+- {Resource title} - {URL or reference}
+
+## Language-Specific Notes (Optional)
+
+### TypeScript/JavaScript
+{Language-specific considerations}
+
+### Python
+{Language-specific considerations}
+
+### Java
+{Language-specific considerations}
+
+### Go
+{Language-specific considerations}
+
+---
+
+## Template Guidelines
+
+### Frontmatter
+
+- **id**: Use format `{prefix}-{concept}-{specificity}`. Must be unique and match filename.
+- **title**: Full descriptive title, human-readable
+- **category**: One of the 7 defined categories
+- **priority**: critical (SOLID, Core) | high (Patterns, Org) | medium (Naming, Functions) | low (Comments)
+- **tags**: 3-5 relevant tags for searchability
+- **related**: 2-4 related rule IDs that commonly apply together
+
+### Content Structure
+
+1. **Title & Summary**: Clear, one-sentence explanation
+2. **Bad Example**: Show the anti-pattern with clear problems listed
+3. **Good Example**: Show proper implementation with benefits
+4. **Why**: 5-7 benefits explaining the value
+5. **When to Apply**: Practical scenarios
+6. **Optional Sections**: Add as needed for complex rules
+
+### Code Examples
+
+- Use TypeScript for primary examples (language-agnostic)
+- Keep examples focused and minimal
+- Show realistic scenarios, not toy examples
+- Include comments explaining key points
+- Use ❌ for bad examples, ✅ for good examples
+
+### Writing Style
+
+- Be direct and actionable
+- Focus on "why" not just "what"
+- Use active voice
+- Keep explanations concise
+- Provide context for decisions
+- Assume intermediate developer knowledge
+
+### Length Guidelines
+
+- Minimum: 200 lines (simple rules)
+- Target: 300-400 lines (most rules)
+- Maximum: 600 lines (complex patterns)
+
+### Quality Checklist
+
+- [ ] Frontmatter complete and accurate
+- [ ] Clear bad example with explained problems
+- [ ] Clear good example with explained benefits
+- [ ] At least 5 benefits in "Why" section
+- [ ] Practical "When to Apply" scenarios
+- [ ] Related rules referenced
+- [ ] Code examples are realistic
+- [ ] Comments explain key concepts
+- [ ] Language-agnostic where possible
+- [ ] Proofread for clarity and typos
diff --git a/.agents/skills/clean-code-principles/rules/core-composition.md b/.agents/skills/clean-code-principles/rules/core-composition.md
new file mode 100644
index 0000000..d0839c4
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-composition.md
@@ -0,0 +1,317 @@
+---
+id: core-composition
+title: Composition Over Inheritance
+category: core-principles
+priority: critical
+tags: [composition, inheritance, flexibility, design]
+related: [solid-srp-class, solid-dip-injection, core-encapsulation]
+---
+
+# Composition Over Inheritance
+
+Favor composing objects from smaller, focused pieces over building deep inheritance hierarchies. Composition provides more flexibility, better encapsulation, and avoids the fragile base class problem.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Deep inheritance hierarchy
+
+class Animal {
+  protected name: string;
+  protected energy: number = 100;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  eat(amount: number): void {
+    this.energy += amount;
+    console.log(`${this.name} is eating. Energy: ${this.energy}`);
+  }
+
+  sleep(hours: number): void {
+    this.energy += hours * 10;
+    console.log(`${this.name} slept for ${hours} hours. Energy: ${this.energy}`);
+  }
+}
+
+class Bird extends Animal {
+  fly(): void {
+    this.energy -= 20;
+    console.log(`${this.name} is flying. Energy: ${this.energy}`);
+  }
+}
+
+class Duck extends Bird {
+  swim(): void {
+    this.energy -= 5;
+    console.log(`${this.name} is swimming. Energy: ${this.energy}`);
+  }
+
+  quack(): void {
+    console.log(`${this.name} says quack!`);
+  }
+}
+
+class FlyingFish extends Animal {
+  // Problem: Can't inherit from both Bird and Fish
+  // Must duplicate flying code or create awkward hierarchy
+
+  swim(): void {
+    this.energy -= 5;
+    console.log(`${this.name} is swimming. Energy: ${this.energy}`);
+  }
+
+  // Duplicated from Bird class!
+  fly(): void {
+    this.energy -= 20;
+    console.log(`${this.name} is flying. Energy: ${this.energy}`);
+  }
+}
+
+class Penguin extends Bird {
+  // Problem: Penguins can't fly but inherit fly()
+  // Must override to throw error - LSP violation
+
+  fly(): void {
+    throw new Error('Penguins cannot fly!');
+  }
+
+  swim(): void {
+    this.energy -= 5;
+    console.log(`${this.name} is swimming. Energy: ${this.energy}`);
+  }
+}
+
+// More problems:
+// - What about a robot bird? It doesn't eat or sleep.
+// - What about a bat? It flies but isn't a bird.
+// - Every change to Animal affects all subclasses.
+// - Testing requires understanding entire hierarchy.
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Composition with focused behaviors
+
+// Define behaviors as interfaces
+interface Eater {
+  eat(amount: number): void;
+}
+
+interface Sleeper {
+  sleep(hours: number): void;
+}
+
+interface Flyer {
+  fly(): void;
+}
+
+interface Swimmer {
+  swim(): void;
+}
+
+interface Speaker {
+  speak(): void;
+}
+
+// Implement behaviors as standalone classes
+class StandardEater implements Eater {
+  constructor(private entity: { name: string; energy: number }) {}
+
+  eat(amount: number): void {
+    this.entity.energy += amount;
+    console.log(`${this.entity.name} is eating. Energy: ${this.entity.energy}`);
+  }
+}
+
+class StandardSleeper implements Sleeper {
+  constructor(private entity: { name: string; energy: number }) {}
+
+  sleep(hours: number): void {
+    this.entity.energy += hours * 10;
+    console.log(`${this.entity.name} slept for ${hours} hours. Energy: ${this.entity.energy}`);
+  }
+}
+
+class WingedFlyer implements Flyer {
+  constructor(
+    private entity: { name: string; energy: number },
+    private energyCost: number = 20
+  ) {}
+
+  fly(): void {
+    this.entity.energy -= this.energyCost;
+    console.log(`${this.entity.name} is flying. Energy: ${this.entity.energy}`);
+  }
+}
+
+class AquaticSwimmer implements Swimmer {
+  constructor(
+    private entity: { name: string; energy: number },
+    private energyCost: number = 5
+  ) {}
+
+  swim(): void {
+    this.entity.energy -= this.energyCost;
+    console.log(`${this.entity.name} is swimming. Energy: ${this.entity.energy}`);
+  }
+}
+
+// Compose animals from behaviors
+class Duck implements Eater, Sleeper, Flyer, Swimmer, Speaker {
+  public name: string;
+  public energy: number = 100;
+
+  private eater: Eater;
+  private sleeper: Sleeper;
+  private flyer: Flyer;
+  private swimmer: Swimmer;
+
+  constructor(name: string) {
+    this.name = name;
+    this.eater = new StandardEater(this);
+    this.sleeper = new StandardSleeper(this);
+    this.flyer = new WingedFlyer(this);
+    this.swimmer = new AquaticSwimmer(this);
+  }
+
+  eat(amount: number): void {
+    this.eater.eat(amount);
+  }
+
+  sleep(hours: number): void {
+    this.sleeper.sleep(hours);
+  }
+
+  fly(): void {
+    this.flyer.fly();
+  }
+
+  swim(): void {
+    this.swimmer.swim();
+  }
+
+  speak(): void {
+    console.log(`${this.name} says quack!`);
+  }
+}
+
+// Penguin: swims but doesn't fly - no problem!
+class Penguin implements Eater, Sleeper, Swimmer, Speaker {
+  public name: string;
+  public energy: number = 100;
+
+  private eater: Eater;
+  private sleeper: Sleeper;
+  private swimmer: Swimmer;
+
+  constructor(name: string) {
+    this.name = name;
+    this.eater = new StandardEater(this);
+    this.sleeper = new StandardSleeper(this);
+    this.swimmer = new AquaticSwimmer(this);
+  }
+
+  eat(amount: number): void {
+    this.eater.eat(amount);
+  }
+
+  sleep(hours: number): void {
+    this.sleeper.sleep(hours);
+  }
+
+  swim(): void {
+    this.swimmer.swim();
+  }
+
+  speak(): void {
+    console.log(`${this.name} says squawk!`);
+  }
+}
+
+// Flying fish: swims and flies - easy!
+class FlyingFish implements Swimmer, Flyer {
+  public name: string;
+  public energy: number = 100;
+
+  private swimmer: Swimmer;
+  private flyer: Flyer;
+
+  constructor(name: string) {
+    this.name = name;
+    this.swimmer = new AquaticSwimmer(this);
+    this.flyer = new WingedFlyer(this, 30); // Different energy cost
+  }
+
+  swim(): void {
+    this.swimmer.swim();
+  }
+
+  fly(): void {
+    this.flyer.fly();
+  }
+}
+
+// Robot bird: flies but doesn't eat or sleep
+class RobotBird implements Flyer, Speaker {
+  public name: string;
+  public energy: number = 100;
+
+  private flyer: Flyer;
+
+  constructor(name: string) {
+    this.name = name;
+    this.flyer = new WingedFlyer(this, 10); // Efficient robot
+  }
+
+  fly(): void {
+    this.flyer.fly();
+  }
+
+  speak(): void {
+    console.log(`${this.name} says BEEP BOOP!`);
+  }
+
+  recharge(): void {
+    this.energy = 100;
+    console.log(`${this.name} recharged to full energy.`);
+  }
+}
+
+// Functions work with any entity that has the required behavior
+function makeEntityFly(flyer: Flyer): void {
+  flyer.fly();
+}
+
+function feedEntity(eater: Eater, amount: number): void {
+  eater.eat(amount);
+}
+
+// Works with duck, flying fish, or robot bird
+makeEntityFly(new Duck('Donald'));
+makeEntityFly(new FlyingFish('Nemo'));
+makeEntityFly(new RobotBird('R2D2'));
+
+// Works with duck or penguin, but not robot bird (correctly!)
+feedEntity(new Duck('Donald'), 50);
+feedEntity(new Penguin('Pingu'), 50);
+// feedEntity(new RobotBird('R2D2'), 50); // Type error - RobotBird isn't an Eater
+```
+
+## Why
+
+1. **Flexibility**: Compose any combination of behaviors. No artificial hierarchy constraints.
+
+2. **Avoids Diamond Problem**: No multiple inheritance issues. Just implement multiple interfaces.
+
+3. **LSP Compliance**: No need to override methods to throw errors. Types only have methods they actually support.
+
+4. **Reusability**: Behaviors can be reused across unrelated types.
+
+5. **Testability**: Test behaviors in isolation. Mock specific behaviors easily.
+
+6. **Runtime Flexibility**: Can change behaviors at runtime by swapping implementations.
+
+7. **Stable Dependencies**: Behavior implementations are stable. Adding new composed types doesn't affect existing code.
diff --git a/.agents/skills/clean-code-principles/rules/core-dry-extraction.md b/.agents/skills/clean-code-principles/rules/core-dry-extraction.md
new file mode 100644
index 0000000..55b617d
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-dry-extraction.md
@@ -0,0 +1,316 @@
+---
+id: core-dry-extraction
+title: DRY - Code Extraction
+category: core-principles
+priority: critical
+tags: [DRY, refactoring, extraction, code-reuse]
+related: [core-dry, core-dry-single-source, solid-srp-function]
+---
+
+# DRY - Code Extraction
+
+Don't Repeat Yourself. When you find duplicated code, extract it into a reusable function, method, or module. Every piece of knowledge should have a single, unambiguous representation.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Same validation logic repeated in multiple places
+
+class UserController {
+  async createUser(req: Request, res: Response): Promise<void> {
+    const { email, password, name } = req.body;
+
+    // Email validation - duplicated
+    if (!email) {
+      res.status(400).json({ error: 'Email is required' });
+      return;
+    }
+    if (!email.includes('@') || !email.includes('.')) {
+      res.status(400).json({ error: 'Invalid email format' });
+      return;
+    }
+    if (email.length > 255) {
+      res.status(400).json({ error: 'Email too long' });
+      return;
+    }
+
+    // Password validation - duplicated
+    if (!password) {
+      res.status(400).json({ error: 'Password is required' });
+      return;
+    }
+    if (password.length < 8) {
+      res.status(400).json({ error: 'Password must be at least 8 characters' });
+      return;
+    }
+    if (!/[A-Z]/.test(password)) {
+      res.status(400).json({ error: 'Password must contain uppercase letter' });
+      return;
+    }
+    if (!/[0-9]/.test(password)) {
+      res.status(400).json({ error: 'Password must contain a number' });
+      return;
+    }
+
+    // Create user...
+  }
+
+  async updateUser(req: Request, res: Response): Promise<void> {
+    const { email, password } = req.body;
+
+    // Same email validation repeated
+    if (email) {
+      if (!email.includes('@') || !email.includes('.')) {
+        res.status(400).json({ error: 'Invalid email format' });
+        return;
+      }
+      if (email.length > 255) {
+        res.status(400).json({ error: 'Email too long' });
+        return;
+      }
+    }
+
+    // Same password validation repeated
+    if (password) {
+      if (password.length < 8) {
+        res.status(400).json({ error: 'Password must be at least 8 characters' });
+        return;
+      }
+      if (!/[A-Z]/.test(password)) {
+        res.status(400).json({ error: 'Password must contain uppercase letter' });
+        return;
+      }
+      if (!/[0-9]/.test(password)) {
+        res.status(400).json({ error: 'Password must contain a number' });
+        return;
+      }
+    }
+
+    // Update user...
+  }
+
+  async resetPassword(req: Request, res: Response): Promise<void> {
+    const { email, newPassword } = req.body;
+
+    // Email validation repeated again
+    if (!email) {
+      res.status(400).json({ error: 'Email is required' });
+      return;
+    }
+    if (!email.includes('@') || !email.includes('.')) {
+      res.status(400).json({ error: 'Invalid email format' });
+      return;
+    }
+
+    // Password validation repeated again
+    if (!newPassword) {
+      res.status(400).json({ error: 'New password is required' });
+      return;
+    }
+    if (newPassword.length < 8) {
+      res.status(400).json({ error: 'Password must be at least 8 characters' });
+      return;
+    }
+    if (!/[A-Z]/.test(newPassword)) {
+      res.status(400).json({ error: 'Password must contain uppercase letter' });
+      return;
+    }
+    if (!/[0-9]/.test(newPassword)) {
+      res.status(400).json({ error: 'Password must contain a number' });
+      return;
+    }
+
+    // Reset password...
+  }
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Extract reusable validation functions
+
+// Validation result type
+interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+// Reusable validation functions
+class Validators {
+  static email(email: string | undefined, options: { required?: boolean } = {}): ValidationResult {
+    const errors: string[] = [];
+
+    if (!email) {
+      if (options.required) {
+        errors.push('Email is required');
+      }
+      return { isValid: !options.required, errors };
+    }
+
+    if (!email.includes('@') || !email.includes('.')) {
+      errors.push('Invalid email format');
+    }
+
+    if (email.length > 255) {
+      errors.push('Email must be 255 characters or less');
+    }
+
+    return { isValid: errors.length === 0, errors };
+  }
+
+  static password(password: string | undefined, options: { required?: boolean } = {}): ValidationResult {
+    const errors: string[] = [];
+
+    if (!password) {
+      if (options.required) {
+        errors.push('Password is required');
+      }
+      return { isValid: !options.required, errors };
+    }
+
+    if (password.length < 8) {
+      errors.push('Password must be at least 8 characters');
+    }
+
+    if (!/[A-Z]/.test(password)) {
+      errors.push('Password must contain at least one uppercase letter');
+    }
+
+    if (!/[a-z]/.test(password)) {
+      errors.push('Password must contain at least one lowercase letter');
+    }
+
+    if (!/[0-9]/.test(password)) {
+      errors.push('Password must contain at least one number');
+    }
+
+    return { isValid: errors.length === 0, errors };
+  }
+
+  static combine(...results: ValidationResult[]): ValidationResult {
+    const errors = results.flatMap(r => r.errors);
+    return { isValid: errors.length === 0, errors };
+  }
+}
+
+// Reusable error response helper
+function validationError(res: Response, errors: string[]): void {
+  res.status(400).json({ errors });
+}
+
+// Clean controller using extracted validations
+class UserController {
+  async createUser(req: Request, res: Response): Promise<void> {
+    const { email, password, name } = req.body;
+
+    const validation = Validators.combine(
+      Validators.email(email, { required: true }),
+      Validators.password(password, { required: true })
+    );
+
+    if (!validation.isValid) {
+      return validationError(res, validation.errors);
+    }
+
+    // Create user...
+  }
+
+  async updateUser(req: Request, res: Response): Promise<void> {
+    const { email, password } = req.body;
+
+    const validation = Validators.combine(
+      Validators.email(email),
+      Validators.password(password)
+    );
+
+    if (!validation.isValid) {
+      return validationError(res, validation.errors);
+    }
+
+    // Update user...
+  }
+
+  async resetPassword(req: Request, res: Response): Promise<void> {
+    const { email, newPassword } = req.body;
+
+    const validation = Validators.combine(
+      Validators.email(email, { required: true }),
+      Validators.password(newPassword, { required: true })
+    );
+
+    if (!validation.isValid) {
+      return validationError(res, validation.errors);
+    }
+
+    // Reset password...
+  }
+}
+
+// Validators can be reused across the application
+class AdminController {
+  async inviteUser(req: Request, res: Response): Promise<void> {
+    const { email } = req.body;
+
+    const validation = Validators.email(email, { required: true });
+
+    if (!validation.isValid) {
+      return validationError(res, validation.errors);
+    }
+
+    // Send invite...
+  }
+}
+
+// Easy to test in isolation
+describe('Validators', () => {
+  describe('email', () => {
+    it('should reject invalid email format', () => {
+      const result = Validators.email('invalid');
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Invalid email format');
+    });
+
+    it('should accept valid email', () => {
+      const result = Validators.email('user@example.com');
+      expect(result.isValid).toBe(true);
+    });
+
+    it('should require email when required option is set', () => {
+      const result = Validators.email(undefined, { required: true });
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Email is required');
+    });
+  });
+
+  describe('password', () => {
+    it('should reject short passwords', () => {
+      const result = Validators.password('short');
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Password must be at least 8 characters');
+    });
+
+    it('should require uppercase letter', () => {
+      const result = Validators.password('lowercase123');
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Password must contain at least one uppercase letter');
+    });
+  });
+});
+```
+
+## Why
+
+1. **Single Source of Truth**: Password rules are defined once. Change them in one place, and all usages are updated.
+
+2. **Consistency**: All email validations behave the same way. No risk of inconsistent error messages or rules.
+
+3. **Easier Testing**: Test the validation logic once, thoroughly. No need to test the same logic in every controller.
+
+4. **Bug Fixes Propagate**: Fix a bug in `Validators.email()`, and it's fixed everywhere.
+
+5. **Reduced Code Size**: Less code means less to read, less to maintain, and fewer places for bugs.
+
+6. **Better Abstraction**: Controllers focus on HTTP concerns, validators focus on validation.
+
+7. **Reusability**: Same validators work in controllers, services, CLI tools, or anywhere else.
diff --git a/.agents/skills/clean-code-principles/rules/core-dry-single-source.md b/.agents/skills/clean-code-principles/rules/core-dry-single-source.md
new file mode 100644
index 0000000..63e5415
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-dry-single-source.md
@@ -0,0 +1,282 @@
+---
+id: core-dry-single-source
+title: DRY - Single Source of Truth
+category: core-principles
+priority: critical
+tags: [DRY, single-source-of-truth, constants, configuration]
+related: [core-dry, core-dry-extraction, core-encapsulation]
+---
+
+# DRY - Single Source of Truth
+
+Every piece of knowledge or configuration should exist in exactly one place. When data or logic needs to be referenced from multiple locations, use a single authoritative source.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Same values defined in multiple places
+
+// In constants file
+const API_BASE_URL = 'https://api.example.com/v1';
+
+// In another file - duplicate!
+const baseUrl = 'https://api.example.com/v1';
+
+// In config.ts - another duplicate!
+export const config = {
+  apiUrl: 'https://api.example.com/v1'
+};
+
+// In API client - yet another!
+class ApiClient {
+  private baseUrl = 'https://api.example.com/v1'; // Duplicated!
+}
+
+// Status codes defined in multiple places
+class OrderService {
+  async getOrder(id: string): Promise<Order> {
+    const order = await this.repository.findById(id);
+    if (order.status === 'pending') { // Magic string
+      // ...
+    }
+    if (order.status === 'completed') { // Magic string
+      // ...
+    }
+  }
+}
+
+class OrderController {
+  async listPendingOrders(): Promise<Order[]> {
+    return this.repository.findByStatus('pending'); // Same magic string
+  }
+}
+
+// In frontend code
+const isPending = order.status === 'pending'; // And again
+
+// Database seeds with duplicated data
+const seedRoles = [
+  { id: 1, name: 'admin', permissions: ['read', 'write', 'delete', 'admin'] },
+  { id: 2, name: 'editor', permissions: ['read', 'write'] },
+  { id: 3, name: 'viewer', permissions: ['read'] }
+];
+
+// In authorization middleware - duplicated permission logic
+function checkPermission(user: User, action: string): boolean {
+  if (user.role === 'admin') {
+    return true; // Admin can do anything - duplicated knowledge
+  }
+  if (user.role === 'editor' && ['read', 'write'].includes(action)) {
+    return true; // Editor permissions - duplicated
+  }
+  if (user.role === 'viewer' && action === 'read') {
+    return true; // Viewer permissions - duplicated
+  }
+  return false;
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Single source of truth for all shared knowledge
+
+// Configuration - one authoritative source
+// config/index.ts
+export const Config = {
+  api: {
+    baseUrl: process.env.API_BASE_URL || 'https://api.example.com/v1',
+    timeout: Number(process.env.API_TIMEOUT) || 30000,
+    retries: Number(process.env.API_RETRIES) || 3
+  },
+  database: {
+    url: process.env.DATABASE_URL!,
+    poolSize: Number(process.env.DB_POOL_SIZE) || 10
+  }
+} as const;
+
+// All code references the single config
+class ApiClient {
+  constructor(private baseUrl: string = Config.api.baseUrl) {}
+}
+
+// Enums for finite sets of values - single source of truth
+// domain/order/status.ts
+export const OrderStatus = {
+  PENDING: 'pending',
+  PROCESSING: 'processing',
+  SHIPPED: 'shipped',
+  DELIVERED: 'delivered',
+  CANCELLED: 'cancelled'
+} as const;
+
+export type OrderStatus = typeof OrderStatus[keyof typeof OrderStatus];
+
+// All code uses the enum
+class OrderService {
+  async getOrder(id: string): Promise<Order> {
+    const order = await this.repository.findById(id);
+    if (order.status === OrderStatus.PENDING) {
+      // Single source of truth
+    }
+  }
+}
+
+class OrderController {
+  async listPendingOrders(): Promise<Order[]> {
+    return this.repository.findByStatus(OrderStatus.PENDING); // Same source
+  }
+}
+
+// Roles and permissions - single authoritative definition
+// domain/auth/roles.ts
+export const Permission = {
+  READ: 'read',
+  WRITE: 'write',
+  DELETE: 'delete',
+  ADMIN: 'admin'
+} as const;
+
+export type Permission = typeof Permission[keyof typeof Permission];
+
+export const RoleDefinitions = {
+  admin: {
+    name: 'Administrator',
+    permissions: [Permission.READ, Permission.WRITE, Permission.DELETE, Permission.ADMIN]
+  },
+  editor: {
+    name: 'Editor',
+    permissions: [Permission.READ, Permission.WRITE]
+  },
+  viewer: {
+    name: 'Viewer',
+    permissions: [Permission.READ]
+  }
+} as const;
+
+export type RoleName = keyof typeof RoleDefinitions;
+
+// Permission checking uses the definitions
+export function hasPermission(role: RoleName, permission: Permission): boolean {
+  const roleDef = RoleDefinitions[role];
+  return roleDef.permissions.includes(permission);
+}
+
+// Database seeds generated from the single source
+export function generateRoleSeeds(): RoleSeed[] {
+  return Object.entries(RoleDefinitions).map(([key, def], index) => ({
+    id: index + 1,
+    name: key,
+    displayName: def.name,
+    permissions: [...def.permissions]
+  }));
+}
+
+// Validation rules - single source
+// domain/user/validation.ts
+export const UserValidationRules = {
+  email: {
+    maxLength: 255,
+    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  },
+  password: {
+    minLength: 8,
+    maxLength: 128,
+    requireUppercase: true,
+    requireLowercase: true,
+    requireNumber: true,
+    requireSpecial: false
+  },
+  username: {
+    minLength: 3,
+    maxLength: 30,
+    pattern: /^[a-zA-Z0-9_]+$/
+  }
+} as const;
+
+// Validators use the rules
+export function validateEmail(email: string): ValidationResult {
+  const rules = UserValidationRules.email;
+
+  if (email.length > rules.maxLength) {
+    return { valid: false, error: `Email must be ${rules.maxLength} characters or less` };
+  }
+  if (!rules.pattern.test(email)) {
+    return { valid: false, error: 'Invalid email format' };
+  }
+  return { valid: true };
+}
+
+// Database schema uses the same rules
+// migrations/001_create_users.ts
+export const createUsersTable = `
+  CREATE TABLE users (
+    id UUID PRIMARY KEY,
+    email VARCHAR(${UserValidationRules.email.maxLength}) NOT NULL UNIQUE,
+    username VARCHAR(${UserValidationRules.username.maxLength}) NOT NULL UNIQUE,
+    -- ...
+  )
+`;
+
+// Frontend validation uses the same rules (shared module)
+// shared/validation.ts (used by both frontend and backend)
+export function getPasswordRequirements(): string[] {
+  const rules = UserValidationRules.password;
+  const requirements: string[] = [];
+
+  requirements.push(`At least ${rules.minLength} characters`);
+  if (rules.requireUppercase) requirements.push('At least one uppercase letter');
+  if (rules.requireLowercase) requirements.push('At least one lowercase letter');
+  if (rules.requireNumber) requirements.push('At least one number');
+  if (rules.requireSpecial) requirements.push('At least one special character');
+
+  return requirements;
+}
+
+// Error messages - single source
+// errors/messages.ts
+export const ErrorMessages = {
+  user: {
+    notFound: 'User not found',
+    alreadyExists: 'A user with this email already exists',
+    invalidCredentials: 'Invalid email or password',
+    accountLocked: 'Account is locked. Please contact support.'
+  },
+  order: {
+    notFound: 'Order not found',
+    alreadyCancelled: 'Order has already been cancelled',
+    cannotCancel: 'Order cannot be cancelled in its current state'
+  },
+  auth: {
+    tokenExpired: 'Your session has expired. Please log in again.',
+    unauthorized: 'You do not have permission to perform this action'
+  }
+} as const;
+
+// All code uses the same error messages
+class UserService {
+  async findById(id: string): Promise<User> {
+    const user = await this.repository.findById(id);
+    if (!user) {
+      throw new NotFoundError(ErrorMessages.user.notFound);
+    }
+    return user;
+  }
+}
+```
+
+## Why
+
+1. **Consistency**: The same value is always the same everywhere. No "this worked yesterday" bugs.
+
+2. **Easy Updates**: Change a validation rule, config value, or status code in one place.
+
+3. **Prevents Drift**: Without a single source, values diverge over time as different developers make changes.
+
+4. **Documentation**: The source file serves as documentation for what values are valid.
+
+5. **Type Safety**: TypeScript can enforce that only valid values are used.
+
+6. **Searchability**: Easy to find all usages by searching for the constant name.
+
+7. **Refactoring**: Rename a status? Change it in one place and let the compiler find all usages.
diff --git a/.agents/skills/clean-code-principles/rules/core-dry.md b/.agents/skills/clean-code-principles/rules/core-dry.md
new file mode 100644
index 0000000..9ec1160
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-dry.md
@@ -0,0 +1,320 @@
+---
+id: core-dry
+title: Don't Repeat Yourself (DRY)
+category: core-principles
+priority: critical
+tags: [DRY, duplication, single-source-of-truth, maintainability]
+related: [core-dry-extraction, core-dry-single-source, solid-srp-class]
+---
+
+# Don't Repeat Yourself (DRY)
+
+## Why It Matters
+
+"Don't Repeat Yourself" means every piece of knowledge should have a single, authoritative representation. Duplication leads to inconsistencies, increases maintenance burden, and makes bugs harder to fix. When you change one copy but forget others, bugs creep in.
+
+## Incorrect
+
+```typescript
+// ❌ Duplicated validation logic
+class UserController {
+  createUser(data) {
+    if (!data.email || !data.email.includes('@')) {
+      throw new Error('Invalid email');
+    }
+    if (!data.password || data.password.length < 8) {
+      throw new Error('Password too short');
+    }
+    // create user...
+  }
+
+  updateUser(id, data) {
+    if (!data.email || !data.email.includes('@')) { // Duplicated
+      throw new Error('Invalid email');
+    }
+    if (!data.password || data.password.length < 8) { // Duplicated
+      throw new Error('Password too short');
+    }
+    // update user...
+  }
+}
+
+// ❌ Duplicated business rules
+function calculateOrderTotal(items) {
+  let total = 0;
+  for (const item of items) {
+    total += item.price * item.quantity;
+  }
+  if (total > 100) {
+    total = total * 0.9; // 10% discount over $100
+  }
+  return total;
+}
+
+function calculateCartTotal(cartItems) {
+  let total = 0;
+  for (const item of cartItems) {
+    total += item.price * item.quantity; // Duplicated
+  }
+  if (total > 100) {
+    total = total * 0.9; // Duplicated discount logic
+  }
+  return total;
+}
+
+// ❌ Duplicated constants
+// file: checkout.ts
+const TAX_RATE = 0.08;
+const FREE_SHIPPING_THRESHOLD = 50;
+
+// file: cart.ts
+const TAX_RATE = 0.08; // Duplicated
+const FREE_SHIPPING_THRESHOLD = 50; // Duplicated
+```
+
+## Correct
+
+### Extract Shared Validation
+
+```typescript
+// ✅ Single validation module
+// validators/user.ts
+export class UserValidator {
+  static validateEmail(email: string): void {
+    if (!email || !email.includes('@')) {
+      throw new ValidationError('Invalid email address');
+    }
+  }
+
+  static validatePassword(password: string): void {
+    if (!password || password.length < 8) {
+      throw new ValidationError('Password must be at least 8 characters');
+    }
+  }
+
+  static validate(data: UserData): void {
+    this.validateEmail(data.email);
+    this.validatePassword(data.password);
+  }
+}
+
+// controller.ts
+class UserController {
+  createUser(data) {
+    UserValidator.validate(data);
+    // create user...
+  }
+
+  updateUser(id, data) {
+    UserValidator.validate(data);
+    // update user...
+  }
+}
+```
+
+### Extract Shared Business Logic
+
+```typescript
+// ✅ Single source of truth for pricing
+// services/pricing.ts
+export class PricingService {
+  private static readonly BULK_DISCOUNT_THRESHOLD = 100;
+  private static readonly BULK_DISCOUNT_RATE = 0.1;
+
+  static calculateSubtotal(items: LineItem[]): number {
+    return items.reduce(
+      (sum, item) => sum + item.price * item.quantity,
+      0
+    );
+  }
+
+  static applyDiscount(subtotal: number): number {
+    if (subtotal > this.BULK_DISCOUNT_THRESHOLD) {
+      return subtotal * (1 - this.BULK_DISCOUNT_RATE);
+    }
+    return subtotal;
+  }
+
+  static calculateTotal(items: LineItem[]): number {
+    const subtotal = this.calculateSubtotal(items);
+    return this.applyDiscount(subtotal);
+  }
+}
+
+// Both order and cart use the same logic
+const orderTotal = PricingService.calculateTotal(order.items);
+const cartTotal = PricingService.calculateTotal(cart.items);
+```
+
+### Centralize Constants
+
+```typescript
+// ✅ Single constants file
+// constants/pricing.ts
+export const PRICING = {
+  TAX_RATE: 0.08,
+  FREE_SHIPPING_THRESHOLD: 50,
+  BULK_DISCOUNT_THRESHOLD: 100,
+  BULK_DISCOUNT_RATE: 0.1,
+} as const;
+
+// Used everywhere
+import { PRICING } from '@/constants/pricing';
+
+const tax = subtotal * PRICING.TAX_RATE;
+const freeShipping = total >= PRICING.FREE_SHIPPING_THRESHOLD;
+```
+
+### Extract Shared Components
+
+```tsx
+// ❌ Duplicated UI patterns
+function UserCard({ user }) {
+  return (
+    <div className="p-4 rounded-lg shadow bg-white">
+      <img src={user.avatar} className="w-12 h-12 rounded-full" />
+      <h3 className="font-bold">{user.name}</h3>
+      <p className="text-gray-600">{user.email}</p>
+    </div>
+  );
+}
+
+function TeamMemberCard({ member }) {
+  return (
+    <div className="p-4 rounded-lg shadow bg-white"> {/* Same styles */}
+      <img src={member.avatar} className="w-12 h-12 rounded-full" />
+      <h3 className="font-bold">{member.name}</h3>
+      <p className="text-gray-600">{member.role}</p>
+    </div>
+  );
+}
+
+// ✅ Reusable component
+function Card({ children, className }) {
+  return (
+    <div className={cn("p-4 rounded-lg shadow bg-white", className)}>
+      {children}
+    </div>
+  );
+}
+
+function Avatar({ src, alt }) {
+  return <img src={src} alt={alt} className="w-12 h-12 rounded-full" />;
+}
+
+function UserCard({ user }) {
+  return (
+    <Card>
+      <Avatar src={user.avatar} alt={user.name} />
+      <h3 className="font-bold">{user.name}</h3>
+      <p className="text-gray-600">{user.email}</p>
+    </Card>
+  );
+}
+
+function TeamMemberCard({ member }) {
+  return (
+    <Card>
+      <Avatar src={member.avatar} alt={member.name} />
+      <h3 className="font-bold">{member.name}</h3>
+      <p className="text-gray-600">{member.role}</p>
+    </Card>
+  );
+}
+```
+
+### Extract Shared Hooks
+
+```typescript
+// ❌ Duplicated fetch logic
+function UserProfile() {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/user')
+      .then(res => res.json())
+      .then(setUser)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, []);
+  // ...
+}
+
+function ProductList() {
+  const [products, setProducts] = useState(null);
+  const [loading, setLoading] = useState(true); // Duplicated
+  const [error, setError] = useState(null); // Duplicated
+
+  useEffect(() => {
+    fetch('/api/products') // Same pattern
+      .then(res => res.json())
+      .then(setProducts)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, []);
+  // ...
+}
+
+// ✅ Custom hook (or use React Query)
+function useFetch<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    fetch(url)
+      .then(res => res.json())
+      .then(setData)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, [url]);
+
+  return { data, loading, error };
+}
+
+function UserProfile() {
+  const { data: user, loading, error } = useFetch<User>('/api/user');
+  // ...
+}
+
+function ProductList() {
+  const { data: products, loading, error } = useFetch<Product[]>('/api/products');
+  // ...
+}
+```
+
+## When NOT to DRY
+
+```typescript
+// ⚠️ Don't extract coincidentally similar code
+// These might look similar but serve different purposes
+
+function validateUserAge(age: number) {
+  return age >= 18; // Legal adult age
+}
+
+function validateMinimumOrderQuantity(quantity: number) {
+  return quantity >= 18; // Business rule: minimum order
+}
+
+// These should remain separate even though both check >= 18
+// Their reasons for change are different
+```
+
+## Rule of Three
+
+```
+Wait until you see duplication three times before extracting.
+Two occurrences might be coincidental. Three indicates a pattern.
+```
+
+## Benefits
+
+- Single source of truth
+- Fix bugs in one place
+- Consistent behavior across codebase
+- Easier refactoring
+- Reduced code size
+- Lower maintenance cost
diff --git a/.agents/skills/clean-code-principles/rules/core-encapsulation.md b/.agents/skills/clean-code-principles/rules/core-encapsulation.md
new file mode 100644
index 0000000..5c9bcea
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-encapsulation.md
@@ -0,0 +1,335 @@
+---
+id: core-encapsulation
+title: Encapsulation
+category: core-principles
+priority: critical
+tags: [encapsulation, information-hiding, data-protection]
+related: [solid-srp-class, core-law-demeter, solid-isp-interfaces]
+---
+
+# Encapsulation
+
+Hide internal implementation details and expose only what's necessary through a well-defined interface. Protect data integrity by controlling access to internal state.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Exposed internals, no encapsulation
+
+class BankAccount {
+  // Public fields - anyone can modify directly
+  public accountNumber: string;
+  public balance: number;
+  public transactions: Transaction[];
+  public overdraftLimit: number;
+  public isLocked: boolean;
+
+  constructor(accountNumber: string, initialBalance: number) {
+    this.accountNumber = accountNumber;
+    this.balance = initialBalance;
+    this.transactions = [];
+    this.overdraftLimit = 0;
+    this.isLocked = false;
+  }
+}
+
+// External code can violate business rules
+const account = new BankAccount('12345', 1000);
+
+// Direct modification bypasses validation
+account.balance = -999999; // Negative balance without check!
+account.balance = account.balance + 1000; // No transaction record!
+
+// Can manipulate transaction history
+account.transactions.push({
+  id: 'fake',
+  amount: 1000000,
+  type: 'deposit'
+}); // Fraudulent transaction!
+
+// Can unlock locked accounts
+account.isLocked = false; // Bypasses security!
+
+// Can change overdraft without authorization
+account.overdraftLimit = 100000; // Unauthorized overdraft!
+
+// Other classes depend on internal structure
+class AccountReport {
+  generate(account: BankAccount): Report {
+    // Directly accesses internal array
+    const deposits = account.transactions.filter(t => t.type === 'deposit');
+    const withdrawals = account.transactions.filter(t => t.type === 'withdrawal');
+
+    // Depends on internal structure of Transaction
+    const totalDeposits = deposits.reduce((sum, t) => sum + t.amount, 0);
+
+    return {
+      balance: account.balance,
+      totalDeposits,
+      transactionCount: account.transactions.length
+    };
+  }
+}
+
+// Problems:
+// 1. Anyone can modify balance without recording transaction
+// 2. Business rules can be bypassed
+// 3. No audit trail for changes
+// 4. Internal structure changes break external code
+// 5. No way to add validation later without breaking changes
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Proper encapsulation
+
+class BankAccount {
+  private readonly _accountNumber: string;
+  private _balance: number;
+  private readonly _transactions: Transaction[] = [];
+  private _overdraftLimit: number = 0;
+  private _isLocked: boolean = false;
+  private _lockReason: string | null = null;
+
+  constructor(accountNumber: string, initialBalance: number) {
+    if (!accountNumber || accountNumber.length < 5) {
+      throw new Error('Invalid account number');
+    }
+    if (initialBalance < 0) {
+      throw new Error('Initial balance cannot be negative');
+    }
+
+    this._accountNumber = accountNumber;
+    this._balance = initialBalance;
+    this._transactions.push(
+      Transaction.createInitial(initialBalance)
+    );
+  }
+
+  // Read-only access to account number
+  get accountNumber(): string {
+    return this._accountNumber;
+  }
+
+  // Read-only access to balance
+  get balance(): number {
+    return this._balance;
+  }
+
+  // Read-only access to lock status
+  get isLocked(): boolean {
+    return this._isLocked;
+  }
+
+  // Controlled deposit with validation and audit trail
+  deposit(amount: number, description: string = 'Deposit'): Transaction {
+    this.ensureNotLocked();
+
+    if (amount <= 0) {
+      throw new InvalidAmountError('Deposit amount must be positive');
+    }
+
+    this._balance += amount;
+
+    const transaction = Transaction.createDeposit(amount, description, this._balance);
+    this._transactions.push(transaction);
+
+    return transaction;
+  }
+
+  // Controlled withdrawal with business rules
+  withdraw(amount: number, description: string = 'Withdrawal'): Transaction {
+    this.ensureNotLocked();
+
+    if (amount <= 0) {
+      throw new InvalidAmountError('Withdrawal amount must be positive');
+    }
+
+    const availableBalance = this._balance + this._overdraftLimit;
+    if (amount > availableBalance) {
+      throw new InsufficientFundsError(amount, availableBalance);
+    }
+
+    this._balance -= amount;
+
+    const transaction = Transaction.createWithdrawal(amount, description, this._balance);
+    this._transactions.push(transaction);
+
+    return transaction;
+  }
+
+  // Transfer with proper validation
+  transferTo(recipient: BankAccount, amount: number): TransferResult {
+    this.ensureNotLocked();
+    recipient.ensureNotLocked();
+
+    if (amount <= 0) {
+      throw new InvalidAmountError('Transfer amount must be positive');
+    }
+
+    const withdrawalTx = this.withdraw(amount, `Transfer to ${recipient.accountNumber}`);
+    const depositTx = recipient.deposit(amount, `Transfer from ${this._accountNumber}`);
+
+    return { withdrawalTx, depositTx };
+  }
+
+  // Controlled overdraft limit modification
+  setOverdraftLimit(limit: number, authorizedBy: string): void {
+    if (limit < 0) {
+      throw new Error('Overdraft limit cannot be negative');
+    }
+    if (limit > 10000) {
+      throw new Error('Overdraft limit exceeds maximum allowed');
+    }
+
+    this._overdraftLimit = limit;
+
+    // Audit trail for limit changes
+    this._transactions.push(
+      Transaction.createAdministrative(
+        `Overdraft limit set to ${limit} by ${authorizedBy}`
+      )
+    );
+  }
+
+  // Security control with audit
+  lock(reason: string): void {
+    this._isLocked = true;
+    this._lockReason = reason;
+    this._transactions.push(
+      Transaction.createAdministrative(`Account locked: ${reason}`)
+    );
+  }
+
+  unlock(authorizedBy: string): void {
+    this._isLocked = false;
+    this._lockReason = null;
+    this._transactions.push(
+      Transaction.createAdministrative(`Account unlocked by ${authorizedBy}`)
+    );
+  }
+
+  // Return copy of transactions, not the internal array
+  getTransactionHistory(): ReadonlyArray<Transaction> {
+    return [...this._transactions];
+  }
+
+  // Provide summary without exposing internals
+  getSummary(): AccountSummary {
+    const deposits = this._transactions.filter(t => t.type === 'deposit');
+    const withdrawals = this._transactions.filter(t => t.type === 'withdrawal');
+
+    return {
+      accountNumber: this._accountNumber,
+      balance: this._balance,
+      isLocked: this._isLocked,
+      totalDeposits: deposits.reduce((sum, t) => sum + t.amount, 0),
+      totalWithdrawals: withdrawals.reduce((sum, t) => sum + t.amount, 0),
+      transactionCount: this._transactions.length
+    };
+  }
+
+  // Private helper method
+  private ensureNotLocked(): void {
+    if (this._isLocked) {
+      throw new AccountLockedError(this._lockReason || 'Account is locked');
+    }
+  }
+}
+
+// Transaction is also encapsulated
+class Transaction {
+  private constructor(
+    public readonly id: string,
+    public readonly type: TransactionType,
+    public readonly amount: number,
+    public readonly description: string,
+    public readonly balanceAfter: number,
+    public readonly timestamp: Date
+  ) {}
+
+  static createDeposit(amount: number, description: string, balanceAfter: number): Transaction {
+    return new Transaction(
+      generateId(),
+      'deposit',
+      amount,
+      description,
+      balanceAfter,
+      new Date()
+    );
+  }
+
+  static createWithdrawal(amount: number, description: string, balanceAfter: number): Transaction {
+    return new Transaction(
+      generateId(),
+      'withdrawal',
+      amount,
+      description,
+      balanceAfter,
+      new Date()
+    );
+  }
+
+  static createInitial(balance: number): Transaction {
+    return new Transaction(
+      generateId(),
+      'initial',
+      balance,
+      'Account opened',
+      balance,
+      new Date()
+    );
+  }
+
+  static createAdministrative(description: string): Transaction {
+    return new Transaction(
+      generateId(),
+      'administrative',
+      0,
+      description,
+      0,
+      new Date()
+    );
+  }
+}
+
+// Usage - business rules are enforced
+const account = new BankAccount('12345', 1000);
+
+// Proper deposit with audit trail
+account.deposit(500, 'Paycheck');
+
+// Withdrawal validates funds
+try {
+  account.withdraw(2000); // Will throw InsufficientFundsError
+} catch (error) {
+  console.log('Cannot withdraw more than available');
+}
+
+// Cannot manipulate balance directly
+// account.balance = 999999; // Error: Property 'balance' is read-only
+
+// Cannot manipulate transactions
+// account.getTransactionHistory().push(fakeTx); // Original array unaffected
+
+// Account summary provides what reports need
+const summary = account.getSummary();
+console.log(`Balance: ${summary.balance}, Transactions: ${summary.transactionCount}`);
+```
+
+## Why
+
+1. **Data Integrity**: Balance can only change through proper deposit/withdraw methods that maintain consistency.
+
+2. **Business Rules**: All rules (positive amounts, sufficient funds, locked accounts) are enforced in one place.
+
+3. **Audit Trail**: Every change is recorded. Cannot modify history without proper methods.
+
+4. **Flexibility**: Internal representation can change without affecting clients. Switch from array to database later.
+
+5. **Security**: Cannot bypass validation or manipulate internal state directly.
+
+6. **Testing**: Can verify all edge cases through the public interface. Internal state is controlled.
+
+7. **Documentation**: The public interface documents what operations are allowed and how to use them.
diff --git a/.agents/skills/clean-code-principles/rules/core-fail-fast.md b/.agents/skills/clean-code-principles/rules/core-fail-fast.md
new file mode 100644
index 0000000..a131641
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-fail-fast.md
@@ -0,0 +1,325 @@
+---
+id: core-fail-fast
+title: Fail Fast Principle
+category: core-principles
+priority: critical
+tags: [fail-fast, error-handling, validation]
+related: [solid-lsp-preconditions, core-encapsulation]
+---
+
+# Fail Fast Principle
+
+Detect and report errors as early as possible. Validate inputs at system boundaries, check preconditions at the start of functions, and throw exceptions immediately when something is wrong.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Delayed error detection
+
+class OrderProcessor {
+  async processOrder(order: any): Promise<ProcessResult> {
+    // No validation - problems will surface later
+
+    // Proceeds even with potentially invalid data
+    const customer = await this.customerRepo.findById(order.customerId);
+
+    // Customer might be null, but we keep going
+    const items = order.items;
+
+    // Calculates total even if items might be undefined or empty
+    let total = 0;
+    if (items) {
+      for (const item of items) {
+        // item.productId might not exist
+        const product = await this.productRepo.findById(item.productId);
+        // product might be null
+        if (product) {
+          total += product.price * (item.quantity || 1);
+        }
+      }
+    }
+
+    // Attempts payment even if customer is null
+    let paymentResult;
+    if (customer && customer.paymentMethod) {
+      paymentResult = await this.paymentService.charge(
+        customer.paymentMethod,
+        total
+      );
+    }
+
+    // Creates order record even if payment failed
+    const orderRecord = await this.orderRepo.create({
+      customerId: order.customerId,
+      total,
+      status: paymentResult?.success ? 'paid' : 'pending'
+    });
+
+    // Sends email even if we don't have a valid email
+    if (customer?.email) {
+      await this.emailService.send(customer.email, 'Order confirmation');
+    }
+
+    // Returns "success" even though many things might have gone wrong
+    return { success: true, orderId: orderRecord.id };
+  }
+}
+
+// Problems:
+// 1. Null customer leads to silent failures
+// 2. Empty order goes through system doing nothing useful
+// 3. Payment failure creates orphaned order records
+// 4. No indication of what went wrong
+// 5. Database in inconsistent state
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Fail fast with immediate validation
+
+// Custom error types for clear failure reasons
+class ValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly value: unknown
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+class NotFoundError extends Error {
+  constructor(
+    public readonly entity: string,
+    public readonly id: string
+  ) {
+    super(`${entity} not found: ${id}`);
+    this.name = 'NotFoundError';
+  }
+}
+
+class PaymentError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string
+  ) {
+    super(message);
+    this.name = 'PaymentError';
+  }
+}
+
+// Input validation schema
+interface CreateOrderInput {
+  customerId: string;
+  items: OrderItemInput[];
+}
+
+interface OrderItemInput {
+  productId: string;
+  quantity: number;
+}
+
+class OrderProcessor {
+  async processOrder(input: unknown): Promise<ProcessResult> {
+    // STEP 1: Validate input immediately
+    const validatedInput = this.validateInput(input);
+
+    // STEP 2: Verify customer exists before proceeding
+    const customer = await this.loadCustomer(validatedInput.customerId);
+
+    // STEP 3: Verify all products exist before any processing
+    const products = await this.loadProducts(validatedInput.items);
+
+    // STEP 4: Verify payment method before creating order
+    this.verifyPaymentMethod(customer);
+
+    // STEP 5: Calculate total (now safe - all data validated)
+    const total = this.calculateTotal(validatedInput.items, products);
+
+    // STEP 6: Verify sufficient inventory before payment
+    await this.verifyInventory(validatedInput.items, products);
+
+    // STEP 7: Process payment before creating order
+    const payment = await this.processPayment(customer, total);
+
+    // STEP 8: Create order only after successful payment
+    const order = await this.createOrder(validatedInput, customer, total, payment);
+
+    // STEP 9: Send confirmation (non-critical, can fail gracefully)
+    await this.sendConfirmation(customer, order);
+
+    return { success: true, orderId: order.id };
+  }
+
+  private validateInput(input: unknown): CreateOrderInput {
+    if (!input || typeof input !== 'object') {
+      throw new ValidationError('Input must be an object', 'input', input);
+    }
+
+    const obj = input as Record<string, unknown>;
+
+    if (!obj.customerId || typeof obj.customerId !== 'string') {
+      throw new ValidationError('customerId is required and must be a string', 'customerId', obj.customerId);
+    }
+
+    if (!Array.isArray(obj.items) || obj.items.length === 0) {
+      throw new ValidationError('items must be a non-empty array', 'items', obj.items);
+    }
+
+    const validatedItems: OrderItemInput[] = [];
+    for (let i = 0; i < obj.items.length; i++) {
+      const item = obj.items[i];
+      if (!item || typeof item !== 'object') {
+        throw new ValidationError(`Item at index ${i} must be an object`, `items[${i}]`, item);
+      }
+
+      const itemObj = item as Record<string, unknown>;
+
+      if (!itemObj.productId || typeof itemObj.productId !== 'string') {
+        throw new ValidationError(
+          `productId is required at index ${i}`,
+          `items[${i}].productId`,
+          itemObj.productId
+        );
+      }
+
+      if (typeof itemObj.quantity !== 'number' || itemObj.quantity < 1) {
+        throw new ValidationError(
+          `quantity must be a positive number at index ${i}`,
+          `items[${i}].quantity`,
+          itemObj.quantity
+        );
+      }
+
+      validatedItems.push({
+        productId: itemObj.productId,
+        quantity: itemObj.quantity
+      });
+    }
+
+    return {
+      customerId: obj.customerId,
+      items: validatedItems
+    };
+  }
+
+  private async loadCustomer(customerId: string): Promise<Customer> {
+    const customer = await this.customerRepo.findById(customerId);
+
+    if (!customer) {
+      throw new NotFoundError('Customer', customerId);
+    }
+
+    if (!customer.isActive) {
+      throw new ValidationError('Customer account is inactive', 'customerId', customerId);
+    }
+
+    return customer;
+  }
+
+  private async loadProducts(items: OrderItemInput[]): Promise<Map<string, Product>> {
+    const productIds = items.map(item => item.productId);
+    const products = await this.productRepo.findByIds(productIds);
+
+    const productMap = new Map<string, Product>();
+    for (const product of products) {
+      productMap.set(product.id, product);
+    }
+
+    // Verify all products were found
+    for (const item of items) {
+      if (!productMap.has(item.productId)) {
+        throw new NotFoundError('Product', item.productId);
+      }
+    }
+
+    return productMap;
+  }
+
+  private verifyPaymentMethod(customer: Customer): void {
+    if (!customer.paymentMethodId) {
+      throw new ValidationError(
+        'Customer has no payment method configured',
+        'paymentMethod',
+        null
+      );
+    }
+  }
+
+  private calculateTotal(items: OrderItemInput[], products: Map<string, Product>): number {
+    return items.reduce((total, item) => {
+      const product = products.get(item.productId)!; // Safe - already validated
+      return total + product.price * item.quantity;
+    }, 0);
+  }
+
+  private async verifyInventory(
+    items: OrderItemInput[],
+    products: Map<string, Product>
+  ): Promise<void> {
+    for (const item of items) {
+      const product = products.get(item.productId)!;
+      if (product.stock < item.quantity) {
+        throw new ValidationError(
+          `Insufficient stock for product ${product.name}. Available: ${product.stock}, Requested: ${item.quantity}`,
+          'quantity',
+          item.quantity
+        );
+      }
+    }
+  }
+
+  private async processPayment(customer: Customer, amount: number): Promise<Payment> {
+    try {
+      return await this.paymentService.charge(customer.paymentMethodId, amount);
+    } catch (error) {
+      throw new PaymentError(
+        `Payment failed: ${error.message}`,
+        error.code || 'UNKNOWN'
+      );
+    }
+  }
+
+  private async createOrder(
+    input: CreateOrderInput,
+    customer: Customer,
+    total: number,
+    payment: Payment
+  ): Promise<Order> {
+    return this.orderRepo.create({
+      customerId: customer.id,
+      items: input.items,
+      total,
+      paymentId: payment.id,
+      status: 'paid'
+    });
+  }
+
+  private async sendConfirmation(customer: Customer, order: Order): Promise<void> {
+    try {
+      await this.emailService.sendOrderConfirmation(customer.email, order);
+    } catch (error) {
+      // Log but don't fail - email is non-critical
+      this.logger.error('Failed to send order confirmation', { orderId: order.id, error });
+    }
+  }
+}
+```
+
+## Why
+
+1. **Clear Error Messages**: When validation fails, you know exactly what's wrong and where.
+
+2. **No Wasted Work**: Invalid requests fail immediately, not after expensive operations.
+
+3. **Data Integrity**: The database never enters an inconsistent state because we validate before mutating.
+
+4. **Debugging**: Stack traces point to the actual problem, not to a downstream symptom.
+
+5. **Predictability**: Either the operation fully succeeds or it cleanly fails with a clear reason.
+
+6. **Security**: Invalid inputs are rejected at the boundary, not passed through the system.
+
+7. **Recovery**: Callers can handle specific error types appropriately (retry, report, fallback).
diff --git a/.agents/skills/clean-code-principles/rules/core-kiss-readability.md b/.agents/skills/clean-code-principles/rules/core-kiss-readability.md
new file mode 100644
index 0000000..c302e61
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-kiss-readability.md
@@ -0,0 +1,202 @@
+---
+id: core-kiss-readability
+title: KISS - Readability
+category: core-principles
+priority: critical
+tags: [KISS, readability, clear-code, maintainability]
+related: [core-kiss-simplicity, solid-srp-function]
+---
+
+# KISS - Readability
+
+Code is read far more often than it is written. Optimize for readability by using clear names, straightforward logic, and avoiding clever tricks that obscure intent.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Clever but cryptic code
+
+// One-liner that's hard to understand
+const r = d.filter(x => x.s === 'a' && x.t > Date.now() - 864e5).reduce((a, x) => ({ ...a, [x.c]: (a[x.c] || 0) + x.v }), {});
+
+// Nested ternaries
+const status = x > 100 ? 'high' : x > 50 ? 'medium' : x > 20 ? 'low' : x > 0 ? 'minimal' : 'none';
+
+// Bitwise operations for boolean logic
+const isValid = !!(flags & 0x1) && !!(flags & 0x2) || !!(flags & 0x4);
+
+// Regex that nobody can read
+const isValidEmail = /^(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$/i.test(email);
+
+// Clever use of || and && for control flow
+user && user.isActive && user.hasPermission('admin') && doAdminStuff() || showError();
+
+// Abusing array methods
+const result = [...Array(10)].map((_, i) => i * 2).filter(Boolean).reduce((a, b) => a + b, 0);
+
+// Short variable names that save typing but cost understanding
+function p(d, o) {
+  return d.map(i => ({ ...i, t: i.t * o.r, s: o.s ? i.s + o.s : i.s })).filter(i => i.t > o.m);
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Clear, self-documenting code
+
+// Break complex operations into named steps
+function getActiveOrdersSummaryByCategory(orders: Order[]): Record<string, number> {
+  const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
+
+  const activeRecentOrders = orders.filter(order =>
+    order.status === 'active' && order.timestamp > oneDayAgo
+  );
+
+  const summaryByCategory: Record<string, number> = {};
+
+  for (const order of activeRecentOrders) {
+    const currentTotal = summaryByCategory[order.category] || 0;
+    summaryByCategory[order.category] = currentTotal + order.value;
+  }
+
+  return summaryByCategory;
+}
+
+// Use clear conditional logic
+function getAlertLevel(value: number): AlertLevel {
+  if (value > 100) {
+    return 'high';
+  }
+  if (value > 50) {
+    return 'medium';
+  }
+  if (value > 20) {
+    return 'low';
+  }
+  if (value > 0) {
+    return 'minimal';
+  }
+  return 'none';
+}
+
+// Use named constants for flags
+const UserFlags = {
+  IS_VERIFIED: 0x1,
+  IS_PREMIUM: 0x2,
+  IS_ADMIN: 0x4
+} as const;
+
+function hasUserFlag(flags: number, flag: number): boolean {
+  return (flags & flag) !== 0;
+}
+
+function isValidPremiumAdmin(flags: number): boolean {
+  const isVerified = hasUserFlag(flags, UserFlags.IS_VERIFIED);
+  const isPremium = hasUserFlag(flags, UserFlags.IS_PREMIUM);
+  const isAdmin = hasUserFlag(flags, UserFlags.IS_ADMIN);
+
+  return (isVerified && isPremium) || isAdmin;
+}
+
+// Use a simple email validation
+function isValidEmail(email: string): boolean {
+  if (!email || email.length > 254) {
+    return false;
+  }
+
+  const atIndex = email.indexOf('@');
+  if (atIndex < 1) {
+    return false;
+  }
+
+  const domain = email.slice(atIndex + 1);
+  if (!domain || !domain.includes('.')) {
+    return false;
+  }
+
+  return true;
+}
+
+// Or use a well-tested library with clear intent
+import { isEmail } from 'validator';
+const isValidEmail = isEmail(email);
+
+// Use explicit control flow
+function handleUserAction(user: User | null): void {
+  if (!user) {
+    showError('User not found');
+    return;
+  }
+
+  if (!user.isActive) {
+    showError('User account is inactive');
+    return;
+  }
+
+  if (!user.hasPermission('admin')) {
+    showError('Admin permission required');
+    return;
+  }
+
+  doAdminStuff();
+}
+
+// Use descriptive variable and function names
+function generateEvenNumbersSum(count: number): number {
+  const evenNumbers: number[] = [];
+
+  for (let i = 0; i < count; i++) {
+    evenNumbers.push(i * 2);
+  }
+
+  const sum = evenNumbers.reduce((total, num) => total + num, 0);
+
+  return sum;
+}
+
+// Use full, descriptive parameter names
+interface PriceAdjustmentOptions {
+  rateMultiplier: number;
+  shippingSurcharge?: number;
+  minimumThreshold: number;
+}
+
+function adjustProductPrices(
+  products: Product[],
+  options: PriceAdjustmentOptions
+): Product[] {
+  return products
+    .map(product => ({
+      ...product,
+      totalPrice: product.basePrice * options.rateMultiplier,
+      shippingCost: options.shippingSurcharge
+        ? product.shippingCost + options.shippingSurcharge
+        : product.shippingCost
+    }))
+    .filter(product => product.totalPrice > options.minimumThreshold);
+}
+
+// Usage is self-documenting
+const adjustedProducts = adjustProductPrices(products, {
+  rateMultiplier: 1.1,
+  shippingSurcharge: 5,
+  minimumThreshold: 20
+});
+```
+
+## Why
+
+1. **Comprehension Speed**: Readable code is understood quickly. Clever code requires deciphering.
+
+2. **Fewer Bugs**: When code clearly expresses intent, mistakes are obvious.
+
+3. **Onboarding**: New team members can contribute faster with readable code.
+
+4. **Code Reviews**: Reviewers can focus on logic, not translation.
+
+5. **Future You**: Code you wrote 6 months ago might as well have been written by someone else.
+
+6. **Maintenance Cost**: Most of a codebase's lifetime is spent in maintenance, not initial development.
+
+7. **Collaboration**: Teams work better when everyone can understand everyone's code.
diff --git a/.agents/skills/clean-code-principles/rules/core-kiss-simplicity.md b/.agents/skills/clean-code-principles/rules/core-kiss-simplicity.md
new file mode 100644
index 0000000..376c846
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-kiss-simplicity.md
@@ -0,0 +1,255 @@
+---
+id: core-kiss-simplicity
+title: KISS - Simplicity
+category: core-principles
+priority: critical
+tags: [KISS, simplicity, over-engineering, maintainability]
+related: [core-kiss-readability, core-yagni-abstractions, solid-srp-function]
+---
+
+# KISS Principle - Simplicity
+
+Keep It Simple, Stupid. Choose the simplest solution that solves the problem. Avoid unnecessary complexity, over-engineering, and clever code that's hard to understand.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Over-engineered solution for a simple problem
+
+// Simple task: Check if a user can access a resource
+// Over-engineered approach with unnecessary abstractions
+
+interface AccessControlStrategy {
+  evaluate(context: AccessContext): AccessDecision;
+}
+
+interface AccessContext {
+  subject: Subject;
+  resource: Resource;
+  action: Action;
+  environment: Environment;
+}
+
+interface Subject {
+  id: string;
+  attributes: Map<string, AttributeValue>;
+}
+
+interface Resource {
+  id: string;
+  type: string;
+  attributes: Map<string, AttributeValue>;
+}
+
+interface Action {
+  id: string;
+  attributes: Map<string, AttributeValue>;
+}
+
+interface Environment {
+  currentTime: Date;
+  ipAddress: string;
+  attributes: Map<string, AttributeValue>;
+}
+
+type AttributeValue = string | number | boolean | string[];
+
+interface AccessDecision {
+  decision: 'permit' | 'deny' | 'indeterminate' | 'not_applicable';
+  obligations?: Obligation[];
+  advice?: Advice[];
+}
+
+interface Obligation {
+  id: string;
+  fulfillOn: 'permit' | 'deny';
+  attributes: Map<string, AttributeValue>;
+}
+
+interface Advice {
+  id: string;
+  appliesTo: 'permit' | 'deny';
+  attributes: Map<string, AttributeValue>;
+}
+
+class AttributeBasedAccessControl {
+  private strategies: AccessControlStrategy[] = [];
+  private combiningAlgorithm: CombiningAlgorithm;
+
+  constructor(combiningAlgorithm: CombiningAlgorithm) {
+    this.combiningAlgorithm = combiningAlgorithm;
+  }
+
+  addStrategy(strategy: AccessControlStrategy): void {
+    this.strategies.push(strategy);
+  }
+
+  evaluate(context: AccessContext): AccessDecision {
+    const decisions = this.strategies.map(s => s.evaluate(context));
+    return this.combiningAlgorithm.combine(decisions);
+  }
+}
+
+// 500+ more lines of abstraction layers...
+
+// Actually usage for a simple check:
+const context: AccessContext = {
+  subject: {
+    id: user.id,
+    attributes: new Map([['role', user.role]])
+  },
+  resource: {
+    id: document.id,
+    type: 'document',
+    attributes: new Map([['ownerId', document.ownerId]])
+  },
+  action: {
+    id: 'read',
+    attributes: new Map()
+  },
+  environment: {
+    currentTime: new Date(),
+    ipAddress: request.ip,
+    attributes: new Map()
+  }
+};
+
+const decision = accessControl.evaluate(context);
+if (decision.decision === 'permit') {
+  // Allow access
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Simple, direct solution
+
+// Simple function that does what's needed
+function canUserAccessDocument(user: User, document: Document, action: 'read' | 'write' | 'delete'): boolean {
+  // Admin can do anything
+  if (user.role === 'admin') {
+    return true;
+  }
+
+  // Owner can do anything with their document
+  if (document.ownerId === user.id) {
+    return true;
+  }
+
+  // Check explicit permissions
+  const permission = document.permissions.find(p => p.userId === user.id);
+  if (!permission) {
+    return false;
+  }
+
+  // Check if permission level is sufficient
+  switch (action) {
+    case 'read':
+      return ['read', 'write', 'admin'].includes(permission.level);
+    case 'write':
+      return ['write', 'admin'].includes(permission.level);
+    case 'delete':
+      return permission.level === 'admin';
+    default:
+      return false;
+  }
+}
+
+// Usage is straightforward
+if (canUserAccessDocument(user, document, 'read')) {
+  // Allow access
+}
+
+// If requirements grow, evolve the solution incrementally
+// Add time-based access when actually needed
+function canUserAccessDocument(
+  user: User,
+  document: Document,
+  action: 'read' | 'write' | 'delete'
+): boolean {
+  // Admin can do anything
+  if (user.role === 'admin') {
+    return true;
+  }
+
+  // Owner can do anything with their document
+  if (document.ownerId === user.id) {
+    return true;
+  }
+
+  // Check explicit permissions
+  const permission = document.permissions.find(p => p.userId === user.id);
+  if (!permission) {
+    return false;
+  }
+
+  // Check expiration (added when actually needed)
+  if (permission.expiresAt && permission.expiresAt < new Date()) {
+    return false;
+  }
+
+  // Check if permission level is sufficient
+  const requiredLevel = getRequiredLevel(action);
+  return hasRequiredLevel(permission.level, requiredLevel);
+}
+
+function getRequiredLevel(action: 'read' | 'write' | 'delete'): PermissionLevel {
+  const levels: Record<string, PermissionLevel> = {
+    read: 'read',
+    write: 'write',
+    delete: 'admin'
+  };
+  return levels[action];
+}
+
+function hasRequiredLevel(userLevel: PermissionLevel, required: PermissionLevel): boolean {
+  const hierarchy: PermissionLevel[] = ['read', 'write', 'admin'];
+  return hierarchy.indexOf(userLevel) >= hierarchy.indexOf(required);
+}
+
+// Still simple, still readable, handles new requirement
+
+// For multiple resources, create focused helper
+class DocumentAccessChecker {
+  canRead(user: User, document: Document): boolean {
+    return canUserAccessDocument(user, document, 'read');
+  }
+
+  canWrite(user: User, document: Document): boolean {
+    return canUserAccessDocument(user, document, 'write');
+  }
+
+  canDelete(user: User, document: Document): boolean {
+    return canUserAccessDocument(user, document, 'delete');
+  }
+
+  // Filter a list of documents to only accessible ones
+  filterReadable(user: User, documents: Document[]): Document[] {
+    return documents.filter(doc => this.canRead(user, doc));
+  }
+}
+
+// Usage remains simple
+const checker = new DocumentAccessChecker();
+if (checker.canRead(user, document)) {
+  // Show document
+}
+const accessibleDocs = checker.filterReadable(user, allDocuments);
+```
+
+## Why
+
+1. **Readability**: Simple code can be understood in seconds. Complex abstractions require studying.
+
+2. **Maintainability**: New developers can work with simple code immediately. Complex frameworks need training.
+
+3. **Debugging**: When something breaks, simple code has obvious failure points.
+
+4. **Performance**: Simple code is often faster - fewer layers, fewer allocations, less indirection.
+
+5. **Time to Market**: Simple solutions are built and shipped faster.
+
+6. **YAGNI Alignment**: The complex solution solves problems you don't have (and may never have).
+
+7. **Incremental Complexity**: Start simple, add complexity only when real requirements demand it. The simple solution can evolve.
diff --git a/.agents/skills/clean-code-principles/rules/core-law-demeter.md b/.agents/skills/clean-code-principles/rules/core-law-demeter.md
new file mode 100644
index 0000000..f844ce1
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-law-demeter.md
@@ -0,0 +1,321 @@
+---
+id: core-law-demeter
+title: Law of Demeter
+category: core-principles
+priority: critical
+tags: [law-of-demeter, coupling, encapsulation]
+related: [core-encapsulation, solid-srp-class, core-separation-concerns]
+---
+
+# Law of Demeter
+
+A method should only talk to its immediate friends, not to strangers. Don't reach through objects to access their internal structure. This reduces coupling and makes code more maintainable.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Reaching through object chains
+
+class Address {
+  street: string;
+  city: string;
+  country: Country;
+}
+
+class Country {
+  name: string;
+  code: string;
+  taxRules: TaxRules;
+}
+
+class TaxRules {
+  vatRate: number;
+  calculateTax(amount: number): number {
+    return amount * this.vatRate;
+  }
+}
+
+class Customer {
+  name: string;
+  address: Address;
+  wallet: Wallet;
+}
+
+class Wallet {
+  balance: number;
+  currency: Currency;
+
+  deduct(amount: number): void {
+    this.balance -= amount;
+  }
+}
+
+class Currency {
+  code: string;
+  exchangeRate: number;
+}
+
+class Order {
+  customer: Customer;
+  items: OrderItem[];
+
+  // Violation: Reaching deep into customer's structure
+  getCustomerCountry(): string {
+    return this.customer.address.country.name; // 4 levels deep!
+  }
+
+  // Violation: Reaching into customer's wallet
+  calculateTax(): number {
+    const amount = this.getTotal();
+    // Reaching through customer -> address -> country -> taxRules
+    return this.customer.address.country.taxRules.calculateTax(amount);
+  }
+
+  // Violation: Manipulating customer's wallet directly
+  processPayment(): void {
+    const total = this.calculateTax() + this.getTotal();
+
+    // Reaching into wallet to check and modify
+    if (this.customer.wallet.balance < total) {
+      throw new Error('Insufficient funds');
+    }
+
+    // Reaching into wallet's currency for conversion
+    const exchangeRate = this.customer.wallet.currency.exchangeRate;
+    const convertedAmount = total * exchangeRate;
+
+    this.customer.wallet.deduct(convertedAmount);
+  }
+
+  getTotal(): number {
+    return this.items.reduce((sum, item) => sum + item.price, 0);
+  }
+}
+
+// Problems with this approach:
+// 1. Order knows too much about Customer's internal structure
+// 2. Changes to Address, Country, or Wallet break Order
+// 3. Hard to test - must mock entire object graph
+// 4. Tight coupling between unrelated classes
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Talk only to immediate friends
+
+class Address {
+  private street: string;
+  private city: string;
+  private country: Country;
+
+  constructor(street: string, city: string, country: Country) {
+    this.street = street;
+    this.city = city;
+    this.country = country;
+  }
+
+  getCountryName(): string {
+    return this.country.getName();
+  }
+
+  calculateTax(amount: number): number {
+    return this.country.calculateTax(amount);
+  }
+}
+
+class Country {
+  private name: string;
+  private code: string;
+  private taxRules: TaxRules;
+
+  constructor(name: string, code: string, taxRules: TaxRules) {
+    this.name = name;
+    this.code = code;
+    this.taxRules = taxRules;
+  }
+
+  getName(): string {
+    return this.name;
+  }
+
+  getCode(): string {
+    return this.code;
+  }
+
+  calculateTax(amount: number): number {
+    return this.taxRules.calculate(amount);
+  }
+}
+
+class TaxRules {
+  private vatRate: number;
+
+  constructor(vatRate: number) {
+    this.vatRate = vatRate;
+  }
+
+  calculate(amount: number): number {
+    return amount * this.vatRate;
+  }
+}
+
+class Wallet {
+  private balance: number;
+  private currency: Currency;
+
+  constructor(balance: number, currency: Currency) {
+    this.balance = balance;
+    this.currency = currency;
+  }
+
+  canAfford(amount: number): boolean {
+    const convertedAmount = this.currency.convert(amount);
+    return this.balance >= convertedAmount;
+  }
+
+  pay(amount: number): PaymentResult {
+    const convertedAmount = this.currency.convert(amount);
+
+    if (!this.canAfford(amount)) {
+      return { success: false, error: 'Insufficient funds' };
+    }
+
+    this.balance -= convertedAmount;
+    return { success: true, amountPaid: convertedAmount };
+  }
+
+  getBalance(): number {
+    return this.balance;
+  }
+}
+
+class Currency {
+  private code: string;
+  private exchangeRate: number;
+
+  constructor(code: string, exchangeRate: number) {
+    this.code = code;
+    this.exchangeRate = exchangeRate;
+  }
+
+  convert(amount: number): number {
+    return amount * this.exchangeRate;
+  }
+}
+
+class Customer {
+  private name: string;
+  private address: Address;
+  private wallet: Wallet;
+
+  constructor(name: string, address: Address, wallet: Wallet) {
+    this.name = name;
+    this.address = address;
+    this.wallet = wallet;
+  }
+
+  getName(): string {
+    return this.name;
+  }
+
+  getCountryName(): string {
+    return this.address.getCountryName();
+  }
+
+  calculateTaxFor(amount: number): number {
+    return this.address.calculateTax(amount);
+  }
+
+  canAfford(amount: number): boolean {
+    return this.wallet.canAfford(amount);
+  }
+
+  pay(amount: number): PaymentResult {
+    return this.wallet.pay(amount);
+  }
+}
+
+class Order {
+  private customer: Customer;
+  private items: OrderItem[];
+
+  constructor(customer: Customer, items: OrderItem[]) {
+    this.customer = customer;
+    this.items = items;
+  }
+
+  // Only talks to immediate friend (customer)
+  getCustomerCountry(): string {
+    return this.customer.getCountryName();
+  }
+
+  getTotal(): number {
+    return this.items.reduce((sum, item) => sum + item.getPrice(), 0);
+  }
+
+  // Asks customer to calculate tax (customer knows how)
+  calculateTax(): number {
+    return this.customer.calculateTaxFor(this.getTotal());
+  }
+
+  getTotalWithTax(): number {
+    return this.getTotal() + this.calculateTax();
+  }
+
+  // Asks customer to pay (customer handles wallet)
+  processPayment(): PaymentResult {
+    const total = this.getTotalWithTax();
+
+    if (!this.customer.canAfford(total)) {
+      return { success: false, error: 'Insufficient funds' };
+    }
+
+    return this.customer.pay(total);
+  }
+}
+
+// Usage
+const order = new Order(customer, items);
+const result = order.processPayment();
+
+if (result.success) {
+  console.log(`Payment successful: ${result.amountPaid}`);
+} else {
+  console.log(`Payment failed: ${result.error}`);
+}
+
+// Testing is now easy - only mock the immediate friend
+describe('Order', () => {
+  it('should process payment through customer', () => {
+    const mockCustomer: Customer = {
+      getCountryName: () => 'USA',
+      calculateTaxFor: (amount: number) => amount * 0.1,
+      canAfford: () => true,
+      pay: jest.fn().mockReturnValue({ success: true, amountPaid: 110 })
+    } as any;
+
+    const order = new Order(mockCustomer, [{ getPrice: () => 100 }]);
+    const result = order.processPayment();
+
+    expect(result.success).toBe(true);
+    expect(mockCustomer.pay).toHaveBeenCalledWith(110);
+  });
+});
+```
+
+## Why
+
+1. **Reduced Coupling**: Order only knows about Customer. Changes to Address, Country, or Wallet don't affect Order.
+
+2. **Encapsulation**: Internal structure is hidden. Customer can change how it stores address without affecting clients.
+
+3. **Easier Testing**: Mock only the immediate friend. No need to construct deep object graphs.
+
+4. **Better Abstraction**: Customer is responsible for customer things. Order doesn't need to know about wallets.
+
+5. **Maintainability**: When requirements change, changes are localized to the responsible class.
+
+6. **Readability**: `customer.calculateTaxFor(amount)` is clearer than `customer.address.country.taxRules.calculateTax(amount)`.
+
+7. **Flexibility**: Can change internal implementations without affecting clients. Customer could switch from wallet to payment service.
diff --git a/.agents/skills/clean-code-principles/rules/core-separation-concerns.md b/.agents/skills/clean-code-principles/rules/core-separation-concerns.md
new file mode 100644
index 0000000..96abbba
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-separation-concerns.md
@@ -0,0 +1,337 @@
+---
+id: core-separation-concerns
+title: Separation of Concerns
+category: core-principles
+priority: critical
+tags: [separation-of-concerns, modularity, cohesion]
+related: [solid-srp-class, solid-srp-function, core-law-demeter]
+---
+
+# Separation of Concerns
+
+Different concerns should be handled by different parts of the system. Each module, class, or function should address a single concern, making the code easier to understand, test, and modify.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Multiple concerns mixed together
+
+class OrderProcessor {
+  async processOrder(orderData: any, request: Request): Promise<Response> {
+    // Concern 1: HTTP request parsing
+    const authHeader = request.headers.get('Authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+    }
+    const token = authHeader.slice(7);
+
+    // Concern 2: Authentication
+    let userId: string;
+    try {
+      const decoded = jwt.verify(token, process.env.JWT_SECRET!) as { userId: string };
+      userId = decoded.userId;
+    } catch {
+      return new Response(JSON.stringify({ error: 'Invalid token' }), { status: 401 });
+    }
+
+    // Concern 3: Validation
+    if (!orderData.items || orderData.items.length === 0) {
+      return new Response(JSON.stringify({ error: 'Order must have items' }), { status: 400 });
+    }
+    for (const item of orderData.items) {
+      if (!item.productId || item.quantity < 1) {
+        return new Response(JSON.stringify({ error: 'Invalid item' }), { status: 400 });
+      }
+    }
+
+    // Concern 4: Database access
+    const connection = await mysql.createConnection(process.env.DATABASE_URL!);
+
+    try {
+      // Concern 5: Business logic - inventory check
+      for (const item of orderData.items) {
+        const [rows] = await connection.execute(
+          'SELECT stock FROM products WHERE id = ?',
+          [item.productId]
+        );
+        if (rows[0].stock < item.quantity) {
+          return new Response(
+            JSON.stringify({ error: `Insufficient stock for ${item.productId}` }),
+            { status: 400 }
+          );
+        }
+      }
+
+      // Concern 6: Business logic - pricing
+      let total = 0;
+      for (const item of orderData.items) {
+        const [rows] = await connection.execute(
+          'SELECT price FROM products WHERE id = ?',
+          [item.productId]
+        );
+        total += rows[0].price * item.quantity;
+      }
+
+      // Concern 7: Business logic - create order
+      const orderId = crypto.randomUUID();
+      await connection.execute(
+        'INSERT INTO orders (id, user_id, total, status) VALUES (?, ?, ?, ?)',
+        [orderId, userId, total, 'pending']
+      );
+
+      // Concern 8: Payment processing
+      const stripe = new Stripe(process.env.STRIPE_KEY!);
+      const paymentIntent = await stripe.paymentIntents.create({
+        amount: Math.round(total * 100),
+        currency: 'usd',
+        customer: userId
+      });
+
+      // Concern 9: Inventory update
+      for (const item of orderData.items) {
+        await connection.execute(
+          'UPDATE products SET stock = stock - ? WHERE id = ?',
+          [item.quantity, item.productId]
+        );
+      }
+
+      // Concern 10: Notification
+      const transporter = nodemailer.createTransport({ /* SMTP config */ });
+      await transporter.sendMail({
+        to: orderData.email,
+        subject: 'Order Confirmation',
+        html: `<h1>Order ${orderId} confirmed</h1><p>Total: $${total}</p>`
+      });
+
+      // Concern 11: Logging
+      console.log(`Order ${orderId} created for user ${userId}`);
+
+      // Concern 12: HTTP response formatting
+      return new Response(
+        JSON.stringify({ orderId, total, paymentIntentId: paymentIntent.id }),
+        { status: 201, headers: { 'Content-Type': 'application/json' } }
+      );
+
+    } finally {
+      await connection.end();
+    }
+  }
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Each concern in its own module
+
+// Concern: HTTP handling
+class OrderController {
+  constructor(private orderService: OrderService) {}
+
+  async createOrder(req: Request, res: Response): Promise<void> {
+    try {
+      const userId = req.user.id; // Auth middleware already handled this
+      const orderData = req.body; // Validation middleware already validated
+
+      const order = await this.orderService.createOrder(userId, orderData);
+
+      res.status(201).json({
+        orderId: order.id,
+        total: order.total,
+        status: order.status
+      });
+    } catch (error) {
+      if (error instanceof InsufficientStockError) {
+        res.status(400).json({ error: error.message });
+      } else if (error instanceof PaymentFailedError) {
+        res.status(402).json({ error: 'Payment failed' });
+      } else {
+        throw error; // Let error middleware handle
+      }
+    }
+  }
+}
+
+// Concern: Authentication (middleware)
+class AuthMiddleware {
+  constructor(private authService: AuthService) {}
+
+  async handle(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const token = this.extractToken(req);
+    if (!token) {
+      res.status(401).json({ error: 'Unauthorized' });
+      return;
+    }
+
+    const user = await this.authService.validateToken(token);
+    if (!user) {
+      res.status(401).json({ error: 'Invalid token' });
+      return;
+    }
+
+    req.user = user;
+    next();
+  }
+
+  private extractToken(req: Request): string | null {
+    const header = req.headers.authorization;
+    return header?.startsWith('Bearer ') ? header.slice(7) : null;
+  }
+}
+
+// Concern: Validation (separate validator)
+class OrderValidator {
+  validate(data: unknown): CreateOrderData {
+    const schema = z.object({
+      items: z.array(z.object({
+        productId: z.string().uuid(),
+        quantity: z.number().int().positive()
+      })).min(1)
+    });
+
+    return schema.parse(data);
+  }
+}
+
+// Concern: Business logic orchestration
+class OrderService {
+  constructor(
+    private orderRepository: OrderRepository,
+    private inventoryService: InventoryService,
+    private pricingService: PricingService,
+    private paymentService: PaymentService,
+    private notificationService: NotificationService,
+    private logger: Logger
+  ) {}
+
+  async createOrder(userId: string, data: CreateOrderData): Promise<Order> {
+    // Check inventory
+    await this.inventoryService.checkAvailability(data.items);
+
+    // Calculate pricing
+    const pricing = await this.pricingService.calculateTotal(data.items);
+
+    // Create order
+    const order = await this.orderRepository.create({
+      userId,
+      items: data.items,
+      total: pricing.total,
+      status: 'pending'
+    });
+
+    // Process payment
+    await this.paymentService.charge(userId, pricing.total, order.id);
+
+    // Reserve inventory
+    await this.inventoryService.reserve(data.items);
+
+    // Send confirmation
+    await this.notificationService.sendOrderConfirmation(order);
+
+    // Log
+    this.logger.info('Order created', { orderId: order.id, userId });
+
+    return order;
+  }
+}
+
+// Concern: Inventory management
+class InventoryService {
+  constructor(private productRepository: ProductRepository) {}
+
+  async checkAvailability(items: OrderItem[]): Promise<void> {
+    for (const item of items) {
+      const product = await this.productRepository.findById(item.productId);
+      if (product.stock < item.quantity) {
+        throw new InsufficientStockError(item.productId, product.stock, item.quantity);
+      }
+    }
+  }
+
+  async reserve(items: OrderItem[]): Promise<void> {
+    for (const item of items) {
+      await this.productRepository.decrementStock(item.productId, item.quantity);
+    }
+  }
+}
+
+// Concern: Pricing calculation
+class PricingService {
+  constructor(private productRepository: ProductRepository) {}
+
+  async calculateTotal(items: OrderItem[]): Promise<PricingResult> {
+    let subtotal = 0;
+
+    for (const item of items) {
+      const product = await this.productRepository.findById(item.productId);
+      subtotal += product.price * item.quantity;
+    }
+
+    const tax = this.calculateTax(subtotal);
+    const total = subtotal + tax;
+
+    return { subtotal, tax, total };
+  }
+
+  private calculateTax(amount: number): number {
+    return amount * 0.1; // 10% tax
+  }
+}
+
+// Concern: Payment processing
+class PaymentService {
+  constructor(private stripeClient: Stripe) {}
+
+  async charge(userId: string, amount: number, orderId: string): Promise<Payment> {
+    const intent = await this.stripeClient.paymentIntents.create({
+      amount: Math.round(amount * 100),
+      currency: 'usd',
+      metadata: { orderId }
+    });
+
+    return { id: intent.id, status: 'pending' };
+  }
+}
+
+// Concern: Notifications
+class NotificationService {
+  constructor(private emailService: EmailService) {}
+
+  async sendOrderConfirmation(order: Order): Promise<void> {
+    await this.emailService.send({
+      to: order.userEmail,
+      template: 'order-confirmation',
+      data: { orderId: order.id, total: order.total }
+    });
+  }
+}
+
+// Concern: Data access
+class OrderRepository {
+  constructor(private db: Database) {}
+
+  async create(data: CreateOrderInput): Promise<Order> {
+    return this.db.orders.create({ data });
+  }
+
+  async findById(id: string): Promise<Order | null> {
+    return this.db.orders.findUnique({ where: { id } });
+  }
+}
+```
+
+## Why
+
+1. **Understandability**: Each module has one job. Easy to understand what it does.
+
+2. **Testability**: Test inventory logic without payment, test pricing without database.
+
+3. **Reusability**: `PricingService` can be used for quotes, carts, or invoices.
+
+4. **Maintainability**: Change email provider? Only touch `EmailService`.
+
+5. **Team Scaling**: Different developers can work on different concerns without conflicts.
+
+6. **Flexibility**: Swap Stripe for another payment provider by changing only `PaymentService`.
+
+7. **Debugging**: Error in pricing? Look at `PricingService`. Clear boundaries help locate issues.
diff --git a/.agents/skills/clean-code-principles/rules/core-yagni-abstractions.md b/.agents/skills/clean-code-principles/rules/core-yagni-abstractions.md
new file mode 100644
index 0000000..ecd5c15
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-yagni-abstractions.md
@@ -0,0 +1,252 @@
+---
+id: core-yagni-abstractions
+title: YAGNI - Abstractions
+category: core-principles
+priority: critical
+tags: [YAGNI, premature-abstraction, simplicity]
+related: [core-yagni-features, core-kiss-simplicity, solid-ocp-abstraction]
+---
+
+# YAGNI Principle - Abstractions
+
+Don't create abstractions until you have concrete evidence they're needed. Premature abstraction leads to wrong abstractions that are worse than no abstraction.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Creating abstractions before understanding the problem
+
+// Task: Send an email notification
+// Over-abstracted solution based on imagined future needs
+
+// "We might need different notification channels someday"
+interface NotificationChannel {
+  send(notification: Notification): Promise<void>;
+  getCapabilities(): ChannelCapabilities;
+  isAvailable(): Promise<boolean>;
+}
+
+// "We might need different notification types"
+interface Notification {
+  id: string;
+  type: NotificationType;
+  priority: NotificationPriority;
+  payload: NotificationPayload;
+  metadata: NotificationMetadata;
+}
+
+// "We might need complex routing logic"
+interface NotificationRouter {
+  route(notification: Notification): Promise<NotificationChannel[]>;
+  registerChannel(channel: NotificationChannel): void;
+  setRoutingRules(rules: RoutingRule[]): void;
+}
+
+// "We might need to transform notifications per channel"
+interface NotificationTransformer {
+  transform(notification: Notification, channel: NotificationChannel): TransformedNotification;
+}
+
+// "We might need retry logic"
+interface NotificationRetryPolicy {
+  shouldRetry(attempt: number, error: Error): boolean;
+  getDelay(attempt: number): number;
+}
+
+// "We might need to track delivery"
+interface NotificationTracker {
+  trackSent(notification: Notification, channel: NotificationChannel): Promise<void>;
+  trackDelivered(notificationId: string): Promise<void>;
+  trackFailed(notificationId: string, error: Error): Promise<void>;
+}
+
+// "We might need a notification queue"
+interface NotificationQueue {
+  enqueue(notification: Notification): Promise<void>;
+  process(): Promise<void>;
+  getStatus(notificationId: string): Promise<QueueStatus>;
+}
+
+// Orchestrator that ties it all together
+class NotificationOrchestrator {
+  constructor(
+    private router: NotificationRouter,
+    private transformer: NotificationTransformer,
+    private retryPolicy: NotificationRetryPolicy,
+    private tracker: NotificationTracker,
+    private queue: NotificationQueue
+  ) {}
+
+  async notify(notification: Notification): Promise<void> {
+    await this.queue.enqueue(notification);
+    // 200+ lines of orchestration logic
+  }
+}
+
+// But all we actually needed was:
+// Send an email when a user registers
+
+// Result: 1000+ lines of abstraction, weeks of work, for sending one email
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Start concrete, abstract when patterns emerge
+
+// Task: Send an email notification
+// Simple, direct solution
+
+interface EmailOptions {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+class EmailService {
+  constructor(private smtpClient: SmtpClient) {}
+
+  async send(options: EmailOptions): Promise<void> {
+    await this.smtpClient.send({
+      from: 'noreply@example.com',
+      to: options.to,
+      subject: options.subject,
+      html: options.body
+    });
+  }
+}
+
+// Usage
+const emailService = new EmailService(smtpClient);
+await emailService.send({
+  to: user.email,
+  subject: 'Welcome!',
+  body: '<h1>Welcome to our app!</h1>'
+});
+
+// Later, when we actually need SMS (not "might need"):
+class SmsService {
+  constructor(private twilioClient: TwilioClient) {}
+
+  async send(phone: string, message: string): Promise<void> {
+    await this.twilioClient.messages.create({
+      to: phone,
+      from: process.env.TWILIO_NUMBER,
+      body: message
+    });
+  }
+}
+
+// Now we have TWO concrete implementations
+// We can see what they have in common
+
+// Abstract AFTER seeing the pattern (Rule of Three)
+// After email, SMS, and push notifications exist:
+
+interface NotificationSender {
+  send(recipient: string, message: NotificationMessage): Promise<void>;
+}
+
+interface NotificationMessage {
+  subject?: string;
+  body: string;
+}
+
+class EmailNotificationSender implements NotificationSender {
+  constructor(private emailService: EmailService) {}
+
+  async send(recipient: string, message: NotificationMessage): Promise<void> {
+    await this.emailService.send({
+      to: recipient,
+      subject: message.subject || 'Notification',
+      body: message.body
+    });
+  }
+}
+
+class SmsNotificationSender implements NotificationSender {
+  constructor(private smsService: SmsService) {}
+
+  async send(recipient: string, message: NotificationMessage): Promise<void> {
+    // SMS doesn't support subject, so we just use body
+    await this.smsService.send(recipient, message.body);
+  }
+}
+
+class PushNotificationSender implements NotificationSender {
+  constructor(private pushService: PushService) {}
+
+  async send(recipient: string, message: NotificationMessage): Promise<void> {
+    await this.pushService.send(recipient, {
+      title: message.subject,
+      body: message.body
+    });
+  }
+}
+
+// Simple notification service that uses the abstraction
+class NotificationService {
+  constructor(private senders: Map<string, NotificationSender>) {}
+
+  async notify(
+    channel: 'email' | 'sms' | 'push',
+    recipient: string,
+    message: NotificationMessage
+  ): Promise<void> {
+    const sender = this.senders.get(channel);
+    if (!sender) {
+      throw new Error(`Unknown notification channel: ${channel}`);
+    }
+    await sender.send(recipient, message);
+  }
+}
+
+// The abstraction fits because it was derived from concrete implementations
+// It's minimal - just what's needed, nothing speculative
+
+// If we later need retry logic, we add it when we have concrete requirements:
+class RetryingNotificationSender implements NotificationSender {
+  constructor(
+    private sender: NotificationSender,
+    private maxAttempts: number = 3
+  ) {}
+
+  async send(recipient: string, message: NotificationMessage): Promise<void> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      try {
+        await this.sender.send(recipient, message);
+        return;
+      } catch (error) {
+        lastError = error as Error;
+        if (attempt < this.maxAttempts) {
+          await this.delay(attempt * 1000);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+## Why
+
+1. **Wrong Abstractions Are Costly**: Premature abstractions are often wrong because you don't understand the problem yet. Wrong abstractions are harder to change than no abstractions.
+
+2. **Rule of Three**: Wait until you have three concrete examples before abstracting. Two is often coincidence; three reveals the pattern.
+
+3. **Duplication Is Cheaper Than Wrong Abstraction**: It's easier to extract a correct abstraction from duplicated code than to fix a wrong abstraction.
+
+4. **Context Matters**: Abstractions made with real requirements fit better than those made speculatively.
+
+5. **Simplicity**: Concrete code is simpler to understand, debug, and modify.
+
+6. **Evolutionary Design**: Let the design emerge from actual needs rather than imagined ones.
+
+7. **Time Value**: The time spent on speculative abstractions could be spent on real features.
diff --git a/.agents/skills/clean-code-principles/rules/core-yagni-features.md b/.agents/skills/clean-code-principles/rules/core-yagni-features.md
new file mode 100644
index 0000000..acac28c
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/core-yagni-features.md
@@ -0,0 +1,205 @@
+---
+id: core-yagni-features
+title: YAGNI - Features
+category: core-principles
+priority: critical
+tags: [YAGNI, speculative-features, lean-development]
+related: [core-yagni-abstractions, core-kiss-simplicity]
+---
+
+# YAGNI Principle - Features
+
+You Aren't Gonna Need It. Don't implement features until they are actually required. Building speculative features wastes time and adds unnecessary complexity.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Building features "just in case"
+
+// Task: Create a simple user registration
+// Over-built solution with features nobody asked for
+
+interface User {
+  id: string;
+  email: string;
+  password: string;
+  // Speculative fields - nobody asked for these
+  phone?: string;
+  address?: Address;
+  preferences?: UserPreferences;
+  socialProfiles?: SocialProfile[];
+  twoFactorEnabled?: boolean;
+  twoFactorSecret?: string;
+  backupCodes?: string[];
+  apiKeys?: ApiKey[];
+  loginHistory?: LoginAttempt[];
+  sessions?: Session[];
+  subscriptionTier?: 'free' | 'basic' | 'premium' | 'enterprise';
+  billingInfo?: BillingInfo;
+  teamMemberships?: TeamMembership[];
+  referralCode?: string;
+  referredBy?: string;
+  loyaltyPoints?: number;
+}
+
+class UserService {
+  // Basic registration - actually needed
+  async register(email: string, password: string): Promise<User> {
+    // ...
+  }
+
+  // These were built "just in case" - never used
+
+  async enableTwoFactor(userId: string): Promise<TwoFactorSetup> {
+    // 200 lines of 2FA implementation
+    // Product never asked for this feature
+  }
+
+  async generateApiKey(userId: string, scopes: string[]): Promise<ApiKey> {
+    // 150 lines of API key management
+    // No API exists for external developers
+  }
+
+  async trackLoginAttempt(userId: string, success: boolean, ip: string): Promise<void> {
+    // 100 lines of login tracking
+    // No dashboard to view this data
+  }
+
+  async manageSessions(userId: string): Promise<Session[]> {
+    // 180 lines of session management
+    // Users can't actually see or manage sessions
+  }
+
+  async upgradeSubscription(userId: string, tier: string): Promise<void> {
+    // 300 lines of subscription logic
+    // App is free, no paid tiers planned
+  }
+
+  async processReferral(referrerCode: string, newUserId: string): Promise<void> {
+    // 120 lines of referral logic
+    // Marketing hasn't planned a referral program
+  }
+
+  async awardLoyaltyPoints(userId: string, action: string): Promise<void> {
+    // 100 lines of loyalty point logic
+    // No loyalty program exists
+  }
+
+  // 1500+ lines of code for features that may never be used
+}
+
+// Result:
+// - 3 weeks spent building speculative features
+// - 1500+ lines to maintain
+// - Bugs introduced in code that's never executed
+// - Actual requirements delayed
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Build only what's needed now
+
+// Task: Create a simple user registration
+// Focused solution that meets actual requirements
+
+interface User {
+  id: string;
+  email: string;
+  passwordHash: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface CreateUserData {
+  email: string;
+  password: string;
+}
+
+class UserService {
+  constructor(
+    private userRepository: UserRepository,
+    private passwordHasher: PasswordHasher,
+    private emailService: EmailService
+  ) {}
+
+  async register(data: CreateUserData): Promise<User> {
+    // Validate email
+    const existingUser = await this.userRepository.findByEmail(data.email);
+    if (existingUser) {
+      throw new UserAlreadyExistsError(data.email);
+    }
+
+    // Create user
+    const passwordHash = await this.passwordHasher.hash(data.password);
+    const user = await this.userRepository.create({
+      email: data.email,
+      passwordHash,
+      createdAt: new Date(),
+      updatedAt: new Date()
+    });
+
+    // Send welcome email
+    await this.emailService.sendWelcome(user.email);
+
+    return user;
+  }
+
+  async findById(id: string): Promise<User | null> {
+    return this.userRepository.findById(id);
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.userRepository.findByEmail(email);
+  }
+}
+
+// Result:
+// - Built in 2 days
+// - ~100 lines of focused code
+// - Easy to understand and maintain
+// - Shipped to users quickly
+// - Can add features when actually needed
+
+// When 2FA is actually requested (6 months later):
+// Add it then with full context of actual requirements
+
+interface TwoFactorService {
+  enable(userId: string): Promise<TwoFactorSetup>;
+  verify(userId: string, code: string): Promise<boolean>;
+  disable(userId: string): Promise<void>;
+}
+
+// When subscription tiers are planned (1 year later):
+// Add with actual business requirements, pricing, and features defined
+
+interface SubscriptionService {
+  getCurrentPlan(userId: string): Promise<Plan>;
+  upgrade(userId: string, planId: string): Promise<void>;
+  downgrade(userId: string, planId: string): Promise<void>;
+  cancel(userId: string): Promise<void>;
+}
+
+// Benefits of waiting:
+// 1. Requirements are clearer
+// 2. You know the actual use cases
+// 3. Technology may have improved
+// 4. You didn't maintain unused code for months
+// 5. You might not need it at all (50%+ of speculative features are never used)
+```
+
+## Why
+
+1. **Waste Prevention**: Speculative features consume development time that could be spent on actual needs.
+
+2. **Maintenance Burden**: Every line of code must be maintained, tested, and understood - even unused code.
+
+3. **Complexity Cost**: Unused features add cognitive load when reading and modifying the codebase.
+
+4. **Requirements Clarity**: Future requirements are clearer when you're actually implementing them.
+
+5. **Flexibility**: Code without speculative features is easier to refactor and evolve.
+
+6. **Faster Delivery**: Ship what's needed now, iterate based on real feedback.
+
+7. **Better Design**: Features designed with real requirements and user feedback are better than guessed features.
diff --git a/.agents/skills/clean-code-principles/rules/pattern-repository.md b/.agents/skills/clean-code-principles/rules/pattern-repository.md
new file mode 100644
index 0000000..63ef16e
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/pattern-repository.md
@@ -0,0 +1,359 @@
+---
+id: pattern-repository
+title: Design Pattern - Repository
+category: design-patterns
+priority: high
+tags: [design-patterns, repository, data-access, separation-of-concerns]
+related: [solid-dip-abstractions, solid-srp-class, core-separation-concerns]
+---
+
+# Repository Pattern
+
+The Repository pattern abstracts data persistence, providing a collection-like interface for accessing domain objects. It separates business logic from data access, makes code testable, and allows swapping storage implementations without changing application code.
+
+## Bad Example
+
+```typescript
+// ❌ Data access mixed with business logic
+class OrderService {
+  async createOrder(userId: string, items: CartItem[]) {
+    // Business logic
+    const total = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+
+    // Direct database access - tightly coupled
+    const result = await pool.query(
+      `INSERT INTO orders (user_id, total, status, created_at)
+       VALUES ($1, $2, $3, NOW()) RETURNING *`,
+      [userId, total, 'pending']
+    );
+
+    const orderId = result.rows[0].id;
+
+    // More SQL scattered in business logic
+    for (const item of items) {
+      await pool.query(
+        `INSERT INTO order_items (order_id, product_id, quantity, price)
+         VALUES ($1, $2, $3, $4)`,
+        [orderId, item.productId, item.quantity, item.price]
+      );
+    }
+
+    return result.rows[0];
+  }
+
+  async getOrdersByUser(userId: string) {
+    // SQL everywhere
+    const result = await pool.query(
+      `SELECT o.*, json_agg(oi.*) as items
+       FROM orders o
+       LEFT JOIN order_items oi ON o.id = oi.order_id
+       WHERE o.user_id = $1
+       GROUP BY o.id`,
+      [userId]
+    );
+    return result.rows;
+  }
+}
+```
+
+**Problems:**
+- Business logic mixed with SQL
+- Hard to test without real database
+- Changing database requires rewriting service
+- SQL scattered across codebase
+
+## Good Example
+
+### Define Repository Interface
+
+```typescript
+// ✅ Repository interface - contract for data access
+interface OrderRepository {
+  find(id: string): Promise<Order | null>;
+  findByUser(userId: string): Promise<Order[]>;
+  findByStatus(status: OrderStatus): Promise<Order[]>;
+  save(order: Order): Promise<Order>;
+  delete(id: string): Promise<void>;
+}
+
+interface OrderItemRepository {
+  findByOrder(orderId: string): Promise<OrderItem[]>;
+  saveMany(items: OrderItem[]): Promise<OrderItem[]>;
+  deleteByOrder(orderId: string): Promise<void>;
+}
+```
+
+### Implement Repository
+
+```typescript
+// ✅ PostgreSQL implementation
+class PostgresOrderRepository implements OrderRepository {
+  constructor(private db: Pool) {}
+
+  async find(id: string): Promise<Order | null> {
+    const result = await this.db.query(
+      'SELECT * FROM orders WHERE id = $1',
+      [id]
+    );
+    return result.rows[0] ? this.mapToOrder(result.rows[0]) : null;
+  }
+
+  async findByUser(userId: string): Promise<Order[]> {
+    const result = await this.db.query(
+      'SELECT * FROM orders WHERE user_id = $1 ORDER BY created_at DESC',
+      [userId]
+    );
+    return result.rows.map(this.mapToOrder);
+  }
+
+  async findByStatus(status: OrderStatus): Promise<Order[]> {
+    const result = await this.db.query(
+      'SELECT * FROM orders WHERE status = $1',
+      [status]
+    );
+    return result.rows.map(this.mapToOrder);
+  }
+
+  async save(order: Order): Promise<Order> {
+    if (order.id) {
+      return this.update(order);
+    }
+    return this.insert(order);
+  }
+
+  private async insert(order: Order): Promise<Order> {
+    const result = await this.db.query(
+      `INSERT INTO orders (user_id, total, status, created_at)
+       VALUES ($1, $2, $3, NOW()) RETURNING *`,
+      [order.userId, order.total, order.status]
+    );
+    return this.mapToOrder(result.rows[0]);
+  }
+
+  private async update(order: Order): Promise<Order> {
+    const result = await this.db.query(
+      `UPDATE orders SET total = $1, status = $2, updated_at = NOW()
+       WHERE id = $3 RETURNING *`,
+      [order.total, order.status, order.id]
+    );
+    return this.mapToOrder(result.rows[0]);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.db.query('DELETE FROM orders WHERE id = $1', [id]);
+  }
+
+  private mapToOrder(row: any): Order {
+    return new Order({
+      id: row.id,
+      userId: row.user_id,
+      total: parseFloat(row.total),
+      status: row.status as OrderStatus,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    });
+  }
+}
+```
+
+### Clean Service Layer
+
+```typescript
+// ✅ Service focuses on business logic only
+class OrderService {
+  constructor(
+    private orderRepository: OrderRepository,
+    private orderItemRepository: OrderItemRepository,
+    private productRepository: ProductRepository,
+  ) {}
+
+  async createOrder(userId: string, items: CartItem[]): Promise<Order> {
+    // Pure business logic
+    const total = this.calculateTotal(items);
+
+    const order = new Order({
+      userId,
+      total,
+      status: OrderStatus.Pending,
+    });
+
+    // Repository handles persistence
+    const savedOrder = await this.orderRepository.save(order);
+
+    const orderItems = items.map(item => new OrderItem({
+      orderId: savedOrder.id,
+      productId: item.productId,
+      quantity: item.quantity,
+      price: item.price,
+    }));
+
+    await this.orderItemRepository.saveMany(orderItems);
+
+    return savedOrder;
+  }
+
+  async cancelOrder(orderId: string): Promise<Order> {
+    const order = await this.orderRepository.find(orderId);
+
+    if (!order) {
+      throw new OrderNotFoundException(orderId);
+    }
+
+    if (!order.canBeCancelled()) {
+      throw new InvalidOrderStateException('Order cannot be cancelled');
+    }
+
+    order.cancel();
+    return this.orderRepository.save(order);
+  }
+
+  private calculateTotal(items: CartItem[]): number {
+    return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  }
+}
+```
+
+### In-Memory Repository for Testing
+
+```typescript
+// ✅ In-memory implementation for tests
+class InMemoryOrderRepository implements OrderRepository {
+  private orders: Map<string, Order> = new Map();
+  private idCounter = 1;
+
+  async find(id: string): Promise<Order | null> {
+    return this.orders.get(id) ?? null;
+  }
+
+  async findByUser(userId: string): Promise<Order[]> {
+    return Array.from(this.orders.values())
+      .filter(order => order.userId === userId);
+  }
+
+  async findByStatus(status: OrderStatus): Promise<Order[]> {
+    return Array.from(this.orders.values())
+      .filter(order => order.status === status);
+  }
+
+  async save(order: Order): Promise<Order> {
+    if (!order.id) {
+      order.id = String(this.idCounter++);
+    }
+    this.orders.set(order.id, order);
+    return order;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.orders.delete(id);
+  }
+
+  // Test helper methods
+  clear(): void {
+    this.orders.clear();
+  }
+
+  seed(orders: Order[]): void {
+    orders.forEach(order => this.orders.set(order.id, order));
+  }
+}
+```
+
+### Easy Testing
+
+```typescript
+// ✅ Unit tests without database
+describe('OrderService', () => {
+  let orderService: OrderService;
+  let orderRepository: InMemoryOrderRepository;
+  let orderItemRepository: InMemoryOrderItemRepository;
+
+  beforeEach(() => {
+    orderRepository = new InMemoryOrderRepository();
+    orderItemRepository = new InMemoryOrderItemRepository();
+    orderService = new OrderService(
+      orderRepository,
+      orderItemRepository,
+      new InMemoryProductRepository(),
+    );
+  });
+
+  it('creates order with calculated total', async () => {
+    const items = [
+      { productId: '1', quantity: 2, price: 10 },
+      { productId: '2', quantity: 1, price: 25 },
+    ];
+
+    const order = await orderService.createOrder('user-1', items);
+
+    expect(order.total).toBe(45);
+    expect(order.status).toBe(OrderStatus.Pending);
+  });
+
+  it('cancels pending order', async () => {
+    orderRepository.seed([
+      new Order({ id: '1', userId: 'user-1', status: OrderStatus.Pending }),
+    ]);
+
+    const order = await orderService.cancelOrder('1');
+
+    expect(order.status).toBe(OrderStatus.Cancelled);
+  });
+
+  it('throws when cancelling shipped order', async () => {
+    orderRepository.seed([
+      new Order({ id: '1', userId: 'user-1', status: OrderStatus.Shipped }),
+    ]);
+
+    await expect(orderService.cancelOrder('1'))
+      .rejects.toThrow(InvalidOrderStateException);
+  });
+});
+```
+
+### Generic Repository Base
+
+```typescript
+// ✅ Generic base for common operations
+interface Repository<T, ID> {
+  find(id: ID): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  save(entity: T): Promise<T>;
+  delete(id: ID): Promise<void>;
+  exists(id: ID): Promise<boolean>;
+}
+
+abstract class BasePostgresRepository<T, ID> implements Repository<T, ID> {
+  constructor(
+    protected db: Pool,
+    protected tableName: string,
+  ) {}
+
+  async find(id: ID): Promise<T | null> {
+    const result = await this.db.query(
+      `SELECT * FROM ${this.tableName} WHERE id = $1`,
+      [id]
+    );
+    return result.rows[0] ? this.mapToEntity(result.rows[0]) : null;
+  }
+
+  async exists(id: ID): Promise<boolean> {
+    const result = await this.db.query(
+      `SELECT 1 FROM ${this.tableName} WHERE id = $1`,
+      [id]
+    );
+    return result.rows.length > 0;
+  }
+
+  protected abstract mapToEntity(row: any): T;
+}
+```
+
+## Why
+
+- Separation of concerns
+- Business logic free of persistence details
+- Easy to test with in-memory implementations
+- Swap databases without changing services
+- Centralized query logic
+- Consistent data access patterns
+- Single place to add caching, logging
diff --git a/.agents/skills/clean-code-principles/rules/solid-dip-abstractions.md b/.agents/skills/clean-code-principles/rules/solid-dip-abstractions.md
new file mode 100644
index 0000000..feb7eaf
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-dip-abstractions.md
@@ -0,0 +1,336 @@
+---
+id: solid-dip-abstractions
+title: SOLID - Dependency Inversion (Abstractions)
+category: solid-principles
+priority: critical
+tags: [SOLID, DIP, dependency-inversion, abstractions]
+related: [solid-dip-injection, solid-ocp-abstraction, pattern-repository]
+---
+
+# Dependency Inversion Principle - Depend on Abstractions
+
+High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details; details should depend on abstractions.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: High-level module depends on low-level implementation details
+
+// Low-level modules (concrete implementations)
+class MySQLDatabase {
+  connect(): void {
+    console.log('Connecting to MySQL...');
+  }
+
+  query(sql: string): any[] {
+    console.log(`Executing MySQL query: ${sql}`);
+    return [];
+  }
+
+  close(): void {
+    console.log('Closing MySQL connection');
+  }
+}
+
+class SmtpEmailSender {
+  send(to: string, subject: string, body: string): void {
+    console.log(`Sending SMTP email to ${to}`);
+  }
+}
+
+class StripePaymentGateway {
+  charge(amount: number, cardToken: string): string {
+    console.log(`Charging $${amount} via Stripe`);
+    return 'stripe_txn_123';
+  }
+}
+
+// High-level module directly depends on low-level implementations
+class OrderService {
+  private database: MySQLDatabase;
+  private emailSender: SmtpEmailSender;
+  private paymentGateway: StripePaymentGateway;
+
+  constructor() {
+    // Direct instantiation creates tight coupling
+    this.database = new MySQLDatabase();
+    this.emailSender = new SmtpEmailSender();
+    this.paymentGateway = new StripePaymentGateway();
+  }
+
+  async createOrder(orderData: OrderData): Promise<Order> {
+    this.database.connect();
+
+    // MySQL-specific query
+    const result = this.database.query(
+      `INSERT INTO orders (customer_id, total) VALUES (${orderData.customerId}, ${orderData.total})`
+    );
+
+    // Stripe-specific charging
+    const txnId = this.paymentGateway.charge(orderData.total, orderData.cardToken);
+
+    // SMTP-specific sending
+    this.emailSender.send(
+      orderData.customerEmail,
+      'Order Confirmation',
+      `Your order has been placed. Transaction: ${txnId}`
+    );
+
+    this.database.close();
+
+    return { id: 'order_1', ...orderData };
+  }
+}
+
+// Problems:
+// 1. Cannot switch to PostgreSQL without modifying OrderService
+// 2. Cannot use SendGrid for emails without modifying OrderService
+// 3. Cannot test without real MySQL, SMTP, and Stripe
+// 4. OrderService knows implementation details it shouldn't
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Depend on abstractions, not concretions
+
+// Abstractions (interfaces) - owned by the high-level module
+interface Database {
+  connect(): Promise<void>;
+  query<T>(query: QueryBuilder): Promise<T[]>;
+  execute(command: Command): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+interface QueryBuilder {
+  table: string;
+  select?: string[];
+  where?: Record<string, any>;
+  orderBy?: string;
+  limit?: number;
+}
+
+interface Command {
+  table: string;
+  operation: 'insert' | 'update' | 'delete';
+  data?: Record<string, any>;
+  where?: Record<string, any>;
+}
+
+interface EmailSender {
+  send(options: EmailOptions): Promise<void>;
+}
+
+interface EmailOptions {
+  to: string;
+  subject: string;
+  body: string;
+  html?: string;
+}
+
+interface PaymentGateway {
+  charge(request: ChargeRequest): Promise<ChargeResult>;
+  refund(transactionId: string, amount?: number): Promise<RefundResult>;
+}
+
+interface ChargeRequest {
+  amount: number;
+  currency: string;
+  paymentMethodId: string;
+  metadata?: Record<string, string>;
+}
+
+interface ChargeResult {
+  transactionId: string;
+  status: 'success' | 'pending' | 'failed';
+  amount: number;
+}
+
+// High-level module depends only on abstractions
+class OrderService {
+  constructor(
+    private database: Database,
+    private emailSender: EmailSender,
+    private paymentGateway: PaymentGateway
+  ) {}
+
+  async createOrder(orderData: OrderData): Promise<Order> {
+    await this.database.connect();
+
+    try {
+      // Uses abstraction - no SQL dialect specifics
+      await this.database.execute({
+        table: 'orders',
+        operation: 'insert',
+        data: {
+          customerId: orderData.customerId,
+          total: orderData.total,
+          status: 'pending'
+        }
+      });
+
+      // Uses abstraction - no payment provider specifics
+      const chargeResult = await this.paymentGateway.charge({
+        amount: orderData.total,
+        currency: 'USD',
+        paymentMethodId: orderData.paymentMethodId,
+        metadata: { orderId: orderData.id }
+      });
+
+      // Uses abstraction - no email provider specifics
+      await this.emailSender.send({
+        to: orderData.customerEmail,
+        subject: 'Order Confirmation',
+        body: `Your order has been placed. Transaction: ${chargeResult.transactionId}`
+      });
+
+      return { id: orderData.id, ...orderData, status: 'completed' };
+    } finally {
+      await this.database.disconnect();
+    }
+  }
+}
+
+// Low-level implementations depend on abstractions
+class MySQLDatabase implements Database {
+  private connection: any;
+
+  async connect(): Promise<void> {
+    this.connection = await mysql.createConnection(config);
+  }
+
+  async query<T>(query: QueryBuilder): Promise<T[]> {
+    const sql = this.buildSelectQuery(query);
+    const [rows] = await this.connection.execute(sql);
+    return rows as T[];
+  }
+
+  async execute(command: Command): Promise<void> {
+    const sql = this.buildCommandQuery(command);
+    await this.connection.execute(sql);
+  }
+
+  async disconnect(): Promise<void> {
+    await this.connection.end();
+  }
+
+  private buildSelectQuery(query: QueryBuilder): string {
+    // MySQL-specific query building
+    return `SELECT ${query.select?.join(', ') ?? '*'} FROM ${query.table}`;
+  }
+
+  private buildCommandQuery(command: Command): string {
+    // MySQL-specific command building
+    return `INSERT INTO ${command.table} ...`;
+  }
+}
+
+class PostgreSQLDatabase implements Database {
+  // PostgreSQL-specific implementation of the same interface
+  async connect(): Promise<void> { /* PostgreSQL connection */ }
+  async query<T>(query: QueryBuilder): Promise<T[]> { /* PostgreSQL query */ }
+  async execute(command: Command): Promise<void> { /* PostgreSQL execute */ }
+  async disconnect(): Promise<void> { /* PostgreSQL disconnect */ }
+}
+
+class SendGridEmailSender implements EmailSender {
+  constructor(private apiKey: string) {}
+
+  async send(options: EmailOptions): Promise<void> {
+    await sendgrid.send({
+      to: options.to,
+      from: 'noreply@example.com',
+      subject: options.subject,
+      text: options.body,
+      html: options.html
+    });
+  }
+}
+
+class StripePaymentGateway implements PaymentGateway {
+  constructor(private stripe: Stripe) {}
+
+  async charge(request: ChargeRequest): Promise<ChargeResult> {
+    const intent = await this.stripe.paymentIntents.create({
+      amount: request.amount * 100,
+      currency: request.currency,
+      payment_method: request.paymentMethodId,
+      confirm: true
+    });
+
+    return {
+      transactionId: intent.id,
+      status: intent.status === 'succeeded' ? 'success' : 'pending',
+      amount: request.amount
+    };
+  }
+
+  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
+    const refund = await this.stripe.refunds.create({
+      payment_intent: transactionId,
+      amount: amount ? amount * 100 : undefined
+    });
+    return { refundId: refund.id, status: 'success' };
+  }
+}
+
+// Composition root - where we wire everything together
+function createOrderService(): OrderService {
+  const database = new PostgreSQLDatabase();
+  const emailSender = new SendGridEmailSender(process.env.SENDGRID_API_KEY!);
+  const paymentGateway = new StripePaymentGateway(new Stripe(process.env.STRIPE_KEY));
+
+  return new OrderService(database, emailSender, paymentGateway);
+}
+
+// Testing with mock implementations
+class MockDatabase implements Database {
+  public queries: QueryBuilder[] = [];
+  public commands: Command[] = [];
+
+  async connect(): Promise<void> {}
+  async query<T>(query: QueryBuilder): Promise<T[]> {
+    this.queries.push(query);
+    return [];
+  }
+  async execute(command: Command): Promise<void> {
+    this.commands.push(command);
+  }
+  async disconnect(): Promise<void> {}
+}
+
+// Test without real databases, email servers, or payment gateways
+describe('OrderService', () => {
+  it('should create order', async () => {
+    const mockDb = new MockDatabase();
+    const mockEmail: EmailSender = { send: jest.fn() };
+    const mockPayment: PaymentGateway = {
+      charge: jest.fn().mockResolvedValue({ transactionId: 'test_txn', status: 'success', amount: 100 }),
+      refund: jest.fn()
+    };
+
+    const service = new OrderService(mockDb, mockEmail, mockPayment);
+    await service.createOrder(testOrderData);
+
+    expect(mockDb.commands).toHaveLength(1);
+    expect(mockPayment.charge).toHaveBeenCalled();
+    expect(mockEmail.send).toHaveBeenCalled();
+  });
+});
+```
+
+## Why
+
+1. **Loose Coupling**: `OrderService` doesn't know or care about MySQL, Stripe, or SendGrid. It works with any implementation.
+
+2. **Easy Swapping**: Switch from MySQL to PostgreSQL by providing a different implementation. No changes to `OrderService`.
+
+3. **Testability**: Test with mock implementations - no real databases or external services needed.
+
+4. **Parallel Development**: Teams can work on different implementations simultaneously against the same interface.
+
+5. **Policy/Detail Separation**: Business rules (OrderService) are separate from infrastructure details (MySQLDatabase).
+
+6. **Stable Architecture**: Abstractions change less frequently than implementations. The core is protected from change.
+
+7. **Plugin Architecture**: New implementations can be added without modifying existing code.
diff --git a/.agents/skills/clean-code-principles/rules/solid-dip-injection.md b/.agents/skills/clean-code-principles/rules/solid-dip-injection.md
new file mode 100644
index 0000000..1bbd78d
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-dip-injection.md
@@ -0,0 +1,349 @@
+---
+id: solid-dip-injection
+title: SOLID - Dependency Inversion (Injection)
+category: solid-principles
+priority: critical
+tags: [SOLID, DIP, dependency-injection, testability]
+related: [solid-dip-abstractions, solid-srp-class, core-composition]
+---
+
+# Dependency Inversion Principle - Dependency Injection
+
+Dependencies should be injected from outside rather than created inside a class. This enables loose coupling, testability, and flexibility in how dependencies are provided.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Creating dependencies inside the class
+
+class UserRegistrationService {
+  private userRepository: UserRepository;
+  private passwordHasher: PasswordHasher;
+  private emailService: EmailService;
+  private logger: Logger;
+  private analyticsService: AnalyticsService;
+
+  constructor() {
+    // Dependencies created inside - tight coupling
+    this.userRepository = new PostgresUserRepository(
+      new PostgresConnection('localhost', 5432, 'mydb')
+    );
+    this.passwordHasher = new BcryptPasswordHasher(10);
+    this.emailService = new SendGridEmailService(process.env.SENDGRID_KEY!);
+    this.logger = new WinstonLogger('UserRegistration');
+    this.analyticsService = new MixpanelAnalytics(process.env.MIXPANEL_TOKEN!);
+  }
+
+  async register(email: string, password: string): Promise<User> {
+    this.logger.info(`Registering user: ${email}`);
+
+    const existingUser = await this.userRepository.findByEmail(email);
+    if (existingUser) {
+      throw new Error('User already exists');
+    }
+
+    const hashedPassword = await this.passwordHasher.hash(password);
+    const user = await this.userRepository.create({ email, password: hashedPassword });
+
+    await this.emailService.send({
+      to: email,
+      subject: 'Welcome!',
+      body: 'Thanks for registering'
+    });
+
+    await this.analyticsService.track('user_registered', { userId: user.id });
+
+    return user;
+  }
+}
+
+// Problems:
+// 1. Cannot test without real Postgres, SendGrid, Mixpanel
+// 2. Cannot reuse with different implementations
+// 3. Hard-coded configuration scattered through constructors
+// 4. Class responsible for creating its dependencies
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Dependencies injected from outside
+
+// Interfaces for all dependencies
+interface UserRepository {
+  findByEmail(email: string): Promise<User | null>;
+  findById(id: string): Promise<User | null>;
+  create(data: CreateUserData): Promise<User>;
+  update(id: string, data: Partial<User>): Promise<User>;
+}
+
+interface PasswordHasher {
+  hash(password: string): Promise<string>;
+  verify(password: string, hash: string): Promise<boolean>;
+}
+
+interface EmailService {
+  send(options: EmailOptions): Promise<void>;
+}
+
+interface Logger {
+  info(message: string, meta?: Record<string, any>): void;
+  error(message: string, error?: Error, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+}
+
+interface AnalyticsService {
+  track(event: string, properties?: Record<string, any>): Promise<void>;
+  identify(userId: string, traits?: Record<string, any>): Promise<void>;
+}
+
+// Service with constructor injection
+class UserRegistrationService {
+  constructor(
+    private readonly userRepository: UserRepository,
+    private readonly passwordHasher: PasswordHasher,
+    private readonly emailService: EmailService,
+    private readonly logger: Logger,
+    private readonly analyticsService: AnalyticsService
+  ) {}
+
+  async register(email: string, password: string): Promise<User> {
+    this.logger.info('Registering user', { email });
+
+    const existingUser = await this.userRepository.findByEmail(email);
+    if (existingUser) {
+      throw new UserAlreadyExistsError(email);
+    }
+
+    const hashedPassword = await this.passwordHasher.hash(password);
+    const user = await this.userRepository.create({
+      email,
+      password: hashedPassword,
+      createdAt: new Date()
+    });
+
+    await this.sendWelcomeEmail(user);
+    await this.trackRegistration(user);
+
+    this.logger.info('User registered successfully', { userId: user.id });
+    return user;
+  }
+
+  private async sendWelcomeEmail(user: User): Promise<void> {
+    try {
+      await this.emailService.send({
+        to: user.email,
+        subject: 'Welcome!',
+        body: 'Thanks for registering'
+      });
+    } catch (error) {
+      this.logger.error('Failed to send welcome email', error as Error, { userId: user.id });
+      // Don't fail registration if email fails
+    }
+  }
+
+  private async trackRegistration(user: User): Promise<void> {
+    try {
+      await this.analyticsService.identify(user.id, { email: user.email });
+      await this.analyticsService.track('user_registered', { userId: user.id });
+    } catch (error) {
+      this.logger.error('Failed to track registration', error as Error, { userId: user.id });
+      // Don't fail registration if analytics fails
+    }
+  }
+}
+
+// Concrete implementations
+class PostgresUserRepository implements UserRepository {
+  constructor(private db: DatabaseConnection) {}
+
+  async findByEmail(email: string): Promise<User | null> {
+    const result = await this.db.query('SELECT * FROM users WHERE email = $1', [email]);
+    return result.rows[0] || null;
+  }
+
+  async findById(id: string): Promise<User | null> {
+    const result = await this.db.query('SELECT * FROM users WHERE id = $1', [id]);
+    return result.rows[0] || null;
+  }
+
+  async create(data: CreateUserData): Promise<User> {
+    const result = await this.db.query(
+      'INSERT INTO users (email, password, created_at) VALUES ($1, $2, $3) RETURNING *',
+      [data.email, data.password, data.createdAt]
+    );
+    return result.rows[0];
+  }
+
+  async update(id: string, data: Partial<User>): Promise<User> {
+    // Implementation
+  }
+}
+
+class BcryptPasswordHasher implements PasswordHasher {
+  constructor(private rounds: number = 10) {}
+
+  async hash(password: string): Promise<string> {
+    return bcrypt.hash(password, this.rounds);
+  }
+
+  async verify(password: string, hash: string): Promise<boolean> {
+    return bcrypt.compare(password, hash);
+  }
+}
+
+// Dependency Injection Container (manual)
+class Container {
+  private services: Map<string, any> = new Map();
+
+  register<T>(key: string, factory: () => T): void {
+    this.services.set(key, factory);
+  }
+
+  resolve<T>(key: string): T {
+    const factory = this.services.get(key);
+    if (!factory) {
+      throw new Error(`Service not registered: ${key}`);
+    }
+    return factory();
+  }
+}
+
+// Composition root - wire up all dependencies
+function configureContainer(): Container {
+  const container = new Container();
+
+  // Register infrastructure
+  container.register('DatabaseConnection', () =>
+    new PostgresConnection(process.env.DATABASE_URL!)
+  );
+
+  container.register('Logger', () =>
+    new WinstonLogger({ level: process.env.LOG_LEVEL || 'info' })
+  );
+
+  // Register repositories
+  container.register('UserRepository', () =>
+    new PostgresUserRepository(container.resolve('DatabaseConnection'))
+  );
+
+  // Register services
+  container.register('PasswordHasher', () =>
+    new BcryptPasswordHasher(12)
+  );
+
+  container.register('EmailService', () =>
+    new SendGridEmailService(process.env.SENDGRID_API_KEY!)
+  );
+
+  container.register('AnalyticsService', () =>
+    new MixpanelAnalytics(process.env.MIXPANEL_TOKEN!)
+  );
+
+  // Register application services
+  container.register('UserRegistrationService', () =>
+    new UserRegistrationService(
+      container.resolve('UserRepository'),
+      container.resolve('PasswordHasher'),
+      container.resolve('EmailService'),
+      container.resolve('Logger'),
+      container.resolve('AnalyticsService')
+    )
+  );
+
+  return container;
+}
+
+// Application startup
+const container = configureContainer();
+const registrationService = container.resolve<UserRegistrationService>('UserRegistrationService');
+
+// Testing is now trivial with mock implementations
+describe('UserRegistrationService', () => {
+  let service: UserRegistrationService;
+  let mockUserRepository: jest.Mocked<UserRepository>;
+  let mockPasswordHasher: jest.Mocked<PasswordHasher>;
+  let mockEmailService: jest.Mocked<EmailService>;
+  let mockLogger: jest.Mocked<Logger>;
+  let mockAnalytics: jest.Mocked<AnalyticsService>;
+
+  beforeEach(() => {
+    mockUserRepository = {
+      findByEmail: jest.fn(),
+      findById: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn()
+    };
+    mockPasswordHasher = {
+      hash: jest.fn(),
+      verify: jest.fn()
+    };
+    mockEmailService = { send: jest.fn() };
+    mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() };
+    mockAnalytics = { track: jest.fn(), identify: jest.fn() };
+
+    service = new UserRegistrationService(
+      mockUserRepository,
+      mockPasswordHasher,
+      mockEmailService,
+      mockLogger,
+      mockAnalytics
+    );
+  });
+
+  it('should register a new user', async () => {
+    mockUserRepository.findByEmail.mockResolvedValue(null);
+    mockPasswordHasher.hash.mockResolvedValue('hashed_password');
+    mockUserRepository.create.mockResolvedValue({
+      id: '1',
+      email: 'test@example.com',
+      password: 'hashed_password',
+      createdAt: new Date()
+    });
+
+    const user = await service.register('test@example.com', 'password123');
+
+    expect(user.id).toBe('1');
+    expect(mockPasswordHasher.hash).toHaveBeenCalledWith('password123');
+    expect(mockEmailService.send).toHaveBeenCalled();
+    expect(mockAnalytics.track).toHaveBeenCalledWith('user_registered', { userId: '1' });
+  });
+
+  it('should throw error if user already exists', async () => {
+    mockUserRepository.findByEmail.mockResolvedValue({ id: '1', email: 'test@example.com' } as User);
+
+    await expect(service.register('test@example.com', 'password123'))
+      .rejects.toThrow(UserAlreadyExistsError);
+
+    expect(mockUserRepository.create).not.toHaveBeenCalled();
+  });
+
+  it('should not fail registration if email sending fails', async () => {
+    mockUserRepository.findByEmail.mockResolvedValue(null);
+    mockPasswordHasher.hash.mockResolvedValue('hashed_password');
+    mockUserRepository.create.mockResolvedValue({ id: '1', email: 'test@example.com' } as User);
+    mockEmailService.send.mockRejectedValue(new Error('SMTP error'));
+
+    const user = await service.register('test@example.com', 'password123');
+
+    expect(user.id).toBe('1');
+    expect(mockLogger.error).toHaveBeenCalled();
+  });
+});
+```
+
+## Why
+
+1. **Testability**: All dependencies can be mocked. Tests run fast without external services.
+
+2. **Flexibility**: Switch implementations at configuration time, not code change time.
+
+3. **Single Responsibility**: Classes focus on business logic, not on constructing dependencies.
+
+4. **Configuration Centralization**: All wiring happens in one place (composition root), making it easy to see and change.
+
+5. **Lifetime Management**: The container can manage singleton vs. transient instances.
+
+6. **Environment Adaptation**: Easy to provide different implementations for dev, test, staging, and production.
+
+7. **Explicit Dependencies**: Looking at the constructor tells you exactly what a class needs to function.
diff --git a/.agents/skills/clean-code-principles/rules/solid-isp-clients.md b/.agents/skills/clean-code-principles/rules/solid-isp-clients.md
new file mode 100644
index 0000000..490e054
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-isp-clients.md
@@ -0,0 +1,246 @@
+---
+id: solid-isp-clients
+title: SOLID - Interface Segregation (Client-Specific)
+category: solid-principles
+priority: critical
+tags: [SOLID, ISP, interface-segregation, client-design]
+related: [solid-isp-interfaces, solid-srp-class, solid-lsp-contracts]
+---
+
+# Interface Segregation Principle - Client-Specific Interfaces
+
+Clients should not be forced to depend on interfaces they do not use. Design interfaces from the client's perspective, not the implementation's.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Fat interface that forces clients to depend on methods they don't use
+
+interface UserService {
+  // Authentication
+  login(email: string, password: string): Promise<AuthToken>;
+  logout(userId: string): Promise<void>;
+  refreshToken(token: string): Promise<AuthToken>;
+  validateToken(token: string): Promise<boolean>;
+
+  // User management
+  createUser(data: CreateUserData): Promise<User>;
+  updateUser(id: string, data: UpdateUserData): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+  getUser(id: string): Promise<User>;
+  listUsers(filters: UserFilters): Promise<User[]>;
+
+  // Profile
+  updateProfile(userId: string, profile: ProfileData): Promise<Profile>;
+  uploadAvatar(userId: string, image: Buffer): Promise<string>;
+  getProfile(userId: string): Promise<Profile>;
+
+  // Notifications
+  sendNotification(userId: string, notification: Notification): Promise<void>;
+  getNotificationPreferences(userId: string): Promise<NotificationPrefs>;
+  updateNotificationPreferences(userId: string, prefs: NotificationPrefs): Promise<void>;
+
+  // Analytics
+  trackUserEvent(userId: string, event: AnalyticsEvent): Promise<void>;
+  getUserAnalytics(userId: string): Promise<UserAnalytics>;
+}
+
+// Login page only needs authentication but must depend on entire interface
+class LoginPage {
+  constructor(private userService: UserService) {} // Depends on 15+ methods!
+
+  async handleLogin(email: string, password: string): Promise<void> {
+    // Only uses 1 method
+    const token = await this.userService.login(email, password);
+    this.storeToken(token);
+  }
+}
+
+// Profile component forced to depend on authentication and analytics
+class ProfileEditor {
+  constructor(private userService: UserService) {} // Depends on 15+ methods!
+
+  async saveProfile(userId: string, data: ProfileData): Promise<void> {
+    // Only uses 2 methods
+    await this.userService.updateProfile(userId, data);
+    const profile = await this.userService.getProfile(userId);
+  }
+}
+
+// Mock implementation nightmare for testing
+class MockUserService implements UserService {
+  // Must implement ALL methods even for simple tests
+  login = jest.fn();
+  logout = jest.fn();
+  refreshToken = jest.fn();
+  validateToken = jest.fn();
+  createUser = jest.fn();
+  updateUser = jest.fn();
+  deleteUser = jest.fn();
+  getUser = jest.fn();
+  listUsers = jest.fn();
+  updateProfile = jest.fn();
+  uploadAvatar = jest.fn();
+  getProfile = jest.fn();
+  sendNotification = jest.fn();
+  getNotificationPreferences = jest.fn();
+  updateNotificationPreferences = jest.fn();
+  trackUserEvent = jest.fn();
+  getUserAnalytics = jest.fn();
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Client-specific interfaces
+
+// Authentication client interface
+interface Authenticator {
+  login(email: string, password: string): Promise<AuthToken>;
+  logout(userId: string): Promise<void>;
+  refreshToken(token: string): Promise<AuthToken>;
+  validateToken(token: string): Promise<boolean>;
+}
+
+// User management client interface
+interface UserManager {
+  createUser(data: CreateUserData): Promise<User>;
+  updateUser(id: string, data: UpdateUserData): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+  getUser(id: string): Promise<User>;
+  listUsers(filters: UserFilters): Promise<User[]>;
+}
+
+// Profile client interface
+interface ProfileManager {
+  updateProfile(userId: string, profile: ProfileData): Promise<Profile>;
+  uploadAvatar(userId: string, image: Buffer): Promise<string>;
+  getProfile(userId: string): Promise<Profile>;
+}
+
+// Notification client interface
+interface NotificationManager {
+  sendNotification(userId: string, notification: Notification): Promise<void>;
+  getNotificationPreferences(userId: string): Promise<NotificationPrefs>;
+  updateNotificationPreferences(userId: string, prefs: NotificationPrefs): Promise<void>;
+}
+
+// Analytics client interface
+interface UserAnalyticsTracker {
+  trackUserEvent(userId: string, event: AnalyticsEvent): Promise<void>;
+  getUserAnalytics(userId: string): Promise<UserAnalytics>;
+}
+
+// Read-only user lookup for components that only need to fetch
+interface UserLookup {
+  getUser(id: string): Promise<User>;
+  getProfile(userId: string): Promise<Profile>;
+}
+
+// Login page depends only on what it needs
+class LoginPage {
+  constructor(private auth: Authenticator) {} // Only 4 methods
+
+  async handleLogin(email: string, password: string): Promise<void> {
+    const token = await this.auth.login(email, password);
+    this.storeToken(token);
+  }
+}
+
+// Profile editor depends only on profile operations
+class ProfileEditor {
+  constructor(private profileManager: ProfileManager) {} // Only 3 methods
+
+  async saveProfile(userId: string, data: ProfileData): Promise<void> {
+    await this.profileManager.updateProfile(userId, data);
+  }
+
+  async loadProfile(userId: string): Promise<Profile> {
+    return this.profileManager.getProfile(userId);
+  }
+}
+
+// User display component only needs read access
+class UserCard {
+  constructor(private userLookup: UserLookup) {} // Only 2 methods
+
+  async render(userId: string): Promise<void> {
+    const user = await this.userLookup.getUser(userId);
+    const profile = await this.userLookup.getProfile(userId);
+    // Render user card
+  }
+}
+
+// Admin panel needs user management
+class AdminUserPanel {
+  constructor(private userManager: UserManager) {} // Only 5 methods
+
+  async deleteUserAccount(id: string): Promise<void> {
+    await this.userManager.deleteUser(id);
+  }
+}
+
+// Implementation can still implement multiple interfaces
+class UserServiceImpl implements
+  Authenticator,
+  UserManager,
+  ProfileManager,
+  NotificationManager,
+  UserAnalyticsTracker,
+  UserLookup
+{
+  // Implement all methods...
+  async login(email: string, password: string): Promise<AuthToken> { /* ... */ }
+  async logout(userId: string): Promise<void> { /* ... */ }
+  // ... rest of implementation
+}
+
+// Testing is now simple - only mock what you need
+describe('LoginPage', () => {
+  it('should login user', async () => {
+    const mockAuth: Authenticator = {
+      login: jest.fn().mockResolvedValue({ token: 'abc123' }),
+      logout: jest.fn(),
+      refreshToken: jest.fn(),
+      validateToken: jest.fn()
+    };
+
+    const loginPage = new LoginPage(mockAuth);
+    await loginPage.handleLogin('test@example.com', 'password');
+
+    expect(mockAuth.login).toHaveBeenCalledWith('test@example.com', 'password');
+  });
+});
+
+describe('ProfileEditor', () => {
+  it('should save profile', async () => {
+    const mockProfileManager: ProfileManager = {
+      updateProfile: jest.fn().mockResolvedValue({}),
+      uploadAvatar: jest.fn(),
+      getProfile: jest.fn()
+    };
+
+    const editor = new ProfileEditor(mockProfileManager);
+    await editor.saveProfile('user1', { name: 'John' });
+
+    expect(mockProfileManager.updateProfile).toHaveBeenCalled();
+  });
+});
+```
+
+## Why
+
+1. **Minimal Dependencies**: Each client depends only on the methods it actually uses, reducing coupling.
+
+2. **Easier Testing**: Mocks are small and focused. Testing `LoginPage` requires mocking 4 methods, not 15+.
+
+3. **Better Encapsulation**: Clients can't accidentally call methods they shouldn't have access to.
+
+4. **Clearer Intent**: Interface names describe what clients need: `Authenticator`, `ProfileManager`, `UserLookup`.
+
+5. **Independent Evolution**: Changes to analytics don't affect authentication clients. Interfaces can evolve separately.
+
+6. **Flexible Composition**: Different implementations can provide different subsets of functionality.
+
+7. **Single Responsibility**: Each interface has a focused responsibility, making the system easier to understand.
diff --git a/.agents/skills/clean-code-principles/rules/solid-isp-interfaces.md b/.agents/skills/clean-code-principles/rules/solid-isp-interfaces.md
new file mode 100644
index 0000000..be92a05
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-isp-interfaces.md
@@ -0,0 +1,286 @@
+---
+id: solid-isp-interfaces
+title: SOLID - Interface Segregation (Small Interfaces)
+category: solid-principles
+priority: critical
+tags: [SOLID, ISP, interface-segregation, cohesion]
+related: [solid-isp-clients, solid-srp-class, core-separation-concerns]
+---
+
+# Interface Segregation Principle - Small Cohesive Interfaces
+
+Interfaces should be small and cohesive, grouping only closely related methods. Split large interfaces into smaller, more focused ones.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Large interface with unrelated methods grouped together
+
+interface Document {
+  // Content operations
+  getContent(): string;
+  setContent(content: string): void;
+  appendContent(content: string): void;
+
+  // Persistence operations
+  save(): Promise<void>;
+  load(id: string): Promise<void>;
+  delete(): Promise<void>;
+
+  // Export operations
+  exportToPdf(): Promise<Buffer>;
+  exportToWord(): Promise<Buffer>;
+  exportToHtml(): Promise<string>;
+
+  // Collaboration operations
+  share(userId: string): Promise<void>;
+  getCollaborators(): Promise<User[]>;
+  addComment(comment: Comment): Promise<void>;
+  getComments(): Promise<Comment[]>;
+
+  // Version control
+  createVersion(): Promise<Version>;
+  getVersionHistory(): Promise<Version[]>;
+  revertToVersion(versionId: string): Promise<void>;
+
+  // Permissions
+  setPermissions(permissions: Permissions): Promise<void>;
+  getPermissions(): Promise<Permissions>;
+  checkPermission(userId: string, action: string): Promise<boolean>;
+}
+
+// Simple note-taking app forced to implement everything
+class SimpleNote implements Document {
+  private content: string = '';
+
+  getContent(): string { return this.content; }
+  setContent(content: string): void { this.content = content; }
+  appendContent(content: string): void { this.content += content; }
+
+  // Forced to implement methods it doesn't need
+  async save(): Promise<void> { throw new Error('Not supported'); }
+  async load(id: string): Promise<void> { throw new Error('Not supported'); }
+  async delete(): Promise<void> { throw new Error('Not supported'); }
+
+  async exportToPdf(): Promise<Buffer> { throw new Error('Not supported'); }
+  async exportToWord(): Promise<Buffer> { throw new Error('Not supported'); }
+  async exportToHtml(): Promise<string> { throw new Error('Not supported'); }
+
+  async share(userId: string): Promise<void> { throw new Error('Not supported'); }
+  async getCollaborators(): Promise<User[]> { throw new Error('Not supported'); }
+  async addComment(comment: Comment): Promise<void> { throw new Error('Not supported'); }
+  async getComments(): Promise<Comment[]> { throw new Error('Not supported'); }
+
+  async createVersion(): Promise<Version> { throw new Error('Not supported'); }
+  async getVersionHistory(): Promise<Version[]> { throw new Error('Not supported'); }
+  async revertToVersion(versionId: string): Promise<void> { throw new Error('Not supported'); }
+
+  async setPermissions(permissions: Permissions): Promise<void> { throw new Error('Not supported'); }
+  async getPermissions(): Promise<Permissions> { throw new Error('Not supported'); }
+  async checkPermission(userId: string, action: string): Promise<boolean> { throw new Error('Not supported'); }
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Small, cohesive interfaces
+
+// Core content interface - the essence of a document
+interface DocumentContent {
+  getContent(): string;
+  setContent(content: string): void;
+}
+
+// Extended content operations
+interface EditableContent extends DocumentContent {
+  appendContent(content: string): void;
+  insertContent(position: number, content: string): void;
+  deleteRange(start: number, end: number): void;
+}
+
+// Persistence operations
+interface Persistable {
+  save(): Promise<void>;
+  load(id: string): Promise<void>;
+}
+
+interface Deletable {
+  delete(): Promise<void>;
+}
+
+// Export capabilities
+interface PdfExportable {
+  exportToPdf(): Promise<Buffer>;
+}
+
+interface WordExportable {
+  exportToWord(): Promise<Buffer>;
+}
+
+interface HtmlExportable {
+  exportToHtml(): Promise<string>;
+}
+
+// Combine export interfaces when needed
+interface FullyExportable extends PdfExportable, WordExportable, HtmlExportable {}
+
+// Collaboration interfaces
+interface Shareable {
+  share(userId: string, permission: Permission): Promise<void>;
+  unshare(userId: string): Promise<void>;
+  getCollaborators(): Promise<Collaborator[]>;
+}
+
+interface Commentable {
+  addComment(comment: Comment): Promise<void>;
+  removeComment(commentId: string): Promise<void>;
+  getComments(): Promise<Comment[]>;
+}
+
+// Version control
+interface Versionable {
+  createVersion(message?: string): Promise<Version>;
+  getVersionHistory(): Promise<Version[]>;
+  revertToVersion(versionId: string): Promise<void>;
+}
+
+// Permissions
+interface PermissionControlled {
+  setPermissions(permissions: Permissions): Promise<void>;
+  getPermissions(): Promise<Permissions>;
+  checkPermission(userId: string, action: string): Promise<boolean>;
+}
+
+// Simple note only implements what it needs
+class SimpleNote implements DocumentContent {
+  private content: string = '';
+
+  getContent(): string {
+    return this.content;
+  }
+
+  setContent(content: string): void {
+    this.content = content;
+  }
+}
+
+// Persistent note adds storage
+class PersistentNote implements EditableContent, Persistable {
+  private content: string = '';
+  private id: string | null = null;
+
+  constructor(private storage: StorageService) {}
+
+  getContent(): string { return this.content; }
+  setContent(content: string): void { this.content = content; }
+  appendContent(content: string): void { this.content += content; }
+  insertContent(position: number, content: string): void {
+    this.content = this.content.slice(0, position) + content + this.content.slice(position);
+  }
+  deleteRange(start: number, end: number): void {
+    this.content = this.content.slice(0, start) + this.content.slice(end);
+  }
+
+  async save(): Promise<void> {
+    this.id = await this.storage.save(this.content);
+  }
+
+  async load(id: string): Promise<void> {
+    this.content = await this.storage.load(id);
+    this.id = id;
+  }
+}
+
+// Full-featured collaborative document
+class CollaborativeDocument implements
+  EditableContent,
+  Persistable,
+  Deletable,
+  FullyExportable,
+  Shareable,
+  Commentable,
+  Versionable,
+  PermissionControlled
+{
+  constructor(
+    private storage: StorageService,
+    private exportService: ExportService,
+    private collaborationService: CollaborationService,
+    private versionService: VersionService,
+    private permissionService: PermissionService
+  ) {}
+
+  // Implement all methods with actual functionality
+  // Each service handles its domain
+
+  getContent(): string { /* ... */ }
+  setContent(content: string): void { /* ... */ }
+  appendContent(content: string): void { /* ... */ }
+  insertContent(position: number, content: string): void { /* ... */ }
+  deleteRange(start: number, end: number): void { /* ... */ }
+
+  async save(): Promise<void> { /* delegate to storage */ }
+  async load(id: string): Promise<void> { /* delegate to storage */ }
+  async delete(): Promise<void> { /* delegate to storage */ }
+
+  async exportToPdf(): Promise<Buffer> { return this.exportService.toPdf(this); }
+  async exportToWord(): Promise<Buffer> { return this.exportService.toWord(this); }
+  async exportToHtml(): Promise<string> { return this.exportService.toHtml(this); }
+
+  async share(userId: string, permission: Permission): Promise<void> { /* ... */ }
+  async unshare(userId: string): Promise<void> { /* ... */ }
+  async getCollaborators(): Promise<Collaborator[]> { /* ... */ }
+
+  async addComment(comment: Comment): Promise<void> { /* ... */ }
+  async removeComment(commentId: string): Promise<void> { /* ... */ }
+  async getComments(): Promise<Comment[]> { /* ... */ }
+
+  async createVersion(message?: string): Promise<Version> { /* ... */ }
+  async getVersionHistory(): Promise<Version[]> { /* ... */ }
+  async revertToVersion(versionId: string): Promise<void> { /* ... */ }
+
+  async setPermissions(permissions: Permissions): Promise<void> { /* ... */ }
+  async getPermissions(): Promise<Permissions> { /* ... */ }
+  async checkPermission(userId: string, action: string): Promise<boolean> { /* ... */ }
+}
+
+// Functions can accept only the interfaces they need
+function renderDocument(doc: DocumentContent): void {
+  console.log(doc.getContent());
+}
+
+async function exportToPdf(doc: PdfExportable): Promise<void> {
+  const pdf = await doc.exportToPdf();
+  // Send pdf...
+}
+
+function canUserEdit(doc: PermissionControlled, userId: string): Promise<boolean> {
+  return doc.checkPermission(userId, 'edit');
+}
+
+// All document types work where their interfaces are expected
+const simpleNote = new SimpleNote();
+renderDocument(simpleNote); // Works!
+
+const collabDoc = new CollaborativeDocument(/* ... */);
+renderDocument(collabDoc); // Works!
+await exportToPdf(collabDoc); // Works!
+await canUserEdit(collabDoc, 'user123'); // Works!
+```
+
+## Why
+
+1. **Cohesion**: Each interface groups related methods. `Commentable` is about comments, `Versionable` about versions.
+
+2. **Flexibility**: Classes implement only the interfaces that match their capabilities.
+
+3. **Composability**: Complex types are built by combining simple interfaces: `EditableContent & Persistable & Shareable`.
+
+4. **No Empty Implementations**: No need for `throw new Error('Not supported')` - just don't implement the interface.
+
+5. **Clear Capabilities**: Looking at a class's implemented interfaces tells you exactly what it can do.
+
+6. **Easier Evolution**: Add new capabilities by creating new interfaces without modifying existing ones.
+
+7. **Better Typing**: Functions declare exactly what they need. `exportToPdf(doc: PdfExportable)` is self-documenting.
diff --git a/.agents/skills/clean-code-principles/rules/solid-lsp-contracts.md b/.agents/skills/clean-code-principles/rules/solid-lsp-contracts.md
new file mode 100644
index 0000000..38a3c8d
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-lsp-contracts.md
@@ -0,0 +1,203 @@
+---
+id: solid-lsp-contracts
+title: SOLID - Liskov Substitution (Contracts)
+category: solid-principles
+priority: critical
+tags: [SOLID, LSP, liskov-substitution, contracts]
+related: [solid-lsp-preconditions, solid-ocp-abstraction, core-composition]
+---
+
+# Liskov Substitution Principle - Contracts
+
+Subtypes must be substitutable for their base types without altering the correctness of the program. Derived classes must honor the contracts established by their base classes.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Subclass violates the contract of the base class
+
+class Rectangle {
+  protected _width: number;
+  protected _height: number;
+
+  constructor(width: number, height: number) {
+    this._width = width;
+    this._height = height;
+  }
+
+  get width(): number {
+    return this._width;
+  }
+
+  set width(value: number) {
+    this._width = value;
+  }
+
+  get height(): number {
+    return this._height;
+  }
+
+  set height(value: number) {
+    this._height = value;
+  }
+
+  getArea(): number {
+    return this._width * this._height;
+  }
+}
+
+// Square violates LSP - it changes the behavior of setters
+class Square extends Rectangle {
+  constructor(side: number) {
+    super(side, side);
+  }
+
+  // Violates LSP: setter has different behavior than parent
+  set width(value: number) {
+    this._width = value;
+    this._height = value; // Unexpected side effect!
+  }
+
+  set height(value: number) {
+    this._width = value; // Unexpected side effect!
+    this._height = value;
+  }
+}
+
+// This code works with Rectangle but breaks with Square
+function resizeRectangle(rect: Rectangle): void {
+  rect.width = 10;
+  rect.height = 5;
+
+  // Expects area to be 50, but Square gives 25!
+  console.assert(rect.getArea() === 50, 'Area should be 50');
+}
+
+const rectangle = new Rectangle(4, 4);
+resizeRectangle(rectangle); // Works: area is 50
+
+const square = new Square(4);
+resizeRectangle(square); // Fails: area is 25, not 50
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Use composition and proper abstractions
+
+// Define what shapes can do
+interface Shape {
+  getArea(): number;
+  getPerimeter(): number;
+}
+
+// Define what resizable shapes can do
+interface ResizableShape extends Shape {
+  scale(factor: number): void;
+}
+
+// Immutable rectangle - no setters that could be violated
+class Rectangle implements Shape {
+  constructor(
+    readonly width: number,
+    readonly height: number
+  ) {
+    if (width <= 0 || height <= 0) {
+      throw new Error('Dimensions must be positive');
+    }
+  }
+
+  getArea(): number {
+    return this.width * this.height;
+  }
+
+  getPerimeter(): number {
+    return 2 * (this.width + this.height);
+  }
+
+  // Return new instance instead of mutating
+  withWidth(width: number): Rectangle {
+    return new Rectangle(width, this.height);
+  }
+
+  withHeight(height: number): Rectangle {
+    return new Rectangle(this.width, height);
+  }
+
+  scale(factor: number): Rectangle {
+    return new Rectangle(this.width * factor, this.height * factor);
+  }
+}
+
+// Square is its own shape, not a subtype of Rectangle
+class Square implements Shape {
+  constructor(readonly side: number) {
+    if (side <= 0) {
+      throw new Error('Side must be positive');
+    }
+  }
+
+  getArea(): number {
+    return this.side * this.side;
+  }
+
+  getPerimeter(): number {
+    return 4 * this.side;
+  }
+
+  withSide(side: number): Square {
+    return new Square(side);
+  }
+
+  scale(factor: number): Square {
+    return new Square(this.side * factor);
+  }
+}
+
+// Functions work with the Shape interface
+function printShapeInfo(shape: Shape): void {
+  console.log(`Area: ${shape.getArea()}`);
+  console.log(`Perimeter: ${shape.getPerimeter()}`);
+}
+
+// This works correctly with both Rectangle and Square
+const rect = new Rectangle(10, 5);
+printShapeInfo(rect); // Area: 50, Perimeter: 30
+
+const square = new Square(5);
+printShapeInfo(square); // Area: 25, Perimeter: 20
+
+// For operations specific to rectangles, use Rectangle type
+function createBanner(width: number, height: number): Rectangle {
+  return new Rectangle(width, height);
+}
+
+// For operations that work with any shape, use Shape interface
+function calculateTotalArea(shapes: Shape[]): number {
+  return shapes.reduce((total, shape) => total + shape.getArea(), 0);
+}
+
+const shapes: Shape[] = [
+  new Rectangle(10, 5),
+  new Square(4),
+  new Rectangle(3, 7)
+];
+
+console.log(calculateTotalArea(shapes)); // 50 + 16 + 21 = 87
+```
+
+## Why
+
+1. **Predictable Behavior**: Code using the base type works correctly with any subtype. No surprises.
+
+2. **Safe Polymorphism**: You can pass any `Shape` to functions expecting `Shape` without checking the concrete type.
+
+3. **Contract Honoring**: Each class fully honors its interface contract - `getArea()` always returns the correct area.
+
+4. **Immutability Benefits**: By making shapes immutable, we avoid the setter problem entirely.
+
+5. **Proper Modeling**: Square and Rectangle are separate concepts that happen to share behavior (Shape), not a parent-child relationship.
+
+6. **Easier Testing**: Tests for `Shape` work for all implementations. No special cases needed.
+
+7. **Design Clarity**: The inheritance hierarchy reflects true "is-a" relationships, not just code reuse.
diff --git a/.agents/skills/clean-code-principles/rules/solid-lsp-preconditions.md b/.agents/skills/clean-code-principles/rules/solid-lsp-preconditions.md
new file mode 100644
index 0000000..aeb950a
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-lsp-preconditions.md
@@ -0,0 +1,256 @@
+---
+id: solid-lsp-preconditions
+title: SOLID - Liskov Substitution (Preconditions)
+category: solid-principles
+priority: critical
+tags: [SOLID, LSP, liskov-substitution, preconditions, postconditions]
+related: [solid-lsp-contracts, core-fail-fast, solid-ocp-abstraction]
+---
+
+# Liskov Substitution Principle - Preconditions and Postconditions
+
+Subtypes cannot strengthen preconditions (require more) or weaken postconditions (guarantee less) compared to their base types.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Subclass strengthens preconditions and weakens postconditions
+
+interface PaymentProcessor {
+  // Contract: accepts any amount > 0, returns transaction ID
+  processPayment(amount: number): Promise<string>;
+}
+
+class StandardPaymentProcessor implements PaymentProcessor {
+  async processPayment(amount: number): Promise<string> {
+    if (amount <= 0) {
+      throw new Error('Amount must be positive');
+    }
+    // Process payment and return transaction ID
+    return `TXN-${Date.now()}`;
+  }
+}
+
+// Violates LSP: Strengthens preconditions
+class PremiumPaymentProcessor implements PaymentProcessor {
+  private readonly minimumAmount = 100; // Stronger precondition!
+  private readonly maximumAmount = 10000; // Stronger precondition!
+
+  async processPayment(amount: number): Promise<string> {
+    if (amount <= 0) {
+      throw new Error('Amount must be positive');
+    }
+    // Additional restrictions not in base contract
+    if (amount < this.minimumAmount) {
+      throw new Error(`Minimum amount is ${this.minimumAmount}`); // Violates LSP!
+    }
+    if (amount > this.maximumAmount) {
+      throw new Error(`Maximum amount is ${this.maximumAmount}`); // Violates LSP!
+    }
+    return `PREM-TXN-${Date.now()}`;
+  }
+}
+
+// Violates LSP: Weakens postconditions
+class UnreliablePaymentProcessor implements PaymentProcessor {
+  async processPayment(amount: number): Promise<string> {
+    if (amount <= 0) {
+      throw new Error('Amount must be positive');
+    }
+
+    // Sometimes returns null instead of transaction ID - weaker postcondition!
+    if (Math.random() > 0.5) {
+      return null as any; // Violates the guarantee of returning a string
+    }
+
+    return `TXN-${Date.now()}`;
+  }
+}
+
+// Client code breaks when substituting implementations
+async function checkout(processor: PaymentProcessor, amount: number): Promise<void> {
+  const txnId = await processor.processPayment(amount);
+  // Assumes txnId is always a valid string (as per contract)
+  console.log(`Payment complete: ${txnId.toUpperCase()}`); // Crashes with null!
+}
+
+// Works with StandardPaymentProcessor
+await checkout(new StandardPaymentProcessor(), 50);
+
+// Fails with PremiumPaymentProcessor - amount too low
+await checkout(new PremiumPaymentProcessor(), 50); // Error: Minimum amount is 100
+
+// Fails with UnreliablePaymentProcessor - null txnId
+await checkout(new UnreliablePaymentProcessor(), 50); // Error: Cannot read toUpperCase of null
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Subtypes honor preconditions and postconditions
+
+// Clear contract with documented preconditions and postconditions
+interface PaymentProcessor {
+  /**
+   * Process a payment transaction.
+   *
+   * @precondition amount > 0
+   * @postcondition returns a non-empty transaction ID string
+   * @throws PaymentError if payment fails (not for invalid preconditions)
+   */
+  processPayment(amount: number): Promise<PaymentResult>;
+
+  /**
+   * Check if this processor can handle the given amount.
+   * Allows clients to check before attempting payment.
+   */
+  canProcess(amount: number): boolean;
+
+  /**
+   * Get the constraints of this processor.
+   */
+  getConstraints(): ProcessorConstraints;
+}
+
+interface PaymentResult {
+  readonly transactionId: string;
+  readonly processedAt: Date;
+  readonly amount: number;
+  readonly status: 'success' | 'pending';
+}
+
+interface ProcessorConstraints {
+  readonly minAmount: number;
+  readonly maxAmount: number;
+  readonly supportedCurrencies: string[];
+}
+
+// Base implementation with standard constraints
+class StandardPaymentProcessor implements PaymentProcessor {
+  private readonly constraints: ProcessorConstraints = {
+    minAmount: 0.01,
+    maxAmount: Infinity,
+    supportedCurrencies: ['USD', 'EUR', 'GBP']
+  };
+
+  getConstraints(): ProcessorConstraints {
+    return this.constraints;
+  }
+
+  canProcess(amount: number): boolean {
+    return amount >= this.constraints.minAmount &&
+           amount <= this.constraints.maxAmount;
+  }
+
+  async processPayment(amount: number): Promise<PaymentResult> {
+    // Precondition check (same as interface contract)
+    if (amount <= 0) {
+      throw new InvalidAmountError('Amount must be positive');
+    }
+
+    // Implementation
+    const transactionId = `TXN-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+
+    // Postcondition: always returns valid PaymentResult
+    return {
+      transactionId,
+      processedAt: new Date(),
+      amount,
+      status: 'success'
+    };
+  }
+}
+
+// Premium processor with different constraints but same contract behavior
+class PremiumPaymentProcessor implements PaymentProcessor {
+  private readonly constraints: ProcessorConstraints = {
+    minAmount: 100,
+    maxAmount: 100000,
+    supportedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CHF']
+  };
+
+  getConstraints(): ProcessorConstraints {
+    return this.constraints;
+  }
+
+  // Clients can check constraints before calling processPayment
+  canProcess(amount: number): boolean {
+    return amount >= this.constraints.minAmount &&
+           amount <= this.constraints.maxAmount;
+  }
+
+  async processPayment(amount: number): Promise<PaymentResult> {
+    // Same precondition as interface - not strengthened
+    if (amount <= 0) {
+      throw new InvalidAmountError('Amount must be positive');
+    }
+
+    // Business logic can still reject, but with proper error handling
+    if (!this.canProcess(amount)) {
+      throw new PaymentError(
+        `Amount ${amount} outside processor range [${this.constraints.minAmount}, ${this.constraints.maxAmount}]`
+      );
+    }
+
+    // Premium processing logic
+    const transactionId = `PREM-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+
+    // Postcondition: always returns valid PaymentResult (same guarantee)
+    return {
+      transactionId,
+      processedAt: new Date(),
+      amount,
+      status: 'success'
+    };
+  }
+}
+
+// Factory that selects appropriate processor
+class PaymentProcessorFactory {
+  private processors: PaymentProcessor[] = [
+    new StandardPaymentProcessor(),
+    new PremiumPaymentProcessor()
+  ];
+
+  getProcessorFor(amount: number): PaymentProcessor {
+    const suitable = this.processors.find(p => p.canProcess(amount));
+    if (!suitable) {
+      throw new NoSuitableProcessorError(amount);
+    }
+    return suitable;
+  }
+}
+
+// Client code works correctly with any processor
+async function checkout(amount: number, factory: PaymentProcessorFactory): Promise<void> {
+  const processor = factory.getProcessorFor(amount);
+  const result = await processor.processPayment(amount);
+
+  // Postcondition guarantees result is valid
+  console.log(`Payment complete: ${result.transactionId}`);
+  console.log(`Processed at: ${result.processedAt.toISOString()}`);
+}
+
+// Usage
+const factory = new PaymentProcessorFactory();
+
+await checkout(50, factory);    // Uses StandardPaymentProcessor
+await checkout(500, factory);   // Uses PremiumPaymentProcessor
+await checkout(5000, factory);  // Uses PremiumPaymentProcessor
+```
+
+## Why
+
+1. **Substitutability**: Any `PaymentProcessor` can be used interchangeably where `PaymentProcessor` is expected.
+
+2. **Client Safety**: Clients can rely on the contract. If preconditions are met, postconditions are guaranteed.
+
+3. **Explicit Constraints**: Instead of silently strengthening preconditions, processors expose their constraints through `getConstraints()` and `canProcess()`.
+
+4. **Proper Error Handling**: Constraint violations throw appropriate errors that clients can handle, rather than unexpected failures.
+
+5. **Factory Pattern**: The factory selects the appropriate processor, keeping constraint logic out of client code.
+
+6. **Design by Contract**: Clear documentation of preconditions and postconditions makes the contract explicit.
+
+7. **Defensive Programming**: Clients can check `canProcess()` before attempting payment, avoiding errors entirely.
diff --git a/.agents/skills/clean-code-principles/rules/solid-ocp-abstraction.md b/.agents/skills/clean-code-principles/rules/solid-ocp-abstraction.md
new file mode 100644
index 0000000..2d1f57a
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-ocp-abstraction.md
@@ -0,0 +1,265 @@
+---
+id: solid-ocp-abstraction
+title: SOLID - Open/Closed (Abstraction)
+category: solid-principles
+priority: critical
+tags: [SOLID, OCP, open-closed, abstraction]
+related: [solid-ocp-extension, solid-dip-abstractions, pattern-repository]
+---
+
+# Open/Closed Principle - Abstraction
+
+Use abstractions (interfaces and abstract classes) to define stable contracts that allow new implementations without modifying existing code.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Concrete dependencies that require modification for new requirements
+class ReportGenerator {
+  generateReport(data: SalesData[], format: string): string {
+    let report = '';
+
+    // Calculate totals
+    const totalSales = data.reduce((sum, d) => sum + d.amount, 0);
+    const averageSale = totalSales / data.length;
+
+    if (format === 'html') {
+      report = `
+        <html>
+          <body>
+            <h1>Sales Report</h1>
+            <p>Total Sales: $${totalSales}</p>
+            <p>Average Sale: $${averageSale.toFixed(2)}</p>
+            <table>
+              ${data.map(d => `<tr><td>${d.date}</td><td>$${d.amount}</td></tr>`).join('')}
+            </table>
+          </body>
+        </html>
+      `;
+    } else if (format === 'pdf') {
+      // PDF generation logic mixed in
+      const pdf = new PDFDocument();
+      pdf.text('Sales Report');
+      pdf.text(`Total: $${totalSales}`);
+      // ... more PDF logic
+      report = pdf.output();
+    } else if (format === 'csv') {
+      report = 'Date,Amount\n';
+      report += data.map(d => `${d.date},${d.amount}`).join('\n');
+    } else if (format === 'excel') {
+      // Excel generation logic
+      // Adding new format requires modifying this class
+    }
+
+    return report;
+  }
+}
+
+// Problems:
+// 1. Adding JSON format requires modifying ReportGenerator
+// 2. All format logic is tightly coupled
+// 3. Testing is difficult
+// 4. No way to extend without modification
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Abstractions enable extension without modification
+
+// Stable abstraction for report data
+interface ReportData {
+  readonly title: string;
+  readonly generatedAt: Date;
+  readonly summary: ReportSummary;
+  readonly items: ReportItem[];
+}
+
+interface ReportSummary {
+  readonly totalSales: number;
+  readonly averageSale: number;
+  readonly itemCount: number;
+}
+
+interface ReportItem {
+  readonly date: string;
+  readonly amount: number;
+  readonly description?: string;
+}
+
+// Stable abstraction for formatters
+interface ReportFormatter {
+  readonly format: string;
+  readonly mimeType: string;
+  render(data: ReportData): string | Buffer | Promise<string | Buffer>;
+}
+
+// Stable abstraction for data sources
+interface ReportDataSource<T> {
+  fetch(criteria: ReportCriteria): Promise<T[]>;
+  transform(rawData: T[]): ReportData;
+}
+
+// Report generator depends only on abstractions
+class ReportGenerator {
+  constructor(
+    private formatters: Map<string, ReportFormatter> = new Map()
+  ) {}
+
+  registerFormatter(formatter: ReportFormatter): void {
+    this.formatters.set(formatter.format, formatter);
+  }
+
+  async generate<T>(
+    dataSource: ReportDataSource<T>,
+    criteria: ReportCriteria,
+    format: string
+  ): Promise<GeneratedReport> {
+    const formatter = this.formatters.get(format);
+    if (!formatter) {
+      throw new UnsupportedFormatError(format, this.getSupportedFormats());
+    }
+
+    const rawData = await dataSource.fetch(criteria);
+    const reportData = dataSource.transform(rawData);
+    const content = await Promise.resolve(formatter.render(reportData));
+
+    return {
+      content,
+      mimeType: formatter.mimeType,
+      format,
+      generatedAt: new Date()
+    };
+  }
+
+  getSupportedFormats(): string[] {
+    return Array.from(this.formatters.keys());
+  }
+}
+
+// Concrete formatters - each can be added without modifying ReportGenerator
+
+class HtmlReportFormatter implements ReportFormatter {
+  readonly format = 'html';
+  readonly mimeType = 'text/html';
+
+  render(data: ReportData): string {
+    return `
+      <!DOCTYPE html>
+      <html>
+        <head><title>${data.title}</title></head>
+        <body>
+          <h1>${data.title}</h1>
+          <p>Generated: ${data.generatedAt.toISOString()}</p>
+          <section class="summary">
+            <p>Total Sales: $${data.summary.totalSales.toFixed(2)}</p>
+            <p>Average Sale: $${data.summary.averageSale.toFixed(2)}</p>
+          </section>
+          <table>
+            <thead><tr><th>Date</th><th>Amount</th></tr></thead>
+            <tbody>
+              ${data.items.map(item =>
+                `<tr><td>${item.date}</td><td>$${item.amount}</td></tr>`
+              ).join('')}
+            </tbody>
+          </table>
+        </body>
+      </html>
+    `;
+  }
+}
+
+class CsvReportFormatter implements ReportFormatter {
+  readonly format = 'csv';
+  readonly mimeType = 'text/csv';
+
+  render(data: ReportData): string {
+    const header = 'Date,Amount,Description';
+    const rows = data.items.map(item =>
+      `${item.date},${item.amount},"${item.description || ''}"`
+    );
+    return [header, ...rows].join('\n');
+  }
+}
+
+class JsonReportFormatter implements ReportFormatter {
+  readonly format = 'json';
+  readonly mimeType = 'application/json';
+
+  render(data: ReportData): string {
+    return JSON.stringify(data, null, 2);
+  }
+}
+
+// Adding Excel format - no modification to existing code
+class ExcelReportFormatter implements ReportFormatter {
+  readonly format = 'xlsx';
+  readonly mimeType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+
+  render(data: ReportData): Buffer {
+    const workbook = new ExcelJS.Workbook();
+    const sheet = workbook.addWorksheet(data.title);
+
+    sheet.addRow(['Date', 'Amount', 'Description']);
+    data.items.forEach(item => {
+      sheet.addRow([item.date, item.amount, item.description || '']);
+    });
+
+    return workbook.xlsx.writeBuffer();
+  }
+}
+
+// Concrete data source - can create new sources without modification
+class SalesReportDataSource implements ReportDataSource<SalesData> {
+  constructor(private salesRepository: SalesRepository) {}
+
+  async fetch(criteria: ReportCriteria): Promise<SalesData[]> {
+    return this.salesRepository.findByCriteria(criteria);
+  }
+
+  transform(rawData: SalesData[]): ReportData {
+    const totalSales = rawData.reduce((sum, d) => sum + d.amount, 0);
+
+    return {
+      title: 'Sales Report',
+      generatedAt: new Date(),
+      summary: {
+        totalSales,
+        averageSale: rawData.length > 0 ? totalSales / rawData.length : 0,
+        itemCount: rawData.length
+      },
+      items: rawData.map(d => ({
+        date: d.date,
+        amount: d.amount,
+        description: d.productName
+      }))
+    };
+  }
+}
+
+// Usage
+const generator = new ReportGenerator();
+generator.registerFormatter(new HtmlReportFormatter());
+generator.registerFormatter(new CsvReportFormatter());
+generator.registerFormatter(new JsonReportFormatter());
+generator.registerFormatter(new ExcelReportFormatter());
+
+const salesDataSource = new SalesReportDataSource(salesRepository);
+const report = await generator.generate(salesDataSource, criteria, 'xlsx');
+```
+
+## Why
+
+1. **Stable Core**: The `ReportGenerator` class and interfaces form a stable core that rarely changes.
+
+2. **Independent Development**: Teams can develop new formatters or data sources independently.
+
+3. **Composition Over Inheritance**: New functionality is added through composition (registering new implementations) rather than inheritance hierarchies.
+
+4. **Testing**: Each component can be tested in isolation with mock implementations of interfaces.
+
+5. **Flexibility**: The same generator works with any combination of data sources and formatters.
+
+6. **Dependency Inversion**: High-level modules (ReportGenerator) don't depend on low-level modules (specific formatters), both depend on abstractions.
+
+7. **Plugin System**: Natural foundation for a plugin architecture where third parties can add formatters.
diff --git a/.agents/skills/clean-code-principles/rules/solid-ocp-extension.md b/.agents/skills/clean-code-principles/rules/solid-ocp-extension.md
new file mode 100644
index 0000000..88515ba
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-ocp-extension.md
@@ -0,0 +1,205 @@
+---
+id: solid-ocp-extension
+title: SOLID - Open/Closed Principle (Extension)
+category: solid-principles
+priority: critical
+tags: [SOLID, OCP, open-closed, extensibility, design-patterns]
+related: [solid-ocp-abstraction, pattern-repository, solid-dip-abstractions]
+---
+
+# Open/Closed Principle - Extension
+
+Software entities should be open for extension but closed for modification. Add new functionality by adding new code, not by changing existing code.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Modifying existing code to add new functionality
+class PaymentProcessor {
+  processPayment(payment: Payment): PaymentResult {
+    switch (payment.method) {
+      case 'credit_card':
+        return this.processCreditCard(payment);
+      case 'paypal':
+        return this.processPayPal(payment);
+      case 'stripe':
+        return this.processStripe(payment);
+      // Every new payment method requires modifying this class
+      case 'apple_pay':
+        return this.processApplePay(payment);
+      case 'google_pay':
+        return this.processGooglePay(payment);
+      case 'crypto':
+        return this.processCrypto(payment);
+      default:
+        throw new Error(`Unknown payment method: ${payment.method}`);
+    }
+  }
+
+  private processCreditCard(payment: Payment): PaymentResult {
+    // Credit card logic
+  }
+
+  private processPayPal(payment: Payment): PaymentResult {
+    // PayPal logic
+  }
+
+  private processStripe(payment: Payment): PaymentResult {
+    // Stripe logic
+  }
+
+  private processApplePay(payment: Payment): PaymentResult {
+    // Apple Pay logic
+  }
+
+  private processGooglePay(payment: Payment): PaymentResult {
+    // Google Pay logic
+  }
+
+  private processCrypto(payment: Payment): PaymentResult {
+    // Crypto logic
+  }
+}
+
+// Adding a new payment method requires:
+// 1. Adding a new case to the switch statement
+// 2. Adding a new private method
+// 3. Testing the entire class again
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Open for extension, closed for modification
+
+// Define the contract for payment handlers
+interface PaymentHandler {
+  readonly methodType: string;
+  canHandle(payment: Payment): boolean;
+  process(payment: Payment): Promise<PaymentResult>;
+  validate(payment: Payment): ValidationResult;
+}
+
+// Payment processor that never needs modification
+class PaymentProcessor {
+  private handlers: Map<string, PaymentHandler> = new Map();
+
+  registerHandler(handler: PaymentHandler): void {
+    this.handlers.set(handler.methodType, handler);
+  }
+
+  async processPayment(payment: Payment): Promise<PaymentResult> {
+    const handler = this.handlers.get(payment.method);
+
+    if (!handler) {
+      throw new UnsupportedPaymentMethodError(payment.method);
+    }
+
+    const validation = handler.validate(payment);
+    if (!validation.isValid) {
+      throw new PaymentValidationError(validation.errors);
+    }
+
+    return handler.process(payment);
+  }
+
+  getSupportedMethods(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+}
+
+// Each payment method is a separate class that can be added without modifying PaymentProcessor
+
+class CreditCardPaymentHandler implements PaymentHandler {
+  readonly methodType = 'credit_card';
+
+  canHandle(payment: Payment): boolean {
+    return payment.method === this.methodType;
+  }
+
+  validate(payment: Payment): ValidationResult {
+    const errors: string[] = [];
+    if (!payment.cardNumber || payment.cardNumber.length !== 16) {
+      errors.push('Invalid card number');
+    }
+    if (!payment.cvv || payment.cvv.length !== 3) {
+      errors.push('Invalid CVV');
+    }
+    return { isValid: errors.length === 0, errors };
+  }
+
+  async process(payment: Payment): Promise<PaymentResult> {
+    // Credit card processing logic
+    return { success: true, transactionId: generateId() };
+  }
+}
+
+class PayPalPaymentHandler implements PaymentHandler {
+  readonly methodType = 'paypal';
+
+  canHandle(payment: Payment): boolean {
+    return payment.method === this.methodType;
+  }
+
+  validate(payment: Payment): ValidationResult {
+    const errors: string[] = [];
+    if (!payment.paypalEmail) {
+      errors.push('PayPal email required');
+    }
+    return { isValid: errors.length === 0, errors };
+  }
+
+  async process(payment: Payment): Promise<PaymentResult> {
+    // PayPal processing logic
+    return { success: true, transactionId: generateId() };
+  }
+}
+
+// Adding a new payment method - no modification to existing code!
+class CryptoPaymentHandler implements PaymentHandler {
+  readonly methodType = 'crypto';
+
+  canHandle(payment: Payment): boolean {
+    return payment.method === this.methodType;
+  }
+
+  validate(payment: Payment): ValidationResult {
+    const errors: string[] = [];
+    if (!payment.walletAddress) {
+      errors.push('Wallet address required');
+    }
+    if (!payment.cryptoCurrency) {
+      errors.push('Cryptocurrency type required');
+    }
+    return { isValid: errors.length === 0, errors };
+  }
+
+  async process(payment: Payment): Promise<PaymentResult> {
+    // Crypto processing logic
+    return { success: true, transactionId: generateId() };
+  }
+}
+
+// Application setup - register handlers
+const processor = new PaymentProcessor();
+processor.registerHandler(new CreditCardPaymentHandler());
+processor.registerHandler(new PayPalPaymentHandler());
+processor.registerHandler(new CryptoPaymentHandler());
+// Add new payment methods by simply registering new handlers
+```
+
+## Why
+
+1. **Stability**: The `PaymentProcessor` class is stable and tested. Adding new payment methods doesn't risk breaking existing functionality.
+
+2. **Team Scalability**: Different developers can work on different payment handlers simultaneously without merge conflicts.
+
+3. **Plugin Architecture**: Payment handlers can be loaded dynamically, even from external packages or plugins.
+
+4. **Testing Isolation**: Each handler is tested independently. New handlers don't require retesting old ones.
+
+5. **Feature Flags**: New payment methods can be enabled/disabled by simply registering or not registering the handler.
+
+6. **Compliance**: When regulations change for one payment method, only that handler needs updating.
+
+7. **Rollback Safety**: If a new payment handler has issues, remove it without touching proven code.
diff --git a/.agents/skills/clean-code-principles/rules/solid-srp-class.md b/.agents/skills/clean-code-principles/rules/solid-srp-class.md
new file mode 100644
index 0000000..765328d
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-srp-class.md
@@ -0,0 +1,149 @@
+---
+id: solid-srp-class
+title: SOLID - Single Responsibility Principle (Class Level)
+category: solid-principles
+priority: critical
+tags: [SOLID, SRP, single-responsibility, class-design]
+related: [solid-srp-function, core-separation-concerns, solid-isp-interfaces]
+---
+
+# Single Responsibility Principle - Class Level
+
+A class should have only one reason to change, meaning it should have only one job or responsibility.
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Class handles multiple responsibilities
+class UserManager {
+  private db: Database;
+  private mailer: EmailService;
+
+  constructor() {
+    this.db = new Database();
+    this.mailer = new EmailService();
+  }
+
+  createUser(userData: UserData): User {
+    // Validation logic
+    if (!userData.email.includes('@')) {
+      throw new Error('Invalid email');
+    }
+    if (userData.password.length < 8) {
+      throw new Error('Password too short');
+    }
+
+    // Database logic
+    const user = this.db.insert('users', userData);
+
+    // Email logic
+    const htmlContent = `<h1>Welcome ${user.name}!</h1>`;
+    this.mailer.send(user.email, 'Welcome', htmlContent);
+
+    // Logging logic
+    console.log(`User created: ${user.id} at ${new Date()}`);
+    this.writeToFile(`/logs/users.log`, `Created: ${user.id}`);
+
+    return user;
+  }
+
+  private writeToFile(path: string, content: string): void {
+    // File writing implementation
+  }
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Each class has a single responsibility
+
+// Handles user validation only
+class UserValidator {
+  validate(userData: UserData): ValidationResult {
+    const errors: string[] = [];
+
+    if (!userData.email.includes('@')) {
+      errors.push('Invalid email format');
+    }
+    if (userData.password.length < 8) {
+      errors.push('Password must be at least 8 characters');
+    }
+
+    return { isValid: errors.length === 0, errors };
+  }
+}
+
+// Handles user persistence only
+class UserRepository {
+  constructor(private db: Database) {}
+
+  save(userData: UserData): User {
+    return this.db.insert('users', userData);
+  }
+
+  findById(id: string): User | null {
+    return this.db.findOne('users', { id });
+  }
+}
+
+// Handles welcome email only
+class WelcomeEmailService {
+  constructor(private mailer: EmailService) {}
+
+  sendWelcomeEmail(user: User): void {
+    const htmlContent = this.buildTemplate(user);
+    this.mailer.send(user.email, 'Welcome', htmlContent);
+  }
+
+  private buildTemplate(user: User): string {
+    return `<h1>Welcome ${user.name}!</h1>`;
+  }
+}
+
+// Handles user activity logging only
+class UserActivityLogger {
+  constructor(private logger: Logger) {}
+
+  logCreation(user: User): void {
+    this.logger.info(`User created: ${user.id}`, { userId: user.id });
+  }
+}
+
+// Orchestrates the user creation process
+class UserService {
+  constructor(
+    private validator: UserValidator,
+    private repository: UserRepository,
+    private welcomeEmail: WelcomeEmailService,
+    private activityLogger: UserActivityLogger
+  ) {}
+
+  createUser(userData: UserData): User {
+    const validation = this.validator.validate(userData);
+    if (!validation.isValid) {
+      throw new ValidationError(validation.errors);
+    }
+
+    const user = this.repository.save(userData);
+    this.welcomeEmail.sendWelcomeEmail(user);
+    this.activityLogger.logCreation(user);
+
+    return user;
+  }
+}
+```
+
+## Why
+
+1. **Easier Testing**: Each class can be unit tested in isolation without mocking unrelated dependencies.
+
+2. **Reduced Coupling**: Changes to email templates don't affect database logic or validation rules.
+
+3. **Better Reusability**: The `UserValidator` can be reused for profile updates, the `WelcomeEmailService` can be triggered from different flows.
+
+4. **Clearer Ownership**: Teams can own specific classes without stepping on each other's work.
+
+5. **Simpler Maintenance**: Bug in email formatting? Look only at `WelcomeEmailService`. Validation issue? Check `UserValidator`.
+
+6. **Flexible Composition**: Easy to add features like async email sending or different logging strategies without touching core logic.
diff --git a/.agents/skills/clean-code-principles/rules/solid-srp-function.md b/.agents/skills/clean-code-principles/rules/solid-srp-function.md
new file mode 100644
index 0000000..842888e
--- /dev/null
+++ b/.agents/skills/clean-code-principles/rules/solid-srp-function.md
@@ -0,0 +1,208 @@
+---
+id: solid-srp-function
+title: SOLID - Single Responsibility Principle (Function Level)
+category: solid-principles
+priority: critical
+tags: [SOLID, SRP, single-responsibility, function-design]
+related: [solid-srp-class, core-dry-extraction, core-kiss-simplicity]
+---
+
+# Single Responsibility Principle - Function Level
+
+A function should do one thing, do it well, and do it only. It should have a single, clear purpose that can be described without using conjunctions like "and" or "or".
+
+## Bad Example
+
+```typescript
+// Anti-pattern: Function does multiple things
+async function processOrder(orderId: string): Promise<void> {
+  // Fetch order
+  const order = await db.query('SELECT * FROM orders WHERE id = ?', [orderId]);
+
+  // Validate order
+  if (!order) throw new Error('Order not found');
+  if (order.status !== 'pending') throw new Error('Order already processed');
+  if (order.items.length === 0) throw new Error('Order has no items');
+
+  // Calculate totals
+  let subtotal = 0;
+  for (const item of order.items) {
+    const product = await db.query('SELECT price FROM products WHERE id = ?', [item.productId]);
+    subtotal += product.price * item.quantity;
+  }
+  const tax = subtotal * 0.1;
+  const shipping = subtotal > 100 ? 0 : 10;
+  const total = subtotal + tax + shipping;
+
+  // Update inventory
+  for (const item of order.items) {
+    await db.query('UPDATE products SET stock = stock - ? WHERE id = ?',
+      [item.quantity, item.productId]);
+  }
+
+  // Process payment
+  const paymentResult = await stripe.charges.create({
+    amount: Math.round(total * 100),
+    currency: 'usd',
+    customer: order.customerId
+  });
+
+  // Update order status
+  await db.query('UPDATE orders SET status = ?, total = ?, payment_id = ? WHERE id = ?',
+    ['completed', total, paymentResult.id, orderId]);
+
+  // Send confirmation email
+  const emailHtml = `<h1>Order Confirmed</h1><p>Total: $${total}</p>`;
+  await sendgrid.send({
+    to: order.customerEmail,
+    subject: 'Order Confirmation',
+    html: emailHtml
+  });
+
+  // Log analytics
+  await analytics.track('order_completed', { orderId, total, itemCount: order.items.length });
+}
+```
+
+## Good Example
+
+```typescript
+// Correct approach: Each function has a single purpose
+
+async function processOrder(orderId: string): Promise<ProcessedOrder> {
+  const order = await fetchAndValidateOrder(orderId);
+  const pricing = await calculateOrderPricing(order);
+
+  await reserveInventory(order.items);
+
+  try {
+    const payment = await processPayment(order.customerId, pricing.total);
+    const completedOrder = await finalizeOrder(order, pricing, payment);
+
+    await sendOrderConfirmation(completedOrder);
+    await trackOrderCompletion(completedOrder);
+
+    return completedOrder;
+  } catch (error) {
+    await releaseInventory(order.items);
+    throw error;
+  }
+}
+
+async function fetchAndValidateOrder(orderId: string): Promise<Order> {
+  const order = await orderRepository.findById(orderId);
+
+  if (!order) {
+    throw new OrderNotFoundError(orderId);
+  }
+
+  validateOrderStatus(order);
+  validateOrderItems(order);
+
+  return order;
+}
+
+function validateOrderStatus(order: Order): void {
+  if (order.status !== 'pending') {
+    throw new InvalidOrderStatusError(order.id, order.status);
+  }
+}
+
+function validateOrderItems(order: Order): void {
+  if (order.items.length === 0) {
+    throw new EmptyOrderError(order.id);
+  }
+}
+
+async function calculateOrderPricing(order: Order): Promise<OrderPricing> {
+  const subtotal = await calculateSubtotal(order.items);
+  const tax = calculateTax(subtotal);
+  const shipping = calculateShipping(subtotal);
+
+  return {
+    subtotal,
+    tax,
+    shipping,
+    total: subtotal + tax + shipping
+  };
+}
+
+async function calculateSubtotal(items: OrderItem[]): Promise<number> {
+  const itemTotals = await Promise.all(
+    items.map(item => calculateItemTotal(item))
+  );
+  return itemTotals.reduce((sum, total) => sum + total, 0);
+}
+
+async function calculateItemTotal(item: OrderItem): Promise<number> {
+  const product = await productRepository.findById(item.productId);
+  return product.price * item.quantity;
+}
+
+function calculateTax(subtotal: number): number {
+  const TAX_RATE = 0.1;
+  return subtotal * TAX_RATE;
+}
+
+function calculateShipping(subtotal: number): number {
+  const FREE_SHIPPING_THRESHOLD = 100;
+  const STANDARD_SHIPPING = 10;
+  return subtotal > FREE_SHIPPING_THRESHOLD ? 0 : STANDARD_SHIPPING;
+}
+
+async function reserveInventory(items: OrderItem[]): Promise<void> {
+  await Promise.all(
+    items.map(item => inventoryService.reserve(item.productId, item.quantity))
+  );
+}
+
+async function releaseInventory(items: OrderItem[]): Promise<void> {
+  await Promise.all(
+    items.map(item => inventoryService.release(item.productId, item.quantity))
+  );
+}
+
+async function processPayment(customerId: string, amount: number): Promise<Payment> {
+  return paymentService.charge(customerId, amount);
+}
+
+async function finalizeOrder(
+  order: Order,
+  pricing: OrderPricing,
+  payment: Payment
+): Promise<ProcessedOrder> {
+  return orderRepository.updateStatus(order.id, {
+    status: 'completed',
+    total: pricing.total,
+    paymentId: payment.id
+  });
+}
+
+async function sendOrderConfirmation(order: ProcessedOrder): Promise<void> {
+  await emailService.sendOrderConfirmation(order);
+}
+
+async function trackOrderCompletion(order: ProcessedOrder): Promise<void> {
+  await analyticsService.track('order_completed', {
+    orderId: order.id,
+    total: order.total,
+    itemCount: order.items.length
+  });
+}
+```
+
+## Why
+
+1. **Readability**: The main function reads like a story - fetch, validate, calculate, reserve, charge, finalize, notify.
+
+2. **Testability**: Each function can be unit tested independently. Testing `calculateTax` doesn't require mocking a database.
+
+3. **Reusability**: `calculateShipping` can be reused in a shipping estimate feature. `validateOrderStatus` can be used in other order operations.
+
+4. **Debugging**: Stack traces point to specific functions. "Error in calculateSubtotal" is more helpful than "Error in processOrder at line 47".
+
+5. **Modification**: Changing tax calculation only touches `calculateTax`. Adding a discount feature can be inserted cleanly between subtotal and tax.
+
+6. **Error Handling**: Each function can have appropriate error handling. The main function can orchestrate rollback on failure.
+
+7. **Documentation**: Function names serve as documentation. The code is self-explanatory without comments.
diff --git a/.agents/skills/clean-code/SKILL.md b/.agents/skills/clean-code/SKILL.md
new file mode 100644
index 0000000..ac11a9e
--- /dev/null
+++ b/.agents/skills/clean-code/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: clean-code
+description: "This skill embodies the principles of \"Clean Code\" by Robert C. Martin (Uncle Bob). Use it to transform \"code that works\" into \"code that is clean.\""
+risk: safe
+source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
+date_added: "2026-02-27"
+---
+
+# Clean Code Skill
+
+This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
+
+## 🧠 Core Philosophy
+> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch
+
+## When to Use
+Use this skill when:
+- **Writing new code**: To ensure high quality from the start.
+- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
+- **Refactoring legacy code**: To identify and remove code smells.
+- **Improving team standards**: To align on industry-standard best practices.
+
+## 1. Meaningful Names
+- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
+- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
+- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
+- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
+- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
+- **Method Names**: Use verbs (`postPayment`, `deletePage`).
+
+## 2. Functions
+- **Small!**: Functions should be shorter than you think.
+- **Do One Thing**: A function should do only one thing, and do it well.
+- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
+- **Descriptive Names**: `isPasswordValid` is better than `check`.
+- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
+- **No Side Effects**: Functions shouldn't secretly change global state.
+
+## 3. Comments
+- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.
+- **Explain Yourself in Code**: 
+  ```python
+  # Check if employee is eligible for full benefits
+  if employee.flags & HOURLY and employee.age > 65:
+  ```
+  vs
+  ```python
+  if employee.isEligibleForFullBenefits():
+  ```
+- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
+- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
+
+## 4. Formatting
+- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
+- **Vertical Density**: Related lines should be close to each other.
+- **Distance**: Variables should be declared near their usage.
+- **Indentation**: Essential for structural readability.
+
+## 5. Objects and Data Structures
+- **Data Abstraction**: Hide the implementation behind interfaces.
+- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
+- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
+
+## 6. Error Handling
+- **Use Exceptions instead of Return Codes**: Keeps logic clean.
+- **Write Try-Catch-Finally First**: Defines the scope of the operation.
+- **Don't Return Null**: It forces the caller to check for null every time.
+- **Don't Pass Null**: Leads to `NullPointerException`.
+
+## 7. Unit Tests
+- **The Three Laws of TDD**:
+  1. Don't write production code until you have a failing unit test.
+  2. Don't write more of a unit test than is sufficient to fail.
+  3. Don't write more production code than is sufficient to pass the failing test.
+- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+## 8. Classes
+- **Small!**: Classes should have a single responsibility (SRP).
+- **The Stepdown Rule**: We want the code to read like a top-down narrative.
+
+## 9. Smells and Heuristics
+- **Rigidity**: Hard to change.
+- **Fragility**: Breaks in many places.
+- **Immobility**: Hard to reuse.
+- **Viscosity**: Hard to do the right thing.
+- **Needless Complexity/Repetition**.
+
+## 🛠️ Implementation Checklist
+- [ ] Is this function smaller than 20 lines?
+- [ ] Does this function do exactly one thing?
+- [ ] Are all names searchable and intention-revealing?
+- [ ] Have I avoided comments by making the code clearer?
+- [ ] Am I passing too many arguments?
+- [ ] Is there a failing test for this change?
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
diff --git a/.agents/skills/hono/SKILL.md b/.agents/skills/hono/SKILL.md
new file mode 100644
index 0000000..857453f
--- /dev/null
+++ b/.agents/skills/hono/SKILL.md
@@ -0,0 +1,598 @@
+---
+name: hono
+description: Use when building Hono web applications or when the user asks about Hono APIs, routing, middleware, JSX, validation, testing, or streaming. TRIGGER when code imports from 'hono' or 'hono/*', or user mentions Hono. Use Hono CLI to inspect and test the app.
+---
+
+# Hono Skill
+
+Build Hono web applications. This skill provides inline API knowledge for AI. Use Hono CLI to inspect and test the app.
+
+## Latest Documentation
+
+For details beyond this inline reference, fetch the latest documentation from https://hono.dev. Get the index of doc pages from `https://hono.dev/llms.txt`, then fetch a page with the `Accept: text/markdown` header to receive it as Markdown:
+
+```bash
+curl -H "Accept: text/markdown" https://hono.dev/docs/helpers/cookie
+```
+
+## Hono CLI
+
+Use [Hono CLI](https://github.com/honojs/cli) to inspect and test the app. Install it in the project, then let the CLI explain itself:
+
+<!-- TODO at the 0.2 release: change @hono/cli@next to @hono/cli -->
+
+```bash
+npm install -D @hono/cli@next
+npx hono agent-context
+```
+
+Follow the output. It explains every command (`routes`, `request`, `benchmark`, `optimize`, `ssg`), the JSON output contract, and the workflow.
+
+Notes:
+
+- `hono request` sends a request with `app.request()` — no server needed. Do not pass credentials directly in CLI arguments; use environment variables for sensitive values.
+- For Cloudflare Workers bindings (KV, D1, R2, etc.), use `hono request /path --runtime workerd`. It starts the app with the wrangler config of the project, so the local bindings (`c.env`) are real. wrangler must be installed in the project.
+- For several requests, or a flow that keeps state (POST, then use the returned id), use one `hono request --batch -` call. One JSON object per line; `save` a value and use it as `{{id}}` in later steps. The steps share one app instance:
+
+  ```bash
+  npx hono request --batch - <<'EOF'
+  {"method":"POST","path":"/users","body":{"name":"Alice"},"save":{"id":".id"}}
+  {"path":"/users/{{id}}"}
+  EOF
+  ```
+
+---
+
+## Hono API Reference
+
+### App Constructor
+
+```ts
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+// With TypeScript generics
+type Env = {
+  Bindings: { DATABASE: D1Database; KV: KVNamespace }
+  Variables: { user: User }
+}
+const app = new Hono<Env>()
+```
+
+### Routing Methods
+
+```ts
+app.get('/path', handler)
+app.post('/path', handler)
+app.put('/path', handler)
+app.delete('/path', handler)
+app.patch('/path', handler)
+app.options('/path', handler)
+app.all('/path', handler) // all HTTP methods
+app.on('PURGE', '/path', handler) // custom method
+app.on(['PUT', 'DELETE'], '/path', handler) // multiple methods
+```
+
+### Routing Patterns
+
+```ts
+// Path parameters
+app.get('/user/:name', (c) => {
+  const name = c.req.param('name')
+  return c.json({ name })
+})
+
+// Multiple params
+app.get('/posts/:id/comments/:commentId', (c) => {
+  const { id, commentId } = c.req.param()
+})
+
+// Optional parameters
+app.get('/api/animal/:type?', (c) => c.text('Animal!'))
+
+// Wildcards
+app.get('/wild/*/card', (c) => c.text('Wildcard'))
+
+// Regexp constraints
+app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
+  const { date, title } = c.req.param()
+})
+
+// Chained routes
+app
+  .get('/endpoint', (c) => c.text('GET'))
+  .post((c) => c.text('POST'))
+  .delete((c) => c.text('DELETE'))
+```
+
+### Route Grouping
+
+```ts
+// Using route()
+const api = new Hono()
+api.get('/users', (c) => c.json([]))
+
+const app = new Hono()
+app.route('/api', api) // mounts at /api/users
+
+// Using basePath()
+const app = new Hono().basePath('/api')
+app.get('/users', (c) => c.json([])) // GET /api/users
+```
+
+### Error Handling
+
+```ts
+app.notFound((c) => c.json({ message: 'Not Found' }, 404))
+
+app.onError((err, c) => {
+  console.error(err)
+  return c.json({ message: 'Internal Server Error' }, 500)
+})
+```
+
+---
+
+## Context (c)
+
+### Response Methods
+
+```ts
+c.text('Hello') // text/plain
+c.json({ message: 'Hello' }) // application/json
+c.html('<h1>Hello</h1>') // text/html
+c.redirect('/new-path') // 302 redirect
+c.redirect('/new-path', 301) // 301 redirect
+c.body('raw body', 200, headers) // raw response
+c.notFound() // 404 response
+```
+
+### Headers & Status
+
+```ts
+c.status(201)
+c.header('X-Custom', 'value')
+c.header('Cache-Control', 'no-store')
+```
+
+### Variables (request-scoped data)
+
+```ts
+// In middleware
+c.set('user', { id: 1, name: 'Alice' })
+
+// In handler
+const user = c.get('user')
+// or
+const user = c.var.user
+```
+
+### Environment (Cloudflare Workers)
+
+```ts
+const value = await c.env.KV.get('key')
+const db = c.env.DATABASE
+c.executionCtx.waitUntil(promise)
+```
+
+### Renderer
+
+```ts
+app.use(async (c, next) => {
+  c.setRenderer((content) =>
+    c.html(
+      <html><body>{content}</body></html>
+    )
+  )
+  await next()
+})
+
+app.get('/', (c) => c.render(<h1>Hello</h1>))
+```
+
+---
+
+## HonoRequest (c.req)
+
+```ts
+c.req.param('id') // path parameter
+c.req.param() // all path params as object
+c.req.query('page') // query string parameter
+c.req.query() // all query params as object
+c.req.queries('tags') // multiple values: ?tags=A&tags=B → ['A', 'B']
+c.req.header('Authorization') // request header
+c.req.header() // all headers (keys are lowercase)
+
+// Body parsing
+await c.req.json() // parse JSON body
+await c.req.text() // parse text body
+await c.req.formData() // parse as FormData
+await c.req.parseBody() // parse multipart/form-data or urlencoded
+await c.req.arrayBuffer() // parse as ArrayBuffer
+await c.req.blob() // parse as Blob
+
+// Validated data (used with validator middleware)
+c.req.valid('json')
+c.req.valid('query')
+c.req.valid('form')
+c.req.valid('param')
+
+// Properties
+c.req.url // full URL string
+c.req.path // pathname
+c.req.method // HTTP method
+c.req.raw // underlying Request object
+```
+
+---
+
+## Middleware
+
+### Using Built-in Middleware
+
+```ts
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { basicAuth } from 'hono/basic-auth'
+import { prettyJSON } from 'hono/pretty-json'
+import { secureHeaders } from 'hono/secure-headers'
+import { etag } from 'hono/etag'
+import { compress } from 'hono/compress'
+import { poweredBy } from 'hono/powered-by'
+import { timing } from 'hono/timing'
+import { cache } from 'hono/cache'
+import { bearerAuth } from 'hono/bearer-auth'
+import { jwt } from 'hono/jwt'
+import { jwk } from 'hono/jwk'
+import { csrf } from 'hono/csrf'
+import { ipRestriction } from 'hono/ip-restriction'
+import { bodyLimit } from 'hono/body-limit'
+import { timeout } from 'hono/timeout'
+import { requestId } from 'hono/request-id'
+import { methodOverride } from 'hono/method-override'
+import { methodNotAllowed } from 'hono/method-not-allowed'
+import { languageDetector } from 'hono/language'
+import { some, every, except } from 'hono/combine'
+import { contextStorage, getContext } from 'hono/context-storage'
+import { trailingSlash, trimTrailingSlash } from 'hono/trailing-slash'
+
+// Registration
+app.use(logger()) // all routes
+app.use('/api/*', cors()) // specific path
+app.post('/api/*', basicAuth({ username: 'admin', password: 'secret' }))
+```
+
+### Custom Middleware
+
+```ts
+// Inline
+app.use(async (c, next) => {
+  const start = Date.now()
+  await next()
+  const elapsed = Date.now() - start
+  c.res.headers.set('X-Response-Time', `${elapsed}ms`)
+})
+
+// Reusable with createMiddleware
+import { createMiddleware } from 'hono/factory'
+
+const auth = createMiddleware(async (c, next) => {
+  const token = c.req.header('Authorization')
+  if (!token) return c.json({ error: 'Unauthorized' }, 401)
+  await next()
+})
+
+app.use('/api/*', auth)
+```
+
+### Middleware Execution Order
+
+Middleware executes in registration order. `await next()` calls the next middleware/handler, and code after `next()` runs on the way back:
+
+```
+Request → mw1 before → mw2 before → handler → mw2 after → mw1 after → Response
+```
+
+```ts
+app.use(async (c, next) => {
+  // before handler
+  await next()
+  // after handler
+})
+```
+
+---
+
+## Validation
+
+Validation targets: `json`, `form`, `query`, `header`, `param`, `cookie`.
+
+### Zod Validator
+
+```ts
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+const schema = z.object({
+  title: z.string().min(1),
+  body: z.string()
+})
+
+app.post('/posts', zValidator('json', schema), (c) => {
+  const data = c.req.valid('json') // fully typed
+  return c.json(data, 201)
+})
+```
+
+### Valibot / Standard Schema Validator
+
+```ts
+import { sValidator } from '@hono/standard-validator'
+import * as v from 'valibot'
+
+const schema = v.object({ name: v.string(), age: v.number() })
+
+app.post('/users', sValidator('json', schema), (c) => {
+  const data = c.req.valid('json')
+  return c.json(data, 201)
+})
+```
+
+---
+
+## JSX
+
+### Setup
+
+In `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}
+```
+
+Or use pragma: `/** @jsxImportSource hono/jsx */`
+
+**Important:** Files using JSX must have a `.tsx` extension. Rename `.ts` to `.tsx` or the compiler will fail.
+
+### Components
+
+```tsx
+import type { PropsWithChildren } from 'hono/jsx'
+
+const Layout = (props: PropsWithChildren) => (
+  <html>
+    <head>
+      <title>My App</title>
+    </head>
+    <body>{props.children}</body>
+  </html>
+)
+
+const UserCard = ({ name }: { name: string }) => (
+  <div class="card">
+    <h2>{name}</h2>
+  </div>
+)
+
+app.get('/', (c) => {
+  return c.html(
+    <Layout>
+      <UserCard name="Alice" />
+    </Layout>
+  )
+})
+```
+
+### jsxRenderer Middleware
+
+Use `jsxRenderer` middleware for layouts. For details, see https://hono.dev/docs/middleware/builtin/jsx-renderer
+
+### Async Components
+
+```tsx
+const UserList = async () => {
+  const users = await fetchUsers()
+  return (
+    <ul>
+      {users.map((u) => (
+        <li>{u.name}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Fragments
+
+```tsx
+const Items = () => (
+  <>
+    <li>Item 1</li>
+    <li>Item 2</li>
+  </>
+)
+```
+
+---
+
+## Streaming
+
+```ts
+import { stream, streamText, streamSSE } from 'hono/streaming'
+
+// Basic stream
+app.get('/stream', (c) => {
+  return stream(c, async (stream) => {
+    stream.onAbort(() => console.log('Aborted'))
+    await stream.write(new Uint8Array([0x48, 0x65]))
+    await stream.pipe(readableStream)
+  })
+})
+
+// Text stream
+app.get('/stream-text', (c) => {
+  return streamText(c, async (stream) => {
+    await stream.writeln('Hello')
+    await stream.sleep(1000)
+    await stream.write('World')
+  })
+})
+
+// Server-Sent Events
+app.get('/sse', (c) => {
+  return streamSSE(c, async (stream) => {
+    let id = 0
+    while (true) {
+      await stream.writeSSE({
+        data: JSON.stringify({ time: new Date().toISOString() }),
+        event: 'time-update',
+        id: String(id++)
+      })
+      await stream.sleep(1000)
+    }
+  })
+})
+```
+
+---
+
+## Testing with app.request()
+
+Test endpoints without starting an HTTP server:
+
+```ts
+// GET
+const res = await app.request('/posts')
+expect(res.status).toBe(200)
+expect(await res.json()).toEqual({ posts: [] })
+
+// POST with JSON
+const res = await app.request('/posts', {
+  method: 'POST',
+  body: JSON.stringify({ title: 'Hello' }),
+  headers: { 'Content-Type': 'application/json' }
+})
+
+// POST with FormData
+const formData = new FormData()
+formData.append('name', 'Alice')
+const res = await app.request('/users', { method: 'POST', body: formData })
+
+// With mock env (Cloudflare Workers bindings)
+const res = await app.request('/api/data', {}, { KV: mockKV, DATABASE: mockDB })
+
+// Using Request object
+const req = new Request('http://localhost/api', { method: 'DELETE' })
+const res = await app.request(req)
+```
+
+---
+
+## Hono Client (RPC)
+
+Type-safe API client using shared types between server and client.
+
+**IMPORTANT: Routes MUST be chained for type inference to work. Without chaining, the client cannot infer route types.**
+
+```ts
+// Server: routes MUST be chained to preserve types
+const route = app
+  .post('/posts', zValidator('json', schema), (c) => {
+    return c.json({ ok: true }, 201)
+  })
+  .get('/posts', (c) => {
+    return c.json({ posts: [] })
+  })
+export type AppType = typeof route
+
+// Client: use hc() with the exported type
+import { hc } from 'hono/client'
+import type { AppType } from './server'
+
+const client = hc<AppType>('http://localhost:8787/')
+const res = await client.posts.$post({ json: { title: 'Hello' } })
+const data = await res.json() // fully typed
+```
+
+Type utilities:
+
+```ts
+import type { InferRequestType, InferResponseType } from 'hono/client'
+
+type ReqType = InferRequestType<typeof client.posts.$post>
+type ResType = InferResponseType<typeof client.posts.$post, 200>
+```
+
+---
+
+## Helpers
+
+Helpers are utility functions imported from `hono/<helper-name>`:
+
+```ts
+import { getConnInfo } from 'hono/conninfo'
+import { getCookie, setCookie, deleteCookie } from 'hono/cookie'
+import { css, Style } from 'hono/css'
+import { createFactory } from 'hono/factory'
+import { html, raw } from 'hono/html'
+import { stream, streamText, streamSSE } from 'hono/streaming'
+import { testClient } from 'hono/testing'
+import { upgradeWebSocket } from 'hono/cloudflare-workers' // or other adapter
+```
+
+Available helpers: Accepts, Adapter, ConnInfo, Cookie, css, Dev, Factory, html, JWT, Proxy, Route, SSG, Streaming, Testing, WebSocket.
+
+For details, see `https://hono.dev/docs/helpers/<helper-name>` (fetch with `Accept: text/markdown`).
+
+### Factory
+
+Use `createFactory` to define `Env` once and share it across app, middleware, and handlers:
+
+```ts
+import { createFactory } from 'hono/factory'
+
+const factory = createFactory<Env>()
+
+// Create app (Env type is inherited)
+const app = factory.createApp()
+
+// Create middleware (Env type is inherited, no need to pass generics)
+const mw = factory.createMiddleware(async (c, next) => {
+  await next()
+})
+
+// Create handlers separately (preserves type inference)
+const handlers = factory.createHandlers(logger(), (c) => c.json({ message: 'Hello' }))
+app.get('/api', ...handlers)
+```
+
+---
+
+## Best Practices
+
+- Write handlers inline in route definitions for proper type inference of path params.
+- Use `app.route()` to organize large apps by feature, not Rails-style controllers.
+- Use `createFactory()` to share Env type across app, middleware, and handlers.
+- Use `c.set()`/`c.get()` to pass data between middleware and handlers.
+- Chain validators for multiple request parts (param + query + json).
+- Export app type for RPC: `export type AppType = typeof routes`
+- Use `app.request()` for testing — no server startup needed.
+
+## Adapters
+
+Hono runs on multiple runtimes. The default export works for Cloudflare Workers, Deno, and Bun. For Node.js, use the Node adapter:
+
+```ts
+// Cloudflare Workers / Deno / Bun
+export default app
+
+// Node.js
+import { serve } from '@hono/node-server'
+serve(app)
+```
diff --git a/.agents/skills/interface-design/SKILL.md b/.agents/skills/interface-design/SKILL.md
new file mode 100644
index 0000000..92e1df4
--- /dev/null
+++ b/.agents/skills/interface-design/SKILL.md
@@ -0,0 +1,320 @@
+---
+name: interface-design
+description: Craft-first interface design for dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces, and interactive products. Use when designing, building, reviewing, auditing, or refining product UI where visual craft, layout hierarchy, tokens, states, visual direction, or design-system consistency matter. Not for marketing pages, landing pages, campaigns, or brand-only work.
+---
+
+# Interface Design
+
+Build product interfaces with the craft of a top design team — Linear, Vercel, Stripe, Apple. The difference between those and generic output is not talent. It is that every decision was *decided*, the hierarchy is unmistakable, and a hundred small details are correct at once. This skill is how you get there.
+
+## Scope
+
+**Use for:** Dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces.
+
+**Not for:** Landing pages, marketing sites, campaigns, brand-only work. Use a marketing/frontend design skill for those.
+
+This skill is self-contained: direction, visual hierarchy, design-system architecture, and the polish and motion essentials needed to ship production-grade UI all live here.
+
+---
+
+# The Problem
+
+You will generate generic output. Your training has seen thousands of dashboards, and the patterns are strong. You can follow this entire process — explore the domain, name a signature, state your intent — and still produce a template: warm colors on cold structures, friendly fonts on generic layouts.
+
+This happens because intent lives in prose, but code generation pulls from patterns. The gap between them is where defaults win. Process helps, but it doesn't guarantee craft. You have to catch yourself, and you have to know the concrete moves that defaults don't.
+
+**The bar:** If another AI, given a similar prompt, would produce substantially the same output, you have failed. Not different for its own sake — different because the interface emerged from *this* user, *this* task, *this* world. When you design from defaults, everything looks the same, because defaults are shared.
+
+---
+
+# Where Defaults Hide
+
+Defaults disguise themselves as infrastructure — the parts that feel like they just need to work, not be designed.
+
+- **Typography feels like a container.** But type isn't holding your design, it *is* your design. The weight of a headline, the personality of a label, the texture of a paragraph shape how the product feels before anyone reads a word. Reaching for your usual font means you're not designing.
+- **Navigation feels like scaffolding.** But navigation *is* the product — where you are, where you can go, what matters. A page floating in space is a component demo, not software.
+- **Data feels like presentation.** But a number on screen is not design. What does it *mean* to the person looking? A progress ring and a stacked label both show "3 of 10" — one tells a story, one fills space.
+- **Token names feel like implementation detail.** But `--ink` and `--parchment` evoke a world; `--gray-700` and `--surface-2` evoke a template. Someone reading only your tokens should guess what product this is.
+
+There are no structural decisions. Everything is design. The moment you stop asking "why this?" is the moment defaults take over.
+
+---
+
+# Intent First
+
+Before touching code, answer these. Keep it a compact working brief unless the direction needs user confirmation.
+
+- **Who is this human?** Not "users." The actual person. Where are they when they open this? What did they do 5 minutes ago, what will they do 5 minutes after? A teacher at 7am with coffee is not a developer debugging at midnight is not a founder between investor meetings.
+- **What must they accomplish?** The verb. Grade these submissions. Find the broken deployment. Approve the payment. The answer determines what leads, what follows, what hides.
+- **What should this feel like?** In words that mean something. "Clean and modern" means nothing — every AI says that. Warm like a notebook? Cold like a terminal? Dense like a trading floor? Calm like a reading app? This shapes color, type, spacing, density — everything.
+
+If the prompt is too vague to identify the human, task, and feel, ask one concise question. If context allows a responsible assumption, state it briefly and proceed.
+
+**Intent must be systemic.** Saying "warm" then using cold colors is not following through. If the intent is warm: surfaces, text, borders, accents, semantic colors, type — all warm. If dense: spacing, type size, information architecture — all dense. Check every token against the stated intent. For every choice — layout, color temperature, typeface, spacing scale, hierarchy — you must be able to say *why*. "It's common" or "it works" means you defaulted.
+
+---
+
+# Product Domain Exploration
+
+This is where defaults get caught — or don't. Generic path: Task type → visual template → theme. Crafted path: Task type → product domain → signature → structure + expression. The difference is time spent in the product's world before any visual thinking.
+
+**Produce all four before proposing any direction:**
+
+- **Domain** — concepts, metaphors, vocabulary from this product's world. Not features — territory. Minimum 5.
+- **Color world** — what colors exist *naturally* here? Not "warm" or "cool" — go to the actual world. If this product were a physical space, what would you see? List 5+.
+- **Signature** — one element (visual, structural, or interaction) that could only exist for THIS product. If you can't name one, keep exploring.
+- **Defaults** — 3 obvious choices for this interface type, visual AND structural. You can't avoid patterns you haven't named.
+
+**The test:** Read your proposal with the product name removed. Could someone identify what it's for? If not, explore deeper.
+
+---
+
+# Render It When You Can
+
+If an inline visual-rendering tool is available in the session (e.g. a `show_widget` / `visualize` tool that renders HTML or SVG inline in the conversation), prefer **showing** the design over describing it. A direction trapped in prose is a fraction as useful as one the person can look at. This is conditional: when no such tool is present (CI, headless agents, plain terminals), fall back to code, tokens, and a written proposal. Never assume the tool exists; check, then use it.
+
+Render at three moments:
+
+1. **Proposing a direction.** Alongside the Suggest + Ask block, render a small live specimen: the palette as actual swatches, the type scale in the real typeface, the surface-elevation steps as stacked cards, the signature element as a real component. The person should *see* "warm like a notebook," not read the words.
+2. **Designing a component.** Render the actual component (or a tight before/after, both variants side by side) so the craft decisions — spacing, borders, hierarchy, states — are visible, not asserted. Render the real states (default, hover, empty, error) where they matter.
+3. **Critiquing or auditing.** Render the current version and the improved version together so the gap is shown, not narrated.
+
+Rules when rendering:
+
+- The widget shows the **visual only**. All reasoning, the domain exploration, the rejected-defaults list, and the recommendation stay in your response text — never paste prose into the widget.
+- Match the rendering tool's own design-system contract (load its `read_me`/guidance if it has one). Use its theme variables so the specimen inherits light/dark mode and sits native in the host. Don't fight the host chrome.
+- The specimen must still pass the checks below. A rendered default is still a default — rendering is how craft gets *seen*, not a substitute for it.
+- This renders to the *conversation*, not the project. The actual implementation still lands in the codebase through normal edits.
+
+The point: collapse the loop between "here's my thinking" and "here's what it looks like" into a single message the person can react to.
+
+---
+
+# Visual Hierarchy & Composition
+
+The single biggest driver of "this looks designed" versus "this looks generated." Defaults produce *flatness* — everything the same size, weight, and spacing, so nothing leads and the eye has nowhere to go. Craft produces *hierarchy* — the eye knows instantly what matters. These are concrete moves, not vibes.
+
+## One focal point per view
+
+Every screen has one thing the user came to do. That thing dominates — through size, contrast, position, or the space around it. When everything competes equally, nothing wins and the interface reads like a parking lot. Before building, name the focal element out loud. Then make it win: bigger, higher-contrast, or ringed in whitespace. Demote everything else deliberately.
+
+## Type scale is a ratio, and weight beats size
+
+Don't pick sizes by feel. Pick a ratio and step it: ~1.2 (minor third) for dense/calm UI, ~1.25 for most product UI, ~1.333 for expressive. From a 14–16px body that yields a *visibly* distinct scale, not 15/16/17 mush. A 14px base at 1.25: `caption 11 · body 14 · h4 16 · h3 18 · h2 22 · h1 28 · display 44+`. Round to whole pixels and to your spacing grid.
+
+The Apple/Linear move: **weight and color do more hierarchy work than size.** A single 14px size holds three tiers through weight + opacity alone — `value: 600 / primary`, `label: 500 / secondary`, `meta: 400 / muted` — separating more cleanly than two regular weights two points apart. Build from three levers together (size, weight, color/opacity), never size alone. If you squint and can't tell headline from body from label, the hierarchy is too weak.
+
+Worked example — a metric, flat vs decided. *Flat:* `Revenue` / `$48,200` both 14px regular gray, three identical boxes, no focal point. *Decided:* `REVENUE` 11px/500/muted/tracked · `$48,200` 28px/600/primary/tabular-nums (the hero) · `↑12%` 12px/500/success. Same data, opposite legibility — the figure leads through size+weight+one accent, the label is demoted, secondary metrics drop to a lower tier.
+
+## Density is a decision, expressed in px
+
+Linear is tight; Stripe is airy. Neither is default — both are *chosen*, and the choice is the same number repeated everywhere. Decide the density up front and name the values: a tool panel at 12–16px padding feels workbench-tight; the same card at 24px feels like a brochure. The same number can be right in one context and lazy in another. Pick deliberately, then hold it.
+
+## Spatial rhythm — breathe unevenly
+
+Great interfaces don't space everything equally. Dense control zones give way to open content; heavy elements balance against light ones; the eye travels with purpose. Monotone layouts — same card size, same gap, same density everywhere — are the sound of no one deciding. Vary the rhythm on purpose: group tightly-related things, then put real air between groups.
+
+## Proportions speak
+
+A 280px sidebar next to full-width content says "navigation serves content." A 360px sidebar says "these are peers." The specific number declares what matters. If you can't articulate what a proportion is saying, it isn't saying anything. Choose widths and ratios that state a relationship.
+
+## Distribution and restraint (the "expensive" look)
+
+- **~60/30/10**: a dominant neutral surface, a secondary tone, and ~10% accent. Color is a scarce resource — most of the screen is structure.
+- **One accent, used with intention**, beats five colors used without thought. Gray builds structure; color *communicates* (status, action, identity). Unmotivated color is noise.
+- **Hierarchy through space and weight, not lines.** Reach for whitespace and tonal shift before borders and dividers. The most premium interfaces are mostly invisible structure.
+- **Optical sizing on large type**: tighten letter-spacing as type gets bigger (headings slightly negative tracking); loosen line-height on body for readability (~1.5). Tight type reads as crafted; default tracking on a 32px heading reads as a document.
+
+---
+
+# Craft Foundations
+
+## Subtle Layering (the backbone)
+
+Regardless of direction, this applies to everything. You should *barely notice the system working* — when you look at Vercel's dashboard you don't think "nice borders," you just understand the structure. Invisible craft is working craft.
+
+**Surface elevation.** Surfaces stack: a dropdown sits above a card sits above the page. Build a numbered system — base, then increasing levels. Each jump is only a few percentage points of lightness — e.g. dark mode base → +7% → +9% → +12%; light mode stays light and adds shadow instead. You can barely see one step in isolation, but stacked, the hierarchy emerges. Whisper-quiet shifts you feel rather than see.
+
+- **Sidebars:** same background as canvas, not a different color. Different colors fragment the space into "sidebar world" and "content world." A subtle border is enough.
+- **Dropdowns/popovers:** one level above their parent surface, or they blend in and layering is lost.
+- **Inputs:** slightly *darker* than surroundings, not lighter. Inputs are inset — they receive content. A darker fill signals "type here" without heavy borders.
+
+**Borders.** Should disappear when you're not looking for them, but be findable when you need structure. Low-opacity rgba blends with the background and defines an edge without demanding attention; solid hex borders look harsh by comparison. Dark mode lives around `rgba(255,255,255,0.06–0.12)`, light mode slightly higher. Build a progression — standard, softer separation, emphasis, focus-ring — and match intensity to the importance of the boundary.
+
+**The squint test:** blur your eyes at the interface. You should still perceive hierarchy — what's above what, where sections divide — but nothing should jump out. No harsh lines, no jarring shifts. Just quiet structure. Get this wrong and nothing else matters.
+
+## Infinite Expression
+
+Every pattern has infinite expressions — **no two interfaces should look the same.** A metric display could be a hero number, inline stat, sparkline, gauge, progress bar, comparison delta, or trend badge. Same sidebar width, same card grid, same icon-left-number-big-label-small metric boxes every time *signals AI-generated immediately* and is forgettable. Linear's cards don't look like Notion's; Vercel's metrics don't look like Stripe's. Same concepts, infinite expressions. Before building, ask: what's the ONE thing users do here, and what product solves a similar problem brilliantly?
+
+## Color Lives Somewhere
+
+Every product exists in a world, and that world has colors. Before reaching for a palette, walk into the physical version of this space — what materials, what light, what objects? Your palette should feel like it came FROM somewhere, not applied TO something. Temperature is one axis; also ask quiet or loud, dense or spacious, serious or playful, geometric or organic. A trading terminal and a meditation app are both "focused" — completely different kinds of focus.
+
+---
+
+# Before Writing Each Component
+
+**Every time** you write UI code — even small additions — state:
+
+```
+Intent:     [who is this human, what must they do, how should it feel]
+Hierarchy:  [the focal element, and how it wins — size / weight / contrast / space]
+Palette:    [colors from your exploration — and WHY they fit this world]
+Depth:      [borders / subtle shadows / layered — and WHY it fits the intent]
+Surfaces:   [your elevation scale — and WHY this temperature]
+Typography: [typeface + the size/weight/color levers — and WHY]
+Spacing:    [base unit + chosen density]
+```
+
+This checkpoint is mandatory. If you can't explain WHY for each, you're defaulting — stop and think.
+
+---
+
+# Use What Exists
+
+The most common way AI degrades a codebase: it hand-rolls what already exists. A bespoke `<div onClick>` "button" beside the project's real `Button`. A from-scratch dropdown with no keyboard support beside an installed primitive that has it. A 14-class Tailwind string copy-pasted onto every card instead of the component or token that's right there. Every one of these is the same failure — generating new instead of using what's present — and the result is inconsistent, inaccessible, and unmaintainable. **Before you build a control or style an element, look at what the project already gives you.**
+
+## Controls: native → primitive → hand-roll
+
+1. **Native HTML first** where it works. A `<button>` is a button; an `<a>` is a link; `<input type="text">`, `<dialog>`, `<details>` exist. Never `<div onClick>` something the platform already provides — you lose focus, keyboard, and semantics for free.
+2. **A battle-tested headless primitive** for anything stateful and hard to get right — select, combobox, dialog, popover, tooltip, dropdown menu, tabs, date picker. These ship keyboard navigation, focus management, ARIA, and collision/positioning that take days to reproduce correctly. Reach for what the ecosystem already trusts (e.g. Radix UI, React Aria, Ark, Headless UI, Vaul, `cmdk` in React; the equivalent accessible primitive in other frameworks), then style it to your direction. "Build custom" means *compose and style a primitive*, not write the behavior from scratch.
+3. **Hand-roll only as a genuine last resort** — no primitive fits, or there's no dependency budget. Then you owe the complete behavior contract: keyboard nav (arrow keys, Enter, Escape), focus trap/return, full ARIA roles and state, click-outside, and scroll-lock for overlays. A styled control missing these is broken, however good it looks.
+
+## Styling: system → component → token → utility
+
+1. **If the project has a design system, use it.** shadcn/`Button`, a CVA variant set, a theme, a component library — use `<Button variant="…">` and the existing variants before writing a one-off. Match the codebase's styling convention (Tailwind, CSS modules, CSS-in-JS), don't introduce your own.
+2. **When a styled element repeats, extract a component.** The same utility string on nine buttons is duplication, not design. One component (or one CVA/variant) owns it; call sites stay clean. Extract on the second real reuse, not the first.
+3. **Bind to semantic tokens, not hardcoded literals.** `bg-card border-border text-muted-foreground`, not `bg-white border-gray-200 text-gray-500`. Hardcoded `gray-200`/`#fff`/`px-4` raw values are the Tailwind form of random hex — they break theming and dark mode and signal no system. (See Token Architecture below.)
+4. **Inline utilities are for genuine one-offs** — a layout nudge used once. The tell of slop is the *same* long className sprayed everywhere; that's a missing component or token, not styling.
+
+---
+
+# Design System Essentials
+
+The token, spacing, and depth architecture beneath every craft decision.
+
+- **Token architecture.** Every color traces to a small set of primitives: foreground (text), background (surface), border, brand, semantic (destructive/warning/success). No random hex — everything maps to primitives.
+- **Text hierarchy — four levels.** Primary, secondary, tertiary, muted (default / supporting / metadata / disabled). Using only two means the hierarchy is too flat.
+- **Spacing.** Pick a base unit (4 or 8px), use multiples only. Scale by context: micro (icon gaps), component (within buttons/cards), section (between groups), major (between areas). Random values signal no system.
+- **Padding.** Symmetrical — if one side has a value, the others match unless content genuinely demands asymmetry.
+- **Depth — choose ONE and commit.** Borders-only (clean, technical, dense tools) · subtle shadows (approachable) · layered shadows (premium, dimensional) · surface-color shifts (tints, no shadows). Don't mix strategies.
+- **Border radius — a scale.** Small for inputs/buttons, medium for cards, large for modals. Don't mix sharp and soft randomly.
+- **Control tokens.** Inputs/selects/checkboxes get dedicated background, border, and focus tokens — don't reuse surface tokens, so you can tune controls independently. Native `<select>`/`<input type="date">` can't be styled — compose a headless primitive instead of hand-rolling one (see "Use What Exists").
+- **Dark mode.** Shadows are weak on dark — lean on borders. Desaturate semantic colors slightly. Same hierarchy system, inverted values. Keep one hue; shift only lightness across surfaces.
+
+---
+
+# Polish & Motion Essentials
+
+A hundred small details compound into "feels great." These are the highest-leverage ones — enough to ship genuinely polished UI.
+
+## Static polish
+
+- **Concentric radius.** Nested rounded elements: `outerRadius = innerRadius + padding`. Same radius on parent and child is the most common thing that makes UI feel off.
+- **Tabular numbers.** Any dynamic number (counters, prices, timers, table columns) gets `font-variant-numeric: tabular-nums` to prevent layout shift.
+- **Optical alignment.** When geometric centering looks off, fix it optically — icon-side padding ≈ text-side − 2px; nudge play triangles ~2px right.
+- **States are not optional.** Every interactive element needs default, hover, active, focus, disabled. Data needs loading, empty, error. Missing states feel broken — they're the fastest tell of an unfinished interface.
+- **Hit areas — 44×44px (WCAG), 40 at minimum.** If the visible control is smaller (a 20px checkbox), extend with a pseudo-element. Never let two hit areas overlap.
+- **Shadows over borders for elevation.** For cards/buttons/containers that lift, prefer a layered transparent `box-shadow` (it adapts to any background); keep real borders for dividers and input outlines. Light-mode lift stacks three layers — a 1px ring + two soft depths, e.g. `0 0 0 1px rgba(0,0,0,.06), 0 1px 2px -1px rgba(0,0,0,.06), 0 2px 4px rgba(0,0,0,.04)`; dark mode collapses to a single ring `0 0 0 1px rgba(255,255,255,.08)` (depth shadows don't read on dark).
+- **Text wrapping.** `text-wrap: balance` on headings; `text-wrap: pretty` on body/captions to kill orphans.
+- **Font smoothing.** `-webkit-font-smoothing: antialiased` on the root (macOS renders heavy otherwise).
+- **Image outlines.** 1px inset outline, pure `rgba(0,0,0,0.1)` light / `rgba(255,255,255,0.1)` dark — never a tinted near-black/white (reads as dirt on the edge).
+
+## Motion
+
+Motion should be felt, not watched. Fast, purposeful, and *never* in the way.
+
+- **Should it animate at all?** Actions repeated 100+×/day (keyboard shortcuts, command palette) get **no** animation — it makes them feel slow. Occasional surfaces (modals, drawers, toasts) get standard animation. Rare/first-run moments can add delight.
+- **Duration < 300ms** for UI. Button press 100–160ms; tooltips/popovers 125–200ms; dropdowns 150–250ms; modals/drawers 200–500ms. A 180ms dropdown feels more responsive than a 400ms one.
+- **Custom ease-out, never ease-in.** Built-in curves are too weak. Use `cubic-bezier(0.23, 1, 0.32, 1)` for entering/interactive; ease-in-out (`cubic-bezier(0.77, 0, 0.175, 1)`) for on-screen movement. `ease-in` delays the first frame — the moment the user is watching — and feels sluggish.
+- **Press feedback.** `transform: scale(0.97)` on `:active` (never below 0.95). Tactile confirmation the UI heard the click.
+- **Never animate from `scale(0)`.** Nothing appears from nothing — start at `scale(0.95)` + `opacity: 0`.
+- **Origin-aware popovers.** Popovers scale from their trigger (`transform-origin` set to the trigger), not center. Modals are the exception — they stay centered.
+- **Only animate `transform` and `opacity`** (GPU-composited). Animating width/height/margin/padding triggers layout + paint and drops frames. Never `transition: all` — name exact properties.
+- **Stagger entrances** 30–80ms between items for a natural cascade; keep exits faster and subtler than enters.
+- **Respect `prefers-reduced-motion`** — keep opacity/color transitions, drop movement.
+
+---
+
+# Avoid
+
+- **Harsh borders** — if borders are the first thing you see, they're too strong
+- **Dramatic surface jumps** — elevation should be whisper-quiet
+- **Flat hierarchy** — everything one size/weight; no clear focal point
+- **Monotone layout** — same card size, gap, and density everywhere
+- **Inconsistent spacing** — the clearest sign of no system
+- **Mixed depth strategies** — pick one and commit
+- **Missing states** — hover, focus, disabled, loading, empty, error
+- **Dramatic drop shadows** — subtle, not attention-grabbing
+- **Large radius on small elements**; **thick decorative borders**
+- **Gradients and color for decoration** — color should mean something
+- **Multiple accent colors** — dilutes focus
+- **Different hues for different surfaces** — keep one hue, shift only lightness
+- **Default typography** — system/Inter fonts and size-only hierarchy where a direction was set
+- **Structural hacks** — negative margins undoing parent padding, escape-hatch `calc()`, absolute positioning to dodge layout flow
+
+---
+
+# Workflow
+
+## Communication
+Be invisible. Don't announce modes or narrate process. Never say "I'm in ESTABLISH MODE" or "Let me check system.md." Jump into the work; state suggestions with reasoning.
+
+## Execution discipline
+Use this skill as a working discipline, not just advice. When editing UI:
+
+1. Inspect the existing app, design tokens, component patterns, and `.interface-design/system.md` if present.
+2. Make the domain exploration concrete before choosing layout, color, type, density, and navigation.
+3. For greenfield screens, major redesigns, or vague direction, consider a visual reference pass *if an image-generation tool is available* (skip otherwise — it's a companion, never the deliverable). Four modes: **direction board** (2–3 abstract mood/material/color explorations before code — no real UI), **UI reference** (medium-fidelity composition for a chosen direction), **paintover** (a stronger version of an existing screenshot), **raster asset** (empty-state art, textures — never icons/logos/charts). Always reject generic SaaS, illegible text, off-domain palettes; extract palette/density/proportions/signature, then build it in real code and verify in the browser.
+4. Patch the implementation, then run the relevant build/typecheck/tests when available.
+5. Verify visually for non-trivial UI. Use the inline render tool, a local browser, or screenshots at desktop and mobile widths; fix overlap, broken spacing, blank states, unreadable text, missing assets, and generic composition before presenting.
+6. Keep user-facing updates short. Don't expose long private design monologues — surface the useful recommendation or decision.
+
+## Suggest + Ask
+Lead with exploration and recommendation, then confirm:
+
+```
+Domain:     [5+ concepts from the product's world]
+Color world:[5+ colors that exist in this domain]
+Signature:  [one element unique to this product]
+Rejecting:  [default 1] → [alternative], [default 2] → [alternative], [default 3] → [alternative]
+Direction:  [approach connecting to the above]
+```
+
+Then ask: "Does that direction feel right?" If an inline render tool is available, render a live specimen of the direction in the same message — show the palette, type, and signature, don't just name them.
+
+## Build flow
+- **If `.interface-design/system.md` exists:** read it and apply — decisions are made.
+- **If not:** explore domain (all four outputs) → propose (reference all four) → confirm when the direction is ambiguous or costly to change → build → run the checks below → offer to save.
+
+## The checks (before showing)
+Run these against your output; if any fails, iterate before presenting.
+
+- **Swap test** — swap your typeface for the usual one, your layout for a standard template: would anything feel different? Where swapping wouldn't matter is where you defaulted.
+- **Squint test** — blur your eyes: hierarchy still readable? Nothing jumping out harshly?
+- **Signature test** — point to five specific elements where your signature appears. "The overall feel" doesn't count.
+- **Token test** — read your CSS variables aloud: do they belong to this product's world, or any project?
+
+---
+
+# After Completing a Task
+
+Always offer to save: "Want me to save these patterns for future sessions?" If yes, write to `.interface-design/system.md`:
+
+- Direction and feel
+- Depth strategy (borders/shadows/layered) and spacing base unit
+- Hierarchy decisions (type scale ratio, density values, focal pattern)
+- Key component patterns — add when a component is used 2+ times, is reusable, or has measurements worth remembering (not one-offs or prop variations). Record the values, e.g. `Button primary — 36px h · 12px 16px pad · 6px radius · 14px/500`.
+- Visual direction notes and selected references when an image pass shaped the design
+
+**Consistency checks.** If system.md defines values, hold to them: spacing on the grid, the declared depth strategy throughout, colors from the palette, documented patterns reused not reinvented. This compounds — each save makes future work faster and more consistent.
+
+---
+
+# Commands
+
+- `/interface-design:design-review` — strict craft + hierarchy review of a build, with an approval bar; renders before/after when possible
+- `/interface-design:design-deslop` — fast, diff-scoped pass that strips visual slop from a branch
+
+If a user asks for design status, audit, or pattern extraction in natural language: read `.interface-design/system.md` and summarize it, check UI files against it for drift, or scan for repeated spacing/radius/color/component values and propose a system.md — perform the equivalent inline.
diff --git a/.agents/skills/interface-design/agents/openai.yaml b/.agents/skills/interface-design/agents/openai.yaml
new file mode 100644
index 0000000..69138ea
--- /dev/null
+++ b/.agents/skills/interface-design/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Interface Design"
+  short_description: "Craft-first product UI guidance"
+  default_prompt: "Use $interface-design to design or refine a product interface with a domain-specific visual system and image-based references when useful."
+policy:
+  allow_implicit_invocation: true
diff --git a/.agents/skills/make-interfaces-feel-better/SKILL.md b/.agents/skills/make-interfaces-feel-better/SKILL.md
new file mode 100644
index 0000000..e47b87b
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/SKILL.md
@@ -0,0 +1,187 @@
+---
+name: make-interfaces-feel-better
+description: >-
+  Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, typography, icons, micro-interactions, enter/exit animations, or any visual detail work. Supports quick and full review modes. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, font smoothing, tabular numbers, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.
+---
+
+# Details that make interfaces feel better
+
+Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code. Before suggesting or writing a fix, identify the project's existing styling system and express the change in that system: Tailwind in a Tailwind project, plain CSS in a CSS project, or the established CSS-in-JS approach. Never introduce a second styling system just to apply a polish fix.
+
+When reviewing, slow the interface down: replay motion at 10% speed in the browser's Animations panel and walk every state: hover, focus, active, loading, empty. What feels off at 10% speed is what's subtly wrong at full speed.
+
+## Quick Reference
+
+| Category | When to Use |
+| --- | --- |
+| [Typography](typography.md) | Text wrapping, font smoothing, tabular numbers |
+| [Surfaces](surfaces.md) | Border radius, optical alignment, shadows, image outlines, hit areas |
+| [Animations](animations.md) | Interruptible animations, enter/exit transitions, icon animations, scale on press, motion restraint |
+| [Icons](icons.md) | Icon stroke weight, states via `currentColor`, outline vs fill, sizing, RTL flipping |
+| [Performance](performance.md) | Transition specificity, `will-change` usage |
+
+## Core Principles
+
+### 1. Concentric Border Radius
+
+Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off.
+
+### 2. Optical Over Geometric Alignment
+
+When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment.
+
+### 3. Shadows for Elevation, Borders for Structure
+
+For buttons, cards, and containers whose border exists only to create depth, prefer layered transparent `box-shadow` values. Keep borders that communicate structure or state: dividers, layout separators, and selected or focus states.
+
+### 4. Interruptible Animations
+
+Use CSS transitions for interactive state changes — they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.
+
+### 5. Split and Stagger Enter Animations
+
+For an infrequent staged entrance where sequence helps communicate hierarchy, break content into semantic chunks and stagger them by ~100ms instead of animating one container. Do not stagger routine, high-frequency interactions.
+
+### 6. Subtle Exit Animations
+
+Use a small fixed `translateY` instead of full height. Exits should be softer than enters. Use `ease-out` for both enter and exit transitions.
+
+### 7. Contextual Icon Animations
+
+Animate icons with `opacity`, `scale`, and `blur` instead of toggling visibility. Use exactly these values: scale from `0.25` to `1`, opacity from `0` to `1`, blur from `4px` to `0px`. If the project has `motion` or `framer-motion` in `package.json`, match that package's import path (or the established nearby imports when both exist) and use `transition: { type: "spring", duration: 0.3, bounce: 0 }` — bounce must always be `0`. If no motion library is installed, keep both icons in the DOM (one absolute-positioned) and cross-fade with CSS transitions using `cubic-bezier(0.2, 0, 0, 1)` — this gives both enter and exit animations without any dependency.
+
+### 8. Font Smoothing
+
+Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text.
+
+### 9. Tabular Numbers
+
+Use `font-variant-numeric: tabular-nums` for any dynamically updating numbers to prevent layout shift.
+
+### 10. Text Wrapping
+
+Use `text-wrap: balance` on headings. Use `text-wrap: pretty` for body text to avoid orphans.
+
+### 11. Image Outlines
+
+Add a subtle `1px` outline with low opacity to images for consistent depth. The color must be pure black in light mode (`oklch(0 0 0 / 0.1)`) and pure white in dark mode (`oklch(1 0 0 / 0.1)`), never a near-black like slate, zinc, or any tinted neutral. A tinted outline picks up the surface color underneath it and reads as dirt on the image edge.
+
+### 12. Scale on Press
+
+A subtle `scale(0.96)` on click gives buttons tactile feedback. Always use `0.96`. Never use a value smaller than `0.95` — anything below feels exaggerated. Add a `static` prop to disable it when motion would be distracting.
+
+### 13. Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations.
+
+### 14. Never Use `transition: all`
+
+Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.
+
+### 15. Use `will-change` Sparingly
+
+Only for `transform`, `opacity`, `filter` — properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter.
+
+### 16. Minimum Hit Area
+
+Interactive elements should prefer a 44×44px hit area for touch or mobile contexts. In dense desktop interfaces, use at least 40×40px. Extend with a pseudo-element if the visible element is smaller. Never let hit areas of two elements overlap.
+
+### 17. Match Icon Stroke to Text Weight
+
+An icon next to text carries the text's optical weight: `1.5px` stroke beside regular (400) text, `2px` beside semibold (600). One stroke weight per icon set; never mix libraries on one surface.
+
+### 18. One SVG, Recolored per State
+
+Icons use `currentColor` and get their states (hover, selected, disabled) from CSS color and opacity, never from separate assets. Outline variant is the default; fill variant marks the active state.
+
+### 19. Motion Restraint
+
+No custom animation on high-frequency interactions: the attention cost repeats on every trigger. Motion is never the only feedback channel; every animated state change also needs a static cue such as color, icon, or label.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Same border radius on parent and child | Calculate `outerRadius = innerRadius + padding` |
+| Icons look off-center | Adjust optically with padding or fix SVG directly |
+| Border used only to fake elevation | Use layered `box-shadow` with transparency; keep structural and state borders |
+| Jarring staged entrance or contextual exit | Stagger infrequent entrances and keep context-preserving exits subtle |
+| Numbers cause layout shift | Apply `tabular-nums` |
+| Heavy text on macOS | Apply `antialiased` to root |
+| Animation plays on page load | Add `initial={false}` to `AnimatePresence` |
+| `transition: all` on elements | Specify exact properties |
+| First-frame animation stutter | Add `will-change: transform` (sparingly) |
+| Tiny hit areas on small controls | Extend with a pseudo-element to 44×44px for touch/mobile, or at least 40×40px in dense desktop UI |
+| Hairline icon beside bold text | Match the stroke width to the text weight |
+| Separate icon assets per state | One `currentColor` SVG, states via CSS |
+| Filled icons everywhere | Outline as default, fill only for the active state |
+| Entrance animation on every hover or keystroke | Instant feedback or ≤150ms opacity/color transition |
+
+## Review Output Format
+
+Use `full` when no review mode is supplied.
+
+| Mode | Coverage | Finding cap |
+| --- | --- | --- |
+| `quick` | Primary user path and highest-traffic states; report only `HIGH` and `MEDIUM` issues | 5 |
+| `full` | Entire requested scope across typography, surfaces, animations, icons, and performance | 15 |
+
+### Scope and Coverage
+
+State the mode, exact scope, framework, styling conventions, and any review boundary. Show what was actually inspected:
+
+| Category | Evidence inspected | Result |
+| --- | --- | --- |
+| Typography | Files, components, states, or checks | Findings count, `Clear`, or `Not reviewed` with a reason |
+
+Include all five Quick Reference categories. Never imply an uninspected surface was reviewed.
+
+### Findings
+
+Group findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Include every change made or proposed, not a subset. Never use separate "Before:" / "After:" lines.
+
+- **Severity**: `HIGH` makes an interaction inaccessible, misleading, unreadable, or repeatedly disruptive; `MEDIUM` creates a noticeable usability or consistency problem; `LOW` is isolated polish and appears only in `full` mode.
+- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.
+- **Before / After**: show the current implementation and an actionable replacement.
+- **Why**: name the violated principle and explain its user impact.
+
+Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings and never pad the report to reach the cap.
+
+### Example
+
+#### Concentric border radius
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Card.tsx:28` | `rounded-xl` on card + `rounded-xl` on inner button (`p-2`) | `rounded-2xl` on card (`8 + 8 = 16`), `rounded-lg` on inner button | Nested corners should be concentric |
+| LOW | `src/card.css:11` | `border-radius: 16px` on both nested surfaces | Outer `24px`, inner `16px` with `8px` padding | Equal nested radii make the inner surface look pinched |
+
+#### Tabular numbers
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| MEDIUM | `src/Counter.tsx:17` | `<span>{count}</span>` | `<span className="tabular-nums">{count}</span>` | Proportional digits cause changing values to shift |
+| LOW | `src/timer.css:8` | Default numerals on a timer | Add `font-variant-numeric: tabular-nums` to the timer | Equal-width digits keep the timer stable |
+
+#### Scale on press
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+| LOW | `src/Button.tsx:19` | `<button className="...">` | Add `active:scale-[0.96] transition-transform` | Press feedback makes the control feel responsive |
+| MEDIUM | `src/button.css:24` | `scale(0.9)` on press | Raise to `scale(0.96)` | Anything below `0.95` feels exaggerated |
+
+### Considered but Rejected
+
+Include 1–3 real candidates in `quick` mode and 2–5 in `full` mode:
+
+| Location | Candidate | Rejected because |
+| --- | --- | --- |
+| `src/Card.tsx:28` | Increase the shadow | Existing depth matches the shared surface token; changing one card would reduce consistency |
+
+Do not invent filler. If the scope contains fewer borderline candidates, include the ones that exist and say so.
+
+### Verification and Verdict
+
+After the findings:
+
+1. **Verification**: list the exact commands or interactions run and their observed results. Walk every relevant state and inspect motion at 10% speed when animation is involved. If a check was not run, label it **Not verified** and state what remains.
+2. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain. List every unverified check beside the verdict.
+
+When there are no findings, omit the findings table, state "No actionable interface-polish findings", report verification and rejected candidates, and end with `Approve`.
diff --git a/.agents/skills/make-interfaces-feel-better/agents/openai.yaml b/.agents/skills/make-interfaces-feel-better/agents/openai.yaml
new file mode 100644
index 0000000..e4ce76a
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Make Interfaces Feel Better"
+  short_description: "Typography, surfaces, motion, icons and UI polish"
diff --git a/.agents/skills/make-interfaces-feel-better/animations.md b/.agents/skills/make-interfaces-feel-better/animations.md
new file mode 100644
index 0000000..d319874
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/animations.md
@@ -0,0 +1,403 @@
+# Animations
+
+Interruptible animations, enter/exit transitions, contextual icon animations, and motion restraint.
+
+## Interruptible Animations
+
+Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
+
+### CSS Transitions vs. Keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes — retargets mid-animation | No — restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Fixed; retargets the value mid-flight, not the timeline | Fixed timeline, restarts from the beginning |
+
+```css
+/* Good — interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses — no jank */
+```
+
+```css
+/* Bad — keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts — feels broken */
+```
+
+**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Enter Animations: Split and Stagger
+
+Use this pattern for infrequent staged entrances where sequence helps communicate hierarchy, such as the first load of a page hero, success state, or empty state. Break a large container into semantic chunks and animate each individually. Do not stagger routine interactions such as row hovers, keystrokes, or repeated tab changes.
+
+### Step by Step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
+
+### Code Example
+
+```tsx
+// Motion (Framer Motion) — staggered enter
+function PageHeader() {
+  return (
+    <motion.div
+      initial="hidden"
+      animate="visible"
+      variants={{
+        visible: { transition: { staggerChildren: 0.1 } },
+      }}
+    >
+      <motion.h1
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        Welcome
+      </motion.h1>
+
+      <motion.p
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        A description of the page.
+      </motion.p>
+
+      <motion.div
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        <Button>Get started</Button>
+      </motion.div>
+    </motion.div>
+  );
+}
+```
+
+### CSS-Only Stagger
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  filter: blur(4px);
+  animation: fadeInUp 400ms ease-out forwards;
+}
+
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 100ms; }
+.stagger-item:nth-child(3) { animation-delay: 200ms; }
+
+@keyframes fadeInUp {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+```
+
+## Exit Animations
+
+Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing — don't fight for attention.
+
+### Subtle Exit (Recommended)
+
+```tsx
+// Small fixed translateY — indicates direction without drama
+<motion.div
+  exit={{
+    opacity: 0,
+    y: -12,
+    filter: "blur(4px)",
+    transition: { duration: 0.15, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Full Exit (When Context Matters)
+
+```tsx
+// Slide fully out — use when spatial context is important
+// (e.g., a card returning to a list, a drawer closing)
+<motion.div
+  exit={{
+    opacity: 0,
+    x: "-100%",
+    transition: { duration: 0.2, ease: "easeOut" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Good vs. Bad
+
+```css
+/* Good — subtle exit */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-12px);
+  transition: opacity 150ms ease-out, transform 150ms ease-out;
+}
+
+/* Bad — dramatic exit that steals focus */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-100%) scale(0.5);
+  transition: all 400ms ease-out;
+}
+
+/* Sometimes correct — remove immediately when motion adds no context */
+.item-exit {
+  display: none;
+}
+```
+
+**Key points:**
+- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
+- Keep some directional movement to indicate where the element went
+- Exit duration should be shorter than enter duration (150ms vs 300ms)
+- Use a subtle exit when it preserves spatial context. Remove immediately when motion adds no information, the interaction repeats frequently, or reduced motion is requested.
+
+## Contextual Icon Animations
+
+When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
+
+### Motion Example
+
+This example uses the `motion` package. If the project instead has `framer-motion`, import the same APIs from `"framer-motion"`; never mix an installed package with the other package's import path.
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS Transition Approach (No Motion)
+
+If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
+
+The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them — the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
+
+### Choosing Between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade — icon never unmounts) |
+| **Spring physics** | Yes | No — use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+
+**Rule:** Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or from `"framer-motion"` when `framer-motion` is installed. If both exist, follow the imports already used by the component or its nearest peers. If neither is present, use the CSS cross-fade pattern — don't add a dependency just for icon transitions.
+
+### When to Animate Icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+**Important:** Always use exactly these values for contextual icon animations — do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }` — **bounce must always be `0`**, never `0.1` or any other value
+
+## Scale on Press
+
+A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95` — anything below feels exaggerated. Use CSS transitions for interruptibility — if the user releases mid-press, it should smoothly return.
+
+Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
+
+### CSS Example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion Example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static Prop Pattern
+
+Extract the scale class into a variable and conditionally apply it based on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load — only on subsequent state changes.
+
+### When It Works
+
+```tsx
+// Good — icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for: icon swaps, toggles, tabs, segmented controls — anything that has a default state on page load.
+
+### When It Breaks
+
+Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
+
+```tsx
+// Bad — initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.
+
+## Motion Restraint
+
+Motion is a budget, not a garnish:
+
+- **No custom animation on high-frequency interactions.** Repeated interactions get instant feedback or a minimal `opacity` or `background-color` transition at ≤150ms.
+- **Motion is never the only feedback channel.** Every animated state change also needs a static cue such as color, icon, or label.
+- **Brief and precise beats prominent.** If a shorter, smaller animation communicates the same thing, use it.
+- **Honor reduced-motion preferences.** Preserve the static cue and remove unnecessary movement.
+
+```css
+/* Good: high-frequency hover gets a minimal transition */
+.row:hover {
+  background-color: var(--surface-hover);
+  transition: background-color 100ms ease-out;
+}
+
+/* Bad: every hover replays a full entrance */
+.row:hover .row-icon {
+  animation: bounceIn 500ms;
+}
+```
diff --git a/.agents/skills/make-interfaces-feel-better/icons.md b/.agents/skills/make-interfaces-feel-better/icons.md
new file mode 100644
index 0000000..6bdc007
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/icons.md
@@ -0,0 +1,63 @@
+# Icons
+
+Icon weight, states, sizing, and direction: the details that make icons sit naturally in an interface.
+
+## Match Icon Stroke to Text Weight
+
+An icon next to text should carry the same optical weight as the text.
+
+| Adjacent text | Icon stroke width (24px grid) |
+| --- | --- |
+| Regular (400), 14–16px | `1.5px` |
+| Medium/Semibold (500–600) | `2px` |
+| Bold (700), or emphasized standalone | `2.5px` |
+
+Use one stroke weight per icon set on a surface. Size inline icons relative to the text's cap height, typically `1em`–`1.25em`.
+
+## One SVG, Recolored per State
+
+Use one SVG drawn with `currentColor`; let CSS drive hover, selected, and disabled states. Strip hardcoded `fill` and `stroke` colors when importing icons.
+
+```html
+<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
+```
+
+```css
+.icon-button { color: oklch(0.552 0.016 285.938); }
+.icon-button:hover { color: oklch(0.21 0.006 285.885); }
+.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
+.icon-button:disabled { opacity: 0.4; }
+```
+
+## Outline Default, Fill Active
+
+| Variant | Use for |
+| --- | --- |
+| Outline | Default state: toolbars, list rows, inline with text |
+| Fill | Selected or active state: active tab, toggled bookmark, liked heart |
+
+The swap between variants is a contextual icon animation; use the exact cross-fade values in [animations.md](animations.md).
+
+## Design at Render Size
+
+- Test every icon at the smallest size it will render, often `16px`.
+- Prefer simplified glyphs for small contexts over scaled-down detailed artwork.
+- Use the icon set's native grid sizes (`16`, `20`, `24`) rather than arbitrary fractional scales.
+- Use SVG rather than raster assets.
+
+## Icons in RTL
+
+| Flip | Don't flip |
+| --- | --- |
+| Back/forward arrows, navigation chevrons | Logos and brand marks |
+| Text alignment, lists, indent | Checkmarks |
+| Directional send glyphs | Clocks, cups, pencils |
+| Speaker waves tied to reading direction | Media playback controls |
+
+```css
+[dir="rtl"] .icon-directional {
+  scale: -1 1;
+}
+```
+
+Analyze composite icons part by part: an overlay may keep its position even when the base glyph flips. Give every icon-only control an accessible name and mark purely decorative icons hidden from assistive technology.
diff --git a/.agents/skills/make-interfaces-feel-better/performance.md b/.agents/skills/make-interfaces-feel-better/performance.md
new file mode 100644
index 0000000..c12257a
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/performance.md
@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition Only What Changes
+
+Never use `transition: all` or Tailwind's `transition-all`. Always specify the exact properties that change. Tailwind's bare `transition` maps to a curated default list of colors, opacity, shadow, and transforms, not to `all`; still prefer naming exactly what changes.
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS Example
+
+```css
+/* Good — only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad — transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good — explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad — transition all
+<button className="transition-all duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` Note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate` — it covers all transform-related properties, not just `transform`. Use this when you're only animating transforms. For multiple non-transform properties, use the bracket syntax: `transition-[scale,opacity,filter]`.
+
+## Use `will-change` Sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it, the browser promotes the element only when the animation starts — that one-time layer promotion can cause a micro-stutter on the first frame.
+
+This particularly helps when an element is changing `scale`, `rotation`, or moving around with `transform`. For other properties, it doesn't help much — the browser can't composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good — specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good — multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad — never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad — properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful Properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Newer Chromium only | Rarely; not reliable cross-browser |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to Skip
+
+Modern browsers are already good at optimizing on their own. Only add `will-change` when you notice first-frame stutter — Safari in particular benefits from it. Don't add it preemptively to every animated element; each extra compositing layer costs memory.
diff --git a/.agents/skills/make-interfaces-feel-better/surfaces.md b/.agents/skills/make-interfaces-feel-better/surfaces.md
new file mode 100644
index 0000000..e66d44c
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/surfaces.md
@@ -0,0 +1,256 @@
+# Surfaces
+
+Border radius, optical alignment, shadows, and image outlines.
+
+## Concentric Border Radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
+
+### Example
+
+```css
+/* Good — concentric radii */
+.card {
+  border-radius: 20px; /* 12 + 8 */
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+
+/* Bad — same radius on both */
+.card {
+  border-radius: 12px;
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+// Good — outer radius accounts for padding
+<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
+  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad — same radius on both
+<div className="rounded-xl p-2">
+  <div className="rounded-xl">          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched border radii on nested elements is one of the most common things that makes interfaces feel off. Always calculate concentrically.
+
+## Optical Alignment
+
+When geometric centering looks off, align optically instead.
+
+### Buttons with Text + Icon
+
+Use slightly less padding on the icon side to make the button feel balanced. A reliable rule of thumb is:
+`icon-side padding = text-side padding - 2px`.
+
+```css
+/* Good — less padding on icon side */
+.button-with-icon {
+  padding-left: 16px;
+  padding-right: 14px; /* icon side = text side - 2px */
+}
+
+/* Bad — equal padding looks like icon is pushed too far right */
+.button-with-icon {
+  padding: 0 16px;
+}
+```
+
+```tsx
+// Tailwind
+<button className="pl-4 pr-3.5 flex items-center gap-2">
+  <span>Continue</span>
+  <ArrowRightIcon />
+</button>
+```
+
+### Play Button Triangles
+
+Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
+
+```css
+/* Good — optically centered */
+.play-button svg {
+  margin-left: 2px; /* shift right to account for triangle shape */
+}
+
+/* Bad — geometrically centered but looks off */
+.play-button svg {
+  /* no adjustment */
+}
+```
+
+### Asymmetric Icons (Stars, Arrows, Carets)
+
+Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
+
+```tsx
+// Best — fix in the SVG itself
+// Adjust the viewBox or path to visually center the icon
+
+// Fallback — adjust with margin
+<span className="ml-px">
+  <StarIcon />
+</span>
+```
+
+## Shadows Instead of Borders
+
+For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds — solid border colors don't work well on backgrounds other than the ones they were designed for.
+
+**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
+
+### Shadow as Border (Light Mode)
+
+The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0px 0px 0px 1px oklch(0 0 0 / 0.06),
+    0px 1px 2px -1px oklch(0 0 0 / 0.06),
+    0px 2px 4px 0px oklch(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0px 0px 0px 1px oklch(0 0 0 / 0.08),
+    0px 1px 2px -1px oklch(0 0 0 / 0.08),
+    0px 2px 4px 0px oklch(0 0 0 / 0.06);
+}
+```
+
+### Shadow as Border (Dark Mode)
+
+In dark mode, simplify to a single white ring — layered depth shadows aren't visible on dark backgrounds:
+
+```css
+/* Dark mode — adapt to whatever setup the project uses
+   (prefers-color-scheme, class, data attribute, etc.) */
+--shadow-border: 0 0 0 1px oklch(1 0 0 / 0.08);
+--shadow-border-hover: 0 0 0 1px oklch(1 0 0 / 0.13);
+```
+
+### Usage with Hover Transition
+
+Apply the variable and add `transition-[box-shadow]` for a smooth hover:
+
+```css
+.card {
+  box-shadow: var(--shadow-border);
+  transition-property: box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-border-hover);
+}
+```
+
+### When to Use Shadows vs. Borders
+
+| Use shadows | Use borders |
+| --- | --- |
+| Cards, containers with depth | Dividers between list items |
+| Buttons with bordered styles | Table cell boundaries |
+| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
+| Elements on varied backgrounds | Hairline separators in dense UI |
+| Hover/focus states for lift effect | |
+
+## Image Outlines
+
+Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
+
+### Color rules (non-negotiable)
+
+- **Light mode**: pure black, `oklch(0 0 0 / 0.1)`.
+- **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`.
+- Never use a near-black or near-white from the project palette (e.g. slate-900, zinc-900, `#0a0a0a`, `#111827`, `#f5f5f7`). Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
+- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
+
+### Light Mode
+
+```css
+img {
+  outline: 1px solid oklch(0 0 0 / 0.1);
+  outline-offset: -1px; /* inset so it doesn't add to layout */
+}
+```
+
+### Dark Mode
+
+```css
+img {
+  outline: 1px solid oklch(1 0 0 / 0.1);
+  outline-offset: -1px;
+}
+```
+
+### Tailwind with Dark Mode
+
+```tsx
+<img
+  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+  src={src}
+  alt={alt}
+/>
+```
+
+Use `outline-black/10` and `outline-white/10` specifically — not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
+
+**Why outline instead of border?** `outline` doesn't affect layout (no added width/height), and `outline-offset: -1px` keeps it inset so images stay their intended size.
+
+## Minimum Hit Area
+
+Interactive elements should prefer a 44×44px hit area for touch or mobile contexts. In dense desktop interfaces, use at least 40×40px. If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element.
+
+### CSS Example
+
+```css
+/* Small checkbox with expanded 44px hit area */
+.checkbox {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Collision Rule
+
+If the extended hit area overlaps another interactive element, shrink the pseudo-element — but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.
diff --git a/.agents/skills/make-interfaces-feel-better/typography.md b/.agents/skills/make-interfaces-feel-better/typography.md
new file mode 100644
index 0000000..a950535
--- /dev/null
+++ b/.agents/skills/make-interfaces-feel-better/typography.md
@@ -0,0 +1,157 @@
+# Typography
+
+Typography rendering details that make interfaces feel better.
+
+## Text Wrapping
+
+### text-wrap: balance
+
+Distributes text evenly across lines, preventing orphaned words on headings and short text blocks. **Only works on blocks of 6 lines or fewer** (Chromium) or 10 lines or fewer (Firefox) — the balancing algorithm is computationally expensive, so browsers limit it to short text.
+
+```css
+/* Good — even line lengths on short text */
+h1, h2, h3 {
+  text-wrap: balance;
+}
+```
+
+```css
+/* Bad — default wrapping leaves orphans */
+h1 {
+  /* no text-wrap rule → "Read our
+     blog" instead of balanced lines */
+}
+```
+
+```css
+/* Bad — balance on long paragraphs (silently ignored, wastes intent) */
+.article-body p {
+  text-wrap: balance;
+}
+```
+
+**Tailwind:** `text-balance`
+
+### text-wrap: pretty
+
+Prevents orphaned words (a single word dangling on the last line) by adjusting line breaks throughout the paragraph. Unlike `balance`, it doesn't try to equalize line lengths — it just ensures the last line isn't embarrassingly short. Works on text of any length with no line-count limit.
+
+This should be your **default for short-to-medium text** — paragraphs, descriptions, captions, list items, card text. For very long text (10+ lines), skip both `pretty` and `balance` — the browser's default wrapping is fine and you avoid unnecessary layout cost.
+
+```css
+/* Good — descriptions, captions, short paragraphs */
+p, li, figcaption, blockquote {
+  text-wrap: pretty;
+}
+```
+
+```tsx
+// Tailwind
+<p className="text-pretty">
+  A short paragraph that won't leave an orphan on the last line.
+</p>
+```
+
+**Tailwind:** `text-pretty`
+
+### When to Use Which
+
+| Scenario | Use |
+| --- | --- |
+| Headings, titles where even distribution matters | `text-wrap: balance` |
+| Short-to-medium text — paragraphs, descriptions, captions, UI text | `text-wrap: pretty` |
+| Long text (10+ lines), code blocks, pre-formatted text | Neither — leave default |
+
+## Font Smoothing (macOS)
+
+On macOS, text renders heavier than intended by default. Apply antialiased smoothing to the root layout so all text renders crisper and thinner.
+
+```css
+/* CSS */
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+```tsx
+// Tailwind — apply to root layout
+<html className="antialiased">
+```
+
+### Good vs. Bad
+
+```css
+/* Good — applied once at the root */
+html {
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Bad — applied per-element, inconsistent */
+.heading {
+  -webkit-font-smoothing: antialiased;
+}
+.body {
+  /* no smoothing → heavier than heading */
+}
+```
+
+**Note:** This only affects macOS rendering. Other platforms ignore these properties, so it's safe to apply universally.
+
+## Font Family Scope
+
+This skill does not require a specific font family. Do not introduce a paid or proprietary typeface just to satisfy the polish checklist.
+
+Use the product's existing type system unless the task explicitly asks for a type change. If the design calls for a system-native macOS feel, use the system font stack. If the design calls for a commercial face such as Helvetica Now, treat it as an optional brand decision and keep a practical fallback stack.
+
+```css
+/* System-native macOS/iOS feel */
+html {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+```
+
+```css
+/* Commercial brand face with safe fallbacks */
+html {
+  font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
+**Rule:** font smoothing, text wrapping, and tabular numbers are rendering details. They do not override the project's chosen font family.
+
+## Tabular Numbers
+
+When numbers update dynamically (counters, prices, timers, table columns), use tabular-nums to make all digits equal width. This prevents layout shift as values change.
+
+```css
+/* CSS */
+.counter {
+  font-variant-numeric: tabular-nums;
+}
+```
+
+```tsx
+// Tailwind
+<span className="tabular-nums">{count}</span>
+```
+
+### When to Use
+
+| Use tabular-nums | Don't use tabular-nums |
+| --- | --- |
+| Counters and timers | Static display numbers |
+| Prices that update | Decorative large numbers |
+| Table columns with numbers | Phone numbers, zip codes |
+| Animated number transitions | Version numbers (v2.1.0) |
+| Scoreboards, dashboards | |
+
+### Caveat
+
+Some fonts (like Inter) change the visual appearance of numerals with this property — specifically, the digit `1` becomes wider and centered. This is expected behavior and usually desirable for alignment, but verify it looks right in your specific font.
+
+```css
+/* With Inter font:
+   Default:  1234  → proportional, "1" is narrow
+   Tabular:  1234  → all digits equal width, "1" centered */
+```
diff --git a/.agents/skills/prisma-client-api/SKILL.md b/.agents/skills/prisma-client-api/SKILL.md
new file mode 100644
index 0000000..57aa8a5
--- /dev/null
+++ b/.agents/skills/prisma-client-api/SKILL.md
@@ -0,0 +1,216 @@
+---
+name: prisma-client-api
+description: Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
+license: MIT
+metadata:
+  author: prisma
+  version: "7.9.1"
+---
+
+# Prisma Client API Reference
+
+Complete API reference for Prisma Client. This skill provides guidance on model queries, filtering, relations, and client methods for current Prisma projects.
+
+## When to Apply
+
+Reference this skill when:
+- Writing database queries with Prisma Client
+- Performing CRUD operations (create, read, update, delete)
+- Filtering and sorting data
+- Working with relations
+- Using transactions
+- Configuring client options
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Client Construction | HIGH | `constructor` |
+| 2 | Model Queries | CRITICAL | `model-queries` |
+| 3 | Query Shape | HIGH | `query-options` |
+| 4 | Filtering | HIGH | `filters` |
+| 5 | Relations | HIGH | `relations` |
+| 6 | Transactions | CRITICAL | `transactions` |
+| 7 | Raw SQL | CRITICAL | `raw-queries` |
+| 8 | Client Methods | MEDIUM | `client-methods` |
+
+## Quick Reference
+
+- `constructor` - `PrismaClient` setup, adapter wiring, logging, and SQL commenter plugins
+- `model-queries` - CRUD operations and bulk operations
+- `query-options` - `select`, `include`, `omit`, sort, pagination
+- `filters` - scalar and logical filter operators
+- `relations` - relation reads and nested writes
+- `transactions` - array and interactive transaction patterns
+- `raw-queries` - `$queryRaw` and `$executeRaw` safety
+- `client-methods` - lifecycle methods, extensions, and `satisfies` patterns for `prisma-client`
+
+## Client Instantiation
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+## Model Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `findUnique()` | Find one record by unique field |
+| `findUniqueOrThrow()` | Find one or throw error |
+| `findFirst()` | Find first matching record |
+| `findFirstOrThrow()` | Find first or throw error |
+| `findMany()` | Find multiple records |
+| `create()` | Create a new record |
+| `createMany()` | Create multiple records |
+| `createManyAndReturn()` | Create multiple and return them |
+| `update()` | Update one record |
+| `updateMany()` | Update multiple records |
+| `updateManyAndReturn()` | Update multiple and return them |
+| `upsert()` | Update or create record |
+| `delete()` | Delete one record |
+| `deleteMany()` | Delete multiple records |
+| `count()` | Count matching records |
+| `aggregate()` | Aggregate values (sum, avg, etc.) |
+| `groupBy()` | Group and aggregate |
+
+## Query Options
+
+| Option | Description |
+|--------|-------------|
+| `where` | Filter conditions |
+| `select` | Fields to include |
+| `include` | Relations to load |
+| `omit` | Fields to exclude |
+| `orderBy` | Sort order |
+| `take` | Limit results |
+| `skip` | Skip results (pagination) |
+| `cursor` | Cursor-based pagination |
+| `distinct` | Unique values only |
+
+## Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `$connect()` | Explicitly connect to database |
+| `$disconnect()` | Disconnect from database |
+| `$transaction()` | Execute transaction |
+| `$queryRaw()` | Execute raw SQL query |
+| `$executeRaw()` | Execute raw SQL command |
+| `$on()` | Subscribe to events |
+| `$extends()` | Add extensions |
+
+## Quick Examples
+
+### Find records
+
+```typescript
+// Find by unique field
+const user = await prisma.user.findUnique({
+  where: { email: 'alice@prisma.io' }
+})
+
+// Find with filter
+const users = await prisma.user.findMany({
+  where: { role: 'ADMIN' },
+  orderBy: { createdAt: 'desc' },
+  take: 10
+})
+```
+
+### Create records
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    name: 'Alice',
+    posts: {
+      create: { title: 'Hello World' }
+    }
+  },
+  include: { posts: true }
+})
+```
+
+### Update records
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: { name: 'Alice Smith' }
+})
+```
+
+### Delete records
+
+```typescript
+await prisma.user.delete({
+  where: { id: 1 }
+})
+```
+
+### Transactions
+
+```typescript
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+  prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
+])
+```
+
+## Rule Files
+
+Detailed API documentation:
+
+```
+references/constructor.md        - PrismaClient constructor options
+references/model-queries.md      - CRUD operations
+references/query-options.md      - select, include, omit, where, orderBy
+references/filters.md            - Filter conditions and operators
+references/relations.md          - Relation queries and nested operations
+references/transactions.md       - Transaction API
+references/raw-queries.md        - $queryRaw, $executeRaw
+references/client-methods.md     - $connect, $disconnect, $on, $extends
+```
+
+## Filter Operators
+
+| Operator | Description |
+|----------|-------------|
+| `equals` | Exact match |
+| `not` | Not equal |
+| `in` | In array |
+| `notIn` | Not in array |
+| `lt`, `lte` | Less than |
+| `gt`, `gte` | Greater than |
+| `contains` | String contains |
+| `startsWith` | String starts with |
+| `endsWith` | String ends with |
+| `mode` | Case sensitivity |
+
+## Relation Filters
+
+| Operator | Description |
+|----------|-------------|
+| `some` | At least one related record matches |
+| `every` | All related records match |
+| `none` | No related records match |
+| `is` | Related record matches (1-to-1) |
+| `isNot` | Related record doesn't match |
+
+## Resources
+
+- [Prisma Client API Reference](https://www.prisma.io/docs/orm/reference/prisma-client-reference)
+- [CRUD Operations](https://www.prisma.io/docs/orm/prisma-client/queries/crud)
+- [Filtering and Sorting](https://www.prisma.io/docs/orm/prisma-client/queries/filtering-and-sorting)
+
+## How to Use
+
+Pick the category from the table above, then open the matching reference file for implementation details and examples.
diff --git a/.agents/skills/prisma-client-api/references/client-methods.md b/.agents/skills/prisma-client-api/references/client-methods.md
new file mode 100644
index 0000000..17beb1f
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/client-methods.md
@@ -0,0 +1,223 @@
+# Client Methods
+
+Prisma Client instance methods.
+
+## $connect()
+
+Explicitly connect to the database:
+
+```typescript
+const prisma = new PrismaClient({ adapter })
+
+// Explicit connection
+await prisma.$connect()
+```
+
+### When to use
+
+Usually not needed - Prisma connects automatically on first query. Use for:
+- Fail fast on startup
+- Health checks
+- Pre-warming connections
+
+```typescript
+async function main() {
+  try {
+    await prisma.$connect()
+    console.log('Database connected')
+  } catch (e) {
+    console.error('Failed to connect:', e)
+    process.exit(1)
+  }
+}
+```
+
+## $disconnect()
+
+Close database connection:
+
+```typescript
+await prisma.$disconnect()
+```
+
+### Graceful shutdown
+
+```typescript
+process.on('beforeExit', async () => {
+  await prisma.$disconnect()
+})
+
+// Or with SIGTERM
+process.on('SIGTERM', async () => {
+  await prisma.$disconnect()
+  process.exit(0)
+})
+```
+
+### In tests
+
+```typescript
+afterAll(async () => {
+  await prisma.$disconnect()
+})
+```
+
+## $on()
+
+Subscribe to events:
+
+### Query events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [{ level: 'query', emit: 'event' }]
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Params:', e.params)
+  console.log('Duration:', e.duration, 'ms')
+})
+```
+
+### Log events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [
+    { level: 'info', emit: 'event' },
+    { level: 'warn', emit: 'event' },
+    { level: 'error', emit: 'event' }
+  ]
+})
+
+prisma.$on('info', (e) => console.log(e.message))
+prisma.$on('warn', (e) => console.warn(e.message))
+prisma.$on('error', (e) => console.error(e.message))
+```
+
+## $extends()
+
+Add extensions for custom behavior:
+
+### Add custom methods
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  client: {
+    $log: (message: string) => console.log(message)
+  }
+})
+
+prisma.$log('Hello!')
+```
+
+### Add model methods
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  model: {
+    user: {
+      async findByEmail(email: string) {
+        return prisma.user.findUnique({ where: { email } })
+      }
+    }
+  }
+})
+
+const user = await prisma.user.findByEmail('alice@prisma.io')
+```
+
+### Query extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  query: {
+    user: {
+      async findMany({ args, query }) {
+        // Add default filter
+        args.where = { ...args.where, deletedAt: null }
+        return query(args)
+      }
+    }
+  }
+})
+```
+
+### Result extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  result: {
+    user: {
+      fullName: {
+        needs: { firstName: true, lastName: true },
+        compute(user) {
+          return `${user.firstName} ${user.lastName}`
+        }
+      }
+    }
+  }
+})
+
+const user = await prisma.user.findFirst()
+console.log(user.fullName) // Computed field
+```
+
+### Chain extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter })
+  .$extends(loggingExtension)
+  .$extends(softDeleteExtension)
+  .$extends(computedFieldsExtension)
+```
+
+## $transaction()
+
+See `transactions.md` for details.
+
+## $queryRaw() / $executeRaw()
+
+See `raw-queries.md` for details.
+
+## Type utilities
+
+### Prisma namespace
+
+```typescript
+import { Prisma } from '../generated/client'
+
+// Input types
+type UserCreateInput = Prisma.UserCreateInput
+type UserWhereInput = Prisma.UserWhereInput
+
+// Output types
+type User = Prisma.UserGetPayload<{}>
+type UserWithPosts = Prisma.UserGetPayload<{
+  include: { posts: true }
+}>
+```
+
+### Type-safe query fragments with satisfies
+
+Type-safe query fragments:
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const userSelect = {
+  id: true,
+  email: true,
+  name: true
+} satisfies Prisma.UserSelect
+
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: userSelect
+})
+```
+
+With the `prisma-client` generator, use TypeScript `satisfies` for typed query fragments. You may still see older examples that use `Prisma.validator()` with `prisma-client-js`.
diff --git a/.agents/skills/prisma-client-api/references/constructor.md b/.agents/skills/prisma-client-api/references/constructor.md
new file mode 100644
index 0000000..a9fb5e8
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/constructor.md
@@ -0,0 +1,221 @@
+# PrismaClient Constructor
+
+Configure Prisma Client when instantiating.
+
+## Basic Instantiation
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+## Constructor Options
+
+### adapter (Required for the SQL provider workflow)
+
+Driver adapter instance:
+
+```typescript
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+### accelerateUrl (For Accelerate users)
+
+```typescript
+import { withAccelerate } from '@prisma/extension-accelerate'
+
+const prisma = new PrismaClient({
+  accelerateUrl: process.env.DATABASE_URL,  // prisma:// URL
+}).$extends(withAccelerate())
+```
+
+### log
+
+Configure logging:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: ['query', 'info', 'warn', 'error'],
+})
+```
+
+#### Log levels
+
+| Level | Description |
+|-------|-------------|
+| `query` | All SQL queries |
+| `info` | Informational messages |
+| `warn` | Warnings |
+| `error` | Errors |
+
+#### Log to events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [
+    { level: 'query', emit: 'event' },
+    { level: 'error', emit: 'stdout' },
+  ],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Duration:', e.duration, 'ms')
+})
+```
+
+### errorFormat
+
+Control error formatting:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  errorFormat: 'pretty',  // 'pretty' | 'colorless' | 'minimal'
+})
+```
+
+### comments
+
+Attach SQL commenter plugins for observability, tracing, or query insights:
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+import { queryTags, withQueryTags } from '@prisma/sqlcommenter-query-tags'
+import { traceContext } from '@prisma/sqlcommenter-trace-context'
+
+const prisma = new PrismaClient({
+  adapter: new PrismaPg(process.env.DATABASE_URL!),
+  comments: [prismaQueryInsights(), traceContext(), queryTags()],
+})
+
+await withQueryTags({ route: '/api/users', requestId: 'req-123' }, () =>
+  prisma.user.findMany(),
+)
+```
+
+Use `comments` only for SQL providers. This is the clean way to add trace or query-shape metadata without changing your query calls.
+
+### transactionOptions
+
+Default transaction settings:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  transactionOptions: {
+    maxWait: 5000,      // Max wait to acquire transaction (ms)
+    timeout: 10000,     // Max transaction duration (ms)
+    isolationLevel: 'Serializable',
+  },
+})
+```
+
+### queryPlanCacheMaxSize
+
+Use `queryPlanCacheMaxSize` to limit the in-memory query-plan cache:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  queryPlanCacheMaxSize: 2_000,
+})
+```
+
+The value must be a non-negative integer. Set it to `0` to disable query-plan caching; omit it to use Prisma's default. Treat this as a process-local memory/performance control, not a database prepared-statement setting.
+
+## Singleton Pattern
+
+Prevent multiple client instances in development:
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+function createPrismaClient() {
+  const adapter = new PrismaPg({
+    connectionString: process.env.DATABASE_URL!
+  })
+  return new PrismaClient({ adapter })
+}
+
+export const prisma = globalForPrisma.prisma ?? createPrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+## Next.js Pattern
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '@/generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const createAdapter = () => new PrismaPg({
+  connectionString: process.env.DATABASE_URL!
+})
+
+const prismaClientSingleton = () => {
+  return new PrismaClient({ adapter: createAdapter() })
+}
+
+declare const globalThis: {
+  prismaGlobal: ReturnType<typeof prismaClientSingleton>
+} & typeof global
+
+const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()
+
+export default prisma
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.prismaGlobal = prisma
+}
+```
+
+## Query Events
+
+Listen to query events:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [{ level: 'query', emit: 'event' }],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Params:', e.params)
+  console.log('Duration:', e.duration)
+})
+```
+
+## Log Events
+
+```typescript
+prisma.$on('info', (e) => console.log(e.message))
+prisma.$on('warn', (e) => console.warn(e.message))
+prisma.$on('error', (e) => console.error(e.message))
+```
diff --git a/.agents/skills/prisma-client-api/references/filters.md b/.agents/skills/prisma-client-api/references/filters.md
new file mode 100644
index 0000000..a9b7eea
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/filters.md
@@ -0,0 +1,256 @@
+# Filter Conditions and Operators
+
+Filter operators for the `where` clause.
+
+## Equality
+
+```typescript
+// Exact match (implicit)
+where: { email: 'alice@prisma.io' }
+
+// Explicit equals
+where: { email: { equals: 'alice@prisma.io' } }
+
+// Not equal
+where: { email: { not: 'alice@prisma.io' } }
+```
+
+## Comparison
+
+```typescript
+// Greater than
+where: { age: { gt: 18 } }
+
+// Greater than or equal
+where: { age: { gte: 18 } }
+
+// Less than
+where: { age: { lt: 65 } }
+
+// Less than or equal
+where: { age: { lte: 65 } }
+
+// Combined
+where: { age: { gte: 18, lte: 65 } }
+```
+
+## Lists
+
+```typescript
+// In array
+where: { role: { in: ['ADMIN', 'MODERATOR'] } }
+
+// Not in array
+where: { role: { notIn: ['GUEST', 'BANNED'] } }
+```
+
+## String Filters
+
+```typescript
+// Contains
+where: { email: { contains: 'prisma' } }
+
+// Starts with
+where: { email: { startsWith: 'alice' } }
+
+// Ends with
+where: { email: { endsWith: '@prisma.io' } }
+
+// Case-insensitive (default for some databases)
+where: { 
+  email: { 
+    contains: 'PRISMA',
+    mode: 'insensitive' 
+  } 
+}
+```
+
+## Null Checks
+
+```typescript
+// Is null
+where: { deletedAt: null }
+
+// Is not null
+where: { deletedAt: { not: null } }
+
+// Using isSet (for optional fields)
+where: { middleName: { isSet: true } }
+```
+
+## Logical Operators
+
+### AND (implicit)
+
+```typescript
+// Multiple conditions = AND
+where: {
+  email: { contains: '@prisma.io' },
+  role: 'ADMIN'
+}
+```
+
+### AND (explicit)
+
+```typescript
+where: {
+  AND: [
+    { email: { contains: '@prisma.io' } },
+    { role: 'ADMIN' }
+  ]
+}
+```
+
+### OR
+
+```typescript
+where: {
+  OR: [
+    { email: { contains: '@gmail.com' } },
+    { email: { contains: '@prisma.io' } }
+  ]
+}
+```
+
+### NOT
+
+```typescript
+where: {
+  NOT: {
+    role: 'GUEST'
+  }
+}
+
+// Multiple NOT conditions
+where: {
+  NOT: [
+    { role: 'GUEST' },
+    { verified: false }
+  ]
+}
+```
+
+### Combined
+
+```typescript
+where: {
+  AND: [
+    { verified: true },
+    {
+      OR: [
+        { role: 'ADMIN' },
+        { role: 'MODERATOR' }
+      ]
+    }
+  ],
+  NOT: { deletedAt: { not: null } }
+}
+```
+
+## Relation Filters
+
+### some
+
+At least one related record matches:
+
+```typescript
+// Users with at least one published post
+where: {
+  posts: {
+    some: { published: true }
+  }
+}
+```
+
+### every
+
+All related records match:
+
+```typescript
+// Users where all posts are published
+where: {
+  posts: {
+    every: { published: true }
+  }
+}
+```
+
+### none
+
+No related records match:
+
+```typescript
+// Users with no published posts
+where: {
+  posts: {
+    none: { published: true }
+  }
+}
+```
+
+### is / isNot (1-to-1)
+
+```typescript
+// Users with profile in specific country
+where: {
+  profile: {
+    is: { country: 'USA' }
+  }
+}
+
+// Users without profile
+where: {
+  profile: {
+    isNot: null
+  }
+}
+```
+
+## Array Field Filters
+
+For fields like `String[]`:
+
+```typescript
+// Has element
+where: { tags: { has: 'typescript' } }
+
+// Has some elements
+where: { tags: { hasSome: ['typescript', 'javascript'] } }
+
+// Has every element
+where: { tags: { hasEvery: ['typescript', 'prisma'] } }
+
+// Is empty
+where: { tags: { isEmpty: true } }
+```
+
+## JSON Filters
+
+```typescript
+// Path-based filter
+where: {
+  metadata: {
+    path: ['settings', 'theme'],
+    equals: 'dark'
+  }
+}
+
+// String contains in JSON
+where: {
+  metadata: {
+    path: ['bio'],
+    string_contains: 'developer'
+  }
+}
+```
+
+## Full-Text Search
+
+```typescript
+// Requires @@fulltext index
+where: {
+  content: {
+    search: 'prisma database'
+  }
+}
+```
diff --git a/.agents/skills/prisma-client-api/references/model-queries.md b/.agents/skills/prisma-client-api/references/model-queries.md
new file mode 100644
index 0000000..0687ef5
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/model-queries.md
@@ -0,0 +1,281 @@
+# Model Queries
+
+CRUD operations for your Prisma models.
+
+## Read Operations
+
+### findUnique
+
+Find a single record by unique field:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 }
+})
+
+const user = await prisma.user.findUnique({
+  where: { email: 'alice@prisma.io' }
+})
+```
+
+#### With composite unique key
+
+```typescript
+// Model with @@unique([firstName, lastName])
+const user = await prisma.user.findUnique({
+  where: {
+    firstName_lastName: {
+      firstName: 'Alice',
+      lastName: 'Smith'
+    }
+  }
+})
+```
+
+### findUniqueOrThrow
+
+Same as findUnique but throws if not found:
+
+```typescript
+const user = await prisma.user.findUniqueOrThrow({
+  where: { id: 1 }
+})
+// Throws PrismaClientKnownRequestError if not found
+```
+
+### findFirst
+
+Find first matching record:
+
+```typescript
+const user = await prisma.user.findFirst({
+  where: { role: 'ADMIN' },
+  orderBy: { createdAt: 'desc' }
+})
+```
+
+### findFirstOrThrow
+
+```typescript
+const user = await prisma.user.findFirstOrThrow({
+  where: { role: 'ADMIN' }
+})
+```
+
+### findMany
+
+Find multiple records:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: { role: 'USER' },
+  orderBy: { name: 'asc' },
+  take: 10,
+  skip: 0
+})
+```
+
+## Create Operations
+
+### create
+
+Create a single record:
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    name: 'Alice'
+  }
+})
+```
+
+#### With relations
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'First Post' },
+        { title: 'Second Post' }
+      ]
+    }
+  },
+  include: { posts: true }
+})
+```
+
+### createMany
+
+Create multiple records:
+
+```typescript
+const result = await prisma.user.createMany({
+  data: [
+    { email: 'alice@prisma.io', name: 'Alice' },
+    { email: 'bob@prisma.io', name: 'Bob' }
+  ],
+  skipDuplicates: true  // Skip records with duplicate unique fields
+})
+// Returns { count: 2 }
+```
+
+### createManyAndReturn
+
+Create multiple and return them:
+
+```typescript
+const users = await prisma.user.createManyAndReturn({
+  data: [
+    { email: 'alice@prisma.io', name: 'Alice' },
+    { email: 'bob@prisma.io', name: 'Bob' }
+  ]
+})
+// Returns array of created users
+```
+
+## Update Operations
+
+### update
+
+Update a single record:
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: { name: 'Alice Smith' }
+})
+```
+
+#### Atomic operations
+
+```typescript
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    views: { increment: 1 },
+    likes: { decrement: 1 },
+    score: { multiply: 2 },
+    rating: { divide: 2 },
+    version: { set: 5 }
+  }
+})
+```
+
+### updateMany
+
+Update multiple records:
+
+```typescript
+const result = await prisma.user.updateMany({
+  where: { role: 'USER' },
+  data: { verified: true }
+})
+// Returns { count: 42 }
+```
+
+### updateManyAndReturn
+
+```typescript
+const users = await prisma.user.updateManyAndReturn({
+  where: { role: 'USER' },
+  data: { verified: true }
+})
+// Returns array of updated users
+```
+
+### upsert
+
+Update or create:
+
+```typescript
+const user = await prisma.user.upsert({
+  where: { email: 'alice@prisma.io' },
+  update: { name: 'Alice Smith' },
+  create: { email: 'alice@prisma.io', name: 'Alice' }
+})
+```
+
+## Delete Operations
+
+### delete
+
+Delete a single record:
+
+```typescript
+const user = await prisma.user.delete({
+  where: { id: 1 }
+})
+// Returns deleted record
+```
+
+### deleteMany
+
+Delete multiple records:
+
+```typescript
+const result = await prisma.user.deleteMany({
+  where: { role: 'GUEST' }
+})
+// Returns { count: 5 }
+
+// Delete all
+const result = await prisma.user.deleteMany({})
+```
+
+## Aggregation Operations
+
+### count
+
+```typescript
+const count = await prisma.user.count({
+  where: { role: 'ADMIN' }
+})
+```
+
+### aggregate
+
+```typescript
+const result = await prisma.post.aggregate({
+  _avg: { views: true },
+  _sum: { views: true },
+  _min: { views: true },
+  _max: { views: true },
+  _count: { _all: true }
+})
+```
+
+### groupBy
+
+```typescript
+const groups = await prisma.user.groupBy({
+  by: ['country'],
+  _count: { _all: true },
+  _avg: { age: true },
+  having: {
+    age: { _avg: { gt: 30 } }
+  }
+})
+```
+
+## Return Types
+
+| Method | Returns |
+|--------|---------|
+| `findUnique` | Record \| null |
+| `findUniqueOrThrow` | Record (throws if not found) |
+| `findFirst` | Record \| null |
+| `findFirstOrThrow` | Record (throws if not found) |
+| `findMany` | Record[] |
+| `create` | Record |
+| `createMany` | { count: number } |
+| `createManyAndReturn` | Record[] |
+| `update` | Record |
+| `updateMany` | { count: number } |
+| `delete` | Record |
+| `deleteMany` | { count: number } |
+| `count` | number |
+| `aggregate` | Aggregate result |
+| `groupBy` | Group result[] |
diff --git a/.agents/skills/prisma-client-api/references/query-options.md b/.agents/skills/prisma-client-api/references/query-options.md
new file mode 100644
index 0000000..25864a4
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/query-options.md
@@ -0,0 +1,276 @@
+# Query Options
+
+Options for controlling query behavior.
+
+## select
+
+Choose specific fields to return:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    // password: false (excluded by not including)
+  }
+})
+// Returns: { id: 1, name: 'Alice', email: 'alice@prisma.io' }
+```
+
+### Select relations
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    name: true,
+    posts: {
+      select: {
+        title: true,
+        published: true
+      }
+    }
+  }
+})
+```
+
+### Select with include inside
+
+```typescript
+const user = await prisma.user.findMany({
+  select: {
+    name: true,
+    posts: {
+      include: {
+        comments: true
+      }
+    }
+  }
+})
+```
+
+### Select relation count
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: { posts: true }
+    }
+  }
+})
+// Returns: { name: 'Alice', _count: { posts: 5 } }
+```
+
+## include
+
+Include related records:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: true,
+    profile: true
+  }
+})
+```
+
+### Filtered include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5
+    }
+  }
+})
+```
+
+### Nested include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      include: {
+        comments: {
+          include: {
+            author: true
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+### Include relation count
+
+```typescript
+const users = await prisma.user.findMany({
+  include: {
+    _count: {
+      select: { posts: true, followers: true }
+    }
+  }
+})
+```
+
+## omit
+
+Exclude specific fields:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  omit: {
+    password: true
+  }
+})
+// Returns all fields except password
+```
+
+### Omit in relations
+
+```typescript
+const users = await prisma.user.findMany({
+  omit: { password: true },
+  include: {
+    posts: {
+      omit: { content: true }
+    }
+  }
+})
+```
+
+**Note:** Cannot use `select` and `omit` together.
+
+## where
+
+Filter records:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    email: { contains: '@prisma.io' },
+    role: 'ADMIN'
+  }
+})
+```
+
+See `filters.md` for detailed filter operators.
+
+## orderBy
+
+Sort results:
+
+```typescript
+// Single field
+const users = await prisma.user.findMany({
+  orderBy: { name: 'asc' }
+})
+
+// Multiple fields
+const users = await prisma.user.findMany({
+  orderBy: [
+    { role: 'desc' },
+    { name: 'asc' }
+  ]
+})
+```
+
+### Order by relation
+
+```typescript
+const users = await prisma.user.findMany({
+  orderBy: {
+    posts: { _count: 'desc' }
+  }
+})
+```
+
+### Null handling
+
+```typescript
+const users = await prisma.user.findMany({
+  orderBy: {
+    name: { sort: 'asc', nulls: 'last' }
+  }
+})
+```
+
+## take & skip
+
+Pagination:
+
+```typescript
+// First page
+const users = await prisma.user.findMany({
+  take: 10,
+  skip: 0
+})
+
+// Second page
+const users = await prisma.user.findMany({
+  take: 10,
+  skip: 10
+})
+```
+
+### Negative take (reverse)
+
+```typescript
+const lastUsers = await prisma.user.findMany({
+  take: -10,
+  orderBy: { id: 'asc' }
+})
+// Returns last 10 users
+```
+
+## cursor
+
+Cursor-based pagination:
+
+```typescript
+// First page
+const firstPage = await prisma.user.findMany({
+  take: 10,
+  orderBy: { id: 'asc' }
+})
+
+// Next page using cursor
+const nextPage = await prisma.user.findMany({
+  take: 10,
+  skip: 1,  // Skip the cursor record
+  cursor: { id: firstPage[firstPage.length - 1].id },
+  orderBy: { id: 'asc' }
+})
+```
+
+## distinct
+
+Return unique values:
+
+```typescript
+const cities = await prisma.user.findMany({
+  distinct: ['city'],
+  select: { city: true }
+})
+```
+
+### Multiple distinct fields
+
+```typescript
+const locations = await prisma.user.findMany({
+  distinct: ['city', 'country']
+})
+```
diff --git a/.agents/skills/prisma-client-api/references/raw-queries.md b/.agents/skills/prisma-client-api/references/raw-queries.md
new file mode 100644
index 0000000..e444ce2
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/raw-queries.md
@@ -0,0 +1,198 @@
+# Raw Queries
+
+Execute raw SQL when Prisma's query API isn't sufficient.
+
+## $queryRaw
+
+Execute SELECT queries and get typed results:
+
+```typescript
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE email LIKE ${'%@prisma.io'}
+`
+```
+
+### With type
+
+```typescript
+type User = { id: number; email: string; name: string | null }
+
+const users = await prisma.$queryRaw<User[]>`
+  SELECT id, email, name FROM "User" WHERE role = ${'ADMIN'}
+`
+```
+
+### Dynamic table/column names
+
+Use `Prisma.raw()` for identifiers (not safe for user input):
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const column = 'email'
+const users = await prisma.$queryRaw`
+  SELECT ${Prisma.raw(column)} FROM "User"
+`
+```
+
+### With Prisma.sql
+
+Build queries dynamically:
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const email = 'alice@prisma.io'
+const query = Prisma.sql`SELECT * FROM "User" WHERE email = ${email}`
+const users = await prisma.$queryRaw(query)
+```
+
+### Join multiple SQL fragments
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const conditions = [
+  Prisma.sql`role = ${'ADMIN'}`,
+  Prisma.sql`verified = ${true}`
+]
+
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" 
+  WHERE ${Prisma.join(conditions, ' AND ')}
+`
+```
+
+## $executeRaw
+
+Execute INSERT, UPDATE, DELETE (returns affected count):
+
+```typescript
+const count = await prisma.$executeRaw`
+  UPDATE "User" SET verified = true WHERE email LIKE ${'%@prisma.io'}
+`
+console.log(`Updated ${count} users`)
+```
+
+### Delete example
+
+```typescript
+const deleted = await prisma.$executeRaw`
+  DELETE FROM "User" WHERE "deletedAt" < ${thirtyDaysAgo}
+`
+```
+
+### Insert example
+
+```typescript
+const inserted = await prisma.$executeRaw`
+  INSERT INTO "Log" (message, level, timestamp)
+  VALUES (${message}, ${level}, ${new Date()})
+`
+```
+
+## $queryRawUnsafe / $executeRawUnsafe
+
+For fully dynamic queries (use with caution!):
+
+```typescript
+// ⚠️ SQL injection risk - only use with trusted input
+const table = 'User'
+const users = await prisma.$queryRawUnsafe(
+  `SELECT * FROM "${table}" WHERE id = $1`,
+  userId
+)
+```
+
+### Parameterized unsafe query
+
+```typescript
+const result = await prisma.$executeRawUnsafe(
+  'UPDATE "User" SET name = $1 WHERE id = $2',
+  'Alice',
+  1
+)
+```
+
+## SQL Injection Prevention
+
+### Safe (parameterized)
+
+```typescript
+// ✅ User input is parameterized
+const email = userInput
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE email = ${email}
+`
+```
+
+### Unsafe (concatenation)
+
+```typescript
+// ❌ SQL injection vulnerability!
+const email = userInput
+const users = await prisma.$queryRawUnsafe(
+  `SELECT * FROM "User" WHERE email = '${email}'`
+)
+```
+
+## Database-Specific Features
+
+### PostgreSQL
+
+```typescript
+// Array operations
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE 'admin' = ANY(roles)
+`
+
+// JSON operations
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE metadata->>'theme' = 'dark'
+`
+```
+
+### MySQL
+
+```typescript
+// Full-text search
+const posts = await prisma.$queryRaw`
+  SELECT * FROM Post WHERE MATCH(title, content) AGAINST(${searchTerm})
+`
+```
+
+## Transactions with Raw Queries
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  await tx.$executeRaw`UPDATE "Account" SET balance = balance - ${amount} WHERE id = ${senderId}`
+  await tx.$executeRaw`UPDATE "Account" SET balance = balance + ${amount} WHERE id = ${recipientId}`
+})
+```
+
+## Handling Results
+
+### BigInt handling
+
+PostgreSQL returns BigInt for COUNT:
+
+```typescript
+const result = await prisma.$queryRaw<[{ count: bigint }]>`
+  SELECT COUNT(*) as count FROM "User"
+`
+const count = Number(result[0].count)
+```
+
+### Date handling
+
+```typescript
+type Result = { createdAt: Date }
+const users = await prisma.$queryRaw<Result[]>`
+  SELECT "createdAt" FROM "User"
+`
+// createdAt is already a Date object
+```
+
+Invalid JavaScript `Date` values passed to raw queries fail validation instead of being silently serialized as `null`. Validate date input at the application boundary; do not rely on `new Date(badValue)` reaching the database.
+
+When a driver adapter returns an unmapped database-specific error, Prisma surfaces `P2039` with the adapter's preserved original code/message. If those details are missing, fix the adapter mapping rather than parsing rendered error text.
diff --git a/.agents/skills/prisma-client-api/references/relations.md b/.agents/skills/prisma-client-api/references/relations.md
new file mode 100644
index 0000000..001c448
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/relations.md
@@ -0,0 +1,308 @@
+# Relation Queries
+
+Query and modify related records.
+
+## Include Relations
+
+Load related records:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: true,
+    profile: true
+  }
+})
+```
+
+### Filtered include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5,
+      select: { id: true, title: true }
+    }
+  }
+})
+```
+
+### Nested include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      include: {
+        comments: {
+          include: { author: true }
+        }
+      }
+    }
+  }
+})
+```
+
+## Select Relations
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    name: true,
+    posts: {
+      select: { title: true }
+    }
+  }
+})
+```
+
+## Nested Writes
+
+### Create with relations
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'Post 1' },
+        { title: 'Post 2' }
+      ]
+    },
+    profile: {
+      create: { bio: 'Hello!' }
+    }
+  }
+})
+```
+
+### Create or connect
+
+```typescript
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    author: {
+      connectOrCreate: {
+        where: { email: 'alice@prisma.io' },
+        create: { email: 'alice@prisma.io', name: 'Alice' }
+      }
+    }
+  }
+})
+```
+
+### Connect existing
+
+```typescript
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    author: {
+      connect: { id: 1 }
+    }
+  }
+})
+
+// Shorthand for foreign key
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    authorId: 1
+  }
+})
+```
+
+## Update Relations
+
+### Update related records
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      update: {
+        where: { id: 1 },
+        data: { title: 'Updated Title' }
+      }
+    }
+  }
+})
+```
+
+### Update many related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      updateMany: {
+        where: { published: false },
+        data: { published: true }
+      }
+    }
+  }
+})
+```
+
+### Upsert related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    profile: {
+      upsert: {
+        create: { bio: 'New bio' },
+        update: { bio: 'Updated bio' }
+      }
+    }
+  }
+})
+```
+
+### Disconnect
+
+```typescript
+// 1-to-1 optional
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    profile: { disconnect: true }
+  }
+})
+
+// Many-to-many
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    tags: {
+      disconnect: [{ id: 1 }, { id: 2 }]
+    }
+  }
+})
+```
+
+### Delete related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      delete: { id: 1 }
+    }
+  }
+})
+
+// Delete many
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      deleteMany: { published: false }
+    }
+  }
+})
+```
+
+### Set (replace all)
+
+```typescript
+// Replace all related records
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    tags: {
+      set: [{ id: 1 }, { id: 2 }]
+    }
+  }
+})
+```
+
+## Relation Filters
+
+### some
+
+At least one matches:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { some: { published: true } }
+  }
+})
+```
+
+### every
+
+All match:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { every: { published: true } }
+  }
+})
+```
+
+### none
+
+None match:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { none: { published: true } }
+  }
+})
+```
+
+### is / isNot (1-to-1)
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    profile: { is: { country: 'USA' } }
+  }
+})
+```
+
+## Count Relations
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: { posts: true, followers: true }
+    }
+  }
+})
+// { name: 'Alice', _count: { posts: 5, followers: 100 } }
+```
+
+### Filter counted relations
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: {
+        posts: { where: { published: true } }
+      }
+    }
+  }
+})
+```
diff --git a/.agents/skills/prisma-client-api/references/transactions.md b/.agents/skills/prisma-client-api/references/transactions.md
new file mode 100644
index 0000000..c2a981a
--- /dev/null
+++ b/.agents/skills/prisma-client-api/references/transactions.md
@@ -0,0 +1,184 @@
+# Transactions
+
+Execute multiple operations atomically.
+
+## Sequential Transactions
+
+Array of operations executed in order:
+
+```typescript
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+  prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
+])
+```
+
+### All or nothing
+
+If any operation fails, all are rolled back:
+
+```typescript
+try {
+  await prisma.$transaction([
+    prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+    prisma.user.create({ data: { email: 'alice@prisma.io' } }) // Duplicate!
+  ])
+} catch (e) {
+  // Both operations rolled back
+}
+```
+
+## Interactive Transactions
+
+For complex logic and dependent operations:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // Decrement sender balance
+  const sender = await tx.account.update({
+    where: { id: senderId },
+    data: { balance: { decrement: amount } }
+  })
+  
+  // Check balance
+  if (sender.balance < 0) {
+    throw new Error('Insufficient funds')
+  }
+  
+  // Increment recipient balance
+  await tx.account.update({
+    where: { id: recipientId },
+    data: { balance: { increment: amount } }
+  })
+})
+```
+
+### Transaction options
+
+```typescript
+await prisma.$transaction(
+  async (tx) => {
+    // operations
+  },
+  {
+    maxWait: 5000,    // Max wait to acquire lock (ms)
+    timeout: 10000,   // Max transaction duration (ms)
+    isolationLevel: 'Serializable'  // Isolation level
+  }
+)
+```
+
+### Isolation levels
+
+| Level | Description |
+|-------|-------------|
+| `ReadUncommitted` | Lowest isolation, can read uncommitted changes |
+| `ReadCommitted` | Only read committed changes |
+| `RepeatableRead` | Consistent reads within transaction |
+| `Serializable` | Highest isolation, serialized execution |
+
+## Nested Writes
+
+Automatic transactions for nested operations:
+
+```typescript
+// This is automatically a transaction
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'Post 1' },
+        { title: 'Post 2' }
+      ]
+    },
+    profile: {
+      create: { bio: 'Hello!' }
+    }
+  }
+})
+```
+
+## Transaction Client
+
+The `tx` parameter is a Prisma Client scoped to the transaction:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // Use tx instead of prisma
+  await tx.user.create({ ... })
+  await tx.post.create({ ... })
+  
+  // Can call methods
+  const count = await tx.user.count()
+})
+```
+
+## OrThrow in Transactions
+
+Use with interactive transactions:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // If not found, throws and rolls back entire transaction
+  const user = await tx.user.findUniqueOrThrow({
+    where: { id: 1 }
+  })
+  
+  await tx.post.create({
+    data: { title: 'New Post', authorId: user.id }
+  })
+})
+```
+
+## Best Practices
+
+### Keep transactions short
+
+```typescript
+// Good - only DB operations in transaction
+const data = prepareData() // Outside transaction
+await prisma.$transaction(async (tx) => {
+  await tx.user.create({ data })
+})
+```
+
+### Handle errors
+
+```typescript
+try {
+  await prisma.$transaction(async (tx) => {
+    // operations
+  })
+} catch (e) {
+  if (e.code === 'P2002') {
+    // Handle unique constraint violation
+  }
+  throw e
+}
+```
+
+### Use appropriate isolation
+
+```typescript
+// Default is fine for most cases
+await prisma.$transaction(async (tx) => {
+  // operations
+})
+
+// Use Serializable for strict consistency
+await prisma.$transaction(
+  async (tx) => { /* operations */ },
+  { isolationLevel: 'Serializable' }
+)
+```
+
+## Sequential vs Interactive
+
+| Feature | Sequential | Interactive |
+|---------|------------|-------------|
+| Syntax | Array | Async function |
+| Dependent ops | No | Yes |
+| Conditional logic | No | Yes |
+| Performance | Better | More flexible |
+| Use case | Simple batch | Complex logic |
diff --git a/.agents/skills/prisma-postgres/SKILL.md b/.agents/skills/prisma-postgres/SKILL.md
new file mode 100644
index 0000000..568543f
--- /dev/null
+++ b/.agents/skills/prisma-postgres/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: prisma-postgres
+description: Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres databases, working in Prisma Console, provisioning with create-db/create-pg/create-postgres, or integrating programmatic provisioning with service tokens or OAuth.
+license: MIT
+metadata:
+  author: prisma
+  version: "7.9.1"
+---
+
+# Prisma Postgres
+
+Guidance for creating, managing, and integrating Prisma Postgres across interactive and programmatic workflows.
+
+## When to Apply
+
+Reference this skill when:
+- Setting up Prisma Postgres from Prisma Console
+- Provisioning instant temporary databases with `create-db`
+- Linking an existing local project with `prisma postgres link`
+- Managing Prisma Postgres resources via Management API
+- Using `@prisma/management-api-sdk` in TypeScript/JavaScript
+- Handling claim URLs, connection strings, regions, and auth flows
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | CLI Provisioning | CRITICAL | `create-db-cli` |
+| 2 | Management API | CRITICAL | `management-api` |
+| 3 | Management API SDK | HIGH | `management-api-sdk` |
+| 4 | Console and Connections | HIGH | `console-and-connections` |
+
+## Quick Reference
+
+- `create-db-cli` - instant databases and current CLI flags (`--ttl`, `--copy`, `--quiet`, `--open`)
+- `management-api` - service token and OAuth API workflows
+- `management-api-sdk` - typed SDK usage with token storage
+- `console-and-connections` - Console operations, `prisma postgres link`, direct TCP connections, and serverless-driver choices
+
+## Core Workflows
+
+### 1. Console-first workflow
+
+Use Prisma Console for manual setup and operations:
+
+- Open `https://console.prisma.io`
+- Create/select workspace and project
+- Use Studio in the project sidebar to view/edit data
+- Retrieve direct connection details from the project UI
+
+### 2. Quick provisioning with create-db
+
+Use `create-db` when you need a database immediately:
+
+```bash
+npx create-db@latest
+```
+
+Aliases:
+
+```bash
+npx create-pg@latest
+npx create-postgres@latest
+```
+
+For app integrations, you can also use the programmatic API (`create()` / `regions()`) from the `create-db` npm package.
+
+Temporary databases auto-delete after ~24 hours unless claimed.
+
+### 2b. Persistent databases with the Platform CLI
+
+For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`:
+
+```bash
+npx -y @prisma/cli@latest database create --help
+npx -y @prisma/cli@latest database list --json
+npx -y @prisma/cli@latest database connection create db_123
+npx -y @prisma/cli@latest database usage db_123
+npx -y @prisma/cli@latest database backup list db_123
+```
+
+`database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm <id>`.
+
+For automation, prefer `--json --no-interactive`, resolve ids before mutations, and verify the installed command's help because this CLI is beta.
+
+### 3. Link an existing local project
+
+Use `prisma postgres link` when the database already exists and you want to wire a local project to it:
+
+```bash
+prisma postgres link
+```
+
+For CI or other non-interactive environments:
+
+```bash
+prisma postgres link --api-key "<your-api-key>" --database "db_..."
+```
+
+This flow updates your local `.env` with `DATABASE_URL`, then you can run `prisma generate` and `prisma migrate dev`.
+
+### 4. Programmatic provisioning with Management API
+
+Use API endpoints on:
+
+```text
+https://api.prisma.io/v1
+```
+
+Explore the schema and endpoints using:
+
+- OpenAPI docs: `https://api.prisma.io/v1/doc`
+- Swagger Editor: `https://api.prisma.io/v1/swagger-editor`
+
+Auth options:
+
+- Service token (workspace server-to-server)
+- OAuth 2.0 (act on behalf of users)
+
+### 5. Type-safe integration with Management API SDK
+
+Install and use:
+
+```bash
+npm install @prisma/management-api-sdk
+```
+
+Use `createManagementApiClient` for existing tokens, or `createManagementApiSdk` for OAuth + token refresh.
+
+The SDK exposes typed workspace service-token list, create, and revoke routes. A newly created token value is returned exactly once. Let the installed SDK types or OpenAPI document settle exact beta endpoint shapes.
+
+## Rule Files
+
+Detailed guidance lives in:
+
+```
+references/console-and-connections.md
+references/create-db-cli.md
+references/management-api.md
+references/management-api-sdk.md
+```
+
+## How to Use
+
+Start with `references/create-db-cli.md` for fast setup, then switch to `references/management-api.md` or `references/management-api-sdk.md` when you need programmatic provisioning.
diff --git a/.agents/skills/prisma-postgres/references/console-and-connections.md b/.agents/skills/prisma-postgres/references/console-and-connections.md
new file mode 100644
index 0000000..4025d12
--- /dev/null
+++ b/.agents/skills/prisma-postgres/references/console-and-connections.md
@@ -0,0 +1,69 @@
+# console-and-connections
+
+Use Prisma Console workflows for project visibility, data inspection, and connection setup.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+Many Prisma Postgres tasks are quickest in the Console: viewing Studio data, checking metrics, and retrieving connection details. This avoids unnecessary API or CLI work for simple operational tasks.
+
+## Console workflow
+
+1. Open `https://console.prisma.io`.
+2. Select workspace and project.
+3. Use dashboard metrics for usage and billing visibility.
+4. Open the **Studio** tab in the sidebar to inspect and edit data.
+
+## Local Studio
+
+You can also inspect data locally:
+
+```bash
+npx prisma studio
+```
+
+## Linking an existing project
+
+If the Prisma Postgres database already exists, link the local project instead of provisioning a new one:
+
+```bash
+prisma postgres link
+```
+
+For CI or non-interactive usage:
+
+```bash
+prisma postgres link --api-key "<your-api-key>" --database "db_..."
+```
+
+This command updates or creates `.env` with `DATABASE_URL`. If the project is already linked, use `--force` to re-link. After linking, run `prisma generate`, then `prisma migrate dev` if you need to apply the schema.
+
+## Connection setup
+
+For direct PostgreSQL tools and drivers:
+
+- Generate/copy direct connection credentials from the project connection UI.
+- Use the resulting PostgreSQL URL as `DATABASE_URL` for `pg` and `@prisma/adapter-pg`.
+- For Prisma Postgres direct TCP, include `sslmode=require`.
+
+Typical direct TCP format:
+
+```env
+DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require"
+```
+
+Management API connection responses expose both `endpoints.direct` (`db.prisma.io:5432`) and `endpoints.pooled` (`pooled.db.prisma.io:5432`); prefer those fields over the deprecated flat `connectionString`. Connection secrets are shown once at creation (one-time view); store them immediately.
+
+## Adapter choices
+
+- Standard Node.js apps: prefer `@prisma/adapter-pg` with the direct TCP URL above.
+- Edge/serverless runtimes: use `@prisma/adapter-ppg` with `@prisma/ppg` only when you specifically need the Prisma Postgres serverless driver.
+
+## References
+
+- [Prisma Postgres overview](https://www.prisma.io/docs/postgres/introduction/overview)
+- [Viewing data](https://www.prisma.io/docs/postgres/integrations/viewing-data)
+- [Direct connections](https://www.prisma.io/docs/postgres/database/direct-connections)
diff --git a/.agents/skills/prisma-postgres/references/create-db-cli.md b/.agents/skills/prisma-postgres/references/create-db-cli.md
new file mode 100644
index 0000000..7359b78
--- /dev/null
+++ b/.agents/skills/prisma-postgres/references/create-db-cli.md
@@ -0,0 +1,136 @@
+# create-db-cli
+
+Use `create-db` for instant Prisma Postgres provisioning from the terminal.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+`create-db` is the fastest way to get a working Prisma Postgres instance for development, demos, and CI previews. It can also emit machine-readable output and write env variables directly.
+
+## Commands
+
+```bash
+npx create-db@latest
+npx create-db@latest create [options]
+npx create-db@latest regions
+```
+
+Aliases:
+
+```bash
+npx create-pg@latest
+npx create-postgres@latest
+```
+
+## Command discovery (`--help`)
+
+Always use `--help` first when integrating CLI commands:
+
+```bash
+npx create-db@latest --help
+npx create-db@latest create --help
+npx create-db@latest regions --help
+```
+
+Top-level commands currently exposed:
+
+- `create` (default) to provision a database
+- `regions` to list available regions
+
+## `create` options
+
+| Flag | Shorthand | Description |
+|---|---|---|
+| `--region [string]` | `-r` | Region choice: `ap-southeast-1`, `ap-northeast-1`, `eu-central-1`, `eu-west-3`, `us-east-1`, `us-west-1` |
+| `--interactive [boolean]` | `-i` | Open region selector |
+| `--json [boolean]` | `-j` | Output machine-readable JSON |
+| `--env [string]` | `-e` | Write `DATABASE_URL` and `CLAIM_URL` into a target `.env` |
+| `--ttl [string]` | `-t` | Auto-delete after a TTL like `30m` or `1h-24h` |
+| `--copy [boolean]` | `-c` | Copy the connection string to the clipboard |
+| `--quiet [boolean]` | `-q` | Only print the connection string |
+| `--open [boolean]` | `-o` | Open the claim URL in your browser |
+
+## Lifecycle and claim flow
+
+- Databases are temporary by default.
+- Unclaimed databases are auto-deleted after ~24 hours.
+- Claim the database using the URL shown in command output to keep it permanently.
+
+## Programmatic usage (library API)
+
+You can also use `create-db` programmatically in Node.js/Bun instead of shelling out to the CLI.
+
+Install:
+
+```bash
+npm install create-db
+# or
+bun add create-db
+```
+
+Create a database:
+
+```ts
+import { create, isDatabaseSuccess, isDatabaseError } from "create-db";
+
+const result = await create({
+  region: "us-east-1",
+  userAgent: "my-app/1.0.0",
+});
+
+if (isDatabaseSuccess(result)) {
+  console.log(result.connectionString);
+  console.log(result.claimUrl);
+  console.log(result.deletionDate);
+}
+
+if (isDatabaseError(result)) {
+  console.error(result.error, result.message);
+}
+```
+
+List regions programmatically:
+
+```ts
+import { regions } from "create-db";
+
+const available = await regions();
+console.log(available);
+```
+
+Programmatic `create()` defaults to `us-east-1` if no region is passed.
+
+## Common patterns
+
+```bash
+# quick database
+npx create-db@latest
+
+# region-specific database
+npx create-db@latest --region eu-central-1
+
+# interactive region selection
+npx create-db@latest --interactive
+
+# write env vars for app bootstrap
+npx create-db@latest --env .env
+
+# auto-delete sooner
+npx create-db@latest --ttl 2h
+
+# copy connection string to clipboard
+npx create-db@latest --copy
+
+# print only the connection string
+npx create-db@latest --quiet
+
+# CI-friendly output
+npx create-db@latest --json
+```
+
+## References
+
+- [npx create-db docs](https://www.prisma.io/docs/postgres/introduction/npx-create-db)
diff --git a/.agents/skills/prisma-postgres/references/management-api-sdk.md b/.agents/skills/prisma-postgres/references/management-api-sdk.md
new file mode 100644
index 0000000..026aa5f
--- /dev/null
+++ b/.agents/skills/prisma-postgres/references/management-api-sdk.md
@@ -0,0 +1,70 @@
+# management-api-sdk
+
+Use `@prisma/management-api-sdk` for typed API integration with optional OAuth and token refresh.
+
+The Platform API evolves independently from Prisma ORM. Inspect the installed package's generated `api.d.ts` for exact paths and request/response shapes.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+The SDK provides typed endpoint methods and removes boilerplate around auth and refresh handling, which reduces errors in production provisioning flows.
+
+## Install
+
+```bash
+npm install @prisma/management-api-sdk
+```
+
+## Simple client (existing token)
+
+```typescript
+import { createManagementApiClient } from '@prisma/management-api-sdk'
+
+const client = createManagementApiClient({ token: process.env.PRISMA_SERVICE_TOKEN! })
+const { data: workspaces } = await client.GET('/v1/workspaces')
+```
+
+Check the generated client result before using `data`; typed clients surface HTTP failures separately. Never log a full response from connection/key creation because it may contain one-time credentials.
+
+## Workspace service tokens
+
+The typed client exposes routes to list, create, and revoke workspace service tokens:
+
+- `GET /v1/workspaces/{workspaceId}/service-tokens`
+- `POST /v1/workspaces/{workspaceId}/service-tokens`
+- `DELETE /v1/workspaces/{workspaceId}/service-tokens/{serviceTokenId}`
+
+Creation accepts a display `name`. The response's `data.value` is the complete token and is returned exactly once; transfer it directly to the intended secret store without logging the response. Later list calls return metadata and `valueHint`, not the token value. Treat revocation as destructive and resolve both ids explicitly.
+
+## Full SDK (OAuth + refresh)
+
+```typescript
+import { createManagementApiSdk, type TokenStorage } from '@prisma/management-api-sdk'
+
+const tokenStorage: TokenStorage = {
+  async getTokens() { return null },
+  async setTokens(tokens) {},
+  async clearTokens() {},
+}
+
+const api = createManagementApiSdk({
+  clientId: process.env.PRISMA_CLIENT_ID!,
+  redirectUri: 'https://your-app.com/auth/callback',
+  tokenStorage,
+})
+```
+
+## OAuth SDK flow
+
+1. Call `getLoginUrl()` and persist `state` + `verifier`.
+2. Redirect user to login URL.
+3. Handle callback with `handleCallback()`.
+4. Use `api.client` for typed endpoint calls.
+5. Call `logout()` when needed.
+
+## References
+
+- [Management API SDK docs](https://www.prisma.io/docs/postgres/introduction/management-api-sdk)
diff --git a/.agents/skills/prisma-postgres/references/management-api.md b/.agents/skills/prisma-postgres/references/management-api.md
new file mode 100644
index 0000000..4e4e76f
--- /dev/null
+++ b/.agents/skills/prisma-postgres/references/management-api.md
@@ -0,0 +1,79 @@
+# management-api
+
+Use Prisma Management API for programmatic provisioning and workspace/project/database management.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+When you need backend automation, multi-tenant onboarding flows, or controlled resource provisioning, the Management API is the source of truth and is more reliable than interactive workflows.
+
+## Base URL
+
+```text
+https://api.prisma.io/v1
+```
+
+## API exploration
+
+- OpenAPI docs: `https://api.prisma.io/v1/doc`
+- Swagger Editor: `https://api.prisma.io/v1/swagger-editor`
+
+## Authentication methods
+
+- Service token: best for server-to-server operations in your own workspace
+- OAuth 2.0: best for acting on behalf of users across workspaces
+
+## Service token flow
+
+1. Create token in Prisma Console workspace settings.
+2. Send token as Bearer auth:
+
+```text
+Authorization: Bearer $TOKEN
+```
+
+## OAuth flow summary
+
+1. Redirect user to `https://auth.prisma.io/authorize` with `client_id`, `redirect_uri`, `response_type=code`, and scopes.
+2. Receive `code` on callback.
+3. Exchange code at `https://auth.prisma.io/token`.
+4. Use returned access token in Management API requests.
+
+## Resource model
+
+Workspace -> Project -> Branch -> Database. Branches are a first-class resource: databases attach to a Branch, and branch-scoped env/databases are how preview isolation works.
+
+## Current resource inventory
+
+The 1.55 OpenAPI surface includes:
+
+- workspaces, subscriptions, workspace integrations, workspace service tokens, and current-user metadata
+- projects, transfers, project databases, and project/branch environment variables
+- branches under a project plus branch get/update/delete operations
+- databases, usage, backups, restore, connections, and connection rotation
+- apps, deployments, promotion/rollback, runtime logs, domains, and build logs
+- buckets and bucket keys
+- source repositories, SCM installations/install intents, and repositories
+- integrations and regions
+
+App/deployment, branch mutation, SCM, and bucket routes include experimental surfaces. Read the installed SDK types or live OpenAPI before building durable automation around them.
+
+Connection create/rotate responses reveal credentials once. Later reads redact or omit the secret, so store the URL immediately. Use the structured direct/pooled endpoint returned by the concrete operation; do not assume a historical flat response shape.
+
+Workspace service-token creation also returns the complete token value exactly once. List calls expose only metadata and a `valueHint`; delete revokes the token. Keep workspace and token ids opaque, and never log a create response.
+
+Database create supports explicit project, region, branch, and source context. A source may be empty, a backup, or another database. Backup records are incremental; rely on current fields and documented units rather than old full-backup examples.
+
+## Notes
+
+- Management API mutation responses may include direct connection credentials; treat the entire response as secret until redacted.
+- Prefer an API-provided connection string over manually assembling one from fields.
+
+## References
+
+- [Management API docs](https://www.prisma.io/docs/postgres/introduction/management-api)
+- [OpenAPI docs](https://api.prisma.io/v1/doc)
+- [Swagger Editor](https://api.prisma.io/v1/swagger-editor)
diff --git a/.agents/skills/react-hook-form/AGENTS.md b/.agents/skills/react-hook-form/AGENTS.md
new file mode 100644
index 0000000..a1e82a3
--- /dev/null
+++ b/.agents/skills/react-hook-form/AGENTS.md
@@ -0,0 +1,96 @@
+# React Hook Form
+
+**Version 2.1.0**  
+Community  
+July 2026
+
+> **Note:** This document targets React Hook Form codebases.
+> It is mainly for agents and LLMs to follow when maintaining, generating, or refactoring forms.
+> Humans may also find it useful, but guidance here is optimized for automation and consistency
+> by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Focused guide to the React Hook Form decisions a capable model gets wrong. Contains 35 rules across 7 categories, verified against react-hook-form 7.82.0 by diffing the shipped type definitions and type-checking every code block under tsc --strict against the real package types. Covers where a subscription must live to isolate re-renders, the third useForm generic that transforming resolvers require, the options that silently drop data from the submitted payload (register disabled, shouldUnregister, useFieldArray disabled), the NaN that valueAsNumber produces for an empty input, server error handling via setError('root.*'), resetDefaultValues() for rebasing the dirty baseline after a save, and the Watch / FormStateSubscribe / FieldArray render-prop components. Rules that merely restate what the library already does correctly have been removed.
+
+---
+
+## Table of Contents
+
+1. [Form Configuration](references/_sections.md#1-form-configuration) — **CRITICAL**
+   - 1.1 [Always Provide defaultValues for Form Initialization](references/formcfg-default-values.md) — CRITICAL (prevents uncontrolled-to-controlled input warnings and a reset() with nothing to restore)
+   - 1.2 [Depend on formState Slices, Not on formState Itself](references/formcfg-useeffect-dependency.md) — HIGH (prevents effects that re-run on every keystroke)
+   - 1.3 [Justify Any mode Other Than the Default onSubmit](references/formcfg-validation-mode.md) — CRITICAL (prevents a full validation pass and re-render on every keystroke)
+   - 1.4 [Keep Default reValidateMode Unless Validation Is Expensive](references/formcfg-revalidate-mode.md) — MEDIUM (maintains immediate corrective feedback after first submit)
+   - 1.5 [Keep shouldUnregister Off Unless Hidden Fields Must Leave the Payload](references/formcfg-should-unregister.md) — HIGH (prevents silently dropping values the user already entered)
+   - 1.6 [Pass the Third useForm Generic When the Resolver Transforms Values](references/formcfg-transformed-values-generic.md) — CRITICAL (makes handleSubmit receive the schema's output type instead of its input type)
+   - 1.7 [Use Async defaultValues for Server Data](references/formcfg-async-default-values.md) — CRITICAL (eliminates manual useEffect reset patterns)
+   - 1.8 [Use the HTML disabled Attribute for Visual Disabling, Not register's disabled Option](references/formcfg-disabled-prop.md) — MEDIUM (prevents fields silently missing from submission and skipped validation)
+   - 1.9 [Use the values Prop to Keep a Form in Sync with Server Data](references/formcfg-values-prop.md) — HIGH (replaces a useEffect+reset that overwrites edits whenever the query refetches)
+2. [Field Subscription](references/_sections.md#2-field-subscription) — **CRITICAL**
+   - 2.1 [Avoid Calling watch() in Render for One-Time Reads](references/sub-avoid-watch-in-render.md) — HIGH (prevents unnecessary subscriptions and re-renders)
+   - 2.2 [React.memo Cannot Stop Context-Driven Re-renders Under FormProvider](references/sub-memo-cannot-beat-context.md) — MEDIUM (replaces a memo pass that has no effect with isolation that does)
+   - 2.3 [Use subscribe() to React to Form Changes Outside the React Lifecycle](references/sub-subscribe-outside-react.md) — HIGH (eliminates re-renders for non-UI consumers like analytics, autosave, telemetry)
+   - 2.4 [Use the Render-Prop Components to Isolate Re-renders Without a Child Component](references/sub-render-prop-components.md) — HIGH (confines a subscription to one subtree without authoring a wrapper component)
+   - 2.5 [Use useFormContext Sparingly for Deep Nesting](references/sub-useformcontext-sparingly.md) — MEDIUM (reduces prop drilling but increases implicit dependencies)
+   - 2.6 [Use useWatch Instead of watch for Isolated Re-renders](references/sub-usewatch-over-watch.md) — CRITICAL (confines value-change re-renders to the subscribing component)
+   - 2.7 [Watch Specific Fields Instead of Entire Form](references/sub-watch-specific-fields.md) — CRITICAL (reduces re-renders from N fields to 1 field change)
+3. [Controlled Components](references/_sections.md#3-controlled-components) — **HIGH**
+   - 3.1 [Isolate Controlled Inputs in Dedicated Child Components](references/ctrl-usecontroller-isolation.md) — HIGH (re-renders only the changed field instead of the whole form)
+   - 3.2 [Wire Controller Field Props Correctly for UI Libraries](references/ctrl-controller-field-props.md) — HIGH (prevents a control that renders correctly but never writes back to the form)
+4. [Validation Patterns](references/_sections.md#4-validation-patterns) — **HIGH**
+   - 4.1 [Build the Validation Schema Once, Outside the Render Path](references/valid-resolver-caching.md) — HIGH (stops rebuilding the whole schema object on every keystroke)
+   - 4.2 [Handle the NaN valueAsNumber Produces for an Empty Input](references/valid-valueasnumber-empty-nan.md) — HIGH (prevents an optional number field that can never be left blank)
+   - 4.3 [Surface Server Errors via setError('root.serverError', ...)](references/valid-server-errors.md) — HIGH (prevents lost server-side validation errors and unrecoverable form state)
+   - 4.4 [Use delayError to Debounce Rapid Error Display](references/valid-delay-error.md) — MEDIUM (reduces UI flicker during fast typing validation)
+5. [State Management](references/_sections.md#5-state-management) — **MEDIUM-HIGH**
+   - 5.1 [Avoid isValid with onSubmit Mode for Button State](references/formstate-avoid-isvalid-with-onsubmit.md) — MEDIUM (prevents whole-form validation on every change under a deferred-validation mode)
+   - 5.2 [Read Every formState Property You Depend On During Render](references/formstate-destructure-formstate.md) — MEDIUM (prevents a component that never re-renders when the state it shows changes)
+   - 5.3 [Rebase Defaults with resetDefaultValues After a Successful Save](references/formstate-reset-default-values.md) — HIGH (clears isDirty without discarding edits made during the in-flight request)
+   - 5.4 [Use handleSubmit's Second Argument to Handle a Rejected Submit](references/formstate-handlesubmit-oninvalid.md) — MEDIUM (gives a failed submit somewhere to go instead of silently doing nothing)
+   - 5.5 [Use useFormState for Isolated State Subscriptions](references/formstate-useformstate-isolation.md) — MEDIUM (prevents parent re-renders from state access in children)
+   - 5.6 [Wrap Async Submit Handlers in try/catch and Reset on isSubmitSuccessful](references/formstate-async-submit-lifecycle.md) — HIGH (prevents stuck isSubmitting state and missing post-success reset)
+6. [Field Arrays](references/_sections.md#6-field-arrays) — **MEDIUM-HIGH**
+   - 6.1 [Separate Sequential Field Array Operations](references/array-separate-crud-operations.md) — MEDIUM-HIGH (prevents state corruption from batched mutations)
+   - 6.2 [Use field.id as Key in useFieldArray Maps](references/array-use-field-id-as-key.md) — MEDIUM-HIGH (prevents state corruption and unnecessary re-renders)
+   - 6.3 [Use Single useFieldArray Instance Per Field Name](references/array-unique-fieldarray-per-name.md) — MEDIUM-HIGH (prevents state conflicts from duplicate subscriptions)
+   - 6.4 [useFieldArray's disabled Option Makes Every Mutation a Silent No-op](references/array-disabled-silently-noops.md) — MEDIUM-HIGH (prevents append/remove calls that vanish with no error or warning)
+7. [Integration Patterns](references/_sections.md#7-integration-patterns) — **MEDIUM**
+   - 7.1 [Transform Values at Controller Level for Type Coercion](references/integ-value-transform.md) — MEDIUM (stops string input values reaching a number- or date-typed schema)
+   - 7.2 [Verify shadcn Form Component Import Source](references/integ-shadcn-form-import.md) — MEDIUM (prevents silent component mismatch bugs)
+   - 7.3 [Wire shadcn Select with onValueChange Instead of Spread](references/integ-shadcn-select-wiring.md) — MEDIUM (prevents a Radix Select that renders but never writes to the form)
+
+---
+
+## References
+
+1. [https://react-hook-form.com/docs](https://react-hook-form.com/docs)
+2. [https://react-hook-form.com/advanced-usage](https://react-hook-form.com/advanced-usage)
+3. [https://react-hook-form.com/docs/useform](https://react-hook-form.com/docs/useform)
+4. [https://react-hook-form.com/docs/useform/subscribe](https://react-hook-form.com/docs/useform/subscribe)
+5. [https://react-hook-form.com/docs/useform/seterror](https://react-hook-form.com/docs/useform/seterror)
+6. [https://react-hook-form.com/docs/useform/setvalue](https://react-hook-form.com/docs/useform/setvalue)
+7. [https://react-hook-form.com/docs/useform/resetdefaultvalues](https://react-hook-form.com/docs/useform/resetdefaultvalues)
+8. [https://react-hook-form.com/docs/useform/formstate](https://react-hook-form.com/docs/useform/formstate)
+9. [https://react-hook-form.com/docs/usewatch](https://react-hook-form.com/docs/usewatch)
+10. [https://react-hook-form.com/docs/usecontroller](https://react-hook-form.com/docs/usecontroller)
+11. [https://react-hook-form.com/docs/usefieldarray](https://react-hook-form.com/docs/usefieldarray)
+12. [https://react-hook-form.com/docs/useformstate](https://react-hook-form.com/docs/useformstate)
+13. [https://github.com/react-hook-form/react-hook-form/releases](https://github.com/react-hook-form/react-hook-form/releases)
+14. [https://github.com/react-hook-form/resolvers](https://github.com/react-hook-form/resolvers)
+15. [https://ui.shadcn.com/docs/components/form](https://ui.shadcn.com/docs/components/form)
+
+---
+
+## Source Files
+
+This document was compiled from individual reference files. For detailed editing or extension:
+
+| File | Description |
+|------|-------------|
+| [references/_sections.md](references/_sections.md) | Category definitions and impact ordering |
+| [assets/templates/_template.md](assets/templates/_template.md) | Template for creating new rules |
+| [SKILL.md](SKILL.md) | Quick reference entry point |
+| [metadata.json](metadata.json) | Version and reference URLs |
\ No newline at end of file
diff --git a/.agents/skills/react-hook-form/README.md b/.agents/skills/react-hook-form/README.md
new file mode 100644
index 0000000..be038dc
--- /dev/null
+++ b/.agents/skills/react-hook-form/README.md
@@ -0,0 +1,126 @@
+# React Hook Form Best Practices Skill
+
+Corrective guidance for React Hook Form — the decisions that go wrong by default.
+
+## Overview
+
+This skill provides 35 rules across 7 categories. Every rule names a decision that a capable model gets wrong by default; rules that merely restated correct library behaviour were removed in 2.0.0. Verified against **react-hook-form 7.82.0** (July 2026), with every code block type-checked under `tsc --strict` against the real package types.
+
+### Directory Structure
+
+```
+react-hook-form/
+├── SKILL.md                    # Entry point with quick reference
+├── AGENTS.md                   # Compiled comprehensive guide (TOC over references/)
+├── metadata.json               # Version, org, references
+├── README.md                   # This file
+├── assets/
+│   └── templates/
+│       └── _template.md        # Rule template
+└── references/
+    ├── _sections.md            # Category definitions and impact ordering
+    ├── formcfg-*.md            # Form configuration rules (9)
+    ├── sub-*.md                # Field subscription rules (7)
+    ├── ctrl-*.md               # Controlled component rules (2)
+    ├── valid-*.md              # Validation pattern rules (4)
+    ├── formstate-*.md          # State management rules (6)
+    ├── array-*.md              # Field array rules (4)
+    └── integ-*.md              # Integration pattern rules (3)
+```
+
+## Validating
+
+This skill is validated by the repo-level tooling, not by per-skill scripts:
+
+```bash
+npm run validate                                     # structural validation of every skill
+node /path/to/dev-skill/scripts/validate-skill.js .  # discipline-aware validation of this skill
+```
+
+## Creating a New Rule
+
+1. Choose the appropriate category prefix:
+
+| Category | Prefix | Impact |
+|----------|--------|--------|
+| Form Configuration | `formcfg-` | CRITICAL |
+| Field Subscription | `sub-` | CRITICAL |
+| Controlled Components | `ctrl-` | HIGH |
+| Validation Patterns | `valid-` | HIGH |
+| State Management | `formstate-` | MEDIUM-HIGH |
+| Field Arrays | `array-` | MEDIUM-HIGH |
+| Integration Patterns | `integ-` | MEDIUM |
+
+2. Create a new file: `references/{prefix}-{slug}.md`
+
+3. Use the rule template from `assets/templates/_template.md`
+
+4. Add the rule to the SKILL.md quick reference and to the AGENTS.md table of contents (entries are ordered alphabetically by title within each section).
+
+## Rule File Structure
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
+impactDescription: What the rule prevents or enables
+tags: prefix, keyword1, keyword2
+---
+
+## Rule Title Here
+
+Brief explanation of WHY this matters (1-3 sentences).
+
+**Incorrect (description of problem):**
+
+\`\`\`typescript
+// Bad code with comment on key line
+\`\`\`
+
+**Correct (description of solution):**
+
+\`\`\`typescript
+// Good code with minimal diff from incorrect
+\`\`\`
+
+Reference: [Documentation Link](https://example.com)
+```
+
+## File Naming Convention
+
+Rules follow the pattern: `{prefix}-{slug}.md`
+
+- **prefix**: Category identifier from `_sections.md` (lowercase letters only)
+- **slug**: Kebab-case description of the rule
+
+Examples:
+- `formcfg-validation-mode.md`
+- `sub-usewatch-over-watch.md`
+- `ctrl-usecontroller-isolation.md`
+
+## Impact Levels
+
+| Level | Description |
+|-------|-------------|
+| CRITICAL | Cascade effect on entire form performance |
+| HIGH | Significant impact on specific operations |
+| MEDIUM-HIGH | Notable improvement for common patterns |
+| MEDIUM | Measurable improvement in specific scenarios |
+| LOW-MEDIUM | Minor optimization for edge cases |
+| LOW | Best practice with minimal performance impact |
+
+## Companion Skill
+
+`react-hook-form-audit` is a static-analysis skill that detects violations of these rules in a Next.js App Router codebase and links each finding back to the corresponding file in `references/`.
+
+## Contributing
+
+1. Read existing rules in the same category for style consistency
+2. Ensure incorrect/correct examples have minimal diff
+3. Typecheck every example against the pinned react-hook-form version before committing
+4. Include authoritative reference links
+5. Run validation before submitting
+
+## Acknowledgments
+
+Based on official React Hook Form documentation, the library's shipped type definitions, and community best practices.
diff --git a/.agents/skills/react-hook-form/SKILL.md b/.agents/skills/react-hook-form/SKILL.md
new file mode 100644
index 0000000..dcf50ed
--- /dev/null
+++ b/.agents/skills/react-hook-form/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: react-hook-form
+description: React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
+---
+
+# React Hook Form Best Practices by Community
+
+Comprehensive performance optimization guide for React Hook Form applications. Contains 35 rules across 7 categories, each naming a decision that goes wrong by default. Verified against react-hook-form **7.82.0**.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new forms with React Hook Form
+- Configuring useForm options (mode, defaultValues, validation)
+- Subscribing to form values with watch / useWatch / subscribe
+- Integrating controlled UI components (MUI, shadcn, Ant Design)
+- Managing dynamic field arrays with useFieldArray
+- Handling async submit, server errors, and submit lifecycle state
+- Reviewing forms for performance issues
+
+## When NOT to Use This Skill
+
+- **React 19 Server Actions / `useActionState`** — use the `react-19` skill instead
+- **Deeply nested, fully type-safe forms** — TanStack Form may be a better fit for forms with complex nested schemas; this skill assumes you've already chosen RHF
+- **Single-input or trivial forms** — uncontrolled `<form>` + `FormData` is often simpler than pulling in any library
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Form Configuration | CRITICAL | `formcfg-` |
+| 2 | Field Subscription | CRITICAL | `sub-` |
+| 3 | Controlled Components | HIGH | `ctrl-` |
+| 4 | Validation Patterns | HIGH | `valid-` |
+| 5 | State Management | MEDIUM-HIGH | `formstate-` |
+| 6 | Field Arrays | MEDIUM-HIGH | `array-` |
+| 7 | Integration Patterns | MEDIUM | `integ-` |
+
+## Quick Reference
+
+### 1. Form Configuration (CRITICAL)
+
+- `formcfg-default-values` - Always Provide defaultValues for Form Initialization
+- `formcfg-useeffect-dependency` - Depend on formState Slices, Not on formState Itself
+- `formcfg-validation-mode` - Justify Any mode Other Than the Default onSubmit
+- `formcfg-revalidate-mode` - Keep Default reValidateMode Unless Validation Is Expensive
+- `formcfg-should-unregister` - Keep shouldUnregister Off Unless Hidden Fields Must Leave the Payload
+- `formcfg-transformed-values-generic` - Pass the Third useForm Generic When the Resolver Transforms Values
+- `formcfg-async-default-values` - Use Async defaultValues for Server Data
+- `formcfg-disabled-prop` - Use the HTML disabled Attribute for Visual Disabling, Not register's disabled Option
+- `formcfg-values-prop` - Use the values Prop to Keep a Form in Sync with Server Data
+
+### 2. Field Subscription (CRITICAL)
+
+- `sub-avoid-watch-in-render` - Avoid Calling watch() in Render for One-Time Reads
+- `sub-memo-cannot-beat-context` - React.memo Cannot Stop Context-Driven Re-renders Under FormProvider
+- `sub-subscribe-outside-react` - Use subscribe() to React to Form Changes Outside the React Lifecycle
+- `sub-render-prop-components` - Use the Render-Prop Components to Isolate Re-renders Without a Child Component
+- `sub-useformcontext-sparingly` - Use useFormContext Sparingly for Deep Nesting
+- `sub-usewatch-over-watch` - Use useWatch Instead of watch for Isolated Re-renders
+- `sub-watch-specific-fields` - Watch Specific Fields Instead of Entire Form
+
+### 3. Controlled Components (HIGH)
+
+- `ctrl-usecontroller-isolation` - Isolate Controlled Inputs in Dedicated Child Components
+- `ctrl-controller-field-props` - Wire Controller Field Props Correctly for UI Libraries
+
+### 4. Validation Patterns (HIGH)
+
+- `valid-resolver-caching` - Build the Validation Schema Once, Outside the Render Path
+- `valid-valueasnumber-empty-nan` - Handle the NaN valueAsNumber Produces for an Empty Input
+- `valid-server-errors` - Surface Server Errors via setError('root.serverError', ...)
+- `valid-delay-error` - Use delayError to Debounce Rapid Error Display
+
+### 5. State Management (MEDIUM-HIGH)
+
+- `formstate-avoid-isvalid-with-onsubmit` - Avoid isValid with onSubmit Mode for Button State
+- `formstate-destructure-formstate` - Read Every formState Property You Depend On During Render
+- `formstate-reset-default-values` - Rebase Defaults with resetDefaultValues After a Successful Save
+- `formstate-handlesubmit-oninvalid` - Use handleSubmit's Second Argument to Handle a Rejected Submit
+- `formstate-useformstate-isolation` - Use useFormState for Isolated State Subscriptions
+- `formstate-async-submit-lifecycle` - Wrap Async Submit Handlers in try/catch and Reset on isSubmitSuccessful
+
+### 6. Field Arrays (MEDIUM-HIGH)
+
+- `array-separate-crud-operations` - Separate Sequential Field Array Operations
+- `array-use-field-id-as-key` - Use field.id as Key in useFieldArray Maps
+- `array-unique-fieldarray-per-name` - Use Single useFieldArray Instance Per Field Name
+- `array-disabled-silently-noops` - useFieldArray's disabled Option Makes Every Mutation a Silent No-op
+
+### 7. Integration Patterns (MEDIUM)
+
+- `integ-value-transform` - Transform Values at Controller Level for Type Coercion
+- `integ-shadcn-form-import` - Verify shadcn Form Component Import Source
+- `integ-shadcn-select-wiring` - Wire shadcn Select with onValueChange Instead of Spread
+
+## How to Use
+
+Read individual reference files for detailed explanations and code examples:
+
+- [Section definitions](references/_sections.md) - Category structure and impact levels
+- [Rule template](assets/templates/_template.md) - Template for adding new rules
+- Reference files: `references/{prefix}-{slug}.md`
+
+## Related Skills
+
+- For schema validation with Zod resolver, see `zod` skill
+- For React 19 server actions, see `react-19` skill
+- For UI/UX form design, see `frontend-design` skill
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.agents/skills/react-hook-form/assets/templates/_template.md b/.agents/skills/react-hook-form/assets/templates/_template.md
new file mode 100644
index 0000000..4d0a698
--- /dev/null
+++ b/.agents/skills/react-hook-form/assets/templates/_template.md
@@ -0,0 +1,26 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: prefix, tag1, tag2
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/.agents/skills/react-hook-form/references/_sections.md b/.agents/skills/react-hook-form/references/_sections.md
new file mode 100644
index 0000000..0d9d723
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/_sections.md
@@ -0,0 +1,41 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Form Configuration (formcfg)
+
+**Impact:** CRITICAL
+**Description:** Initial useForm setup determines validation timing, re-render boundaries, and what ends up in the submitted payload. The wrong mode validates on every keystroke; the wrong disabled or shouldUnregister setting silently drops data.
+
+## 2. Field Subscription (sub)
+
+**Impact:** CRITICAL
+**Description:** Where a subscription lives decides how much of the tree re-renders. Reading a value at the form root instead of in the leaf that displays it is the difference between re-rendering the whole form and re-rendering one field.
+
+## 3. Controlled Components (ctrl)
+
+**Impact:** HIGH
+**Description:** Controller and useController isolate re-renders only when they sit in a child component. Wiring their field props to a third-party control also has to match that library's prop names, or the input renders but never writes back.
+
+## 4. Validation Patterns (valid)
+
+**Impact:** HIGH
+**Description:** Where the schema is constructed, how server-side failures re-enter the form, and how error display is paced. Building a schema inside render pays the construction cost on every keystroke.
+
+## 5. State Management (formstate)
+
+**Impact:** MEDIUM-HIGH
+**Description:** formState is a per-property Proxy, so a value you never read during render is a value you never re-render for. Submit lifecycle belongs here too: an async handler that throws without a catch strands isSubmitting forever.
+
+## 6. Field Arrays (array)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Dynamic field management requires stable keys and one owner per field name. Some options — notably disabled — fail silently rather than loudly.
+
+## 7. Integration Patterns (integ)
+
+**Impact:** MEDIUM
+**Description:** Third-party UI library integration (shadcn/Radix, MUI) requires specific wiring, and native inputs need explicit type coercion before values reach a typed schema.
diff --git a/.agents/skills/react-hook-form/references/array-disabled-silently-noops.md b/.agents/skills/react-hook-form/references/array-disabled-silently-noops.md
new file mode 100644
index 0000000..179ff73
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/array-disabled-silently-noops.md
@@ -0,0 +1,56 @@
+---
+title: useFieldArray's disabled Option Makes Every Mutation a Silent No-op
+impact: MEDIUM-HIGH
+impactDescription: prevents append/remove calls that vanish with no error or warning
+tags: array, useFieldArray, disabled, read-only, no-op
+---
+
+## useFieldArray's disabled Option Makes Every Mutation a Silent No-op
+
+`useFieldArray({ disabled })` (RHF 7.79+) is not a UI hint. When `disabled` is truthy, `append`, `prepend`, `insert`, `remove`, `swap`, `move`, `update`, and `replace` each return immediately — no mutation, no error, no console warning. Reaching for it as "grey the rows out while saving" produces a form where clicking Add does nothing and there is nothing in the console to explain why.
+
+**Incorrect (`disabled` tied to submit state — the append silently disappears):**
+
+```typescript
+function TeamMembersFields({ control }: { control: Control<TeamForm> }) {
+  const { isSubmitting } = useFormState({ control })
+  const { fields, append, remove } = useFieldArray({
+    control,
+    name: 'members',
+    disabled: isSubmitting,  // Also kills append/remove, not just the visuals
+  })
+
+  return (
+    <>
+      {fields.map((field, index) => (
+        <MemberRow key={field.id} index={index} onRemove={() => remove(index)} />
+      ))}
+      <button type="button" onClick={() => append({ email: '' })}>Add member</button>
+    </>
+  )
+}
+```
+
+**Correct (disable the controls; reserve the option for genuinely read-only arrays):**
+
+```typescript
+function TeamMembersFields({ control }: { control: Control<TeamForm> }) {
+  const { isSubmitting } = useFormState({ control })
+  const { fields, append, remove } = useFieldArray({ control, name: 'members' })
+
+  return (
+    <>
+      {fields.map((field, index) => (
+        <MemberRow key={field.id} index={index} onRemove={() => remove(index)} disabled={isSubmitting} />
+      ))}
+      <button type="button" onClick={() => append({ email: '' })} disabled={isSubmitting}>
+        Add member
+      </button>
+    </>
+  )
+}
+```
+
+Use `disabled: true` when the array is structurally immutable for this user — a locked invoice, a plan the current role may not edit — where a mutation slipping through would be a bug. In that case `fields[index].disabled` (7.80+) carries the flag down to each row so the inputs can render disabled from the same source of truth.
+
+Reference: [useFieldArray](https://react-hook-form.com/docs/usefieldarray)
diff --git a/.agents/skills/react-hook-form/references/array-separate-crud-operations.md b/.agents/skills/react-hook-form/references/array-separate-crud-operations.md
new file mode 100644
index 0000000..9182fb2
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/array-separate-crud-operations.md
@@ -0,0 +1,76 @@
+---
+title: Separate Sequential Field Array Operations
+impact: MEDIUM-HIGH
+impactDescription: prevents state corruption from batched mutations
+tags: array, useFieldArray, append, remove, sequential
+---
+
+## Separate Sequential Field Array Operations
+
+Chaining `append()` and `remove()` in the same handler can cause state corruption. Defer removals to a useEffect or separate user action to allow React to process renders between operations.
+
+**Incorrect (stacked operations cause state issues):**
+
+```typescript
+function ReplaceItemForm() {
+  const { control } = useForm()
+  const { fields, append, remove } = useFieldArray({ control, name: 'items' })
+
+  const replaceItem = (indexToReplace: number, newItem: Item) => {
+    remove(indexToReplace)  // Remove old item
+    append(newItem)  // Immediately add new - state may be stale
+  }
+
+  return (
+    <div>
+      {fields.map((field, index) => (
+        <ItemRow
+          key={field.id}
+          index={index}
+          onReplace={(newItem) => replaceItem(index, newItem)}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+**Correct (use update for replacements, or defer operations):**
+
+```typescript
+function ReplaceItemForm() {
+  const { control } = useForm()
+  const { fields, update } = useFieldArray({ control, name: 'items' })
+
+  const replaceItem = (indexToReplace: number, newItem: Item) => {
+    update(indexToReplace, newItem)  // Single atomic operation
+  }
+
+  return (
+    <div>
+      {fields.map((field, index) => (
+        <ItemRow
+          key={field.id}
+          index={index}
+          onReplace={(newItem) => replaceItem(index, newItem)}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+**Alternative (defer removal with useEffect):**
+
+```typescript
+const [pendingRemoval, setPendingRemoval] = useState<number | null>(null)
+
+useEffect(() => {
+  if (pendingRemoval !== null) {
+    remove(pendingRemoval)
+    setPendingRemoval(null)
+  }
+}, [pendingRemoval, remove])
+```
+
+Reference: [useFieldArray](https://react-hook-form.com/docs/usefieldarray)
diff --git a/.agents/skills/react-hook-form/references/array-unique-fieldarray-per-name.md b/.agents/skills/react-hook-form/references/array-unique-fieldarray-per-name.md
new file mode 100644
index 0000000..db00867
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/array-unique-fieldarray-per-name.md
@@ -0,0 +1,58 @@
+---
+title: Use Single useFieldArray Instance Per Field Name
+impact: MEDIUM-HIGH
+impactDescription: prevents state conflicts from duplicate subscriptions
+tags: array, useFieldArray, instance, state-management
+---
+
+## Use Single useFieldArray Instance Per Field Name
+
+Each field name should have only one useFieldArray instance. Multiple instances managing the same field name cause state conflicts and unpredictable behavior.
+
+**Incorrect (multiple instances for same field):**
+
+```typescript
+function OrderForm() {
+  const { control } = useForm()
+
+  return (
+    <div>
+      <ItemsList control={control} />
+      <ItemsSummary control={control} />
+    </div>
+  )
+}
+
+function ItemsList({ control }: { control: Control }) {
+  const { fields, append } = useFieldArray({ control, name: 'items' })  // Instance 1
+  return <div>{/* render items */}</div>
+}
+
+function ItemsSummary({ control }: { control: Control }) {
+  const { fields } = useFieldArray({ control, name: 'items' })  // Instance 2 - conflicts!
+  return <div>Total items: {fields.length}</div>
+}
+```
+
+**Correct (single instance, pass fields down or use useWatch):**
+
+```typescript
+function OrderForm() {
+  const { control } = useForm()
+  const { fields, append, remove } = useFieldArray({ control, name: 'items' })
+
+  return (
+    <div>
+      <ItemsList fields={fields} append={append} remove={remove} />
+      <ItemsSummary control={control} />  {/* Uses useWatch, not useFieldArray */}
+    </div>
+  )
+}
+
+function ItemsSummary({ control }: { control: Control }) {
+  const items = useWatch({ control, name: 'items' })  // Read-only subscription
+  return <div>Total items: {items?.length ?? 0}</div>
+}
+```
+
+Reference: [useFieldArray](https://react-hook-form.com/docs/usefieldarray)
diff --git a/.agents/skills/react-hook-form/references/array-use-field-id-as-key.md b/.agents/skills/react-hook-form/references/array-use-field-id-as-key.md
new file mode 100644
index 0000000..f9241df
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/array-use-field-id-as-key.md
@@ -0,0 +1,56 @@
+---
+title: Use field.id as Key in useFieldArray Maps
+impact: MEDIUM-HIGH
+impactDescription: prevents state corruption and unnecessary re-renders
+tags: array, useFieldArray, key, react-key
+---
+
+## Use field.id as Key in useFieldArray Maps
+
+useFieldArray generates a unique `id` for each field. Using array index as key causes React to lose track of component identity when items are reordered, removed, or inserted.
+
+**Incorrect (index as key causes state corruption):**
+
+```typescript
+function IngredientsForm() {
+  const { control, register } = useForm()
+  const { fields, append, remove } = useFieldArray({ control, name: 'ingredients' })
+
+  return (
+    <div>
+      {fields.map((field, index) => (
+        <div key={index}>  {/* Index key causes re-render issues */}
+          <input {...register(`ingredients.${index}.name`)} />
+          <button type="button" onClick={() => remove(index)}>Remove</button>
+        </div>
+      ))}
+      <button type="button" onClick={() => append({ name: '' })}>Add</button>
+    </div>
+  )
+}
+```
+
+**Correct (field.id ensures stable identity):**
+
+```typescript
+function IngredientsForm() {
+  const { control, register } = useForm()
+  const { fields, append, remove } = useFieldArray({ control, name: 'ingredients' })
+
+  return (
+    <div>
+      {fields.map((field, index) => (
+        <div key={field.id}>  {/* Stable identity across operations */}
+          <input {...register(`ingredients.${index}.name`)} />
+          <button type="button" onClick={() => remove(index)}>Remove</button>
+        </div>
+      ))}
+      <button type="button" onClick={() => append({ name: '' })}>Add</button>
+    </div>
+  )
+}
+```
+
+**Forward compatibility:** `field.id` is correct for all of v7. The v8 beta line renames the generated render key to `field.key` and drops the `keyName` option, so `id` becomes an ordinary data property that no longer guarantees uniqueness. Do not pre-emptively switch on v7 — but if you set `keyName` to something custom today, that is the piece with no v8 equivalent.
+
+Reference: [useFieldArray](https://react-hook-form.com/docs/usefieldarray)
diff --git a/.agents/skills/react-hook-form/references/ctrl-controller-field-props.md b/.agents/skills/react-hook-form/references/ctrl-controller-field-props.md
new file mode 100644
index 0000000..5b5b349
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/ctrl-controller-field-props.md
@@ -0,0 +1,56 @@
+---
+title: Wire Controller Field Props Correctly for UI Libraries
+impact: HIGH
+impactDescription: prevents a control that renders correctly but never writes back to the form
+tags: ctrl, Controller, field-props, ui-libraries
+---
+
+## Wire Controller Field Props Correctly for UI Libraries
+
+Different UI libraries expect different prop names. Map Controller's field props correctly: `onChange` sends data back, `onBlur` reports interaction, `value` sets the display, `ref` enables focus on error.
+
+**Incorrect (spreading field on incompatible component):**
+
+```typescript
+function FormWithSelect({ control }: { control: Control<ShippingFormValues> }) {
+  return (
+    <Controller
+      name="country"
+      control={control}
+      render={({ field }) => (
+        <Select {...field} />  // Select may not accept all field props directly
+      )}
+    />
+  )
+}
+```
+
+**Correct (manually wire required props):**
+
+```typescript
+function FormWithSelect({ control }: { control: Control<ShippingFormValues> }) {
+  return (
+    <Controller
+      name="country"
+      control={control}
+      render={({ field }) => (
+        <Select
+          value={field.value}
+          onValueChange={field.onChange}  // Map to component's change handler
+          onBlur={field.onBlur}
+        >
+          <SelectItem value="us">United States</SelectItem>
+          <SelectItem value="uk">United Kingdom</SelectItem>
+        </Select>
+      )}
+    />
+  )
+}
+```
+
+**Common mappings by library:**
+- MUI Select: `value`, `onChange` (receives event)
+- Radix/shadcn Select: `value`, `onValueChange` (receives value directly)
+- React Select: `value`, `onChange` (receives option object)
+
+Reference: [useController](https://react-hook-form.com/docs/usecontroller)
diff --git a/.agents/skills/react-hook-form/references/ctrl-usecontroller-isolation.md b/.agents/skills/react-hook-form/references/ctrl-usecontroller-isolation.md
new file mode 100644
index 0000000..e5e7ae2
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/ctrl-usecontroller-isolation.md
@@ -0,0 +1,80 @@
+---
+title: Isolate Controlled Inputs in Dedicated Child Components
+impact: HIGH
+impactDescription: re-renders only the changed field instead of the whole form
+tags: ctrl, useController, Controller, controlled-components, re-renders
+---
+
+## Isolate Controlled Inputs in Dedicated Child Components
+
+`Controller` and `useController` are equivalent — `Controller` is a thin component wrapper around `useController`. Re-render isolation does **not** come from picking one over the other. It comes from putting the subscription in a **child component**, so that when the field value changes, only the child re-renders. Inlining `Controller` (or `useController`) in the parent form makes every parent re-render flow through every controlled input.
+
+**Incorrect (Controllers inlined in parent — every parent re-render re-renders all controlled inputs):**
+
+```typescript
+function PaymentForm() {
+  const { control, handleSubmit } = useForm<PaymentFormData>()
+
+  return (
+    <form onSubmit={handleSubmit(submitPayment)}>
+      <Controller
+        name="amount"
+        control={control}
+        render={({ field }) => <CurrencyInput {...field} />}
+      />
+      <Controller
+        name="currency"
+        control={control}
+        render={({ field }) => <CurrencySelect {...field} />}
+      />
+    </form>
+  )
+}
+```
+
+**Correct (subscription moved into dedicated child components, isolating re-renders to the changed field):**
+
+```typescript
+function PaymentForm() {
+  const { control, handleSubmit } = useForm<PaymentFormData>()
+
+  return (
+    <form onSubmit={handleSubmit(submitPayment)}>
+      <AmountInput control={control} />
+      <CurrencySelectField control={control} />
+    </form>
+  )
+}
+
+function AmountInput({ control }: { control: Control<PaymentFormData> }) {
+  const { field } = useController({ name: 'amount', control })
+  return <CurrencyInput {...field} />
+}
+
+function CurrencySelectField({ control }: { control: Control<PaymentFormData> }) {
+  const { field } = useController({ name: 'currency', control })
+  return <CurrencySelect {...field} />
+}
+```
+
+**Equivalent with `Controller` (also correct — same isolation):**
+
+```typescript
+function AmountField({ control }: { control: Control<PaymentFormData> }) {
+  return (
+    <Controller
+      name="amount"
+      control={control}
+      render={({ field }) => <CurrencyInput {...field} />}
+    />
+  )
+}
+```
+
+**When to prefer one API over the other:**
+- `useController` — when you also need `fieldState`/`formState` in the same component, or want to compose with custom logic
+- `Controller` — when you want a single JSX-only declaration and don't need to read state in the surrounding component
+
+Both achieve the same re-render isolation when placed in a child component.
+
+Reference: [useController](https://react-hook-form.com/docs/usecontroller) · [Controller](https://react-hook-form.com/docs/usecontroller/controller)
diff --git a/.agents/skills/react-hook-form/references/formcfg-async-default-values.md b/.agents/skills/react-hook-form/references/formcfg-async-default-values.md
new file mode 100644
index 0000000..edd42cd
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-async-default-values.md
@@ -0,0 +1,69 @@
+---
+title: Use Async defaultValues for Server Data
+impact: CRITICAL
+impactDescription: eliminates manual useEffect reset patterns
+tags: formcfg, async, default-values, data-fetching
+---
+
+## Use Async defaultValues for Server Data
+
+React Hook Form supports async functions for `defaultValues`, eliminating the need for manual useEffect + reset() patterns when loading initial data from an API.
+
+**Incorrect (manual useEffect reset pattern):**
+
+```typescript
+function EditUserForm({ userId }: { userId: string }) {
+  const { register, reset, handleSubmit, formState: { isLoading } } = useForm({
+    defaultValues: {
+      email: '',
+      name: '',
+    },
+  })
+
+  useEffect(() => {
+    async function loadUser() {
+      const user = await fetchUser(userId)
+      reset(user)  // Manual reset required
+    }
+    loadUser()
+  }, [userId, reset])
+
+  if (isLoading) return <Spinner />
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      <input {...register('name')} />
+    </form>
+  )
+}
+```
+
+**Correct (async defaultValues handles loading automatically):**
+
+```typescript
+function EditUserForm({ userId }: { userId: string }) {
+  const { register, handleSubmit, formState: { isLoading } } = useForm({
+    defaultValues: async () => {
+      const user = await fetchUser(userId)
+      return {
+        email: user.email,
+        name: user.name,
+      }
+    },
+  })
+
+  if (isLoading) return <Spinner />
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      <input {...register('name')} />
+    </form>
+  )
+}
+```
+
+**Note:** defaultValues are cached after initial load. Use `reset()` with new values if you need to refresh data.
+
+Reference: [useForm - defaultValues](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formcfg-default-values.md b/.agents/skills/react-hook-form/references/formcfg-default-values.md
new file mode 100644
index 0000000..7e6f5e4
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-default-values.md
@@ -0,0 +1,58 @@
+---
+title: Always Provide defaultValues for Form Initialization
+impact: CRITICAL
+impactDescription: prevents uncontrolled-to-controlled input warnings and a reset() with nothing to restore
+tags: formcfg, default-values, initialization, useForm
+---
+
+## Always Provide defaultValues for Form Initialization
+
+`useForm<T>()` with no `defaultValues` starts every field as `undefined`. Three things break at once: any controlled input flips from uncontrolled to controlled on first keystroke (React logs a warning and can lose the value), `reset()` with no arguments has no baseline to restore to, and `isDirty`/`dirtyFields` compare against nothing so the form reads as dirty the moment anything is touched. Provide the full shape up front, using empty strings rather than `undefined`.
+
+**Incorrect (no defaultValues — reset() has no baseline, inputs start uncontrolled):**
+
+```typescript
+function ProfileForm({ user }: { user: User }) {
+  const { register, reset, handleSubmit } = useForm<ProfileFormValues>()
+
+  useEffect(() => {
+    reset(user)
+  }, [user, reset])
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('firstName')} />
+      <input {...register('lastName')} />
+      <button type="button" onClick={() => reset()}>Discard changes</button>
+    </form>
+  )
+}
+```
+
+**Correct (explicit defaults — reset() restores them, isDirty is meaningful):**
+
+```typescript
+function ProfileForm({ user }: { user: User }) {
+  const { register, reset, handleSubmit } = useForm<ProfileFormValues>({
+    defaultValues: { firstName: '', lastName: '' },
+  })
+
+  useEffect(() => {
+    reset(user)
+  }, [user, reset])
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('firstName')} />
+      <input {...register('lastName')} />
+      <button type="button" onClick={() => reset()}>Discard changes</button>
+    </form>
+  )
+}
+```
+
+When the defaults come from the server, pass them directly rather than defaulting-then-resetting — see `formcfg-async-default-values`. After a successful save, move the baseline with `resetDefaultValues` rather than `reset` (see `formstate-reset-default-values`).
+
+**Note:** Avoid custom objects with prototype methods (Moment, Luxon) as defaultValues — RHF deep-clones them. Use plain objects or primitives.
+
+Reference: [useForm - defaultValues](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formcfg-disabled-prop.md b/.agents/skills/react-hook-form/references/formcfg-disabled-prop.md
new file mode 100644
index 0000000..606c34e
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-disabled-prop.md
@@ -0,0 +1,83 @@
+---
+title: Use the HTML disabled Attribute for Visual Disabling, Not register's disabled Option
+impact: MEDIUM
+impactDescription: prevents fields silently missing from submission and skipped validation
+tags: formcfg, register, disabled, validation, footgun
+---
+
+## Use the HTML disabled Attribute for Visual Disabling, Not register's disabled Option
+
+Passing `disabled: true` to `register` (or to `useController`/`Controller`) tells RHF the field is "not part of submission": `handleSubmit` deletes the field from the values object it hands your handler, and validation for that field is skipped. It is **not** the same as `<input disabled>` for purely visual disabling. If you only want the input greyed out, use the plain HTML attribute.
+
+The value itself is **not** destroyed — `handleSubmit` unsets disabled names from a *clone* of the form values, so `getValues('promoCode')` still returns what the user typed and re-enabling the field brings it back into the payload. The bug this causes is a field that quietly vanishes from your submit handler while the UI still shows a value in it.
+
+**Incorrect (using register's disabled option for visual disabling — promoCode silently disappears from the submitted payload):**
+
+```typescript
+function CheckoutForm() {
+  const [usingGiftCard, setUsingGiftCard] = useState(false)
+  const { register, handleSubmit } = useForm<CheckoutFormData>({
+    defaultValues: { promoCode: '', giftCardCode: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(submitCheckout)}>
+      <label>
+        <input type="checkbox" onChange={(e) => setUsingGiftCard(e.target.checked)} />
+        Use a gift card
+      </label>
+      <input
+        {...register('promoCode', { disabled: usingGiftCard })}
+        // When usingGiftCard flips true, submitCheckout receives no promoCode key at all
+        // and its validation is skipped — while the input still shows the typed value.
+      />
+      <input {...register('giftCardCode', { disabled: !usingGiftCard })} />
+    </form>
+  )
+}
+```
+
+**Correct (use HTML disabled for visual-only disable; use register's disabled only when intentionally excluding the field):**
+
+```typescript
+function CheckoutForm() {
+  const [usingGiftCard, setUsingGiftCard] = useState(false)
+  const { register, handleSubmit, watch } = useForm<CheckoutFormData & { useShippingForBilling: boolean }>({
+    defaultValues: { promoCode: '', giftCardCode: '', useShippingForBilling: true, billingAddress: '' },
+  })
+  const useShippingForBilling = watch('useShippingForBilling')
+
+  return (
+    <form onSubmit={handleSubmit(submitCheckout)}>
+      <label>
+        <input type="checkbox" onChange={(e) => setUsingGiftCard(e.target.checked)} />
+        Use a gift card
+      </label>
+
+      {/* Visual disable only: value stays in form state, validation still runs */}
+      <input {...register('promoCode')} disabled={usingGiftCard} />
+      <input {...register('giftCardCode')} disabled={!usingGiftCard} />
+
+      {/* Intentional exclusion: when checked, billingAddress is omitted from submission */}
+      <label>
+        <input type="checkbox" {...register('useShippingForBilling')} />
+        Billing same as shipping
+      </label>
+      <input
+        {...register('billingAddress', {
+          disabled: useShippingForBilling,
+          required: !useShippingForBilling,
+        })}
+      />
+    </form>
+  )
+}
+```
+
+**Rule of thumb:**
+- Want the field greyed out but still submitted/validated → use the HTML `disabled` attribute directly on the input
+- Want the field excluded from submission and validation → use `register('name', { disabled: true })`
+
+If a value is disappearing from your submit handler, check for this option before suspecting `getValues()` — the two disagree by design.
+
+Reference: [register - disabled](https://react-hook-form.com/docs/useform/register)
diff --git a/.agents/skills/react-hook-form/references/formcfg-revalidate-mode.md b/.agents/skills/react-hook-form/references/formcfg-revalidate-mode.md
new file mode 100644
index 0000000..9b917cb
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-revalidate-mode.md
@@ -0,0 +1,58 @@
+---
+title: Keep Default reValidateMode Unless Validation Is Expensive
+impact: MEDIUM
+impactDescription: maintains immediate corrective feedback after first submit
+tags: formcfg, revalidate-mode, validation, useForm
+---
+
+## Keep Default reValidateMode Unless Validation Is Expensive
+
+After the first submit, `reValidateMode` controls when fields re-validate. The default is `onChange`, which gives users immediate positive feedback the moment they fix an error — this is the recommended UX in most cases ("don't eagerly scold, but eagerly reward"). Only switch to `onBlur` or `onSubmit` when validation is genuinely expensive (async checks, large schemas, heavy regex on long inputs).
+
+**Incorrect (switching reValidateMode to onBlur for a cheap synchronous schema):**
+
+```typescript
+function CheckoutForm() {
+  const { register, handleSubmit } = useForm<CheckoutFormData>({
+    mode: 'onSubmit',
+    reValidateMode: 'onBlur',  // Hurts UX: user fixes a wrong CVV and gets no feedback until blur
+    resolver: zodResolver(cheapSyncSchema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(placeOrder)}>
+      <input {...register('cardNumber')} />
+      <input {...register('cvv')} />
+    </form>
+  )
+}
+```
+
+**Correct (default onChange revalidation; switch only when validation is genuinely expensive):**
+
+```typescript
+function CheckoutForm() {
+  const { register, handleSubmit } = useForm<CheckoutFormData>({
+    mode: 'onSubmit',
+    // reValidateMode: 'onChange' is the default — leave it for immediate feedback on correction.
+    // Switch to 'onBlur' only if you have an async check or >16ms-per-keystroke validation cost.
+    resolver: zodResolver(cheapSyncSchema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(placeOrder)}>
+      <input {...register('cardNumber')} />
+      <input {...register('cvv')} />
+    </form>
+  )
+}
+```
+
+**When to deviate from the default:**
+- Validation involves a network call or expensive computation (>16ms per keystroke)
+- The form has dozens of fields and post-submit re-render cost is measurable in profiling
+- The error message is purely informational, not correctable in real time
+
+Otherwise keep `onChange` — users who just fixed an error get instant validation success, which is the UX the RHF defaults are tuned for.
+
+Reference: [useForm - reValidateMode](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formcfg-should-unregister.md b/.agents/skills/react-hook-form/references/formcfg-should-unregister.md
new file mode 100644
index 0000000..0ae5402
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-should-unregister.md
@@ -0,0 +1,56 @@
+---
+title: Keep shouldUnregister Off Unless Hidden Fields Must Leave the Payload
+impact: HIGH
+impactDescription: prevents silently dropping values the user already entered
+tags: formcfg, should-unregister, dynamic-forms, conditional-fields
+---
+
+## Keep shouldUnregister Off Unless Hidden Fields Must Leave the Payload
+
+The default (`shouldUnregister: false`) keeps a field's value in form state after its input unmounts. That is the right default and it is not a memory problem — the retained data is a few strings per field. `shouldUnregister: true` is a **submission-shape** option: it removes unmounted fields from the values object entirely. Reaching for it to "clean up" a multi-step wizard silently deletes everything the user entered on step 1 the moment they advance to step 2.
+
+**Incorrect (wizard loses step 1 the moment step 2 renders):**
+
+```typescript
+function OnboardingWizard() {
+  const [step, setStep] = useState(1)
+  const { register, handleSubmit } = useForm<OnboardingData>({
+    shouldUnregister: true,  // personalName is dropped as soon as step 1 unmounts
+    defaultValues: { personalName: '', companyName: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(completeOnboarding)}>
+      {step === 1 && <input {...register('personalName')} />}
+      {step === 2 && <input {...register('companyName')} />}
+      <button type="button" onClick={() => setStep(2)}>Next</button>
+    </form>
+  )
+}
+```
+
+**Correct (default retention — every step survives to submit):**
+
+```typescript
+function OnboardingWizard() {
+  const [step, setStep] = useState(1)
+  const { register, handleSubmit } = useForm<OnboardingData>({
+    defaultValues: { personalName: '', companyName: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(completeOnboarding)}>
+      {step === 1 && <input {...register('personalName')} />}
+      {step === 2 && <input {...register('companyName')} />}
+      <button type="button" onClick={() => setStep(2)}>Next</button>
+    </form>
+  )
+}
+```
+
+**When `shouldUnregister: true` is the right call:**
+- A discriminated payload where the hidden branch's keys must be absent, not empty — e.g. a "Business" account sends `taxId` and a "Personal" one must not send the key at all
+- A backend that treats a present-but-empty key differently from an absent one
+- Set it per field via `register('taxId', { shouldUnregister: true })` rather than form-wide, so the rest of the form keeps the safe default
+
+Reference: [useForm - shouldUnregister](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formcfg-transformed-values-generic.md b/.agents/skills/react-hook-form/references/formcfg-transformed-values-generic.md
new file mode 100644
index 0000000..a291b5b
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-transformed-values-generic.md
@@ -0,0 +1,70 @@
+---
+title: Pass the Third useForm Generic When the Resolver Transforms Values
+impact: CRITICAL
+impactDescription: makes handleSubmit receive the schema's output type instead of its input type
+tags: formcfg, generics, resolver, zod, transform, typescript
+---
+
+## Pass the Third useForm Generic When the Resolver Transforms Values
+
+`useForm` takes three generics: `useForm<TFieldValues, TContext, TTransformedValues>`. The first is what lives in the form (what inputs produce, before validation); the third is what `handleSubmit` hands your success callback. They are the same type only when the schema does no transformation.
+
+The moment a schema uses `z.coerce`, `.transform()`, or a `.default()`, input and output diverge — the form holds a string, the schema yields a `Date` or a `number`. Omit the third generic and TypeScript pins the output to the input type, which the resolver then contradicts. With `@hookform/resolvers` v5 the error lands on the `resolver:` property and reads like this:
+
+```text
+Type 'Resolver<{ arrivesOn: string; … }, any, { arrivesOn: Date; … }>' is not assignable to
+type 'Resolver<{ arrivesOn: string; … }, any, { arrivesOn: string; … }>'.
+  Types of property 'arrivesOn' are incompatible.
+    Type 'Date' is not assignable to type 'string'.
+```
+
+Nothing in that message mentions a missing generic, so the usual reactions are to cast the resolver, widen the schema until the transform is gone, or drop the resolver's type entirely — all of which trade a correct error for silently wrong types. This is the most common typing failure in RHF + Zod and the fix is one type argument.
+
+**Incorrect (one generic — the resolver's output type contradicts the form's, and handleSubmit is typed with the pre-validation input):**
+
+```typescript
+const bookingSchema = z.object({
+  guests: z.coerce.number().int().min(1),
+  arrivesOn: z.iso.date().transform((value) => new Date(value)),
+})
+
+type BookingInput = z.input<typeof bookingSchema>
+
+function BookingForm() {
+  const { register, handleSubmit } = useForm<BookingInput>({
+    resolver: zodResolver(bookingSchema),
+    defaultValues: { guests: '1', arrivesOn: '' },
+  })
+
+  // The resolver above fails to typecheck; values.arrivesOn is string, but is a Date at runtime
+  return <form onSubmit={handleSubmit((values) => createBooking(values))} />
+}
+```
+
+**Correct (three generics — the callback is typed with the schema's output):**
+
+```typescript
+const bookingSchema = z.object({
+  guests: z.coerce.number().int().min(1),
+  arrivesOn: z.iso.date().transform((value) => new Date(value)),
+})
+
+type BookingInput = z.input<typeof bookingSchema>
+type BookingOutput = z.output<typeof bookingSchema>
+
+function BookingForm() {
+  const { register, handleSubmit } = useForm<BookingInput, unknown, BookingOutput>({
+    resolver: zodResolver(bookingSchema),
+    defaultValues: { guests: '1', arrivesOn: '' },
+  })
+
+  // values.arrivesOn is Date, values.guests is number — matching runtime
+  return <form onSubmit={handleSubmit((values) => createBooking(values))} />
+}
+```
+
+The middle generic is the resolver context; pass `unknown` when you don't use one. Derive both types from the schema (`z.input` / `z.output`) rather than hand-writing them, so they can't drift.
+
+If `handleSubmit` is fighting you about a field type, check this generic before reaching for `as`.
+
+Reference: [useForm](https://react-hook-form.com/docs/useform) · [React Hook Form Resolvers](https://github.com/react-hook-form/resolvers)
diff --git a/.agents/skills/react-hook-form/references/formcfg-useeffect-dependency.md b/.agents/skills/react-hook-form/references/formcfg-useeffect-dependency.md
new file mode 100644
index 0000000..408db3b
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-useeffect-dependency.md
@@ -0,0 +1,62 @@
+---
+title: Depend on formState Slices, Not on formState Itself
+impact: HIGH
+impactDescription: prevents effects that re-run on every keystroke
+tags: formcfg, useEffect, dependencies, formState
+---
+
+## Depend on formState Slices, Not on formState Itself
+
+The `useForm()` return object is **stable**. `useForm` keeps it in a `useRef` and returns the same object on every render, mutating `formState` onto it — so `useEffect(fn, [form])` runs once, and `register`, `reset`, `control`, `setValue` and friends are all safe dependencies. (Widely repeated advice says the form object is a fresh reference each render and loops; that is not true of any v7 release.)
+
+The `formState` **proxy** is the part that changes. It is rebuilt via `useMemo` keyed on the underlying state, so it gets a new identity on every form-state update — every keystroke, in `onChange` mode. Depending on it re-runs the effect that often. Depend on the specific boolean you care about.
+
+**Incorrect (effect re-runs on every form-state update, not just on success):**
+
+```typescript
+function ContactForm({ onSaved }: { onSaved: () => void }) {
+  const { register, handleSubmit, reset, formState } = useForm({
+    defaultValues: { email: '' },
+  })
+
+  useEffect(() => {
+    if (formState.isSubmitSuccessful) {
+      reset()
+      onSaved()
+    }
+  }, [formState, reset, onSaved])  // New proxy identity on every keystroke
+
+  return (
+    <form onSubmit={handleSubmit(saveContact)}>
+      <input {...register('email')} />
+    </form>
+  )
+}
+```
+
+**Correct (depend on the slice that actually gates the effect):**
+
+```typescript
+function ContactForm({ onSaved }: { onSaved: () => void }) {
+  const { register, handleSubmit, reset, formState: { isSubmitSuccessful } } = useForm({
+    defaultValues: { email: '' },
+  })
+
+  useEffect(() => {
+    if (isSubmitSuccessful) {
+      reset()
+      onSaved()
+    }
+  }, [isSubmitSuccessful, reset, onSaved])  // Only flips once per successful submit
+
+  return (
+    <form onSubmit={handleSubmit(saveContact)}>
+      <input {...register('email')} />
+    </form>
+  )
+}
+```
+
+Destructuring also matters for a second reason: reading `formState.isSubmitSuccessful` is what registers the Proxy subscription in the first place — see `formstate-destructure-formstate`.
+
+Reference: [useForm](https://react-hook-form.com/docs/useform) · [formState](https://react-hook-form.com/docs/useform/formstate)
diff --git a/.agents/skills/react-hook-form/references/formcfg-validation-mode.md b/.agents/skills/react-hook-form/references/formcfg-validation-mode.md
new file mode 100644
index 0000000..903711f
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-validation-mode.md
@@ -0,0 +1,55 @@
+---
+title: Justify Any mode Other Than the Default onSubmit
+impact: CRITICAL
+impactDescription: prevents a full validation pass and re-render on every keystroke
+tags: formcfg, validation-mode, re-renders, useForm
+---
+
+## Justify Any mode Other Than the Default onSubmit
+
+`mode` decides when RHF validates. The default is `'onSubmit'`, and you should have to argue your way off it: `'onChange'` runs the field's validation — the whole resolver schema, if you use one — and re-renders on every keystroke. It gets reached for reflexively because "validate as they type" sounds like better UX, when in practice it means showing someone an "invalid email" error while they are still on the third character.
+
+**Incorrect (onChange chosen by default — errors fire mid-word, every keystroke re-validates):**
+
+```typescript
+function RegistrationForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<RegistrationData>({
+    mode: 'onChange',
+    defaultValues: { email: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(createAccount)}>
+      <input {...register('email', { pattern: { value: /^\S+@\S+$/, message: 'Enter a valid email' } })} />
+      {errors.email && <span>{errors.email.message}</span>}
+    </form>
+  )
+}
+```
+
+**Correct (leave the default; escalate only where it earns its keep):**
+
+```typescript
+function RegistrationForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<RegistrationData>({
+    defaultValues: { email: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(createAccount)}>
+      <input {...register('email', { pattern: { value: /^\S+@\S+$/, message: 'Enter a valid email' } })} />
+      {errors.email && <span>{errors.email.message}</span>}
+    </form>
+  )
+}
+```
+
+`reValidateMode` already defaults to `'onChange'`, so a field that has *failed* validation does give immediate feedback as the user corrects it — which is what people usually think they need `mode: 'onChange'` for.
+
+**Modes worth the escalation:**
+- `onTouched` — validate after the first blur, then on change. The usual right answer when submit-time errors feel too late.
+- `onBlur` — validate on blur only; quieter than `onTouched` while correcting.
+- `onChange` — password-strength meters, "username is available" checks, live-computed totals. Add a comment saying which.
+- `all` — `onBlur` and `onChange` together; rarely justified.
+
+Reference: [useForm - mode](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formcfg-values-prop.md b/.agents/skills/react-hook-form/references/formcfg-values-prop.md
new file mode 100644
index 0000000..4f055ec
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formcfg-values-prop.md
@@ -0,0 +1,61 @@
+---
+title: Use the values Prop to Keep a Form in Sync with Server Data
+impact: HIGH
+impactDescription: replaces a useEffect+reset that overwrites edits whenever the query refetches
+tags: formcfg, values, resetOptions, react-query, server-state
+---
+
+## Use the values Prop to Keep a Form in Sync with Server Data
+
+When the initial data arrives from a query, the reflex is `useEffect(() => reset(data), [data])`. That works until the query refetches — on window focus, on interval, after an unrelated mutation — and the effect fires again mid-edit, wiping whatever the user had typed.
+
+`useForm({ values })` is the built-in answer. RHF re-syncs the form when the `values` reference changes, and `resetOptions: { keepDirtyValues: true }` tells it to leave fields the user has touched alone while updating the ones they haven't. `defaultValues` still supplies the shape before the first response lands.
+
+**Incorrect (effect-driven reset — a background refetch discards in-progress edits):**
+
+```typescript
+function ProfileForm({ userId }: { userId: string }) {
+  const { data: profile } = useQuery({ queryKey: ['profile', userId], queryFn: fetchProfile })
+  const { register, reset, handleSubmit } = useForm<ProfileFormValues>({
+    defaultValues: { displayName: '', bio: '' },
+  })
+
+  useEffect(() => {
+    if (profile) reset(profile)  // Fires again on every refetch, mid-edit
+  }, [profile, reset])
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('displayName')} />
+    </form>
+  )
+}
+```
+
+**Correct (declarative sync that preserves what the user has touched):**
+
+```typescript
+function ProfileForm({ userId }: { userId: string }) {
+  const { data: profile } = useQuery({ queryKey: ['profile', userId], queryFn: fetchProfile })
+  const { register, handleSubmit } = useForm<ProfileFormValues>({
+    defaultValues: { displayName: '', bio: '' },
+    values: profile,
+    resetOptions: { keepDirtyValues: true },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('displayName')} />
+    </form>
+  )
+}
+```
+
+**Which initialiser to reach for:**
+- `defaultValues` — the shape and the baseline; required regardless (see `formcfg-default-values`)
+- `values` — the record is fetched and may change while the form is open
+- async `defaultValues` — the record is fetched once and will not change under the form (see `formcfg-async-default-values`)
+
+Drop `keepDirtyValues` only when a server change should win over the user's edit — a record another person may be editing concurrently, for instance.
+
+Reference: [useForm - values](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formstate-async-submit-lifecycle.md b/.agents/skills/react-hook-form/references/formstate-async-submit-lifecycle.md
new file mode 100644
index 0000000..806656e
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-async-submit-lifecycle.md
@@ -0,0 +1,79 @@
+---
+title: Wrap Async Submit Handlers in try/catch and Reset on isSubmitSuccessful
+impact: HIGH
+impactDescription: prevents stuck isSubmitting state and missing post-success reset
+tags: formstate, isSubmitting, isSubmitSuccessful, async, submit, reset
+---
+
+## Wrap Async Submit Handlers in try/catch and Reset on isSubmitSuccessful
+
+`isSubmitting` is the canonical way to disable the submit button while a request is in flight, but it has a well-known footgun: if your submit handler **throws**, `isSubmitting` stays `true` and the form becomes unrecoverable. Always `try/catch` inside the async handler. Pair this with `isSubmitSuccessful` + `useEffect(reset)` to clear the form after a successful submit (resetting inside the handler races with the success state transition).
+
+**Incorrect (throw leaves isSubmitting stuck; manual reset races):**
+
+```typescript
+function CreatePostForm() {
+  const { register, handleSubmit, reset, formState: { isSubmitting } } = useForm<PostFormData>()
+
+  const onSubmit = async (data: PostFormData) => {
+    const res = await fetch('/api/posts', { method: 'POST', body: JSON.stringify(data) })
+    if (!res.ok) throw new Error('Save failed')  // isSubmitting will stay true forever
+    reset()  // Races with the form's success state
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('title')} />
+      <textarea {...register('body')} />
+      <button disabled={isSubmitting}>{isSubmitting ? 'Saving…' : 'Save'}</button>
+    </form>
+  )
+}
+```
+
+**Correct (try/catch keeps form recoverable; useEffect resets after success):**
+
+```typescript
+function CreatePostForm() {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    setError,
+    formState: { isSubmitting, isSubmitSuccessful, errors },
+  } = useForm<PostFormData>()
+
+  const onSubmit = async (data: PostFormData) => {
+    try {
+      const res = await fetch('/api/posts', { method: 'POST', body: JSON.stringify(data) })
+      if (!res.ok) {
+        setError('root.serverError', { type: 'server', message: 'Save failed' })
+      }
+    } catch {
+      setError('root.serverError', { type: 'network', message: 'Network error — please retry' })
+    }
+  }
+
+  // Reset after a successful submit completes — runs once per success transition
+  useEffect(() => {
+    if (isSubmitSuccessful) reset()
+  }, [isSubmitSuccessful, reset])
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {errors.root?.serverError && <div role="alert">{errors.root.serverError.message}</div>}
+      <input {...register('title')} />
+      <textarea {...register('body')} />
+      <button disabled={isSubmitting}>{isSubmitting ? 'Saving…' : 'Save'}</button>
+    </form>
+  )
+}
+```
+
+**Key details:**
+- `isSubmitting` resets only when the handler **returns** (resolves). A throw leaves it `true` and the form unrecoverable
+- `isSubmitSuccessful` becomes `true` when the handler completes without throwing and without calling `setError`. Use it to gate the post-success reset
+- Calling `reset()` inside the submit handler races with React's commit of `isSubmitSuccessful`; the `useEffect` form is the documented pattern
+- If you want to preserve specific fields across reset, pass them: `reset(undefined, { keepDirtyValues: true })` or `reset({ defaultValue: lastSaved })`
+
+Reference: [formState](https://react-hook-form.com/docs/useform/formstate) · [reset](https://react-hook-form.com/docs/useform/reset) · [Discussion #10103 — isSubmitting does not recover when submit handler throws](https://github.com/orgs/react-hook-form/discussions/10103)
diff --git a/.agents/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md b/.agents/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md
new file mode 100644
index 0000000..e33cf9a
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md
@@ -0,0 +1,65 @@
+---
+title: Avoid isValid with onSubmit Mode for Button State
+impact: MEDIUM
+impactDescription: prevents whole-form validation on every change under a deferred-validation mode
+tags: formstate, isValid, onSubmit, validation-mode
+---
+
+## Avoid isValid with onSubmit Mode for Button State
+
+Subscribing to `isValid` opts the form into continuous validation. RHF only computes it when something reads it — `_setValid()` is gated on `isValid` being subscribed — but once it is, RHF runs the **whole form's** validation (the entire resolver schema, not just the changed field) on mount and again on every change event. Choosing `mode: 'onSubmit'` to defer validation and then reading `isValid` to grey out the submit button cancels out the deferral you asked for.
+
+(The cost is per change event, not per render: re-rendering the component without touching a field does not re-validate.)
+
+**Incorrect (isValid re-validates the whole form on every change despite onSubmit mode):**
+
+```typescript
+function RegistrationForm() {
+  const { register, handleSubmit, formState: { isValid } } = useForm<RegistrationData>({
+    defaultValues: { email: '', password: '' },  // mode defaults to 'onSubmit'
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email', { required: true })} />
+      <input {...register('password', { required: true })} />
+      <button disabled={!isValid}>Register</button>  {/* Opts the form into validating on every change */}
+    </form>
+  )
+}
+```
+
+**Correct (use isSubmitting or allow submit attempt):**
+
+```typescript
+function RegistrationForm() {
+  const { register, handleSubmit, formState: { isSubmitting } } = useForm<RegistrationData>({
+    defaultValues: { email: '', password: '' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email', { required: true })} />
+      <input {...register('password', { required: true })} />
+      <button disabled={isSubmitting}>
+        {isSubmitting ? 'Registering...' : 'Register'}
+      </button>
+    </form>
+  )
+}
+```
+
+**Alternative:** if a live-disabled submit button really is the requirement, say so explicitly rather than leaving the two settings in tension — pair `isValid` with a mode that already validates continuously:
+
+```typescript
+function RegistrationForm() {
+  const { register, formState: { isValid } } = useForm<RegistrationData>({
+    mode: 'onChange',  // Deliberate: the button reflects validity as the user types
+    defaultValues: { email: '', password: '' },
+  })
+
+  return <button disabled={!isValid}>Register</button>
+}
+```
+
+Reference: [useForm - mode](https://react-hook-form.com/docs/useform)
diff --git a/.agents/skills/react-hook-form/references/formstate-destructure-formstate.md b/.agents/skills/react-hook-form/references/formstate-destructure-formstate.md
new file mode 100644
index 0000000..91692dd
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-destructure-formstate.md
@@ -0,0 +1,49 @@
+---
+title: Read Every formState Property You Depend On During Render
+impact: MEDIUM
+impactDescription: prevents a component that never re-renders when the state it shows changes
+tags: formstate, formState, proxy, subscription, conditional
+---
+
+## Read Every formState Property You Depend On During Render
+
+`formState` is a Proxy: each property has a getter that marks it subscribed the first time it is read. Subscription is established by the *read*, not by how you write it — `formState.isValid`, `const { isValid } = formState`, and destructuring in the `useForm` call are all equivalent, and all three subscribe to exactly `isValid`. (The common claim that touching the whole object "disables the optimization" is not true; the getters are per-property.)
+
+The real trap is a property that is never read during render. Read it only inside a callback, or only in a branch that doesn't run on the first render, and the getter never fires — so RHF never re-renders the component when that property changes, and the UI silently stops updating.
+
+**Incorrect (isSubmitting is only read inside the handler — the button label never updates):**
+
+```typescript
+function SaveButton() {
+  const { handleSubmit, formState } = useForm<ArticleDraft>({ defaultValues: emptyDraft })
+
+  const onClick = handleSubmit(async (values) => {
+    if (formState.isSubmitting) return  // First read happens in a callback, after render
+    await saveDraft(values)
+  })
+
+  return <button onClick={onClick}>Save</button>
+}
+```
+
+**Correct (read it in the render body, so the subscription exists):**
+
+```typescript
+function SaveButton() {
+  const { handleSubmit, formState: { isSubmitting } } = useForm<ArticleDraft>({ defaultValues: emptyDraft })
+
+  const onClick = handleSubmit(async (values) => {
+    await saveDraft(values)
+  })
+
+  return (
+    <button onClick={onClick} disabled={isSubmitting}>
+      {isSubmitting ? 'Saving…' : 'Save'}
+    </button>
+  )
+}
+```
+
+The same applies to a conditional read: `{step === 2 && errors.email && …}` does not subscribe to `errors` until `step` reaches 2. Destructuring at the top of the component is the habit that makes this a non-issue, which is the real reason to do it.
+
+Reference: [formState](https://react-hook-form.com/docs/useform/formstate) · [useFormState](https://react-hook-form.com/docs/useformstate)
diff --git a/.agents/skills/react-hook-form/references/formstate-handlesubmit-oninvalid.md b/.agents/skills/react-hook-form/references/formstate-handlesubmit-oninvalid.md
new file mode 100644
index 0000000..24a076c
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-handlesubmit-oninvalid.md
@@ -0,0 +1,57 @@
+---
+title: Use handleSubmit's Second Argument to Handle a Rejected Submit
+impact: MEDIUM
+impactDescription: gives a failed submit somewhere to go instead of silently doing nothing
+tags: formstate, handleSubmit, onInvalid, errors, accessibility
+---
+
+## Use handleSubmit's Second Argument to Handle a Rejected Submit
+
+`handleSubmit(onValid, onInvalid)` takes two callbacks. Almost all code passes only the first, so when validation fails the click does nothing observable: no navigation, no request, and — on a long form — an error message somewhere below the fold that the user never scrolls to. They press the button again, harder.
+
+`onInvalid` receives the same `FieldErrors` object as `formState.errors` and is the natural place to move focus to the first bad field, scroll it into view, announce it, or record that submission is failing.
+
+**Incorrect (invalid submit is a no-op from the user's point of view):**
+
+```typescript
+function ApplicationForm() {
+  const { register, handleSubmit } = useForm<ApplicationValues>({
+    defaultValues: emptyApplication,
+  })
+
+  return (
+    <form onSubmit={handleSubmit(submitApplication)}>
+      {/* 40 fields; the invalid one may be far off-screen */}
+      <button type="submit">Submit application</button>
+    </form>
+  )
+}
+```
+
+**Correct (failed validation moves the user to the problem):**
+
+```typescript
+function ApplicationForm() {
+  const { register, handleSubmit, setFocus } = useForm<ApplicationValues>({
+    defaultValues: emptyApplication,
+  })
+
+  const onInvalid = (errors: FieldErrors<ApplicationValues>) => {
+    const firstField = Object.keys(errors)[0] as FieldPath<ApplicationValues> | undefined
+    if (firstField) setFocus(firstField, { shouldSelect: true })
+    trackEvent('application_submit_rejected', { fieldCount: Object.keys(errors).length })
+  }
+
+  return (
+    <form onSubmit={handleSubmit(submitApplication, onInvalid)}>
+      <button type="submit">Submit application</button>
+    </form>
+  )
+}
+```
+
+Note the two callbacks are typed differently: `onValid` receives the schema's **output** type (see `formcfg-transformed-values-generic`), while `onInvalid` receives errors keyed on the form's input type.
+
+RHF also focuses the first errored field itself when the field was registered with a ref — `onInvalid` is what you need when the control is custom, virtualized, or on another wizard step, where there is no ref to focus.
+
+Reference: [handleSubmit](https://react-hook-form.com/docs/useform/handlesubmit)
diff --git a/.agents/skills/react-hook-form/references/formstate-reset-default-values.md b/.agents/skills/react-hook-form/references/formstate-reset-default-values.md
new file mode 100644
index 0000000..f4dc448
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-reset-default-values.md
@@ -0,0 +1,70 @@
+---
+title: Rebase Defaults with resetDefaultValues After a Successful Save
+impact: HIGH
+impactDescription: clears isDirty without discarding edits made during the in-flight request
+tags: formstate, resetDefaultValues, isDirty, dirtyFields, save
+---
+
+## Rebase Defaults with resetDefaultValues After a Successful Save
+
+For a form that stays mounted after saving (settings pages, inline editors), the goal after a successful `PATCH` is to make `isDirty` false again — the saved values are the new baseline. The reflex is `reset(savedValues)`, but `reset` writes **both** `defaultValues` and the live form values. Any keystroke the user made while the request was in flight is silently thrown away, and controlled inputs re-mount.
+
+`resetDefaultValues(savedValues)` (RHF 7.77+, also exposed on `useFormContext` since 7.82) replaces `defaultValues` and recomputes `dirtyFields`/`isDirty` against the values already in the form, without touching them. Edits made during the save stay put and are correctly reported as dirty.
+
+**Incorrect (reset discards edits made while the save was in flight):**
+
+```typescript
+function NotificationSettingsForm({ settings }: { settings: NotificationSettings }) {
+  const { register, handleSubmit, reset, formState: { isDirty, isSubmitting } } =
+    useForm({ defaultValues: settings })
+
+  const onSubmit = async (values: NotificationSettings) => {
+    try {
+      const saved = await updateNotificationSettings(values)
+      reset(saved)  // Overwrites live values — anything typed during the request is lost
+    } catch {
+      setError('root.serverError', { message: 'Could not save settings' })
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('digestEmail')} />
+      <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+    </form>
+  )
+}
+```
+
+**Correct (rebase the baseline, keep the user's in-flight edits):**
+
+```typescript
+function NotificationSettingsForm({ settings }: { settings: NotificationSettings }) {
+  const { register, handleSubmit, resetDefaultValues, setError, formState: { isDirty, isSubmitting } } =
+    useForm({ defaultValues: settings })
+
+  const onSubmit = async (values: NotificationSettings) => {
+    try {
+      const saved = await updateNotificationSettings(values)
+      resetDefaultValues(saved)  // New baseline; live values untouched, isDirty recomputed against them
+    } catch {
+      setError('root.serverError', { message: 'Could not save settings' })
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('digestEmail')} />
+      <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+    </form>
+  )
+}
+```
+
+**Which to reach for:**
+- `resetDefaultValues(saved)` — form stays mounted and the user keeps editing; you only want the dirty baseline moved
+- `reset(saved)` — you genuinely want to discard the current values too (form closes, or you are loading a different record)
+
+`resetDefaultValues` accepts `{ keepDirty }` and `{ keepIsValid }` if you need to suppress either recomputation.
+
+Reference: [useForm - resetDefaultValues](https://react-hook-form.com/docs/useform/resetdefaultvalues)
diff --git a/.agents/skills/react-hook-form/references/formstate-useformstate-isolation.md b/.agents/skills/react-hook-form/references/formstate-useformstate-isolation.md
new file mode 100644
index 0000000..5532a02
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/formstate-useformstate-isolation.md
@@ -0,0 +1,71 @@
+---
+title: Use useFormState for Isolated State Subscriptions
+impact: MEDIUM
+impactDescription: prevents parent re-renders from state access in children
+tags: formstate, useFormState, isolation, re-renders
+---
+
+## Use useFormState for Isolated State Subscriptions
+
+useFormState allows subscribing to form state in child components without causing parent re-renders. Each useFormState instance is isolated and doesn't affect other subscribers.
+
+**Incorrect (formState at root re-renders entire form):**
+
+```typescript
+function ContactForm() {
+  const { register, handleSubmit, formState: { errors, isDirty } } = useForm()
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email', { required: true })} />
+      {errors.email && <span>Email required</span>}  {/* Re-renders all on any state change */}
+      <input {...register('message')} />
+      <SaveIndicator isDirty={isDirty} />  {/* Prop drilling */}
+    </form>
+  )
+}
+```
+
+**Correct (useFormState isolates subscriptions):**
+
+```typescript
+function ContactForm() {
+  const { register, handleSubmit, control } = useForm()
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <EmailField register={register} control={control} />
+      <input {...register('message')} />
+      <SaveIndicator control={control} />  {/* Isolated subscription */}
+    </form>
+  )
+}
+
+function EmailField({ register, control }: EmailFieldProps) {
+  const { errors } = useFormState({ control, name: 'email' })
+
+  return (
+    <div>
+      <input {...register('email', { required: true })} />
+      {errors.email && <span>Email required</span>}
+    </div>
+  )
+}
+
+function SaveIndicator({ control }: { control: Control }) {
+  const { isDirty } = useFormState({ control })
+
+  return isDirty ? <span>Unsaved changes</span> : null
+}
+```
+
+**Scope it further with `name`.** An isolated `useFormState({ control })` still re-renders on *any* field's state change. Pass `name` to narrow it to the fields the component actually displays:
+
+```typescript
+function EmailFieldError({ control }: { control: Control<SignupFormValues> }) {
+  const { errors } = useFormState({ control, name: 'email' })
+  return errors.email ? <span>{errors.email.message}</span> : null
+}
+```
+
+Reference: [useFormState](https://react-hook-form.com/docs/useformstate)
diff --git a/.agents/skills/react-hook-form/references/integ-shadcn-form-import.md b/.agents/skills/react-hook-form/references/integ-shadcn-form-import.md
new file mode 100644
index 0000000..9f3c686
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/integ-shadcn-form-import.md
@@ -0,0 +1,64 @@
+---
+title: Verify shadcn Form Component Import Source
+impact: MEDIUM
+impactDescription: prevents silent component mismatch bugs
+tags: integ, shadcn, imports, Form-component
+---
+
+## Verify shadcn Form Component Import Source
+
+React Hook Form exports its own `<Form>` component. When using shadcn/ui, ensure you import the shadcn Form wrapper, not RHF's Form. Auto-imports often get this wrong.
+
+**Incorrect (imports RHF Form instead of shadcn):**
+
+```typescript
+import { useForm, Form } from 'react-hook-form'  // Wrong Form!
+import { FormField, FormItem, FormLabel } from '@/components/ui/form'
+
+function LoginForm() {
+  const form = useForm()
+
+  return (
+    <Form {...form}>  {/* RHF Form doesn't work with shadcn FormField */}
+      <FormField
+        control={form.control}
+        name="email"
+        render={({ field }) => (
+          <FormItem>
+            <FormLabel>Email</FormLabel>
+            <Input {...field} />
+          </FormItem>
+        )}
+      />
+    </Form>
+  )
+}
+```
+
+**Correct (separate imports for each library):**
+
+```typescript
+import { useForm } from 'react-hook-form'
+import { Form, FormField, FormItem, FormLabel } from '@/components/ui/form'
+
+function LoginForm() {
+  const form = useForm()
+
+  return (
+    <Form {...form}>  {/* shadcn Form wraps FormProvider correctly */}
+      <FormField
+        control={form.control}
+        name="email"
+        render={({ field }) => (
+          <FormItem>
+            <FormLabel>Email</FormLabel>
+            <Input {...field} />
+          </FormItem>
+        )}
+      />
+    </Form>
+  )
+}
+```
+
+Reference: [shadcn Form](https://ui.shadcn.com/docs/components/form)
diff --git a/.agents/skills/react-hook-form/references/integ-shadcn-select-wiring.md b/.agents/skills/react-hook-form/references/integ-shadcn-select-wiring.md
new file mode 100644
index 0000000..de924ee
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/integ-shadcn-select-wiring.md
@@ -0,0 +1,64 @@
+---
+title: Wire shadcn Select with onValueChange Instead of Spread
+impact: MEDIUM
+impactDescription: prevents a Radix Select that renders but never writes to the form
+tags: integ, shadcn, select, radix
+---
+
+## Wire shadcn Select with onValueChange Instead of Spread
+
+shadcn's Select (built on Radix) uses `onValueChange` instead of `onChange`. Spreading field props directly doesn't work. Manually wire the value change handler.
+
+**Incorrect (spread doesn't work with Radix Select):**
+
+```typescript
+function CountrySelect({ control }: { control: Control }) {
+  return (
+    <FormField
+      control={control}
+      name="country"
+      render={({ field }) => (
+        <Select {...field}>  {/* field.onChange expects event, Radix passes value */}
+          <SelectTrigger>
+            <SelectValue placeholder="Select country" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="us">United States</SelectItem>
+            <SelectItem value="uk">United Kingdom</SelectItem>
+          </SelectContent>
+        </Select>
+      )}
+    />
+  )
+}
+```
+
+**Correct (wire props individually):**
+
+```typescript
+function CountrySelect({ control }: { control: Control }) {
+  return (
+    <FormField
+      control={control}
+      name="country"
+      render={({ field }) => (
+        <Select
+          value={field.value}
+          onValueChange={field.onChange}  // Radix passes value directly
+          onOpenChange={() => field.onBlur()}  // Trigger blur on close
+        >
+          <SelectTrigger>
+            <SelectValue placeholder="Select country" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="us">United States</SelectItem>
+            <SelectItem value="uk">United Kingdom</SelectItem>
+          </SelectContent>
+        </Select>
+      )}
+    />
+  )
+}
+```
+
+Reference: [shadcn Select](https://ui.shadcn.com/docs/components/select)
diff --git a/.agents/skills/react-hook-form/references/integ-value-transform.md b/.agents/skills/react-hook-form/references/integ-value-transform.md
new file mode 100644
index 0000000..8d76889
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/integ-value-transform.md
@@ -0,0 +1,59 @@
+---
+title: Transform Values at Controller Level for Type Coercion
+impact: MEDIUM
+impactDescription: stops string input values reaching a number- or date-typed schema
+tags: integ, transform, value-coercion, Controller
+---
+
+## Transform Values at Controller Level for Type Coercion
+
+Native inputs return strings. When your form needs numbers, dates, or other types, transform values in the Controller render function rather than relying solely on `valueAsNumber` or `valueAsDate`.
+
+**Incorrect (valueAsNumber has edge cases):**
+
+```typescript
+function QuantityInput() {
+  const { register } = useForm()
+
+  return (
+    <input
+      {...register('quantity', { valueAsNumber: true })}  // Returns NaN for empty string
+      type="number"
+    />
+  )
+}
+```
+
+**Correct (explicit transformation in Controller):**
+
+```typescript
+function QuantityInput({ control }: { control: Control }) {
+  return (
+    <Controller
+      name="quantity"
+      control={control}
+      render={({ field }) => (
+        <input
+          type="number"
+          value={field.value ?? ''}
+          onChange={(e) => {
+            const value = e.target.value
+            field.onChange(value === '' ? null : parseInt(value, 10))
+          }}
+          onBlur={field.onBlur}
+        />
+      )}
+    />
+  )
+}
+```
+
+**Alternative (Zod transform at schema level):**
+
+```typescript
+const schema = z.object({
+  quantity: z.string().transform((val) => (val === '' ? null : parseInt(val, 10))),
+})
+```
+
+Reference: [React Hook Form - Advanced Usage](https://react-hook-form.com/advanced-usage)
diff --git a/.agents/skills/react-hook-form/references/sub-avoid-watch-in-render.md b/.agents/skills/react-hook-form/references/sub-avoid-watch-in-render.md
new file mode 100644
index 0000000..610e526
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-avoid-watch-in-render.md
@@ -0,0 +1,48 @@
+---
+title: Avoid Calling watch() in Render for One-Time Reads
+impact: HIGH
+impactDescription: prevents unnecessary subscriptions and re-renders
+tags: sub, watch, getValues, render, one-time-read
+---
+
+## Avoid Calling watch() in Render for One-Time Reads
+
+If you only need to read a value once (not subscribe to changes), use `getValues()` instead of `watch()`. Calling watch() creates a subscription that triggers re-renders on every change.
+
+**Incorrect (watch creates subscription for one-time read):**
+
+```typescript
+function SubmitButton() {
+  const { watch, handleSubmit, formState: { isValid } } = useForm()
+
+  const handleClick = () => {
+    const email = watch('email')  // Creates subscription, but we only need current value
+    analytics.track('form_submit_attempt', { email })
+    handleSubmit(onSubmit)()
+  }
+
+  return <button onClick={handleClick} disabled={!isValid}>Submit</button>
+}
+```
+
+**Correct (getValues for one-time read):**
+
+```typescript
+function SubmitButton() {
+  const { getValues, handleSubmit, formState: { isValid } } = useForm()
+
+  const handleClick = () => {
+    const email = getValues('email')  // No subscription, just current value
+    analytics.track('form_submit_attempt', { email })
+    handleSubmit(onSubmit)()
+  }
+
+  return <button onClick={handleClick} disabled={!isValid}>Submit</button>
+}
+```
+
+**When to use each:**
+- `watch()`: Need to react to value changes (display, conditional rendering)
+- `getValues()`: Need current value at a point in time (event handlers, submit)
+
+Reference: [useForm - getValues](https://react-hook-form.com/docs/useform/getvalues)
diff --git a/.agents/skills/react-hook-form/references/sub-memo-cannot-beat-context.md b/.agents/skills/react-hook-form/references/sub-memo-cannot-beat-context.md
new file mode 100644
index 0000000..181240e
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-memo-cannot-beat-context.md
@@ -0,0 +1,51 @@
+---
+title: React.memo Cannot Stop Context-Driven Re-renders Under FormProvider
+impact: MEDIUM
+impactDescription: replaces a memo pass that has no effect with isolation that does
+tags: sub, FormProvider, memo, useFormContext, isolation
+---
+
+## React.memo Cannot Stop Context-Driven Re-renders Under FormProvider
+
+The instinct when a `FormProvider` tree re-renders too much is to wrap the heavy children in `React.memo`. It does nothing here. `React.memo` compares props; a component that calls `useFormContext()` is a context consumer, and a context value change re-renders it regardless of whether its props were equal. `FormProvider` already memoizes its own value, but `formState` is one of that memo's dependencies, so the value's identity does change on every form-state update — and every `useFormContext()` consumer under it re-renders.
+
+Wrapping in `memo` therefore buys nothing for the components you were worried about, and costs a comparison on every render for the ones you weren't.
+
+**Incorrect (memo on a context consumer — still re-renders on every form-state update):**
+
+```typescript
+const AddressSection = React.memo(function AddressSection() {
+  const { register, control } = useFormContext<CheckoutForm>()
+  const { errors } = useFormState<CheckoutForm>({ control })  // Consumes context; memo is bypassed
+
+  return (
+    <fieldset>
+      <input {...register('street')} />
+      {errors.street && <span>{errors.street.message}</span>}
+    </fieldset>
+  )
+})
+```
+
+**Correct (subscribe to the narrowest slice, so the re-render is cheap and local):**
+
+```typescript
+function AddressSection() {
+  const { register, control } = useFormContext<CheckoutForm>()
+
+  return (
+    <fieldset>
+      <input {...register('street')} />
+      <FormStateSubscribe
+        control={control}
+        name="street"
+        render={({ errors }) => (errors.street ? <span>{errors.street.message}</span> : null)}
+      />
+    </fieldset>
+  )
+}
+```
+
+`React.memo` is still worth reaching for on a genuinely expensive child that takes plain props and does **not** read form context — a chart, a map, a large static list rendered as a sibling of the form. The distinction is whether the component consumes context at all.
+
+Reference: [FormProvider](https://react-hook-form.com/docs/formprovider) · [useFormState](https://react-hook-form.com/docs/useformstate)
diff --git a/.agents/skills/react-hook-form/references/sub-render-prop-components.md b/.agents/skills/react-hook-form/references/sub-render-prop-components.md
new file mode 100644
index 0000000..c562d50
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-render-prop-components.md
@@ -0,0 +1,76 @@
+---
+title: Use the Render-Prop Components to Isolate Re-renders Without a Child Component
+impact: HIGH
+impactDescription: confines a subscription to one subtree without authoring a wrapper component
+tags: sub, Watch, FormStateSubscribe, FieldArray, isolation, render-prop
+---
+
+## Use the Render-Prop Components to Isolate Re-renders Without a Child Component
+
+Re-render isolation comes from putting the subscription somewhere other than the form component. The usual advice — extract a child component — works but costs a component and a prop-drilled `control` for every watched value. React Hook Form ships render-prop wrappers that do the same thing inline: `<Watch>` wraps `useWatch`, `<FormStateSubscribe>` wraps `useFormState`, and `<FieldArray>` (7.81+) wraps `useFieldArray`. Each is a one-line component that calls the hook and hands the result to `render`, so the subscription lives in that element and only that subtree re-renders.
+
+**Incorrect (hooks in the form component — every keystroke re-renders the whole form):**
+
+```typescript
+function InvoiceForm() {
+  const { control, register, handleSubmit } = useForm<Invoice>({ defaultValues: emptyInvoice })
+  const { fields, append } = useFieldArray({ control, name: 'lineItems' })
+  const [quantity, unitPrice] = useWatch({ control, name: ['quantity', 'unitPrice'] })
+  const { isDirty, isSubmitting } = useFormState({ control })
+
+  return (
+    <form onSubmit={handleSubmit(saveInvoice)}>
+      {fields.map((field, index) => (
+        <input key={field.id} {...register(`lineItems.${index}.description`)} />
+      ))}
+      <button type="button" onClick={() => append({ description: '' })}>Add line</button>
+      <p>Total: {quantity * unitPrice}</p>
+      <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+    </form>
+  )
+}
+```
+
+**Correct (each subscription confined to its own element):**
+
+```typescript
+function InvoiceForm() {
+  const { control, register, handleSubmit } = useForm<Invoice>({ defaultValues: emptyInvoice })
+
+  return (
+    <form onSubmit={handleSubmit(saveInvoice)}>
+      <FieldArray
+        control={control}
+        name="lineItems"
+        render={({ fields, append }) => (
+          <>
+            {fields.map((field, index) => (
+              <input key={field.id} {...register(`lineItems.${index}.description`)} />
+            ))}
+            <button type="button" onClick={() => append({ description: '' })}>Add line</button>
+          </>
+        )}
+      />
+      <Watch
+        control={control}
+        name={['quantity', 'unitPrice']}
+        render={([quantity, unitPrice]) => <p>Total: {quantity * unitPrice}</p>}
+      />
+      <FormStateSubscribe
+        control={control}
+        render={({ isDirty, isSubmitting }) => (
+          <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+        )}
+      />
+    </form>
+  )
+}
+```
+
+**Two traps in the current typings:**
+- `<Watch>` accepts both `name` and `names`. `names` is marked `@deprecated` in 7.82 and is renamed away in v8 — write `name`, even though the shipped JSDoc example still shows `names`.
+- `FieldArrayProps.render` is typed to return `React.ReactElement`, not `ReactNode[]`. Returning `fields.map(...)` directly fails to typecheck despite appearing that way in the shipped JSDoc — wrap the output in a fragment.
+
+Prefer an extracted child component when the subtree needs its own logic, handlers, or memoization; prefer the render-prop component when it is purely "read this value, render this markup".
+
+Reference: [useWatch](https://react-hook-form.com/docs/usewatch) · [useFieldArray](https://react-hook-form.com/docs/usefieldarray)
diff --git a/.agents/skills/react-hook-form/references/sub-subscribe-outside-react.md b/.agents/skills/react-hook-form/references/sub-subscribe-outside-react.md
new file mode 100644
index 0000000..1c78849
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-subscribe-outside-react.md
@@ -0,0 +1,92 @@
+---
+title: Use subscribe() to React to Form Changes Outside the React Lifecycle
+impact: HIGH
+impactDescription: eliminates re-renders for non-UI consumers like analytics, autosave, telemetry
+tags: sub, subscribe, side-effects, analytics, autosave, useForm
+---
+
+## Use subscribe() to React to Form Changes Outside the React Lifecycle
+
+Introduced in v7.55.0, `useForm().subscribe(...)` registers a callback that fires on form state or value changes **without causing any re-renders**. Use it when the consumer of the change is not a UI element — analytics, autosave to localStorage, debounced telemetry, sending drafts to a server. `useWatch` and `watch` are still right for things that paint to screen; `subscribe` is right for everything else.
+
+**Incorrect (using useWatch to drive a non-UI side-effect — re-renders the form on every keystroke):**
+
+```typescript
+function ProfileForm() {
+  const { register, handleSubmit, control } = useForm<ProfileFormData>()
+  const values = useWatch({ control })  // Every keystroke re-renders ProfileForm
+
+  useEffect(() => {
+    analytics.track('profile_field_edited', { values })  // Fires on every render
+  }, [values])
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('displayName')} />
+      <input {...register('bio')} />
+    </form>
+  )
+}
+```
+
+**Correct (subscribe() runs the side-effect with zero re-renders):**
+
+```typescript
+function ProfileForm() {
+  const { register, handleSubmit, subscribe } = useForm<ProfileFormData>()
+
+  useEffect(() => {
+    const unsubscribe = subscribe({
+      formState: { values: true },
+      callback: ({ values, name }) => {
+        analytics.track('profile_field_edited', { field: name, values })
+      },
+    })
+    return unsubscribe
+  }, [subscribe])
+
+  return (
+    <form onSubmit={handleSubmit(saveProfile)}>
+      <input {...register('displayName')} />
+      <input {...register('bio')} />
+    </form>
+  )
+}
+```
+
+**Subscribing to specific fields with formState slices (e.g. dirty-aware autosave):**
+
+```typescript
+function DraftEditor() {
+  const { register, subscribe } = useForm<DraftFormData>({
+    defaultValues: loadDraft(),
+  })
+
+  useEffect(() => {
+    const unsubscribe = subscribe({
+      name: ['title', 'body'],
+      formState: { values: true, isDirty: true },
+      callback: ({ values, isDirty }) => {
+        if (isDirty) debouncedSaveDraft(values)
+      },
+    })
+    return unsubscribe
+  }, [subscribe])
+
+  return (
+    <>
+      <input {...register('title')} />
+      <textarea {...register('body')} />
+    </>
+  )
+}
+```
+
+**When to use which:**
+- `useWatch` / `Controller` — the value drives a rendered element
+- `subscribe` — the value drives a non-UI side-effect (analytics, autosave, localStorage sync, telemetry)
+- `watch(callback)` — legacy callback form; prefer `subscribe` in new code (subscribe replaces the watch-callback pattern with explicit formState slicing and no implicit re-renders)
+
+`subscribe` returns an unsubscribe function — always return it from the `useEffect` cleanup to avoid leaks across remounts.
+
+Reference: [subscribe](https://react-hook-form.com/docs/useform/subscribe) · [Release notes v7.55.0](https://github.com/react-hook-form/react-hook-form/releases/tag/v7.55.0)
diff --git a/.agents/skills/react-hook-form/references/sub-useformcontext-sparingly.md b/.agents/skills/react-hook-form/references/sub-useformcontext-sparingly.md
new file mode 100644
index 0000000..1e38cf4
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-useformcontext-sparingly.md
@@ -0,0 +1,58 @@
+---
+title: Use useFormContext Sparingly for Deep Nesting
+impact: MEDIUM
+impactDescription: reduces prop drilling but increases implicit dependencies
+tags: sub, useFormContext, FormProvider, prop-drilling
+---
+
+## Use useFormContext Sparingly for Deep Nesting
+
+useFormContext eliminates prop drilling by accessing form methods via context, but creates implicit dependencies that are harder to track. Use it for deeply nested components; prefer explicit props for shallow nesting.
+
+**Incorrect (useFormContext for shallow nesting):**
+
+```typescript
+function ContactForm() {
+  const methods = useForm()
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <NameInput />  {/* One level deep, context overhead not needed */}
+        <EmailInput />
+      </form>
+    </FormProvider>
+  )
+}
+
+function NameInput() {
+  const { register } = useFormContext()  // Implicit dependency
+  return <input {...register('name')} />
+}
+```
+
+**Correct (explicit props for shallow nesting):**
+
+```typescript
+function ContactForm() {
+  const { register, handleSubmit } = useForm()
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <NameInput register={register} />  {/* Explicit dependency */}
+      <EmailInput register={register} />
+    </form>
+  )
+}
+
+function NameInput({ register }: { register: UseFormRegister<ContactFormData> }) {
+  return <input {...register('name')} />
+}
+```
+
+**When to use useFormContext:**
+- Components nested 3+ levels deep
+- Shared components used across multiple forms
+- Complex form sections with many fields
+
+Reference: [useFormContext](https://react-hook-form.com/docs/useformcontext)
diff --git a/.agents/skills/react-hook-form/references/sub-usewatch-over-watch.md b/.agents/skills/react-hook-form/references/sub-usewatch-over-watch.md
new file mode 100644
index 0000000..36d35c9
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-usewatch-over-watch.md
@@ -0,0 +1,60 @@
+---
+title: Use useWatch Instead of watch for Isolated Re-renders
+impact: CRITICAL
+impactDescription: confines value-change re-renders to the subscribing component
+tags: sub, useWatch, watch, re-renders, subscription
+---
+
+## Use useWatch Instead of watch for Isolated Re-renders
+
+The `watch()` method triggers re-renders at the useForm hook level, affecting the entire form component. Use `useWatch()` in child components to isolate re-renders to only the components that need the watched value.
+
+**Incorrect (watch at root causes entire form to re-render):**
+
+```typescript
+function CheckoutForm() {
+  const { register, watch, handleSubmit } = useForm()
+  const shippingMethod = watch('shippingMethod')  // Every change re-renders entire form
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <select {...register('shippingMethod')}>
+        <option value="standard">Standard</option>
+        <option value="express">Express</option>
+      </select>
+      <ShippingCost method={shippingMethod} />
+      <input {...register('address')} />
+      <input {...register('city')} />
+    </form>
+  )
+}
+```
+
+**Correct (useWatch isolates re-render to child component):**
+
+```typescript
+function CheckoutForm() {
+  const { register, handleSubmit, control } = useForm()
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <select {...register('shippingMethod')}>
+        <option value="standard">Standard</option>
+        <option value="express">Express</option>
+      </select>
+      <ShippingCostDisplay control={control} />  {/* Only this re-renders */}
+      <input {...register('address')} />
+      <input {...register('city')} />
+    </form>
+  )
+}
+
+function ShippingCostDisplay({ control }: { control: Control<CheckoutFormData> }) {
+  const shippingMethod = useWatch({ control, name: 'shippingMethod' })
+  return <ShippingCost method={shippingMethod} />
+}
+```
+
+**Push the subscription as deep as it will go.** The win is not `useWatch` over `watch` in itself — it is *where the subscription lives*. A `useWatch` at the top of the form re-renders the whole form exactly like `watch` does. Put it in the leaf that renders the value, and pass `control` down rather than the watched value; the sibling sections then never re-render. If you don't want to author a component for it, `<Watch>` does the same inline — see `sub-render-prop-components`.
+
+Reference: [useWatch](https://react-hook-form.com/docs/usewatch)
diff --git a/.agents/skills/react-hook-form/references/sub-watch-specific-fields.md b/.agents/skills/react-hook-form/references/sub-watch-specific-fields.md
new file mode 100644
index 0000000..e0715eb
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/sub-watch-specific-fields.md
@@ -0,0 +1,54 @@
+---
+title: Watch Specific Fields Instead of Entire Form
+impact: CRITICAL
+impactDescription: reduces re-renders from N fields to 1 field change
+tags: sub, watch, specific-fields, re-renders
+---
+
+## Watch Specific Fields Instead of Entire Form
+
+Calling `watch()` without arguments subscribes to ALL form fields, causing re-renders on any field change. Always specify the field names you need.
+
+**Incorrect (watches all fields, re-renders on any change):**
+
+```typescript
+function OrderForm() {
+  const { register, watch, handleSubmit } = useForm()
+  const formValues = watch()  // Re-renders when ANY field changes
+
+  const total = calculateTotal(formValues.quantity, formValues.price)
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('customerName')} />  {/* Changes here trigger total recalc */}
+      <input {...register('email')} />  {/* Changes here trigger total recalc */}
+      <input {...register('quantity', { valueAsNumber: true })} />
+      <input {...register('price', { valueAsNumber: true })} />
+      <div>Total: ${total}</div>
+    </form>
+  )
+}
+```
+
+**Correct (watches only needed fields):**
+
+```typescript
+function OrderForm() {
+  const { register, watch, handleSubmit } = useForm()
+  const [quantity, price] = watch(['quantity', 'price'])  // Only re-renders when these change
+
+  const total = calculateTotal(quantity, price)
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('customerName')} />  {/* No re-render on change */}
+      <input {...register('email')} />  {/* No re-render on change */}
+      <input {...register('quantity', { valueAsNumber: true })} />
+      <input {...register('price', { valueAsNumber: true })} />
+      <div>Total: ${total}</div>
+    </form>
+  )
+}
+```
+
+Reference: [useForm - watch](https://react-hook-form.com/docs/useform/watch)
diff --git a/.agents/skills/react-hook-form/references/valid-delay-error.md b/.agents/skills/react-hook-form/references/valid-delay-error.md
new file mode 100644
index 0000000..b4161d9
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/valid-delay-error.md
@@ -0,0 +1,62 @@
+---
+title: Use delayError to Debounce Rapid Error Display
+impact: MEDIUM
+impactDescription: reduces UI flicker during fast typing validation
+tags: valid, delayError, debounce, user-experience
+---
+
+## Use delayError to Debounce Rapid Error Display
+
+When using `onChange` mode, errors appear and disappear rapidly as users type. Use `delayError` to add a small delay, preventing UI flicker while still providing timely feedback.
+
+**Incorrect (errors flash rapidly during typing):**
+
+```typescript
+function SearchForm() {
+  const { register, formState: { errors } } = useForm({
+    mode: 'onChange',
+  })
+
+  return (
+    <form>
+      <input {...register('query', { minLength: 3 })} />
+      {errors.query && <span>Min 3 characters</span>}  {/* Flashes on/off rapidly */}
+    </form>
+  )
+}
+```
+
+**Correct (error display debounced):**
+
+```typescript
+function SearchForm() {
+  const { register, formState: { errors } } = useForm({
+    mode: 'onChange',
+    delayError: 300,  // 300ms delay before showing errors
+  })
+
+  return (
+    <form>
+      <input {...register('query', { minLength: 3 })} />
+      {errors.query && <span>Min 3 characters</span>}  {/* Appears after 300ms delay */}
+    </form>
+  )
+}
+```
+
+**When to use:**
+- Real-time validation with `onChange` mode
+- Fields with character count requirements
+- Search inputs with minimum length
+
+**Opting a single `setValue` into the delay (7.82+):** `setValue` accepts `delayError`, but it is a **boolean** — it opts that call into the debounce, and the duration still comes from `useForm({ delayError })`. Passing a number is a type error, even though the 7.82.0 release notes show `delayError: 500`:
+
+```typescript
+const { setValue } = useForm({ mode: 'onChange', delayError: 300 })
+
+setValue('query', suggestion, { shouldValidate: true, delayError: true })  // debounced by 300ms
+```
+
+Without a form-level `delayError`, `{ delayError: true }` on `setValue` has nothing to debounce with and the error appears immediately.
+
+Reference: [useForm - delayError](https://react-hook-form.com/docs/useform) · [useForm - setValue](https://react-hook-form.com/docs/useform/setvalue)
diff --git a/.agents/skills/react-hook-form/references/valid-resolver-caching.md b/.agents/skills/react-hook-form/references/valid-resolver-caching.md
new file mode 100644
index 0000000..9be1128
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/valid-resolver-caching.md
@@ -0,0 +1,82 @@
+---
+title: Build the Validation Schema Once, Outside the Render Path
+impact: HIGH
+impactDescription: stops rebuilding the whole schema object on every keystroke
+tags: valid, resolver, schema, zod, useMemo
+---
+
+## Build the Validation Schema Once, Outside the Render Path
+
+There is no resolver cache in React Hook Form — `useForm` reassigns `control._options = props` on every render, and whatever resolver you passed is used as-is. The cost of an inline schema is the **construction**: `z.object({ … })` allocates a fresh validator tree every render, and under `mode: 'onChange'` that is once per keystroke, on top of the validation itself. Hoisting the schema to module scope makes it a one-time cost at import.
+
+**Incorrect (a new schema object built on every render):**
+
+```typescript
+function InviteMemberForm() {
+  const { register, handleSubmit } = useForm<InviteFormValues>({
+    resolver: zodResolver(
+      z.object({
+        email: z.email('Enter a valid email address'),
+        role: z.enum(['admin', 'editor', 'viewer']),
+      }),
+    ),
+    defaultValues: { email: '', role: 'viewer' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(sendInvite)}>
+      <input {...register('email')} />
+    </form>
+  )
+}
+```
+
+**Correct (built once at module load):**
+
+```typescript
+const inviteSchema = z.object({
+  email: z.email('Enter a valid email address'),
+  role: z.enum(['admin', 'editor', 'viewer']),
+})
+
+function InviteMemberForm() {
+  const { register, handleSubmit } = useForm<InviteFormValues>({
+    resolver: zodResolver(inviteSchema),
+    defaultValues: { email: '', role: 'viewer' },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(sendInvite)}>
+      <input {...register('email')} />
+    </form>
+  )
+}
+```
+
+**When the schema genuinely depends on props or context**, hoist a factory instead of the schema and memoize the call — so it rebuilds when the input changes, not when the component renders:
+
+```typescript
+const createSeatSchema = (maxSeats: number) =>
+  z.object({
+    seats: z.number().int().max(maxSeats, `Your plan allows ${maxSeats} seats`),
+  })
+
+function SeatAllocationForm({ maxSeats }: { maxSeats: number }) {
+  const schema = useMemo(() => createSeatSchema(maxSeats), [maxSeats])
+
+  const { register, handleSubmit } = useForm<SeatFormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { seats: 1 },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(updateSeats)}>
+      <input type="number" {...register('seats', { valueAsNumber: true })} />
+    </form>
+  )
+}
+```
+
+Prefer a schema-level `.refine()` over a factory when the rule depends on *other fields* rather than on props — cross-field rules don't need the schema rebuilt.
+
+Reference: [React Hook Form Resolvers](https://github.com/react-hook-form/resolvers)
diff --git a/.agents/skills/react-hook-form/references/valid-server-errors.md b/.agents/skills/react-hook-form/references/valid-server-errors.md
new file mode 100644
index 0000000..e838f02
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/valid-server-errors.md
@@ -0,0 +1,85 @@
+---
+title: Surface Server Errors via setError('root.serverError', ...)
+impact: HIGH
+impactDescription: prevents lost server-side validation errors and unrecoverable form state
+tags: valid, server-errors, setError, async, error-handling
+---
+
+## Surface Server Errors via setError('root.serverError', ...)
+
+`handleSubmit` does not catch errors thrown inside async submit handlers — it logs them and silently leaves the form unrecoverable (`isSubmitting` stays `true` if you `throw`). The canonical pattern is to `try/catch` inside the submit handler and route API failures into `setError`. Use field-level `setError(name, ...)` when the server tells you which field is wrong; use `setError('root.serverError', ...)` for general failures (network error, 500, "Account is locked").
+
+**Incorrect (server error is thrown, swallowed, and form is now stuck):**
+
+```typescript
+function LoginForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<LoginFormData>()
+
+  const onSubmit = async (data: LoginFormData) => {
+    const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify(data) })
+    if (!res.ok) throw new Error('Login failed')  // Lost: no UI feedback, isSubmitting stuck
+    redirect('/dashboard')
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      <input type="password" {...register('password')} />
+      <button disabled={isSubmitting}>Sign in</button>
+    </form>
+  )
+}
+```
+
+**Correct (server errors surfaced via setError, form stays recoverable):**
+
+```typescript
+function LoginForm() {
+  const {
+    register,
+    handleSubmit,
+    setError,
+    clearErrors,
+    formState: { errors, isSubmitting },
+  } = useForm<LoginFormData>()
+
+  const onSubmit = async (data: LoginFormData) => {
+    clearErrors('root.serverError')
+    try {
+      const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify(data) })
+      if (!res.ok) {
+        const body = await res.json()
+        if (body.field === 'password') {
+          setError('password', { type: 'server', message: body.message })
+        } else {
+          setError('root.serverError', { type: 'server', message: body.message ?? 'Sign in failed' })
+        }
+        return
+      }
+      redirect('/dashboard')
+    } catch {
+      setError('root.serverError', { type: 'network', message: 'Network error — please retry' })
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {errors.root?.serverError && (
+        <div role="alert">{errors.root.serverError.message}</div>
+      )}
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+      <input type="password" {...register('password')} />
+      {errors.password && <span>{errors.password.message}</span>}
+      <button disabled={isSubmitting}>Sign in</button>
+    </form>
+  )
+}
+```
+
+**Key details:**
+- Root-level errors live under `errors.root.{key}` — pick any key (`serverError`, `network`, `rateLimit`) and read it back the same way
+- Root errors **persist across submissions** until you call `clearErrors('root.serverError')` — clear at the start of each submit, or rely on the next resolver pass to overwrite
+- Always `try/catch` async submit handlers. `handleSubmit` will not surface thrown errors, and `isSubmitting` only resets when the handler returns (resolves), not when it throws — see also `formstate-async-submit-lifecycle`
+
+Reference: [setError](https://react-hook-form.com/docs/useform/seterror) · [Discussion #9691 — Handle global/server errors](https://github.com/orgs/react-hook-form/discussions/9691)
diff --git a/.agents/skills/react-hook-form/references/valid-valueasnumber-empty-nan.md b/.agents/skills/react-hook-form/references/valid-valueasnumber-empty-nan.md
new file mode 100644
index 0000000..2d6cbe3
--- /dev/null
+++ b/.agents/skills/react-hook-form/references/valid-valueasnumber-empty-nan.md
@@ -0,0 +1,68 @@
+---
+title: Handle the NaN valueAsNumber Produces for an Empty Input
+impact: HIGH
+impactDescription: prevents an optional number field that can never be left blank
+tags: valid, valueAsNumber, setValueAs, NaN, optional-fields
+---
+
+## Handle the NaN valueAsNumber Produces for an Empty Input
+
+`register('n', { valueAsNumber: true })` converts an empty string to **`NaN`**, not to `undefined` or `null`. This is deliberate — a fix that treated `NaN` as empty was reverted in 7.76.1 — so it is stable behaviour you have to design around rather than a bug to wait out.
+
+It is invisible on a required field, where any complaint is the complaint you wanted. It breaks **optional** number fields: the user clears the box, the schema receives `NaN`, `z.number().optional()` rejects it, and the field can never be left blank. The error text ("expected number, received nan") points at the schema rather than at the conversion, so the cause is easy to miss.
+
+**Incorrect (an optional field the user cannot clear):**
+
+```typescript
+const listingSchema = z.object({
+  title: z.string().min(1),
+  reservePrice: z.number().positive().optional(),
+})
+
+function ListingForm() {
+  const { register, handleSubmit } = useForm<ListingFormValues>({
+    resolver: zodResolver(listingSchema),
+    defaultValues: { title: '', reservePrice: undefined },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(saveListing)}>
+      {/* Clearing the input yields NaN, which fails .optional() */}
+      <input type="number" {...register('reservePrice', { valueAsNumber: true })} />
+    </form>
+  )
+}
+```
+
+**Correct (map empty to undefined with setValueAs):**
+
+```typescript
+const listingSchema = z.object({
+  title: z.string().min(1),
+  reservePrice: z.number().positive().optional(),
+})
+
+function ListingForm() {
+  const { register, handleSubmit } = useForm<ListingFormValues>({
+    resolver: zodResolver(listingSchema),
+    defaultValues: { title: '', reservePrice: undefined },
+  })
+
+  return (
+    <form onSubmit={handleSubmit(saveListing)}>
+      <input
+        type="number"
+        {...register('reservePrice', {
+          setValueAs: (value) => (value === '' ? undefined : Number(value)),
+        })}
+      />
+    </form>
+  )
+}
+```
+
+`setValueAs` and `valueAsNumber` are mutually exclusive — supplying `setValueAs` replaces the built-in conversion, which is exactly what you want here.
+
+For a **required** number, `valueAsNumber: true` is fine: `NaN` fails validation, which is the correct outcome. Reserve `setValueAs` for fields that are genuinely allowed to be empty, and prefer it over `z.coerce.number()`, which turns `''` into `0` and would silently record a reserve price of zero.
+
+Reference: [register - valueAsNumber](https://react-hook-form.com/docs/useform/register)
diff --git a/.agents/skills/shadcn/SKILL.md b/.agents/skills/shadcn/SKILL.md
new file mode 100644
index 0000000..1b4c414
--- /dev/null
+++ b/.agents/skills/shadcn/SKILL.md
@@ -0,0 +1,277 @@
+---
+name: shadcn
+description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
+user-invocable: false
+allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
+---
+
+# shadcn/ui
+
+A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+```json
+!`npx shadcn@latest info --json`
+```
+
+The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
+
+## Principles
+
+1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`className` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast follows the project base.** Use `toast` from the `toast` component for
+  Base UI projects. Use `toast()` from `sonner` for Radix and React Aria
+  projects.
+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.
+
+### Chat & Messaging → [chat.md](./rules/chat.md)
+
+- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container.
+- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook.
+- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label.
+
+### CLI
+
+- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@latest preset resolve`.
+- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
+
+```tsx
+// Form layout: FieldGroup + Field, not div + Label.
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+// Validation: data-invalid on Field, aria-invalid on the control.
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes.
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+// Spacing: gap-*, not space-y-*.
+<div className="flex flex-col gap-4">  // correct
+<div className="space-y-4">           // wrong
+
+// Equal dimensions: size-*, not w-* h-*.
+<Avatar className="size-10">   // correct
+<Avatar className="w-10 h-10"> // wrong
+
+// Status colors: Badge variants or semantic tokens, not raw colors.
+<Badge variant="secondary">+20.1%</Badge>    // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`                 |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (wraps Recharts)                                                                            |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+| Chat / conversation UI     | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`                                      |
+
+## Key Fields
+
+The injected project context contains these key fields:
+
+- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
+- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.
+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
+- **`style`** → component visual treatment (e.g. `nova`, `vega`).
+- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
+- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
+- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
+- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
+- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information.
+
+See [cli.md — `info` command](./cli.md) for the full field reference.
+
+## Component Docs, Examples, and Usage
+
+Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+
+```bash
+npx shadcn@latest docs button dialog select
+```
+
+**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+
+## Workflow
+
+1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
+3. **Find components** — `npx shadcn@latest search`.
+4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
+9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**?
+   - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values.
+   - **Inspect incoming preset**: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
+   - **Overwrite**: `npx shadcn@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Partial**: `npx shadcn@latest apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
+   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
+
+## Updating Components
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
+
+1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
+3. Decide per file based on the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
+   - User says "just update everything" → use `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Create a new project.
+npx shadcn@latest init --name my-app --preset base-nova
+npx shadcn@latest init --name my-app --preset a2r6bw --template vite
+
+# Create a monorepo project.
+npx shadcn@latest init --name my-app --preset base-nova --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
+
+# Initialize existing project.
+npx shadcn@latest init --preset base-nova
+npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+
+# Apply a preset to an existing project.
+npx shadcn@latest apply a2r6bw
+npx shadcn@latest apply a2r6bw --only theme
+npx shadcn@latest apply a2r6bw --only font
+npx shadcn@latest apply a2r6bw --only theme,font
+
+# Inspect preset codes and project preset state.
+npx shadcn@latest preset decode a2r6bw
+npx shadcn@latest preset url a2r6bw
+npx shadcn@latest preset open a2r6bw
+npx shadcn@latest preset resolve
+npx shadcn@latest preset resolve --json
+
+# Add components.
+npx shadcn@latest add button card dialog
+npx shadcn@latest add @magicui/shimmer-button
+npx shadcn@latest add owner/repo/item
+npx shadcn@latest add --all
+
+# Preview changes before adding/updating.
+npx shadcn@latest add button --dry-run
+npx shadcn@latest add button --diff button.tsx
+npx shadcn@latest add @acme/form --view button.tsx
+npx shadcn@latest add owner/repo/item --dry-run
+
+# Search registries.
+npx shadcn@latest search @shadcn -q "sidebar"
+npx shadcn@latest search @tailark -q "stats"
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest search                          # all configured registries
+npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
+
+# Get component docs and example URLs.
+npx shadcn@latest docs button dialog select
+
+# View registry item details (for items not yet installed).
+npx shadcn@latest view @shadcn/button
+npx shadcn@latest view owner/repo/item
+```
+
+**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com).
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/chat.md](./rules/chat.md) — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
+- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
+- [cli.md](./cli.md) — Commands, flags, presets, templates
+- [registry.md](./registry.md) — Authoring source registries, `include`, item definitions, dependencies, GitHub registry rules
+- [customization.md](./customization.md) — Theming, CSS variables, extending components
diff --git a/.agents/skills/shadcn/agents/openai.yml b/.agents/skills/shadcn/agents/openai.yml
new file mode 100644
index 0000000..ab636da
--- /dev/null
+++ b/.agents/skills/shadcn/agents/openai.yml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "shadcn/ui"
+  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
+  icon_small: "./assets/shadcn-small.png"
+  icon_large: "./assets/shadcn.png"
diff --git a/.agents/skills/shadcn/assets/shadcn-small.png b/.agents/skills/shadcn/assets/shadcn-small.png
new file mode 100644
index 0000000..547154b
Binary files /dev/null and b/.agents/skills/shadcn/assets/shadcn-small.png differ
diff --git a/.agents/skills/shadcn/assets/shadcn.png b/.agents/skills/shadcn/assets/shadcn.png
new file mode 100644
index 0000000..b7b6814
Binary files /dev/null and b/.agents/skills/shadcn/assets/shadcn.png differ
diff --git a/.agents/skills/shadcn/cli.md b/.agents/skills/shadcn/cli.md
new file mode 100644
index 0000000..8a1d195
--- /dev/null
+++ b/.agents/skills/shadcn/cli.md
@@ -0,0 +1,290 @@
+# shadcn CLI Reference
+
+Configuration is read from `components.json`.
+
+> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
+
+## Contents
+
+- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build
+- Templates: next, vite, start, react-router, astro
+- Presets: named, code, URL formats and fields
+- Switching presets
+
+---
+
+## Commands
+
+### `init` — Initialize or create a project
+
+```bash
+npx shadcn@latest init [components...] [options]
+```
+
+Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
+
+| Flag                    | Short | Description                                               | Default |
+| ----------------------- | ----- | --------------------------------------------------------- | ------- |
+| `--template <template>` | `-t`  | Template (next, start, vite, next-monorepo, react-router) | —       |
+| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)                | —       |
+| `--yes`                 | `-y`  | Skip confirmation prompt                                  | `true`  |
+| `--defaults`            | `-d`  | Use defaults (`--template=next --preset=base-nova`)       | `false` |
+| `--force`               | `-f`  | Force overwrite existing configuration                    | `false` |
+| `--cwd <cwd>`           | `-c`  | Working directory                                         | current |
+| `--name <name>`         | `-n`  | Name for new project                                      | —       |
+| `--silent`              | `-s`  | Mute output                                               | `false` |
+| `--rtl`                 |       | Enable RTL support                                        | —       |
+| `--reinstall`           |       | Re-install existing UI components                         | `false` |
+| `--monorepo`            |       | Scaffold a monorepo project                               | —       |
+| `--no-monorepo`         |       | Skip the monorepo prompt                                  | —       |
+
+`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
+
+### `apply` — Apply a preset to an existing project
+
+```bash
+npx shadcn@latest apply [preset] [options]
+```
+
+Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
+
+| Flag                | Short | Description                                | Default |
+| ------------------- | ----- | ------------------------------------------ | ------- |
+| `--preset <preset>` | —     | Preset configuration (named, code, or URL) | —       |
+| `--yes`             | `-y`  | Skip confirmation prompt                   | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                          | current |
+| `--silent`          | `-s`  | Mute output                                | `false` |
+
+`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
+If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.
+
+### `add` — Add components
+
+> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
+
+```bash
+npx shadcn@latest add [components...] [options]
+```
+
+Accepts component names, registry-prefixed names (`@magicui/shimmer-button`),
+GitHub item addresses (`owner/repo/item`), URLs, or local paths.
+
+| Flag            | Short | Description                                                                                                          | Default |
+| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
+| `--yes`         | `-y`  | Skip confirmation prompt                                                                                             | `false` |
+| `--overwrite`   | `-o`  | Overwrite existing files                                                                                             | `false` |
+| `--cwd <cwd>`   | `-c`  | Working directory                                                                                                    | current |
+| `--all`         | `-a`  | Add all available components                                                                                         | `false` |
+| `--path <path>` | `-p`  | Target path for the component                                                                                        | —       |
+| `--silent`      | `-s`  | Mute output                                                                                                          | `false` |
+| `--dry-run`     |       | Preview all changes without writing files                                                                            | `false` |
+| `--diff [path]` |       | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`)         | —       |
+| `--view [path]` |       | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | —       |
+
+#### Dry-Run Mode
+
+Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
+
+```bash
+# Preview all changes.
+npx shadcn@latest add button --dry-run
+
+# Show diffs for all files (top 5).
+npx shadcn@latest add button --diff
+
+# Show the diff for a specific file.
+npx shadcn@latest add button --diff button.tsx
+
+# Show contents for all files (top 5).
+npx shadcn@latest add button --view
+
+# Show the full content of a specific file.
+npx shadcn@latest add button --view button.tsx
+
+# Works with URLs too.
+npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
+
+# Works with public GitHub registries too.
+npx shadcn@latest add owner/repo/item --dry-run
+
+# CSS diffs.
+npx shadcn@latest add button --diff globals.css
+```
+
+**When to use dry-run:**
+
+- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
+- Before overwriting existing components — use `--diff` to preview the changes first.
+- When the user wants to inspect component source code without installing — use `--view`.
+- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
+- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
+
+> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
+
+#### Smart Merge from Upstream
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
+
+### `search` — Search registries
+
+```bash
+npx shadcn@latest search [registries...] [options]
+```
+
+Fuzzy search across registries. Also aliased as `npx shadcn@latest list`.
+Supports namespaces (`@acme`), public GitHub registry sources (`owner/repo`),
+and registry catalog URLs. Without `-q`, lists all items. When no registries are
+passed, searches every registry configured in `components.json`.
+
+| Flag                | Short | Description                                       | Default |
+| ------------------- | ----- | ------------------------------------------------- | ------- |
+| `--query <query>`   | `-q`  | Search query                                      | —       |
+| `--type <type>`     | `-t`  | Filter by item type (e.g. `ui`, `block`, `hook`); comma-separated | —       |
+| `--limit <number>`  | `-l`  | Max items to display                              | `100`   |
+| `--offset <number>` | `-o`  | Items to skip                                     | `0`     |
+| `--json`            |       | Output as JSON                                    | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                                 | current |
+
+### `view` — View item details
+
+```bash
+npx shadcn@latest view <items...> [options]
+```
+
+Displays item info including file contents. Examples:
+`npx shadcn@latest view @shadcn/button`,
+`npx shadcn@latest view owner/repo/item`.
+
+### `docs` — Get component documentation URLs
+
+```bash
+npx shadcn@latest docs <components...> [options]
+```
+
+Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
+
+Example output for `npx shadcn@latest docs input button`:
+
+```
+base  radix
+
+input
+  docs      https://ui.shadcn.com/docs/components/radix/input
+  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx
+
+button
+  docs      https://ui.shadcn.com/docs/components/radix/button
+  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx
+```
+
+Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
+
+### `diff` — Check for updates
+
+Do not use this command. Use `npx shadcn@latest add --diff` instead.
+
+### `info` — Project information
+
+```bash
+npx shadcn@latest info [options]
+```
+
+Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+**Project Info fields:**
+
+| Field                | Type      | Meaning                                                            |
+| -------------------- | --------- | ------------------------------------------------------------------ |
+| `framework`          | `string`  | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |
+| `frameworkVersion`   | `string`  | Framework version (e.g. `15.2.4`)                                  |
+| `isSrcDir`           | `boolean` | Whether the project uses a `src/` directory                        |
+| `isRSC`              | `boolean` | Whether React Server Components are enabled                        |
+| `isTsx`              | `boolean` | Whether the project uses TypeScript                                |
+| `tailwindVersion`    | `string`  | `"v3"` or `"v4"`                                                   |
+| `tailwindConfigFile` | `string`  | Path to the Tailwind config file                                   |
+| `tailwindCssFile`    | `string`  | Path to the global CSS file                                        |
+| `aliasPrefix`        | `string`  | Import alias prefix (e.g. `@`, `~`, `@/`)                          |
+| `packageManager`     | `string`  | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`)            |
+
+**Components.json fields:**
+
+| Field                | Type      | Meaning                                                                                    |
+| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `base`               | `string`  | Primitive library (`radix` or `base`) — determines component APIs and available props      |
+| `style`              | `string`  | Visual style (e.g. `nova`, `vega`)                                                         |
+| `rsc`                | `boolean` | RSC flag from config                                                                       |
+| `tsx`                | `boolean` | TypeScript flag                                                                            |
+| `tailwind.config`    | `string`  | Tailwind config path                                                                       |
+| `tailwind.css`       | `string`  | Global CSS path — this is where custom CSS variables go                                    |
+| `iconLibrary`        | `string`  | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
+| `aliases.components` | `string`  | Component import alias (e.g. `@/components`)                                               |
+| `aliases.utils`      | `string`  | Utils import alias (e.g. `@/lib/utils`)                                                    |
+| `aliases.ui`         | `string`  | UI component alias (e.g. `@/components/ui`)                                                |
+| `aliases.lib`        | `string`  | Lib alias (e.g. `@/lib`)                                                                   |
+| `aliases.hooks`      | `string`  | Hooks alias (e.g. `@/hooks`)                                                               |
+| `resolvedPaths`      | `object`  | Absolute file-system paths for each alias                                                  |
+| `registries`         | `object`  | Configured custom registries                                                               |
+
+**Links fields:**
+
+The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
+
+### `build` — Build a custom registry
+
+```bash
+npx shadcn@latest build [registry] [options]
+```
+
+Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
+
+For authoring rules, `include`, item definitions, `registryDependencies`, and
+GitHub registry behavior, see [registry.md](./registry.md).
+
+| Flag              | Short | Description       | Default      |
+| ----------------- | ----- | ----------------- | ------------ |
+| `--output <path>` | `-o`  | Output directory  | `./public/r` |
+| `--cwd <cwd>`     | `-c`  | Working directory | current      |
+
+---
+
+## Templates
+
+| Value          | Framework      | Monorepo support |
+| -------------- | -------------- | ---------------- |
+| `next`         | Next.js        | Yes              |
+| `vite`         | Vite           | Yes              |
+| `start`        | TanStack Start | Yes              |
+| `react-router` | React Router   | Yes              |
+| `astro`        | Astro          | Yes              |
+| `laravel`      | Laravel        | No               |
+
+All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
+
+---
+
+## Presets
+
+Three ways to specify a preset via `--preset`:
+
+1. **Named:** `--preset nova` or `--preset lyra`
+2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
+3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
+
+> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.
+> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
+
+## Switching Presets
+
+Ask the user first: **overwrite**, **merge**, or **skip** existing components?
+
+- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
+- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
+- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
+
+Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
diff --git a/.agents/skills/shadcn/customization.md b/.agents/skills/shadcn/customization.md
new file mode 100644
index 0000000..16954f5
--- /dev/null
+++ b/.agents/skills/shadcn/customization.md
@@ -0,0 +1,209 @@
+# Customization & Theming
+
+Components reference semantic CSS variable tokens. Change the variables to change every component.
+
+## Contents
+
+- How it works (CSS variables → Tailwind utilities → components)
+- Color variables and OKLCH format
+- Dark mode setup
+- Changing the theme (presets, CSS variables)
+- Adding custom colors (Tailwind v3 and v4)
+- Border radius
+- Customizing components (variants, className, wrappers)
+- Checking for updates
+
+---
+
+## How It Works
+
+1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
+2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
+3. Components use these utilities — changing a variable changes all components that reference it.
+
+---
+
+## Color Variables
+
+Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
+
+| Variable                                     | Purpose                          |
+| -------------------------------------------- | -------------------------------- |
+| `--background` / `--foreground`              | Page background and default text |
+| `--card` / `--card-foreground`               | Card surfaces                    |
+| `--primary` / `--primary-foreground`         | Primary buttons and actions      |
+| `--secondary` / `--secondary-foreground`     | Secondary actions                |
+| `--muted` / `--muted-foreground`             | Muted/disabled states            |
+| `--accent` / `--accent-foreground`           | Hover and accent states          |
+| `--destructive` / `--destructive-foreground` | Error and destructive actions    |
+| `--border`                                   | Default border color             |
+| `--input`                                    | Form input borders               |
+| `--ring`                                     | Focus ring color                 |
+| `--chart-1` through `--chart-5`              | Chart/data visualization         |
+| `--sidebar-*`                                | Sidebar-specific colors          |
+| `--surface` / `--surface-foreground`         | Secondary surface                |
+
+Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
+
+---
+
+## Dark Mode
+
+Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
+
+```tsx
+import { ThemeProvider } from "next-themes"
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+  {children}
+</ThemeProvider>
+```
+
+---
+
+## Changing the Theme
+
+```bash
+# Apply a preset code from ui.shadcn.com.
+npx shadcn@latest apply --preset a2r6bw
+
+# Positional shorthand also works.
+npx shadcn@latest apply a2r6bw
+
+# Switch to a named preset and overwrite existing components.
+npx shadcn@latest apply --preset nova
+
+# Preserve existing components instead.
+npx shadcn@latest init --preset nova --force --no-reinstall
+
+# Use a custom theme URL.
+npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."
+```
+
+Or edit CSS variables directly in `globals.css`.
+
+---
+
+## Adding Custom Colors
+
+Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
+
+```css
+/* 1. Define in the global CSS file. */
+:root {
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
+}
+```
+
+```css
+/* 2a. Register with Tailwind v4 (@theme inline). */
+@theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+```
+
+When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
+
+```js
+// 2b. Register with Tailwind v3 (tailwind.config.js).
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        warning: "oklch(var(--warning) / <alpha-value>)",
+        "warning-foreground":
+          "oklch(var(--warning-foreground) / <alpha-value>)",
+      },
+    },
+  },
+}
+```
+
+```tsx
+// 3. Use in components.
+<div className="bg-warning text-warning-foreground">Warning</div>
+```
+
+---
+
+## Border Radius
+
+`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
+
+---
+
+## Customizing Components
+
+See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
+
+Prefer these approaches in order:
+
+### 1. Built-in variants
+
+```tsx
+<Button variant="outline" size="sm">
+  Click
+</Button>
+```
+
+### 2. Tailwind classes via `className`
+
+```tsx
+<Card className="mx-auto max-w-md">...</Card>
+```
+
+### 3. Add a new variant
+
+Edit the component source to add a variant via `cva`:
+
+```tsx
+// components/ui/button.tsx
+warning: "bg-warning text-warning-foreground hover:bg-warning/90",
+```
+
+### 4. Wrapper components
+
+Compose shadcn/ui primitives into higher-level components:
+
+```tsx
+export function ConfirmDialog({ title, description, onConfirm, children }) {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+---
+
+## Checking for Updates
+
+```bash
+npx shadcn@latest add button --diff
+```
+
+To preview exactly what would change before updating, use `--dry-run` and `--diff`:
+
+```bash
+npx shadcn@latest add button --dry-run        # see all affected files
+npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
+```
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.
diff --git a/.agents/skills/shadcn/evals/evals.json b/.agents/skills/shadcn/evals/evals.json
new file mode 100644
index 0000000..c1b7bdd
--- /dev/null
+++ b/.agents/skills/shadcn/evals/evals.json
@@ -0,0 +1,77 @@
+{
+  "skill_name": "shadcn",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
+      "expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
+      "files": [],
+      "expectations": [
+        "Uses FieldGroup and Field components for form layout instead of raw div with space-y",
+        "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
+        "Uses data-invalid on Field and aria-invalid on the input control for validation states",
+        "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
+        "Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
+        "No manual dark: color overrides"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
+      "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
+      "files": [],
+      "expectations": [
+        "Includes DialogTitle for accessibility (visible or with sr-only class)",
+        "Avatar component includes AvatarFallback",
+        "Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
+        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
+        "Uses tabler icons (@tabler/icons-react) instead of lucide-react",
+        "Uses asChild for custom triggers (radix preset)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
+      "expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
+      "files": [],
+      "expectations": [
+        "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
+        "Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
+        "Uses Badge component for percentage change instead of custom styled spans",
+        "Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
+        "Uses gap-* instead of space-y-* or space-x-* for spacing",
+        "Uses size-* when width and height are equal instead of separate w-* h-*"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Build a chat conversation view: a scrollable thread of messages from two different people, each with an avatar, sender name, timestamp, and message bubble. A couple of messages include an image attachment and a PDF file attachment, and there's a 'Today' divider separating the days.",
+      "expected_output": "A React component composing MessageScroller, Message, Bubble, Attachment, and Marker from the registry instead of hand-rolled bubble/divider/attachment markup.",
+      "files": [],
+      "expectations": [
+        "Uses MessageScroller (MessageScrollerProvider, MessageScrollerViewport, MessageScrollerContent, MessageScrollerItem) for the scrollable thread instead of a raw overflow-y-auto div or ScrollArea",
+        "Wraps each row in MessageScrollerItem inside MessageScrollerContent",
+        "Uses Message with MessageAvatar/MessageContent/MessageHeader for row layout instead of custom flex divs",
+        "Uses Bubble + BubbleContent for the message surface instead of a styled div with bg-muted/bg-primary",
+        "Uses Attachment (AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription) for the file and image attachments instead of Item or a custom card",
+        "Uses Marker (variant=\"separator\") for the 'Today' divider instead of Separator plus a centered label",
+        "Uses semantic color tokens and gap-* spacing; no raw colors like bg-emerald-500 and no space-y-*",
+        "Includes \"use client\" when the component uses state or event handlers (isRSC)"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Using shadcn/ui (base-nova preset, lucide icons), build a streaming AI chat UI. The assistant's reply streams in while it generates, the view auto-scrolls to follow the latest content but stops following if the user scrolls up to read earlier messages, a 'jump to latest' button appears when the user has scrolled away from the bottom, and a subtle 'thinking…' shimmer shows while the model is generating.",
+      "expected_output": "A React component that delegates scroll/anchor behavior to MessageScroller and uses MessageScrollerButton for jump-to-latest and the shimmer utility for the thinking indicator — no hand-rolled scroll logic or custom shimmer keyframes.",
+      "files": [],
+      "expectations": [
+        "Uses MessageScroller with MessageScrollerProvider (autoScroll) and scrollAnchor on message items for the stick-to-bottom/follow behavior instead of a custom useStickToBottom hook or ResizeObserver/scrollTop wiring",
+        "Uses MessageScrollerButton for the jump-to-latest control instead of a hand-built conditional button driven by manual scroll-position state",
+        "Uses the shimmer utility class for the 'thinking…' indicator instead of a custom @keyframes or bg-clip-text gradient animation",
+        "Wraps each message row in MessageScrollerItem inside MessageScrollerContent",
+        "Uses Message + Bubble + BubbleContent for the conversation rows instead of hand-rolled bubble divs",
+        "Uses semantic color tokens and gap-* spacing; includes \"use client\" (isRSC)"
+      ]
+    }
+  ]
+}
diff --git a/.agents/skills/shadcn/mcp.md b/.agents/skills/shadcn/mcp.md
new file mode 100644
index 0000000..6539dda
--- /dev/null
+++ b/.agents/skills/shadcn/mcp.md
@@ -0,0 +1,105 @@
+# shadcn MCP Server
+
+The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
+
+---
+
+## Setup
+
+```bash
+shadcn mcp        # start the MCP server (stdio)
+shadcn mcp init   # write config for your editor
+```
+
+Editor config files:
+
+| Editor      | Config file                     |
+| ----------- | ------------------------------- |
+| Claude Code | `.mcp.json`                     |
+| Cursor      | `.cursor/mcp.json`              |
+| VS Code     | `.vscode/mcp.json`              |
+| OpenCode    | `opencode.json`                 |
+| Codex       | `~/.codex/config.toml` (manual) |
+
+---
+
+## Tools
+
+> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
+
+### `shadcn:get_project_registries`
+
+Returns registry names from `components.json`. Errors if no `components.json` exists.
+
+**Input:** none
+
+### `shadcn:list_items_in_registries`
+
+Lists all items from one or more registries. Registries can be configured
+namespaces such as `@acme`, public GitHub sources such as `owner/repo`, or
+registry catalog URLs. Omit `registries` to list from every registry configured
+in `components.json`.
+
+**Input:** `registries` (string[], optional — omit for all configured), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
+
+### `shadcn:search_items_in_registries`
+
+Fuzzy search across registries. Registries can be configured namespaces, public
+GitHub sources, or registry catalog URLs. Omit `registries` to search every
+registry configured in `components.json` — e.g. "find me a hero" across all
+configured registries.
+
+**Input:** `registries` (string[], optional — omit for all configured), `query` (string), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
+
+### `shadcn:view_items_in_registries`
+
+View item details including full file contents.
+
+**Input:** `items` (string[]) — e.g.
+`["@shadcn/button", "@shadcn/card", "owner/repo/item"]`
+
+### `shadcn:get_item_examples_from_registries`
+
+Find usage examples and demos with source code. Omit `registries` to search
+every registry configured in `components.json`.
+
+**Input:** `registries` (string[], optional — omit for all configured), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
+
+### `shadcn:get_add_command_for_items`
+
+Returns the CLI install command.
+
+**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
+
+### `shadcn:get_audit_checklist`
+
+Returns a checklist for verifying components (imports, deps, lint, TypeScript).
+
+**Input:** none
+
+---
+
+## Configuring Registries
+
+Namespaced and authenticated registries are set in `components.json`. The
+`@shadcn` registry is always built-in. Public GitHub registries can also be used
+directly as `owner/repo` registry sources when the repository has a root
+`registry.json`; they do not need `components.json` configuration.
+
+```json
+{
+  "registries": {
+    "@acme": "https://acme.com/r/{name}.json",
+    "@private": {
+      "url": "https://private.com/r/{name}.json",
+      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
+    }
+  }
+}
+```
+
+- Names must start with `@`.
+- URLs must contain `{name}`.
+- `${VAR}` references are resolved from environment variables.
+
+Community registry index: `https://ui.shadcn.com/r/registries.json`
diff --git a/.agents/skills/shadcn/registry.md b/.agents/skills/shadcn/registry.md
new file mode 100644
index 0000000..5369468
--- /dev/null
+++ b/.agents/skills/shadcn/registry.md
@@ -0,0 +1,277 @@
+# Registry Authoring and Addresses
+
+Use this reference when the user wants to create, fix, publish, or reason about
+a shadcn registry.
+
+## Mental Model
+
+A registry has two forms:
+
+- **Source registry**: an authored `registry.json` in a project or repository.
+  It may use `include` and file paths that point at source files.
+- **Built registry**: generated JSON files served to CLI consumers, usually
+  from `public/r`. Use `npx shadcn@latest build` to create this form.
+
+The CLI installer consumes registry item payloads. A source registry is a way to
+author those payloads from real files.
+
+Registry items are not limited to React components. They can distribute
+components, hooks, utilities, design tokens, pages, config files, docs, rules,
+workflows, templates, MCP files, and other project files.
+
+## Root `registry.json`
+
+The root registry file should define registry metadata and either `items` or
+`include`.
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://acme.com",
+  "items": [
+    {
+      "name": "absolute-url",
+      "type": "registry:lib",
+      "title": "Absolute URL",
+      "description": "A utility to turn any path into an absolute URL.",
+      "files": [
+        {
+          "path": "lib/absolute-url.ts",
+          "type": "registry:lib"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Root registry rules:
+
+- Root `registry.json` must include `name` and `homepage`.
+- `items` is an array of registry item definitions.
+- `include` may be used to split the source registry into multiple files.
+- Included registry files may omit `name` and `homepage`.
+
+## Include
+
+Use `include` to keep large registries modular.
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://acme.com",
+  "include": ["registry/ui/registry.json", "registry/blocks/registry.json"]
+}
+```
+
+Include rules:
+
+- Include paths are relative to the `registry.json` that declares them.
+- Include paths must explicitly point to a `registry.json` file.
+- Do not use remote URLs, absolute paths, or parent traversal (`..`).
+- Item file paths are relative to the registry file that declares the item.
+- Duplicate item names fail across the resolved registry.
+
+Example included file:
+
+```json
+{
+  "items": [
+    {
+      "name": "button",
+      "type": "registry:ui",
+      "files": [
+        {
+          "path": "button.tsx",
+          "type": "registry:ui"
+        }
+      ]
+    }
+  ]
+}
+```
+
+If this file is at `registry/ui/registry.json`, then `button.tsx` is read from
+`registry/ui/button.tsx`, and the built item path is emitted relative to the
+root registry.
+
+## Item Definitions
+
+Common item fields:
+
+```json
+{
+  "name": "login-form",
+  "type": "registry:block",
+  "title": "Login Form",
+  "description": "A login form with email and password fields.",
+  "dependencies": ["zod"],
+  "registryDependencies": ["button", "input", "label"],
+  "files": [
+    {
+      "path": "blocks/login-form.tsx",
+      "type": "registry:block"
+    }
+  ],
+  "cssVars": {
+    "light": {
+      "brand": "oklch(0.62 0.18 250)"
+    },
+    "dark": {
+      "brand": "oklch(0.72 0.16 250)"
+    }
+  }
+}
+```
+
+Important fields:
+
+- `name`: the installable item name. It is not necessarily a file path.
+- `type`: one of the registry item types, such as `registry:ui`,
+  `registry:block`, `registry:lib`, `registry:hook`, `registry:file`,
+  `registry:page`, `registry:theme`, `registry:style`, `registry:font`, or
+  `registry:item`.
+- `files`: source files copied or generated by the item.
+- `dependencies`: npm runtime dependencies.
+- `devDependencies`: npm development dependencies.
+- `registryDependencies`: other registry items required by this item.
+- `cssVars`, `css`, `tailwind`, `envVars`, and `docs`: optional install-time
+  additions.
+
+File rules:
+
+- File paths are relative to the declaring `registry.json`.
+- `registry:file` and `registry:page` files require a `target`.
+- Do not use remote file URLs in source registry file paths.
+- Keep source files copy-pasteable: no hidden app-only imports.
+
+## Registry Dependencies
+
+`registryDependencies` entries are item addresses, not file paths.
+
+```json
+{
+  "name": "login-form",
+  "type": "registry:block",
+  "registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"],
+  "files": [
+    {
+      "path": "blocks/login-form.tsx",
+      "type": "registry:block"
+    }
+  ]
+}
+```
+
+Dependency rules:
+
+- Bare names such as `"button"` mean official shadcn items.
+- Bare names never mean same-registry or same-repository items.
+- Namespaced dependencies use `@namespace/item-name`.
+- GitHub dependencies use `owner/repo/item-name`.
+- Pin GitHub dependencies with `owner/repo/item-name#ref` when needed.
+- Refs are not inherited. If `owner/repo/foo#v2` depends on `bar` from the same
+  repo at `v2`, write `owner/repo/bar#v2`.
+- Do not use relative dependencies such as `"./bar"`.
+
+## Address Schemes
+
+When reasoning about a registry item string, classify it first.
+
+| Address                             | Scheme    | Meaning                                                      |
+| ----------------------------------- | --------- | ------------------------------------------------------------ |
+| `button`                            | shadcn    | Official shadcn item named `button`.                         |
+| `@acme/button`                      | namespace | Item `button` from configured registry `@acme`.              |
+| `@acme/ui/button`                   | namespace | Item `ui/button` from configured registry `@acme`.           |
+| `https://example.com/r/button.json` | url       | Built registry item JSON at that URL.                        |
+| `./button.json`                     | file      | Built registry item JSON on disk.                            |
+| `acme/ui/button`                    | github    | Item `button` from GitHub repo `acme/ui`.                    |
+| `acme/ui/forms/login#main`          | github    | Item `forms/login` from GitHub repo `acme/ui` at ref `main`. |
+
+For namespace and GitHub addresses, slashful item names are allowed and are item
+names, not file paths. Addresses ending in `.json` keep file-address
+precedence, so `acme/ui/data/schema.json` is treated as a file path, not a
+GitHub item address.
+
+## GitHub Registries
+
+A public GitHub repository can act as a source registry when it has a root
+`registry.json`.
+
+```txt
+owner/repo/item-name[#ref]
+```
+
+Rules:
+
+- The first two path segments are GitHub owner and repo.
+- All remaining path segments are the registry item name.
+- The source entrypoint is always root `registry.json`.
+- GitHub registries are source registries consumed directly by the CLI. They do
+  not require `shadcn build` or generated item JSON files.
+- `include` follows the same source-registry rules as local registries.
+- Currently, GitHub addresses support public `github.com` repositories only.
+- Private repos and GitHub Enterprise require explicit product decisions.
+
+When implementing GitHub registry fetching, resolve refs to a commit SHA before
+reading source files. Do not read moving refs directly from
+`raw.githubusercontent.com`, because branch-like refs can be cached for several
+minutes.
+
+Preferred flow:
+
+```txt
+owner/repo[#ref]
+  -> resolve ref with git ls-remote
+  -> commit SHA
+  -> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json
+  -> read includes and item files from the same SHA
+```
+
+This keeps a command on one consistent repository snapshot.
+
+Full 40-character commit SHAs are already stable and can be used directly.
+Branches, tags, and short refs require Git so the CLI can resolve them to a
+commit SHA first.
+
+## Build and Verify
+
+Use the CLI to build source registries:
+
+```bash
+npx shadcn@latest build
+npx shadcn@latest build registry.json --output public/r
+```
+
+Use CLI commands to inspect the result:
+
+```bash
+npx shadcn@latest list @acme
+npx shadcn@latest search @acme -q "login"
+npx shadcn@latest view @acme/login-form
+npx shadcn@latest add @acme/login-form --dry-run
+npx shadcn@latest registry validate ./registry.json
+```
+
+Use GitHub addresses directly for public GitHub registries:
+
+```bash
+npx shadcn@latest list owner/repo
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest view owner/repo/item
+npx shadcn@latest add owner/repo/item --dry-run
+npx shadcn@latest registry validate owner/repo
+```
+
+When working on registry implementation in the shadcn/ui codebase:
+
+- Keep address parsing pure and testable.
+- Do not add side effects to validators.
+- Preserve existing behavior for official shadcn, namespace, URL, and file
+  schemes.
+- Add tests for address parsing, source loading, dependency resolution, list,
+  search, view, and add paths.
+- Prefer small source-reader abstractions over a plugin system until there are
+  multiple real providers.
diff --git a/.agents/skills/shadcn/rules/base-vs-radix.md b/.agents/skills/shadcn/rules/base-vs-radix.md
new file mode 100644
index 0000000..c1ed7d1
--- /dev/null
+++ b/.agents/skills/shadcn/rules/base-vs-radix.md
@@ -0,0 +1,306 @@
+# Base vs Radix
+
+API differences between `base` and `radix`. Check the `base` field from `npx shadcn@latest info`.
+
+## Contents
+
+- Composition: asChild vs render
+- Button / trigger as non-button element
+- Select (items prop, placeholder, positioning, multiple, object values)
+- ToggleGroup (type vs multiple)
+- Slider (scalar vs array)
+- Accordion (type and defaultValue)
+
+---
+
+## Composition: asChild (radix) vs render (base)
+
+Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
+
+**Incorrect:**
+
+```tsx
+<DialogTrigger>
+  <div>
+    <Button>Open</Button>
+  </div>
+</DialogTrigger>
+```
+
+**Correct (radix):**
+
+```tsx
+<DialogTrigger asChild>
+  <Button>Open</Button>
+</DialogTrigger>
+```
+
+**Correct (base):**
+
+```tsx
+<DialogTrigger render={<Button />}>Open</DialogTrigger>
+```
+
+This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
+
+---
+
+## Button / trigger as non-button element (base only)
+
+When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
+
+**Incorrect (base):** missing `nativeButton={false}`.
+
+```tsx
+<Button render={<a href="/docs" />}>Read the docs</Button>
+```
+
+**Correct (base):**
+
+```tsx
+<Button render={<a href="/docs" />} nativeButton={false}>
+  Read the docs
+</Button>
+```
+
+**Correct (radix):**
+
+```tsx
+<Button asChild>
+  <a href="/docs">Read the docs</a>
+</Button>
+```
+
+Same for triggers whose `render` is not a `Button`:
+
+```tsx
+// base.
+<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
+  Pick date
+</PopoverTrigger>
+```
+
+---
+
+## Select
+
+**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
+
+**Incorrect (base):**
+
+```tsx
+<Select>
+  <SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>
+</Select>
+```
+
+**Correct (base):**
+
+```tsx
+const items = [
+  { label: "Select a fruit", value: null },
+  { label: "Apple", value: "apple" },
+  { label: "Banana", value: "banana" },
+]
+
+<Select items={items}>
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      {items.map((item) => (
+        <SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
+      ))}
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Correct (radix):**
+
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectItem value="apple">Apple</SelectItem>
+      <SelectItem value="banana">Banana</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
+
+**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
+
+```tsx
+// base.
+<SelectContent alignItemWithTrigger={false} side="bottom">
+
+// radix.
+<SelectContent position="popper">
+```
+
+---
+
+## Select — multiple selection and object values (base only)
+
+Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
+
+**Correct (base — multiple selection):**
+
+```tsx
+<Select items={items} multiple defaultValue={[]}>
+  <SelectTrigger>
+    <SelectValue>
+      {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}
+    </SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+**Correct (base — object values):**
+
+```tsx
+<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
+  <SelectTrigger>
+    <SelectValue>{(value) => value.name}</SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+---
+
+## ToggleGroup
+
+Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
+
+**Incorrect (base):**
+
+```tsx
+<ToggleGroup type="single" defaultValue="daily">
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (base):**
+
+```tsx
+// Single (no prop needed), defaultValue is always an array.
+<ToggleGroup defaultValue={["daily"]} spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup multiple>
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (radix):**
+
+```tsx
+// Single, defaultValue is a string.
+<ToggleGroup type="single" defaultValue="daily" spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup type="multiple">
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Controlled single value:**
+
+```tsx
+// base — wrap/unwrap arrays.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
+
+// radix — plain string.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup type="single" value={value} onValueChange={setValue}>
+```
+
+---
+
+## Slider
+
+Base accepts a plain number for a single thumb. Radix always requires an array.
+
+**Incorrect (base):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+**Correct (base):**
+
+```tsx
+<Slider defaultValue={50} max={100} step={1} />
+```
+
+**Correct (radix):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
+
+```tsx
+// base.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
+
+// radix.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={setValue} />
+```
+
+---
+
+## Accordion
+
+Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
+
+**Incorrect (base):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (base):**
+
+```tsx
+<Accordion defaultValue={["item-1"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+
+// Multi-select.
+<Accordion multiple defaultValue={["item-1", "item-2"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+  <AccordionItem value="item-2">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (radix):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```
diff --git a/.agents/skills/shadcn/rules/chat.md b/.agents/skills/shadcn/rules/chat.md
new file mode 100644
index 0000000..9e1a6bf
--- /dev/null
+++ b/.agents/skills/shadcn/rules/chat.md
@@ -0,0 +1,250 @@
+# Chat & Messaging
+
+Components for conversation and chat UI. Compose these instead of hand-rolling
+bubbles, scroll containers, dividers, or attachment cards.
+
+Install: `npx shadcn@latest add message-scroller message bubble attachment marker`
+
+The same component names and props ship for both `base` and `radix`; only
+composition differs (`render` vs `asChild`). See [base-vs-radix.md](./base-vs-radix.md).
+
+## Contents
+
+- Scrollable threads use MessageScroller
+- Message rows use Message
+- Message surfaces use Bubble
+- Attachments use Attachment
+- System notes and dividers use Marker
+- Streaming, anchoring, and jump-to-latest are built in
+- Escape hatch: the scroller hooks
+
+---
+
+## Scrollable threads use MessageScroller
+
+A conversation that scrolls, follows new messages, restores position, or jumps
+to a message uses `MessageScroller`. Don't build a raw overflow container with
+manual scroll wiring, and don't reach for `ScrollArea`.
+
+The parts nest in a fixed order. Every direct child of the content is wrapped in
+a `MessageScrollerItem` so the scroller can measure, anchor, preserve position,
+track visibility, and jump to it. `MessageScrollerButton` sits inside
+`MessageScroller`, after the viewport.
+
+**Incorrect:**
+
+```tsx
+// Hand-rolled scroll container with manual stick-to-bottom logic.
+<div ref={scrollRef} onScroll={handleScroll} className="flex-1 overflow-y-auto">
+  <div className="flex flex-col gap-6 p-4">
+    {messages.map((m) => (
+      <ChatMessage key={m.id} message={m} />
+    ))}
+  </div>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<MessageScrollerProvider autoScroll>
+  <MessageScroller>
+    <MessageScrollerViewport>
+      <MessageScrollerContent>
+        {messages.map((message) => (
+          <MessageScrollerItem
+            key={message.id}
+            messageId={message.id}
+            scrollAnchor={message.role === "user"}
+          >
+            <Message align={message.role === "user" ? "end" : "start"}>
+              {/* ...message content... */}
+            </Message>
+          </MessageScrollerItem>
+        ))}
+      </MessageScrollerContent>
+    </MessageScrollerViewport>
+    <MessageScrollerButton />
+  </MessageScroller>
+</MessageScrollerProvider>
+```
+
+---
+
+## Message rows use Message
+
+`Message` lays out a single row: avatar, header, content, footer, with
+alignment. Group consecutive rows from one sender with `MessageGroup`. Don't
+rebuild the row from flex divs.
+
+`align="end"` is the current user's side; `align="start"` is everyone else.
+
+```tsx
+<Message align="start">
+  <MessageAvatar>
+    <Avatar>
+      <AvatarImage src={sender.avatar} alt={sender.name} />
+      <AvatarFallback>{initials}</AvatarFallback>
+    </Avatar>
+  </MessageAvatar>
+  <MessageContent>
+    <MessageHeader>{sender.name}</MessageHeader>
+    <Bubble>
+      <BubbleContent>{text}</BubbleContent>
+    </Bubble>
+    <MessageFooter>{time}</MessageFooter>
+  </MessageContent>
+</Message>
+```
+
+---
+
+## Message surfaces use Bubble
+
+The colored message surface is `Bubble` + `BubbleContent`, never a styled `div`
+with `bg-muted` / `bg-primary` and hand-managed corners.
+
+- `variant`: `default`, `secondary`, `muted`, `tinted`, `outline`, `ghost`, `destructive`.
+- `align`: `start` or `end` (matches the `Message` side).
+
+`BubbleReactions` renders the reaction cluster. `side` (`top` | `bottom`) and
+`align` (`start` | `end`) position it against the bubble. Don't lay reactions out
+with absolutely-positioned `Badge`s.
+
+**Incorrect:**
+
+```tsx
+<div className="w-fit rounded-2xl bg-primary px-3 py-2 text-primary-foreground">
+  {text}
+</div>
+```
+
+**Correct:**
+
+```tsx
+<Bubble variant="default" align="end">
+  <BubbleContent>{text}</BubbleContent>
+  <BubbleReactions side="bottom" align="end">
+    <Badge variant="secondary">👍 2</Badge>
+  </BubbleReactions>
+</Bubble>
+```
+
+---
+
+## Attachments use Attachment
+
+File and image attachments use `Attachment`, not `Item` or a custom card. It
+carries upload state, so wire `state` to the real status rather than rendering a
+separate spinner.
+
+- `state`: `idle`, `uploading`, `processing`, `error`, `done`. `uploading` and
+  `processing` apply the `shimmer` animation to the title automatically.
+- `size`: `default`, `sm`, `xs`. `orientation`: `horizontal`, `vertical`.
+- Use `AttachmentGroup` to lay out several attachments in a scrolling row.
+
+```tsx
+<Attachment state="done">
+  <AttachmentMedia variant="icon">
+    <FileTextIcon />
+  </AttachmentMedia>
+  <AttachmentContent>
+    <AttachmentTitle>homepage-feedback.pdf</AttachmentTitle>
+    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
+  </AttachmentContent>
+  <AttachmentActions>
+    <AttachmentAction>
+      <DownloadIcon />
+    </AttachmentAction>
+  </AttachmentActions>
+</Attachment>
+```
+
+For an image, use `<AttachmentMedia variant="image">` with an `img` child.
+
+---
+
+## System notes and dividers use Marker
+
+Status lines ("Sarah joined the conversation"), date dividers ("Today"), and
+labeled separators are `Marker`, not a `Separator` plus a centered span.
+
+- `variant`: `default` (plain row), `separator` (centered label with rules on
+  each side), `border` (bottom-bordered row).
+- `MarkerIcon` holds a leading icon; `MarkerContent` holds the label.
+
+**Incorrect:**
+
+```tsx
+<div className="flex items-center gap-3 py-2">
+  <Separator className="flex-1" />
+  <span className="text-xs text-muted-foreground">Today</span>
+  <Separator className="flex-1" />
+</div>
+```
+
+**Correct:**
+
+```tsx
+<Marker variant="separator">
+  <MarkerContent>Today</MarkerContent>
+</Marker>
+```
+
+---
+
+## Streaming, anchoring, and jump-to-latest are built in
+
+`MessageScroller` handles the behavior that chat UIs usually reinvent. Don't
+write a `useStickToBottom` hook, a `ResizeObserver`, or manual `scrollTop` math.
+
+- **Follow the live edge while streaming.** `MessageScrollerProvider` with
+  `autoScroll` keeps the view pinned to new content and yields the moment the
+  user scrolls up. Streaming token updates that grow the last message are
+  followed automatically.
+- **Anchor a turn.** `scrollAnchor` on a `MessageScrollerItem` marks the row to
+  hold in view (typically the user's message that started the turn).
+- **Jump to latest.** `MessageScrollerButton` appears when the user scrolls away
+  and scrolls back on click. `direction="end"` (default) or `direction="start"`.
+  It is a self-managing control, so don't gate it behind your own scroll-position
+  state.
+- **Open a saved transcript without a flash.** `defaultScrollPosition` applies
+  after mount. When it is `"end"` or `"last-anchor"`, the viewport has
+  `data-pending-scroll` until that position is applied. The styled viewport
+  hides. For `"end"` on first paint when messages are in the server HTML, copy
+  this script into the page, not into the primitive. Skip it for `"last-anchor"`
+  and for client-fetched messages. Keep `suppressHydrationWarning` on the
+  viewport. Pass a `nonce` if you use a Content Security Policy.
+
+```tsx
+const scrollToEndScript = `(function () {
+  var viewport = document.getElementById("messages")
+  if (!viewport) {
+    return
+  }
+  viewport.scrollTop = viewport.scrollHeight
+  viewport.removeAttribute("data-pending-scroll")
+})()`
+
+<MessageScroller>
+  <MessageScrollerViewport id="messages" suppressHydrationWarning>
+    <MessageScrollerContent>{/* transcript */}</MessageScrollerContent>
+  </MessageScrollerViewport>
+  <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
+  <MessageScrollerButton />
+</MessageScroller>
+```
+
+For a "thinking…" indicator while the model generates, apply the `shimmer`
+utility to text. Don't author a custom keyframe animation. See
+[styling.md](./styling.md).
+
+---
+
+## Escape hatch: the scroller hooks
+
+For behavior the parts don't expose, read state from the hooks rather than
+re-implementing the scroller: `useMessageScroller`,
+`useMessageScrollerVisibility`, and `useMessageScrollerScrollable`. They come
+from the auto-installed `@shadcn/react` dependency, so there's nothing extra to
+install. Reach for them only when composition can't express what you need.
diff --git a/.agents/skills/shadcn/rules/composition.md b/.agents/skills/shadcn/rules/composition.md
new file mode 100644
index 0000000..a8aa427
--- /dev/null
+++ b/.agents/skills/shadcn/rules/composition.md
@@ -0,0 +1,213 @@
+# Component Composition
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use Empty component
+- Toast notifications follow the project base
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- Button has no isPending or isLoading prop
+- TabsTrigger must be inside TabsList
+- Avatar always needs AvatarFallback
+- Use Separator instead of raw hr or border divs
+- Use Skeleton for loading placeholders
+- Use Badge instead of custom styled spans
+
+---
+
+## Items always inside their Group component
+
+Never render items directly inside the content container.
+
+**Incorrect:**
+
+```tsx
+<SelectContent>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+
+**Correct:**
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+This applies to all group-based components:
+
+| Item | Group |
+|------|-------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` |
+| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
+| `MenubarItem` | `MenubarGroup` |
+| `ContextMenuItem` | `ContextMenuGroup` |
+| `CommandItem` | `CommandGroup` |
+| `MessageScrollerItem` | `MessageScrollerContent` |
+| `Message` (consecutive, same sender) | `MessageGroup` |
+| `Bubble` (stacked) | `BubbleGroup` |
+| `Attachment` (in a row) | `AttachmentGroup` |
+
+Chat components nest in a fixed order (`MessageScrollerProvider` → `MessageScroller` → `MessageScrollerViewport` → `MessageScrollerContent` → `MessageScrollerItem`). See [chat.md](./chat.md).
+
+---
+
+## Callouts use Alert
+
+```tsx
+<Alert>
+  <AlertTitle>Warning</AlertTitle>
+  <AlertDescription>Something needs attention.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Empty states use Empty component
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Create Project</Button>
+  </EmptyContent>
+</Empty>
+```
+
+---
+
+## Toast notifications follow the project base
+
+For Base UI projects, use the `toast` component:
+
+```tsx
+import { toast } from "@/components/ui/toast"
+
+toast.add({
+  title: "Changes saved.",
+})
+```
+
+For Radix and React Aria projects, use Sonner:
+
+```tsx
+import { toast } from "sonner"
+
+toast.success("Changes saved.")
+toast.error("Something went wrong.")
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+})
+```
+
+---
+
+## Choosing between overlay components
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `Dialog` |
+| Destructive action confirmation | `AlertDialog` |
+| Side panel with details or filters | `Sheet` |
+| Mobile-first bottom panel | `Drawer` |
+| Quick info on hover | `HoverCard` |
+| Small contextual content on click | `Popover` |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
+
+```tsx
+<DialogContent>
+  <DialogHeader>
+    <DialogTitle>Edit Profile</DialogTitle>
+    <DialogDescription>Update your profile.</DialogDescription>
+  </DialogHeader>
+  ...
+</DialogContent>
+```
+
+---
+
+## Card structure
+
+Use full composition — don't dump everything into `CardContent`:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team.</CardDescription>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <Button>Invite</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Button has no isPending or isLoading prop
+
+Compose with `Spinner` + `data-icon` + `disabled`:
+
+```tsx
+<Button disabled>
+  <Spinner data-icon="inline-start" />
+  Saving...
+</Button>
+```
+
+---
+
+## TabsTrigger must be inside TabsList
+
+Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+Always include `AvatarFallback` for when the image fails to load:
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+| Instead of | Use |
+|---|---|
+| `<hr>` or `<div className="border-t">` | `<Separator />` |
+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
+| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |
diff --git a/.agents/skills/shadcn/rules/forms.md b/.agents/skills/shadcn/rules/forms.md
new file mode 100644
index 0000000..f451e2f
--- /dev/null
+++ b/.agents/skills/shadcn/rules/forms.md
@@ -0,0 +1,192 @@
+# Forms & Inputs
+
+## Contents
+
+- Forms use FieldGroup + Field
+- InputGroup requires InputGroupInput/InputGroupTextarea
+- Buttons inside inputs use InputGroup + InputGroupAddon
+- Option sets (2–7 choices) use ToggleGroup
+- FieldSet + FieldLegend for grouping related fields
+- Field validation and disabled states
+
+---
+
+## Forms use FieldGroup + Field
+
+Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
+
+**Choosing form controls:**
+
+- Simple text input → `Input`
+- Dropdown with predefined options → `Select`
+- Searchable dropdown → `Combobox`
+- Native HTML select (no JS) → `native-select`
+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
+- Single choice from few options → `RadioGroup`
+- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
+- OTP/verification code → `InputOTP`
+- Multi-line text → `Textarea`
+
+---
+
+## InputGroup requires InputGroupInput/InputGroupTextarea
+
+Never use raw `Input` or `Textarea` inside an `InputGroup`.
+
+**Incorrect:**
+
+```tsx
+<InputGroup>
+  <Input placeholder="Search..." />
+</InputGroup>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+```
+
+---
+
+## Buttons inside inputs use InputGroup + InputGroupAddon
+
+Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
+
+**Incorrect:**
+
+```tsx
+<div className="relative">
+  <Input placeholder="Search..." className="pr-10" />
+  <Button className="absolute right-0 top-0" size="icon">
+    <SearchIcon />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput, InputGroupAddon } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <Button size="icon">
+      <SearchIcon data-icon="inline-start" />
+    </Button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+Don't manually loop `Button` components with active state.
+
+**Incorrect:**
+
+```tsx
+const [selected, setSelected] = useState("daily")
+
+<div className="flex gap-2">
+  {["daily", "weekly", "monthly"].map((option) => (
+    <Button
+      key={option}
+      variant={selected === option ? "default" : "outline"}
+      onClick={() => setSelected(option)}
+    >
+      {option}
+    </Button>
+  ))}
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
+
+<ToggleGroup spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
+</ToggleGroup>
+```
+
+Combine with `Field` for labelled toggle groups:
+
+```tsx
+<Field orientation="horizontal">
+  <FieldTitle id="theme-label">Theme</FieldTitle>
+  <ToggleGroup aria-labelledby="theme-label" spacing={2}>
+    <ToggleGroupItem value="light">Light</ToggleGroupItem>
+    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="system">System</ToggleGroupItem>
+  </ToggleGroup>
+</Field>
+```
+
+> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).
+
+---
+
+## FieldSet + FieldLegend for grouping related fields
+
+Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Preferences</FieldLegend>
+  <FieldDescription>Select all that apply.</FieldDescription>
+  <FieldGroup className="gap-3">
+    <Field orientation="horizontal">
+      <Checkbox id="dark" />
+      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+---
+
+## Field validation and disabled states
+
+Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
+
+```tsx
+// Invalid.
+<Field data-invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid />
+  <FieldDescription>Invalid email address.</FieldDescription>
+</Field>
+
+// Disabled.
+<Field data-disabled>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" disabled />
+</Field>
+```
+
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.
diff --git a/.agents/skills/shadcn/rules/icons.md b/.agents/skills/shadcn/rules/icons.md
new file mode 100644
index 0000000..bba8102
--- /dev/null
+++ b/.agents/skills/shadcn/rules/icons.md
@@ -0,0 +1,101 @@
+# Icons
+
+**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field from project context: `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. Never assume `lucide-react`.
+
+---
+
+## Icons in Button use data-icon attribute
+
+Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="mr-2 size-4" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start"/>
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon data-icon="inline-end"/>
+</Button>
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other shadcn components. Unless the user explicitly asks for custom icon sizes.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="size-4" data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon className="mr-2 size-4" />
+  Settings
+</DropdownMenuItem>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+```
+
+---
+
+## Pass icons as component objects, not string keys
+
+Use `icon={CheckIcon}`, not a string key to a lookup map.
+
+**Incorrect:**
+
+```tsx
+const iconMap = {
+  check: CheckIcon,
+  alert: AlertIcon,
+}
+
+function StatusBadge({ icon }: { icon: string }) {
+  const Icon = iconMap[icon]
+  return <Icon />
+}
+
+<StatusBadge icon="check" />
+```
+
+**Correct:**
+
+```tsx
+// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
+import { CheckIcon } from "lucide-react"
+
+function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
+  return <Icon />
+}
+
+<StatusBadge icon={CheckIcon} />
+```
diff --git a/.agents/skills/shadcn/rules/styling.md b/.agents/skills/shadcn/rules/styling.md
new file mode 100644
index 0000000..4e6e063
--- /dev/null
+++ b/.agents/skills/shadcn/rules/styling.md
@@ -0,0 +1,185 @@
+# Styling & Customization
+
+See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- className for layout only
+- No space-x-* / space-y-*
+- Prefer size-* over w-* h-* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components
+- Use shimmer / scroll-fade utilities, not custom animations
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```tsx
+<div className="bg-blue-500 text-white">
+  <p className="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<div className="bg-primary text-primary-foreground">
+  <p className="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```tsx
+<span className="text-emerald-600">+20.1%</span>
+<span className="text-green-500">Active</span>
+<span className="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span className="text-destructive">-3.2%</span>
+```
+
+If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```tsx
+<Button className="border border-input bg-transparent hover:bg-accent">
+  Click me
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## className for layout only
+
+Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```tsx
+<Card className="bg-blue-100 text-blue-900 font-bold">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+**Correct:**
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
+
+---
+
+## No space-x-* / space-y-*
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-* over w-* h-* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
+
+**Incorrect:**
+
+```tsx
+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "cn"
+
+<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.
+
+---
+
+## Use shimmer / scroll-fade utilities, not custom animations
+
+For a live "thinking…" or loading-text shimmer, apply the `shimmer` utility. Don't author a custom `@keyframes` or a `bg-clip-text` gradient sweep.
+
+For scroll-aware edge fading on a scroll container, use `scroll-fade` (and the axis variants `scroll-fade-x` / `scroll-fade-b`). Don't hand-roll mask gradients. The chat components already apply these internally: `Attachment` shimmers its title during upload, and `MessageScrollerViewport` fades its edges.
+
+**Incorrect:**
+
+```tsx
+<span className="animate-pulse bg-gradient-to-r from-muted-foreground/40 via-foreground/70 to-muted-foreground/40 bg-clip-text text-transparent [animation:shimmer_1.6s_infinite]">
+  Thinking…
+</span>
+```
+
+**Correct:**
+
+```tsx
+<span className="shimmer">Thinking…</span>
+```
diff --git a/.agents/skills/tanstack-query-best-practices/SKILL.md b/.agents/skills/tanstack-query-best-practices/SKILL.md
new file mode 100644
index 0000000..374b847
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: tanstack-query-best-practices
+description: TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
+---
+
+# TanStack Query Best Practices
+
+Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
+
+## When to Apply
+
+- Creating new data fetching logic
+- Setting up query configurations
+- Implementing mutations and optimistic updates
+- Configuring caching strategies
+- Integrating with SSR/SSG
+- Refactoring existing data fetching code
+
+## Rule Categories by Priority
+
+| Priority | Category | Rules | Impact |
+|----------|----------|-------|--------|
+| CRITICAL | Query Keys | 5 rules | Prevents cache bugs and data inconsistencies |
+| CRITICAL | Caching | 5 rules | Optimizes performance and data freshness |
+| HIGH | Mutations | 6 rules | Ensures data integrity and UI consistency |
+| HIGH | Error Handling | 3 rules | Prevents poor user experiences |
+| MEDIUM | Prefetching | 4 rules | Improves perceived performance |
+| MEDIUM | Parallel Queries | 2 rules | Enables dynamic parallel fetching |
+| MEDIUM | Infinite Queries | 3 rules | Prevents pagination bugs |
+| MEDIUM | SSR Integration | 4 rules | Enables proper hydration |
+| LOW | Performance | 4 rules | Reduces unnecessary re-renders |
+| LOW | Offline Support | 2 rules | Enables offline-first patterns |
+
+## Quick Reference
+
+### Query Keys (Prefix: `qk-`)
+
+- `qk-array-structure` — Always use arrays for query keys
+- `qk-include-dependencies` — Include all variables the query depends on
+- `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters)
+- `qk-factory-pattern` — Use query key factories for complex applications
+- `qk-serializable` — Ensure all key parts are JSON-serializable
+
+### Caching (Prefix: `cache-`)
+
+- `cache-stale-time` — Set appropriate staleTime based on data volatility
+- `cache-gc-time` — Configure gcTime for inactive query retention
+- `cache-defaults` — Set sensible defaults at QueryClient level
+- `cache-invalidation` — Use targeted invalidation over broad patterns
+- `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences
+
+### Mutations (Prefix: `mut-`)
+
+- `mut-invalidate-queries` — Always invalidate related queries after mutations
+- `mut-optimistic-updates` — Implement optimistic updates for responsive UI
+- `mut-rollback-context` — Provide rollback context from onMutate
+- `mut-error-handling` — Handle mutation errors gracefully
+- `mut-loading-states` — Use isPending for mutation loading states
+- `mut-mutation-state` — Use useMutationState for cross-component tracking
+
+### Error Handling (Prefix: `err-`)
+
+- `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary
+- `err-retry-config` — Configure retry logic appropriately
+- `err-fallback-data` — Provide fallback data when appropriate
+
+### Prefetching (Prefix: `pf-`)
+
+- `pf-intent-prefetch` — Prefetch on user intent (hover, focus)
+- `pf-route-prefetch` — Prefetch data during route transitions
+- `pf-stale-time-config` — Set staleTime when prefetching
+- `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching
+
+### Infinite Queries (Prefix: `inf-`)
+
+- `inf-page-params` — Always provide getNextPageParam
+- `inf-loading-guards` — Check isFetchingNextPage before fetching more
+- `inf-max-pages` — Consider maxPages for large datasets
+
+### SSR Integration (Prefix: `ssr-`)
+
+- `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR
+- `ssr-client-per-request` — Create QueryClient per request
+- `ssr-stale-time-server` — Set higher staleTime on server
+- `ssr-hydration-boundary` — Wrap with HydrationBoundary
+
+### Parallel Queries (Prefix: `parallel-`)
+
+- `parallel-use-queries` — Use useQueries for dynamic parallel queries
+- `query-cancellation` — Implement query cancellation properly
+
+### Performance (Prefix: `perf-`)
+
+- `perf-select-transform` — Use select to transform/filter data
+- `perf-structural-sharing` — Leverage structural sharing
+- `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps
+- `perf-placeholder-data` — Use placeholderData for instant UI
+
+### Offline Support (Prefix: `offline-`)
+
+- `network-mode` — Configure network mode for offline support
+- `persist-queries` — Configure query persistence for offline support
+
+## How to Use
+
+Each rule file in the `rules/` directory contains:
+1. **Explanation** — Why this pattern matters
+2. **Bad Example** — Anti-pattern to avoid
+3. **Good Example** — Recommended implementation
+4. **Context** — When to apply or skip this rule
+
+## Full Reference
+
+See individual rule files in `rules/` directory for detailed guidance and code examples.
diff --git a/.agents/skills/tanstack-query-best-practices/rules/cache-gc-time.md b/.agents/skills/tanstack-query-best-practices/rules/cache-gc-time.md
new file mode 100644
index 0000000..7f8f769
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/cache-gc-time.md
@@ -0,0 +1,93 @@
+# cache-gc-time: Configure gcTime for Inactive Query Retention
+
+## Priority: CRITICAL
+
+## Explanation
+
+`gcTime` (garbage collection time, formerly `cacheTime`) controls how long inactive queries remain in the cache before being garbage collected. Default is 5 minutes. Configure based on your navigation patterns and memory constraints.
+
+## Bad Example
+
+```tsx
+// Not considering gcTime for frequently revisited pages
+const { data } = useQuery({
+  queryKey: ['dashboard-stats'],
+  queryFn: fetchDashboardStats,
+  // Default gcTime of 5 minutes - might be too short for frequently revisited data
+})
+
+// Setting gcTime too high without consideration
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: Infinity,  // Never garbage collect - potential memory leak
+    },
+  },
+})
+
+// Setting gcTime to 0 - cache is immediately removed
+const { data } = useQuery({
+  queryKey: ['user-data'],
+  queryFn: fetchUserData,
+  gcTime: 0,  // Loses cache benefits entirely
+})
+```
+
+## Good Example
+
+```tsx
+// Longer gcTime for frequently revisited data
+const { data } = useQuery({
+  queryKey: ['dashboard-stats'],
+  queryFn: fetchDashboardStats,
+  gcTime: 30 * 60 * 1000,  // 30 minutes - user returns to dashboard often
+})
+
+// Shorter gcTime for rarely revisited large data
+const { data: report } = useQuery({
+  queryKey: ['detailed-report', reportId],
+  queryFn: () => fetchReport(reportId),
+  gcTime: 2 * 60 * 1000,  // 2 minutes - large payload, viewed once
+})
+
+// Sensible default with query-specific overrides
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 10 * 60 * 1000,  // 10 minutes default
+    },
+  },
+})
+```
+
+## Understanding gcTime vs staleTime
+
+```
+Query Mount → Data Fresh (staleTime) → Data Stale → Query Unmount → gcTime countdown → Garbage Collected
+
+Timeline example (staleTime: 1min, gcTime: 5min):
+0:00 - Query mounts, fetches data
+0:00-1:00 - Data is fresh (no background refetch)
+1:00+ - Data is stale (background refetch on new mount)
+5:00 - User navigates away, query unmounts
+5:00-10:00 - Data in cache but inactive (gcTime countdown)
+10:00 - Data garbage collected (next mount = full loading state)
+```
+
+## Recommended gcTime Values
+
+| Scenario | gcTime | Rationale |
+|----------|--------|-----------|
+| Frequently revisited routes | 15 - 30min | Instant navigation |
+| Detail pages (viewed once) | 2 - 5min | Memory efficient |
+| Large payloads | 1 - 2min | Prevent memory bloat |
+| Critical user data | 30min+ | Offline-like experience |
+| SSR hydration | >= 2s | Prevent hydration issues |
+
+## Context
+
+- gcTime countdown starts when ALL query observers unmount
+- Remounting before gcTime expires returns cached data instantly
+- Setting gcTime < staleTime is rarely useful
+- For SSR, avoid gcTime: 0 (use minimum 2000ms to allow hydration)
+- Monitor memory usage in long-running applications
diff --git a/.agents/skills/tanstack-query-best-practices/rules/cache-invalidation.md b/.agents/skills/tanstack-query-best-practices/rules/cache-invalidation.md
new file mode 100644
index 0000000..51172f6
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/cache-invalidation.md
@@ -0,0 +1,116 @@
+# cache-invalidation: Use Targeted Invalidation Over Broad Patterns
+
+## Priority: CRITICAL
+
+## Explanation
+
+Query invalidation marks cached data as stale, triggering background refetches. Use targeted invalidation to refresh only affected data. Overly broad invalidation causes unnecessary network requests; too narrow invalidation leaves stale data.
+
+## Bad Example
+
+```tsx
+// Invalidating everything after a single todo update
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSuccess: () => {
+    queryClient.invalidateQueries()  // Invalidates ENTIRE cache
+  },
+})
+
+// Invalidating too broadly
+const mutation = useMutation({
+  mutationFn: updateTodoStatus,
+  onSuccess: () => {
+    // Invalidates all todos including unrelated lists
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// Missing invalidation of related queries
+const mutation = useMutation({
+  mutationFn: addComment,
+  onSuccess: () => {
+    // Only invalidates comment list, misses comment count
+    queryClient.invalidateQueries({ queryKey: ['comments', postId] })
+  },
+})
+```
+
+## Good Example
+
+```tsx
+// Targeted invalidation with exact matching
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSuccess: (data, variables) => {
+    // Invalidate specific todo and related queries
+    queryClient.invalidateQueries({ queryKey: ['todos', variables.id] })
+    // Also invalidate lists that might contain this todo
+    queryClient.invalidateQueries({ queryKey: ['todos', 'list'] })
+  },
+})
+
+// Use exact: true when you only want one specific query
+const mutation = useMutation({
+  mutationFn: updateUserProfile,
+  onSuccess: () => {
+    queryClient.invalidateQueries({
+      queryKey: ['user', 'profile'],
+      exact: true,  // Only this exact key, not ['user', 'profile', 'settings']
+    })
+  },
+})
+
+// Invalidate multiple related queries
+const mutation = useMutation({
+  mutationFn: addComment,
+  onSuccess: (data, { postId }) => {
+    // Invalidate all comment-related queries for this post
+    queryClient.invalidateQueries({ queryKey: ['posts', postId, 'comments'] })
+    queryClient.invalidateQueries({ queryKey: ['posts', postId, 'comment-count'] })
+    // Optionally invalidate the post itself if it shows comment count
+    queryClient.invalidateQueries({ queryKey: ['posts', postId] })
+  },
+})
+
+// Predicate-based invalidation for complex scenarios
+queryClient.invalidateQueries({
+  predicate: (query) =>
+    query.queryKey[0] === 'todos' &&
+    query.state.data?.userId === currentUserId,
+})
+```
+
+## Invalidation Patterns
+
+```tsx
+// Prefix matching (default) - invalidates all matching prefixes
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+// Matches: ['todos'], ['todos', 1], ['todos', { status: 'done' }]
+
+// Exact matching - only the exact key
+queryClient.invalidateQueries({ queryKey: ['todos'], exact: true })
+// Matches: ['todos'] only
+
+// Predicate matching - custom logic
+queryClient.invalidateQueries({
+  predicate: (query) => query.queryKey.includes('user-generated'),
+})
+
+// Refetch type control
+queryClient.invalidateQueries({
+  queryKey: ['todos'],
+  refetchType: 'active',  // Only refetch active queries (default)
+  // refetchType: 'inactive' - Only inactive
+  // refetchType: 'all' - Both
+  // refetchType: 'none' - Mark stale but don't refetch
+})
+```
+
+## Context
+
+- Invalidation only marks queries as stale; refetch happens when query is used
+- `refetchType: 'active'` (default) only refetches queries with active observers
+- Use hierarchical query keys to enable precise invalidation
+- Consider `setQueryData` for optimistic updates instead of invalidation
+- Always test invalidation patterns to ensure all affected queries are refreshed
diff --git a/.agents/skills/tanstack-query-best-practices/rules/cache-placeholder-vs-initial.md b/.agents/skills/tanstack-query-best-practices/rules/cache-placeholder-vs-initial.md
new file mode 100644
index 0000000..0d169b2
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/cache-placeholder-vs-initial.md
@@ -0,0 +1,156 @@
+# cache-placeholder-vs-initial: Understand Placeholder vs Initial Data
+
+## Priority: MEDIUM
+
+## Explanation
+
+`placeholderData` and `initialData` both provide data before the fetch completes, but behave differently. `initialData` is treated as real cached data, while `placeholderData` is temporary and doesn't persist to cache. Choose based on whether your fallback data should be cached.
+
+## Bad Example
+
+```tsx
+// Using initialData when you don't want it cached
+function PostPreview({ postId, previewData }: Props) {
+  const { data } = useQuery({
+    queryKey: ['posts', postId],
+    queryFn: () => fetchPost(postId),
+    initialData: previewData,  // Wrong: this becomes cached "truth"
+    // If previewData is incomplete, it pollutes the cache
+    // staleTime applies to this data as if it were fetched
+  })
+}
+
+// Using placeholderData when you want persistence
+function UserProfile({ userId }: Props) {
+  const { data } = useQuery({
+    queryKey: ['users', userId],
+    queryFn: () => fetchUser(userId),
+    placeholderData: cachedUserFromList,  // Wrong: won't persist
+    // User navigates away and back - placeholder shown again
+    // No cache entry created until fetch completes
+  })
+}
+```
+
+## Good Example: placeholderData for Temporary Display
+
+```tsx
+// Show list data while fetching detail
+function PostDetail({ postId }: { postId: string }) {
+  const queryClient = useQueryClient()
+
+  const { data, isPlaceholderData } = useQuery({
+    queryKey: ['posts', postId],
+    queryFn: () => fetchPost(postId),
+    placeholderData: () => {
+      // Use partial data from list cache as placeholder
+      const posts = queryClient.getQueryData<Post[]>(['posts'])
+      return posts?.find(p => p.id === postId)
+    },
+  })
+
+  return (
+    <article className={isPlaceholderData ? 'opacity-50' : ''}>
+      <h1>{data?.title}</h1>
+      {isPlaceholderData ? (
+        <p>Loading full content...</p>
+      ) : (
+        <div>{data?.content}</div>
+      )}
+    </article>
+  )
+}
+```
+
+## Good Example: initialData for Known Good Data
+
+```tsx
+// SSR: Data fetched on server should be initial
+function PostPage({ serverData }: { serverData: Post }) {
+  const { data } = useQuery({
+    queryKey: ['posts', serverData.id],
+    queryFn: () => fetchPost(serverData.id),
+    initialData: serverData,
+    // Specify when this data was fetched for proper stale calculation
+    initialDataUpdatedAt: serverData.fetchedAt,
+  })
+
+  return <PostContent post={data} />
+}
+
+// Pre-seeding cache with complete data
+function App() {
+  const queryClient = useQueryClient()
+
+  // If you have complete, authoritative data
+  useEffect(() => {
+    queryClient.setQueryData(['config'], completeConfigData)
+  }, [])
+}
+```
+
+## Good Example: keepPreviousData Pattern
+
+```tsx
+// Keep showing old data while fetching new (pagination, filters)
+function ProductList({ page }: { page: number }) {
+  const { data, isPlaceholderData } = useQuery({
+    queryKey: ['products', page],
+    queryFn: () => fetchProducts(page),
+    placeholderData: keepPreviousData,  // Built-in helper
+  })
+
+  return (
+    <div className={isPlaceholderData ? 'opacity-70' : ''}>
+      {data?.map(product => (
+        <ProductCard key={product.id} product={product} />
+      ))}
+      {isPlaceholderData && <LoadingOverlay />}
+    </div>
+  )
+}
+```
+
+## Comparison Table
+
+| Behavior | `initialData` | `placeholderData` |
+|----------|---------------|-------------------|
+| Persisted to cache | Yes | No |
+| `staleTime` applies | Yes | No (always fetches) |
+| `isPlaceholderData` | `false` | `true` |
+| Shown to other components | Yes (cached) | No |
+| Use case | SSR, complete known data | Preview, previous page |
+| Affects `dataUpdatedAt` | Yes (use `initialDataUpdatedAt`) | No |
+
+## Good Example: Combining Both
+
+```tsx
+function PostDetail({ postId, ssrData }: Props) {
+  const queryClient = useQueryClient()
+
+  const { data } = useQuery({
+    queryKey: ['posts', postId],
+    queryFn: () => fetchPost(postId),
+
+    // If we have SSR data, use as initial (cached)
+    initialData: ssrData,
+    initialDataUpdatedAt: ssrData?.fetchedAt,
+
+    // If no SSR data, try to use list preview as placeholder
+    placeholderData: () => {
+      if (ssrData) return undefined  // Already have initial
+      const posts = queryClient.getQueryData<Post[]>(['posts'])
+      return posts?.find(p => p.id === postId)
+    },
+  })
+}
+```
+
+## Context
+
+- `placeholderData` can be a value or function (lazy evaluation)
+- `initialData` affects cache immediately on query creation
+- Use `initialDataUpdatedAt` with `initialData` for proper stale calculations
+- `keepPreviousData` is a built-in placeholder strategy
+- Check `isPlaceholderData` to show loading indicators
+- `placeholderData` is ideal for "instant" UI while fetching
diff --git a/.agents/skills/tanstack-query-best-practices/rules/cache-stale-time.md b/.agents/skills/tanstack-query-best-practices/rules/cache-stale-time.md
new file mode 100644
index 0000000..fa38fe4
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/cache-stale-time.md
@@ -0,0 +1,80 @@
+# cache-stale-time: Set Appropriate staleTime Based on Data Volatility
+
+## Priority: CRITICAL
+
+## Explanation
+
+`staleTime` determines how long data is considered fresh. The default is 0ms, meaning data is immediately stale and will refetch on every new query mount. Set appropriate staleTime based on how often your data actually changes to reduce unnecessary network requests.
+
+## Bad Example
+
+```tsx
+// Default staleTime of 0 - refetches on every component mount
+const { data } = useQuery({
+  queryKey: ['user-profile', userId],
+  queryFn: () => fetchUserProfile(userId),
+  // No staleTime set - always considered stale
+})
+
+// User profile probably doesn't change every second
+// This causes unnecessary API calls on navigation
+
+// Setting same staleTime everywhere regardless of data type
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000,  // 1 minute for everything - too simple
+    },
+  },
+})
+```
+
+## Good Example
+
+```tsx
+// Match staleTime to data volatility
+const { data: profile } = useQuery({
+  queryKey: ['user-profile', userId],
+  queryFn: () => fetchUserProfile(userId),
+  staleTime: 5 * 60 * 1000,  // 5 minutes - profile rarely changes
+})
+
+const { data: notifications } = useQuery({
+  queryKey: ['notifications'],
+  queryFn: fetchNotifications,
+  staleTime: 30 * 1000,  // 30 seconds - changes more frequently
+})
+
+const { data: stockPrice } = useQuery({
+  queryKey: ['stock', symbol],
+  queryFn: () => fetchStockPrice(symbol),
+  staleTime: 0,  // Real-time data - always refetch
+})
+
+// Set sensible defaults, override per-query
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000,  // 1 minute default
+    },
+  },
+})
+```
+
+## Recommended staleTime Values
+
+| Data Type | staleTime | Rationale |
+|-----------|-----------|-----------|
+| Real-time (stocks, live feeds) | 0 | Must always be current |
+| Frequently changing (notifications) | 30s - 1min | Balance freshness and requests |
+| User-generated content | 1 - 5min | Changes on user action |
+| Reference data (categories, config) | 10 - 30min | Rarely changes |
+| Static content | Infinity | Never changes |
+
+## Context
+
+- `staleTime: 0` (default) triggers background refetch on every mount
+- `staleTime: Infinity` never considers data stale (manual invalidation only)
+- Stale data is still returned instantly - refetch happens in background
+- For SSR, set higher staleTime to avoid immediate client refetch
+- Consider using `queryOptions` factory to centralize staleTime per data type
diff --git a/.agents/skills/tanstack-query-best-practices/rules/err-error-boundaries.md b/.agents/skills/tanstack-query-best-practices/rules/err-error-boundaries.md
new file mode 100644
index 0000000..0209561
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/err-error-boundaries.md
@@ -0,0 +1,150 @@
+# err-error-boundaries: Use Error Boundaries with useQueryErrorResetBoundary
+
+## Priority: HIGH
+
+## Explanation
+
+When using Suspense with TanStack Query, errors propagate to error boundaries. Use `useQueryErrorResetBoundary` to reset query errors when users retry, preventing stuck error states.
+
+## Bad Example
+
+```tsx
+// Error boundary without query reset - retry may not work
+function ErrorBoundary({ children }: { children: React.ReactNode }) {
+  return (
+    <ReactErrorBoundary
+      fallbackRender={({ error, resetErrorBoundary }) => (
+        <div>
+          <p>Error: {error.message}</p>
+          <button onClick={resetErrorBoundary}>Try again</button>
+          {/* resetErrorBoundary alone doesn't reset query state */}
+        </div>
+      )}
+    >
+      {children}
+    </ReactErrorBoundary>
+  )
+}
+
+// Query error persists after retry click
+```
+
+## Good Example
+
+```tsx
+import { useQueryErrorResetBoundary } from '@tanstack/react-query'
+import { ErrorBoundary } from 'react-error-boundary'
+
+function QueryErrorBoundary({ children }: { children: React.ReactNode }) {
+  const { reset } = useQueryErrorResetBoundary()
+
+  return (
+    <ErrorBoundary
+      onReset={reset}
+      fallbackRender={({ error, resetErrorBoundary }) => (
+        <div className="error-container">
+          <h2>Something went wrong</h2>
+          <pre>{error.message}</pre>
+          <button onClick={resetErrorBoundary}>
+            Try again
+          </button>
+        </div>
+      )}
+    >
+      {children}
+    </ErrorBoundary>
+  )
+}
+
+// Usage with Suspense
+function App() {
+  return (
+    <QueryErrorBoundary>
+      <Suspense fallback={<Loading />}>
+        <Posts />
+      </Suspense>
+    </QueryErrorBoundary>
+  )
+}
+
+function Posts() {
+  // useSuspenseQuery throws on error, caught by boundary
+  const { data } = useSuspenseQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+  })
+
+  return <PostList posts={data} />
+}
+```
+
+## Good Example: With TanStack Router
+
+```tsx
+// Route-level error handling
+import { createFileRoute } from '@tanstack/react-router'
+import { useQueryErrorResetBoundary } from '@tanstack/react-query'
+
+export const Route = createFileRoute('/posts')({
+  loader: ({ context: { queryClient } }) =>
+    queryClient.ensureQueryData(postQueries.list()),
+
+  errorComponent: ({ error, reset }) => {
+    const { reset: resetQuery } = useQueryErrorResetBoundary()
+
+    return (
+      <div>
+        <p>Failed to load posts: {error.message}</p>
+        <button
+          onClick={() => {
+            resetQuery()
+            reset()
+          }}
+        >
+          Retry
+        </button>
+      </div>
+    )
+  },
+
+  component: PostsPage,
+})
+```
+
+## Error Boundary Placement Strategy
+
+```tsx
+// Granular error boundaries for isolated failures
+function Dashboard() {
+  return (
+    <div className="dashboard">
+      {/* Each section can fail independently */}
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <RecentActivity />
+        </Suspense>
+      </QueryErrorBoundary>
+
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <Statistics />
+        </Suspense>
+      </QueryErrorBoundary>
+
+      <QueryErrorBoundary>
+        <Suspense fallback={<Skeleton />}>
+          <Notifications />
+        </Suspense>
+      </QueryErrorBoundary>
+    </div>
+  )
+}
+```
+
+## Context
+
+- `useQueryErrorResetBoundary` clears error state for all queries in the boundary
+- Always pair Suspense queries with error boundaries
+- Place boundaries based on failure isolation needs
+- Consider inline error handling for non-critical data
+- The reset only affects queries that were in error state
diff --git a/.agents/skills/tanstack-query-best-practices/rules/inf-page-params.md b/.agents/skills/tanstack-query-best-practices/rules/inf-page-params.md
new file mode 100644
index 0000000..7a1ccf5
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/inf-page-params.md
@@ -0,0 +1,132 @@
+# inf-page-params: Always Provide getNextPageParam for Infinite Queries
+
+## Priority: MEDIUM
+
+## Explanation
+
+`useInfiniteQuery` requires `getNextPageParam` to determine how to fetch subsequent pages. This function receives the last page's data and must return the next page parameter, or `undefined` when there are no more pages.
+
+## Bad Example
+
+```tsx
+// Missing getNextPageParam - can't load more pages
+const { data, fetchNextPage } = useInfiniteQuery({
+  queryKey: ['posts'],
+  queryFn: ({ pageParam }) => fetchPosts(pageParam),
+  initialPageParam: 1,
+  // Missing getNextPageParam - fetchNextPage won't work correctly
+})
+```
+
+## Good Example: Offset-Based Pagination
+
+```tsx
+const {
+  data,
+  fetchNextPage,
+  hasNextPage,
+  isFetchingNextPage,
+} = useInfiniteQuery({
+  queryKey: ['posts'],
+  queryFn: ({ pageParam }) => fetchPosts({ page: pageParam, limit: 20 }),
+  initialPageParam: 1,
+  getNextPageParam: (lastPage, allPages) => {
+    // Return next page number, or undefined if no more pages
+    if (lastPage.length < 20) {
+      return undefined  // No more pages
+    }
+    return allPages.length + 1
+  },
+})
+```
+
+## Good Example: Cursor-Based Pagination
+
+```tsx
+interface PostsResponse {
+  posts: Post[]
+  nextCursor: string | null
+}
+
+const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
+  queryKey: ['posts'],
+  queryFn: ({ pageParam }): Promise<PostsResponse> =>
+    fetchPosts({ cursor: pageParam }),
+  initialPageParam: undefined as string | undefined,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+})
+```
+
+## Good Example: Bi-directional Pagination
+
+```tsx
+const { data, fetchNextPage, fetchPreviousPage, hasNextPage, hasPreviousPage } =
+  useInfiniteQuery({
+    queryKey: ['messages', chatId],
+    queryFn: ({ pageParam }) => fetchMessages({ chatId, cursor: pageParam }),
+    initialPageParam: { direction: 'initial' } as PageParam,
+    getNextPageParam: (lastPage) =>
+      lastPage.hasMore ? { cursor: lastPage.nextCursor, direction: 'next' } : undefined,
+    getPreviousPageParam: (firstPage) =>
+      firstPage.hasPrevious
+        ? { cursor: firstPage.prevCursor, direction: 'prev' }
+        : undefined,
+  })
+```
+
+## Good Example: With Total Count
+
+```tsx
+interface PaginatedResponse<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+const { data, hasNextPage } = useInfiniteQuery({
+  queryKey: ['products', filters],
+  queryFn: ({ pageParam }) =>
+    fetchProducts({ ...filters, page: pageParam, pageSize: 20 }),
+  initialPageParam: 1,
+  getNextPageParam: (lastPage) => {
+    const totalPages = Math.ceil(lastPage.total / lastPage.pageSize)
+    if (lastPage.page < totalPages) {
+      return lastPage.page + 1
+    }
+    return undefined
+  },
+})
+```
+
+## Accessing Flattened Data
+
+```tsx
+// data.pages is an array of page responses
+// Flatten for easier iteration
+const allPosts = data?.pages.flatMap(page => page.posts) ?? []
+
+return (
+  <div>
+    {allPosts.map(post => (
+      <PostCard key={post.id} post={post} />
+    ))}
+    {hasNextPage && (
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={isFetchingNextPage}
+      >
+        {isFetchingNextPage ? 'Loading...' : 'Load More'}
+      </button>
+    )}
+  </div>
+)
+```
+
+## Context
+
+- `getNextPageParam` returning `undefined` sets `hasNextPage` to `false`
+- For bi-directional scrolling, also provide `getPreviousPageParam`
+- `initialPageParam` is required and sets the first page parameter
+- Use `maxPages` option to limit stored pages for memory management
+- Consider `select` to transform page structure for component consumption
diff --git a/.agents/skills/tanstack-query-best-practices/rules/mut-invalidate-queries.md b/.agents/skills/tanstack-query-best-practices/rules/mut-invalidate-queries.md
new file mode 100644
index 0000000..b2de2ab
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/mut-invalidate-queries.md
@@ -0,0 +1,118 @@
+# mut-invalidate-queries: Always Invalidate Related Queries After Mutations
+
+## Priority: HIGH
+
+## Explanation
+
+After mutations, invalidate all queries whose data might be affected. This ensures the cache stays synchronized with the server. Forgetting to invalidate related queries leads to stale UI data.
+
+## Bad Example
+
+```tsx
+// No invalidation - cache remains stale
+const createTodo = useMutation({
+  mutationFn: (newTodo) => api.createTodo(newTodo),
+  // Missing onSuccess handler - todo list won't show new item
+})
+
+// Partial invalidation - misses related queries
+const deleteTodo = useMutation({
+  mutationFn: (todoId) => api.deleteTodo(todoId),
+  onSuccess: () => {
+    // Only invalidates list, not summary/counts
+    queryClient.invalidateQueries({ queryKey: ['todos', 'list'] })
+    // Missing: ['todos', 'count'], ['todos', 'completed-count'], etc.
+  },
+})
+```
+
+## Good Example
+
+```tsx
+// Comprehensive invalidation
+const createTodo = useMutation({
+  mutationFn: (newTodo) => api.createTodo(newTodo),
+  onSuccess: () => {
+    // Invalidate all todo-related queries
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// Targeted invalidation with all affected queries
+const updateTodo = useMutation({
+  mutationFn: ({ id, data }) => api.updateTodo(id, data),
+  onSuccess: (data, { id }) => {
+    // Specific todo
+    queryClient.invalidateQueries({ queryKey: ['todos', id] })
+    // Lists that might contain this todo
+    queryClient.invalidateQueries({ queryKey: ['todos', 'list'] })
+    // If todo status changed, invalidate filtered views
+    queryClient.invalidateQueries({ queryKey: ['todos', 'completed'] })
+    queryClient.invalidateQueries({ queryKey: ['todos', 'active'] })
+  },
+})
+
+// Cross-entity invalidation
+const assignTodoToUser = useMutation({
+  mutationFn: ({ todoId, userId }) => api.assignTodo(todoId, userId),
+  onSuccess: (data, { todoId, userId }) => {
+    // Invalidate the todo
+    queryClient.invalidateQueries({ queryKey: ['todos', todoId] })
+    // Invalidate user's assigned todos
+    queryClient.invalidateQueries({ queryKey: ['users', userId, 'todos'] })
+    // Invalidate previous assignee's list if available
+    if (data.previousAssignee) {
+      queryClient.invalidateQueries({
+        queryKey: ['users', data.previousAssignee, 'todos'],
+      })
+    }
+  },
+})
+```
+
+## Pattern: Mutation with Variables Access
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updatePost,
+  onSuccess: (
+    data,      // Server response
+    variables, // What you passed to mutate()
+    context    // What onMutate returned
+  ) => {
+    // Use variables to know which queries to invalidate
+    queryClient.invalidateQueries({ queryKey: ['posts', variables.id] })
+    queryClient.invalidateQueries({ queryKey: ['posts', 'list', variables.category] })
+  },
+})
+```
+
+## Pattern: Invalidate or Update Directly
+
+```tsx
+// Option 1: Invalidate and refetch
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: ['todos'] })
+}
+
+// Option 2: Update cache directly (no network request)
+onSuccess: (newTodo) => {
+  queryClient.setQueryData(['todos'], (old: Todo[]) => [...old, newTodo])
+}
+
+// Option 3: Hybrid - update one, invalidate others
+onSuccess: (newTodo) => {
+  // Immediately add to list
+  queryClient.setQueryData(['todos', 'list'], (old: Todo[]) => [...old, newTodo])
+  // Invalidate counts/summaries for eventual consistency
+  queryClient.invalidateQueries({ queryKey: ['todos', 'count'] })
+}
+```
+
+## Context
+
+- Place invalidation in `onSuccess` for successful mutations
+- Use `onSettled` if you want to invalidate regardless of success/failure
+- Think about all UI surfaces that display related data
+- For complex relationships, consider a centralized invalidation helper
+- Using hierarchical query keys makes this easier (see `qk-hierarchical-organization`)
diff --git a/.agents/skills/tanstack-query-best-practices/rules/mut-mutation-state.md b/.agents/skills/tanstack-query-best-practices/rules/mut-mutation-state.md
new file mode 100644
index 0000000..ea050c7
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/mut-mutation-state.md
@@ -0,0 +1,169 @@
+# mut-mutation-state: Use useMutationState for Cross-Component Mutation Tracking
+
+## Priority: MEDIUM
+
+## Explanation
+
+`useMutationState` allows you to access mutation state from anywhere in your component tree, not just where `useMutation` was called. Use it to show loading indicators, display optimistic updates, or track pending mutations across components.
+
+## Bad Example
+
+```tsx
+// Prop drilling mutation state
+function App() {
+  const mutation = useMutation({ mutationFn: createPost })
+
+  return (
+    <div>
+      <Header isPending={mutation.isPending} />
+      <Sidebar isPending={mutation.isPending} />
+      <Content mutation={mutation} />
+      <Footer isPending={mutation.isPending} />
+    </div>
+  )
+}
+
+// Or using context for every mutation
+const MutationContext = createContext<UseMutationResult | null>(null)
+```
+
+## Good Example
+
+```tsx
+// Define mutation with a key
+const useCreatePost = () => useMutation({
+  mutationKey: ['create-post'],
+  mutationFn: createPost,
+})
+
+// In the component that triggers mutation
+function CreatePostButton() {
+  const mutation = useCreatePost()
+
+  return (
+    <button onClick={() => mutation.mutate(newPost)}>
+      Create Post
+    </button>
+  )
+}
+
+// In any other component - track mutation state
+function GlobalLoadingIndicator() {
+  const pendingMutations = useMutationState({
+    filters: { status: 'pending' },
+    select: (mutation) => mutation.state.variables,
+  })
+
+  if (pendingMutations.length === 0) return null
+
+  return (
+    <div className="global-loading">
+      Saving {pendingMutations.length} item(s)...
+    </div>
+  )
+}
+```
+
+## Good Example: Optimistic UI in Separate Component
+
+```tsx
+// Mutation defined in form
+function TodoForm() {
+  const createTodo = useMutation({
+    mutationKey: ['create-todo'],
+    mutationFn: (todo: NewTodo) => api.createTodo(todo),
+  })
+
+  return <form onSubmit={...}>...</form>
+}
+
+// Optimistic display in list (different component)
+function TodoList() {
+  const { data: todos } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+  // Get pending todo creations
+  const pendingTodos = useMutationState({
+    filters: {
+      mutationKey: ['create-todo'],
+      status: 'pending',
+    },
+    select: (mutation) => mutation.state.variables as NewTodo,
+  })
+
+  return (
+    <ul>
+      {/* Existing todos */}
+      {todos?.map(todo => (
+        <TodoItem key={todo.id} todo={todo} />
+      ))}
+
+      {/* Optimistic todos (pending creation) */}
+      {pendingTodos.map((todo, index) => (
+        <TodoItem
+          key={`pending-${index}`}
+          todo={{ ...todo, id: `temp-${index}` }}
+          isPending
+        />
+      ))}
+    </ul>
+  )
+}
+```
+
+## Good Example: Track Specific Mutations
+
+```tsx
+function PostActions({ postId }: { postId: string }) {
+  // Track if THIS post is being deleted
+  const isDeletingThisPost = useMutationState({
+    filters: {
+      mutationKey: ['delete-post', postId],
+      status: 'pending',
+    },
+    select: () => true,
+  }).length > 0
+
+  // Track if THIS post is being updated
+  const isUpdatingThisPost = useMutationState({
+    filters: {
+      mutationKey: ['update-post', postId],
+      status: 'pending',
+    },
+    select: () => true,
+  }).length > 0
+
+  return (
+    <div>
+      <button disabled={isDeletingThisPost || isUpdatingThisPost}>
+        {isDeletingThisPost ? 'Deleting...' : 'Delete'}
+      </button>
+    </div>
+  )
+}
+```
+
+## Filters Reference
+
+```tsx
+useMutationState({
+  filters: {
+    mutationKey: ['key'],           // Match mutation key
+    status: 'pending',              // 'idle' | 'pending' | 'success' | 'error'
+    predicate: (mutation) => bool,  // Custom filter function
+  },
+  select: (mutation) => {
+    // Transform each matching mutation
+    // mutation.state contains: variables, data, error, status, etc.
+    return mutation.state.variables
+  },
+})
+```
+
+## Context
+
+- Requires `mutationKey` on mutations you want to track
+- Returns array of selected values from matching mutations
+- Updates reactively as mutations progress
+- Use `status` filter to track pending/success/error states
+- Enables optimistic UI without prop drilling
+- Pairs with `mutationKey` arrays for granular tracking (e.g., `['delete-post', postId]`)
diff --git a/.agents/skills/tanstack-query-best-practices/rules/mut-optimistic-updates.md b/.agents/skills/tanstack-query-best-practices/rules/mut-optimistic-updates.md
new file mode 100644
index 0000000..89e9235
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/mut-optimistic-updates.md
@@ -0,0 +1,137 @@
+# mut-optimistic-updates: Implement Optimistic Updates for Responsive UI
+
+## Priority: HIGH
+
+## Explanation
+
+Optimistic updates immediately reflect changes in the UI before the server confirms them, creating a snappy user experience. Implement them for user-initiated mutations where the expected outcome is predictable.
+
+## Bad Example
+
+```tsx
+// No optimistic update - UI waits for server response
+const mutation = useMutation({
+  mutationFn: toggleTodoComplete,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// User clicks checkbox, waits 200-500ms for visual feedback
+```
+
+## Good Example: Via Cache Manipulation
+
+```tsx
+const mutation = useMutation({
+  mutationFn: toggleTodoComplete,
+  onMutate: async (todoId) => {
+    // 1. Cancel outgoing refetches to prevent overwriting optimistic update
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    // 2. Snapshot previous value for potential rollback
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // 3. Optimistically update the cache
+    queryClient.setQueryData(['todos'], (old: Todo[]) =>
+      old.map((todo) =>
+        todo.id === todoId ? { ...todo, completed: !todo.completed } : todo
+      )
+    )
+
+    // 4. Return context for rollback
+    return { previousTodos }
+  },
+  onError: (err, todoId, context) => {
+    // Rollback on error
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // Refetch to ensure consistency regardless of success/failure
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## Good Example: Via UI Variables (Simpler)
+
+```tsx
+// When mutation only affects local UI, use mutation state directly
+function TodoItem({ todo }: { todo: Todo }) {
+  const mutation = useMutation({
+    mutationFn: toggleTodoComplete,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  // Show optimistic state while pending
+  const displayCompleted = mutation.isPending
+    ? !todo.completed  // Optimistic: show toggled state
+    : todo.completed   // Settled: show actual state
+
+  return (
+    <div>
+      <input
+        type="checkbox"
+        checked={displayCompleted}
+        disabled={mutation.isPending}
+        onChange={() => mutation.mutate(todo.id)}
+      />
+      <span style={{ opacity: mutation.isPending ? 0.5 : 1 }}>
+        {todo.title}
+      </span>
+    </div>
+  )
+}
+```
+
+## Good Example: Optimistic Create with Temporary ID
+
+```tsx
+const createTodo = useMutation({
+  mutationFn: (newTodo: CreateTodoInput) => api.createTodo(newTodo),
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // Add with temporary ID
+    const optimisticTodo = {
+      id: `temp-${Date.now()}`,
+      ...newTodo,
+      completed: false,
+      createdAt: new Date().toISOString(),
+    }
+
+    queryClient.setQueryData(['todos'], (old: Todo[]) => [...old, optimisticTodo])
+
+    return { previousTodos, optimisticTodo }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSuccess: (data, variables, context) => {
+    // Replace temp todo with real one
+    queryClient.setQueryData(['todos'], (old: Todo[]) =>
+      old.map((todo) =>
+        todo.id === context?.optimisticTodo.id ? data : todo
+      )
+    )
+  },
+})
+```
+
+## When to Use Each Approach
+
+| Approach | Use When |
+|----------|----------|
+| Cache Manipulation | Update appears in multiple places, complex data structures |
+| UI Variables | Update only visible in one component, simpler implementation |
+
+## Context
+
+- Always provide rollback logic in `onError`
+- Cancel queries before optimistic update to prevent race conditions
+- Call `invalidateQueries` in `onSettled` to sync with server truth
+- For forms, consider if validation should block optimistic display
+- Test error scenarios to verify rollback works correctly
diff --git a/.agents/skills/tanstack-query-best-practices/rules/network-mode.md b/.agents/skills/tanstack-query-best-practices/rules/network-mode.md
new file mode 100644
index 0000000..02217af
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/network-mode.md
@@ -0,0 +1,179 @@
+# network-mode: Configure Network Mode for Offline Support
+
+## Priority: LOW
+
+## Explanation
+
+TanStack Query's `networkMode` controls how queries and mutations behave when there's no network connection. Configure it based on your app's offline requirements: always fetch, pause when offline, or work entirely offline.
+
+## Bad Example
+
+```tsx
+// Not considering offline behavior
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  // Default networkMode: 'online'
+  // Query pauses with no feedback when offline
+})
+
+// User goes offline, sees stale data with no indication
+// Mutations silently queue with no UI feedback
+```
+
+## Good Example: Default Online Mode with Offline UI
+
+```tsx
+// Show clear offline state to users
+function TodoList() {
+  const { data, fetchStatus, status } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    networkMode: 'online',  // Default - pauses when offline
+  })
+
+  // fetchStatus: 'fetching' | 'paused' | 'idle'
+  // 'paused' means waiting for network
+
+  return (
+    <div>
+      {fetchStatus === 'paused' && (
+        <Banner>You're offline. Showing cached data.</Banner>
+      )}
+      <TodoItems todos={data} />
+    </div>
+  )
+}
+```
+
+## Good Example: Always Mode for Offline-First
+
+```tsx
+// App works offline with local data
+const { data, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    // Try network first
+    try {
+      const todos = await fetchTodosFromServer()
+      await saveToLocalDB(todos)  // Sync to local
+      return todos
+    } catch (e) {
+      // Fall back to local data
+      return getFromLocalDB()
+    }
+  },
+  networkMode: 'always',  // Always runs queryFn, even offline
+})
+
+// Or set globally
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      networkMode: 'always',
+    },
+    mutations: {
+      networkMode: 'always',
+    },
+  },
+})
+```
+
+## Good Example: Offline-First Mode
+
+```tsx
+// Only fetch when online, but don't fail when offline
+const { data } = useQuery({
+  queryKey: ['user-preferences'],
+  queryFn: fetchPreferences,
+  networkMode: 'offlineFirst',
+  // Runs queryFn once, then waits for network if it fails
+  // Good for: data that's useful to attempt offline
+})
+```
+
+## Good Example: Mutation Offline Queue
+
+```tsx
+function TodoApp() {
+  const queryClient = useQueryClient()
+
+  const addTodo = useMutation({
+    mutationFn: createTodo,
+    networkMode: 'online',  // Pauses when offline
+    onMutate: async (newTodo) => {
+      // Optimistic update works offline
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+      const previous = queryClient.getQueryData(['todos'])
+      queryClient.setQueryData(['todos'], (old: Todo[]) => [...old, newTodo])
+      return { previous }
+    },
+    onError: (err, newTodo, context) => {
+      queryClient.setQueryData(['todos'], context?.previous)
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  // Track paused mutations
+  const pendingMutations = useMutationState({
+    filters: { status: 'pending' },
+  })
+
+  const pausedMutations = pendingMutations.filter(
+    m => m.state.isPaused
+  )
+
+  return (
+    <div>
+      {pausedMutations.length > 0 && (
+        <Banner>
+          {pausedMutations.length} changes waiting to sync
+        </Banner>
+      )}
+      <TodoList />
+    </div>
+  )
+}
+```
+
+## Network Mode Comparison
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `'online'` (default) | Pauses when offline, resumes when online | Most apps, show offline state |
+| `'always'` | Always runs queryFn regardless of network | Offline-first apps, local-only data |
+| `'offlineFirst'` | Tries once, then waits for network if fails | Best-effort offline |
+
+## Good Example: Online Status Detection
+
+```tsx
+import { onlineManager } from '@tanstack/react-query'
+
+// React to online/offline changes
+function NetworkStatus() {
+  const isOnline = useSyncExternalStore(
+    onlineManager.subscribe,
+    () => onlineManager.isOnline(),
+  )
+
+  return (
+    <div className={isOnline ? 'online' : 'offline'}>
+      {isOnline ? 'Connected' : 'Offline'}
+    </div>
+  )
+}
+
+// Manually override online detection (for testing)
+onlineManager.setOnline(false)
+```
+
+## Context
+
+- Default `'online'` mode is best for most apps
+- `fetchStatus: 'paused'` indicates waiting for network
+- Mutations queue automatically and retry when back online
+- Use `onlineManager` to detect and control online state
+- Combine with optimistic updates for seamless offline UX
+- Consider service workers for true offline support
diff --git a/.agents/skills/tanstack-query-best-practices/rules/parallel-use-queries.md b/.agents/skills/tanstack-query-best-practices/rules/parallel-use-queries.md
new file mode 100644
index 0000000..291dc31
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/parallel-use-queries.md
@@ -0,0 +1,152 @@
+# parallel-use-queries: Use useQueries for Dynamic Parallel Queries
+
+## Priority: MEDIUM
+
+## Explanation
+
+When you need to fetch multiple queries in parallel where the number or identity of queries is dynamic (e.g., fetching details for a list of IDs), use `useQueries`. It handles parallel execution and returns an array of query results.
+
+## Bad Example
+
+```tsx
+// Sequential fetching with useEffect - waterfall
+function UserProfiles({ userIds }: { userIds: string[] }) {
+  const [users, setUsers] = useState<User[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    async function fetchAll() {
+      const results = []
+      for (const id of userIds) {
+        const user = await fetchUser(id)  // Sequential!
+        results.push(user)
+      }
+      setUsers(results)
+      setLoading(false)
+    }
+    fetchAll()
+  }, [userIds])
+
+  // N requests run one after another
+}
+
+// Multiple useQuery calls - breaks rules of hooks
+function UserProfiles({ userIds }: { userIds: string[] }) {
+  // Can't call hooks in a loop!
+  const queries = userIds.map(id => useQuery({
+    queryKey: ['user', id],
+    queryFn: () => fetchUser(id),
+  }))
+}
+```
+
+## Good Example
+
+```tsx
+import { useQueries } from '@tanstack/react-query'
+
+function UserProfiles({ userIds }: { userIds: string[] }) {
+  const userQueries = useQueries({
+    queries: userIds.map(id => ({
+      queryKey: ['users', id],
+      queryFn: () => fetchUser(id),
+      staleTime: 5 * 60 * 1000,
+    })),
+  })
+
+  const isLoading = userQueries.some(q => q.isLoading)
+  const isError = userQueries.some(q => q.isError)
+  const users = userQueries.map(q => q.data).filter(Boolean)
+
+  if (isLoading) return <Loading />
+  if (isError) return <Error />
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Good Example: With Combine Option
+
+```tsx
+function UserProfiles({ userIds }: { userIds: string[] }) {
+  const { data: users, isPending } = useQueries({
+    queries: userIds.map(id => ({
+      queryKey: ['users', id],
+      queryFn: () => fetchUser(id),
+    })),
+    // Combine results into single value
+    combine: (results) => ({
+      data: results.map(r => r.data).filter(Boolean),
+      isPending: results.some(r => r.isPending),
+      isError: results.some(r => r.isError),
+    }),
+  })
+
+  if (isPending) return <Loading />
+
+  return <UserList users={users} />
+}
+```
+
+## Good Example: Dependent Parallel Queries
+
+```tsx
+function PostsWithAuthors({ postIds }: { postIds: string[] }) {
+  // First: fetch all posts in parallel
+  const postQueries = useQueries({
+    queries: postIds.map(id => ({
+      queryKey: ['posts', id],
+      queryFn: () => fetchPost(id),
+    })),
+  })
+
+  const posts = postQueries.map(q => q.data).filter(Boolean)
+  const authorIds = [...new Set(posts.map(p => p.authorId))]
+
+  // Then: fetch all unique authors in parallel
+  const authorQueries = useQueries({
+    queries: authorIds.map(id => ({
+      queryKey: ['users', id],
+      queryFn: () => fetchUser(id),
+      enabled: posts.length > 0,  // Wait for posts
+    })),
+  })
+
+  // Combine data...
+}
+```
+
+## Good Example: With Suspense
+
+```tsx
+import { useSuspenseQueries } from '@tanstack/react-query'
+
+function UserProfiles({ userIds }: { userIds: string[] }) {
+  const userQueries = useSuspenseQueries({
+    queries: userIds.map(id => ({
+      queryKey: ['users', id],
+      queryFn: () => fetchUser(id),
+    })),
+  })
+
+  // All data guaranteed - no loading states needed
+  const users = userQueries.map(q => q.data)
+
+  return <UserList users={users} />
+}
+```
+
+## Context
+
+- Queries run in parallel, not sequentially
+- Each query is cached independently
+- Use `combine` to transform results array into single value
+- Empty queries array is valid (returns empty results)
+- Pairs well with `useSuspenseQueries` for guaranteed data
+- Individual query options (staleTime, etc.) apply per-query
diff --git a/.agents/skills/tanstack-query-best-practices/rules/perf-select-transform.md b/.agents/skills/tanstack-query-best-practices/rules/perf-select-transform.md
new file mode 100644
index 0000000..3fa6921
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/perf-select-transform.md
@@ -0,0 +1,144 @@
+# perf-select-transform: Use Select to Transform and Filter Data
+
+## Priority: LOW
+
+## Explanation
+
+The `select` option transforms query data before it reaches your component. Use it for filtering, sorting, or deriving data. Benefits include memoization (re-runs only when data changes) and reduced component re-renders.
+
+## Bad Example
+
+```tsx
+// Transforming in component - runs on every render
+function CompletedTodos() {
+  const { data: todos } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  // This filtering runs on every render
+  const completedTodos = todos?.filter(todo => todo.completed) ?? []
+  const sortedTodos = [...completedTodos].sort((a, b) =>
+    new Date(b.completedAt).getTime() - new Date(a.completedAt).getTime()
+  )
+
+  return <TodoList todos={sortedTodos} />
+}
+```
+
+## Good Example
+
+```tsx
+// Using select - runs only when data changes
+function CompletedTodos() {
+  const { data: completedTodos } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: (todos) =>
+      todos
+        .filter(todo => todo.completed)
+        .sort((a, b) =>
+          new Date(b.completedAt).getTime() - new Date(a.completedAt).getTime()
+        ),
+  })
+
+  return <TodoList todos={completedTodos ?? []} />
+}
+```
+
+## Good Example: Selecting Specific Fields
+
+```tsx
+// Derive computed values
+function TodoStats() {
+  const { data: stats } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: (todos) => ({
+      total: todos.length,
+      completed: todos.filter(t => t.completed).length,
+      pending: todos.filter(t => !t.completed).length,
+      completionRate: todos.length
+        ? (todos.filter(t => t.completed).length / todos.length) * 100
+        : 0,
+    }),
+  })
+
+  return (
+    <div>
+      <span>{stats?.completed} / {stats?.total} completed</span>
+      <span>({stats?.completionRate.toFixed(1)}%)</span>
+    </div>
+  )
+}
+```
+
+## Good Example: Stable Select with useCallback
+
+```tsx
+// When select depends on external values, stabilize with useCallback
+function FilteredTodos({ status }: { status: 'all' | 'active' | 'completed' }) {
+  const selectTodos = useCallback(
+    (todos: Todo[]) => {
+      switch (status) {
+        case 'active':
+          return todos.filter(t => !t.completed)
+        case 'completed':
+          return todos.filter(t => t.completed)
+        default:
+          return todos
+      }
+    },
+    [status]
+  )
+
+  const { data: filteredTodos } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: selectTodos,
+  })
+
+  return <TodoList todos={filteredTodos ?? []} />
+}
+```
+
+## Good Example: Picking Single Item from List
+
+```tsx
+// Select single item from cached list
+function useTodoById(id: number) {
+  return useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: (todos) => todos.find(todo => todo.id === id),
+  })
+}
+
+// Usage - shares cache with list query
+function TodoDetail({ id }: { id: number }) {
+  const { data: todo } = useTodoById(id)
+
+  if (!todo) return <div>Todo not found</div>
+  return <div>{todo.title}</div>
+}
+```
+
+## When to Use Select
+
+| Scenario | Use Select? |
+|----------|-------------|
+| Filtering list data | Yes |
+| Sorting data | Yes |
+| Computing derived values | Yes |
+| Picking single item from list | Yes |
+| Heavy transformations | Yes (memoized) |
+| Simple data pass-through | No |
+| Transformation needs external state | Yes, with useCallback |
+
+## Context
+
+- `select` leverages structural sharing - only re-runs when data actually changes
+- Original query data stays cached; transformation applies to consumer
+- Multiple components can use different `select` on the same query
+- Avoid unstable function references - use `useCallback` when needed
+- For complex transformations, consider useMemo in component instead if readability suffers
diff --git a/.agents/skills/tanstack-query-best-practices/rules/persist-queries.md b/.agents/skills/tanstack-query-best-practices/rules/persist-queries.md
new file mode 100644
index 0000000..282adaf
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/persist-queries.md
@@ -0,0 +1,194 @@
+# persist-queries: Configure Query Persistence for Offline Support
+
+## Priority: LOW
+
+## Explanation
+
+TanStack Query can persist the cache to storage (localStorage, IndexedDB, AsyncStorage) and restore it on app load. This enables offline support and faster startup by eliminating initial loading states.
+
+## Bad Example
+
+```tsx
+// No persistence - always starts fresh
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+    </QueryClientProvider>
+  )
+}
+
+// User refreshes page:
+// 1. Empty cache
+// 2. Loading spinners everywhere
+// 3. Refetch all data
+// Poor offline experience
+```
+
+## Good Example: Basic Persistence with localStorage
+
+```tsx
+import { QueryClient } from '@tanstack/react-query'
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 1000 * 60 * 60 * 24,  // 24 hours - keep cache longer for persistence
+      staleTime: 1000 * 60 * 5,     // 5 minutes
+    },
+  },
+})
+
+const persister = createSyncStoragePersister({
+  storage: window.localStorage,
+  key: 'REACT_QUERY_CACHE',
+})
+
+function App() {
+  return (
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{
+        persister,
+        maxAge: 1000 * 60 * 60 * 24,  // 24 hours max
+      }}
+    >
+      <MyApp />
+    </PersistQueryClientProvider>
+  )
+}
+```
+
+## Good Example: Async Persistence with IndexedDB
+
+```tsx
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
+import { get, set, del } from 'idb-keyval'
+
+const persister = createAsyncStoragePersister({
+  storage: {
+    getItem: async (key) => await get(key),
+    setItem: async (key, value) => await set(key, value),
+    removeItem: async (key) => await del(key),
+  },
+  key: 'REACT_QUERY_CACHE',
+})
+
+function App() {
+  return (
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{
+        persister,
+        maxAge: 1000 * 60 * 60 * 24 * 7,  // 7 days
+        buster: APP_VERSION,  // Bust cache on app updates
+      }}
+    >
+      <MyApp />
+    </PersistQueryClientProvider>
+  )
+}
+```
+
+## Good Example: Selective Persistence
+
+```tsx
+import { persistQueryClient } from '@tanstack/react-query-persist-client'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 1000 * 60 * 60 * 24,
+    },
+  },
+})
+
+// Only persist certain queries
+persistQueryClient({
+  queryClient,
+  persister,
+  dehydrateOptions: {
+    shouldDehydrateQuery: (query) => {
+      // Don't persist user-specific sensitive data
+      if (query.queryKey[0] === 'user-session') return false
+      // Don't persist real-time data
+      if (query.queryKey[0] === 'notifications') return false
+      // Don't persist failed queries
+      if (query.state.status !== 'success') return false
+      // Persist everything else
+      return true
+    },
+  },
+})
+```
+
+## Good Example: React Native with AsyncStorage
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
+
+const persister = createAsyncStoragePersister({
+  storage: AsyncStorage,
+  key: 'app-query-cache',
+})
+
+// Usage is the same as web
+```
+
+## Good Example: Handling Restoration Loading
+
+```tsx
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
+
+function App() {
+  return (
+    <PersistQueryClientProvider
+      client={queryClient}
+      persistOptions={{ persister }}
+      onSuccess={() => {
+        // Cache restored successfully
+        console.log('Cache restored')
+      }}
+    >
+      {/* Show loading while restoring */}
+      <PersistQueryClientProvider.Consumer>
+        {({ isRestoring }) =>
+          isRestoring ? <SplashScreen /> : <MainApp />
+        }
+      </PersistQueryClientProvider.Consumer>
+    </PersistQueryClientProvider>
+  )
+}
+
+// Or use the hook
+function MainApp() {
+  const { isRestoring } = usePersistQueryClientRestore()
+
+  if (isRestoring) return <SplashScreen />
+  return <App />
+}
+```
+
+## Persistence Configuration
+
+| Option | Purpose |
+|--------|---------|
+| `maxAge` | Maximum cache age before considered invalid |
+| `buster` | String to invalidate cache (use app version) |
+| `dehydrateOptions.shouldDehydrateQuery` | Filter which queries to persist |
+| `hydrateOptions.shouldHydrate` | Filter which queries to restore |
+
+## Context
+
+- Requires `@tanstack/react-query-persist-client` package
+- Set `gcTime` higher than default (5 min) for persistence to be useful
+- Use `buster` option to invalidate cache on app updates
+- Don't persist sensitive data or real-time data
+- IndexedDB is better than localStorage for large caches
+- Restored data is still subject to staleTime checks
+- Works well with `networkMode: 'offlineFirst'`
diff --git a/.agents/skills/tanstack-query-best-practices/rules/pf-intent-prefetch.md b/.agents/skills/tanstack-query-best-practices/rules/pf-intent-prefetch.md
new file mode 100644
index 0000000..d742311
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/pf-intent-prefetch.md
@@ -0,0 +1,143 @@
+# pf-intent-prefetch: Prefetch on User Intent (Hover, Focus)
+
+## Priority: MEDIUM
+
+## Explanation
+
+Prefetch data when users show intent to navigate (hover, focus) rather than waiting for click. This eliminates perceived loading time for likely next actions.
+
+## Bad Example
+
+```tsx
+// No prefetching - data fetches on click
+function PostList({ posts }: { posts: Post[] }) {
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>
+          <Link to={`/posts/${post.id}`}>
+            {post.title}
+          </Link>
+          {/* User clicks, waits for data to load */}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Good Example
+
+```tsx
+import { useQueryClient } from '@tanstack/react-query'
+import { postQueries } from '@/lib/queries'
+
+function PostList({ posts }: { posts: Post[] }) {
+  const queryClient = useQueryClient()
+
+  const handlePrefetch = (postId: number) => {
+    queryClient.prefetchQuery({
+      ...postQueries.detail(postId),
+      staleTime: 60 * 1000,  // Consider fresh for 1 minute
+    })
+  }
+
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>
+          <Link
+            to={`/posts/${post.id}`}
+            onMouseEnter={() => handlePrefetch(post.id)}
+            onFocus={() => handlePrefetch(post.id)}
+          >
+            {post.title}
+          </Link>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Good Example: With TanStack Router
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// TanStack Router has built-in prefetching
+function PostList({ posts }: { posts: Post[] }) {
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>
+          <Link
+            to="/posts/$postId"
+            params={{ postId: post.id }}
+            preload="intent"  // Prefetch on hover/focus
+          >
+            {post.title}
+          </Link>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// Or set as router default
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  defaultPreloadDelay: 100,  // Wait 100ms before prefetching
+})
+```
+
+## Good Example: Prefetch with Delay
+
+```tsx
+function PostLink({ post }: { post: Post }) {
+  const queryClient = useQueryClient()
+  const timeoutRef = useRef<NodeJS.Timeout>()
+
+  const handleMouseEnter = () => {
+    // Delay prefetch to avoid unnecessary requests on quick mouse movements
+    timeoutRef.current = setTimeout(() => {
+      queryClient.prefetchQuery(postQueries.detail(post.id))
+    }, 100)
+  }
+
+  const handleMouseLeave = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+    }
+  }
+
+  return (
+    <Link
+      to={`/posts/${post.id}`}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+    >
+      {post.title}
+    </Link>
+  )
+}
+```
+
+## Prefetch Triggers
+
+| Trigger | When to Use |
+|---------|-------------|
+| `onMouseEnter` | Desktop, links/buttons user will likely click |
+| `onFocus` | Keyboard navigation, accessibility |
+| `onTouchStart` | Mobile, before navigation |
+| Component mount | Likely next pages, wizard steps |
+| Intersection Observer | Below-fold content |
+
+## Context
+
+- Set appropriate `staleTime` when prefetching to avoid immediate refetch
+- Consider mobile where hover isn't available
+- Don't prefetch everything - focus on likely paths
+- Prefetched data uses `gcTime` for retention
+- Watch network tab to verify prefetch timing
diff --git a/.agents/skills/tanstack-query-best-practices/rules/qk-array-structure.md b/.agents/skills/tanstack-query-best-practices/rules/qk-array-structure.md
new file mode 100644
index 0000000..70364c0
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/qk-array-structure.md
@@ -0,0 +1,50 @@
+# qk-array-structure: Always Use Arrays for Query Keys
+
+## Priority: CRITICAL
+
+## Explanation
+
+Query keys must always be arrays at the top level. This enables proper caching, invalidation matching, and query deduplication. Using non-array keys will cause unexpected behavior and cache misses.
+
+## Bad Example
+
+```tsx
+// Never use strings or non-array types as query keys
+const { data } = useQuery({
+  queryKey: 'todos',  // Wrong: string instead of array
+  queryFn: fetchTodos,
+})
+
+const { data: user } = useQuery({
+  queryKey: { id: 1, type: 'user' },  // Wrong: object instead of array
+  queryFn: fetchUser,
+})
+```
+
+## Good Example
+
+```tsx
+// Always use arrays for query keys
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+const { data: user } = useQuery({
+  queryKey: ['user', 1],
+  queryFn: () => fetchUser(1),
+})
+
+// Complex keys with objects inside arrays are fine
+const { data: filteredTodos } = useQuery({
+  queryKey: ['todos', { status: 'done', page: 1 }],
+  queryFn: () => fetchTodos({ status: 'done', page: 1 }),
+})
+```
+
+## Context
+
+- Always applicable when defining query keys
+- Arrays enable prefix-based invalidation (e.g., `invalidateQueries({ queryKey: ['todos'] })` matches all todo queries)
+- Object property order inside arrays doesn't matter for matching
+- Array element order does matter: `['todos', 1]` !== `['1', 'todos']`
diff --git a/.agents/skills/tanstack-query-best-practices/rules/qk-factory-pattern.md b/.agents/skills/tanstack-query-best-practices/rules/qk-factory-pattern.md
new file mode 100644
index 0000000..a358c4f
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/qk-factory-pattern.md
@@ -0,0 +1,102 @@
+# qk-factory-pattern: Use Query Key Factories for Complex Applications
+
+## Priority: CRITICAL
+
+## Explanation
+
+For applications with many queries, centralize query key definitions in factory functions. This ensures consistency, enables autocomplete, prevents typos, and makes refactoring safer. Query key factories are the recommended pattern for production applications.
+
+## Bad Example
+
+```tsx
+// Scattered, inconsistent key definitions across files
+// file: components/TodoList.tsx
+const { data } = useQuery({
+  queryKey: ['todos', 'list'],
+  queryFn: fetchTodos,
+})
+
+// file: components/TodoDetail.tsx
+const { data } = useQuery({
+  queryKey: ['todo', id],  // Inconsistent: 'todo' vs 'todos'
+  queryFn: () => fetchTodo(id),
+})
+
+// file: components/TodoComments.tsx
+const { data } = useQuery({
+  queryKey: ['todoComments', todoId],  // Different naming convention
+  queryFn: () => fetchComments(todoId),
+})
+
+// Invalidation is error-prone
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // Misses 'todo' and 'todoComments'
+```
+
+## Good Example
+
+```tsx
+// file: lib/query-keys.ts
+export const todoKeys = {
+  all: ['todos'] as const,
+  lists: () => [...todoKeys.all, 'list'] as const,
+  list: (filters: TodoFilters) => [...todoKeys.lists(), filters] as const,
+  details: () => [...todoKeys.all, 'detail'] as const,
+  detail: (id: number) => [...todoKeys.details(), id] as const,
+  comments: (id: number) => [...todoKeys.detail(id), 'comments'] as const,
+}
+
+export const userKeys = {
+  all: ['users'] as const,
+  detail: (id: string) => [...userKeys.all, id] as const,
+  posts: (id: string) => [...userKeys.detail(id), 'posts'] as const,
+}
+
+// file: components/TodoList.tsx
+import { todoKeys } from '@/lib/query-keys'
+
+const { data } = useQuery({
+  queryKey: todoKeys.list({ status: 'active' }),
+  queryFn: () => fetchTodos({ status: 'active' }),
+})
+
+// file: components/TodoDetail.tsx
+const { data } = useQuery({
+  queryKey: todoKeys.detail(id),
+  queryFn: () => fetchTodo(id),
+})
+
+// Invalidation is type-safe and predictable
+queryClient.invalidateQueries({ queryKey: todoKeys.all })  // Invalidates everything
+queryClient.invalidateQueries({ queryKey: todoKeys.detail(5) })  // Specific todo + comments
+```
+
+## Query Options Factory Pattern
+
+```tsx
+// Even better: combine with queryOptions for full type safety
+import { queryOptions } from '@tanstack/react-query'
+
+export const todoQueries = {
+  all: () => queryOptions({
+    queryKey: todoKeys.all,
+    queryFn: fetchAllTodos,
+  }),
+  detail: (id: number) => queryOptions({
+    queryKey: todoKeys.detail(id),
+    queryFn: () => fetchTodo(id),
+    staleTime: 5 * 60 * 1000,
+  }),
+}
+
+// Usage
+const { data } = useQuery(todoQueries.detail(5))
+await queryClient.prefetchQuery(todoQueries.detail(5))
+```
+
+## Context
+
+- Essential for applications with 10+ different query types
+- Enables IDE autocomplete and typo prevention
+- Makes invalidation patterns discoverable
+- Pairs well with `queryOptions` for full type inference
+- Consider the `@lukemorales/query-key-factory` package for standardized implementation
diff --git a/.agents/skills/tanstack-query-best-practices/rules/qk-hierarchical-organization.md b/.agents/skills/tanstack-query-best-practices/rules/qk-hierarchical-organization.md
new file mode 100644
index 0000000..dd934e6
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/qk-hierarchical-organization.md
@@ -0,0 +1,76 @@
+# qk-hierarchical-organization: Organize Keys Hierarchically
+
+## Priority: CRITICAL
+
+## Explanation
+
+Structure query keys from general to specific: entity type first, then ID, then modifiers/filters. This enables efficient invalidation at any level of specificity and creates predictable cache organization.
+
+## Bad Example
+
+```tsx
+// Flat, inconsistent key structures
+const { data: todos } = useQuery({
+  queryKey: ['all-todos-list'],
+  queryFn: fetchTodos,
+})
+
+const { data: todo } = useQuery({
+  queryKey: ['single-todo-5'],
+  queryFn: () => fetchTodo(5),
+})
+
+const { data: comments } = useQuery({
+  queryKey: ['todo-5-comments'],
+  queryFn: () => fetchTodoComments(5),
+})
+
+// Can't easily invalidate all todo-related queries
+```
+
+## Good Example
+
+```tsx
+// Hierarchical: entity → id → sub-resource → filters
+const { data: todos } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+const { data: todo } = useQuery({
+  queryKey: ['todos', 5],
+  queryFn: () => fetchTodo(5),
+})
+
+const { data: comments } = useQuery({
+  queryKey: ['todos', 5, 'comments'],
+  queryFn: () => fetchTodoComments(5),
+})
+
+const { data: filteredTodos } = useQuery({
+  queryKey: ['todos', { status: 'done', page: 1 }],
+  queryFn: () => fetchTodos({ status: 'done', page: 1 }),
+})
+
+// Now we can invalidate at any level:
+queryClient.invalidateQueries({ queryKey: ['todos'] })        // All todos
+queryClient.invalidateQueries({ queryKey: ['todos', 5] })     // Todo 5 and its sub-resources
+queryClient.invalidateQueries({ queryKey: ['todos', 5, 'comments'] }) // Just comments
+```
+
+## Recommended Hierarchy Pattern
+
+```
+['entity']                              // List
+['entity', id]                          // Single item
+['entity', id, 'sub-resource']          // Related data
+['entity', { filters }]                 // Filtered list
+['entity', id, 'sub-resource', { filters }] // Filtered sub-resource
+```
+
+## Context
+
+- Essential for applications with related data
+- Enables efficient cache management
+- Works with prefix-based invalidation
+- Consider using query key factories (see `qk-factory-pattern`) for consistency
diff --git a/.agents/skills/tanstack-query-best-practices/rules/qk-include-dependencies.md b/.agents/skills/tanstack-query-best-practices/rules/qk-include-dependencies.md
new file mode 100644
index 0000000..dfaa0f4
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/qk-include-dependencies.md
@@ -0,0 +1,62 @@
+# qk-include-dependencies: Include All Variables the Query Depends On
+
+## Priority: CRITICAL
+
+## Explanation
+
+If your query function depends on a variable, that variable must be included in the query key. This ensures independent caching per variable combination and automatic refetching when dependencies change. Missing dependencies cause stale data bugs and cache collisions.
+
+## Bad Example
+
+```tsx
+function UserPosts({ userId }: { userId: string }) {
+  // Missing userId in query key - all users share the same cache!
+  const { data } = useQuery({
+    queryKey: ['posts'],
+    queryFn: () => fetchPostsByUser(userId),
+  })
+
+  return <PostList posts={data} />
+}
+
+function FilteredTodos({ status, page }: { status: string; page: number }) {
+  // Missing filter parameters - won't refetch when filters change
+  const { data } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetchTodos({ status, page }),
+  })
+
+  return <TodoList todos={data} />
+}
+```
+
+## Good Example
+
+```tsx
+function UserPosts({ userId }: { userId: string }) {
+  // userId included - each user has their own cache entry
+  const { data } = useQuery({
+    queryKey: ['posts', userId],
+    queryFn: () => fetchPostsByUser(userId),
+  })
+
+  return <PostList posts={data} />
+}
+
+function FilteredTodos({ status, page }: { status: string; page: number }) {
+  // All dependencies included - refetches when any change
+  const { data } = useQuery({
+    queryKey: ['todos', { status, page }],
+    queryFn: () => fetchTodos({ status, page }),
+  })
+
+  return <TodoList todos={data} />
+}
+```
+
+## Context
+
+- This is arguably the most important query key rule
+- Applies whenever query function uses external variables
+- Prevents subtle bugs where different contexts share cached data
+- Works in conjunction with staleTime - even with long staleTime, changing keys triggers new fetches
diff --git a/.agents/skills/tanstack-query-best-practices/rules/qk-serializable.md b/.agents/skills/tanstack-query-best-practices/rules/qk-serializable.md
new file mode 100644
index 0000000..0af9193
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/qk-serializable.md
@@ -0,0 +1,93 @@
+# qk-serializable: Ensure All Key Parts Are JSON-Serializable
+
+## Priority: CRITICAL
+
+## Explanation
+
+Query keys are hashed using JSON serialization for cache lookups. Non-serializable values (functions, class instances, symbols, circular references) break caching and cause unexpected behavior. All parts of your query key must be JSON-serializable.
+
+## Bad Example
+
+```tsx
+// Functions are not serializable
+const { data } = useQuery({
+  queryKey: ['todos', () => 'active'],  // Wrong: function in key
+  queryFn: fetchTodos,
+})
+
+// Class instances lose their prototype
+class Filter {
+  constructor(public status: string) {}
+  isActive() { return this.status === 'active' }
+}
+const filter = new Filter('active')
+const { data: todos } = useQuery({
+  queryKey: ['todos', filter],  // Wrong: class instance
+  queryFn: () => fetchTodos(filter),
+})
+
+// Dates are technically serializable but become strings
+const { data: events } = useQuery({
+  queryKey: ['events', new Date()],  // Problematic: new Date() each render
+  queryFn: () => fetchEvents(date),
+})
+
+// Symbols are not serializable
+const { data: settings } = useQuery({
+  queryKey: ['settings', Symbol('user')],  // Wrong: symbol
+  queryFn: fetchSettings,
+})
+```
+
+## Good Example
+
+```tsx
+// Use primitive values and plain objects
+const { data } = useQuery({
+  queryKey: ['todos', 'active'],
+  queryFn: fetchTodos,
+})
+
+// Plain objects are fine
+const filters = { status: 'active', priority: 'high' }
+const { data: todos } = useQuery({
+  queryKey: ['todos', filters],
+  queryFn: () => fetchTodos(filters),
+})
+
+// For dates, use stable string representations
+const dateKey = date.toISOString().split('T')[0]  // '2024-01-15'
+const { data: events } = useQuery({
+  queryKey: ['events', dateKey],
+  queryFn: () => fetchEvents(date),
+})
+
+// Arrays of primitives work correctly
+const { data: users } = useQuery({
+  queryKey: ['users', { ids: [1, 2, 3] }],
+  queryFn: () => fetchUsers([1, 2, 3]),
+})
+```
+
+## Serializable Types
+
+**Safe to use:**
+- Strings, numbers, booleans, null
+- Plain objects (no prototype methods)
+- Arrays of serializable values
+- undefined (stripped but handled)
+
+**Avoid:**
+- Functions
+- Class instances
+- Symbols
+- Date objects (use ISO strings instead)
+- Map/Set (use arrays/objects instead)
+- Circular references
+
+## Context
+
+- TanStack Query uses deterministic JSON hashing
+- Object property order doesn't matter: `{ a: 1, b: 2 }` equals `{ b: 2, a: 1 }`
+- Keys with `undefined` properties are normalized: `{ a: 1, b: undefined }` equals `{ a: 1 }`
+- Test serialization: `JSON.stringify(queryKey)` should work without errors
diff --git a/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md b/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md
new file mode 100644
index 0000000..5ec3f8c
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md
@@ -0,0 +1,171 @@
+# query-cancellation: Implement Query Cancellation Properly
+
+## Priority: MEDIUM
+
+## Explanation
+
+TanStack Query provides an `AbortSignal` to cancel in-flight requests when queries become stale or components unmount. Pass this signal to your fetch calls to prevent memory leaks and wasted bandwidth.
+
+## Bad Example
+
+```tsx
+// Not using abort signal - requests complete even when unnecessary
+const { data } = useQuery({
+  queryKey: ['search', searchTerm],
+  queryFn: async () => {
+    // User types fast: "a", "ab", "abc"
+    // Three requests fire, all complete, wasting bandwidth
+    const response = await fetch(`/api/search?q=${searchTerm}`)
+    return response.json()
+  },
+})
+
+// Component unmounts but request keeps running
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: async () => {
+      const response = await fetch(`/api/users/${userId}`)
+      return response.json()  // Completes even if user navigated away
+    },
+  })
+}
+```
+
+## Good Example: Using AbortSignal with Fetch
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['search', searchTerm],
+  queryFn: async ({ signal }) => {
+    const response = await fetch(`/api/search?q=${searchTerm}`, {
+      signal,  // Pass abort signal to fetch
+    })
+    return response.json()
+  },
+})
+
+// Now when user types "a", "ab", "abc" quickly:
+// - "a" request is cancelled when "ab" starts
+// - "ab" request is cancelled when "abc" starts
+// - Only "abc" completes
+```
+
+## Good Example: With Axios
+
+```tsx
+import axios from 'axios'
+
+const { data } = useQuery({
+  queryKey: ['users', userId],
+  queryFn: async ({ signal }) => {
+    const response = await axios.get(`/api/users/${userId}`, {
+      signal,  // Axios supports AbortSignal
+    })
+    return response.data
+  },
+})
+```
+
+## Good Example: Manual Cancellation
+
+```tsx
+function SearchResults() {
+  const queryClient = useQueryClient()
+  const [searchTerm, setSearchTerm] = useState('')
+
+  const { data } = useQuery({
+    queryKey: ['search', searchTerm],
+    queryFn: async ({ signal }) => {
+      const response = await fetch(`/api/search?q=${searchTerm}`, { signal })
+      return response.json()
+    },
+    enabled: searchTerm.length > 0,
+  })
+
+  // Cancel all search queries manually
+  const handleClear = () => {
+    queryClient.cancelQueries({ queryKey: ['search'] })
+    setSearchTerm('')
+  }
+
+  return (
+    <div>
+      <input
+        value={searchTerm}
+        onChange={(e) => setSearchTerm(e.target.value)}
+      />
+      <button onClick={handleClear}>Clear</button>
+      <Results data={data} />
+    </div>
+  )
+}
+```
+
+## Good Example: In Mutations (Before Optimistic Update)
+
+```tsx
+const updateTodo = useMutation({
+  mutationFn: (todo: Todo) => api.updateTodo(todo),
+  onMutate: async (newTodo) => {
+    // Cancel outgoing queries to prevent overwriting optimistic update
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+
+    // Proceed with optimistic update...
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) => /* ... */)
+
+    return { previousTodos }
+  },
+})
+```
+
+## Good Example: Custom Cancellable Promise
+
+```tsx
+// For non-fetch APIs that need custom cancellation
+const { data } = useQuery({
+  queryKey: ['expensive-computation', params],
+  queryFn: ({ signal }) => {
+    return new Promise((resolve, reject) => {
+      // Check if already cancelled
+      if (signal.aborted) {
+        reject(new DOMException('Aborted', 'AbortError'))
+        return
+      }
+
+      const worker = new Worker('computation.js')
+      worker.postMessage(params)
+
+      worker.onmessage = (e) => resolve(e.data)
+      worker.onerror = (e) => reject(e)
+
+      // Listen for cancellation
+      signal.addEventListener('abort', () => {
+        worker.terminate()
+        reject(new DOMException('Aborted', 'AbortError'))
+      })
+    })
+  },
+})
+```
+
+## When Queries Are Cancelled
+
+| Scenario | Cancelled? |
+|----------|------------|
+| Query key changes | Yes |
+| Component unmounts | Yes |
+| `queryClient.cancelQueries()` called | Yes |
+| Refetch triggered | Previous request cancelled |
+| `enabled` becomes false | Yes |
+
+## Context
+
+- Always pass `signal` to fetch/axios for automatic cancellation
+- Cancelled queries don't trigger `onError` - they're silently dropped
+- Use `queryClient.cancelQueries()` before optimistic updates
+- AbortError is thrown when cancelled - handle if needed
+- Cancellation prevents wasted bandwidth and race conditions
+- Essential for search-as-you-type and fast navigation patterns
diff --git a/.agents/skills/tanstack-query-best-practices/rules/ssr-dehydration.md b/.agents/skills/tanstack-query-best-practices/rules/ssr-dehydration.md
new file mode 100644
index 0000000..456caea
--- /dev/null
+++ b/.agents/skills/tanstack-query-best-practices/rules/ssr-dehydration.md
@@ -0,0 +1,158 @@
+# ssr-dehydration: Use Dehydrate/Hydrate Pattern for SSR
+
+## Priority: MEDIUM
+
+## Explanation
+
+For server-side rendering, prefetch queries on the server, dehydrate the cache to a serializable format, send it to the client, and hydrate on the client. This prevents content flash and duplicate requests.
+
+## Bad Example
+
+```tsx
+// No SSR data passing - client refetches everything
+// server-side
+export async function getServerSideProps() {
+  const data = await fetchPosts()
+  return { props: { posts: data } }  // Bypasses React Query cache
+}
+
+// client-side
+function PostsPage({ posts }: { posts: Post[] }) {
+  // This doesn't benefit from the server fetch
+  const { data } = useQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+    // Will refetch on client, causing flash
+  })
+
+  return <PostList posts={data ?? posts} />  // Awkward fallback pattern
+}
+```
+
+## Good Example: Next.js App Router
+
+```tsx
+// app/posts/page.tsx
+import {
+  dehydrate,
+  HydrationBoundary,
+  QueryClient,
+} from '@tanstack/react-query'
+import { postQueries } from '@/lib/queries'
+
+export default async function PostsPage() {
+  const queryClient = new QueryClient()
+
+  await queryClient.prefetchQuery(postQueries.list())
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <PostList />
+    </HydrationBoundary>
+  )
+}
+
+// components/PostList.tsx
+'use client'
+
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { postQueries } from '@/lib/queries'
+
+export function PostList() {
+  const { data: posts } = useSuspenseQuery(postQueries.list())
+
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Good Example: TanStack Start/Router
+
+```tsx
+// routes/posts.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { postQueries } from '@/lib/queries'
+
+export const Route = createFileRoute('/posts')({
+  loader: async ({ context: { queryClient } }) => {
+    // Prefetch in route loader
+    await queryClient.ensureQueryData(postQueries.list())
+  },
+  component: PostsPage,
+})
+
+function PostsPage() {
+  const { data: posts } = useSuspenseQuery(postQueries.list())
+  return <PostList posts={posts} />
+}
+```
+
+## Good Example: Manual SSR Setup
+
+```tsx
+// server.tsx
+import { dehydrate, QueryClient } from '@tanstack/react-query'
+import { renderToString } from 'react-dom/server'
+
+export async function render(url: string) {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,  // Prevent immediate client refetch
+      },
+    },
+  })
+
+  // Prefetch required data
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: fetchPosts,
+  })
+
+  const dehydratedState = dehydrate(queryClient)
+
+  const html = renderToString(
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  )
+
+  // Serialize safely - JSON.stringify is XSS vulnerable
+  const serializedState = serialize(dehydratedState)
+
+  return `
+    <html>
+      <body>
+        <div id="app">${html}</div>
+        <script>window.__DEHYDRATED_STATE__ = ${serializedState}</script>
+      </body>
+    </html>
+  `
+}
+
+// client.tsx
+import { hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+hydrate(queryClient, window.__DEHYDRATED_STATE__)
+
+hydrateRoot(
+  document.getElementById('app'),
+  <QueryClientProvider client={queryClient}>
+    <App />
+  </QueryClientProvider>
+)
+```
+
+## Context
+
+- Create new QueryClient per request to prevent data sharing between users
+- Set `staleTime > 0` on server to prevent immediate client refetch
+- Use a safe serializer (not JSON.stringify) to prevent XSS
+- Failed queries aren't dehydrated by default; use `shouldDehydrateQuery` to override
+- `HydrationBoundary` can be nested for route-level prefetching
diff --git a/.agents/skills/tanstack-query/SKILL.md b/.agents/skills/tanstack-query/SKILL.md
new file mode 100644
index 0000000..1538eb4
--- /dev/null
+++ b/.agents/skills/tanstack-query/SKILL.md
@@ -0,0 +1,849 @@
+---
+name: tanstack-query
+description: Powerful asynchronous state management, server-state utilities, and data fetching for TS/JS, React, Vue, Solid, Svelte & Angular.
+---
+
+
+## Overview
+
+TanStack Query (formerly React Query) manages server state - data that lives on the server and needs to be fetched, cached, synchronized, and updated. It provides automatic caching, background refetching, stale-while-revalidate patterns, pagination, infinite scrolling, and optimistic updates out of the box.
+
+**Package:** `@tanstack/react-query`
+**Devtools:** `@tanstack/react-query-devtools`
+**Current Version:** v5
+
+## Installation
+
+```bash
+npm install @tanstack/react-query
+npm install -D @tanstack/react-query-devtools  # Optional
+```
+
+## Setup
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60, // 1 minute
+      gcTime: 1000 * 60 * 5, // 5 minutes (garbage collection)
+      retry: 3,
+      refetchOnWindowFocus: true,
+      refetchOnReconnect: true,
+    },
+  },
+})
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+## Core Concepts
+
+### Query Keys
+
+Query keys uniquely identify cached data. They must be serializable arrays:
+
+```tsx
+// Simple key
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// With variables (dependency array pattern)
+useQuery({ queryKey: ['todos', { status, page }], queryFn: fetchTodos })
+
+// Hierarchical keys for invalidation
+useQuery({ queryKey: ['todos', todoId], queryFn: () => fetchTodo(todoId) })
+useQuery({ queryKey: ['todos', todoId, 'comments'], queryFn: () => fetchComments(todoId) })
+
+// Invalidation matches prefixes:
+// queryClient.invalidateQueries({ queryKey: ['todos'] })
+// ^ Invalidates ALL queries starting with 'todos'
+```
+
+### Query Functions
+
+```tsx
+// Query function receives a QueryFunctionContext
+useQuery({
+  queryKey: ['todos', todoId],
+  queryFn: async ({ queryKey, signal, meta }) => {
+    const [_key, id] = queryKey
+    const response = await fetch(`/api/todos/${id}`, { signal })
+    if (!response.ok) throw new Error('Failed to fetch')
+    return response.json()
+  },
+})
+
+// Using the signal for automatic cancellation
+useQuery({
+  queryKey: ['todos'],
+  queryFn: async ({ signal }) => {
+    const response = await fetch('/api/todos', { signal })
+    return response.json()
+  },
+})
+```
+
+### queryOptions Helper
+
+Create reusable, type-safe query configurations:
+
+```tsx
+import { queryOptions } from '@tanstack/react-query'
+
+export const todosQueryOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000,
+})
+
+export const todoQueryOptions = (todoId: string) =>
+  queryOptions({
+    queryKey: ['todos', todoId],
+    queryFn: () => fetchTodo(todoId),
+    enabled: !!todoId,
+  })
+
+// Usage
+const { data } = useQuery(todosQueryOptions)
+const { data } = useSuspenseQuery(todoQueryOptions(id))
+await queryClient.prefetchQuery(todosQueryOptions)
+```
+
+## Queries (useQuery)
+
+### Basic Usage
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const {
+    data,
+    error,
+    isLoading,      // First load, no data yet
+    isFetching,     // Any fetch in progress (including background)
+    isError,
+    isSuccess,
+    isPending,      // No data yet (same as isLoading in most cases)
+    status,         // 'pending' | 'error' | 'success'
+    fetchStatus,    // 'fetching' | 'paused' | 'idle'
+    refetch,
+    isStale,
+    isPlaceholderData,
+    dataUpdatedAt,
+    errorUpdatedAt,
+  } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isLoading) return <Spinner />
+  if (isError) return <Error message={error.message} />
+  return <TodoList todos={data} />
+}
+```
+
+### Query Options
+
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+
+  // Freshness
+  staleTime: 5000,            // ms data stays fresh (default: 0)
+  gcTime: 300000,             // ms unused data stays in cache (default: 5 min)
+
+  // Refetching
+  refetchInterval: 10000,     // Poll every 10s
+  refetchIntervalInBackground: false, // Don't poll when tab hidden
+  refetchOnMount: true,       // Refetch on component mount if stale
+  refetchOnWindowFocus: true, // Refetch on window focus if stale
+  refetchOnReconnect: true,   // Refetch on network reconnect
+
+  // Retry
+  retry: 3,                   // Number of retries (or function)
+  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+
+  // Conditional
+  enabled: !!userId,          // Only run when truthy
+
+  // Initial/placeholder data
+  initialData: () => cachedData,
+  initialDataUpdatedAt: Date.now() - 10000,
+  placeholderData: (previousData) => previousData, // keepPreviousData pattern
+  placeholderData: initialTodos,
+
+  // Transform
+  select: (data) => data.filter(todo => !todo.done),
+
+  // Structural sharing (default: true)
+  structuralSharing: true,
+
+  // Network mode
+  networkMode: 'online', // 'online' | 'always' | 'offlineFirst'
+
+  // Meta (accessible in query function context)
+  meta: { purpose: 'user-facing' },
+})
+```
+
+## Mutations (useMutation)
+
+### Basic Usage
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) => {
+      return fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+      }).then(res => res.json())
+    },
+    // Lifecycle callbacks
+    onMutate: async (variables) => {
+      // Called before mutationFn
+      // Good for optimistic updates
+      return { previousTodos } // context for onError
+    },
+    onSuccess: (data, variables, context) => {
+      // Invalidate related queries
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+    onError: (error, variables, context) => {
+      // Rollback optimistic updates
+      queryClient.setQueryData(['todos'], context.previousTodos)
+    },
+    onSettled: (data, error, variables, context) => {
+      // Always runs (success or error)
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ title: 'New Todo' })}
+      disabled={mutation.isPending}
+    >
+      {mutation.isPending ? 'Adding...' : 'Add Todo'}
+    </button>
+  )
+}
+```
+
+### Mutation State
+
+```tsx
+const {
+  mutate,         // Fire-and-forget
+  mutateAsync,    // Returns promise
+  isPending,      // Mutation in progress
+  isError,
+  isSuccess,
+  isIdle,         // Not yet fired
+  data,           // Success response
+  error,          // Error object
+  reset,          // Reset state to idle
+  variables,      // Variables passed to mutate
+  status,         // 'idle' | 'pending' | 'error' | 'success'
+} = useMutation({ ... })
+```
+
+## Optimistic Updates
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // 1. Cancel outgoing refetches
+    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+
+    // 2. Snapshot previous value
+    const previousTodo = queryClient.getQueryData(['todos', newTodo.id])
+
+    // 3. Optimistically update
+    queryClient.setQueryData(['todos', newTodo.id], newTodo)
+
+    // 4. Return context for rollback
+    return { previousTodo }
+  },
+  onError: (err, newTodo, context) => {
+    // Rollback on error
+    queryClient.setQueryData(['todos', newTodo.id], context.previousTodo)
+  },
+  onSettled: () => {
+    // Always refetch to sync with server
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+### Optimistic Updates on Lists
+
+```tsx
+onMutate: async (newTodo) => {
+  await queryClient.cancelQueries({ queryKey: ['todos'] })
+  const previousTodos = queryClient.getQueryData(['todos'])
+
+  queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+
+  return { previousTodos }
+},
+onError: (err, newTodo, context) => {
+  queryClient.setQueryData(['todos'], context.previousTodos)
+},
+```
+
+## Query Invalidation
+
+```tsx
+const queryClient = useQueryClient()
+
+// Invalidate all queries
+queryClient.invalidateQueries()
+
+// Invalidate by prefix
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// Invalidate exact match
+queryClient.invalidateQueries({ queryKey: ['todos', 1], exact: true })
+
+// Invalidate with predicate
+queryClient.invalidateQueries({
+  predicate: (query) =>
+    query.queryKey[0] === 'todos' && query.queryKey[1]?.status === 'done',
+})
+
+// Invalidate and refetch immediately
+queryClient.refetchQueries({ queryKey: ['todos'] })
+
+// Remove from cache entirely
+queryClient.removeQueries({ queryKey: ['todos', 1] })
+
+// Reset to initial state
+queryClient.resetQueries({ queryKey: ['todos'] })
+```
+
+## Infinite Queries
+
+```tsx
+import { useInfiniteQuery } from '@tanstack/react-query'
+
+function InfiniteList() {
+  const {
+    data,
+    fetchNextPage,
+    fetchPreviousPage,
+    hasNextPage,
+    hasPreviousPage,
+    isFetchingNextPage,
+    isFetchingPreviousPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: async ({ pageParam }) => {
+      const res = await fetch(`/api/projects?cursor=${pageParam}`)
+      return res.json()
+    },
+    initialPageParam: 0,
+    getNextPageParam: (lastPage, allPages, lastPageParam) => {
+      return lastPage.nextCursor ?? undefined // undefined = no more pages
+    },
+    getPreviousPageParam: (firstPage, allPages, firstPageParam) => {
+      return firstPage.prevCursor ?? undefined
+    },
+    maxPages: 3, // Keep max 3 pages in cache (for performance)
+  })
+
+  return (
+    <div>
+      {data.pages.map((page) =>
+        page.items.map((item) => <Item key={item.id} item={item} />)
+      )}
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetchingNextPage}
+      >
+        {isFetchingNextPage ? 'Loading...' : hasNextPage ? 'Load More' : 'No more'}
+      </button>
+    </div>
+  )
+}
+```
+
+## Parallel Queries
+
+```tsx
+// Multiple independent queries run in parallel automatically
+function Dashboard() {
+  const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+  const projectsQuery = useQuery({ queryKey: ['projects'], queryFn: fetchProjects })
+
+  // Both fetch simultaneously
+}
+
+// Dynamic parallel queries with useQueries
+function UserProjects({ userIds }) {
+  const queries = useQueries({
+    queries: userIds.map((id) => ({
+      queryKey: ['user', id],
+      queryFn: () => fetchUser(id),
+    })),
+    combine: (results) => ({
+      data: results.map(r => r.data),
+      pending: results.some(r => r.isPending),
+    }),
+  })
+}
+```
+
+## Dependent Queries
+
+```tsx
+// Sequential queries using enabled
+function UserPosts({ userId }) {
+  const userQuery = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+  })
+
+  const postsQuery = useQuery({
+    queryKey: ['posts', userId],
+    queryFn: () => fetchPostsByUser(userId),
+    enabled: !!userQuery.data, // Only run when user is loaded
+  })
+}
+```
+
+## Paginated Queries
+
+```tsx
+function PaginatedList() {
+  const [page, setPage] = useState(1)
+
+  const { data, isPlaceholderData } = useQuery({
+    queryKey: ['todos', page],
+    queryFn: () => fetchTodos(page),
+    placeholderData: (previousData) => previousData, // Keep showing old data
+  })
+
+  return (
+    <div style={{ opacity: isPlaceholderData ? 0.5 : 1 }}>
+      {data.items.map(item => <Item key={item.id} item={item} />)}
+      <button
+        onClick={() => setPage(p => p + 1)}
+        disabled={isPlaceholderData || !data.hasMore}
+      >
+        Next
+      </button>
+    </div>
+  )
+}
+```
+
+## Suspense Integration
+
+```tsx
+import { useSuspenseQuery, useSuspenseInfiniteQuery } from '@tanstack/react-query'
+
+// Component will suspend until data is loaded
+function TodoList() {
+  const { data } = useSuspenseQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+  // data is guaranteed to be defined here
+  return <ul>{data.map(todo => <li key={todo.id}>{todo.title}</li>)}</ul>
+}
+
+// Wrap with Suspense boundary
+function App() {
+  return (
+    <ErrorBoundary fallback={<Error />}>
+      <Suspense fallback={<Loading />}>
+        <TodoList />
+      </Suspense>
+    </ErrorBoundary>
+  )
+}
+
+// Multiple suspense queries (fetch in parallel)
+function Dashboard() {
+  const [{ data: users }, { data: projects }] = useSuspenseQueries({
+    queries: [
+      { queryKey: ['users'], queryFn: fetchUsers },
+      { queryKey: ['projects'], queryFn: fetchProjects },
+    ],
+  })
+}
+```
+
+## Prefetching
+
+```tsx
+const queryClient = useQueryClient()
+
+// Prefetch on hover
+function TodoLink({ todoId }) {
+  const prefetch = () => {
+    queryClient.prefetchQuery({
+      queryKey: ['todo', todoId],
+      queryFn: () => fetchTodo(todoId),
+      staleTime: 5000, // Only prefetch if data older than 5s
+    })
+  }
+
+  return (
+    <Link to={`/todos/${todoId}`} onMouseEnter={prefetch}>
+      Todo {todoId}
+    </Link>
+  )
+}
+
+// Prefetch in route loader (TanStack Router integration)
+export const Route = createFileRoute('/todos/$todoId')({
+  loader: ({ context: { queryClient }, params: { todoId } }) =>
+    queryClient.ensureQueryData(todoQueryOptions(todoId)),
+})
+
+// Prefetch infinite queries
+queryClient.prefetchInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: fetchProjects,
+  initialPageParam: 0,
+  pages: 3, // Prefetch first 3 pages
+})
+```
+
+## SSR & Hydration
+
+### Server-Side Prefetching
+
+```tsx
+// Server component or loader
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+
+async function getServerSideProps() {
+  const queryClient = new QueryClient()
+
+  await queryClient.prefetchQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  return {
+    props: {
+      dehydratedState: dehydrate(queryClient),
+    },
+  }
+}
+
+function Page({ dehydratedState }) {
+  return (
+    <HydrationBoundary state={dehydratedState}>
+      <Todos />
+    </HydrationBoundary>
+  )
+}
+```
+
+### Streaming SSR (React Server Components)
+
+```tsx
+import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
+import { makeQueryClient } from './query-client'
+
+export default async function Page() {
+  const queryClient = makeQueryClient()
+
+  // Prefetch on server
+  await queryClient.prefetchQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <TodoList />
+    </HydrationBoundary>
+  )
+}
+```
+
+## QueryClient API
+
+```tsx
+const queryClient = useQueryClient()
+
+// Get cached data
+queryClient.getQueryData(['todos'])
+
+// Set cached data
+queryClient.setQueryData(['todos'], updatedTodos)
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+
+// Get query state
+queryClient.getQueryState(['todos'])
+
+// Check if fetching
+queryClient.isFetching({ queryKey: ['todos'] })
+queryClient.isMutating()
+
+// Cancel queries
+queryClient.cancelQueries({ queryKey: ['todos'] })
+
+// Invalidate (marks stale, refetches active)
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// Refetch (force refetch even if fresh)
+queryClient.refetchQueries({ queryKey: ['todos'] })
+
+// Remove from cache
+queryClient.removeQueries({ queryKey: ['todos'] })
+
+// Reset to initial state
+queryClient.resetQueries({ queryKey: ['todos'] })
+
+// Clear entire cache
+queryClient.clear()
+
+// Prefetch
+queryClient.prefetchQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+queryClient.ensureQueryData({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// Get/set defaults
+queryClient.setQueryDefaults(['todos'], { staleTime: 10000 })
+queryClient.getQueryDefaults(['todos'])
+queryClient.setMutationDefaults(['addTodo'], { mutationFn: addTodo })
+```
+
+## Testing
+
+```tsx
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false, // Don't retry in tests
+        gcTime: Infinity, // Prevent garbage collection during tests
+      },
+    },
+  })
+  return ({ children }) => (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  )
+}
+
+test('fetches todos', async () => {
+  const { result } = renderHook(() => useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  }), { wrapper: createWrapper() })
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data).toEqual(expectedTodos)
+})
+
+// Mock with setQueryData for component tests
+test('renders todos', () => {
+  const queryClient = new QueryClient()
+  queryClient.setQueryData(['todos'], mockTodos)
+
+  render(
+    <QueryClientProvider client={queryClient}>
+      <TodoList />
+    </QueryClientProvider>
+  )
+
+  expect(screen.getByText('Todo 1')).toBeInTheDocument()
+})
+```
+
+## TypeScript Patterns
+
+### Typing Query Functions
+
+```tsx
+interface Todo {
+  id: number
+  title: string
+  completed: boolean
+}
+
+// Type is inferred from queryFn return type
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async (): Promise<Todo[]> => {
+    const res = await fetch('/api/todos')
+    return res.json()
+  },
+})
+// data: Todo[] | undefined
+
+// With select
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  select: (data): string[] => data.map(t => t.title),
+})
+// data: string[] | undefined
+```
+
+### Typing Errors
+
+```tsx
+// Default error type is Error
+const { error } = useQuery<Todo[], AxiosError>({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+// Or register globally
+declare module '@tanstack/react-query' {
+  interface Register {
+    defaultError: AxiosError
+  }
+}
+```
+
+### Query Options Pattern (Recommended)
+
+```tsx
+import { queryOptions, infiniteQueryOptions } from '@tanstack/react-query'
+
+export const todosOptions = queryOptions({
+  queryKey: ['todos'] as const,
+  queryFn: fetchTodos,
+  staleTime: 5000,
+})
+
+export const todoOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['todos', id] as const,
+    queryFn: () => fetchTodo(id),
+    enabled: !!id,
+  })
+
+// Full type inference everywhere
+const { data } = useQuery(todosOptions)
+const { data } = useSuspenseQuery(todoOptions('123'))
+await queryClient.ensureQueryData(todosOptions)
+queryClient.invalidateQueries({ queryKey: todosOptions.queryKey })
+```
+
+## Advanced Patterns
+
+### Window Focus Refetching
+
+```tsx
+// Disable globally
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { refetchOnWindowFocus: false },
+  },
+})
+
+// Custom focus manager
+import { focusManager } from '@tanstack/react-query'
+
+// For React Native
+focusManager.setEventListener((handleFocus) => {
+  const subscription = AppState.addEventListener('change', (state) => {
+    handleFocus(state === 'active')
+  })
+  return () => subscription.remove()
+})
+```
+
+### Network Mode
+
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  // 'online' (default): only fetch when online
+  // 'always': always fetch (useful for local-first)
+  // 'offlineFirst': try fetch, use cache if offline
+  networkMode: 'offlineFirst',
+})
+```
+
+### Query Cancellation
+
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: async ({ signal }) => {
+    // signal is AbortSignal - automatically cancelled on unmount or key change
+    const res = await fetch('/api/todos', { signal })
+    return res.json()
+  },
+})
+
+// Manual cancellation
+queryClient.cancelQueries({ queryKey: ['todos'] })
+```
+
+### Persistence
+
+```tsx
+import { persistQueryClient } from '@tanstack/react-query-persist-client'
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+
+const persister = createSyncStoragePersister({
+  storage: window.localStorage,
+})
+
+persistQueryClient({
+  queryClient,
+  persister,
+  maxAge: 1000 * 60 * 60 * 24, // 24 hours
+})
+```
+
+## Best Practices
+
+1. **Use `queryOptions` helper** for type-safe, reusable query configurations
+2. **Structure query keys hierarchically** for granular invalidation
+3. **Set appropriate `staleTime`** - 0 means always refetch on mount (default), increase for less dynamic data
+4. **Use `placeholderData`** (not `initialData`) for keeping previous page data during pagination
+5. **Prefer `useSuspenseQuery`** when using Suspense boundaries for cleaner component code
+6. **Use `enabled`** for dependent queries, not conditional hook calls
+7. **Always invalidate after mutations** - don't rely solely on optimistic updates
+8. **Cancel queries in `onMutate`** before optimistic updates to prevent race conditions
+9. **Use `ensureQueryData`** in route loaders instead of `prefetchQuery` for immediate access
+10. **Set `retry: false` in tests** to avoid timeout issues
+11. **Don't destructure the query result** if you need to pass it around (breaks reactivity)
+12. **Use `select`** for derived data instead of transforming in the component
+13. **Keep query functions pure** - they should only fetch, not cause side effects
+14. **Use `gcTime: Infinity`** in tests to prevent cache cleanup during assertions
+
+## Common Pitfalls
+
+- Using `initialData` when you mean `placeholderData` (initialData counts as "fresh" data)
+- Not providing `initialPageParam` for infinite queries (required in v5)
+- Calling hooks conditionally (violates React rules)
+- Not cancelling queries before optimistic updates (race conditions)
+- Setting `staleTime` higher than `gcTime` (data gets garbage collected while "fresh")
+- Forgetting to wrap tests with `QueryClientProvider`
+- Using same `QueryClient` instance across tests (shared state)
+- Not awaiting `invalidateQueries` in mutation callbacks when order matters
diff --git a/.agents/skills/tanstack-router/SKILL.md b/.agents/skills/tanstack-router/SKILL.md
new file mode 100644
index 0000000..a4b817c
--- /dev/null
+++ b/.agents/skills/tanstack-router/SKILL.md
@@ -0,0 +1,734 @@
+---
+name: tanstack-router
+description: Type-safe routing for React and Solid applications with first-class search params, data loading, and seamless integration with the React ecosystem.
+---
+
+
+## Overview
+
+TanStack Router is a fully type-safe router for React (and Solid) applications. It provides file-based routing, first-class search parameter management, built-in data loading, code splitting, and deep TypeScript integration. It serves as the routing foundation for TanStack Start (the full-stack framework).
+
+**Package:** `@tanstack/react-router`
+**CLI:** `@tanstack/router-cli` or `@tanstack/router-plugin` (Vite/Rspack/Webpack)
+**Devtools:** `@tanstack/react-router-devtools`
+
+## Installation
+
+```bash
+npm install @tanstack/react-router
+# For file-based routing with Vite:
+npm install -D @tanstack/router-plugin
+# Or standalone CLI:
+npm install -D @tanstack/router-cli
+```
+
+## Core Concepts
+
+### Route Trees
+
+Routes are organized in a tree structure. The root route is the top-level layout, and child routes nest underneath.
+
+```tsx
+import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({
+  component: RootLayout,
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: HomePage,
+})
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: AboutPage,
+})
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
+const router = createRouter({ routeTree })
+```
+
+### File-Based Routing
+
+File-based routing automatically generates the route tree from your file structure. Configure with Vite plugin:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+
+export default defineConfig({
+  plugins: [
+    TanStackRouterVite(),
+    // ... other plugins
+  ],
+})
+```
+
+#### File Naming Conventions
+
+| File Pattern | Route Type | Example Path |
+|---|---|---|
+| `__root.tsx` | Root layout | N/A (wraps all) |
+| `index.tsx` | Index route | `/` |
+| `about.tsx` | Static route | `/about` |
+| `$postId.tsx` | Dynamic param | `/posts/$postId` |
+| `posts.tsx` | Layout route | `/posts/*` (layout) |
+| `posts/index.tsx` | Nested index | `/posts` |
+| `posts/$postId.tsx` | Nested dynamic | `/posts/123` |
+| `posts_.$postId.tsx` | Pathless layout | `/posts/123` (different layout) |
+| `_layout.tsx` | Pathless layout | N/A (groups routes) |
+| `_layout/dashboard.tsx` | Grouped route | `/dashboard` |
+| `$.tsx` | Splat/catch-all | `/*` |
+| `posts.$postId.edit.tsx` | Dot notation | `/posts/123/edit` |
+
+#### Special Prefixes
+- `_` prefix: Pathless routes (layout groups without URL segment)
+- `$` prefix: Dynamic path parameters
+- `(folder)` parentheses: Route groups (organizational, no URL impact)
+
+### Route Configuration
+
+Each route can define:
+
+```tsx
+// routes/posts.$postId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  // Validation for path params
+  params: {
+    parse: (params) => ({ postId: Number(params.postId) }),
+    stringify: (params) => ({ postId: String(params.postId) }),
+  },
+
+  // Search params validation
+  validateSearch: (search: Record<string, unknown>) => {
+    return {
+      page: Number(search.page ?? 1),
+      filter: (search.filter as string) || '',
+    }
+  },
+
+  // Data loading
+  loader: async ({ params, context, abortController }) => {
+    return fetchPost(params.postId)
+  },
+
+  // Loader dependencies (re-run loader when these change)
+  loaderDeps: ({ search }) => ({ page: search.page }),
+
+  // Stale time for cached loader data
+  staleTime: 5_000,
+
+  // Preloading
+  preloadStaleTime: 30_000,
+
+  // Error component
+  errorComponent: PostErrorComponent,
+
+  // Pending/loading component
+  pendingComponent: PostLoadingComponent,
+
+  // 404 component
+  notFoundComponent: PostNotFoundComponent,
+
+  // Before load hook (authentication, redirects)
+  beforeLoad: async ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+  },
+
+  // Head/meta management
+  head: () => ({
+    meta: [{ title: 'Post Details' }],
+  }),
+
+  // Component
+  component: PostComponent,
+})
+
+function PostComponent() {
+  const { postId } = Route.useParams()
+  const post = Route.useLoaderData()
+  const { page, filter } = Route.useSearch()
+
+  return <div>{post.title}</div>
+}
+```
+
+## Data Loading
+
+### Route Loaders
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loader: async ({ context }) => {
+    // Access router context (e.g., queryClient)
+    const posts = await context.queryClient.ensureQueryData({
+      queryKey: ['posts'],
+      queryFn: fetchPosts,
+    })
+    return { posts }
+  },
+  component: PostsComponent,
+})
+
+function PostsComponent() {
+  const { posts } = Route.useLoaderData()
+  // ...
+}
+```
+
+### Loader Dependencies
+
+Control when loaders re-execute:
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loaderDeps: ({ search: { page, filter } }) => ({ page, filter }),
+  loader: async ({ deps: { page, filter } }) => {
+    return fetchPosts({ page, filter })
+  },
+})
+```
+
+### Deferred Data Loading
+
+Stream non-critical data:
+
+```tsx
+import { Await, defer } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const criticalData = await fetchCriticalData()
+    const deferredData = defer(fetchSlowData())
+    return { criticalData, deferredData }
+  },
+  component: DashboardComponent,
+})
+
+function DashboardComponent() {
+  const { criticalData, deferredData } = Route.useLoaderData()
+
+  return (
+    <div>
+      <CriticalSection data={criticalData} />
+      <Suspense fallback={<Loading />}>
+        <Await promise={deferredData}>
+          {(data) => <SlowSection data={data} />}
+        </Await>
+      </Suspense>
+    </div>
+  )
+}
+```
+
+### Context-Based Data Loading
+
+Provide shared dependencies via router context:
+
+```tsx
+// Create router with context
+const router = createRouter({
+  routeTree,
+  context: {
+    queryClient,
+    auth: undefined!, // Will be provided by RouterProvider
+  },
+})
+
+// In root/app component
+function App() {
+  const auth = useAuth()
+  return <RouterProvider router={router} context={{ auth }} />
+}
+
+// In routes
+export const Route = createFileRoute('/protected')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.user) throw redirect({ to: '/login' })
+  },
+  loader: ({ context }) => {
+    return context.queryClient.ensureQueryData(userQueryOptions())
+  },
+})
+```
+
+## Search Parameters
+
+### Validation
+
+```tsx
+import { z } from 'zod'
+
+const postSearchSchema = z.object({
+  page: z.number().default(1),
+  filter: z.string().default(''),
+  sort: z.enum(['date', 'title']).default('date'),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: postSearchSchema,
+  // Or manual validation:
+  // validateSearch: (search) => postSearchSchema.parse(search),
+})
+```
+
+### Reading Search Params
+
+```tsx
+function PostsComponent() {
+  // From route
+  const { page, filter, sort } = Route.useSearch()
+
+  // Or from any component with useSearch hook
+  const search = useSearch({ from: '/posts' })
+}
+```
+
+### Updating Search Params
+
+```tsx
+import { useNavigate } from '@tanstack/react-router'
+
+function Pagination() {
+  const navigate = useNavigate()
+  const { page } = Route.useSearch()
+
+  return (
+    <button
+      onClick={() =>
+        navigate({
+          search: (prev) => ({ ...prev, page: prev.page + 1 }),
+        })
+      }
+    >
+      Next Page
+    </button>
+  )
+}
+
+// Or via Link component
+<Link
+  to="/posts"
+  search={(prev) => ({ ...prev, page: 2 })}
+>
+  Page 2
+</Link>
+```
+
+### Search Param Options
+
+```tsx
+const router = createRouter({
+  routeTree,
+  // Custom serialization
+  search: {
+    strict: true, // Reject unknown params
+  },
+  // Default search param serializer
+  stringifySearch: defaultStringifySearch,
+  parseSearch: defaultParseSearch,
+})
+```
+
+## Navigation
+
+### Link Component
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// Static route
+<Link to="/about">About</Link>
+
+// Dynamic route with params
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  Post 123
+</Link>
+
+// With search params
+<Link to="/posts" search={{ page: 2, filter: 'react' }}>
+  Page 2
+</Link>
+
+// Active link styling
+<Link
+  to="/posts"
+  activeProps={{ className: 'active' }}
+  inactiveProps={{ className: 'inactive' }}
+  activeOptions={{ exact: true }}
+>
+  Posts
+</Link>
+
+// Preloading
+<Link to="/posts" preload="intent">Posts</Link>
+<Link to="/dashboard" preload="viewport">Dashboard</Link>
+
+// Hash
+<Link to="/docs" hash="api-reference">API Reference</Link>
+```
+
+### Programmatic Navigation
+
+```tsx
+import { useNavigate, useRouter } from '@tanstack/react-router'
+
+function MyComponent() {
+  const navigate = useNavigate()
+  const router = useRouter()
+
+  // Navigate to a route
+  navigate({ to: '/posts', search: { page: 1 } })
+
+  // Navigate with replace
+  navigate({ to: '/posts', replace: true })
+
+  // Relative navigation
+  navigate({ to: '.', search: (prev) => ({ ...prev, page: 2 }) })
+
+  // Go back/forward
+  router.history.back()
+  router.history.forward()
+
+  // Invalidate and reload current route
+  router.invalidate()
+}
+```
+
+### Redirects
+
+```tsx
+import { redirect } from '@tanstack/react-router'
+
+// In beforeLoad or loader
+throw redirect({
+  to: '/login',
+  search: { redirect: location.href },
+  // Optional status code
+  statusCode: 301, // Permanent redirect (SSR)
+})
+```
+
+### Navigation Blocking
+
+```tsx
+import { useBlocker } from '@tanstack/react-router'
+
+function FormComponent() {
+  const [isDirty, setIsDirty] = useState(false)
+
+  useBlocker({
+    shouldBlockFn: () => isDirty,
+    withResolver: true, // Shows confirm dialog
+  })
+
+  // Or with custom UI
+  const { proceed, reset, status } = useBlocker({
+    shouldBlockFn: () => isDirty,
+  })
+
+  if (status === 'blocked') {
+    return (
+      <div>
+        <p>Are you sure you want to leave?</p>
+        <button onClick={proceed}>Leave</button>
+        <button onClick={reset}>Stay</button>
+      </div>
+    )
+  }
+}
+```
+
+## Code Splitting
+
+### Automatic (File-Based Routing)
+
+With file-based routing, create a lazy file:
+
+```
+routes/
+  posts.tsx          # Critical: loader, beforeLoad, meta
+  posts.lazy.tsx     # Lazy: component, pendingComponent, errorComponent
+```
+
+```tsx
+// posts.tsx (loaded eagerly)
+export const Route = createFileRoute('/posts')({
+  loader: () => fetchPosts(),
+})
+
+// posts.lazy.tsx (loaded lazily)
+import { createLazyFileRoute } from '@tanstack/react-router'
+
+export const Route = createLazyFileRoute('/posts')({
+  component: PostsComponent,
+  pendingComponent: PostsLoading,
+  errorComponent: PostsError,
+})
+```
+
+### Manual Code Splitting
+
+```tsx
+const postsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/posts',
+  loader: () => fetchPosts(),
+}).lazy(() => import('./posts.lazy').then((d) => d.Route))
+```
+
+## Preloading
+
+```tsx
+// Router-level defaults
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent', // 'intent' | 'viewport' | 'render' | false
+  defaultPreloadStaleTime: 30_000, // 30 seconds
+})
+
+// Route-level
+export const Route = createFileRoute('/posts/$postId')({
+  // Stale time for the loader data
+  staleTime: 5_000,
+  // How long preloaded data stays fresh
+  preloadStaleTime: 30_000,
+})
+
+// Link-level
+<Link to="/posts" preload="intent" preloadDelay={100}>
+  Posts
+</Link>
+```
+
+## Type Safety
+
+### Register Router Type
+
+```tsx
+// Declare module for type inference
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+```
+
+### Type-Safe Hooks
+
+All hooks are fully typed based on the route tree:
+
+```tsx
+// useParams - typed to route's params
+const { postId } = useParams({ from: '/posts/$postId' })
+
+// useSearch - typed to route's search schema
+const { page } = useSearch({ from: '/posts' })
+
+// useLoaderData - typed to loader return
+const data = useLoaderData({ from: '/posts/$postId' })
+
+// useRouteContext - typed to route context
+const { auth } = useRouteContext({ from: '/protected' })
+```
+
+### Route Generics
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  // TypeScript infers:
+  // params: { postId: string }
+  // search: validated search schema type
+  // loaderData: return type of loader
+  // context: router context type
+})
+```
+
+## Authenticated Routes
+
+```tsx
+// __root.tsx
+export const Route = createRootRouteWithContext<{
+  auth: AuthContext
+}>()({
+  component: RootComponent,
+})
+
+// _authenticated.tsx (pathless layout for auth)
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+
+// _authenticated/dashboard.tsx
+export const Route = createFileRoute('/_authenticated/dashboard')({
+  component: Dashboard, // Only accessible when authenticated
+})
+```
+
+## Scroll Restoration
+
+```tsx
+const router = createRouter({
+  routeTree,
+  // Enable scroll restoration
+  defaultScrollRestoration: true,
+})
+
+// Or per-route
+export const Route = createFileRoute('/posts')({
+  // Scroll to top on navigation
+  scrollRestoration: true,
+})
+
+// Custom scroll restoration key
+<ScrollRestoration
+  getKey={(location) => location.pathname}
+/>
+```
+
+## Route Masking
+
+Display a different URL than the actual route:
+
+```tsx
+<Link
+  to="/photos/$photoId"
+  params={{ photoId: photo.id }}
+  mask={{ to: '/photos', search: { photoId: photo.id } }}
+>
+  View Photo
+</Link>
+
+// Or programmatically
+navigate({
+  to: '/photos/$photoId',
+  params: { photoId: photo.id },
+  mask: { to: '/photos', search: { photoId: photo.id } },
+})
+```
+
+## Not Found Handling
+
+```tsx
+// Global 404
+const router = createRouter({
+  routeTree,
+  defaultNotFoundComponent: () => <div>Page not found</div>,
+})
+
+// Route-level 404
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId)
+    if (!post) throw notFound()
+    return post
+  },
+  notFoundComponent: () => <div>Post not found</div>,
+})
+```
+
+## Head Management
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData.title },
+      { name: 'description', content: loaderData.excerpt },
+      { property: 'og:title', content: loaderData.title },
+    ],
+    links: [
+      { rel: 'canonical', href: `https://example.com/posts/${loaderData.id}` },
+    ],
+  }),
+})
+```
+
+## Integration with TanStack Query
+
+```tsx
+import { queryOptions } from '@tanstack/react-query'
+
+const postsQueryOptions = queryOptions({
+  queryKey: ['posts'],
+  queryFn: fetchPosts,
+})
+
+export const Route = createFileRoute('/posts')({
+  loader: ({ context: { queryClient } }) => {
+    // Ensure data is in cache, won't refetch if fresh
+    return queryClient.ensureQueryData(postsQueryOptions)
+  },
+  component: PostsComponent,
+})
+
+function PostsComponent() {
+  // Use the same query options for reactive updates
+  const { data: posts } = useSuspenseQuery(postsQueryOptions)
+  return <PostsList posts={posts} />
+}
+```
+
+## Router Hooks Reference
+
+| Hook | Purpose |
+|------|---------|
+| `useRouter()` | Access router instance |
+| `useRouterState()` | Subscribe to router state |
+| `useParams()` | Get route path params |
+| `useSearch()` | Get validated search params |
+| `useLoaderData()` | Get route loader data |
+| `useRouteContext()` | Get route context |
+| `useNavigate()` | Get navigate function |
+| `useLocation()` | Get current location |
+| `useMatches()` | Get all matched routes |
+| `useMatch()` | Get specific route match |
+| `useBlocker()` | Block navigation |
+| `useLinkProps()` | Get link props for custom components |
+| `useMatchRoute()` | Check if a route matches |
+
+## Best Practices
+
+1. **Use file-based routing** for most applications - it's simpler and auto-generates the route tree
+2. **Validate search params** with Zod or custom validators for type safety
+3. **Use `loaderDeps`** to control when loaders re-execute based on search param changes
+4. **Leverage context** for dependency injection (QueryClient, auth state)
+5. **Use `beforeLoad`** for authentication guards, not in components
+6. **Separate critical vs lazy code** - keep loaders in the main file, components in `.lazy.tsx`
+7. **Use `preload="intent"`** on Links for perceived performance
+8. **Use `staleTime`** to prevent unnecessary refetches during navigation
+9. **Register the router type** for full TypeScript inference across the app
+10. **Use `notFound()`** instead of conditional rendering for 404 states
+11. **Colocate search param logic** with routes that own them
+12. **Use pathless layouts** (`_authenticated`) for shared auth/layout logic without URL segments
+
+## Common Pitfalls
+
+- Forgetting to register the router type (`declare module`)
+- Not using `loaderDeps` when loader depends on search params (causes stale data)
+- Putting auth checks in components instead of `beforeLoad` (flash of protected content)
+- Not handling the loading state with `pendingComponent`
+- Using `useEffect` for data fetching instead of route loaders
+- Mutating search params directly instead of using navigate/Link
+- Not wrapping the app with `RouterProvider`
+- Forgetting `getParentRoute` in code-based route definitions
diff --git a/.agents/skills/tanstack-table/SKILL.md b/.agents/skills/tanstack-table/SKILL.md
new file mode 100644
index 0000000..3159adb
--- /dev/null
+++ b/.agents/skills/tanstack-table/SKILL.md
@@ -0,0 +1,582 @@
+---
+name: tanstack-table
+description: Headless UI for building powerful tables & datagrids for TS/JS, React, Vue, Solid, Svelte, Qwik, Angular, and Lit.
+---
+
+
+## Overview
+
+TanStack Table is a headless UI library for building data tables and datagrids. It provides logic for sorting, filtering, pagination, grouping, expanding, column pinning/ordering/visibility/resizing, and row selection - without rendering any markup or styles.
+
+**Package:** `@tanstack/react-table`
+**Utilities:** `@tanstack/match-sorter-utils` (fuzzy filtering)
+**Current Version:** v8
+
+## Installation
+
+```bash
+npm install @tanstack/react-table
+```
+
+## Core Architecture
+
+### Building Blocks
+
+1. **Column Definitions** - describe columns (data access, rendering, features)
+2. **Table Instance** - central coordinator with state and APIs
+3. **Row Models** - data processing pipeline (filter -> sort -> group -> paginate)
+4. **Headers, Rows, Cells** - renderable units
+
+### Critical: Data & Column Stability
+
+```typescript
+// WRONG - new references every render, causes infinite loops
+const table = useReactTable({
+  data: fetchedData.results,     // new ref!
+  columns: [{ accessorKey: 'name' }], // new ref!
+})
+
+// CORRECT - stable references
+const columns = useMemo(() => [...], [])
+const data = useMemo(() => fetchedData?.results ?? [], [fetchedData])
+
+const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
+```
+
+## Column Definitions
+
+### Using createColumnHelper (Recommended)
+
+```typescript
+import { createColumnHelper } from '@tanstack/react-table'
+
+type Person = {
+  firstName: string
+  lastName: string
+  age: number
+  status: 'active' | 'inactive'
+}
+
+const columnHelper = createColumnHelper<Person>()
+
+const columns = [
+  // Accessor column (data column)
+  columnHelper.accessor('firstName', {
+    header: 'First Name',
+    cell: info => info.getValue(),
+    footer: info => info.column.id,
+  }),
+
+  // Accessor with function
+  columnHelper.accessor(row => row.lastName, {
+    id: 'lastName', // required with accessorFn
+    header: () => <span>Last Name</span>,
+    cell: info => <i>{info.getValue()}</i>,
+  }),
+
+  // Display column (no data, custom rendering)
+  columnHelper.display({
+    id: 'actions',
+    header: 'Actions',
+    cell: ({ row }) => (
+      <button onClick={() => deleteRow(row.original)}>Delete</button>
+    ),
+  }),
+
+  // Group column (nested headers)
+  columnHelper.group({
+    id: 'info',
+    header: 'Info',
+    columns: [
+      columnHelper.accessor('age', { header: 'Age' }),
+      columnHelper.accessor('status', { header: 'Status' }),
+    ],
+  }),
+]
+```
+
+### Column Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Unique identifier (auto-derived from accessorKey) |
+| `accessorKey` | `string` | Dot-notation path to row data |
+| `accessorFn` | `(row) => any` | Custom accessor function |
+| `header` | `string \| (context) => ReactNode` | Header renderer |
+| `cell` | `(context) => ReactNode` | Cell renderer |
+| `footer` | `(context) => ReactNode` | Footer renderer |
+| `size` | `number` | Default width (default: 150) |
+| `minSize` | `number` | Min width (default: 20) |
+| `maxSize` | `number` | Max width |
+| `enableSorting` | `boolean` | Enable sorting |
+| `sortingFn` | `string \| SortingFn` | Sort function |
+| `enableFiltering` | `boolean` | Enable filtering |
+| `filterFn` | `string \| FilterFn` | Filter function |
+| `enableGrouping` | `boolean` | Enable grouping |
+| `aggregationFn` | `string \| AggregationFn` | Aggregation function |
+| `enableHiding` | `boolean` | Enable visibility toggle |
+| `enableResizing` | `boolean` | Enable resizing |
+| `enablePinning` | `boolean` | Enable pinning |
+| `meta` | `any` | Custom metadata |
+
+## Table Instance
+
+### Creating a Table
+
+```typescript
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  flexRender,
+} from '@tanstack/react-table'
+
+function MyTable() {
+  const [sorting, setSorting] = useState<SortingState>([])
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: 10,
+  })
+
+  const table = useReactTable({
+    data,
+    columns,
+    state: { sorting, columnFilters, pagination },
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+  })
+
+  return (
+    <table>
+      <thead>
+        {table.getHeaderGroups().map(headerGroup => (
+          <tr key={headerGroup.id}>
+            {headerGroup.headers.map(header => (
+              <th key={header.id} onClick={header.column.getToggleSortingHandler()}>
+                {header.isPlaceholder ? null :
+                  flexRender(header.column.columnDef.header, header.getContext())}
+                {{ asc: ' ↑', desc: ' ↓' }[header.column.getIsSorted() as string] ?? null}
+              </th>
+            ))}
+          </tr>
+        ))}
+      </thead>
+      <tbody>
+        {table.getRowModel().rows.map(row => (
+          <tr key={row.id}>
+            {row.getVisibleCells().map(cell => (
+              <td key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+```
+
+## Sorting
+
+```typescript
+const table = useReactTable({
+  state: { sorting },
+  onSortingChange: setSorting,
+  getSortedRowModel: getSortedRowModel(),
+  enableSorting: true,
+  enableMultiSort: true,
+  // manualSorting: true,  // For server-side sorting
+})
+
+// Built-in sort functions: 'alphanumeric', 'text', 'datetime', 'basic'
+// Column-level: sortingFn: 'alphanumeric'
+```
+
+## Filtering
+
+### Column Filtering
+
+```typescript
+const table = useReactTable({
+  state: { columnFilters },
+  onColumnFiltersChange: setColumnFilters,
+  getFilteredRowModel: getFilteredRowModel(),
+  getFacetedRowModel: getFacetedRowModel(),
+  getFacetedUniqueValues: getFacetedUniqueValues(),
+  getFacetedMinMaxValues: getFacetedMinMaxValues(),
+})
+
+// Built-in: 'includesString', 'equalsString', 'arrIncludes', 'inNumberRange', etc.
+
+// Filter UI
+function Filter({ column }) {
+  return (
+    <input
+      value={(column.getFilterValue() ?? '') as string}
+      onChange={e => column.setFilterValue(e.target.value)}
+      placeholder={`Filter... (${column.getFacetedUniqueValues()?.size})`}
+    />
+  )
+}
+```
+
+### Global Filtering
+
+```typescript
+const [globalFilter, setGlobalFilter] = useState('')
+
+const table = useReactTable({
+  state: { globalFilter },
+  onGlobalFilterChange: setGlobalFilter,
+  globalFilterFn: 'includesString',
+  getFilteredRowModel: getFilteredRowModel(),
+})
+```
+
+### Fuzzy Filtering
+
+```typescript
+import { rankItem } from '@tanstack/match-sorter-utils'
+
+const fuzzyFilter: FilterFn<any> = (row, columnId, value, addMeta) => {
+  const itemRank = rankItem(row.getValue(columnId), value)
+  addMeta({ itemRank })
+  return itemRank.passed
+}
+
+const table = useReactTable({
+  filterFns: { fuzzy: fuzzyFilter },
+  globalFilterFn: 'fuzzy',
+})
+```
+
+## Pagination
+
+```typescript
+const table = useReactTable({
+  state: { pagination },
+  onPaginationChange: setPagination,
+  getPaginationRowModel: getPaginationRowModel(),
+  // For server-side:
+  // manualPagination: true,
+  // pageCount: serverPageCount,
+})
+
+// Navigation
+table.nextPage()
+table.previousPage()
+table.firstPage()
+table.lastPage()
+table.setPageSize(20)
+table.getCanNextPage()     // boolean
+table.getCanPreviousPage() // boolean
+table.getPageCount()       // total pages
+```
+
+## Row Selection
+
+```typescript
+const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
+
+const table = useReactTable({
+  state: { rowSelection },
+  onRowSelectionChange: setRowSelection,
+  enableRowSelection: true,
+  enableMultiRowSelection: true,
+})
+
+// Checkbox column
+columnHelper.display({
+  id: 'select',
+  header: ({ table }) => (
+    <input
+      type="checkbox"
+      checked={table.getIsAllRowsSelected()}
+      onChange={table.getToggleAllRowsSelectedHandler()}
+    />
+  ),
+  cell: ({ row }) => (
+    <input
+      type="checkbox"
+      checked={row.getIsSelected()}
+      disabled={!row.getCanSelect()}
+      onChange={row.getToggleSelectedHandler()}
+    />
+  ),
+})
+
+// Get selected rows
+table.getSelectedRowModel().rows
+```
+
+## Column Visibility
+
+```typescript
+const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
+
+const table = useReactTable({
+  state: { columnVisibility },
+  onColumnVisibilityChange: setColumnVisibility,
+})
+
+// Toggle UI
+{table.getAllLeafColumns().map(column => (
+  <label key={column.id}>
+    <input
+      type="checkbox"
+      checked={column.getIsVisible()}
+      onChange={column.getToggleVisibilityHandler()}
+    />
+    {column.id}
+  </label>
+))}
+```
+
+## Column Pinning
+
+```typescript
+const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
+  left: ['select', 'name'],
+  right: ['actions'],
+})
+
+const table = useReactTable({
+  state: { columnPinning },
+  onColumnPinningChange: setColumnPinning,
+  enableColumnPinning: true,
+})
+
+// Render pinned sections separately
+row.getLeftVisibleCells()   // Left-pinned
+row.getCenterVisibleCells() // Unpinned
+row.getRightVisibleCells()  // Right-pinned
+```
+
+## Column Resizing
+
+```typescript
+const table = useReactTable({
+  enableColumnResizing: true,
+  columnResizeMode: 'onChange', // 'onChange' | 'onEnd'
+  defaultColumn: { size: 150, minSize: 50, maxSize: 500 },
+})
+
+// Resize handle in header
+<div
+  onMouseDown={header.getResizeHandler()}
+  onTouchStart={header.getResizeHandler()}
+  className={`resizer ${header.column.getIsResizing() ? 'isResizing' : ''}`}
+/>
+```
+
+## Grouping & Aggregation
+
+```typescript
+const [grouping, setGrouping] = useState<GroupingState>([])
+
+const table = useReactTable({
+  state: { grouping },
+  onGroupingChange: setGrouping,
+  getGroupedRowModel: getGroupedRowModel(),
+  getExpandedRowModel: getExpandedRowModel(),
+})
+
+// Built-in aggregation: 'sum', 'min', 'max', 'mean', 'median', 'count', 'unique', 'uniqueCount'
+columnHelper.accessor('amount', {
+  aggregationFn: 'sum',
+  aggregatedCell: ({ getValue }) => `Total: ${getValue()}`,
+})
+```
+
+## Row Expanding
+
+```typescript
+const [expanded, setExpanded] = useState<ExpandedState>({})
+
+const table = useReactTable({
+  state: { expanded },
+  onExpandedChange: setExpanded,
+  getExpandedRowModel: getExpandedRowModel(),
+  getSubRows: (row) => row.subRows, // For hierarchical data
+})
+
+// Expand toggle
+<button onClick={row.getToggleExpandedHandler()}>
+  {row.getIsExpanded() ? '−' : '+'}
+</button>
+
+// Detail row pattern
+{row.getIsExpanded() && (
+  <tr>
+    <td colSpan={columns.length}>
+      <DetailComponent data={row.original} />
+    </td>
+  </tr>
+)}
+```
+
+## Virtualization Integration
+
+```typescript
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+function VirtualizedTable() {
+  const table = useReactTable({ /* ... */ })
+  const { rows } = table.getRowModel()
+  const parentRef = useRef<HTMLDivElement>(null)
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+    overscan: 10,
+  })
+
+  return (
+    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
+      <table>
+        <tbody style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+          {virtualizer.getVirtualItems().map(virtualRow => {
+            const row = rows[virtualRow.index]
+            return (
+              <tr
+                key={row.id}
+                style={{
+                  position: 'absolute',
+                  transform: `translateY(${virtualRow.start}px)`,
+                  height: `${virtualRow.size}px`,
+                }}
+              >
+                {row.getVisibleCells().map(cell => (
+                  <td key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </td>
+                ))}
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+```
+
+## Server-Side Operations
+
+```typescript
+const table = useReactTable({
+  data: serverData,
+  columns,
+  manualSorting: true,
+  manualFiltering: true,
+  manualPagination: true,
+  pageCount: serverPageCount,
+  state: { sorting, columnFilters, pagination },
+  onSortingChange: setSorting,
+  onColumnFiltersChange: setColumnFilters,
+  onPaginationChange: setPagination,
+  getCoreRowModel: getCoreRowModel(),
+  // Do NOT include getSortedRowModel, getFilteredRowModel, getPaginationRowModel
+})
+
+// Fetch data based on state
+useEffect(() => {
+  fetchData({ sorting, filters: columnFilters, pagination })
+}, [sorting, columnFilters, pagination])
+```
+
+## TypeScript Patterns
+
+### Extending Column Meta
+
+```typescript
+declare module '@tanstack/react-table' {
+  interface ColumnMeta<TData extends RowData, TValue> {
+    filterVariant?: 'text' | 'range' | 'select'
+    align?: 'left' | 'center' | 'right'
+  }
+}
+```
+
+### Custom Filter/Sort Function Registration
+
+```typescript
+declare module '@tanstack/react-table' {
+  interface FilterFns {
+    fuzzy: FilterFn<unknown>
+  }
+  interface SortingFns {
+    myCustomSort: SortingFn<unknown>
+  }
+}
+```
+
+### Editable Cells via Table Meta
+
+```typescript
+declare module '@tanstack/react-table' {
+  interface TableMeta<TData extends RowData> {
+    updateData: (rowIndex: number, columnId: string, value: unknown) => void
+  }
+}
+
+const table = useReactTable({
+  meta: {
+    updateData: (rowIndex, columnId, value) => {
+      setData(old => old.map((row, i) =>
+        i === rowIndex ? { ...row, [columnId]: value } : row
+      ))
+    },
+  },
+})
+```
+
+## Key Imports
+
+```typescript
+import {
+  createColumnHelper, flexRender, useReactTable,
+  getCoreRowModel, getSortedRowModel, getFilteredRowModel,
+  getPaginationRowModel, getGroupedRowModel, getExpandedRowModel,
+  getFacetedRowModel, getFacetedUniqueValues, getFacetedMinMaxValues,
+} from '@tanstack/react-table'
+
+import type {
+  ColumnDef, SortingState, ColumnFiltersState, VisibilityState,
+  PaginationState, ExpandedState, RowSelectionState, GroupingState,
+  ColumnOrderState, ColumnPinningState, FilterFn, SortingFn,
+} from '@tanstack/react-table'
+```
+
+## Best Practices
+
+1. **Always memoize `data` and `columns`** to prevent infinite re-renders
+2. **Use `flexRender`** for all header/cell/footer rendering
+3. **Use `table.getRowModel().rows`** for final rendered rows (not getCoreRowModel)
+4. **Import only needed row models** - each adds processing to the pipeline
+5. **Use `getRowId`** for stable row keys when data has unique IDs
+6. **Use `manualX` options** for server-side operations
+7. **Pair controlled state** with both `state.X` and `onXChange`
+8. **Use module augmentation** for custom meta, filter fns, sort fns
+9. **Use column helper** for type-safe column definitions
+10. **Set `autoResetPageIndex: true`** when filtering should reset pagination
+
+## Common Pitfalls
+
+- Defining columns inline (creates new ref each render)
+- Forgetting `getCoreRowModel()` (required for all tables)
+- Using row models without importing them
+- Not providing `id` when using `accessorFn`
+- Mixing `manualPagination` with client-side `getPaginationRowModel`
+- Forgetting `colSpan` for grouped headers
+- Not handling `header.isPlaceholder` for group column spacers
diff --git a/.agents/skills/test-driven-development/SKILL.md b/.agents/skills/test-driven-development/SKILL.md
new file mode 100644
index 0000000..4320d88
--- /dev/null
+++ b/.agents/skills/test-driven-development/SKILL.md
@@ -0,0 +1,320 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## When to Use
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask your human partner):**
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+## Red-Green-Refactor
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="Verify fails\ncorrectly", shape=diamond];
+    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="Verify passes\nAll green", shape=diamond];
+    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="Next", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="yes"];
+    verify_red -> red [label="wrong\nfailure"];
+    green -> verify_green;
+    verify_green -> refactor [label="yes"];
+    verify_green -> green [label="no"];
+    refactor -> verify_green [label="stay\ngreen"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### RED - Write Failing Test
+
+Write one minimal test showing what should happen.
+
+<Good>
+```typescript
+test('retries failed operations 3 times', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+Clear name, tests real behavior, one thing
+</Good>
+
+<Bad>
+```typescript
+test('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+Vague name, tests mock not code
+</Bad>
+
+**Requirements:**
+- One behavior
+- Clear name
+- Real code (no mocks unless unavoidable)
+
+### Verify RED - Watch It Fail
+
+**MANDATORY. Never skip.**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test fails (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+**Test passes?** You're testing existing behavior. Fix test.
+
+**Test errors?** Fix error, re-run until it fails correctly.
+
+### GREEN - Minimal Code
+
+Write simplest code to pass the test.
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+Just enough to pass
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI
+}
+```
+Over-engineered
+</Bad>
+
+Don't add features, refactor other code, or "improve" beyond the test.
+
+### Verify GREEN - Watch It Pass
+
+**MANDATORY.**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix code, not test.
+
+**Other tests fail?** Fix now.
+
+### REFACTOR - Clean Up
+
+After green only:
+- Remove duplication
+- Improve names
+- Extract helpers
+
+Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next feature.
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes behavior | `test('test1')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
+
+When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest:
+- Name the production change that would make the test fail — before writing it
+- Assert on real behavior, never on mock behavior
+- Keep test-only code in test utilities, out of production classes
+- Understand a dependency's side effects before mocking it
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. |
+| "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. |
+| "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for existing code. |
+
+## Red Flags - STOP and Start Over
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+
+## Example: Bug Fix
+
+**Bug:** Empty email accepted
+
+**RED**
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**Verify RED**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**GREEN**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**Verify GREEN**
+```bash
+$ npm test
+PASS
+```
+
+**REFACTOR**
+Extract validation for multiple fields if needed.
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.
+
+## When Stuck
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
+| Test too complicated | Design too complicated. Simplify interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+## Debugging Integration
+
+Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
+
+Never fix bugs without a test.
+
+## Final Rule
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+No exceptions without your human partner's permission.
diff --git a/.agents/skills/test-driven-development/writing-good-tests.md b/.agents/skills/test-driven-development/writing-good-tests.md
new file mode 100644
index 0000000..d3c4482
--- /dev/null
+++ b/.agents/skills/test-driven-development/writing-good-tests.md
@@ -0,0 +1,198 @@
+# Writing Good Tests
+
+**Load this reference when:** writing or changing tests, adding mocks, or
+adding cleanup/helper methods for tests.
+
+## Overview
+
+A test exists to catch a specific break. Two principles govern everything
+here:
+
+```
+1. Every test names the break it catches
+2. Every test exercises the real thing
+```
+
+Strict TDD produces both naturally: a test written first and watched
+failing against real code has already proven it can fail, and only earns
+a mock when the real dependency proves slow or external.
+
+## Principle 1: Name the Break
+
+Before writing the test body, answer: **what production change should
+make this test fail — and is that change a bug or a decision?** A test
+earns its place by catching a wrong branch, missing side effect, wrong
+argument, boundary case, or broken contract.
+
+**Derive expectations independently.** Use literals and hand-checked
+fixtures; table-driven tests with literal `want` values are the preferred
+shape. An expectation computed by the code under test — or its helpers —
+passes no matter what that code does:
+
+```typescript
+// ❌ Mirror assertion: the same builder computes both sides — always true
+const expected = buildSearchQuery({ tag: 'urgent' });
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
+
+// ✅ Hand-derived literal
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
+```
+
+**No change detectors.** If only intentional decisions can fail a test —
+a constant's value, exact message wording, private structure — it fires
+on redesign and sleeps through bugs. Test the behavior that depends on
+the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is
+retried 5 times and the 6th attempt never happens."
+
+**Behavior, not text.** Asserting that a script, skill, or config
+contains an exact line proves only that the source is the source. Run
+scripts against controlled inputs and assert outputs, side effects, or
+exit codes. Documents that instruct agents are tested by the consuming
+agent's behavior (superpowers:writing-skills); prose for humans earns no
+test at all.
+
+**Your code, not the framework.** Test the contract your code makes at
+its boundaries — the route you register, the query you emit, the payload
+you produce. Upstream mechanics are their maintainers' tests to write
+(the classic: asserting your router invokes a registered handler — that
+is the framework's test, not yours). When upstream behavior genuinely
+surprised you, write one narrow characterization test naming the
+assumption. The same boundary applies inside your code: constructors,
+getters, constants, and trivial forwarding earn tests only when they
+validate, normalize, default, derive, enforce, or cause side effects —
+otherwise assert the first consumer-visible result that depends on them.
+
+### Gate Function
+
+```
+BEFORE writing the test body:
+  Name the production change that would make this test fail.
+
+  Cannot name one            → redesign around an observable behavior
+  "The source text changed"  → run the artifact and assert its effects
+  Only intentional decisions → change detector; test the behavior
+                               that depends on the decision
+
+  Confirm the expected value is derived without the code under test.
+  IF it reuses the code's logic or helpers:
+    Replace it with a literal or hand-checked fixture
+```
+
+## Principle 2: Exercise the Real Thing
+
+**The mock earns no assertions.** A mock assertion passes when the mock
+is present and fails when it is absent — it says nothing about the
+component. Assert the real component's behavior; if the mock is what you
+are checking, unmock it or delete the assertion.
+
+```typescript
+// ✅ Real behavior
+expect(screen.getByRole('navigation')).toBeInTheDocument();
+
+// ❌ Mock existence
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+```
+
+**your human partner's correction:** "Are we testing the behavior of a
+mock?"
+
+**Mock at the right level.** Learn every side effect of the real method
+before replacing it; mock the slow or external operation and keep what
+the test depends on real. When unsure, run the test against the real
+implementation first and observe what actually needs to happen.
+
+```typescript
+// ❌ The mock swallows the config write that duplicate detection reads
+vi.mock('ToolCatalog', () => ({
+  discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+}));
+
+// ✅ Mock only the slow server startup; the config write stays real
+vi.mock('MCPServerManager');
+```
+
+**Make doubles specific.** When arguments, call counts, or ordering are
+part of the contract, assert them — a fake that accepts anything verifies
+nothing. Give each branch (success, error, malformed) its own fixture or
+spy, so the wrong branch cannot satisfy the expectation.
+
+**Mirror real data completely.** Mock the complete structure as it exists
+in reality — all documented fields — not just the ones your test reads.
+Partial mocks fail silently when downstream code reads an omitted field:
+the test passes while integration breaks.
+
+**Production classes carry production methods only.** Cleanup that only
+tests need lives in test utilities, never as a `destroy()` on the
+production class. Ask: is this method called only from tests? Does this
+class own this resource's lifecycle? Wrong answers → test utility.
+
+**Prefer real components over complex mocks.** When mock setup outgrows
+the test logic, mocks miss methods the real components have, or tests
+break when the mock changes, switch to an integration test with real
+components. **your human partner's question:** "Do we need to be using a
+mock here?"
+
+### Gate Function
+
+```
+BEFORE adding a mock or test helper:
+  List the real method's side effects; keep the ones the test
+  depends on real — mock the slow/external level below them.
+
+  Mock responses mirror the complete real structure.
+
+  A method only tests call lives in test utilities, not production.
+
+  About to assert on the mock itself?
+    Unmock it or delete the assertion.
+```
+
+## Tests Ship With the Implementation
+
+The TDD cycle — failing test, minimal implementation, refactor — is what
+"complete" means. Ship the tests the behavior needs and only those:
+trivial code and human prose earn none, and a test written to satisfy
+process costs maintenance forever.
+
+## The Mutation Check
+
+Before finishing, mentally mutate the production code; at least one test
+should fail for each realistic mutation:
+
+- Wrong constant or argument
+- Wrong branch handler
+- Missing state change or side effect
+- Empty or default return
+- Missing validation for zero, empty, nil, unauthorized, or malformed input
+
+A mutation nothing catches marks the behavior as unprotected — or the
+test as tautological.
+
+## Quick Reference
+
+| When you... | Do |
+|-------------|-----|
+| Write any test | Name the break it catches — a bug, not a decision |
+| Build an expected value | Derive it by hand; never with the code under test |
+| Test a script or document | Run it / pressure-test its consumer; never grep its text |
+| Reach for a dependency test | Test your boundary contract, not their documented mechanics |
+| Want to assert on a mocked element | Test the real component, or unmock it |
+| Are about to mock a method | Learn its side effects; mock the slow/external level |
+| Build a mock response | Mirror the real structure completely |
+| Need cleanup only tests use | Put it in test utilities |
+| Watch mock setup balloon | Switch to an integration test with real components |
+| Finish a test file | Run the mutation check |
+
+## Warning Signs
+
+- Setup and assertion share the same object, guaranteeing equality
+- The test can fail only through a panic, crash, or missing selector
+- The test fails on every intentional change, never on accidental breakage
+- Expected values are hidden behind loops, builders, or helpers
+- The test greps source text, or asserts a removed symbol stays removed
+- The test would still matter if only the framework remained
+- The test exists for coverage, checking no side effect or outcome
+- An assertion checks a `*-mock` test ID, or fails if you remove the mock
+- A method is called only from test files
+- Mock setup is more than half the test, or you can't explain why the mock is needed
+- Mocking "just to be safe"
diff --git a/.agents/skills/typescript-advanced-types/SKILL.md b/.agents/skills/typescript-advanced-types/SKILL.md
new file mode 100644
index 0000000..5057af7
--- /dev/null
+++ b/.agents/skills/typescript-advanced-types/SKILL.md
@@ -0,0 +1,318 @@
+---
+name: typescript-advanced-types
+description: Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.
+---
+
+# TypeScript Advanced Types
+
+Comprehensive guidance for mastering TypeScript's advanced type system including generics, conditional types, mapped types, template literal types, and utility types for building robust, type-safe applications.
+
+## When to Use This Skill
+
+- Building type-safe libraries or frameworks
+- Creating reusable generic components
+- Implementing complex type inference logic
+- Designing type-safe API clients
+- Building form validation systems
+- Creating strongly-typed configuration objects
+- Implementing type-safe state management
+- Migrating JavaScript codebases to TypeScript
+
+## Core Concepts
+
+### 1. Generics
+
+**Purpose:** Create reusable, type-flexible components while maintaining type safety.
+
+**Basic Generic Function:**
+
+```typescript
+function identity<T>(value: T): T {
+  return value;
+}
+
+const num = identity<number>(42); // Type: number
+const str = identity<string>("hello"); // Type: string
+const auto = identity(true); // Type inferred: boolean
+```
+
+**Generic Constraints:**
+
+```typescript
+interface HasLength {
+  length: number;
+}
+
+function logLength<T extends HasLength>(item: T): T {
+  console.log(item.length);
+  return item;
+}
+
+logLength("hello"); // OK: string has length
+logLength([1, 2, 3]); // OK: array has length
+logLength({ length: 10 }); // OK: object has length
+// logLength(42);             // Error: number has no length
+```
+
+**Multiple Type Parameters:**
+
+```typescript
+function merge<T, U>(obj1: T, obj2: U): T & U {
+  return { ...obj1, ...obj2 };
+}
+
+const merged = merge({ name: "John" }, { age: 30 });
+// Type: { name: string } & { age: number }
+```
+
+### 2. Conditional Types
+
+**Purpose:** Create types that depend on conditions, enabling sophisticated type logic.
+
+**Basic Conditional Type:**
+
+```typescript
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<string>; // true
+type B = IsString<number>; // false
+```
+
+**Extracting Return Types:**
+
+```typescript
+type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+
+function getUser() {
+  return { id: 1, name: "John" };
+}
+
+type User = ReturnType<typeof getUser>;
+// Type: { id: number; name: string; }
+```
+
+**Distributive Conditional Types:**
+
+```typescript
+type ToArray<T> = T extends any ? T[] : never;
+
+type StrOrNumArray = ToArray<string | number>;
+// Type: string[] | number[]
+```
+
+**Nested Conditions:**
+
+```typescript
+type TypeName<T> = T extends string
+  ? "string"
+  : T extends number
+    ? "number"
+    : T extends boolean
+      ? "boolean"
+      : T extends undefined
+        ? "undefined"
+        : T extends Function
+          ? "function"
+          : "object";
+
+type T1 = TypeName<string>; // "string"
+type T2 = TypeName<() => void>; // "function"
+```
+
+### 3. Mapped Types
+
+**Purpose:** Transform existing types by iterating over their properties.
+
+**Basic Mapped Type:**
+
+```typescript
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+interface User {
+  id: number;
+  name: string;
+}
+
+type ReadonlyUser = Readonly<User>;
+// Type: { readonly id: number; readonly name: string; }
+```
+
+**Optional Properties:**
+
+```typescript
+type Partial<T> = {
+  [P in keyof T]?: T[P];
+};
+
+type PartialUser = Partial<User>;
+// Type: { id?: number; name?: string; }
+```
+
+**Key Remapping:**
+
+```typescript
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+interface Person {
+  name: string;
+  age: number;
+}
+
+type PersonGetters = Getters<Person>;
+// Type: { getName: () => string; getAge: () => number; }
+```
+
+**Filtering Properties:**
+
+```typescript
+type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+interface Mixed {
+  id: number;
+  name: string;
+  age: number;
+  active: boolean;
+}
+
+type OnlyNumbers = PickByType<Mixed, number>;
+// Type: { id: number; age: number; }
+```
+
+### 4. Template Literal Types
+
+**Purpose:** Create string-based types with pattern matching and transformation.
+
+**Basic Template Literal:**
+
+```typescript
+type EventName = "click" | "focus" | "blur";
+type EventHandler = `on${Capitalize<EventName>}`;
+// Type: "onClick" | "onFocus" | "onBlur"
+```
+
+**String Manipulation:**
+
+```typescript
+type UppercaseGreeting = Uppercase<"hello">; // "HELLO"
+type LowercaseGreeting = Lowercase<"HELLO">; // "hello"
+type CapitalizedName = Capitalize<"john">; // "John"
+type UncapitalizedName = Uncapitalize<"John">; // "john"
+```
+
+**Path Building:**
+
+```typescript
+type Path<T> = T extends object
+  ? {
+      [K in keyof T]: K extends string ? `${K}` | `${K}.${Path<T[K]>}` : never;
+    }[keyof T]
+  : never;
+
+interface Config {
+  server: {
+    host: string;
+    port: number;
+  };
+  database: {
+    url: string;
+  };
+}
+
+type ConfigPath = Path<Config>;
+// Type: "server" | "database" | "server.host" | "server.port" | "database.url"
+```
+
+### 5. Utility Types
+
+**Built-in Utility Types:**
+
+```typescript
+// Partial<T> - Make all properties optional
+type PartialUser = Partial<User>;
+
+// Required<T> - Make all properties required
+type RequiredUser = Required<PartialUser>;
+
+// Readonly<T> - Make all properties readonly
+type ReadonlyUser = Readonly<User>;
+
+// Pick<T, K> - Select specific properties
+type UserName = Pick<User, "name" | "email">;
+
+// Omit<T, K> - Remove specific properties
+type UserWithoutPassword = Omit<User, "password">;
+
+// Exclude<T, U> - Exclude types from union
+type T1 = Exclude<"a" | "b" | "c", "a">; // "b" | "c"
+
+// Extract<T, U> - Extract types from union
+type T2 = Extract<"a" | "b" | "c", "a" | "b">; // "a" | "b"
+
+// NonNullable<T> - Exclude null and undefined
+type T3 = NonNullable<string | null | undefined>; // string
+
+// Record<K, T> - Create object type with keys K and values T
+type PageInfo = Record<"home" | "about", { title: string }>;
+```
+
+## Detailed worked examples and patterns
+
+Detailed sections (starting with `## Advanced Patterns`) live in `references/details.md`. Read that file when the navigation summary above is insufficient.
+
+## Best Practices
+
+1. **Use `unknown` over `any`**: Enforce type checking
+2. **Prefer `interface` for object shapes**: Better error messages
+3. **Use `type` for unions and complex types**: More flexible
+4. **Leverage type inference**: Let TypeScript infer when possible
+5. **Create helper types**: Build reusable type utilities
+6. **Use const assertions**: Preserve literal types
+7. **Avoid type assertions**: Use type guards instead
+8. **Document complex types**: Add JSDoc comments
+9. **Use strict mode**: Enable all strict compiler options
+10. **Test your types**: Use type tests to verify type behavior
+
+## Type Testing
+
+```typescript
+// Type assertion tests
+type AssertEqual<T, U> = [T] extends [U]
+  ? [U] extends [T]
+    ? true
+    : false
+  : false;
+
+type Test1 = AssertEqual<string, string>; // true
+type Test2 = AssertEqual<string, number>; // false
+type Test3 = AssertEqual<string | number, string>; // false
+
+// Expect error helper
+type ExpectError<T extends never> = T;
+
+// Example usage
+type ShouldError = ExpectError<AssertEqual<string, number>>;
+```
+
+## Common Pitfalls
+
+1. **Over-using `any`**: Defeats the purpose of TypeScript
+2. **Ignoring strict null checks**: Can lead to runtime errors
+3. **Too complex types**: Can slow down compilation
+4. **Not using discriminated unions**: Misses type narrowing opportunities
+5. **Forgetting readonly modifiers**: Allows unintended mutations
+6. **Circular type references**: Can cause compiler errors
+7. **Not handling edge cases**: Like empty arrays or null values
+
+## Performance Considerations
+
+- Avoid deeply nested conditional types
+- Use simple types when possible
+- Cache complex type computations
+- Limit recursion depth in recursive types
+- Use build tools to skip type checking in production
diff --git a/.agents/skills/typescript-advanced-types/references/details.md b/.agents/skills/typescript-advanced-types/references/details.md
new file mode 100644
index 0000000..6b1b9a1
--- /dev/null
+++ b/.agents/skills/typescript-advanced-types/references/details.md
@@ -0,0 +1,404 @@
+# typescript-advanced-types — detailed worked examples
+
+## Advanced Patterns
+
+### Pattern 1: Type-Safe Event Emitter
+
+```typescript
+type EventMap = {
+  "user:created": { id: string; name: string };
+  "user:updated": { id: string };
+  "user:deleted": { id: string };
+};
+
+class TypedEventEmitter<T extends Record<string, any>> {
+  private listeners: {
+    [K in keyof T]?: Array<(data: T[K]) => void>;
+  } = {};
+
+  on<K extends keyof T>(event: K, callback: (data: T[K]) => void): void {
+    if (!this.listeners[event]) {
+      this.listeners[event] = [];
+    }
+    this.listeners[event]!.push(callback);
+  }
+
+  emit<K extends keyof T>(event: K, data: T[K]): void {
+    const callbacks = this.listeners[event];
+    if (callbacks) {
+      callbacks.forEach((callback) => callback(data));
+    }
+  }
+}
+
+const emitter = new TypedEventEmitter<EventMap>();
+
+emitter.on("user:created", (data) => {
+  console.log(data.id, data.name); // Type-safe!
+});
+
+emitter.emit("user:created", { id: "1", name: "John" });
+// emitter.emit("user:created", { id: "1" });  // Error: missing 'name'
+```
+
+### Pattern 2: Type-Safe API Client
+
+```typescript
+type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+type EndpointConfig = {
+  "/users": {
+    GET: { response: User[] };
+    POST: { body: { name: string; email: string }; response: User };
+  };
+  "/users/:id": {
+    GET: { params: { id: string }; response: User };
+    PUT: { params: { id: string }; body: Partial<User>; response: User };
+    DELETE: { params: { id: string }; response: void };
+  };
+};
+
+type ExtractParams<T> = T extends { params: infer P } ? P : never;
+type ExtractBody<T> = T extends { body: infer B } ? B : never;
+type ExtractResponse<T> = T extends { response: infer R } ? R : never;
+
+class APIClient<Config extends Record<string, Record<HTTPMethod, any>>> {
+  async request<Path extends keyof Config, Method extends keyof Config[Path]>(
+    path: Path,
+    method: Method,
+    ...[options]: ExtractParams<Config[Path][Method]> extends never
+      ? ExtractBody<Config[Path][Method]> extends never
+        ? []
+        : [{ body: ExtractBody<Config[Path][Method]> }]
+      : [
+          {
+            params: ExtractParams<Config[Path][Method]>;
+            body?: ExtractBody<Config[Path][Method]>;
+          },
+        ]
+  ): Promise<ExtractResponse<Config[Path][Method]>> {
+    // Implementation here
+    return {} as any;
+  }
+}
+
+const api = new APIClient<EndpointConfig>();
+
+// Type-safe API calls
+const users = await api.request("/users", "GET");
+// Type: User[]
+
+const newUser = await api.request("/users", "POST", {
+  body: { name: "John", email: "john@example.com" },
+});
+// Type: User
+
+const user = await api.request("/users/:id", "GET", {
+  params: { id: "123" },
+});
+// Type: User
+```
+
+### Pattern 3: Builder Pattern with Type Safety
+
+```typescript
+type BuilderState<T> = {
+  [K in keyof T]: T[K] | undefined;
+};
+
+type RequiredKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+
+type OptionalKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+
+type IsComplete<T, S> =
+  RequiredKeys<T> extends keyof S
+    ? S[RequiredKeys<T>] extends undefined
+      ? false
+      : true
+    : false;
+
+class Builder<T, S extends BuilderState<T> = {}> {
+  private state: S = {} as S;
+
+  set<K extends keyof T>(key: K, value: T[K]): Builder<T, S & Record<K, T[K]>> {
+    this.state[key] = value;
+    return this as any;
+  }
+
+  build(this: IsComplete<T, S> extends true ? this : never): T {
+    return this.state as T;
+  }
+}
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  age?: number;
+}
+
+const builder = new Builder<User>();
+
+const user = builder
+  .set("id", "1")
+  .set("name", "John")
+  .set("email", "john@example.com")
+  .build(); // OK: all required fields set
+
+// const incomplete = builder
+//   .set("id", "1")
+//   .build();  // Error: missing required fields
+```
+
+### Pattern 4: Deep Readonly/Partial
+
+```typescript
+type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object
+    ? T[P] extends Function
+      ? T[P]
+      : DeepReadonly<T[P]>
+    : T[P];
+};
+
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object
+    ? T[P] extends Array<infer U>
+      ? Array<DeepPartial<U>>
+      : DeepPartial<T[P]>
+    : T[P];
+};
+
+interface Config {
+  server: {
+    host: string;
+    port: number;
+    ssl: {
+      enabled: boolean;
+      cert: string;
+    };
+  };
+  database: {
+    url: string;
+    pool: {
+      min: number;
+      max: number;
+    };
+  };
+}
+
+type ReadonlyConfig = DeepReadonly<Config>;
+// All nested properties are readonly
+
+type PartialConfig = DeepPartial<Config>;
+// All nested properties are optional
+```
+
+### Pattern 5: Type-Safe Form Validation
+
+```typescript
+type ValidationRule<T> = {
+  validate: (value: T) => boolean;
+  message: string;
+};
+
+type FieldValidation<T> = {
+  [K in keyof T]?: ValidationRule<T[K]>[];
+};
+
+type ValidationErrors<T> = {
+  [K in keyof T]?: string[];
+};
+
+class FormValidator<T extends Record<string, any>> {
+  constructor(private rules: FieldValidation<T>) {}
+
+  validate(data: T): ValidationErrors<T> | null {
+    const errors: ValidationErrors<T> = {};
+    let hasErrors = false;
+
+    for (const key in this.rules) {
+      const fieldRules = this.rules[key];
+      const value = data[key];
+
+      if (fieldRules) {
+        const fieldErrors: string[] = [];
+
+        for (const rule of fieldRules) {
+          if (!rule.validate(value)) {
+            fieldErrors.push(rule.message);
+          }
+        }
+
+        if (fieldErrors.length > 0) {
+          errors[key] = fieldErrors;
+          hasErrors = true;
+        }
+      }
+    }
+
+    return hasErrors ? errors : null;
+  }
+}
+
+interface LoginForm {
+  email: string;
+  password: string;
+}
+
+const validator = new FormValidator<LoginForm>({
+  email: [
+    {
+      validate: (v) => v.includes("@"),
+      message: "Email must contain @",
+    },
+    {
+      validate: (v) => v.length > 0,
+      message: "Email is required",
+    },
+  ],
+  password: [
+    {
+      validate: (v) => v.length >= 8,
+      message: "Password must be at least 8 characters",
+    },
+  ],
+});
+
+const errors = validator.validate({
+  email: "invalid",
+  password: "short",
+});
+// Type: { email?: string[]; password?: string[]; } | null
+```
+
+### Pattern 6: Discriminated Unions
+
+```typescript
+type Success<T> = {
+  status: "success";
+  data: T;
+};
+
+type Error = {
+  status: "error";
+  error: string;
+};
+
+type Loading = {
+  status: "loading";
+};
+
+type AsyncState<T> = Success<T> | Error | Loading;
+
+function handleState<T>(state: AsyncState<T>): void {
+  switch (state.status) {
+    case "success":
+      console.log(state.data); // Type: T
+      break;
+    case "error":
+      console.log(state.error); // Type: string
+      break;
+    case "loading":
+      console.log("Loading...");
+      break;
+  }
+}
+
+// Type-safe state machine
+type State =
+  | { type: "idle" }
+  | { type: "fetching"; requestId: string }
+  | { type: "success"; data: any }
+  | { type: "error"; error: Error };
+
+type Event =
+  | { type: "FETCH"; requestId: string }
+  | { type: "SUCCESS"; data: any }
+  | { type: "ERROR"; error: Error }
+  | { type: "RESET" };
+
+function reducer(state: State, event: Event): State {
+  switch (state.type) {
+    case "idle":
+      return event.type === "FETCH"
+        ? { type: "fetching", requestId: event.requestId }
+        : state;
+    case "fetching":
+      if (event.type === "SUCCESS") {
+        return { type: "success", data: event.data };
+      }
+      if (event.type === "ERROR") {
+        return { type: "error", error: event.error };
+      }
+      return state;
+    case "success":
+    case "error":
+      return event.type === "RESET" ? { type: "idle" } : state;
+  }
+}
+```
+
+## Type Inference Techniques
+
+### 1. Infer Keyword
+
+```typescript
+// Extract array element type
+type ElementType<T> = T extends (infer U)[] ? U : never;
+
+type NumArray = number[];
+type Num = ElementType<NumArray>; // number
+
+// Extract promise type
+type PromiseType<T> = T extends Promise<infer U> ? U : never;
+
+type AsyncNum = PromiseType<Promise<number>>; // number
+
+// Extract function parameters
+type Parameters<T> = T extends (...args: infer P) => any ? P : never;
+
+function foo(a: string, b: number) {}
+type FooParams = Parameters<typeof foo>; // [string, number]
+```
+
+### 2. Type Guards
+
+```typescript
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isArrayOf<T>(
+  value: unknown,
+  guard: (item: unknown) => item is T,
+): value is T[] {
+  return Array.isArray(value) && value.every(guard);
+}
+
+const data: unknown = ["a", "b", "c"];
+
+if (isArrayOf(data, isString)) {
+  data.forEach((s) => s.toUpperCase()); // Type: string[]
+}
+```
+
+### 3. Assertion Functions
+
+```typescript
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== "string") {
+    throw new Error("Not a string");
+  }
+}
+
+function processValue(value: unknown) {
+  assertIsString(value);
+  // value is now typed as string
+  console.log(value.toUpperCase());
+}
+```
diff --git a/.agents/skills/typescript-clean-code/LICENSE b/.agents/skills/typescript-clean-code/LICENSE
new file mode 100644
index 0000000..326cc1e
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/LICENSE
@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2025 BMAD Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/.agents/skills/typescript-clean-code/SKILL.md b/.agents/skills/typescript-clean-code/SKILL.md
new file mode 100644
index 0000000..ac78e50
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: typescript-clean-code
+description: |
+  Clean Code principles, professional practices, and workflows for TypeScript developers. Based on Robert C. Martin's "Clean Code" and "The Clean Coder" books.
+
+  IMPORTANT: When this skill is active, always load and consult the reference files (rules.md, examples.md) before giving advice or writing code. Reference content takes precedence over general knowledge.
+
+  Use this skill when:
+  - Writing TypeScript/JavaScript code
+  - Reviewing code or pull requests
+  - Refactoring existing code
+  - Following test-driven development (TDD)
+  - Fixing bugs with proper test coverage
+  - Planning test strategy for features
+  - Estimating tasks accurately
+  - Handling deadlines and commitments professionally
+  - Working effectively with teams
+---
+
+# Clean Code
+
+Principles, practices, and workflows for TypeScript developers.
+
+## Critical: Reference-First Approach
+
+**Always load and consult the reference files before applying any principle or making any recommendation.** The references in this skill contain curated, authoritative knowledge from Robert C. Martin's books, adapted for TypeScript. When this skill is active:
+
+1. **Read references before responding** - For any code quality or professional practice topic, load the relevant `rules.md` and `examples.md` files from `references/` before giving advice or writing code. Do not rely on general knowledge alone.
+2. **Reference content overrides internal knowledge** - If your general knowledge conflicts with what the reference files state, follow the reference files. They contain the specific rules, thresholds, and patterns this skill enforces.
+3. **Cite specific rules** - When making recommendations, reference the specific rule (e.g., "per `references/functions/rules.md` Rule 1: Keep Functions Small, 2-5 lines ideal") so the user can trace the guidance back to its source.
+4. **Use examples from reference files** - Prefer the bad/good code examples in `references/[topic]/examples.md` over generating your own. These examples are curated for TypeScript and demonstrate the exact patterns intended.
+5. **Follow workflows step-by-step** - When executing a task (review, refactoring, TDD, etc.), load the corresponding workflow file and follow each step, loading the reference files each step points to.
+
+**Do not skip loading references.** Even if you "know" Clean Code principles, the reference files contain specific TypeScript adaptations, thresholds, checklists, and smell catalogs that your general knowledge may not match exactly.
+
+## Quick Start
+
+1. **For a task**: Check `guidelines.md` → find the right workflow → load it → follow each step (loading referenced files)
+2. **For reference**: Load the specific `rules.md` and `examples.md` files relevant to your work → apply them
+3. **Follow the workflow**: Step-by-step process for consistent results — always load the files each step references
+
+## Workflows
+
+Step-by-step processes for common tasks:
+
+| Workflow | When to Use |
+|----------|-------------|
+| `workflows/code-review/workflow.md` | Reviewing code for quality |
+| `workflows/pr-review/workflow.md` | Reviewing pull requests |
+| `workflows/tdd.md` | Test-driven development cycle |
+| `workflows/refactoring/workflow.md` | Safe refactoring with tests |
+| `workflows/new-feature.md` | Building new functionality |
+| `workflows/bug-fix.md` | Fixing bugs properly |
+| `workflows/test-strategy.md` | Planning test coverage |
+| `workflows/estimation.md` | Estimating tasks (PERT) |
+| `workflows/deadline-negotiation.md` | Handling unrealistic deadlines |
+
+### Step-File Architecture (Code Review, PR Review, Refactoring)
+
+The code review, PR review, and refactoring workflows use a **step-file architecture** for context-safe execution:
+
+- Each workflow has a `workflow.md` entry point that describes steps and loads `steps/step-01-init.md`
+- Each step is a separate file in `steps/`, loaded sequentially
+- Progress is tracked via `stepsCompleted` array in the output document's YAML frontmatter
+- If context is compacted mid-workflow, `step-01-init.md` detects the existing output and `step-01b-continue.md` resumes from the last completed step
+- Each step loads specific reference files before analysis and cites rules in findings
+- The refactoring workflow includes a loop (steps 4-7) for iterative change-test-commit cycles
+
+## Reference Categories
+
+### Part 1: Code Quality (Clean Code book)
+
+| Category | Files | Purpose |
+|----------|-------|---------|
+| naming | 3 | Variable, function, class naming |
+| functions | 4 | Function design and review |
+| classes | 3 | Class/module design |
+| comments | 3 | Comment best practices |
+| error-handling | 3 | Exception handling |
+| unit-tests | 3 | Clean test principles |
+| formatting | 3 | Code layout |
+| smells | 3 | Code smell catalog (50+) |
+
+### Part 2: Professional Practices (Clean Coder book)
+
+| Category | Files | Purpose |
+|----------|-------|---------|
+| professionalism | 3 | Professional ethics |
+| saying-no | 3 | Declining requests |
+| commitment | 3 | Making promises |
+| coding-practices | 3 | Daily habits, flow, debugging |
+| tdd | 3 | TDD workflow and benefits |
+| practicing | 3 | Deliberate practice |
+| acceptance-testing | 3 | Requirements as tests |
+| testing-strategies | 3 | Test pyramid |
+| time-management | 3 | Meetings, focus |
+| estimation | 3 | PERT estimation |
+| pressure | 3 | Working under pressure |
+| collaboration | 3 | Working with teams |
+
+## Key Principles (Summary Only — Always Load Full References)
+
+These are abbreviated reminders. **Always load the corresponding reference files for the full rules, thresholds, and examples before applying.**
+
+### Code Quality
+1. **Readability** → `references/formatting/rules.md`, `references/naming/rules.md`
+2. **Single Responsibility** → `references/classes/rules.md`, `references/functions/rules.md`
+3. **Small Units** → `references/functions/rules.md` (Rule 1: 2-5 lines ideal)
+4. **Meaningful Names** → `references/naming/rules.md`
+5. **DRY** → `references/smells/rules.md` (G5)
+6. **Clean Tests** → `references/unit-tests/rules.md`
+
+### Professional Practices
+1. **Take Responsibility** → `references/professionalism/rules.md`
+2. **Say No** → `references/saying-no/rules.md`
+3. **Commit Clearly** → `references/commitment/rules.md`
+4. **Estimates != Commitments** → `references/estimation/rules.md`
+5. **Stay Clean Under Pressure** → `references/pressure/rules.md`
+
+## Guidelines
+
+See `guidelines.md` for:
+- Task → workflow mapping
+- Situation → reference file mapping
+- Decision tree for common scenarios
+
+## Reference Loading Checklist
+
+Before giving any code advice or writing code, verify:
+- [ ] Identified which reference categories apply to the current task
+- [ ] Loaded the `rules.md` for each applicable category
+- [ ] Loaded `examples.md` if demonstrating patterns or reviewing code
+- [ ] Loaded the relevant `workflow/*.md` if executing a multi-step task
+- [ ] Will cite specific rules/files in recommendations
diff --git a/.agents/skills/typescript-clean-code/guidelines.md b/.agents/skills/typescript-clean-code/guidelines.md
new file mode 100644
index 0000000..4c25878
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/guidelines.md
@@ -0,0 +1,249 @@
+# Clean Code Guidelines
+
+Quick reference for finding the right workflow or reference file.
+
+**How to use**: 
+1. Find your task below → use the recommended **workflow**
+2. Need specific rules → load the **reference files**
+
+---
+
+## Workflows
+
+Step-by-step processes for common tasks. **Start here for known tasks.**
+
+### Code Tasks
+
+| Task | Workflow |
+|------|----------|
+| Review code quality | `workflows/code-review/workflow.md` |
+| Review a pull request | `workflows/pr-review/workflow.md` |
+| Build new feature | `workflows/new-feature.md` |
+| Fix a bug | `workflows/bug-fix.md` |
+| Refactor code | `workflows/refactoring/workflow.md` |
+| Write tests (TDD) | `workflows/tdd.md` |
+| Plan test coverage | `workflows/test-strategy.md` |
+
+### Professional Tasks
+
+| Task | Workflow |
+|------|----------|
+| Estimate a task | `workflows/estimation.md` |
+| Handle unrealistic deadline | `workflows/deadline-negotiation.md` |
+
+---
+
+## Part 1: Code Quality References
+
+### By Task - Code Review
+
+| Reviewing... | Load these files |
+|--------------|------------------|
+| Function quality | `references/functions/rules.md`, `references/functions/checklist.md` |
+| Variable/function names | `references/naming/rules.md` |
+| Class design | `references/classes/rules.md` |
+| Comment quality | `references/comments/rules.md` |
+| Error handling | `references/error-handling/rules.md` |
+| Test quality | `references/unit-tests/rules.md` |
+| Code formatting | `references/formatting/rules.md` |
+| General code smells | `references/smells/rules.md` |
+
+### By Task - Writing New Code
+
+| Creating... | Load these files |
+|-------------|------------------|
+| New function | `references/functions/rules.md`, `references/naming/rules.md` |
+| New class/module | `references/classes/rules.md`, `references/naming/rules.md` |
+| Unit tests | `references/unit-tests/rules.md`, `references/tdd/rules.md` |
+| Acceptance tests | `references/acceptance-testing/rules.md` |
+| Error handling | `references/error-handling/rules.md` |
+| Comments/docs | `references/comments/rules.md` |
+
+### By Task - Refactoring
+
+| Fixing... | Load these files |
+|-----------|------------------|
+| Long function | `references/functions/rules.md`, `references/functions/examples.md` |
+| Large class | `references/classes/rules.md`, `references/classes/examples.md` |
+| Bad names | `references/naming/rules.md`, `references/naming/examples.md` |
+| Poor error handling | `references/error-handling/rules.md`, `references/error-handling/examples.md` |
+| Messy tests | `references/unit-tests/rules.md`, `references/unit-tests/examples.md` |
+| Any smell | `references/smells/rules.md`, `references/smells/examples.md` |
+
+### By Code Element
+
+| Working with... | Primary | Secondary |
+|-----------------|---------|-----------|
+| Functions | `references/functions/rules.md` | `references/naming/rules.md` |
+| Classes | `references/classes/rules.md` | `references/functions/rules.md` |
+| Modules | `references/classes/rules.md` | `references/naming/rules.md` |
+| Variables | `references/naming/rules.md` | `references/comments/rules.md` |
+| Tests | `references/unit-tests/rules.md` | `references/tdd/rules.md` |
+| Error handling | `references/error-handling/rules.md` | `references/functions/rules.md` |
+| Comments | `references/comments/rules.md` | - |
+
+### By Problem/Symptom
+
+| If you notice... | Load these files |
+|------------------|------------------|
+| Function > 20 lines | `references/functions/rules.md` |
+| Too many arguments (> 3) | `references/functions/rules.md` |
+| Unclear variable name | `references/naming/rules.md` |
+| Class doing too much | `references/classes/rules.md` (SRP) |
+| Duplicate code blocks | `references/smells/rules.md` (G5) |
+| Commented-out code | `references/smells/rules.md` (C5) |
+| Null checks everywhere | `references/error-handling/rules.md` |
+| Hard-to-read tests | `references/unit-tests/rules.md` |
+| Inconsistent formatting | `references/formatting/rules.md` |
+| Feature envy | `references/smells/rules.md` (G14) |
+| God class | `references/classes/rules.md`, `references/smells/rules.md` |
+
+---
+
+## Part 2: Professional Practices References
+
+### By Situation - Communication
+
+| Situation | Load these files |
+|-----------|------------------|
+| Asked to commit to deadline | `references/commitment/rules.md`, `references/saying-no/rules.md` |
+| Need to say no | `references/saying-no/rules.md`, `references/saying-no/examples.md` |
+| Making a promise | `references/commitment/rules.md`, `references/commitment/examples.md` |
+| Providing estimates | `references/estimation/rules.md`, `references/estimation/examples.md` |
+| Under pressure from stakeholders | `references/pressure/rules.md`, `references/saying-no/rules.md` |
+
+### By Situation - Daily Work
+
+| Situation | Load these files |
+|-----------|------------------|
+| Starting TDD workflow | `references/tdd/rules.md`, `references/tdd/examples.md` |
+| Planning test strategy | `references/testing-strategies/rules.md` |
+| Writing acceptance tests | `references/acceptance-testing/rules.md` |
+| Struggling to code | `references/coding-practices/rules.md` |
+| Too many meetings | `references/time-management/rules.md` |
+| Feeling stuck | `references/coding-practices/rules.md` (writer's block) |
+| Working under deadline | `references/pressure/rules.md`, `references/coding-practices/rules.md` |
+
+### By Situation - Team & Career
+
+| Situation | Load these files |
+|-----------|------------------|
+| Working with others | `references/collaboration/rules.md` |
+| Pairing decisions | `references/collaboration/rules.md` |
+| Career development | `references/professionalism/rules.md`, `references/practicing/rules.md` |
+| Improving skills | `references/practicing/rules.md`, `references/practicing/examples.md` |
+| New to team | `references/professionalism/rules.md`, `references/collaboration/rules.md` |
+
+### By Problem - Professional
+
+| If you're facing... | Load these files |
+|---------------------|------------------|
+| Unrealistic deadline | `references/saying-no/rules.md`, `references/estimation/rules.md` |
+| Pressure to cut corners | `references/pressure/rules.md`, `references/professionalism/rules.md` |
+| Estimate treated as commitment | `references/estimation/rules.md` |
+| Too much in meetings | `references/time-management/rules.md` |
+| Stuck in a mess/swamp | `references/time-management/rules.md` (messes section) |
+| Code ownership conflict | `references/collaboration/rules.md` |
+| Not improving skills | `references/practicing/rules.md` |
+
+---
+
+## Decision Tree
+
+```
+What do you need to do?
+│
+├─► KNOWN TASK (use workflow)
+│   │
+│   ├─► Code Tasks
+│   │   ├─► Review code → workflows/code-review/workflow.md
+│   │   ├─► Review PR → workflows/pr-review/workflow.md
+│   │   ├─► Build feature → workflows/new-feature.md
+│   │   ├─► Fix bug → workflows/bug-fix.md
+│   │   ├─► Refactor → workflows/refactoring/workflow.md
+│   │   ├─► Write tests → workflows/tdd.md
+│   │   └─► Plan tests → workflows/test-strategy.md
+│   │
+│   └─► Professional Tasks
+│       ├─► Estimate task → workflows/estimation.md
+│       └─► Negotiate deadline → workflows/deadline-negotiation.md
+│
+├─► NEED REFERENCE (use reference files)
+│   │
+│   ├─► Code Quality
+│   │   ├─► Names → references/naming/rules.md
+│   │   ├─► Functions → references/functions/rules.md
+│   │   ├─► Classes → references/classes/rules.md
+│   │   ├─► Tests → references/unit-tests/rules.md
+│   │   └─► Smells → references/smells/rules.md
+│   │
+│   └─► Professional
+│       ├─► Saying no → references/saying-no/rules.md
+│       ├─► Commitments → references/commitment/rules.md
+│       └─► Estimation → references/estimation/rules.md
+│
+└─► LEARNING (use knowledge files)
+    └─► Start with → references/[topic]/knowledge.md
+```
+
+---
+
+## File Index
+
+### Workflows (9 files)
+
+| Workflow | Purpose |
+|----------|---------|
+| `workflows/code-review/workflow.md` | Review code for quality |
+| `workflows/pr-review/workflow.md` | Review pull requests |
+| `workflows/new-feature.md` | Build new functionality |
+| `workflows/bug-fix.md` | Fix bugs with test coverage |
+| `workflows/refactoring/workflow.md` | Safe refactoring process |
+| `workflows/tdd.md` | Test-driven development |
+| `workflows/test-strategy.md` | Plan test coverage |
+| `workflows/estimation.md` | PERT-based estimation |
+| `workflows/deadline-negotiation.md` | Handle deadline pressure |
+
+### Code Quality References (25 files)
+
+| Category | Files | Purpose |
+|----------|-------|---------|
+| naming | 3 | Variable, function, class naming |
+| functions | 4 | Function design and review |
+| classes | 3 | Class/module design |
+| comments | 3 | Comment best practices |
+| error-handling | 3 | Exception handling |
+| unit-tests | 3 | Clean test principles |
+| formatting | 3 | Code layout |
+| smells | 3 | Code smell catalog |
+
+### Professional Practice References (36 files)
+
+| Category | Files | Purpose |
+|----------|-------|---------|
+| professionalism | 3 | Professional ethics |
+| saying-no | 3 | Declining requests professionally |
+| commitment | 3 | Making real commitments |
+| coding-practices | 3 | Daily coding habits |
+| tdd | 3 | Test-driven development workflow |
+| practicing | 3 | Deliberate practice |
+| acceptance-testing | 3 | Requirements as tests |
+| testing-strategies | 3 | Test pyramid |
+| time-management | 3 | Meetings, focus, priorities |
+| estimation | 3 | Estimating tasks |
+| pressure | 3 | Working under pressure |
+| collaboration | 3 | Working with others |
+
+---
+
+## Common Combinations
+
+| Scenario | Files |
+|----------|-------|
+| Full code review | `workflows/code-review/workflow.md` or `references/functions/checklist.md` + `references/smells/rules.md` |
+| Writing a new feature | `workflows/new-feature.md` |
+| Starting TDD | `workflows/tdd.md` |
+| Test strategy planning | `workflows/test-strategy.md` |
+| Estimate + negotiate | `workflows/estimation.md` + `workflows/deadline-negotiation.md` |
+| Under pressure | `references/pressure/rules.md` + `references/coding-practices/rules.md` |
+| Career growth | `references/professionalism/rules.md` + `references/practicing/rules.md` |
diff --git a/.agents/skills/typescript-clean-code/progress.md b/.agents/skills/typescript-clean-code/progress.md
new file mode 100644
index 0000000..9336ec0
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/progress.md
@@ -0,0 +1,245 @@
+# Clean Code Skill - Creation Progress
+
+## Status Overview
+
+| Phase | Files | Complete |
+|-------|-------|----------|
+| Foundation | 3 | 3/3 |
+| Workflows | 9 | 9/9 |
+| **Code Quality (Clean Code book)** | | |
+| naming | 3 | 3/3 |
+| functions | 4 | 4/4 |
+| comments | 3 | 3/3 |
+| formatting | 3 | 3/3 |
+| error-handling | 3 | 3/3 |
+| unit-tests | 3 | 3/3 |
+| classes | 3 | 3/3 |
+| smells | 3 | 3/3 |
+| **Professional Practices (Clean Coder book)** | | |
+| professionalism | 3 | 3/3 |
+| saying-no | 3 | 3/3 |
+| commitment | 3 | 3/3 |
+| coding-practices | 3 | 3/3 |
+| tdd | 3 | 3/3 |
+| practicing | 3 | 3/3 |
+| acceptance-testing | 3 | 3/3 |
+| testing-strategies | 3 | 3/3 |
+| time-management | 3 | 3/3 |
+| estimation | 3 | 3/3 |
+| pressure | 3 | 3/3 |
+| collaboration | 3 | 3/3 |
+| **Total** | **73** | **73/73** |
+
+## Legend
+
+- [ ] Not started
+- [~] In progress  
+- [x] Completed
+- [-] Skipped/Not needed
+
+---
+
+## Foundation
+
+- [x] SKILL.md
+- [x] progress.md
+- [x] guidelines.md
+
+## Workflows
+
+- [x] workflows/code-review/workflow.md - Review code for quality (step-file architecture: 10 step files)
+- [x] workflows/pr-review/workflow.md - Review pull requests (step-file architecture: 10 step files)
+- [x] workflows/tdd.md - Test-driven development cycle
+- [x] workflows/refactoring/workflow.md - Safe refactoring with tests (step-file architecture: 8 step files)
+- [x] workflows/new-feature.md - Building new functionality
+- [x] workflows/bug-fix.md - Fixing bugs properly
+- [x] workflows/test-strategy.md - Planning test coverage
+- [x] workflows/estimation.md - PERT-based task estimation
+- [x] workflows/deadline-negotiation.md - Handling deadline pressure
+
+### Step-File Workflows (new)
+
+Code review, PR review, and refactoring workflows converted to step-file architecture for context-safe execution. Original files preserved as `.legacy.md`.
+
+- [x] workflows/code-review.legacy.md (original, preserved for reference)
+- [x] workflows/pr-review.legacy.md (original, preserved for reference)
+- [x] workflows/refactoring.legacy.md (original, preserved for reference)
+
+---
+
+## Part 1: Code Quality (Clean Code book)
+
+### naming
+
+Source: Clean Code, Chapter 2 (lines 749-1179)
+
+- [x] references/naming/knowledge.md
+- [x] references/naming/rules.md
+- [x] references/naming/examples.md
+
+### functions
+
+Source: Clean Code, Chapter 3 (lines 1190-1889)
+
+- [x] references/functions/knowledge.md
+- [x] references/functions/rules.md
+- [x] references/functions/examples.md
+- [x] references/functions/checklist.md
+
+### comments
+
+Source: Clean Code, Chapter 4 (lines 1889-2848)
+
+- [x] references/comments/knowledge.md
+- [x] references/comments/rules.md
+- [x] references/comments/examples.md
+
+### formatting
+
+Source: Clean Code, Chapter 5 (lines 2848-3455)
+
+- [x] references/formatting/knowledge.md
+- [x] references/formatting/rules.md
+- [x] references/formatting/examples.md
+
+### error-handling
+
+Source: Clean Code, Chapter 7 (lines 3772-4165)
+
+- [x] references/error-handling/knowledge.md
+- [x] references/error-handling/rules.md
+- [x] references/error-handling/examples.md
+
+### unit-tests
+
+Source: Clean Code, Chapter 9 (lines 4381-4785)
+
+- [x] references/unit-tests/knowledge.md
+- [x] references/unit-tests/rules.md
+- [x] references/unit-tests/examples.md
+
+### classes
+
+Source: Clean Code, Chapter 10 (lines 4785-5417)
+
+- [x] references/classes/knowledge.md
+- [x] references/classes/rules.md
+- [x] references/classes/examples.md
+
+### smells
+
+Source: Clean Code, Chapter 17 (lines 10864-11962)
+
+- [x] references/smells/knowledge.md
+- [x] references/smells/rules.md
+- [x] references/smells/examples.md
+
+---
+
+## Part 2: Professional Practices (Clean Coder book)
+
+### professionalism
+
+Source: Clean Coder, Chapter 1 (lines 822-1083)
+
+- [x] references/professionalism/knowledge.md
+- [x] references/professionalism/rules.md
+- [x] references/professionalism/examples.md
+
+### saying-no
+
+Source: Clean Coder, Chapter 2 (lines 1083-1573)
+
+- [x] references/saying-no/knowledge.md
+- [x] references/saying-no/rules.md
+- [x] references/saying-no/examples.md
+
+### commitment
+
+Source: Clean Coder, Chapter 3 (lines 1573-1811)
+
+- [x] references/commitment/knowledge.md
+- [x] references/commitment/rules.md
+- [x] references/commitment/examples.md
+
+### coding-practices
+
+Source: Clean Coder, Chapter 4 (lines 1811-2105)
+
+- [x] references/coding-practices/knowledge.md
+- [x] references/coding-practices/rules.md
+- [x] references/coding-practices/examples.md
+
+### tdd
+
+Source: Clean Coder, Chapter 5 (lines 2105-2235)
+
+- [x] references/tdd/knowledge.md
+- [x] references/tdd/rules.md
+- [x] references/tdd/examples.md
+
+### practicing
+
+Source: Clean Coder, Chapter 6 (lines 2235-2387)
+
+- [x] references/practicing/knowledge.md
+- [x] references/practicing/rules.md
+- [x] references/practicing/examples.md
+
+### acceptance-testing
+
+Source: Clean Coder, Chapter 7 (lines 2387-2804)
+
+- [x] references/acceptance-testing/knowledge.md
+- [x] references/acceptance-testing/rules.md
+- [x] references/acceptance-testing/examples.md
+
+### testing-strategies
+
+Source: Clean Coder, Chapter 8 (lines 2804-2903)
+
+- [x] references/testing-strategies/knowledge.md
+- [x] references/testing-strategies/rules.md
+- [x] references/testing-strategies/examples.md
+
+### time-management
+
+Source: Clean Coder, Chapter 9 (lines 2903-3122)
+
+- [x] references/time-management/knowledge.md
+- [x] references/time-management/rules.md
+- [x] references/time-management/examples.md
+
+### estimation
+
+Source: Clean Coder, Chapter 10 (lines 3122-3361)
+
+- [x] references/estimation/knowledge.md
+- [x] references/estimation/rules.md
+- [x] references/estimation/examples.md
+
+### pressure
+
+Source: Clean Coder, Chapter 11 (lines 3361-3457)
+
+- [x] references/pressure/knowledge.md
+- [x] references/pressure/rules.md
+- [x] references/pressure/examples.md
+
+### collaboration
+
+Source: Clean Coder, Chapter 12 (lines 3457-3543)
+
+- [x] references/collaboration/knowledge.md
+- [x] references/collaboration/rules.md
+- [x] references/collaboration/examples.md
+
+---
+
+## Notes
+
+- Part 1 (Clean Code): All Java examples converted to TypeScript
+- Part 2 (Clean Coder): Professional practices, scenario-based examples
+- Workflows: Step-by-step processes for consistent task execution
+- Skipped: Java-specific chapters, case studies, appendices
+- Completed: 2026-01-26
diff --git a/.agents/skills/typescript-clean-code/references/acceptance-testing/examples.md b/.agents/skills/typescript-clean-code/references/acceptance-testing/examples.md
new file mode 100644
index 0000000..2ead7d7
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/acceptance-testing/examples.md
@@ -0,0 +1,200 @@
+# Acceptance Testing Examples
+
+Code examples demonstrating acceptance testing principles in modern TypeScript/Gherkin style.
+
+## Bad Examples
+
+### Vague Requirement Without Test
+
+```typescript
+// Requirement: "Log files need to be backed up daily"
+// No acceptance test - ambiguity remains:
+// - Backup one file or all files?
+// - Keep history or overwrite?
+// - What time of day?
+```
+
+**Problems**:
+- Developers interpret differently than stakeholders
+- No formal definition of "done"
+- Bugs discovered only after deployment
+
+### GUI Position-Based Test
+
+```typescript
+// Bad: Tests break when layout changes
+test('submit form', async ({ page }) => {
+  await page.click('button:nth-child(3)');  // Position-based
+  await page.click('div.grid > div:nth-child(4) > button');
+});
+```
+
+**Problems**:
+- Fragile - breaks on any layout change
+- Hard to understand intent
+- Maintenance nightmare
+
+### Testing Business Rules Through GUI
+
+```typescript
+// Bad: Business logic tested through UI layer
+test('calculate discount', async ({ page }) => {
+  await page.goto('/checkout');
+  await page.fill('#quantity', '100');
+  await page.fill('#coupon', 'SAVE20');
+  await page.click('#calculate');
+  await expect(page.locator('#total')).toContainText('$800');
+});
+```
+
+**Problems**:
+- Slow execution through full UI
+- Breaks when UI changes
+- Business rule buried in GUI test
+
+## Good Examples
+
+### Gherkin Feature Specification
+
+```gherkin
+Feature: Log File Backup
+  As a system administrator
+  I want log files archived daily
+  So that I can review historical logs for audits
+
+  Scenario: Create backup directory on startup
+    Given the command LogFileDirectoryStartupCommand
+    And the old_inactive_logs directory does not exist
+    When the command is executed
+    Then the old_inactive_logs directory should exist
+    And it should be empty
+
+  Scenario: Preserve existing backups on restart
+    Given the command LogFileDirectoryStartupCommand
+    And the old_inactive_logs directory exists
+    And it contains a file named "2024-01-15.log"
+    When the command is executed
+    Then the old_inactive_logs directory should still exist
+    And it should still contain a file named "2024-01-15.log"
+```
+
+**Why it works**:
+- Unambiguous specification
+- Readable by business stakeholders
+- Executable documentation
+
+### Step Definitions in TypeScript
+
+```typescript
+import { Given, When, Then } from '@cucumber/cucumber';
+import { LogFileDirectoryStartupCommand } from '../src/commands';
+import * as fs from 'fs';
+
+const LOG_DIR = './old_inactive_logs';
+let command: LogFileDirectoryStartupCommand;
+
+Given('the command LogFileDirectoryStartupCommand', () => {
+  command = new LogFileDirectoryStartupCommand();
+});
+
+Given('the old_inactive_logs directory does not exist', () => {
+  if (fs.existsSync(LOG_DIR)) fs.rmSync(LOG_DIR, { recursive: true });
+});
+
+When('the command is executed', async () => {
+  await command.execute();
+});
+
+Then('the old_inactive_logs directory should exist', () => {
+  expect(fs.existsSync(LOG_DIR)).toBe(true);
+});
+```
+
+**Why it works**:
+- Tests through command API, not GUI
+- Reusable step definitions
+- Clear mapping from spec to code
+
+### Statistical Performance Test
+
+```gherkin
+Scenario: Response time meets SLA
+  When 15 post transactions are executed
+  Then the odds should be 99.5% that response time is less than 2 seconds
+```
+
+**Why it works**:
+- Statistical guarantee instead of impossible absolute
+- Negotiated with stakeholders for realistic criteria
+- Business-readable requirement
+
+### Testing Through API, Not GUI
+
+```typescript
+// Good: Test business rules through service layer
+describe('Discount Calculator', () => {
+  it('applies 20% discount for orders over $1000', async () => {
+    const order = new Order({ items: [{ price: 100, quantity: 12 }], couponCode: 'SAVE20' });
+    const result = await discountService.calculateTotal(order);
+    expect(result.total).toBe(960);  // 20% off $1200
+  });
+});
+
+// Separate: Minimal GUI test with stubbed business logic
+describe('Checkout UI', () => {
+  it('displays calculated total', async ({ page }) => {
+    await mockDiscountService({ total: 960 });
+    await page.goto('/checkout');
+    await expect(page.getByTestId('total')).toContainText('$960');
+  });
+});
+```
+
+**Why it works**:
+- Business rules tested fast through API
+- GUI tests only verify display logic
+- GUI changes don't break business tests
+
+## Refactoring Walkthrough
+
+### Before: Ambiguous Manual Process
+
+```
+Requirements Document:
+"The system shall backup log files daily."
+
+Manual Test Plan:
+1. Wait until midnight
+2. Check if backup exists
+3. Mark pass/fail in spreadsheet
+```
+
+### After: Executable Specification
+
+```gherkin
+Feature: Daily Log Backup
+
+  Background:
+    Given the system clock can be controlled
+    And the backup service is initialized
+
+  Scenario: Midnight triggers backup of current log
+    Given today is "2024-01-15"
+    And the active log file contains 500 entries
+    When the clock reaches midnight
+    Then a file "2024-01-15.log" should exist in old_inactive_logs
+    And it should contain 500 entries
+    And a new empty active log should be created
+
+  Scenario: Backup preserves all historical logs
+    Given old_inactive_logs contains 30 log files
+    When a new backup is triggered
+    Then old_inactive_logs should contain 31 log files
+```
+
+### Changes Made
+
+1. **Converted prose to scenarios** - Each behavior is testable
+2. **Added specific assertions** - "500 entries" not "backup exists"
+3. **Made time controllable** - No waiting for midnight
+4. **Specified edge cases** - Historical logs preserved
diff --git a/.agents/skills/typescript-clean-code/references/acceptance-testing/knowledge.md b/.agents/skills/typescript-clean-code/references/acceptance-testing/knowledge.md
new file mode 100644
index 0000000..7859a2d
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/acceptance-testing/knowledge.md
@@ -0,0 +1,101 @@
+# Acceptance Testing Knowledge
+
+Core concepts and foundational understanding for acceptance testing as a communication and specification tool.
+
+## Overview
+
+Acceptance tests are formal specifications written collaboratively by stakeholders, testers, and developers to define when a requirement is truly "done." They serve primarily as communication tools that eliminate ambiguity, not just as verification mechanisms. The tests become executable requirements documents that cannot get out of sync with the application.
+
+## Key Concepts
+
+### Acceptance Tests as Communication
+
+**Definition**: Tests written by collaboration of stakeholders and programmers to define when a requirement is complete.
+
+Acceptance tests are documents first, tests second. Their primary purpose is to formally specify system behavior in unambiguous terms that all parties understand.
+
+**Key points**:
+- Eliminate communication errors between programmers and stakeholders
+- Force precision in requirements discussions
+- Create shared understanding of expected behavior
+
+### The Definition of "Done"
+
+**Definition**: Done means all code written, all tests pass, QA and stakeholders have accepted.
+
+Professional developers have a single, unambiguous definition of done. When acceptance tests pass, the feature is complete and ready for deployment.
+
+**Key points**:
+- Not "done" vs "done-done" - just done
+- Automated tests define the finish line
+- Eliminates ambiguity about completion status
+
+### Premature Precision
+
+**Definition**: The trap of trying to specify requirements with exact detail too early in the process.
+
+Both business and developers want precision before it's achievable. Business wants to know exactly what they'll get; developers want to know exactly what to build. This precision cannot be achieved early and wastes resources.
+
+**Key points**:
+- Requirements appear different on paper vs. running system
+- Stakeholders change minds when they see working software
+- Early precision becomes irrelevant as understanding evolves
+
+### The Uncertainty Principle (Requirements)
+
+**Definition**: Demonstrating a feature gives stakeholders new information that changes how they see the whole system.
+
+When you show working software, stakeholders gain insight that impacts their view of requirements. The more precise early requirements are, the less relevant they become during implementation.
+
+### Late Ambiguity
+
+**Definition**: Unresolved disagreements or assumptions hidden in vague requirement language.
+
+Stakeholders may "wordsmith" around disagreements rather than resolve them. Ambiguity in requirements often represents unresolved arguments or unstated assumptions.
+
+**Key points**:
+- Defer precision as long as possible, but resolve ambiguity before coding
+- Context differs between stakeholders and developers
+- Professional developers ensure all ambiguity is removed
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Acceptance Test | Automated test defining when a requirement is done |
+| Happy Path | Tests describing features with business value |
+| Unhappy Path | Tests for boundary conditions, exceptions, corner cases |
+| Fixture | Code connecting test statements to the system under test |
+| Scenario | Reusable test pattern matching statements to functions |
+
+## How It Relates To
+
+- **Unit Tests**: Different audience and purpose; unit tests are for programmers, acceptance tests are for business
+- **Requirements Documents**: Acceptance tests ARE the requirements, but executable
+- **Continuous Integration**: All acceptance tests should run on every commit
+- **Definition of Done**: Acceptance tests formally define completion criteria
+
+## Common Misconceptions
+
+- **Myth**: Acceptance tests are extra work on top of requirements
+  **Reality**: They ARE the work of specifying requirements, just in executable form
+
+- **Myth**: Unit tests and acceptance tests are redundant
+  **Reality**: They test through different pathways and serve different audiences
+
+- **Myth**: Acceptance tests are primarily for verification
+  **Reality**: Their primary purpose is specification and communication; verification is secondary
+
+- **Myth**: Stakeholders should write all acceptance tests
+  **Reality**: Collaboration is key; BAs write happy paths, QA writes edge cases, developers may help
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Acceptance Tests | Executable requirements written collaboratively |
+| Definition of Done | All tests pass, QA and stakeholders accept |
+| Premature Precision | Specifying details too early wastes effort |
+| Uncertainty Principle | Seeing software changes stakeholder understanding |
+| Late Ambiguity | Hidden disagreements in vague requirements |
+| Communication Purpose | Tests eliminate ambiguity between all parties |
diff --git a/.agents/skills/typescript-clean-code/references/acceptance-testing/rules.md b/.agents/skills/typescript-clean-code/references/acceptance-testing/rules.md
new file mode 100644
index 0000000..46e8a4f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/acceptance-testing/rules.md
@@ -0,0 +1,119 @@
+# Acceptance Testing Rules
+
+Rules for writing, managing, and executing acceptance tests as professional developers.
+
+## Core Rules
+
+### 1. Always Automate Acceptance Tests
+
+Acceptance tests must always be automated. Manual test plans are economically unsustainable.
+
+- Manual testing costs grow with each execution
+- Automated tests can run multiple times daily
+- Manual tests get cut when budgets tighten, leaving gaps in coverage
+
+**The cost comparison**: A manual test plan costing $1M+ per execution vs. one-time automation investment.
+
+### 2. Define "Done" With Passing Tests
+
+Done means done: all code written, all tests pass, QA and stakeholders accept.
+
+- Create automated tests that define completion criteria
+- When acceptance tests pass, the feature is deployable
+- No ambiguous states like "done" vs "done-done"
+
+### 3. Write Tests Late, But Before Implementation
+
+Follow "late precision" - write acceptance tests just before implementing the feature.
+
+- Tests should be ready by the first day of iteration/sprint
+- All tests ready by iteration midpoint
+- If tests aren't ready, developers help complete them
+
+### 4. Separate Test Authors From Implementers
+
+The developer who writes the test should not implement the tested feature.
+
+- Business analysts write happy path tests (business value)
+- QA writes unhappy path tests (edge cases, exceptions)
+- Developers review for consistency and feasibility
+
+### 5. Never Be Passive-Aggressive With Tests
+
+If a test doesn't make sense, negotiate - don't blindly implement.
+
+- Tests may be too complicated, awkward, or wrong
+- Professionals help the team create the best software
+- "That's what the test says" is not a valid excuse
+
+**Bad approach**:
+```
+// Test says 2-second guarantee, so I'll implement exactly that
+// even though it's statistically impossible
+```
+
+**Good approach**:
+```
+// Negotiate with test author for realistic criteria
+// e.g., "99.5% of requests complete in 2 seconds"
+```
+
+### 6. Test Through APIs, Not GUIs
+
+Write business rule tests through an API below the GUI.
+
+- GUIs change frequently, making tests fragile
+- GUI changes shouldn't break business rule tests
+- Keep GUI-specific tests minimal
+- Decouple GUI from business rules for testing
+
+### 7. Keep CI Tests Always Passing
+
+Broken tests in continuous integration are emergencies.
+
+- Run all tests on every commit
+- Failed tests = "stop the presses"
+- Never disable failing tests to meet deadlines
+- Never remove tests from the build
+
+## Guidelines
+
+Less strict recommendations for effective acceptance testing:
+
+- Use unique IDs for GUI elements rather than positional selectors
+- Make intermediate calculations visible in test reports for verification
+- Create reusable scenarios and fixtures across tests
+- Include error bars in estimates when requirements are imprecise
+- Involve testers early in requirements discussions
+
+## Exceptions
+
+When rules may be relaxed:
+
+- **Manual testing**: Acceptable for exploratory testing and aesthetics, but not for acceptance criteria
+- **Developer-written tests**: When stakeholders lack time, developers may write tests - but not for features they implement
+- **GUI testing**: Necessary when testing GUI behavior specifically, but use stubs for business rules
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Automate | Never use manual acceptance tests |
+| Define Done | Passing tests = feature complete |
+| Late Precision | Write tests just before implementation |
+| Separate Authors | Test writer != implementer |
+| Negotiate Tests | Push back on problematic tests |
+| API Over GUI | Test business rules below UI layer |
+| CI Always Green | Broken build = emergency |
+
+## Acceptance Tests vs Unit Tests
+
+| Aspect | Acceptance Tests | Unit Tests |
+|--------|-----------------|------------|
+| Written by | Business/QA/BAs | Programmers |
+| Written for | Business + Programmers | Programmers |
+| Tests through | API or UI level | Method calls |
+| Documents | System behavior | Code structure |
+| Primary purpose | Specification | Design documentation |
+
+Both test similar things through different pathways - neither is redundant.
diff --git a/.agents/skills/typescript-clean-code/references/classes/examples.md b/.agents/skills/typescript-clean-code/references/classes/examples.md
new file mode 100644
index 0000000..ab1a7fe
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/classes/examples.md
@@ -0,0 +1,200 @@
+# Classes Examples
+
+Code examples demonstrating clean class design principles in TypeScript.
+
+## Bad Examples
+
+### God Class with Too Many Responsibilities
+
+```typescript
+class SuperDashboard {
+  getLastFocusedComponent(): Component { }
+  setLastFocused(component: Component): void { }
+  getMajorVersionNumber(): number { }
+  getMinorVersionNumber(): number { }
+  getBuildNumber(): number { }
+  getProject(): Project { }
+  addProject(project: Project): void { }
+  getConfigManager(): ConfigManager { }
+  // ... 60+ more methods
+}
+```
+
+**Problems**:
+- Multiple reasons to change (versioning, UI focus, projects, config)
+- Name uses "Super" - a weasel word indicating too many responsibilities
+
+### Class Violating Open-Closed Principle
+
+```typescript
+class Sql {
+  constructor(private table: string, private columns: Column[]) { }
+  create(): string { }
+  insert(fields: object[]): string { }
+  selectAll(): string { }
+  select(criteria: Criteria): string { }
+  private columnList(): string { }
+  private valuesList(fields: object[]): string { }
+}
+```
+
+**Problems**:
+- Must open class to add new statement types (UPDATE, DELETE)
+- Private methods relate only to specific public methods (hints at extraction)
+
+### Concrete Dependency Making Testing Hard
+
+```typescript
+class Portfolio {
+  private exchange = new TokyoStockExchange();
+  
+  getValue(): Money {
+    return this.holdings.reduce((total, h) => {
+      const price = this.exchange.currentPrice(h.symbol);
+      return total.add(price.times(h.shares));
+    }, Money.zero());
+  }
+}
+```
+
+**Problems**:
+- Cannot test without hitting real stock exchange API
+- Test results vary based on actual stock prices
+
+## Good Examples
+
+### Single Responsibility - Version Class
+
+```typescript
+class Version {
+  constructor(
+    private readonly major: number,
+    private readonly minor: number,
+    private readonly build: number
+  ) { }
+
+  getMajorVersionNumber(): number { return this.major; }
+  getMinorVersionNumber(): number { return this.minor; }
+  getBuildNumber(): number { return this.build; }
+  toString(): string { return `${this.major}.${this.minor}.${this.build}`; }
+}
+```
+
+**Why it works**: Single responsibility, one reason to change, highly reusable.
+
+### Highly Cohesive Class
+
+```typescript
+class Stack<T> {
+  private topOfStack = 0;
+  private elements: T[] = [];
+
+  size(): number { return this.topOfStack; }
+
+  push(element: T): void {
+    this.topOfStack++;
+    this.elements.push(element);
+  }
+
+  pop(): T {
+    if (this.topOfStack === 0) throw new Error('Stack is empty');
+    this.topOfStack--;
+    return this.elements.pop()!;
+  }
+}
+```
+
+**Why it works**: All methods use shared instance variables, forming a logical whole.
+
+### Dependency Injection for Testability
+
+```typescript
+interface StockExchange {
+  currentPrice(symbol: string): Money;
+}
+
+class Portfolio {
+  constructor(private readonly exchange: StockExchange) { }
+
+  getValue(): Money {
+    return this.holdings.reduce((total, h) => {
+      const price = this.exchange.currentPrice(h.symbol);
+      return total.add(price.times(h.shares));
+    }, Money.zero());
+  }
+}
+
+// Test stub
+class FixedStockExchangeStub implements StockExchange {
+  private prices = new Map<string, number>();
+  fix(symbol: string, price: number): void { this.prices.set(symbol, price); }
+  currentPrice(symbol: string): Money { return Money.dollars(this.prices.get(symbol) ?? 0); }
+}
+```
+
+**Why it works**: Depends on abstraction, easy to test with stub.
+
+## Refactoring Walkthrough
+
+### Before: Monolithic SQL Class
+
+```typescript
+class Sql {
+  constructor(private table: string, private columns: Column[]) { }
+  create(): string { /* ... */ }
+  insert(fields: object[]): string { /* ... */ }
+  selectAll(): string { /* ... */ }
+  private columnList(): string { /* ... */ }
+}
+```
+
+### After: Family of Single-Purpose Classes
+
+```typescript
+abstract class Sql {
+  constructor(protected table: string, protected columns: Column[]) { }
+  abstract generate(): string;
+}
+
+class CreateSql extends Sql {
+  generate(): string {
+    const defs = this.columns.map(c => `${c.name} ${c.type}`).join(', ');
+    return `CREATE TABLE ${this.table} (${defs})`;
+  }
+}
+
+class SelectSql extends Sql {
+  generate(): string {
+    return `SELECT ${new ColumnList(this.columns).generate()} FROM ${this.table}`;
+  }
+}
+
+class InsertSql extends Sql {
+  constructor(table: string, columns: Column[], private fields: object[]) { super(table, columns); }
+  generate(): string {
+    const cols = new ColumnList(this.columns).generate();
+    return `INSERT INTO ${this.table} (${cols}) VALUES (${this.fields.map(f => `'${f}'`).join(', ')})`;
+  }
+}
+
+// Adding UPDATE requires NO changes to existing classes
+class UpdateSql extends Sql {
+  constructor(table: string, columns: Column[], private values: Record<string, unknown>, private where: string) { super(table, columns); }
+  generate(): string {
+    return `UPDATE ${this.table} SET ${Object.entries(this.values).map(([k, v]) => `${k} = '${v}'`).join(', ')} WHERE ${this.where}`;
+  }
+}
+
+class ColumnList {
+  constructor(private columns: Column[]) { }
+  generate(): string { return this.columns.map(c => c.name).join(', '); }
+}
+```
+
+### Changes Made
+
+1. **Extracted abstract base class** - Common structure shared by all SQL types
+2. **Created subclass per statement type** - Each has single responsibility
+3. **Moved private methods** - `valuesList` now lives only where needed
+4. **Extracted shared utilities** - `ColumnList` for common formatting
+5. **Open for extension** - Adding `UpdateSql` required zero changes to existing classes
diff --git a/.agents/skills/typescript-clean-code/references/classes/knowledge.md b/.agents/skills/typescript-clean-code/references/classes/knowledge.md
new file mode 100644
index 0000000..16ee37d
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/classes/knowledge.md
@@ -0,0 +1,115 @@
+# Classes Knowledge
+
+Core concepts and foundational understanding for designing clean classes and modules.
+
+## Overview
+
+Classes are the higher-level organizational units of code. While functions handle blocks of code, classes organize functions and data into cohesive units with clear responsibilities. Clean classes are small (measured by responsibilities, not lines), highly cohesive, and loosely coupled.
+
+## Key Concepts
+
+### Class Organization
+
+**Definition**: The standard ordering of elements within a class file.
+
+Classes should follow a consistent structure for readability:
+
+**Ordering (top to bottom)**:
+- Public static constants
+- Private static variables
+- Private instance variables (rarely public)
+- Public methods
+- Private utility methods (placed after the public method that calls them)
+
+This follows the "stepdown rule" - the class reads like a newspaper article.
+
+### Encapsulation
+
+**Definition**: Keeping variables and utility functions private, exposing only what's necessary.
+
+**Key points**:
+- Default to private for variables and helper methods
+- Use protected only when tests require access (same package)
+- Loosening encapsulation is always a last resort
+- Tests can justify relaxing access, but first look for alternatives
+
+### Single Responsibility Principle (SRP)
+
+**Definition**: A class should have one, and only one, reason to change.
+
+SRP is the most important concept in class design. A "responsibility" equals a "reason to change."
+
+**Key points**:
+- The class name should describe its single responsibility
+- If you need "and," "or," "if," or "but" to describe it, it's too big
+- Weasel words hint at multiple responsibilities: `Processor`, `Manager`, `Super`, `Handler`
+- A 25-word description without conjunctions is a good test
+
+### Cohesion
+
+**Definition**: The degree to which methods use the class's instance variables.
+
+A highly cohesive class has methods that work together with shared state.
+
+**Key points**:
+- Each method should manipulate one or more instance variables
+- More shared variable usage = higher cohesion
+- When cohesion drops, it signals time to split the class
+- Ideal: variables exist because multiple methods need them together
+
+### Open-Closed Principle (OCP)
+
+**Definition**: Classes should be open for extension but closed for modification.
+
+**Key points**:
+- Add new functionality by creating new classes (subclasses)
+- Existing classes should not need modification for new features
+- Reduces risk when adding features to a system
+
+### Dependency Inversion Principle (DIP)
+
+**Definition**: Classes should depend upon abstractions, not concrete details.
+
+**Key points**:
+- Use interfaces to decouple from implementation details
+- Makes testing easier (can substitute test doubles)
+- Promotes flexibility and reuse
+- Isolates classes from changes in dependencies
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Responsibility | A reason for a class to change |
+| Cohesion | How closely methods relate via shared instance variables |
+| Coupling | Degree of interdependence between classes |
+| God Class | A class that knows/does too much (anti-pattern) |
+| Abstraction | Interface or abstract class representing a concept |
+
+## How It Relates To
+
+- **Functions**: Classes organize functions; both should be small and focused
+- **Modules**: TypeScript modules follow similar principles - single responsibility, cohesion
+- **Testing**: Decoupled classes are easier to test in isolation
+- **Refactoring**: Breaking large classes maintains cohesion as code evolves
+
+## Common Misconceptions
+
+- **Myth**: Many small classes are harder to understand than few large ones
+  **Reality**: The total complexity is the same; small classes make it easier to find and understand relevant code
+
+- **Myth**: A class with few methods is small enough
+  **Reality**: Size is measured by responsibilities, not method count - 5 methods with 2 responsibilities is too big
+
+- **Myth**: Encapsulation must never be broken
+  **Reality**: Tests can justify protected access when no other option exists
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| SRP | One reason to change per class |
+| Cohesion | Methods should share instance variables |
+| OCP | Extend, don't modify |
+| DIP | Depend on abstractions |
+| Organization | Constants, variables, public methods, private methods |
diff --git a/.agents/skills/typescript-clean-code/references/classes/rules.md b/.agents/skills/typescript-clean-code/references/classes/rules.md
new file mode 100644
index 0000000..1eaae8a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/classes/rules.md
@@ -0,0 +1,147 @@
+# Classes Rules
+
+Guidelines for designing clean, maintainable classes and modules in TypeScript.
+
+## Core Rules
+
+### 1. Classes Should Be Small (Measured by Responsibilities)
+
+Size is measured by counting responsibilities, not lines of code.
+
+- A class should have ONE reason to change
+- If the class name needs weasel words (`Manager`, `Processor`, `Handler`, `Super`), it's too big
+- You should describe the class in ~25 words without "if," "and," "or," or "but"
+
+**Example**:
+```typescript
+// Bad - multiple responsibilities
+class SuperDashboard {
+  getLastFocusedComponent(): Component { }
+  setLastFocused(component: Component): void { }
+  getMajorVersionNumber(): number { }
+  getMinorVersionNumber(): number { }
+  getBuildNumber(): number { }
+}
+
+// Good - single responsibility extracted
+class Version {
+  getMajorVersionNumber(): number { }
+  getMinorVersionNumber(): number { }
+  getBuildNumber(): number { }
+}
+```
+
+### 2. Follow the Single Responsibility Principle (SRP)
+
+Every class should have one, and only one, reason to change.
+
+- Identify responsibilities by asking "what would cause this class to change?"
+- Different reasons to change = different classes
+- Extract responsibilities into their own classes
+
+### 3. Maintain High Cohesion
+
+Methods should use the class's instance variables.
+
+- Each method should manipulate one or more instance variables
+- If a subset of variables is only used by a subset of methods, consider splitting
+- When cohesion drops after extracting functions, split the class
+
+**Example**:
+```typescript
+// Good - highly cohesive
+class Stack<T> {
+  private topOfStack = 0;
+  private elements: T[] = [];
+
+  size(): number {
+    return this.topOfStack;
+  }
+
+  push(element: T): void {
+    this.topOfStack++;
+    this.elements.push(element);
+  }
+
+  pop(): T {
+    if (this.topOfStack === 0) throw new Error('Stack is empty');
+    this.topOfStack--;
+    return this.elements.pop()!;
+  }
+}
+```
+
+### 4. Organize for Change (Open-Closed Principle)
+
+Structure classes to minimize modification when adding features.
+
+- Prefer extension over modification
+- New features should be new classes, not changes to existing ones
+- Private methods used by only one public method may indicate extraction opportunity
+
+### 5. Isolate from Change (Dependency Inversion)
+
+Depend on abstractions, not concrete implementations.
+
+- Use interfaces to decouple from external dependencies
+- Inject dependencies through constructors
+- Enables testing with mocks/stubs
+
+**Example**:
+```typescript
+// Bad - depends on concrete class
+class Portfolio {
+  private exchange = new TokyoStockExchange();
+  
+  getValue(): Money { }
+}
+
+// Good - depends on abstraction
+interface StockExchange {
+  currentPrice(symbol: string): Money;
+}
+
+class Portfolio {
+  constructor(private exchange: StockExchange) { }
+  
+  getValue(): Money { }
+}
+```
+
+### 6. Follow Standard Class Organization
+
+Order elements consistently within a class.
+
+- Public static constants first
+- Private static variables
+- Private instance variables
+- Public methods
+- Private methods (after the public method that calls them)
+
+## Guidelines
+
+Less strict recommendations:
+
+- Prefer many small, single-purpose classes over few large ones
+- When breaking up functions creates shared variables, consider if those variables define a new class
+- Tests can justify relaxing encapsulation (protected access), but try other approaches first
+- A class that is "logically complete" with no anticipated changes can stay as-is
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Testing**: Make methods/properties protected when tests need access (last resort)
+- **Stable code**: Don't preemptively split a class if no changes are anticipated
+- **Simple utilities**: Pure utility functions may stay together if truly cohesive
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Small classes | Measure by responsibilities, not lines |
+| SRP | One reason to change |
+| Cohesion | Methods share instance variables |
+| OCP | Extend, don't modify |
+| DIP | Depend on abstractions |
+| Organization | Constants > variables > public > private |
diff --git a/.agents/skills/typescript-clean-code/references/coding-practices/examples.md b/.agents/skills/typescript-clean-code/references/coding-practices/examples.md
new file mode 100644
index 0000000..91440af
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/coding-practices/examples.md
@@ -0,0 +1,195 @@
+# Coding Practices Examples
+
+Scenarios demonstrating professional vs unprofessional coding behavior.
+
+## Bad Scenarios
+
+### The 3 AM Hero
+
+**Situation**: Developer works 18-hour days, 60-70 hour weeks, feeling dedicated and professional. At 3 AM, solves a timing problem by having code send messages to itself.
+
+**What happened**:
+- The "solution" instituted a faulty design structure
+- Everyone had to work around it constantly
+- Caused strange timing errors and infinite loops
+- Became team cruft surrounded by workarounds
+- Years of accumulated patches and side effects
+
+**Problems**:
+- Tired brain chose wrong solution that "looked good enough"
+- Confusion of long hours with professionalism
+- Technical debt that lasted years
+- Team morale impact (became a running joke)
+
+**Lesson**: Dedication is about discipline, not hours. Eight good hours beats eighteen exhausted ones.
+
+---
+
+### The Worried Coder
+
+**Situation**: Developer has argument with spouse, then tries to code. Sits with eyes on screen, fingers on keyboard, doing nothing.
+
+**What happened**:
+- Background process runs in mind reviewing the argument
+- Physical stress felt in chest and stomach
+- Forces self to write a line or two, but can't sustain
+- Descends into "stupefied insensibility"
+- Any code produced is trash
+
+**Problems**:
+- Wasted time producing nothing
+- Code produced needs rework
+- Prolonged personal issue by not addressing it
+
+**Better approach**: Spend a dedicated hour addressing the worry, then return to coding with clearer mind.
+
+---
+
+### The Zone Addict
+
+**Situation**: Developer measures self-worth by time spent in the Zone, enjoying the euphoria and sense of conquest.
+
+**What happened**:
+- Wrote more code, went through TDD loops faster
+- Lost big-picture perspective
+- Made decisions that needed reversal later
+- Snapped at colleagues who interrupted
+
+**Problems**:
+- Net productivity lower due to rework
+- Damaged team relationships
+- Missed better design solutions
+
+**Better approach**: Walk away when feeling the Zone coming on; find a pair partner.
+
+---
+
+### The Hope-Based Estimate
+
+**Situation**: Trade show in 10 days. Developer's three-number estimate is 8/12/20 days. Developer hopes to make it in 10.
+
+**What happened**:
+- Didn't communicate reality to stakeholders
+- Took shortcuts, worked extra hours
+- Team had false hope
+- Delayed necessary tough decisions
+- Missed deadline anyway
+
+**Problems**:
+- Hope destroyed schedule and reputation
+- Everyone avoided facing the real issue
+- No fall-back plan was created
+- Rushed code created technical debt
+
+**Better approach**: Immediately communicate the 12-day nominal estimate, request scope reduction or fall-back plan.
+
+---
+
+### The False Delivery
+
+**Situation**: Pressure to show progress. Developer convinces self that feature is "done enough" and moves to next task.
+
+**What happened**:
+- Practice became contagious on team
+- Definition of "done" stretched further and further
+- One team defined "done" as "checked-in" (didn't have to compile)
+- Managers heard everything was fine
+- "Freight train of unfinished work" hit the team
+
+**Problems**:
+- Status reports became fiction
+- No visibility into real project state
+- Catastrophic surprise when truth emerged
+
+**Better approach**: Create independent definition of "done" with automated acceptance tests.
+
+---
+
+## Good Scenarios
+
+### The Partitioned Worrier
+
+**Situation**: Developer has financial worries nagging during work.
+
+**What they did**:
+- Recognized the background process consuming focus
+- Dedicated one hour specifically to financial planning
+- Didn't solve the problem but reduced anxiety
+- Returned to coding with quieted background process
+- Produced quality code for rest of day
+
+**Why it works**:
+- Acknowledges human reality
+- One hour of worry-time beats full day of half-focused coding
+- Professional allocation of mental resources
+
+---
+
+### The Gracious Interruptee
+
+**Situation**: Developer deep in complex problem when colleague asks for help.
+
+**What they did**:
+- Stopped what they were doing politely
+- Helped colleague work through their issue
+- Spent 30 minutes pairing on the problem
+- Returned to own work refreshed with new perspective
+- Used failing test to reconstruct context
+
+**Why it works**:
+- Professional ethics require mutual help
+- Fresh perspective often solves problems quickly
+- TDD maintained context for return
+- Built team trust and collaboration
+
+---
+
+### The Honest Estimator
+
+**Situation**: Manager asks developer to "try" to make impossible deadline.
+
+**What they did**:
+- Held to original estimates
+- Presented three-number estimate (best/nominal/worst)
+- Suggested scope reduction as only viable option
+
+**Why it works**: Original estimates more accurate than pressure-modified ones; no false hope.
+
+---
+
+### The Block Breaker
+
+**Situation**: Developer sits at workstation but code won't come.
+
+**What they did**:
+- Recognized writer's block symptoms
+- Found a pair partner
+- Felt the physiological change that breaks blockage
+
+**Why it works**: Pairing has chemical/physiological effect on brain that breaks mental logjams.
+
+---
+
+### The Strategic Walker
+
+**Situation**: Developer stuck on problem late in the day, tempted to stay until solved.
+
+**What they did**:
+- Went home at normal time instead of pushing through
+- Let subconscious work on problem overnight
+- Solved problem in shower next morning
+
+**Why it works**: Disengagement allows creative hunting; fresh perspective sees options intensity missed.
+
+---
+
+## Key Patterns
+
+| Scenario | Unprofessional | Professional |
+|----------|---------------|--------------|
+| Tired | Push through, "heroic" hours | Go home, get sleep |
+| Worried | Force yourself to code | Partition time for the worry |
+| In Zone | Stay there, feel productive | Walk away, find partner |
+| Interrupted | Snap, glare, protect turf | Help graciously, use TDD for context |
+| Behind schedule | Hope, rush, false delivery | Honest estimates, reduce scope |
+| Stuck | Stay stuck, avoid asking | Ask for help, pair up |
diff --git a/.agents/skills/typescript-clean-code/references/coding-practices/knowledge.md b/.agents/skills/typescript-clean-code/references/coding-practices/knowledge.md
new file mode 100644
index 0000000..e6c8b22
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/coding-practices/knowledge.md
@@ -0,0 +1,103 @@
+# Coding Practices Knowledge
+
+Core concepts and foundational understanding for the mental and behavioral aspects of professional coding.
+
+## Overview
+
+Coding is an intellectually challenging activity requiring concentration, focus, and the right mental state. Professional coding is about behavior, mood, and attitude while writing code - not just the code itself. Understanding these mental aspects is essential for sustainable, high-quality output.
+
+## Key Concepts
+
+### Preparedness
+
+**Definition**: The mental and physical readiness required to write quality code.
+
+Coding requires juggling multiple concerns simultaneously: making code work, solving customer problems, fitting into existing systems, and maintaining readability.
+
+**Key points**:
+- Code must work and faithfully represent the solution
+- Code must solve the customer's true needs (not just stated requirements)
+- Code must follow solid engineering principles
+- Code must be readable and reveal intent
+
+### The Flow Zone
+
+**Definition**: A hyper-focused, tunnel-vision state of consciousness during coding that feels productive but diminishes rational faculties.
+
+**Key points**:
+- You write more code in the Zone, but lose big-picture thinking
+- Decisions made in Zone often need reversal later
+- The Zone is a mild meditative state, not true hyper-productivity
+- The feeling of productivity is deceptive
+
+### Writer's Block
+
+**Definition**: The inability to produce code despite sitting at the workstation, often caused by fatigue, worry, fear, or depression.
+
+**Key points**:
+- Manifests as avoiding the keyboard through busy work
+- Pair programming is the most effective solution
+- There's a physiological change when working with others
+- Creative input helps prevent blockage
+
+### Pacing
+
+**Definition**: The practice of conserving energy and creativity over time, treating software development as a marathon rather than sprint.
+
+**Key points**:
+- Creativity and intelligence are fleeting states
+- Tired minds produce poor solutions
+- Disengagement allows creative subconscious to work
+- Learn your personal patterns of creativity
+
+### Debugging Mindset
+
+**Definition**: The professional attitude toward debugging as expensive coding time that should be minimized, not accepted as inevitable.
+
+**Key points**:
+- Debugging time is as expensive as coding time
+- Professionals work to reduce debugging time toward zero
+- TDD can reduce debugging time by a factor of ten
+- Creating bugs frequently is unprofessional behavior
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Error-sense | The ability to feel when you're making a mistake |
+| Confidence | Trust in your abilities that enables flow without constant verification |
+| Background process | Mental processing of worries that consumes focus |
+| Creative input | External stimulation that primes creative output |
+| False delivery | Claiming work is done when it isn't |
+
+## How It Relates To
+
+- **Time Management**: Knowing when to code and when to step away
+- **Collaboration**: Pair programming as solution for blocks and interruptions
+- **Estimation**: Being honest about progress and avoiding hope-based estimates
+- **Professionalism**: Taking responsibility for debugging time and quality
+
+## Common Misconceptions
+
+- **Myth**: The Zone is the optimal state for programming
+  **Reality**: The Zone diminishes rational faculties; code written there often needs rework
+
+- **Myth**: Long hours show dedication and professionalism
+  **Reality**: Professionalism is about discipline, not hours; 3 AM code creates long-term problems
+
+- **Myth**: Interruptions are always bad for productivity
+  **Reality**: Being helpful to others is professional; rudeness often stems from Zone attachment
+
+- **Myth**: You can rush to meet deadlines
+  **Reality**: You cannot make yourself code faster; rushing creates messes that slow everyone
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Preparedness | Must be mentally ready before coding; distracted coding creates waste |
+| Flow Zone | Avoid it - feels productive but loses big picture |
+| Writer's Block | Solved by pair programming and creative input |
+| Pacing | Conserve energy; walk away when stuck |
+| Debugging | Expensive time that professionals minimize |
+| Hope | Project killer; never incorporate into estimates |
diff --git a/.agents/skills/typescript-clean-code/references/coding-practices/rules.md b/.agents/skills/typescript-clean-code/references/coding-practices/rules.md
new file mode 100644
index 0000000..a10567c
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/coding-practices/rules.md
@@ -0,0 +1,153 @@
+# Coding Practices Rules
+
+Rules for professional behavior, mindset, and practices while coding.
+
+## Core Rules
+
+### 1. Never Code When Impaired
+
+**Don't write code when you are tired, worried, or distracted.**
+
+- Tired coding produces bugs, wrong structure, and opaque solutions
+- Code written at 3 AM will haunt you for years
+- Worry creates a background process that consumes focus
+- Any code produced while impaired will need rework
+
+**Action**: Find a way to eliminate distractions and settle your mind first.
+
+### 2. Avoid the Flow Zone
+
+**Deliberately exit the Zone when you feel yourself slipping into it.**
+
+- Walk away for a few minutes
+- Answer emails, check messages
+- Take a lunch break
+- Find a pair partner (pairing blocks Zone entry)
+
+**Why**: Zone code comes out faster but needs more revisiting.
+
+### 3. Handle Interruptions Gracefully
+
+**Respond to interruptions with polite willingness to help.**
+
+- Don't snap or glare at people asking questions
+- Treat others as you'd want to be treated when stuck
+- Use pair programming to maintain context during interruptions
+- Use TDD - failing tests hold your context
+
+**Remember**: Next time you may need to interrupt someone else.
+
+### 4. Seek Creative Input
+
+**Feed your creativity to prevent blockages.**
+
+- Read broadly (software, science, fiction, varied topics)
+- Find what works for you (novels, movies, music)
+- Escapism combined with creative stimulation fuels output
+- Creativity breeds creativity
+
+### 5. Minimize Debugging Time
+
+**Treat debugging time as expensive coding time to be reduced.**
+
+- Adopt TDD or equivalent discipline
+- Aim for zero debugging time (asymptotic goal)
+- Creating many bugs is unprofessional
+- Track and measure debugging time
+
+### 6. Know When to Walk Away
+
+**Disengage when stuck or tired.**
+
+- Can't solve a problem? Go home anyway
+- Pounding a nonfunctioning brain wastes time
+- Give your creative subconscious a chance
+- Solutions come in showers, cars, and off-hours
+
+### 7. Never Incorporate Hope Into Estimates
+
+**Be honest about schedule reality.**
+
+- Provide three estimates: best case, nominal, worst case
+- Update estimates daily with fact-based data
+- Hope destroys schedules and ruins reputations
+- Make sure everyone understands the situation
+
+### 8. Don't Rush
+
+**Hold to your original estimates under pressure.**
+
+- You cannot make yourself code faster
+- Rushing creates messes that slow everyone
+- Shortcuts and extra hours provide false hope
+- Reduce scope instead of promising miracles
+
+### 9. Agree to Overtime Only Conditionally
+
+**Accept overtime only when all three conditions are met:**
+
+1. You can personally afford it
+2. It is short term (two weeks or less)
+3. Your boss has a fall-back plan if overtime fails
+
+**Note**: 20% more hours does not yield 20% more work.
+
+### 10. Never Falsely Deliver
+
+**Don't say you're done when you aren't.**
+
+- Overt lies are bad; rationalized definitions of "done" are worse
+- False delivery is contagious on teams
+- Create independent definition of "done" with automated acceptance tests
+- "Checked-in" does not mean "done"
+
+### 11. Help Others and Accept Help
+
+**Make yourself available; accept help graciously.**
+
+- Sequestering yourself is a violation of professional ethics
+- Set specific available hours if you need alone time
+- When stuck, ask for help - remaining stuck is unprofessional
+- Give help sessions at least 30 minutes; accept help for 30 minutes before excusing yourself
+
+### 12. Partition Worry Time
+
+**Deal with personal worries deliberately, not during coding.**
+
+- Dedicate a block of time to the worry (perhaps an hour)
+- Call home, address financial issues, talk through arguments
+- Reduce anxiety to quiet the background process
+- Ideally handle on personal time; if at office, better than forcing bad code
+
+## Guidelines
+
+Less strict recommendations:
+
+- Be suspicious of music while coding - it may just help you enter the Zone
+- Use pair programming as first resort for writer's block
+- Learn your patterns of creativity and brilliance
+- Recognize that the drive home and shower are problem-solving time
+- Mentor junior developers; seek mentoring from seniors
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Zone for practice**: The Zone is fine during deliberate practice sessions (katas, exercises)
+- **Short overtime**: Acceptable for genuine short-term crunches with fall-back plans
+- **Urgent production issues**: May need to code tired, but expect to revisit the code
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| 3 AM Code | Never code when tired - produces lasting problems |
+| Worry Code | Resolve worries first or partition time for them |
+| Flow Zone | Avoid it - walk away when you feel it coming |
+| Interruptions | Be politely helpful; rudeness is unprofessional |
+| Walking Away | Do it when stuck; subconscious will work |
+| Hope | Never include in estimates; it kills projects |
+| Rushing | Impossible; reduces scope instead |
+| Overtime | Only if affordable, short, and has fall-back |
+| False Delivery | Never; define "done" with automated tests |
+| Helping | Honor bound to offer and accept help |
diff --git a/.agents/skills/typescript-clean-code/references/collaboration/examples.md b/.agents/skills/typescript-clean-code/references/collaboration/examples.md
new file mode 100644
index 0000000..14c9eb2
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/collaboration/examples.md
@@ -0,0 +1,148 @@
+# Collaboration Examples
+
+Scenarios demonstrating good and bad collaboration patterns in software teams.
+
+## Bad Scenarios
+
+### The Printer Company Fiasco
+
+**Situation**: A company built high-end printers with many components (feeders, printers, stackers, staplers, cutters).
+
+**What happened**:
+- Each programmer worked on "their" device
+- One person owned the feeder code, another owned the stapler code
+- Each kept their technology to themselves
+- No one could touch anyone else's code
+- Political clout was tied to how much the business valued each device
+- The printer programmer was "unassailable"
+- Salary reviews were tied to device importance
+
+**Problems observed**:
+- Massive duplication across the codebase
+- Completely skewed interfaces between modules
+- No amount of consulting could convince them to change
+- Business incentives reinforced bad technical practices
+
+**Root cause**: Owned code culture backed by misaligned incentives.
+
+---
+
+### The Cubicle Corner Anti-Pattern
+
+**Situation**: A team of programmers working in a modern office.
+
+**What it looks like**:
+- Programmers sitting in cubicle corners
+- Backs turned to each other
+- Staring at screens
+- Wearing headphones all day
+- No spontaneous conversation
+
+**Problems**:
+- No serendipitous communication
+- Can't sense when teammates are struggling
+- No knowledge sharing happening
+- Not actually functioning as a team
+- Might as well be remote contractors
+
+**The metaphor**: "Rubbing cerebellums" - the cerebellum is at the back of the brain, so to rub them you'd face away from each other. That's not collaboration.
+
+---
+
+### The "I Work Better Alone" Fallacy
+
+**Situation**: A developer believes they are more productive working solo.
+
+**The problem**:
+- Even if individually true, the *team* doesn't work better
+- Creates knowledge silos
+- No code review happening
+- When that person is sick or leaves, their code is a mystery
+- Other team members can't help or contribute
+
+**Reality check**: Programming is about working with people, not avoiding them.
+
+## Good Scenarios
+
+### Collective Ownership in Practice
+
+**Situation**: A team that practices true collective ownership.
+
+**What it looks like**:
+- Any team member can check out any module
+- Changes are made where needed, not based on "ownership"
+- Team members learn by working on unfamiliar parts
+- No single points of failure in knowledge
+- Code reviews happen naturally through pairing
+
+**Benefits**:
+- Less duplication (multiple eyes see patterns)
+- Better interfaces (designed for team, not individual)
+- Resilient team (anyone can cover for anyone)
+- Continuous learning built into daily work
+
+---
+
+### Effective Pairing
+
+**Situation**: Two developers working together on a challenging problem.
+
+**What it looks like**:
+- Sharing a workstation (or screen in remote)
+- Discussing approaches before coding
+- One types while other reviews in real-time
+- Frequent role swaps
+- Knowledge transfers naturally
+
+**Why it works**:
+- "Two heads are better than one"
+- Real-time code review (most efficient form)
+- Knowledge sharing happens automatically
+- No code goes unreviewed
+- Both can now work on this part of the system
+
+**When to pair**:
+- Complex problems (most efficient approach)
+- Unfamiliar code areas (learning opportunity)
+- Critical features (need the review)
+- Emergency fixes (why do we pair then but not normally?)
+
+---
+
+### The Collaborative Workspace
+
+**Situation**: A team arranged for maximum collaboration.
+
+**What it looks like**:
+- Team members sitting around tables
+- Facing each other, not walls
+- Can see body language and facial expressions
+- Overhear when someone is frustrated
+- Spontaneous conversations happen naturally
+- Headphones off most of the time
+
+**Benefits**:
+- Serendipitous communication
+- Problems surface quickly
+- Help offered before it's requested
+- Team feels like a unit
+- Shared context and awareness
+
+## Comparison Table
+
+| Aspect | Bad Pattern | Good Pattern |
+|--------|-------------|--------------|
+| Code Ownership | Individual ("my code") | Collective (team code) |
+| Physical Setup | Corners, backs turned | Tables, facing each other |
+| Knowledge | Silos, single experts | Shared, everyone learns |
+| Code Review | Rare, formal, after-the-fact | Constant through pairing |
+| Communication | Scheduled meetings only | Continuous, serendipitous |
+| Incentives | Tied to individual ownership | Tied to team outcomes |
+
+## Key Takeaways
+
+1. **Owned code is a disaster** - It creates duplication, bad interfaces, and political dysfunction
+2. **Collective ownership works** - When everyone can work anywhere, the code improves
+3. **Pairing is efficient** - If it works in emergencies, it works for regular work
+4. **Physical collaboration matters** - Face each other, communicate constantly
+5. **Programming is about people** - Accept it and learn to work well with others
diff --git a/.agents/skills/typescript-clean-code/references/collaboration/knowledge.md b/.agents/skills/typescript-clean-code/references/collaboration/knowledge.md
new file mode 100644
index 0000000..ee2244a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/collaboration/knowledge.md
@@ -0,0 +1,97 @@
+# Collaboration Knowledge
+
+Core concepts and foundational understanding for team collaboration in software development.
+
+## Overview
+
+Software is created by teams, and teams are most effective when members collaborate professionally. Being a loner or recluse on a team is unprofessional. Programming is fundamentally about working with people - both with business stakeholders and with fellow developers.
+
+## Key Concepts
+
+### Owned Code
+
+**Definition**: A dysfunctional pattern where each programmer builds walls around "their" code and refuses to let others touch or even see it.
+
+This creates silos where political clout is tied to code ownership rather than team success.
+
+**Key problems**:
+- Massive code duplication across modules
+- Skewed interfaces between components
+- Knowledge silos that make the team fragile
+- Political dynamics that hinder technical improvement
+
+### Collective Ownership
+
+**Definition**: A healthy team pattern where all team members own all the code, and anyone can check out any module and make appropriate changes.
+
+Professional developers do not prevent others from working in the code. They work with each other on as much of the system as they can.
+
+**Key points**:
+- The *team* owns the code, not individuals
+- No walls of ownership around code
+- Team members learn from each other by working together
+- Everyone can work on any part of the system
+
+### Pairing
+
+**Definition**: Two programmers working together on the same code, sharing a workstation and collaborating in real-time.
+
+Professionals pair because it is often the most efficient way to solve problems. Most programmers will pair in emergencies - because "two heads are better than one."
+
+**Key points**:
+- Best way to share knowledge across the team
+- Most efficient and effective form of code review
+- Prevents knowledge silos
+- Ensures all team members can play any position in a pinch
+
+### Cerebellums (Working Together)
+
+**Definition**: The importance of physical proximity and face-to-face collaboration rather than isolated work.
+
+Teams need serendipitous communication - both verbal and body language. Working in isolation (facing corners, wearing headphones) prevents true teamwork.
+
+**Key points**:
+- Sit around tables facing each other
+- Enable overhearing and spontaneous communication
+- Communicate as a unit, not as individuals
+- Physical presence matters for team cohesion
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Owned Code | Dysfunctional pattern of individual code ownership |
+| Collective Ownership | Team-wide shared responsibility for all code |
+| Pairing | Two programmers collaborating on the same code |
+| Knowledge Silo | When only one person understands a part of the system |
+| Serendipitous Communication | Unplanned, spontaneous information sharing |
+
+## How It Relates To
+
+- **Code Quality**: Collective ownership prevents duplication and improves interfaces
+- **Code Review**: Pairing is the most effective form of review
+- **Team Resilience**: No single points of failure when everyone can work on any code
+- **Professional Development**: Learning from each other by working together
+
+## Common Misconceptions
+
+- **Myth**: I work better when I work alone
+  **Reality**: Even if true for you individually, the team doesn't work better when you work alone
+
+- **Myth**: Pairing is only for emergencies
+  **Reality**: If pairing is most efficient in emergencies, it's efficient for regular work too
+
+- **Myth**: Code ownership creates accountability
+  **Reality**: It creates silos, duplication, and political dynamics that harm the codebase
+
+- **Myth**: Programmers don't need to work with people
+  **Reality**: Programming is fundamentally about working with people - business and teammates
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Owned Code | Anti-pattern where individuals wall off "their" code |
+| Collective Ownership | Team owns all code; anyone can modify any module |
+| Pairing | Two programmers working together - efficient and educational |
+| Working Together | Face each other, communicate, don't isolate in corners |
diff --git a/.agents/skills/typescript-clean-code/references/collaboration/rules.md b/.agents/skills/typescript-clean-code/references/collaboration/rules.md
new file mode 100644
index 0000000..435fab5
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/collaboration/rules.md
@@ -0,0 +1,78 @@
+# Collaboration Rules
+
+Rules for professional collaboration between developers and with business stakeholders.
+
+## Core Rules
+
+### 1. Practice Collective Code Ownership
+
+Break down all walls of code ownership and have the team own all the code.
+
+- Any team member can check out any module
+- Any team member can make changes they think are appropriate
+- The *team* owns the code, not individuals
+- Do not prevent others from working in the code
+
+### 2. Do Not Build Walls Around Code
+
+Professional developers do not build walls of ownership around code.
+
+- Don't refuse to let others touch "your" code
+- Don't hide your code from other programmers
+- Don't tie your identity or status to particular modules
+- Work with each other on as much of the system as possible
+
+### 3. Pair with Other Programmers
+
+Professionals pair because it is often the most efficient way to solve problems.
+
+- Pair to share knowledge with each other
+- Pair to review code collaboratively (most effective review method)
+- Pair to ensure no knowledge silos exist
+- All team members should be able to play another position in a pinch
+
+### 4. Work Together Physically
+
+Face each other, communicate constantly, work as a unit.
+
+- Sit around tables facing each other, not in corners
+- Don't isolate with headphones all day
+- Enable serendipitous communication (verbal and body language)
+- Overhear frustrated mutterings, sense the team's state
+
+### 5. Review All Code
+
+No system should consist of code that hasn't been reviewed by other programmers.
+
+- Pairing is the most efficient code review method
+- Collaboration in writing code is better than after-the-fact review
+- Every piece of code needs another set of eyes
+
+## Guidelines
+
+Less strict recommendations:
+
+- Learn different parts of the system by pairing with others
+- Learn the business domain by working with teammates who know it
+- Recognize that all team members have a primary position but should be versatile
+- Accept that programming is fundamentally about working with people
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Deep thinking time**: Sometimes you need to think long and hard about a problem alone
+- **Trivial tasks**: When the task is so simple that another person would be wasted
+- **Personal focus time**: Short periods of solo work are acceptable within a collaborative culture
+
+However, "in general, it is best to collaborate closely with others and to pair with them a large fraction of the time."
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Collective Ownership | Team owns all code; anyone can modify anything |
+| No Walls | Don't hide or protect "your" code from teammates |
+| Pair Regularly | Best way to share knowledge and review code |
+| Face Each Other | Physical proximity enables team communication |
+| Review Everything | All code needs review; pairing is most efficient |
diff --git a/.agents/skills/typescript-clean-code/references/comments/examples.md b/.agents/skills/typescript-clean-code/references/comments/examples.md
new file mode 100644
index 0000000..b22fcc7
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/comments/examples.md
@@ -0,0 +1,241 @@
+# Comments Examples
+
+Code examples demonstrating comment principles.
+
+## Bad Examples
+
+### Explaining What Instead of Refactoring
+
+```typescript
+// Check to see if the employee is eligible for full benefits
+if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
+```
+
+**Problems**:
+- Comment explains WHAT, not WHY
+- Code could be made self-explanatory
+
+### Redundant Comment
+
+```typescript
+// Utility method that returns when this.closed is true.
+// Throws an exception if the timeout is reached.
+async waitForClose(timeoutMillis: number): Promise<void> {
+  if (!this.closed) {
+    await this.wait(timeoutMillis);
+    if (!this.closed) {
+      throw new Error('Could not be closed');
+    }
+  }
+}
+```
+
+**Problems**:
+- Comment is less precise than code
+- Takes longer to read than the code itself
+- Actually misleading (returns IF closed, not WHEN)
+
+### Noise Comments
+
+```typescript
+/** The processor delay for this component */
+protected backgroundProcessorDelay = -1;
+
+/** The lifecycle event support for this component */
+protected lifecycle = new LifecycleSupport(this);
+
+/** The container event listeners for this Container */
+protected listeners: EventListener[] = [];
+```
+
+**Problems**:
+- Comments add zero information
+- Variable names already describe purpose
+- Creates clutter that obscures code
+
+### Commented-Out Code
+
+```typescript
+const response = new InputStreamResponse();
+response.setBody(formatter.getResultStream(), formatter.getByteCount());
+// const resultsStream = formatter.getResultStream();
+// const reader = new StreamReader(resultsStream);
+// response.setContent(reader.read(formatter.getByteCount()));
+```
+
+**Problems**:
+- No one will delete it (assumes it's important)
+- Gathers like sediment over time
+- Version control already preserves history
+
+### Frustration Venting
+
+```typescript
+catch (e) {
+  // Give me a break!
+}
+```
+
+**Problems**:
+- Provides no useful information
+- Signals need for refactoring, not commenting
+
+## Good Examples
+
+### Explanation of Intent
+
+```typescript
+compareTo(other: unknown): number {
+  if (other instanceof WikiPagePath) {
+    const compressedName = this.names.join('');
+    const compressedOther = other.names.join('');
+    return compressedName.localeCompare(compressedOther);
+  }
+  return 1; // We are greater because we are the right type
+}
+```
+
+**Why it works**:
+- Explains the decision, not the mechanics
+- Documents non-obvious business logic
+
+### Warning of Consequences
+
+```typescript
+// Intl.DateTimeFormat caches results per locale, but options vary
+// Create new instance to avoid stale format conflicts
+function makeStandardHttpDateFormat(): Intl.DateTimeFormat {
+  return new Intl.DateTimeFormat('en-US', {
+    weekday: 'short',
+    day: '2-digit',
+    month: 'short',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    timeZone: 'GMT'
+  });
+}
+```
+
+**Why it works**:
+- Prevents future "optimization" that would break code
+- Explains WHY, not WHAT
+
+### Clarifying External Library Returns
+
+```typescript
+test('compareTo ordering', () => {
+  const a = PathParser.parse('PageA');
+  const b = PathParser.parse('PageB');
+  const ab = PathParser.parse('PageA.PageB');
+
+  expect(a.compareTo(a)).toBe(0);    // a == a
+  expect(a.compareTo(b)).toBe(-1);   // a < b
+  expect(b.compareTo(a)).toBe(1);    // b > a
+  expect(ab.compareTo(a)).toBe(1);   // ab > a (child > parent)
+});
+```
+
+**Why it works**:
+- Makes test assertions readable
+- Clarifies comparison semantics
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+// Check to see if the employee is eligible for full benefits
+if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
+```
+
+### After
+
+```typescript
+if (employee.isEligibleForFullBenefits())
+```
+
+### Changes Made
+
+1. Extracted condition to descriptive method name
+2. Comment became unnecessary - code speaks for itself
+3. Logic now reusable across codebase
+
+---
+
+### Before
+
+```typescript
+// does the module from the global list <mod> depend on the
+// subsystem we are part of?
+if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
+```
+
+### After
+
+```typescript
+const moduleDependencies = smodule.getDependSubsystems();
+const ourSubSystem = subSysMod.getSubSystem();
+if (moduleDependencies.includes(ourSubSystem))
+```
+
+### Changes Made
+
+1. Extracted intermediate variables with descriptive names
+2. Comment became redundant
+3. Code now reads as English
+
+---
+
+### Before (with frustration comment)
+
+```typescript
+private startSending(): void {
+  try {
+    this.doSending();
+  } catch (e) {
+    if (e instanceof SocketException) {
+      // normal. someone stopped the request.
+    } else {
+      try {
+        this.response.add(ErrorResponder.makeExceptionString(e));
+        this.response.closeAll();
+      } catch {
+        // Give me a break!
+      }
+    }
+  }
+}
+```
+
+### After
+
+```typescript
+private startSending(): void {
+  try {
+    this.doSending();
+  } catch (e) {
+    if (e instanceof SocketException) {
+      // Expected when client disconnects mid-request
+      return;
+    }
+    this.addExceptionAndCloseResponse(e);
+  }
+}
+
+private addExceptionAndCloseResponse(e: Error): void {
+  try {
+    this.response.add(ErrorResponder.makeExceptionString(e));
+    this.response.closeAll();
+  } catch {
+    // Response already closed, safe to ignore
+  }
+}
+```
+
+### Changes Made
+
+1. Extracted nested try/catch to separate method
+2. Replaced frustrated comment with meaningful one
+3. Reduced complexity, improved readability
diff --git a/.agents/skills/typescript-clean-code/references/comments/knowledge.md b/.agents/skills/typescript-clean-code/references/comments/knowledge.md
new file mode 100644
index 0000000..e89a14b
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/comments/knowledge.md
@@ -0,0 +1,86 @@
+# Comments Knowledge
+
+Core concepts and foundational understanding for code comments.
+
+## Overview
+
+Comments are, at best, a necessary evil used to compensate for our failure to express intent in code. The proper use of comments is to explain what cannot be made clear through code alone. Truth can only be found in the code itself.
+
+## Key Concepts
+
+### Comments as Failure
+
+**Definition**: Every comment represents a failure to express yourself clearly in code.
+
+When you write a comment, it means the code wasn't expressive enough on its own. The goal should be to minimize comments by writing clearer, more self-documenting code.
+
+**Key points**:
+- Comments should trigger reflection: "Can I express this in code instead?"
+- Energy spent on comments is better spent improving code clarity
+- Success is measured by how few comments are needed
+
+### Comment Decay
+
+**Definition**: Comments become increasingly inaccurate over time as code evolves.
+
+Code changes and moves, but comments often don't follow. Comments become "orphaned blurbs of ever-decreasing accuracy."
+
+**Key points**:
+- Comments lie - not intentionally, but inevitably
+- The older and farther from code, the more likely to be wrong
+- Inaccurate comments are worse than no comments
+
+### Code as Truth
+
+**Definition**: Only the code truly tells you what the system does.
+
+The code is the only source of accurate information. Comments can mislead, but executable code cannot lie about what it actually does.
+
+**Key points**:
+- Trust the code over the comment when they conflict
+- Make the code tell the truth clearly
+- Use comments only when code cannot express intent
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Self-documenting code | Code that explains itself through clear naming and structure |
+| Comment decay | The process by which comments become inaccurate over time |
+| Noise comment | A comment that adds no information beyond what code already shows |
+| Orphaned comment | A comment separated from the code it was meant to describe |
+
+## How It Relates To
+
+- **Naming**: Good names eliminate need for explanatory comments
+- **Functions**: Small, well-named functions replace comment blocks
+- **Refactoring**: Often the solution to "needing" a comment is refactoring
+
+## Common Misconceptions
+
+- **Myth**: More comments mean better documented code
+  **Reality**: Comments often indicate code that needs to be clearer
+
+- **Myth**: Every function needs a doc comment
+  **Reality**: Good function names make most doc comments redundant
+
+- **Myth**: Comments help future maintainers
+  **Reality**: Outdated comments actively mislead maintainers
+
+## The Comment Test
+
+Before writing a comment, ask:
+
+1. Can I rename a variable to make this clear?
+2. Can I extract a well-named function?
+3. Can I restructure the code to be self-explanatory?
+4. Is this comment explaining WHAT (bad) or WHY (potentially good)?
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Comments as failure | Every comment means code wasn't clear enough |
+| Comment decay | Comments become lies over time |
+| Code as truth | Only executable code is reliable documentation |
+| Self-documenting | The goal is code that needs no comments |
diff --git a/.agents/skills/typescript-clean-code/references/comments/rules.md b/.agents/skills/typescript-clean-code/references/comments/rules.md
new file mode 100644
index 0000000..b906840
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/comments/rules.md
@@ -0,0 +1,196 @@
+# Comments Rules
+
+Guidelines for when comments are acceptable and when to avoid them.
+
+## Good Comments
+
+### 1. Legal Comments
+
+Copyright and license statements at file start are acceptable.
+
+- Keep brief - reference external license files
+- Let IDE collapse them to reduce clutter
+
+```typescript
+// Copyright (C) 2024 Company Inc. All rights reserved.
+// Released under the terms of the MIT License.
+```
+
+### 2. Explanation of Intent
+
+Explain WHY a decision was made, not WHAT the code does.
+
+```typescript
+// We sort our type higher than others to ensure consistent ordering
+// when mixed with external types in collections
+return 1;
+```
+
+### 3. Clarification
+
+Translate obscure library returns or arguments when you can't modify them.
+
+```typescript
+expect(a.compareTo(a)).toBe(0);    // a == a
+expect(a.compareTo(b)).toBe(-1);   // a < b
+expect(b.compareTo(a)).toBe(1);    // b > a
+```
+
+**Warning**: Verify accuracy - clarifying comments are high-risk for errors.
+
+### 4. Warning of Consequences
+
+Alert other developers to non-obvious risks.
+
+```typescript
+// DateTimeFormat is not thread-safe, create new instance each call
+function makeStandardDateFormat(): Intl.DateTimeFormat {
+  return new Intl.DateTimeFormat('en-US', { /* options */ });
+}
+```
+
+### 5. TODO Comments
+
+Mark planned work with context, but clean them up regularly.
+
+```typescript
+// TODO: Remove after checkout model migration (Q2 2024)
+function makeVersion(): VersionInfo | null {
+  return null;
+}
+```
+
+### 6. Amplification
+
+Highlight importance of something that appears trivial.
+
+```typescript
+const listItemContent = match[3].trim();
+// trim() is critical - leading spaces cause incorrect list detection
+```
+
+### 7. JSDoc for Public APIs
+
+Document public APIs that others will consume.
+
+- Keep concise and accurate
+- Update when API changes
+- Skip for internal/private code
+
+## Bad Comments
+
+### 1. Mumbling
+
+Unclear comments that require reading other code to understand.
+
+- If the comment needs explanation, rewrite it or delete it
+
+### 2. Redundant Comments
+
+Comments that restate what the code already says.
+
+```typescript
+// Bad - says nothing the code doesn't
+/** Returns the day of the month */
+getDayOfMonth(): number {
+  return this.dayOfMonth;
+}
+```
+
+### 3. Misleading Comments
+
+Comments that are subtly inaccurate.
+
+- Causes debugging nightmares when developers trust the comment over code
+
+### 4. Mandated Comments
+
+Requiring comments on every function/variable creates noise.
+
+```typescript
+// Bad - adds no value, potential for lies
+/**
+ * @param title The title of the CD
+ * @param author The author of the CD
+ */
+function addCD(title: string, author: string): void { }
+```
+
+### 5. Journal Comments
+
+Change logs at file top - use version control instead.
+
+### 6. Noise Comments
+
+Comments restating the obvious.
+
+```typescript
+// Bad
+/** Default constructor */
+constructor() { }
+
+/** The day of the month */
+private dayOfMonth: number;
+```
+
+### 7. Position Markers / Banners
+
+```typescript
+// Bad - use sparingly if at all
+// //////////////// Actions ////////////////
+```
+
+### 8. Closing Brace Comments
+
+If you need these, your function is too long.
+
+```typescript
+// Bad
+} // end while
+} // end try
+```
+
+### 9. Attributions
+
+Use version control, not comments like `// Added by Rick`.
+
+### 10. Commented-Out Code
+
+Delete it. Version control remembers everything.
+
+### 11. Nonlocal Information
+
+Don't describe system-wide behavior in local comments.
+
+### 12. Too Much Information
+
+Skip historical context, RFCs, or algorithms - link to external docs instead.
+
+## Guidelines
+
+- Prefer extracting a well-named function over writing a comment
+- If comment explains WHAT, refactor the code instead
+- If comment explains WHY, it might be valuable
+- Scan TODOs regularly and resolve them
+
+## Exceptions
+
+- **Third-party code**: Clarifying comments acceptable when you can't modify the source
+- **Complex algorithms**: Mathematical or algorithmic intent may need explanation
+- **Regulatory requirements**: Some domains require specific documentation
+
+## Quick Reference
+
+| Comment Type | Verdict |
+|--------------|---------|
+| Legal headers | OK |
+| Intent explanation | OK |
+| Warning of consequences | OK |
+| TODO with context | OK (clean up regularly) |
+| Amplification | OK |
+| Public API docs | OK |
+| Redundant/obvious | Bad |
+| Commented-out code | Bad |
+| Journal/changelog | Bad |
+| Attributions | Bad |
+| Closing brace markers | Bad |
diff --git a/.agents/skills/typescript-clean-code/references/commitment/examples.md b/.agents/skills/typescript-clean-code/references/commitment/examples.md
new file mode 100644
index 0000000..7965799
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/commitment/examples.md
@@ -0,0 +1,132 @@
+# Commitment Examples
+
+Dialogue examples demonstrating commitment vs non-commitment language.
+
+## Non-Commitment Language
+
+### Weasel Words to Avoid
+
+| Word/Phrase | Example | Problem |
+|-------------|---------|---------|
+| Need/Should | "We need to get this done." | No personal ownership |
+| Hope/Wish | "I hope to get this done by tomorrow." | No commitment to outcome |
+| Let's | "Let's meet sometime." | Vague, no specific action |
+| Try | "I'll try to get that done as well." | Maybe/maybe not hedge |
+
+### Bad Response Examples
+
+**IT guy avoiding responsibility**:
+> "Yeah. We really need to get some new routers."
+
+**Problem**: Uses "need" - nothing will happen.
+
+**Developer hedging on testing**:
+> "Sure. I hope to get to it by the end of the day."
+
+**Problem**: Uses "hope" - no real commitment made.
+
+**Manager deflecting**:
+> "We have to move faster."
+
+**Problem**: Uses "we" and "have to" - really means YOU should do something.
+
+### The "Doable" Trap
+
+> Marge: "Peter, will you have the rating engine mods done by Friday?"
+>
+> Peter: "I think that's doable."
+>
+> Marge: "Will that include the documentation?"
+>
+> Peter: "I'll try to get that done as well."
+
+**Problems**:
+- "I think that's doable" is not yes or no
+- "I'll try" is the maybe/maybe not hedge
+- Marge asked boolean questions, got fuzzy answers
+
+## Commitment Language
+
+### The Formula
+
+**Pattern**: "I will [specific action] by [specific time]."
+
+**Good examples**:
+- "I will finish this by Tuesday."
+- "I will have the docs ready by Monday morning."
+- "I will call you by 3pm today with an update."
+
+### Honest Uncertainty
+
+Better than hedging - express uncertainty explicitly:
+
+> Marge: "Peter, will you have the rating engine mods done by Friday?"
+>
+> Peter: "Probably, but it might be Monday."
+>
+> Marge: "Will that include the documentation?"
+>
+> Peter: "The documentation will take me another few hours, so Monday is possible, but it might be as late as Tuesday."
+
+**Why it works**:
+- Describes his actual uncertainty
+- Gives Marge real information to work with
+- No false promises
+
+### Saying No Professionally
+
+When you can't commit, say so clearly:
+
+> Marge: "Peter, I need a definite yes or no. Will you have the rating engine finished and documented by Friday?"
+>
+> Peter: "In that case, Marge, I'll have to say no. The soonest I can be sure that I'll be done with the mods and the docs is Tuesday."
+>
+> Marge: "You are committing to Tuesday?"
+>
+> Peter: "Yes, I will have it all ready on Tuesday."
+
+**Why it works**:
+- Clear no to the impossible date
+- Offers alternative he CAN commit to
+- Final statement is real commitment language
+
+### Negotiating a Real Commitment
+
+When there's pressure but a path forward:
+
+> Marge: "Peter, look, I know this is a huge imposition, but I really need you to find a way to get this all done by Monday morning."
+>
+> Peter: "OK, Marge, I'll tell you what. I'll call home and clear some overtime with my family. If they are OK with it, then I'll get this task done by Monday morning. I'll even come in on Monday morning to make sure everything goes smoothly with Willy. But then I'll go home and won't be back until Wednesday. Deal?"
+
+**Why it works**:
+- Acknowledges real constraints (family, recovery time)
+- Makes explicit trade-off visible
+- Conditional commitment with clear terms
+- Real "I will" language with specific time
+
+### Breaking Dependencies into Controllable Actions
+
+**Instead of**: "I will finish the module with full integration."
+
+**Commit to**:
+- "I will sit down for an hour with Gary to understand dependencies."
+- "I will create an interface that abstracts my module's dependency."
+- "I will meet three times this week with the build guy."
+- "I will create my own personal build that runs integration tests."
+
+**Instead of**: "I will fix all 25 bugs before release."
+
+**Commit to**:
+- "I will go through all 25 bugs and try to recreate them."
+- "I will sit down with the QA who found each bug to see a repro."
+- "I will spend all my time this week trying to fix each bug."
+
+## Summary Comparison
+
+| Non-Commitment | Commitment |
+|----------------|------------|
+| "We need to..." | "I will..." |
+| "I hope to..." | "I will... by..." |
+| "I'll try to..." | "Yes, I will" or "No, I cannot" |
+| "That's doable" | "Yes" or "Probably, but might be [date]" |
+| "Let's meet sometime" | "I will meet you at [place] at [time]" |
diff --git a/.agents/skills/typescript-clean-code/references/commitment/knowledge.md b/.agents/skills/typescript-clean-code/references/commitment/knowledge.md
new file mode 100644
index 0000000..9296bb7
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/commitment/knowledge.md
@@ -0,0 +1,86 @@
+# Commitment Knowledge
+
+Core concepts and foundational understanding for making real commitments.
+
+## Overview
+
+Commitment is a three-part process: saying, meaning, and doing. Most communication failures stem from unclear commitment language. Professionals use specific language patterns that signal genuine commitment versus vague promises.
+
+## Key Concepts
+
+### The Say/Mean/Do Framework
+
+**Definition**: A commitment requires three sequential parts that must all be present.
+
+1. You **say** you'll do it
+2. You **mean** it
+3. You **actually do** it
+
+**Key points**:
+- Most people fail at one or more stages
+- Saying without meaning creates false expectations
+- Meaning without doing breaks trust
+
+### Language of Commitment
+
+**Definition**: Specific verbal patterns that indicate genuine commitment versus hedging.
+
+The formula for real commitment: **"I will... by..."**
+
+**Key points**:
+- States a fact about what YOU will do
+- Includes a clear end time
+- Creates binary outcome (done or not done)
+- Takes full personal responsibility
+
+### Victim vs. Owner Mindset
+
+**Definition**: The distinction between treating situations as outside your control versus taking ownership.
+
+Non-commitment phrases assume things are out of "my" hands. Real commitment acknowledges you ALWAYS have something under your control.
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Weasel words | Language that sounds like commitment but avoids it |
+| Red flag | Early warning that a commitment may not be met |
+| Binary response | A clear yes or no answer, not fuzzy language |
+| Commitment language | "I will X by Y" - specific, time-bound promise |
+| Stakeholder | Anyone relying on your commitment |
+
+## The "Try" Problem
+
+There are two meanings of "try":
+1. **Extra effort** - Working harder to achieve something
+2. **Maybe, maybe not** - Hedging without real commitment
+
+When someone says "I'll try," they often mean the second definition while implying the first.
+
+## Why Commitment Matters
+
+- **Estimations**: Clear commitments improve planning accuracy
+- **Deadlines**: Binary language eliminates ambiguity
+- **Trust**: Following through builds professional reputation
+- **Collaboration**: Others can depend on your promises
+
+## Common Misconceptions
+
+- **Myth**: You can only commit to final outcomes
+  **Reality**: You can commit to specific actions that move toward a goal
+
+- **Myth**: Commitment means never failing
+  **Reality**: Commitment means raising red flags early when problems arise
+
+- **Myth**: Professionals always say yes
+  **Reality**: Professionals say no when they can't genuinely commit
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Say/Mean/Do | Three parts must all be present for real commitment |
+| "I will... by..." | The language formula for genuine commitment |
+| Weasel words | need, should, hope, wish, let's (without "I") |
+| Red flag protocol | Raise issues immediately when commitment is at risk |
+| Binary response | Give clear yes/no, not fuzzy answers |
diff --git a/.agents/skills/typescript-clean-code/references/commitment/rules.md b/.agents/skills/typescript-clean-code/references/commitment/rules.md
new file mode 100644
index 0000000..7bd305f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/commitment/rules.md
@@ -0,0 +1,100 @@
+# Commitment Rules
+
+Rules for making and keeping professional commitments.
+
+## Core Rules
+
+### 1. Use "I will... by..." Language
+
+State what YOU will do with a clear end time.
+
+- First person singular ("I"), not "we" or "someone"
+- Specific action, not vague intention
+- Concrete deadline, not "soon" or "when I can"
+
+**Example**:
+```
+// Bad
+"We need to get this done."
+"I'll try to finish it."
+"Hopefully by next week."
+
+// Good
+"I will finish the API integration by Thursday 5pm."
+```
+
+### 2. Only Commit to What You Control
+
+You can only commit to things fully under your control.
+
+- If outcome depends on others, commit to YOUR actions
+- Break external dependencies into controllable steps
+- Commit to actions that move you toward the goal
+
+**Example**:
+```
+// Bad - depends on others
+"I will finish the module with full integration with the other team."
+
+// Good - actions you control
+"I will meet with Gary from infrastructure for one hour tomorrow."
+"I will create an interface that abstracts the dependency."
+"I will create a personal build that runs integration tests."
+```
+
+### 3. Raise Red Flags Immediately
+
+When a commitment is at risk, notify stakeholders as soon as possible.
+
+- Don't wait until the deadline passes
+- Earlier notice = more options for the team
+- Enables replanning, reprioritizing, or getting help
+
+### 4. Give Binary Responses
+
+Answer yes/no questions with yes or no.
+
+- Avoid fuzzy responses to boolean questions
+- Express uncertainty explicitly with ranges
+- "Probably, but it might be Monday" is better than "I think that's doable"
+
+### 5. Maintain Discipline Under Pressure
+
+Never sacrifice professional standards to meet a commitment.
+
+- Don't skip tests to go faster (you won't)
+- Don't skip refactoring (it slows you down)
+- Don't skip regression suites
+- Your commitment to standards comes first
+
+## Guidelines
+
+- Know your limits for overtime and its costs
+- Clear overtime with family/stakeholders before committing to it
+- Plan for recovery time after intense effort
+- Be honest with yourself about stamina and reserves
+
+## Exceptions
+
+- **Discovery work**: When you genuinely don't know if something is possible, commit to actions that will find out
+- **External blockers**: When dependencies are truly outside your control, commit to escalation and communication actions
+
+## When NOT to Commit
+
+Situations where you should say no:
+
+- You don't have full control over the outcome
+- Meeting the deadline would require breaking professional standards
+- You're being asked to commit to "try" harder (vague effort)
+- The timeline doesn't account for realistic uncertainty
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| "I will... by..." | The only commitment language that counts |
+| Control test | Only commit to what YOU control |
+| Red flag rule | Raise issues immediately when at risk |
+| Binary answers | Yes or no, not maybe |
+| Standards first | Never sacrifice quality to meet deadlines |
+| Know your limits | Be realistic about overtime capacity |
diff --git a/.agents/skills/typescript-clean-code/references/error-handling/examples.md b/.agents/skills/typescript-clean-code/references/error-handling/examples.md
new file mode 100644
index 0000000..dcc1025
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/error-handling/examples.md
@@ -0,0 +1,200 @@
+# Error Handling Examples
+
+Code examples demonstrating clean error handling principles.
+
+## Bad Examples
+
+### Error Codes Cluttering Logic
+
+```typescript
+class DeviceController {
+  sendShutDown(): void {
+    const handle = this.getHandle(DEV1);
+    if (handle !== INVALID_HANDLE) {
+      const record = this.retrieveDeviceRecord(handle);
+      if (record.status !== DeviceStatus.SUSPENDED) {
+        this.pauseDevice(handle);
+        this.clearDeviceWorkQueue(handle);
+        this.closeDevice(handle);
+      } else {
+        logger.log('Device suspended. Unable to shut down');
+      }
+    } else {
+      logger.log(`Invalid handle for: ${DEV1}`);
+    }
+  }
+}
+```
+
+**Problems**: Business logic tangled with error checks; hard to see intent.
+
+### Multiple Catch Blocks with Duplication
+
+```typescript
+try {
+  port.open();
+} catch (e) {
+  if (e instanceof DeviceResponseException) {
+    reportPortError(e);
+    logger.log('Device response exception', e);
+  } else if (e instanceof ATM1212UnlockedException) {
+    reportPortError(e);
+    logger.log('Unlock exception', e);
+  }
+}
+```
+
+**Problems**: Duplicated handling; tied to third-party types.
+
+### Excessive Null Checks
+
+```typescript
+function registerItem(item: Item | null): void {
+  if (item !== null) {
+    const registry = persistentStore.getItemRegistry();
+    if (registry !== null) {
+      const existing = registry.getItem(item.id);
+      if (existing.billingPeriod.hasRetailOwner()) {
+        existing.register(item);
+      }
+    }
+  }
+}
+```
+
+**Problems**: Nested conditionals; easy to miss checks; obscures intent.
+
+## Good Examples
+
+### Clean Exception-Based Code
+
+```typescript
+class DeviceController {
+  sendShutDown(): void {
+    try {
+      this.tryToShutDown();
+    } catch (e) {
+      if (e instanceof DeviceShutDownError) logger.log(e);
+    }
+  }
+
+  private tryToShutDown(): void {
+    const handle = this.getHandle(DEV1);
+    this.pauseDevice(handle);
+    this.clearDeviceWorkQueue(handle);
+    this.closeDevice(handle);
+  }
+}
+```
+
+**Why it works**: Shutdown algorithm clearly visible; concerns separated.
+
+### Wrapped Third-Party API
+
+```typescript
+class LocalPort {
+  constructor(private innerPort: ACMEPort) {}
+
+  open(): void {
+    try {
+      this.innerPort.open();
+    } catch (e) {
+      throw new PortDeviceFailure('Failed to open port', { cause: e });
+    }
+  }
+}
+
+// Usage - single exception type
+try {
+  port.open();
+} catch (e) {
+  if (e instanceof PortDeviceFailure) reportError(e);
+}
+```
+
+**Why it works**: Single exception type; not tied to vendor; easy to mock.
+
+### Special Case Pattern
+
+```typescript
+interface MealExpenses {
+  getTotal(): number;
+}
+
+class PerDiemMealExpenses implements MealExpenses {
+  getTotal(): number { return DEFAULT_PER_DIEM; }
+}
+
+// DAO returns Special Case when no expenses found
+function getMeals(employeeId: string): MealExpenses {
+  const expenses = db.findExpenses(employeeId);
+  return expenses ?? new PerDiemMealExpenses();
+}
+
+// Clean business logic - no exception handling
+const expenses = getMeals(employee.id);
+total += expenses.getTotal();
+```
+
+**Why it works**: No try/catch; special case handled internally.
+
+### Empty Collection Instead of Null
+
+```typescript
+// Bad
+function getEmployees(): Employee[] | null {
+  if (noEmployees) return null;
+  return employees;
+}
+
+// Good  
+function getEmployees(): Employee[] {
+  return employees ?? [];
+}
+
+// Usage - no null check needed
+for (const e of getEmployees()) {
+  totalPay += e.getPay();
+}
+```
+
+**Why it works**: Safe to iterate; cleaner code.
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+async function processOrder(orderId: string): Promise<void> {
+  const order = await getOrder(orderId);
+  if (order === null) { logger.error('Order not found'); return; }
+  
+  const customer = await getCustomer(order.customerId);
+  if (customer === null) { logger.error('Customer not found'); return; }
+  
+  await fulfillOrder(order);
+}
+```
+
+### After
+
+```typescript
+async function processOrder(orderId: string): Promise<void> {
+  try {
+    const order = await getOrder(orderId);         // Throws if not found
+    const customer = await getCustomer(order.customerId);
+    await fulfillOrder(order, customer);
+  } catch (e) {
+    if (e instanceof OrderError) {
+      logger.error(e.message, { orderId });
+    } else throw e;
+  }
+}
+```
+
+### Changes Made
+
+1. **Removed null returns** - Functions throw specific errors
+2. **Separated concerns** - Happy path clearly visible
+3. **Consolidated handling** - Single catch for all order errors
+4. **Added context** - Errors include orderId for debugging
diff --git a/.agents/skills/typescript-clean-code/references/error-handling/knowledge.md b/.agents/skills/typescript-clean-code/references/error-handling/knowledge.md
new file mode 100644
index 0000000..74dd99f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/error-handling/knowledge.md
@@ -0,0 +1,93 @@
+# Error Handling Knowledge
+
+Core concepts and foundational understanding for error handling in clean code.
+
+## Overview
+
+Error handling is essential but should not obscure business logic. Clean error handling separates error concerns from main algorithms, making code both readable and robust. The goal is graceful, stylish error management that enhances rather than clutters code.
+
+## Key Concepts
+
+### Separation of Concerns
+
+**Definition**: Error handling logic should be separate from business logic.
+
+When error handling dominates code, it becomes impossible to see what the code actually does. Error handling is important, but if it obscures logic, it's wrong.
+
+**Key points**:
+- Two concerns should not be tangled together
+- You should be able to understand each concern independently
+- Business logic should read like a clean, unadorned algorithm
+
+### Exception-Based Error Handling
+
+**Definition**: Using exceptions instead of return codes or error flags to signal errors.
+
+Exceptions allow error handling at a distance, separating where errors occur from where they're handled. This keeps the happy path clean.
+
+**Key points**:
+- Return codes clutter the caller with immediate checks
+- Exceptions let calling code focus on its primary purpose
+- Missing a return code check is easy; exceptions can't be ignored
+
+### Normal Flow Pattern
+
+**Definition**: Designing code so that special cases don't require exception handling in business logic.
+
+Instead of using try/catch for expected variations, design objects that handle special cases internally. This keeps business logic clean and linear.
+
+**Key points**:
+- Push error detection to the edges of your program
+- Use Special Case objects for expected variations
+- Business logic shouldn't deal with exceptional behavior directly
+
+### Transaction Scope
+
+**Definition**: A try block defines a scope where execution can abort and resume at catch.
+
+Think of try blocks as transactions - the catch must leave the program in a consistent state regardless of what happens in the try block.
+
+**Key points**:
+- Start with try-catch-finally when writing code that could throw
+- Define what users should expect regardless of failures
+- Build up logic inside the try block after establishing the scope
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Exception | An object thrown to signal an error condition |
+| Try-Catch-Finally | Structure that defines error handling scope |
+| Special Case Pattern | Object that handles edge cases internally |
+| Wrapper | Class that translates third-party exceptions to your own |
+| Context | Information provided with exceptions for debugging |
+
+## How It Relates To
+
+- **Functions**: Error handling should be extracted into separate functions
+- **Testing**: Write tests that force exceptions first (TDD approach)
+- **Third-Party APIs**: Wrap external APIs to control exception types
+- **Null Safety**: Avoiding null prevents many error conditions
+
+## Common Misconceptions
+
+- **Myth**: More null checks make code safer
+  **Reality**: Too many null checks indicate a design problem; return empty collections or Special Case objects instead
+
+- **Myth**: Exceptions should match their technical source
+  **Reality**: Define exceptions based on how callers will catch them, not where they originate
+
+- **Myth**: Each error type needs its own exception class
+  **Reality**: Often a single exception class per area is sufficient; use different classes only when callers need to handle them differently
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Separation | Error handling separate from business logic |
+| Exceptions | Prefer throwing over return codes |
+| Try-First | Start with try-catch-finally structure |
+| Normal Flow | Design to minimize exception handling in business code |
+| Context | Exceptions should explain what failed and why |
+| Wrapping | Translate third-party exceptions to your types |
+| No Null | Don't return null; use empty collections or Special Case |
diff --git a/.agents/skills/typescript-clean-code/references/error-handling/rules.md b/.agents/skills/typescript-clean-code/references/error-handling/rules.md
new file mode 100644
index 0000000..841de99
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/error-handling/rules.md
@@ -0,0 +1,196 @@
+# Error Handling Rules
+
+Rules for writing clean, robust error handling code.
+
+## Core Rules
+
+### 1. Use Exceptions, Not Return Codes
+
+Throw exceptions when you encounter errors instead of returning error codes or flags.
+
+- Return codes clutter caller with immediate checks
+- Easy to forget to check return codes
+- Exceptions separate error handling from main logic
+
+**Example**:
+```typescript
+// Bad - return codes
+function getUser(id: string): User | null {
+  const user = db.find(id);
+  if (!user) return null;  // Caller must check
+  return user;
+}
+
+// Good - exceptions
+function getUser(id: string): User {
+  const user = db.find(id);
+  if (!user) throw new UserNotFoundError(`User ${id} not found`);
+  return user;
+}
+```
+
+### 2. Write Try-Catch-Finally First
+
+Start with the error handling structure before writing the logic.
+
+- Try blocks define a transaction scope
+- Catch must leave program in consistent state
+- Establishes expectations for callers upfront
+
+**Example**:
+```typescript
+// Start with the structure
+async function readConfig(path: string): Promise<Config> {
+  try {
+    // Add logic here after establishing scope
+    const content = await fs.readFile(path, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    throw new ConfigError(`Failed to read config: ${path}`, { cause: error });
+  }
+}
+```
+
+### 3. Provide Context with Exceptions
+
+Include enough information to determine source and location of errors.
+
+- Mention the operation that failed
+- Include the type of failure
+- Provide enough info for logging
+
+**Example**:
+```typescript
+// Bad - no context
+throw new Error('Failed');
+
+// Good - rich context
+throw new StorageError(
+  `Failed to save user ${userId} to database: connection timeout after ${timeout}ms`
+);
+```
+
+### 4. Define Exceptions by Caller's Needs
+
+Classify exceptions based on how they will be caught, not their source.
+
+- Wrap third-party exceptions into your own types
+- One exception class per area is often sufficient
+- Use different classes only when callers handle them differently
+
+**Example**:
+```typescript
+// Bad - exposing third-party exceptions
+try {
+  await externalApi.call();
+} catch (e) {
+  if (e instanceof AxiosError) { /* ... */ }
+  if (e instanceof TimeoutError) { /* ... */ }
+  if (e instanceof NetworkError) { /* ... */ }
+}
+
+// Good - wrapped with common type
+try {
+  await apiClient.call();
+} catch (e) {
+  if (e instanceof ApiError) {
+    logger.error(e.message);
+  }
+}
+```
+
+### 5. Define the Normal Flow
+
+Use Special Case pattern to avoid exceptions in business logic.
+
+- Return default objects instead of throwing for expected cases
+- Encapsulate special behavior in the object itself
+- Keep business logic clean and linear
+
+**Example**:
+```typescript
+// Bad - exception for normal case
+try {
+  const expenses = await getMealExpenses(employeeId);
+  total += expenses.getTotal();
+} catch (e) {
+  if (e instanceof NoExpensesError) {
+    total += getPerDiem();
+  }
+}
+
+// Good - Special Case pattern
+const expenses = await getMealExpenses(employeeId); // Returns PerDiemExpenses if none
+total += expenses.getTotal();
+```
+
+### 6. Don't Return Null
+
+Return empty collections, throw exceptions, or use Special Case objects.
+
+- Null forces callers to add null checks everywhere
+- One missing check causes runtime errors
+- Empty collections are safe to iterate
+
+**Example**:
+```typescript
+// Bad - returning null
+function getEmployees(): Employee[] | null {
+  if (noEmployees) return null;
+  return employees;
+}
+
+// Good - return empty array
+function getEmployees(): Employee[] {
+  if (noEmployees) return [];
+  return employees;
+}
+```
+
+### 7. Don't Pass Null
+
+Avoid passing null as function arguments.
+
+- Forces defensive null checks in every function
+- No good way to handle accidentally passed null
+- Forbid null by default in your codebase
+
+**Example**:
+```typescript
+// Bad - allows null
+function calculateDistance(p1: Point | null, p2: Point | null): number {
+  if (!p1 || !p2) throw new Error('Invalid arguments');
+  return Math.sqrt((p2.x - p1.x) ** 2 + (p2.y - p1.y) ** 2);
+}
+
+// Good - require valid arguments, use TypeScript strict mode
+function calculateDistance(p1: Point, p2: Point): number {
+  return Math.sqrt((p2.x - p1.x) ** 2 + (p2.y - p1.y) ** 2);
+}
+```
+
+## Guidelines
+
+- Wrap third-party APIs to minimize dependencies and enable mocking
+- Use a single exception class per module/area when possible
+- Push error detection to the edges of your program
+- Use TypeScript strict null checks to catch null issues at compile time
+- Use optional chaining (`?.`) and nullish coalescing (`??`) for safe property access
+
+## Exceptions
+
+- **External APIs expecting null**: When calling APIs that require null, pass it
+- **Performance-critical paths**: Return codes may be acceptable in hot loops
+- **Optional parameters**: Use TypeScript optional parameters (`param?: Type`) instead of null
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Use Exceptions | Throw instead of return error codes |
+| Try-First | Start with try-catch-finally structure |
+| Context | Include operation and failure type in errors |
+| Caller's Needs | Define exceptions by how they're caught |
+| Normal Flow | Use Special Case pattern for expected variations |
+| No Return Null | Return empty collections or throw |
+| No Pass Null | Forbid null arguments by default |
diff --git a/.agents/skills/typescript-clean-code/references/estimation/examples.md b/.agents/skills/typescript-clean-code/references/estimation/examples.md
new file mode 100644
index 0000000..4a81a41
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/estimation/examples.md
@@ -0,0 +1,183 @@
+# Estimation Examples
+
+Examples demonstrating estimation principles and calculations.
+
+## Bad Examples
+
+### Vague Single-Number Estimate
+
+```
+Mike: "What is your estimate for completing the Frazzle task?"
+Peter: "Three days."
+```
+
+**Problems**:
+- No information about likelihood
+- Mike doesn't know if 3 days is certain or optimistic
+- No way to plan for delays
+- Creates implied expectation of completion in 3 days
+
+### The "Try" Trap
+
+```
+Mike: "Peter, can you give me a hard date when you'll be done?"
+Peter: "No, Mike. Like I said, it'll probably be done in three, 
+        maybe four, days."
+Mike: "Can we say four then?"
+Peter: "No, it could be five or six."
+Mike: "OK, Peter, but can you try to make it no more than six days?"
+Peter: "Sure, I'll try."
+```
+
+**Problems**:
+- Peter just made a commitment disguised as "trying"
+- If not done in 6 days, Mike can accuse him of "not trying hard enough"
+- Peter is now implicitly agreeing to work overtime, weekends
+- The word "try" is loaded - agreeing to try is agreeing to succeed
+
+## Good Examples
+
+### Communicating Uncertainty
+
+```
+Mike: "What is your estimate for completing the Frazzle task?"
+Peter: "I'd estimate three days as most likely."
+Mike: "How likely is it that you'll be done in three days?"
+Peter: "Fifty or sixty percent."
+Mike: "So there's a good chance that it'll take you four days."
+Peter: "Yes, in fact it might even take me five or six, though I doubt it."
+Mike: "How much do you doubt it?"
+Peter: "I'm ninety-five percent certain I'll be done before six days. 
+        If everything goes wrong, it could take ten or eleven days. 
+        But it's not very likely that so much will go wrong."
+```
+
+**Why it works**:
+- Peter shares the full probability distribution
+- Mike understands the range of possibilities
+- No false precision or hidden commitments
+- Mike can plan appropriately for the uncertainty
+
+### Declining a Commitment Request
+
+```
+Mike: "Peter, can you give me a hard date when you'll be done?"
+Peter: "No, Mike. Like I said, it'll probably be done in three, 
+        maybe four, days."
+Mike: "Can we say four then?"
+Peter: "No, it could be five or six."
+Mike: "Can you try to make it no more than six days?"
+Peter: "I can't commit to that, Mike. I've given you my best estimate - 
+        probably 3-4 days, could be 5-6, outside chance of longer."
+```
+
+**Why it works**:
+- Peter avoids the "try" trap
+- Clear distinction between estimate and commitment
+- Repeats the probability information
+- Professional and honest
+
+## PERT Calculation Examples
+
+### Single Task Estimate
+
+**Scenario**: Peter estimates the Frazzle task
+
+| Estimate Type | Value | Meaning |
+|--------------|-------|---------|
+| O (Optimistic) | 1 day | If everything goes perfectly |
+| N (Nominal) | 3 days | Most likely duration |
+| P (Pessimistic) | 12 days | If everything goes wrong |
+
+**Calculations**:
+- Expected duration (mu) = (1 + 4(3) + 12) / 6 = (1 + 12 + 12) / 6 = **4.2 days**
+- Standard deviation (sigma) = (12 - 1) / 6 = **1.8 days**
+
+**Interpretation**: Task will likely take ~4 days, could reasonably take 6 days (mu + sigma), possibly even 8 days (mu + 2*sigma).
+
+### Multiple Tasks Combined
+
+**Scenario**: Peter has three sequential tasks
+
+| Task | O | N | P | mu | sigma |
+|------|---|---|---|-----|-------|
+| Alpha | 1 | 3 | 12 | 4.2 | 1.8 |
+| Beta | 1 | 1 | 14 | 3.5 | 2.2 |
+| Gamma | 3 | 6 | 8 | 6.5 | 1.3 |
+
+**Combined Calculations**:
+- Total expected = 4.2 + 3.5 + 6.5 = **14 days**
+- Combined sigma = sqrt(1.8^2 + 2.2^2 + 1.3^2)
+  - = sqrt(3.24 + 4.84 + 1.69)
+  - = sqrt(9.77)
+  - = **~3 days**
+
+**Interpretation**:
+- Likely completion: 14 days
+- Could take 17 days (1 sigma)
+- Possibly 20 days (2 sigma)
+
+**The Surprise**: 
+- Optimistic totals: 1 + 1 + 3 = 5 days
+- Nominal totals: 3 + 1 + 6 = 10 days
+- Yet realistic expectation: 14+ days
+
+This is why projects estimated optimistically take 3-5x longer than hoped!
+
+## Estimation Technique Examples
+
+### Flying Fingers
+
+```
+Moderator: "Let's estimate the user authentication task. 
+            Scale is days. Discussion first..."
+
+[Team discusses requirements, complications, implementation approaches]
+
+Moderator: "Hands under the table... 1, 2, 3, show!"
+
+Alice: 3 fingers
+Bob: 4 fingers  
+Carol: 3 fingers
+Dave: 1 finger  <-- outlier
+
+Moderator: "Dave, why 1 day?"
+Dave: "I thought we could reuse the OAuth library from project X."
+Alice: "Oh, I didn't know about that. That changes things."
+
+[Further discussion, then re-vote]
+
+All: 2 fingers
+Moderator: "Consensus at 2 days."
+```
+
+### Planning Poker with Trivariate
+
+```
+Moderator: "Task: Implement payment processing. 
+            First, show cards for OPTIMISTIC estimate."
+
+[Team shows cards]
+Results: 2, 1, 2, 1, 2
+Take lowest: O = 1 day
+
+Moderator: "Now NOMINAL estimate."
+Results: 5, 5, 3, 5, 5
+Take consensus: N = 5 days
+
+Moderator: "Now PESSIMISTIC estimate."
+Results: 10, 14, 12, 10, 8
+Take highest: P = 14 days
+
+Expected = (1 + 20 + 14) / 6 = 5.8 days
+Sigma = (14 - 1) / 6 = 2.2 days
+```
+
+## Key Takeaways
+
+| Situation | Bad Response | Good Response |
+|-----------|--------------|---------------|
+| "How long?" | "3 days" | "Probably 3, could be 5-6, possibly longer" |
+| "Can you commit?" | "I'll try" | "I can't commit, but here's my estimate..." |
+| "Just give me a number" | Single number | O/N/P with calculation |
+| Estimating alone | Trust your gut | Use team consensus techniques |
diff --git a/.agents/skills/typescript-clean-code/references/estimation/knowledge.md b/.agents/skills/typescript-clean-code/references/estimation/knowledge.md
new file mode 100644
index 0000000..2e5431f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/estimation/knowledge.md
@@ -0,0 +1,99 @@
+# Estimation Knowledge
+
+Core concepts and foundational understanding for software estimation.
+
+## Overview
+
+Estimation is one of the most misunderstood activities in software development. The fundamental problem is that business and developers view estimates differently - business sees commitments, developers see guesses. Understanding this distinction is critical for professional software development.
+
+## Key Concepts
+
+### Estimate vs Commitment
+
+**Definition**: An estimate is a guess with no commitment implied; a commitment is a promise that must be achieved.
+
+This is the most important distinction in professional estimation. Confusing these two concepts leads to broken promises, damaged reputations, and failed projects.
+
+**Key points**:
+- Estimates have no promises attached - missing an estimate is not dishonorable
+- Commitments require certainty - professionals only commit when they know they can deliver
+- Business needs both, but they serve different purposes
+
+### An Estimate is a Distribution
+
+**Definition**: An estimate is not a single number but a probability distribution describing the range of possible completion times.
+
+When someone says "three days," they're giving you the most likely duration, not a guarantee. The actual completion time could fall anywhere on a probability curve, with a tail extending toward longer durations.
+
+**Key points**:
+- The "estimate" typically represents the peak of probability (most likely)
+- There's always a tail extending toward longer times
+- Professional estimates communicate this uncertainty explicitly
+
+### Implied Commitments
+
+**Definition**: Implicit promises created through language that sounds like agreement, especially the word "try."
+
+When you agree to "try" to meet a deadline, you've made a commitment. There's no other interpretation - agreeing to try is agreeing to succeed.
+
+**Key points**:
+- "Can you try?" = "Will you commit?"
+- Saying yes to "try" implies working extra hours, weekends, skipping vacations
+- Professionals carefully avoid implied commitments
+
+### PERT (Program Evaluation and Review Technique)
+
+**Definition**: A technique using three estimates (optimistic, nominal, pessimistic) to create probability distributions suitable for planning.
+
+Created in 1957 for the U.S. Navy's Polaris submarine project, PERT converts estimates into realistic probability distributions.
+
+**Key points**:
+- Uses trivariate analysis: O (optimistic), N (nominal), P (pessimistic)
+- Expected duration: (O + 4N + P) / 6
+- Standard deviation: (P - O) / 6
+
+### Law of Large Numbers
+
+**Definition**: Breaking large tasks into smaller ones and estimating independently produces more accurate total estimates because errors tend to integrate out.
+
+**Key points**:
+- Small task errors tend to cancel each other
+- Underestimation bias means integration isn't perfect
+- Breaking tasks up also helps discover hidden complexity
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Commitment | A promise you must achieve, regardless of required effort |
+| Estimate | A guess about duration with no promise implied |
+| Trivariate Analysis | Using three estimates (O, N, P) to model uncertainty |
+| Expected Duration (mu) | The statistically expected completion time |
+| Standard Deviation (sigma) | A measure of uncertainty in the estimate |
+
+## How It Relates To
+
+- **Saying No**: Declining impossible commitments while providing honest estimates
+- **Time Management**: Realistic estimates enable better planning
+- **Professionalism**: Clear communication about certainty builds trust
+
+## Common Misconceptions
+
+- **Myth**: A good developer should be able to estimate accurately
+  **Reality**: Estimates are inherently uncertain - that's why they're called estimates
+
+- **Myth**: Agreeing to "try" is different from committing
+  **Reality**: Agreeing to try IS committing - there's no other interpretation
+
+- **Myth**: The nominal estimate is when you'll be done
+  **Reality**: The nominal is just the most likely point on a distribution curve
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Estimate | A probability distribution, not a single number |
+| Commitment | A promise requiring certainty before making |
+| PERT Formula | (O + 4N + P) / 6 for expected duration |
+| Standard Deviation | (P - O) / 6 measures uncertainty |
+| "Try" | Agreeing to try = agreeing to succeed |
diff --git a/.agents/skills/typescript-clean-code/references/estimation/rules.md b/.agents/skills/typescript-clean-code/references/estimation/rules.md
new file mode 100644
index 0000000..9d2256e
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/estimation/rules.md
@@ -0,0 +1,106 @@
+# Estimation Rules
+
+Rules for providing professional estimates and avoiding commitment traps.
+
+## Core Rules
+
+### 1. Never Confuse Estimates with Commitments
+
+Estimates are guesses; commitments are promises. Keep them separate.
+
+- Only commit when you are certain you can deliver
+- Communicate estimates as probability distributions, not single numbers
+- Make the distinction explicit in conversations with stakeholders
+
+### 2. Never Make Implied Commitments
+
+Watch for language that creates hidden commitments.
+
+- Never agree to "try" - it's a commitment in disguise
+- If you say yes to "try," you're committing to work extra hours, weekends, etc.
+- If pressed for commitment, decline clearly rather than hedge
+
+**Example**:
+```
+// Bad - creates implied commitment
+Mike: "Can you try to make it no more than six days?"
+Peter: "I'll try."
+
+// Good - maintains honesty
+Mike: "Can you try to make it no more than six days?"
+Peter: "I can't commit to that. It could be five or six days, 
+        possibly longer if things go wrong."
+```
+
+### 3. Provide Trivariate Estimates (PERT)
+
+Give three numbers, not one.
+
+- **O (Optimistic)**: Everything goes perfectly (< 1% chance)
+- **N (Nominal)**: Most likely duration (highest probability)
+- **P (Pessimistic)**: Everything goes wrong (< 1% chance)
+
+Calculate expected duration: **(O + 4N + P) / 6**
+Calculate uncertainty: **(P - O) / 6**
+
+### 4. Use Team Estimation Techniques
+
+Don't estimate alone - use the people around you.
+
+- **Wideband Delphi**: Team discusses and estimates until consensus
+- **Flying Fingers**: Show 0-5 fingers simultaneously after discussion
+- **Planning Poker**: Use cards (0, 1, 3, 5, 10) to estimate simultaneously
+- **Affinity Estimation**: Silently sort task cards by size, then discuss
+
+### 5. Break Large Tasks into Smaller Ones
+
+The Law of Large Numbers improves accuracy.
+
+- Estimate small tasks independently
+- Errors tend to cancel out (though underestimation bias persists)
+- Breaking tasks up reveals hidden complexity
+
+## Guidelines
+
+### Communicating Estimates
+
+- Always include the probability distribution, not just the peak
+- "Probably 3 days, could be 5-6, unlikely but possibly 10-11"
+- Let managers understand the uncertainty to make appropriate plans
+
+### When Asked for Commitment
+
+- Ask yourself: Am I *certain* I can achieve this?
+- If not certain, decline to commit
+- Offer an estimate with probability distribution instead
+
+### Combining Multiple Task Estimates
+
+For a sequence of tasks:
+- Expected total = sum of individual expected durations
+- Combined sigma = sqrt(sum of squared individual sigmas)
+
+## Exceptions
+
+- **Crisis situations**: May need to provide quick rough estimates, but clarify they are rough
+- **Trivial tasks**: Very small, well-understood tasks may not need trivariate analysis
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Estimate != Commitment | Keep guesses and promises separate |
+| Never "try" | Agreeing to try is agreeing to commit |
+| Use PERT | Three numbers: O, N, P -> calculate expected |
+| Team estimation | Use consensus techniques, don't estimate alone |
+| Break it down | Smaller tasks = better accuracy |
+| Communicate uncertainty | Share the distribution, not just the peak |
+
+## Estimation Techniques Summary
+
+| Technique | How It Works | Best For |
+|-----------|--------------|----------|
+| Flying Fingers | Hold up 0-5 fingers simultaneously | Quick team estimates |
+| Planning Poker | Cards (0,1,3,5,10) shown simultaneously | Distributed teams |
+| Affinity Estimation | Silent sorting, then discussion | Many tasks at once |
+| Trivariate (PERT) | O + 4N + P / 6 | Individual task probability |
diff --git a/.agents/skills/typescript-clean-code/references/formatting/examples.md b/.agents/skills/typescript-clean-code/references/formatting/examples.md
new file mode 100644
index 0000000..09d758a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/formatting/examples.md
@@ -0,0 +1,278 @@
+# Formatting Examples
+
+Code examples demonstrating formatting principles in TypeScript.
+
+## Bad Examples
+
+### Missing Vertical Openness
+
+```typescript
+import { regex } from './utils';
+import { ParentWidget } from './widgets';
+export class BoldWidget extends ParentWidget {
+  private static readonly REGEXP = /'''.+?'''/;
+  private pattern = /'''(.+?)'''/gs;
+  constructor(parent: ParentWidget, text: string) {
+    super(parent);
+    const match = this.pattern.exec(text);
+    if (match) this.addChildWidgets(match[1]);
+  }
+  render(): string {
+    return `<b>${this.childHtml()}</b>`;
+  }
+}
+```
+
+**Problems**:
+- No blank lines between imports and class
+- No separation between static fields and constructor
+- No separation between constructor and methods
+- Code appears as an unstructured block
+
+### Excessive Comments Breaking Density
+
+```typescript
+class ReporterConfig {
+  /**
+   * The class name of the reporter listener
+   */
+  private className: string;
+
+  /**
+   * The properties of the reporter listener
+   */
+  private properties: Property[] = [];
+
+  public addProperty(property: Property): void {
+    this.properties.push(property);
+  }
+}
+```
+
+**Problems**:
+- Trivial comments separate related declarations
+- Forces reader to scan more vertical space
+- Comments add no information beyond the names
+
+### Instance Variables Hidden in Class
+
+```typescript
+class TestSuite implements Test {
+  static createTest(testClass: TestClass, name: string): Test {
+    // ... implementation
+  }
+
+  static getTestConstructor(testClass: TestClass): Constructor {
+    // ... implementation
+  }
+
+  // Instance variables buried after static methods!
+  private name: string;
+  private tests: Test[] = [];
+
+  constructor() {}
+}
+```
+
+**Problems**:
+- Instance variables declared in middle of class
+- Reader must hunt to find class state
+- Violates convention of declarations at top
+
+### No Indentation
+
+```typescript
+class FitNesseServer implements SocketServer { private context: FitNesseContext; constructor(context: FitNesseContext) { this.context = context; } serve(socket: Socket): void { this.serveWithTimeout(socket, 10000); } serveWithTimeout(socket: Socket, timeout: number): void { try { const sender = new FitNesseExpediter(socket, this.context); sender.setRequestParsingTimeLimit(timeout); sender.start(); } catch (e) { console.error(e); } } }
+```
+
+**Problems**:
+- Impossible to discern structure
+- Cannot identify method boundaries
+- Cannot see nesting levels
+
+### Collapsed One-Liners
+
+```typescript
+class CommentWidget extends TextWidget {
+  static readonly REGEXP = /^#[^\r\n]*(?:(?:\r\n)|\n|\r)?/;
+
+  constructor(parent: ParentWidget, text: string) { super(parent, text); }
+  render(): string { return ''; }
+}
+```
+
+**Problems**:
+- Methods are hard to scan
+- Inconsistent visual rhythm
+- Easy to miss method boundaries
+
+## Good Examples
+
+### Proper Vertical Openness
+
+```typescript
+import { regex } from './utils';
+
+import { ParentWidget } from './widgets';
+
+export class BoldWidget extends ParentWidget {
+  private static readonly REGEXP = /'''.+?'''/;
+  private pattern = /'''(.+?)'''/gs;
+
+  constructor(parent: ParentWidget, text: string) {
+    super(parent);
+    const match = this.pattern.exec(text);
+    if (match) {
+      this.addChildWidgets(match[1]);
+    }
+  }
+
+  render(): string {
+    return `<b>${this.childHtml()}</b>`;
+  }
+}
+```
+
+**Why it works**:
+- Blank lines separate logical groups
+- Easy to scan and identify structure
+- Each concept is visually distinct
+
+### Related Code Kept Dense
+
+```typescript
+class ReporterConfig {
+  private className: string;
+  private properties: Property[] = [];
+
+  addProperty(property: Property): void {
+    this.properties.push(property);
+  }
+}
+```
+
+**Why it works**:
+- Related properties grouped together
+- No unnecessary vertical separation
+- Fits in one "eye-full"
+
+### Proper Function Ordering (Caller Above Callee)
+
+```typescript
+class WikiPageResponder implements SecureResponder {
+  private page: WikiPage | null = null;
+  private pageData: PageData | null = null;
+  private crawler: PageCrawler;
+
+  makeResponse(context: FitNesseContext, request: Request): Response {
+    const pageName = this.getPageNameOrDefault(request, 'FrontPage');
+    this.loadPage(pageName, context);
+
+    if (!this.page) {
+      return this.notFoundResponse(context, request);
+    }
+    return this.makePageResponse(context);
+  }
+
+  private getPageNameOrDefault(request: Request, defaultName: string): string {
+    const pageName = request.getResource();
+    return pageName || defaultName;
+  }
+
+  private loadPage(resource: string, context: FitNesseContext): void {
+    const path = PathParser.parse(resource);
+    this.crawler = context.root.getPageCrawler();
+    this.page = this.crawler.getPage(context.root, path);
+
+    if (this.page) {
+      this.pageData = this.page.getData();
+    }
+  }
+
+  private notFoundResponse(context: FitNesseContext, request: Request): Response {
+    return new NotFoundResponder().makeResponse(context, request);
+  }
+
+  private makePageResponse(context: FitNesseContext): SimpleResponse {
+    const html = this.makeHtml(context);
+    const response = new SimpleResponse();
+    response.setMaxAge(0);
+    response.setContent(html);
+    return response;
+  }
+}
+```
+
+**Why it works**:
+- Public entry point at top
+- Called functions follow their callers
+- Creates natural top-down reading flow
+- Easy to trace execution path
+
+### Proper Indentation
+
+```typescript
+class FitNesseServer implements SocketServer {
+  private context: FitNesseContext;
+
+  constructor(context: FitNesseContext) {
+    this.context = context;
+  }
+
+  serve(socket: Socket): void {
+    this.serveWithTimeout(socket, 10000);
+  }
+
+  serveWithTimeout(socket: Socket, timeout: number): void {
+    try {
+      const sender = new FitNesseExpediter(socket, this.context);
+      sender.setRequestParsingTimeLimit(timeout);
+      sender.start();
+    } catch (e) {
+      console.error(e);
+    }
+  }
+}
+```
+
+**Why it works**:
+- Structure immediately visible
+- Scopes clearly delineated
+- Easy to navigate mentally
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+class Assert {
+static assertTrue(message: string, condition: boolean): void { if (!condition) fail(message); }
+static assertTrue(condition: boolean): void { assertTrue(null, condition); }
+static assertFalse(message: string, condition: boolean): void { assertTrue(message, !condition); }
+static assertFalse(condition: boolean): void { assertFalse(null, condition); }
+}
+```
+
+### After
+
+```typescript
+class Assert {
+  static assertTrue(condition: boolean, message?: string): void {
+    if (!condition) {
+      fail(message);
+    }
+  }
+
+  static assertFalse(condition: boolean, message?: string): void {
+    Assert.assertTrue(!condition, message);
+  }
+}
+```
+
+### Changes Made
+
+1. Added proper indentation to reveal class structure
+2. Expanded method bodies with braces
+3. Combined overloads using optional parameters (TypeScript idiom)
+4. Added blank line between methods for visual separation
+5. Used proper braces for if statement
diff --git a/.agents/skills/typescript-clean-code/references/formatting/knowledge.md b/.agents/skills/typescript-clean-code/references/formatting/knowledge.md
new file mode 100644
index 0000000..2b67f37
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/formatting/knowledge.md
@@ -0,0 +1,86 @@
+# Formatting Knowledge
+
+Core concepts and foundational understanding for code formatting.
+
+## Overview
+
+Code formatting is about communication, not aesthetics. The readability of your code affects all future changes, long after the original functionality has been modified. Good formatting makes code feel professional and establishes trust with readers.
+
+## Key Concepts
+
+### The Communication Principle
+
+**Definition**: Code formatting is primarily about communicating intent to other developers.
+
+Functionality changes frequently, but readability affects maintainability forever. Your coding style and discipline survive even when your original code does not.
+
+**Key points**:
+- Formatting is too important to ignore
+- Formatting is too important to treat religiously
+- Professional developers prioritize communication
+
+### Vertical Formatting
+
+**Definition**: How code is organized from top to bottom within a file.
+
+Controls file size, concept separation, and the reading flow through your code.
+
+**Key points**:
+- Files should typically be 200-500 lines
+- High-level concepts at top, details at bottom
+- Related concepts should be vertically close
+
+### Horizontal Formatting
+
+**Definition**: How code is organized from left to right within a line.
+
+Controls line length, whitespace usage, and visual grouping of related elements.
+
+**Key points**:
+- Keep lines under 100-120 characters
+- Use whitespace to show relationships
+- Indentation reveals code hierarchy
+
+### The Newspaper Metaphor
+
+**Definition**: Source files should read like newspaper articles - headline first, then synopsis, then increasing detail.
+
+The file name is the headline. Top-level code provides the overview. Details and low-level functions come last.
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Vertical openness | Blank lines that separate distinct concepts |
+| Vertical density | Tightly related code appearing close together |
+| Vertical distance | Physical separation between related concepts |
+| Conceptual affinity | Degree to which code elements belong together |
+| Horizontal density | Elements without spaces indicating close relationship |
+
+## How It Relates To
+
+- **Functions**: Small functions enable proper vertical formatting
+- **Naming**: Good names support the newspaper metaphor
+- **Classes**: Class structure determines file organization
+- **Comments**: Excessive comments disrupt vertical density
+
+## Common Misconceptions
+
+- **Myth**: Formatting is just about aesthetics
+  **Reality**: Formatting directly impacts code comprehension and maintenance
+
+- **Myth**: Personal style preferences should prevail
+  **Reality**: Team consistency trumps individual preferences
+
+- **Myth**: Modern IDEs eliminate formatting concerns
+  **Reality**: Tools help enforce rules, but humans must choose good rules
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Purpose | Formatting is communication, not decoration |
+| File size | Target 200 lines, rarely exceed 500 |
+| Line width | Stay under 100-120 characters |
+| Newspaper metaphor | High-level first, details last |
+| Team rules | Consistency matters more than personal preference |
diff --git a/.agents/skills/typescript-clean-code/references/formatting/rules.md b/.agents/skills/typescript-clean-code/references/formatting/rules.md
new file mode 100644
index 0000000..e6015f5
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/formatting/rules.md
@@ -0,0 +1,209 @@
+# Formatting Rules
+
+Specific guidelines for vertical and horizontal code formatting.
+
+## Vertical Formatting Rules
+
+### 1. Keep Files Small
+
+Target 200 lines, with an upper limit of 500 lines. Significant systems can be built with small files.
+
+- Small files are easier to understand
+- If a file grows too large, split it
+
+### 2. Follow the Newspaper Metaphor
+
+Structure files with high-level concepts first, details last.
+
+- File name should tell you if you're in the right module
+- Top of file: high-level concepts and algorithms
+- Bottom of file: lowest-level functions and details
+
+### 3. Separate Concepts with Blank Lines
+
+Use blank lines between package/import statements, classes, and functions.
+
+```typescript
+// Good - concepts separated
+import { Logger } from './logger';
+
+import { Config } from './config';
+
+export class BoldWidget extends ParentWidget {
+  private static readonly REGEXP = /'''.+?'''/;
+
+  constructor(parent: ParentWidget, text: string) {
+    super(parent);
+  }
+
+  render(): string {
+    return `<b>${this.childHtml()}</b>`;
+  }
+}
+```
+
+### 4. Keep Related Code Dense
+
+Lines of tightly related code should appear together without blank lines.
+
+```typescript
+// Bad - unnecessary separation
+class ReporterConfig {
+  /**
+   * The class name of the reporter listener
+   */
+  private className: string;
+
+  /**
+   * The properties of the reporter listener
+   */
+  private properties: Property[] = [];
+}
+
+// Good - related items together
+class ReporterConfig {
+  private className: string;
+  private properties: Property[] = [];
+
+  addProperty(property: Property): void {
+    this.properties.push(property);
+  }
+}
+```
+
+### 5. Minimize Vertical Distance
+
+Related concepts should be vertically close to each other.
+
+- **Variables**: Declare close to usage, typically at function top
+- **Instance variables**: Declare at top of class
+- **Dependent functions**: Caller above callee
+- **Conceptually related functions**: Keep near each other
+
+### 6. Order Functions Top-Down
+
+Functions that are called should appear below their callers.
+
+```typescript
+// Good - caller above callee
+class WikiPageResponder {
+  makeResponse(context: Context, request: Request): Response {
+    const pageName = this.getPageNameOrDefault(request, 'FrontPage');
+    this.loadPage(pageName, context);
+    return this.page ? this.makePageResponse(context) : this.notFoundResponse();
+  }
+
+  private getPageNameOrDefault(request: Request, defaultName: string): string {
+    return request.getResource() || defaultName;
+  }
+
+  private loadPage(resource: string, context: Context): void {
+    // implementation
+  }
+}
+```
+
+## Horizontal Formatting Rules
+
+### 7. Keep Lines Short
+
+Limit lines to 100-120 characters maximum.
+
+- Programmers prefer short lines
+- Don't rely on horizontal scrolling
+
+### 8. Use Whitespace to Show Relationships
+
+Surround operators with spaces; keep function names attached to parentheses.
+
+```typescript
+// Good - whitespace shows relationships
+function measureLine(line: string): void {
+  lineCount++;
+  const lineSize = line.length;
+  totalChars += lineSize;
+  lineWidthHistogram.addLine(lineSize, lineCount);
+  recordWidestLine(lineSize);
+}
+```
+
+### 9. Avoid Column Alignment
+
+Don't align variable names or values in columns - it emphasizes wrong things.
+
+```typescript
+// Bad - aligned columns
+private socket:                   Socket;
+private input:                    InputStream;
+private requestParsingTimeLimit:  number;
+
+// Good - natural formatting
+private socket: Socket;
+private input: InputStream;
+private requestParsingTimeLimit: number;
+```
+
+### 10. Use Proper Indentation
+
+Indent code proportionally to its hierarchy level.
+
+- Class-level declarations: no indent
+- Methods: one level in from class
+- Method bodies: one level in from method
+- Nested blocks: one level per nesting
+
+### 11. Never Collapse Short Statements
+
+Always expand and indent scopes, even for one-liners.
+
+```typescript
+// Bad - collapsed
+constructor(parent: ParentWidget, text: string) { super(parent, text); }
+render(): string { return ''; }
+
+// Good - expanded
+constructor(parent: ParentWidget, text: string) {
+  super(parent, text);
+}
+
+render(): string {
+  return '';
+}
+```
+
+## Team Rules
+
+### 12. Agree on Team Standards
+
+Every team should agree on a single formatting style.
+
+- Decide on braces, indentation, naming conventions
+- Encode rules in automated formatters (Prettier, ESLint)
+- All members follow team rules, not personal preferences
+- Consistency across the codebase is the goal
+
+## Guidelines
+
+- Use automated formatters (Prettier) to enforce consistency
+- Configure ESLint for style enforcement
+- Keep format configuration in version control
+- Run formatters on save or pre-commit
+
+## Exceptions
+
+- **Legacy code**: May need gradual reformatting to avoid massive diffs
+- **Generated code**: May have different formatting requirements
+- **External dependencies**: Don't reformat third-party code
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| File size | 200-500 lines max |
+| Line width | 100-120 characters max |
+| Blank lines | Separate concepts, not related items |
+| Variable declarations | Close to usage |
+| Instance properties | Top of class |
+| Function order | Caller above callee |
+| Indentation | Always use, never collapse |
+| Team rules | Follow team standards, use formatters |
diff --git a/.agents/skills/typescript-clean-code/references/functions/checklist.md b/.agents/skills/typescript-clean-code/references/functions/checklist.md
new file mode 100644
index 0000000..70c5951
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/functions/checklist.md
@@ -0,0 +1,68 @@
+# Functions Checklist
+
+Use when writing new functions or reviewing existing code.
+
+## Size and Structure
+
+- [ ] Function is 20 lines or less
+- [ ] Indent level is 2 or less
+- [ ] Blocks in `if`/`else`/`while` are one line (function calls)
+- [ ] No sections or comments dividing the function
+
+## Single Responsibility
+
+- [ ] Can describe what function does in one sentence without "and"
+- [ ] Cannot extract another function with a meaningful name
+- [ ] All statements are at the same abstraction level
+- [ ] Function does not have hidden side effects
+
+## Arguments
+
+- [ ] Has 2 or fewer arguments (3 max in rare cases)
+- [ ] No boolean/flag arguments
+- [ ] No output arguments (use return values instead)
+- [ ] Related arguments grouped into objects
+
+## Naming
+
+- [ ] Name describes what the function does
+- [ ] Verb/noun pair for monadic functions
+- [ ] Consistent with similar functions in the codebase
+- [ ] Long enough to be clear (don't abbreviate)
+
+## Error Handling
+
+- [ ] Uses exceptions, not error codes
+- [ ] Try/catch bodies extracted to separate functions
+- [ ] Error handling function does nothing else
+- [ ] No error code enums
+
+## Command Query Separation
+
+- [ ] Function either changes state OR returns information, not both
+- [ ] If returning boolean, it's asking a question, not performing action
+- [ ] State changes don't return status codes
+
+## Red Flags
+
+Stop and refactor if you find:
+
+- Function longer than 20 lines
+- More than 3 arguments
+- Boolean parameters controlling behavior
+- Mixed abstraction levels in one function
+- Same switch statement in multiple places
+- Function name includes "And" or "Or"
+- Side effects hidden in function body
+- Deep nesting (3+ levels)
+
+## Quick Reference
+
+| Aspect | Ideal | Acceptable | Red Flag |
+|--------|-------|------------|----------|
+| Lines | 2-5 | 6-20 | >20 |
+| Arguments | 0-1 | 2 | 3+ |
+| Indent depth | 1 | 2 | 3+ |
+| Abstraction levels | 1 | 1 | 2+ mixed |
+| Side effects | 0 | Named | Hidden |
+| Returns per function | 1 | 2-3 small fn | Many in large fn |
diff --git a/.agents/skills/typescript-clean-code/references/functions/examples.md b/.agents/skills/typescript-clean-code/references/functions/examples.md
new file mode 100644
index 0000000..89e760c
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/functions/examples.md
@@ -0,0 +1,221 @@
+# Functions Examples
+
+Code examples demonstrating clean function principles.
+
+## Bad Examples
+
+### Long Function with Mixed Abstraction
+
+```typescript
+const testableHtml = async (
+  pageData: PageData,
+  includeSuiteSetup: boolean
+): Promise<string> => {
+  const wikiPage = pageData.getWikiPage();
+  let buffer = "";
+  if (pageData.hasAttribute("Test")) {
+    if (includeSuiteSetup) {
+      const suiteSetup = await PageCrawlerImpl.getInheritedPage(
+        SuiteResponder.SUITE_SETUP_NAME, wikiPage
+      );
+      if (suiteSetup !== null) {
+        const pagePath = suiteSetup.getPageCrawler().getFullPath(suiteSetup);
+        const pagePathName = PathParser.render(pagePath);
+        buffer += `!include -setup .${pagePathName}\n`;
+      }
+    }
+    // ... 40 more lines of similar code
+  }
+  pageData.setContent(buffer);
+  return pageData.getHtml();
+};
+```
+
+**Problems**:
+- Too long - hard to understand in 3 minutes
+- Mixed abstraction levels (high: `getHtml()`, low: string concatenation)
+- Duplicated algorithm for setup/teardown handling
+- Does many things: creates buffers, fetches pages, builds strings, generates HTML
+
+### Switch Statement Violating OCP
+
+```typescript
+const calculatePay = (employee: Employee): Money => {
+  switch (employee.type) {
+    case EmployeeType.COMMISSIONED:
+      return calculateCommissionedPay(employee);
+    case EmployeeType.HOURLY:
+      return calculateHourlyPay(employee);
+    case EmployeeType.SALARIED:
+      return calculateSalariedPay(employee);
+    default:
+      throw new InvalidEmployeeTypeError(employee.type);
+  }
+};
+```
+
+**Problems**:
+- Large and grows with each new type
+- Violates Single Responsibility Principle
+- Violates Open/Closed Principle
+- Same structure repeated in `isPayday()`, `deliverPay()`, etc.
+
+### Hidden Side Effect
+
+```typescript
+const checkPassword = (userName: string, password: string): boolean => {
+  const user = UserGateway.findByName(userName);
+  if (user !== null) {
+    const codedPhrase = user.getPhraseEncodedByPassword();
+    const phrase = cryptographer.decrypt(codedPhrase, password);
+    if (phrase === "Valid Password") {
+      Session.initialize(); // Hidden side effect!
+      return true;
+    }
+  }
+  return false;
+};
+```
+
+**Problems**:
+- Name says "check password" but also initializes session
+- Creates temporal coupling - can only call when safe to initialize
+- Caller may accidentally erase session data
+
+## Good Examples
+
+### Small, Focused Function
+
+```typescript
+const renderPageWithSetupsAndTeardowns = async (
+  pageData: PageData,
+  isSuite: boolean
+): Promise<string> => {
+  if (isTestPage(pageData)) {
+    await includeSetupAndTeardownPages(pageData, isSuite);
+  }
+  return pageData.getHtml();
+};
+```
+
+**Why it works**:
+- Very small (4 lines)
+- Does one thing: includes setups/teardowns and renders
+- Clear intent from function name
+- All statements at same abstraction level
+
+### Polymorphic Solution to Switch
+
+```typescript
+// Abstract base
+interface Employee {
+  isPayday(): boolean;
+  calculatePay(): Money;
+  deliverPay(pay: Money): void;
+}
+
+// Factory hides the switch
+interface EmployeeFactory {
+  makeEmployee(record: EmployeeRecord): Employee;
+}
+
+class EmployeeFactoryImpl implements EmployeeFactory {
+  makeEmployee(record: EmployeeRecord): Employee {
+    switch (record.type) {
+      case EmployeeType.COMMISSIONED:
+        return new CommissionedEmployee(record);
+      case EmployeeType.HOURLY:
+        return new HourlyEmployee(record);
+      case EmployeeType.SALARIED:
+        return new SalariedEmployee(record);
+      default:
+        throw new InvalidEmployeeTypeError(record.type);
+    }
+  }
+}
+```
+
+**Why it works**:
+- Switch appears only once, in the factory
+- New types only require adding a new class
+- Methods dispatch polymorphically
+- Rest of system doesn't see the switch
+
+### Command Query Separation
+
+```typescript
+// Bad - mixed command and query
+const set = (attribute: string, value: string): boolean => { /* ... */ };
+
+// Good - separated
+const attributeExists = (attribute: string): boolean => {
+  return attributes.has(attribute);
+};
+
+const setAttribute = (attribute: string, value: string): void => {
+  attributes.set(attribute, value);
+};
+
+// Usage is clear
+if (attributeExists("username")) {
+  setAttribute("username", "unclebob");
+}
+```
+
+**Why it works**:
+- No ambiguity about what each function does
+- Query returns info, command changes state
+- Code reads naturally
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+const delete_ = async (page: Page): Promise<void> => {
+  if (await deletePage(page) === E_OK) {
+    if (await registry.deleteReference(page.name) === E_OK) {
+      if (await configKeys.deleteKey(page.name.makeKey()) === E_OK) {
+        logger.log("page deleted");
+      } else {
+        logger.log("configKey not deleted");
+      }
+    } else {
+      logger.log("deleteReference from registry failed");
+    }
+  } else {
+    logger.log("delete failed");
+    throw new Error("E_ERROR");
+  }
+};
+```
+
+### After
+
+```typescript
+const deletePage = async (page: Page): Promise<void> => {
+  try {
+    await deletePageAndAllReferences(page);
+  } catch (error) {
+    logError(error);
+  }
+};
+
+const deletePageAndAllReferences = async (page: Page): Promise<void> => {
+  await pageService.delete(page);
+  await registry.deleteReference(page.name);
+  await configKeys.deleteKey(page.name.makeKey());
+};
+
+const logError = (error: Error): void => {
+  logger.log(error.message);
+};
+```
+
+### Changes Made
+
+1. **Used exceptions instead of error codes** - Eliminated deep nesting
+2. **Extracted try/catch body** - `deletePageAndAllReferences` handles happy path
+3. **Extracted error logging** - `logError` handles error path
+4. **Each function does one thing** - Delete, do operations, or log errors
+5. **Consistent abstraction level** - Each function stays at one level
diff --git a/.agents/skills/typescript-clean-code/references/functions/knowledge.md b/.agents/skills/typescript-clean-code/references/functions/knowledge.md
new file mode 100644
index 0000000..ef92645
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/functions/knowledge.md
@@ -0,0 +1,91 @@
+# Functions Knowledge
+
+Core concepts and foundational understanding for writing clean functions.
+
+## Overview
+
+Functions are the first line of organization in any program. Well-written functions tell a story, are easy to read, and communicate intent clearly. The goal is to make code read like a top-down narrative, with each function leading naturally to the next.
+
+## Key Concepts
+
+### Small Functions
+
+**Definition**: Functions should be very small, ideally 2-5 lines, rarely exceeding 20 lines.
+
+Small functions are easier to read, understand, and test. Each function should be "transparently obvious" and tell a story that leads to the next function.
+
+**Key points**:
+- Blocks in `if`/`else`/`while` should be one line (a function call)
+- Indent level should not exceed one or two
+- If it's hard to shrink further, you've reached the right size
+
+### Do One Thing
+
+**Definition**: A function should do one thing, do it well, and do it only.
+
+A function does "one thing" if you can describe it as a brief TO paragraph and all steps are one level of abstraction below the function name.
+
+**Key points**:
+- If you can extract another function with a meaningful (non-restating) name, it does more than one thing
+- Functions that can be divided into sections are doing more than one thing
+
+### Abstraction Levels
+
+**Definition**: All statements within a function should be at the same level of abstraction.
+
+Mixing high-level concepts (`getHtml()`) with low-level details (`.append("\n")`) is confusing. Readers can't tell what's essential vs. detail.
+
+**Key points**:
+- High level: business logic, domain operations
+- Intermediate level: utility operations
+- Low level: string manipulation, data formatting
+
+### The Stepdown Rule
+
+**Definition**: Code should read like a top-down narrative, with each function followed by those at the next level of abstraction.
+
+Write code as a set of TO paragraphs, each describing the current level and referencing the next level down.
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Niladic | Function with zero arguments (ideal) |
+| Monadic | Function with one argument |
+| Dyadic | Function with two arguments |
+| Triadic | Function with three arguments (avoid) |
+| Polyadic | Function with more than three arguments (never) |
+| Side Effect | Hidden action beyond the function's stated purpose |
+| Temporal Coupling | When a function can only be called at certain times |
+| Command | Function that changes state |
+| Query | Function that returns information |
+
+## How It Relates To
+
+- **Naming**: Small, focused functions are easier to name descriptively
+- **Testing**: Fewer arguments and single responsibility make testing simpler
+- **Error Handling**: Separate error handling from business logic using exceptions
+- **DRY Principle**: Extract duplicated code into well-named functions
+
+## Common Misconceptions
+
+- **Myth**: Functions need comments to explain what they do
+  **Reality**: A well-named small function is self-documenting
+
+- **Myth**: Extracting small functions hurts performance
+  **Reality**: Readability matters more; compilers optimize well
+
+- **Myth**: Functions should have one return statement
+  **Reality**: Multiple returns are fine in small functions
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Small | 2-5 lines ideal, max 20 lines |
+| Do One Thing | One level of abstraction below the function name |
+| Abstraction | All statements at same level |
+| Stepdown | Code reads top-down like TO paragraphs |
+| Arguments | Zero is best, three is maximum |
+| Side Effects | Functions should not have hidden behaviors |
+| Command/Query | Do something OR answer something, not both |
diff --git a/.agents/skills/typescript-clean-code/references/functions/rules.md b/.agents/skills/typescript-clean-code/references/functions/rules.md
new file mode 100644
index 0000000..adb171a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/functions/rules.md
@@ -0,0 +1,181 @@
+# Functions Rules
+
+Guidelines for writing clean, readable, and maintainable functions.
+
+## Core Rules
+
+### 1. Keep Functions Small
+
+Functions should be very small, ideally 2-5 lines, rarely exceeding 20.
+
+- Blocks in `if`/`else`/`while` should be one line (a function call)
+- Maximum indent level of one or two
+- Each function should be transparently obvious
+
+**Example**:
+```typescript
+// Bad - too long, multiple levels
+const processOrder = (order: Order): void => {
+  if (order.isValid()) {
+    for (const item of order.items) {
+      if (item.inStock) {
+        inventory.reserve(item);
+        // ... 20 more lines
+      }
+    }
+  }
+};
+
+// Good - small, delegating
+const processOrder = (order: Order): void => {
+  if (order.isValid()) {
+    reserveItems(order);
+    calculateTotals(order);
+    notifyCustomer(order);
+  }
+};
+```
+
+### 2. Do One Thing
+
+Functions should do one thing, do it well, and do it only.
+
+- All steps should be one level of abstraction below the function name
+- If you can extract a meaningful function, it's doing too much
+- If it has sections, it's doing too much
+
+### 3. One Level of Abstraction
+
+All statements in a function should be at the same abstraction level.
+
+- Don't mix `getUser()` with `str.toLowerCase()`
+- High-level calls with high-level, low-level with low-level
+
+### 4. Minimize Arguments
+
+Zero arguments is ideal. Three is the maximum.
+
+- Zero (niladic): Best
+- One (monadic): Good for questions or transformations
+- Two (dyadic): Acceptable, but harder to understand
+- Three (triadic): Avoid - very hard to understand
+- More: Never
+
+**Example**:
+```typescript
+// Bad - too many arguments
+const createUser = (
+  name: string,
+  email: string,
+  age: number,
+  address: string,
+  phone: string
+): User => { /* ... */ };
+
+// Good - use an object
+interface CreateUserParams {
+  name: string;
+  email: string;
+  age: number;
+  address: string;
+  phone: string;
+}
+
+const createUser = (params: CreateUserParams): User => { /* ... */ };
+```
+
+### 5. No Flag Arguments
+
+Never pass a boolean to control function behavior.
+
+- Flag arguments mean the function does more than one thing
+- Split into two functions instead
+
+**Example**:
+```typescript
+// Bad
+const render = (data: Data, isSuite: boolean): string => { /* ... */ };
+
+// Good
+const renderSuite = (data: Data): string => { /* ... */ };
+const renderSingleTest = (data: Data): string => { /* ... */ };
+```
+
+### 6. No Side Effects
+
+Functions should not have hidden behaviors beyond their stated purpose.
+
+- Don't modify global state unexpectedly
+- Don't modify input parameters unexpectedly
+- If side effects are necessary, make them explicit in the name
+
+### 7. Command Query Separation
+
+Functions should either do something OR answer something, never both.
+
+- Commands: Change state, return nothing (or void)
+- Queries: Return information, change nothing
+
+**Example**:
+```typescript
+// Bad - does both
+const set = (attr: string, value: string): boolean => { /* ... */ };
+if (set("username", "bob")) { /* confusing! */ }
+
+// Good - separated
+const attributeExists = (attr: string): boolean => { /* ... */ };
+const setAttribute = (attr: string, value: string): void => { /* ... */ };
+
+if (attributeExists("username")) {
+  setAttribute("username", "bob");
+}
+```
+
+### 8. Use Exceptions, Not Error Codes
+
+Throw exceptions instead of returning error codes.
+
+- Error codes force immediate handling, causing deep nesting
+- Exceptions separate happy path from error handling
+- Error code enums become dependency magnets
+
+### 9. Extract Try/Catch Blocks
+
+Error handling is one thing - functions that handle errors should do nothing else.
+
+- If `try` exists, it should be the first word in the function
+- Nothing should come after `catch`/`finally` blocks
+- Extract the try body and catch body into separate functions
+
+### 10. Use Descriptive Names
+
+Long descriptive names are better than short cryptic ones.
+
+- Names should say what the function does
+- Be consistent: use same phrases, nouns, verbs
+- Spend time choosing names - it clarifies design
+
+## Guidelines
+
+- Use verb/noun pairs for monadic functions: `writeField(name)`
+- Encode argument names in function name: `assertExpectedEqualsActual(expected, actual)`
+- Avoid output arguments - use return values or `this`
+- Multiple `return`/`break`/`continue` are fine in small functions
+
+## Exceptions
+
+- **Switch statements**: Acceptable if used once, to create polymorphic objects, hidden behind a factory
+- **Multiple returns**: Fine in small functions where it improves clarity
+- **Two arguments**: Acceptable for ordered pairs like `Point(x, y)` or natural pairs
+
+## Quick Reference
+
+| Rule | Guideline |
+|------|-----------|
+| Size | 2-5 lines ideal, max 20 |
+| Arguments | 0-2 preferred, max 3 |
+| Flag args | Never use |
+| Side effects | Make explicit or eliminate |
+| Command/Query | Separate state changes from returns |
+| Error handling | Use exceptions, extract try/catch |
+| Naming | Long and descriptive beats short |
diff --git a/.agents/skills/typescript-clean-code/references/naming/examples.md b/.agents/skills/typescript-clean-code/references/naming/examples.md
new file mode 100644
index 0000000..2c6bfd8
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/naming/examples.md
@@ -0,0 +1,188 @@
+# Naming Examples
+
+Code examples demonstrating meaningful naming principles in TypeScript.
+
+## Bad Examples
+
+### Non-Revealing Names
+
+```typescript
+const d = 0; // elapsed time in days
+
+function getThem(): number[][] {
+  const list1: number[][] = [];
+  for (const x of theList) {
+    if (x[0] === 4) list1.push(x);
+  }
+  return list1;
+}
+```
+
+**Problems**: `d`, `getThem`, `list1`, `x` reveal nothing; magic number `4` unexplained
+
+### Disinformative Names
+
+```typescript
+const accountList = new Set<Account>(); // not actually a list!
+let a = l;  // l looks like 1
+if (O === l) a = O1;  // O looks like 0
+```
+
+**Problems**: `accountList` lies about type; `l` and `O` are visually confusing
+
+### Number-Series and Noise Words
+
+```typescript
+function copyChars(a1: string[], a2: string[]): void {
+  for (let i = 0; i < a1.length; i++) a2[i] = a1[i];
+}
+
+class Product {}
+class ProductInfo {}  // What's the difference?
+class ProductData {}  // Info and Data add no meaning
+```
+
+**Problems**: `a1`/`a2` are meaningless; noise words create false distinctions
+
+### Unpronounceable and Unsearchable
+
+```typescript
+class DtaRcrd102 {
+  private genymdhms: Date;  // "gen why emm dee aich emm ess"
+  private readonly pszqint = "102";
+}
+
+for (let j = 0; j < 34; j++) {
+  s += (t[j] * 4) / 5;  // Can't search for 4 or 5
+}
+```
+
+**Problems**: Can't discuss verbally; can't find magic numbers in codebase
+
+### Encoded Names
+
+```typescript
+class Part {
+  private m_dsc: string;  // m_ prefix is clutter
+  setName(name: string): void { this.m_dsc = name; }
+}
+
+let strName: string;  // Hungarian notation duplicates type system
+let phoneString: PhoneNumber;  // Encoding lies when type changes
+```
+
+**Problems**: Prefixes add noise; encodings become lies when types change
+
+## Good Examples
+
+### Intention-Revealing Names
+
+```typescript
+const elapsedTimeInDays = 0;
+const daysSinceCreation = 0;
+
+function getFlaggedCells(): Cell[] {
+  const flaggedCells: Cell[] = [];
+  for (const cell of gameBoard) {
+    if (cell.isFlagged()) flaggedCells.push(cell);
+  }
+  return flaggedCells;
+}
+```
+
+**Why it works**: Names reveal units, purpose, and domain context
+
+### Pronounceable and Searchable
+
+```typescript
+class Customer {
+  private generationTimestamp: Date;
+  private modificationTimestamp: Date;
+}
+
+const WORK_DAYS_PER_WEEK = 5;
+for (let j = 0; j < NUMBER_OF_TASKS; j++) {
+  const realTaskWeeks = taskEstimate[j] / WORK_DAYS_PER_WEEK;
+  sum += realTaskWeeks;
+}
+```
+
+**Why it works**: Can discuss verbally; constants are searchable
+
+### Clean Class Without Encodings
+
+```typescript
+class Part {
+  private description: string;
+  setDescription(description: string): void {
+    this.description = description;
+  }
+}
+```
+
+**Why it works**: No prefixes; name matches concept; method matches field
+
+## Refactoring Walkthrough
+
+### Before: Variables Without Context
+
+```typescript
+function printGuessStatistics(candidate: string, count: number): void {
+  let number: string, verb: string, pluralModifier: string;
+  if (count === 0) { number = "no"; verb = "are"; pluralModifier = "s"; }
+  else if (count === 1) { number = "1"; verb = "is"; pluralModifier = ""; }
+  else { number = count.toString(); verb = "are"; pluralModifier = "s"; }
+  console.log(`There ${verb} ${number} ${candidate}${pluralModifier}`);
+}
+```
+
+### After: Context Through Class
+
+```typescript
+class GuessStatisticsMessage {
+  private number: string;
+  private verb: string;
+  private pluralModifier: string;
+
+  make(candidate: string, count: number): string {
+    this.createPluralDependentMessageParts(count);
+    return `There ${this.verb} ${this.number} ${candidate}${this.pluralModifier}`;
+  }
+
+  private createPluralDependentMessageParts(count: number): void {
+    if (count === 0) this.thereAreNoLetters();
+    else if (count === 1) this.thereIsOneLetter();
+    else this.thereAreManyLetters(count);
+  }
+
+  private thereAreManyLetters(count: number): void {
+    this.number = count.toString(); this.verb = "are"; this.pluralModifier = "s";
+  }
+  private thereIsOneLetter(): void {
+    this.number = "1"; this.verb = "is"; this.pluralModifier = "";
+  }
+  private thereAreNoLetters(): void {
+    this.number = "no"; this.verb = "are"; this.pluralModifier = "s";
+  }
+}
+```
+
+**Changes**: Class provides context; method names reveal intent; each method does one thing
+
+## Method Naming Patterns
+
+```typescript
+// Accessors: get prefix
+const name = employee.getName();
+
+// Mutators: set prefix
+customer.setName("Mike");
+
+// Predicates: is/has prefix
+if (paycheck.isPosted()) { }
+if (user.hasPermission("admin")) { }
+
+// Factory methods: describe what they create from
+const point = Complex.fromRealNumber(23.0);
+const user = User.createGuest();
+```
diff --git a/.agents/skills/typescript-clean-code/references/naming/knowledge.md b/.agents/skills/typescript-clean-code/references/naming/knowledge.md
new file mode 100644
index 0000000..63e8220
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/naming/knowledge.md
@@ -0,0 +1,92 @@
+# Naming Knowledge
+
+Core concepts and foundational understanding for meaningful names in code.
+
+## Overview
+
+Names are everywhere in software: variables, functions, arguments, classes, modules, files, and directories. Good names make code readable without comments. The investment in choosing good names pays dividends in maintainability and comprehension.
+
+## Key Concepts
+
+### Intention-Revealing Names
+
+**Definition**: Names that answer why something exists, what it does, and how it's used.
+
+A name should make comments unnecessary. If you need a comment to explain what a variable is, the name doesn't reveal its intent.
+
+**Key points**:
+- Names should answer the "big questions" about the thing being named
+- Good names eliminate the need for explanatory comments
+- Take time choosing names; change them when you find better ones
+
+### Meaningful Distinctions
+
+**Definition**: Names that differ in ways that convey actual semantic differences.
+
+When names must be different, they should mean something different. Number-series naming (a1, a2) and noise words (Info, Data) create distinctions without meaning.
+
+**Key points**:
+- Avoid arbitrary differences just to satisfy the compiler
+- Noise words like Info, Data, Object add no meaning
+- If you can't tell the difference between two names, readers can't either
+
+### Searchability
+
+**Definition**: Names that can be easily located across a codebase.
+
+Single-letter names and magic numbers are nearly impossible to search for. Longer, descriptive names enable effective code navigation.
+
+**Key points**:
+- Name length should correspond to scope size
+- Constants should have searchable names
+- Single letters acceptable only in tiny local scopes (loop counters)
+
+### Mental Mapping
+
+**Definition**: The cognitive load required to translate a name into its actual meaning.
+
+Readers shouldn't have to mentally map your names to concepts they already know. Professional programmers prioritize clarity over cleverness.
+
+**Key points**:
+- Clarity is king
+- Avoid forcing readers to remember what abbreviations mean
+- Use domain-appropriate terminology directly
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Disinformation | Names that lie or mislead about what something is |
+| Noise words | Meaningless additions like Info, Data, Object, String |
+| Hungarian Notation | Encoding type information in name prefixes (obsolete) |
+| Solution domain | Technical/CS terms programmers already know |
+| Problem domain | Business/domain-specific terminology |
+
+## How It Relates To
+
+- **Readability**: Names are the primary vehicle for code comprehension
+- **Comments**: Good names reduce or eliminate need for comments
+- **Refactoring**: Renaming is a fundamental refactoring operation
+- **Communication**: Code is read more than written; names enable team communication
+
+## Common Misconceptions
+
+- **Myth**: Short names are always better for brevity
+  **Reality**: Clarity trumps brevity; name length should match scope size
+
+- **Myth**: Adding prefixes like `m_` or `I` adds useful information
+  **Reality**: Modern IDEs make these encodings unnecessary clutter
+
+- **Myth**: Consistent word choice means using the same word everywhere
+  **Reality**: Different concepts deserve different words even if similar
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Intention-revealing | Name answers why, what, and how |
+| Meaningful distinctions | Different names = different meanings |
+| Searchability | Longer names for larger scopes |
+| No mental mapping | Reader shouldn't need to translate |
+| Solution domain | Use CS terms for technical concepts |
+| Problem domain | Use business terms for domain concepts |
diff --git a/.agents/skills/typescript-clean-code/references/naming/rules.md b/.agents/skills/typescript-clean-code/references/naming/rules.md
new file mode 100644
index 0000000..bbc8677
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/naming/rules.md
@@ -0,0 +1,142 @@
+# Naming Rules
+
+Specific guidelines for choosing meaningful names in code.
+
+## Core Rules
+
+### 1. Use Intention-Revealing Names
+
+Names should tell you why something exists, what it does, and how it's used.
+
+- A name requiring a comment doesn't reveal its intent
+- Include units of measurement when relevant
+
+```typescript
+// Bad
+const d = 0; // elapsed time in days
+
+// Good
+const elapsedTimeInDays = 0;
+```
+
+### 2. Avoid Disinformation
+
+Don't use names that lie about what something is.
+
+- Don't use `list` unless it's actually a List type
+- Avoid names that look too similar to each other
+- Never use `l` (lowercase L) or `O` as variable names
+
+### 3. Make Meaningful Distinctions
+
+If names must be different, they should mean something different.
+
+- Avoid number-series naming (a1, a2, a3)
+- Avoid noise words (Info, Data, Object, String)
+
+```typescript
+// Bad: a1, a2 mean nothing
+function copyChars(a1: string[], a2: string[]): void { }
+
+// Good: source, destination are meaningful
+function copyChars(source: string[], destination: string[]): void { }
+```
+
+### 4. Use Pronounceable Names
+
+If you can't say it, you can't discuss it.
+
+- Programming is a social activity
+- New developers shouldn't need names explained
+
+### 5. Use Searchable Names
+
+Single letters and magic numbers can't be found in a codebase.
+
+- Name length should correspond to scope size
+- Single letters only in small local scopes
+- Constants must have descriptive names
+
+```typescript
+// Bad: can't search for 5
+s += (t[j] * 4) / 5;
+
+// Good: WORK_DAYS_PER_WEEK is searchable
+const realTaskWeeks = realTaskDays / WORK_DAYS_PER_WEEK;
+```
+
+### 6. Avoid Encodings
+
+Don't encode type or scope information into names.
+
+- No Hungarian Notation (strName, intCount)
+- No member prefixes (m_description, _name)
+- Leave interfaces unadorned; encode implementations if needed (ShapeFactoryImpl)
+
+### 7. Class Names Should Be Nouns
+
+- Good: Customer, WikiPage, Account, AddressParser
+- Avoid: Manager, Processor, Data, Info
+- Never use verbs for class names
+
+### 8. Method Names Should Be Verbs
+
+- Accessors: `get` prefix (getName)
+- Mutators: `set` prefix (setName)
+- Predicates: `is`/`has` prefix (isPosted, hasPermission)
+- Use static factory methods over overloaded constructors
+
+### 9. Pick One Word Per Concept
+
+- Don't mix fetch, retrieve, and get for the same concept
+- Don't mix controller, manager, and driver arbitrarily
+- Consistent lexicon helps programmers navigate code
+
+### 10. Don't Pun
+
+Don't use the same word for different concepts.
+
+- If `add` concatenates values, don't use it for collection insertion
+- Use `insert` or `append` when semantics differ
+
+### 11. Add Meaningful Context
+
+Place names in context through enclosing structures.
+
+- Variables alone may be ambiguous (`state` could be anything)
+- Group related variables in classes
+- Use prefixes only as a last resort
+
+### 12. Don't Add Gratuitous Context
+
+Shorter names are better if they're clear.
+
+- Don't prefix every class with application name
+- Add only necessary context
+
+## Guidelines
+
+- Use solution domain names (CS terms) for technical concepts
+- Use problem domain names for business concepts
+- Rename fearlessly; modern tools make it safe
+
+## Exceptions
+
+- **Loop counters**: `i`, `j`, `k` acceptable in small loops
+- **Lambda parameters**: Short names OK in tiny scopes
+- **Well-known abbreviations**: `id`, `url`, `html` are acceptable
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Intention-revealing | Names answer why, what, how |
+| No disinformation | Don't lie about types or purpose |
+| Meaningful distinctions | Different names = different meanings |
+| Pronounceable | You can discuss it out loud |
+| Searchable | Can be found with grep/search |
+| No encodings | No type prefixes or Hungarian Notation |
+| Nouns for classes | Customer, not Manage |
+| Verbs for methods | calculatePay, not payment |
+| One word per concept | Consistent vocabulary |
+| No puns | Same word = same concept |
diff --git a/.agents/skills/typescript-clean-code/references/practicing/examples.md b/.agents/skills/typescript-clean-code/references/practicing/examples.md
new file mode 100644
index 0000000..70d2b56
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/practicing/examples.md
@@ -0,0 +1,201 @@
+# Practicing Examples
+
+Practice exercises and kata examples for deliberate skill development.
+
+## Classic Kata Examples
+
+### The Bowling Game Kata
+
+A 30-minute TDD exercise that calculates bowling scores.
+
+**What you practice**:
+- TDD red-green-refactor cycle
+- Incremental design
+- Handling edge cases (strikes, spares)
+
+```typescript
+// Start: Write a failing test
+describe('BowlingGame', () => {
+  let game: BowlingGame;
+
+  beforeEach(() => {
+    game = new BowlingGame();
+  });
+
+  it('should score zero for gutter game', () => {
+    rollMany(20, 0);
+    expect(game.score()).toBe(0);
+  });
+
+  it('should score 20 for all ones', () => {
+    rollMany(20, 1);
+    expect(game.score()).toBe(20);
+  });
+
+  // Continue with spare, strike, perfect game...
+});
+```
+
+### Prime Factors Kata
+
+Decompose a number into its prime factors.
+
+**What you practice**:
+- Algorithm development through TDD
+- Simple incremental steps
+- Refactoring as patterns emerge
+
+```typescript
+// Tests drive the implementation
+describe('PrimeFactors', () => {
+  it('returns empty for 1', () => {
+    expect(primeFactors(1)).toEqual([]);
+  });
+
+  it('returns [2] for 2', () => {
+    expect(primeFactors(2)).toEqual([2]);
+  });
+
+  it('returns [3] for 3', () => {
+    expect(primeFactors(3)).toEqual([3]);
+  });
+
+  it('returns [2, 2] for 4', () => {
+    expect(primeFactors(4)).toEqual([2, 2]);
+  });
+
+  // Pattern emerges, refactor...
+});
+```
+
+### Word Wrap Kata
+
+Wrap text at a given column width.
+
+**What you practice**:
+- String manipulation
+- Edge case handling
+- Clean function design
+
+```typescript
+describe('WordWrap', () => {
+  it('returns empty for null', () => {
+    expect(wrap(null, 10)).toBe('');
+  });
+
+  it('returns text unchanged if shorter than width', () => {
+    expect(wrap('hello', 10)).toBe('hello');
+  });
+
+  it('wraps at word boundary', () => {
+    expect(wrap('hello world', 7)).toBe('hello\nworld');
+  });
+});
+```
+
+## Wasa (Ping-Pong) Session Example
+
+### Setup
+
+Two developers, one problem, alternating roles.
+
+**Round 1**: Developer A writes test
+```typescript
+it('should return fizz for multiples of 3', () => {
+  expect(fizzBuzz(3)).toBe('fizz');
+});
+```
+
+**Round 2**: Developer B makes it pass, writes next test
+```typescript
+function fizzBuzz(n: number): string {
+  if (n % 3 === 0) return 'fizz';
+  return String(n);
+}
+
+it('should return buzz for multiples of 5', () => {
+  expect(fizzBuzz(5)).toBe('buzz');
+});
+```
+
+**Round 3**: Developer A makes it pass, writes next test
+```typescript
+function fizzBuzz(n: number): string {
+  if (n % 3 === 0) return 'fizz';
+  if (n % 5 === 0) return 'buzz';
+  return String(n);
+}
+
+it('should return fizzbuzz for multiples of 15', () => {
+  expect(fizzBuzz(15)).toBe('fizzbuzz');
+});
+```
+
+## Practice Routines
+
+### Daily Warm-up (15 minutes)
+
+```
+1. Pick a familiar kata
+2. Set a timer for 15 minutes
+3. Focus on smooth keystrokes and minimal mouse use
+4. Track how far you get each day
+```
+
+### Weekly Deep Practice (1-2 hours)
+
+```
+1. Choose a kata you don't know well
+2. Work through it slowly, understanding each step
+3. Repeat 3-5 times
+4. By end of session, aim for fluent execution
+```
+
+### Monthly Challenge
+
+```
+1. Learn a new kata in a language you don't use at work
+2. Contribute to an open source project
+3. Attend or host a coding dojo session
+```
+
+## Kata Resources
+
+| Resource | URL |
+|----------|-----|
+| Kata Catalog | katas.softwarecraftsmanship.org |
+| Code Kata | codekata.pragprog.com |
+| Coding Dojo | codingdojo.org |
+
+## Good Practice Habits
+
+### Before Practice
+
+- Clear workspace
+- Close distractions (email, chat)
+- Set a time limit
+- Choose a specific focus
+
+### During Practice
+
+- Focus on form, not just completion
+- Notice inefficiencies in keystrokes
+- Experiment with IDE shortcuts
+- Stay in flow state
+
+### After Practice
+
+- Reflect on what felt awkward
+- Note improvements to try next time
+- Track progress over weeks
+
+## TypeScript-Friendly Kata Ideas
+
+| Kata | Focus Area |
+|------|------------|
+| String Calculator | TDD basics, parsing |
+| Roman Numerals | Algorithm, edge cases |
+| Tennis Scoring | State management |
+| Bank Account | OOP, immutability |
+| Gilded Rose | Refactoring legacy code |
+| Mars Rover | Command pattern, state |
diff --git a/.agents/skills/typescript-clean-code/references/practicing/knowledge.md b/.agents/skills/typescript-clean-code/references/practicing/knowledge.md
new file mode 100644
index 0000000..ec85706
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/practicing/knowledge.md
@@ -0,0 +1,91 @@
+# Practicing Knowledge
+
+Core concepts and foundational understanding for deliberate practice in software development.
+
+## Overview
+
+Professional programmers practice their craft just like musicians, athletes, and doctors. Practice involves skill-sharpening exercises done on your own time to build muscle memory and quick decision-making. The goal is to make common solutions automatic so your mind can focus on higher-level problems.
+
+## Key Concepts
+
+### The Coding Dojo
+
+**Definition**: A practice space where programmers gather (or practice solo) to sharpen their skills through structured exercises.
+
+The martial arts metaphor fits programming practice well - both require quick reactions, pattern recognition, and automatic responses built through repetition.
+
+**Key points**:
+- Practice sessions can be solo or group-based
+- Focus is on perfecting movements/keystrokes, not just solving problems
+- Goal is to make solutions instinctive and automatic
+
+### Kata
+
+**Definition**: A precise set of choreographed keystrokes and movements that simulates solving a programming problem you already know the solution to.
+
+You aren't solving the problem - you're practicing the movements and decisions involved. The asymptote of perfection is the goal: repeat until movements are automatic.
+
+**Key points**:
+- Learn hot keys and navigation idioms
+- Practice disciplines like TDD and CI
+- Drive problem/solution pairs into your subconscious
+- Know several kata and practice regularly so they don't fade
+
+### Wasa (Ping-Pong)
+
+**Definition**: A two-person practice technique where partners alternate roles while working through a problem.
+
+One programmer writes a unit test, the other makes it pass, then they swap roles. Can use a known kata (practicing form) or a new problem (competitive challenge).
+
+**Key points**:
+- Critique each other's techniques
+- Test writer controls problem direction
+- Can add constraints to challenge partner
+
+### Randori
+
+**Definition**: Free-form group practice where multiple people take turns writing tests and making them pass.
+
+Screen projected on wall, one person writes a test and sits down, next person makes it pass and writes another test. Rotates through the group.
+
+**Key points**:
+- Learn how others solve problems
+- Broaden your own approach
+- Can be sequential or voluntary participation
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Kata | Choreographed solo exercise for a known problem |
+| Wasa | Two-person paired practice (ping-pong) |
+| Randori | Free-form group practice with rotating participants |
+| Dojo | Practice space/session for skill development |
+| TDD | Test-Driven Development - red/green/refactor loop |
+
+## How It Relates To
+
+- **TDD**: Practice builds speed for the red-green-refactor loop
+- **Professionalism**: Practice is part of being a professional
+- **Time Management**: Practice happens on your own time, not employer's
+
+## Common Misconceptions
+
+- **Myth**: Practice means working on real projects more
+  **Reality**: Practice is separate from production work - it's deliberate repetition of known problems
+
+- **Myth**: Experienced developers don't need practice
+  **Reality**: All professionals practice to maintain and sharpen skills
+
+- **Myth**: Fast coding is just about typing speed
+  **Reality**: Speed comes from pattern recognition and automatic responses built through practice
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Kata | Solo choreographed exercises for known problems |
+| Wasa | Paired ping-pong practice |
+| Randori | Group rotation practice |
+| Dojo | Practice session or space |
+| Purpose | Build muscle memory for automatic problem-solving |
diff --git a/.agents/skills/typescript-clean-code/references/practicing/rules.md b/.agents/skills/typescript-clean-code/references/practicing/rules.md
new file mode 100644
index 0000000..2bd46fd
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/practicing/rules.md
@@ -0,0 +1,97 @@
+# Practicing Rules
+
+Rules for effective deliberate practice as a professional developer.
+
+## Core Rules
+
+### 1. Practice on Your Own Time
+
+Professional programmers practice on their own time. It is not your employer's job to keep your skills sharp.
+
+- Patients don't pay doctors to practice sutures
+- Concert-goers don't pay to hear musicians play scales
+- Employers don't pay you for practice time
+- Your skills are your responsibility
+
+### 2. Use Different Languages and Platforms
+
+Since practice time is your own, you don't have to use the same technologies as your employer.
+
+- Pick any language you like
+- Keep your polyglot skills sharp
+- If you work in .NET, practice Java or Ruby at lunch
+- Broadens your resume and mindset
+
+### 3. Know Multiple Kata
+
+A programmer should know several different kata and practice them regularly.
+
+- Practice so they don't fade from memory
+- Each kata teaches different problem/solution pairs
+- Mix up your practice routine
+- Aim for variety in types of problems
+
+### 4. Practice Until Automatic
+
+The goal is to make movements automatic and instinctive.
+
+- Repeat exercises until you know them cold
+- Your body should know what keys to hit
+- Mind free for higher-level strategy
+- Pattern recognition becomes instant
+
+### 5. Contribute to Open Source
+
+Take on pro-bono work to broaden your experience.
+
+- Work on something someone else cares about
+- Best way to increase your repertoire
+- If you write Java, contribute to a Rails project
+- Prevents unhealthy narrowing of skills
+
+## Guidelines
+
+Less strict recommendations:
+
+- Start with simple kata before complex ones
+- Record your practice to review technique
+- Set kata to music for an advanced challenge
+- Join or form a local coding dojo
+- Practice the same kata in different languages
+
+## When to Practice
+
+| Time | Activity |
+|------|----------|
+| Lunch break | Quick kata (15-20 min) |
+| Before work | Morning warm-up kata |
+| Evening | Longer practice sessions |
+| Weekends | Open source contributions |
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Learning new tech at work**: If employer is paying for training, that's different from practice
+- **Pair programming**: Work-time pairing has some practice benefits, but isn't deliberate practice
+- **Hackathons**: May be employer-sponsored but still provide practice value
+
+## Practice Ethics Summary
+
+| Do | Don't |
+|----|-------|
+| Practice on your own time | Expect employer to pay for skill sharpening |
+| Use different languages | Limit yourself to work technologies |
+| Contribute to open source | Only work on paid projects |
+| Practice regularly | Let skills fade from lack of use |
+| Take responsibility for your skills | Blame employer for skill gaps |
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Own time | Practice is your responsibility, not employer's |
+| Polyglot | Practice different languages than work |
+| Multiple kata | Know several, practice regularly |
+| Automatic | Repeat until movements are instinctive |
+| Open source | Contribute to broaden experience |
diff --git a/.agents/skills/typescript-clean-code/references/pressure/examples.md b/.agents/skills/typescript-clean-code/references/pressure/examples.md
new file mode 100644
index 0000000..96c11b6
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/pressure/examples.md
@@ -0,0 +1,123 @@
+# Pressure Examples
+
+Scenarios demonstrating professional and unprofessional behavior under pressure.
+
+## Unprofessional Behavior Scenarios
+
+### The Surgeon Analogy
+
+Imagine you're on an operating table watching a surgeon perform open heart surgery on you under a deadline - a *literal* deadline.
+
+**Unprofessional behavior**:
+- Sweating and swearing
+- Slamming and throwing instruments
+- Blaming management for unrealistic expectations
+- Continuously complaining about time
+- Behaving "like a typical developer"
+
+**Why it fails**: This behavior doesn't help meet the deadline and creates chaos that makes outcomes worse.
+
+### The Start-up Death Spiral
+
+**Scenario**: Company burning through financing, product vision constantly changing, pressure to deliver for demos and customers.
+
+**Unprofessional responses observed**:
+- Working 80-hour weeks as "heroism"
+- Writing 3,000-line functions at 2 AM
+- Arguments with shouting and name calling
+- Throwing pens, punching walls
+- "Hacking some mess together" for customer demos
+- Getting people fired who didn't "shape up"
+
+**Results**:
+- Functions that were unmaintainable (3,000 lines of C)
+- Constant anger and stress
+- Personal life destruction
+- Never-ending cycle of crises
+
+**The turning point**: Realizing this approach was "making life miserable for himself and others in the name of---what?"
+
+### Discipline Abandonment
+
+**Scenario**: Developer follows TDD in normal times but abandons it when deadline pressure hits.
+
+**What this reveals**: They don't actually trust that TDD is helpful. If they believed it worked, they'd use it especially when it matters most.
+
+**Similar patterns**:
+- Keeping code clean normally, making messes under pressure → Don't believe messes slow you down
+- Not pairing normally, but pairing in crisis → Believe pairing is actually more efficient
+
+## Professional Behavior Scenarios
+
+### The Calm Surgeon
+
+**Scenario**: Surgeon under time pressure performing critical operation.
+
+**Professional behavior**:
+- Appearing calm and collected
+- Issuing clear and precise orders to support staff
+- Following training and adhering to disciplines
+- No panic, no blaming, no complaining
+
+**Why it works**: The trained disciplines exist precisely for these moments.
+
+### Commitment Management
+
+**Scenario**: Business makes promises to customers without consulting developers.
+
+**Professional response**:
+- Help the business find a way to meet commitments
+- Do not accept responsibility for commitments you didn't make
+- Quantify and present risk so business can manage it
+- If no way is found, those who made promises accept responsibility
+
+**Key distinction**: Professionals help the business achieve goals but don't accept commitments made for them.
+
+### Pressure Response Protocol
+
+**Scenario**: Project taking longer than expected, initial design is wrong and needs rework, commitment can't be kept.
+
+**Professional response sequence**:
+
+1. **Don't Panic**
+   - Resist the urge to rush
+   - Slow down and think the problem through
+   - Plot course to best possible outcome
+   - Drive toward it at reasonable, steady pace
+
+2. **Communicate**
+   - Tell team and superiors you're in trouble
+   - Share your best plans for getting out
+   - Ask for their input and guidance
+   - Avoid creating surprises
+
+3. **Rely on Disciplines**
+   - Write even more tests than usual
+   - Refactor even more carefully
+   - Keep functions even smaller
+   - Become more deliberate and dedicated
+
+4. **Get Help**
+   - Find someone to pair program with
+   - Let them help you hold onto disciplines
+   - Let them spot things you miss
+   - Offer the same help to others under pressure
+
+## Contrasting Approaches
+
+| Situation | Unprofessional | Professional |
+|-----------|----------------|--------------|
+| Tight deadline | Rush and cut corners | Slow down, stay disciplined |
+| Unrealistic commitment | Accept and stress | Quantify risk, present options |
+| Code quality vs speed | Create messes | Stay clean (dirty = slow) |
+| Crisis hits | Abandon practices | Trust disciplines more |
+| Getting behind | Work alone, longer hours | Communicate, pair up |
+| Others make promises | Accept blame | Help but don't accept commitments |
+
+## Key Insight
+
+> "You know what you believe by observing yourself in a crisis. If in a crisis you follow your disciplines, then you truly believe in those disciplines."
+
+The way to handle pressure:
+- **Avoid it** by managing commitments, following disciplines, keeping clean
+- **Weather it** by staying calm, communicating, following disciplines, getting help
diff --git a/.agents/skills/typescript-clean-code/references/pressure/knowledge.md b/.agents/skills/typescript-clean-code/references/pressure/knowledge.md
new file mode 100644
index 0000000..77a3708
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/pressure/knowledge.md
@@ -0,0 +1,84 @@
+# Pressure Knowledge
+
+Core concepts and foundational understanding for handling pressure professionally.
+
+## Overview
+
+Pressure is inevitable in software development - deadlines, missed estimates, and crises occur. What separates professionals from amateurs is how they behave under that pressure. The key insight is "crisis discipline": your true beliefs are revealed by how you behave in a crisis, not in calm times.
+
+## Key Concepts
+
+### Crisis Discipline
+
+**Definition**: The principle that you should behave in a crisis the same way you wish you always behaved - following your established disciplines rather than abandoning them.
+
+Your behavior in a crisis reveals your true beliefs about your practices. If you abandon TDD under pressure, you don't truly trust TDD. If you make messes when rushed, you don't truly believe that messes slow you down.
+
+**Key points**:
+- Choose disciplines you feel comfortable following in a crisis
+- Then follow them all the time
+- Following disciplines prevents crises from occurring
+- Don't change behavior when the crunch comes
+
+### Avoiding Pressure
+
+**Definition**: Proactive strategies to minimize and shorten high-pressure periods before they occur.
+
+The best way to stay calm under pressure is to avoid situations that cause it. Prevention is more effective than reaction.
+
+**Key points**:
+- Avoid committing to deadlines you aren't sure you can meet
+- Keep systems, code, and design clean at all times
+- "Quick and dirty" is an oxymoron - dirty always means slow
+- Messes slow you down and cause missed dates
+
+### Handling Pressure
+
+**Definition**: Reactive strategies for when pressure occurs despite your best prevention efforts.
+
+Sometimes projects take longer than expected, designs need rework, or commitments can't be kept. When this happens, professionals have specific responses.
+
+**Key points**:
+- Don't panic - rushing drives you deeper into the hole
+- Communicate with team and superiors
+- Rely on your disciplines more, not less
+- Get help through pairing
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Crisis Discipline | Following your normal disciplines during high-pressure times |
+| Staying Clean | Not creating messes to move faster |
+| Forestalling Pressure | Preventing pressure through good practices |
+| Weathering Pressure | Managing pressure when it can't be avoided |
+
+## How It Relates To
+
+- **Commitment**: Managing commitments prevents unrealistic deadlines that cause pressure
+- **Estimation**: Proper estimation with risk quantification avoids pressure situations
+- **TDD**: A key discipline to maintain (not abandon) under pressure
+- **Professionalism**: Calm, decisive behavior under pressure defines a professional
+
+## Common Misconceptions
+
+- **Myth**: Working more hours under pressure shows dedication
+  **Reality**: Sleepless nights and rushing won't help - they drive you deeper into trouble
+
+- **Myth**: Quick and dirty code helps meet deadlines
+  **Reality**: Dirty always means slow - messes slow you down and cause missed dates
+
+- **Myth**: Abandoning practices like TDD saves time during crunch
+  **Reality**: If you abandon disciplines under pressure, you don't truly believe in them
+
+- **Myth**: Pressure requires changing how you work
+  **Reality**: Your disciplines are the best way through - follow them even more carefully
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Crisis Discipline | Behave in crisis as you wish you always behaved |
+| Avoiding Pressure | Manage commitments and stay clean to prevent crises |
+| Handling Pressure | Don't panic, communicate, trust disciplines, get help |
+| Staying Clean | Never sacrifice code quality for speed |
diff --git a/.agents/skills/typescript-clean-code/references/pressure/rules.md b/.agents/skills/typescript-clean-code/references/pressure/rules.md
new file mode 100644
index 0000000..0d902a5
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/pressure/rules.md
@@ -0,0 +1,88 @@
+# Pressure Rules
+
+Rules for avoiding and handling pressure as a professional developer.
+
+## Core Rules
+
+### 1. Never Change Your Behavior in a Crisis
+
+Your disciplines exist to guide you through high-pressure times. If you abandon them under pressure, you don't truly believe in them.
+
+- If you follow TDD normally but abandon it in crisis, you don't trust TDD
+- If you keep code clean normally but make messes in crisis, you don't believe messes slow you down
+- Choose disciplines you're comfortable following in a crisis, then follow them all the time
+
+### 2. Never Commit to Deadlines You Can't Meet
+
+The business wants commitments to eliminate risk. Your job is to quantify and present risk so they can manage it.
+
+- Make sure risk is visible to the business
+- Accepting unrealistic commitments does a disservice to everyone
+- When commitments are made for you, help find a way to meet them but don't accept responsibility for promises you didn't make
+
+### 3. Stay Clean to Go Fast
+
+"Quick and dirty" is an oxymoron. Dirty always means slow.
+
+- Don't tolerate messes - they cause missed dates
+- Don't spend endless hours polishing, but don't create messes either
+- Keep systems, code, and design as clean as possible
+
+### 4. Don't Panic When Pressure Hits
+
+Rushing drives you deeper into the hole. Manage your stress instead.
+
+- Sleepless nights won't help you get done faster
+- Sitting and fretting won't help either
+- Slow down and think the problem through
+- Plot a course to the best outcome and drive toward it at steady pace
+
+### 5. Communicate Early and Often
+
+Nothing makes people more angry and less rational than surprises.
+
+- Let team and superiors know when you're in trouble
+- Tell them your best plans for getting out of trouble
+- Ask for input and guidance
+- Surprises multiply pressure by ten
+
+### 6. Rely More on Disciplines Under Pressure
+
+These are the times to pay special attention to all your disciplines, not question or abandon them.
+
+- Write even more tests than usual if you follow TDD
+- Refactor even more if you're a merciless refactorer
+- Keep functions even smaller if you normally keep them small
+- Become more deliberate and dedicated to your disciplines
+
+### 7. Get Help Through Pairing
+
+When the heat is on, pair programming helps you get done faster with fewer defects.
+
+- Your partner helps you hold onto disciplines and keeps you from panicking
+- Your partner spots things you miss and has helpful ideas
+- Your partner picks up slack when you lose focus
+- Offer to pair with others when you see them under pressure
+
+## Guidelines
+
+- Be calm and decisive under pressure - this defines professional behavior
+- Know that your disciplines are the best way to meet deadlines and commitments
+- Help the business find ways to meet its goals while maintaining professional standards
+- When you can't meet promises made by others, those who made the promises must accept responsibility
+
+## Exceptions
+
+- **External commitments made without you**: You should help find solutions but are not honor bound to accept commitments made for you by the business
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Crisis Behavior | Don't change behavior under pressure |
+| Commitments | Never commit to what you can't deliver |
+| Stay Clean | Dirty always means slow |
+| Don't Panic | Slow down and think; rushing makes it worse |
+| Communicate | No surprises; ask for help early |
+| Trust Disciplines | Follow them more, not less, under pressure |
+| Pair Up | Get help when the heat is on |
diff --git a/.agents/skills/typescript-clean-code/references/professionalism/examples.md b/.agents/skills/typescript-clean-code/references/professionalism/examples.md
new file mode 100644
index 0000000..c8450a4
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/professionalism/examples.md
@@ -0,0 +1,199 @@
+# Professionalism Examples
+
+Scenarios demonstrating professional vs unprofessional behavior.
+
+## Unprofessional Behavior Scenarios
+
+### Shipping Without Testing
+
+**Scenario**: Developer ships software on the promised date without testing a critical feature because "the bug fixes weren't in that code."
+
+**What happened**:
+- Software caused customer data loss
+- Multiple customers affected simultaneously
+- Took days to diagnose and fix
+- Field service manager fielded angry calls
+- Customer trust damaged
+
+**Why it's unprofessional**:
+- Prioritized "saving face" over customer needs
+- Rationalized skipping tests to meet deadline
+- Passed consequences to others (customers, field service)
+
+**Professional alternative**:
+- Communicate that testing isn't complete
+- Delay ship date if necessary
+- Take responsibility early, before damage occurs
+
+---
+
+### Using QA as Bug Catchers
+
+**Scenario**: Developer sends code to QA knowing it hasn't been thoroughly checked, relying on QA to find and report bugs.
+
+**Why it's unprofessional**:
+- Shifts responsibility to QA team
+- Damages schedules when bugs are found late
+- Undermines confidence in development team
+- Lazy and irresponsible behavior
+- Violates "do no harm" principle
+
+**Professional alternative**:
+- Test thoroughly before release
+- Expect QA to find nothing
+- Be surprised and investigate when bugs escape
+
+---
+
+### Letting Employer Own Your Career
+
+**Scenario**: Developer does only assigned work during work hours, expects employer to provide all training, and doesn't learn new technologies.
+
+**Why it's unprofessional**:
+- Career becomes dependent on employer's priorities
+- Skills stagnate and become outdated
+- Industry passes them by
+- Others with current skills advance instead
+
+**Professional alternative**:
+- Invest 20 hours/week in personal development
+- Read books, attend conferences, learn new languages
+- Take ownership of career trajectory
+
+---
+
+### Coding Without Domain Knowledge
+
+**Scenario**: Developer implements accounting system features exactly as specified, without understanding why the spec makes business sense.
+
+**Why it's unprofessional**:
+- Can't recognize or challenge specification errors
+- Builds features that may not solve real problems
+- Misses opportunities to suggest better solutions
+- Abdication of professional judgment
+
+**Professional alternative**:
+- Read books on accounting
+- Interview users about fundamentals
+- Understand principles behind specifications
+- Challenge specs that don't make sense
+
+---
+
+### Refusing to Touch Working Code
+
+**Scenario**: Developer avoids making structural improvements because "if it ain't broke, don't fix it."
+
+**Why it's unprofessional**:
+- Code becomes rigid over time
+- Future changes become exorbitantly expensive
+- Technical debt accumulates
+- Eventually the project becomes mired in "tar pit"
+
+**Professional alternative**:
+- Make small improvements with every touch
+- Follow Boy Scout Rule
+- Use tests to enable fearless refactoring
+- Treat code like clay to be continuously shaped
+
+## Professional Behavior Scenarios
+
+### Taking Responsibility Early
+
+**Scenario**: Developer realizes tests aren't complete but deadline is tomorrow. They inform the manager immediately.
+
+**Actions**:
+- Communicate honestly about status
+- Explain the risk of shipping untested code
+- Propose alternatives (delay, partial release)
+- Accept the difficult conversation
+
+**Why it's professional**:
+- Protects customers from potential harm
+- Demonstrates accountability
+- Allows informed decision-making
+- Builds long-term trust
+
+---
+
+### Continuous Learning in Practice
+
+**Scenario**: Developer structures their week to include professional development.
+
+**Actions**:
+- Uses lunch hour to read technical books
+- Listens to podcasts during commute
+- Spends 90 minutes daily learning a new language
+- Does morning kata to warm up
+- Attends monthly user group meetings
+
+**Why it's professional**:
+- Takes ownership of career
+- Maintains current skills
+- Builds expertise beyond current job
+- Prevents burnout through passion reinforcement
+
+---
+
+### Fearless Refactoring
+
+**Scenario**: Developer reads through a module and notices a method that's getting long.
+
+**Actions**:
+- Runs existing test suite (passes)
+- Repartitions the method into smaller pieces
+- Runs tests again (passes)
+- Commits the improvement
+- Continues with original task
+
+**Why it's professional**:
+- Maintains code structure continuously
+- Tests enable confident changes
+- Small improvements compound over time
+- Treats code as malleable material
+
+---
+
+### Mentoring a Junior Developer
+
+**Scenario**: New developer joins the team, unfamiliar with the codebase.
+
+**Actions**:
+- Sits down with them personally
+- Walks through system architecture
+- Explains team conventions and practices
+- Pairs on initial tasks
+- Remains available for questions
+
+**Why it's professional**:
+- Doesn't let junior "flail about unsupervised"
+- Teaching deepens own understanding
+- Accelerates team productivity
+- Fulfills responsibility to profession
+
+---
+
+### Humble Response to Failure
+
+**Scenario**: Developer's estimate turns out wrong. The team jokes about it.
+
+**Actions**:
+- Laughs at themselves first
+- Acknowledges the mistake openly
+- Adjusts approach for future estimates
+
+**Why it's professional**:
+- Accepts failure is inevitable
+- Uses failure as learning opportunity
+
+## Contrasts Summary
+
+| Situation | Unprofessional | Professional |
+|-----------|---------------|--------------|
+| Deadline pressure | Skip tests to ship on time | Communicate risk, negotiate scope |
+| QA process | Send code hoping QA catches bugs | Expect QA to find nothing |
+| Career development | Wait for employer to provide training | Invest 20 hours/week personally |
+| Domain knowledge | Code blindly from spec | Learn domain, challenge errors |
+| Working code | Don't touch it | Improve it continuously |
+| New team member | Let them figure it out | Mentor them personally |
+| Personal failure | Deflect blame | Laugh, learn, improve |
diff --git a/.agents/skills/typescript-clean-code/references/professionalism/knowledge.md b/.agents/skills/typescript-clean-code/references/professionalism/knowledge.md
new file mode 100644
index 0000000..cc91a48
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/professionalism/knowledge.md
@@ -0,0 +1,84 @@
+# Professionalism Knowledge
+
+Core concepts and foundational understanding for software professionalism.
+
+## Overview
+
+Professionalism is about taking responsibility for your work and its consequences. It combines pride and honor with accountability. A professional developer owns their mistakes, continuously improves their skills, and prioritizes the good of their code, customers, and employer.
+
+## Key Concepts
+
+### Responsibility and Accountability
+
+**Definition**: Taking ownership of your work outcomes, both successes and failures.
+
+A professional doesn't pass the buck when things go wrong. When a bug escapes to production, a professional feels it as if the cost came from their own pocket.
+
+**Key points**:
+- Professionals clean up their own messes
+- The weight of responsibility should be felt constantly
+- Apologies are necessary but insufficient - you must improve
+
+### Do No Harm
+
+**Definition**: The principle that a developer's first obligation is to avoid damaging the software or the business.
+
+Borrowed from the Hippocratic oath, this principle establishes that professionals must not harm the function (correctness) or structure (maintainability) of the software.
+
+**Key points**:
+- Applies to both function (bugs) and structure (design)
+- You are responsible for imperfections even though perfection is impossible
+- Error rate should asymptotically approach zero over your career
+
+### Work Ethic
+
+**Definition**: The commitment to continuous self-improvement outside of employer-paid time.
+
+Your career is your responsibility, not your employer's. Professionals invest their own time in learning, practicing, and growing.
+
+**Key points**:
+- 40 hours for employer, 20 hours for your own growth
+- Don't rely on employer for training, books, or conferences
+- This investment prevents burnout by reinforcing passion
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Professional | One who takes responsibility and is accountable for their work |
+| Merciless Refactoring | Continuously improving code structure with every touch |
+| Boy Scout Rule | Always leave code cleaner than you found it |
+| Kata | Repetitive coding exercises to sharpen skills |
+| Asymptote | A limit approached but never reached (e.g., zero bugs) |
+
+## How It Relates To
+
+- **Testing**: Tests enable fearless refactoring and prove code works
+- **Code Quality**: Structure must be maintained to preserve changeability
+- **Team Collaboration**: Learning accelerates through pairing and mentoring
+- **Domain Knowledge**: Professionals understand what they're building and why
+
+## Common Misconceptions
+
+- **Myth**: Software is too complex for zero-bug expectations
+  **Reality**: You're still responsible for bugs; aim for the asymptote of zero
+
+- **Myth**: Making continuous changes to working code is dangerous
+  **Reality**: NOT changing code is dangerous - it becomes rigid
+
+- **Myth**: QA exists to catch your bugs
+  **Reality**: QA should find nothing; sending known-faulty code is unprofessional
+
+- **Myth**: Employer should provide all training and learning time
+  **Reality**: Career development is your responsibility, not theirs
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Responsibility | Own your mistakes and their consequences |
+| Do No Harm | Protect both function (bugs) and structure (design) |
+| Work Ethic | Invest 20 hours/week in your own growth |
+| Continuous Learning | Never stop acquiring new knowledge and skills |
+| Practice | Exercise skills deliberately, outside of work performance |
+| Humility | Accept that you will fail and be ready to laugh at yourself |
diff --git a/.agents/skills/typescript-clean-code/references/professionalism/rules.md b/.agents/skills/typescript-clean-code/references/professionalism/rules.md
new file mode 100644
index 0000000..da21dc0
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/professionalism/rules.md
@@ -0,0 +1,165 @@
+# Professionalism Rules
+
+Guidelines for professional behavior in software development.
+
+## Core Rules
+
+### 1. Do No Harm to Function
+
+Create software that works correctly. You are responsible for bugs even though they are inevitable.
+
+- Never release code you aren't certain about
+- Apologize for bugs, then prevent recurrence
+- Your error rate should decrease over your career toward zero
+
+### 2. Do No Harm to Structure
+
+Never sacrifice code structure for short-term function delivery.
+
+- Flexible structure enables future changes
+- Compromising structure compromises the future
+- You must be able to make changes without exorbitant costs
+
+### 3. QA Should Find Nothing
+
+Release only code you expect to pass QA completely.
+
+- Never use QA as bug catchers
+- Sending known-faulty code is unprofessional
+- Be surprised and chagrined when QA finds issues
+- Every escaped bug requires root cause analysis
+
+### 4. Know It Works
+
+Test thoroughly before release.
+
+- Test it up, down, and seven ways to Sunday
+- Automate your tests for quick, repeatable execution
+- 100% test coverage is demanded, not suggested
+- Design code to be easy to test (write tests first)
+
+### 5. Maintain Automated QA
+
+Your test suite should be your release gate.
+
+- If tests pass, you should be confident to ship
+- Tests should run quickly (minutes, not hours)
+- At minimum, tests should indicate high probability of passing QA
+
+### 6. Practice Merciless Refactoring
+
+Continuously improve code structure.
+
+- Make small improvements every time you touch code
+- The Boy Scout Rule: leave code cleaner than you found it
+- Tests enable fearless refactoring
+- Treat code like clay - continuously shape it
+
+### 7. Own Your Career
+
+Your professional development is your responsibility.
+
+- Don't rely on employer for training, books, or conferences
+- Invest ~20 hours/week in your own growth
+- 40 hours for employer's problems, 20 for your career
+- If employer provides learning opportunities, be grateful but don't expect them
+
+### 8. Know Your Field
+
+Maintain broad knowledge of software development history and techniques.
+
+- Know design patterns (all 24 GOF patterns, POSA patterns)
+- Know design principles (SOLID, component principles)
+- Know methods (XP, Scrum, Lean, Kanban, Waterfall, Structured Analysis)
+- Know disciplines (TDD, OO design, CI, Pair Programming)
+- Know artifacts (UML, DFDs, State Diagrams, decision tables)
+
+### 9. Never Stop Learning
+
+Continuous learning is mandatory for professionals.
+
+- Read books, articles, blogs
+- Attend conferences and user groups
+- Learn outside your comfort zone
+- Architects who stop coding become irrelevant
+
+### 10. Practice Deliberately
+
+Performance is not practice. Practice skills outside daily work.
+
+- Use kata exercises for skill sharpening
+- 10-minute warm-up in morning, cool-down in evening
+- Practice in multiple languages
+- Train fingers and brain through repetition
+
+### 11. Collaborate and Teach
+
+Learning accelerates through interaction with others.
+
+- Program together, practice together, design together
+- Mentoring juniors is a professional responsibility
+- Teaching drives knowledge deeper into your own understanding
+- Balance collaboration with necessary alone time
+
+### 12. Know Your Domain
+
+Understand the business context of your software.
+
+- Read books on the domain
+- Interview customers and users
+- Challenge specification errors with domain knowledge
+- Never code blindly from specs
+
+### 13. Identify with Employer/Customer
+
+Their problems are your problems.
+
+- Work toward solutions that address real needs
+- Avoid "us versus them" mentality
+- Put yourself in employer's shoes when developing features
+
+### 14. Practice Humility
+
+Balance confidence with awareness of your fallibility.
+
+- Know your job and take pride in your work
+- Take bold, calculated risks based on confidence
+- Accept that you will sometimes fail
+- Be first to laugh when you're the butt of a joke
+- Never demean others for mistakes
+
+## Guidelines
+
+Less strict recommendations for professional behavior:
+
+- Use lunch hours for reading
+- Listen to podcasts during commute
+- Spend 90 minutes daily learning something new
+- Do kata to maintain skills in multiple languages
+- Pair program regularly but preserve alone time
+- Sit with new team members to show them the ropes
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Time investment**: Life circumstances may require temporary adjustment, but this should be exception not norm
+- **Test coverage**: Some mission-critical systems may need additional QA beyond automated tests
+- **Domain expertise**: You needn't be a domain expert, but due diligence is required
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Do No Harm - Function | Don't create bugs; own the ones that escape |
+| Do No Harm - Structure | Never sacrifice design for features |
+| QA Finds Nothing | Release only code you're certain about |
+| Know It Works | Test everything, automate everything |
+| Merciless Refactoring | Improve code every time you touch it |
+| Own Your Career | Invest 20 hours/week in growth |
+| Know Your Field | Master patterns, principles, methods, disciplines |
+| Never Stop Learning | Read, attend, participate continuously |
+| Practice | Do kata daily to sharpen skills |
+| Collaborate | Program and learn together |
+| Know Domain | Understand the business you're coding for |
+| Stay Humble | Accept you will fail; laugh at yourself |
diff --git a/.agents/skills/typescript-clean-code/references/saying-no/examples.md b/.agents/skills/typescript-clean-code/references/saying-no/examples.md
new file mode 100644
index 0000000..e41e58c
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/saying-no/examples.md
@@ -0,0 +1,169 @@
+# Saying No Examples
+
+Dialogue examples demonstrating professional ways to decline requests.
+
+## Bad Examples
+
+### Avoiding Confrontation (Both Parties Fail)
+
+> Paula: "Mike, I need the login page done by tomorrow."
+>
+> Mike: "Oh, wow! That soon? Well, OK, I'll try."
+>
+> Paula: "OK, that's great. Thanks!"
+
+**Problems**:
+- Paula is lying - she knows it takes longer than a day
+- Mike accepts "I'll try" as "Yes" - a dumb mistake
+- Both avoid confrontation but create future disaster
+- Neither party searched for the best possible outcome
+
+### Passive Acceptance (No Advocacy)
+
+> Paula: "Mike, I need the login page done by tomorrow."
+>
+> Mike: "Oh, sorry Mike, but it's going to take me more time than that."
+>
+> Paula: "When do you think you can have it done?"
+>
+> Mike: "How about two weeks from now?"
+>
+> Paula: (scribbles in daytimer) "OK, thanks."
+
+**Problems**:
+- Paula should state her timeline assertively, not ask permission
+- Mike accepts without question, as if his objectives don't matter
+- Likely to lead to passive-aggressive blame later
+- Neither defended their position
+
+### Manager Commits Team Without Input
+
+> Don: "OK Mike, the customer is coming in six weeks. They're expecting to see everything working."
+>
+> Mike: "Yes, and we'll be ready. My team is busting their butts and we're going to get it done. We'll have to work some overtime, but we'll make it happen!"
+>
+> Don: "It's great that you and your staff are such team players."
+
+**Problems**:
+- Mike committed Paula's team to something she explicitly said was impossible
+- Mike is playing for himself, not the team
+- "Team player" label rewards dishonesty
+- Disaster is now scheduled
+
+## Good Examples
+
+### Professional Negotiation
+
+> Mike: "Paula, I need the login page done by tomorrow."
+>
+> Paula: "No, Mike, that's a two-week job."
+>
+> Mike: "Two weeks? The architects estimated it at three days!"
+>
+> Paula: "The architects were wrong. I've got at least ten more days of work. Didn't you see my updated estimate on the wiki?"
+>
+> Mike: "This isn't acceptable Paula. Customers are coming tomorrow, and I need the login page working."
+>
+> Paula: "What part of the login page do you need working by tomorrow?"
+>
+> Mike: "I need to be able to log in."
+>
+> Paula: "I can give you a mock-up that lets you log in. It won't check passwords, email forgotten passwords, or have the news banner. But you'll be able to log in. Will that do?"
+>
+> Mike: "I'll be able to log in?"
+>
+> Paula: "Yes."
+>
+> Mike: "That's great Paula, you're a life saver!"
+
+**Why it works**:
+- Paula says no clearly and firmly
+- She offers what IS possible as an alternative
+- They negotiate to find the best possible outcome
+- Both parties get something valuable
+
+### Refusing to "Try"
+
+> Mike: "Come on Paula, can't you guys at least try?"
+>
+> Paula: "Mike, I could try to levitate. I could try to change lead into gold. I could try to swim across the Atlantic. Do you think I'd succeed?"
+>
+> Mike: "Now you're being unreasonable. I'm not asking for the impossible."
+>
+> Paula: "Yes, Mike, you are."
+
+**Why it works**:
+- Paula refuses the "try" trap clearly
+- Uses absurdity to show the request is impossible
+- Doesn't leave any room for false hope
+- Maintains her position despite pressure
+
+### Threatening Escalation Professionally
+
+> Paula: "Mike, have you told Don about my estimates?"
+>
+> Mike: "Yeah, but you were going to try anyway, right?"
+>
+> Paula: "We've already had that discussion. Remember, gold and lead?"
+>
+> Mike: "You've just got to do it. Please do whatever it takes."
+>
+> Paula: "Mike. I don't have to make this happen for you. What I have to do, if you don't, is tell Don."
+>
+> Mike: "That'd be going over my head."
+>
+> Paula: "I don't want to, but I will if you force me."
+
+**Why it works**:
+- Paula gives Mike the chance to act first
+- Clear deadline: "tomorrow I expect a meeting"
+- Documents in writing (memo)
+- Explains she's protecting both of them
+
+### High Stakes Confrontation
+
+> Charles: "Damn it Don! This was supposed to be done three weeks ago! You've got to do better."
+>
+> Don: "Chuck, I told you three months ago, after the layoffs, that we'd need four more months. You cut my staff twenty percent!"
+>
+> Charles: "Without Galitron, we're really hosed. Don, you've got to do better."
+>
+> Don: "There's nothing I can do Chuck. Galitron won't cut scope, won't accept interim releases. I cannot do that any faster. It's not going to happen."
+>
+> Charles: "I don't suppose it would matter if I told you your job was at stake."
+>
+> Don: "Firing me isn't going to change the estimate, Charles."
+
+**Why it works**:
+- Don stands firm under extreme pressure
+- Provides facts, not excuses
+- Doesn't cave even when job is threatened
+- CEO can now make informed decisions
+
+## Contrast: Same Situation, Different Approaches
+
+### The Wrong Response to Pressure
+
+> Bill and Jalil: "No, it's really got to be Friday. Can you at least try?"
+>
+> Team Lead: "OK, we'll try."
+
+**Result**: Blazing disaster. System crashed repeatedly. Customer told them to shut it down. Everyone quit.
+
+### The Right Response to Pressure
+
+> Bill and Jalil: "It's got to be ready by Friday."
+>
+> Professional Response: "Look, we just barely got this system to sort-of work. We need to shake down the troubles. We need four weeks. Friday is not possible."
+
+**Note**: The team lead should have maintained this position. Professionals speak truth to power and have the courage to say no to their managers.
+
+## Key Patterns
+
+| Situation | Bad Response | Good Response |
+|-----------|--------------|---------------|
+| Impossible deadline | "I'll try" | "No, that's a two-week job" |
+| Pressure to commit | Accept silently | "What part do you actually need?" |
+| Repeated manipulation | Eventually cave | "We've had this discussion" |
+| Boss ignores warnings | Passive aggression | "I will escalate tomorrow" |
+| Threatened with firing | Cave to pressure | "Firing me won't change the estimate" |
diff --git a/.agents/skills/typescript-clean-code/references/saying-no/knowledge.md b/.agents/skills/typescript-clean-code/references/saying-no/knowledge.md
new file mode 100644
index 0000000..63a14f0
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/saying-no/knowledge.md
@@ -0,0 +1,92 @@
+# Saying No Knowledge
+
+Core concepts and foundational understanding for professional communication and the art of saying no.
+
+## Overview
+
+Saying no is a fundamental professional skill. Professionals are expected to say no when necessary - it's how teams reach the best possible outcomes. The ability to decline requests appropriately protects projects, teams, and organizations from disaster.
+
+## Key Concepts
+
+### Adversarial Roles
+
+**Definition**: The productive tension between managers and developers pursuing their respective objectives.
+
+Managers pursue and defend their objectives aggressively - that's their job. Developers must do the same for their objectives. This adversarial dynamic leads to the best possible outcomes through negotiation.
+
+**Key points**:
+- Both parties defending their positions leads to better solutions
+- Avoiding confrontation often leads to dysfunction
+- The goal is finding a mutually acceptable outcome, not winning
+
+### High Stakes Situations
+
+**Definition**: Scenarios where the cost of failure threatens the survival of a project, team, or company.
+
+The most important time to say no is when stakes are highest. When company survival depends on accurate information, you must give managers the best information possible - even if that means saying no.
+
+**Key points**:
+- Higher stakes make honest "no" more valuable
+- Hiding bad news makes disasters worse
+- Your job is to provide accurate information, not false hope
+
+### Being a Team Player
+
+**Definition**: Playing your position well and helping teammates - which includes saying no when necessary.
+
+A team player is NOT someone who says yes all the time. True team players communicate frequently, defend their estimates, and represent what can and cannot be done accurately.
+
+**Key points**:
+- Saying yes to impossible requests is NOT being a team player
+- Defending accurate estimates protects the whole team
+- Committing others to impossible deadlines is selfish, not collaborative
+
+### The Cost of Saying Yes
+
+**Definition**: The negative consequences that result from agreeing to unrealistic commitments.
+
+Saying yes to impossible deadlines leads to: rushed code, dropped quality practices, family sacrifice, team burnout, and ultimately project failure. The "hero" who says yes to everything often causes the most damage.
+
+**Key points**:
+- Rushing creates technical debt and bugs
+- Overtime makes teams slower, not faster
+- Dropped quality practices multiply problems
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Best Possible Outcome | The goal shared by managers and developers, found through negotiation |
+| Professional | Someone expected to say no and defend their objectives |
+| Passive Aggression | Letting someone fail rather than confronting the issue directly |
+| The Brass Ring | The temptation to be a hero by accepting impossible tasks |
+
+## How It Relates To
+
+- **Estimation**: Saying no protects your estimates from unrealistic pressure
+- **Commitment**: A "no" now prevents a broken commitment later
+- **Code Quality**: Saying no to rushed timelines protects code quality
+- **Team Dynamics**: Honest disagreement leads to better solutions
+
+## Common Misconceptions
+
+- **Myth**: Professionals always do what their boss says
+  **Reality**: Professionals are expected to say no - good managers crave it
+
+- **Myth**: Team players say yes to help the team
+  **Reality**: Team players defend accurate estimates to protect the team
+
+- **Myth**: Saying no is insubordination
+  **Reality**: Slaves can't say no; laborers hesitate; professionals say no
+
+- **Myth**: Adversarial relationships are bad for teams
+  **Reality**: Constructive tension through defended positions yields best outcomes
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Adversarial Roles | Manager vs developer tension leads to best outcomes |
+| High Stakes | More valuable to say no when stakes are higher |
+| Team Player | Defends estimates, doesn't just agree to everything |
+| Cost of Yes | Agreeing to impossible tasks causes more harm than no |
diff --git a/.agents/skills/typescript-clean-code/references/saying-no/rules.md b/.agents/skills/typescript-clean-code/references/saying-no/rules.md
new file mode 100644
index 0000000..622ee14
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/saying-no/rules.md
@@ -0,0 +1,94 @@
+# Saying No Rules
+
+Guidelines for when and how to decline requests professionally.
+
+## Core Rules
+
+### 1. Say No to Impossible Commitments
+
+If you know something cannot be done by the requested deadline, say no clearly.
+
+- Don't agree hoping things will work out
+- Don't cave to pressure or intimidation
+- State the fact plainly: "No, that's a two-week job"
+
+### 2. Never Promise to "Try"
+
+The promise to try implies you were holding back effort before.
+
+- "Trying" is a commitment to succeed with extra effort
+- If you have no new plan, promising to try is dishonest
+- Either you can do it or you can't - "trying" is a lie
+
+### 3. Avoid Passive Aggression
+
+Don't let others walk off a cliff just to prove you were right.
+
+- Escalate when someone won't communicate bad news
+- Warn teammates of impending disasters
+- Cover-your-ass memos are not enough - take action
+
+### 4. Defend Your Estimates Under Pressure
+
+Maintain your position through wheedling, cajoling, and manipulation.
+
+- Keep stating the uncertainty: "eight or nine weeks"
+- Don't suggest extra effort could change the outcome
+- Document your estimates in writing (memos, email)
+
+### 5. Negotiate Toward the Best Outcome
+
+Say no, then work together to find what IS possible.
+
+- Ask what parts are actually needed
+- Offer alternatives with reduced scope
+- Find the mutually acceptable solution
+
+## Guidelines
+
+Less strict recommendations:
+
+- Explain the "why" only if it helps - facts matter more than reasons
+- Too much detail invites micro-management
+- When escalating, give the person a chance to act first
+- Set deadlines for action before going over someone's head
+
+## When to Escalate
+
+Circumstances requiring you to go above someone's head:
+
+- **Ignored warnings**: They won't tell their boss about real problems
+- **Approaching disaster**: Customers will arrive expecting impossible deliverables
+- **Continued manipulation**: Repeated attempts to get you to "try"
+
+Always give warning first: "If that meeting doesn't happen tomorrow, I will be forced to go to Don myself."
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Genuine new information**: If scope actually shrinks, revise estimates
+- **Real options emerge**: New resources or timeline extensions change facts
+- **Collaborative problem-solving**: Brainstorming alternatives is not caving
+
+## What NOT to Do
+
+Behaviors to avoid:
+
+- Don't say "OK, I'll try" to avoid confrontation
+- Don't accept dates without defending your objectives
+- Don't let others commit you to impossible deadlines
+- Don't sacrifice quality practices to meet unrealistic dates
+- Don't work 80-hour weeks hoping to be a hero
+- Don't stay silent when you see a disaster coming
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| No to Impossible | State clearly when something cannot be done |
+| Never "Try" | Trying implies you were holding back |
+| No Passive Aggression | Warn people, don't just let them fail |
+| Defend Estimates | Maintain position through pressure |
+| Negotiate Solutions | Say no, then find what IS possible |
+| Escalate When Needed | Go up the chain if warnings are ignored |
diff --git a/.agents/skills/typescript-clean-code/references/smells/examples.md b/.agents/skills/typescript-clean-code/references/smells/examples.md
new file mode 100644
index 0000000..52449ba
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/smells/examples.md
@@ -0,0 +1,437 @@
+# Code Smells Examples
+
+TypeScript examples demonstrating key code smells and their fixes.
+
+## G5: Duplication
+
+### Bad Example
+
+```typescript
+// Duplication - copy-pasted logic
+function calculateRegularPay(employee: Employee): number {
+  const hoursWorked = employee.getHoursWorked();
+  const hourlyRate = employee.getHourlyRate();
+  const straightTime = Math.min(40, hoursWorked);
+  return straightTime * hourlyRate;
+}
+
+function calculateOvertimePay(employee: Employee): number {
+  const hoursWorked = employee.getHoursWorked();
+  const hourlyRate = employee.getHourlyRate();
+  const straightTime = Math.min(40, hoursWorked);
+  const overtime = Math.max(0, hoursWorked - straightTime);
+  return straightTime * hourlyRate + overtime * hourlyRate * 1.5;
+}
+```
+
+**Problems**:
+- Hours and rate retrieval duplicated
+- Straight time calculation duplicated
+- Changes require updating both functions
+
+### Good Example
+
+```typescript
+function calculatePay(employee: Employee): PayBreakdown {
+  const hours = employee.getHoursWorked();
+  const rate = employee.getHourlyRate();
+  const straightHours = Math.min(40, hours);
+  const overtimeHours = Math.max(0, hours - 40);
+  
+  return {
+    straight: straightHours * rate,
+    overtime: overtimeHours * rate * 1.5,
+    total: straightHours * rate + overtimeHours * rate * 1.5
+  };
+}
+```
+
+**Why it works**:
+- Single source of truth for pay calculation
+- Changes only need to be made once
+
+---
+
+## G6: Wrong Level of Abstraction
+
+### Bad Example
+
+```typescript
+interface Stack<T> {
+  push(item: T): void;
+  pop(): T | undefined;
+  peek(): T | undefined;
+  isEmpty(): boolean;
+  // Wrong level - not all stacks have bounded capacity
+  percentFull(): number;
+  isFull(): boolean;
+}
+```
+
+**Problems**:
+- `percentFull()` assumes bounded capacity
+- Unbounded stacks can't implement this meaningfully
+- Forcing implementations to lie (return 0) or throw
+
+### Good Example
+
+```typescript
+interface Stack<T> {
+  push(item: T): void;
+  pop(): T | undefined;
+  peek(): T | undefined;
+  isEmpty(): boolean;
+}
+
+interface BoundedStack<T> extends Stack<T> {
+  readonly capacity: number;
+  percentFull(): number;
+  isFull(): boolean;
+}
+```
+
+**Why it works**:
+- Base interface has only universal operations
+- Capacity concepts isolated in appropriate derivative
+
+---
+
+## G14: Feature Envy
+
+### Bad Example
+
+```typescript
+class HourlyPayCalculator {
+  calculateWeeklyPay(employee: HourlyEmployee): Money {
+    // This method "envies" HourlyEmployee - uses all its data
+    const tenthRate = employee.getTenthRate().getPennies();
+    const tenthsWorked = employee.getTenthsWorked();
+    const straightTime = Math.min(400, tenthsWorked);
+    const overtime = Math.max(0, tenthsWorked - straightTime);
+    const straightPay = straightTime * tenthRate;
+    const overtimePay = Math.round(overtime * tenthRate * 1.5);
+    return new Money(straightPay + overtimePay);
+  }
+}
+```
+
+**Problems**:
+- Calculator reaches deep into Employee for all data
+- Exposes Employee's internal structure
+- Logic belongs with the data it operates on
+
+### Good Example
+
+```typescript
+class HourlyEmployee {
+  private tenthRate: Money;
+  private tenthsWorked: number;
+
+  calculateWeeklyPay(): Money {
+    const straightPay = this.calculateStraightPay();
+    const overtimePay = this.calculateOvertimePay();
+    return straightPay.add(overtimePay);
+  }
+
+  private calculateStraightPay(): Money {
+    const straightTenths = Math.min(400, this.tenthsWorked);
+    return this.tenthRate.times(straightTenths);
+  }
+
+  private calculateOvertimePay(): Money {
+    const overtimeTenths = Math.max(0, this.tenthsWorked - 400);
+    return this.tenthRate.times(overtimeTenths).times(1.5);
+  }
+}
+```
+
+**Why it works**:
+- Calculation lives with its data
+- Employee encapsulates its own business logic
+- External callers don't need to know internal structure
+
+### Acceptable Feature Envy
+
+```typescript
+// Sometimes feature envy is acceptable - reporting shouldn't be in domain
+class HourlyEmployeeReport {
+  constructor(private employee: HourlyEmployee) {}
+
+  formatHoursWorked(): string {
+    // Envy is OK here - we don't want Employee coupled to reporting
+    const hours = Math.floor(this.employee.getTenthsWorked() / 10);
+    const tenths = this.employee.getTenthsWorked() % 10;
+    return `${this.employee.getName()}: ${hours}.${tenths} hours`;
+  }
+}
+```
+
+---
+
+## G23: Prefer Polymorphism to Switch
+
+### Bad Example
+
+```typescript
+// Multiple switches on same type - scattered throughout codebase
+function calculateArea(shape: Shape): number {
+  switch (shape.type) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rectangle':
+      return shape.width * shape.height;
+    case 'triangle':
+      return (shape.base * shape.height) / 2;
+  }
+}
+
+function calculatePerimeter(shape: Shape): number {
+  switch (shape.type) {
+    case 'circle':
+      return 2 * Math.PI * shape.radius;
+    case 'rectangle':
+      return 2 * (shape.width + shape.height);
+    case 'triangle':
+      return shape.sideA + shape.sideB + shape.sideC;
+  }
+}
+
+function draw(shape: Shape): void {
+  switch (shape.type) {
+    case 'circle':
+      drawCircle(shape);
+      break;
+    case 'rectangle':
+      drawRectangle(shape);
+      break;
+    case 'triangle':
+      drawTriangle(shape);
+      break;
+  }
+}
+```
+
+**Problems**:
+- Adding new shape requires changing multiple functions
+- Switch statements duplicated everywhere
+- Easy to miss a case when adding shapes
+
+### Good Example
+
+```typescript
+// ONE SWITCH creates objects, polymorphism handles the rest
+interface Shape {
+  calculateArea(): number;
+  calculatePerimeter(): number;
+  draw(): void;
+}
+
+class Circle implements Shape {
+  constructor(private radius: number) {}
+  
+  calculateArea(): number {
+    return Math.PI * this.radius ** 2;
+  }
+  
+  calculatePerimeter(): number {
+    return 2 * Math.PI * this.radius;
+  }
+  
+  draw(): void {
+    // Circle-specific drawing
+  }
+}
+
+class Rectangle implements Shape {
+  constructor(private width: number, private height: number) {}
+  
+  calculateArea(): number {
+    return this.width * this.height;
+  }
+  
+  calculatePerimeter(): number {
+    return 2 * (this.width + this.height);
+  }
+  
+  draw(): void {
+    // Rectangle-specific drawing
+  }
+}
+
+// Only one switch - in factory
+function createShape(config: ShapeConfig): Shape {
+  switch (config.type) {
+    case 'circle':
+      return new Circle(config.radius);
+    case 'rectangle':
+      return new Rectangle(config.width, config.height);
+    default:
+      throw new Error(`Unknown shape: ${config.type}`);
+  }
+}
+```
+
+**Why it works**:
+- New shapes only require new class + factory update
+- No scattered switch statements to maintain
+- Compiler enforces interface implementation
+
+---
+
+## G30: Functions Should Do One Thing
+
+### Bad Example
+
+```typescript
+function pay(employees: Employee[]): void {
+  for (const employee of employees) {
+    if (employee.isPayday()) {
+      const pay = employee.calculatePay();
+      employee.deliverPay(pay);
+    }
+  }
+}
+```
+
+**Problems**:
+- Function does three things: iterates, checks, and pays
+- Hard to reuse individual operations
+- Single responsibility violated
+
+### Good Example
+
+```typescript
+function pay(employees: Employee[]): void {
+  for (const employee of employees) {
+    payIfNecessary(employee);
+  }
+}
+
+function payIfNecessary(employee: Employee): void {
+  if (employee.isPayday()) {
+    calculateAndDeliverPay(employee);
+  }
+}
+
+function calculateAndDeliverPay(employee: Employee): void {
+  const pay = employee.calculatePay();
+  employee.deliverPay(pay);
+}
+```
+
+**Why it works**:
+- Each function does exactly one thing
+- Functions are composable and testable
+- Intent is clear from function names
+
+---
+
+## G31: Hidden Temporal Couplings
+
+### Bad Example
+
+```typescript
+class MoogDiver {
+  private gradient: Gradient;
+  private splines: Spline[];
+
+  dive(reason: string): void {
+    // Order matters but nothing enforces it
+    this.saturateGradient();
+    this.reticulateSplines();
+    this.diveForMoog(reason);
+  }
+}
+```
+
+**Problems**:
+- Call order is critical but not enforced
+- Easy to reorder incorrectly
+- No compile-time protection
+
+### Good Example
+
+```typescript
+class MoogDiver {
+  dive(reason: string): void {
+    // Each step produces input for next - order is enforced
+    const gradient = this.saturateGradient();
+    const splines = this.reticulateSplines(gradient);
+    this.diveForMoog(splines, reason);
+  }
+
+  private saturateGradient(): Gradient {
+    // Returns gradient needed by next step
+  }
+
+  private reticulateSplines(gradient: Gradient): Spline[] {
+    // Requires gradient, returns splines
+  }
+
+  private diveForMoog(splines: Spline[], reason: string): void {
+    // Requires splines from previous step
+  }
+}
+```
+
+**Why it works**:
+- Dependencies are explicit in function signatures
+- Cannot call out of order - won't compile
+- Temporal coupling is now a physical coupling
+
+---
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+function renderHorizontalRule(size: number): string {
+  let html = '<hr';
+  if (size > 0) {
+    html += ` size="${size + 1}"`;
+  }
+  html += '>';
+  return html;
+}
+```
+
+### After
+
+```typescript
+function renderHorizontalRule(extraDashes: number): string {
+  const hr = new HtmlTag('hr');
+  if (extraDashes > 0) {
+    hr.addAttribute('size', formatHrSize(extraDashes));
+  }
+  return hr.toHtml();
+}
+
+function formatHrSize(extraDashes: number): string {
+  return String(extraDashes + 1);
+}
+
+class HtmlTag {
+  private attributes: Map<string, string> = new Map();
+  
+  constructor(private tagName: string) {}
+  
+  addAttribute(name: string, value: string): void {
+    this.attributes.set(name, value);
+  }
+  
+  toHtml(): string {
+    const attrs = Array.from(this.attributes)
+      .map(([k, v]) => ` ${k}="${v}"`)
+      .join('');
+    return `<${this.tagName}${attrs} />`;
+  }
+}
+```
+
+### Changes Made
+
+1. **Renamed parameter** - `size` to `extraDashes` reveals true meaning
+2. **Separated abstraction levels** - HTML syntax isolated in `HtmlTag` class
+3. **Extracted formatting** - Size calculation in dedicated function
+4. **Fixed bug** - Original missed XHTML closing slash; `HtmlTag` handles correctly
diff --git a/.agents/skills/typescript-clean-code/references/smells/knowledge.md b/.agents/skills/typescript-clean-code/references/smells/knowledge.md
new file mode 100644
index 0000000..71823c8
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/smells/knowledge.md
@@ -0,0 +1,102 @@
+# Code Smells Knowledge
+
+Core concepts and foundational understanding for identifying and addressing code smells.
+
+## Overview
+
+Code smells are indicators of deeper problems in code. They are not bugs - the code may work correctly - but they suggest weaknesses in design that may slow development or increase the risk of bugs or failures in the future. This chapter compiles heuristics for recognizing and eliminating common smells.
+
+## Key Concepts
+
+### Code Smell
+
+**Definition**: A surface indication that usually corresponds to a deeper problem in the system.
+
+Code smells are warning signs, not definitive rules. They require judgment to evaluate - some smells may be acceptable in certain contexts while being problematic in others.
+
+**Key points**:
+- Smells indicate potential problems, not guaranteed defects
+- Each smell suggests specific refactoring techniques
+- Multiple smells often compound each other
+
+### Heuristic
+
+**Definition**: A practical approach to problem-solving that may not be optimal but is sufficient for finding satisfactory solutions.
+
+The smells in this chapter are heuristics - they guide decision-making but don't mandate specific actions. Use them to question your code, not as absolute rules.
+
+### The DRY Principle
+
+**Definition**: Don't Repeat Yourself - every piece of knowledge should have a single, unambiguous representation in a system.
+
+Duplication is the root of many smells. When you find duplication, you've found an opportunity for abstraction.
+
+## Smell Categories
+
+| Category | Focus Area | Count |
+|----------|------------|-------|
+| Comments (C) | Comment quality and necessity | 5 |
+| Environment (E) | Build and test processes | 2 |
+| Functions (F) | Function design issues | 4 |
+| General (G) | Broad design heuristics | 36 |
+| Names (N) | Naming conventions | 7 |
+| Tests (T) | Testing practices | 9 |
+
+## Category Overview
+
+### Comments (C1-C5)
+Problems with comments including inappropriate information, obsolete content, redundancy, poor writing, and commented-out code. Comments should explain *why*, not *what*.
+
+### Environment (E1-E2)
+Build and test execution should be simple one-step operations. Complexity here slows the entire development cycle.
+
+### Functions (F1-F4)
+Function design issues: too many arguments, output arguments, flag arguments, and dead functions. Functions should be small, focused, and intuitive.
+
+### General (G1-G36)
+The largest category covering design principles, abstraction levels, coupling, precision, and code organization. These are universal heuristics applicable to any codebase.
+
+### Names (N1-N7)
+Naming should be descriptive, unambiguous, and follow conventions. Names are the primary way code communicates intent.
+
+### Tests (T1-T9)
+Tests should be comprehensive, fast, and easy to run. They are the safety net that enables refactoring and continuous improvement.
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Refactoring | Restructuring code without changing external behavior |
+| Abstraction | Hiding implementation details behind an interface |
+| Coupling | Degree of interdependence between modules |
+| Cohesion | Degree to which elements of a module belong together |
+| Polymorphism | Ability to process objects differently based on type |
+
+## How It Relates To
+
+- **Clean Functions**: Many smells (F1-F4, G30) directly address function design
+- **Meaningful Names**: The naming smells (N1-N7) expand on naming principles
+- **Comments**: C1-C5 reinforce when comments are harmful vs. helpful
+- **Error Handling**: G3 (boundary conditions), G4 (overridden safeties) relate to robustness
+- **Testing**: T1-T9 connect to TDD and test-first development
+
+## Common Misconceptions
+
+- **Myth**: Eliminating all smells guarantees clean code
+  **Reality**: Smells are heuristics, not absolute rules. Context matters.
+
+- **Myth**: Code that works doesn't need smell checking
+  **Reality**: Smells affect maintainability, not just correctness.
+
+- **Myth**: Fixing smells always improves code
+  **Reality**: Over-engineering to avoid smells can be worse than the smell itself.
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Code Smell | Surface indicator of deeper design problems |
+| DRY | Don't Repeat Yourself - eliminate duplication |
+| Law of Demeter | Only talk to immediate collaborators |
+| Single Responsibility | Each module should have one reason to change |
+| Least Surprise | Code should behave as readers expect |
diff --git a/.agents/skills/typescript-clean-code/references/smells/rules.md b/.agents/skills/typescript-clean-code/references/smells/rules.md
new file mode 100644
index 0000000..567cbb3
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/smells/rules.md
@@ -0,0 +1,514 @@
+# Code Smells Reference
+
+Complete catalog of code smells organized by category. Use for code review and refactoring.
+
+---
+
+## Comments (C1-C5)
+
+### C1: Inappropriate Information
+
+**What it is**: Comments containing metadata (change history, authors, dates, ticket numbers)
+
+**How to fix**: Move to source control, issue tracker, or other record-keeping systems. Comments are for technical notes only.
+
+---
+
+### C2: Obsolete Comment
+
+**What it is**: Comments that are old, irrelevant, or incorrect
+
+**How to fix**: Update or delete immediately. Obsolete comments mislead readers.
+
+---
+
+### C3: Redundant Comment
+
+**What it is**: Comments that describe what code already clearly shows
+
+**How to fix**: Delete the comment. Let the code speak for itself.
+
+```typescript
+// Bad
+i++; // increment i
+
+// Good - no comment needed
+i++;
+```
+
+---
+
+### C4: Poorly Written Comment
+
+**What it is**: Comments with bad grammar, unclear wording, or rambling explanations
+
+**How to fix**: Rewrite concisely with correct grammar. If worth writing, write well.
+
+---
+
+### C5: Commented-Out Code
+
+**What it is**: Code blocks left commented out "just in case"
+
+**How to fix**: Delete it. Source control remembers everything.
+
+---
+
+## Environment (E1-E2)
+
+### E1: Build Requires More Than One Step
+
+**What it is**: Complex build processes requiring multiple commands or manual steps
+
+**How to fix**: Single command to check out and build:
+```bash
+git clone mySystem
+cd mySystem
+npm install && npm run build
+```
+
+---
+
+### E2: Tests Require More Than One Step
+
+**What it is**: Running tests requires multiple commands or manual configuration
+
+**How to fix**: Single command to run all tests: `npm test`
+
+---
+
+## Functions (F1-F4)
+
+### F1: Too Many Arguments
+
+**What it is**: Functions with more than three arguments
+
+**How to fix**: 
+- Group related arguments into objects
+- Split function into smaller functions
+- Zero arguments is best, then one, two, three
+
+---
+
+### F2: Output Arguments
+
+**What it is**: Arguments used to return values instead of using return statements
+
+**How to fix**: Return values directly. If state must change, change the owning object.
+
+---
+
+### F3: Flag Arguments
+
+**What it is**: Boolean arguments that select between behaviors
+
+**How to fix**: Split into separate functions - one for each behavior.
+
+---
+
+### F4: Dead Function
+
+**What it is**: Functions that are never called
+
+**How to fix**: Delete them. Source control remembers.
+
+---
+
+## General (G1-G36)
+
+### G1: Multiple Languages in One Source File
+
+**What it is**: Mixing languages (HTML in TS, SQL strings, embedded JSON)
+
+**How to fix**: Minimize extra languages. Separate concerns into distinct files.
+
+---
+
+### G2: Obvious Behavior Is Unimplemented
+
+**What it is**: Functions that don't do what their names suggest
+
+**How to fix**: Implement expected behaviors. Follow Principle of Least Surprise.
+
+---
+
+### G3: Incorrect Behavior at the Boundaries
+
+**What it is**: Missing edge case handling, untested corner cases
+
+**How to fix**: Test every boundary condition explicitly. Don't trust intuition.
+
+---
+
+### G4: Overridden Safeties
+
+**What it is**: Disabling warnings, skipping tests, bypassing validations
+
+**How to fix**: Fix the underlying issues. Don't suppress symptoms.
+
+---
+
+### G5: Duplication
+
+**What it is**: Repeated code, similar switch statements, parallel algorithms
+
+**How to fix**:
+- Identical code: Extract to function
+- Similar conditionals: Use polymorphism
+- Similar algorithms: Template Method or Strategy pattern
+
+---
+
+### G6: Code at Wrong Level of Abstraction
+
+**What it is**: Implementation details in base classes, generic code in specific classes
+
+**How to fix**: Separate high-level concepts from low-level details completely.
+
+---
+
+### G7: Base Classes Depending on Their Derivatives
+
+**What it is**: Base classes that reference or know about derived classes
+
+**How to fix**: Base classes should be ignorant of derivatives. Invert dependencies.
+
+---
+
+### G8: Too Much Information
+
+**What it is**: Classes with too many methods, variables, or public members
+
+**How to fix**: Hide data, utility functions, constants. Minimize interfaces.
+
+---
+
+### G9: Dead Code
+
+**What it is**: Unreachable code, unused variables, uncalled functions
+
+**How to fix**: Delete it. Dead code rots and misleads.
+
+---
+
+### G10: Vertical Separation
+
+**What it is**: Variables declared far from usage, functions far from callers
+
+**How to fix**: Declare variables just before use. Define functions just below first call.
+
+---
+
+### G11: Inconsistency
+
+**What it is**: Similar things done differently throughout the codebase
+
+**How to fix**: Choose conventions and follow them consistently.
+
+---
+
+### G12: Clutter
+
+**What it is**: Default constructors, unused variables, meaningless comments
+
+**How to fix**: Remove anything that adds no value.
+
+---
+
+### G13: Artificial Coupling
+
+**What it is**: Dependencies that serve no direct purpose (enums in unrelated classes)
+
+**How to fix**: Place items where they logically belong, not where convenient.
+
+---
+
+### G14: Feature Envy
+
+**What it is**: Methods that use more of another class than their own
+
+**How to fix**: Move the method to the class it envies, or rethink responsibilities.
+
+---
+
+### G15: Selector Arguments
+
+**What it is**: Arguments (boolean, enum) that select function behavior
+
+**How to fix**: Split into multiple functions with descriptive names.
+
+---
+
+### G16: Obscured Intent
+
+**What it is**: Dense expressions, magic numbers, cryptic abbreviations
+
+**How to fix**: Use explanatory variables and meaningful names.
+
+---
+
+### G17: Misplaced Responsibility
+
+**What it is**: Code placed where convenient rather than where expected
+
+**How to fix**: Follow Principle of Least Surprise. Place code where readers expect it.
+
+---
+
+### G18: Inappropriate Static
+
+**What it is**: Static methods that should be polymorphic instance methods
+
+**How to fix**: Prefer non-static. Use static only when polymorphism is impossible.
+
+---
+
+### G19: Use Explanatory Variables
+
+**What it is**: Complex expressions without intermediate named values
+
+**How to fix**: Break calculations into well-named intermediate variables.
+
+---
+
+### G20: Function Names Should Say What They Do
+
+**What it is**: Ambiguous names like `add()` that don't explain behavior
+
+**How to fix**: Names should reveal intent: `addDaysTo()` or `daysLater()`.
+
+---
+
+### G21: Understand the Algorithm
+
+**What it is**: Code that works by accident, with unclear logic
+
+**How to fix**: Refactor until the algorithm is obvious. Know why it works.
+
+---
+
+### G22: Make Logical Dependencies Physical
+
+**What it is**: Assumptions between modules not enforced in code
+
+**How to fix**: Make dependencies explicit through parameters and interfaces.
+
+---
+
+### G23: Prefer Polymorphism to If/Else or Switch/Case
+
+**What it is**: Type-checking conditionals repeated throughout code
+
+**How to fix**: ONE SWITCH rule - one switch creates polymorphic objects, no others.
+
+---
+
+### G24: Follow Standard Conventions
+
+**What it is**: Inconsistent style, non-standard patterns
+
+**How to fix**: Follow team/industry conventions. Let code be the style guide.
+
+---
+
+### G25: Replace Magic Numbers with Named Constants
+
+**What it is**: Raw numbers without context: `86400`, `55`, `7777`
+
+**How to fix**: Use constants: `SECONDS_PER_DAY`, `LINES_PER_PAGE`.
+
+---
+
+### G26: Be Precise
+
+**What it is**: Lazy decisions, unchecked nulls, ignored edge cases
+
+**How to fix**: Handle all cases explicitly. Use appropriate types.
+
+---
+
+### G27: Structure over Convention
+
+**What it is**: Relying on naming to enforce design instead of code structure
+
+**How to fix**: Use abstract classes/interfaces to force compliance.
+
+---
+
+### G28: Encapsulate Conditionals
+
+**What it is**: Complex boolean expressions inline in if statements
+
+**How to fix**: Extract to well-named functions.
+
+```typescript
+// Bad
+if (timer.hasExpired() && !timer.isRecurrent())
+
+// Good
+if (shouldBeDeleted(timer))
+```
+
+---
+
+### G29: Avoid Negative Conditionals
+
+**What it is**: Negated conditions that are harder to understand
+
+**How to fix**: Express positively: `shouldCompact()` not `!shouldNotCompact()`.
+
+---
+
+### G30: Functions Should Do One Thing
+
+**What it is**: Functions with multiple distinct operations
+
+**How to fix**: Extract each operation into its own function.
+
+---
+
+### G31: Hidden Temporal Couplings
+
+**What it is**: Function call order requirements not visible in code
+
+**How to fix**: Chain results - each function produces what the next needs.
+
+---
+
+### G32: Don't Be Arbitrary
+
+**What it is**: Structure without clear purpose
+
+**How to fix**: Have reasons for structure. Make them evident in code.
+
+---
+
+### G33: Encapsulate Boundary Conditions
+
+**What it is**: `+1` and `-1` scattered throughout code
+
+**How to fix**: Capture in named variables: `nextLevel = level + 1`.
+
+---
+
+### G34: Functions Should Descend Only One Level of Abstraction
+
+**What it is**: Mixing high-level logic with low-level details
+
+**How to fix**: Keep each function at one abstraction level.
+
+---
+
+### G35: Keep Configurable Data at High Levels
+
+**What it is**: Configuration values buried in low-level code
+
+**How to fix**: Define defaults at top level, pass down as parameters.
+
+---
+
+### G36: Avoid Transitive Navigation
+
+**What it is**: Chain calls like `a.getB().getC().doSomething()`
+
+**How to fix**: Law of Demeter - talk only to immediate collaborators.
+
+---
+
+## Names (N1-N7)
+
+### N1: Choose Descriptive Names
+
+**What it is**: Names that don't reveal intent
+
+**How to fix**: Names should describe what and why, not how.
+
+### N2: Choose Names at the Appropriate Level of Abstraction
+
+**What it is**: Implementation details in interface names
+
+**How to fix**: Name for concept level, not implementation.
+
+### N3: Use Standard Nomenclature Where Possible
+
+**What it is**: Custom names for well-known patterns
+
+**How to fix**: Use recognized terms (Factory, Visitor, Decorator).
+
+### N4: Unambiguous Names
+
+**What it is**: Names that could mean multiple things
+
+**How to fix**: Be specific. Disambiguate.
+
+### N5: Use Long Names for Long Scopes
+
+**What it is**: Short names used across large scopes
+
+**How to fix**: Scope determines length. Longer scope = longer name.
+
+### N6: Avoid Encodings
+
+**What it is**: Type prefixes, Hungarian notation
+
+**How to fix**: Let the type system handle types. Name for meaning.
+
+### N7: Names Should Describe Side-Effects
+
+**What it is**: Names hiding what functions actually do
+
+**How to fix**: Reveal all effects: `createOrReturnOos()` not `getOos()`.
+
+---
+
+## Tests (T1-T9)
+
+### T1: Insufficient Tests
+
+**How to fix**: Test everything that could break. Use coverage tools.
+
+### T2: Use a Coverage Tool
+
+**How to fix**: Run coverage reports. Fill gaps in tested code.
+
+### T3: Don't Skip Trivial Tests
+
+**How to fix**: Trivial tests document behavior and catch regressions.
+
+### T4: An Ignored Test Is a Question about an Ambiguity
+
+**How to fix**: Resolve ambiguity, then enable or remove the test.
+
+### T5: Test Boundary Conditions
+
+**How to fix**: Explicitly test edges, corners, and limits.
+
+### T6: Exhaustively Test Near Bugs
+
+**How to fix**: Bugs cluster. When you find one, test the surrounding code.
+
+### T7: Patterns of Failure Are Revealing
+
+**How to fix**: Analyze which tests fail together to find root causes.
+
+### T8: Test Coverage Patterns Can Be Revealing
+
+**How to fix**: Look at what's untested - it often reveals design problems.
+
+### T9: Tests Should Be Fast
+
+**How to fix**: Slow tests don't get run. Keep them fast.
+
+---
+
+## Quick Detection Table
+
+| ID | Smell | Key Indicator |
+|----|-------|---------------|
+| C5 | Commented-Out Code | `//` or `/* */` around functional code |
+| G5 | Duplication | Copy-pasted blocks, similar switches |
+| G9 | Dead Code | Unreachable branches, uncalled functions |
+| G14 | Feature Envy | Method uses other class more than own |
+| G23 | Overuse of Switch | Multiple switches on same type |
+| G30 | Does Too Much | Function has multiple sections |
+| G36 | Law of Demeter | Chain of getters: `a.b().c().d()` |
diff --git a/.agents/skills/typescript-clean-code/references/tdd/examples.md b/.agents/skills/typescript-clean-code/references/tdd/examples.md
new file mode 100644
index 0000000..71229e7
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/tdd/examples.md
@@ -0,0 +1,174 @@
+# TDD Examples
+
+Code examples demonstrating the TDD red-green-refactor cycle in TypeScript.
+
+## The TDD Cycle in Practice
+
+### Example: Building a Stack
+
+We'll build a simple Stack class following the three laws of TDD.
+
+#### Cycle 1: Empty Stack
+
+**Red** - Write a failing test:
+
+```typescript
+// stack.test.ts
+import { Stack } from './stack';
+
+describe('Stack', () => {
+  it('should be empty when created', () => {
+    const stack = new Stack<number>();
+    expect(stack.isEmpty()).toBe(true);
+  });
+});
+```
+
+**Green** - Write minimal code to pass:
+
+```typescript
+// stack.ts
+export class Stack<T> {
+  isEmpty(): boolean {
+    return true;
+  }
+}
+```
+
+**Why it works**:
+- Test fails first (Stack doesn't exist)
+- We write just enough to compile and pass
+- No unnecessary code
+
+#### Cycle 2: Push Makes Non-Empty
+
+**Red** - Write the next failing test:
+
+```typescript
+it('should not be empty after push', () => {
+  const stack = new Stack<number>();
+  stack.push(1);
+  expect(stack.isEmpty()).toBe(false);
+});
+```
+
+**Green** - Make it pass:
+
+```typescript
+export class Stack<T> {
+  private items: T[] = [];
+
+  isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+
+  push(item: T): void {
+    this.items.push(item);
+  }
+}
+```
+
+#### Cycle 3: Pop Returns Pushed Item
+
+**Red**:
+
+```typescript
+it('should pop the pushed item', () => {
+  const stack = new Stack<number>();
+  stack.push(42);
+  expect(stack.pop()).toBe(42);
+});
+```
+
+**Green**:
+
+```typescript
+export class Stack<T> {
+  private items: T[] = [];
+
+  isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+
+  push(item: T): void {
+    this.items.push(item);
+  }
+
+  pop(): T | undefined {
+    return this.items.pop();
+  }
+}
+```
+
+#### Cycle 4: LIFO Order
+
+**Red**:
+
+```typescript
+it('should pop in LIFO order', () => {
+  const stack = new Stack<number>();
+  stack.push(1);
+  stack.push(2);
+  expect(stack.pop()).toBe(2);
+  expect(stack.pop()).toBe(1);
+});
+```
+
+**Green**: Already passes! Our implementation naturally handles this.
+
+**Refactor**: Tests are clean, code is clean. Nothing to refactor yet.
+
+---
+
+## Refactoring Example
+
+### Before Refactoring
+
+After several TDD cycles, we might have:
+
+```typescript
+export class UserService {
+  createUser(name: string, email: string): User {
+    if (!name || name.trim() === '') {
+      throw new Error('Name required');
+    }
+    if (!email || !email.includes('@')) {
+      throw new Error('Valid email required');
+    }
+    const user = { id: generateId(), name: name.trim(), email: email.toLowerCase() };
+    saveToDatabase(user);
+    return user;
+  }
+}
+```
+
+### After Refactoring
+
+With tests protecting us, we safely extract validation methods:
+
+```typescript
+export class UserService {
+  createUser(name: string, email: string): User {
+    const validatedName = this.validateName(name);
+    const validatedEmail = this.validateEmail(email);
+    return this.buildUser(validatedName, validatedEmail);
+  }
+
+  private validateName(name: string): string { /* validation logic */ }
+  private validateEmail(email: string): string { /* validation logic */ }
+  private buildUser(name: string, email: string): User { /* create user */ }
+}
+```
+
+**Key point**: Tests still pass - refactoring is safe
+
+---
+
+## Quick Reference
+
+| Phase | Action | Duration |
+|-------|--------|----------|
+| Red | Write failing test | ~10 sec |
+| Green | Write minimal code | ~15 sec |
+| Refactor | Clean up | ~5 sec |
+| **Total** | One cycle | ~30 sec |
diff --git a/.agents/skills/typescript-clean-code/references/tdd/knowledge.md b/.agents/skills/typescript-clean-code/references/tdd/knowledge.md
new file mode 100644
index 0000000..e3a1c7d
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/tdd/knowledge.md
@@ -0,0 +1,118 @@
+# TDD Knowledge
+
+Core concepts and foundational understanding for Test Driven Development.
+
+## Overview
+
+Test Driven Development (TDD) is a discipline where you write tests before writing production code, following a rapid cycle of test-code-refactor. It provides certainty that your code works, reduces defects, gives you courage to refactor, serves as documentation, and drives better design.
+
+## Key Concepts
+
+### The Jury Is In
+
+**Definition**: TDD is a proven, settled practice - not an experimental technique.
+
+The debate is over. Like GOTO being harmful, TDD's effectiveness is established fact. Studies from IBM, Microsoft, Sabre, and Symantec show defect reductions of 2X, 5X, and even 10X.
+
+**Key points**:
+- Programmers should not have to defend TDD any more than surgeons defend hand-washing
+- The evidence is overwhelming across multiple companies and teams
+- Controversy at this point is just "rants," not serious critique
+
+### Certainty
+
+**Definition**: The confidence that your changes haven't broken anything.
+
+With TDD, you write thousands of tests that run in seconds. After any change, run the tests - if they pass, you're nearly certain nothing broke.
+
+**Key points**:
+- "Nearly certain" means certain enough to ship
+- Real example: FitNesse has 64,000 lines of code, 2,200 tests, 90% coverage, runs in 90 seconds
+- The QA process can become simply: build + run tests + ship
+
+### Defect Injection Rate
+
+**Definition**: The rate at which bugs are introduced into the codebase.
+
+TDD dramatically reduces defect injection. Studies show 2X to 10X reduction in defects.
+
+**Key points**:
+- FitNesse example: 20,000 new lines of code, only 17 bugs (many cosmetic)
+- These are numbers no professional should ignore
+- Multiple independent studies confirm the effect
+
+### Courage
+
+**Definition**: The willingness to improve code without fear of breaking it.
+
+TDD eliminates the fear of touching messy code. When you trust your test suite, you clean code on the spot.
+
+**Key points**:
+- Without tests: "This is a mess" -> "I'm not touching it!"
+- With tests: You can click a button and know in 90 seconds your changes broke nothing
+- Code becomes clay you can safely sculpt
+- Code base improves instead of rotting
+
+### Documentation
+
+**Definition**: Tests serve as executable, accurate documentation of how the system works.
+
+Unit tests describe how to create every object and call every function in meaningful ways. They are unambiguous, accurate, and written in a language developers understand.
+
+**Key points**:
+- Programmers go to code examples first, not prose documentation
+- Tests are "the best kind of low-level documentation that can exist"
+- Tests execute, so they can never be out of date
+
+### Design Benefits
+
+**Definition**: TDD forces you to think about design and decoupling before writing code.
+
+Writing tests first forces you to isolate code, which drives better decoupled design.
+
+**Key points**:
+- Testing code requires isolating it from dependencies
+- Without tests first, nothing prevents coupling into an "untestable mass"
+- Tests written first are "offense"; tests written after are "defense"
+- After-the-fact tests can't be as incisive as test-first tests
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| TDD | Test Driven Development - write tests before production code |
+| Red-Green-Refactor | The TDD cycle: failing test, make it pass, improve code |
+| Test First | Writing the test before the implementation |
+| Cycle Time | Time between running tests (aim for ~30 seconds) |
+| Coverage | Percentage of production code exercised by tests |
+
+## How It Relates To
+
+- **Unit Tests**: TDD produces comprehensive unit test suites as a byproduct
+- **Refactoring**: TDD provides the safety net that makes refactoring possible
+- **Clean Code**: TDD encourages cleaner, more decoupled designs
+- **Professionalism**: TDD is the professional option for software development
+
+## Common Misconceptions
+
+- **Myth**: TDD is just about testing
+  **Reality**: TDD is primarily about design and confidence, tests are a byproduct
+
+- **Myth**: You can write tests later and get the same benefits
+  **Reality**: Tests written after are "defense"; tests written first are "offense"
+
+- **Myth**: TDD is a magic formula that guarantees good code
+  **Reality**: You can still write bad code and bad tests with TDD
+
+- **Myth**: TDD always applies
+  **Reality**: There are rare situations where TDD is impractical or inappropriate
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Certainty | Run tests, know nothing broke, ship with confidence |
+| Defect Reduction | 2X-10X fewer bugs with TDD |
+| Courage | Trust tests, clean code fearlessly |
+| Documentation | Tests are executable, always-current docs |
+| Design | Test-first forces decoupled design |
diff --git a/.agents/skills/typescript-clean-code/references/tdd/rules.md b/.agents/skills/typescript-clean-code/references/tdd/rules.md
new file mode 100644
index 0000000..d62e0d4
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/tdd/rules.md
@@ -0,0 +1,94 @@
+# TDD Rules
+
+The three laws of TDD and guidelines for professional practice.
+
+## Core Rules
+
+### 1. First Law: No Production Code Without a Failing Test
+
+You are not allowed to write any production code until you have first written a failing unit test.
+
+- Start every feature or fix with a test
+- The test defines what you're about to build
+- Even a compile error counts as a failing test
+
+### 2. Second Law: Minimal Failing Test
+
+You are not allowed to write more of a unit test than is sufficient to fail - and not compiling is failing.
+
+- Write just enough test to fail
+- A compilation failure is a valid failure
+- Stop writing test code as soon as it fails to compile or run
+
+### 3. Third Law: Minimal Production Code
+
+You are not allowed to write more production code than is sufficient to pass the currently failing unit test.
+
+- Write only enough code to make the test pass
+- Don't anticipate future needs
+- Stop as soon as the test goes green
+
+## The TDD Cycle
+
+The three laws lock you into a ~30 second cycle:
+
+1. **Red**: Write a small failing test
+2. **Green**: Write minimal code to pass
+3. **Refactor**: Clean up while tests stay green
+4. Repeat
+
+**Key insight**: The test code and production code grow simultaneously into complementary components - "like an antibody fits an antigen."
+
+## Guidelines
+
+### The Professional Option
+
+TDD enhances:
+- **Certainty** - Know your code works
+- **Courage** - Fearlessly improve code
+- **Defect reduction** - 2X-10X fewer bugs
+- **Documentation** - Tests describe the system
+- **Design** - Forces decoupling
+
+> It could be considered *unprofessional* not to use TDD.
+
+### Rapid Cycle Time
+
+- Aim for ~30 second cycles
+- Run tests after every small change
+- Don't go more than a few minutes without green tests
+
+### Test Coverage Through TDD
+
+- Following the three laws naturally produces high coverage
+- Every object creation method gets tested
+- Every meaningful function call gets tested
+- No production code exists without a corresponding test
+
+## Exceptions
+
+When TDD may not apply:
+
+- **Impractical situations**: Rare cases where the discipline does more harm than good
+- **Exploratory spikes**: Sometimes you need to explore before you test
+- **Legacy code**: May need different strategies for untested codebases
+
+> No professional developer should ever follow a discipline when that discipline does more harm than good.
+
+## What TDD Is Not
+
+- **Not a religion**: It's a practical discipline, not dogma
+- **Not a magic formula**: Following the laws doesn't guarantee good code
+- **Not a guarantee**: You can still write bad code and bad tests
+- **Not always applicable**: Use judgment about when it applies
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| Law 1 | No production code without a failing test first |
+| Law 2 | Write only enough test to fail (compile failure counts) |
+| Law 3 | Write only enough code to pass the failing test |
+| Cycle Time | ~30 seconds between test runs |
+| Coverage | Emerges naturally from following the three laws |
+| Professional | TDD is the professional option, not an optional extra |
diff --git a/.agents/skills/typescript-clean-code/references/testing-strategies/examples.md b/.agents/skills/typescript-clean-code/references/testing-strategies/examples.md
new file mode 100644
index 0000000..ec2a63a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/testing-strategies/examples.md
@@ -0,0 +1,193 @@
+# Testing Strategies Examples
+
+Code examples demonstrating the test automation pyramid in TypeScript.
+
+## Unit Tests (Vitest/Jest)
+
+### Business Logic Test
+
+```typescript
+// src/services/pricing.ts
+export function calculateDiscount(price: number, quantity: number): number {
+  if (quantity >= 100) return price * 0.20;
+  if (quantity >= 50) return price * 0.10;
+  if (quantity >= 10) return price * 0.05;
+  return 0;
+}
+
+// src/services/pricing.test.ts
+import { describe, it, expect } from 'vitest';
+import { calculateDiscount } from './pricing';
+
+describe('calculateDiscount', () => {
+  it('applies 20% discount for 100+ items', () => {
+    expect(calculateDiscount(100, 100)).toBe(20);
+  });
+
+  it('applies 10% discount for 50-99 items', () => {
+    expect(calculateDiscount(100, 50)).toBe(10);
+  });
+
+  it('applies 5% discount for 10-49 items', () => {
+    expect(calculateDiscount(100, 10)).toBe(5);
+  });
+
+  it('applies no discount for fewer than 10 items', () => {
+    expect(calculateDiscount(100, 9)).toBe(0);
+  });
+});
+```
+
+**Why it works**:
+- Tests pure business logic in isolation
+- Covers all branches with explicit assertions
+- Fast execution, runs on every commit
+
+## Component Tests (Supertest)
+
+### API Endpoint Test
+
+```typescript
+// src/routes/orders.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import request from 'supertest';
+import { app } from '../app';
+import { OrderService } from '../services/orderService';
+
+// Mock the service layer
+vi.mock('../services/orderService');
+
+describe('POST /api/orders', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates order and returns 201 with order details', async () => {
+    const mockOrder = { id: '123', items: [], total: 99.99 };
+    vi.mocked(OrderService.create).mockResolvedValue(mockOrder);
+
+    const response = await request(app)
+      .post('/api/orders')
+      .send({ items: [{ productId: 'abc', quantity: 2 }] })
+      .expect(201);
+
+    expect(response.body).toEqual(mockOrder);
+    expect(OrderService.create).toHaveBeenCalledWith({
+      items: [{ productId: 'abc', quantity: 2 }]
+    });
+  });
+
+  it('returns 400 for invalid order data', async () => {
+    const response = await request(app)
+      .post('/api/orders')
+      .send({ items: [] })
+      .expect(400);
+
+    expect(response.body.error).toBe('Order must have at least one item');
+  });
+});
+```
+
+**Why it works**:
+- Tests component in isolation with mocked dependencies
+- Verifies input/output behavior
+- Business stakeholders can understand the test intent
+
+## Integration Tests (Supertest + Database)
+
+### Multi-Component Communication Test
+
+```typescript
+// tests/integration/order-flow.test.ts
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import request from 'supertest';
+import { app } from '../../src/app';
+import { db } from '../../src/database';
+import { setupTestDatabase, teardownTestDatabase } from '../helpers';
+
+describe('Order Flow Integration', () => {
+  beforeAll(async () => {
+    await setupTestDatabase();
+  });
+
+  afterAll(async () => {
+    await teardownTestDatabase();
+  });
+
+  it('order creation updates inventory and notifies warehouse', async () => {
+    // Seed test data
+    await db.products.create({ id: 'prod-1', stock: 10 });
+
+    // Create order through API
+    const orderResponse = await request(app)
+      .post('/api/orders')
+      .send({ items: [{ productId: 'prod-1', quantity: 3 }] })
+      .expect(201);
+
+    // Verify inventory was updated
+    const product = await db.products.findById('prod-1');
+    expect(product.stock).toBe(7);
+
+    // Verify warehouse notification was queued
+    const notifications = await db.notifications.findByOrderId(
+      orderResponse.body.id
+    );
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].type).toBe('WAREHOUSE_PICK');
+  });
+});
+```
+
+**Why it works**:
+- Tests choreography between components
+- Verifies real database interactions
+- Runs periodically, not on every commit
+
+## System Tests (Playwright)
+
+### End-to-End User Flow
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase', async ({ page }) => {
+    // Navigate and add item to cart
+    await page.goto('/products');
+    await page.click('[data-testid="product-widget-1"]');
+    await page.click('[data-testid="add-to-cart"]');
+
+    // Go to checkout
+    await page.click('[data-testid="cart-icon"]');
+    await page.click('[data-testid="checkout-button"]');
+
+    // Fill payment details
+    await page.fill('[name="cardNumber"]', '4111111111111111');
+    await page.fill('[name="expiry"]', '12/25');
+    await page.fill('[name="cvv"]', '123');
+
+    // Complete purchase
+    await page.click('[data-testid="pay-button"]');
+
+    // Verify confirmation
+    await expect(page.locator('[data-testid="confirmation"]'))
+      .toContainText('Order confirmed');
+  });
+});
+```
+
+**Why it works**:
+- Tests entire system end-to-end
+- Verifies system construction and wiring
+- Runs infrequently due to longer execution time
+
+## Quick Reference
+
+| Level | Tool | Frequency | Coverage |
+|-------|------|-----------|----------|
+| Unit | Vitest/Jest | Every commit | ~90% |
+| Component | Supertest + Mocks | Every commit | ~50% |
+| Integration | Supertest + DB | Nightly | Architectural |
+| System | Playwright | Weekly | ~10% |
+| Exploratory | Human | Sprint end | Creative |
diff --git a/.agents/skills/typescript-clean-code/references/testing-strategies/knowledge.md b/.agents/skills/typescript-clean-code/references/testing-strategies/knowledge.md
new file mode 100644
index 0000000..80e4760
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/testing-strategies/knowledge.md
@@ -0,0 +1,80 @@
+# Testing Strategies Knowledge
+
+Core concepts and foundational understanding for professional testing strategies.
+
+## Overview
+
+Professional developers need more than unit tests and acceptance tests - they need a comprehensive testing strategy. The goal is that QA should find nothing wrong, achieved through a hierarchy of automated tests at different levels of the system.
+
+## Key Concepts
+
+### QA Should Find Nothing
+
+**Definition**: The development team's goal should be that QA discovers zero defects.
+
+Every time QA finds something, the development team should react with concern and take steps to prevent similar issues in the future. While this goal may not always be achieved, it should drive the team's testing practices.
+
+**Key points**:
+- QA finding bugs indicates gaps in the testing strategy
+- Each discovered bug is an opportunity to improve prevention
+- Development owns quality, not QA
+
+### QA as Part of the Team
+
+**Definition**: QA and Development work together toward quality, not as adversaries.
+
+QA serves two critical roles that complement development:
+
+**Key points**:
+- QA acts as specifiers (creating acceptance tests from requirements)
+- QA acts as characterizers (exploring actual system behavior)
+- Business writes happy-path tests; QA writes edge cases
+
+### The Test Automation Pyramid
+
+**Definition**: A hierarchical structure of automated tests, with unit tests forming the large base and exploratory tests at the small top.
+
+The pyramid represents both the quantity and granularity of tests needed at each level. More tests at the bottom (fast, focused), fewer at the top (slow, broad).
+
+**Key points**:
+- Unit tests form the foundation (highest quantity)
+- Each level builds on the confidence of levels below
+- Higher levels test integration, not business rules
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Unit Test | Tests written by programmers to specify system at lowest level |
+| Component Test | Acceptance tests for individual components and business rules |
+| Integration Test | Tests how component assemblies communicate together |
+| System Test | Tests against entire integrated system |
+| Exploratory Test | Manual, unscripted testing to find unexpected behaviors |
+| Test Doubles | Mocks/stubs used to isolate components under test |
+| Choreography Test | Tests that verify components work together (integration) |
+
+## How It Relates To
+
+- **TDD**: Unit tests from the pyramid's base come from Test-Driven Development
+- **Acceptance Testing**: Component tests are the acceptance tests for business rules
+- **Continuous Integration**: Lower-level tests run on every commit; higher levels run periodically
+
+## Common Misconceptions
+
+- **Myth**: More tests at every level is always better
+  **Reality**: The pyramid shape is intentional - more unit tests, fewer system tests
+
+- **Myth**: QA is responsible for finding all bugs
+  **Reality**: Development should prevent bugs; QA validates the prevention worked
+
+- **Myth**: Manual testing can be replaced entirely by automation
+  **Reality**: Exploratory testing requires human creativity and cannot be scripted
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| QA Finds Nothing | Development's goal is zero defects reaching QA |
+| QA as Specifiers | QA translates requirements into acceptance tests |
+| QA as Characterizers | QA identifies actual system behavior through exploration |
+| Test Pyramid | Unit (90%+) > Component (50%) > Integration > System (10%) > Exploratory |
diff --git a/.agents/skills/typescript-clean-code/references/testing-strategies/rules.md b/.agents/skills/typescript-clean-code/references/testing-strategies/rules.md
new file mode 100644
index 0000000..26ec9cd
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/testing-strategies/rules.md
@@ -0,0 +1,86 @@
+# Testing Strategies Rules
+
+Rules for implementing a comprehensive testing strategy across all levels of the test pyramid.
+
+## Core Rules
+
+### 1. Unit Tests
+
+Tests written by programmers, for programmers, in the system's language.
+
+- Write tests BEFORE production code (TDD)
+- Execute as part of Continuous Integration
+- Target ~90%+ true coverage (not false tests that execute without asserting)
+
+**Coverage**: As close to 100% as practical (typically 90s%)
+
+### 2. Component Tests
+
+Acceptance tests for individual components encapsulating business rules.
+
+- Wrap individual components with input/output verification
+- Decouple from other components using mocks and test doubles
+- Business should be able to read and interpret these tests
+- Written by QA and Business with development assistance
+
+**Coverage**: ~50% of system (happy paths + obvious edge cases)
+
+### 3. Integration Tests
+
+Tests that verify component assemblies communicate correctly.
+
+- Test choreography, not business rules
+- Verify plumbing and connections between components
+- Written by system architects or lead designers
+- Run periodically (nightly/weekly), not on every CI build
+- Include performance and throughput tests at this level
+
+**Coverage**: Architectural soundness verification
+
+### 4. System Tests
+
+Automated tests against the entire integrated system.
+
+- Ultimate integration tests
+- Verify system is wired together correctly
+- Test that parts interoperate according to plan
+- Include throughput and performance tests
+- Written by architects and technical leads
+
+**Coverage**: ~10% of system (construction, not behavior)
+
+### 5. Manual Exploratory Tests
+
+Human-driven, unscripted testing.
+
+- NOT automated
+- NOT scripted (no written test plans)
+- Explore for unexpected behaviors
+- Confirm expected behaviors
+- Use human creativity to investigate the system
+
+**Goal**: Find peculiarities, not prove coverage
+
+## Guidelines
+
+- Run tests as frequently as possible for maximum feedback
+- Lower pyramid levels should run more frequently
+- Business writes happy-path tests; QA writes corner/boundary/unhappy-path tests
+- React to every QA-found bug with process improvement
+- Keep system continuously clean through continuous testing
+
+## Exceptions
+
+- **Small systems**: May skip integration tests if few components exist
+- **Performance-critical paths**: May need additional system-level tests beyond 10%
+- **Rapidly changing UI**: May reduce component test coverage in favor of unit tests
+
+## Quick Reference
+
+| Test Level | Coverage | Frequency | Written By |
+|------------|----------|-----------|------------|
+| Unit | ~90%+ | Every CI build | Developers |
+| Component | ~50% | Every CI build | QA + Business + Dev |
+| Integration | Architectural | Periodic (nightly/weekly) | Architects |
+| System | ~10% | Periodic | Tech Leads |
+| Exploratory | N/A | As needed | Humans (anyone) |
diff --git a/.agents/skills/typescript-clean-code/references/time-management/examples.md b/.agents/skills/typescript-clean-code/references/time-management/examples.md
new file mode 100644
index 0000000..ef10bc1
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/time-management/examples.md
@@ -0,0 +1,191 @@
+# Time Management Examples
+
+Scenarios demonstrating good vs bad time management decisions.
+
+## Bad Examples
+
+### Accepting All Meeting Invites
+
+**Scenario**: Developer receives invite for cross-team architecture discussion. Topic is interesting but unrelated to current sprint work.
+
+**Bad Decision**: Accepts because "it might be useful to know about" and "I don't want to seem unhelpful."
+
+**Problems**:
+- 2-hour meeting costs focus-manna needed for actual deliverables
+- Sets precedent for future invites
+- No immediate benefit to current responsibilities
+- Interest is not the same as necessity
+
+---
+
+### Staying in Hijacked Meetings
+
+**Scenario**: Joined a 30-minute meeting about API design. After 15 minutes, discussion shifts to someone's pet peeve about logging standards.
+
+**Bad Decision**: Stays for remaining 45 minutes (meeting runs over) because "it would be rude to leave."
+
+**Problems**:
+- Remaining is unprofessional - you're wasting employer's money
+- You had no value to add to the new topic
+- Lost an hour that could have been productive
+
+---
+
+### Avoiding the Hard Task
+
+**Scenario**: Need to refactor authentication module (scary, might break things). Instead, spend morning on "urgent" task of reorganizing test folder structure.
+
+**Bad Decision**: Convince yourself folder organization is more important right now.
+
+**Problems**:
+- Classic priority inversion
+- Building defenses against future judgment ("I was being productive!")
+- Auth refactor remains undone and gets harder over time
+- The lie compounds - tomorrow you'll find another avoidance task
+
+---
+
+### Pushing Through a Blind Alley
+
+**Scenario**: Chose microservices architecture. Two months in, realize the overhead is killing velocity for a team of three. But you championed this approach.
+
+**Bad Decision**: Double down. "We just need better tooling. Once we get past this hump..."
+
+**Problems**:
+- Professional reputation became more important than project success
+- Each day forward makes the return path longer
+- Team suffers while you protect ego
+
+---
+
+### Wading Through the Swamp
+
+**Scenario**: Original design doesn't scale with new requirements. Refactoring back looks like 2 weeks. Pushing forward looks like 1 week.
+
+**Bad Decision**: Push forward. "We're so close, we can clean it up later."
+
+**Problems**:
+- Forward path is always deceptively shorter
+- "Later" never comes - next feature adds more mess
+- Team productivity enters death spiral
+- Moving forward through known swamp is worst priority inversion
+
+---
+
+### Coding Without Focus
+
+**Scenario**: 3 PM, focus-manna depleted after morning meetings. Critical feature deadline tomorrow.
+
+**Bad Decision**: Power through with coffee. "I'll just push harder."
+
+**Problems**:
+- Code written without focus requires rewriting
+- Creates mess that slows future work
+- Jittery caffeine focus goes in wrong directions
+- Better to take 30-60 min break, return refreshed
+
+## Good Examples
+
+### Declining with Professionalism
+
+**Scenario**: Same cross-team architecture invite as above.
+
+**Good Decision**: "Thanks for including me. My sprint commitments won't allow me to attend, but I'd appreciate the meeting notes. Let me know if there's a specific topic where my input is essential."
+
+**Why it works**:
+- Protects your time for actual responsibilities
+- Leaves door open for truly necessary inclusion
+- Manager will support this decision
+
+---
+
+### Negotiating Meeting Exit
+
+**Scenario**: Same hijacked API meeting.
+
+**Good Decision**: At natural pause: "I need to get back to my sprint work. Is there anything else about the API design where you need my input before I go?"
+
+**Why it works**:
+- Polite but clear
+- Offers final chance for relevant contribution
+- Models professional time management for others
+
+---
+
+### Facing the Hard Task
+
+**Scenario**: Same scary auth refactor.
+
+**Good Decision**: Block first two hours of day (highest focus-manna) for auth work. Write down fears specifically. Start with smallest piece.
+
+**Why it works**:
+- Uses best focus time for hardest work
+- Naming fears reduces their power
+- Small start builds momentum
+- Priority order maintained despite discomfort
+
+---
+
+### Backing Out of Blind Alley
+
+**Scenario**: Same microservices realization.
+
+**Good Decision**: Call team meeting. "I advocated for microservices, but the data shows it's not working for our team size. I recommend we consolidate. Here's a migration plan."
+
+**Why it works**:
+- Ego subordinated to project success
+- Demonstrates professional courage
+- Team respects honesty over stubbornness
+- Earlier exit = less rework
+
+---
+
+### Escaping the Swamp Early
+
+**Scenario**: Same scaling problem.
+
+**Good Decision**: "The 2-week refactor is actually cheaper than the 1-week push. Going forward will never be easier than now. Let's fix the design."
+
+**Why it works**:
+- Recognizes the deception of "shorter path forward"
+- Understands inflection point
+- Prevents productivity death spiral
+- Shows fear of messes (appropriate professional fear)
+
+## Pomodoro Technique in Practice
+
+### Setup
+```
+25 minutes: Focused work (tomato time)
+5 minutes: Short break
+Repeat 4x
+30 minutes: Long break
+```
+
+### Handling Interruptions
+
+**During tomato**: "I'm in the middle of something - can I get back to you in 15 minutes?"
+
+**What it achieves**:
+- Most interruptions can wait 25 minutes
+- Creates predictable availability windows
+- 12-14 tomatoes = excellent day
+- 2-3 tomatoes = day consumed by "stuff"
+- Tracking reveals time usage patterns
+
+## Time Blocking Example
+
+From the book - managing a 15-person department:
+
+| Time | Activity |
+|------|----------|
+| 5:00 AM | Wake, bike to office |
+| 6:00-9:00 | Quiet focused work (fully scheduled) |
+| 9:00-12:00 | Scheduled work with 15-min gaps/hour for interruptions |
+| 12:00+ | Unscheduled - reactive mode for chaos |
+
+**Why it works**:
+- Protects 3 hours before interruptions begin
+- Built-in slots for pushing interruptions into
+- Acknowledges reality of afternoon chaos
+- When chaos doesn't intrude, works on most important thing
diff --git a/.agents/skills/typescript-clean-code/references/time-management/knowledge.md b/.agents/skills/typescript-clean-code/references/time-management/knowledge.md
new file mode 100644
index 0000000..89a92d5
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/time-management/knowledge.md
@@ -0,0 +1,105 @@
+# Time Management Knowledge
+
+Core concepts and foundational understanding for developer time management.
+
+## Overview
+
+Professionals have only 480 minutes (8 hours) per day and must use them efficiently. Time management for developers involves protecting focused work time, minimizing meeting overhead, and maintaining the mental energy needed for programming.
+
+## Key Concepts
+
+### Focus-Manna
+
+**Definition**: A finite mental resource required for concentration and programming that depletes with use and must be recharged.
+
+Programming requires extended periods of concentration. Focus-manna is expended during intellectual work and cannot be forced once depleted.
+
+**Key points**:
+- You can *feel* when focus-manna is present or depleted
+- It decays if not used - wasting it in meetings means none left for coding
+- Worry and distractions consume focus-manna rapidly
+- Code written without focus-manna will likely need rewriting
+
+### Meeting Cost
+
+**Definition**: The true expense of meetings calculated as ~$200/hour per attendee (including salary, benefits, facilities).
+
+Meetings have two truths: they are necessary AND they are huge time wasters. Often both apply to the same meeting - some attendees find value, others find it redundant.
+
+**Key points**:
+- Calculate the actual cost of meetings you attend
+- Your presence costs your employer real money
+- Remaining in wasteful meetings is unprofessional
+
+### Priority Inversion
+
+**Definition**: Raising the priority of a less important task to avoid a task you find scary, uncomfortable, or boring.
+
+This is a lie we tell ourselves - we know the avoided task is truly more important but we build defenses against the judgment of others.
+
+**Key points**:
+- Often triggered by fear of confrontation or inescapable problems
+- Professionals execute tasks in true priority order regardless of personal discomfort
+
+### Blind Alleys
+
+**Definition**: Technical pathways that lead nowhere, often discovered only after significant investment.
+
+The more vested you are in a decision, the longer you'll wander. Staking professional reputation leads to endless wandering.
+
+**Key points**:
+- Unavoidable - even experience won't prevent all blind alleys
+- Key skill is recognizing them quickly and having courage to back out
+- "The Rule of Holes": When you are in one, stop digging
+
+### Messes (Bogs/Swamps)
+
+**Definition**: Technical debt that slows progress but doesn't stop it - you can always see a way forward that looks shorter than going back (but isn't).
+
+Messes are worse than blind alleys because you can still make progress through brute force, deceiving yourself about the true cost.
+
+**Key points**:
+- Nothing has more negative effect on team productivity than a mess
+- The progression is insidious - starts clean, then design choices don't scale
+- The inflection point is when going back will never be easier than now
+- Moving forward through a known swamp is the worst priority inversion
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| Focus-manna | Finite mental energy for concentration |
+| Pomodoro/Tomato | 25-minute focused work session |
+| Priority inversion | Avoiding important work by elevating lesser tasks |
+| Blind alley | Technical dead-end requiring backtracking |
+| Mess/Bog/Swamp | Technical debt that impedes but doesn't stop progress |
+
+## Recharging Strategies
+
+### Sleep
+Seven hours of sleep provides a full eight hours of focus-manna. Professionals manage sleep schedules to arrive at work with topped-up focus.
+
+### Physical Activity (Muscle Focus)
+Physical disciplines (martial arts, yoga, cycling, carpentry) use a different kind of focus that helps recharge mental focus. Regular muscle focus *increases* capacity for mental focus.
+
+### De-focusing Activities
+- Long walks
+- Conversations with friends
+- Looking out a window
+- Meditation or power naps
+- Podcasts or light reading
+
+### Input for Output
+Creative work requires creative input. Reading fiction or exposure to others' creativity stimulates your own creative capacity.
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| Focus-manna | Finite mental resource - protect and recharge it |
+| Meeting cost | ~$200/hour/person - calculate before attending |
+| Priority inversion | Lying to avoid scary work - fight it as honor |
+| Blind alleys | Recognize quickly, back out with courage |
+| Messes | Fear them more than blind alleys - escape early |
+| Sleep | 7 hours sleep = 8 hours focus capacity |
+| Muscle focus | Physical activity recharges mental focus |
diff --git a/.agents/skills/typescript-clean-code/references/time-management/rules.md b/.agents/skills/typescript-clean-code/references/time-management/rules.md
new file mode 100644
index 0000000..f417435
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/time-management/rules.md
@@ -0,0 +1,134 @@
+# Time Management Rules
+
+Specific guidelines for managing time, meetings, and focus as a professional developer.
+
+## Core Rules
+
+### 1. Decline Meetings Without Clear Value
+
+You do not have to attend every meeting. Going to too many meetings is unprofessional.
+
+- Only accept if participation is immediately and significantly necessary to YOUR job
+- The inviter is not responsible for managing your time - only you can do that
+- Interest alone is not sufficient reason to attend
+- Your responsibility is to your projects first
+
+**Ask before accepting**:
+- What discussions are on the table?
+- How much time is allotted for each topic?
+- What goal is to be achieved?
+- If no clear answers, politely decline
+
+### 2. Leave Meetings That Waste Your Time
+
+When the meeting gets boring, leave.
+
+- Remaining in a wasteful meeting is unprofessional
+- You have an obligation to wisely spend your employer's time and money
+- Don't storm out - negotiate exit at an appropriate moment
+- Ask: "Is my presence still necessary?" or "Can we expedite the discussion?"
+
+### 3. Require Agendas and Goals
+
+Meetings must have clear structure to justify their cost.
+
+- Clear agenda with times for each topic
+- Stated goal to achieve
+- If agenda is hijacked, request return to original topics
+- If agenda cannot be restored, leave when possible
+
+### 4. Keep Stand-ups Under 10 Minutes
+
+Three questions only, 20 seconds each maximum:
+
+1. What did I do yesterday?
+2. What am I going to do today?
+3. What's in my way?
+
+- Each person: ~1 minute maximum
+- 10 people: under 10 minutes total
+- Stand to discourage lingering
+
+### 5. Limit Iteration Planning to 5% of Iteration Time
+
+One-week iteration = 2 hours maximum for planning.
+
+- Estimates should already be done for candidates
+- Business value assessment should already be done
+- 5-10 minutes maximum per backlog item
+- Longer discussions scheduled separately with subset of team
+
+### 6. Schedule Retrospectives Before Quitting Time
+
+Schedule 45 minutes before end of last day of iteration.
+
+- 20 minutes for retrospective
+- 25 minutes for demo
+- Only a week or two of work - shouldn't need more time
+
+### 7. Settle Arguments with Data, Not Force
+
+> "Any argument that can't be settled in five minutes can't be settled by arguing." - Kent Beck
+
+- Technical disagreements without data won't forge agreement
+- Force of character (yelling, condescension) doesn't settle anything long-term
+- If you agree, you MUST engage - passive-aggressive sabotage is the worst unprofessional behavior
+- Run experiments, simulations, or flip a coin and set criteria for abandonment
+
+**For team disagreements**:
+- Each arguer presents case in 5 minutes or less
+- Team votes
+- Whole meeting under 15 minutes
+
+### 8. Execute True Priorities Despite Discomfort
+
+Professionals evaluate priority disregarding personal fears and desires.
+
+- Don't elevate comfortable tasks over scary-but-important ones
+- Recognize when you're building defenses against others' judgment
+- Priority inversion is a lie to yourself and others
+
+### 9. Recognize Blind Alleys and Back Out
+
+Keep options open by keeping an open mind about alternatives.
+
+- Never become so vested you can't abandon an idea
+- When in a hole, stop digging
+- Backing out is not failure - it's prudence
+
+### 10. Fear Messes More Than Blind Alleys
+
+The inflection point is when going back will never be easier than now.
+
+- Always watch for messes growing without bound
+- Expend all necessary effort to escape early
+- Moving forward through a known swamp is the worst priority inversion
+- Clean messes as soon as they are recognized
+
+## Guidelines
+
+- Use your manager to defend your meeting decline decisions
+- Block early morning hours for focused work before chaos begins
+- Schedule reactive time for afternoons when interruptions are highest
+- Use 15-minute scheduling increments with gaps for interruption handling
+- Protect your sleep - it's your primary focus-manna source
+- Take 30-60 minutes to de-focus when manna is depleted - forcing focus produces bad code
+
+## Exceptions
+
+- **Authority requests**: When someone senior requests attendance, weigh authority against work schedule with your team/manager
+- **Team helping team**: Sometimes worth the loss to your project to help another team - discuss with your team first
+
+## Quick Reference
+
+| Rule | Guideline |
+|------|-----------|
+| Meeting invites | Decline unless immediately necessary to your job |
+| Boring meetings | Leave politely at appropriate moment |
+| No agenda | Don't attend / request agenda first |
+| Stand-ups | 1 min/person, 10 min max total |
+| Iteration planning | 5% of iteration time |
+| Arguments > 5 min | Get data, don't keep arguing |
+| Uncomfortable tasks | Execute in true priority order |
+| Blind alleys | Recognize quickly, back out |
+| Messes | Fear them, escape early, never wade forward |
diff --git a/.agents/skills/typescript-clean-code/references/unit-tests/examples.md b/.agents/skills/typescript-clean-code/references/unit-tests/examples.md
new file mode 100644
index 0000000..ae791df
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/unit-tests/examples.md
@@ -0,0 +1,181 @@
+# Unit Tests Examples
+
+Code examples demonstrating clean test principles in TypeScript (Jest/Vitest).
+
+## Bad Examples
+
+### Noisy Test with Too Much Detail
+
+```typescript
+it('should get page hierarchy as XML', async () => {
+  await crawler.addPage(root, PathParser.parse('PageOne'));
+  await crawler.addPage(root, PathParser.parse('PageOne.ChildOne'));
+  request.setResource('root');
+  request.addInput('type', 'pages');
+  const responder = new SerializedPageResponder();
+  const response = await responder.makeResponse(new Context(root), request);
+  expect(response.getContentType()).toBe('text/xml');
+  expect(response.getContent()).toContain('<name>PageOne</name>');
+});
+```
+
+**Problems**: PathParser calls are noise, setup details obscure intent, reader must understand implementation.
+
+### Multiple Concepts in One Test
+
+```typescript
+it('should add months correctly', () => {
+  const d1 = SerialDate.createInstance(31, 5, 2004);
+  const d2 = SerialDate.addMonths(1, d1);
+  expect(d2.getDayOfMonth()).toBe(30);  // Concept 1: cap to 30-day month
+  const d3 = SerialDate.addMonths(2, d1);
+  expect(d3.getDayOfMonth()).toBe(31);  // Concept 2: preserve in 31-day month
+  const d4 = SerialDate.addMonths(1, SerialDate.addMonths(1, d1));
+  expect(d4.getDayOfMonth()).toBe(30);  // Concept 3: chained addition
+});
+```
+
+**Problems**: Three concepts in one test, hard to identify which failed, missing edge cases.
+
+### Hard-to-Read State Assertions
+
+```typescript
+it('should turn on low temp alarm at threshold', () => {
+  hw.setTemp(WAY_TOO_COLD);
+  controller.tic();
+  expect(hw.heaterState()).toBe(true);
+  expect(hw.blowerState()).toBe(true);
+  expect(hw.coolerState()).toBe(false);
+  expect(hw.hiTempAlarm()).toBe(false);
+  expect(hw.loTempAlarm()).toBe(true);
+});
+```
+
+**Problems**: Eyes bounce between state names and values, tedious to read.
+
+## Good Examples
+
+### Clean Test with Domain Language
+
+```typescript
+it('should get page hierarchy as XML', async () => {
+  await makePages('PageOne', 'PageOne.ChildOne', 'PageTwo');
+  await submitRequest('root', 'type:pages');
+  assertResponseIsXML();
+  assertResponseContains('<name>PageOne</name>', '<name>PageTwo</name>');
+});
+
+it('should exclude symbolic links from hierarchy', async () => {
+  const page = await makePage('PageOne');
+  await addLinkTo(page, 'PageTwo', 'SymPage');
+  await submitRequest('root', 'type:pages');
+  assertResponseDoesNotContain('SymPage');
+});
+```
+
+**Why it works**: Clear BUILD-OPERATE-CHECK structure, details hidden in helpers.
+
+### Compact State Representation
+
+```typescript
+// State: Heater, Blower, Cooler, HiAlarm, LoAlarm (uppercase=ON)
+it('should turn on cooler and blower if too hot', () => {
+  tooHot();
+  expect(hw.getState()).toBe('hBChl');
+});
+
+it('should turn on heater and blower if too cold', () => {
+  tooCold();
+  expect(hw.getState()).toBe('HBchl');
+});
+
+it('should turn on lo-temp alarm at threshold', () => {
+  wayTooCold();
+  expect(hw.getState()).toBe('HBchL');
+});
+```
+
+**Why it works**: Compact, consistent format; once learned, easy to scan.
+
+### Single Concept per Test
+
+```typescript
+describe('SerialDate.addMonths', () => {
+  describe('given last day of 31-day month', () => {
+    const may31 = SerialDate.createInstance(31, 5, 2004);
+
+    it('should cap to 30th when target month has 30 days', () => {
+      const june = SerialDate.addMonths(1, may31);
+      expect(june.getDayOfMonth()).toBe(30);
+    });
+
+    it('should preserve 31st when target month has 31 days', () => {
+      const july = SerialDate.addMonths(2, may31);
+      expect(july.getDayOfMonth()).toBe(31);
+    });
+  });
+});
+```
+
+**Why it works**: One concept per test, easy to add edge cases, clear what failed.
+
+## Refactoring Walkthrough
+
+### Before
+
+```typescript
+it('should handle page requests', async () => {
+  await crawler.addPage(root, PathParser.parse('PageOne'));
+  request.setResource('root');
+  request.addInput('type', 'pages');
+  const responder = new SerializedPageResponder();
+  const response = await responder.makeResponse(ctx, request);
+  expect(response.getContentType()).toBe('text/xml');
+  expect(response.getContent()).toContain('<name>PageOne</name>');
+});
+```
+
+### After
+
+```typescript
+it('should return XML containing requested pages', async () => {
+  await makePages('PageOne');
+  await submitRequest('root', 'type:pages');
+  assertResponseIsXML();
+  assertResponseContains('<name>PageOne</name>');
+});
+```
+
+### Test Helpers (Domain-Specific Testing Language)
+
+```typescript
+async function makePages(...names: string[]): Promise<void> {
+  for (const name of names) {
+    await crawler.addPage(root, PathParser.parse(name));
+  }
+}
+
+async function submitRequest(resource: string, params: string): Promise<void> {
+  request.setResource(resource);
+  const [key, value] = params.split(':');
+  request.addInput(key, value);
+  response = await new SerializedPageResponder().makeResponse(ctx, request);
+}
+
+function assertResponseIsXML(): void {
+  expect(response.getContentType()).toBe('text/xml');
+}
+
+function assertResponseContains(...substrings: string[]): void {
+  for (const s of substrings) {
+    expect(response.getContent()).toContain(s);
+  }
+}
+```
+
+### Changes Made
+
+1. **Extracted helpers** - Hide implementation noise (PathParser, request setup)
+2. **Created assertion DSL** - Domain-specific language for responses
+3. **Improved test name** - Describes behavior, not implementation
+4. **Clear structure** - BUILD-OPERATE-CHECK pattern is visible
diff --git a/.agents/skills/typescript-clean-code/references/unit-tests/knowledge.md b/.agents/skills/typescript-clean-code/references/unit-tests/knowledge.md
new file mode 100644
index 0000000..27550cf
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/unit-tests/knowledge.md
@@ -0,0 +1,102 @@
+# Unit Tests Knowledge
+
+Core concepts and foundational understanding for writing clean, maintainable unit tests.
+
+## Overview
+
+Unit tests are as important as production code. They enable fearless refactoring by providing a safety net that catches regressions. Clean tests must be readable, maintainable, and expressive to preserve their value over time.
+
+## Key Concepts
+
+### Test-Driven Development (TDD)
+
+**Definition**: A development practice where tests are written before production code, in short cycles of approximately 30 seconds.
+
+Tests and production code are written together, with tests just seconds ahead of the code. This results in comprehensive test coverage that rivals the size of production code.
+
+**Key points**:
+- Write failing test first, then minimal code to pass
+- Cycle time is approximately 30 seconds
+- Results in dozens of tests daily, thousands yearly
+
+### Clean Tests
+
+**Definition**: Tests that prioritize readability through clarity, simplicity, and density of expression.
+
+A clean test says a lot with as few expressions as possible. It uses domain-specific language and hides implementation details behind well-named helper functions.
+
+**Key points**:
+- Readability is paramount (even more than production code)
+- Use helper functions to hide noisy details
+- Follow BUILD-OPERATE-CHECK pattern
+
+### The -ilities
+
+**Definition**: The qualities that unit tests enable in production code: flexibility, maintainability, and reusability.
+
+Without tests, every change is a possible bug. With tests, you can make changes with confidence and continuously improve architecture and design.
+
+**Key points**:
+- Tests enable fearless refactoring
+- Higher coverage = less fear of change
+- Dirty tests lead to dirty code, then no tests, then rotting code
+
+### Domain-Specific Testing Language (DSL)
+
+**Definition**: A specialized API of functions and utilities built for writing and reading tests more easily.
+
+This API evolves through refactoring test code, making tests more succinct and expressive while hiding implementation details.
+
+**Key points**:
+- Not designed upfront; evolves through refactoring
+- Makes tests convenient to write and easy to read
+- Hides system APIs behind intention-revealing functions
+
+### Dual Standard
+
+**Definition**: The principle that test code has different engineering standards than production code regarding efficiency.
+
+Test code must be simple, succinct, and expressive but need not be as efficient as production code since it runs in test environments, not production.
+
+**Key points**:
+- Efficiency trade-offs acceptable in tests
+- Cleanliness is never compromised
+- Test environment has different constraints than production
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| BUILD-OPERATE-CHECK | Test pattern: setup data, perform action, verify results |
+| Given-When-Then | BDD convention for structuring test names and bodies |
+| Test Coverage | Percentage of production code exercised by tests |
+| Test Suite | Collection of all automated tests for a codebase |
+| Red-Green-Refactor | TDD cycle: failing test, passing code, clean up |
+
+## How It Relates To
+
+- **Refactoring**: Tests enable safe refactoring by catching regressions
+- **Code Quality**: Dirty tests lead to dirty production code over time
+- **Maintainability**: Clean tests preserve ability to change code
+- **Documentation**: Well-written tests serve as living documentation
+
+## Common Misconceptions
+
+- **Myth**: Test code can be "quick and dirty" since it's not production code
+  **Reality**: Dirty tests become a liability and eventually get abandoned, leading to rotting production code
+
+- **Myth**: Having any tests is better than no tests
+  **Reality**: Dirty tests can be worse than no tests due to maintenance burden
+
+- **Myth**: Tests only verify correctness
+  **Reality**: Tests enable the -ilities (flexibility, maintainability, reusability)
+
+## Quick Reference
+
+| Concept | One-Line Summary |
+|---------|-----------------|
+| TDD | Write failing test, minimal code to pass, refactor |
+| Clean Tests | Readable, simple, expressive with domain language |
+| The -ilities | Tests enable flexibility, maintainability, reusability |
+| Dual Standard | Tests can trade efficiency for clarity, never cleanliness |
+| DSL | Build helper functions that make tests read like specs |
diff --git a/.agents/skills/typescript-clean-code/references/unit-tests/rules.md b/.agents/skills/typescript-clean-code/references/unit-tests/rules.md
new file mode 100644
index 0000000..fb7e1fb
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/references/unit-tests/rules.md
@@ -0,0 +1,126 @@
+# Unit Tests Rules
+
+Rules for writing clean, maintainable unit tests that enable confident refactoring.
+
+## Core Rules
+
+### 1. Three Laws of TDD
+
+Follow these laws for test-driven development:
+
+- **First Law**: Never write production code until you have a failing unit test
+- **Second Law**: Write only enough test to fail (not compiling counts as failing)
+- **Third Law**: Write only enough production code to pass the failing test
+
+**Cycle time**: ~30 seconds per iteration
+
+### 2. Keep Tests Clean
+
+Test code is just as important as production code.
+
+- Tests require thought, design, and care
+- Dirty tests become harder to change as production code evolves
+- Dirty tests eventually get abandoned, leading to rotting code
+- Maintain tests to the same quality standards as production code
+
+### 3. Prioritize Readability
+
+What makes tests readable: clarity, simplicity, density of expression.
+
+- Say a lot with few expressions
+- Hide noisy details behind well-named helper functions
+- Use domain-specific testing language
+- Make test intent immediately clear
+
+**Example**:
+```typescript
+// Bad - too much noise
+it('should get page hierarchy as XML', async () => {
+  await crawler.addPage(root, PathParser.parse('PageOne'));
+  await crawler.addPage(root, PathParser.parse('PageOne.ChildOne'));
+  request.setResource('root');
+  request.addInput('type', 'pages');
+  const responder = new SerializedPageResponder();
+  const response = await responder.makeResponse(new Context(root), request);
+  expect(response.getContentType()).toBe('text/xml');
+  expect(response.getContent()).toContain('<name>PageOne</name>');
+});
+
+// Good - clear intent with helpers
+it('should get page hierarchy as XML', async () => {
+  await makePages('PageOne', 'PageOne.ChildOne', 'PageTwo');
+  await submitRequest('root', 'type:pages');
+  assertResponseIsXML();
+  assertResponseContains('<name>PageOne</name>', '<name>PageTwo</name>');
+});
+```
+
+### 4. Follow BUILD-OPERATE-CHECK Pattern
+
+Structure each test in three clear parts:
+
+- **Build**: Set up the test data
+- **Operate**: Perform the action being tested
+- **Check**: Verify the expected results
+
+Also known as Arrange-Act-Assert (AAA) or Given-When-Then.
+
+### 5. Single Concept per Test
+
+Test one concept per test function.
+
+- Don't test multiple unrelated things in one test
+- Each test should have a single reason to fail
+- Split tests that verify multiple independent behaviors
+- Helps identify what broke when a test fails
+
+### 6. Minimize Asserts per Concept
+
+Keep assertions focused on the concept being tested.
+
+- One assert per test is a good guideline (not strict rule)
+- Multiple asserts are acceptable if testing same concept
+- Avoid unrelated assertions in same test
+- Create domain-specific assertion helpers
+
+### 7. F.I.R.S.T. Principles
+
+Clean tests follow these five principles:
+
+| Principle | Description |
+|-----------|-------------|
+| **Fast** | Tests run quickly; slow tests won't be run frequently |
+| **Independent** | Tests don't depend on each other; run in any order |
+| **Repeatable** | Run in any environment without external dependencies |
+| **Self-Validating** | Boolean output - pass or fail, no manual checking |
+| **Timely** | Written just before the production code |
+
+## Guidelines
+
+Less strict recommendations:
+
+- Build a domain-specific testing language over time
+- Refactor tests to be more expressive as patterns emerge
+- Efficiency trade-offs are acceptable in test code
+- Use Given-When-Then naming convention for clarity
+- Name tests to describe the behavior being verified
+
+## Exceptions
+
+When these rules may be relaxed:
+
+- **Efficiency in tests**: Test code can be less efficient than production code (but never less clean)
+- **Multiple asserts**: Acceptable when testing a single logical concept
+- **Integration tests**: May require more setup and multiple verifications
+
+## Quick Reference
+
+| Rule | Summary |
+|------|---------|
+| TDD Laws | Failing test → minimal code → refactor |
+| Keep Clean | Test code = production code quality |
+| Readability | Clarity, simplicity, density of expression |
+| BUILD-OPERATE-CHECK | Setup → Action → Verify |
+| Single Concept | One behavior per test |
+| Minimize Asserts | Few assertions per concept |
+| F.I.R.S.T. | Fast, Independent, Repeatable, Self-Validating, Timely |
diff --git a/.agents/skills/typescript-clean-code/workflows/bug-fix.md b/.agents/skills/typescript-clean-code/workflows/bug-fix.md
new file mode 100644
index 0000000..5d7fcfd
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/bug-fix.md
@@ -0,0 +1,303 @@
+# Bug Fix Workflow
+
+Debugging and fixing bugs cleanly with test coverage.
+
+## When to Use
+
+- Fixing reported bugs
+- Addressing production issues
+- Correcting unexpected behavior
+
+## Prerequisites
+
+- Bug report with reproduction steps
+- Access to the codebase
+- Test framework available
+
+**Reference**: `tdd/rules.md`, `coding-practices/rules.md`, `refactoring.md`
+
+---
+
+## The Golden Rule
+
+> **Write a failing test that reproduces the bug BEFORE fixing it.**
+
+This ensures:
+1. You understand the bug
+2. You'll know when it's fixed
+3. It won't regress in the future
+
+---
+
+## Workflow Steps
+
+### Step 1: Understand the Bug
+
+**Goal**: Know exactly what's wrong before trying to fix it.
+
+- [ ] Read the bug report completely
+- [ ] Understand expected vs. actual behavior
+- [ ] Identify reproduction steps
+- [ ] Determine severity and impact
+
+**Gather Information**:
+```
+Bug: User export fails for users with special characters
+Expected: Export completes successfully
+Actual: Error "Invalid JSON" thrown
+Steps to reproduce:
+  1. Create user with name "O'Brien"
+  2. Call export endpoint
+  3. Observe error
+```
+
+**Ask**:
+- When did this start happening?
+- What changed recently?
+- Does it happen consistently or intermittently?
+
+---
+
+### Step 2: Reproduce the Bug
+
+**Goal**: Verify you can trigger the bug yourself.
+
+- [ ] Follow the reproduction steps
+- [ ] Confirm you see the same behavior
+- [ ] Identify the minimal reproduction case
+- [ ] Document any additional findings
+
+**If you can't reproduce**:
+- Ask for more details
+- Check environment differences
+- Look at logs/monitoring
+
+**Minimal reproduction**:
+```typescript
+// Minimal case that triggers the bug
+const user = { name: "O'Brien", email: "obrien@test.com" };
+const result = exporter.export(user, 'json');
+// Throws: Error "Invalid JSON"
+```
+
+---
+
+### Step 3: Write a Failing Test
+
+**Goal**: Capture the bug as a failing test.
+
+**Reference**: `tdd/rules.md`
+
+```typescript
+describe('UserExporter', () => {
+  it('should handle special characters in names', () => {
+    // Arrange
+    const user = { name: "O'Brien", email: "obrien@test.com" };
+    
+    // Act
+    const result = exporter.export(user, 'json');
+    
+    // Assert
+    expect(result.success).toBe(true);
+    expect(result.data).toContain("O'Brien");
+  });
+});
+```
+
+- [ ] Test reproduces the bug
+- [ ] Test fails (proving bug exists)
+- [ ] Test is specific to this bug
+- [ ] Test name describes the scenario
+
+**Run the test**: It MUST fail.
+
+---
+
+### Step 4: Locate the Bug
+
+**Goal**: Find the root cause.
+
+**Debugging Strategies**:
+
+1. **Binary Search**: Comment out half the code, see if bug persists
+2. **Print Debugging**: Add logs at key points
+3. **Debugger**: Step through execution
+4. **Git Bisect**: Find the commit that introduced it
+
+**Reference**: `coding-practices/rules.md` (debugging section)
+
+**Questions to ask**:
+- Where does the data get corrupted?
+- What assumption is being violated?
+- What edge case wasn't handled?
+
+**Example finding**:
+```typescript
+// Found the bug here:
+function formatJson(user: User): string {
+  // BUG: Not escaping quotes in string values
+  return `{"name":"${user.name}","email":"${user.email}"}`;
+}
+```
+
+- [ ] Root cause identified
+- [ ] You understand WHY it's happening
+
+---
+
+### Step 5: Fix the Bug
+
+**Goal**: Make the test pass with minimal change.
+
+**Write the simplest fix**:
+```typescript
+function formatJson(user: User): string {
+  // FIX: Use JSON.stringify for proper escaping
+  return JSON.stringify({ name: user.name, email: user.email });
+}
+```
+
+- [ ] Fix is minimal and focused
+- [ ] Fix addresses root cause (not symptoms)
+- [ ] No unrelated changes
+
+**Run the test**: It MUST pass now.
+
+---
+
+### Step 6: Check for Regressions
+
+**Goal**: Ensure fix didn't break anything else.
+
+```bash
+npm test  # Run ALL tests
+```
+
+- [ ] New test passes
+- [ ] All existing tests still pass
+- [ ] No regressions introduced
+
+**If other tests fail**:
+- Understand why
+- Decide if those tests were correct
+- Fix or update as needed
+
+---
+
+### Step 7: Look for Similar Bugs
+
+**Goal**: Find and fix related issues.
+
+**Ask**:
+- Could this bug exist elsewhere?
+- Is this a pattern that's repeated?
+- Should we add more tests for similar cases?
+
+**Example**:
+```typescript
+// If formatJson had the bug, check formatCsv too
+it('should handle special characters in CSV export', () => {
+  const user = { name: "O'Brien", email: "obrien@test.com" };
+  const result = exporter.export(user, 'csv');
+  expect(result.success).toBe(true);
+});
+```
+
+- [ ] Checked for similar bugs
+- [ ] Added tests for related cases
+- [ ] Fixed any additional issues found
+
+---
+
+### Step 8: Refactor if Needed
+
+**Goal**: Clean up while tests are green.
+
+**Reference**: `refactoring.md` workflow
+
+- [ ] Is the fix clean?
+- [ ] Could the code be clearer?
+- [ ] Is there duplication to remove?
+- [ ] All tests still pass after refactoring?
+
+**Don't**:
+- Refactor unrelated code in the same commit
+- Make the fix commit harder to review
+
+---
+
+### Step 9: Document the Fix
+
+**Goal**: Help future developers understand.
+
+**Commit message**:
+```
+fix: handle special characters in user export
+
+Users with apostrophes in their names (e.g., "O'Brien") caused
+JSON export to fail due to unescaped quotes.
+
+Fixed by using JSON.stringify instead of string interpolation.
+
+Fixes #123
+```
+
+**Code comment (if needed)**:
+```typescript
+// Use JSON.stringify to properly escape special characters
+// See bug #123 for context
+```
+
+- [ ] Commit message explains the bug and fix
+- [ ] References the bug ticket
+- [ ] Code comments added if fix isn't obvious
+
+---
+
+## Quick Checklist
+
+```
+[ ] Bug understood and documented
+[ ] Bug reproduced locally
+[ ] Failing test written
+[ ] Root cause identified
+[ ] Fix implemented (minimal change)
+[ ] Original test passes
+[ ] All tests pass (no regressions)
+[ ] Similar bugs checked
+[ ] Refactored if needed
+[ ] Fix documented in commit
+```
+
+---
+
+## Debugging Tips
+
+### When Stuck
+
+- [ ] Take a break (15 min walk)
+- [ ] Explain the bug to someone (rubber duck)
+- [ ] Check recent changes (git log)
+- [ ] Look at similar working code
+- [ ] Simplify the reproduction case
+
+### Red Flags
+
+| Symptom | Possible Cause |
+|---------|---------------|
+| Works on my machine | Environment difference |
+| Intermittent failure | Race condition, timing |
+| Only in production | Config/data difference |
+| After deploy | Recent code change |
+
+---
+
+## Exit Criteria
+
+Bug is fixed when:
+- [ ] Failing test written and passes
+- [ ] All tests pass
+- [ ] Root cause addressed (not just symptoms)
+- [ ] Similar issues checked
+- [ ] Fix committed with good message
+- [ ] Bug ticket updated/closed
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01-init.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01-init.md
new file mode 100644
index 0000000..6d87c38
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01-init.md
@@ -0,0 +1,76 @@
+---
+name: 'step-01-init'
+description: 'Initialize code review workflow — set output path and detect continuation'
+nextStepFile: './step-02-function-quality.md'
+---
+
+# Step 1: Initialize Code Review
+
+## STEP GOAL
+
+Set up the code review session: identify the target code, set the output path for the review report, and check for an existing report to resume.
+
+## EXECUTION
+
+### 1. Ask the User
+
+Ask the user:
+- **What code to review?** (file path, module, or directory)
+- **Output path** for the review report (suggest a default: `./code-review-report-{{date}}.md`)
+- **Or provide path to an existing report** to resume a previous review
+
+### 2. Check for Existing Report
+
+If the user provides a path to an existing report file:
+- Read the file
+- Parse the YAML frontmatter
+- If `stepsCompleted` is non-empty → **STOP and load `step-01b-continue.md`**
+
+### 3. Fresh Workflow Setup
+
+If starting fresh:
+1. Copy the template from `templates/report-template.md`
+2. Fill in the frontmatter:
+   - `targetCode`: the code path/scope provided by the user
+   - `outputPath`: the chosen output path
+   - `date`: current date
+3. Write the initialized report to the output path
+
+### 4. Understand Context
+
+**Goal**: Understand what the code is supposed to do before judging how it does it.
+
+- Read the related ticket/story/requirement (if provided)
+- Understand the business purpose
+- Identify the scope of changes
+
+**Ask**: "What problem is this code solving?"
+
+### 5. Append Context to Report
+
+Append to the output document:
+
+```markdown
+## Step 1: Context
+
+**Code Under Review**: {{targetCode}}
+**Purpose**: {{purpose described by user}}
+**Scope**: {{scope of the review}}
+```
+
+## FRONTMATTER UPDATE
+
+Update the output document frontmatter:
+- Add `1` to `stepsCompleted`
+
+## PRESENT TO USER
+
+Show the user:
+- Confirmation of the review target and output path
+- Context summary
+
+Then ask: **[C] Continue to Step 2: Function Quality**
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-02-function-quality.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01b-continue.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01b-continue.md
new file mode 100644
index 0000000..8b489c2
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-01b-continue.md
@@ -0,0 +1,71 @@
+---
+name: 'step-01b-continue'
+description: 'Resume code review from last completed step'
+---
+
+# Step 1b: Continue Previous Code Review
+
+## STEP GOAL
+
+Resume a previously started code review by reading the existing report, determining progress, and routing to the next incomplete step.
+
+## EXECUTION
+
+### 1. Read Existing Report
+
+- Read the file at the output path provided by the user
+- Parse the YAML frontmatter
+- Extract `stepsCompleted` array
+
+### 2. Show Progress Summary
+
+Display to the user:
+
+```
+Code Review Progress
+====================
+Target: {{targetCode}}
+Date Started: {{date}}
+Steps Completed: {{stepsCompleted}}
+
+Step Map:
+  [1] Initialize & Context    {{done/pending}}
+  [2] Function Quality         {{done/pending}}
+  [3] Naming                   {{done/pending}}
+  [4] Class/Module Design      {{done/pending}}
+  [5] Error Handling           {{done/pending}}
+  [6] Tests                    {{done/pending}}
+  [7] Comments                 {{done/pending}}
+  [8] Smells                   {{done/pending}}
+  [9] Feedback                 {{done/pending}}
+```
+
+### 3. Offer Options
+
+Present:
+- **[R] Resume** from the next incomplete step
+- **[O] Overview** — re-read the existing report content before resuming
+- **[X] Start over** — create a fresh report (confirm: this will overwrite)
+
+### 4. Route to Next Step
+
+On **[R]** or after **[O]**:
+
+Determine the next step from `max(stepsCompleted) + 1` and load the corresponding file:
+
+| Next Step | File |
+|-----------|------|
+| 2 | `step-02-function-quality.md` |
+| 3 | `step-03-naming.md` |
+| 4 | `step-04-class-design.md` |
+| 5 | `step-05-error-handling.md` |
+| 6 | `step-06-tests.md` |
+| 7 | `step-07-comments.md` |
+| 8 | `step-08-smells.md` |
+| 9 | `step-09-feedback.md` |
+
+On **[X]**: Go back to `step-01-init.md` fresh workflow setup (section 3).
+
+## NEXT STEP
+
+Load the step file determined above.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-02-function-quality.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-02-function-quality.md
new file mode 100644
index 0000000..717e719
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-02-function-quality.md
@@ -0,0 +1,72 @@
+---
+name: 'step-02-function-quality'
+description: 'Review function quality — size, SRP, arguments, side effects'
+nextStepFile: './step-03-naming.md'
+referenceFiles:
+  - 'references/functions/rules.md'
+  - 'references/functions/checklist.md'
+---
+
+# Step 2: Check Function Quality
+
+## STEP GOAL
+
+Review every function in the target code for size, single responsibility, argument count, abstraction level consistency, and side effects.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/functions/rules.md` — function design rules
+- `references/functions/checklist.md` — function review checklist
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+For each function in the target code, verify:
+
+1. **Size**: Is it small (5-20 lines)?
+2. **Single Responsibility**: Does it do ONE thing?
+3. **Abstraction Level**: Is it consistent throughout?
+4. **Arguments**: Are there 3 or fewer?
+5. **Side Effects**: Are there hidden side effects?
+6. **Name**: Does the name describe what it does?
+
+### Red Flags
+
+Watch for and report:
+- Function > 20 lines
+- More than 3 arguments
+- Boolean flag arguments
+- Output arguments
+- Mixed abstraction levels
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 2: Function Quality
+========================
+
+[PASS/ISSUE] function_name (file:line)
+  - Size: OK / TOO LARGE (N lines)
+  - SRP: OK / MULTIPLE RESPONSIBILITIES
+  - Arguments: OK / TOO MANY (N args)
+  - Side Effects: NONE / FOUND: description
+  Rule: functions/rules.md — Rule N
+
+Summary: N functions reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 3: Naming**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `2` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-03-naming.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-03-naming.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-03-naming.md
new file mode 100644
index 0000000..451f44d
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-03-naming.md
@@ -0,0 +1,67 @@
+---
+name: 'step-03-naming'
+description: 'Review naming conventions — intent, consistency, searchability'
+nextStepFile: './step-04-class-design.md'
+referenceFiles:
+  - 'references/naming/rules.md'
+---
+
+# Step 3: Check Naming
+
+## STEP GOAL
+
+Review all names (variables, functions, classes) in the target code for intent-revealing quality, consistency, and searchability.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/naming/rules.md` — naming rules and conventions
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+Check all names in the target code:
+
+1. **Variables**: Do they reveal intent without comments?
+2. **Functions**: Are they verb phrases that describe the action?
+3. **Classes**: Are they noun phrases that describe responsibility?
+4. **No Encodings**: No Hungarian notation or prefixes?
+5. **Searchable**: Can you grep for important names?
+6. **Consistent**: Same concept = same word throughout?
+
+### Red Flags
+
+Watch for and report:
+- Single-letter variables (except loop counters)
+- Abbreviations that aren't universal
+- Names that require comments to explain
+- Different words for the same concept
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 3: Naming
+==============
+
+[PASS/ISSUE] name (file:line)
+  - Problem: description
+  - Suggestion: better_name
+  Rule: naming/rules.md — Rule N
+
+Summary: N names reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 4: Class/Module Design**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `3` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-04-class-design.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-04-class-design.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-04-class-design.md
new file mode 100644
index 0000000..64de09c
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-04-class-design.md
@@ -0,0 +1,65 @@
+---
+name: 'step-04-class-design'
+description: 'Review class/module design — SRP, cohesion, dependencies'
+nextStepFile: './step-05-error-handling.md'
+referenceFiles:
+  - 'references/classes/rules.md'
+---
+
+# Step 4: Check Class/Module Design
+
+## STEP GOAL
+
+Review classes and modules in the target code for single responsibility, cohesion, size, and proper dependency management.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/classes/rules.md` — class design rules
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+For each class/module in the target code, verify:
+
+1. **Single Responsibility**: One reason to change?
+2. **Cohesion**: Methods use most instance variables?
+3. **Size**: Small and focused?
+4. **Dependencies**: Depends on abstractions, not concretions?
+
+### Red Flags
+
+Watch for and report:
+- God classes with many responsibilities
+- Low cohesion (methods don't use shared state)
+- Concrete dependencies that should be injected
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 4: Class/Module Design
+============================
+
+[PASS/ISSUE] ClassName (file:line)
+  - SRP: OK / MULTIPLE RESPONSIBILITIES: list
+  - Cohesion: HIGH / LOW — reason
+  - Dependencies: OK / CONCRETE: list
+  Rule: classes/rules.md — Rule N
+
+Summary: N classes reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 5: Error Handling**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `4` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-05-error-handling.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-05-error-handling.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-05-error-handling.md
new file mode 100644
index 0000000..e715ac9
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-05-error-handling.md
@@ -0,0 +1,66 @@
+---
+name: 'step-05-error-handling'
+description: 'Review error handling — exceptions, null safety, context'
+nextStepFile: './step-06-tests.md'
+referenceFiles:
+  - 'references/error-handling/rules.md'
+---
+
+# Step 5: Check Error Handling
+
+## STEP GOAL
+
+Review error handling patterns in the target code for proper exception usage, null safety, and error context.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/error-handling/rules.md` — error handling rules
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+Check all error handling in the target code:
+
+1. **Exceptions over codes**: Using exceptions, not error codes?
+2. **No null returns**: Returning empty collections or Optional instead?
+3. **No null passes**: Not passing null to functions?
+4. **Context**: Exceptions include enough context?
+5. **Normal flow**: Happy path is clear and uncluttered?
+
+### Red Flags
+
+Watch for and report:
+- Returning null
+- Swallowing exceptions silently
+- Error handling mixed with business logic
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 5: Error Handling
+======================
+
+[PASS/ISSUE] location (file:line)
+  - Problem: description
+  - Pattern: null return / swallowed exception / mixed logic
+  - Suggestion: fix description
+  Rule: error-handling/rules.md — Rule N
+
+Summary: N patterns reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 6: Tests**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `5` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-06-tests.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-06-tests.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-06-tests.md
new file mode 100644
index 0000000..e902f4f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-06-tests.md
@@ -0,0 +1,67 @@
+---
+name: 'step-06-tests'
+description: 'Review test quality — coverage, readability, FIRST principles'
+nextStepFile: './step-07-comments.md'
+referenceFiles:
+  - 'references/unit-tests/rules.md'
+---
+
+# Step 6: Check Tests
+
+## STEP GOAL
+
+Review tests for the target code — coverage, readability, single concept per test, and F.I.R.S.T. principles.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/unit-tests/rules.md` — test quality rules
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+Check all tests related to the target code:
+
+1. **Coverage**: Are the changes tested?
+2. **Readability**: Can you understand what's being tested?
+3. **Single Concept**: One concept per test?
+4. **F.I.R.S.T.**: Fast, Independent, Repeatable, Self-validating, Timely?
+5. **Naming**: Test names describe the scenario?
+
+### Red Flags
+
+Watch for and report:
+- No tests for new code
+- Tests that test multiple things
+- Tests that depend on each other
+- Slow tests
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 6: Tests
+=============
+
+[PASS/ISSUE] test_name (file:line)
+  - Coverage: OK / MISSING for: description
+  - Readability: OK / UNCLEAR: reason
+  - F.I.R.S.T.: OK / VIOLATION: which principle
+  Rule: unit-tests/rules.md — Rule N
+
+Summary: N tests reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 7: Comments**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `6` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-07-comments.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-07-comments.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-07-comments.md
new file mode 100644
index 0000000..fc65ca8
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-07-comments.md
@@ -0,0 +1,65 @@
+---
+name: 'step-07-comments'
+description: 'Review comments — necessity, accuracy, noise'
+nextStepFile: './step-08-smells.md'
+referenceFiles:
+  - 'references/comments/rules.md'
+---
+
+# Step 7: Check Comments
+
+## STEP GOAL
+
+Review all comments in the target code for necessity, accuracy, and noise.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/comments/rules.md` — comment rules
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+Check all comments in the target code:
+
+1. **Necessary**: Could the code explain itself instead?
+2. **Accurate**: Do comments match the code?
+3. **No noise**: No redundant or obvious comments?
+4. **No commented-out code**: Old code removed, not commented?
+
+### Red Flags
+
+Watch for and report:
+- Comments explaining "what" instead of "why"
+- Commented-out code blocks
+- TODO comments that should be tickets
+- Outdated comments
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 7: Comments
+================
+
+[PASS/ISSUE] comment (file:line)
+  - Problem: unnecessary / inaccurate / noise / dead code
+  - Suggestion: remove / rewrite / convert to ticket
+  Rule: comments/rules.md — Rule N
+
+Summary: N comments reviewed, N issues found
+```
+
+Then ask: **[C] Continue to Step 8: Code Smells**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `7` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-08-smells.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-08-smells.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-08-smells.md
new file mode 100644
index 0000000..12841d9
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-08-smells.md
@@ -0,0 +1,61 @@
+---
+name: 'step-08-smells'
+description: 'Scan for code smells — duplication, feature envy, coupling'
+nextStepFile: './step-09-feedback.md'
+referenceFiles:
+  - 'references/smells/rules.md'
+---
+
+# Step 8: Check for Smells
+
+## STEP GOAL
+
+Scan the target code for common code smells using the smell catalog.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/smells/rules.md` — code smell catalog
+
+Cite specific smell codes when reporting findings.
+
+## ANALYSIS PROCESS
+
+Scan for common smells:
+
+1. **G5 - Duplication**: Any copy-pasted code?
+2. **G14 - Feature Envy**: Methods using other class's data excessively?
+3. **G30 - Functions Do One Thing**: Any functions doing multiple things?
+4. **G31 - Hidden Temporal Coupling**: Hidden order dependencies?
+5. **C5 - Commented-Out Code**: Any dead code?
+
+Also scan for any other smells from the catalog that apply to the target code.
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 8: Code Smells
+===================
+
+[PASS/FOUND] smell_code - smell_name (file:line)
+  - Evidence: description
+  - Impact: why this is a problem
+  - Suggestion: how to fix
+  Rule: smells/rules.md — G5/G14/G30/etc.
+
+Summary: N smells found
+```
+
+Then ask: **[C] Continue to Step 9: Feedback**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `8` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-09-feedback.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-09-feedback.md b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-09-feedback.md
new file mode 100644
index 0000000..fbcb047
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/steps/step-09-feedback.md
@@ -0,0 +1,94 @@
+---
+name: 'step-09-feedback'
+description: 'Compile final feedback — prioritize, summarize, mark complete'
+referenceFiles:
+  - 'references/collaboration/rules.md'
+---
+
+# Step 9: Provide Feedback
+
+## STEP GOAL
+
+Compile all findings from steps 2-8 into a prioritized, actionable feedback summary. Mark the review as complete.
+
+## REFERENCE LOADING
+
+Before compiling feedback, load and read:
+- `references/collaboration/rules.md` — feedback and communication rules
+
+## COMPILATION PROCESS
+
+### 1. Gather All Findings
+
+Read through the output document and collect all issues found in steps 2-8.
+
+### 2. Prioritize Issues
+
+Categorize each issue:
+
+| Priority | Category | Meaning |
+|----------|----------|---------|
+| 1 | `[BLOCKING]` | Must fix — correctness, security, major design flaw |
+| 2 | `[SUGGESTION]` | Should fix — improves quality significantly |
+| 3 | `[NIT]` | Nice to have — minor style or preference |
+
+### 3. Format Feedback
+
+For each issue, use this template:
+
+```
+[BLOCKING/SUGGESTION/NIT] [File:Line]
+Issue: What's wrong
+Why: Reference to specific rule
+Suggestion: How to fix
+```
+
+### 4. Write Summary
+
+Append to the output document:
+
+```markdown
+## Final Review Summary
+
+### Blocking Issues (Must Fix)
+- [list or "None found"]
+
+### Suggestions (Should Fix)
+- [list or "None"]
+
+### Nits (Nice to Have)
+- [list or "None"]
+
+### Quick Checklist
+- [ ] Functions: small, single purpose, few arguments
+- [ ] Names: reveal intent, consistent
+- [ ] Classes: SRP, cohesive
+- [ ] Errors: exceptions, no null, context
+- [ ] Tests: exist, readable, F.I.R.S.T.
+- [ ] Comments: necessary, accurate
+- [ ] Smells: none detected
+
+### Verdict
+[Overall assessment — approve, needs work, or major concerns]
+```
+
+## PRESENT TO USER
+
+Show the final summary to the user. Highlight blocking issues first.
+
+Feedback principles (from `collaboration/rules.md`):
+1. **Be specific**: Point to exact lines/functions
+2. **Explain why**: Reference principles, not just preferences
+3. **Suggest alternatives**: Don't just criticize, propose solutions
+4. **Prioritize**: Distinguish blocking issues from nice-to-haves
+5. **Be respectful**: Critique code, not the person
+
+## FRONTMATTER UPDATE
+
+Update the output document frontmatter:
+- Add `9` to `stepsCompleted`
+- Set `status` to `'complete'`
+
+## WORKFLOW COMPLETE
+
+The code review workflow is complete. The full report is saved at the output path.
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/templates/report-template.md b/.agents/skills/typescript-clean-code/workflows/code-review/templates/report-template.md
new file mode 100644
index 0000000..b0f480a
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/templates/report-template.md
@@ -0,0 +1,18 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'code-review'
+targetCode: ''
+outputPath: ''
+date: ''
+status: 'in-progress'
+---
+
+# Code Review Report
+
+**Date**: {{date}}
+**Target**: {{targetCode}}
+**Status**: {{status}}
+
+---
+
diff --git a/.agents/skills/typescript-clean-code/workflows/code-review/workflow.md b/.agents/skills/typescript-clean-code/workflows/code-review/workflow.md
new file mode 100644
index 0000000..e86e066
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/code-review/workflow.md
@@ -0,0 +1,55 @@
+---
+name: 'code-review'
+description: 'Step-by-step process for reviewing code quality'
+firstStepFile: './steps/step-01-init.md'
+templateFile: './templates/report-template.md'
+---
+
+# Code Review Workflow
+
+Step-by-step process for reviewing code quality.
+
+## When to Use
+
+- Reviewing your own code before committing
+- Reviewing a colleague's code
+- Performing a quality check on a module
+
+## Prerequisites
+
+Have the code to review accessible and understand its purpose.
+
+## Step-File Architecture
+
+This workflow uses a **step-file architecture** for context-safe execution:
+
+- Each step is a separate file loaded sequentially
+- Progress is tracked via `stepsCompleted` in the output document's YAML frontmatter
+- If context is compacted mid-workflow, step-01 detects existing output and resumes from the last completed step via step-01b
+
+### Steps
+
+| Step | File | Description |
+|------|------|-------------|
+| 1 | `step-01-init.md` | Initialize workflow, set output path, detect continuation |
+| 1b | `step-01b-continue.md` | Resume from last completed step |
+| 2 | `step-02-function-quality.md` | Check function quality |
+| 3 | `step-03-naming.md` | Check naming conventions |
+| 4 | `step-04-class-design.md` | Check class/module design |
+| 5 | `step-05-error-handling.md` | Check error handling |
+| 6 | `step-06-tests.md` | Check test quality |
+| 7 | `step-07-comments.md` | Check comments |
+| 8 | `step-08-smells.md` | Check for code smells |
+| 9 | `step-09-feedback.md` | Provide feedback, mark complete |
+
+### Rules
+
+1. **Load one step at a time** - Read the step file, execute it, then load the next
+2. **Update frontmatter after each step** - Add the step number to `stepsCompleted`
+3. **Wait for user confirmation** - Present findings and wait for `[C]` before proceeding
+4. **Load reference files** - Each step specifies which reference files to load before analysis
+5. **Cite specific rules** - When reporting findings, cite the specific rule from the reference file
+
+## Begin
+
+Load `steps/step-01-init.md` to start.
diff --git a/.agents/skills/typescript-clean-code/workflows/deadline-negotiation.md b/.agents/skills/typescript-clean-code/workflows/deadline-negotiation.md
new file mode 100644
index 0000000..b0e3a64
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/deadline-negotiation.md
@@ -0,0 +1,276 @@
+# Deadline Negotiation Workflow
+
+Handling unrealistic deadline requests professionally.
+
+## When to Use
+
+- Asked to commit to an impossible deadline
+- Deadline is set without your input
+- Scope exceeds available time
+- Pressure to "just make it work"
+
+## Prerequisites
+
+- Understanding of the work required
+- Estimate of realistic timeline (see `estimation.md`)
+- Knowledge of your capacity
+
+**Reference**: `saying-no/rules.md`, `commitment/rules.md`, `estimation/rules.md`, `pressure/rules.md`
+
+---
+
+## The Golden Rules
+
+1. **Never say "I'll try"** - It's dishonest and sets you up to fail
+2. **Provide data, not emotions** - Use estimates and facts
+3. **Offer alternatives** - Don't just say no, propose solutions
+4. **Escalate professionally** - Not as a threat, but as information
+
+---
+
+## Workflow Steps
+
+### Step 1: Gather Information
+
+**Goal**: Understand what's being asked before responding.
+
+- [ ] What exactly is the deadline?
+- [ ] What is the full scope of work?
+- [ ] Why is this deadline set?
+- [ ] What are the consequences of missing it?
+- [ ] Who set the deadline?
+
+**Ask clarifying questions**:
+```
+"Help me understand - what's driving the March 1st date?"
+"What's included in 'complete'? Does that include testing and documentation?"
+"What happens if we deliver on March 15th instead?"
+```
+
+---
+
+### Step 2: Do Your Estimation
+
+**Goal**: Know the realistic timeline before negotiating.
+
+**Reference**: `estimation.md` workflow
+
+- [ ] Break down the work into tasks
+- [ ] Apply PERT estimation
+- [ ] Calculate expected time and uncertainty
+- [ ] Document assumptions
+
+**Example**:
+```
+Feature: User Export
+
+Estimated: 25-32 hours (95% confidence)
+Calendar time: 4-5 days (accounting for meetings, etc.)
+Realistic delivery: 1.5 weeks from start
+
+Requested deadline: End of this week (3 days)
+Gap: 2-4 days short
+```
+
+---
+
+### Step 3: Identify Options
+
+**Goal**: Prepare alternatives before the conversation.
+
+**Option types**:
+
+1. **Reduce scope**: What can be cut or deferred?
+2. **Extend deadline**: What's the realistic date?
+3. **Add resources**: Can anyone help? (Be realistic about ramp-up)
+4. **Change approach**: Is there a simpler solution?
+
+**Example options**:
+```
+Option A: Reduce Scope
+- Deliver JSON export only (cut CSV)
+- Skip documentation
+- Delivery: End of week (meets deadline)
+- Trade-off: CSV comes in week 2
+
+Option B: Extend Deadline
+- Full feature with JSON + CSV
+- Complete documentation
+- Delivery: End of next week
+- Trade-off: 1 week later
+
+Option C: Partial Delivery
+- JSON export by end of week
+- CSV export by mid next week
+- Trade-off: Two releases needed
+```
+
+---
+
+### Step 4: Have the Conversation
+
+**Goal**: Communicate clearly and professionally.
+
+**Structure**:
+1. Acknowledge the request
+2. Share your analysis
+3. Present the gap
+4. Offer alternatives
+5. Ask for decision
+
+**Example conversation**:
+
+**Bad approach** (don't do this):
+```
+"There's no way I can do this by Friday. It's impossible."
+```
+
+**Good approach**:
+```
+"I understand the deadline is Friday. I've broken down the work,
+and with testing and documentation, I estimate 4-5 days of work.
+
+Given we're starting today (Tuesday), that puts realistic 
+completion at next Tuesday, not Friday.
+
+I see three options:
+1. We can deliver JSON export only by Friday, and add CSV next week
+2. We can extend the deadline to next Tuesday for the full feature
+3. We can discuss if there's scope I'm not understanding correctly
+
+Which option works best for the business?"
+```
+
+**Key phrases**:
+- "Based on my analysis..."
+- "Here are the options I see..."
+- "What would you like to prioritize?"
+- "I want to give you a commitment I can keep"
+
+---
+
+### Step 5: Handle Pushback
+
+**Goal**: Stay professional when pressured.
+
+**Common pushback and responses**:
+
+**"Can't you just try?"**
+```
+Reference: commitment/rules.md - The "Try" problem
+
+Response: "I want to be honest with you. If I say I'll try, I'm really 
+saying I don't think I can do it but I don't want to say no. 
+That's not fair to either of us. Here's what I CAN commit to..."
+```
+
+**"We promised the client"**
+```
+Reference: saying-no/rules.md - High stakes
+
+Response: "I understand there's a commitment to the client. That makes 
+it even more important that we're realistic. Would you rather tell 
+them now about a 3-day delay, or on Friday that we missed the deadline?
+Let's figure out the best path forward together."
+```
+
+**"Everyone else manages to deliver on time"**
+```
+Response: "I want to deliver on time too. Can we look at the scope 
+together? Maybe I'm including work that isn't needed, or maybe 
+there's something I can learn from how others approach this."
+```
+
+**"This is critical for the business"**
+```
+Response: "I understand this is important. That's exactly why I want 
+to give you accurate information. Committing to Friday and delivering 
+broken code or missing on Tuesday would hurt the business more than 
+being clear now about realistic timing."
+```
+
+---
+
+### Step 6: Document the Agreement
+
+**Goal**: Have a clear record of what was agreed.
+
+After the conversation:
+- [ ] Send a follow-up email/message summarizing:
+  - What was agreed
+  - What's in scope / out of scope
+  - The delivery date
+  - Any assumptions or dependencies
+
+**Example follow-up**:
+```
+Hi [Manager],
+
+Thanks for the discussion. To confirm our agreement:
+
+Scope: User export feature - JSON format only
+Deadline: Friday, March 1st
+Out of scope: CSV format (scheduled for March 8th)
+
+Assumptions:
+- No other high-priority work assigned this week
+- API contract is finalized
+- Test environment is available
+
+Let me know if I've missed anything.
+```
+
+---
+
+### Step 7: Handle Escalation (if needed)
+
+**Goal**: Escalate professionally if pushback continues.
+
+**When to escalate**:
+- You're being asked to commit to something impossible
+- Your concerns are being dismissed
+- The risk to the project/company is significant
+
+**How to escalate**:
+```
+"I want to make sure we're making the right decision here. I'm 
+not comfortable committing to Friday because [specific reasons].
+
+I think we should involve [manager/stakeholder] to make sure we're 
+aligned on the trade-offs. Would you like me to set up that meeting?"
+```
+
+**Reference**: `saying-no/rules.md` - "Threaten professionally"
+
+---
+
+## Quick Reference
+
+### What NOT to Say
+
+| Don't Say | Why | Say Instead |
+|-----------|-----|-------------|
+| "I'll try" | Dishonest, sets up failure | "I can commit to X by Y" |
+| "That's impossible" | Sounds defensive | "Based on my analysis, that would require..." |
+| "You don't understand" | Confrontational | "Help me understand the constraints..." |
+| "Fine, I'll do it" | Resentful commitment | "Here are the options..." |
+
+### What TO Say
+
+| Situation | Response |
+|-----------|----------|
+| Unrealistic deadline | "Based on my estimate, realistic delivery is [date]. Here are options..." |
+| Pressure to commit | "I want to give you a commitment I can keep. Can we discuss scope?" |
+| Scope creep | "If we add X, the deadline moves to Y. Which do you prefer?" |
+| Being dismissed | "I understand the pressure. Let's involve [stakeholder] to decide." |
+
+---
+
+## Exit Criteria
+
+Negotiation is complete when:
+- [ ] Clear agreement on scope and deadline
+- [ ] Agreement documented in writing
+- [ ] You can honestly commit to the deadline
+- [ ] Trade-offs are understood by all parties
+- [ ] Escalation path is clear if things change
diff --git a/.agents/skills/typescript-clean-code/workflows/estimation.md b/.agents/skills/typescript-clean-code/workflows/estimation.md
new file mode 100644
index 0000000..c99d8a9
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/estimation.md
@@ -0,0 +1,264 @@
+# Estimation Workflow
+
+PERT-based task estimation process for accurate estimates.
+
+## When to Use
+
+- Sprint planning
+- Project scoping
+- When asked "how long will this take?"
+- Committing to deadlines
+
+## Prerequisites
+
+- Understanding of the task/feature
+- Knowledge of the codebase
+- Ability to break down work
+
+**Reference**: `estimation/rules.md`, `estimation/examples.md`, `commitment/rules.md`
+
+---
+
+## The Golden Rules
+
+1. **Estimates are NOT commitments** - They're probability distributions
+2. **Never give a single number** - Always provide a range
+3. **Break it down** - Large tasks have large uncertainty
+4. **Communicate uncertainty** - Be explicit about what you don't know
+
+---
+
+## Workflow Steps
+
+### Step 1: Clarify the Request
+
+**Goal**: Understand exactly what's being asked.
+
+- [ ] What is the scope of the work?
+- [ ] What are the acceptance criteria?
+- [ ] What's NOT included?
+- [ ] Are there dependencies on others?
+
+**Ask**:
+- "Can you clarify what 'done' means for this?"
+- "Does this include testing/documentation/deployment?"
+- "Are there any constraints I should know about?"
+
+**Reference**: `acceptance-testing/knowledge.md`
+
+---
+
+### Step 2: Break Down the Task
+
+**Goal**: Decompose into estimable pieces.
+
+Break the task into subtasks that are:
+- Independent (can be done separately)
+- Small (< 1 day ideal, < 3 days max)
+- Clear (you know what "done" means)
+
+**Example**:
+```
+Feature: User Export
+
+Subtasks:
+1. Create UserExporter interface
+2. Implement JSON formatter
+3. Implement CSV formatter  
+4. Add error handling
+5. Write unit tests
+6. Write integration tests
+7. Update API documentation
+```
+
+- [ ] Each subtask is small enough to estimate
+- [ ] No subtask > 3 days
+- [ ] Dependencies identified
+
+---
+
+### Step 3: Apply PERT to Each Subtask
+
+**Goal**: Get trivariate estimates for each subtask.
+
+For each subtask, estimate three values:
+
+| Value | Symbol | Meaning |
+|-------|--------|---------|
+| Optimistic | O | Best case (everything goes right) |
+| Nominal | N | Most likely (normal conditions) |
+| Pessimistic | P | Worst case (things go wrong) |
+
+**Example**:
+```
+Subtask: Implement JSON formatter
+- Optimistic (O): 2 hours (straightforward, no surprises)
+- Nominal (N): 4 hours (normal development)
+- Pessimistic (P): 12 hours (unexpected complexity, bugs)
+```
+
+**Tips for each value**:
+- **Optimistic**: "If everything goes perfectly"
+- **Nominal**: "Most likely scenario"
+- **Pessimistic**: "If I hit problems but still finish"
+
+---
+
+### Step 4: Calculate PERT Values
+
+**Goal**: Compute expected time and uncertainty.
+
+**PERT Formulas**:
+```
+Expected Time (μ) = (O + 4N + P) / 6
+Standard Deviation (σ) = (P - O) / 6
+```
+
+**Example Calculation**:
+```
+O = 2, N = 4, P = 12
+
+μ = (2 + 4×4 + 12) / 6 = (2 + 16 + 12) / 6 = 30/6 = 5 hours
+σ = (12 - 2) / 6 = 10/6 = 1.67 hours
+```
+
+**Calculate for each subtask**:
+```
+| Subtask              | O  | N  | P   | μ     | σ    |
+|---------------------|----|----|-----|-------|------|
+| UserExporter interface| 1  | 2  | 4   | 2.2   | 0.5  |
+| JSON formatter       | 2  | 4  | 12  | 5.0   | 1.7  |
+| CSV formatter        | 2  | 4  | 10  | 4.7   | 1.3  |
+| Error handling       | 1  | 2  | 6   | 2.5   | 0.8  |
+| Unit tests           | 2  | 4  | 8   | 4.3   | 1.0  |
+| Integration tests    | 2  | 4  | 10  | 4.7   | 1.3  |
+| Documentation        | 1  | 2  | 4   | 2.2   | 0.5  |
+```
+
+---
+
+### Step 5: Sum and Calculate Total
+
+**Goal**: Combine subtask estimates.
+
+**Total Expected Time**:
+```
+μ_total = Σ μ_i  (sum of all expected times)
+```
+
+**Total Standard Deviation**:
+```
+σ_total = √(Σ σ_i²)  (square root of sum of squares)
+```
+
+**Example**:
+```
+μ_total = 2.2 + 5.0 + 4.7 + 2.5 + 4.3 + 4.7 + 2.2 = 25.6 hours
+
+σ_total = √(0.5² + 1.7² + 1.3² + 0.8² + 1.0² + 1.3² + 0.5²)
+        = √(0.25 + 2.89 + 1.69 + 0.64 + 1.0 + 1.69 + 0.25)
+        = √8.41
+        = 2.9 hours
+```
+
+---
+
+### Step 6: Communicate the Estimate
+
+**Goal**: Present estimate with appropriate uncertainty.
+
+**Never say**: "It will take 26 hours"
+
+**Instead say**:
+```
+"I estimate this will take about 26 hours, give or take 3 hours.
+There's about a 95% chance it will be done within 32 hours."
+```
+
+**Confidence Intervals**:
+| Confidence | Formula | Example |
+|------------|---------|---------|
+| 68% | μ ± 1σ | 23-29 hours |
+| 95% | μ ± 2σ | 20-32 hours |
+| 99.7% | μ ± 3σ | 17-35 hours |
+
+**Communicate**:
+- [ ] Expected time (μ)
+- [ ] Range (μ ± σ or μ ± 2σ)
+- [ ] Key assumptions
+- [ ] What could change the estimate
+
+---
+
+### Step 7: Document Assumptions
+
+**Goal**: Make uncertainty explicit.
+
+List what you assumed:
+```
+Assumptions:
+- API contract is already defined
+- No major refactoring needed
+- Test environment is available
+- No dependencies on other teams
+
+Risks that could increase time:
+- If we need to refactor the data layer: +8-16 hours
+- If API contract changes: +4-8 hours
+- If test environment issues: +2-4 hours
+```
+
+- [ ] Assumptions documented
+- [ ] Risks identified
+- [ ] Impact of risks quantified
+
+---
+
+## Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────┐
+│                PERT ESTIMATION                       │
+│                                                      │
+│  For each task, estimate:                           │
+│    O = Optimistic (best case)                       │
+│    N = Nominal (most likely)                        │
+│    P = Pessimistic (worst case)                     │
+│                                                      │
+│  Calculate:                                          │
+│    Expected: μ = (O + 4N + P) / 6                   │
+│    Std Dev:  σ = (P - O) / 6                        │
+│                                                      │
+│  For multiple tasks:                                │
+│    μ_total = sum of all μ                           │
+│    σ_total = √(sum of all σ²)                       │
+│                                                      │
+│  Report as range:                                   │
+│    "About X hours, give or take Y hours"            │
+│    or "Between X and Z hours (95% confidence)"      │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Mistake | Why It's Bad | Do Instead |
+|---------|--------------|------------|
+| Single number | Creates false precision | Give a range |
+| Optimistic only | You'll always be "late" | Include pessimistic |
+| Padding | Dishonest, still often wrong | Use PERT honestly |
+| Commitment language | "I'll have it done by..." | "I estimate..." |
+| Skipping breakdown | Large tasks = large error | Break it down |
+
+---
+
+## Exit Criteria
+
+Estimation is complete when:
+- [ ] Task broken into subtasks (< 3 days each)
+- [ ] Each subtask has O, N, P values
+- [ ] Total μ and σ calculated
+- [ ] Estimate communicated as a range
+- [ ] Assumptions documented
+- [ ] Risks identified
diff --git a/.agents/skills/typescript-clean-code/workflows/new-feature.md b/.agents/skills/typescript-clean-code/workflows/new-feature.md
new file mode 100644
index 0000000..a11dfed
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/new-feature.md
@@ -0,0 +1,269 @@
+# New Feature Workflow
+
+Writing new code following clean code principles from the start.
+
+## When to Use
+
+- Implementing a new feature or user story
+- Adding new functionality to an existing system
+- Creating a new module or service
+
+## Prerequisites
+
+- Clear understanding of requirements
+- Access to the codebase
+- Test framework set up
+
+**Reference**: `functions/rules.md`, `naming/rules.md`, `classes/rules.md`, `tdd/rules.md`
+
+---
+
+## Workflow Steps
+
+### Step 1: Understand Requirements
+
+**Goal**: Know exactly what you're building before writing code.
+
+- [ ] Read the ticket/story/requirement completely
+- [ ] Identify acceptance criteria
+- [ ] Clarify any ambiguities with stakeholders
+- [ ] Understand the "why" behind the feature
+
+**Ask**:
+- What problem does this solve?
+- What are the edge cases?
+- What should happen on errors?
+- How will this be tested?
+
+**Reference**: `acceptance-testing/knowledge.md`
+
+---
+
+### Step 2: Plan the Approach
+
+**Goal**: Design before coding.
+
+- [ ] Identify the components/classes needed
+- [ ] Define the interfaces/contracts
+- [ ] Consider dependencies
+- [ ] Plan for testability
+
+**Design Questions**:
+- What are the nouns? (potential classes)
+- What are the verbs? (potential methods)
+- What are the dependencies?
+- How will I test this?
+
+**Sketch the structure**:
+```typescript
+// Example: Feature to export user data
+
+// Nouns: UserExporter, ExportFormat, ExportResult
+// Verbs: export, format, validate
+
+interface UserExporter {
+  export(userId: string, format: ExportFormat): Promise<ExportResult>;
+}
+```
+
+---
+
+### Step 3: Write Acceptance Test(s)
+
+**Goal**: Define "done" with executable tests.
+
+**Reference**: `acceptance-testing/rules.md`
+
+```typescript
+describe('User Export Feature', () => {
+  it('should export user data as JSON', async () => {
+    // Arrange
+    const userId = 'user-123';
+    await createTestUser(userId, { name: 'Alice', email: 'alice@example.com' });
+    
+    // Act
+    const result = await userExporter.export(userId, 'json');
+    
+    // Assert
+    expect(result.success).toBe(true);
+    expect(result.data).toContain('"name":"Alice"');
+  });
+});
+```
+
+- [ ] Tests describe the acceptance criteria
+- [ ] Tests are readable by non-developers
+- [ ] Tests fail (feature doesn't exist yet)
+
+---
+
+### Step 4: Build with TDD
+
+**Goal**: Implement using red-green-refactor cycles.
+
+**Reference**: `tdd.md` workflow
+
+For each piece of functionality:
+
+1. **RED**: Write a small failing unit test
+2. **GREEN**: Write minimum code to pass
+3. **REFACTOR**: Clean up while green
+
+**Start with the simplest case**:
+```typescript
+describe('UserExporter', () => {
+  it('should throw if user not found', async () => {
+    const exporter = new UserExporter(mockRepo);
+    await expect(exporter.export('nonexistent', 'json'))
+      .rejects.toThrow('User not found');
+  });
+});
+```
+
+**Build up complexity**:
+```
+1. Error case: user not found
+2. Simple case: export one field
+3. Full case: export all fields
+4. Format: JSON format
+5. Format: CSV format
+6. Edge: special characters
+```
+
+---
+
+### Step 5: Apply Clean Code Principles
+
+**Goal**: Write clean code from the start.
+
+While building, continuously apply:
+
+**Functions** (`functions/rules.md`):
+- [ ] Small (5-20 lines)
+- [ ] Do one thing
+- [ ] Descriptive names
+- [ ] Few arguments (≤3)
+
+**Naming** (`naming/rules.md`):
+- [ ] Intention-revealing names
+- [ ] No abbreviations
+- [ ] Consistent terminology
+
+**Error Handling** (`error-handling/rules.md`):
+- [ ] Use exceptions, not error codes
+- [ ] Don't return null
+- [ ] Provide context in errors
+
+**Example of clean implementation**:
+```typescript
+class UserExporter {
+  constructor(private readonly userRepository: UserRepository) {}
+
+  async export(userId: string, format: ExportFormat): Promise<ExportResult> {
+    const user = await this.findUserOrThrow(userId);
+    const formatter = this.getFormatter(format);
+    const data = formatter.format(user);
+    
+    return { success: true, data };
+  }
+
+  private async findUserOrThrow(userId: string): Promise<User> {
+    const user = await this.userRepository.findById(userId);
+    if (!user) {
+      throw new UserNotFoundError(userId);
+    }
+    return user;
+  }
+
+  private getFormatter(format: ExportFormat): Formatter {
+    const formatters: Record<ExportFormat, Formatter> = {
+      json: new JsonFormatter(),
+      csv: new CsvFormatter(),
+    };
+    return formatters[format] ?? throw new UnsupportedFormatError(format);
+  }
+}
+```
+
+---
+
+### Step 6: Review Against Checklist
+
+**Goal**: Self-review before considering "done".
+
+**Reference**: `functions/checklist.md`, `code-review.md` workflow
+
+- [ ] All acceptance tests pass
+- [ ] Unit test coverage is adequate
+- [ ] Functions are small and focused
+- [ ] Names reveal intent
+- [ ] No code smells
+- [ ] Error handling is clean
+- [ ] No commented-out code
+- [ ] Code is formatted consistently
+
+---
+
+### Step 7: Refactor if Needed
+
+**Goal**: Polish the implementation.
+
+**Reference**: `refactoring.md` workflow
+
+- [ ] Remove any duplication
+- [ ] Improve any unclear names
+- [ ] Extract any long methods
+- [ ] Simplify any complex logic
+- [ ] All tests still pass
+
+---
+
+### Step 8: Document if Necessary
+
+**Goal**: Add only necessary documentation.
+
+**Reference**: `comments/rules.md`
+
+- [ ] Public APIs have doc comments
+- [ ] Complex "why" decisions are explained
+- [ ] No redundant comments
+- [ ] README updated if needed
+
+**Good documentation**:
+```typescript
+/**
+ * Exports user data in the specified format.
+ * 
+ * @throws UserNotFoundError if user doesn't exist
+ * @throws UnsupportedFormatError if format is not supported
+ */
+export(userId: string, format: ExportFormat): Promise<ExportResult>
+```
+
+---
+
+## Quick Checklist
+
+```
+[ ] Requirements understood
+[ ] Approach planned
+[ ] Acceptance tests written
+[ ] Built with TDD (red-green-refactor)
+[ ] Clean code principles applied
+[ ] Self-reviewed against checklist
+[ ] Refactored if needed
+[ ] Documented if necessary
+[ ] All tests pass
+[ ] Ready for code review
+```
+
+---
+
+## Exit Criteria
+
+Feature is complete when:
+- [ ] All acceptance criteria are met
+- [ ] All tests pass
+- [ ] Code follows clean code principles
+- [ ] Self-review checklist passes
+- [ ] Ready for peer code review
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01-init.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01-init.md
new file mode 100644
index 0000000..7f0eb87
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01-init.md
@@ -0,0 +1,93 @@
+---
+name: 'step-01-init'
+description: 'Initialize PR review workflow — set output path, understand context, detect continuation'
+nextStepFile: './step-02-tests-first.md'
+---
+
+# Step 1: Initialize PR Review
+
+## STEP GOAL
+
+Set up the PR review session: identify the target PR, set the output path for the review report, understand context, and check for an existing report to resume.
+
+## EXECUTION
+
+### 1. Ask the User
+
+Ask the user:
+- **Which PR to review?** (PR URL, branch name, or diff)
+- **Output path** for the review report (suggest a default: `./pr-review-report-{{date}}.md`)
+- **Or provide path to an existing report** to resume a previous review
+
+### 2. Check for Existing Report
+
+If the user provides a path to an existing report file:
+- Read the file
+- Parse the YAML frontmatter
+- If `stepsCompleted` is non-empty → **STOP and load `step-01b-continue.md`**
+
+### 3. Fresh Workflow Setup
+
+If starting fresh:
+1. Copy the template from `templates/report-template.md`
+2. Fill in the frontmatter:
+   - `targetPR`: the PR identifier provided by the user
+   - `outputPath`: the chosen output path
+   - `date`: current date
+3. Write the initialized report to the output path
+
+### 4. Understand the Context
+
+**Goal**: Know what the PR is trying to accomplish.
+
+- Read the PR title and description
+- Read the linked ticket/issue
+- Understand the acceptance criteria
+- Check the scope (how big is this change?)
+
+**Questions to answer**:
+- What problem does this solve?
+- Is this a feature, bug fix, or refactor?
+- What should I focus on?
+
+**Time estimate**:
+```
+Small PR (< 100 lines): 15-30 min
+Medium PR (100-400 lines): 30-60 min
+Large PR (> 400 lines): Consider requesting split
+```
+
+### 5. Append Context to Report
+
+Append to the output document:
+
+```markdown
+## Step 1: Context
+
+**PR**: {{targetPR}}
+**Type**: {{feature/bugfix/refactor}}
+**Scope**: {{prSize}} ({{line count}} lines)
+**Purpose**: {{purpose}}
+**Focus Areas**: {{what to focus on}}
+```
+
+Update frontmatter:
+- Set `prSize` to the estimated size
+
+## FRONTMATTER UPDATE
+
+Update the output document frontmatter:
+- Add `1` to `stepsCompleted`
+
+## PRESENT TO USER
+
+Show the user:
+- PR context summary
+- Estimated review time
+- Confirmation of output path
+
+Then ask: **[C] Continue to Step 2: Review Tests First**
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-02-tests-first.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01b-continue.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01b-continue.md
new file mode 100644
index 0000000..17f3753
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-01b-continue.md
@@ -0,0 +1,72 @@
+---
+name: 'step-01b-continue'
+description: 'Resume PR review from last completed step'
+---
+
+# Step 1b: Continue Previous PR Review
+
+## STEP GOAL
+
+Resume a previously started PR review by reading the existing report, determining progress, and routing to the next incomplete step.
+
+## EXECUTION
+
+### 1. Read Existing Report
+
+- Read the file at the output path provided by the user
+- Parse the YAML frontmatter
+- Extract `stepsCompleted` array
+
+### 2. Show Progress Summary
+
+Display to the user:
+
+```
+PR Review Progress
+==================
+PR: {{targetPR}}
+Date Started: {{date}}
+Size: {{prSize}}
+Steps Completed: {{stepsCompleted}}
+
+Step Map:
+  [1] Context & Setup             {{done/pending}}
+  [2] Tests First                  {{done/pending}}
+  [3] High-Level Review            {{done/pending}}
+  [4] Code Details                 {{done/pending}}
+  [5] Security                     {{done/pending}}
+  [6] Performance                  {{done/pending}}
+  [7] Run Code                     {{done/pending}}
+  [8] Feedback                     {{done/pending}}
+  [9] Decision                     {{done/pending}}
+```
+
+### 3. Offer Options
+
+Present:
+- **[R] Resume** from the next incomplete step
+- **[O] Overview** — re-read the existing report content before resuming
+- **[X] Start over** — create a fresh report (confirm: this will overwrite)
+
+### 4. Route to Next Step
+
+On **[R]** or after **[O]**:
+
+Determine the next step from `max(stepsCompleted) + 1` and load the corresponding file:
+
+| Next Step | File |
+|-----------|------|
+| 2 | `step-02-tests-first.md` |
+| 3 | `step-03-high-level.md` |
+| 4 | `step-04-code-details.md` |
+| 5 | `step-05-security.md` |
+| 6 | `step-06-performance.md` |
+| 7 | `step-07-run-code.md` |
+| 8 | `step-08-feedback.md` |
+| 9 | `step-09-decision.md` |
+
+On **[X]**: Go back to `step-01-init.md` fresh workflow setup (section 3).
+
+## NEXT STEP
+
+Load the step file determined above.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-02-tests-first.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-02-tests-first.md
new file mode 100644
index 0000000..268cddf
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-02-tests-first.md
@@ -0,0 +1,75 @@
+---
+name: 'step-02-tests-first'
+description: 'Review tests first — coverage, meaningfulness, edge cases'
+nextStepFile: './step-03-high-level.md'
+referenceFiles:
+  - 'references/unit-tests/rules.md'
+  - 'references/tdd/rules.md'
+---
+
+# Step 2: Review the Tests First
+
+## STEP GOAL
+
+Understand what the code should do by reading the tests first. Verify test coverage, meaningfulness, and edge case handling.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/unit-tests/rules.md` — test quality rules
+- `references/tdd/rules.md` — TDD rules
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+1. **Check test coverage** for new/changed code
+2. **Read test names** to understand expected behavior
+3. **Verify tests are meaningful** (not just coverage padding)
+4. **Look for missing test cases**
+
+### Questions to Answer
+
+- Do tests cover the acceptance criteria?
+- Are edge cases tested?
+- Are error cases handled?
+- Would the tests catch regressions?
+
+### Red Flags
+
+Watch for and report:
+- No tests for new functionality
+- Tests that don't actually assert anything
+- Tests that test implementation, not behavior
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 2: Tests First
+===================
+
+Test Coverage:
+  - New code covered: YES/NO/PARTIAL
+  - Edge cases: covered/missing: [list]
+  - Error cases: covered/missing: [list]
+
+[PASS/ISSUE] test_name (file:line)
+  - Problem: description
+  Rule: unit-tests/rules.md — Rule N
+
+Summary: N tests reviewed, N issues found, N missing test cases
+```
+
+Then ask: **[C] Continue to Step 3: High-Level Review**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `2` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-03-high-level.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-03-high-level.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-03-high-level.md
new file mode 100644
index 0000000..2e80c7f
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-03-high-level.md
@@ -0,0 +1,66 @@
+---
+name: 'step-03-high-level'
+description: 'High-level code review — architecture, approach, structure'
+nextStepFile: './step-04-code-details.md'
+---
+
+# Step 3: Review the Code - High Level
+
+## STEP GOAL
+
+Understand the overall approach, architecture decisions, and whether the solution fits the problem.
+
+## ANALYSIS PROCESS
+
+1. **Look at the file structure** changes
+2. **Understand the architecture** decisions
+3. **Check if the approach** makes sense
+4. **Identify any major concerns**
+
+### Questions to Answer
+
+- Does the solution fit the problem?
+- Is the architecture appropriate?
+- Are there simpler alternatives?
+
+### What to Look At
+
+- New files created
+- Files with significant changes
+- Changes to shared/core code
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 3: High-Level Review
+=========================
+
+File Structure:
+  - New files: [list]
+  - Modified files: [list]
+  - Deleted files: [list]
+
+Architecture Assessment:
+  - Approach: [description]
+  - Fits problem: YES/PARTIALLY/NO — reason
+  - Simpler alternative: [if applicable]
+
+Concerns:
+  - [list or "None"]
+
+Summary: [overall structural assessment]
+```
+
+Then ask: **[C] Continue to Step 4: Code Details**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `3` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-04-code-details.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-04-code-details.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-04-code-details.md
new file mode 100644
index 0000000..cf6eea5
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-04-code-details.md
@@ -0,0 +1,94 @@
+---
+name: 'step-04-code-details'
+description: 'Detailed code review — functions, naming, error handling, comments, smells'
+nextStepFile: './step-05-security.md'
+referenceFiles:
+  - 'references/functions/rules.md'
+  - 'references/naming/rules.md'
+  - 'references/error-handling/rules.md'
+  - 'references/comments/rules.md'
+  - 'references/smells/rules.md'
+---
+
+# Step 4: Review the Code - Details
+
+## STEP GOAL
+
+Check code quality line by line across all changed files, applying the full code review checklist.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/functions/rules.md` — function design rules
+- `references/naming/rules.md` — naming conventions
+- `references/error-handling/rules.md` — error handling rules
+- `references/comments/rules.md` — comment rules
+- `references/smells/rules.md` — code smell catalog
+
+Cite specific rules when reporting findings.
+
+## ANALYSIS PROCESS
+
+For each changed file, check:
+
+### Functions
+- Small (5-20 lines)
+- Do one thing
+- Good names
+- Few arguments
+
+### Naming
+- Intention-revealing
+- Consistent terminology
+- No abbreviations
+
+### Error Handling
+- Exceptions used properly
+- No null returns
+- Proper error context
+
+### Comments
+- Only necessary comments
+- No commented-out code
+- Comments are accurate
+
+### Smells
+- No duplication
+- No feature envy
+- No god classes
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 4: Code Details
+====================
+
+File: {{filename}}
+  [PASS/ISSUE] (line N) category: description
+    Rule: {{category}}/rules.md — Rule N
+    Suggestion: fix
+
+File: {{filename}}
+  ...
+
+Summary: N files reviewed, N issues found
+  - Functions: N issues
+  - Naming: N issues
+  - Error Handling: N issues
+  - Comments: N issues
+  - Smells: N issues
+```
+
+Then ask: **[C] Continue to Step 5: Security**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `4` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-05-security.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-05-security.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-05-security.md
new file mode 100644
index 0000000..d8ed817
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-05-security.md
@@ -0,0 +1,65 @@
+---
+name: 'step-05-security'
+description: 'Check for security vulnerabilities — injection, XSS, auth, secrets'
+nextStepFile: './step-06-performance.md'
+---
+
+# Step 5: Check for Security Issues
+
+## STEP GOAL
+
+Identify potential security vulnerabilities in the PR changes.
+
+## ANALYSIS PROCESS
+
+Check all changed code for:
+
+1. **Input validation** present?
+2. **SQL injection** possible?
+3. **XSS vulnerabilities**?
+4. **Sensitive data** exposed?
+5. **Authentication/authorization** checked?
+6. **Secrets in code**?
+
+### Common Issues
+
+```typescript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD: Parameterized query
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
+```
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 5: Security
+================
+
+[PASS/ISSUE] vulnerability_type (file:line)
+  - Risk: HIGH/MEDIUM/LOW
+  - Description: what the vulnerability is
+  - Attack vector: how it could be exploited
+  - Fix: how to remediate
+
+Summary: N security issues found
+  - HIGH: N
+  - MEDIUM: N
+  - LOW: N
+```
+
+Then ask: **[C] Continue to Step 6: Performance**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `5` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-06-performance.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-06-performance.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-06-performance.md
new file mode 100644
index 0000000..3df70ff
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-06-performance.md
@@ -0,0 +1,61 @@
+---
+name: 'step-06-performance'
+description: 'Check for performance issues — N+1, memory, blocking'
+nextStepFile: './step-07-run-code.md'
+---
+
+# Step 6: Check for Performance Issues
+
+## STEP GOAL
+
+Identify obvious performance problems in the PR changes.
+
+## ANALYSIS PROCESS
+
+Check all changed code for:
+
+1. **N+1 query problems**?
+2. **Large data sets in memory**?
+3. **Unnecessary database calls**?
+4. **Missing indexes for queries**?
+5. **Blocking operations in async code**?
+
+### Common Issues
+
+```typescript
+// BAD: N+1 query
+for (const user of users) {
+  const orders = await db.getOrdersForUser(user.id);
+}
+
+// GOOD: Single query
+const orders = await db.getOrdersForUsers(userIds);
+```
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 6: Performance
+===================
+
+[PASS/ISSUE] issue_type (file:line)
+  - Impact: HIGH/MEDIUM/LOW
+  - Description: what the performance issue is
+  - Suggestion: how to optimize
+
+Summary: N performance issues found
+```
+
+Then ask: **[C] Continue to Step 7: Run Code**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `6` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-07-run-code.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-07-run-code.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-07-run-code.md
new file mode 100644
index 0000000..f2461f9
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-07-run-code.md
@@ -0,0 +1,70 @@
+---
+name: 'step-07-run-code'
+description: 'Run the code if needed — tests, manual verification'
+nextStepFile: './step-08-feedback.md'
+---
+
+# Step 7: Run the Code (if needed)
+
+## STEP GOAL
+
+Verify the code actually works by running tests and optionally testing manually.
+
+## EXECUTION
+
+### 1. Determine if Running is Needed
+
+Running locally is recommended for:
+- Complex logic changes
+- UI changes
+- Integration changes
+- When you're unsure about correctness
+
+### 2. Run Tests
+
+If applicable:
+- Pull the branch locally
+- Run the test suite
+- Note any failures
+
+### 3. Manual Testing
+
+If applicable:
+- Test the happy path
+- Test edge cases
+- Verify the fix/feature works as described
+
+### 4. Record Results
+
+## PRESENT FINDINGS
+
+Present findings to the user in this format:
+
+```
+Step 7: Run Code
+================
+
+Tests:
+  - Ran: YES/NO/SKIPPED
+  - Result: ALL PASS / N FAILURES
+  - Failures: [list if any]
+
+Manual Testing:
+  - Performed: YES/NO/SKIPPED
+  - Result: WORKS / ISSUES FOUND
+  - Issues: [list if any]
+
+Recommendation: [proceed / investigate failures]
+```
+
+Then ask: **[C] Continue to Step 8: Feedback**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `7` to `stepsCompleted`
+- Append the findings section to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-08-feedback.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-08-feedback.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-08-feedback.md
new file mode 100644
index 0000000..43e9fdc
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-08-feedback.md
@@ -0,0 +1,94 @@
+---
+name: 'step-08-feedback'
+description: 'Compile feedback — categorize, format, prepare for decision'
+nextStepFile: './step-09-decision.md'
+referenceFiles:
+  - 'references/collaboration/rules.md'
+---
+
+# Step 8: Provide Feedback
+
+## STEP GOAL
+
+Compile all findings from steps 2-7 into categorized, constructive, actionable feedback.
+
+## REFERENCE LOADING
+
+Before compiling feedback, load and read:
+- `references/collaboration/rules.md` — feedback and communication rules
+
+## COMPILATION PROCESS
+
+### 1. Gather All Findings
+
+Read through the output document and collect all issues found in steps 2-7.
+
+### 2. Categorize Feedback
+
+Use these categories:
+
+| Prefix | Meaning | Action Required |
+|--------|---------|-----------------|
+| `[BLOCKING]` | Must fix before merge | Yes |
+| `[SUGGESTION]` | Nice to have | No |
+| `[QUESTION]` | Need clarification | Depends |
+| `[NIT]` | Minor style issue | No |
+| `[PRAISE]` | Something good | No |
+
+### 3. Format Each Item
+
+```
+[BLOCKING] src/services/userExporter.ts:45
+
+This function is doing too many things. It validates, fetches, formats,
+and saves in one place.
+
+Reference: functions/rules.md - "Do One Thing"
+
+Suggestion: Extract into separate functions:
+- validateExportRequest()
+- fetchUser()
+- formatUser()
+- saveExport()
+```
+
+### 4. Include Praise
+
+Don't forget to call out what's done well — clean patterns, good test coverage, clever solutions.
+
+## PRESENT FINDINGS
+
+Present the categorized feedback to the user:
+
+```
+Step 8: Feedback Summary
+========================
+
+[BLOCKING] (N items)
+  1. ...
+  2. ...
+
+[SUGGESTION] (N items)
+  1. ...
+
+[QUESTION] (N items)
+  1. ...
+
+[NIT] (N items)
+  1. ...
+
+[PRAISE] (N items)
+  1. ...
+```
+
+Then ask: **[C] Continue to Step 9: Decision**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `8` to `stepsCompleted`
+- Append the categorized feedback to the report
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-09-decision.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-09-decision.md b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-09-decision.md
new file mode 100644
index 0000000..949e5bc
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/steps/step-09-decision.md
@@ -0,0 +1,96 @@
+---
+name: 'step-09-decision'
+description: 'Make the final PR decision — approve, request changes, or comment'
+---
+
+# Step 9: Make the Decision
+
+## STEP GOAL
+
+Make the final review decision: approve, request changes, or comment. Complete the review report.
+
+## DECISION CRITERIA
+
+### Approve when:
+- All blocking issues resolved
+- Tests are adequate
+- Code quality is acceptable
+- You'd be comfortable maintaining this code
+
+### Request Changes when:
+- Blocking issues exist
+- Tests are missing for critical paths
+- Security vulnerabilities found
+- Major design problems
+
+### Comment when:
+- You have questions but no blockers
+- You want to discuss approaches
+- You're not the final approver
+
+## COMPILATION
+
+### 1. Write Final Decision
+
+Append to the output document:
+
+```markdown
+## Final Decision
+
+### PR Review Checklist
+
+Context:
+- [ ] PR description read
+- [ ] Ticket/issue understood
+- [ ] Scope is appropriate
+
+Tests:
+- [ ] New code has tests
+- [ ] Tests are meaningful
+- [ ] Edge cases covered
+
+Code Quality:
+- [ ] Functions are small
+- [ ] Names are clear
+- [ ] No code smells
+- [ ] Error handling is proper
+
+Security:
+- [ ] No vulnerabilities
+- [ ] Input validated
+- [ ] No secrets in code
+
+Performance:
+- [ ] No obvious issues
+- [ ] No N+1 queries
+
+Feedback:
+- [ ] Constructive and specific
+- [ ] Clear blocking vs suggestions
+- [ ] Actionable recommendations
+
+### Decision: [APPROVE / REQUEST CHANGES / COMMENT]
+
+**Reason**: [summary]
+
+### Common Issues Found
+
+| Issue | Location | Category |
+|-------|----------|----------|
+| ... | file:line | BLOCKING/SUGGESTION/NIT |
+```
+
+## PRESENT TO USER
+
+Show the final decision and checklist to the user.
+
+## FRONTMATTER UPDATE
+
+Update the output document frontmatter:
+- Add `9` to `stepsCompleted`
+- Set `status` to `'complete'`
+- Set `decision` to the chosen decision
+
+## WORKFLOW COMPLETE
+
+The PR review workflow is complete. The full report is saved at the output path.
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/templates/report-template.md b/.agents/skills/typescript-clean-code/workflows/pr-review/templates/report-template.md
new file mode 100644
index 0000000..69a63e1
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/templates/report-template.md
@@ -0,0 +1,22 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'pr-review'
+targetPR: ''
+outputPath: ''
+date: ''
+status: 'in-progress'
+prSize: ''
+decision: ''
+---
+
+# PR Review Report
+
+**Date**: {{date}}
+**PR**: {{targetPR}}
+**Size**: {{prSize}}
+**Status**: {{status}}
+**Decision**: {{decision}}
+
+---
+
diff --git a/.agents/skills/typescript-clean-code/workflows/pr-review/workflow.md b/.agents/skills/typescript-clean-code/workflows/pr-review/workflow.md
new file mode 100644
index 0000000..341b0d1
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/pr-review/workflow.md
@@ -0,0 +1,57 @@
+---
+name: 'pr-review'
+description: 'Comprehensive process for reviewing pull requests'
+firstStepFile: './steps/step-01-init.md'
+templateFile: './templates/report-template.md'
+---
+
+# PR Review Workflow
+
+Comprehensive process for reviewing pull requests.
+
+## When to Use
+
+- Reviewing a teammate's PR
+- Doing a final check before merge
+- Conducting formal code review
+
+## Prerequisites
+
+- Access to the PR and codebase
+- Understanding of the feature/fix context
+- Time to do a thorough review
+
+## Step-File Architecture
+
+This workflow uses a **step-file architecture** for context-safe execution:
+
+- Each step is a separate file loaded sequentially
+- Progress is tracked via `stepsCompleted` in the output document's YAML frontmatter
+- If context is compacted mid-workflow, step-01 detects existing output and resumes from the last completed step via step-01b
+
+### Steps
+
+| Step | File | Description |
+|------|------|-------------|
+| 1 | `step-01-init.md` | Initialize workflow, set output path, detect continuation |
+| 1b | `step-01b-continue.md` | Resume from last completed step |
+| 2 | `step-02-tests-first.md` | Review tests first |
+| 3 | `step-03-high-level.md` | Review code at high level |
+| 4 | `step-04-code-details.md` | Review code details |
+| 5 | `step-05-security.md` | Check for security issues |
+| 6 | `step-06-performance.md` | Check for performance issues |
+| 7 | `step-07-run-code.md` | Run code if needed |
+| 8 | `step-08-feedback.md` | Provide constructive feedback |
+| 9 | `step-09-decision.md` | Make approve/reject decision, mark complete |
+
+### Rules
+
+1. **Load one step at a time** - Read the step file, execute it, then load the next
+2. **Update frontmatter after each step** - Add the step number to `stepsCompleted`
+3. **Wait for user confirmation** - Present findings and wait for `[C]` before proceeding
+4. **Load reference files** - Each step specifies which reference files to load before analysis
+5. **Cite specific rules** - When reporting findings, cite the specific rule from the reference file
+
+## Begin
+
+Load `steps/step-01-init.md` to start.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01-init.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01-init.md
new file mode 100644
index 0000000..bcd4c98
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01-init.md
@@ -0,0 +1,86 @@
+---
+name: 'step-01-init'
+description: 'Initialize refactoring workflow — verify tests, set output path, detect continuation'
+nextStepFile: './step-02-identify-smell.md'
+---
+
+# Step 1: Initialize Refactoring
+
+## STEP GOAL
+
+Set up the refactoring session: identify the target code, verify tests pass, set the output path for the refactoring log, and check for an existing log to resume.
+
+## EXECUTION
+
+### 1. Ask the User
+
+Ask the user:
+- **What code to refactor?** (file path, module, or class)
+- **What's the improvement goal?** (what smell to fix, what to clean up)
+- **Output path** for the refactoring log (suggest a default: `./refactoring-log-{{date}}.md`)
+- **Or provide path to an existing log** to resume a previous session
+
+### 2. Check for Existing Log
+
+If the user provides a path to an existing log file:
+- Read the file
+- Parse the YAML frontmatter
+- If `stepsCompleted` is non-empty → **STOP and load `step-01b-continue.md`**
+
+### 3. Fresh Workflow Setup
+
+If starting fresh:
+1. Copy the template from `templates/log-template.md`
+2. Fill in the frontmatter:
+   - `targetCode`: the code path provided by the user
+   - `outputPath`: the chosen output path
+   - `date`: current date
+3. Write the initialized log to the output path
+
+### 4. Verify Tests Pass
+
+**Goal**: Establish a green baseline.
+
+```bash
+npm test  # All tests must pass
+```
+
+- All existing tests pass
+- Coverage is adequate for the code you'll change
+- You understand what the tests verify
+
+**If tests fail**: Fix them first. Don't refactor broken code.
+
+**If no tests exist**: Write characterization tests first. See `test-strategy.md` workflow.
+
+### 5. Append to Log
+
+Append to the output document:
+
+```markdown
+## Step 1: Initialization
+
+**Target**: {{targetCode}}
+**Goal**: {{improvement goal}}
+**Tests**: {{PASS / FAIL — details}}
+**Coverage**: {{adequate / needs improvement}}
+```
+
+## FRONTMATTER UPDATE
+
+Update the output document frontmatter:
+- Add `1` to `stepsCompleted`
+- Set `testsGreen` to `true` (if tests passed)
+
+## PRESENT TO USER
+
+Show the user:
+- Confirmation of the refactoring target and goal
+- Test results
+- Output path
+
+Then ask: **[C] Continue to Step 2: Identify the Smell**
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-02-identify-smell.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01b-continue.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01b-continue.md
new file mode 100644
index 0000000..d9b8db7
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-01b-continue.md
@@ -0,0 +1,77 @@
+---
+name: 'step-01b-continue'
+description: 'Resume refactoring from last completed step'
+---
+
+# Step 1b: Continue Previous Refactoring
+
+## STEP GOAL
+
+Resume a previously started refactoring session by reading the existing log, determining progress, and routing to the next incomplete step.
+
+## EXECUTION
+
+### 1. Read Existing Log
+
+- Read the file at the output path provided by the user
+- Parse the YAML frontmatter
+- Extract `stepsCompleted` array and `iterations` array
+
+### 2. Show Progress Summary
+
+Display to the user:
+
+```
+Refactoring Progress
+====================
+Target: {{targetCode}}
+Smell: {{smell}}
+Date Started: {{date}}
+Steps Completed: {{stepsCompleted}}
+Iterations: {{iterations.length}} change-test-commit cycles
+
+Step Map:
+  [1] Initialize & Verify Tests   {{done/pending}}
+  [2] Identify Smell               {{done/pending}}
+  [3] Plan Steps                   {{done/pending}}
+  [4] Make ONE Change              {{done/pending}}
+  [5] Run Tests                    {{done/pending}}
+  [6] Commit                       {{done/pending}}
+  [7] Repeat / Complete            {{done/pending}}
+
+Note: Steps 4-7 may repeat multiple times (loop).
+Last iteration: {{last iteration details if any}}
+```
+
+### 3. Offer Options
+
+Present:
+- **[R] Resume** from the next incomplete step
+- **[O] Overview** — re-read the existing log content before resuming
+- **[X] Start over** — create a fresh log (confirm: this will overwrite)
+
+### 4. Route to Next Step
+
+On **[R]** or after **[O]**:
+
+Determine the next step. For the refactoring workflow, steps 4-7 loop, so:
+
+- If `stepsCompleted` contains `7` (repeat step was reached and decided to loop):
+  - Check the last entry — if it says "loop back", load `step-04-make-change.md`
+  - If it says "complete", the workflow is done
+- Otherwise, determine from `max(stepsCompleted) + 1`:
+
+| Next Step | File |
+|-----------|------|
+| 2 | `step-02-identify-smell.md` |
+| 3 | `step-03-plan-steps.md` |
+| 4 | `step-04-make-change.md` |
+| 5 | `step-05-run-tests.md` |
+| 6 | `step-06-commit.md` |
+| 7 | `step-07-repeat.md` |
+
+On **[X]**: Go back to `step-01-init.md` fresh workflow setup (section 3).
+
+## NEXT STEP
+
+Load the step file determined above.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-02-identify-smell.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-02-identify-smell.md
new file mode 100644
index 0000000..25de185
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-02-identify-smell.md
@@ -0,0 +1,70 @@
+---
+name: 'step-02-identify-smell'
+description: 'Identify the specific code smell to fix'
+nextStepFile: './step-03-plan-steps.md'
+referenceFiles:
+  - 'references/smells/rules.md'
+---
+
+# Step 2: Identify the Smell
+
+## STEP GOAL
+
+Know exactly what you're fixing. Identify the specific code smell, understand why it's a problem, and define the target state.
+
+## REFERENCE LOADING
+
+Before starting analysis, load and read:
+- `references/smells/rules.md` — code smell catalog
+
+Cite specific smell codes when identifying the smell.
+
+## ANALYSIS PROCESS
+
+### 1. Scan for Smells
+
+Common smells to look for:
+
+| Smell | Symptom | Refactoring |
+|-------|---------|-------------|
+| G5: Duplication | Copy-pasted code | Extract Method/Class |
+| Long Function | > 20 lines | Extract Method |
+| Long Parameter List | > 3 params | Introduce Parameter Object |
+| Feature Envy | Uses other class's data | Move Method |
+| God Class | Too many responsibilities | Extract Class |
+| Primitive Obsession | Primitives instead of objects | Replace with Value Object |
+
+### 2. Confirm with User
+
+Present the identified smell and ask the user to confirm:
+- What the smell is
+- Why it's a problem
+- What the target state looks like
+
+## PRESENT FINDINGS
+
+```
+Step 2: Smell Identification
+============================
+
+Identified Smell: {{smell code}} — {{smell name}}
+Location: {{file:line}}
+Evidence: {{what makes this a smell}}
+Impact: {{why it's a problem}}
+Target State: {{what it should look like after refactoring}}
+
+Rule: smells/rules.md — {{smell code}}
+```
+
+Then ask: **[C] Continue to Step 3: Plan Steps**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `2` to `stepsCompleted`
+- Set `smell` to the identified smell name
+- Append the findings to the log
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-03-plan-steps.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-03-plan-steps.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-03-plan-steps.md
new file mode 100644
index 0000000..22d70ae
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-03-plan-steps.md
@@ -0,0 +1,71 @@
+---
+name: 'step-03-plan-steps'
+description: 'Plan small, safe refactoring steps'
+nextStepFile: './step-04-make-change.md'
+---
+
+# Step 3: Plan Small Steps
+
+## STEP GOAL
+
+Break the refactoring into tiny, safe changes. Each step should take < 5 minutes and keep tests green.
+
+## PLANNING PROCESS
+
+### 1. Break Down the Refactoring
+
+**Rule**: Each step should be:
+- Independently testable
+- Purely structural (no behavior change)
+- Describable in one sentence
+
+### 2. Example Breakdown
+
+For extracting a long function:
+```
+Step 1: Identify code block to extract
+Step 2: Create new function with extracted code
+Step 3: Replace original code with function call
+Step 4: Run tests
+Step 5: Rename function for clarity
+Step 6: Run tests
+Step 7: Move function if needed
+Step 8: Run tests
+```
+
+### 3. Common Refactoring Patterns
+
+**Extract Method**: Function is too long or does multiple things
+**Rename**: Name doesn't reveal intent
+**Introduce Parameter Object**: Too many parameters
+**Replace Conditional with Polymorphism**: Switch statements on type
+**Extract Class**: Class has multiple responsibilities
+
+## PRESENT PLAN
+
+```
+Step 3: Refactoring Plan
+========================
+
+Target Smell: {{smell}}
+Planned Steps:
+  1. {{step description}}
+  2. {{step description}}
+  3. {{step description}}
+  ...
+
+Each step: < 5 min, tests stay green, one change only.
+Estimated total: {{N}} micro-changes
+```
+
+Then ask: **[C] Continue to Step 4: Make ONE Change**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `3` to `stepsCompleted`
+- Append the plan to the log
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-04-make-change.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-04-make-change.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-04-make-change.md
new file mode 100644
index 0000000..97c2382
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-04-make-change.md
@@ -0,0 +1,97 @@
+---
+name: 'step-04-make-change'
+description: 'Make ONE structural change — no behavior change'
+nextStepFile: './step-05-run-tests.md'
+referenceFiles:
+  - 'references/functions/rules.md'
+  - 'references/classes/rules.md'
+---
+
+# Step 4: Make ONE Change
+
+## STEP GOAL
+
+Execute one small refactoring step. The change must be purely structural with no behavior change.
+
+## REFERENCE LOADING
+
+Before making changes, load the relevant reference files:
+- `references/functions/rules.md` — if refactoring functions
+- `references/classes/rules.md` — if refactoring classes
+
+Apply the rules to guide the structural change.
+
+## EXECUTION
+
+### Checklist
+
+- Make exactly ONE change
+- The change is purely structural (no behavior change)
+- You can describe the change in one sentence
+
+### Common Refactorings
+
+**Extract Method**:
+```typescript
+// Before
+function processOrder(order: Order) {
+  // validate
+  if (!order.items.length) throw new Error('Empty order');
+  if (!order.customer) throw new Error('No customer');
+
+  // calculate
+  const subtotal = order.items.reduce((sum, i) => sum + i.price, 0);
+  const tax = subtotal * 0.1;
+  const total = subtotal + tax;
+
+  // save
+  db.save({ ...order, total });
+}
+
+// After (one extraction)
+function processOrder(order: Order) {
+  validateOrder(order);  // Extracted
+
+  const subtotal = order.items.reduce((sum, i) => sum + i.price, 0);
+  const tax = subtotal * 0.1;
+  const total = subtotal + tax;
+
+  db.save({ ...order, total });
+}
+
+function validateOrder(order: Order) {
+  if (!order.items.length) throw new Error('Empty order');
+  if (!order.customer) throw new Error('No customer');
+}
+```
+
+**Rename**: Change a name to better reveal intent
+**Introduce Parameter Object**: Group related parameters
+**Move Method**: Move to the class that uses the data
+**Extract Class**: Split responsibilities
+
+## PRESENT CHANGE
+
+```
+Step 4: Change Made
+===================
+
+Iteration: {{N}}
+Change: {{one-sentence description}}
+Type: {{Extract Method / Rename / etc.}}
+File: {{file:line}}
+Before: {{brief summary}}
+After: {{brief summary}}
+```
+
+Then ask: **[C] Continue to Step 5: Run Tests**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `4` to `stepsCompleted` (or update if looping)
+- Append the change description to the log
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-05-run-tests.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-05-run-tests.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-05-run-tests.md
new file mode 100644
index 0000000..8d8c74d
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-05-run-tests.md
@@ -0,0 +1,65 @@
+---
+name: 'step-05-run-tests'
+description: 'Verify tests still pass after the change'
+nextStepFile: './step-06-commit.md'
+---
+
+# Step 5: Run Tests
+
+## STEP GOAL
+
+Verify the change didn't break anything. All tests must still pass.
+
+## EXECUTION
+
+```bash
+npm test
+```
+
+### Check
+
+- All tests pass
+- No new failures
+- Coverage hasn't dropped
+
+### If Tests Fail
+
+1. **STOP**
+2. Undo the change (`git checkout`)
+3. Make a smaller change
+4. Or fix the issue if it's obvious
+
+**Important**: Do NOT proceed with failing tests. The safety net must stay intact.
+
+## PRESENT RESULTS
+
+```
+Step 5: Test Results
+====================
+
+Iteration: {{N}}
+Result: PASS / FAIL
+Tests Run: {{N}}
+Tests Passed: {{N}}
+Tests Failed: {{N}} — [list if any]
+Coverage: {{percentage}} (change: +/-N%)
+
+Action: {{proceed / undo and retry}}
+```
+
+If PASS, ask: **[C] Continue to Step 6: Commit**
+
+If FAIL, inform the user and undo the change. Return to `step-04-make-change.md` for a smaller change.
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `5` to `stepsCompleted` (or update if looping)
+- Set `testsGreen` to `true` or `false`
+- Append test results to the log
+
+## NEXT STEP
+
+If tests pass and user confirms `[C]`, load `step-06-commit.md`.
+
+If tests fail, load `step-04-make-change.md` after undoing the change.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-06-commit.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-06-commit.md
new file mode 100644
index 0000000..382eff6
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-06-commit.md
@@ -0,0 +1,50 @@
+---
+name: 'step-06-commit'
+description: 'Commit the successful change'
+nextStepFile: './step-07-repeat.md'
+---
+
+# Step 6: Commit
+
+## STEP GOAL
+
+Save progress by committing the successful refactoring step. Each green test should be committed.
+
+## EXECUTION
+
+### Commit the Change
+
+```bash
+git add -A
+git commit -m "refactor: {{one-sentence description of the change}}"
+```
+
+### Checklist
+
+- Commit after each successful step
+- Commit message describes the refactoring
+- You can revert to this point if needed
+
+## PRESENT RESULT
+
+```
+Step 6: Commit
+==============
+
+Iteration: {{N}}
+Committed: YES
+Message: "refactor: {{description}}"
+SHA: {{commit hash}}
+```
+
+Then ask: **[C] Continue to Step 7: Check if Done**
+
+## FRONTMATTER UPDATE
+
+Update the output document:
+- Add `6` to `stepsCompleted` (or update if looping)
+- Append commit details to the log
+
+## NEXT STEP
+
+After user confirms `[C]`, load `step-07-repeat.md`.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-07-repeat.md b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-07-repeat.md
new file mode 100644
index 0000000..ee9f0ef
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/steps/step-07-repeat.md
@@ -0,0 +1,91 @@
+---
+name: 'step-07-repeat'
+description: 'Check if smell is eliminated — loop back to step-04 or mark complete'
+---
+
+# Step 7: Repeat or Complete
+
+## STEP GOAL
+
+Determine if the smell is eliminated. If not, loop back to make another change. If done, mark the workflow as complete.
+
+## EVALUATION
+
+### Check Completion
+
+Ask:
+- Is the identified smell gone?
+- Does the code meet clean code standards?
+- Are there obvious improvements remaining?
+
+### The Refactoring Cycle
+
+```
+Change → Test → Commit → Change → Test → Commit → ...
+```
+
+Continue until:
+- The smell is gone
+- Code meets clean code standards
+- No obvious improvements remain
+
+## DECISION
+
+### If NOT Done (smell remains)
+
+Present to user:
+
+```
+Step 7: Repeat
+==============
+
+Iteration {{N}} complete.
+Smell status: STILL PRESENT / PARTIALLY FIXED
+Remaining: {{what's left to do}}
+
+Looping back to Step 4 for next change.
+```
+
+**Action**: Update `iterations` in frontmatter, then load `step-04-make-change.md`.
+
+### If Done (smell eliminated)
+
+Present to user:
+
+```
+Step 7: Complete
+================
+
+Refactoring complete after {{N}} iterations.
+
+Summary:
+  - Target: {{targetCode}}
+  - Smell: {{smell}} — ELIMINATED
+  - Changes made: {{N}}
+  - All tests: PASSING
+  - Commits: {{N}}
+
+Safety Checklist:
+  - [x] Tests exist and pass
+  - [x] One change at a time
+  - [x] Test after every change
+  - [x] Commit after every green test
+  - [x] No behavior changes
+```
+
+## FRONTMATTER UPDATE
+
+### If looping:
+- Add current iteration number to `iterations` array
+- Reset `stepsCompleted` to remove 4, 5, 6, 7 (they'll be re-added in the next loop)
+- Keep 1, 2, 3 in `stepsCompleted`
+
+### If complete:
+- Add `7` to `stepsCompleted`
+- Set `status` to `'complete'`
+
+## NEXT STEP
+
+If **looping**: Load `step-04-make-change.md`.
+
+If **complete**: Workflow is finished. The full refactoring log is saved at the output path.
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/templates/log-template.md b/.agents/skills/typescript-clean-code/workflows/refactoring/templates/log-template.md
new file mode 100644
index 0000000..4c4ba23
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/templates/log-template.md
@@ -0,0 +1,22 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'refactoring'
+targetCode: ''
+outputPath: ''
+date: ''
+status: 'in-progress'
+smell: ''
+iterations: []
+testsGreen: false
+---
+
+# Refactoring Log
+
+**Date**: {{date}}
+**Target**: {{targetCode}}
+**Smell**: {{smell}}
+**Status**: {{status}}
+
+---
+
diff --git a/.agents/skills/typescript-clean-code/workflows/refactoring/workflow.md b/.agents/skills/typescript-clean-code/workflows/refactoring/workflow.md
new file mode 100644
index 0000000..060c41c
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/refactoring/workflow.md
@@ -0,0 +1,63 @@
+---
+name: 'refactoring'
+description: 'Safe refactoring process with tests as a safety net'
+firstStepFile: './steps/step-01-init.md'
+templateFile: './templates/log-template.md'
+---
+
+# Refactoring Workflow
+
+Safe refactoring process with tests as a safety net.
+
+## When to Use
+
+- Improving code quality without changing behavior
+- Before adding new features to messy code
+- After getting tests passing (the REFACTOR phase of TDD)
+- When you encounter code smells
+
+## Prerequisites
+
+- **Tests exist and pass** - This is non-negotiable
+- Understand what the code does
+- Have a specific improvement goal
+
+## The Golden Rule
+
+> **Never refactor without tests. Never.**
+
+If tests don't exist, write them first. See `test-strategy.md` workflow.
+
+## Step-File Architecture
+
+This workflow uses a **step-file architecture** for context-safe execution:
+
+- Each step is a separate file loaded sequentially
+- Progress is tracked via `stepsCompleted` in the output document's YAML frontmatter
+- If context is compacted mid-workflow, step-01 detects existing output and resumes from the last completed step via step-01b
+- Steps 4-7 form a **loop**: make change, run tests, commit, repeat until smell is eliminated
+
+### Steps
+
+| Step | File | Description |
+|------|------|-------------|
+| 1 | `step-01-init.md` | Initialize workflow, verify tests, detect continuation |
+| 1b | `step-01b-continue.md` | Resume from last completed step |
+| 2 | `step-02-identify-smell.md` | Identify the specific code smell |
+| 3 | `step-03-plan-steps.md` | Plan small, safe refactoring steps |
+| 4 | `step-04-make-change.md` | Make ONE structural change |
+| 5 | `step-05-run-tests.md` | Verify tests still pass |
+| 6 | `step-06-commit.md` | Commit the change |
+| 7 | `step-07-repeat.md` | Check if done; loop to step-04 or mark complete |
+
+### Rules
+
+1. **Load one step at a time** - Read the step file, execute it, then load the next
+2. **Update frontmatter after each step** - Add the step number to `stepsCompleted`
+3. **Wait for user confirmation** - Present findings and wait for `[C]` before proceeding
+4. **One change at a time** - Never make multiple structural changes in one step
+5. **Tests must stay green** - If tests fail after a change, undo immediately
+
+## Begin
+
+Load `steps/step-01-init.md` to start.
diff --git a/.agents/skills/typescript-clean-code/workflows/tdd.md b/.agents/skills/typescript-clean-code/workflows/tdd.md
new file mode 100644
index 0000000..b912e37
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/tdd.md
@@ -0,0 +1,222 @@
+# TDD Workflow
+
+Red-Green-Refactor cycle for test-driven development.
+
+## When to Use
+
+- Writing new functionality
+- Adding features to existing code
+- Fixing bugs (write failing test first)
+
+## Prerequisites
+
+- Test framework set up (Jest, Vitest, etc.)
+- Understanding of the feature to implement
+
+**Reference**: `tdd/rules.md`, `tdd/examples.md`
+
+---
+
+## The Three Laws of TDD
+
+1. **Write no production code** until you have a failing test
+2. **Write only enough test** to demonstrate a failure
+3. **Write only enough production code** to pass the test
+
+**Cycle time**: ~30 seconds per iteration
+
+---
+
+## Workflow Steps
+
+### Step 1: Think
+
+**Goal**: Understand what you're building before writing any code.
+
+- [ ] What is the next smallest piece of functionality?
+- [ ] What behavior should it have?
+- [ ] What is the simplest test that would force this behavior?
+
+**Ask**: "What's the smallest step I can take?"
+
+---
+
+### Step 2: RED - Write a Failing Test
+
+**Goal**: Write a test that fails for the right reason.
+
+```typescript
+// Example: Building a Stack
+describe('Stack', () => {
+  it('should be empty when created', () => {
+    const stack = new Stack();
+    expect(stack.isEmpty()).toBe(true);
+  });
+});
+```
+
+**Checklist**:
+- [ ] Test is small and focused on ONE behavior
+- [ ] Test name describes the expected behavior
+- [ ] Test follows Arrange-Act-Assert pattern
+- [ ] Run the test - it MUST fail
+- [ ] Failure is for the right reason (not syntax error)
+
+**Common Mistakes**:
+- Writing too much test at once
+- Test passes immediately (you wrote too much production code)
+- Test fails for wrong reason (compilation error, not assertion)
+
+---
+
+### Step 3: GREEN - Make It Pass
+
+**Goal**: Write the minimum code to make the test pass.
+
+```typescript
+// Minimum code to pass
+class Stack {
+  isEmpty(): boolean {
+    return true;  // Simplest thing that works
+  }
+}
+```
+
+**Checklist**:
+- [ ] Write the simplest code that passes
+- [ ] Don't write code for future tests
+- [ ] Don't refactor yet
+- [ ] Run the test - it MUST pass
+- [ ] All previous tests still pass
+
+**Common Mistakes**:
+- Writing more code than needed
+- Generalizing before you have multiple examples
+- Refactoring during this phase
+
+---
+
+### Step 4: REFACTOR - Clean Up
+
+**Goal**: Improve code quality while keeping tests green.
+
+**Checklist**:
+- [ ] Remove duplication
+- [ ] Improve names
+- [ ] Extract methods if needed
+- [ ] Improve readability
+- [ ] Run tests after EVERY change
+- [ ] All tests still pass
+
+**Reference**: `refactoring.md` workflow
+
+**Common Mistakes**:
+- Refactoring without running tests
+- Adding new functionality (that's Step 2)
+- Skipping this step
+
+---
+
+### Step 5: Repeat
+
+**Goal**: Continue the cycle until feature is complete.
+
+```
+Think → RED → GREEN → REFACTOR → Think → RED → GREEN → REFACTOR → ...
+```
+
+**Next Iteration Example**:
+```typescript
+// Next test
+it('should not be empty after push', () => {
+  const stack = new Stack();
+  stack.push(1);
+  expect(stack.isEmpty()).toBe(false);
+});
+
+// Make it pass
+class Stack {
+  private items: number[] = [];
+  
+  isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+  
+  push(item: number): void {
+    this.items.push(item);
+  }
+}
+```
+
+---
+
+## TDD Cycle Timing
+
+| Phase | Time | Activity |
+|-------|------|----------|
+| RED | ~1 min | Write failing test |
+| GREEN | ~2 min | Make it pass |
+| REFACTOR | ~2 min | Clean up |
+| **Total** | ~5 min | One cycle |
+
+If a cycle takes longer than 10 minutes, you're taking too big a step.
+
+---
+
+## Test Progression Strategy
+
+Build up complexity gradually:
+
+1. **Degenerate cases**: Empty, null, zero
+2. **Single item**: One element scenarios
+3. **Multiple items**: Normal operation
+4. **Edge cases**: Boundaries, errors
+5. **Error cases**: Invalid inputs, exceptions
+
+**Example for Stack**:
+```
+1. isEmpty() returns true for new stack
+2. isEmpty() returns false after push
+3. pop() returns pushed item
+4. pop() returns items in LIFO order
+5. pop() on empty stack throws
+```
+
+---
+
+## Quick Reference
+
+```
+┌─────────────────────────────────────────────────┐
+│                  TDD CYCLE                       │
+│                                                  │
+│    ┌───────┐                                    │
+│    │ THINK │ ← What's the smallest step?        │
+│    └───┬───┘                                    │
+│        ▼                                        │
+│    ┌───────┐                                    │
+│    │  RED  │ ← Write failing test               │
+│    └───┬───┘                                    │
+│        ▼                                        │
+│    ┌───────┐                                    │
+│    │ GREEN │ ← Minimum code to pass             │
+│    └───┬───┘                                    │
+│        ▼                                        │
+│    ┌──────────┐                                 │
+│    │ REFACTOR │ ← Clean up, tests stay green    │
+│    └────┬─────┘                                 │
+│         │                                       │
+│         └──────────► Repeat                     │
+│                                                  │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Exit Criteria
+
+Feature is complete when:
+- [ ] All acceptance criteria have tests
+- [ ] All tests pass
+- [ ] Code is clean (no obvious refactoring needed)
+- [ ] You can't think of any more tests that would fail
diff --git a/.agents/skills/typescript-clean-code/workflows/test-strategy.md b/.agents/skills/typescript-clean-code/workflows/test-strategy.md
new file mode 100644
index 0000000..930584b
--- /dev/null
+++ b/.agents/skills/typescript-clean-code/workflows/test-strategy.md
@@ -0,0 +1,339 @@
+# Test Strategy Workflow
+
+Planning test coverage for a feature or system.
+
+## When to Use
+
+- Starting a new project/feature
+- Adding tests to legacy code
+- Reviewing test coverage gaps
+- Planning QA strategy
+
+## Prerequisites
+
+- Understanding of the feature/system
+- Knowledge of available testing tools
+- Access to requirements/acceptance criteria
+
+**Reference**: `testing-strategies/rules.md`, `unit-tests/rules.md`, `acceptance-testing/rules.md`
+
+---
+
+## The Test Pyramid
+
+```
+        /\
+       /  \        Manual Exploratory (~5%)
+      /----\       System/E2E Tests (~10%)
+     /      \      Integration Tests (~20%)
+    /--------\     Component Tests (~25%)
+   /          \    Unit Tests (~40%)
+  /______________\
+```
+
+**Principle**: More tests at the bottom, fewer at the top.
+
+---
+
+## Workflow Steps
+
+### Step 1: Understand What to Test
+
+**Goal**: Identify the scope and boundaries.
+
+- [ ] What is the feature/system?
+- [ ] What are the critical paths?
+- [ ] What are the edge cases?
+- [ ] What could go wrong?
+
+**Map the components**:
+```
+User Export Feature
+├── API Layer (Express routes)
+├── Service Layer (UserExporter)
+├── Data Layer (UserRepository)
+├── External (File storage)
+└── Formatters (JSON, CSV)
+```
+
+---
+
+### Step 2: Define Unit Test Coverage
+
+**Goal**: Test individual units in isolation.
+
+**Reference**: `unit-tests/rules.md`
+
+**What to unit test**:
+- Pure functions
+- Business logic
+- Data transformations
+- Validation rules
+- Edge cases
+
+**Coverage target**: ~90%+ of business logic
+
+**Example unit tests**:
+```typescript
+describe('JsonFormatter', () => {
+  it('should format user as JSON', () => {
+    const user = { name: 'Alice', email: 'alice@test.com' };
+    const result = formatter.format(user);
+    expect(JSON.parse(result)).toEqual(user);
+  });
+
+  it('should escape special characters', () => {
+    const user = { name: "O'Brien", email: 'test@test.com' };
+    const result = formatter.format(user);
+    expect(() => JSON.parse(result)).not.toThrow();
+  });
+
+  it('should handle empty fields', () => {
+    const user = { name: '', email: '' };
+    const result = formatter.format(user);
+    expect(result).toContain('""');
+  });
+});
+```
+
+**Checklist**:
+- [ ] All pure functions tested
+- [ ] All business rules tested
+- [ ] Edge cases covered
+- [ ] Error cases tested
+
+---
+
+### Step 3: Define Component Test Coverage
+
+**Goal**: Test components with mocked dependencies.
+
+**Reference**: `testing-strategies/rules.md`
+
+**What to component test**:
+- Service classes with mocked repos
+- API routes with mocked services
+- Happy paths and error paths
+
+**Coverage target**: ~50% of components
+
+**Example component test**:
+```typescript
+describe('UserExporter', () => {
+  let exporter: UserExporter;
+  let mockRepo: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockRepo = {
+      findById: jest.fn(),
+    };
+    exporter = new UserExporter(mockRepo);
+  });
+
+  it('should export user as JSON', async () => {
+    mockRepo.findById.mockResolvedValue({ 
+      id: '123', 
+      name: 'Alice',
+      email: 'alice@test.com' 
+    });
+
+    const result = await exporter.export('123', 'json');
+
+    expect(result.success).toBe(true);
+    expect(result.data).toContain('Alice');
+  });
+
+  it('should throw when user not found', async () => {
+    mockRepo.findById.mockResolvedValue(null);
+
+    await expect(exporter.export('999', 'json'))
+      .rejects.toThrow('User not found');
+  });
+});
+```
+
+**Checklist**:
+- [ ] Happy paths tested
+- [ ] Error handling tested
+- [ ] Dependencies properly mocked
+
+---
+
+### Step 4: Define Integration Test Coverage
+
+**Goal**: Test components working together.
+
+**What to integration test**:
+- Database interactions
+- External API calls
+- File system operations
+- Multiple services together
+
+**Coverage target**: Key integration points
+
+**Example integration test**:
+```typescript
+describe('UserExporter Integration', () => {
+  let db: TestDatabase;
+  let exporter: UserExporter;
+
+  beforeAll(async () => {
+    db = await TestDatabase.create();
+    const repo = new UserRepository(db);
+    exporter = new UserExporter(repo);
+  });
+
+  afterAll(async () => {
+    await db.destroy();
+  });
+
+  it('should export user from real database', async () => {
+    // Arrange
+    await db.insertUser({ id: '123', name: 'Alice', email: 'alice@test.com' });
+
+    // Act
+    const result = await exporter.export('123', 'json');
+
+    // Assert
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+**Checklist**:
+- [ ] Database operations tested
+- [ ] External integrations tested
+- [ ] Uses test database/sandbox
+
+---
+
+### Step 5: Define E2E/System Test Coverage
+
+**Goal**: Test the system as a whole.
+
+**What to E2E test**:
+- Critical user journeys
+- API contracts
+- Authentication flows
+- Key business workflows
+
+**Coverage target**: ~10% (critical paths only)
+
+**Example E2E test**:
+```typescript
+describe('User Export API', () => {
+  it('should export user via API', async () => {
+    // Create user via API
+    const createResponse = await request(app)
+      .post('/api/users')
+      .send({ name: 'Alice', email: 'alice@test.com' });
+    
+    const userId = createResponse.body.id;
+
+    // Export via API
+    const exportResponse = await request(app)
+      .get(`/api/users/${userId}/export?format=json`)
+      .expect(200);
+
+    expect(exportResponse.body.success).toBe(true);
+    expect(exportResponse.body.data).toContain('Alice');
+  });
+});
+```
+
+**Checklist**:
+- [ ] Critical paths covered
+- [ ] End-to-end flows work
+- [ ] API contracts verified
+
+---
+
+### Step 6: Plan Manual/Exploratory Testing
+
+**Goal**: Catch issues automation misses.
+
+**What to manually test**:
+- UI/UX flows
+- Edge cases not worth automating
+- Exploratory "what if" scenarios
+- Accessibility
+
+**Create test scenarios**:
+```
+Manual Test Scenarios:
+1. Export user with very long name (1000 chars)
+2. Export while database is slow
+3. Export from mobile browser
+4. Export with expired session
+5. Try to export another user's data
+```
+
+**Checklist**:
+- [ ] Exploratory scenarios documented
+- [ ] Not automatable cases listed
+- [ ] Security edge cases included
+
+---
+
+### Step 7: Document the Test Strategy
+
+**Goal**: Create a reference for the team.
+
+**Test Strategy Document**:
+```markdown
+# User Export - Test Strategy
+
+## Test Pyramid Distribution
+- Unit Tests: 15 tests (~40%)
+- Component Tests: 10 tests (~25%)  
+- Integration Tests: 5 tests (~20%)
+- E2E Tests: 3 tests (~10%)
+- Manual: 5 scenarios (~5%)
+
+## Coverage by Component
+| Component | Unit | Component | Integration | E2E |
+|-----------|------|-----------|-------------|-----|
+| JsonFormatter | 5 | - | - | - |
+| CsvFormatter | 5 | - | - | - |
+| UserExporter | 3 | 6 | 2 | - |
+| API Routes | 2 | 4 | 3 | 3 |
+
+## Critical Paths (must have E2E)
+1. Export user as JSON
+2. Export user as CSV
+3. Handle user not found
+
+## Test Data Strategy
+- Unit: Hardcoded fixtures
+- Component: Factory functions
+- Integration: Test database with seeding
+- E2E: Isolated test environment
+
+## Not Covered (accepted risk)
+- Performance under load (separate perf tests)
+- Export of 10M+ users (accepted limitation)
+```
+
+---
+
+## Test Type Quick Reference
+
+| Type | Speed | Isolation | Scope | When to Use |
+|------|-------|-----------|-------|-------------|
+| Unit | Fast | Complete | Single function/class | Business logic |
+| Component | Fast | Partial (mocks) | One component | Service behavior |
+| Integration | Slow | None | Multiple components | DB, APIs |
+| E2E | Slowest | None | Full system | Critical paths |
+| Manual | N/A | None | Everything | Edge cases, UX |
+
+---
+
+## Exit Criteria
+
+Test strategy is complete when:
+- [ ] All test types defined
+- [ ] Coverage targets set
+- [ ] Critical paths identified
+- [ ] Test data strategy defined
+- [ ] Manual test scenarios documented
+- [ ] Strategy documented for team
diff --git a/.agents/skills/vercel-react-best-practices/AGENTS.md b/.agents/skills/vercel-react-best-practices/AGENTS.md
new file mode 100644
index 0000000..4e340a5
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/AGENTS.md
@@ -0,0 +1,3810 @@
+# React Best Practices
+
+**Version 1.0.0**  
+Vercel Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React and Next.js codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+   - 1.1 [Check Cheap Conditions Before Async Flags](#11-check-cheap-conditions-before-async-flags)
+   - 1.2 [Defer Await Until Needed](#12-defer-await-until-needed)
+   - 1.3 [Dependency-Based Parallelization](#13-dependency-based-parallelization)
+   - 1.4 [Prevent Waterfall Chains in API Routes](#14-prevent-waterfall-chains-in-api-routes)
+   - 1.5 [Promise.all() for Independent Operations](#15-promiseall-for-independent-operations)
+   - 1.6 [Strategic Suspense Boundaries](#16-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+   - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+   - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+   - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+   - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+   - 2.5 [Prefer Statically Analyzable Paths](#25-prefer-statically-analyzable-paths)
+   - 2.6 [Preload Based on User Intent](#26-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+   - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+   - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+   - 3.3 [Avoid Shared Module State for Request Data](#33-avoid-shared-module-state-for-request-data)
+   - 3.4 [Cross-Request LRU Caching](#34-cross-request-lru-caching)
+   - 3.5 [Hoist Static I/O to Module Level](#35-hoist-static-io-to-module-level)
+   - 3.6 [Minimize Serialization at RSC Boundaries](#36-minimize-serialization-at-rsc-boundaries)
+   - 3.7 [Parallel Data Fetching with Component Composition](#37-parallel-data-fetching-with-component-composition)
+   - 3.8 [Parallel Nested Data Fetching](#38-parallel-nested-data-fetching)
+   - 3.9 [Per-Request Deduplication with React.cache()](#39-per-request-deduplication-with-reactcache)
+   - 3.10 [Use after() for Non-Blocking Operations](#310-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+   - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+   - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+   - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+   - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+   - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
+   - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
+   - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+   - 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components)
+   - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+   - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components)
+   - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies)
+   - 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers)
+   - 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations)
+   - 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state)
+   - 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates)
+   - 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization)
+   - 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates)
+   - 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders)
+   - 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+   - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+   - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+   - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+   - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
+   - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
+   - 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags)
+   - 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering)
+   - 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints)
+   - 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+   - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+   - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+   - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+   - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+   - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+   - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+   - 7.7 [Defer Non-Critical Work with requestIdleCallback](#77-defer-non-critical-work-with-requestidlecallback)
+   - 7.8 [Early Length Check for Array Comparisons](#78-early-length-check-for-array-comparisons)
+   - 7.9 [Early Return from Functions](#79-early-return-from-functions)
+   - 7.10 [Hoist RegExp Creation](#710-hoist-regexp-creation)
+   - 7.11 [Use flatMap to Map and Filter in One Pass](#711-use-flatmap-to-map-and-filter-in-one-pass)
+   - 7.12 [Use Loop for Min/Max Instead of Sort](#712-use-loop-for-minmax-instead-of-sort)
+   - 7.13 [Use Set/Map for O(1) Lookups](#713-use-setmap-for-o1-lookups)
+   - 7.14 [Use toSorted() Instead of sort() for Immutability](#714-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+   - 8.1 [Do Not Put Effect Events in Dependency Arrays](#81-do-not-put-effect-events-in-dependency-arrays)
+   - 8.2 [Initialize App Once, Not Per Mount](#82-initialize-app-once-not-per-mount)
+   - 8.3 [Store Event Handlers in Refs](#83-store-event-handlers-in-refs)
+   - 8.4 [useEffectEvent for Stable Callback Refs](#84-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Check Cheap Conditions Before Async Flags
+
+**Impact: HIGH (avoids unnecessary async work when a synchronous guard already fails)**
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
+
+### 1.2 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect: blocks both branches**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct: only blocks when needed**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example: early return optimization**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
+
+### 1.3 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect: profile waits for config unnecessarily**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct: config and profile run in parallel**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.4 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect: config waits for auth, data waits for both**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct: auth and config start immediately**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+### 1.5 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect: sequential execution, 3 round trips**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct: parallel execution, 1 round trip**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.6 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect: wrapper blocked by data fetching**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct: wrapper shows immediately, data streams in**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
+
+### 2.3 Defer Non-Critical Third-Party Libraries
+
+**Impact: MEDIUM (loads after hydration)**
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect: blocks initial bundle**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct: loads after hydration**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+### 2.4 Dynamic Imports for Heavy Components
+
+**Impact: CRITICAL (directly affects TTI and LCP)**
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect: Monaco bundles with main chunk ~300KB**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct: Monaco loads on demand**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+### 2.5 Prefer Statically Analyzable Paths
+
+**Impact: HIGH (avoids accidental broad bundles and file traces)**
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+
+- Larger server bundles
+
+- Slower builds
+
+- Worse cold starts
+
+- More memory use
+
+**Incorrect: the bundler cannot tell what may be imported**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct: use an explicit map of allowed modules**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+**Incorrect: a 2-value enum still hides the final path from static analysis**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct: make each final path literal at the callsite**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [https://nextjs.org/docs/app/api-reference/config/next-config-js/output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [https://nextjs.org/learn/seo/dynamic-imports](https://nextjs.org/learn/seo/dynamic-imports), [https://vite.dev/guide/features.html](https://vite.dev/guide/features.html), [https://esbuild.github.io/api/](https://esbuild.github.io/api/), [https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [https://webpack.js.org/guides/dependency-management/](https://webpack.js.org/guides/dependency-management/)
+
+### 2.6 Preload Based on User Intent
+
+**Impact: MEDIUM (reduces perceived latency)**
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example: preload on hover/focus**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example: preload when feature flag is enabled**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect: no authentication check**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct: authentication inside the action**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
+
+### 3.2 Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect: duplicates array**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct: sends 3 strings**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+**Operations breaking deduplication: create new references**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
+
+### 3.3 Avoid Shared Module State for Request Data
+
+**Impact: HIGH (prevents concurrency bugs and request data leaks)**
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect: request data leaks across concurrent renders**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct: keep request data local to the render tree**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
+
+### 3.4 Cross-Request LRU Caching
+
+**Impact: HIGH (caches across requests)**
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+### 3.5 Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct: synchronous fs at module level**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect: reads config on every call**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct: hoists config and template to module level**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+
+- Loading static logos, icons, or watermarks
+
+- Reading configuration files that don't change at runtime
+
+- Loading email templates or other static templates
+
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+
+- Files that may change during runtime (use caching with TTL instead)
+
+- Large files that would consume too much memory if kept loaded
+
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
+
+### 3.6 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect: serializes all 50 fields**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
+
+### 3.7 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
+
+### 3.8 Parallel Nested Data Fetching
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect: a single slow item blocks all nested fetches**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct: each item chains its own nested fetch**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
+
+### 3.9 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect: always cache miss**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct: cache hit**
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+If you must pass objects, pass the same reference:
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+
+- Heavy computations
+
+- Authentication checks
+
+- File system operations
+
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.10 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect: blocks response**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+
+- Audit logging
+
+- Sending notifications
+
+- Cache invalidation
+
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect: N instances = N listeners**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct: N instances = 1 listener**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (automatic deduplication)**
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect: no deduplication, each instance fetches**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct: multiple instances share one request**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Calculate Derived State During Rendering
+
+**Impact: MEDIUM (avoids redundant renders and state drift)**
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect: redundant state and effect**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct: derive during render**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+### 5.2 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect: subscribes to all searchParams changes**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct: reads on demand, no subscription**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+### 5.4 Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect: remounts on every render**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct: pass props instead**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+
+- Input fields lose focus on every keystroke
+
+- Animations restart unexpectedly
+
+- `useEffect` cleanup/setup runs on every parent render
+
+- Scroll position resets inside the component
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct: stable default value**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+### 5.6 Extract to Memoized Components
+
+**Impact: MEDIUM (enables early returns)**
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect: computes avatar even when loading**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Split Combined Hook Computations
+
+**Impact: MEDIUM (avoids recomputing independent steps)**
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect: changing `sortOrder` recomputes filtering**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct: filtering only recomputes when products or category change**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect: both effects run when either dependency changes**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct: effects run independently**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
+
+### 5.10 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+### 5.11 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct: stable callbacks, no stale closures**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+
+2. **No stale closures** - Always operates on the latest state value
+
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+
+- Inside useCallback/useMemo when state is needed
+
+- Event handlers that reference state
+
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+
+- Setting state from props/arguments only: `setName(newName)`
+
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
+
+### 5.12 Use Lazy State Initialization
+
+**Impact: MEDIUM (wasted computation on every render)**
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect: runs on every render**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct: runs only once**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
+
+### 5.13 Use Transitions for Non-Urgent Updates
+
+**Impact: MEDIUM (maintains UI responsiveness)**
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect: blocks UI on every scroll**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct: non-blocking updates**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+### 5.14 Use useDeferredValue for Expensive Derived Renders
+
+**Impact: MEDIUM (keeps input responsive during heavy computation)**
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect: input feels laggy while filtering**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct: input stays snappy, results render when ready**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+
+- Expensive visualizations (charts, graphs) reacting to input
+
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [https://react.dev/reference/react/useDeferredValue](https://react.dev/reference/react/useDeferredValue)
+
+### 5.15 Use useRef for Transient Values
+
+**Impact: MEDIUM (avoids unnecessary re-renders on frequent updates)**
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect: renders every update**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct: no re-render for tracking**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct: 1 decimal place**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect: breaks SSR**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect: blocks rendering**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+### 6.10 Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example: preconnect to third-party APIs**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example: preload critical fonts and styles**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example: preload modules for code-split routes**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+
+|-----|----------|
+
+| `prefetchDNS` | Third-party domains you'll connect to later |
+
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+
+| `preload` | Critical resources needed for current page |
+
+| `preloadModule` | JS modules for likely next navigation |
+
+| `preinit` | Stylesheets/scripts that must execute early |
+
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct: useTransition with built-in pending state**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+
+- **Error resilience**: Pending state correctly resets even if the transition throws
+
+- **Better responsiveness**: Keeps the UI responsive during updates
+
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### 7.1 Avoid Layout Thrashing
+
+**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK: browser batches style changes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect: interleaved reads and writes force reflows**
+
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct: batch writes, then read once**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct: batch reads, then writes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Better: use CSS classes**
+
+**React example:**
+
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect: blocks main thread during user interaction**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct: defers non-critical work to idle time**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+
+- Saving state to localStorage/IndexedDB
+
+- Prefetching resources for likely next actions
+
+- Processing non-urgent data transformations
+
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+
+- Rendering updates the user is waiting for
+
+- Time-sensitive operations
+
+### 7.8 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.9 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
+
+### 7.10 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.11 Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect: 2 iterations, intermediate array**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct: 1 iteration, no intermediate array**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+
+- Transforming items while filtering some out
+
+- Conditional mapping where some inputs produce no output
+
+- Parsing/validating where invalid inputs should be skipped
+
+### 7.12 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.13 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.14 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Do Not Put Effect Events in Dependency Arrays
+
+**Impact: LOW (avoids unnecessary effect re-runs and lint errors)**
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect: Effect Event added as a dependency**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct: depend on reactive values, not the Effect Event**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [https://react.dev/reference/react/useEffectEvent#effect-event-in-deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
+
+### 8.2 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.3 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.4 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.agents/skills/vercel-react-best-practices/README.md b/.agents/skills/vercel-react-best-practices/README.md
new file mode 100644
index 0000000..f283e1c
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/README.md
@@ -0,0 +1,123 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Build AGENTS.md from rules:
+   ```bash
+   pnpm build
+   ```
+
+3. Validate rule files:
+   ```bash
+   pnpm validate
+   ```
+
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `async-` for Eliminating Waterfalls (Section 1)
+   - `bundle-` for Bundle Size Optimization (Section 2)
+   - `server-` for Server-Side Performance (Section 3)
+   - `client-` for Client-Side Data Fetching (Section 4)
+   - `rerender-` for Re-render Optimization (Section 5)
+   - `rendering-` for Rendering Performance (Section 6)
+   - `js-` for JavaScript Performance (Section 7)
+   - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
diff --git a/.agents/skills/vercel-react-best-practices/SKILL.md b/.agents/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 0000000..237988d
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.agents/skills/vercel-react-best-practices/metadata.json b/.agents/skills/vercel-react-best-practices/metadata.json
new file mode 100644
index 0000000..3bec38b
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/metadata.json
@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}
diff --git a/.agents/skills/vercel-react-best-practices/rules/_sections.md b/.agents/skills/vercel-react-best-practices/rules/_sections.md
new file mode 100644
index 0000000..4d20c14
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.
diff --git a/.agents/skills/vercel-react-best-practices/rules/_template.md b/.agents/skills/vercel-react-best-practices/rules/_template.md
new file mode 100644
index 0000000..1e9e707
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md b/.agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
new file mode 100644
index 0000000..24d901b
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
@@ -0,0 +1,56 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 0000000..97e7ade
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md b/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 0000000..73ee38e
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 0000000..9c7cb50
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md b/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md
new file mode 100644
index 0000000..6feda1e
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md b/.agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
new file mode 100644
index 0000000..5799d7f
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md b/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md
new file mode 100644
index 0000000..460b5e1
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md b/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md
new file mode 100644
index 0000000..0484eba
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-parallel.md b/.agents/skills/vercel-react-best-practices/rules/async-parallel.md
new file mode 100644
index 0000000..64133f6
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 0000000..1fbc05b
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md b/.agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
new file mode 100644
index 0000000..8276f15
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
@@ -0,0 +1,63 @@
+---
+title: Prefer Statically Analyzable Paths
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, nextjs, vite, webpack, rollup, esbuild, path
+---
+
+## Prefer Statically Analyzable Paths
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+- Larger server bundles
+- Slower builds
+- Worse cold starts
+- More memory use
+
+### Import Paths
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+### File-System Paths
+
+**Incorrect (a 2-value enum still hides the final path from static analysis):**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct (make each final path literal at the callsite):**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 0000000..22d1050
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,60 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```js
+// next.config.js - automatically optimizes barrel imports at build time
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md b/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 0000000..99d6fc9
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md b/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
new file mode 100644
index 0000000..db041d1
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md b/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
new file mode 100644
index 0000000..60b6269
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md b/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md
new file mode 100644
index 0000000..7000504
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md
@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md b/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 0000000..aad4ae9
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 0000000..d30a1a7
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 0000000..ce39a88
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 0000000..2a430f2
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md b/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 0000000..a62d84e
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 0000000..180f8ac
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 0000000..39eec90
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 0000000..aa4a30c
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md b/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 0000000..044d017
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md b/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md
new file mode 100644
index 0000000..f46cb89
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md b/.agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
new file mode 100644
index 0000000..ee0edf0
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
@@ -0,0 +1,60 @@
+---
+title: Use flatMap to Map and Filter in One Pass
+impact: LOW-MEDIUM
+impactDescription: eliminates intermediate array
+tags: javascript, arrays, flatMap, filter, performance
+---
+
+## Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect (2 iterations, intermediate array):**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct (1 iteration, no intermediate array):**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+- Transforming items while filtering some out
+- Conditional mapping where some inputs produce no output
+- Parsing/validating where invalid inputs should be skipped
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md b/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 0000000..dae3fef
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md b/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md
new file mode 100644
index 0000000..9d357a0
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md b/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 0000000..8b89573
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md b/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 0000000..4b6656e
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md b/.agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
new file mode 100644
index 0000000..d81927e
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
@@ -0,0 +1,105 @@
+---
+title: Defer Non-Critical Work with requestIdleCallback
+impact: MEDIUM
+impactDescription: keeps UI responsive during background tasks
+tags: javascript, performance, idle, scheduling, analytics
+---
+
+## Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect (blocks main thread during user interaction):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct (defers non-critical work to idle time):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+- Saving state to localStorage/IndexedDB
+- Prefetching resources for likely next actions
+- Processing non-urgent data transformations
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+- Rendering updates the user is waiting for
+- Time-sensitive operations
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md b/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 0000000..680a489
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md b/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 0000000..eae8b3f
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md b/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md
new file mode 100644
index 0000000..c957a49
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md b/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 0000000..646744c
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 0000000..7e866f5
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 0000000..aa66563
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 0000000..32d2f3f
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 0000000..5cf0e79
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 0000000..24ba251
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md b/.agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
new file mode 100644
index 0000000..1290bef
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
@@ -0,0 +1,85 @@
+---
+title: Use React DOM Resource Hints
+impact: HIGH
+impactDescription: reduces load time for critical resources
+tags: rendering, preload, preconnect, prefetch, resource-hints
+---
+
+## Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example (preconnect to third-party APIs):**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example (preload critical fonts and styles):**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example (preload modules for code-split routes):**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+|-----|----------|
+| `prefetchDNS` | Third-party domains you'll connect to later |
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+| `preload` | Critical resources needed for current page |
+| `preloadModule` | JS modules for likely next navigation |
+| `preinit` | Stylesheets/scripts that must execute early |
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md b/.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
new file mode 100644
index 0000000..ee275ed
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect (blocks rendering):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        {/* Independent script - use async */}
+        <script src="https://example.com/analytics.js" async />
+        {/* DOM-dependent script - use defer */}
+        <script src="/scripts/utils.js" defer />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 0000000..6d77128
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md b/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 0000000..0c1b0b9
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md b/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 0000000..e867c95
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md b/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 0000000..47a4d92
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
new file mode 100644
index 0000000..3d9fe40
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 0000000..e5c899f
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 0000000..b004ef4
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md b/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 0000000..4ecb350
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md b/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 0000000..6357049
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md b/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md
new file mode 100644
index 0000000..f8982ab
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md b/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 0000000..dd58a1a
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md b/.agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
new file mode 100644
index 0000000..d97592a
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
@@ -0,0 +1,82 @@
+---
+title: Don't Define Components Inside Components
+impact: HIGH
+impactDescription: prevents remount on every render
+tags: rerender, components, remount, performance
+---
+
+## Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect (remounts on every render):**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct (pass props instead):**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+- Input fields lose focus on every keystroke
+- Animations restart unexpectedly
+- `useEffect` cleanup/setup runs on every parent render
+- Scroll position resets inside the component
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 0000000..59dfab0
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md b/.agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
new file mode 100644
index 0000000..89d8056
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
@@ -0,0 +1,64 @@
+---
+title: Split Combined Hook Computations
+impact: MEDIUM
+impactDescription: avoids recomputing independent steps
+tags: rerender, useMemo, useEffect, dependencies, optimization
+---
+
+## Split Combined Hook Computations
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect (changing `sortOrder` recomputes filtering):**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct (filtering only recomputes when products or category change):**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect (both effects run when either dependency changes):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct (effects run independently):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md b/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 0000000..d99f43f
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md b/.agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
new file mode 100644
index 0000000..619c04b
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
@@ -0,0 +1,59 @@
+---
+title: Use useDeferredValue for Expensive Derived Renders
+impact: MEDIUM
+impactDescription: keeps input responsive during heavy computation
+tags: rerender, useDeferredValue, optimization, concurrent
+---
+
+## Use useDeferredValue for Expensive Derived Renders
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect (input feels laggy while filtering):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct (input stays snappy, results render when ready):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+- Expensive visualizations (charts, graphs) reacting to input
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md b/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
new file mode 100644
index 0000000..cf04b81
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 0000000..e8f5b26
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md b/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 0000000..ee82c04
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md b/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 0000000..ef6938a
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md b/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md
new file mode 100644
index 0000000..87c9ca3
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md b/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 0000000..fb24a25
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md b/.agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
new file mode 100644
index 0000000..25205c2
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
@@ -0,0 +1,149 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect (reads font file on every request):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct (loads once at module initialization):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct (synchronous fs at module level):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect (reads config on every call):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct (hoists config and template to module level):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md b/.agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
new file mode 100644
index 0000000..ff7d9f2
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
@@ -0,0 +1,50 @@
+---
+title: Avoid Shared Module State for Request Data
+impact: HIGH
+impactDescription: prevents concurrency bugs and request data leaks
+tags: server, rsc, ssr, concurrency, security, state
+---
+
+## Avoid Shared Module State for Request Data
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect (request data leaks across concurrent renders):**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct (keep request data local to the render tree):**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md b/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 0000000..1affc83
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md b/.agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
new file mode 100644
index 0000000..be1dc25
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
@@ -0,0 +1,34 @@
+---
+title: Parallel Nested Data Fetching
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, promise-chaining
+---
+
+## Parallel Nested Data Fetching
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect (a single slow item blocks all nested fetches):**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct (each item chains its own nested fetch):**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-serialization.md b/.agents/skills/vercel-react-best-practices/rules/server-serialization.md
new file mode 100644
index 0000000..39c5c41
--- /dev/null
+++ b/.agents/skills/vercel-react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
diff --git a/.agents/skills/zod/AGENTS.md b/.agents/skills/zod/AGENTS.md
new file mode 100644
index 0000000..dd3b53f
--- /dev/null
+++ b/.agents/skills/zod/AGENTS.md
@@ -0,0 +1,97 @@
+# Zod
+
+**Version 1.0.0**  
+community  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring codebases. Humans may also find it useful,  
+> but guidance here is optimized for automation and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive schema validation guide for Zod in TypeScript applications, designed for AI agents and LLMs. Contains 43 rules across 8 categories, prioritized by impact from critical (schema definition, parsing) to incremental (performance, bundle optimization). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Schema Definition](references/_sections.md#1-schema-definition) — **CRITICAL**
+   - 1.1 [Apply String Validations at Schema Definition](references/schema-string-validations.md) — CRITICAL (Unvalidated strings allow SQL injection, XSS, and malformed data; validating at schema level catches issues at the boundary)
+   - 1.2 [Avoid Overusing Optional Fields](references/schema-avoid-optional-abuse.md) — CRITICAL (Excessive optional fields create schemas that accept almost anything; forces null checks throughout codebase)
+   - 1.3 [Use Coercion for Form and Query Data](references/schema-coercion-for-form-data.md) — CRITICAL (Form data and query params are always strings; without coercion, z.number() rejects "42" and z.boolean() rejects "true")
+   - 1.4 [Use Enums for Fixed String Values](references/schema-use-enums.md) — CRITICAL (Plain strings accept any value including typos; enums restrict to valid values and enable autocomplete)
+   - 1.5 [Use Primitive Schemas Correctly](references/schema-use-primitives-correctly.md) — CRITICAL (Incorrect primitive selection causes validation to pass on wrong types; using z.any() or z.unknown() loses all type safety)
+   - 1.6 [Use z.unknown() Instead of z.any()](references/schema-use-unknown-not-any.md) — CRITICAL (z.any() bypasses TypeScript's type system entirely; z.unknown() forces type narrowing before use)
+2. [Parsing & Validation](references/_sections.md#2-parsing-&-validation) — **CRITICAL**
+   - 2.1 [Avoid Double Validation](references/parse-avoid-double-validation.md) — HIGH (Parsing the same data twice wastes CPU cycles; in hot paths this adds measurable latency)
+   - 2.2 [Handle All Validation Issues Not Just First](references/parse-handle-all-issues.md) — CRITICAL (Showing only the first error forces users to fix-submit-fix repeatedly; collecting all errors improves UX dramatically)
+   - 2.3 [Never Trust JSON.parse Output](references/parse-never-trust-json.md) — CRITICAL (JSON.parse returns any type; unvalidated JSON allows type confusion attacks and runtime crashes)
+   - 2.4 [Use parseAsync for Async Refinements](references/parse-async-for-async-refinements.md) — CRITICAL (Using parse() with async refinements throws an error; async validation silently fails or crashes the application)
+   - 2.5 [Use safeParse() for User Input](references/parse-use-safeparse.md) — CRITICAL (parse() throws exceptions on invalid data; unhandled exceptions crash servers and expose stack traces to users)
+   - 2.6 [Validate at System Boundaries](references/parse-validate-early.md) — CRITICAL (Validating deep in business logic allows corrupt data to propagate; validating at boundaries catches issues before they spread)
+3. [Type Inference](references/_sections.md#3-type-inference) — **HIGH**
+   - 3.1 [Distinguish z.input from z.infer for Transforms](references/type-input-vs-output.md) — HIGH (Using wrong type with transforms causes TypeScript errors; z.input captures pre-transform shape, z.infer captures post-transform)
+   - 3.2 [Enable TypeScript Strict Mode](references/type-enable-strict-mode.md) — HIGH (Without strict mode, Zod's type inference is unreliable; undefined and null slip through, defeating the purpose of validation)
+   - 3.3 [Export Both Schemas and Inferred Types](references/type-export-schemas-and-types.md) — HIGH (Exporting only schemas forces consumers to derive types themselves; exporting both reduces boilerplate and improves DX)
+   - 3.4 [Use Branded Types for Domain Safety](references/type-branded-types.md) — HIGH (Plain string IDs are interchangeable, allowing userId where orderId is expected; branded types catch these bugs at compile time)
+   - 3.5 [Use z.infer Instead of Manual Types](references/type-use-z-infer.md) — HIGH (Manual type definitions drift from schemas over time; z.infer guarantees types match validation exactly)
+4. [Error Handling](references/_sections.md#4-error-handling) — **HIGH**
+   - 4.1 [Implement Internationalized Error Messages](references/error-i18n.md) — HIGH (Hardcoded English messages exclude non-English users; error maps enable localized messages for global applications)
+   - 4.2 [Provide Custom Error Messages](references/error-custom-messages.md) — HIGH (Default messages like "Expected string, received number" confuse users; custom messages like "Email is required" are actionable)
+   - 4.3 [Return False Instead of Throwing in Refine](references/error-avoid-throwing-in-refine.md) — HIGH (Throwing in refine stops validation early, hiding other errors; returning false allows Zod to collect all issues)
+   - 4.4 [Use flatten() for Form Error Display](references/error-use-flatten.md) — HIGH (Raw ZodError.issues requires manual path parsing; flatten() provides field-keyed errors ready for form display)
+   - 4.5 [Use issue.path for Nested Error Location](references/error-path-for-nested.md) — HIGH (Without path information, users can't identify which nested field failed; path provides exact location in complex objects)
+5. [Object Schemas](references/_sections.md#5-object-schemas) — **MEDIUM-HIGH**
+   - 5.1 [Choose strict() vs strip() for Unknown Keys](references/object-strict-vs-strip.md) — MEDIUM-HIGH (Default passthrough mode leaks unexpected data; strict() catches schema mismatches, strip() silently removes extras)
+   - 5.2 [Distinguish optional() from nullable()](references/object-optional-vs-nullable.md) — MEDIUM-HIGH (Confusing undefined and null semantics causes "property does not exist" vs "property is null" bugs; choose deliberately)
+   - 5.3 [Use Discriminated Unions for Type Narrowing](references/object-discriminated-unions.md) — MEDIUM-HIGH (Regular unions require manual type guards; discriminated unions enable TypeScript's automatic narrowing and Zod's optimized parsing)
+   - 5.4 [Use extend() for Adding Fields](references/object-extend-for-composition.md) — MEDIUM-HIGH (Merging objects manually loses type information; extend() preserves types and allows overriding fields safely)
+   - 5.5 [Use partial() for Update Schemas](references/object-partial-for-updates.md) — MEDIUM-HIGH (Creating separate update schemas duplicates definitions; partial() derives update schema from base, staying in sync)
+   - 5.6 [Use pick() and omit() for Schema Variants](references/object-pick-omit.md) — MEDIUM-HIGH (Copying fields between schemas creates duplication; pick/omit derive variants that stay in sync with base schema)
+6. [Schema Composition](references/_sections.md#6-schema-composition) — **MEDIUM**
+   - 6.1 [Extract Shared Schemas into Reusable Modules](references/compose-shared-schemas.md) — MEDIUM (Duplicating schemas across files leads to inconsistency; shared schemas ensure single source of truth)
+   - 6.2 [Use intersection() for Type Combinations](references/compose-intersection.md) — MEDIUM (Manual field combination loses type relationships; intersection creates proper TypeScript intersection types)
+   - 6.3 [Use pipe() for Multi-Stage Validation](references/compose-pipe.md) — MEDIUM (Chaining transforms loses intermediate type info; pipe() explicitly shows data flow through validation stages)
+   - 6.4 [Use preprocess() for Data Normalization](references/compose-preprocess.md) — MEDIUM (Validating before cleaning data causes false rejections; preprocess() normalizes input before schema validation runs)
+   - 6.5 [Use z.lazy() for Recursive Schemas](references/compose-lazy-recursive.md) — MEDIUM (Recursive types reference themselves before definition; z.lazy() defers evaluation to enable self-referential schemas)
+7. [Refinements & Transforms](references/_sections.md#7-refinements-&-transforms) — **MEDIUM**
+   - 7.1 [Add Path to Refinement Errors](references/refine-add-path.md) — MEDIUM (Errors without path show at object level; adding path highlights the specific field that failed)
+   - 7.2 [Choose refine() vs superRefine() Correctly](references/refine-vs-superrefine.md) — MEDIUM (refine() only reports one error; superRefine() enables multiple issues and custom error codes)
+   - 7.3 [Distinguish transform() from refine() and coerce()](references/refine-transform-coerce.md) — MEDIUM (Using wrong method causes validation to pass with wrong data; each method has distinct purpose)
+   - 7.4 [Use catch() for Fault-Tolerant Parsing](references/refine-catch.md) — MEDIUM (parse() fails on first invalid field; catch() provides fallback values, enabling partial success with degraded data)
+   - 7.5 [Use default() for Optional Fields with Defaults](references/refine-defaults.md) — MEDIUM (Manual default handling spreads logic across codebase; .default() centralizes defaults in schema)
+8. [Performance & Bundle](references/_sections.md#8-performance-&-bundle) — **LOW-MEDIUM**
+   - 8.1 [Avoid Dynamic Schema Creation in Hot Paths](references/perf-avoid-dynamic-creation.md) — LOW-MEDIUM (Zod 4's JIT compilation makes schema creation slower; creating schemas in loops adds ~0.15ms per creation)
+   - 8.2 [Cache Schema Instances](references/perf-cache-schemas.md) — LOW-MEDIUM (Creating schemas on every render/call wastes CPU; module-level or memoized schemas are created once)
+   - 8.3 [Lazy Load Large Schemas](references/perf-lazy-loading.md) — LOW-MEDIUM (Large schemas increase initial bundle and parse time; dynamic imports defer loading until needed)
+   - 8.4 [Optimize Large Array Validation](references/perf-arrays.md) — LOW-MEDIUM (Validating 10,000 items takes ~100ms; early exits, sampling, or batching reduce time for large datasets)
+   - 8.5 [Use Zod Mini for Bundle-Sensitive Applications](references/perf-zod-mini.md) — LOW-MEDIUM (Full Zod is ~17kb gzipped; Zod Mini is ~1.9kb - 85% smaller for frontend-critical bundles)
+
+---
+
+## References
+
+1. [https://zod.dev/](https://zod.dev/)
+2. [https://zod.dev/v4](https://zod.dev/v4)
+3. [https://github.com/colinhacks/zod](https://github.com/colinhacks/zod)
+4. [https://zod.dev/packages/mini](https://zod.dev/packages/mini)
+5. [https://www.totaltypescript.com/tutorials/zod](https://www.totaltypescript.com/tutorials/zod)
+6. [https://zod.dev/error-handling](https://zod.dev/error-handling)
+7. [https://zod.dev/api](https://zod.dev/api)
+
+---
+
+## Source Files
+
+This document was compiled from individual reference files. For detailed editing or extension:
+
+| File | Description |
+|------|-------------|
+| [references/_sections.md](references/_sections.md) | Category definitions and impact ordering |
+| [assets/templates/_template.md](assets/templates/_template.md) | Template for creating new rules |
+| [SKILL.md](SKILL.md) | Quick reference entry point |
+| [metadata.json](metadata.json) | Version and reference URLs |
\ No newline at end of file
diff --git a/.agents/skills/zod/README.md b/.agents/skills/zod/README.md
new file mode 100644
index 0000000..9dec824
--- /dev/null
+++ b/.agents/skills/zod/README.md
@@ -0,0 +1,79 @@
+# Zod Best Practices Skill
+
+A comprehensive guide for using Zod effectively in TypeScript applications. This skill provides 42 rules across 8 categories, organized by impact to help AI agents and developers write better validation code.
+
+## Overview
+
+Zod is a TypeScript-first schema declaration and validation library. This skill covers best practices for:
+
+- **Schema Definition**: Choosing correct types, avoiding `z.any()`, proper string validations
+- **Parsing & Validation**: Using `safeParse()`, async validation, error handling
+- **Type Inference**: Leveraging `z.infer`, distinguishing input/output types
+- **Error Handling**: Custom messages, internationalization, form error display
+- **Object Schemas**: strict/strip modes, partial updates, discriminated unions
+- **Schema Composition**: Reusable schemas, intersections, recursive types
+- **Refinements & Transforms**: Custom validation, data transformation
+- **Performance**: Caching, Zod Mini, lazy loading, batch validation
+
+## Usage
+
+### For Claude Code / AI Agents
+
+The skill is automatically loaded when working with Zod code. Reference specific rules:
+
+```
+See rules/parse-use-safeparse.md for safeParse best practices
+```
+
+### For Developers
+
+Read `SKILL.md` for a quick reference, or `AGENTS.md` for the full compiled guide.
+
+## File Structure
+
+```
+zod/
+├── SKILL.md          # Quick reference with rule index
+├── AGENTS.md         # Full compiled guide (all rules)
+├── metadata.json     # Version, categories, references
+├── README.md         # This file
+└── rules/
+    ├── _sections.md  # Category definitions
+    ├── _template.md  # Rule template
+    ├── schema-*.md   # Schema definition rules
+    ├── parse-*.md    # Parsing rules
+    ├── type-*.md     # Type inference rules
+    ├── error-*.md    # Error handling rules
+    ├── object-*.md   # Object schema rules
+    ├── compose-*.md  # Composition rules
+    ├── refine-*.md   # Refinement rules
+    └── perf-*.md     # Performance rules
+```
+
+## Rule Categories
+
+| Priority | Category | Rules | Impact |
+|----------|----------|-------|--------|
+| 1 | Schema Definition | 6 | CRITICAL |
+| 2 | Parsing & Validation | 6 | CRITICAL |
+| 3 | Type Inference | 5 | HIGH |
+| 4 | Error Handling | 5 | HIGH |
+| 5 | Object Schemas | 6 | MEDIUM-HIGH |
+| 6 | Schema Composition | 5 | MEDIUM |
+| 7 | Refinements & Transforms | 5 | MEDIUM |
+| 8 | Performance & Bundle | 5 | LOW-MEDIUM |
+
+## Key Principles
+
+1. **Type Safety First**: Always use `z.infer`, never duplicate types manually
+2. **Validate at Boundaries**: Parse external data immediately at entry points
+3. **User-Friendly Errors**: Provide custom messages, collect all issues
+4. **Single Source of Truth**: Schema defines validation AND TypeScript types
+5. **Composition Over Duplication**: Use extend, pick, omit, partial
+
+## References
+
+- [Zod Official Documentation](https://zod.dev/)
+- [Zod v4 Release Notes](https://zod.dev/v4)
+- [Zod GitHub](https://github.com/colinhacks/zod)
+- [Zod Mini](https://zod.dev/packages/mini)
diff --git a/.agents/skills/zod/SKILL.md b/.agents/skills/zod/SKILL.md
new file mode 100644
index 0000000..7c85830
--- /dev/null
+++ b/.agents/skills/zod/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: zod
+description: Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
+---
+
+# Zod Best Practices
+
+Comprehensive schema validation guide for Zod in TypeScript applications. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new Zod schemas
+- Choosing between parse() and safeParse()
+- Implementing type inference with z.infer
+- Handling validation errors for user feedback
+- Composing complex object schemas
+- Using refinements and transforms
+- Optimizing bundle size and validation performance
+- Reviewing Zod code for best practices
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Schema Definition | CRITICAL | `schema-` |
+| 2 | Parsing & Validation | CRITICAL | `parse-` |
+| 3 | Type Inference | HIGH | `type-` |
+| 4 | Error Handling | HIGH | `error-` |
+| 5 | Object Schemas | MEDIUM-HIGH | `object-` |
+| 6 | Schema Composition | MEDIUM | `compose-` |
+| 7 | Refinements & Transforms | MEDIUM | `refine-` |
+| 8 | Performance & Bundle | LOW-MEDIUM | `perf-` |
+
+## Quick Reference
+
+### 1. Schema Definition (CRITICAL)
+
+- `schema-use-primitives-correctly` - Use correct primitive schemas for each type
+- `schema-use-unknown-not-any` - Use z.unknown() instead of z.any() for type safety
+- `schema-avoid-optional-abuse` - Avoid overusing optional fields
+- `schema-string-validations` - Apply string validations at schema definition
+- `schema-use-enums` - Use enums for fixed string values
+- `schema-coercion-for-form-data` - Use coercion for form and query data
+
+### 2. Parsing & Validation (CRITICAL)
+
+- `parse-use-safeparse` - Use safeParse() for user input
+- `parse-async-for-async-refinements` - Use parseAsync for async refinements
+- `parse-handle-all-issues` - Handle all validation issues not just first
+- `parse-validate-early` - Validate at system boundaries
+- `parse-avoid-double-validation` - Avoid validating same data twice
+- `parse-never-trust-json` - Never trust JSON.parse output
+
+### 3. Type Inference (HIGH)
+
+- `type-use-z-infer` - Use z.infer instead of manual types
+- `type-input-vs-output` - Distinguish z.input from z.infer for transforms
+- `type-export-schemas-and-types` - Export both schemas and inferred types
+- `type-branded-types` - Use branded types for domain safety
+- `type-enable-strict-mode` - Enable TypeScript strict mode
+
+### 4. Error Handling (HIGH)
+
+- `error-custom-messages` - Provide custom error messages
+- `error-use-flatten` - Use flatten() for form error display
+- `error-path-for-nested` - Use issue.path for nested error location
+- `error-i18n` - Implement internationalized error messages
+- `error-avoid-throwing-in-refine` - Return false instead of throwing in refine
+
+### 5. Object Schemas (MEDIUM-HIGH)
+
+- `object-strict-vs-strip` - Choose strict() vs strip() for unknown keys
+- `object-partial-for-updates` - Use partial() for update schemas
+- `object-pick-omit` - Use pick() and omit() for schema variants
+- `object-extend-for-composition` - Use extend() for adding fields
+- `object-optional-vs-nullable` - Distinguish optional() from nullable()
+- `object-discriminated-unions` - Use discriminated unions for type narrowing
+
+### 6. Schema Composition (MEDIUM)
+
+- `compose-shared-schemas` - Extract shared schemas into reusable modules
+- `compose-intersection` - Use intersection() for type combinations
+- `compose-lazy-recursive` - Use z.lazy() for recursive schemas
+- `compose-preprocess` - Use preprocess() for data normalization
+- `compose-pipe` - Use pipe() for multi-stage validation
+
+### 7. Refinements & Transforms (MEDIUM)
+
+- `refine-vs-superrefine` - Choose refine() vs superRefine() correctly
+- `refine-transform-coerce` - Distinguish transform() from refine() and coerce()
+- `refine-add-path` - Add path to refinement errors
+- `refine-defaults` - Use default() for optional fields with defaults
+- `refine-catch` - Use catch() for fault-tolerant parsing
+
+### 8. Performance & Bundle (LOW-MEDIUM)
+
+- `perf-cache-schemas` - Cache schema instances
+- `perf-zod-mini` - Use Zod Mini for bundle-sensitive applications
+- `perf-avoid-dynamic-creation` - Avoid dynamic schema creation in hot paths
+- `perf-lazy-loading` - Lazy load large schemas
+- `perf-arrays` - Optimize large array validation
+
+## How to Use
+
+Read individual reference files for detailed explanations and code examples:
+
+- [Section definitions](references/_sections.md) - Category structure and impact levels
+- [Rule template](assets/templates/_template.md) - Template for adding new rules
+- Individual rules: `references/{prefix}-{slug}.md`
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## Related Skills
+
+- For React Hook Form integration, see `react-hook-form` skill
+- For API client generation, see `orval` skill
+
+## Sources
+
+- [Zod Official Documentation](https://zod.dev/)
+- [Zod v4 Release Notes](https://zod.dev/v4)
+- [Zod GitHub Repository](https://github.com/colinhacks/zod)
+- [Zod Mini](https://zod.dev/packages/mini)
+- [Total TypeScript Zod Tutorial](https://www.totaltypescript.com/tutorials/zod)
diff --git a/.agents/skills/zod/assets/templates/_template.md b/.agents/skills/zod/assets/templates/_template.md
new file mode 100644
index 0000000..a190393
--- /dev/null
+++ b/.agents/skills/zod/assets/templates/_template.md
@@ -0,0 +1,30 @@
+---
+title: Rule Title Here
+impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
+impactDescription: Quantified impact (e.g., "2-10× improvement", "prevents runtime crashes")
+tags: section-prefix, technique, tool, related-concepts
+---
+
+## Rule Title Here
+
+1-3 sentences explaining WHY this matters. Focus on validation implications and cascade effects.
+
+**Incorrect (what's wrong):**
+
+```typescript
+// Bad code example - production-realistic, not strawman
+// Comments explaining the cost
+```
+
+**Correct (what's right):**
+
+```typescript
+// Good code example - minimal diff from incorrect
+// Comments explaining the benefit
+```
+
+**When NOT to use this pattern:**
+- Exception 1
+- Exception 2
+
+Reference: [Reference Title](URL)
diff --git a/.agents/skills/zod/references/_sections.md b/.agents/skills/zod/references/_sections.md
new file mode 100644
index 0000000..0fba266
--- /dev/null
+++ b/.agents/skills/zod/references/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Schema Definition (schema)
+
+**Impact:** CRITICAL
+**Description:** Schema definition is the foundation of all Zod validation; incorrect or overly permissive schemas cascade errors through your entire application, allowing invalid data to corrupt downstream logic.
+
+## 2. Parsing & Validation (parse)
+
+**Impact:** CRITICAL
+**Description:** Parsing is the core Zod operation; using `parse()` vs `safeParse()` incorrectly causes either unhandled exceptions crashing your app or silent failures that let invalid data through.
+
+## 3. Type Inference (type)
+
+**Impact:** HIGH
+**Description:** Zod's TypeScript integration eliminates duplicate type definitions; poor inference practices force manual type declarations that drift from schemas, losing the core benefit of Zod.
+
+## 4. Error Handling (error)
+
+**Impact:** HIGH
+**Description:** Error handling determines user experience; poorly structured error handling produces cryptic messages that harm UX and make debugging validation failures nearly impossible.
+
+## 5. Object Schemas (object)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Objects are the most common schema type; misconfiguring strict/passthrough/strip modes either leaks unexpected data to clients or fails validation on legitimate requests.
+
+## 6. Schema Composition (compose)
+
+**Impact:** MEDIUM
+**Description:** Schema composition enables reuse and maintainability; poor composition patterns lead to duplicated schemas that drift apart or deeply nested structures that are impossible to maintain.
+
+## 7. Refinements & Transforms (refine)
+
+**Impact:** MEDIUM
+**Description:** Refinements and transforms handle custom validation and data coercion; choosing the wrong method causes performance issues, incorrect error aggregation, or async parsing failures.
+
+## 8. Performance & Bundle (perf)
+
+**Impact:** LOW-MEDIUM
+**Description:** Zod's performance and bundle size affect application startup and validation throughput; understanding when to use Zod Mini or cache schemas prevents unnecessary overhead in performance-critical paths.
diff --git a/.agents/skills/zod/references/compose-intersection.md b/.agents/skills/zod/references/compose-intersection.md
new file mode 100644
index 0000000..883e335
--- /dev/null
+++ b/.agents/skills/zod/references/compose-intersection.md
@@ -0,0 +1,144 @@
+---
+title: Use intersection() for Type Combinations
+impact: MEDIUM
+impactDescription: Manual field combination loses type relationships; intersection creates proper TypeScript intersection types
+tags: compose, intersection, and, combination
+---
+
+## Use intersection() for Type Combinations
+
+When you need an object that satisfies multiple schemas simultaneously (like combining a base type with mixins), use `.and()` or `z.intersection()`. This creates proper TypeScript intersection types and validates against all schemas.
+
+**Incorrect (manual combination):**
+
+```typescript
+import { z } from 'zod'
+
+const timestampsSchema = z.object({
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+const softDeleteSchema = z.object({
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+})
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+// Manual combination - verbose and error-prone
+const fullUserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+})
+```
+
+**Correct (using intersection):**
+
+```typescript
+import { z } from 'zod'
+
+const timestampsSchema = z.object({
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+const softDeleteSchema = z.object({
+  deletedAt: z.date().nullable(),
+  deletedBy: z.string().nullable(),
+})
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+// Using .and() for intersection
+const fullUserSchema = userSchema
+  .and(timestampsSchema)
+  .and(softDeleteSchema)
+
+// Or using z.intersection()
+const fullUserSchema2 = z.intersection(
+  z.intersection(userSchema, timestampsSchema),
+  softDeleteSchema
+)
+
+type FullUser = z.infer<typeof fullUserSchema>
+// {
+//   id: string;
+//   name: string;
+//   email: string;
+//   createdAt: Date;
+//   updatedAt: Date;
+//   deletedAt: Date | null;
+//   deletedBy: string | null;
+// }
+```
+
+**Creating mixins:**
+
+```typescript
+// Reusable mixins
+const auditable = z.object({
+  createdBy: z.string(),
+  updatedBy: z.string(),
+})
+
+const versioned = z.object({
+  version: z.number().int().positive(),
+})
+
+const tagged = z.object({
+  tags: z.array(z.string()),
+})
+
+// Apply mixins to any schema
+function withAudit<T extends z.ZodRawShape>(schema: z.ZodObject<T>) {
+  return schema.and(auditable).and(timestampsSchema)
+}
+
+function withVersioning<T extends z.ZodRawShape>(schema: z.ZodObject<T>) {
+  return schema.and(versioned)
+}
+
+// Usage
+const documentSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  content: z.string(),
+})
+
+const fullDocumentSchema = withAudit(withVersioning(documentSchema))
+```
+
+**Intersection vs Merge:**
+
+```typescript
+// .merge() - replaces fields from first with second
+const a = z.object({ x: z.string(), y: z.number() })
+const b = z.object({ y: z.string() })  // y is string, not number
+
+a.merge(b)  // { x: string, y: string } - b's y wins
+
+// .and() - requires fields to be compatible
+// If both have y with different types, intersection fails at runtime
+a.and(b)  // Validation will fail - y can't be both number and string
+```
+
+**When NOT to use this pattern:**
+- When schemas have overlapping fields with different types (use merge)
+- When you need to override fields (use extend)
+- Simple cases where extend works fine
+
+Reference: [Zod API - intersection](https://zod.dev/api#intersection)
diff --git a/.agents/skills/zod/references/compose-lazy-recursive.md b/.agents/skills/zod/references/compose-lazy-recursive.md
new file mode 100644
index 0000000..3a7d0dc
--- /dev/null
+++ b/.agents/skills/zod/references/compose-lazy-recursive.md
@@ -0,0 +1,143 @@
+---
+title: Use z.lazy() for Recursive Schemas
+impact: MEDIUM
+impactDescription: Recursive types reference themselves before definition; z.lazy() defers evaluation to enable self-referential schemas
+tags: compose, lazy, recursive, trees
+---
+
+## Use z.lazy() for Recursive Schemas
+
+TypeScript can't infer recursive Zod schema types automatically. Use `z.lazy()` to defer schema evaluation and manually provide the type annotation. This enables tree structures, nested comments, and other self-referential data.
+
+**Incorrect (direct self-reference):**
+
+```typescript
+import { z } from 'zod'
+
+// This fails - categorySchema used before it's defined
+const categorySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  children: z.array(categorySchema),  // Error: Block-scoped variable used before declaration
+})
+```
+
+**Correct (using z.lazy with type annotation):**
+
+```typescript
+import { z } from 'zod'
+
+// Define the type manually
+interface Category {
+  id: string
+  name: string
+  children: Category[]
+}
+
+// Use z.lazy() to defer schema reference
+const categorySchema: z.ZodType<Category> = z.object({
+  id: z.string(),
+  name: z.string(),
+  children: z.lazy(() => z.array(categorySchema)),
+})
+
+// Now it works
+const tree = categorySchema.parse({
+  id: '1',
+  name: 'Electronics',
+  children: [
+    {
+      id: '2',
+      name: 'Phones',
+      children: [
+        { id: '3', name: 'iPhones', children: [] },
+        { id: '4', name: 'Android', children: [] },
+      ],
+    },
+  ],
+})
+```
+
+**Common recursive patterns:**
+
+```typescript
+// Comments with replies
+interface Comment {
+  id: string
+  content: string
+  author: string
+  replies: Comment[]
+}
+
+const commentSchema: z.ZodType<Comment> = z.object({
+  id: z.string(),
+  content: z.string(),
+  author: z.string(),
+  replies: z.lazy(() => z.array(commentSchema)),
+})
+
+// Binary tree
+interface TreeNode {
+  value: number
+  left: TreeNode | null
+  right: TreeNode | null
+}
+
+const treeNodeSchema: z.ZodType<TreeNode> = z.object({
+  value: z.number(),
+  left: z.lazy(() => treeNodeSchema.nullable()),
+  right: z.lazy(() => treeNodeSchema.nullable()),
+})
+
+// Nested menu structure
+interface MenuItem {
+  label: string
+  href?: string
+  children?: MenuItem[]
+}
+
+const menuItemSchema: z.ZodType<MenuItem> = z.object({
+  label: z.string(),
+  href: z.string().url().optional(),
+  children: z.lazy(() => z.array(menuItemSchema)).optional(),
+})
+```
+
+**JSON Schema (any valid JSON):**
+
+```typescript
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONValue[]
+  | { [key: string]: JSONValue }
+
+const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(jsonValueSchema),
+  ])
+)
+```
+
+**Performance consideration:**
+
+```typescript
+// z.lazy() has minimal overhead - the function is called once
+// and the schema is cached. Safe to use in hot paths.
+
+// If validating many recursive structures, the schema itself
+// is only built once. Validation performance depends on data depth.
+```
+
+**When NOT to use this pattern:**
+- Non-recursive schemas (lazy adds unnecessary indirection)
+- When you can flatten the structure instead
+
+Reference: [Zod API - Recursive Types](https://zod.dev/api#recursive-types)
diff --git a/.agents/skills/zod/references/compose-pipe.md b/.agents/skills/zod/references/compose-pipe.md
new file mode 100644
index 0000000..3c931ab
--- /dev/null
+++ b/.agents/skills/zod/references/compose-pipe.md
@@ -0,0 +1,113 @@
+---
+title: Use pipe() for Multi-Stage Validation
+impact: MEDIUM
+impactDescription: Chaining transforms loses intermediate type info; pipe() explicitly shows data flow through validation stages
+tags: compose, pipe, pipeline, transform
+---
+
+## Use pipe() for Multi-Stage Validation
+
+When data needs to pass through multiple validation stages (coerce string to number, then validate range, then transform to currency), use `.pipe()` to chain schemas. This makes the data transformation pipeline explicit and each stage's type clear.
+
+**Incorrect (unclear transformation chain):**
+
+```typescript
+import { z } from 'zod'
+
+// All transforms in one long chain - hard to understand stages
+const priceSchema = z
+  .string()
+  .transform((s) => parseFloat(s.replace(/[$,]/g, '')))
+  .refine((n) => !isNaN(n), 'Invalid number')
+  .refine((n) => n >= 0, 'Must be positive')
+  .refine((n) => n <= 1000000, 'Too large')
+  .transform((n) => Math.round(n * 100))
+
+// What type is n at each stage? Hard to tell
+```
+
+**Correct (using pipe for clear stages):**
+
+```typescript
+import { z } from 'zod'
+
+// Stage 1: Coerce string to number
+const parsePrice = z.string().transform((s) => {
+  const cleaned = s.replace(/[$,]/g, '')
+  const parsed = parseFloat(cleaned)
+  if (isNaN(parsed)) throw new Error('Invalid number')
+  return parsed
+})
+
+// Stage 2: Validate number constraints
+const validPrice = z.number().min(0, 'Must be positive').max(1000000, 'Too large')
+
+// Stage 3: Transform to cents
+const centsPrice = z.number().transform((n) => Math.round(n * 100))
+
+// Pipe them together - clear data flow
+const priceSchema = parsePrice.pipe(validPrice).pipe(centsPrice)
+
+// Type at each stage is clear:
+// string -> number (parsePrice)
+// number -> number (validPrice)
+// number -> number (centsPrice, but semantically cents)
+```
+
+**Coercion with validation:**
+
+```typescript
+// Without pipe - validation runs on raw input
+const schema1 = z.coerce.number().min(1)
+schema1.parse('')  // Passes! Empty string coerces to 0, but then... wait, 0 < 1
+
+// With pipe - validation runs on coerced value
+const schema2 = z.coerce.number().pipe(z.number().min(1))
+schema2.parse('')  // Fails correctly: 0 is less than 1
+```
+
+**Complex data transformation:**
+
+```typescript
+// Input: CSV string of emails
+// Output: Array of normalized, validated email objects
+
+const emailArraySchema = z
+  .string()
+  // Stage 1: Split CSV
+  .transform((s) => s.split(',').map((e) => e.trim()))
+  // Stage 2: Validate as email array
+  .pipe(z.array(z.string().email()))
+  // Stage 3: Transform to objects
+  .pipe(
+    z.array(z.string()).transform((emails) =>
+      emails.map((email) => ({
+        address: email.toLowerCase(),
+        domain: email.split('@')[1],
+      }))
+    )
+  )
+
+emailArraySchema.parse('John@Example.com, jane@test.com')
+// [
+//   { address: 'john@example.com', domain: 'Example.com' },
+//   { address: 'jane@test.com', domain: 'test.com' }
+// ]
+```
+
+**Type inference with pipe:**
+
+```typescript
+const schema = z.string().pipe(z.coerce.number()).pipe(z.number().positive())
+
+type Input = z.input<typeof schema>  // string
+type Output = z.output<typeof schema>  // number
+
+// Each pipe stage has clear input/output types
+```
+
+**When NOT to use this pattern:**
+- Simple single-stage validation (adds unnecessary complexity)
+- When `.refine()` chain is sufficient and readable
+
+Reference: [Zod API - pipe](https://zod.dev/api#pipe)
diff --git a/.agents/skills/zod/references/compose-preprocess.md b/.agents/skills/zod/references/compose-preprocess.md
new file mode 100644
index 0000000..6eb573c
--- /dev/null
+++ b/.agents/skills/zod/references/compose-preprocess.md
@@ -0,0 +1,142 @@
+---
+title: Use preprocess() for Data Normalization
+impact: MEDIUM
+impactDescription: Validating before cleaning data causes false rejections; preprocess() normalizes input before schema validation runs
+tags: compose, preprocess, normalize, cleaning
+---
+
+## Use preprocess() for Data Normalization
+
+When incoming data needs normalization before validation (trimming whitespace, parsing JSON strings, converting formats), use `z.preprocess()`. This runs a function on the raw input before Zod's type checking, allowing you to clean data that would otherwise fail validation.
+
+**Incorrect (validation fails on unnormalized data):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  config: z.object({
+    theme: z.string(),
+  }),
+})
+
+// Raw form data
+const formData = {
+  name: '  John Doe  ',  // Has whitespace
+  email: 'JOHN@EXAMPLE.COM',  // Uppercase
+  config: '{"theme": "dark"}',  // JSON string, not object
+}
+
+userSchema.parse(formData)
+// ZodError: Expected object, received string at "config"
+```
+
+**Correct (using preprocess):**
+
+```typescript
+import { z } from 'zod'
+
+// Preprocess normalizes before validation
+const trimmedString = z.preprocess(
+  (val) => (typeof val === 'string' ? val.trim() : val),
+  z.string()
+)
+
+const lowercaseEmail = z.preprocess(
+  (val) => (typeof val === 'string' ? val.toLowerCase().trim() : val),
+  z.string().email()
+)
+
+const jsonObject = z.preprocess(
+  (val) => {
+    if (typeof val === 'string') {
+      try {
+        return JSON.parse(val)
+      } catch {
+        return val  // Let Zod report the error
+      }
+    }
+    return val
+  },
+  z.object({ theme: z.string() })
+)
+
+const userSchema = z.object({
+  name: trimmedString.pipe(z.string().min(1)),
+  email: lowercaseEmail,
+  config: jsonObject,
+})
+
+const formData = {
+  name: '  John Doe  ',
+  email: 'JOHN@EXAMPLE.COM',
+  config: '{"theme": "dark"}',
+}
+
+const user = userSchema.parse(formData)
+// { name: 'John Doe', email: 'john@example.com', config: { theme: 'dark' } }
+```
+
+**Common preprocessing patterns:**
+
+```typescript
+// Trim all strings
+const trimmedString = z.preprocess(
+  (val) => (typeof val === 'string' ? val.trim() : val),
+  z.string()
+)
+
+// Parse numeric strings
+const numericString = z.preprocess(
+  (val) => (typeof val === 'string' ? Number(val) : val),
+  z.number()
+)
+
+// Parse boolean-like values
+const booleanLike = z.preprocess(
+  (val) => {
+    if (val === 'true' || val === '1' || val === 1) return true
+    if (val === 'false' || val === '0' || val === 0) return false
+    return val
+  },
+  z.boolean()
+)
+
+// Parse date strings
+const dateString = z.preprocess(
+  (val) => (typeof val === 'string' ? new Date(val) : val),
+  z.date()
+)
+
+// Split comma-separated strings into arrays
+const csvArray = z.preprocess(
+  (val) => (typeof val === 'string' ? val.split(',').map(s => s.trim()) : val),
+  z.array(z.string())
+)
+```
+
+**Preprocess vs Transform:**
+
+```typescript
+// preprocess() runs BEFORE type checking
+// Use for: Normalizing input format before validation
+z.preprocess(val => String(val).trim(), z.string().min(1))
+
+// transform() runs AFTER type checking
+// Use for: Converting validated data to different format
+z.string().transform(s => s.toUpperCase())
+
+// Order of operations:
+// 1. preprocess receives raw unknown input
+// 2. Zod validates the preprocessed value
+// 3. transform converts the validated value
+```
+
+**When NOT to use this pattern:**
+- When `.coerce` methods handle the conversion (simpler)
+- When transformation should happen after validation (use transform)
+- When normalization could hide validation errors
+
+Reference: [Zod API - preprocess](https://zod.dev/api#preprocess)
diff --git a/.agents/skills/zod/references/compose-shared-schemas.md b/.agents/skills/zod/references/compose-shared-schemas.md
new file mode 100644
index 0000000..6724fa3
--- /dev/null
+++ b/.agents/skills/zod/references/compose-shared-schemas.md
@@ -0,0 +1,137 @@
+---
+title: Extract Shared Schemas into Reusable Modules
+impact: MEDIUM
+impactDescription: Duplicating schemas across files leads to inconsistency; shared schemas ensure single source of truth
+tags: compose, reuse, modules, organization
+---
+
+## Extract Shared Schemas into Reusable Modules
+
+When the same schema pattern appears in multiple places, extract it into a shared module. This ensures consistency, reduces duplication, and makes changes propagate automatically across your codebase.
+
+**Incorrect (duplicating schemas):**
+
+```typescript
+// api/users.ts
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().min(1),
+  createdAt: z.date(),
+})
+
+// api/orders.ts
+import { z } from 'zod'
+
+const orderSchema = z.object({
+  id: z.string().uuid(),  // Duplicated
+  userId: z.string().uuid(),  // Same pattern
+  items: z.array(z.object({
+    productId: z.string().uuid(),  // Duplicated
+    quantity: z.number().int().positive(),
+  })),
+  createdAt: z.date(),  // Duplicated
+})
+
+// api/comments.ts
+import { z } from 'zod'
+
+const commentSchema = z.object({
+  id: z.string().uuid(),  // Same duplication
+  userId: z.string().uuid(),
+  content: z.string().min(1),
+  createdAt: z.date(),  // Inconsistency risk
+})
+```
+
+**Correct (shared schema modules):**
+
+```typescript
+// schemas/common.ts
+import { z } from 'zod'
+
+// Reusable ID types
+export const uuid = z.string().uuid()
+export type UUID = z.infer<typeof uuid>
+
+// Timestamps
+export const timestamps = z.object({
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+// Base entity with ID
+export const baseEntity = z.object({
+  id: uuid,
+}).merge(timestamps)
+
+export type BaseEntity = z.infer<typeof baseEntity>
+
+// Pagination
+export const paginationParams = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+})
+```
+
+```typescript
+// schemas/user.ts
+import { z } from 'zod'
+import { baseEntity, uuid } from './common'
+
+export const userSchema = baseEntity.extend({
+  email: z.string().email(),
+  name: z.string().min(1),
+})
+
+export type User = z.infer<typeof userSchema>
+```
+
+```typescript
+// schemas/order.ts
+import { z } from 'zod'
+import { baseEntity, uuid } from './common'
+
+const orderItemSchema = z.object({
+  productId: uuid,
+  quantity: z.number().int().positive(),
+})
+
+export const orderSchema = baseEntity.extend({
+  userId: uuid,
+  items: z.array(orderItemSchema).min(1),
+  total: z.number().positive(),
+})
+
+export type Order = z.infer<typeof orderSchema>
+```
+
+**Organizing schema modules:**
+
+```
+schemas/
+├── common.ts       # Shared primitives and base schemas
+├── user.ts         # User-related schemas
+├── order.ts        # Order-related schemas
+├── product.ts      # Product-related schemas
+└── index.ts        # Re-exports for convenience
+```
+
+```typescript
+// schemas/index.ts
+export * from './common'
+export * from './user'
+export * from './order'
+export * from './product'
+
+// Usage
+import { userSchema, orderSchema, uuid, type User } from '@/schemas'
+```
+
+**When NOT to use this pattern:**
+- One-off schemas used only in a single file
+- When schemas look similar but have different semantics (don't over-abstract)
+
+Reference: [Zod - Type Inference](https://zod.dev/api#type-inference)
diff --git a/.agents/skills/zod/references/error-avoid-throwing-in-refine.md b/.agents/skills/zod/references/error-avoid-throwing-in-refine.md
new file mode 100644
index 0000000..d5f5706
--- /dev/null
+++ b/.agents/skills/zod/references/error-avoid-throwing-in-refine.md
@@ -0,0 +1,127 @@
+---
+title: Return False Instead of Throwing in Refine
+impact: HIGH
+impactDescription: Throwing in refine stops validation early, hiding other errors; returning false allows Zod to collect all issues
+tags: error, refine, validation, best-practices
+---
+
+## Return False Instead of Throwing in Refine
+
+When using `.refine()` for custom validation, return `false` for invalid data instead of throwing an error. Throwing stops validation immediately, preventing Zod from collecting other validation errors. This results in poor UX where users fix one error only to discover another.
+
+**Incorrect (throwing in refine):**
+
+```typescript
+import { z } from 'zod'
+
+const passwordSchema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine((data) => {
+  if (data.password !== data.confirmPassword) {
+    // Throwing stops all further validation
+    throw new Error('Passwords do not match')
+  }
+  return true
+})
+
+const formSchema = z.object({
+  email: z.string().email(),
+  passwords: passwordSchema,
+  terms: z.boolean().refine((v) => v === true, 'Must accept terms'),
+})
+
+// If passwords don't match, user never learns about other errors
+formSchema.safeParse({
+  email: 'bad-email',
+  passwords: { password: '12345678', confirmPassword: 'different' },
+  terms: false,
+})
+// Only shows: "Passwords do not match"
+// Hidden: "Invalid email", "Must accept terms"
+```
+
+**Correct (returning false in refine):**
+
+```typescript
+import { z } from 'zod'
+
+const passwordSchema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(
+  (data) => data.password === data.confirmPassword,
+  { message: 'Passwords do not match', path: ['confirmPassword'] }
+)
+
+const formSchema = z.object({
+  email: z.string().email(),
+  passwords: passwordSchema,
+  terms: z.boolean().refine((v) => v === true, 'Must accept terms'),
+})
+
+// All errors are collected
+formSchema.safeParse({
+  email: 'bad-email',
+  passwords: { password: '12345678', confirmPassword: 'different' },
+  terms: false,
+})
+// Shows all errors:
+// - "Invalid email"
+// - "Passwords do not match"
+// - "Must accept terms"
+```
+
+**For multiple validation rules, use superRefine:**
+
+```typescript
+const passwordSchema = z.string().superRefine((password, ctx) => {
+  // Check multiple rules, report all failures
+  if (password.length < 8) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must be at least 8 characters',
+    })
+  }
+
+  if (!/[A-Z]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must contain an uppercase letter',
+    })
+  }
+
+  if (!/[0-9]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must contain a number',
+    })
+  }
+
+  // Don't return anything - issues are added via ctx
+})
+
+passwordSchema.safeParse('weak')
+// All three errors reported at once
+```
+
+**Correct pattern for async validation:**
+
+```typescript
+const schema = z.object({
+  email: z.string().email(),
+}).refine(
+  async (data) => {
+    // Return boolean, don't throw
+    const exists = await checkEmailExists(data.email)
+    return !exists
+  },
+  { message: 'Email already registered', path: ['email'] }
+)
+```
+
+**When NOT to use this pattern:**
+- When you need to abort validation entirely (security issues)
+- When subsequent validations depend on current check passing
+
+Reference: [Zod API - Refine](https://zod.dev/api#refine)
diff --git a/.agents/skills/zod/references/error-custom-messages.md b/.agents/skills/zod/references/error-custom-messages.md
new file mode 100644
index 0000000..efd30e7
--- /dev/null
+++ b/.agents/skills/zod/references/error-custom-messages.md
@@ -0,0 +1,118 @@
+---
+title: Provide Custom Error Messages
+impact: HIGH
+impactDescription: Default messages like "Expected string, received number" confuse users; custom messages like "Email is required" are actionable
+tags: error, messages, user-experience, validation
+---
+
+## Provide Custom Error Messages
+
+Zod's default error messages are technical and confusing for end users. Provide custom messages that are clear, specific, and actionable. This dramatically improves user experience when validation fails.
+
+**Incorrect (default error messages):**
+
+```typescript
+import { z } from 'zod'
+
+const signupSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  age: z.number().min(18),
+})
+
+signupSchema.parse({ email: 'bad', password: '123', age: 15 })
+// ZodError issues:
+// - "Invalid email"
+// - "String must contain at least 8 character(s)"
+// - "Number must be greater than or equal to 18"
+// Users see: "String must contain at least 8 character(s)" - what string?
+```
+
+**Correct (custom error messages):**
+
+```typescript
+import { z } from 'zod'
+
+const signupSchema = z.object({
+  email: z.string({
+    required_error: 'Email is required',
+    invalid_type_error: 'Email must be text',
+  }).email('Please enter a valid email address'),
+
+  password: z.string({
+    required_error: 'Password is required',
+  }).min(8, 'Password must be at least 8 characters'),
+
+  age: z.number({
+    required_error: 'Age is required',
+    invalid_type_error: 'Age must be a number',
+  }).min(18, 'You must be at least 18 years old'),
+})
+
+signupSchema.parse({ email: 'bad', password: '123', age: 15 })
+// ZodError issues:
+// - "Please enter a valid email address"
+// - "Password must be at least 8 characters"
+// - "You must be at least 18 years old"
+```
+
+**Message types and when they trigger:**
+
+```typescript
+const schema = z.string({
+  // When field is undefined
+  required_error: 'This field is required',
+
+  // When field is wrong type (e.g., number instead of string)
+  invalid_type_error: 'This field must be text',
+
+  // Fallback for any other error
+  message: 'Invalid value',
+})
+.min(1, 'Cannot be empty')  // When length < 1
+.max(100, 'Too long')  // When length > 100
+.email('Invalid email format')  // When format fails
+```
+
+**Using error maps for consistent messaging:**
+
+```typescript
+const customErrorMap: z.ZodErrorMap = (issue, ctx) => {
+  // Customize messages by error code
+  if (issue.code === z.ZodIssueCode.too_small) {
+    if (issue.type === 'string') {
+      return { message: `Must be at least ${issue.minimum} characters` }
+    }
+    if (issue.type === 'number') {
+      return { message: `Must be at least ${issue.minimum}` }
+    }
+  }
+
+  if (issue.code === z.ZodIssueCode.invalid_type) {
+    if (issue.expected === 'string') {
+      return { message: 'Must be text' }
+    }
+  }
+
+  // Default to Zod's message
+  return { message: ctx.defaultError }
+}
+
+// Apply globally
+z.setErrorMap(customErrorMap)
+
+// Or per-schema
+schema.parse(data, { errorMap: customErrorMap })
+```
+
+**Good error message principles:**
+- Say what's wrong: "Password too short" not "Invalid password"
+- Say how to fix it: "at least 8 characters" not just "too short"
+- Use user's language: "email" not "string field at path .email"
+- Be specific: "Must be a positive number" not "Invalid"
+
+**When NOT to use this pattern:**
+- Internal development scripts where technical errors are fine
+- When you'll map errors to user-facing messages in the UI layer
+
+Reference: [Zod Error Customization](https://zod.dev/error-customization)
diff --git a/.agents/skills/zod/references/error-i18n.md b/.agents/skills/zod/references/error-i18n.md
new file mode 100644
index 0000000..30d2021
--- /dev/null
+++ b/.agents/skills/zod/references/error-i18n.md
@@ -0,0 +1,145 @@
+---
+title: Implement Internationalized Error Messages
+impact: HIGH
+impactDescription: Hardcoded English messages exclude non-English users; error maps enable localized messages for global applications
+tags: error, i18n, localization, internationalization
+---
+
+## Implement Internationalized Error Messages
+
+Hardcoded error messages in English exclude users who speak other languages. Use Zod's error map feature to provide localized messages based on user locale, making your application accessible globally.
+
+**Incorrect (hardcoded English messages):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email address'),
+  age: z.number().min(18, 'You must be at least 18 years old'),
+})
+
+// French users see English errors - poor UX
+```
+
+**Correct (localized error messages):**
+
+```typescript
+import { z } from 'zod'
+
+// Translation dictionaries
+const translations = {
+  en: {
+    required: 'This field is required',
+    invalidEmail: 'Please enter a valid email address',
+    tooShort: (min: number) => `Must be at least ${min} characters`,
+    tooYoung: (min: number) => `You must be at least ${min} years old`,
+  },
+  fr: {
+    required: 'Ce champ est obligatoire',
+    invalidEmail: 'Veuillez entrer une adresse email valide',
+    tooShort: (min: number) => `Doit contenir au moins ${min} caractères`,
+    tooYoung: (min: number) => `Vous devez avoir au moins ${min} ans`,
+  },
+  es: {
+    required: 'Este campo es requerido',
+    invalidEmail: 'Por favor ingrese un correo electrónico válido',
+    tooShort: (min: number) => `Debe tener al menos ${min} caracteres`,
+    tooYoung: (min: number) => `Debes tener al menos ${min} años`,
+  },
+} as const
+
+type Locale = keyof typeof translations
+
+function createErrorMap(locale: Locale): z.ZodErrorMap {
+  const t = translations[locale]
+
+  return (issue, ctx) => {
+    switch (issue.code) {
+      case z.ZodIssueCode.invalid_type:
+        if (issue.received === 'undefined') {
+          return { message: t.required }
+        }
+        break
+
+      case z.ZodIssueCode.invalid_string:
+        if (issue.validation === 'email') {
+          return { message: t.invalidEmail }
+        }
+        break
+
+      case z.ZodIssueCode.too_small:
+        if (issue.type === 'string') {
+          return { message: t.tooShort(issue.minimum as number) }
+        }
+        if (issue.type === 'number') {
+          return { message: t.tooYoung(issue.minimum as number) }
+        }
+        break
+    }
+
+    return { message: ctx.defaultError }
+  }
+}
+
+// Usage with user's locale
+const userLocale: Locale = 'fr'
+const errorMap = createErrorMap(userLocale)
+
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().min(18),
+})
+
+const result = userSchema.safeParse(
+  { name: '', email: 'bad', age: 15 },
+  { errorMap }
+)
+
+// French error messages:
+// - "Ce champ est obligatoire"
+// - "Veuillez entrer une adresse email valide"
+// - "Vous devez avoir au moins 18 ans"
+```
+
+**Setting error map globally:**
+
+```typescript
+// At application startup
+const userLocale = getUserLocale()  // From cookie, header, etc.
+z.setErrorMap(createErrorMap(userLocale))
+
+// All schemas now use localized messages
+```
+
+**With i18n libraries (react-intl, i18next):**
+
+```typescript
+import { useIntl } from 'react-intl'
+
+function useZodErrorMap() {
+  const intl = useIntl()
+
+  return (issue: z.ZodIssue, ctx: z.ErrorMapCtx) => {
+    switch (issue.code) {
+      case z.ZodIssueCode.too_small:
+        return {
+          message: intl.formatMessage(
+            { id: 'validation.tooShort' },
+            { min: issue.minimum }
+          )
+        }
+      // ...
+    }
+    return { message: ctx.defaultError }
+  }
+}
+```
+
+**When NOT to use this pattern:**
+- Internal tools used only by your team
+- Single-language applications
+
+Reference: [Zod Error Customization - Internationalization](https://zod.dev/error-customization#internationalization)
diff --git a/.agents/skills/zod/references/error-path-for-nested.md b/.agents/skills/zod/references/error-path-for-nested.md
new file mode 100644
index 0000000..3ec49cc
--- /dev/null
+++ b/.agents/skills/zod/references/error-path-for-nested.md
@@ -0,0 +1,130 @@
+---
+title: Use issue.path for Nested Error Location
+impact: HIGH
+impactDescription: Without path information, users can't identify which nested field failed; path provides exact location in complex objects
+tags: error, path, nested, debugging
+---
+
+## Use issue.path for Nested Error Location
+
+When validating nested objects or arrays, `issue.path` tells you exactly where the error occurred. This is essential for highlighting the correct form field or providing precise error messages in complex data structures.
+
+**Incorrect (ignoring path information):**
+
+```typescript
+import { z } from 'zod'
+
+const orderSchema = z.object({
+  customer: z.object({
+    name: z.string().min(1, 'Name required'),
+    address: z.object({
+      street: z.string().min(1, 'Street required'),
+      city: z.string().min(1, 'City required'),
+    }),
+  }),
+  items: z.array(z.object({
+    productId: z.string(),
+    quantity: z.number().positive('Quantity must be positive'),
+  })),
+})
+
+const result = orderSchema.safeParse({
+  customer: { name: '', address: { street: '', city: '' } },
+  items: [{ productId: 'abc', quantity: -1 }],
+})
+
+if (!result.success) {
+  // Only showing message, not WHERE the error is
+  result.error.issues.forEach(issue => {
+    console.log(issue.message)  // 'Name required', 'Street required', 'Quantity must be positive'
+    // User: "Which quantity? Which field?"
+  })
+}
+```
+
+**Correct (using path information):**
+
+```typescript
+import { z } from 'zod'
+
+const orderSchema = z.object({
+  customer: z.object({
+    name: z.string().min(1, 'Name required'),
+    address: z.object({
+      street: z.string().min(1, 'Street required'),
+      city: z.string().min(1, 'City required'),
+    }),
+  }),
+  items: z.array(z.object({
+    productId: z.string(),
+    quantity: z.number().positive('Quantity must be positive'),
+  })),
+})
+
+const result = orderSchema.safeParse({
+  customer: { name: '', address: { street: '', city: '' } },
+  items: [{ productId: 'abc', quantity: -1 }],
+})
+
+if (!result.success) {
+  result.error.issues.forEach(issue => {
+    // path is an array of keys/indices
+    console.log(`${issue.path.join('.')}: ${issue.message}`)
+    // 'customer.name: Name required'
+    // 'customer.address.street: Street required'
+    // 'customer.address.city: City required'
+    // 'items.0.quantity: Quantity must be positive'
+  })
+}
+```
+
+**Building field-specific error mapping:**
+
+```typescript
+function mapErrorsToFields(error: z.ZodError) {
+  const fieldErrors: Map<string, string[]> = new Map()
+
+  for (const issue of error.issues) {
+    const fieldPath = issue.path.join('.')
+    const existing = fieldErrors.get(fieldPath) ?? []
+    fieldErrors.set(fieldPath, [...existing, issue.message])
+  }
+
+  return fieldErrors
+}
+
+// Usage
+const errors = mapErrorsToFields(result.error)
+errors.get('customer.name')  // ['Name required']
+errors.get('items.0.quantity')  // ['Quantity must be positive']
+```
+
+**For array items, get index from path:**
+
+```typescript
+const itemsWithErrors: Set<number> = new Set()
+
+result.error.issues.forEach(issue => {
+  if (issue.path[0] === 'items' && typeof issue.path[1] === 'number') {
+    itemsWithErrors.add(issue.path[1])
+  }
+})
+
+// Highlight items at indices: Set { 0 }
+```
+
+**Using path with format():**
+
+```typescript
+const formatted = result.error.format()
+
+// Access errors at any path level
+formatted.customer?.address?.city?._errors  // ['City required']
+formatted.items?.[0]?.quantity?._errors  // ['Quantity must be positive']
+```
+
+**When NOT to use this pattern:**
+- Flat objects where field name is obvious
+- When using form libraries that handle path mapping
+
+Reference: [Zod Error Handling](https://zod.dev/error-handling)
diff --git a/.agents/skills/zod/references/error-use-flatten.md b/.agents/skills/zod/references/error-use-flatten.md
new file mode 100644
index 0000000..99557f5
--- /dev/null
+++ b/.agents/skills/zod/references/error-use-flatten.md
@@ -0,0 +1,131 @@
+---
+title: Use flatten() for Form Error Display
+impact: HIGH
+impactDescription: Raw ZodError.issues requires manual path parsing; flatten() provides field-keyed errors ready for form display
+tags: error, flatten, forms, user-experience
+---
+
+## Use flatten() for Form Error Display
+
+`ZodError.issues` is an array that requires manual processing to map errors to form fields. `ZodError.flatten()` returns an object with `fieldErrors` keyed by field name, ready for form libraries and UI display.
+
+**Incorrect (manual issue processing):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password too short'),
+  profile: z.object({
+    name: z.string().min(1, 'Name required'),
+  }),
+})
+
+function getFieldErrors(error: z.ZodError) {
+  const errors: Record<string, string> = {}
+
+  for (const issue of error.issues) {
+    // Manual path joining - error prone
+    const field = issue.path.join('.')
+    if (!errors[field]) {
+      errors[field] = issue.message
+    }
+  }
+
+  return errors
+}
+
+const result = formSchema.safeParse(data)
+if (!result.success) {
+  const errors = getFieldErrors(result.error)
+  // { email: 'Invalid email', 'profile.name': 'Name required' }
+}
+```
+
+**Correct (using flatten):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password too short'),
+  profile: z.object({
+    name: z.string().min(1, 'Name required'),
+  }),
+})
+
+const result = formSchema.safeParse(data)
+
+if (!result.success) {
+  const { formErrors, fieldErrors } = result.error.flatten()
+
+  // formErrors: string[] - top-level errors (from .refine on the object)
+  // fieldErrors: { [key]: string[] } - errors by field
+
+  // Ready for form display
+  console.log(fieldErrors)
+  // {
+  //   email: ['Invalid email'],
+  //   password: ['Password too short'],
+  //   'profile.name': ['Name required']
+  // }
+}
+```
+
+**With React Hook Form:**
+
+```typescript
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useForm } from 'react-hook-form'
+
+const { register, formState: { errors } } = useForm({
+  resolver: zodResolver(formSchema),
+})
+
+// errors are already flattened by the resolver
+// <input {...register('email')} />
+// {errors.email && <span>{errors.email.message}</span>}
+```
+
+**Customizing flatten output:**
+
+```typescript
+const flattened = result.error.flatten((issue) => ({
+  message: issue.message,
+  code: issue.code,
+}))
+
+// fieldErrors now contains custom objects
+// {
+//   email: [{ message: 'Invalid email', code: 'invalid_string' }],
+// }
+```
+
+**For deeply nested objects, use format():**
+
+```typescript
+const result = formSchema.safeParse(data)
+
+if (!result.success) {
+  const formatted = result.error.format()
+  // {
+  //   _errors: [],
+  //   email: { _errors: ['Invalid email'] },
+  //   profile: {
+  //     _errors: [],
+  //     name: { _errors: ['Name required'] }
+  //   }
+  // }
+
+  // Access nested errors naturally
+  formatted.profile?.name?._errors  // ['Name required']
+}
+```
+
+**When NOT to use this pattern:**
+- When you need access to full issue metadata (code, path as array)
+- When using a form library that expects different error format
+
+Reference: [Zod Error Handling](https://zod.dev/error-handling)
diff --git a/.agents/skills/zod/references/object-discriminated-unions.md b/.agents/skills/zod/references/object-discriminated-unions.md
new file mode 100644
index 0000000..c03735b
--- /dev/null
+++ b/.agents/skills/zod/references/object-discriminated-unions.md
@@ -0,0 +1,138 @@
+---
+title: Use Discriminated Unions for Type Narrowing
+impact: MEDIUM-HIGH
+impactDescription: Regular unions require manual type guards; discriminated unions enable TypeScript's automatic narrowing and Zod's optimized parsing
+tags: object, discriminatedUnion, narrowing, typescript
+---
+
+## Use Discriminated Unions for Type Narrowing
+
+When a field's type depends on another field's value (e.g., `type: 'success'` means `data` exists, `type: 'error'` means `error` exists), use `z.discriminatedUnion()`. This enables TypeScript's automatic type narrowing and Zod's optimized O(1) parsing instead of trying each variant.
+
+**Incorrect (regular union - no automatic narrowing):**
+
+```typescript
+import { z } from 'zod'
+
+const successSchema = z.object({
+  type: z.literal('success'),
+  data: z.object({ id: z.string() }),
+})
+
+const errorSchema = z.object({
+  type: z.literal('error'),
+  message: z.string(),
+})
+
+// Regular union - Zod tries each option in order
+const responseSchema = z.union([successSchema, errorSchema])
+
+type Response = z.infer<typeof responseSchema>
+
+function handleResponse(response: Response) {
+  // TypeScript doesn't narrow automatically
+  if (response.type === 'success') {
+    response.data  // Error: Property 'data' does not exist on type 'Response'
+    // Must cast or use type guards
+  }
+}
+```
+
+**Correct (discriminated union):**
+
+```typescript
+import { z } from 'zod'
+
+const successSchema = z.object({
+  type: z.literal('success'),
+  data: z.object({ id: z.string() }),
+})
+
+const errorSchema = z.object({
+  type: z.literal('error'),
+  message: z.string(),
+})
+
+// Discriminated union - Zod uses 'type' field for O(1) dispatch
+const responseSchema = z.discriminatedUnion('type', [
+  successSchema,
+  errorSchema,
+])
+
+type Response = z.infer<typeof responseSchema>
+
+function handleResponse(response: Response) {
+  // TypeScript narrows automatically!
+  if (response.type === 'success') {
+    response.data.id  // Works - TypeScript knows data exists
+  } else {
+    response.message  // Works - TypeScript knows message exists
+  }
+}
+```
+
+**Common use cases:**
+
+```typescript
+// API responses
+const apiResponse = z.discriminatedUnion('status', [
+  z.object({ status: z.literal('success'), data: z.unknown() }),
+  z.object({ status: z.literal('error'), error: z.string(), code: z.number() }),
+  z.object({ status: z.literal('loading') }),
+])
+
+// Event types
+const event = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
+  z.object({ type: z.literal('keypress'), key: z.string() }),
+  z.object({ type: z.literal('scroll'), delta: z.number() }),
+])
+
+// Database records with polymorphic types
+const notification = z.discriminatedUnion('channel', [
+  z.object({ channel: z.literal('email'), address: z.string().email() }),
+  z.object({ channel: z.literal('sms'), phoneNumber: z.string() }),
+  z.object({ channel: z.literal('push'), deviceToken: z.string() }),
+])
+```
+
+**Type-safe handling:**
+
+```typescript
+const paymentSchema = z.discriminatedUnion('method', [
+  z.object({
+    method: z.literal('card'),
+    cardNumber: z.string(),
+    expiryDate: z.string(),
+  }),
+  z.object({
+    method: z.literal('bank'),
+    accountNumber: z.string(),
+    routingNumber: z.string(),
+  }),
+  z.object({
+    method: z.literal('crypto'),
+    walletAddress: z.string(),
+  }),
+])
+
+type Payment = z.infer<typeof paymentSchema>
+
+function processPayment(payment: Payment) {
+  switch (payment.method) {
+    case 'card':
+      return chargeCard(payment.cardNumber, payment.expiryDate)
+    case 'bank':
+      return initiateBankTransfer(payment.accountNumber, payment.routingNumber)
+    case 'crypto':
+      return sendCrypto(payment.walletAddress)
+    // TypeScript exhaustiveness check - no default needed
+  }
+}
+```
+
+**When NOT to use this pattern:**
+- When variants don't share a common discriminator field
+- When the discriminator isn't a literal type (use regular union)
+
+Reference: [Zod API - Discriminated Unions](https://zod.dev/api#discriminated-unions)
diff --git a/.agents/skills/zod/references/object-extend-for-composition.md b/.agents/skills/zod/references/object-extend-for-composition.md
new file mode 100644
index 0000000..abd09f8
--- /dev/null
+++ b/.agents/skills/zod/references/object-extend-for-composition.md
@@ -0,0 +1,147 @@
+---
+title: Use extend() for Adding Fields
+impact: MEDIUM-HIGH
+impactDescription: Merging objects manually loses type information; extend() preserves types and allows overriding fields safely
+tags: object, extend, composition, inheritance
+---
+
+## Use extend() for Adding Fields
+
+When building on existing schemas, use `.extend()` to add new fields rather than manually spreading. Extend preserves type information, allows overriding existing fields, and keeps the schema relationship explicit.
+
+**Incorrect (manual object spreading):**
+
+```typescript
+import { z } from 'zod'
+
+const baseUserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+// Manual spreading loses Zod's schema relationship
+const adminUserSchema = z.object({
+  ...baseUserSchema.shape,  // Accessing internal .shape
+  role: z.literal('admin'),
+  permissions: z.array(z.string()),
+})
+
+// Problems:
+// 1. If baseUserSchema changes, TypeScript might not catch issues
+// 2. Can't override fields easily
+// 3. Loses schema methods and metadata
+```
+
+**Correct (using extend):**
+
+```typescript
+import { z } from 'zod'
+
+const baseUserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+// Extend to add fields
+const adminUserSchema = baseUserSchema.extend({
+  role: z.literal('admin'),
+  permissions: z.array(z.string()),
+})
+
+type AdminUser = z.infer<typeof adminUserSchema>
+// {
+//   id: string;
+//   name: string;
+//   email: string;
+//   role: 'admin';
+//   permissions: string[];
+// }
+
+// Override existing fields
+const strictEmailSchema = baseUserSchema.extend({
+  email: z.string().email().endsWith('@company.com'),  // Stricter validation
+})
+```
+
+**Building hierarchies with extend:**
+
+```typescript
+// Base entity with common fields
+const entitySchema = z.object({
+  id: z.string().uuid(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+// User extends entity
+const userSchema = entitySchema.extend({
+  email: z.string().email(),
+  name: z.string(),
+})
+
+// Product extends entity
+const productSchema = entitySchema.extend({
+  name: z.string(),
+  price: z.number().positive(),
+  sku: z.string(),
+})
+
+// Order extends entity with references
+const orderSchema = entitySchema.extend({
+  userId: z.string().uuid(),
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive(),
+  })),
+  total: z.number().positive(),
+})
+```
+
+**Combining extend with other methods:**
+
+```typescript
+const baseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+})
+
+// Create input: no id, add password
+const createSchema = baseSchema
+  .omit({ id: true })
+  .extend({
+    password: z.string().min(8),
+  })
+
+// Update input: all optional except id
+const updateSchema = baseSchema
+  .partial()
+  .extend({
+    id: z.string(),  // Override to make required
+  })
+```
+
+**Merge for combining independent schemas:**
+
+```typescript
+const addressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+})
+
+const contactSchema = z.object({
+  email: z.string().email(),
+  phone: z.string(),
+})
+
+// Merge combines two schemas (both required)
+const customerSchema = addressSchema.merge(contactSchema)
+// { street: string; city: string; email: string; phone: string }
+```
+
+**When NOT to use this pattern:**
+- When schemas are genuinely independent (use merge or intersection)
+- When you need to remove fields (use omit)
+
+Reference: [Zod API - extend](https://zod.dev/api#extend)
diff --git a/.agents/skills/zod/references/object-optional-vs-nullable.md b/.agents/skills/zod/references/object-optional-vs-nullable.md
new file mode 100644
index 0000000..3b94c28
--- /dev/null
+++ b/.agents/skills/zod/references/object-optional-vs-nullable.md
@@ -0,0 +1,117 @@
+---
+title: Distinguish optional() from nullable()
+impact: MEDIUM-HIGH
+impactDescription: Confusing undefined and null semantics causes "property does not exist" vs "property is null" bugs; choose deliberately
+tags: object, optional, nullable, undefined
+---
+
+## Distinguish optional() from nullable()
+
+`.optional()` allows `undefined` (field can be missing), while `.nullable()` allows `null` (field must be present but can be null). Choosing the wrong one causes subtle bugs in database operations, JSON serialization, and API contracts.
+
+**Incorrect (confusing optional and nullable):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string(),
+  // Intended: field might not exist
+  nickname: z.string().nullable(),  // Wrong! Requires field to be present
+  // Intended: field exists but might be null
+  deletedAt: z.date().optional(),  // Wrong! Allows field to be missing
+})
+
+// This fails - nickname is required
+userSchema.parse({ name: 'John' })
+// ZodError: Required at "nickname"
+
+// This passes but loses semantic meaning
+userSchema.parse({ name: 'John', nickname: null, deletedAt: undefined })
+// Is deletedAt undefined because not deleted, or because data is incomplete?
+```
+
+**Correct (using optional and nullable deliberately):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string(),
+
+  // optional() - field might not exist in the object
+  nickname: z.string().optional(),
+  // Type: string | undefined
+
+  // nullable() - field must exist, but value can be null
+  deletedAt: z.date().nullable(),
+  // Type: Date | null
+})
+
+// Field can be omitted
+userSchema.parse({ name: 'John', deletedAt: null })  // Valid
+
+// Field must be present (even if null)
+userSchema.parse({ name: 'John', nickname: 'Johnny' })
+// ZodError: Required at "deletedAt"
+
+// Correct usage
+userSchema.parse({
+  name: 'John',
+  nickname: 'Johnny',  // Or omit entirely
+  deletedAt: null,  // Must be present, null means "not deleted"
+})
+```
+
+**When to use each:**
+
+```typescript
+// optional() - field may not exist
+// Use for: Optional form fields, sparse updates, optional config
+z.object({
+  bio: z.string().optional(),  // User might not have filled this
+  middleName: z.string().optional(),  // Not everyone has one
+})
+
+// nullable() - field exists but value can be null
+// Use for: Database nullable columns, "cleared" values, explicit absence
+z.object({
+  deletedAt: z.date().nullable(),  // null = not deleted, Date = when deleted
+  parentId: z.string().nullable(),  // null = root node, string = has parent
+  approvedBy: z.string().nullable(),  // null = pending, string = approver
+})
+
+// nullish() - either undefined or null
+// Use for: Lenient APIs, legacy data, optional nullable DB columns
+z.object({
+  legacyField: z.string().nullish(),  // string | null | undefined
+})
+```
+
+**API response patterns:**
+
+```typescript
+// API includes null for "no value" (good for explicit absence)
+const apiResponseSchema = z.object({
+  data: z.object({
+    user: z.object({
+      name: z.string(),
+      avatar: z.string().nullable(),  // null = no avatar set
+    }).nullable(),  // null = user not found
+  }),
+})
+
+// Type: { data: { user: { name: string; avatar: string | null } | null } }
+
+// Partial updates send only changed fields
+const updateSchema = z.object({
+  name: z.string().optional(),  // Omitted = don't change
+  avatar: z.string().nullable().optional(),  // null = clear avatar
+})
+```
+
+**When NOT to use this pattern:**
+- When interacting with systems that treat null and undefined as equivalent
+- When using nullish() for maximum flexibility is acceptable
+
+Reference: [Zod API - optional/nullable](https://zod.dev/api#optional)
diff --git a/.agents/skills/zod/references/object-partial-for-updates.md b/.agents/skills/zod/references/object-partial-for-updates.md
new file mode 100644
index 0000000..b07bfdd
--- /dev/null
+++ b/.agents/skills/zod/references/object-partial-for-updates.md
@@ -0,0 +1,123 @@
+---
+title: Use partial() for Update Schemas
+impact: MEDIUM-HIGH
+impactDescription: Creating separate update schemas duplicates definitions; partial() derives update schema from base, staying in sync
+tags: object, partial, update, patch
+---
+
+## Use partial() for Update Schemas
+
+When handling PATCH/PUT updates, you need a schema where all fields are optional. Instead of duplicating the schema with optional fields, use `.partial()` to derive it from your base schema. This keeps both schemas in sync automatically.
+
+**Incorrect (duplicating schemas):**
+
+```typescript
+import { z } from 'zod'
+
+// Base schema
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+  role: z.enum(['admin', 'user']),
+})
+
+// Manually duplicated for updates - will drift!
+const updateUserSchema = z.object({
+  name: z.string().min(1).optional(),
+  email: z.string().email().optional(),
+  age: z.number().int().positive().optional(),
+  // Forgot to add role - schemas out of sync!
+})
+
+// Later, you add a field to userSchema but forget updateUserSchema
+// Now updates silently ignore the new field
+```
+
+**Correct (using partial):**
+
+```typescript
+import { z } from 'zod'
+
+// Base schema - single source of truth
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+  role: z.enum(['admin', 'user']),
+})
+
+// All fields optional for updates
+const updateUserSchema = userSchema.partial()
+
+type User = z.infer<typeof userSchema>
+// { name: string; email: string; age: number; role: 'admin' | 'user' }
+
+type UpdateUser = z.infer<typeof updateUserSchema>
+// { name?: string; email?: string; age?: number; role?: 'admin' | 'user' }
+
+// Validate partial updates
+updateUserSchema.parse({ email: 'new@example.com' })  // Valid
+updateUserSchema.parse({})  // Valid - all fields optional
+```
+
+**Partial specific fields only:**
+
+```typescript
+// Only name and email are optional for updates
+const updateUserSchema = userSchema.partial({
+  name: true,
+  email: true,
+})
+
+type UpdateUser = z.infer<typeof updateUserSchema>
+// { name?: string; email?: string; age: number; role: 'admin' | 'user' }
+// age and role still required
+```
+
+**Deep partial for nested objects:**
+
+```typescript
+const addressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+  country: z.string(),
+})
+
+const userSchema = z.object({
+  name: z.string(),
+  address: addressSchema,
+})
+
+// .partial() only makes top-level fields optional
+const shallowPartial = userSchema.partial()
+// { name?: string; address?: { street: string; city: string; country: string } }
+// If address is provided, all its fields are still required!
+
+// Use deepPartial for nested optionality
+const deepPartialSchema = userSchema.deepPartial()
+// { name?: string; address?: { street?: string; city?: string; country?: string } }
+```
+
+**Combining with required() for create vs update:**
+
+```typescript
+const baseSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.date(),
+})
+
+// Create: id and createdAt are generated, rest required
+const createSchema = baseSchema.omit({ id: true, createdAt: true })
+
+// Update: all user-editable fields optional
+const updateSchema = baseSchema.partial().omit({ id: true, createdAt: true })
+```
+
+**When NOT to use this pattern:**
+- When update logic differs significantly from create (different validations)
+- When using GraphQL with explicit input types
+
+Reference: [Zod API - partial](https://zod.dev/api#partial)
diff --git a/.agents/skills/zod/references/object-pick-omit.md b/.agents/skills/zod/references/object-pick-omit.md
new file mode 100644
index 0000000..5a1b11e
--- /dev/null
+++ b/.agents/skills/zod/references/object-pick-omit.md
@@ -0,0 +1,146 @@
+---
+title: Use pick() and omit() for Schema Variants
+impact: MEDIUM-HIGH
+impactDescription: Copying fields between schemas creates duplication; pick/omit derive variants that stay in sync with base schema
+tags: object, pick, omit, variants
+---
+
+## Use pick() and omit() for Schema Variants
+
+When you need different views of the same data (public vs private, create vs response), use `.pick()` and `.omit()` instead of duplicating fields. This ensures derived schemas stay in sync with the base schema.
+
+**Incorrect (duplicating for variants):**
+
+```typescript
+import { z } from 'zod'
+
+// Full user schema
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  passwordHash: z.string(),
+  name: z.string(),
+  createdAt: z.date(),
+  isAdmin: z.boolean(),
+})
+
+// Public view - manually duplicated
+const publicUserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  // Forgot email - now users can't see it
+  // Added avatar field - doesn't exist in base schema
+  avatar: z.string().optional(),
+})
+
+// Create input - manually duplicated
+const createUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),  // Different from passwordHash
+  name: z.string(),
+  // Missing isAdmin - can't set on create? Intentional?
+})
+```
+
+**Correct (using pick and omit):**
+
+```typescript
+import { z } from 'zod'
+
+// Full user schema - single source of truth
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  passwordHash: z.string(),
+  name: z.string(),
+  createdAt: z.date(),
+  isAdmin: z.boolean(),
+})
+
+// Public view - explicitly pick public fields
+const publicUserSchema = userSchema.pick({
+  id: true,
+  email: true,
+  name: true,
+})
+
+type PublicUser = z.infer<typeof publicUserSchema>
+// { id: string; email: string; name: string }
+
+// API response - omit sensitive fields
+const userResponseSchema = userSchema.omit({
+  passwordHash: true,
+})
+
+type UserResponse = z.infer<typeof userResponseSchema>
+// { id: string; email: string; name: string; createdAt: Date; isAdmin: boolean }
+
+// Create input - omit generated fields
+const createUserInputSchema = userSchema
+  .omit({ id: true, createdAt: true, passwordHash: true })
+  .extend({
+    password: z.string().min(8),  // Add password (different from hash)
+  })
+
+type CreateUserInput = z.infer<typeof createUserInputSchema>
+// { email: string; name: string; isAdmin: boolean; password: string }
+```
+
+**Common patterns:**
+
+```typescript
+// Database row → API response (hide internal fields)
+const dbRowSchema = z.object({
+  id: z.number(),
+  public_id: z.string().uuid(),
+  email: z.string(),
+  password_hash: z.string(),
+  internal_notes: z.string(),
+  created_at: z.date(),
+})
+
+const apiResponseSchema = dbRowSchema.omit({
+  id: true,  // Internal DB id
+  password_hash: true,  // Sensitive
+  internal_notes: true,  // Staff only
+})
+
+// Form data → Database insert (add generated fields)
+const formSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+})
+
+const dbInsertSchema = formSchema.extend({
+  id: z.string().uuid(),
+  authorId: z.string().uuid(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+```
+
+**Chaining operations:**
+
+```typescript
+const baseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  role: z.enum(['admin', 'user']),
+  secret: z.string(),
+})
+
+// Combine pick, omit, partial, extend
+const updateSchema = baseSchema
+  .omit({ id: true, secret: true })  // Remove immutable/sensitive
+  .partial()  // Make all optional for updates
+  .extend({
+    updatedAt: z.date().optional(),  // Add update timestamp
+  })
+```
+
+**When NOT to use this pattern:**
+- When derived schemas need different validation rules (not just different fields)
+- When the relationship between schemas is not subset/superset
+
+Reference: [Zod API - pick/omit](https://zod.dev/api#pickomit)
diff --git a/.agents/skills/zod/references/object-strict-vs-strip.md b/.agents/skills/zod/references/object-strict-vs-strip.md
new file mode 100644
index 0000000..546db7b
--- /dev/null
+++ b/.agents/skills/zod/references/object-strict-vs-strip.md
@@ -0,0 +1,109 @@
+---
+title: Choose strict() vs strip() for Unknown Keys
+impact: MEDIUM-HIGH
+impactDescription: Default passthrough mode leaks unexpected data; strict() catches schema mismatches, strip() silently removes extras
+tags: object, strict, strip, passthrough
+---
+
+## Choose strict() vs strip() for Unknown Keys
+
+By default, Zod objects use `.strip()` behavior, silently removing unrecognized keys. This can hide schema/data mismatches. Use `.strict()` to reject unknown keys (catching errors) or explicitly use `.strip()` to document the intention.
+
+**Default behavior (strip - silent removal):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+const input = {
+  id: '123',
+  name: 'John',
+  role: 'admin',  // Extra field
+  secretToken: 'abc123',  // Another extra field
+}
+
+const user = userSchema.parse(input)
+// { id: '123', name: 'John' }
+// Extra fields silently removed - was this intentional?
+```
+
+**Using strict() to catch schema mismatches:**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+}).strict()
+
+const input = {
+  id: '123',
+  name: 'John',
+  role: 'admin',
+}
+
+userSchema.parse(input)
+// ZodError: Unrecognized key(s) in object: 'role'
+
+// This catches:
+// - Client sending fields the server doesn't expect
+// - Schema out of sync with actual data structure
+// - Typos in field names
+```
+
+**When to use each mode:**
+
+```typescript
+// strict() - Catch unexpected data (API contracts)
+const apiRequestSchema = z.object({
+  action: z.string(),
+  payload: z.unknown(),
+}).strict()  // Fail if client sends unknown fields
+
+// strip() - Clean up data (explicit intention)
+const dbInsertSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+}).strip()  // Explicitly remove metadata before insert
+
+// passthrough() - Keep everything (pass-through proxy)
+const proxySchema = z.object({
+  id: z.string(),
+}).passthrough()  // Keep fields we don't validate
+
+const input = { id: '123', extra: 'data' }
+proxySchema.parse(input)  // { id: '123', extra: 'data' }
+```
+
+**Choosing the right mode:**
+
+| Mode | Behavior | Use When |
+|------|----------|----------|
+| `.strict()` | Reject unknown keys | API contracts, security-sensitive, debugging |
+| `.strip()` (default) | Remove unknown keys | General validation, data cleaning |
+| `.passthrough()` | Keep unknown keys | Proxying, partial validation |
+
+**Handling specific unknown keys:**
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  name: z.string(),
+}).catchall(z.unknown())  // Allow any additional fields of any type
+
+// Or restrict additional fields to specific type
+const metadataSchema = z.object({
+  id: z.string(),
+}).catchall(z.string())  // Only allow string extras
+```
+
+**When NOT to use this pattern:**
+- `.strict()`: When forwarding data to another system that may add fields
+- `.passthrough()`: When you need to ensure only known fields are stored
+
+Reference: [Zod API - Objects](https://zod.dev/api#objects)
diff --git a/.agents/skills/zod/references/parse-async-for-async-refinements.md b/.agents/skills/zod/references/parse-async-for-async-refinements.md
new file mode 100644
index 0000000..d947764
--- /dev/null
+++ b/.agents/skills/zod/references/parse-async-for-async-refinements.md
@@ -0,0 +1,118 @@
+---
+title: Use parseAsync for Async Refinements
+impact: CRITICAL
+impactDescription: Using parse() with async refinements throws an error; async validation silently fails or crashes the application
+tags: parse, async, parseAsync, refinement
+---
+
+## Use parseAsync for Async Refinements
+
+If your schema uses `refine()` or `superRefine()` with async validation (like database lookups), you must use `parseAsync()` or `safeParseAsync()`. Using synchronous `parse()` with async refinements throws an error.
+
+**Incorrect (sync parse with async refinement):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  username: z.string().min(3),
+}).refine(
+  async (data) => {
+    // Async database check
+    const exists = await db.users.findByEmail(data.email)
+    return !exists
+  },
+  { message: 'Email already registered' }
+)
+
+// This throws an error!
+const user = userSchema.parse(formData)
+// Error: Async refinement encountered during synchronous parse operation.
+// Use .parseAsync instead.
+```
+
+**Correct (using parseAsync):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  username: z.string().min(3),
+}).refine(
+  async (data) => {
+    const exists = await db.users.findByEmail(data.email)
+    return !exists
+  },
+  { message: 'Email already registered' }
+)
+
+// Use parseAsync for async refinements
+const user = await userSchema.parseAsync(formData)
+
+// Or safeParseAsync for error handling
+const result = await userSchema.safeParseAsync(formData)
+if (!result.success) {
+  console.log(result.error.issues)
+}
+```
+
+**Async transforms also require parseAsync:**
+
+```typescript
+const enrichedUserSchema = z.object({
+  userId: z.string().uuid(),
+}).transform(async (data) => {
+  // Async data enrichment
+  const user = await db.users.findById(data.userId)
+  return {
+    ...data,
+    email: user.email,
+    name: user.name,
+  }
+})
+
+// Must use parseAsync
+const enrichedUser = await enrichedUserSchema.parseAsync({ userId: '123' })
+```
+
+**Pattern for API routes:**
+
+```typescript
+import { z } from 'zod'
+import { NextRequest, NextResponse } from 'next/server'
+
+const registerSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+}).superRefine(async (data, ctx) => {
+  const existingUser = await db.users.findByEmail(data.email)
+  if (existingUser) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['email'],
+      message: 'Email already registered',
+    })
+  }
+})
+
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+
+  // Always use safeParseAsync with async schemas
+  const result = await registerSchema.safeParseAsync(body)
+
+  if (!result.success) {
+    return NextResponse.json({ errors: result.error.issues }, { status: 400 })
+  }
+
+  // Proceed with registration
+}
+```
+
+**When NOT to use this pattern:**
+- Schemas with only synchronous validation (use parse/safeParse)
+- When async validation can be moved outside Zod (validate, then check)
+
+Reference: [Zod API - parseAsync](https://zod.dev/api#parseasync)
diff --git a/.agents/skills/zod/references/parse-avoid-double-validation.md b/.agents/skills/zod/references/parse-avoid-double-validation.md
new file mode 100644
index 0000000..8cf45f1
--- /dev/null
+++ b/.agents/skills/zod/references/parse-avoid-double-validation.md
@@ -0,0 +1,129 @@
+---
+title: Avoid Double Validation
+impact: HIGH
+impactDescription: Parsing the same data twice wastes CPU cycles; in hot paths this adds measurable latency
+tags: parse, performance, optimization, architecture
+---
+
+## Avoid Double Validation
+
+Once data is validated by Zod, trust the result. Re-validating the same data in multiple layers doubles CPU usage and adds latency. Pass the typed result through your application instead.
+
+**Incorrect (validating at every layer):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+})
+
+// Controller validates
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+  const user = userSchema.parse(body)  // First parse
+  return await userService.create(user)
+}
+
+// Service validates again
+const userService = {
+  async create(data: unknown) {
+    const user = userSchema.parse(data)  // Second parse - redundant
+    return await userRepository.insert(user)
+  }
+}
+
+// Repository validates again
+const userRepository = {
+  async insert(data: unknown) {
+    const user = userSchema.parse(data)  // Third parse - wasteful
+    return await db.users.create({ data: user })
+  }
+}
+```
+
+**Correct (validate once, pass typed data):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+})
+
+type User = z.infer<typeof userSchema>
+
+// Controller validates at boundary
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+
+  const result = userSchema.safeParse(body)
+  if (!result.success) {
+    return NextResponse.json({ errors: result.error.issues }, { status: 400 })
+  }
+
+  // Pass validated, typed data
+  return await userService.create(result.data)
+}
+
+// Service receives typed data, no re-validation needed
+const userService = {
+  async create(user: User) {
+    // user is guaranteed to match schema
+    return await userRepository.insert(user)
+  }
+}
+
+// Repository receives typed data
+const userRepository = {
+  async insert(user: User) {
+    return await db.users.create({ data: user })
+  }
+}
+```
+
+**When you might validate at multiple layers:**
+
+```typescript
+// Different schemas for different layers
+const apiUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),  // Only in API layer
+})
+
+const dbUserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  passwordHash: z.string(),  // Transformed before storage
+})
+
+// API validates input format
+export async function POST(req: NextRequest) {
+  const input = apiUserSchema.parse(await req.json())
+  const user = await userService.create(input)
+  return NextResponse.json(user)
+}
+
+// Service transforms and validates for storage
+const userService = {
+  async create(input: z.infer<typeof apiUserSchema>) {
+    const dbUser = dbUserSchema.parse({
+      id: crypto.randomUUID(),
+      email: input.email,
+      passwordHash: await hash(input.password),
+    })
+    return await userRepository.insert(dbUser)
+  }
+}
+```
+
+**When NOT to use this pattern:**
+- When schemas differ between layers (API vs DB shape)
+- When data crosses trust boundaries (external service response)
+- During development when debugging data flow
+
+Reference: [Zod Performance](https://zod.dev/v4#performance)
diff --git a/.agents/skills/zod/references/parse-handle-all-issues.md b/.agents/skills/zod/references/parse-handle-all-issues.md
new file mode 100644
index 0000000..2b5aefe
--- /dev/null
+++ b/.agents/skills/zod/references/parse-handle-all-issues.md
@@ -0,0 +1,125 @@
+---
+title: Handle All Validation Issues Not Just First
+impact: CRITICAL
+impactDescription: Showing only the first error forces users to fix-submit-fix repeatedly; collecting all errors improves UX dramatically
+tags: parse, errors, issues, user-experience
+---
+
+## Handle All Validation Issues Not Just First
+
+Zod collects all validation failures, not just the first one. When displaying errors to users, show all issues so they can fix everything at once instead of playing whack-a-mole with one error at a time.
+
+**Incorrect (showing only first error):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password must be 8+ characters'),
+  confirmPassword: z.string(),
+  age: z.number().min(18, 'Must be 18 or older'),
+})
+
+function validateForm(data: unknown) {
+  const result = formSchema.safeParse(data)
+
+  if (!result.success) {
+    // Only shows first error - terrible UX
+    return { error: result.error.issues[0].message }
+  }
+
+  return { data: result.data }
+}
+
+// User submits empty form
+validateForm({})
+// Returns: { error: 'Invalid email' }
+// User fixes email, submits again
+// Returns: { error: 'Password must be 8+ characters' }
+// User fixes password, submits again...
+// 4 round trips to fix 4 errors!
+```
+
+**Correct (showing all errors):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Password must be 8+ characters'),
+  confirmPassword: z.string(),
+  age: z.number().min(18, 'Must be 18 or older'),
+})
+
+function validateForm(data: unknown) {
+  const result = formSchema.safeParse(data)
+
+  if (!result.success) {
+    // Collect errors by field for form display
+    const fieldErrors: Record<string, string[]> = {}
+
+    for (const issue of result.error.issues) {
+      const field = issue.path.join('.')
+      if (!fieldErrors[field]) {
+        fieldErrors[field] = []
+      }
+      fieldErrors[field].push(issue.message)
+    }
+
+    return { errors: fieldErrors }
+  }
+
+  return { data: result.data }
+}
+
+// User submits empty form
+validateForm({})
+// Returns: {
+//   errors: {
+//     email: ['Invalid email'],
+//     password: ['Password must be 8+ characters'],
+//     confirmPassword: ['Required'],
+//     age: ['Expected number, received undefined']
+//   }
+// }
+// User sees ALL errors, fixes everything, submits once!
+```
+
+**Using flatten() for simpler error structure:**
+
+```typescript
+const result = formSchema.safeParse(data)
+
+if (!result.success) {
+  const flattened = result.error.flatten()
+  // {
+  //   formErrors: [],  // Top-level errors
+  //   fieldErrors: {
+  //     email: ['Invalid email'],
+  //     password: ['Password must be 8+ characters'],
+  //     ...
+  //   }
+  // }
+  return { errors: flattened.fieldErrors }
+}
+```
+
+**With React Hook Form integration:**
+
+```typescript
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useForm } from 'react-hook-form'
+
+const form = useForm({
+  resolver: zodResolver(formSchema),
+  // All errors are automatically collected and displayed
+})
+```
+
+**When NOT to use this pattern:**
+- Rate-limited APIs where you want to fail fast on first error
+- Large batch processing where full validation is expensive
+
+Reference: [Zod Error Handling](https://zod.dev/error-handling)
diff --git a/.agents/skills/zod/references/parse-never-trust-json.md b/.agents/skills/zod/references/parse-never-trust-json.md
new file mode 100644
index 0000000..62d3605
--- /dev/null
+++ b/.agents/skills/zod/references/parse-never-trust-json.md
@@ -0,0 +1,113 @@
+---
+title: Never Trust JSON.parse Output
+impact: CRITICAL
+impactDescription: JSON.parse returns any type; unvalidated JSON allows type confusion attacks and runtime crashes
+tags: parse, json, security, type-safety
+---
+
+## Never Trust JSON.parse Output
+
+`JSON.parse()` returns `any` (or `unknown` in strict mode), providing no type guarantees. Always validate JSON output with Zod before using it, even if you control the JSON source. This catches corruption, version mismatches, and ensures type safety.
+
+**Incorrect (trusting JSON.parse):**
+
+```typescript
+// JSON.parse returns any - no type safety
+const config = JSON.parse(fs.readFileSync('config.json', 'utf-8'))
+// config is 'any' - TypeScript allows anything
+
+// This might crash at runtime if structure changed
+console.log(config.database.host)  // TypeError: Cannot read property 'host' of undefined
+
+// API response - also unvalidated
+const response = await fetch('/api/user')
+const user = await response.json()  // any type
+console.log(user.name.toUpperCase())  // Crash if name is null/undefined
+```
+
+**Correct (validate after JSON.parse):**
+
+```typescript
+import { z } from 'zod'
+
+const configSchema = z.object({
+  database: z.object({
+    host: z.string(),
+    port: z.number(),
+    name: z.string(),
+  }),
+  api: z.object({
+    key: z.string(),
+    timeout: z.number().default(5000),
+  }),
+})
+
+// Parse JSON then validate
+const rawConfig = JSON.parse(fs.readFileSync('config.json', 'utf-8'))
+const config = configSchema.parse(rawConfig)
+// config is fully typed: { database: { host: string, ... }, ... }
+
+// API response validation
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+const response = await fetch('/api/user')
+const rawUser = await response.json()
+const user = userSchema.parse(rawUser)
+// user is fully typed and validated
+```
+
+**Helper for validated JSON parsing:**
+
+```typescript
+function parseJSON<T>(schema: z.ZodType<T>, json: string): T {
+  return schema.parse(JSON.parse(json))
+}
+
+function safeParseJSON<T>(schema: z.ZodType<T>, json: string) {
+  try {
+    return { success: true as const, data: schema.parse(JSON.parse(json)) }
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return { success: false as const, error: 'Invalid JSON' }
+    }
+    if (error instanceof z.ZodError) {
+      return { success: false as const, error: error.issues }
+    }
+    throw error
+  }
+}
+
+// Usage
+const config = parseJSON(configSchema, fs.readFileSync('config.json', 'utf-8'))
+```
+
+**Validate localStorage/sessionStorage:**
+
+```typescript
+const cartSchema = z.array(z.object({
+  productId: z.string(),
+  quantity: z.number().int().positive(),
+}))
+
+function getCart() {
+  const raw = localStorage.getItem('cart')
+  if (!raw) return []
+
+  const result = cartSchema.safeParse(JSON.parse(raw))
+  if (!result.success) {
+    // Corrupted cart data - clear it
+    localStorage.removeItem('cart')
+    return []
+  }
+  return result.data
+}
+```
+
+**When NOT to use this pattern:**
+- When you genuinely need to pass through arbitrary JSON without processing
+
+Reference: [Zod API - parse](https://zod.dev/api#parse)
diff --git a/.agents/skills/zod/references/parse-use-safeparse.md b/.agents/skills/zod/references/parse-use-safeparse.md
new file mode 100644
index 0000000..adc7857
--- /dev/null
+++ b/.agents/skills/zod/references/parse-use-safeparse.md
@@ -0,0 +1,102 @@
+---
+title: Use safeParse() for User Input
+impact: CRITICAL
+impactDescription: parse() throws exceptions on invalid data; unhandled exceptions crash servers and expose stack traces to users
+tags: parse, safeParse, error-handling, validation
+---
+
+## Use safeParse() for User Input
+
+`parse()` throws a `ZodError` when validation fails, which crashes your application if not caught. `safeParse()` returns a result object that you can inspect without try/catch. Use `safeParse()` for any user-provided or external data.
+
+**Incorrect (parse without error handling):**
+
+```typescript
+import { z } from 'zod'
+import { NextRequest, NextResponse } from 'next/server'
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+})
+
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+
+  // If validation fails, this throws and crashes the handler
+  const user = createUserSchema.parse(body)
+
+  // Never reached if parse throws
+  await db.users.create({ data: user })
+  return NextResponse.json({ success: true })
+}
+// Result: 500 Internal Server Error with stack trace
+```
+
+**Correct (using safeParse):**
+
+```typescript
+import { z } from 'zod'
+import { NextRequest, NextResponse } from 'next/server'
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+})
+
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+
+  const result = createUserSchema.safeParse(body)
+
+  if (!result.success) {
+    // Return structured error response
+    return NextResponse.json(
+      { error: 'Validation failed', issues: result.error.issues },
+      { status: 400 }
+    )
+  }
+
+  // result.data is typed correctly
+  await db.users.create({ data: result.data })
+  return NextResponse.json({ success: true })
+}
+```
+
+**The result object structure:**
+
+```typescript
+// Success case
+{ success: true, data: T }
+
+// Error case
+{ success: false, error: ZodError }
+
+// Type narrowing works automatically
+if (result.success) {
+  result.data  // T - fully typed
+} else {
+  result.error  // ZodError
+  result.error.issues  // Array of validation issues
+}
+```
+
+**When parse() is acceptable:**
+
+```typescript
+// Internal data you control - parse is fine
+const config = configSchema.parse(JSON.parse(process.env.CONFIG))
+
+// Test assertions - parse throws helpful errors
+expect(() => schema.parse(invalidData)).toThrow()
+
+// Schema development - see errors immediately
+schema.parse(testData)  // See what fails during development
+```
+
+**When NOT to use this pattern:**
+- Internal configuration parsing where invalid data should crash early
+- Tests where you want exceptions to fail the test
+- Scripts where you want to see the full error
+
+Reference: [Zod API - safeParse](https://zod.dev/api#safeparse)
diff --git a/.agents/skills/zod/references/parse-validate-early.md b/.agents/skills/zod/references/parse-validate-early.md
new file mode 100644
index 0000000..f7b5772
--- /dev/null
+++ b/.agents/skills/zod/references/parse-validate-early.md
@@ -0,0 +1,120 @@
+---
+title: Validate at System Boundaries
+impact: CRITICAL
+impactDescription: Validating deep in business logic allows corrupt data to propagate; validating at boundaries catches issues before they spread
+tags: parse, boundaries, architecture, defense-in-depth
+---
+
+## Validate at System Boundaries
+
+Validate external data immediately when it enters your system—at API endpoints, form handlers, message queue consumers, and configuration loaders. Validating deep in business logic allows corrupt data to propagate and makes debugging harder.
+
+**Incorrect (validating deep in business logic):**
+
+```typescript
+import { z } from 'zod'
+
+// No validation at API boundary
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+  // Raw unknown data passed through
+  return await processOrder(body)
+}
+
+async function processOrder(data: unknown) {
+  // Data passed around unvalidated
+  const items = await calculateTotals(data)
+  return await chargeCustomer(data, items)
+}
+
+async function calculateTotals(data: unknown) {
+  // Finally validating way too late
+  const order = orderSchema.parse(data)  // Throws here, far from entry point
+  // ...
+}
+// Hard to trace where bad data came from
+```
+
+**Correct (validating at boundary):**
+
+```typescript
+import { z } from 'zod'
+
+const orderSchema = z.object({
+  customerId: z.string().uuid(),
+  items: z.array(z.object({
+    productId: z.string(),
+    quantity: z.number().int().positive(),
+  })).min(1),
+  shippingAddress: z.object({
+    street: z.string(),
+    city: z.string(),
+    country: z.string(),
+  }),
+})
+
+type Order = z.infer<typeof orderSchema>
+
+// Validate immediately at boundary
+export async function POST(req: NextRequest) {
+  const body = await req.json()
+
+  const result = orderSchema.safeParse(body)
+  if (!result.success) {
+    return NextResponse.json(
+      { error: 'Invalid order', issues: result.error.issues },
+      { status: 400 }
+    )
+  }
+
+  // Now data is validated and typed
+  return await processOrder(result.data)
+}
+
+// Business logic receives typed, validated data
+async function processOrder(order: Order) {
+  // order is guaranteed to match schema
+  const items = await calculateTotals(order)
+  return await chargeCustomer(order, items)
+}
+
+async function calculateTotals(order: Order) {
+  // No validation needed - type guarantees shape
+  return order.items.map(item => ({
+    ...item,
+    total: item.quantity * getPrice(item.productId),
+  }))
+}
+```
+
+**Boundaries to validate:**
+
+```typescript
+// API endpoints
+export async function POST(req: NextRequest) {
+  const data = await req.json()
+  const validated = requestSchema.safeParse(data)
+  // ...
+}
+
+// Message queue consumers
+async function handleMessage(rawMessage: string) {
+  const data = JSON.parse(rawMessage)
+  const validated = messageSchema.safeParse(data)
+  // ...
+}
+
+// Configuration loading
+const config = configSchema.parse(JSON.parse(process.env.CONFIG!))
+
+// External API responses
+const response = await fetch('/api/users')
+const data = await response.json()
+const users = usersResponseSchema.parse(data)
+```
+
+**When NOT to use this pattern:**
+- Internal function calls with already-validated data
+- Performance-critical hot paths (validate once, trust afterward)
+
+Reference: [Zod with TypeScript for Server-side Validation](https://stack.convex.dev/typescript-zod-function-validation)
diff --git a/.agents/skills/zod/references/perf-arrays.md b/.agents/skills/zod/references/perf-arrays.md
new file mode 100644
index 0000000..615b0f7
--- /dev/null
+++ b/.agents/skills/zod/references/perf-arrays.md
@@ -0,0 +1,153 @@
+---
+title: Optimize Large Array Validation
+impact: LOW-MEDIUM
+impactDescription: Validating 10,000 items takes ~100ms; early exits, sampling, or batching reduce time for large datasets
+tags: perf, arrays, batch, large-data
+---
+
+## Optimize Large Array Validation
+
+Validating large arrays (thousands of items) can become a performance bottleneck. For batch imports, streaming data, or large datasets, consider strategies like early exit, sampling, or batched validation.
+
+**Baseline performance:**
+
+```typescript
+import { z } from 'zod'
+
+const itemSchema = z.object({
+  id: z.string(),
+  value: z.number(),
+})
+
+const arraySchema = z.array(itemSchema)
+
+// 10,000 items: ~100ms
+// 100,000 items: ~1000ms
+arraySchema.parse(largeArray)
+```
+
+**Early exit on first error:**
+
+```typescript
+import { z } from 'zod'
+
+function validateArrayFastFail<T>(
+  schema: z.ZodType<T>,
+  items: unknown[]
+): { success: true; data: T[] } | { success: false; error: z.ZodError; index: number } {
+  const validated: T[] = []
+
+  for (let i = 0; i < items.length; i++) {
+    const result = schema.safeParse(items[i])
+    if (!result.success) {
+      return { success: false, error: result.error, index: i }
+    }
+    validated.push(result.data)
+  }
+
+  return { success: true, data: validated }
+}
+
+// Stops at first invalid item instead of validating all
+```
+
+**Sample validation for large datasets:**
+
+```typescript
+function validateSample<T>(
+  schema: z.ZodType<T>,
+  items: unknown[],
+  sampleSize: number = 100
+): { valid: boolean; sampleErrors?: z.ZodIssue[] } {
+  // Validate random sample
+  const indices = new Set<number>()
+  while (indices.size < Math.min(sampleSize, items.length)) {
+    indices.add(Math.floor(Math.random() * items.length))
+  }
+
+  const errors: z.ZodIssue[] = []
+
+  for (const i of indices) {
+    const result = schema.safeParse(items[i])
+    if (!result.success) {
+      errors.push(...result.error.issues)
+    }
+  }
+
+  return errors.length > 0
+    ? { valid: false, sampleErrors: errors }
+    : { valid: true }
+}
+
+// Check 100 random items from 100,000 - very fast
+const check = validateSample(itemSchema, hugeArray)
+```
+
+**Batched validation with progress:**
+
+```typescript
+async function validateInBatches<T>(
+  schema: z.ZodType<T>,
+  items: unknown[],
+  batchSize: number = 1000,
+  onProgress?: (percent: number) => void
+): Promise<z.SafeParseReturnType<unknown, T[]>> {
+  const validated: T[] = []
+  const errors: z.ZodIssue[] = []
+
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize)
+
+    // Validate batch
+    for (let j = 0; j < batch.length; j++) {
+      const result = schema.safeParse(batch[j])
+      if (result.success) {
+        validated.push(result.data)
+      } else {
+        errors.push(...result.error.issues.map(issue => ({
+          ...issue,
+          path: [i + j, ...issue.path],
+        })))
+      }
+    }
+
+    // Report progress and yield to event loop
+    onProgress?.(Math.min(100, ((i + batchSize) / items.length) * 100))
+    await new Promise(resolve => setTimeout(resolve, 0))
+  }
+
+  if (errors.length > 0) {
+    return { success: false, error: new z.ZodError(errors) }
+  }
+  return { success: true, data: validated }
+}
+
+// Use with progress reporting
+await validateInBatches(itemSchema, largeArray, 1000, (percent) => {
+  console.log(`Validating: ${percent.toFixed(1)}%`)
+})
+```
+
+**Streaming validation:**
+
+```typescript
+async function* validateStream<T>(
+  schema: z.ZodType<T>,
+  items: AsyncIterable<unknown>
+): AsyncGenerator<T, void, unknown> {
+  for await (const item of items) {
+    yield schema.parse(item)  // Throws on invalid
+  }
+}
+
+// Process items as they arrive
+for await (const validItem of validateStream(itemSchema, dataStream)) {
+  await processItem(validItem)
+}
+```
+
+**When NOT to use this pattern:**
+- Small arrays (< 1000 items) - standard validation is fine
+- When all items must be validated for correctness guarantees
+
+Reference: [Zod Performance](https://zod.dev/v4#performance)
diff --git a/.agents/skills/zod/references/perf-avoid-dynamic-creation.md b/.agents/skills/zod/references/perf-avoid-dynamic-creation.md
new file mode 100644
index 0000000..9878899
--- /dev/null
+++ b/.agents/skills/zod/references/perf-avoid-dynamic-creation.md
@@ -0,0 +1,139 @@
+---
+title: Avoid Dynamic Schema Creation in Hot Paths
+impact: LOW-MEDIUM
+impactDescription: Zod 4's JIT compilation makes schema creation slower; creating schemas in loops adds ~0.15ms per creation
+tags: perf, dynamic, hot-path, optimization
+---
+
+## Avoid Dynamic Schema Creation in Hot Paths
+
+Zod 4 uses JIT (Just-In-Time) compilation to speed up repeated parsing, but this makes initial schema creation slower. Avoid creating schemas inside loops or frequently-called functions—pre-create them instead.
+
+**Incorrect (schema creation in hot path):**
+
+```typescript
+import { z } from 'zod'
+
+async function validateBatch(items: unknown[]) {
+  const results = []
+
+  for (const item of items) {
+    // Schema created for EACH item - slow!
+    const schema = z.object({
+      id: z.string(),
+      value: z.number(),
+    })
+
+    results.push(schema.safeParse(item))
+  }
+
+  return results
+}
+
+// 1000 items = 1000 schema creations = ~150ms overhead
+```
+
+**Correct (pre-created schema):**
+
+```typescript
+import { z } from 'zod'
+
+// Schema created ONCE
+const itemSchema = z.object({
+  id: z.string(),
+  value: z.number(),
+})
+
+async function validateBatch(items: unknown[]) {
+  // Reuse the same schema instance
+  return items.map(item => itemSchema.safeParse(item))
+}
+
+// 1000 items = 1 schema creation + 1000 fast parses
+```
+
+**Dynamic schemas with caching:**
+
+```typescript
+import { z } from 'zod'
+
+// Cache for dynamically-configured schemas
+const schemaCache = new WeakMap<object, z.ZodType>()
+
+function getSchemaForConfig(config: { fields: string[] }) {
+  // Check cache first
+  if (schemaCache.has(config)) {
+    return schemaCache.get(config)!
+  }
+
+  // Create and cache
+  const shape: Record<string, z.ZodString> = {}
+  for (const field of config.fields) {
+    shape[field] = z.string()
+  }
+
+  const schema = z.object(shape)
+  schemaCache.set(config, schema)
+  return schema
+}
+
+// Subsequent calls with same config reuse cached schema
+```
+
+**Lazy schema creation:**
+
+```typescript
+import { z } from 'zod'
+
+// Schema created only when first used
+let _userSchema: z.ZodObject<any> | null = null
+
+function getUserSchema() {
+  if (!_userSchema) {
+    _userSchema = z.object({
+      id: z.string().uuid(),
+      email: z.string().email(),
+      profile: z.object({
+        name: z.string(),
+        avatar: z.string().url().optional(),
+      }),
+    })
+  }
+  return _userSchema
+}
+
+// Or use a getter
+const schemas = {
+  _user: null as z.ZodType | null,
+  get user() {
+    if (!this._user) {
+      this._user = z.object({ /* ... */ })
+    }
+    return this._user
+  }
+}
+```
+
+**Benchmark considerations:**
+
+```typescript
+// Zod 4 JIT compilation:
+// - Schema creation: ~0.15ms per schema
+// - First parse: triggers JIT compile
+// - Subsequent parses: 7-14x faster
+
+// For schemas used once:
+// - Creation + parse: ~0.15ms + first-parse overhead
+// - Consider if validation is even needed
+
+// For schemas used many times:
+// - Create once, parse many: optimal
+// - JIT compilation amortized over all parses
+```
+
+**When NOT to use this pattern:**
+- One-off validation where schema is used once
+- Dynamically generated forms where fields change per request
+- Test files where performance doesn't matter
+
+Reference: [Zod v4 Performance](https://zod.dev/v4#performance)
diff --git a/.agents/skills/zod/references/perf-cache-schemas.md b/.agents/skills/zod/references/perf-cache-schemas.md
new file mode 100644
index 0000000..cd0c658
--- /dev/null
+++ b/.agents/skills/zod/references/perf-cache-schemas.md
@@ -0,0 +1,138 @@
+---
+title: Cache Schema Instances
+impact: LOW-MEDIUM
+impactDescription: Creating schemas on every render/call wastes CPU; module-level or memoized schemas are created once
+tags: perf, cache, memoization, optimization
+---
+
+## Cache Schema Instances
+
+Schema creation has overhead. Creating schemas inside render functions or on every function call wastes CPU cycles. Define schemas at module level or memoize them so they're created once and reused.
+
+**Incorrect (creating schema every render):**
+
+```typescript
+import { z } from 'zod'
+
+function UserForm() {
+  // Schema created on EVERY render - wasteful
+  const userSchema = z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+    age: z.number().int().positive(),
+  })
+
+  const handleSubmit = (data: unknown) => {
+    const result = userSchema.safeParse(data)
+    // ...
+  }
+
+  return <form onSubmit={handleSubmit}>...</form>
+}
+```
+
+**Correct (module-level schema):**
+
+```typescript
+import { z } from 'zod'
+
+// Schema created ONCE at module load
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+})
+
+type User = z.infer<typeof userSchema>
+
+function UserForm() {
+  const handleSubmit = (data: unknown) => {
+    const result = userSchema.safeParse(data)
+    // ...
+  }
+
+  return <form onSubmit={handleSubmit}>...</form>
+}
+```
+
+**For dynamic schemas, use useMemo:**
+
+```typescript
+import { z } from 'zod'
+import { useMemo } from 'react'
+
+function DynamicForm({ minAge }: { minAge: number }) {
+  // Schema only recreated when minAge changes
+  const userSchema = useMemo(() =>
+    z.object({
+      name: z.string().min(1),
+      age: z.number().min(minAge),
+    }),
+    [minAge]
+  )
+
+  // ...
+}
+```
+
+**For server-side, use module cache:**
+
+```typescript
+// schemas/user.ts - created once per process
+import { z } from 'zod'
+
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+})
+
+// api/users.ts
+import { userSchema } from '@/schemas/user'
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const result = userSchema.safeParse(body)  // Reuses cached schema
+  // ...
+}
+```
+
+**Avoid schema factories in hot paths:**
+
+```typescript
+// BAD: Factory called on every validation
+function createUserSchema(role: string) {
+  return z.object({
+    name: z.string(),
+    permissions: z.array(z.string()),
+  })
+}
+
+// Called in hot loop
+users.forEach(user => {
+  createUserSchema(user.role).parse(user)  // New schema every iteration!
+})
+
+// GOOD: Cache by key
+const schemaCache = new Map<string, z.ZodObject<any>>()
+
+function getUserSchema(role: string) {
+  if (!schemaCache.has(role)) {
+    schemaCache.set(role, z.object({
+      name: z.string(),
+      permissions: z.array(z.string()),
+    }))
+  }
+  return schemaCache.get(role)!
+}
+
+// Reuses cached schemas
+users.forEach(user => {
+  getUserSchema(user.role).parse(user)
+})
+```
+
+**When NOT to use this pattern:**
+- One-off validation where schema is used once
+- Test files where performance doesn't matter
+
+Reference: [Zod Performance](https://zod.dev/v4#performance)
diff --git a/.agents/skills/zod/references/perf-lazy-loading.md b/.agents/skills/zod/references/perf-lazy-loading.md
new file mode 100644
index 0000000..e911b68
--- /dev/null
+++ b/.agents/skills/zod/references/perf-lazy-loading.md
@@ -0,0 +1,135 @@
+---
+title: Lazy Load Large Schemas
+impact: LOW-MEDIUM
+impactDescription: Large schemas increase initial bundle and parse time; dynamic imports defer loading until needed
+tags: perf, lazy, import, code-splitting
+---
+
+## Lazy Load Large Schemas
+
+For applications with many complex schemas, importing all of them upfront increases initial bundle size and startup time. Use dynamic imports to lazy load schemas that aren't needed immediately.
+
+**Incorrect (importing all schemas upfront):**
+
+```typescript
+// schemas/index.ts - barrel file with everything
+export * from './user'
+export * from './order'
+export * from './product'
+export * from './analytics'  // Large, complex schema
+export * from './reports'    // Another large schema
+export * from './admin'      // Admin-only schemas
+
+// app/page.tsx
+import { userSchema, orderSchema, analyticsSchema, reportsSchema } from '@/schemas'
+// All schemas loaded even if not used on this page
+```
+
+**Correct (lazy loading schemas):**
+
+```typescript
+// Only import what's immediately needed
+import { userSchema } from '@/schemas/user'
+
+async function loadAnalyticsSchema() {
+  const { analyticsSchema } = await import('@/schemas/analytics')
+  return analyticsSchema
+}
+
+// Use when needed
+async function handleAnalyticsData(data: unknown) {
+  const schema = await loadAnalyticsSchema()
+  return schema.safeParse(data)
+}
+```
+
+**Route-based schema loading:**
+
+```typescript
+// app/admin/reports/page.tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import type { z } from 'zod'
+
+export default function ReportsPage() {
+  const [schema, setSchema] = useState<z.ZodType | null>(null)
+
+  useEffect(() => {
+    // Load schema only when this route is accessed
+    import('@/schemas/reports').then(({ reportsSchema }) => {
+      setSchema(reportsSchema)
+    })
+  }, [])
+
+  if (!schema) return <Loading />
+
+  // Use schema...
+}
+```
+
+**Better pattern with React Suspense:**
+
+```typescript
+// schemas/reports.ts
+import { z } from 'zod'
+
+export const reportsSchema = z.object({
+  // Large complex schema
+})
+
+// app/admin/reports/page.tsx
+import { lazy, Suspense } from 'react'
+
+const ReportsForm = lazy(() => import('./ReportsForm'))
+
+export default function ReportsPage() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <ReportsForm />
+    </Suspense>
+  )
+}
+
+// ReportsForm.tsx - schema imported with component
+import { reportsSchema } from '@/schemas/reports'
+
+export default function ReportsForm() {
+  // Schema available when component loads
+}
+```
+
+**Schema registry for conditional loading:**
+
+```typescript
+// schemas/registry.ts
+const schemaLoaders = {
+  user: () => import('./user').then(m => m.userSchema),
+  order: () => import('./order').then(m => m.orderSchema),
+  analytics: () => import('./analytics').then(m => m.analyticsSchema),
+  reports: () => import('./reports').then(m => m.reportsSchema),
+} as const
+
+type SchemaName = keyof typeof schemaLoaders
+
+const schemaCache = new Map<SchemaName, z.ZodType>()
+
+export async function getSchema(name: SchemaName) {
+  if (!schemaCache.has(name)) {
+    const schema = await schemaLoaders[name]()
+    schemaCache.set(name, schema)
+  }
+  return schemaCache.get(name)!
+}
+
+// Usage
+const schema = await getSchema('analytics')
+schema.parse(data)
+```
+
+**When NOT to use this pattern:**
+- Server-side rendering where all code is available
+- Small applications with few schemas
+- Schemas used on every page (defeats purpose)
+
+Reference: [Next.js Dynamic Imports](https://nextjs.org/docs/app/building-your-application/optimizing/lazy-loading)
diff --git a/.agents/skills/zod/references/perf-zod-mini.md b/.agents/skills/zod/references/perf-zod-mini.md
new file mode 100644
index 0000000..3c1084d
--- /dev/null
+++ b/.agents/skills/zod/references/perf-zod-mini.md
@@ -0,0 +1,117 @@
+---
+title: Use Zod Mini for Bundle-Sensitive Applications
+impact: LOW-MEDIUM
+impactDescription: Full Zod is ~17kb gzipped; Zod Mini is ~1.9kb - 85% smaller for frontend-critical bundles
+tags: perf, bundle, mini, tree-shaking
+---
+
+## Use Zod Mini for Bundle-Sensitive Applications
+
+For frontend applications where bundle size is critical, use `@zod/mini` instead of `zod`. Zod Mini provides the same validation capabilities with a functional API that tree-shakes better, reducing bundle size by ~85%.
+
+**When to consider Zod Mini:**
+
+```typescript
+// Your app if:
+// - Bundle size is critical (mobile-first, slow networks)
+// - Edge functions with size limits
+// - Simple validation needs (no complex transforms)
+// - Tree-shaking is important
+
+// Zod: ~17kb gzipped
+import { z } from 'zod'
+
+// Zod Mini: ~1.9kb gzipped (when tree-shaken)
+import * as z from '@zod/mini'
+```
+
+**Standard Zod (method chaining):**
+
+```typescript
+import { z } from 'zod'
+
+// Methods are attached to schema objects - hard to tree-shake
+const userSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+})
+
+const result = userSchema.safeParse(data)
+```
+
+**Zod Mini (functional API):**
+
+```typescript
+import * as z from '@zod/mini'
+
+// Functions are imported individually - tree-shakeable
+const userSchema = z.object({
+  name: z.pipe(z.string(), z.minLength(1), z.maxLength(100)),
+  email: z.pipe(z.string(), z.email()),
+  age: z.pipe(z.number(), z.int(), z.positive()),
+})
+
+const result = z.safeParse(userSchema, data)
+```
+
+**API differences:**
+
+```typescript
+// Standard Zod
+z.string().min(5).max(100).email()
+z.number().int().positive()
+z.array(z.string()).min(1)
+schema.parse(data)
+schema.safeParse(data)
+
+// Zod Mini
+z.pipe(z.string(), z.minLength(5), z.maxLength(100), z.email())
+z.pipe(z.number(), z.int(), z.positive())
+z.pipe(z.array(z.string()), z.minLength(1))
+z.parse(schema, data)
+z.safeParse(schema, data)
+```
+
+**When to stick with regular Zod:**
+
+```typescript
+// Use regular Zod when:
+// - Server-side where bundle size doesn't matter
+// - Complex schemas with many transforms
+// - Need full method chaining ergonomics
+// - Bundle size isn't a constraint
+
+// The 17kb isn't huge - only optimize if needed
+// Server: 17kb is negligible
+// Browser: 17kb ≈ 0.6ms additional startup on 3G
+```
+
+**Shared schemas between packages:**
+
+```typescript
+// shared-schemas/package.json
+{
+  "dependencies": {
+    "@zod/mini": "^4.0.0"  // Mini for frontend-shared schemas
+  }
+}
+
+// If you need both, Zod Mini schemas work with regular Zod
+// But prefer consistency - pick one for your codebase
+```
+
+**Bundle size comparison:**
+
+| Package | Gzipped Size | Use Case |
+|---------|--------------|----------|
+| `zod@3` | ~13kb | Legacy, stable |
+| `zod@4` | ~17kb | Full features |
+| `@zod/mini` | ~1.9kb | Bundle-critical |
+
+**When NOT to use this pattern:**
+- Server-side applications (bundle size irrelevant)
+- When method chaining ergonomics are preferred
+- Complex schemas that benefit from full API
+
+Reference: [Zod Mini](https://zod.dev/packages/mini)
diff --git a/.agents/skills/zod/references/refine-add-path.md b/.agents/skills/zod/references/refine-add-path.md
new file mode 100644
index 0000000..15b80bc
--- /dev/null
+++ b/.agents/skills/zod/references/refine-add-path.md
@@ -0,0 +1,141 @@
+---
+title: Add Path to Refinement Errors
+impact: MEDIUM
+impactDescription: Errors without path show at object level; adding path highlights the specific field that failed
+tags: refine, path, errors, forms
+---
+
+## Add Path to Refinement Errors
+
+When using `.refine()` on object schemas for cross-field validation, add a `path` option to indicate which field the error relates to. Without it, the error appears at the object level, making form error display confusing.
+
+**Incorrect (error at object level):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(
+  (data) => data.password === data.confirmPassword,
+  { message: 'Passwords do not match' }  // No path specified
+)
+
+const result = formSchema.safeParse({
+  password: 'secret123',
+  confirmPassword: 'different',
+})
+
+if (!result.success) {
+  const flattened = result.error.flatten()
+  // {
+  //   formErrors: ['Passwords do not match'],  // At form level!
+  //   fieldErrors: {}  // Empty - no field association
+  // }
+}
+
+// Form UI can't highlight which field has the error
+```
+
+**Correct (error with path):**
+
+```typescript
+import { z } from 'zod'
+
+const formSchema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(
+  (data) => data.password === data.confirmPassword,
+  {
+    message: 'Passwords do not match',
+    path: ['confirmPassword'],  // Error appears on this field
+  }
+)
+
+const result = formSchema.safeParse({
+  password: 'secret123',
+  confirmPassword: 'different',
+})
+
+if (!result.success) {
+  const flattened = result.error.flatten()
+  // {
+  //   formErrors: [],
+  //   fieldErrors: {
+  //     confirmPassword: ['Passwords do not match']  // Associated with field
+  //   }
+  // }
+}
+
+// Form can now show error next to confirmPassword input
+```
+
+**Multiple cross-field validations:**
+
+```typescript
+const dateRangeSchema = z.object({
+  startDate: z.coerce.date(),
+  endDate: z.coerce.date(),
+  minDays: z.number().optional(),
+  maxDays: z.number().optional(),
+}).refine(
+  (data) => data.endDate >= data.startDate,
+  { message: 'End date must be after start date', path: ['endDate'] }
+).refine(
+  (data) => {
+    if (!data.minDays) return true
+    const days = (data.endDate.getTime() - data.startDate.getTime()) / 86400000
+    return days >= data.minDays
+  },
+  { message: 'Date range is too short', path: ['endDate'] }
+).refine(
+  (data) => {
+    if (!data.maxDays) return true
+    const days = (data.endDate.getTime() - data.startDate.getTime()) / 86400000
+    return days <= data.maxDays
+  },
+  { message: 'Date range is too long', path: ['endDate'] }
+)
+```
+
+**With superRefine for multiple path errors:**
+
+```typescript
+const orderSchema = z.object({
+  billingAddress: z.object({
+    street: z.string(),
+    city: z.string(),
+  }),
+  shippingAddress: z.object({
+    street: z.string(),
+    city: z.string(),
+  }),
+  sameAsBilling: z.boolean(),
+}).superRefine((data, ctx) => {
+  if (data.sameAsBilling) {
+    // If sameAsBilling but addresses differ, show errors on shipping
+    if (data.shippingAddress.street !== data.billingAddress.street) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Must match billing address',
+        path: ['shippingAddress', 'street'],  // Nested path
+      })
+    }
+    if (data.shippingAddress.city !== data.billingAddress.city) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Must match billing address',
+        path: ['shippingAddress', 'city'],
+      })
+    }
+  }
+})
+```
+
+**When NOT to use this pattern:**
+- When the error genuinely applies to the whole object
+- Simple single-field refinements (path is implicit)
+
+Reference: [Zod API - refine](https://zod.dev/api#refine)
diff --git a/.agents/skills/zod/references/refine-catch.md b/.agents/skills/zod/references/refine-catch.md
new file mode 100644
index 0000000..c2f30bf
--- /dev/null
+++ b/.agents/skills/zod/references/refine-catch.md
@@ -0,0 +1,143 @@
+---
+title: Use catch() for Fault-Tolerant Parsing
+impact: MEDIUM
+impactDescription: parse() fails on first invalid field; catch() provides fallback values, enabling partial success with degraded data
+tags: refine, catch, fallback, resilience
+---
+
+## Use catch() for Fault-Tolerant Parsing
+
+When parsing data that might have some invalid fields but you want to accept what's valid, use `.catch()` to provide fallback values instead of failing entirely. This enables graceful degradation for partially corrupted data.
+
+**Incorrect (all-or-nothing parsing):**
+
+```typescript
+import { z } from 'zod'
+
+const userPrefsSchema = z.object({
+  theme: z.enum(['light', 'dark']),
+  fontSize: z.number().min(8).max(32),
+  language: z.string(),
+  notifications: z.boolean(),
+})
+
+// Corrupted localStorage data
+const stored = {
+  theme: 'invalid-theme',  // Bad
+  fontSize: 200,  // Bad
+  language: 'en',  // Good
+  notifications: 'yes',  // Bad - should be boolean
+}
+
+userPrefsSchema.parse(stored)
+// ZodError: Invalid enum value at "theme"
+// User loses ALL their preferences because one field is bad
+```
+
+**Correct (fault-tolerant with catch):**
+
+```typescript
+import { z } from 'zod'
+
+const userPrefsSchema = z.object({
+  theme: z.enum(['light', 'dark']).catch('light'),
+  fontSize: z.number().min(8).max(32).catch(16),
+  language: z.string().catch('en'),
+  notifications: z.boolean().catch(true),
+})
+
+// Corrupted data
+const stored = {
+  theme: 'invalid-theme',
+  fontSize: 200,
+  language: 'en',
+  notifications: 'yes',
+}
+
+const prefs = userPrefsSchema.parse(stored)
+// {
+//   theme: 'light',      // Fallback used
+//   fontSize: 16,        // Fallback used
+//   language: 'en',      // Original value preserved
+//   notifications: true  // Fallback used
+// }
+// User gets mostly working preferences instead of error
+```
+
+**Catch with factory function:**
+
+```typescript
+// Factory function receives the caught error
+const schema = z.object({
+  data: z.array(z.number()).catch((ctx) => {
+    console.warn('Invalid data array:', ctx.error)
+    return []  // Return empty array as fallback
+  }),
+})
+```
+
+**Use case: API response resilience:**
+
+```typescript
+const productSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number().positive(),
+  // Legacy field that might be missing or wrong format
+  legacyCode: z.string().catch('UNKNOWN'),
+  // External data that might be malformed
+  metadata: z.record(z.string()).catch({}),
+})
+
+// API returns partial data
+const apiResponse = {
+  id: 'prod-123',
+  name: 'Widget',
+  price: 29.99,
+  legacyCode: null,  // Bad - should be string
+  metadata: 'invalid',  // Bad - should be object
+}
+
+const product = productSchema.parse(apiResponse)
+// Works! Returns product with fallbacks for bad fields
+```
+
+**Difference between catch() and default():**
+
+```typescript
+// .default() - only fills in undefined
+z.string().default('fallback')
+// undefined -> 'fallback'
+// null -> ZodError
+// '' -> '' (empty string is valid)
+
+// .catch() - fallback for ANY parse failure
+z.string().catch('fallback')
+// undefined -> 'fallback'
+// null -> 'fallback'
+// 123 -> 'fallback'
+// Even valid strings pass through unchanged
+```
+
+**Combining catch with validation:**
+
+```typescript
+// Catch only specific validation failures
+const schema = z.string()
+  .email()
+  .catch('invalid@example.com')  // Fallback if not valid email
+
+// Chain for complex defaults
+const ageSchema = z.coerce.number()
+  .int()
+  .min(0)
+  .max(120)
+  .catch(0)  // Invalid ages become 0
+```
+
+**When NOT to use this pattern:**
+- When invalid data should cause errors (strict validation)
+- When you need to know which fields failed (use safeParse)
+- Critical fields that must be valid
+
+Reference: [Zod API - catch](https://zod.dev/api#catch)
diff --git a/.agents/skills/zod/references/refine-defaults.md b/.agents/skills/zod/references/refine-defaults.md
new file mode 100644
index 0000000..122de97
--- /dev/null
+++ b/.agents/skills/zod/references/refine-defaults.md
@@ -0,0 +1,131 @@
+---
+title: Use default() for Optional Fields with Defaults
+impact: MEDIUM
+impactDescription: Manual default handling spreads logic across codebase; .default() centralizes defaults in schema
+tags: refine, default, optional, configuration
+---
+
+## Use default() for Optional Fields with Defaults
+
+When a field is optional but should have a default value when missing, use `.default()` instead of handling defaults in business logic. This keeps default values centralized in the schema and ensures consistent behavior.
+
+**Incorrect (defaults spread across codebase):**
+
+```typescript
+import { z } from 'zod'
+
+const configSchema = z.object({
+  timeout: z.number().optional(),
+  retries: z.number().optional(),
+  debug: z.boolean().optional(),
+})
+
+type Config = z.infer<typeof configSchema>
+
+function createClient(config: Config) {
+  // Defaults handled in business logic - duplicated everywhere
+  const timeout = config.timeout ?? 5000
+  const retries = config.retries ?? 3
+  const debug = config.debug ?? false
+
+  // ...
+}
+
+function createOtherClient(config: Config) {
+  // Same defaults duplicated - risk of inconsistency
+  const timeout = config.timeout ?? 5000
+  const retries = config.retries ?? 3  // What if someone uses 2 here?
+  const debug = config.debug ?? false
+
+  // ...
+}
+```
+
+**Correct (defaults in schema):**
+
+```typescript
+import { z } from 'zod'
+
+const configSchema = z.object({
+  timeout: z.number().default(5000),
+  retries: z.number().default(3),
+  debug: z.boolean().default(false),
+})
+
+type Config = z.infer<typeof configSchema>
+// { timeout: number; retries: number; debug: boolean }
+// No optional - defaults fill in missing values
+
+function createClient(config: Config) {
+  // config.timeout is guaranteed to exist
+  console.log(config.timeout)  // 5000 if not provided
+  console.log(config.retries)  // 3 if not provided
+  console.log(config.debug)    // false if not provided
+}
+
+// Parse fills in defaults
+configSchema.parse({})
+// { timeout: 5000, retries: 3, debug: false }
+
+configSchema.parse({ timeout: 10000 })
+// { timeout: 10000, retries: 3, debug: false }
+```
+
+**Input type vs Output type with defaults:**
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  role: z.enum(['admin', 'user']).default('user'),
+})
+
+type SchemaInput = z.input<typeof schema>
+// { name: string; role?: 'admin' | 'user' }
+
+type SchemaOutput = z.output<typeof schema>
+// { name: string; role: 'admin' | 'user' }
+
+// Input type is optional, output type is required
+```
+
+**Default with factory function:**
+
+```typescript
+// Static default
+const schema1 = z.object({
+  id: z.string().default('temp-id'),
+})
+
+// Factory function for dynamic defaults
+const schema2 = z.object({
+  id: z.string().default(() => crypto.randomUUID()),
+  createdAt: z.date().default(() => new Date()),
+})
+
+// Each parse creates new values
+schema2.parse({})  // { id: 'abc-123...', createdAt: 2024-01-15... }
+schema2.parse({})  // { id: 'def-456...', createdAt: 2024-01-15... }
+```
+
+**Combining with optional/nullable:**
+
+```typescript
+// .optional().default() - if undefined, use default
+z.string().optional().default('fallback')
+
+// .nullable().default() - null stays null, only undefined gets default
+z.string().nullable().default('fallback')
+// null -> null
+// undefined -> 'fallback'
+
+// .nullish().default() - both null and undefined get default
+z.string().nullish().default('fallback')
+// null -> 'fallback'
+// undefined -> 'fallback'
+```
+
+**When NOT to use this pattern:**
+- When absence of value has different meaning than default
+- When defaults depend on other fields (use transform)
+
+Reference: [Zod API - default](https://zod.dev/api#default)
diff --git a/.agents/skills/zod/references/refine-transform-coerce.md b/.agents/skills/zod/references/refine-transform-coerce.md
new file mode 100644
index 0000000..bd95c67
--- /dev/null
+++ b/.agents/skills/zod/references/refine-transform-coerce.md
@@ -0,0 +1,105 @@
+---
+title: Distinguish transform() from refine() and coerce()
+impact: MEDIUM
+impactDescription: Using wrong method causes validation to pass with wrong data; each method has distinct purpose
+tags: refine, transform, coerce, conversion
+---
+
+## Distinguish transform() from refine() and coerce()
+
+`.refine()` validates and returns boolean, `.transform()` converts data to new format, and `.coerce` converts input before validation. Using the wrong one causes bugs where validation passes but data is wrong.
+
+**Purpose of each method:**
+
+```typescript
+import { z } from 'zod'
+
+// coerce: Convert type BEFORE validation
+// Input: unknown -> Output: validated type
+z.coerce.number().parse('42')  // Converts "42" to 42, then validates as number
+
+// refine: Validate with custom logic, return boolean
+// Input: T -> Output: T (unchanged, but validated)
+z.number().refine((n) => n > 0)  // Validates n > 0, returns n unchanged
+
+// transform: Convert to different type AFTER validation
+// Input: T -> Output: U (different type)
+z.string().transform((s) => s.length)  // Validates string, returns length
+```
+
+**Incorrect (using transform for validation):**
+
+```typescript
+// Wrong: transform should convert, not validate
+const schema = z.number().transform((n) => {
+  if (n < 0) throw new Error('Must be positive')  // Don't throw in transform
+  return n
+})
+```
+
+**Correct (using appropriate method):**
+
+```typescript
+import { z } from 'zod'
+
+// VALIDATION: Use refine - returns boolean, data unchanged
+const positiveNumber = z.number().refine(
+  (n) => n > 0,
+  { message: 'Must be positive' }
+)
+
+positiveNumber.parse(5)  // 5
+positiveNumber.parse(-1)  // ZodError: Must be positive
+
+// CONVERSION: Use transform - returns new value
+const stringLength = z.string().transform((s) => s.length)
+
+type StringLength = z.infer<typeof stringLength>  // number
+stringLength.parse('hello')  // 5
+
+// COERCION: Use coerce - converts input type
+const coercedNumber = z.coerce.number()
+
+coercedNumber.parse('42')  // 42 (from string)
+coercedNumber.parse(42)  // 42 (already number)
+```
+
+**Combining methods correctly:**
+
+```typescript
+// Input: string -> Coerce to number -> Validate positive -> Transform to dollars
+const priceSchema = z.coerce
+  .number()
+  .refine((n) => n >= 0, 'Price cannot be negative')
+  .transform((cents) => `$${(cents / 100).toFixed(2)}`)
+
+priceSchema.parse('1999')  // "$19.99"
+priceSchema.parse('-100')  // ZodError: Price cannot be negative
+```
+
+**Order of operations:**
+
+```typescript
+const schema = z
+  .preprocess(val => val, z.string())  // 1. preprocess (before type check)
+  .transform(s => s.trim())             // 2. transform (after type check)
+  .refine(s => s.length > 0)            // 3. refine (custom validation)
+  .transform(s => s.toUpperCase())      // 4. another transform
+
+// Input flows: preprocess -> type check -> transforms/refines in order
+```
+
+**Use case comparison:**
+
+| Need | Method | Example |
+|------|--------|---------|
+| Convert string to number | `z.coerce.number()` | Form input |
+| Validate number is positive | `.refine(n => n > 0)` | Business rule |
+| Convert cents to dollars | `.transform(n => n/100)` | Display format |
+| Trim whitespace before check | `z.preprocess` | Input cleanup |
+
+**When NOT to use this pattern:**
+- Simple type coercion: use `z.coerce.*`
+- Simple validation: use built-in methods like `.min()`, `.email()`
+
+Reference: [Zod API - transform](https://zod.dev/api#transform)
diff --git a/.agents/skills/zod/references/refine-vs-superrefine.md b/.agents/skills/zod/references/refine-vs-superrefine.md
new file mode 100644
index 0000000..2a666e5
--- /dev/null
+++ b/.agents/skills/zod/references/refine-vs-superrefine.md
@@ -0,0 +1,152 @@
+---
+title: Choose refine() vs superRefine() Correctly
+impact: MEDIUM
+impactDescription: refine() only reports one error; superRefine() enables multiple issues and custom error codes
+tags: refine, superRefine, validation, custom
+---
+
+## Choose refine() vs superRefine() Correctly
+
+`.refine()` is for simple single-condition validation returning boolean. `.superRefine()` gives you a context object to add multiple issues with custom error codes and paths. Choose based on your error reporting needs.
+
+**Incorrect (using refine for multiple checks):**
+
+```typescript
+import { z } from 'zod'
+
+// refine can only report one error at a time
+const passwordSchema = z.string().refine(
+  (password) => {
+    // Checks all conditions but only reports first failure
+    if (password.length < 8) return false  // Only this error shown
+    if (!/[A-Z]/.test(password)) return false
+    if (!/[0-9]/.test(password)) return false
+    return true
+  },
+  { message: 'Password does not meet requirements' }
+)
+
+passwordSchema.parse('weak')
+// Only shows: "Password does not meet requirements"
+// User doesn't know WHICH requirements failed
+```
+
+**Correct (using superRefine for multiple issues):**
+
+```typescript
+import { z } from 'zod'
+
+const passwordSchema = z.string().superRefine((password, ctx) => {
+  if (password.length < 8) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must be at least 8 characters',
+    })
+  }
+
+  if (!/[A-Z]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must contain an uppercase letter',
+    })
+  }
+
+  if (!/[0-9]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must contain a number',
+    })
+  }
+
+  if (!/[!@#$%^&*]/.test(password)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Password must contain a special character',
+    })
+  }
+})
+
+passwordSchema.safeParse('weak')
+// Shows ALL failures:
+// - "Password must be at least 8 characters"
+// - "Password must contain an uppercase letter"
+// - "Password must contain a number"
+// - "Password must contain a special character"
+```
+
+**When to use refine():**
+
+```typescript
+// Simple boolean condition with one error message
+const adultSchema = z.number().refine(
+  (age) => age >= 18,
+  { message: 'Must be 18 or older' }
+)
+
+// Cross-field validation with single outcome
+const formSchema = z.object({
+  password: z.string(),
+  confirmPassword: z.string(),
+}).refine(
+  (data) => data.password === data.confirmPassword,
+  { message: 'Passwords must match', path: ['confirmPassword'] }
+)
+
+// Async validation
+const emailSchema = z.string().email().refine(
+  async (email) => {
+    const exists = await checkEmailExists(email)
+    return !exists
+  },
+  { message: 'Email already registered' }
+)
+```
+
+**When to use superRefine():**
+
+```typescript
+// Multiple independent checks on same value
+// Cross-field validation with multiple possible errors
+// Need custom error codes for i18n or client handling
+// Need to add issues at specific paths
+
+const orderSchema = z.object({
+  items: z.array(z.object({
+    productId: z.string(),
+    quantity: z.number(),
+  })),
+  promoCode: z.string().optional(),
+}).superRefine(async (order, ctx) => {
+  // Check each item's availability
+  for (let i = 0; i < order.items.length; i++) {
+    const item = order.items[i]
+    const available = await checkInventory(item.productId, item.quantity)
+
+    if (!available) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['items', i, 'quantity'],  // Specific path
+        message: `Only ${available} units available`,
+      })
+    }
+  }
+
+  // Validate promo code
+  if (order.promoCode) {
+    const valid = await validatePromoCode(order.promoCode)
+    if (!valid) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['promoCode'],
+        message: 'Invalid or expired promo code',
+      })
+    }
+  }
+})
+```
+
+**When NOT to use this pattern:**
+- Simple single-condition checks (use refine for simplicity)
+- Transform needed instead of validation (use transform)
+
+Reference: [Zod API - refine/superRefine](https://zod.dev/api#refine)
diff --git a/.agents/skills/zod/references/schema-avoid-optional-abuse.md b/.agents/skills/zod/references/schema-avoid-optional-abuse.md
new file mode 100644
index 0000000..d5f1063
--- /dev/null
+++ b/.agents/skills/zod/references/schema-avoid-optional-abuse.md
@@ -0,0 +1,93 @@
+---
+title: Avoid Overusing Optional Fields
+impact: CRITICAL
+impactDescription: Excessive optional fields create schemas that accept almost anything; forces null checks throughout codebase
+tags: schema, optional, nullable, required
+---
+
+## Avoid Overusing Optional Fields
+
+Making too many fields optional creates overly permissive schemas that validate almost any input. This pushes validation downstream into business logic, requiring defensive null checks everywhere instead of guaranteeing data shape at the boundary.
+
+**Incorrect (optional abuse):**
+
+```typescript
+import { z } from 'zod'
+
+// Every field optional - almost anything passes
+const userSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  email: z.string().optional(),
+  role: z.string().optional(),
+})
+
+type User = z.infer<typeof userSchema>
+// { id?: string; name?: string; email?: string; role?: string }
+
+// Empty object passes validation!
+userSchema.parse({})  // ✓ Valid: {}
+
+function greetUser(user: User) {
+  // Forced to add null checks everywhere
+  if (user.name) {
+    console.log(`Hello, ${user.name}`)
+  } else {
+    console.log('Hello, stranger')  // Shouldn't happen if data is clean
+  }
+}
+```
+
+**Correct (explicit required vs optional):**
+
+```typescript
+import { z } from 'zod'
+
+// Required fields are required, optional fields are intentional
+const userSchema = z.object({
+  id: z.string().uuid(),  // Required
+  name: z.string().min(1),  // Required, non-empty
+  email: z.string().email(),  // Required
+  role: z.enum(['admin', 'user', 'guest']),  // Required
+  nickname: z.string().optional(),  // Intentionally optional
+  bio: z.string().nullable(),  // Can be explicitly null
+})
+
+type User = z.infer<typeof userSchema>
+
+// Empty object fails validation
+userSchema.parse({})  // ✗ Throws ZodError
+
+function greetUser(user: User) {
+  // user.name is guaranteed to exist
+  console.log(`Hello, ${user.name}`)
+
+  // Only optional fields need checks
+  if (user.nickname) {
+    console.log(`Also known as: ${user.nickname}`)
+  }
+}
+```
+
+**Use `.partial()` for update schemas:**
+
+```typescript
+// Base schema with required fields
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+})
+
+// All fields optional for PATCH updates
+const updateUserSchema = userSchema.partial()
+
+// Only specific fields optional
+const createUserSchema = userSchema.partial({ id: true })
+```
+
+**When NOT to use this pattern:**
+- When modeling partial updates (PATCH endpoints)
+- When fields genuinely may not exist (legacy data, external APIs)
+
+Reference: [Zod API - optional](https://zod.dev/api#optional)
diff --git a/.agents/skills/zod/references/schema-coercion-for-form-data.md b/.agents/skills/zod/references/schema-coercion-for-form-data.md
new file mode 100644
index 0000000..a8cc05f
--- /dev/null
+++ b/.agents/skills/zod/references/schema-coercion-for-form-data.md
@@ -0,0 +1,88 @@
+---
+title: Use Coercion for Form and Query Data
+impact: CRITICAL
+impactDescription: Form data and query params are always strings; without coercion, z.number() rejects "42" and z.boolean() rejects "true"
+tags: schema, coerce, forms, query-params
+---
+
+## Use Coercion for Form and Query Data
+
+HTML forms and URL query parameters always transmit data as strings. Using `z.number()` on form data will fail because `"42"` is not a number. Use `z.coerce.number()` to automatically convert strings to the correct type.
+
+**Incorrect (no coercion for form data):**
+
+```typescript
+import { z } from 'zod'
+
+const searchSchema = z.object({
+  query: z.string(),
+  page: z.number(),  // Expects actual number
+  limit: z.number(),
+  showDeleted: z.boolean(),  // Expects actual boolean
+})
+
+// Form data / query params are strings
+const formData = new URLSearchParams('query=test&page=1&limit=10&showDeleted=true')
+const params = Object.fromEntries(formData)
+// { query: 'test', page: '1', limit: '10', showDeleted: 'true' }
+
+searchSchema.parse(params)
+// ZodError: Expected number, received string at "page"
+// ZodError: Expected number, received string at "limit"
+// ZodError: Expected boolean, received string at "showDeleted"
+```
+
+**Correct (using coercion):**
+
+```typescript
+import { z } from 'zod'
+
+const searchSchema = z.object({
+  query: z.string(),
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  showDeleted: z.coerce.boolean().default(false),
+})
+
+// Form data / query params are strings
+const formData = new URLSearchParams('query=test&page=1&limit=10&showDeleted=true')
+const params = Object.fromEntries(formData)
+
+const result = searchSchema.parse(params)
+// { query: 'test', page: 1, limit: 10, showDeleted: true }
+// Types are correct: number, number, boolean
+```
+
+**Available coercion types:**
+
+```typescript
+z.coerce.string()  // Converts anything to string via String(value)
+z.coerce.number()  // Converts via Number(value), NaN fails validation
+z.coerce.boolean()  // Truthy/falsy conversion
+z.coerce.bigint()  // Converts via BigInt(value)
+z.coerce.date()  // Converts via new Date(value)
+```
+
+**Coercion edge cases:**
+
+```typescript
+// z.coerce.number() behavior
+z.coerce.number().parse("42")  // 42
+z.coerce.number().parse("")  // 0 (empty string becomes 0!)
+z.coerce.number().parse("abc")  // ZodError (NaN fails)
+
+// z.coerce.boolean() behavior
+z.coerce.boolean().parse("true")  // true
+z.coerce.boolean().parse("false")  // true! (non-empty string is truthy)
+z.coerce.boolean().parse("")  // false
+z.coerce.boolean().parse("0")  // true! (non-empty string)
+
+// For strict boolean parsing from strings:
+const strictBooleanSchema = z.enum(['true', 'false']).transform(v => v === 'true')
+```
+
+**When NOT to use this pattern:**
+- When receiving JSON payloads (already typed correctly)
+- When you want strict type checking without conversion
+
+Reference: [Zod API - Coercion](https://zod.dev/api#coercion)
diff --git a/.agents/skills/zod/references/schema-string-validations.md b/.agents/skills/zod/references/schema-string-validations.md
new file mode 100644
index 0000000..7a130b6
--- /dev/null
+++ b/.agents/skills/zod/references/schema-string-validations.md
@@ -0,0 +1,90 @@
+---
+title: Apply String Validations at Schema Definition
+impact: CRITICAL
+impactDescription: Unvalidated strings allow SQL injection, XSS, and malformed data; validating at schema level catches issues at the boundary
+tags: schema, string, validation, security
+---
+
+## Apply String Validations at Schema Definition
+
+Plain `z.string()` accepts any string including empty strings, extremely long strings, and malicious content. Apply constraints like `min()`, `max()`, `email()`, `url()`, or `regex()` at schema definition to reject invalid data at the boundary.
+
+**Incorrect (no string validations):**
+
+```typescript
+import { z } from 'zod'
+
+const commentSchema = z.object({
+  author: z.string(),  // Empty string passes
+  email: z.string(),  // "not-an-email" passes
+  content: z.string(),  // 10MB string passes, script tags pass
+  website: z.string().optional(),  // "javascript:alert(1)" passes
+})
+
+// All of these pass validation
+commentSchema.parse({
+  author: '',  // Empty - who wrote this?
+  email: 'invalid',  // Not a real email
+  content: '<script>alert("XSS")</script>'.repeat(100000),  // XSS + huge
+  website: 'javascript:void(0)',  // Dangerous URL
+})
+```
+
+**Correct (string validations applied):**
+
+```typescript
+import { z } from 'zod'
+
+const commentSchema = z.object({
+  author: z.string()
+    .min(1, 'Author is required')
+    .max(100, 'Author name too long'),
+
+  email: z.string()
+    .email('Invalid email address'),
+
+  content: z.string()
+    .min(1, 'Comment cannot be empty')
+    .max(5000, 'Comment too long'),
+
+  website: z.string()
+    .url('Invalid URL')
+    .refine(
+      url => url.startsWith('http://') || url.startsWith('https://'),
+      'Only http/https URLs allowed'
+    )
+    .optional(),
+})
+
+// Invalid data is rejected
+commentSchema.parse({
+  author: '',
+  email: 'invalid',
+  content: '',
+})
+// ZodError with all violations listed
+```
+
+**Common string validations:**
+
+```typescript
+z.string().min(1)  // Non-empty (most common need)
+z.string().max(255)  // Database varchar limit
+z.string().length(36)  // Exact length (UUIDs)
+z.string().email()  // Email format
+z.string().url()  // URL format
+z.string().uuid()  // UUID format
+z.string().cuid()  // CUID format
+z.string().regex(/^[a-z0-9-]+$/)  // Custom pattern (slugs)
+z.string().startsWith('https://')  // Prefix check
+z.string().endsWith('.pdf')  // Suffix check
+z.string().includes('@')  // Contains check
+z.string().trim()  // Strips whitespace (transform)
+z.string().toLowerCase()  // Normalizes case (transform)
+```
+
+**When NOT to use this pattern:**
+- When accepting arbitrary user content for display only (sanitize on output instead)
+- When building a passthrough/proxy that shouldn't validate content
+
+Reference: [Zod API - Strings](https://zod.dev/api#strings)
diff --git a/.agents/skills/zod/references/schema-use-enums.md b/.agents/skills/zod/references/schema-use-enums.md
new file mode 100644
index 0000000..085f9bb
--- /dev/null
+++ b/.agents/skills/zod/references/schema-use-enums.md
@@ -0,0 +1,107 @@
+---
+title: Use Enums for Fixed String Values
+impact: CRITICAL
+impactDescription: Plain strings accept any value including typos; enums restrict to valid values and enable autocomplete
+tags: schema, enum, literal, union
+---
+
+## Use Enums for Fixed String Values
+
+When a field should only accept specific values (status, role, type), use `z.enum()` or `z.literal()` instead of `z.string()`. Plain strings accept any value including typos, while enums provide validation, type safety, and IDE autocomplete.
+
+**Incorrect (plain string for fixed values):**
+
+```typescript
+import { z } from 'zod'
+
+const orderSchema = z.object({
+  id: z.string(),
+  status: z.string(),  // Accepts any string
+  priority: z.string(),  // No constraints
+})
+
+type Order = z.infer<typeof orderSchema>
+// { id: string; status: string; priority: string }
+
+// Typos and invalid values pass validation
+orderSchema.parse({
+  id: '123',
+  status: 'pendng',  // Typo passes
+  priority: 'super-urgent',  // Invalid value passes
+})
+
+function processOrder(order: Order) {
+  if (order.status === 'pending') {  // Might never match due to typos
+    // ...
+  }
+}
+```
+
+**Correct (using z.enum):**
+
+```typescript
+import { z } from 'zod'
+
+const OrderStatus = z.enum(['pending', 'processing', 'shipped', 'delivered'])
+const Priority = z.enum(['low', 'medium', 'high'])
+
+const orderSchema = z.object({
+  id: z.string(),
+  status: OrderStatus,
+  priority: Priority,
+})
+
+type Order = z.infer<typeof orderSchema>
+// { id: string; status: 'pending' | 'processing' | 'shipped' | 'delivered'; priority: 'low' | 'medium' | 'high' }
+
+// Typos are caught at validation
+orderSchema.parse({
+  id: '123',
+  status: 'pendng',  // ZodError: Invalid enum value
+  priority: 'super-urgent',  // ZodError: Invalid enum value
+})
+
+// Extract enum values for reuse
+OrderStatus.options  // ['pending', 'processing', 'shipped', 'delivered']
+type OrderStatusType = z.infer<typeof OrderStatus>  // 'pending' | 'processing' | ...
+```
+
+**For native TypeScript enums:**
+
+```typescript
+enum Role {
+  Admin = 'admin',
+  User = 'user',
+  Guest = 'guest',
+}
+
+// Use z.nativeEnum for TS enums
+const userSchema = z.object({
+  role: z.nativeEnum(Role),
+})
+```
+
+**For single literal values (discriminated unions):**
+
+```typescript
+const successResponse = z.object({
+  status: z.literal('success'),
+  data: z.unknown(),
+})
+
+const errorResponse = z.object({
+  status: z.literal('error'),
+  message: z.string(),
+})
+
+const response = z.discriminatedUnion('status', [
+  successResponse,
+  errorResponse,
+])
+```
+
+**When NOT to use this pattern:**
+- When the set of valid values is dynamic or user-defined
+- When values come from a database that may have more options
+
+Reference: [Zod API - Enums](https://zod.dev/api#enums)
diff --git a/.agents/skills/zod/references/schema-use-primitives-correctly.md b/.agents/skills/zod/references/schema-use-primitives-correctly.md
new file mode 100644
index 0000000..06810fe
--- /dev/null
+++ b/.agents/skills/zod/references/schema-use-primitives-correctly.md
@@ -0,0 +1,61 @@
+---
+title: Use Primitive Schemas Correctly
+impact: CRITICAL
+impactDescription: Incorrect primitive selection causes validation to pass on wrong types; using z.any() or z.unknown() loses all type safety
+tags: schema, primitives, types, basics
+---
+
+## Use Primitive Schemas Correctly
+
+Zod provides specific schemas for each primitive type. Using the wrong schema (e.g., `z.string()` when you need `z.number()`) or falling back to `z.any()` defeats the purpose of validation entirely, allowing corrupt data through.
+
+**Incorrect (wrong primitive or any):**
+
+```typescript
+import { z } from 'zod'
+
+// Using any loses all type safety
+const userSchema = z.object({
+  id: z.any(),  // Accepts anything - no validation
+  age: z.string(),  // Wrong type - age should be number
+  active: z.any(),  // Should be boolean
+})
+
+// This passes validation but data is wrong
+userSchema.parse({ id: null, age: "twenty", active: "yes" })
+// Result: { id: null, age: "twenty", active: "yes" }
+```
+
+**Correct (specific primitives):**
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  id: z.string().uuid(),  // Specific format validation
+  age: z.number().int().positive(),  // Correct type with constraints
+  active: z.boolean(),  // Exact boolean type
+})
+
+// Now invalid data is rejected
+userSchema.parse({ id: null, age: "twenty", active: "yes" })
+// Throws ZodError with specific field errors
+```
+
+**Available primitive schemas:**
+- `z.string()` - strings with optional regex, min, max, email, url, uuid
+- `z.number()` - numbers with optional int, positive, negative, min, max
+- `z.bigint()` - BigInt values
+- `z.boolean()` - true/false only
+- `z.date()` - Date objects
+- `z.symbol()` - Symbol type
+- `z.undefined()` - undefined only
+- `z.null()` - null only
+- `z.void()` - undefined (for function returns)
+- `z.never()` - no valid value
+
+**When NOT to use this pattern:**
+- When you genuinely need to accept any value (rare - consider `z.unknown()` instead)
+- When migrating legacy code incrementally (use `z.any()` temporarily, then fix)
+
+Reference: [Zod Primitives](https://zod.dev/api#primitives)
diff --git a/.agents/skills/zod/references/schema-use-unknown-not-any.md b/.agents/skills/zod/references/schema-use-unknown-not-any.md
new file mode 100644
index 0000000..f13cf3b
--- /dev/null
+++ b/.agents/skills/zod/references/schema-use-unknown-not-any.md
@@ -0,0 +1,88 @@
+---
+title: Use z.unknown() Instead of z.any()
+impact: CRITICAL
+impactDescription: z.any() bypasses TypeScript's type system entirely; z.unknown() forces type narrowing before use
+tags: schema, unknown, any, type-safety
+---
+
+## Use z.unknown() Instead of z.any()
+
+`z.any()` infers to `any` type, disabling TypeScript's type checking for that value. `z.unknown()` infers to `unknown`, which forces you to narrow the type before using it. This preserves type safety while still allowing any input.
+
+**Incorrect (using z.any):**
+
+```typescript
+import { z } from 'zod'
+
+const eventSchema = z.object({
+  type: z.string(),
+  payload: z.any(),  // Infers to 'any'
+})
+
+type Event = z.infer<typeof eventSchema>
+// { type: string; payload: any }
+
+function handleEvent(event: Event) {
+  // No type error - TypeScript allows anything
+  console.log(event.payload.foo.bar.baz)  // Runtime crash if structure is wrong
+}
+```
+
+**Correct (using z.unknown):**
+
+```typescript
+import { z } from 'zod'
+
+const eventSchema = z.object({
+  type: z.string(),
+  payload: z.unknown(),  // Infers to 'unknown'
+})
+
+type Event = z.infer<typeof eventSchema>
+// { type: string; payload: unknown }
+
+function handleEvent(event: Event) {
+  // TypeScript error: Object is of type 'unknown'
+  console.log(event.payload.foo)  // Won't compile
+
+  // Must narrow type first
+  if (typeof event.payload === 'object' && event.payload !== null) {
+    // Now TypeScript knows it's an object
+  }
+}
+```
+
+**Better approach with discriminated unions:**
+
+```typescript
+import { z } from 'zod'
+
+const userCreatedSchema = z.object({
+  type: z.literal('user.created'),
+  payload: z.object({
+    userId: z.string(),
+    email: z.string().email(),
+  }),
+})
+
+const orderPlacedSchema = z.object({
+  type: z.literal('order.placed'),
+  payload: z.object({
+    orderId: z.string(),
+    amount: z.number(),
+  }),
+})
+
+const eventSchema = z.discriminatedUnion('type', [
+  userCreatedSchema,
+  orderPlacedSchema,
+])
+
+// Full type safety for each event type
+```
+
+**When NOT to use this pattern:**
+- When you're consuming a third-party API where you truly don't know the shape
+- When prototyping and will add proper types later
+
+Reference: [Zod API - unknown](https://zod.dev/api#unknown)
diff --git a/.agents/skills/zod/references/type-branded-types.md b/.agents/skills/zod/references/type-branded-types.md
new file mode 100644
index 0000000..57da3f7
--- /dev/null
+++ b/.agents/skills/zod/references/type-branded-types.md
@@ -0,0 +1,102 @@
+---
+title: Use Branded Types for Domain Safety
+impact: HIGH
+impactDescription: Plain string IDs are interchangeable, allowing userId where orderId is expected; branded types catch these bugs at compile time
+tags: type, brand, domain, nominal
+---
+
+## Use Branded Types for Domain Safety
+
+Plain strings and numbers are interchangeable in TypeScript's structural type system—a `userId` can be passed where an `orderId` is expected. Zod's `.brand()` creates nominal types that prevent mixing up semantically different values.
+
+**Incorrect (plain IDs are interchangeable):**
+
+```typescript
+import { z } from 'zod'
+
+const userIdSchema = z.string().uuid()
+const orderIdSchema = z.string().uuid()
+
+type UserId = z.infer<typeof userIdSchema>  // string
+type OrderId = z.infer<typeof orderIdSchema>  // string - same type!
+
+async function getOrder(orderId: OrderId) {
+  return db.orders.findUnique({ where: { id: orderId } })
+}
+
+const userId: UserId = '550e8400-e29b-41d4-a716-446655440000'
+getOrder(userId)  // No error! TypeScript allows this bug
+// Runtime: queries orders table with user ID, returns nothing or wrong data
+```
+
+**Correct (using branded types):**
+
+```typescript
+import { z } from 'zod'
+
+const userIdSchema = z.string().uuid().brand<'UserId'>()
+const orderIdSchema = z.string().uuid().brand<'OrderId'>()
+
+type UserId = z.infer<typeof userIdSchema>
+// string & { __brand: 'UserId' }
+
+type OrderId = z.infer<typeof orderIdSchema>
+// string & { __brand: 'OrderId' }
+
+async function getOrder(orderId: OrderId) {
+  return db.orders.findUnique({ where: { id: orderId } })
+}
+
+const userId = userIdSchema.parse('550e8400-e29b-41d4-a716-446655440000')
+getOrder(userId)  // TypeScript error: Argument of type 'UserId' is not assignable to parameter of type 'OrderId'
+
+const orderId = orderIdSchema.parse('660e8400-e29b-41d4-a716-446655440001')
+getOrder(orderId)  // Works correctly
+```
+
+**Common branded types:**
+
+```typescript
+// IDs for different entities
+const UserId = z.string().uuid().brand<'UserId'>()
+const ProductId = z.string().uuid().brand<'ProductId'>()
+const OrderId = z.string().uuid().brand<'OrderId'>()
+
+// Email (validated and branded)
+const Email = z.string().email().brand<'Email'>()
+
+// Positive numbers
+const PositiveInt = z.number().int().positive().brand<'PositiveInt'>()
+
+// Money amounts (in cents)
+const Cents = z.number().int().nonnegative().brand<'Cents'>()
+
+// Slugs
+const Slug = z.string().regex(/^[a-z0-9-]+$/).brand<'Slug'>()
+```
+
+**Using with object schemas:**
+
+```typescript
+const User = z.object({
+  id: z.string().uuid().brand<'UserId'>(),
+  email: z.string().email().brand<'Email'>(),
+  referredBy: z.string().uuid().brand<'UserId'>().optional(),
+})
+
+type User = z.infer<typeof User>
+
+function sendReferralBonus(
+  referrerId: z.infer<typeof User>['id'],
+  refereeId: z.infer<typeof User>['id']
+) {
+  // Can't accidentally swap these - both are UserId but distinct values
+}
+```
+
+**When NOT to use this pattern:**
+- Simple applications without ID confusion risk
+- When interoperating with external systems that expect plain strings
+- Performance-critical paths (brand adds tiny overhead)
+
+Reference: [Zod API - brand](https://zod.dev/api#brand)
diff --git a/.agents/skills/zod/references/type-enable-strict-mode.md b/.agents/skills/zod/references/type-enable-strict-mode.md
new file mode 100644
index 0000000..8ddeba3
--- /dev/null
+++ b/.agents/skills/zod/references/type-enable-strict-mode.md
@@ -0,0 +1,130 @@
+---
+title: Enable TypeScript Strict Mode
+impact: HIGH
+impactDescription: Without strict mode, Zod's type inference is unreliable; undefined and null slip through, defeating the purpose of validation
+tags: type, typescript, strict, configuration
+---
+
+## Enable TypeScript Strict Mode
+
+Zod requires TypeScript's strict mode to work correctly. Without it, `undefined` sneaks into types, `null` checks are bypassed, and type inference becomes unreliable. This undermines the type safety that Zod provides.
+
+**Incorrect (strict mode disabled):**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": false
+  }
+}
+```
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+})
+
+type User = z.infer<typeof userSchema>
+// With strict:false, type might include undefined implicitly
+
+function processUser(user: User) {
+  // No error even if user.name could be undefined
+  console.log(user.name.toUpperCase())  // Potential runtime crash
+}
+
+// TypeScript allows calling with undefined
+processUser(undefined as any)  // No warning
+```
+
+**Correct (strict mode enabled):**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+})
+
+type User = z.infer<typeof userSchema>
+// { name: string; email: string } - no implicit undefined
+
+function processUser(user: User) {
+  // TypeScript knows name is always string
+  console.log(user.name.toUpperCase())  // Safe
+}
+
+// TypeScript catches potential undefined
+processUser(undefined as any)  // Error with strict null checks
+```
+
+**Minimum strict settings for Zod:**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    // Full strict mode (recommended)
+    "strict": true,
+
+    // Or at minimum, enable these:
+    "strictNullChecks": true,
+    "noImplicitAny": true
+  }
+}
+```
+
+**Common errors when strict mode is disabled:**
+
+```typescript
+// Without strictNullChecks
+const schema = z.string().optional()
+type MaybeString = z.infer<typeof schema>
+// Should be: string | undefined
+// Without strict: just string (undefined is implicit)
+
+// Without noImplicitAny
+const schema = z.object({ name: z.string() })
+schema.parse(data)  // data could be 'any', bypassing validation
+```
+
+**Migrating to strict mode:**
+
+```typescript
+// If enabling strict breaks existing code, fix issues incrementally
+// Common fixes:
+
+// 1. Add null checks
+if (user.name !== undefined) {
+  console.log(user.name.toUpperCase())
+}
+
+// 2. Add explicit types
+function processData(data: unknown) {  // Was implicit any
+  const validated = schema.parse(data)
+}
+
+// 3. Handle optional fields
+const user: User = {
+  name: 'John',
+  email: 'john@example.com',  // Now required, was optional without strict
+}
+```
+
+**When NOT to use this pattern:**
+- Never - always enable strict mode for Zod projects
+
+Reference: [Zod Requirements](https://zod.dev/#requirements)
diff --git a/.agents/skills/zod/references/type-export-schemas-and-types.md b/.agents/skills/zod/references/type-export-schemas-and-types.md
new file mode 100644
index 0000000..2f38dc0
--- /dev/null
+++ b/.agents/skills/zod/references/type-export-schemas-and-types.md
@@ -0,0 +1,116 @@
+---
+title: Export Both Schemas and Inferred Types
+impact: HIGH
+impactDescription: Exporting only schemas forces consumers to derive types themselves; exporting both reduces boilerplate and improves DX
+tags: type, export, module, organization
+---
+
+## Export Both Schemas and Inferred Types
+
+When defining schemas in shared modules, export both the schema and its inferred type. This saves consumers from writing `z.infer<typeof schema>` repeatedly and makes imports cleaner.
+
+**Incorrect (exporting only schema):**
+
+```typescript
+// schemas/user.ts
+import { z } from 'zod'
+
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  role: z.enum(['admin', 'user']),
+})
+
+// Every consumer must derive the type
+// api/users.ts
+import { userSchema } from '@/schemas/user'
+import type { z } from 'zod'
+
+type User = z.infer<typeof userSchema>  // Repeated everywhere
+
+// components/UserCard.tsx
+import { userSchema } from '@/schemas/user'
+import type { z } from 'zod'
+
+type User = z.infer<typeof userSchema>  // Same boilerplate again
+```
+
+**Correct (exporting schema and type):**
+
+```typescript
+// schemas/user.ts
+import { z } from 'zod'
+
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  role: z.enum(['admin', 'user']),
+})
+
+export type User = z.infer<typeof userSchema>
+
+// For schemas with transforms, export both
+export const apiUserSchema = z.object({
+  id: z.string(),
+  created_at: z.string().transform(s => new Date(s)),
+})
+
+export type ApiUserInput = z.input<typeof apiUserSchema>
+export type ApiUser = z.infer<typeof apiUserSchema>
+```
+
+```typescript
+// api/users.ts - clean import
+import { userSchema, type User } from '@/schemas/user'
+
+async function getUser(id: string): Promise<User> {
+  const data = await db.users.findUnique({ where: { id } })
+  return userSchema.parse(data)
+}
+
+// components/UserCard.tsx - just the type
+import type { User } from '@/schemas/user'
+
+function UserCard({ user }: { user: User }) {
+  return <div>{user.name}</div>
+}
+```
+
+**Organizing schema exports:**
+
+```typescript
+// schemas/index.ts - barrel file for schemas
+export { userSchema, type User, type UserInput } from './user'
+export { orderSchema, type Order } from './order'
+export { productSchema, type Product } from './product'
+
+// Usage
+import { userSchema, type User, type Order } from '@/schemas'
+```
+
+**With enums, export the enum values too:**
+
+```typescript
+// schemas/user.ts
+export const UserRole = z.enum(['admin', 'user', 'guest'])
+export type UserRole = z.infer<typeof UserRole>
+
+export const userSchema = z.object({
+  id: z.string(),
+  role: UserRole,
+})
+
+export type User = z.infer<typeof userSchema>
+
+// Access enum values
+UserRole.options  // ['admin', 'user', 'guest']
+UserRole.enum.admin  // 'admin'
+```
+
+**When NOT to use this pattern:**
+- Internal schemas that won't be used outside the module
+- Transient schemas used only for validation (not as types)
+
+Reference: [Zod API - Type Inference](https://zod.dev/api#type-inference)
diff --git a/.agents/skills/zod/references/type-input-vs-output.md b/.agents/skills/zod/references/type-input-vs-output.md
new file mode 100644
index 0000000..2ebb93a
--- /dev/null
+++ b/.agents/skills/zod/references/type-input-vs-output.md
@@ -0,0 +1,116 @@
+---
+title: Distinguish z.input from z.infer for Transforms
+impact: HIGH
+impactDescription: Using wrong type with transforms causes TypeScript errors; z.input captures pre-transform shape, z.infer captures post-transform
+tags: type, input, output, transform
+---
+
+## Distinguish z.input from z.infer for Transforms
+
+When schemas use `.transform()`, the input and output types differ. `z.infer` (same as `z.output`) gives the post-transform type, while `z.input` gives the pre-transform type. Using the wrong one causes confusing TypeScript errors.
+
+**Incorrect (using infer for input type):**
+
+```typescript
+import { z } from 'zod'
+
+const dateSchema = z.string().transform(s => new Date(s))
+
+type DateOutput = z.infer<typeof dateSchema>
+// Date (post-transform)
+
+// Wrong! Expecting Date but should accept string
+function handleDate(input: DateOutput) {
+  return dateSchema.parse(input)  // Error: Argument of type 'Date' is not assignable to type 'string'
+}
+
+// Caller passes string, but type says Date
+handleDate('2024-01-15')  // TypeScript error
+```
+
+**Correct (using z.input for pre-transform type):**
+
+```typescript
+import { z } from 'zod'
+
+const dateSchema = z.string().transform(s => new Date(s))
+
+// Input type = what parse() accepts
+type DateInput = z.input<typeof dateSchema>
+// string (pre-transform)
+
+// Output type = what parse() returns
+type DateOutput = z.output<typeof dateSchema>
+// Date (post-transform)
+
+// Use input type for function parameters
+function handleDate(input: DateInput) {
+  const parsed = dateSchema.parse(input)  // parsed is Date
+  return parsed
+}
+
+handleDate('2024-01-15')  // Works - string input
+```
+
+**Complex example with object transforms:**
+
+```typescript
+const apiUserSchema = z.object({
+  id: z.string(),
+  created_at: z.string().transform(s => new Date(s)),
+  tags: z.string().transform(s => s.split(',')),
+  is_active: z.union([z.boolean(), z.literal(1), z.literal(0)])
+    .transform(v => Boolean(v)),
+})
+
+// What the API sends
+type ApiUserInput = z.input<typeof apiUserSchema>
+// {
+//   id: string
+//   created_at: string
+//   tags: string
+//   is_active: boolean | 1 | 0
+// }
+
+// What your code works with
+type ApiUser = z.infer<typeof apiUserSchema>
+// {
+//   id: string
+//   created_at: Date
+//   tags: string[]
+//   is_active: boolean
+// }
+
+// API response handler
+function handleApiResponse(rawData: ApiUserInput) {
+  const user = apiUserSchema.parse(rawData)
+  // user.created_at is Date
+  // user.tags is string[]
+  // user.is_active is boolean
+  return user
+}
+```
+
+**Using with function types:**
+
+```typescript
+const formSchema = z.object({
+  amount: z.string().transform(s => parseFloat(s)),
+  quantity: z.string().transform(s => parseInt(s, 10)),
+})
+
+type FormInput = z.input<typeof formSchema>
+type FormOutput = z.output<typeof formSchema>
+
+// Form handler receives raw strings
+type FormHandler = (input: FormInput) => Promise<void>
+
+// Business logic receives parsed values
+type OrderProcessor = (order: FormOutput) => Promise<void>
+```
+
+**When NOT to use this pattern:**
+- Schemas without transforms (input and output are identical)
+- When you only work with validated data (just use z.infer)
+
+Reference: [Zod - Type Inference](https://zod.dev/api#type-inference)
diff --git a/.agents/skills/zod/references/type-use-z-infer.md b/.agents/skills/zod/references/type-use-z-infer.md
new file mode 100644
index 0000000..828afd1
--- /dev/null
+++ b/.agents/skills/zod/references/type-use-z-infer.md
@@ -0,0 +1,110 @@
+---
+title: Use z.infer Instead of Manual Types
+impact: HIGH
+impactDescription: Manual type definitions drift from schemas over time; z.infer guarantees types match validation exactly
+tags: type, infer, typescript, dry
+---
+
+## Use z.infer Instead of Manual Types
+
+Defining TypeScript types separately from Zod schemas creates duplication that inevitably drifts. When you update a schema, you must remember to update the type—and you will forget. Use `z.infer<typeof schema>` to derive types from schemas automatically.
+
+**Incorrect (manual type definitions):**
+
+```typescript
+import { z } from 'zod'
+
+// Manual type definition
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+}
+
+// Separate schema
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+  role: z.enum(['admin', 'user']),  // Added to schema, forgot to add to interface!
+})
+
+// Type and schema are now out of sync
+function createUser(user: User) {
+  const validated = userSchema.parse(user)  // Has role
+  saveToDb(user)  // Missing role - TypeScript doesn't warn
+}
+```
+
+**Correct (using z.infer):**
+
+```typescript
+import { z } from 'zod'
+
+// Schema is the single source of truth
+const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+  role: z.enum(['admin', 'user']),
+})
+
+// Type is always in sync with schema
+type User = z.infer<typeof userSchema>
+// { id: string; name: string; email: string; age: number; role: 'admin' | 'user' }
+
+function createUser(user: User) {
+  // user.role exists because type is derived from schema
+  const validated = userSchema.parse(user)
+  saveToDb(validated)
+}
+```
+
+**Input vs Output types with transforms:**
+
+```typescript
+const userSchema = z.object({
+  name: z.string(),
+  createdAt: z.string().transform(s => new Date(s)),  // String in, Date out
+})
+
+// z.infer gives output type (after transforms)
+type User = z.infer<typeof userSchema>
+// { name: string; createdAt: Date }
+
+// z.input gives input type (before transforms)
+type UserInput = z.input<typeof userSchema>
+// { name: string; createdAt: string }
+
+// Use input type for function parameters accepting raw data
+function processUser(input: UserInput) {
+  const user = userSchema.parse(input)  // user is User type
+  return user.createdAt.getTime()  // Date methods available
+}
+```
+
+**Naming convention:**
+
+```typescript
+// Schema named with Schema suffix
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+// Type named without suffix
+type User = z.infer<typeof UserSchema>
+
+// Alternative: lowercase schema, uppercase type
+const userSchema = z.object({/*...*/})
+type User = z.infer<typeof userSchema>
+```
+
+**When NOT to use this pattern:**
+- When you need a type that's different from the validation schema
+- When interfacing with external types you don't control
+
+Reference: [Zod - Type Inference](https://zod.dev/api#type-inference)
diff --git a/skills-lock.json b/skills-lock.json
new file mode 100644
index 0000000..1ea0fca
--- /dev/null
+++ b/skills-lock.json
@@ -0,0 +1,119 @@
+{
+  "version": 1,
+  "skills": {
+    "better-auth-best-practices": {
+      "source": "better-auth/skills",
+      "sourceType": "github",
+      "skillPath": "better-auth/best-practices/SKILL.md",
+      "computedHash": "0c30be0e118c2b7a0c4c57bd9e63bf110c7e420a79ec6ce7997153f3b1e066ee"
+    },
+    "clean-code": {
+      "source": "sickn33/agentic-awesome-skills",
+      "sourceType": "github",
+      "skillPath": "skills/clean-code/SKILL.md",
+      "computedHash": "74bf6ded4f61ddcb593e7a29beb96c284f888cbe0639ad6e23710447c36ff19a"
+    },
+    "clean-code-principles": {
+      "source": "asyrafhussin/agent-skills",
+      "sourceType": "github",
+      "skillPath": "skills/clean-code-principles/SKILL.md",
+      "computedHash": "4c22dca6110d58f1454523dc3f192ef20d91f538233da9132b407edd041a4762"
+    },
+    "hono": {
+      "source": "honojs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/hono/SKILL.md",
+      "computedHash": "dd3a1006c7fd59698e9eb6cefb82e4886df943eb71c0d35c3f0d608d1bffe157"
+    },
+    "interface-design": {
+      "source": "dammyjay93/interface-design",
+      "sourceType": "github",
+      "skillPath": ".claude/skills/interface-design/SKILL.md",
+      "computedHash": "340cc79a1558f09371aa3eb689952a8b777c1d7362c24226e99693606a80828e"
+    },
+    "make-interfaces-feel-better": {
+      "source": "jakubkrehel/make-interfaces-feel-better",
+      "sourceType": "github",
+      "skillPath": "skills/make-interfaces-feel-better/SKILL.md",
+      "computedHash": "c8b15b529e088a318b2d3c17f0a97e15a7b1ce9ddab8bbdf9209e6ab7315cbde"
+    },
+    "prisma-client-api": {
+      "source": "prisma/skills",
+      "sourceType": "github",
+      "skillPath": "prisma-client-api/SKILL.md",
+      "computedHash": "cbbabff961c8e16b2d59f8c1ffb4e7e20be52154e778ab95121e0211d6d09969"
+    },
+    "prisma-postgres": {
+      "source": "prisma/skills",
+      "sourceType": "github",
+      "skillPath": "prisma-postgres/SKILL.md",
+      "computedHash": "0422727e18019add9208b86ce862964025acc011ff31fba1d59a01b836bd6272"
+    },
+    "react-hook-form": {
+      "source": "pproenca/dot-skills",
+      "sourceType": "github",
+      "skillPath": "skills/.curated/react-hook-form/SKILL.md",
+      "computedHash": "e9881245bb3f993f93c9fce336ca7a517ce39864aa46c95d04238fc5ebc4e4d1"
+    },
+    "shadcn": {
+      "source": "shadcn-ui/ui",
+      "sourceType": "github",
+      "skillPath": "skills/shadcn/SKILL.md",
+      "computedHash": "f615de216e085a84e31593ad0fa9062232adc40cd87b7c7ab2b8e49abf6500be"
+    },
+    "tanstack-query": {
+      "source": "tanstack-skills/tanstack-skills",
+      "sourceType": "github",
+      "skillPath": "plugins/tanstack-query/skills/tanstack-query/SKILL.md",
+      "computedHash": "b8a0477cd4d7bf8fa54d27f8e64d82388402f0d502591db50a357df5b9995c75"
+    },
+    "tanstack-query-best-practices": {
+      "source": "deckardger/tanstack-agent-skills",
+      "sourceType": "github",
+      "skillPath": "skills/tanstack-query/SKILL.md",
+      "computedHash": "21d2e8b7468a81d772b6527ad8ca178cc2f3f08af777bb9061333013ee88a0c9"
+    },
+    "tanstack-router": {
+      "source": "tanstack-skills/tanstack-skills",
+      "sourceType": "github",
+      "skillPath": "plugins/tanstack-router/skills/tanstack-router/SKILL.md",
+      "computedHash": "24beccc4016f91bab65547209cfd849ea5e66f3d5d92820683a9dd84669ced56"
+    },
+    "tanstack-table": {
+      "source": "tanstack-skills/tanstack-skills",
+      "sourceType": "github",
+      "skillPath": "plugins/tanstack-table/skills/tanstack-table/SKILL.md",
+      "computedHash": "d5ac71bd795696cd3310165c3ea0e435c310a0ac3c4e9dd45b39ed91b8dbcbb1"
+    },
+    "test-driven-development": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "skillPath": "skills/test-driven-development/SKILL.md",
+      "computedHash": "a4126a9c5f17be3c228aa9e5755898ade283448b86099f56f40852e8c14532be"
+    },
+    "typescript-advanced-types": {
+      "source": "wshobson/agents",
+      "sourceType": "github",
+      "skillPath": "plugins/javascript-typescript/skills/typescript-advanced-types/SKILL.md",
+      "computedHash": "8cbf2bf600f392d7260e476e3202932a876e2281cda3b15a8b6a5a43f383252d"
+    },
+    "typescript-clean-code": {
+      "source": "bmad-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/typescript-clean-code/SKILL.md",
+      "computedHash": "32dd11d590211d7098dfefe206e10acf929d6fcea28151a3994a1823b04df239"
+    },
+    "vercel-react-best-practices": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "skillPath": "skills/react-best-practices/SKILL.md",
+      "computedHash": "ca7b0c0c6e5f2750043f7f0cd72d16ac4e2abc48f9b5500d047a4b77a2506212"
+    },
+    "zod": {
+      "source": "pproenca/dot-skills",
+      "sourceType": "github",
+      "skillPath": "skills/.curated/zod/SKILL.md",
+      "computedHash": "c69b5133b65643317236707f2cd3e521b4fc6e5ee5fd6c6c00cf62a37dfd0144"
+    }
+  }
+}