feat: add repeated dual-QR A4 resource headers

docs/CARD.md

@@ -23,11 +23,25 @@ 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`.
+Opcjonalny obiekt `title_block` włącza tabliczkę zasobu o wysokości dokładnie
+3 cm na każdej stronie, także pierwszej, bibliografii, słownika i stronach
+kontynuacji. Tabliczka zastępuje dużą tabelę metadanych strony tytułowej.
+Zawiera kategorię, tytuł, metadane karty, numer strony oraz widoczny,
+kanoniczny URL. Ten sam URL jest kodowany lokalnie w QR: jako SVG w HTML i
+przez pakiet `qrcode` w TeX. Opcjonalny `repository_url` dodaje drugi QR do
+repozytorium. Przy dwóch kodach komórki mają po 27 mm: Gitea znajduje się po
+lewej, a wyrenderowany zasób po prawej. Jedna zamknięta ramka biegnie dokładnie
+między marginesami strony. W HTML widok ekranowy ma rozmiar A4 (210 × 297 mm) i
+nagłówek na każdej logicznej karcie, a wydruk używa `@page { size: A4; }` oraz
+pól marginesu, dlatego nagłówek powtarza się również po automatycznym podziale
+długiej sekcji.
+
+Pola `height_cm: 3`, `repeat_on_every_page: true` i
+`replace_front_matter: true` dokumentują ten kontrakt. `show_qr: true` wymaga
+kanonicznego adresu HTTP(S) w `url` albo pary `url_host_uuid`/`doc_uuid`, z
+której powstaje `https://<url_host_uuid>/<doc_uuid>`.
+`show_repository_qr: true` wymaga `repository_url`. Adres podglądu `localhost`
+nie powinien być publikowany na karcie.
 
 ### Efekty i kryteria
 
@@ -49,6 +63,42 @@ Pole `sections[]` porządkuje treść. Kroki `sections[].steps[]` mają:
 - `tree_refs` wskazujące drzewka z marginesów;
 - opcjonalne odwołania do wymagań, efektów, kryteriów, równań i figur.
 
+### Referencje zewnętrzne bez kopiowania treści
+
+Karta może ładować kanoniczne rejestry współdzielonych strategii, kart, treści
+i wzorów. Lokalny plik JSON służy do walidacji oraz deterministycznego buildu:
+
+```json
+{
+  "reference_registries": [
+    {
+      "uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003",
+      "source": "../../../tools/debugging-strategies/json/reference_registry.json"
+    }
+  ]
+}
+```
+
+Krok przechowuje tylko rodzaj, UUID rejestru i UUID wpisu:
+
+```json
+{
+  "references": [
+    {
+      "kind": "strategy",
+      "registry_uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003",
+      "uuid": "1ecfc474-4fbd-5a56-8ef1-80ae557761d0"
+    }
+  ]
+}
+```
+
+Generator pobiera z rejestru etykietę, tytuł, ścieżkę i publiczny adres.
+Strategię pokazuje jako kod `Mxx`, kartę jako jej nazwę, a treść lub wzór jako
+kanoniczną etykietę. W TeX/PDF i HTML etykieta jest hiperłączem. Nazw ani URL-i
+nie kopiujemy do `card_source.json`; brak rejestru, UUID albo lokalnego pliku
+przerywa generowanie.
+
 Layouty 5a/5b obsługują również:
 
 - `model_block.steps` — kroki modelowania;
@@ -60,12 +110,57 @@ 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.
 
+### Zrzuty ekranu i inne assety sekcji
+
+Zrzutów nie wpisujemy jako ręcznego `\\includegraphics` w wygenerowanym TeX.
+Sekcja może deklarować listę `assets`, a generator umieszcza każdy element w
+TeX/PDF i HTML, kopiuje plik do `figures/` strony oraz dodaje link do pełnego
+rozmiaru:
+
+```json
+{
+  "title": "Pomiar w debuggerze",
+  "content_tex": "Zatrzymaj program przed pierwszą alokacją.",
+  "assets": [
+    {
+      "path": "assets/task04-first-allocation-annotated.png",
+      "caption": "Task04 przed pierwszym przydziałem pamięci.",
+      "label": "fig:task04-first-allocation",
+      "alt": "Termdebug: kod C, listing, rejestry i allocbuf",
+      "kind": "screenshot",
+      "width": 1.0
+    }
+  ]
+}
+```
+
+- `path` jest liczony względem katalogu `doc/` karty; standardem jest
+  `doc/assets/`;
+- obsługiwane są PNG, JPG/JPEG i PDF;
+- `width` jest ułamkiem szerokości kolumny od `0.1` do `1.0`;
+- `label` jest stabilnym identyfikatorem używanym przez `figure_refs`;
+- `full_size_link` domyślnie włącza otwieranie zrzutu HTML w pełnym rozmiarze.
+
 ### 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.
 
+Rozbudowane zadanie przechowuje przebieg dydaktyczny w uporządkowanym
+`tasks.<id>.flow[]`:
+
+- `kind: "block"` grupuje jedną część objaśnienia lub demonstracji;
+- opcjonalne `block.steps[]` zachowują kolejność czynności wewnątrz bloku;
+- `kind: "exercise"` jest samodzielną pracą ucznia należącą bezpośrednio do
+  zadania i podaje `prompt_tex`, `evidence_tex` oraz `criterion`;
+- `exercise.based_on[]` może wskazać wcześniejsze bloki lub ich kroki.
+
+Bloki i ćwiczenia są rodzeństwem w jednym `flow`, dzięki czemu renderer nie
+gubi kolejności nauczania. `steps` nie może występować bezpośrednio w obiekcie
+zadania. Dawne `prompt_tex` i `criterion` pozostają wymagane dla zgodności ze
+starszymi konsumentami; gdy istnieje `flow`, renderer używa jego treści.
+
 ## Zalecany README karty
 
 README konkretnej karty powinien zawierać:
@@ -89,4 +184,4 @@ 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.
+zadań, rejestrów UUID i odwołań, a dopiero potem zapisuje oba formaty.