# Freemium Principles: PRE-API Validation Phase
## When You're Distributing Software (Not Running Services)

**Context:** You don't have API key validation or backend services yet. Users download/clone your code and run it themselves. Your business model depends on converting adoption into paid services later.

**Note:** This document describes the v1.6.x (PRE-API) implementation. A post-API version (v1.7.0+) with server-side validation will be implemented in a future phase.

**Related Documents:**
- **[FREEMIUM-PRINCIPLES.md](FREEMIUM-PRINCIPLES.md)** - Core tier structure (same for pre-API and post-API)
- **[COMMAND-USE-CASE-PATTERNS.md](COMMAND-USE-CASE-PATTERNS.md)** - Command organization by workflow

---

## Strategic Principles for Code Distribution

### 1. Free Users Are Future Revenue, Not Future Cost
**Pre-API Reality:** Every user who downloads and successfully uses your software is a potential future customer when you launch paid services.

**Decision Framework:**
- **Open Source (Free):** Code that demonstrates value and creates adoption
- **Keep Closed (Paid Later):** Code that you'll eventually monetize as a service, but only if it doesn't block the "aha moment"

**Codebase Analysis Questions:**
```
FOR EACH MODULE/FEATURE:
- Does this code help users understand what problem we solve?
- Will users hit the "aha moment" without this code?
- Is this code we'll eventually turn into a paid service?
- If we hide this now, will anyone adopt our product?
```

**Rule:** In pre-API phase, err on the side of openness. You're buying future customers with current code generosity.

---

### 2. Optimize for the "Aha Moment," Not Feature Completeness
**Pre-API Reality:** Users must be able to run your software and experience the core value proposition without paid services, APIs, or your infrastructure.

**Decision Framework:**
- **Open Source (Free):** Minimum viable code for users to experience core value
- **Keep Closed (Paid Later):** Advanced features, optimizations, or enterprise capabilities

**Codebase Analysis Questions:**
```
FOR EACH MODULE/FEATURE:
- What's the ONE thing users must experience to "get it"?
- Can users reach that moment with this code alone?
- Does this code deliver core insight or peripheral benefits?
- Is this "table stakes" or "competitive advantage"?
```

**Critical Test:** Can a developer clone your repo, run `npm install && npm start` (or equivalent), and experience your product's core value in <30 minutes? If no, you're blocking adoption.

---

### 3. Distribution Should Feel Like Discovery, Not Limitation
**Pre-API Reality:** Users aren't hitting paywalls—they're hitting missing features or services you haven't built yet. This is GOOD if positioned correctly.

**Decision Framework:**
- **Open Source (Free):** All code needed for single-user, local-first, or basic use cases
- **Keep Closed (Future Paid):** Code that enables scale, collaboration, or enterprise features

**Codebase Analysis Questions:**
```
FOR EACH MODULE/FEATURE:
- Does removing this code make the product feel "broken" or "limited edition"?
- Will users naturally want this as they grow usage?
- Can we articulate WHY this isn't included without seeming cheap?
- Does withholding this block learning or block scaling?
```

**Good Limit Examples:**
- "Run locally with SQLite" (free) vs "Postgres cluster management" (future paid)
- "Single user mode" (free) vs "Team collaboration features" (future paid)
- "Process 1000 records" (free) vs "Process millions with our infrastructure" (future paid)

**Bad Limit Examples:**
- Core algorithm crippled or artificially slowed
- Arbitrary feature removal that breaks user experience
- Missing documentation or examples

### 2.4 Feature-Level Gating (Premium Capabilities Within Open Source)

**Pre-API Reality:** Sometimes the same code powers both free AND premium features. Premium isn't about "access to code" but "access to capabilities."

**Decision Framework:**
When you open source code that contains both free and premium features:
- **Open Source (Free):** Core command exists, basic functionality works
- **Keep Gated (Paid Later):** Advanced flags/modes that enhance performance or automation

**Codebase Analysis Questions:**
```
FOR EACH COMMAND/FEATURE:
- Does this code work functionally without the premium flag? (E.g., /scope-release works without --ai)
- Is the premium feature a different code path or just a flag? (--ai invokes AI, but non-AI path still valid)
- Can users understand the limitation from reading code? (Clear error message about missing license key)
- Does hiding this feature block adoption or just limit convenience?
```

**Key Distinction:**
- **Scale Gating** (classic): "Process 1000 records" (free) vs "Process millions" (paid infrastructure)
- **Feature Gating** (emerging): "Generate issues manually" (free) vs "--ai auto-generate issues" (paid AI service)
- **Capability Gating** (same as feature): Basic functionality accessible, advanced modes require subscription

**Good Feature Gating Examples:**
- `/scope-release` works without `--ai` flag (free) but generates issues faster with flag (paid)
- `/analyze-repo` works as basic analysis (free) but `--comprehensive` flag requires license (paid)
- Commands run locally by default (free) but `--toc` (Theory of Constraints) requires license (paid)

**Bad Feature Gating Examples:**
- Removing the command entirely behind paywall (blocks learning)
- Artificial slowdown without `--premium` flag (creates frustration)
- Hidden flags that users can't discover by reading code (broken transparency)

**Roadcrew Pattern:**
Commands like `/scope-release` are fully open-source AND check for ROADCREW_LICENSE_KEY at runtime. Users can read the code, understand that `--ai` requires a license, and use the free version. When monetizing, add the validation check—code doesn't change, just execution constraints.

---

## Open vs. Closed Source Decision Matrix

### OPEN SOURCE (GitHub Public) When:

**Core Product Category:**
- Main application logic that demonstrates your innovation
- CLI tools, SDKs, or libraries users need to integrate
- Example implementations and starter templates
- Documentation, tutorials, and learning resources

**Adoption Drivers:**
- Code that generates word-of-mouth and GitHub stars
- Features that enable developers to evaluate your approach
- Integrations with popular open source tools
- Standard implementations (auth, CRUD, common patterns)

**Community Value:**
- Code that benefits from community contributions
- Bug fixes and security patches from external developers
- Extensions and plugins from ecosystem

**Strategic Considerations:**
- You want to establish a standard or protocol
- Network effects increase value (more users = better product)
- You're building a platform (need developers to build on it)

---

### KEEP CLOSED/COMPILED (Protected) When:

**Future Revenue Sources:**
- Backend services you'll charge for (API endpoints, workers, orchestration)
- Enterprise features (SSO, RBAC, audit logs, compliance tools)
- Proprietary algorithms or data processing you've invested R&D into
- Infrastructure management code (scaling, monitoring, optimization)

**Competitive Moats:**
- Novel techniques or approaches that are hard to replicate
- Accumulated domain expertise that took years to develop
- Integration logic for paid third-party services
- Performance optimizations that create measurable advantage

**Expensive to Support:**
- Features that require you to run infrastructure
- Code that generates support burden without revenue
- Enterprise-specific customizations

**Strategic IP:**
- If a competitor copying this exact code would neutralize your advantage, protect it
- If this code represents your "secret sauce," keep it closed
- If you plan to patent the approach, be cautious about open sourcing

---

### COMPILED BUT OPEN (Source private, distributed compiled) When:

**Pattern:** Keep TypeScript/Go sources private, but distribute pre-compiled JavaScript/binaries publicly.

**Strategic Use Case:**
- Users can inspect compiled code (transparency for trust)
- Users cannot easily modify behavior (protection for monetization)
- Community can't fork/modify easily (maintains control)
- Pre-built distribution works out-of-box (reduces support burden)

**When This Makes Sense:**
- [ ] You're transitioning from fully open to monetized (bridge strategy)
- [ ] Your future revenue comes from services, not the code itself
- [ ] Source code contains internal architecture you want to protect
- [ ] You want to gate premium features via runtime validation (not code removal)
- [ ] You plan to offer source to enterprise customers later (SLA tier)

**When This Fails:**
- [ ] Decompilers/source maps leak your "secret sauce" (risk tolerance matters)
- [ ] Community wants to contribute improvements (blocks ecosystem)
- [ ] Users need to compile/modify for their environment (custom deployments)
- [ ] Maintaining binary compatibility becomes overhead

**Roadcrew Pattern:**
- TypeScript sources: Private in `roadcrew-internal/scripts/`
- Compiled JS: Public in `roadcrew/dist/scripts/`
- Source maps: Included (transparency), but prevent easy modification
- License validator: Public compiled code, private implementation strategy
- Result: "I can see how you validate licenses, but I can't bypass it"

**Key Insight:**
This is NOT the same as proprietary/closed source. It's "transparent but compiled." Users get to inspect your code, contribute ideas, but execution remains under your control.

---

## License Enforcement & Scope Gating (v1.6.x)

**Architecture:** Client-side validation with local license key storage.

### License Validation

**Modified `scripts/core/license-validator.ts`:**

```typescript
interface LicenseValidationResult {
  isValid: boolean;
  tier: 'free' | 'starter' | 'enterprise';
  canUseMonorepo: boolean;
  canUseMultiRepo: boolean;
  canUseAI: boolean;
  expiresAt?: Date;
}

function validateLicense(licenseKey: string): LicenseValidationResult {
  // Check ROADCREW_LICENSE_KEY
  // Validate tier: FREE (no key), STARTER (key + --monorepo), ENTERPRISE (key + --multi-repo)
  // Return validation result
}

function validateScope(
  tier: 'free' | 'starter' | 'enterprise',
  requestedScopes: string[] // ['--monorepo', '--multi-repo', '--ai']
): { isValid: boolean; reason?: string } {
  // FREE: single-repo only, no monorepo/multi-repo
  // STARTER: monorepo allowed, multi-repo blocked
  // ENTERPRISE: both allowed
  // --ai allowed in all tiers (uses user's LLM API)
}
```

### Scope Gating Rules

| Scope | FREE | STARTER | ENTERPRISE |
|-------|------|---------|-----------|
| Single-repo | ✅ | ✅ | ✅ |
| `--monorepo` | ❌ | ✅ | ✅ |
| `--multi-repo` | ❌ | ❌ | ✅ |
| `--ai` (user's API) | ✅ | ✅ | ✅ |

### Error Messages

```typescript
const SCOPE_ERRORS = {
  MONOREPO_REQUIRES_STARTER: (tier: string) => 
    `--monorepo requires STARTER tier or higher. Your tier: ${tier}. Upgrade at roadcrew.ai/pricing`,
  MULTI_REPO_REQUIRES_ENTERPRISE: (tier: string) => 
    `--multi-repo requires ENTERPRISE tier. Your tier: ${tier}. Upgrade at roadcrew.ai/pricing`,
  NO_LICENSE_KEY: 
    `ROADCREW_LICENSE_KEY not set. Set it with: export ROADCREW_LICENSE_KEY=your-key`,
  INVALID_LICENSE_KEY: 
    `Invalid or expired license key. Check your ROADCREW_LICENSE_KEY`,
};
```

### Integration in Commands

Every command that accepts scope flags:

```typescript
import { validateLicense, validateScope } from '../core/license-validator';

async function runCommand() {
  const licenseKey = process.env.ROADCREW_LICENSE_KEY;
  const validation = validateLicense(licenseKey);
  
  if (!validation.isValid) {
    console.error(SCOPE_ERRORS.INVALID_LICENSE_KEY);
    process.exit(1);
  }
  
  const requestedScopes = parseFlags(process.argv); // ['--monorepo', '--ai']
  const scopeCheck = validateScope(validation.tier, requestedScopes);
  
  if (!scopeCheck.isValid) {
    console.error(scopeCheck.reason);
    process.exit(1);
  }
  
  // Proceed with command...
}
```

### Pause Enforcement

**New `scripts/core/pause-tracker.ts`:**

```typescript
interface PauseState {
  itemsGenerated: number;
  lastPauseAt: number;
  tier: 'free' | 'starter' | 'enterprise';
}

const PAUSE_CONFIG = {
  'free': { itemsPerPause: null, timePerPause: null },
  'starter': { itemsPerPause: 3, timePerPause: 5 * 60 * 1000 },
  'enterprise': { itemsPerPause: 10, timePerPause: 20 * 60 * 1000 }
};

class PauseTracker {
  recordItem(): { needsPause: boolean; reason?: string }
  resumeAfterPause(): void
  getState(): PauseState
}
```

**Pause Logic:**
- FREE: No pauses (instant execution)
- STARTER: Pause every 3 items OR every 5 minutes
- ENTERPRISE: Pause every 10 items OR every 20 minutes
- All tiers: `--force` flag skips pauses

---

## Timer Instrumentation & Hands-Off Time Measurement

**Goal:** Measure actual hands-off time empirically for every command, enabling data-driven tier validation.

### What We're Measuring

For each command execution, capture:

| Metric | Definition | Use Case |
|--------|-----------|----------|
| **Hands-On Time** | Time when user is actively interacting | Understand user involvement |
| **Hands-Off Time** | Time when AI/system runs autonomously | Core tier differentiator |
| **Decision Points** | Moments requiring human judgment/approval | Pause enforcement triggers |
| **Pause Duration** | Time spent reviewing during pauses | UX feedback |

### Architecture

**Core Timer Class (`scripts/core/timer.ts`):**
```typescript
interface TimerMetrics {
  handsOnTime: number;
  handsOffTime: number;
  decisionPointsCount: number;
  pauseDurations: number[];
  commandName: string;
  tier: 'free' | 'starter' | 'enterprise';
  timestamp: ISO8601;
}

class CommandTimer {
  recordHandsOnStart(): void
  recordHandsOnEnd(): void
  recordDecisionPoint(): void
  recordDecisionResume(pauseDuration: number): void
  getMetrics(): TimerMetrics
  async saveMetrics(): Promise<void>
}
```

### Storage Format

Metrics stored locally in `.roadcrew/metrics/commands/YYYY-MM-DD.jsonl`:
```jsonl
{"commandName":"scope-release","tier":"starter","handsOnTime":45000,"handsOffTime":435000,"decisionPointsCount":1,"pauseDurations":[15000],"timestamp":"2025-10-28T14:23:45Z"}
```

### Integration Pattern

Every command follows this pattern:
```typescript
const timer = new CommandTimer('scope-release', license.tier);
try {
  timer.recordHandsOnStart();
  const input = await getUserInput();
  timer.recordHandsOnEnd();
  
  // AI/autonomous processing
  const results = await processWithAI(input);
  
  // Pause for review
  if (shouldPause) {
    timer.recordDecisionPoint();
    const approved = await getUserApproval(results);
    timer.recordDecisionResume(pauseWallClockTime);
  }
} finally {
  await timer.saveMetrics();
}
```

### Quarterly Review Process

1. Run analytics on collected metrics
2. Compare actual vs. promised hands-off times
3. If variance > 10%: update tier boundaries
4. Document changes with evidence in git
5. Update FREEMIUM-PRINCIPLES.md

### Data Privacy

- ✅ Metrics stored locally only (no cloud transmission)
- ✅ Tracked: hands-on/hands-off times, command names, tier level
- ❌ NOT tracked: command inputs/outputs, user identity

---

## 4.6 Hands-Off Time: The Human Freedom Principle

**Pre-API Reality:** The tier that truly differentiates is how much time a human can step away while automation runs. This is the core monetization driver.

**CRITICAL:** All time measurements must be **actual measured human time**, not LLM-projected completion estimates. This means real-world instrumented execution, not theoretical speeds.

**Core Principle:**
- **Free Tier:** 0 min hands-off (human must stay present and engaged)
- **Starter Tier:** Up to 15 min hands-off (human takes a quick break, returns to review)
- **Enterprise Tier:** Up to 60 min hands-off (human can step away completely, reviews summary when ready)

**Hands-Off Time = Freedom Level:**

| Hands-Off Time | Human Can... | Execution Model | Tier |
|---|---|---|---|
| 0 min (fully active) | Nothing, must watch | Task completes before break | FREE |
| Up to 15 min (quick break) | Step away briefly | Batch processing, system completes autonomously | STARTER |
| Up to 60 min (full break) | Leave completely, return later | Multi-step orchestration, system makes intermediate decisions | ENTERPRISE |

**Why Hands-Off Time Matters:**

This is the **true value differentiation** because it maps directly to user behavior and willingness to pay:

```
FREE:  "I run this command, I have to stick around and watch"
       → Value: "I get the answer"
       → Time investment: Fully present for task completion

STARTER: "I start this, walk away for 15 min, come back to results"
         → Value: "I get the answer + I regained 15 min focus time"
         → Time investment: 2-3 min to initiate + 3-5 min to review = 5-8 min presence
         → Human freedom: Up to 15 min uninterrupted time
         → Price justification: "I get a real break between context switches"

ENTERPRISE: "I start this and come back when it's done (up to 60 min later)"
            → Value: "Complete workflow runs automatically, I make one decision"
            → Time investment: 2-3 min to initiate + 3-5 min to review = 5-8 min presence
            → Human freedom: Up to 60 min completely uninterrupted
            → Price justification: "I regained uninterrupted focus time"
```

**Decision Framework:**

For each command, determine hands-off time:

```
COMMAND: [name]

[ ] EXECUTION PROFILE (must be measured, not estimated):
    [ ] What's the ACTUAL time a human MUST stay present? (Use instrumentation/timers)
    [ ] At what point can they realistically walk away?
    [ ] How many times must they return to check/approve?
    
    [ ] Hands-off window (actual measured maximum):
        [ ] 0 min → Must be FREE (synchronous, user watching)
        [ ] 1-15 min → STARTER (autonomous batch, quick break)
        [ ] 15-60 min → ENTERPRISE (extended autonomous, full break)

[ ] HIERARCHY CHECK:
    [ ] Does FREE version require continuous human presence? (Should be YES)
    [ ] Does STARTER version achieve 1-15 min hands-off in actual execution? (Should be YES)
    [ ] Does ENTERPRISE version achieve up to 60 min hands-off in actual execution? (Should be YES)
    
[ ] TIME MEASUREMENT:
    [ ] Have you instrumented this command with actual timers?
    [ ] Do you have empirical data on hands-on vs hands-off periods?
    [ ] Is this based on LLM estimates or actual runs? (Must be actual runs)
```

---

## Current System Limits and Constraints

**Note: See [FREEMIUM-PRINCIPLES.md](FREEMIUM-PRINCIPLES.md) for the unified tier structure and implementation details for both Pre-API (v1.6.x) and Post-API (v1.7.0+) phases.**

These limits are currently enforced in the codebase and inform tier placement decisions:

### Epic Constraints (from `issue-classification.ts`)

```
EPIC_CONSTRAINTS = {
  MIN_ISSUES: 2           # Minimum issues to create an epic
  MAX_ISSUES: 7           # Maximum issues per epic (best practice)
  RECOMMEND_SPLIT: 9      # Suggest splitting when reaching 9+ issues
}
```

**Decision Rules:**
- 1 issue: Create as standalone (no epic)
- 2-7 issues: Create epic with child issues
- 8-9 issues: Create epic but flag for review
- 9+ issues: Recommend splitting into multiple epics

### Resource Classification Constraints (from `roadcrew-config.ts`)

```
CLASSIFICATION RANGE: 1-10 (representing complexity/effort)

EXPERT RESOURCES:
  classification_min: 7 (complex, high-risk work)
  classification_max: 10
  capacity: Required (hours/week specified)
  
JUNIOR RESOURCES:
  classification_min: 4 (AI-led, junior-assisted)
  classification_max: 6
  capacity: Required (hours/week specified)
  
AI RESOURCES:
  classification_min: 1 (simple, AI-solo)
  classification_max: 3
  capacity: Unlimited (no constraint)
```

---

## 5. Practical Decision Tree for Cursor AI

When analyzing a file/module in the codebase, ask these questions IN ORDER:

### Question 1: What does this code do?
```
CLASSIFY AS:
[ ] Core product logic (the main thing your product does)
[ ] Infrastructure/scaling code (how you run it at scale)
[ ] UI/UX code (how users interact with it)
[ ] Integration code (connects to other systems)
[ ] Enterprise features (security, compliance, admin)
[ ] Developer tools (CLI, SDK, examples)
```

### Question 2: Can users experience your "aha moment" without this?
```
[ ] YES - Users can see core value without this → Could be CLOSED, GATED, or COMPILED-ONLY
    - If it's a convenience/optimization feature → Consider GATED (license key check at runtime)
    - If it's premium AI or advanced features → Consider GATED + COMPILED (Roadcrew model)
    - If it's strategic IP → Consider CLOSED (don't publish at all)
    
[ ] NO - This is required for basic functionality → Must be OPEN
    - Cannot gate → Users need this to run your software
    - Must be readable/modifiable → Users need to debug/customize
    
[ ] MAYBE - This enhances the experience but isn't required → Context dependent
    - Is this a transition point? (free now, paid later) → COMPILED-ONLY (easier to gate later)
    - Is this server-bound? (will need backend later) → CLOSED (re-build as API)
    - Is this community-contributing? (needs source) → OPEN (accept improvements)
```

**Guidance Note:**
When planning for v1.7.0 server-side validation:
- Start with client-side checks (GATED) in pre-API phase
- Compiled distribution makes transition easier (users already expect validation)
- When you add server backend, compiled code can call home without re-compiling
- This minimizes disruption to users during monetization launch

### Question 3: Will you charge for this capability as a service?
```
[ ] YES, we'll run this as paid infrastructure → Consider for CLOSED
[ ] YES, but users can also run it themselves → Keep OPEN
[ ] NO, this is table stakes → Keep OPEN
[ ] UNSURE → Default to OPEN in pre-API phase
```

### Question 4: Does this create adoption or monetization?
```
[ ] Adoption - Makes product easier to discover/use/love → Keep OPEN
[ ] Monetization - Clear future revenue stream → Consider CLOSED
[ ] Both - Creates adoption AND will be paid later → Keep OPEN now, plan transition
[ ] Neither - Maintenance burden with no strategic value → Consider removing
```

### Question 5: What would a competitor do with this code?
```
[ ] Copy it and neutralize our advantage → Consider CLOSED
[ ] Copy it and still not compete (execution matters more) → Keep OPEN
[ ] Copy it and contribute improvements back → Definitely OPEN
[ ] Ignore it because it's not the valuable part → Keep OPEN
```

---

## Key Metrics to Track (Even Pre-API)

1. **GitHub Stars / Clone Rate:** Are people finding and trying your code?
2. **Issue Activity:** Are users engaged enough to report problems?
3. **Time to "Aha Moment":** Can you instrument when users first experience value?
4. **Feature Usage Patterns:** What do users actually use vs. ignore?
5. **Community Contributions:** Are external developers helping improve the code?

---

## Red Flags in Pre-API Phase

**You're too closed if:**
- GitHub repo has <10 stars after 3 months of promotion
- Developers can't run your product locally without your infrastructure
- Your "open source" project requires API keys for basic functionality
- Documentation says "coming soon" for core features

**You're too open if:**
- You've open sourced your entire future business model with no moat
- Competitors are using your code to compete directly without contributing
- You're supporting enterprise features for free with no revenue path
- Your open source project has more maintainers than users

---

## Transition Planning

**Before you build API validation, document:**

1. **Current State:**
   - What code is open source today?
   - What features work without your infrastructure?
   - How many active users/developers do you have?

2. **Future State:**
   - What will become paid services?
   - What stays free forever?
   - How will you communicate the transition?

3. **Migration Path:**
   - Will existing users be grandfathered?
   - What's the timeline for introducing paid tiers?
   - How do you maintain trust during transition?

**The Goal:** When you do introduce API keys and paid services, it should feel like you're offering valuable new capabilities, not taking away what was free.

---

## Example Decision Scenarios

### Scenario 1: Core ML Model
- **Code:** Your proprietary ML model for content analysis
- **Decision:** OPEN SOURCE
- **Reasoning:** The model is your "aha moment." Users need to run it locally to see value. Your future revenue is the API service (faster, scaled, no setup), not the model itself. Open sourcing builds trust and adoption.

### Scenario 2: Distributed Processing Engine
- **Code:** Your infrastructure for processing millions of records across clusters
- **Decision:** KEEP CLOSED
- **Reasoning:** This is expensive to run and your future revenue stream. Users can start with local/small-scale processing (open source). When they need scale, they pay for your managed service.

### Scenario 3: React UI Components
- **Code:** Beautiful, polished UI components for your product
- **Decision:** OPEN SOURCE
- **Reasoning:** UI reduces friction to adoption. Developers might contribute improvements. Not a competitive moat (anyone can build UI). Creates community goodwill.

### Scenario 4: Enterprise SSO Integration
- **Code:** SAML/OAuth integrations for enterprise identity providers
- **Decision:** KEEP CLOSED
- **Reasoning:** This is an enterprise feature you'll charge for. Small teams don't need it. No point supporting it for free. Clear future revenue path.

### Scenario 5: CLI Tool
- **Code:** Command-line interface for your product
- **Decision:** OPEN SOURCE
- **Reasoning:** Increases accessibility, generates adoption, benefits from community contributions. Not a revenue source itself.

---

## Section 10: Service Transition Patterns (Pre-API → API)

**Context:** When you plan to eventually add backend services (v1.7.0+), your pre-API decisions should make that transition smooth.

### Client-Side to Server-Side Validation (Roadcrew Example)

**Phase 1: Pre-API (v1.6.0) - Client-Side Validation**
- Feature code is open-source (commands published)
- License key check happens at runtime (local validation)
- No server calls, no backend needed
- Validation is "honor system" (users could bypass by modifying code)
- Compiled distribution makes it harder to bypass

**Transition Decision:**
Should this be COMPILED-ONLY or OPEN SOURCE?
- If you think you'll move to server-side later → Choose COMPILED-ONLY
  - Users already expect "you check my license at runtime"
  - When you add server backend, feels like natural upgrade
  - Easy to migrate: compiled code calls server instead of checking locally
  
- If you want community contributions → Choose OPEN SOURCE
  - Accept that users CAN modify/bypass locally
  - Your real protection comes later (server-side validation)
  - When you ship v1.7.0 server-side, local modification becomes irrelevant
  - Example: Even if user modifies local code, server still validates

**Phase 2: API-Based (v1.7.0) - Server-Side Validation**
- Same commands published
- License validation moved to backend API call
- Token quota enforced server-side (hard blocking)
- Client-side validation becomes secondary (belt & suspenders)
- Compiled code calls API transparently

**Key Lesson:**
Your Phase 1 choice (COMPILED-ONLY vs OPEN) doesn't lock you into Phase 2.
- COMPILED-ONLY in Phase 1 makes server transition feel like an optimization
- OPEN in Phase 1 means server validation is the real enforcement when it ships
- Both paths lead to same result (server-validated) but different user experience

### Decision Matrix: Open/Closed/Compiled for Transitioning Products

| Phase | Monetization | Distribution | Validation | User Experience |
|-------|--------------|--------------|-----------|-----------------|
| **Pre-API (Today)** | No | Open/Compiled | Client-side (local) | "Feature works, but I see you check for license" |
| **API-Based (Later)** | Yes | Same | Server-side (API) | "Feature works, you're checking my usage server-side" |

The difference to users is WHEN validation happens, not WHETHER code is published.

---

## Cursor AI Analysis Prompt Template

When analyzing codebase, use this template:

```
ANALYZING: [file/module path]

1. FUNCTION: This code does [description]

2. VALUE CATEGORY:
   [ ] Core "aha moment" feature
   [ ] Infrastructure/scaling capability  
   [ ] Enterprise/governance feature
   [ ] Developer experience improvement
   [ ] Integration/connectivity

3. ADOPTION IMPACT:
   Without this code, users [can/cannot] experience core value
   This code [increases/decreases/neutral] likelihood of adoption

4. REVENUE POTENTIAL:
   This code [will/might/won't] become a paid service
   Estimated future value: [high/medium/low/none]

5. COMPETITIVE ANALYSIS:
   If competitors copy this: [neutralizes advantage / no impact / strengthens ecosystem]
   Our moat is: [the code / the execution / the data / the network]

6. RECOMMENDATION:
   [ ] OPEN SOURCE - Reasoning: [why]
   [ ] KEEP CLOSED - Reasoning: [why]
   [ ] STRATEGIC DECISION NEEDED - Factors: [what to consider]

7. TRANSITION PLAN:
   If OPEN now, close later: [yes/no/maybe] - Plan: [description]
   If CLOSED now, open later: [yes/no/maybe] - Plan: [description]
```

---

## Final Principle for Pre-API Phase

**When in doubt, open source it.**

You're not building a business yet—you're building adoption. Every closed piece of code is friction. Every open piece is a potential viral loop. You can always close things later, but you can't easily re-open them without breaking trust.

**Three Strategies for Protecting Revenue (Pick One):**

1. **CLOSED** - Don't publish at all
   - Strategic IP, internal architecture, roadmap
   - Cost: No community feedback or contributions
   - Benefit: Maximum control

2. **COMPILED-ONLY** - Publish compiled, keep sources private
   - Users see what you do, can't easily modify
   - Cost: Decompilers/source maps risk
   - Benefit: Transparency + Control + Bridge to server-side validation
   - Best for: Transitioning from free to paid (Roadcrew model)

3. **GATED** - Publish with runtime license checks
   - Code is open, features require key at execution time
   - Cost: Users could modify locally (pre-API phase only)
   - Benefit: Community trust + Easy server-side upgrade path later
   - Best for: Feature flags that become paid with server validation (v1.7.0)

**Choose based on your transition plan:**
- 6-month path to paid services? → Use COMPILED-ONLY or GATED
- 18+ month before monetization? → Use full OPEN, server-side validates later
- Competitor risk is high? → Use CLOSED for strategic parts, OPEN for adoption drivers

The code you should protect pre-API:
1. Code you'll definitely charge for as a service within 12 months (COMPILED-ONLY or GATED)
2. Code that would let competitors neutralize your advantage overnight (CLOSED)
3. Code that's expensive for you to support without revenue (CLOSED)
4. Strategic IP that informs your business model (CLOSED)

Everything else? Ship it open or gated. Build trust. Create adoption. Make revenue later.