Manuály a dokumentace zařízení

Tady je archiv všech manuálů, schémat zapojení, modbus map a datasheetů zařízení v domě. PDF (nebo HTML snapshot) je canonical zdroj; vedle něj žije strojově extrahovaný markdown pro vyhledávání a snadnou referenci.

Struktura

docs/manualy/
  index_generated.md          # přehledová tabulka — generuje se skriptem
  <vendor>_<model>/
    meta.yaml                 # metadata zařízení + array dokumentů
    manual.pdf                # nebo manual.html (canonical)
    manual.md                 # text-extrakt
    manual_images/            # vyrenderované schémata (jen u PDF)
    wiring.pdf                # další dokumenty (volitelné)
    modbus.pdf
    datasheet.html
    ...

K jednomu zařízení (jednomu adresáři) může patřit víc dokumentů různých typů: manual, wiring (schéma zapojení), modbus (modbus mapa), datasheet, other.

Jak přidat nový dokument

V Claude Code:

/manual <url-nebo-cesta> [tag1] [tag2] ...

<url-nebo-cesta> — URL na digital-born PDF, URL na HTML stránku s manuálem, nebo lokální cesta k PDF/HTML (typicky ~/Downloads/...).
Cokoli za zdrojem = volitelné tagy.

Příklady:

/manual https://www.bosch-home.com/.../HMH636GB1_manual.pdf trouba kuchyne
/manual ~/Downloads/aqara_fp2.pdf zigbee senzor
/manual https://www.aqara.com/eu/product/fp2 zigbee

Command sám:

Stáhne / zkopíruje zdroj.
Detekuje typ dokumentu (manuál vs schéma vs modbus vs ...) z heuristiky URL/filename — pokud nejasné, zeptá se.
Extrahuje markdown (přes pymupdf4llm u PDF, readability-lxml + markdownify u HTML).
U PDF s vektorovými schématy vyrenderuje stránky-schémata jako PNG do <type>_images/.
Detekuje jazyk(y); pokud PDF obsahuje sekce v CS i EN, vznikne <type>.cs.md + <type>.en.md, jinak jeden <type>.md.
Zařadí do docs/manualy/<vendor>_<model>/.
Aktualizuje index_generated.md.
Nabídne přilinkování ze stránky daného zařízení v docs/ (sekce ## Manuály).
Vypíše summary. Necommitne — to potvrdíš sám.

Omezení v1

Skenované PDFs (bez text vrstvy): uloží se jen PDF + meta s is_scanned: true. MD extrakci přes OCR neděláme; spusť ocrmypdf ručně a re-run.
JS-heavy SPA stránky: extrakce vrátí jasný fail s instrukcí "ulož v prohlížeči jako PDF (Cmd+P → Save as PDF) a spusť znovu s lokální cestou".
Schémata z PDF: stránky s vysokým podílem grafiky se renderují jako PNG; pro detail pracuj s PDF (zoom).
Tabulky: best-effort přes pymupdf4llm. U složitých layoutů (sloučené buňky) může výstup zkreslit — PDF zůstává zdrojem pravdy.
Obrázky v HTML: zatím se nestahují, MD odkazuje na původní URL. Pokud zdroj zmizí, obrázky zmizí taky.

Manuální regenerace indexu

Po změně meta.yaml (např. ručním přidáním tagů, linked_from) přegeneruj přehledovou tabulku:

uv run scripts/doc_gen_manualy.py

Co když chci verzovat?

Nová verze stejného typu manuálu (např. updated FW guide): spusť /manual <new-url> znovu na stejné zařízení a zvol přejmenovat — script vytvoří <type>_<label>.md (např. manual_2025.pdf + manual_2025.md). Předchozí verze zůstane.