# Project Overview & PDR: Vibery Kits Website

## Executive Summary

**Vibery Kits** is a curated template ecosystem and discovery platform for Claude Code developers. The website enables users to:

1. Browse 600+ templates (agents, commands, MCPs, settings, hooks)
2. Discover outcome-based stacks ("Build SaaS in Next.js")
3. Install curated template bundles via CLI
4. Unlock premium features (Smart Stacks Pro, Outcome Wizards)

**Status:** MVP active, Vue Islands migration in progress
**Launch Date:** Dec 2024
**Users:** Professional developers, teams, enterprises

---

## Vision & Business Model

### Value Proposition

**For Free Users:**

- 600+ individual templates free
- Basic search/browse by category
- CLI access (`npx vibery install <template>`)
- Community-created stacks

**For Paid Users (Target):**

- Expert-curated Smart Stacks (compatibility guaranteed)
- Outcome Wizards (guided setup flows)
- Custom Stack Builder (save/share)
- Team features (shared stacks)
- Priority updates

### Pricing Strategy

| Tier       | Price  | Features                                      |
| ---------- | ------ | --------------------------------------------- |
| Free       | $0     | Individual templates, basic stacks, CLI       |
| Pro        | $9/mo  | Smart Stacks Pro, Outcome Wizards             |
| Team       | $29/mo | Team sharing, custom stacks, priority support |
| Enterprise | Custom | Private templates, SSO, dedicated support     |

### Target Users

1. **Professional Developers** - Using Claude Code daily, willing to pay for productivity
2. **Teams/Startups** - Standardizing Claude Code setups across org
3. **Enterprises** - Custom templates, compliance, security

### Competitive Differentiation

| Aspect   | Random GitHub | DIY Setup   | Vibery Kits     |
| -------- | ------------- | ----------- | --------------- |
| Curation | None          | Manual      | Expert-reviewed |
| Guidance | None          | Trial/error | Outcome-focused |
| Updates  | Stale         | Manual      | Continuous      |
| Quality  | Variable      | Unknown     | Tested combos   |

---

## Functional Requirements

### FR1: Template Discovery

**Requirement:** Enable users to browse and search 600+ templates.

**Acceptance Criteria:**

- [x] Search by name (live filtering)
- [x] Filter by type (agents, commands, MCPs, settings, hooks)
- [x] Sort by popularity, date, relevance
- [x] Template detail modal with metadata
- [x] Copy install command to clipboard

**Implementation:** SearchBar.vue, FilterBar.vue, TemplateCard.astro

### FR2: Outcome-Based Wizard

**Requirement:** Guide users to templates based on desired outcome.

**Flow:**

1. "What are you building?" → SaaS, API, AI Project, Mobile
2. "What's your stack?" → Next.js, Python, Go, etc.
3. "What do you need?" → Security, Testing, Deployment
4. Recommended templates + stacks appear

**Acceptance Criteria:**

- [x] Outcome flows defined in outcomes.json (8 flows)
- [ ] Interactive wizard UI (Hero.astro → WizardSection.vue)
- [ ] Template recommendations per outcome
- [ ] Stack recommendations

**Implementation:** WizardSection.vue (planned)

### FR3: Smart Stacks

**Requirement:** Provide pre-curated template bundles for common use cases.

**12 Curated Stacks:**

1. Next.js Production
2. FastAPI Backend
3. Security Hardening
4. DevOps Essentials
5. Startup MVP
6. Python ML Pipeline
7. React SPA
8. Mobile Cross-Platform
9. GraphQL API
10. CI/CD Foundation
11. Data Engineering
12. Cloud Native

**Acceptance Criteria:**

- [x] Stacks defined in stacks.json (12 stacks, 208 lines)
- [x] StacksGrid.astro displays on home + /stacks page
- [ ] Individual stack detail page (/stacks/[id])
- [ ] Install entire stack via CLI
- [x] Credits/sources documented

**Implementation:** StacksGrid.astro, stacks/[id].astro (SSG)

### FR4: Cart/Stack Builder

**Requirement:** Allow users to add templates to cart, generate install commands.

**Acceptance Criteria:**

- [x] Add/remove templates to cart
- [x] Cart persists (localStorage)
- [x] Generate install command (vibery install tmpl1 tmpl2...)
- [x] Copy command to clipboard
- [x] Cart sidebar shows count

**Implementation:** CartSidebar.vue, useCart.ts (109 lines)

### FR5: Modal & Details

**Requirement:** Display full template details in modal.

**Acceptance Criteria:**

- [x] Modal opens on template click
- [x] Shows description, tags, icon, type
- [x] Add to cart button
- [x] View source/docs links
- [x] Keyboard nav (Esc to close)

**Implementation:** TemplateModal.vue (217 lines)

### FR6: Premium Features (Planned)

**Smart Stacks Pro:**

- Expert-researched bundles
- Compatibility guarantees
- Regular updates
- Priority support

**Outcome Wizards:**

- Guided flows ("Build SaaS in Next.js" → stack in 1 click)
- Multiple outcome paths
- Step-by-step guidance

**Custom Stacks:**

- Users save/share personal stacks
- Version history
- Collaboration

**Acceptance Criteria:**

- [ ] Authentication system (Clerk/Auth.js)
- [ ] User accounts + profiles
- [ ] Stripe payment integration
- [ ] Premium stack unlock
- [ ] Usage analytics

---

## Non-Functional Requirements

### NFR1: Performance

**Requirement:** Fast load times, responsive UI

**Targets:**

- Page load: < 2s (Cloudflare CDN)
- First contentful paint: < 1s
- Interactive: < 3s
- Lighthouse score: > 90

**Implementation:**

- Static HTML (Astro SSG)
- Vue Islands (only interactive parts hydrate)
- Tailwind CSS (optimized)
- Image optimization (Phosphor icons)

### NFR2: SEO

**Requirement:** Discoverable in search engines

**Targets:**

- Dynamic meta tags (og:image, description)
- Structured data (JSON-LD for templates)
- Sitemap generation
- Robot-friendly URLs

**Implementation:**

- Layout.astro (master SEO)
- @astrojs/sitemap (automatic)
- ViewTransitions (page history)

### NFR3: Accessibility

**Requirement:** Usable by all users (WCAG 2.1 AA)

**Targets:**

- Semantic HTML
- ARIA labels
- Keyboard navigation
- Color contrast (4.5:1+)
- Screen reader support

**Implementation:**

- Radix/headless UI patterns
- Tailwind utilities
- Testing via axe-core

### NFR4: Maintainability

**Requirement:** Easy to update templates, stacks, outcomes

**Targets:**

- CLI tools (npm run tpl, npm run data)
- JSON-based data
- Type-safe composables
- Consistent patterns

**Implementation:**

- scripts/templates-cli.cjs
- scripts/data-cli.cjs
- TypeScript interfaces
- Composables pattern

### NFR5: Scalability

**Requirement:** Support 600+ templates without performance degradation

**Targets:**

- Virtual scrolling for long lists
- Lazy-loaded modals
- Efficient filtering
- Paginated results (if needed)

**Implementation:**

- Astro static build (zero runtime)
- SearchBar.vue (client-side filtering)
- Modal lazy-loaded on click

### NFR6: Security

**Requirement:** Protect user data and prevent XSS/CSRF

**Targets:**

- No eval() or dynamic HTML
- Sanitized input (search, filters)
- HTTPS only
- CSP headers (Cloudflare)
- No tracking cookies (analytics-safe)

**Implementation:**

- Vue template validation
- Cloudflare security rules
- .env for secrets

---

## Architecture Decisions

### AD1: Static Site Generation (Astro)

**Decision:** Use Astro for static HTML + Cloudflare CDN

**Rationale:**

- ✓ Fast (no server), SEO-friendly
- ✓ Minimal JS (Vue Islands)
- ✓ Simple deployment (Cloudflare Pages)
- ✓ Cost-effective

**Trade-offs:**

- Real-time data requires rebuild
- No server-side logic (unless Cloudflare Workers)

### AD2: Vue Islands for Interactivity

**Decision:** Selective Vue hydration, not full SPA

**Rationale:**

- ✓ Static content = no JS (templates listing is static HTML)
- ✓ Reactive parts = Vue (cart, modal, search)
- ✓ Incremental migration from Astro
- ✓ Keeps build output small

**Components Hydrated:**

- CartSidebar.vue (client:load)
- TemplateModal.vue (client:load)
- SearchBar.vue (client:load)
- FilterBar.vue (client:load)

### AD3: Warm Terminal Design

**Decision:** Professional, warm color palette (not neon)

**Rationale:**

- ✓ Targets paying professionals
- ✓ Stands out (not generic dark theme)
- ✓ Claude-aligned (terracotta accent)
- ✓ Trustworthy feel (stone-based)

**Colors:**

- Backgrounds: Stone-950 (#0c0a09) → Stone-700 (#44403c)
- Accent: Terracotta (#e07256)
- Fonts: Satoshi + IBM Plex Mono

### AD4: JSON-Based Data Management

**Decision:** Store templates, stacks, outcomes in JSON files

**Rationale:**

- ✓ Simple, version-controllable
- ✓ CLI tools for CRUD (npm run tpl)
- ✓ Type-safe (TypeScript interfaces)
- ✓ Embeddable in build output

**Files:**

- templates.json (600+ templates, 1,413 lines)
- stacks.json (12 stacks, 208 lines)
- outcomes.json (8 flows, 434 lines)
- claudekit.json (premium data, 162 lines)

### AD5: Composables for State

**Decision:** Vue 3 Composition API with composables (not Pinia/Vuex)

**Rationale:**

- ✓ Lightweight (no external store)
- ✓ Composable pattern (reusable)
- ✓ TypeScript-friendly
- ✓ Easy to test

**Stores:**

- useCart (cart state + localStorage)
- useModal (modal open/close)
- useSearch (filter logic)
- useNotifications (toast queue)
- useUsageStats (analytics)

---

## Acceptance Criteria Summary

### MVP (Complete)

- [x] Template catalog (600+ items)
- [x] Search + filter
- [x] Cart + command generation
- [x] Stacks grid (12 stacks)
- [x] Modal detail view
- [x] Warm Terminal theme
- [x] Responsive design
- [x] Cloudflare deployment

### Phase 2 (In Progress)

- [ ] Vue Islands migration (remove ClientScripts.astro)
- [ ] Outcome wizard UI
- [ ] Stack detail pages (/stacks/[id])
- [ ] Fixed neon-\* class refs

### Phase 3 (Planned)

- [ ] Authentication
- [ ] Premium features unlock
- [ ] Payment integration
- [ ] Custom stacks

### Phase 4 (Planned)

- [ ] Team features
- [ ] Analytics dashboard
- [ ] Template submission
- [ ] Community ratings

---

## Success Metrics

| Metric                  | Target    | Method                   |
| ----------------------- | --------- | ------------------------ |
| Pageviews               | 10K/month | Cloudflare Analytics     |
| Installs                | 1K+/month | CLI tracking             |
| Free to Pro Conversion  | 2-5%      | Auth + payment           |
| Avg Session Duration    | 3+ min    | Analytics                |
| Cart Completion         | 50%+      | Track add-to-cart ratio  |
| Template Search Success | 80%+      | Analytics on found items |
| Performance (LCP)       | < 1s      | Lighthouse               |

---

## Dependencies & Risks

### Dependencies

- Cloudflare Pages (hosting)
- npm registry (vibery CLI)
- GitHub (template sources)

### Risks

| Risk                               | Impact | Mitigation                     |
| ---------------------------------- | ------ | ------------------------------ |
| Neon-\* class migration incomplete | High   | Remove ClientScripts.astro     |
| Duplicate components (Astro + Vue) | Medium | Complete Vue Islands migration |
| Template data staleness            | Medium | CLI + validation tools         |
| Paid features not implemented      | High   | Phase 3-4 roadmap              |
| Performance regression             | Medium | Lighthouse monitoring          |

---

## Timeline

| Phase             | Duration  | Goals                      |
| ----------------- | --------- | -------------------------- |
| Phase 1: MVP      | Dec 2024  | Launch website, CLI tool   |
| Phase 2: Polish   | Jan 2025  | Vue Islands, fix neon refs |
| Phase 3: Accounts | Feb 2025  | Auth, premium unlock       |
| Phase 4: Growth   | Mar 2025+ | Community, analytics, team |

---

## Related Documentation

- `codebase-summary.md` - File inventory and architecture
- `code-standards.md` - Naming, patterns, styling
- `system-architecture.md` - Data flow, build pipeline
- `CLAUDE.md` - Local development notes