feat: Introduce module-based practice, auto-mode V2, and question management with new UI components and data structures.

archive/legacy-backup-20251209/README.md

@@ -0,0 +1,39 @@
+# Legacy Backup - 2025-12-09
+
+## Archived Files
+
+These files were archived during the repository cleanup on 2025-12-09.
+
+### Deprecated AI Server Actions
+
+| File                  | Reason                                                  |
+| --------------------- | ------------------------------------------------------- |
+| `generateQuestion.ts` | Replaced by `src/lib/questionService.ts` and API routes |
+| `evaluateCode.ts`     | Replaced by `/api/ai/evaluate` route                    |
+| `getHints.ts`         | Replaced by `/api/ai/hints` route                       |
+| `revealSolution.ts`   | Replaced by `/api/ai/solution` route                    |
+| `optimizeSolution.ts` | Replaced by `/api/ai/optimize` route                    |
+
+## Restoration Instructions
+
+To restore any file:
+
+```bash
+# Copy back from archive
+cp archive/legacy-backup-20251209/<filename> src/lib/ai/
+
+# Or use git to restore from before cleanup
+git checkout pre-cleanup-20251209 -- src/lib/ai/<filename>
+```
+
+## Why Archived
+
+These files were marked as DEPRECATED in their headers. They were server actions
+that have been replaced by the new API route-based architecture for Gemini calls.
+
+The new architecture uses:
+
+- `/api/ai/*` routes for all AI operations
+- `src/lib/ai/geminiClient.ts` for client initialization
+- `src/lib/ai/modelRouter.ts` for model selection
+- `src/lib/questionService.ts` for question generation

cleanup-report.json

@@ -0,0 +1,90 @@
+{
+  "auditDate": "2025-12-09T13:44:43+05:30",
+  "branch": "chore/cleanup-legacy-20251209",
+  "summary": {
+    "unusedDependencies": [],
+    "lucideReactUsage": false,
+    "deprecatedFiles": [
+      {
+        "path": "src/lib/ai/generateQuestion.ts",
+        "reason": "Marked DEPRECATED - replaced by questionService",
+        "priority": "high",
+        "action": "archive"
+      },
+      {
+        "path": "src/lib/ai/evaluateCode.ts",
+        "reason": "Marked DEPRECATED - replaced by API routes",
+        "priority": "high",
+        "action": "archive"
+      },
+      {
+        "path": "src/lib/ai/getHints.ts",
+        "reason": "Marked DEPRECATED - replaced by API routes",
+        "priority": "high",
+        "action": "archive"
+      },
+      {
+        "path": "src/lib/ai/revealSolution.ts",
+        "reason": "Marked DEPRECATED - replaced by API routes",
+        "priority": "high",
+        "action": "archive"
+      },
+      {
+        "path": "src/lib/ai/optimizeSolution.ts",
+        "reason": "Marked DEPRECATED - replaced by API routes",
+        "priority": "high",
+        "action": "archive"
+      }
+    ],
+    "mockDataFiles": [
+      {
+        "path": "src/lib/mockQuestions.ts",
+        "reason": "Mock data - still referenced by PracticeContext and fallback",
+        "priority": "low",
+        "action": "keep-for-now",
+        "usedBy": [
+          "src/app/PracticeContext.tsx",
+          "src/lib/ai/generateQuestion.ts",
+          "src/app/api/ai/generate-question/route.ts"
+        ]
+      }
+    ],
+    "lintIssues": [
+      {
+        "file": "src/components/automode/AutoModeStatsBarV2.tsx",
+        "line": 96,
+        "issue": "setState in useEffect",
+        "action": "fix"
+      }
+    ],
+    "manualReview": [
+      {
+        "file": "src/lib/statsStore.ts",
+        "note": "Contains legacy compatibility wrappers - keep for backward compat"
+      }
+    ]
+  },
+  "removalSequence": [
+    {
+      "commit": "A",
+      "description": "Archive deprecated AI server actions",
+      "files": [
+        "src/lib/ai/generateQuestion.ts",
+        "src/lib/ai/evaluateCode.ts",
+        "src/lib/ai/getHints.ts",
+        "src/lib/ai/revealSolution.ts",
+        "src/lib/ai/optimizeSolution.ts"
+      ]
+    },
+    {
+      "commit": "B",
+      "description": "Fix setState in effect issue",
+      "files": ["src/components/automode/AutoModeStatsBarV2.tsx"]
+    },
+    {
+      "commit": "C",
+      "description": "Remove unused STATS_VERSION constant",
+      "files": ["src/lib/statsStore.ts"]
+    }
+  ]
+}

docs/AUTO_MODE_V2.md

@@ -0,0 +1,100 @@
+# Auto Mode v2: Curriculum-Aware Adaptive Pacing
+
+## Overview
+
+Auto Mode v2 provides intelligent, curriculum-aware practice with adaptive difficulty based on user performance.
+
+## How It Works
+
+### 1. Mini-Curriculum
+
+New runs start with a focused 12-question curriculum on **String Manipulation**:
+
+- Basic string operations (indexing, slicing)
+- Two-pointer techniques
+- Sliding window patterns
+- Pattern matching
+
+After completing the mini-curriculum (or demonstrating mastery), the system broadens to weakness-based topic selection.
+
+### 2. Streak-Based Difficulty Progression
+
+| Event              | Action                                              |
+| ------------------ | --------------------------------------------------- |
+| Correct answer     | `streak++`                                          |
+| 3 correct in a row | Promote difficulty (beginner→intermediate→advanced) |
+| Incorrect answer   | `streak = 0`, demote difficulty, inject remediation |
+
+**Aggressive mode** (opt-in): Promote after 2 correct instead of 3.
+
+### 3. Difficulty Per Subtopic
+
+Each subtopic tracks its own difficulty level:
+
+```
+difficultyPointer: {
+  "basic-string-operations": "intermediate",
+  "sliding-window-patterns": "beginner",
+  "pattern-matching": "advanced"
+}
+```
+
+### 4. Remediation
+
+When a user answers incorrectly:
+
+1. Difficulty is demoted for that subtopic
+2. 2 extra beginner questions from that subtopic are injected into the queue
+3. "Slow Down" button available to manually trigger this
+
+### 5. Decay Timer
+
+If inactive for >24 hours, streak is reduced by 50% to prevent stale mastery carryover.
+
+---
+
+## Tuning Parameters
+
+| Parameter                   | Default | Description                           |
+| --------------------------- | ------- | ------------------------------------- |
+| `streakToPromote`           | 3       | Correct answers to promote difficulty |
+| `aggressiveStreakToPromote` | 2       | Same, when Fast Mode enabled          |
+| `extraRemediationCount`     | 2       | Questions injected on failure         |
+| `miniCurriculumSize`        | 12      | Initial focused curriculum size       |
+| `decayHours`                | 24      | Hours before streak decays            |
+| `prefetchBufferSize`        | 2       | Questions to prefetch                 |
+
+---
+
+## User Controls
+
+### Stats Bar
+
+- **Breadcrumb**: Current module → subtopic
+- **Streak**: 🔥 indicator with animation
+- **Difficulty badge**: Current level for subtopic
+- **Progress**: Mini-curriculum or ongoing count
+
+### Quick Settings
+
+- **Fast Progression**: Toggle for 2-correct promotion
+- **Remediation Mode**: Auto-inject questions on mistakes
+- **Slow Down**: Reset streak + add easier questions
+
+---
+
+## Storage
+
+| Key                          | Content                     |
+| ---------------------------- | --------------------------- |
+| `pytrix_auto_run_v2_{runId}` | Individual run state        |
+| `pytrix_auto_analytics`      | Promotion/demotion counters |
+
+---
+
+## Files
+
+- [`src/lib/autoRunTypes.ts`](./src/lib/autoRunTypes.ts) - Type definitions
+- [`src/lib/autoModeServiceV2.ts`](./src/lib/autoModeServiceV2.ts) - Core service
+- [`src/components/automode/AutoModeStatsBarV2.tsx`](./src/components/automode/AutoModeStatsBarV2.tsx) - Stats bar
+- [`src/components/automode/AutoModeControls.tsx`](./src/components/automode/AutoModeControls.tsx) - Settings popover

docs/PAGE-ROLES.md

@@ -0,0 +1,80 @@
+# Page Roles & Responsibilities
+
+This document defines the distinct identities, interaction models, and content hierarchies for the core pages of the PyPractice MVP.
+
+## 1. Dashboard (`/dashboard`)
+
+**"Overview & Progress Hub"**
+
+### Purpose
+
+Answers: _"How am I doing overall, and where should I go next?"_
+
+### Key Responsibilities
+
+- **High-Level Status**: Global stats (mastery, streaks, problems solved).
+- **Navigation Hub**: Suggestions on what to do next (e.g., "Resume Auto Run", "Practice Weakest Topic").
+- **Activity Feed**: Quick history of recent sessions.
+
+### Anti-Patterns (What NOT to do)
+
+- Do not show the full curriculum tree (that belongs in Modules).
+- Do not include detailed configuration controls for new questions (that belongs in Manual Practice).
+
+---
+
+## 2. Modules (`/modules`)
+
+**"Curriculum Browser"**
+
+### Purpose
+
+Answers: _"What content exists and how is it structured?"_
+
+### Key Responsibilities
+
+- **Content Discovery**: Full browseable tree of Modules -> Subtopics -> Problem Types.
+- **Learning Roadmap**: Linear or exploratory view of the curriculum.
+- **Deep Linking**: Entry points to start practice on specific topics.
+
+### Anti-Patterns
+
+- Do not clutter with global user stats or streaks.
+- Do not autoplay practice sessions directly without context.
+
+---
+
+## 3. Manual Practice (`/practice/manual`)
+
+**"Focused Practice Configurator"**
+
+### Purpose
+
+Answers: _"Exactly what type of question do you want to solve right now?"_
+
+### Key Responsibilities
+
+- **Precise Setup**: Form-like controls to select Module, Subtopic, Difficulty, and Constraints.
+- **Quick Launch**: Strong "Generate Question" action.
+- **Preview**: Brief summary of what will be generated.
+
+### Anti-Patterns
+
+- Do not show the full module browsing grid.
+- Do not show unrelated global stats.
+
+---
+
+## 4. Practice Workspace (`/practice`)
+
+**"The IDE"**
+
+### Purpose
+
+Answers: _"How do I solve this specific problem?"_
+
+### Key Responsibilities
+
+- **Execution Environment**: Code editor, question panel, output terminal.
+- **Feedback Loop**: Run, check, hints, solution reveal.
+- **Focus**: Minimal distractions, centered on the current problem.