# Course Package Format (ZIP)

**Specification version: 2.0**

Oceanowledge accepts two package types: `course` (practical lessons) and `book` (narrative chapters). The manifest is always named `course.md`.

## Archive structure

```text
course-name.zip
├── course.md
├── lessons/                 # type: course
│   └── 01-intro.md
├── chapters/                # type: book
│   └── 01-intro.md
└── assets/                  # optional PNG/SVG and other images
```

## Manifest

```markdown
---
type: course                 # course | book; defaults to course
title: "Elixir Basics"
version: "1.1"               # required MAJOR.MINOR package version
slug: elixir-basics
language: en                  # en | ru | es
level: beginner
tags: [elixir, backend]
lessons:
  - 01-intro.md
---
Description in Markdown...
```

Books use `type: book` and replace `lessons:` with `chapters:`. The matching directory and list are required; using the wrong key is a manifest error. The list order defines reading order. A published package re-upload must have a strictly greater `version`. Malformed versions are warnings; missing versions default to `"1.1"`.

## Course lessons

Each lesson has YAML frontmatter and all four sections: `## Theory`, `## Examples`, `## Checklist`, and `## Questions`. Questions use numbered prompts and task-list options, with exactly one `[x]` answer. Mermaid fences are preserved as ordinary Markdown. Relative `assets/...` image links are rewritten when the file exists.

## Book chapters

Chapters have YAML frontmatter and free-form prose. Optional reserved sections are:

- `## Illustration`: each `###` heading defines a named figure with its first image and optional italic caption.
- `## Encyclopedia`: each `###` heading defines a glossary term and its definition.
- `## Questions`: the same optional self-check format as course questions.
- `## Further Reading`: Markdown content, commonly a link list.

Checklists are course-only. Book chapters may contain ordinary `##`/`###` headings outside the reserved sections.

## Validation and limits

Missing `course.md`, invalid type, wrong content key, missing listed files, bad content frontmatter, missing course sections, path traversal, or an archive over 50 MB/1,000 files fails the import. Unlisted content files, malformed package versions, broken image references, and questions without exactly one correct option are warnings; invalid questions are skipped.

Assets are uploaded under a versioned course path. Replacing a package replaces its content and preserves the course record while incrementing the platform’s internal course version.