# Opis repozytorium pojedynczej karty

Każda karta jest osobnym repozytorium lub samodzielnym katalogiem. Jej źródłem
prawdy jest `json/card_source.json`; pliki TeX i HTML są artefaktami
generowanymi.

## Minimalne drzewo

```text
moja-karta/
├── README.md
├── json/card_source.json
├── doc/
├── web/
└── src/
```

## Obowiązkowe warstwy danych

### Metadane

Obiekt `card` identyfikuje serię, numer, wersję, UUID, autora i status.
Obiekt `generated` wskazuje ścieżki wyjściowe TeX/HTML/CSS. Pole `template`
wybiera layout.

Opcjonalny obiekt `title_block` dodaje do pierwszego nagłówka tekstową
tabliczkę dokumentu: osoby odpowiedzialne, kategorię, tytuł, URL, rewizję,
datę wydania, serię, typ, narzędzie i arkusz. Pole `url` jest kodowane także
lokalnie w QR (SVG w HTML i pakiet `qrcode` w TeX). Gdy URL nie jest podany,
generator pokazuje w tej komórce informację `brak URL`.

### Efekty i kryteria

- `educational_requirements` — wymagania `WE`;
- `learning_effects` — efekty `EN` lub `EK`;
- `assessment_criteria` — mierzalne kryteria `KW`;
- `educational_requirements.*.learning_tree` — połączenia renderowane na
  marginesach.

Każdy wpis `learning_tree.ogolne[]` lub `learning_tree.zawodowe[]` ma stabilne
`tree_id`, odwołanie `effect_ref`, etykietę `display` oraz co najmniej jedno
powiązane `KW`.

### Sekcje i kroki

Pole `sections[]` porządkuje treść. Kroki `sections[].steps[]` mają:

- `id` i `title`;
- `tree_refs` wskazujące drzewka z marginesów;
- opcjonalne odwołania do wymagań, efektów, kryteriów, równań i figur.

Layouty 5a/5b obsługują również:

- `model_block.steps` — kroki modelowania;
- `code_block.blocks[].web_steps` — interaktywne kroki HTML;
- `hardware_procedure[]` — tabela `step/action/condition` w TeX i HTML.

`code_block.blocks[]` jest rzeczywistym podziałem na bloki: każdy wpis jest
renderowany jako osobna, opisana ramka w sekcji implementacyjnej, a jego
`web_steps` zasila niezależną checklistę HTML. Kolejność głównych bloków
strony jest opisana przez `block_map` wybranego szablonu.

### Zadania

`tasks` jest słownikiem zadań, a `tasks_order` określa ich kolejność. Każde
zadanie posiada polecenie `prompt_tex`, kryterium zaliczenia i odwołania do
modelu edukacyjnego.

## Zalecany README karty

README konkretnej karty powinien zawierać:

1. nazwę, numer i miejsce w serii;
2. cel oraz rezultat obserwowalny;
3. mapowanie do źródeł i efektów nauczania;
4. listę kroków/zadań;
5. polecenia generowania i testowania;
6. warunek `PASS`;
7. informację, które pliki są źródłowe, a które generowane.

Gotowy przykład znajduje się w `examples/card/README.md`.

## Generowanie

Z katalogu repozytorium `card-layouts`:

```bash
python3 tools/render_card.py /sciezka/do/mojej-karty
```

Generator najpierw sprawdza spójność identyfikatorów WE/EN/EK/KW, kroków,
zadań i odwołań, a dopiero potem zapisuje oba formaty.