# Vibery Kits Website

Browse and install Claude Code templates via interactive web interface. Currently 600+ templates across agents, commands, MCPs, settings, and hooks.

**Live:** https://vibery.app/products/vibery-kits
**CLI:** `npx vibery install <template>`

## Quick Start

```bash
# Install dependencies
npm install

# Development server (http://localhost:4321)
npm run dev

# Production build
npm run build

# Preview build locally
npm run preview
```

## Project Structure

```
src/
├── pages/              # Routes (SSG)
│   ├── index.astro     # Home
│   ├── agents.astro    # Type filters
│   ├── stacks.astro    # Stacks listing
│   └── stacks/[id].astro  # Dynamic detail
├── components/         # UI components
│   ├── Header.astro    # Navigation (Astro)
│   ├── Hero.astro      # Home section
│   ├── StacksGrid.astro
│   └── vue/            # Interactive islands
│       ├── SearchBar.vue
│       ├── CartSidebar.vue
│       ├── TemplateModal.vue
│       └── FilterBar.vue
├── composables/        # Vue state (useCart, useModal, etc.)
├── layouts/            # Master layout
├── types/              # TypeScript interfaces
├── styles/             # Tailwind CSS
└── data/               # JSON data
    ├── templates.json  # 600+ templates
    ├── stacks.json     # 12 curated stacks
    └── outcomes.json   # 8 wizard flows
```

## Key Commands

```bash
# Template management (CLI tool)
npm run tpl:report       # Health check
npm run tpl:validate     # Cross-reference validation
npm run tpl -- add agent "name" "description"
npm run tpl -- remove agent "name"
npm run tpl -- search "query"

# Data validation
npm run data:validate

# Development
npm run dev              # Dev server
npm run build           # Prod build
npm run preview         # Local prod preview
npm run astro          # Direct astro CLI
```

## Design System: Warm Terminal

Professional, warm color palette (not neon). Stone-based backgrounds with terracotta accent.

```
Backgrounds: #0c0a09 (deep) → #44403c (active)
Text: #fafaf9 (primary) → #57534e (muted)
Accent: #e07256 (terracotta)
Fonts: Satoshi (sans), IBM Plex Mono (mono)
```

**Classes:** `warm-bg-deep`, `warm-text-primary`, `warm-accent`, etc.

## Tech Stack

| Component          | Version |
| ------------------ | ------- |
| Astro              | ^5.0.0  |
| Vue                | ^3.4.0  |
| Tailwind CSS       | ^3.4.1  |
| Phosphor Icons     | ^2.1.2  |
| Cloudflare adapter | ^12.0.0 |

## Architecture

**Static Site Generation (Astro)** with **Vue Islands** for interactivity.

- Pages pre-rendered to HTML at build time
- Vue components hydrate only on `client:load`
- Shared state via composables (useCart, useModal, etc.)
- Data persisted to localStorage (cart)

```
Build: Astro → HTML + CSS + JS
Deploy: Cloudflare Pages (global CDN)
Client: HTML (static) + Vue islands (reactive)
```

## State Management

**Composables Pattern** (no external store)

```typescript
useCart(); // Cart items + localStorage sync
useModal(); // Modal open/close + current item
useSearch(); // Filter + search logic
useNotifications(); // Toast queue
useUsageStats(); // Analytics tracking
```

## Documentation

- **`docs/codebase-summary.md`** - File inventory, tech stack, metrics
- **`docs/project-overview-pdr.md`** - Vision, business model, requirements
- **`docs/code-standards.md`** - Naming conventions, patterns, TypeScript
- **`docs/system-architecture.md`** - Data flow, components, deployment

## Known Issues

1. **ClientScripts.astro (451 lines)** - Legacy JS, needs migration to Vue
2. **Dual implementations** - Modal, Cart, FilterBar exist in Astro + Vue
3. **Neon class refs** - Some components have old `neon-*` classes

→ See `docs/system-architecture.md` for details and migration plan.

## Deployment

**Platform:** Cloudflare Pages
**Build:** `astro build` → `dist/`
**Cache:** HTML (1h), CSS/JS (30 days, immutable)

```bash
# Manual deploy
npm run build
# Upload dist/ to Cloudflare Pages
```

## Related Projects

- `/Applications/MAMP/htdocs/vibe-templates/cli/` - CLI tool (npx vibery)
- `/Applications/MAMP/htdocs/claude-code-templates/` - Template library (600+)

## Next Steps

**Phase 2 (Jan 2025):** Vue Islands migration, fix neon-\* classes
**Phase 3 (Feb 2025):** Authentication, premium unlock
**Phase 4 (Mar 2025+):** Team features, community, analytics

See `CLAUDE.md` for development notes.

## License

Licensed under project parent directory.