# How to Add Exams

## ✅ All Previous Exams Removed

The system has been reset:
- ✓ Input folder cleaned
- ✓ Output folder cleaned  
- ✓ Attempts cleaned
- ✓ Manifest reset

## Adding a New Exam

### Step 1: Create Exam JSON

Create a file in `data/input/` following this format:

**Example: `data/input/my-first-exam.json`**

```json
{
  "examId": "my-first-exam",
  "subject": "python",
  "title": "My First Exam",
  "difficulty": "beginner",
  "durationMinutes": 30,
  "sections": [
    {
      "id": "sec-1",
      "title": "Multiple Choice",
      "questions": [
        {
          "id": "q1",
          "type": "single_choice",
          "prompt": "What is 2 + 2?",
          "choices": [
            { "key": "A", "text": "3" },
            { "key": "B", "text": "4" },
            { "key": "C", "text": "5" }
          ],
          "answer": "B",
          "points": 10
        }
      ]
    },
    {
      "id": "sec-2",
      "title": "True/False",
      "questions": [
        {
          "id": "q2",
          "type": "true_false",
          "prompt": "Python is a programming language.",
          "answer": true,
          "points": 5
        }
      ]
    },
    {
      "id": "sec-3",
      "title": "Essay",
      "questions": [
        {
          "id": "q3",
          "type": "essay",
          "prompt": "Explain what you learned today.",
          "rubric": {
            "criteria": [
              { "name": "Clarity", "weight": 0.5 },
              { "name": "Completeness", "weight": 0.5 }
            ],
            "maxPoints": 10
          },
          "points": 10
        }
      ]
    }
  ],
  "metadata": {
    "createdAt": "2025-10-20T00:00:00Z",
    "version": "1.0.0"
  }
}
```

### Step 2: Update Manifest

Edit `data/manifest.json`:

```json
{
  "version": "1.0.0",
  "exams": [
    {
      "examId": "my-first-exam",
      "path": "input/my-first-exam.json",
      "published": true,
      "version": "1.0.0"
    }
  ],
  "users": {}
}
```

**Important:** 
- `examId` must match the filename (without .json)
- `published: true` makes it visible
- `published: false` hides it (draft mode)

### Step 3: Refresh Browser

Go to http://localhost - your exam will appear!

## Question Type Reference

### 1. Single Choice (MCQ)

```json
{
  "id": "q1",
  "type": "single_choice",
  "prompt": "Your question here?",
  "choices": [
    { "key": "A", "text": "Option A" },
    { "key": "B", "text": "Option B" },
    { "key": "C", "text": "Option C" }
  ],
  "answer": "B",
  "points": 10
}
```

### 2. True/False

```json
{
  "id": "q2",
  "type": "true_false",
  "prompt": "Statement to evaluate.",
  "answer": true,
  "points": 5
}
```

### 3. Essay

```json
{
  "id": "q3",
  "type": "essay",
  "prompt": "Write about...",
  "rubric": {
    "criteria": [
      { "name": "Correctness", "weight": 0.6 },
      { "name": "Clarity", "weight": 0.4 }
    ],
    "maxPoints": 20
  },
  "points": 20
}
```

### 4. Simple Coding

```json
{
  "id": "q4",
  "type": "code_simple",
  "language": "python",
  "prompt": "Write a function that...",
  "tests": [
    { "input": "function(5)", "expected": "10", "visibility": "hidden" }
  ],
  "points": 15
}
```

### 5. Coding Exercise

```json
{
  "id": "q5",
  "type": "code_exercise",
  "language": "python",
  "prompt": "Implement a complex function...",
  "constraints": "Must be O(n) time complexity",
  "tests": [
    { "input": "func([1,2,3])", "expected": "[1,4,9]", "visibility": "hidden", "weight": 1 }
  ],
  "rubric": {
    "criteria": [
      { "name": "Correctness", "weight": 0.6 },
      { "name": "Efficiency", "weight": 0.4 }
    ],
    "maxPoints": 25
  },
  "points": 25
}
```

## Multiple Exams

To add multiple exams, create multiple JSON files and add all to manifest:

```json
{
  "version": "1.0.0",
  "exams": [
    {
      "examId": "python-basics",
      "path": "input/python-basics.json",
      "published": true,
      "version": "1.0.0"
    },
    {
      "examId": "django-fundamentals",
      "path": "input/django-fundamentals.json",
      "published": true,
      "version": "1.0.0"
    },
    {
      "examId": "angular-intro",
      "path": "input/angular-intro.json",
      "published": false,
      "version": "1.0.0"
    }
  ],
  "users": {}
}
```

## Publishing/Unpublishing

**Publish an exam:**
- Set `"published": true` in manifest

**Hide an exam (draft):**
- Set `"published": false` in manifest

Changes take effect immediately (refresh browser).

## Tips

1. **Use a template:** Copy an existing exam JSON and modify it
2. **Validate JSON:** Use a JSON validator or `python -m json.tool < your-exam.json`
3. **Test incrementally:** Add one question at a time
4. **Check format:** See `/docs/exam-format.md` for complete spec
5. **Unique IDs:** Make sure all question IDs are unique within an exam

## Validation Checklist

Before adding an exam, verify:
- [ ] Valid JSON format
- [ ] All required fields present (`examId`, `title`, `durationMinutes`, `sections`)
- [ ] Each section has `id`, `title`, `questions`
- [ ] Each question has `id`, `type`, `prompt`, `points`
- [ ] Type-specific fields included (choices, answer, rubric, tests, etc.)
- [ ] All IDs are unique
- [ ] Points are positive integers
- [ ] File saved in `data/input/` with `.json` extension
- [ ] Manifest updated with exam entry

## Quick Test

After adding an exam:

```bash
# Validate JSON
python3 -m json.tool < data/input/your-exam.json

# Check manifest
cat data/manifest.json

# Restart if needed (usually not required)
docker-compose restart exam_server

# Open browser
open http://localhost
```

Your exam should appear in the list!

## Example: Complete Exam Template

See `/docs/exam-format.md` for a complete example with all 5 question types.

---

**Current Status:** System is clean and ready for your exams!
**Next Step:** Create your first exam JSON in `data/input/`