# Freemium Model Documentation

**4 Core Documents | BRD → PRD → Spec Ready**

---

## 1. FREEMIUM-PRINCIPLES.md

**What:** Tier structure, command audit, functional decomposition, optimization opportunities

**Use:** Reference for tier boundaries, command classification, refactoring roadmap

**Contains:**
- Universal tier structure (FREE, STARTER, ENTERPRISE)
- Deployment models (Pre-API v1.6.x, Post-API v1.7.0+)
- Command audit: 49 commands with tokens, dependencies, reusability scores
- Core primitives & functional overlap patterns
- 15-20K token savings opportunities

---

## 2. COMMAND-USE-CASE-PATTERNS.md

**What:** 7 use case patterns organizing commands by workflow (not tier)

**Use:** Understanding command portfolio, identifying gaps, planning new commands

**Contains:**
- ANALYSIS, PLANNING, RELEASE, IMPLEMENT, CODE-ANALYSIS, TESTING, PUBLISH patterns
- Gap analysis for each pattern
- Tier coverage matrix
- Implementation roadmap (review-code2 → testing → scaffolding)

---

## 3. pre-API-freemium.md

**What:** v1.6.x implementation details (current version)

**Use:** Building v1.6.x features, understanding client-side architecture

**Contains:**
- Client-side license validation
- Scope gating (`--monorepo`, `--multi-repo`)
- Pause enforcement logic
- Timer instrumentation architecture
- LLM API integration (user-provided)
- Feature-by-tier mapping

---

## 4. post-API-freemium.md

**What:** v1.7.0+ implementation details (future version)

**Use:** Planning migration, understanding server-side architecture

**Contains:**
- Server-side API validation
- Rate limiting as pause enforcement
- Optional Roadcrew-provided LLM budgets
- Trial license system
- Migration path from v1.6.x
- Multi-repo release coordination

---

## BRD / PRD / Spec Usage

### BRD (Business Requirements)
→ COMMAND-USE-CASE-PATTERNS.md (what should exist)
→ FREEMIUM-PRINCIPLES.md (tier value proposition)

### PRD (Product Requirements)
→ FREEMIUM-PRINCIPLES.md (complete tier definitions)
→ pre-API-freemium.md (v1.6.x feature list)
→ post-API-freemium.md (v1.7.0+ feature list - future implementation)

### Spec (Technical Specifications)
→ pre-API-freemium.md (v1.6.x architecture, code examples)
→ post-API-freemium.md (v1.7.0+ architecture, API design - future implementation)

---

## Quick Reference

| Tier | Repo Scope | Hands-Off Time | Pause Enforcement | Cost |
|------|-----------|----------------|-------------------|------|
| **FREE** | Single repo | 0 min | None | $0 |
| **STARTER** | Monorepo | 1-15 min | Every 3 items or 5 min | $X/mo |
| **ENTERPRISE** | Multi-repo | Up to 60 min | Every 10 items or 20 min | $Y/mo |

All tiers use user's own LLM API. Roadcrew manages token budgeting and cost warnings.