# Documentation Index: Vibery Kits Website

Complete reference for the Vibery Kits Website project.

## Core Documentation

### 0. Search API Documentation

**File:** `search-api.md`

Complete API reference for the search infrastructure using MiniSearch.

**Contents:**

- useSearch() composable API
- SearchableItem and SearchResult types
- Field weighting and fuzzy matching configuration
- Usage examples and integration patterns
- Performance characteristics and benchmarks
- Testing information and troubleshooting

**For:** Developers using search functionality, implementing search features

---

### 1. Project Overview & PDR

**File:** `project-overview-pdr.md`

Project vision, business model, and comprehensive requirements specification.

**Contents:**

- Executive summary (MVP status, target users)
- Business model (Free/Pro/Team/Enterprise pricing)
- Functional requirements (6 FRs, fully mapped)
- Non-functional requirements (performance, SEO, security, etc.)
- Architecture decisions (5 key decisions documented)
- Acceptance criteria & success metrics
- Timeline & roadmap (4 phases)

**For:** Product managers, architects, developers understanding scope

---

### 2. Codebase Summary

**File:** `codebase-summary.md`

File inventory, structure, tech stack, and quick metrics.

**Contents:**

- Directory structure (src/, scripts/, public/)
- Component inventory (19 total: 12 Astro + 7 Vue)
- Data files overview (templates, stacks, outcomes)
- Composables (5 state management hooks)
- Pages & routes (12 total)
- Tech stack & versions
- Design system (Warm Terminal colors)
- Known issues (3 documented)

**For:** New developers, code navigation, quick reference

---

### 3. Code Standards

**File:** `code-standards.md`

Naming conventions, component patterns, and best practices.

**Contents:**

- File naming conventions (components, composables, types, data, pages)
- Component patterns (Astro static vs Vue interactive)
- Composable pattern (singleton state with public API)
- Styling guide (Warm Terminal classes, responsive design)
- TypeScript conventions (strict mode, interfaces)
- State management (composables as stores)
- Security & error handling best practices
- Migration guidelines (Astro → Vue Islands)
- Code review checklist

**For:** Developers writing code, PRs, style consistency

---

### 4. System Architecture

**File:** `system-architecture.md`

Data flow, component architecture, build pipeline, deployment.

**Contents:**

- High-level architecture diagram
- Data flow (build-time, runtime, state management)
- Component architecture (detailed Astro + Vue breakdown)
- Composable architecture (5 state stores)
- Data schemas (Template, Stack, Outcome interfaces)
- Build pipeline (6-step process)
- Deployment architecture (Cloudflare Pages)
- Performance metrics & targets
- Security architecture (CSP, headers, validation)
- Known architectural issues with solutions
- Future improvements (Phases 2-5)

**For:** Architects, performance engineers, DevOps, future planning

---

## Quick References

### Quick Start

**In:** `README.md`

```bash
npm install      # Install dependencies
npm run dev      # Start dev server (localhost:4321)
npm run build    # Production build
npm run preview  # Preview production build
```

---

### Design System Colors

**In:** `code-standards.md` → Styling section

```
warm-bg-deep:       #0c0a09  (main background)
warm-bg-surface:    #1c1917  (cards)
warm-text-primary:  #fafaf9  (text)
warm-accent:        #e07256  (terracotta)
```

---

### Key Commands

**In:** `codebase-summary.md` → CLI Commands

```bash
npm run tpl:report       # Health check
npm run tpl:validate     # Cross-reference
npm run tpl -- add <type> <name> <desc>
npm run data:validate    # Validate JSON
```

---

### Component Overview

**In:** `codebase-summary.md` → Components

| Type        | Count | Purpose                   |
| ----------- | ----- | ------------------------- |
| Astro       | 12    | Static HTML, no client JS |
| Vue         | 7     | Interactive islands       |
| Composables | 5     | State management          |

---

## By Role

### Product Manager

1. Start: `project-overview-pdr.md` (vision, requirements, roadmap)
2. Reference: `codebase-summary.md` (what's built)
3. Track: Success metrics in PDR

### Developer (New)

1. Start: `README.md` (quick start)
2. Learn: `codebase-summary.md` (file structure)
3. Code: `code-standards.md` (conventions, patterns)
4. Understand: `system-architecture.md` (data flow)

### Developer (Existing)

1. Reference: `code-standards.md` (conventions)
2. Debug: `system-architecture.md` (data flow, issues)
3. Optimize: Performance targets in architecture doc

### Architect

1. Study: `system-architecture.md` (design, flow, issues)
2. Review: `project-overview-pdr.md` (decisions)
3. Plan: Future improvements section

### DevOps Engineer

1. Focus: `system-architecture.md` (deployment, cache strategy)
2. Reference: `project-overview-pdr.md` (dependencies, risks)
3. Setup: Cloudflare Pages configuration

---

## Navigation Guide

### Find Information About...

| Topic                   | Location                                            |
| ----------------------- | --------------------------------------------------- |
| **Project vision**      | project-overview-pdr.md → Executive Summary         |
| **Business model**      | project-overview-pdr.md → Vision & Business Model   |
| **File structure**      | codebase-summary.md → Directory Structure           |
| **Component inventory** | codebase-summary.md → File Inventory                |
| **React/Vue patterns**  | code-standards.md → Component Patterns              |
| **Search API**          | search-api.md → Complete reference                  |
| **Search composable**   | code-standards.md → Search Composable Pattern       |
| **State management**    | code-standards.md → State Management                |
| **Color palette**       | code-standards.md → Styling & Design System         |
| **Build pipeline**      | system-architecture.md → Build Pipeline             |
| **Data flow**           | system-architecture.md → Data Flow Architecture     |
| **Known issues**        | system-architecture.md → Known Architectural Issues |
| **Performance targets** | system-architecture.md → Performance Considerations |
| **Security**            | system-architecture.md → Security Architecture      |
| **Testing**             | codebase-summary.md → Testing                       |
| **CLI commands**        | codebase-summary.md → CLI Commands                  |
| **Deployment**          | system-architecture.md → Deployment Architecture    |
| **Roadmap**             | project-overview-pdr.md → Timeline                  |
| **Code review**         | code-standards.md → Code Review Checklist           |

---

## Documentation Statistics

| File                    | Lines     | Sections | Tables | Code Examples |
| ----------------------- | --------- | -------- | ------ | ------------- |
| project-overview-pdr.md | 456       | 12       | 8      | 2             |
| codebase-summary.md     | 382       | 13       | 12     | 3             |
| code-standards.md       | 712       | 18       | 6      | 18            |
| system-architecture.md  | 627       | 16       | 5      | 4             |
| **Total**               | **2,177** | **59**   | **31** | **27**        |

---

## Related Documentation

**In Repository:**

- `README.md` - Quick start & overview
- `CLAUDE.md` - Local development notes
- `INTEGRATION.md` - CLI integration guide
- `INTEGRATION_EXAMPLE.md` - CLI usage examples
- `VUE_COMPONENTS_SUMMARY.md` - Vue component reference

**In Parent Project:**

- `/Applications/MAMP/htdocs/vibe-templates/CLAUDE.md` - Project vision
- `/Applications/MAMP/htdocs/vibe-templates/cli/` - CLI tool documentation

---

## Updates & Maintenance

**Last Updated:** 2025-12-21
**Created By:** docs-manager agent
**Status:** Complete (MVP documentation)

**Next Updates Planned:**

- Phase 2 (Jan 2025): Vue Islands migration notes
- Phase 3 (Feb 2025): Authentication & premium features
- Phase 4 (Mar 2025+): Team features, analytics, community

**How to Update:**

1. Modify relevant `.md` file
2. Update cross-references if needed
3. Update this INDEX.md if adding new sections
4. Commit with message: `docs: [section] update`

---

## Getting Help

**Question Type** → **Check Document**

- "How do I get started?" → README.md
- "Where is the X component?" → codebase-summary.md
- "What's the project about?" → project-overview-pdr.md
- "How do I write code?" → code-standards.md
- "How does data flow?" → system-architecture.md
- "What are the issues?" → system-architecture.md → Known Issues
- "What's the roadmap?" → project-overview-pdr.md → Timeline
- "How is it deployed?" → system-architecture.md → Deployment
- "What are the targets?" → system-architecture.md → Performance

---

**Documentation is AI-readable and developer-friendly. Keep it concise and up-to-date.**