Merge pull request #2 from batmn-dev/007-ai-agent-jk-im-batman

feat: migrate to pnpm monorepo with Turborepo and add AI agent context

Author: batmn-dev

.agents/context/README.md

@@ -0,0 +1,50 @@
+# AI Context Directory
+
+> Passive knowledge that AI agents can retrieve on-demand. This content is NOT automatically loaded.
+
+## Structure
+
+```
+context/
+├── research/       # Raw research materials, deep-dive documentation
+│   └── *.md        # Topic-specific research
+├── decisions/      # Architecture Decision Records (ADRs)
+│   └── NNN-*.md    # Numbered decision records
+└── glossary.md     # Project-specific terminology
+```
+
+## Purpose
+
+This directory contains **reference materials** (passive knowledge) that agents can fetch when needed, but that should NOT be included in every context window.
+
+### vs Skills
+
+| Context (`context/`) | Skills (`skills/`) |
+|---------------------|-------------------|
+| **WHAT** things are | **HOW** to do things |
+| Reference materials | Action-oriented instructions |
+| Loaded on-demand | Triggered by user request |
+| Background knowledge | Step-by-step procedures |
+
+### vs Workflows
+
+| Context (`context/`) | Workflows (`workflows/`) |
+|---------------------|-------------------------|
+| Understanding | Execution |
+| Research & decisions | Step-by-step procedures |
+| Read to learn | Follow to accomplish |
+
+## When to Add Here
+
+Add content to `context/` when:
+- It's background research that informs decisions
+- It's an Architecture Decision Record (ADR)
+- It defines terminology or concepts
+- It's too detailed for AGENTS.md but useful for deep dives
+
+## When NOT to Add Here
+
+Don't add content to `context/` when:
+- It's a step-by-step procedure → use `workflows/`
+- It's a reusable capability → use `skills/`
+- It needs to be in every session → use `AGENTS.md` or `.cursor/rules/`

.agents/context/decisions/001-use-oklch-colors.md

@@ -0,0 +1,52 @@
+# ADR-001: Use OKLCH Color Space for CSS Variables
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+When setting up the theming system for Usage UI, we needed to choose a color space for CSS variables. Options considered:
+- HSL (Hue, Saturation, Lightness)
+- RGB/Hex
+- OKLCH (OK Lightness, Chroma, Hue)
+
+## Decision
+
+Use **OKLCH** color space for all CSS variables.
+
+```css
+:root {
+  --meter-success: oklch(0.723 0.191 142.5);
+  --meter-warning: oklch(0.795 0.184 86.047);
+  --meter-danger: oklch(0.637 0.237 25.331);
+}
+```
+
+## Rationale
+
+1. **Perceptual uniformity**: OKLCH is perceptually uniform, meaning equal changes in values produce equal perceived changes in color.
+
+2. **shadcn/ui alignment**: shadcn/ui v4+ uses OKLCH as the default color space. Aligning with upstream reduces friction.
+
+3. **Better for programmatic manipulation**: Creating tints/shades and color palettes is more predictable in OKLCH.
+
+4. **Modern browser support**: All modern browsers support OKLCH as of 2024.
+
+## Consequences
+
+### Positive
+- Consistent color perception across the theme
+- Easy to create harmonious color variations
+- Future-proof alignment with CSS standards
+
+### Negative
+- Less familiar to developers used to HSL/RGB
+- Requires conversion when working with design tools that don't support OKLCH
+- Slightly more complex syntax
+
+## Notes
+
+When converting from other color spaces, use tools like:
+- [oklch.com](https://oklch.com)
+- CSS `color()` function for browser conversion

.agents/context/decisions/002-monorepo-structure.md

@@ -0,0 +1,70 @@
+# ADR-002: Adopt Lightweight Monorepo Structure
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+Usage UI started as a single Next.js app using the Vercel Registry Starter template. As the project grew to support 20+ components, we needed to decide on the architecture:
+
+1. **Single App**: Keep everything in one Next.js application
+2. **Monorepo**: Separate docs site and component registry into packages
+3. **Multi-repo**: Separate repositories for docs and components
+
+## Decision
+
+Adopt a **lightweight monorepo** structure using pnpm workspaces and Turborepo.
+
+```
+usage-ui/
+├── apps/
+│   └── www/              # Documentation site
+├── packages/
+│   └── ui/               # Component registry
+├── tooling/              # Shared configs
+├── turbo.json
+└── pnpm-workspace.yaml
+```
+
+## Rationale
+
+### Why Monorepo Over Single App
+
+1. **Industry standard**: Magic UI, Origin UI, shadcn/ui all use monorepo structure
+2. **Separation of concerns**: Docs site vs distributable components are distinct
+3. **Scalability**: Easier to manage 20+ components with clear boundaries
+4. **Independent deployment**: Can deploy docs without rebuilding components
+
+### Why Monorepo Over Multi-repo
+
+1. **Atomic changes**: Can update component + docs in single PR
+2. **Shared tooling**: One Biome config, one TypeScript config
+3. **Simpler CI/CD**: Single pipeline with Turbo caching
+4. **Cross-package testing**: Can test integration between packages
+
+### Why pnpm + Turborepo
+
+1. **pnpm**: Fastest package manager, best monorepo support, disk efficient
+2. **Turborepo**: Simple config, excellent caching, Vercel-native integration
+
+## Consequences
+
+### Positive
+- Clear separation between distributable code and docs
+- Turbo caching speeds up CI/CD significantly
+- Changesets enables proper versioning
+- Matches industry best practices
+
+### Negative
+- More complex initial setup
+- Steeper learning curve for contributors
+- Requires understanding of workspace protocols
+
+## Implementation Notes
+
+Key files created:
+- `pnpm-workspace.yaml` - Workspace definition
+- `turbo.json` - Build orchestration
+- `.changeset/config.json` - Version management
+- `lefthook.yml` - Git hooks

.agents/context/decisions/003-dual-primitive-strategy.md

@@ -0,0 +1,82 @@
+# ADR-003: Dual Primitive Strategy (Radix + Base)
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+When building meter components, we needed to decide how to handle accessibility primitives:
+
+1. **Radix-only**: All components use Radix UI primitives
+2. **Base-only**: All components use plain HTML with manual ARIA
+3. **Dual versions**: Provide both Radix and Base versions
+
+## Decision
+
+Implement **dual versions** for core meter components:
+- `usage-meter.tsx` - Radix-based (full accessibility)
+- `usage-meter-base.tsx` - Lightweight (no Radix)
+
+## Rationale
+
+### Why Not Radix-Only
+
+1. **Bundle size**: Some users prioritize minimal bundle size
+2. **Simple use cases**: Not all meters need full keyboard nav
+3. **Framework flexibility**: Some frameworks don't work well with Radix
+
+### Why Not Base-Only
+
+1. **Accessibility compliance**: Many projects require WCAG compliance
+2. **Complex interactions**: Radix handles edge cases we'd miss
+3. **shadcn alignment**: shadcn/ui uses Radix for all interactive components
+
+### Why Dual Versions
+
+1. **User choice**: Let users pick based on their requirements
+2. **Documentation value**: Shows both accessible and minimal patterns
+3. **Gradual adoption**: Users can start with base, upgrade to Radix
+
+## Implementation
+
+```
+packages/ui/src/components/registry/usage-meter/
+├── usage-meter.tsx       # Radix Progress primitive
+├── usage-meter-base.tsx  # div with role="progressbar"
+└── index.ts              # Exports both
+```
+
+### When to Create Both Versions
+
+| Component Type | Radix | Base |
+|----------------|-------|------|
+| Core meters | ✅ | ✅ |
+| Cards (use shadcn Card) | ❌ | ❌ |
+| Indicators (simple display) | ❌ | ✅ |
+| Charts (Tremor-based) | ❌ | ❌ |
+
+## Consequences
+
+### Positive
+- Maximum flexibility for users
+- Clear accessibility story
+- Smaller bundle for simple use cases
+
+### Negative
+- More code to maintain
+- Must keep both versions in sync
+- Documentation complexity
+
+## Notes
+
+The base version MUST include manual ARIA attributes:
+```tsx
+<div
+  role="progressbar"
+  aria-valuenow={value}
+  aria-valuemin={0}
+  aria-valuemax={max}
+  aria-valuetext={`${percentage}%`}
+/>
+```

.agents/context/decisions/004-migration-hybrid-approach.md

@@ -0,0 +1,104 @@
+# ADR-004: Hybrid Monorepo Migration Approach
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+When migrating Usage UI from single-app to monorepo structure, we needed to choose between:
+
+1. **CLI Scaffold**: Use `npx shadcn@latest init` with monorepo preset to generate correct configs
+2. **Manual Migration**: Manually restructure directories and create configs
+3. **Hybrid Approach**: Use CLI to generate reference configs, manually migrate code
+
+Key considerations:
+- 46+ shadcn components already installed with customizations
+- Custom theme (OKLCH colors, nature palette)
+- Git history preservation important for accountability
+- Configuration errors are common and hard to debug
+
+## Decision
+
+Adopt a **hybrid migration approach**:
+
+1. Generate a reference monorepo using shadcn CLI in a temp directory
+2. Use reference configs as authoritative source
+3. Execute migration manually to preserve git history
+4. Validate structure with automated checks
+
+## Rationale
+
+### Why Not CLI Scaffold
+
+- Loses all git history
+- Requires manually copying 46+ components
+- Custom theme would need re-implementation
+- High risk of missing customizations
+
+### Why Not Pure Manual
+
+- shadcn monorepo config is complex (components.json aliases, exports)
+- Easy to make subtle errors in turbo.json, tsconfig.json paths
+- No authoritative reference for correct configuration
+- Higher chance of "works on my machine" issues
+
+### Why Hybrid
+
+| Benefit | How It Helps |
+|---------|--------------|
+| Correct configs | Reference from CLI is guaranteed correct |
+| Preserved history | Manual moves keep git blame |
+| Validation | Can diff against reference |
+| Customizations kept | Copy files, don't regenerate |
+
+## Implementation
+
+### Reference Generation
+
+```bash
+mkdir -p /tmp/shadcn-monorepo-reference
+cd /tmp/shadcn-monorepo-reference
+pnpm dlx shadcn@latest init  # Select "Next.js (Monorepo)"
+```
+
+Reference files to use:
+- `turbo.json` — Build orchestration
+- `pnpm-workspace.yaml` — Workspace definition
+- `apps/web/components.json` — App-level shadcn config
+- `packages/ui/components.json` — Package-level shadcn config
+- `packages/ui/package.json` — Exports configuration
+
+### Migration Execution
+
+See [execute-monorepo-migration.md](../../workflows/execute-monorepo-migration.md) for step-by-step workflow.
+
+### Validation
+
+See [monorepo-validation skill](../../skills/monorepo-validation/SKILL.md) for automated structure checks.
+
+## Consequences
+
+### Positive
+
+- Git history preserved for all components
+- Configs match shadcn CLI expectations exactly
+- Automated validation catches drift
+- Documented process is repeatable
+
+### Negative
+
+- More steps than pure CLI scaffold
+- Requires understanding of both approaches
+- Reference must be regenerated if shadcn CLI changes
+
+### Mitigations
+
+- Workflow documentation reduces complexity
+- Validation script catches most errors
+- Reference can be cached or checked into `.references/` if needed
+
+## Related
+
+- [ADR-002: Adopt Lightweight Monorepo Structure](./002-monorepo-structure.md) — Why monorepo
+- [MONOREPO-MIGRATION.md](../../MONOREPO-MIGRATION.md) — Detailed migration guide