Course Package Format (ZIP)

Specification for the course archive that authors upload in Studio. Referenced from plan.md.

1. Archive structure

course-name.zip
├── course.md              # "CoC" — Course of Contents / manifest
├── lessons/
│   ├── 01-intro.md
│   ├── 02-basics.md
│   └── ...
└── assets/                # images referenced by lessons (PNG; SVG also accepted)
    ├── 01-diagram-a.png
    └── 01-diagram-b.png

assets/ is optional. Files are uploaded as part of the course package and relative references are rewritten when a matching asset exists. Image filenames may be prefixed with the lesson number for readability, but the importer does not enforce a naming convention or image count.

2. course.md (manifest) — YAML frontmatter + description body

---
title: "Elixir Basics"
slug: elixir-basics
language: en            # en | ru | es
level: beginner
tags: [elixir, backend]
lessons:
  - 01-intro.md
  - 02-basics.md
---

Course description in markdown...

Manifest rules:

• title, slug, language, lessons are required; level, tags optional. The platform assigns and increments the stored course version; there is no user-controlled manifest version field.

• language must be one of en | ru | es.

• lessons order defines course order; every listed file must exist in lessons/.
• slug is unique per language. New imports receive a unique slug if the requested slug is already used. ZIP updates target the selected course and preserve its current slug if the manifest slug conflicts with another course. User progress is keyed by lesson and user records; replacing a ZIP recreates the course lessons.

3. Lesson file — frontmatter + structured sections

---
title: "Introduction"
position: 1
---

## Theory
Regular markdown content...

![BEAM process model](assets/01-process-model.png)

## Examples
```elixir
IO.puts("hello")
```

```mermaid
flowchart LR
    A[spawn] --> B[Process]
    B --> C[receive]
```

## Checklist
- [ ] Understand mix
- [ ] Install Elixir

## Questions
1. What is a process in Elixir?
   - [ ] OS thread
   - [x] Lightweight BEAM process
   - [ ] Green thread

Section rules:

• Recognized ## sections: Theory, Examples, Checklist, Questions. Unrecognized sections are kept as plain content.
• Checklist items become interactive checkable items with per-user state.
• Questions become quiz data: numbered items are prompts, task-list items are options, [x] marks the correct answer (exactly one per question).
• Relative image links (![alt](assets/file.png), ./assets/file.png, or ../assets/file.png) are rewritten to stored asset URLs when the matching file exists. Supported image MIME types include SVG, PNG, JPG, JPEG, WebP, GIF, AVIF, BMP, and ICO.
• Fenced ```mermaid blocks are imported as ordinary Markdown code blocks. The importer does not validate or render Mermaid diagrams.

4. Validation & failure modes