# Phase 1: Campaign Foundation & Core Systems

**Priority**: HIGHEST - Must complete first  
**Estimated Effort**: 12-16 hours  
**Status**: In Progress  
**Dependencies**: None

---

## 📝 Subphase Tracking

- [x] **Subphase 1.1**: Campaign Progression System (2-3 hrs) - ✅ COMPLETE - User tested and confirmed
- [x] **Subphase 1.2**: Preference Management System (2-3 hrs) - ✅ COMPLETE - User tested and confirmed
- [x] **Subphase 1.3**: Library Tagging System (2-3 hrs) - ✅ COMPLETE - User tested and confirmed
- [x] **Subphase 1.4**: Content Filtering & UI (2-3 hrs) - ✅ COMPLETE - Awaiting user test

**⚠️ IMPORTANT**: After each subphase implementation, WAIT for user to test and confirm before proceeding to next subphase.

---

## 🎯 Phase Goals

Build the foundational systems required for The Academy's 30-level campaign structure, including campaign progression, preference management, and media library tagging.

---

## 📋 What This Phase Delivers

### Core Systems:
1. **Campaign Progression System** - Level unlocking, completion tracking, failure states
2. **Preference Management System** - User preferences with checkpoint updates
3. **Media Library Tagging System** - Directory and individual file tagging
4. **Tag-Based Content Filtering** - Filter videos/images by preferences and tags
5. **Data Persistence** - Save/load campaign progress, preferences, library data
6. **Basic UI Infrastructure** - Level selection, preference forms, library management

**End Result**: Foundation that all 30 levels will build upon.

---

## 🏗️ Implementation Tasks

### Task 1: Campaign Progression System (4-5 hours)

**File to Create**: `src/features/academy/campaignManager.js`

**Responsibilities**:
- Track which levels are unlocked (start with only Level 1)
- Handle level completion (unlock next level)
- Track current level, highest completed level
- Handle failure states (cumming, abandoning session, feature closure)
- Manage level restart on failure
- Save/load campaign state

**Data Structure** (in `gameData.js`):
```javascript
academyProgress: {
  version: 1,
  currentLevel: 1,
  highestUnlockedLevel: 1,
  completedLevels: [], // array of level numbers completed
  currentArc: 'Foundation', // Foundation, Feature Discovery, etc.
  failedAttempts: {}, // { levelNum: count }
  totalSessionTime: 0, // seconds across all levels
  lastPlayedLevel: null,
  lastPlayedDate: null,
  graduationCompleted: false,
  freeplayUnlocked: false,
  ascendedModeUnlocked: false
}
```

**Key Methods**:
```javascript
class CampaignManager {
  constructor() {
    this.loadProgress();
  }
  
  // Get list of unlocked levels
  getUnlockedLevels() {
    // Returns array: [1, 2, 3, ...highestUnlockedLevel]
  }
  
  // Check if level is unlocked
  isLevelUnlocked(levelNum) {
    // Returns true if levelNum <= highestUnlockedLevel
  }
  
  // Start a level
  startLevel(levelNum) {
    // Validates level is unlocked
    // Loads level data
    // Returns level config or error
  }
  
  // Complete a level
  completeLevel(levelNum, sessionData) {
    // Add to completedLevels
    // Unlock next level
    // Update stats
    // Check for arc completion
    // Save progress
    // Return: { nextLevelUnlocked, achievements, arcComplete }
  }
  
  // Fail a level
  failLevel(levelNum, reason) {
    // Increment failedAttempts
    // Log failure reason ('cumming', 'abandoned', 'feature-closed')
    // Save progress
  }
  
  // Get current arc
  getCurrentArc() {
    // Based on current level, return arc name
    // L1-5: Foundation
    // L6-10: Feature Discovery
    // L11-15: Mind & Body
    // L16-20: Advanced Training
    // L21-25: Path Specialization
    // L26-30: Ultimate Mastery
  }
  
  // Check if level is a checkpoint
  isCheckpointLevel(levelNum) {
    // Returns true for levels 1, 5, 10, 15, 20, 25
  }
  
  // Save/load
  saveProgress() { /* save to gameData */ }
  loadProgress() { /* load from gameData */ }
}
```

**Testing Checklist**:
- [ ] Can start Level 1
- [ ] Completing L1 unlocks L2
- [ ] Cannot start L2 before completing L1
- [ ] Failing L1 allows restart
- [ ] Progress persists across page refresh
- [ ] Arc detection works correctly
- [ ] Checkpoint detection works for L1, L5, L10, etc.

---

### Task 2: Preference Management System (3-4 hours)

**File to Create**: `src/features/academy/preferenceManager.js`

**Responsibilities**:
- Display preference form at checkpoint levels
- Save user preferences
- Filter content based on preferences
- Generate preference-based text (captions, mantras, oaths)

**Data Structure** (in `gameData.js`):
```javascript
academyPreferences: {
  lastUpdatedLevel: 1,
  contentThemes: {
    sissy: false,
    humiliation: false,
    worship: false,
    denial: false,
    obedience: true,
    bimbo: false,
    findom: false,
    edging: true // always true
  },
  visualPreferences: {
    amateur: true,
    professional: true,
    hentai: false,
    bodyTypes: ['curvy', 'athletic'],
    specificContent: [] // 'feet', 'BBC', etc.
  },
  intensity: {
    soft: false,
    moderate: true,
    harsh: false,
    extreme: false
  },
  captionTone: {
    neutral: true,
    masculine: false,
    feminine: false,
    motivational: true,
    degrading: false
  }
}
```

**Key Methods**:
```javascript
class PreferenceManager {
  // Display preference form (at checkpoints)
  showPreferenceForm(levelNum) {
    // Generate HTML form with checkboxes
    // Pre-fill with current preferences
    // Return promise that resolves when user submits
  }
  
  // Save preferences
  savePreferences(prefs) {
    // Update academyPreferences in gameData
    // Set lastUpdatedLevel
    // Save to storage
  }
  
  // Get preferences
  getPreferences() {
    // Return current preferences
  }
  
  // Check if theme is enabled
  isThemeEnabled(theme) {
    // Returns true if contentThemes[theme] === true
  }
  
  // Get enabled themes
  getEnabledThemes() {
    // Returns array of enabled theme names
  }
  
  // Generate preference-based text
  generateMantra() {
    // Based on enabled themes, return appropriate mantra
    // e.g., sissy enabled: "I am a sissy gooner..."
  }
  
  generateCaptionTags() {
    // Returns array of caption tags based on themes
    // Used to filter caption images
  }
  
  // Filter content by preferences
  matchesPreferences(contentTags) {
    // Given array of tags, check if matches user preferences
    // Returns true if compatible
  }
}
```

**UI Components Needed**:
```html
<!-- Preference Form (shown at L1, L5, L10, 15, 20, 25) -->
<div id="preference-form">
  <h2>Set Your Preferences</h2>
  <p>Customize your Academy experience.</p>
  
  <section>
    <h3>Content Themes</h3>
    <label><input type="checkbox" name="theme-sissy"> Sissy/Feminization</label>
    <label><input type="checkbox" name="theme-humiliation"> Humiliation/Degradation</label>
    <label><input type="checkbox" name="theme-worship"> Worship/Devotion</label>
    <label><input type="checkbox" name="theme-denial"> Denial/Chastity</label>
    <label><input type="checkbox" name="theme-obedience" checked> Obedience/Control</label>
    <label><input type="checkbox" name="theme-bimbo"> Bimbo/Dumbification</label>
    <label><input type="checkbox" name="theme-findom"> Findom/Tribute</label>
  </section>
  
  <!-- Visual Preferences, Intensity, Caption Tone sections similar -->
  
  <button id="save-preferences">Save Preferences</button>
</div>
```

**Testing Checklist**:
- [ ] Preference form appears at L1
- [ ] Can select/deselect preferences
- [ ] Preferences save to gameData
- [ ] Preferences persist across refresh
- [ ] Content filtering respects preferences
- [ ] Mantra generation adapts to preferences

---

### Task 3: Media Library Tagging System (4-5 hours)

**Files to Create**: 
- `src/features/academy/libraryManager.js`
- `src/features/academy/tagManager.js`

**Responsibilities**:
- Add directories to library
- Tag directories (bulk tags for all files in directory)
- Tag individual files (specific tags per file)
- Calculate tag coverage percentage
- Track curator rank
- Display library statistics

**Data Structure** (in `gameData.js`):
```javascript
libraryData: {
  directories: [
    {
      path: '/assets/BBC/',
      tags: ['bbc', 'interracial'],
      addedAtLevel: 2,
      fileCount: 47,
      subdirectories: [...]
    }
  ],
  individualFiles: [
    {
      path: '/assets/BBC/amateur/video01.mp4',
      type: 'video',
      duration: 272,
      quality: '1080p',
      directoryTags: ['bbc', 'interracial', 'amateur'],
      customTags: ['pov', 'blowjob'],
      allTags: ['bbc', 'interracial', 'amateur', 'pov', 'blowjob'],
      taggedAtLevel: 3,
      timesPlayed: 12
    }
  ],
  statistics: {
    totalFiles: 1247,
    taggedFiles: 1200,
    untaggedFiles: 47,
    tagCoverage: 96.2,
    curatorRank: 'Expert',
    totalTags: 2847,
    uniqueTags: 87,
    topTags: [
      { tag: 'amateur', count: 423 }
    ]
  }
}
```

**Key Methods**:

```javascript
class LibraryManager {
  addDirectory(path, tags = []) { /* Add to directories array */ }
  tagDirectory(path, tags) { /* Add tags to directory */ }
  tagFile(filePath, tags) { /* Add custom tags to specific file */ }
  getFileTags(filePath) { /* Return allTags for a file */ }
  getFilesByTags(tags, matchMode = 'AND') { /* Filter files by tags */ }
  updateStatistics() { /* Calculate totals, coverage %, curator rank */ }
  getCuratorRank() { 
    // <50%: Novice, 50-75%: Apprentice, 75-90%: Journeyman
    // 90-98%: Expert, 98-100%: Master
  }
}

class TagManager {
  getAllTags() { /* Return comprehensive tag list */ }
  suggestTags(filename) { /* Parse filename for keywords */ }
  isValidTag(tag) { /* Check if tag exists in catalog */ }
  addCustomTag(tag) { /* Allow user-defined tags */ }
}
```

**UI Components**:
- Directory tagging form
- File tagging form  
- Library statistics dashboard

**Testing Checklist**:
- [ ] Can add directory with tags
- [ ] Can tag individual file
- [ ] File inherits directory tags
- [ ] Tag coverage calculates correctly
- [ ] Curator rank advances based on coverage
- [ ] Statistics persist across refresh

---

### Task 4: Tag-Based Content Filtering (2-3 hours)

**File to Update**: `src/features/video/videoLibrary.js`

**New Methods**:
```javascript
class VideoLibrary {
  getVideosByTags(tags, matchMode = 'AND') {
    // Use LibraryManager to get matching files
    // Filter by type === 'video'
  }
  
  getVideosByPreferences(preferences) {
    // Convert preferences to tags
    // Use getVideosByTags
  }
  
  getRandomVideo(tags = null, preferences = null) {
    // Filter by tags/preferences, return random
  }
}
```

**Testing Checklist**:
- [ ] Video filtering by tags works
- [ ] Preference-based filtering works
- [ ] Returns null gracefully if no matches

---

### Task 5: Data Persistence (1-2 hours)

**File to Update**: `src/core/gameDataManager.js`

Add academy data structures and ensure save/load works.

**Testing Checklist**:
- [ ] All academy data saves
- [ ] All academy data loads on refresh
- [ ] Existing saves migrate without errors

---

### Task 6: Basic UI Infrastructure (2-3 hours)

**File to Update**: `training-academy.html`

Add:
- Level select screen (30 level buttons)
- Checkpoint modal (preferences/library tabs)
- Level completion screen

**Testing Checklist**:
- [ ] Level select screen displays
- [ ] Locked levels appear disabled
- [ ] Checkpoint modal appears correctly
- [ ] Level completion screen shows stats

---

## 📏 Measurable Test Criteria

After Phase 1, ALL of these must pass:

### Campaign Progression:
- [ ] Can select and start Level 1
- [ ] Completing Level 1 unlocks Level 2
- [ ] Cannot start Level 2 before completing Level 1
- [ ] Failing Level 1 allows restart
- [ ] Progress persists across refresh
- [ ] Current arc displays correctly

### Preferences:
- [ ] Preference form appears at Level 1
- [ ] Preferences save and persist
- [ ] Preference form appears at Level 5

### Library Tagging:
- [ ] Can add directory with tags at Level 2
- [ ] Can tag individual file at Level 3
- [ ] Tag coverage calculates correctly
- [ ] Curator rank displays
- [ ] Library statistics persist

### Content Filtering:
- [ ] Can filter videos by tags
- [ ] Preference filtering works

### Data Persistence:
- [ ] All data saves and loads correctly
- [ ] No console errors

### UI:
- [ ] Level select renders 30 levels
- [ ] Checkpoint modal functional
- [ ] Level completion screen displays

---

## 🎯 Success Criteria

**Phase 1 Complete When:**
1. All 6 tasks implemented
2. All measurable tests pass
3. No console errors
4. Can complete L1 → unlock L2 → checkpoint at L5
5. Library tagging works at L2-3
6. All data persists

---

## 📂 Files Created/Modified

### New Files:
- `src/features/academy/campaignManager.js`
- `src/features/academy/preferenceManager.js`
- `src/features/academy/libraryManager.js`
- `src/features/academy/tagManager.js`

### Modified Files:
- `src/core/gameDataManager.js`
- `src/features/video/videoLibrary.js`
- `training-academy.html`

---

## 🚀 Next Phase

After Phase 1: **Phase 2: Levels 1-10 Implementation**
