Merge pull request #87 from ARUP-CAS/version/v2.2.0

Vydání verze 2.2.0: sjednocené popisky filtrů, váha prvku u komponent, ověření přihlášení před stahováním, zapamatované filtry s resetem a aktualizované README.

.editorconfig

@@ -0,0 +1,24 @@
+# Jednotné kódování a konce řádků napříč editory.
+# Vzor: aiscr-management (quality_baseline/foundations/editorconfig.ini)
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Zdrojáky bez BOM – pyqgis4-checker na BOM spadne (viz AGENTS.md)
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+# Heslář zapisuje plugin s BOM a CRLF (kvůli Excelu) – needitovat ručně
+[amcr_viewer/codelists/heslar.csv]
+charset = utf-8-bom
+end_of_line = crlf
+insert_final_newline = unset
+trim_trailing_whitespace = unset

.gitattributes

@@ -0,0 +1,10 @@
+# Textové soubory v repozitáři s LF; vzor: aiscr-management
+# (quality_baseline/foundations/gitattributes.fragment)
+* text=auto eol=lf
+
+# Heslář generuje plugin (BOM + CRLF kvůli Excelu) – ukládat bajt po bajtu
+amcr_viewer/codelists/heslar.csv -text
+
+# Binární soubory
+*.png binary
+*.zip binary

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# Dependabot hlídá jen GitHub Actions: akce jsou ve workflow připnuté
+# na SHA s komentářem verze a Dependabot umí obojí povýšit naráz.
+# Plugin nemá pip/npm manifest a verze nástrojů (ruff, flake8 …) se
+# v workflow drží napevno vědomě – viz AGENTS.md.
+# Vzor: aiscr-management/.github/dependabot.yml
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    target-branch: main
+    commit-message:
+      prefix: "ci"

.github/pull_request_template.md

@@ -25,7 +25,7 @@ Nepotřebné body můžeš smazat. Komentáře (<!-- ... -->) se v PR nezobrazuj
 
 ## Kontrolní seznam
 - [ ] Změny jsou v souladu se stylem projektu (viz `AGENTS.md`)
-- [ ] Při změně funkcí povýšena verze v `amcr_viewer/metadata.txt` a doplněn `changelog`
+- [ ] Při změně funkcí povýšena verze v `amcr_viewer/metadata.txt` (+ `changelog`) a v `CITATION.cff` (`version`, `date-released`)
 - [ ] Otestováno v QGIS (min. podporovaná verze 3.44)
 - [ ] PR míří do správné cílové větve
 - [ ] Větev odpovídá konvenci (`feat/ fix/ docs/ chore/<téma>`, AI `agents/<jméno>/<téma>`)

.github/workflows/api_monitor.yml

@@ -0,0 +1,160 @@
+name: API Monitor
+
+# Denní kontrola kontraktu s API digiarchivu a AMČR OAI (change
+# add-daily-api-monitor). Na rozdíl od code_quality.yml neslouží jako
+# branka pro PR – běží z plánu (schedule) a ručního spuštění:
+#
+#  * kontrakt (tests/api_contract.py) – posílá stejné dotazy jako plugin
+#    a kontroluje tvar odpovědí, které plugin čte; obyčejný requests,
+#    bez QGIS
+#  * plugin proti živému API (tests/api_plugin_live.py) – volá přímo
+#    funkce pluginu (fetch_set, load_amcr_data) v qgis/qgis:ltr
+#  * report (tests/api_monitor_report.py) – z výsledků obou jobů
+#    vytvoří/aktualizuje/zavře sledovací issue s popiskem api-monitor;
+#    běží jen na výchozí větvi
+#
+# Výsledky: OK / DRIFT (změna, kterou plugin snáší) / FAIL (plugin se
+# rozbije) / UNAVAILABLE (API nedosažitelné – není to chyba kontraktu,
+# issue se neotvírá). Stav najdete v přehledu běhu (results-*.json
+# artefakty + tabulka v summary).
+#
+# Schválně není pull_request: PR nesmí červenat kvůli výpadku
+# digiarchivu. Na jiné větvi než main jde workflow spustit ručně
+# (workflow_dispatch), report se ale otvírá jen na výchozí větvi.
+
+on:
+  schedule:
+    # 17 5 * * * = 07:17 SELČ, mimo celou hodinu, před začátkem pracovního
+    # dne. GitHub ale spouští schedule jen na výchozí větvi.
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+
+# Souběžné běhy téhož refu se nepřebíjejí – denní běh a ruční dispatch
+# se nemají vzájemně rušit (cancel-in-progress: false).
+concurrency:
+  group: api-monitor-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  # Verze se drží napevno, aby se výsledek nezměnil sám od sebe.
+  REQUESTS: requests==2.34.2
+
+jobs:
+  # --------------------------------------------------------------------
+  # 1. Kontrakt – stejné dotazy jako plugin, kontrola tvaru odpovědí
+  # --------------------------------------------------------------------
+  api_contract:
+    name: API kontrakt
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Install requests
+        run: pip install "$REQUESTS"
+
+      # Výstup je i tak hlavně v results-api_contract.json artefaktu,
+      # ne v logu.
+      - name: API contract test
+        run: python3 tests/api_contract.py
+
+      # Výsledky se nahrávají i po selhání testu – report je potřebuje
+      # v každém případě (i mrtvý job je informace).
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: results-api_contract
+          path: results-api_contract.json
+          if-no-files-found: warn
+
+  # --------------------------------------------------------------------
+  # 2. Plugin proti živému API – vlastní funkce pluginu v QGISu
+  # --------------------------------------------------------------------
+  plugin_live:
+    name: Plugin proti živému API
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # Repozitář přimontovaný jen pro čtení, výsledky jdou do zapisova-
+      # telného adresáře mimo něj. Stejný styl jako smoke test v
+      # code_quality.yml, jen s přidaným AMCR_RESULTS_DIR.
+      - name: Live plugin test
+        run: |
+          mkdir -p results && chmod 777 results
+          docker run --rm -v "$PWD:/work:ro" -v "$PWD/results:/tmp/results" \
+            -w /work --user "$(id -u):$(id -g)" -e HOME=/tmp \
+            -e AMCR_RESULTS_DIR=/tmp/results \
+            "qgis/qgis:ltr" python3 tests/api_plugin_live.py
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: results-plugin_live
+          path: results/results-plugin_live.json
+          if-no-files-found: warn
+
+  # --------------------------------------------------------------------
+  # 3. Report – sledovací issue s popiskem api-monitor
+  # --------------------------------------------------------------------
+  report:
+    name: Report issue
+    needs: [api_contract, plugin_live]
+    # Běží vždy, i když některý test job padl – report potřebuje výsledky
+    # obou (chybějící soubor se počítá jako FAIL). Chybí-li výsledky,
+    # zůstává workflow celé červené.
+    if: always() && github.ref_name == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+
+    # issues: write jen tady; zbytek workflow má nahoře contents: read
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # merge-multiple: oba artefakty (results-api_contract,
+      # results-plugin_live) se složí do jednoho adresáře results/,
+      # kam je čeká api_monitor_report.py.
+      - name: Download results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: results
+          pattern: results-*
+          merge-multiple: true
+
+      # Nasazenou verzi digiarchivu (kontrola deployed-version) si skript
+      # přečte sám z results-api_contract.json. Report vždy vrací 0,
+      # chyby v něm nemají přebít výsledek testů.
+      - name: Report to issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          python3 tests/api_monitor_report.py results \
+            "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+      # Sledovací issue musí být vidět i v přehledu běhu; FAIL/DRIFT
+      # testů ale workflow přežije (exit code 0 reportu). Skutečné
+      # selhání testů se ale do závěru běhu musí vrátit – jinak by běh
+      # s FAIL/DRIFT vypadal zeleně.
+      - name: Propagate test results
+        if: needs.api_contract.result == 'failure' || needs.plugin_live.result == 'failure'
+        run: |
+          echo "::error::testy API monitoru selhaly (FAIL/DRIFT), viz issue a artefakty"
+          exit 1

.github/workflows/code_quality.yml

@@ -28,6 +28,7 @@ env:
   DETECT_SECRETS: detect-secrets==1.5.0
   FLAKE8: flake8==7.3.0
   RUFF: ruff==0.16.5
+  OPENSPEC: 1.14.0
 
 jobs:
   # --------------------------------------------------------------------
@@ -39,7 +40,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -74,10 +75,10 @@ jobs:
           print('detect-secrets: bez nálezů')
           "
 
-      # Na plugins.qgis.org je informativní, tady blokuje – konfigurace
+      # Na plugins.qgis.org je informativní, tady blokuje. Bez konfigurace,
-      # v amcr_viewer/.flake8 je stejná pro obě místa.
+      # tj. se stejnými výchozími pravidly jako scanner.
       - name: Flake8
-        run: flake8 --config amcr_viewer/.flake8 amcr_viewer/
+        run: flake8 --isolated amcr_viewer/
 
       # Nad rámec plugins.qgis.org; konfigurace v pyproject.toml
       - name: Ruff
@@ -92,7 +93,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # Pozor: skript končí kódem 0 i když něco najde, výsledek je jen
       # v logu. Prázdný log (samotná hlavička) znamená čisto.
@@ -110,6 +111,24 @@ jobs:
             exit 1
           fi
 
+  # --------------------------------------------------------------------
+  # OpenSpec – artefakty změn v openspec/ musí projít validací
+  # --------------------------------------------------------------------
+  openspec:
+    name: OpenSpec
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # Verze CLI napevno – formát validace se mezi verzemi mění.
+      # Node je v ubuntu-latest předinstalovaný.
+      - name: openspec validate
+        run: |
+          npx --yes @fission-ai/openspec@${{ env.OPENSPEC }} \
+            validate --all --strict --no-interactive
+
   # --------------------------------------------------------------------
   # 3. Načtení pluginu ve skutečném QGIS, v obou podporovaných verzích
   # --------------------------------------------------------------------
@@ -125,7 +144,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Smoke test
         run: |
@@ -142,19 +161,32 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Zip plugin
         run: zip -r amcr_viewer.zip amcr_viewer -x "*.git*"
 
-      # Kontrola obsahu ZIPu. Config soubory pro scanner musí být uvnitř
+      # Verze v CITATION.cff se povyšuje ručně spolu s metadata.txt a snadno
-      # vedle metadata.txt, jinak je plugins.qgis.org nenajde – a některé
+      # se zapomene – tag by pak nesl v citaci jinou verzi než plugin
-      # nástroje skryté soubory tiše vynechávají.
+      - name: Verify CITATION.cff version
+        run: |
+          plugin=$(sed -n 's/^version=//p' amcr_viewer/metadata.txt \
+                   | tr -d "\r\"' ")
+          citace=$(sed -n 's/^version://p' CITATION.cff \
+                   | tr -d "\r\"' ")
+          echo "metadata.txt: '$plugin', CITATION.cff: '$citace'"
+          if [ -z "$plugin" ] || [ "$plugin" != "$citace" ]; then
+            echo "::error file=CITATION.cff::verze '$citace' neodpovídá" \
+                 "metadata.txt ('$plugin')"
+            exit 1
+          fi
+
+      # Kontrola obsahu ZIPu: povinné soubory jsou uvnitř, git soubory ne.
       - name: Verify archive contents
         run: |
           unzip -l amcr_viewer.zip
           for soubor in amcr_viewer/metadata.txt amcr_viewer/__init__.py \
-                        amcr_viewer/.flake8; do
+                        amcr_viewer/LICENSE; do
             unzip -l amcr_viewer.zip | grep -qF " $soubor" \
               || { echo "::error::v ZIPu chybí $soubor"; exit 1; }
           done

.github/workflows/release_plugin.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
       # 1. Stáhne kód z tagu, který běh spustil
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # 2. Vytvoří ZIP (předpokládá, že kód je ve složce 'amcr_viewer')
       - name: Zip Plugin
@@ -34,7 +34,7 @@ jobs:
       # 3. Založí koncept releasu i s přílohou
       #    Tagy s pomlčkou (v2.0.0-alpha.1) se označí jako pre-release.
       - name: Create draft release with asset
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           files: amcr_viewer.zip
           draft: true

.github/workflows/release_pr_checks.yml

@@ -0,0 +1,41 @@
+name: Release PR Checks
+
+# Hlídá bump verze a changelog v okamžiku, kdy se release větev
+# version/vX.Y.Z slévá do main – tady poprvé jde skutečně o to, co se
+# vydá, a zapomenutý bump by se jinak dostal rovnou k tagu a releasu.
+#
+# Kontroly viz tests/check_version_bump.py: verze v metadata.txt musí jít
+# nahoru, první položka changelogu musí patřit nové verzi, CITATION.cff
+# musí mít stejnou verzi (a posunuté date-released) a název větve musí
+# odpovídat verzi, kterou nese.
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  version-bump:
+    name: Kontrola verze a changelogu
+    runs-on: ubuntu-latest
+    if: startsWith(github.head_ref, 'version/')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Verze a changelog
+        run: |
+          python3 tests/check_version_bump.py \
+            "${{ github.event.pull_request.base.sha }}" \
+            "${{ github.head_ref }}"

AGENTS.md

@@ -17,9 +17,36 @@ Zdroj dat: https://digiarchiv.aiscr.cz/ · Nápověda: https://amcr-help.aiscr.c
 Tento repozitář je jedním ze **sourozeneckých repozitářů** ekosystému AIS CR.
 Centrální governance a AI konfigurace spravuje hub **`aiscr-management`**; konvence
 v tomto souboru jsou s tímto vzorem sladěné a zjednodušené pro potřeby jednoho
-QGIS pluginu. Těžkou mašinerii hubu (složka `.agents/`, OpenSpec, sync skripty,
+QGIS pluginu. Z hubu přebírá **OpenSpec** ve stupni `change-tracked` (viz
-multi-assistant generování) tento repozitář **záměrně nepřebírá**. Při širších
+níže). Ostatní mašinerii hubu (složka `.agents/`, sync skripty, vlastní
-otázkách governance má přednost vzor z `aiscr-management`.
+schémata OpenSpec, multi-assistant generování) tento repozitář **záměrně
+nepřebírá**. Při širších otázkách governance má přednost vzor
+z `aiscr-management`.
+
+## OpenSpec
+
+Repozitář používá OpenSpec ve stupni **`change-tracked`**: plánovací
+artefakty změn (`proposal.md`, delta spec, `design.md`, `tasks.md`) žijí
+v `openspec/changes/<slug>/`, trvalé specifikace v `openspec/specs/` se
+**neudržují**. Stupeň a kontext pro agenty jsou v `openspec/config.yaml`;
+změna stupně se dělá vědomě společně s hubem, ne v rámci rozpracované práce.
+
+- **Kdy založit změnu:** práce, která mění chování (co uživatel vidí,
+  atributy vrstev, kontrakt s API digiarchivu, uložená nastavení), zasahuje
+  víc repozitářů nebo mění pravidla / AI konfiguraci / CI.
+- **Kdy ne:** překlepy a formátování, bump závislostí či pinů nástrojů bez
+  změny chování, přegenerování odvozených souborů.
+- **Postup:** `openspec new change <slug>` → artefakty → `openspec validate
+  <slug> --strict` → implementace (až na výslovný pokyn) → po merge
+  `openspec archive <slug> --skip-specs` (archiv
+  `openspec/changes/archive/RRRR-MM-DD-<slug>/`).
+- Artefakty změny jdou **ve stejném PR** jako implementace; v popisu PR
+  odkaž na adresář změny.
+- Používá se vestavěné schéma `spec-driven`; vlastní schémata hubu se sem
+  nepřenášejí. CLI: `npx @fission-ai/openspec@1.14.0` (nebo lokálně
+  nainstalované `openspec`); bez CLI lze artefakty psát i ručně.
+- Asistentské povrchy (`.claude/`, `.github/prompts/` …) doručuje sync
+  z hubu; v tomto repozitáři se ručně nezakládají ani necommitují.
 
 ## Struktura repozitáře
 
@@ -33,7 +60,8 @@ amcr_viewer/            # vlastní kód pluginu (toto se balí do releasu)
   metadata.txt          # metadata pluginu + verze + changelog
   i18n/                 # překlady (.ts)
   *.png                 # ikony
-.github/workflows/      # CI – release pluginu
+.github/workflows/      # CI – kontroly kvality a release pluginu
+openspec/               # OpenSpec – konfigurace a plánovací artefakty změn
 README.md               # uživatelská dokumentace (anglicky)
 ```
 
@@ -140,6 +168,9 @@ flatpak run --command=sh org.qgis.qgis -c \
 - Verze pluginu žije v **`amcr_viewer/metadata.txt`** (`version=`).
 - **Při každé změně chování / nové funkci** povyš verzi a doplň položku do
   `changelog=` v `metadata.txt` (formát `vX.Y.Z (RRRR-MM-DD)` + odrážky).
+- Současně povyš i **`CITATION.cff`** v kořeni repozitáře: `version:` na
+  stejnou verzi jako v `metadata.txt` a `date-released:` na datum releasu.
+  Oba soubory musí mít stejnou verzi, než se založí tag.
 - Datum v changelogu ber z **deterministického zdroje**, ne z paměti, např.
   `python -c "import datetime; print(datetime.date.today().isoformat())"`.
 - Release se spouští **pushnutím tagu `vX.Y.Z`**, ne publikací releasu
@@ -160,6 +191,7 @@ flatpak run --command=sh org.qgis.qgis -c \
 - PR musí mířit do správné `version/v2.x.y` větve.
 - Před požádáním o review projdi kontrolní seznam v šabloně (zejména bump verze
   v `metadata.txt`, pokud měníš chování).
+- Mění-li PR chování, obsahuje i odpovídající změnu v `openspec/changes/`.
 - V popisu PR uveď **podíl AI** (např. „text navržen AI, ručně zkontrolováno")
   a odkaz na související issue, pokud existuje.
 
@@ -189,7 +221,7 @@ tohle:
 | **Lint a bezpečnost** | `check_sources.py`, bandit, detect-secrets, flake8, ruff |
 | **Kompatibilita s Qt6** | `pyqgis4-checker` v dockeru |
 | **Smoke test** | `smoke_test.py` v `qgis/qgis:ltr` i `qgis/qgis:stable` |
-| **Balíček pluginu** | sestaví ZIP, ověří obsah, přiloží jako artefakt |
+| **Balíček pluginu** | ověří shodu verze v `CITATION.cff` a `metadata.txt`, sestaví ZIP, ověří obsah, přiloží jako artefakt |
 
 Smoke test běží v obou podporovaných řadách: `ltr` je QGIS 3.44 na Qt5,
 `stable` je QGIS 4.x na Qt6.
@@ -205,7 +237,7 @@ pip install bandit detect-secrets flake8 ruff
 python3 tests/check_sources.py
 bandit -r amcr_viewer/
 detect-secrets scan --all-files amcr_viewer/
-flake8 --config amcr_viewer/.flake8 amcr_viewer/
+flake8 --isolated amcr_viewer/
 ruff check .
 
 # smoke test v obou verzích QGIS (docker, bez instalace čehokoli)
@@ -222,11 +254,69 @@ Na co si dát pozor:
   v logu. Workflow proto kontroluje, že log obsahuje jen hlavičku.
 - **`detect-secrets` bez `--all-files` prohledá jen soubory sledované
   gitem** a o nesledovaném souboru mlčí. Vypadá to jako čistý výsledek.
-- **Konfigurace lintů je rozdělená schválně.** `amcr_viewer/.flake8` leží
+- **Flake8 běží bez konfigurace** (`--isolated`), tedy se stejnými
-  vedle `metadata.txt`, protože scanner na plugins.qgis.org hledá config
+  výchozími pravidly jako scanner na plugins.qgis.org. Do balíčku nepatří
-  soubory jen v kořeni balíčku uvnitř ZIPu; díky tomu platí stejná pravidla
+  `.flake8`, `.bandit` ani `.secrets.baseline`: scanner by plugin označil
-  v CI, lokálně i při uploadu. Konfigurace ruffu je naopak v kořenovém
+  jako „Validated (configured)“ a nález je lepší opravit v kódu.
-  `pyproject.toml` – ruff se do balíčku pluginu nedistribuuje.
+  Konfigurace ruffu je v kořenovém `pyproject.toml` – ruff se do balíčku
+  pluginu nedistribuuje.
   Viz https://plugins.qgis.org/docs/security-scanning/config-files
 - **Verze nástrojů jsou v workflow napevno.** Výchozí sada pravidel ruffu se
   mezi verzemi mění, takže bez pinu by CI začalo padat samo od sebe.
+
+### Denní kontrola API
+
+Workflow `.github/workflows/api_monitor.yml` jednou denně (05:17 UTC)
+a na ruční spuštění ověřuje, že API digiarchivu a AMČR OAI pořád vrací
+to, co plugin čte. Změny typu #67 se tak odhalí do druhého dne, ne až
+od uživatelů. Na pull requesty se schválně nespouští – PR nesmí
+zčervenat kvůli výpadku digiarchivu.
+
+| job | co dělá |
+|---|---|
+| **API kontrakt** | `tests/api_contract.py` – stejné dotazy jako plugin, kontrola klíčů, typů a tvarů odpovědí; jen `requests` |
+| **Plugin proti živému API** | `tests/api_plugin_live.py` v `qgis/qgis:ltr` – volá přímo `fetch_set` a `load_amcr_data` |
+| **Report** | jedno sledovací issue se štítkem `api-monitor` |
+
+Každá kontrola skončí jedním ze stavů:
+
+- **OK** – odpověď odpovídá očekávání,
+- **DRIFT** – API se změnilo, ale plugin to ustojí,
+- **FAIL** – změna, na které se plugin rozbije,
+- **UNAVAILABLE** – server nedostupný ani po opakování; výpadek, ne
+  změna API. Po prvním neúspěchu se daný server už nezkouší, takže
+  běh při výpadku skončí za pár sekund.
+
+Běh s FAIL nebo DRIFT na `main` založí issue `api-monitor`, nebo
+doplní komentář do otevřeného, pokud se změnil seznam selhaných
+kontrol. Další čistý běh issue zavře; samotné UNAVAILABLE ho
+nemění. Job, který nevyrobí výsledky, se počítá jako FAIL.
+
+Očekávání jsou zapsaná přímo v `tests/api_contract.py`. Jejich změna
+je běžná změna kódu přes PR – automaticky obnovovaný baseline by
+změnu API, kterou chceme vidět, tiše přijal.
+
+Lokálně:
+
+```sh
+uv run -q --no-project --with requests==2.34.2 \
+    python tests/api_contract.py
+
+docker run --rm -v "$PWD:/work:ro" -w /work \
+    --user "$(id -u):$(id -g)" -e HOME=/tmp \
+    -e AMCR_RESULTS_DIR=/tmp/results \
+    qgis/qgis:ltr python3 tests/api_plugin_live.py
+```
+
+Na co si dát pozor:
+
+- **`schedule` běží jen na výchozí větvi.** Verzní větev se dá ověřit
+  ručně: `gh workflow run api_monitor.yml --ref <větev>`; issue se
+  přitom nezakládá ani nezavírá.
+- **GitHub plánovaný workflow vypne po 60 dnech bez aktivity**
+  v repozitáři. Stačí jakýkoli push do `main`, i od dependabota.
+- **Testy běží anonymně**, pokrývají tedy jen záznamy s přístupností A.
+  Z přihlášení se ověřuje jen chybová cesta.
+- **Simulace výpadku:** `AMCR_DA_URL=http://127.0.0.1:9` a
+  `AMCR_OAI_URL=http://127.0.0.1:9/oai` – všechno má skončit
+  UNAVAILABLE s kódem 0.

CITATION.cff

@@ -25,5 +25,5 @@ abstract: >-
   the Digital archive of the Archaeological Map of the
   Czech Republic (https://digiarchiv.aiscr.cz/).
 license: GPL-3.0
-version: '2.1.2'
+version: '2.2.0'
-date-released: '2026-09-01'
+date-released: '2026-10-02'

README.md

@@ -106,12 +106,16 @@ to see.
 * They are then saved encrypted in the **QGIS Authentication Manager** (DPAPI
   on Windows, Keychain on macOS, encrypted SQLite on Linux). QGIS will ask for
   its master password.
-* Stored credentials are reused across QGIS sessions. If the session cookie
+* Stored credentials are reused across QGIS sessions. The plugin checks
-  expires mid-download, the plugin re-authenticates automatically and repeats
+  the login state before every download (via the `islogged` endpoint)
-  the request.
+  and, when the session cookie has expired, re-authenticates
+  automatically. If re-authentication is not possible, a warning in the
+  message bar says the download runs anonymously (access level A only);
+  a failed check never blocks the download.
 * Reopening the login dialog lets you change the e-mail (leave the password
   blank to keep the stored one) or remove the credentials entirely
-  (*Odebrat uložené přihlašovací údaje*).
+  (*Odebrat uložené přihlašovací údaje*). Removing them also logs you out
+  of the Digital Archive, so the next download runs anonymously.
 
 ### 3.3 The filter dialog
 
@@ -119,6 +123,30 @@ Filters of different categories are combined with **AND**; multiple values
 inside one filter are combined with **OR**. A filter left empty means "no
 restriction". Click *Vybrat…* to open a searchable, checkable list.
 
+#### Remembered filters, reset, clearing one filter
+
+* The dialog **remembers the filters you confirmed with OK** — separately
+  for Fieldwork events, Sites and Individual finds — for the rest of the
+  QGIS session. Reopening the dialog restores all selections, checkboxes
+  and date ranges, so refining a query ("same area, one more period") does
+  not mean re-entering everything. Nothing is written to disk: after a QGIS
+  restart (or a plugin reload) every dialog starts from its defaults again.
+  *Cancel* leaves the remembered state untouched.
+* When the reopened dialog contains filters that differ from the defaults,
+  a green notice at the top says so and counts them, so a forgotten filter
+  further down the scrollable form is not missed.
+* **Obnovit výchozí** (left of OK/Cancel) resets the whole form to its
+  defaults: the map-extent restriction checked, *PIAN – přesnost* back to
+  its three pre-selected levels (where the data type has it), everything
+  else empty. The reset applies to the form only — the remembered state
+  changes when you confirm with OK.
+* Each picker has a small **✕** (*Vymazat výběr*; *Vrátit výchozí výběr*
+  for *PIAN – přesnost*) that returns just that
+  filter to its default — empty for almost all filters, the three
+  pre-selected levels for *PIAN – přesnost*; it is disabled while the
+  filter already is at its default. To drop the *PIAN – přesnost*
+  restriction entirely, uncheck all levels in its *Vybrat…* dialog.
+
 #### Availability per entity
 
 | Filter (Czech UI label) | Events | Sites | Ind. finds | API parameter |
@@ -138,11 +166,11 @@ restriction". Click *Vybrat…* to open a searchable, checkable list.
 | Lokalita – typ | — | ✓ | — | `f_typ_lokality` |
 | Lokalita – druh | — | ✓ | — | `f_druh_lokality` |
 | Lokalita – jistota určení | — | ✓ | — | `f_jistota` |
-| Lokalita - stav dochování | — | ✓ | — | `f_lokalita_zachovalost` |
+| Lokalita – stav dochování | — | ✓ | — | `f_lokalita_zachovalost` |
 | Období | ✓ | ✓ | ✓ | `f_obdobi` |
 | Kategorie nálezu | — | — | ✓ | `f_kategorie` |
 | Druh nálezu | — | — | ✓ | `f_druh_nalezu` |
-| Specifikace nálezu | — | — | ✓ | `f_specifikace` |
+| Materiál | — | — | ✓ | `f_specifikace` |
 | Okolnosti nálezu | — | — | ✓ | `f_nalezove_okolnosti` |
 | Nálezce | — | — | ✓ | `f_nalezce` |
 | Datum nálezu | — | — | ✓ | `samostatny_nalez_datum_nalezu` |
@@ -163,7 +191,10 @@ filter in place, otherwise you will hit the record cap (see 4.5).
 > *odchylka desítky metrů* and *odchylka stovky metrů* checked, so an
 > otherwise untouched dialog already sends `f_pian_presnost`. Records
 > localised only to a cadastral territory are excluded until you open the
-> picker and add that level yourself.
+> picker and add that level yourself. *Obnovit výchozí* brings the three
+> levels back; the picker's ✕ returns them too (it restores the filter's
+> default). To have no accuracy restriction at all, uncheck all levels
+> in the picker's *Vybrat…* dialog.
 
 #### Date ranges
 
@@ -181,7 +212,10 @@ from a genuinely empty result.
 The controlled vocabularies behind the pickers are cached in
 `amcr_viewer/codelists/heslar.csv` and ship with the plugin. Click
 **Aktualizovat hesláře 🔄** to rebuild the file from the live APIs; it runs as
-a background QGIS task with a progress bar and takes a few minutes.
+a background QGIS task with a progress bar and takes a few minutes. A
+codelist that fails to download or comes back empty keeps its previous values
+instead of being wiped; when the update finishes, a warning lists the affected
+codelists.
 
 Most codelists come from the AMČR **OAI-PMH** endpoint. Two are built from
 Digiarchiv **search facets** instead, because they are lists of people rather
@@ -195,7 +229,8 @@ activity area of each component into the output layer.
 
 > ⚠ With components loaded, spatial features are **duplicated** — one feature
 > per component. Areas and feature counts computed on such a layer are
-> misleading.
+> misleading. Weight such computations (e.g. a heatmap) by the `prvek_vaha`
+> field (see 3.4): the weights of one documentation unit sum to 1.
 
 Note that *Období* and *Areál* also act as component filters even when the
 box is unchecked: a documentation unit whose components match nothing is
@@ -294,6 +329,7 @@ order *common → entity-specific → `pristupnost` → component fields*.
 | `komponenta` | Komponenta | Component identifier. |
 | `komponenta_areal` | Areál | Activity area \[settlement / burial area / field / …\]. |
 | `komponenta_obdobi` | Období | Period \[Neolithic / High Middle Ages–Modern Period / …\]. |
+| `prvek_vaha` | Váha prvku | Feature weight: 1/*n*, where *n* is the number of features created from the same documentation unit after the period/area filters, so the weights of one documentation unit sum to 1. |
 
 ### 3.5 When a query returns nothing
 
@@ -333,12 +369,13 @@ amcr_viewer/            the plugin package (this is what gets zipped)
   codelists/heslar.csv  cached controlled vocabularies
   i18n/                 Qt translation files
   *.png                 toolbar and menu icons
-  resources.py          generated by pyrcc, currently unused
   metadata.txt          plugin metadata and changelog
-  .flake8               lint config, read by the plugins.qgis.org scanner
 tests/
   check_sources.py      source hygiene checks (no QGIS needed)
   smoke_test.py         loads the plugin in a real, headless QGIS
+  check_version_bump.py release-PR guard: version bump, changelog entry and
+                        matching versions in metadata.txt, CITATION.cff
+                        and the branch name
 .github/workflows/      CI (code quality, release packaging)
 pyproject.toml          ruff configuration
 AGENTS.md               contributor and AI-agent guidelines
@@ -349,6 +386,8 @@ AGENTS.md               contributor and AI-agent guidelines
 | Purpose | Endpoint | Notes |
 | --- | --- | --- |
 | Login | `POST https://digiarchiv.aiscr.cz/api/user/login` | Returns a session cookie. Errors arrive with HTTP 200 and an `error` key. |
+| Logout | `GET https://digiarchiv.aiscr.cz/api/user/logout` | Called when the stored credentials are removed. |
+| Login state | `GET https://digiarchiv.aiscr.cz/api/user/islogged` | `{"remaining": <s>}` when logged in, `{"error":"nologged"}` otherwise; checked before each download. |
 | Search | `GET https://digiarchiv.aiscr.cz/api/search/query` | `entity=akce\|lokalita\|samostatny_nalez\|pian`, `mapa=true`, paginated. |
 | Translations | `GET https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json` | Code → Czech label; cached in memory for the session. |
 | Codelists | `GET https://api.aiscr.cz/2.2/oai` | OAI-PMH `ListRecords`, with resumption tokens. |
@@ -396,6 +435,7 @@ not:
 | --- | --- |
 | **Lint a bezpečnost** | `tests/check_sources.py`, bandit, detect-secrets, flake8, ruff |
 | **Kompatibilita s Qt6** | `pyqgis4-checker` in dry-run mode |
+| **OpenSpec** | validates change artefacts in `openspec/changes/` |
 | **Smoke test** | loads the plugin in headless QGIS — both `ltr` (Qt 5) and `stable` (Qt 6) |
 | **Balíček pluginu** | builds `amcr_viewer.zip`, asserts its contents, uploads it as an artifact |
 
@@ -404,7 +444,7 @@ Reproducing them locally:
 ```bash
 python3 tests/check_sources.py
 ruff check .
-flake8 --config amcr_viewer/.flake8 amcr_viewer/
+flake8 --isolated amcr_viewer/
 bandit -r amcr_viewer/
 docker run --rm -v "$PWD:/work:ro" -w /work --user "$(id -u):$(id -g)" \
   -e HOME=/tmp qgis/qgis:stable python3 tests/smoke_test.py

amcr_viewer/.flake8

@@ -1,12 +0,0 @@
-# Konfigurace flake8 pro plugin AMČR Viewer.
-#
-# Soubor leží vedle metadata.txt schválně: scanner na plugins.qgis.org
-# hledá .flake8 pouze v kořeni balíčku uvnitř ZIPu, takže stejná pravidla
-# platí v CI, lokálně i při uploadu.
-# https://plugins.qgis.org/docs/security-scanning/config-files
-[flake8]
-# resources.py je vygenerovaný výstup pyrcc ("All changes made in this
-# file will be lost"), není nikde importovaný a zdrojový .qrc v repu není.
-# Ručně se neformátuje.
-per-file-ignores =
-    *resources.py: E302,E305,E501

amcr_viewer/amcr_codelists.py

@@ -104,6 +104,21 @@ def load_all_data():
     return categorized_data
 
 
+def _facet_name(item):
+    """
+    Returns the value of one facet item from the Digiarchive API.
+
+    Digiarchive v4.1.0 (Solr 10, json.nl=arrarr) returns facet items as
+    ["value", count] pairs; older versions returned {"name": "value", ...}
+    objects. Both shapes are accepted so the plugin works against either.
+    """
+    if isinstance(item, dict):
+        return item.get("name")
+    if isinstance(item, (list, tuple)) and item:
+        return item[0]
+    return None
+
+
 def fetch_set(base_url, internal_name, api_set, task=None):
     dataset = []
     params_amcr = {
@@ -206,7 +221,9 @@ def fetch_set(base_url, internal_name, api_set, task=None):
 
                 for r in records:
 
-                    nazev = r["name"]
+                    nazev = _facet_name(r)
+                    if not nazev:
+                        continue
 
                     dataset.append({
                             'Název': nazev,
@@ -217,17 +234,48 @@ def fetch_set(base_url, internal_name, api_set, task=None):
                 break
 
         except Exception as e:
+            # A partial set (e.g. pagination interrupted halfway) would
+            # silently drop codes – report the whole set as failed instead
+            # and let the caller keep the previous values
             QgsMessageLog.logMessage(
                 f"Chyba u setu {api_set}: {e}",
                 "AMČR", Qgis.MessageLevel.Warning)
-            break
+            return []
 
     return dataset
 
 
-def download_heslare(task=None):
+def _read_existing_rows():
-    """Fetches the codelists from the AMČR API and saves it to a CSV file."""
+    """
+    Returns the rows of the current heslar.csv grouped by category, so a set
+    that fails to download can keep its previous values.
+    """
+    rows = {}
+    if not os.path.exists(OUTPUT_FILE):
+        return rows
+    try:
+        with open(OUTPUT_FILE, encoding='utf-8-sig', newline='') as f:
+            for row in csv.DictReader(f, delimiter=';'):
+                cat = (row.get('Kategorie') or '').strip()
+                if cat:
+                    rows.setdefault(cat, []).append(row)
+    except Exception as e:
+        QgsMessageLog.logMessage(
+            f"Nelze načíst stávající hesláře: {e}",
+            "AMČR", Qgis.MessageLevel.Warning)
+    return rows
+
+
+def download_heslare(task=None, failed=None):
+    """
+    Fetches the codelists from the AMČR API and saves it to a CSV file.
+
+    A set that fails or comes back empty keeps its rows from the current
+    heslar.csv instead of being wiped; its name is appended to ``failed``
+    (if given) so the caller can warn the user.
+    """
     ensure_codelists_dir()
+    existing = _read_existing_rows()
     all_data = []
     total_sets = len(slovnicek)
 # index, (interni, api_nazev)
@@ -251,6 +299,18 @@ def download_heslare(task=None):
         if data is None:
             return False  # Cancelled mid-download
 
+        if not data:
+            # Never replace a working codelist with nothing – an API change
+            # would otherwise silently empty the filter in the dialog
+            old = existing.get(interni, [])
+            QgsMessageLog.logMessage(
+                f"Heslář '{interni}' se nepodařilo stáhnout, "
+                f"ponechávám předchozí hodnoty ({len(old)} položek).",
+                "AMČR", Qgis.MessageLevel.Warning)
+            if failed is not None:
+                failed.append(interni)
+            data = old
+
         all_data.extend(data)
 
         # Report progress (0-100)
@@ -261,7 +321,8 @@ def download_heslare(task=None):
     # Save to CSV
     with open(OUTPUT_FILE, 'w', newline='', encoding='utf-8-sig') as f:
         fieldnames = ['Název', 'Kód', 'Kategorie']
-        writer = csv.DictWriter(f, fieldnames=fieldnames, delimiter=';')
+        writer = csv.DictWriter(f, fieldnames=fieldnames, delimiter=';',
+                                extrasaction='ignore')
         writer.writeheader()
         writer.writerows(all_data)
 

amcr_viewer/amcr_dialog.py

@@ -7,7 +7,7 @@ from qgis.core import (
     QgsTask,
 )
 from qgis.gui import QgsDateEdit
-from qgis.PyQt.QtCore import QSettings, Qt
+from qgis.PyQt.QtCore import QDate, QSettings, Qt
 from qgis.PyQt.QtWidgets import (
     QCheckBox,
     QDialog,
@@ -24,6 +24,7 @@ from qgis.PyQt.QtWidgets import (
     QMessageBox,
     QPushButton,
     QScrollArea,
+    QToolButton,
     QVBoxLayout,
     QWidget,
 )
@@ -63,6 +64,19 @@ DATE_OPEN_TO = "9999-12-31"
 # Shown by a date picker that is left empty
 DATE_NULL_TEXT = "neomezeno"
 
+# The non-empty defaults of the form: PIAN – přesnost pre-selects the
+# three levels better than a cadastral territory, and the map-extent
+# restriction is on. Everything else starts empty.
+DEFAULT_CODES = {
+    "pian_presnost": ["HES-000861", "HES-000862", "HES-000863"],
+}
+DEFAULT_CHECKS = {"bbox": True}
+
+# The last OK-confirmed form state per data type, alive for the QGIS
+# run only: re-importing the plugin (a restart, Plugin Reloader) drops
+# the dict, which is exactly the required lifetime.
+_REMEMBERED_STATE = {}
+
 
 # Keep Python references to running tasks. QgsTaskManager only holds the
 # C++ object; without a Python-side reference the wrapper can be garbage
@@ -75,12 +89,15 @@ class UpdateCodelistsTask(QgsTask):
         super().__init__(description, QgsTask.Flag.CanCancel)
         self.success = False
         self.exception = None
+        # Codelists that failed to download and kept their previous values
+        self.failed_sets = []
 
     def run(self):
         """Runs in a background thread."""
         try:
             # Call the download function with the task reference
-            self.success = download_heslare(task=self)
+            self.success = download_heslare(
+                task=self, failed=self.failed_sets)
             return self.success
         except Exception as e:
             self.exception = e
@@ -91,6 +108,13 @@ class UpdateCodelistsTask(QgsTask):
         if result:
             # Safely update the global variables in the main thread
             refresh_globals()
+            if self.failed_sets:
+                QgsMessageLog.logMessage(
+                    "Hesláře AMČR aktualizovány částečně, beze změny "
+                    f"zůstaly: {', '.join(self.failed_sets)}",
+                    "AMČR", Qgis.MessageLevel.Warning
+                )
+            else:
                 QgsMessageLog.logMessage(
                     "Hesláře AMČR byly úspěšně aktualizovány.",
                     "AMČR", Qgis.MessageLevel.Info
@@ -224,15 +248,29 @@ class AmcrFilterDialog(QDialog):
             'nalezce': [],
         }
 
+        # Pickers registered by setup_picker():
+        # cache_key -> (data_source, display_field, clear button)
+        self.pickers = {}
+
         # Date range pickers, filled by setup_date_range():
         # (API field, label for messages, 'from' widget, 'to' widget)
         self.date_ranges = []
 
         layout = QVBoxLayout()
 
+        # Notice shown when a remembered state was restored
+        self.lbl_notice = QLabel()
+        self.lbl_notice.setWordWrap(True)
+        self.lbl_notice.setStyleSheet(
+            "color: #1b5e20; background-color: #e8f5e9; "
+            "border: 1px solid #a5d6a7; border-radius: 4px; padding: 6px;"
+        )
+        self.lbl_notice.setVisible(False)
+        layout.addWidget(self.lbl_notice)
+
         # Filter by current map canvas extent
         self.chk_bbox = QCheckBox("Omezit vyhledávání rozsahem okna")
-        self.chk_bbox.setChecked(True)
+        self.chk_bbox.setChecked(DEFAULT_CHECKS["bbox"])
         layout.addWidget(self.chk_bbox)
 
         # Positive/negative evidence – valid for Akce
@@ -333,7 +371,7 @@ class AmcrFilterDialog(QDialog):
             layout.addWidget(self.picker_jistota)
 
             self.picker_lokalita_zachovalost = self.setup_picker(
-                "Lokalita - stav dochování",
+                "Lokalita – stav dochování",
                 'lokalita_zachovalost',
                 LOKALITA_ZACHOVALOST
             )
@@ -360,7 +398,7 @@ class AmcrFilterDialog(QDialog):
             layout.addWidget(self.picker_druh_nalezu)
 
             self.picker_specifikace = self.setup_picker(
-                "Specifikace nálezu",
+                "Materiál",
                 'specifikace',
                 SPECIFIKACE
             )
@@ -447,6 +485,15 @@ class AmcrFilterDialog(QDialog):
             self.btn_update,
             QDialogButtonBox.ButtonRole.ActionRole
         )
+
+        # Reset the form to its defaults; the remembered state changes
+        # only on OK. ResetRole puts the button left of the OK/Cancel pair.
+        self.btn_reset = buttons.addButton(
+            QDialogButtonBox.StandardButton.RestoreDefaults
+        )
+        self.btn_reset.setText("Obnovit výchozí")
+        self.btn_reset.clicked.connect(self.action_reset)
+
         buttons.addButton(QDialogButtonBox.StandardButton.Ok)
         buttons.addButton(QDialogButtonBox.StandardButton.Cancel)
 
@@ -456,6 +503,126 @@ class AmcrFilterDialog(QDialog):
 
         self.setLayout(outer)
 
+        # Restore the remembered state (defaults when there is none)
+        restored = _REMEMBERED_STATE.get(self.typ_dat)
+        if restored is None:
+            self._apply_state(self._default_state())
+        else:
+            self._apply_state(restored)
+            diff = self._diff_from_default(restored)
+            if diff:
+                self.lbl_notice.setText(
+                    "Načteny filtry z minulého hledání "
+                    f"(aktivní filtry: {diff})."
+                )
+                self.lbl_notice.setVisible(True)
+
+    def _default_state(self):
+        """A full snapshot of the default form state for this typ_dat."""
+        # Every checkbox defaults to off, except the ones DEFAULT_CHECKS
+        # turns on (the map-extent restriction)
+        checks = {name: False for name, _ in self._check_widgets()}
+        for name, value in DEFAULT_CHECKS.items():
+            if name in checks:
+                checks[name] = value
+
+        return {
+            "codes": {
+                key: (list(DEFAULT_CODES[key])
+                      if key in DEFAULT_CODES else [])
+                for key in self.pickers
+            },
+            "checks": checks,
+            "dates": {
+                api_field: (None, None)
+                for api_field, _, _, _ in self.date_ranges
+            },
+        }
+
+    def _check_widgets(self):
+        """(name, checkbox) of every checkbox, in a stable order."""
+        widgets = []
+        for name, attr in (
+            ("bbox", "chk_bbox"),
+            ("posevidence", "chk_posevidence"),
+            ("proj_akce", "chk_proj_akce"),
+            ("komponenty", "chk_komponenty"),
+        ):
+            if hasattr(self, attr):
+                widgets.append((name, getattr(self, attr)))
+        return widgets
+
+    def _snapshot(self):
+        """The whole form state as plain Python (codes/checks/dates)."""
+        return {
+            "codes": {key: list(codes)
+                      for key, codes in self.selection_cache.items()},
+            "checks": {name: chk.isChecked()
+                       for name, chk in self._check_widgets()},
+            "dates": {
+                api_field: (
+                    None if date_from.isNull()
+                    else date_from.date().toString("yyyy-MM-dd"),
+                    None if date_to.isNull()
+                    else date_to.date().toString("yyyy-MM-dd"),
+                )
+                for api_field, _, date_from, date_to in self.date_ranges
+            },
+        }
+
+    def _apply_state(self, state):
+        """Applies a snapshot; codes unknown to the codelists are
+        dropped and the picker texts are rebuilt from them."""
+        for key, codes in state.get("codes", {}).items():
+            if key in self.pickers:
+                self._set_picker(key, codes)
+
+        for name, chk in self._check_widgets():
+            chk.setChecked(state.get("checks", {}).get(name, False))
+
+        stored = state.get("dates", {})
+        for api_field, _, date_from, date_to in self.date_ranges:
+            iso_from, iso_to = stored.get(api_field, (None, None))
+            # clear(), not setEmpty(): an empty picker must stay
+            # isNull() so no filter is sent (see _date_edit)
+            if iso_from:
+                date_from.setDate(QDate.fromString(
+                    iso_from, "yyyy-MM-dd"))
+            else:
+                date_from.clear()
+            if iso_to:
+                date_to.setDate(QDate.fromString(
+                    iso_to, "yyyy-MM-dd"))
+            else:
+                date_to.clear()
+
+    def _diff_from_default(self, state):
+        """Number of form items in the snapshot that differ from
+        _default_state(): one per picker, checkbox and date row."""
+        diff = 0
+        defaults = self._default_state()
+
+        for key, codes in state.get("codes", {}).items():
+            if (key in defaults["codes"]
+                    and codes != defaults["codes"][key]):
+                diff += 1
+
+        for name, value in state.get("checks", {}).items():
+            if defaults["checks"].get(name) != value:
+                diff += 1
+
+        for api_field, bounds in state.get("dates", {}).items():
+            if defaults["dates"].get(api_field) != bounds:
+                diff += 1
+
+        return diff
+
+    def action_reset(self):
+        """Resets the form to its defaults (the remembered state is
+        changed only by OK, so Cancel after reset reverts it)."""
+        self._apply_state(self._default_state())
+        self.lbl_notice.setVisible(False)
+
     def setup_picker(self, label_text, cache_key, data_source, extra_btn=None):
         """
         Creates a reusable UI component consisting of a label, a read-only
@@ -475,6 +642,20 @@ class AmcrFilterDialog(QDialog):
         btn = QPushButton("Vybrat...")
         btn.setFixedWidth(80)
 
+        # Returns this one filter to its default; enabled only while
+        # the selection differs from it (open_dialog re-evaluates it
+        # through _set_picker)
+        clear_btn = QToolButton()
+        clear_btn.setText("✕")
+        default_codes = DEFAULT_CODES.get(cache_key, [])
+        clear_btn.setToolTip(
+            "Vrátit výchozí výběr" if default_codes else "Vymazat výběr"
+        )
+        clear_btn.setEnabled(False)
+        clear_btn.clicked.connect(
+            lambda: self._set_picker(cache_key, list(default_codes))
+        )
+
         # Nested handler: opens the selection dialog and saves the result
         def open_dialog():
             dlg = FilterableSelectionDialog(
@@ -484,39 +665,57 @@ class AmcrFilterDialog(QDialog):
                 self
             )
             if dlg.exec() == QDialog.DialogCode.Accepted:
-                codes, labels = dlg.get_selected_codes()
+                codes, _labels = dlg.get_selected_codes()
-                # Update the local cache with selected IDs
+                self._set_picker(cache_key, codes)
-                self.selection_cache[cache_key] = codes
-                # Update the display field with the selected item names
-                if labels:
-                    display_field.setText(", ".join(labels))
-                else:
-                    display_field.clear()
-
-        # Special case: pre-select default PIAN accuracy levels
-        if cache_key == 'pian_presnost':
-            display_field.setText(
-                "odchylka jednotky metrů, odchylka desítky metrů, "
-                "odchylka stovky metrů"
-            )
-            self.selection_cache[cache_key] = [
-                'HES-000861',
-                'HES-000862',
-                'HES-000863',
-            ]
 
         btn.clicked.connect(open_dialog)
 
         row_layout.addWidget(display_field)
         row_layout.addWidget(btn)
+        row_layout.addWidget(clear_btn)
 
         # Optionally append an extra button (e.g. a refresh button)
         if extra_btn:
             row_layout.addWidget(extra_btn)
 
         row_widget.setLayout(row_layout)
+
+        # One place knows the widgets behind every picker, so the cache
+        # and the display text can never drift apart
+        self.pickers[cache_key] = (data_source, display_field, clear_btn)
+
         return row_widget
 
+    def _set_picker(self, cache_key, codes):
+        """
+        Sets one picker: stores the codes, rebuilds the display text from
+        the current codelist (a label renamed by Aktualizovat hesláře
+        shows its new name, an unknown code is dropped) and enables the
+        clear button only while the selection differs from the picker's
+        default.
+        """
+        data_source, display_field, clear_btn = self.pickers[cache_key]
+
+        # Keep the order the user picked, drop codes the current
+        # codelist no longer knows
+        code_to_label = {v: k for k, v in data_source.items()}
+        valid_codes = [code for code in codes if code in code_to_label]
+
+        # Rebuild the labels the same way the selection dialog shows
+        # them: sorted by name
+        labels = sorted(code_to_label[code] for code in valid_codes)
+
+        self.selection_cache[cache_key] = valid_codes
+        if labels:
+            display_field.setText(", ".join(labels))
+        else:
+            display_field.clear()
+        # Order-insensitive: a reordered default is still the default
+        default = DEFAULT_CODES.get(cache_key, [])
+        clear_btn.setEnabled(
+            sorted(valid_codes) != sorted(default)
+        )
+
     def setup_date_range(self, title, rows):
         """
         Creates a compact date range block: one row per API date field,
@@ -603,6 +802,9 @@ class AmcrFilterDialog(QDialog):
             )
             return
 
+        # Remember the confirmed state only after the date check passed
+        _REMEMBERED_STATE[self.typ_dat] = self._snapshot()
+
         super().accept()
 
     def action_update_heslare(self):
@@ -629,6 +831,16 @@ class AmcrFilterDialog(QDialog):
 
         def on_completed():
             _cleanup()
+            if task.failed_sets:
+                QMessageBox.warning(
+                    parent_win,
+                    "Hesláře aktualizovány částečně",
+                    "Některé hesláře se nepodařilo stáhnout, "
+                    "ponechány byly jejich předchozí hodnoty:\n"
+                    + "\n".join(f"• {name}" for name in task.failed_sets)
+                    + "\n\nPodrobnosti jsou v panelu Zprávy, záložka AMČR."
+                )
+                return
             QMessageBox.information(
                 parent_win,
                 "Hotovo",
@@ -1013,6 +1225,10 @@ class LoginDialog(QDialog):
         self.accept()
 
     def _forget_credentials(self):
+        # Lazy import to avoid an import cycle
+        # (amcr_tools imports LoginDialog lazily as well)
+        from . import amcr_tools
+
         settings = QSettings()
         existing_id = settings.value(self.SETTINGS_KEY, "")
         if existing_id:
@@ -1020,11 +1236,17 @@ class LoginDialog(QDialog):
                 existing_id
             )
             settings.remove(self.SETTINGS_KEY)
-        QMessageBox.information(
+
-            self,
+        # Without credentials the session in memory would otherwise stay
-            "Hotovo",
+        # logged in until QGIS is restarted
-            "Uložené přihlašovací údaje byly odebrány."
+        if amcr_tools.logout_from_api():
-        )
+            zprava = ("Uložené přihlašovací údaje byly odebrány "
+                      "a uživatel byl odhlášen.")
+        else:
+            zprava = ("Uložené přihlašovací údaje byly odebrány. Server "
+                      "se nepodařilo kontaktovat, další stahování ale "
+                      "proběhne anonymně.")
+        QMessageBox.information(self, "Hotovo", zprava)
         self.reject()
 
     # ------------------------------------------------------------------

amcr_viewer/amcr_tools.py

@@ -157,6 +157,125 @@ def _get_session() -> requests.Session | None:
     return AMCR_SESSION
 
 
+def logout_from_api() -> bool:
+    """
+    Logs the current session out on the server (GET /api/user/logout)
+    and drops it from memory, so the next download runs anonymously
+    (or logs in again only if credentials are stored).
+    The local session is dropped even when the server cannot be
+    reached. Returns True when the server confirmed the logout or there
+    was no session at all.
+    """
+    global AMCR_SESSION
+    session = AMCR_SESSION
+    AMCR_SESSION = None
+    if session is None:
+        return True
+
+    url = "https://digiarchiv.aiscr.cz/api/user/logout"
+    try:
+        response = session.get(url, timeout=10)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        _log(f"Odhlášení na serveru se nezdařilo: {e} – session "
+             "zahozena jen lokálně.", Qgis.MessageLevel.Warning)
+        return False
+    _log("Uživatel odhlášen.")
+    return True
+
+
+def _check_islogged(session) -> bool | None:
+    """
+    Asks the server whether the session is logged in
+    (GET /api/user/islogged; the check does not extend the session).
+    Returns True when logged in, False when the server reports
+    'nologged', or None when the check itself failed (network error,
+    invalid JSON) or the response has an unknown shape.
+    """
+    url = "https://digiarchiv.aiscr.cz/api/user/islogged"
+    try:
+        body = session.get(url, timeout=10).json()
+    except (requests.exceptions.RequestException, ValueError) as e:
+        _log(f"Stav přihlášení se nepodařilo ověřit: {e}",
+             Qgis.MessageLevel.Warning)
+        return None
+
+    if not isinstance(body, dict):
+        _log("Neznámý formát odpovědi islogged – pokračuji dál.",
+             Qgis.MessageLevel.Warning)
+        return None
+    if "remaining" in body:
+        # Only the remaining seconds are logged, never a user profile
+        _log(f"Session je přihlášená (zbývá {body['remaining']} s).")
+        return True
+    if body.get("error"):
+        _log(f"Server session neuznává ({body['error']}).",
+             Qgis.MessageLevel.Warning)
+        return False
+    _log("Neznámý formát odpovědi islogged – pokračuji dál.",
+         Qgis.MessageLevel.Warning)
+    return None
+
+
+def _ensure_logged_in() -> str:
+    """
+    Verifies before a download that the user is logged in, whenever
+    a session exists or credentials are stored; renews the session
+    once when it has expired. Returns one of:
+
+    * "anonymous" – no session and no stored credentials (nothing
+      to check, no request is sent)
+    * "logged_in" – the current session is valid
+    * "relogged" – the session had expired and was renewed
+    * "fallback" – a login was expected but could not be established;
+      the download will run anonymously
+    * "unknown" – the check itself failed; the download proceeds
+      with the current session
+    """
+    global AMCR_SESSION
+
+    session = _get_session()
+    if session is None:
+        # _get_session() has already tried the stored credentials;
+        # their presence therefore means the login failed
+        from .amcr_dialog import LoginDialog
+        username, password = LoginDialog.get_credentials()
+        if username and password:
+            _log("Přihlášení se nezdařilo – stahuji anonymně.",
+                 Qgis.MessageLevel.Warning)
+            return "fallback"
+        return "anonymous"
+
+    stav = _check_islogged(session)
+    if stav is None:
+        return "unknown"
+    if stav:
+        return "logged_in"
+
+    # The server no longer accepts the session – drop it and try
+    # one re-login with the stored credentials
+    AMCR_SESSION = None
+    from .amcr_dialog import LoginDialog
+    username, password = LoginDialog.get_credentials()
+    if not (username and password):
+        _log("Session vypršela a přihlašovací údaje nejsou uloženy "
+             "– stahuji anonymně.", Qgis.MessageLevel.Warning)
+        return "fallback"
+
+    session = login_to_api(username, password)
+    if session is None:
+        return "fallback"
+
+    stav = _check_islogged(session)
+    if stav is None:
+        return "unknown"
+    if stav:
+        return "relogged"
+    _log("Nová session nebyla serverem uznána – stahuji anonymně.",
+         Qgis.MessageLevel.Warning)
+    return "fallback"
+
+
 def _api_get_json(url, params, timeout=30) -> dict:
     """
     Performs a GET request and returns the parsed JSON body.
@@ -168,7 +287,13 @@ def _api_get_json(url, params, timeout=30) -> dict:
 
     def _is_auth_error(resp: requests.Response, body) -> bool:
         """The API returns auth errors with status 200 –
-        the body must be checked."""
+        the body must be checked.
+
+        Fallback only: the current server signals an expired session
+        by silently answering as anonymous (HTTP 200, no 'error'), so
+        this check never triggers on expiry today – the login state is
+        verified upfront by _ensure_logged_in() instead. Kept for the
+        day the API starts returning 401 or an explicit error text."""
         if resp.status_code == 401:
             return True
         if not isinstance(body, dict):
@@ -261,6 +386,49 @@ def tr_code(code):
     return TRANSLATIONS.get(code, code)
 
 
+def _component_entries(dj_meta, komps, passes):
+    """
+    Builds the feature metadata entries of the "Načíst komponenty"
+    mode: one entry per component that passes the given predicate,
+    with the weight 1/n where n is the number of passing components,
+    so the weights of one documentation unit sum to 1 even when a
+    period/area filter removes some of them. A documentation unit
+    without components gets a single entry with empty component
+    fields and weight 1.
+
+    dj_meta: metadata shared by the documentation unit (spread into
+    every entry); komps: its component documents; passes: predicate
+    komp -> bool deciding whether a component becomes a feature.
+    """
+    if not komps:
+        # DJ without components – still one feature, weight 1
+        return [{
+            **dj_meta,
+            'komponenta_id': "",
+            'komponenta_areal': "",
+            'komponenta_obdobi': "",
+            'vaha': 1,
+        }]
+
+    prochazejici = [komp for komp in komps if passes(komp)]
+    vaha = 1 / len(prochazejici) if prochazejici else 1
+
+    return [
+        {
+            **dj_meta,
+            'komponenta_id': komp.get('ident_cely', ""),
+            'komponenta_areal': (
+                komp.get('komponenta_areal') or {}
+            ).get('value', ""),
+            'komponenta_obdobi': (
+                komp.get('komponenta_obdobi') or {}
+            ).get('value', ""),
+            'vaha': vaha,
+        }
+        for komp in prochazejici
+    ]
+
+
 def komp_projde_filtrem(komp, filter_areal, filter_datace, filters):
     # 'or {}' – the key may be present with a None value
     areal_id = (komp.get('komponenta_areal') or {}).get('id', "")
@@ -292,6 +460,27 @@ def load_amcr_data(canvas, bb, filters=None,
         return
     _LOADING = True
 
+    # Login state is verified before the first query: an expired
+    # session would otherwise silently degrade the result to
+    # access level A without any error
+    try:
+        login_stav = _ensure_logged_in()
+    except Exception as e:
+        # The check must never block the download nor leave _LOADING
+        # stuck – an unexpected error means "proceed as today"
+        QgsMessageLog.logMessage(
+            f"Ověření stavu přihlášení selhalo: {e}",
+            "AMČR", Qgis.MessageLevel.Warning
+        )
+        login_stav = "unknown"
+    if login_stav == "fallback":
+        iface.messageBar().pushMessage(
+            "AMCR",
+            "Přihlášení se nepodařilo obnovit – stahování proběhne "
+            "anonymně a bude obsahovat jen záznamy s přístupností A.",
+            level=Qgis.MessageLevel.Warning
+        )
+
     load_translations()
 
     # --- 1. COORDINATE TRANSFORMATION ---
@@ -680,28 +869,16 @@ def load_amcr_data(canvas, bb, filters=None,
                                 # One feature per component –
                                 # all data on a single row, no relations needed
                                 if komps:
-                                    for komp in komps:
+                                    # The weight is 1/n of the components
-                                        if not komp_projde_filtrem(
+                                    # that pass the period/area filter,
-                                            komp, filter_areal,
+                                    # so one DJ sums to 1
+                                    for komp_meta in _component_entries(
+                                        dj_meta, komps,
+                                        lambda k: komp_projde_filtrem(
+                                            k, filter_areal,
                                             filter_datace, filters
+                                        )
                                     ):
-                                            continue
-
-                                        komp_meta = {
-                                            **dj_meta,
-                                            'komponenta_id': komp.get(
-                                                'ident_cely',
-                                                ""
-                                                ),
-                                            'komponenta_areal': (
-                                                komp.get('komponenta_areal')
-                                                or {}
-                                            ).get('value', ""),
-                                            'komponenta_obdobi': (
-                                                komp.get('komponenta_obdobi')
-                                                or {}
-                                            ).get('value', ""),
-                                        }
                                         pian_lookup[dj_pian_value].append(
                                             komp_meta)
                                         target_pian_ids_count += 1
@@ -711,14 +888,11 @@ def load_amcr_data(canvas, bb, filters=None,
                                     if filter_areal or filter_datace:
                                         continue
 
-                                    empty_meta = {
+                                    for komp_meta in _component_entries(
-                                        **dj_meta,
+                                        dj_meta, [], lambda k: True
-                                        'komponenta_id': "",
+                                    ):
-                                        'komponenta_areal': "",
-                                        'komponenta_obdobi': "",
-                                    }
                                         pian_lookup[dj_pian_value].append(
-                                        empty_meta)
+                                            komp_meta)
                                         target_pian_ids_count += 1
                             else:
                                 target_pian_ids_count += 1
@@ -1056,6 +1230,7 @@ def load_amcr_data(canvas, bb, filters=None,
             "poznamka": "Poznámka/bližší popis",
             "pred_org": "Předáno organizaci",
             "evidencni": "Evidenční číslo",
+            "prvek_vaha": "Váha prvku",
         }
 
         if komponenty == "true":
@@ -1063,6 +1238,7 @@ def load_amcr_data(canvas, bb, filters=None,
                 QgsField("komponenta", QMetaType.Type.QString),
                 QgsField("komponenta_areal", QMetaType.Type.QString),
                 QgsField("komponenta_obdobi", QMetaType.Type.QString),
+                QgsField("prvek_vaha", QMetaType.Type.Double),
             ]
 
         for vl in layers:
@@ -1209,6 +1385,7 @@ def load_amcr_data(canvas, bb, filters=None,
                                         meta.get('komponenta_id', ""),
                                         meta.get('komponenta_areal', ""),
                                         meta.get('komponenta_obdobi', ""),
+                                        meta.get('vaha', 1),
                                     ])
 
                                 feat.setAttributes(atributy)

amcr_viewer/metadata.txt

@@ -8,7 +8,7 @@ name=AMČR Viewer
 qgisMinimumVersion=3.44.0
 qgisMaximumVersion=4.99.0
 description=Viewing and downloading the AMČR data.
-version=2.1.2
+version=2.2.0
 author=David Spáčil
 email=spacil@arub.cz
 
@@ -23,7 +23,18 @@ repository=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer
 hasProcessingProvider=no
 # Uncomment the following line and add your changelog:
 changelog=
-  Plný seznam změn v češtině je dostupný zde: https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases/tag/v2.1.1
+  Plný seznam změn v češtině je dostupný zde: https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases/tag/v2.2.0
+  v2.2.0 (2026-10-02)
+   * Tables for Akce and Lokality contain a field with feature weight, when Komponenty rendering is enabled; the weights of one documentation unit sum to 1 also with period/area filters
+   * The login state is verified before each download via /api/user/islogged; an expired session is renewed automatically
+   * When a logged-in download falls back to anonymous access, a message bar warning says so (only access level A data)
+   * Removing the stored credentials also logs the user out of the Digital Archive
+   * The filter dialog remembers the last confirmed filters per data type for the QGIS run and restores them on reopening
+  v2.1.4 (2026-10-01)
+   * Removed unused generated resources.py and the bundled flake8 config, so the plugin passes the plugins.qgis.org scan without custom configuration
+  v2.1.3 (2026-10-01)
+   * Fixed empty person codelists (excavation leaders, finders) after updating codelists against Digiarchive v4.1.0
+   * A codelist that fails to download keeps its previous values and the user is warned
   v2.1.2 (2026-09-01)
    * Qt6 compatibility
    * Code clean-up

amcr_viewer/resources.py

@@ -1,128 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# Resource object code
-#
-# Created by: The Resource Compiler for PyQt5 (Qt v5.15.13)
-#
-# WARNING! All changes made in this file will be lost!
-
-from qgis.PyQt import QtCore
-
-qt_resource_data = b"\
-\x00\x00\x04\x0a\
-\x89\
-\x50\x4e\x47\x0d\x0a\x1a\x0a\x00\x00\x00\x0d\x49\x48\x44\x52\x00\
-\x00\x00\x17\x00\x00\x00\x18\x08\x06\x00\x00\x00\x11\x7c\x66\x75\
-\x00\x00\x00\x01\x73\x52\x47\x42\x00\xae\xce\x1c\xe9\x00\x00\x00\
-\x06\x62\x4b\x47\x44\x00\xff\x00\xff\x00\xff\xa0\xbd\xa7\x93\x00\
-\x00\x00\x09\x70\x48\x59\x73\x00\x00\x0b\x13\x00\x00\x0b\x13\x01\
-\x00\x9a\x9c\x18\x00\x00\x00\x07\x74\x49\x4d\x45\x07\xd9\x02\x15\
-\x16\x11\x2c\x9d\x48\x83\xbb\x00\x00\x03\x8a\x49\x44\x41\x54\x48\
-\xc7\xad\x95\x4b\x68\x5c\x55\x18\xc7\x7f\xe7\xdc\x7b\x67\xe6\xce\
-\x4c\x66\x26\x49\xd3\x24\x26\xa6\xc6\xf8\x40\x21\xa5\x04\xb3\x28\
-\xda\x98\x20\xa5\x0b\xad\x55\xa8\x2b\xc5\x50\x1f\xa0\x6e\x34\x2b\
-\x45\x30\x14\x02\xba\x52\x69\x15\x17\x66\x63\x45\x97\x95\xa0\xad\
-\x0b\xfb\xc0\x06\x25\xb6\x71\x61\x12\x41\x50\xdb\x2a\x21\xd1\xe2\
-\x24\xf3\x9e\xc9\xcc\xbd\xe7\x1c\x17\x35\x43\x1e\x33\x21\xb6\xfd\
-\x56\x87\xf3\x9d\xfb\xfb\x1e\xf7\xff\x9d\x23\x8c\x31\x43\x95\xf4\
-\x85\x1e\x3f\x3b\x35\xac\xfd\xcc\x43\xdc\xa4\x49\x3b\xfe\x9d\x1d\
-\xdb\x7b\x22\x90\x78\xf8\xb2\x28\xa7\xbe\x7d\xc1\x4b\x9d\x79\xdf\
-\x18\x15\xe5\x16\x99\x10\x56\xde\x69\xdc\x3f\x22\xfd\xec\xd4\xf0\
-\xad\x04\x03\x18\xa3\xa2\x7e\x76\x6a\x58\xde\x68\x2b\xb4\x36\xf8\
-\xbe\xc6\x18\x53\xdb\xef\xe7\xfa\xec\xed\x67\x63\x10\x42\x00\xf0\
-\xfb\xd5\x65\x2a\x15\x45\xc7\x6d\x0d\x00\xc4\xa2\xc1\xaa\x6f\x0d\
-\x3e\x6c\xab\xc2\x1c\x56\xa4\x77\x4b\xb0\xf2\x35\x15\x5f\x21\x85\
-\xe0\xc8\x6b\x5f\x92\x2d\x37\x33\x39\xf9\x03\x27\x8e\x1f\xa2\xf7\
-\xbe\x9d\x04\x1c\x0b\x37\xe4\xac\xff\xa6\x30\x87\xbd\xba\x00\x6a\
-\x06\x79\xe5\xf5\xaf\x89\xd9\x92\xc5\xcc\x0a\xd9\x7c\x19\xcf\xe9\
-\xe2\xe4\xa9\x2f\x78\x7c\xff\x01\x72\x85\x0a\x2b\x65\x1f\xa5\x4c\
-\xb5\xb2\x55\x16\x80\xbd\x31\xda\xda\x20\x1f\x7d\x3e\xcd\xc2\xfd\
-\x59\xa6\x93\x39\x92\xd1\x22\xea\x9b\x16\xce\x9d\x3f\xce\xe0\x83\
-\x03\x24\x82\x59\x3a\xdb\x7b\x88\xc7\x82\x68\x63\x58\xc9\xcc\x62\
-\x8c\x21\x18\xb0\x6a\xc3\x37\x06\x49\x16\xff\x24\x6b\xa5\x49\xbb\
-\x25\xbc\xa2\xa6\x21\xbb\x40\x7f\xdf\x00\x83\xbd\x01\x8e\x3c\xd5\
-\x45\xd7\x8e\x6b\x9c\x9c\x98\x25\x1a\xb6\xe8\xbe\x3d\xc2\xdd\x77\
-\x44\x48\xc4\x1c\x22\xe1\xeb\x58\x59\xaf\xcf\xd3\x33\x29\x2e\x34\
-\x2d\x91\x93\x3e\xbe\x34\x78\x01\xc5\xe2\x61\xc5\xae\x72\x8e\x70\
-\xc8\xc2\x0d\x5a\xbc\xf5\xee\x2f\x9c\xfa\x3e\x86\x69\x7a\x8e\xcf\
-\x26\xe6\xf9\x63\xa1\x44\xa1\xa4\xd0\xda\x6c\x0d\x2f\x15\x7c\xb4\
-\x67\x28\x59\x0a\xcf\xd6\x54\xe2\x06\x13\x87\x2b\x6f\x68\xa6\x27\
-\xaf\x31\x32\x36\xc7\xb2\x7f\x17\xef\x7d\x7c\x8c\x33\x67\xcf\x12\
-\x70\x24\x4a\x69\xd6\x6a\x46\xd6\xd3\x70\x72\xa9\x82\x67\x34\x45\
-\xad\x28\xdb\x1a\x15\x34\x98\xff\x46\xed\xef\x37\x0d\x99\xbf\x4a\
-\x3c\x30\x38\xc0\xc8\x4b\xaf\x92\x5a\x9c\xe2\xe0\x23\x6d\x74\xb4\
-\xba\x84\x5d\x0b\x29\x45\x7d\xb8\x94\x82\x96\xb6\x10\xf3\xc5\x12\
-\x2a\xef\x53\x11\x1a\x63\xad\x3f\x93\x19\x85\xf1\xb1\x77\x58\x5a\
-\xf8\x99\x97\x9f\xe9\xa6\x75\x47\x90\xc6\xb8\x43\xd8\xb5\xb6\xce\
-\xfc\xfa\xfd\x00\xfb\x3e\xf4\xc8\x05\x35\xba\x5e\xeb\x46\x21\xf9\
-\xcf\x0a\xa9\x8c\x87\xe3\x48\xdc\x90\xb5\x6e\x98\x6a\xaa\x65\xf2\
-\x52\x92\x43\x2f\x5e\xc2\x8c\x02\x1a\x10\xf5\x07\xac\xc3\x75\x70\
-\x83\x92\x80\xb3\xf9\xd0\x26\xf8\x8f\xb3\x29\xc6\x3e\xb8\x8c\x19\
-\x35\x75\x6b\x7b\x7e\x3c\xca\x45\x0c\x7e\x49\x31\xf4\x58\x3b\xf7\
-\xf6\x34\x90\x88\x39\x04\x1c\x59\x1f\xfe\xdb\xd5\x3c\x5f\x9d\x4b\
-\x32\xfd\x44\xb2\xba\xd7\xfa\xb6\x60\xcf\xde\x16\xdc\x90\x45\x4c\
-\x4a\x2a\x9e\x62\xfe\x4e\xc5\xc8\xc1\x4e\xda\x76\x86\xe8\xe9\x0a\
-\xe3\xd8\x92\x58\xd4\xc6\xb2\x44\x6d\x78\x2a\x53\xe1\xca\x7c\x99\
-\x63\x5d\xbf\x56\x9d\xbd\x9f\x44\x18\x7a\xba\x95\x27\x0f\xb4\xd3\
-\xdc\x18\xc0\xf3\x0d\x52\x40\xd8\xb5\xb0\xa4\x20\x14\xb2\x70\x6c\
-\x81\x63\xcb\xaa\x42\xd6\xfd\xb7\xf4\xec\xa3\x06\xa0\x50\x52\xd8\
-\x4e\x1b\x7e\x4a\xd3\x31\xf9\x29\xcf\xfe\xd4\x49\x7f\x5f\x13\xfb\
-\xfa\x9b\x71\x43\x92\x58\xd4\x21\x18\x90\xac\xde\xb0\x42\x50\x13\
-\x58\x33\xf3\x88\x6b\xa1\xfd\x65\x96\xf2\x79\xc6\x43\x7b\xd8\x75\
-\x38\xcc\x3d\xdd\xd1\xaa\xcf\x71\xe4\xff\x7f\x91\x56\x33\xaf\xea\
-\x37\xe7\xa1\x94\x21\x16\xb5\xd1\x06\x2c\x29\x36\xf5\x72\x9b\x96\
-\x95\xc0\xc4\xda\x9d\x78\x83\x43\x53\x22\x80\x65\x09\x1c\xfb\x86\
-\xc1\x00\xe7\x25\x70\x14\x48\x6f\x1e\x22\x51\xe3\x75\xd9\xb6\xa5\
-\x81\xa3\x32\xb1\xfb\xf4\x0c\x30\xb8\xb1\x82\x9b\xb0\x09\x60\x30\
-\xb1\xfb\xf4\xcc\xbf\xa0\xe9\x6e\xae\x5a\xdf\x4b\x81\x00\x00\x00\
-\x00\x49\x45\x4e\x44\xae\x42\x60\x82\
-"
-
-qt_resource_name = b"\
-\x00\x07\
-\x07\x3b\xe0\xb3\
-\x00\x70\
-\x00\x6c\x00\x75\x00\x67\x00\x69\x00\x6e\x00\x73\
-\x00\x0b\
-\x06\x1f\xb8\xc2\
-\x00\x61\
-\x00\x6d\x00\x63\x00\x72\x00\x5f\x00\x76\x00\x69\x00\x65\x00\x77\x00\x65\x00\x72\
-\x00\x08\
-\x0a\x61\x5a\xa7\
-\x00\x69\
-\x00\x63\x00\x6f\x00\x6e\x00\x2e\x00\x70\x00\x6e\x00\x67\
-"
-
-qt_resource_struct_v1 = b"\
-\x00\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x01\
-\x00\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x02\
-\x00\x00\x00\x14\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\
-\x00\x00\x00\x30\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\
-"
-
-qt_resource_struct_v2 = b"\
-\x00\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x01\
-\x00\x00\x00\x00\x00\x00\x00\x00\
-\x00\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x02\
-\x00\x00\x00\x00\x00\x00\x00\x00\
-\x00\x00\x00\x14\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\
-\x00\x00\x00\x00\x00\x00\x00\x00\
-\x00\x00\x00\x30\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\
-\x00\x00\x01\x9c\x23\xfd\x16\x70\
-"
-
-qt_version = [int(v) for v in QtCore.qVersion().split('.')]
-if qt_version < [5, 8, 0]:
-    rcc_version = 1
-    qt_resource_struct = qt_resource_struct_v1
-else:
-    rcc_version = 2
-    qt_resource_struct = qt_resource_struct_v2
-
-def qInitResources():
-    QtCore.qRegisterResourceData(rcc_version, qt_resource_struct, qt_resource_name, qt_resource_data)
-
-def qCleanupResources():
-    QtCore.qUnregisterResourceData(rcc_version, qt_resource_struct, qt_resource_name, qt_resource_data)
-
-qInitResources()

openspec/changes/archive/2026-10-02-add-daily-api-monitor/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-02

openspec/changes/archive/2026-10-02-add-daily-api-monitor/design.md

@@ -0,0 +1,173 @@
+# Design
+
+## Context
+
+- What broke in #67: the facet item shape of `api/search/query`
+  (`json.nl` `arrntv` → `arrarr` with the Solr 10 migration in digiarchiv
+  v4.1.0). `fetch_set` caught the `TypeError`, logged a warning and returned
+  `[]`; nothing outside QGIS noticed. The plugin now accepts both shapes
+  (`amcr_codelists._facet_name`) and keeps previous codelist values when a
+  set comes back empty, which makes the next break of this kind even
+  quieter for users – only a check outside the plugin catches it.
+- What the plugin uses (from the code on `main`):
+  - `GET https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json`
+    (`amcr_tools.load_translations`)
+  - `GET …/api/search/query` with `entity`, `mapa=true`, `sort=ident_cely
+    asc`, `rows=500`, `page`, `loc_rpt=minLat,minLon,maxLat,maxLon`,
+    filters as `key=value:or` lists, date ranges; response
+    `response.numFound` / `response.docs[]`, errors as HTTP 200 without
+    `response` (`amcr_tools.load_amcr_data`, `_api_get_json`)
+  - PIAN geometry requests in batches (`amcr_tools.load_amcr_data`)
+  - `…/api/search/query` with `rows=0&noFacets=false&onlyFacets=true`,
+    response `facet_counts.facet_fields.<f_…>[]` (`amcr_codelists.fetch_set`
+    for `vedouci`, `nalezce`)
+  - `GET https://api.aiscr.cz/2.2/oai?verb=ListRecords&metadataPrefix=oai_dc
+    &set=…` with `resumptionToken` pagination (`fetch_set`, all other sets
+    in `amcr_codelists.slovnicek`)
+  - `POST …/api/user/login`, `GET …/api/user/islogged`, `…/logout`
+    (`amcr_tools.login_to_api`, session check)
+- Live probe (2026-10-02, anonymous, Praha bbox `49.9,14.3,50.2,14.7`, one
+  page of 500): `akce` numFound 20 635 (1.0 MB, 0.6 s), `lokalita` 342
+  (0.8 MB, 0.4 s), `pian` 30 321 (0.8 MB, 0.5 s), `samostatny_nalez` 0
+  (anonymous SN are sparse – the test bbox must be chosen so that every
+  entity returns records). Bbox chosen: Mikulov `48.8,16.6,48.9,16.75`
+  – akce 185, lokalita 18, samostatny_nalez 2, pian 294. Only 12
+  anonymous map-enabled SN exist in the whole CZ, so 2 is accepted:
+  archive records do not disappear (maintainer decision); facet request 54 fields, items are lists. The
+  deployed version read from the web bundle: `v4.0.3-237-g96deec70-dirty`
+  (footer text is hard-coded and not reliable).
+- GitHub runs `schedule` only on the default branch (`main`) and disables
+  scheduled workflows after 60 days without repository activity.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Daily, credential-free check that tells apart three outcomes: the API
+  changed in a way the plugin breaks on (fail), the API changed in a way
+  the plugin survives (drift), the API was not reachable (unavailable).
+- Messages specific enough to start a fix without re-probing (field, old
+  shape, new shape, request).
+- One tracking issue, no daily noise.
+
+**Non-Goals:**
+- Logged-in access, access levels B–D.
+- Full data validation (counts, contents of records).
+- Changing plugin code to make it more testable – if a function cannot be
+  called without UI, the live test provides a fake `iface` / canvas.
+
+## Decisions
+
+1. **Two scripts, two jobs.** `tests/api_contract.py` (job *API contract*,
+   `ubuntu-latest` + `actions/setup-python`, `requests` pinned in workflow
+   `env`) and `tests/api_plugin_live.py` (job *Plugin against live API*,
+   `docker run qgis/qgis:ltr`, same invocation style as the smoke test).
+   *Alternative:* one script in the QGIS container – rejected: a QGIS image
+   problem would hide the contract result, and the contract check would
+   pay the image pull every day.
+   Only `ltr` for the live job: the API path does not differ between Qt5
+   and Qt6, which the PR smoke test already covers on both.
+2. **Contract = recorded expectations in the script, not a stored
+   baseline file.** Each check states the expected keys/types/shapes
+   inline (e.g. facet item is `[str, int]`, `numFound` is `int`,
+   `docs[].ident_cely` is `str`). A mismatch the plugin tolerates is
+   reported as **DRIFT** (e.g. facet shape back to `{"name":…}`, an
+   extra type the parser accepts), a mismatch it does not tolerate as
+   **FAIL**. Updating an expectation is a reviewed code change.
+   *Alternative:* snapshot JSON baseline refreshed automatically – rejected:
+   a silent baseline refresh would accept the very change we want to see.
+3. **Statuses and exit codes.** Each check yields `OK` / `DRIFT` / `FAIL` /
+   `UNAVAILABLE` + detail. Both scripts write `results-<job>.json`
+   (check name, status, detail, request URL without secrets) and a Markdown
+   table to `$GITHUB_STEP_SUMMARY` when set; exit code 1 on any `FAIL` or
+   `DRIFT`, 0 otherwise (an all-`UNAVAILABLE` run is green but visible in
+   the summary). Locally the scripts print the same table.
+4. **Retries.** Network errors, timeouts and HTTP 5xx: 3 attempts with
+   backoff (2 s, 8 s). After that the check is `UNAVAILABLE`; checks that
+   depend on it are skipped as `UNAVAILABLE`, not `FAIL`. HTTP 4xx or a
+   200 with an `error` body is a real answer and is judged by the contract.
+   A per-host circuit breaker follows: once a host fails its full retry
+   cycle, later requests to it return "unreachable" without network I/O,
+   so an all-unreachable run ends in ~10 s instead of tens of minutes.
+5. **Test inputs from the live API, not from `heslar.csv`.** Filter values
+   are taken from facets of the same bbox in the same run; the test bbox is
+   a fixed small area where every entity (`akce`, `lokalita`,
+   `samostatny_nalez`, `pian`) returns a non-zero anonymous count below
+   one page, chosen during implementation by a probe and documented in
+   the script. Pagination is checked separately with `rows=100` on a larger
+   area (pages must not overlap; downloaded ≥ numFound when it is small
+   enough).
+6. **Live plugin test thresholds.** For each set in
+   `amcr_codelists.slovnicek`: `fetch_set` must return ≥ 1 item **and** at
+   least 50 % of the row count of that category in the bundled
+   `codelists/heslar.csv` (a shrunken codelist is the #67 symptom). For
+   each data type: `load_amcr_data` on the test bbox (fake `iface`, fake
+   canvas in EPSG:5514) must add at least one layer with ≥ 1 feature with
+   a valid geometry and the expected attribute fields. The plugin package
+   is imported as a package (`amcr_viewer.amcr_tools`), so its relative
+   imports work – a bare `spec_from_file_location` makes `load_amcr_data`
+   swallow the import error into "0 records".
+7. **Deployed version.** Fetch `https://digiarchiv.aiscr.cz/home`, scan the
+   referenced `*.js` bundles for `raw:"v…"` (git-describe) and report it;
+   not finding it is a `DRIFT` of its own check, never a `FAIL` of the run.
+8. **Reporting job** (`needs` both, `if: always()`, only when
+   `github.ref_name == github.event.repository.default_branch`; the
+   workflow has no other triggers than `schedule` and `workflow_dispatch`; `permissions: issues: write`
+   for this job only, `contents: read` elsewhere). It downloads both result
+   files (artifacts) and with `gh`:
+   - any `FAIL`/`DRIFT` → find the open issue with label `api-monitor`; if
+     none, create it (`gh label create api-monitor --force` first); if it
+     exists and the fingerprint (sorted names of FAIL/DRIFT checks – not
+     UNAVAILABLE, which would make it flap – stored as an HTML comment in
+     the issue body) differs, add a comment and update the
+     fingerprint; identical fingerprint → do nothing;
+   - every check `OK` → close the open issue with a comment linking the
+     run;
+   - no `FAIL`/`DRIFT` but some `UNAVAILABLE` → leave the issue as it is
+     (an outage proves neither break nor recovery);
+   - a job that did not produce its result file (crashed script, image
+     pull failure) counts as one `FAIL` check named after the job.
+   Issue text in Czech (repo convention for issues), unwrapped GFM: deployed
+   version, table of non-OK checks, run link, how to reproduce locally.
+   *Alternative:* `actions/github-script` or a marketplace action – rejected:
+   `gh` is preinstalled and needs no third-party action pin.
+9. **Schedule** `cron: "17 5 * * *"` (07:17 CEST) – off the full hour,
+   before the working day. Plus `workflow_dispatch`. Concurrency group per
+   ref, `cancel-in-progress: false`.
+10. **Not a PR check.** The new workflow does not run on `pull_request`: a
+    PR must not go red because digiarchiv is down. Contributors run the
+    scripts locally or dispatch the workflow on their branch.
+
+## Risks / Trade-offs
+
+- **False alarms from data changes** (a record deleted in the test bbox,
+  an entity count dropping to 0) → thresholds are "≥ 1" and "≥ 50 % of the
+  bundled codelist", not exact counts; the bbox is chosen with margin.
+- **Scheduled workflow auto-disabled after 60 days of inactivity** →
+  documented in `AGENTS.md`; any push to `main` (dependabot included)
+  resets the timer.
+- **Tests only `main`'s plugin code** – a fix waiting on a version branch
+  is not exercised by the schedule → manual dispatch on that branch.
+- **Anonymous only** → `pristupnost` B–D paths and login success are not
+  covered; the login *error* path is.
+- **Load on digiarchiv** – a few dozen small requests a day; negligible.
+
+## Verification
+
+- Both scripts run locally against the live API and pass
+  (`uv run -q --no-project --with requests python tests/api_contract.py`;
+  live test in `docker run qgis/qgis:ltr`).
+- **#67 regression check**: run the live test against the plugin as of the
+  commit before the #67 fix (`git archive`) – it must FAIL on `vedouci` /
+  `nalezce`; the contract test must flag a facet-shape DRIFT when its
+  expectation is temporarily set to the old `{"name":…}` shape.
+- Outage simulation: point the scripts at an unroutable host
+  (environment override of the base URLs) → all checks `UNAVAILABLE`,
+  exit 0.
+- Reporting logic tested with a dry-run mode (`API_MONITOR_DRY_RUN=1`
+  prints the `gh` commands instead of running them) for: new issue, same
+  fingerprint, changed fingerprint, recovery.
+- The full `AGENTS.md` check set passes on the new files (check_sources,
+  bandit, detect-secrets `--all-files`, flake8 `--isolated` on
+  `amcr_viewer/`, ruff on the repo); `actionlint` on the new workflow.
+- After merge: one manual `workflow_dispatch` on `main` and inspection of
+  the summary.

openspec/changes/archive/2026-10-02-add-daily-api-monitor/proposal.md

@@ -0,0 +1,78 @@
+# Proposal
+
+## Why
+
+Digiarchiv changes its API without notice to clients. Issue #67 showed the
+cost: digiarchiv v4.1.0 (Solr 10) changed the facet item shape from
+`{"name": …}` to `[value, count]`, the plugin swallowed the resulting
+exception and the person codelists (`vedouci`, `nalezce`) came out empty –
+found by hand, after users were already affected. Today nothing in the
+repository talks to the live API: `tests/smoke_test.py` is deliberately
+offline and CI runs only on pull requests and pushes, so an API change is
+noticed only when a user hits it.
+
+## What Changes
+
+- New scheduled GitHub Actions workflow `.github/workflows/api_monitor.yml`
+  that runs once a day (and on manual dispatch) against the production
+  digiarchiv and `api.aiscr.cz` OAI, without credentials.
+- New **contract test** `tests/api_contract.py` (plain `requests`, no QGIS):
+  sends the same requests the plugin sends and checks the shape of every
+  response the plugin reads – endpoints, keys, value types, facet item
+  shape, OAI sets, pagination, bbox restriction, PIAN geometry, filters,
+  login error path. Says *what* changed in the API.
+- New **live plugin test** `tests/api_plugin_live.py`, run in
+  `qgis/qgis:ltr`: calls the plugin's own functions (`fetch_set` for every
+  codelist set, `load_translations`, `load_amcr_data` per data type) against
+  the live API and checks that they produce non-empty, well-formed results.
+  Says *whether* the change breaks users.
+- Every run records the deployed digiarchiv version (git-describe string
+  from the web bundle) in its summary.
+- Outages (timeouts, HTTP 5xx, connection errors after retries) are
+  reported as *unavailable*, separately from contract breaks, and do not
+  open an issue.
+- A failing or drifting run opens **one** tracking issue (label
+  `api-monitor`) or updates the open one; the next clean run closes it.
+- `AGENTS.md` documents the monitor (what it runs, how to run it locally,
+  how to read the issue).
+
+What changes for a plugin user: nothing directly – no file under
+`amcr_viewer/` changes and the plugin version is not bumped. Indirectly,
+API breaks like #67 are found within a day of a digiarchiv release instead
+of by users.
+
+Out of scope:
+
+- Logged-in checks (variant D): no account secret is stored in the repo;
+  anonymous runs cover only `pristupnost=A` records.
+- Testing version branches on schedule: GitHub runs `schedule` only on the
+  default branch; other refs can be run by manual dispatch.
+- Availability monitoring of digiarchiv as a service.
+
+## Capabilities
+
+### New Capabilities
+
+- `api-monitoring`: periodic verification that the digiarchiv / AMČR OAI
+  API still satisfies the contract the plugin depends on, and reporting of
+  breaks through a tracking issue.
+
+### Modified Capabilities
+
+<!-- none – openspec/specs/ is not maintained (change-tracked) -->
+
+## Impact
+
+- New files: `.github/workflows/api_monitor.yml`, `tests/api_contract.py`,
+  `tests/api_plugin_live.py`; edited `AGENTS.md`.
+- Affected plugin modules (read, not changed): `amcr_viewer/amcr_tools.py`
+  (`load_translations`, `load_amcr_data`, `login_to_api`),
+  `amcr_viewer/amcr_codelists.py` (`slovnicek`, `fetch_set`).
+- API: one run ≈ a few dozen anonymous requests to
+  `digiarchiv.aiscr.cz/api/*` and `api.aiscr.cz/2.2/oai`, restricted to a
+  small bbox – negligible load for digiarchiv.
+- GitHub: scheduled workflow minutes (two short jobs per day), the
+  `api-monitor` label, `issues: write` permission for the reporting job
+  only. Depends on the digiarchiv repository
+  (`ARUP-CAS/aiscr-digiarchiv-2`) only as the source of the API under test.
+- PR targets `main` (repository tooling, no plugin behaviour change).

openspec/changes/archive/2026-10-02-add-daily-api-monitor/specs/api-monitoring/spec.md

@@ -0,0 +1,63 @@
+# Spec Delta
+
+## Purpose
+
+Detects changes of the digiarchiv / AMČR OAI API that break or alter what
+the AMČR Viewer plugin relies on, within a day of their deployment, and
+reports them where maintainers see them.
+
+## ADDED Requirements
+
+### Requirement: The API contract is checked daily
+The repository SHALL run, once a day and on manual dispatch, a check of
+every API endpoint, parameter and response field the plugin uses, without
+credentials, against the production API.
+
+#### Scenario: Scheduled run
+- **WHEN** the daily schedule fires on the default branch
+- **THEN** both the contract test and the live plugin test run against the production API and their results are published in the run summary
+
+#### Scenario: Manual run on another branch
+- **WHEN** a maintainer dispatches the workflow on a non-default branch
+- **THEN** the tests run against that branch's plugin code and no issue is opened, updated or closed
+
+### Requirement: Checks follow the plugin, not the API documentation
+The contract test SHALL send requests built the way the plugin builds them
+and check the response keys, value types and shapes the plugin reads. The
+live plugin test SHALL call the plugin's own codelist and download
+functions.
+
+#### Scenario: Facet shape changes
+- **WHEN** the API returns facet items in a shape different from the one recorded in the contract test
+- **THEN** the contract test reports a drift naming the facet field and the old and new shape
+
+#### Scenario: Plugin function returns nothing
+- **WHEN** a plugin codelist set or data download returns zero items for an input that returned items before
+- **THEN** the live plugin test fails and names the set or data type
+
+### Requirement: Outages are not reported as API changes
+A request that times out, fails to connect or returns HTTP 5xx SHALL be
+retried; if it still fails, the check SHALL be reported as unavailable,
+separately from failures and drifts.
+
+#### Scenario: Server maintenance
+- **WHEN** digiarchiv is unreachable during the whole run
+- **THEN** the run reports the affected checks as unavailable and no issue is opened
+
+### Requirement: Breaks are reported through one tracking issue
+A run with a failure or drift on the default branch SHALL open an issue
+labelled `api-monitor`, or update the open one, with the deployed
+digiarchiv version and the list of failing checks. A clean run SHALL close
+the open issue.
+
+#### Scenario: First failing run
+- **WHEN** a scheduled run fails and no open `api-monitor` issue exists
+- **THEN** a new issue is opened with the deployed version, failing checks and a link to the run
+
+#### Scenario: Repeated identical failure
+- **WHEN** a scheduled run fails with the same set of FAIL/DRIFT checks as the open issue already lists, regardless of which checks are unavailable
+- **THEN** no new issue and no new comment is created
+
+#### Scenario: Recovery
+- **WHEN** a scheduled run passes while an `api-monitor` issue is open
+- **THEN** the issue is closed with a comment linking the passing run

openspec/changes/archive/2026-10-02-add-daily-api-monitor/tasks.md

@@ -0,0 +1,65 @@
+# Tasks
+
+## 1. Contract test
+
+- [x] 1.1 Probe and fix the test inputs: a small bbox where `akce`,
+  `lokalita`, `samostatny_nalez` and `pian` all return 1–499 anonymous
+  records, and a larger area for pagination; record the probe numbers in
+  the script header; verify by a probe run in scratch
+- [x] 1.2 Write `tests/api_contract.py` with the status model, retries and
+  outputs from design.md (decisions 3, 4, 7) and checks for: i18n
+  `cs.json`, every OAI set in `amcr_codelists.slovnicek` (first page shape
+  + `resumptionToken` paging), facet fields `f_vedouci` / `f_nalezce` item
+  shape, main query per entity (keys and value types the plugin reads,
+  `numFound` int), pagination without overlap, bbox restriction, PIAN
+  batch geometry, every filter key the dialog builds (values taken from
+  live facets), date range, error answer for an invalid parameter (HTTP 200
+  without `response`), unknown entity, login with deliberately wrong
+  credentials; verify a local run is all OK
+- [x] 1.3 Verify the drift detection: temporarily set the facet
+  expectation to the old `{"name":…}` shape → DRIFT reported with the
+  field and both shapes; revert
+
+## 2. Live plugin test
+
+- [x] 2.1 Write `tests/api_plugin_live.py` (package import of
+  `amcr_viewer`, fake `iface` / canvas, thresholds from design.md
+  decision 6, same status model and outputs); verify it passes in
+  `qgis/qgis:ltr`
+- [x] 2.2 #67 regression: run it against the plugin from the commit before
+  the #67 fix (`git archive` into scratch) → FAIL on `vedouci` and
+  `nalezce`; verify and record the output
+
+## 3. Workflow and reporting
+
+- [x] 3.1 Write `.github/workflows/api_monitor.yml` per design.md
+  (decisions 1, 8, 9, 10): pinned action SHAs as in `code_quality.yml`,
+  pinned `requests`, artifacts with result files, reporting job with
+  `issues: write` only; verify with `actionlint`
+- [x] 3.2 Reporting script (inline step or `tests/api_monitor_report.py`)
+  with `API_MONITOR_DRY_RUN=1`; verify the four cases (new issue, same
+  fingerprint, changed fingerprint, recovery) and that a run with only
+  UNAVAILABLE leaves the issue untouched
+- [x] 3.3 Outage simulation (unroutable base URL override) → all
+  UNAVAILABLE, exit 0; verify
+
+## 4. Documentation and checks
+
+- [x] 4.1 `AGENTS.md`: new subsection on the API monitor (what it runs,
+  local commands, how to read the issue, 60-day schedule disable, manual
+  dispatch for version branches); verify by reading the diff
+- [x] 4.2 Run the `AGENTS.md` check set (check_sources, bandit,
+  detect-secrets `--all-files`, flake8 `--isolated` on `amcr_viewer/`,
+  ruff, smoke test in `qgis/qgis:ltr` and `:stable` – unchanged plugin
+  code, must stay green) and `openspec validate add-daily-api-monitor
+  --strict`; verify all clean
+- [x] 4.3 After merge into `main`: manual `workflow_dispatch` on `main`,
+  inspect the summary and that no issue was opened on a clean run
+  - Run 37059874538 on `main` (02144d8), 2026-10-02: not a clean run –
+    `api.aiscr.cz/2.2/oai` returns `amcr:amcr` for `metadataPrefix=oai_dc`
+    since that evening (`2.0`/`2.1` correct). Contract job FAIL on all 17
+    OAI sets, live job FAIL on all 17 OAI `fetch_set`; digiarchiv facets
+    and downloads OK. Report opened issue #89 with label `api-monitor`,
+    deployed version, 34 failing checks and run link; run ended red as
+    designed. The clean-run path (no issue / issue closed) was verified
+    by the dry run in 3.2 and waits for the API fix.

openspec/changes/archive/2026-10-02-add-filter-memory-and-reset/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-02

openspec/changes/archive/2026-10-02-add-filter-memory-and-reset/design.md

@@ -0,0 +1,172 @@
+# Design
+
+## Context
+
+See proposal.md – Why. Current state of `amcr_viewer/amcr_dialog.py`
+(branch `version/v2.2.0`):
+
+- `AmcrViewer.run_download()` builds a new `AmcrFilterDialog(typ_dat)` for
+  every opening (`amcr_viewer.py`), without a parent.
+- Form state is spread over:
+  - `self.selection_cache` – 19 keys, each a list of codelist codes; the
+    picker's read-only `QLineEdit` text is only set inside the nested
+    `open_dialog()` closure in `setup_picker()`, which keeps no reference
+    to the line edit.
+  - checkboxes `chk_bbox` (default checked), `chk_posevidence`,
+    `chk_proj_akce` (events only), `chk_komponenty` (events and sites);
+  - `self.date_ranges` – `(api_field, name, date_from, date_to)` with
+    nullable `QgsDateEdit`s (`clear()` is the only correct way to empty
+    them, see `_date_edit`).
+- The one non-empty default, *PIAN – přesnost* = `HES-000861/862/863`, is
+  hard-coded inside `setup_picker()` together with its display text.
+- Codelists are module-level dicts in `amcr_codelists.py` mapping
+  **label → code**; `refresh_globals()` updates them in place after
+  *Aktualizovat hesláře*, so the dialog always sees the current values.
+- `tests/smoke_test.py` already builds the dialog offscreen for all three
+  data types and checks `get_filters()` for date ranges.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- One snapshot format that describes the whole form, used for remember,
+  restore, defaults and "is it default?" comparison.
+- No change in `get_filters()` / `get_bbox()` / `get_komponenty()` output
+  for the same form state.
+
+**Non-Goals:**
+
+- Persisting to `QgsSettings` or the project (variants B and C of #84).
+- Remembering the window size or scroll position.
+
+## Decisions
+
+### Snapshot = plain dict kept at module level in `amcr_dialog.py`
+
+`_REMEMBERED_STATE: dict[str, dict]` keyed by `typ_dat`. The snapshot is
+
+```python
+{
+    "codes": {cache_key: [code, ...], ...},   # only pickers of this typ
+    "checks": {"bbox": bool, "posevidence": bool, ...},
+    "dates": {api_field: (iso_from | None, iso_to | None), ...},
+}
+```
+
+Dates are stored as ISO strings (or `None` for an empty picker), never as
+`QDate`, so a stored value can never turn an empty picker into "today".
+
+- *Why module level, not on `AmcrViewer`:* `run_download()` stays
+  untouched and the smoke test can exercise remember/restore just by
+  creating dialogs. QGIS (and Plugin Reloader) re-imports the plugin
+  package on reload, which drops the dict – that matches the "QGIS run
+  only" requirement.
+- *Alternative – keep one dialog instance per type and only `hide()` it:*
+  rejected. Restoring would be free, but Cancel would then keep the
+  cancelled edits (the requirement says it must not), and long-lived
+  dialogs would hold stale codelist references after an update.
+- *Alternative – pass state in/out through `AmcrViewer`:* works, but adds
+  plumbing in two files for no behavioural gain.
+
+### Defaults defined once
+
+A module-level `DEFAULT_CODES = {"pian_presnost": ["HES-000861",
+"HES-000862", "HES-000863"]}` and `DEFAULT_CHECKS = {"bbox": True}`
+replace the hard-coded block in `setup_picker()`. `_default_state()`
+builds a full snapshot for the dialog's `typ_dat` from them. It is used
+by the constructor (no remembered state), the reset button and the
+"differs from defaults" comparison – one definition, three users.
+
+### Pickers keep a handle to their widgets
+
+`setup_picker()` registers each picker in `self.pickers[cache_key] =
+(data_source, display_field, clear_btn)`. A single
+`_set_picker(cache_key, codes)` sets `selection_cache`, rebuilds the
+display text from the current codelist (inverted `code → label`, sorted
+like the selection dialog), drops unknown codes and enables/disables the
+clear button. `open_dialog()`, restore, reset and clear all go through
+it, so the display text can never disagree with the cache.
+
+Display text is rebuilt from codes rather than stored, so a label renamed
+by a codelist update shows its new name, and a removed code disappears
+(spec: *Restored values follow the current codelists*).
+
+### Remember only in `accept()` after validation
+
+`accept()` already returns early on a reversed date range; the snapshot is
+taken just before `super().accept()`. `reject()` is not overridden.
+
+### Reset button
+
+`QDialogButtonBox.StandardButton.RestoreDefaults` with Czech text
+*Obnovit výchozí* (the standard button would otherwise show the Qt
+translation of "Restore Defaults", which depends on the installed Qt
+translations). Clicking applies `_default_state()` to the form and hides
+the notice; `_REMEMBERED_STATE` is untouched until OK.
+
+The button box already holds *Aktualizovat hesláře* in `ActionRole`; the
+reset button sits next to it on the left, OK/Cancel stay on the right.
+
+### Per-picker clear button
+
+A narrow `QToolButton` with text `✕` next to *Vybrat…*. It calls
+`_set_picker(cache_key, DEFAULT_CODES.get(cache_key, []))` – it returns
+the filter to its default, which is empty for every picker except
+*pian_presnost* (its three pre-selected levels). The tooltip is
+*Vymazat výběr* for an empty default and *Vrátit výchozí výběr* for
+*pian_presnost*. `_set_picker()` enables the button only while the
+current codes differ from the default (compared order-insensitively, so
+a reordered default still counts as the default); on a fresh dialog the
+PIAN button is therefore disabled. For `pian_presnost`, empty means the
+filter is not sent (current `get_filters()` behaviour for an empty
+list) – this matches the spec.
+
+Changed after the user's manual test in QGIS: the ✕ on *PIAN – přesnost*
+emptied the picker, but the user expected it to restore the default
+three levels, so the button now returns each filter to its default
+instead of always emptying it.
+
+Checkboxes and date pickers do not get their own clear button: a
+checkbox is one click, and `QgsDateEdit` with `setAllowNull(True)`
+already has its own clear control.
+
+### Notice about restored filters
+
+A `QLabel` above the bbox checkbox, styled like the existing component
+warning (neutral info colours), hidden by default. Shown in the
+constructor only when a remembered state exists **and** differs from
+`_default_state()`. Text: *Načteny filtry z minulého hledání (aktivní
+filtry: N).* (changed after the user's manual test in QGIS: the leading
+"ℹ " was removed). N counts form items that differ from the default –
+one per picker, checkbox and date row (a date row counts once even
+with both bounds set). Hidden again on reset; not updated live on
+every edit (it describes what was loaded, not the current form).
+
+### Qt5/Qt6
+
+`QToolButton` from `qgis.PyQt.QtWidgets`; all enums fully scoped
+(`QDialogButtonBox.StandardButton.RestoreDefaults`,
+`QDialogButtonBox.ButtonRole.ResetRole`); no `exec_()`.
+
+## Risks / Trade-offs
+
+- [Forgotten filter gives a suspiciously small result] → notice at the top
+  with a count; reset is one click.
+- [Restored bbox restriction with a different map extent] → bbox is a
+  checkbox, the extent itself is read at download time as today; nothing
+  extent-specific is stored.
+- [Codelist update removes a selected code] → dropped silently on
+  restore. Considered warning about it; not done, because the picker text
+  already shows what is selected and the case is rare.
+- [Plugin reload during development keeps the old dict] → only if the
+  package is not re-imported; both QGIS and Plugin Reloader do re-import.
+
+## Verification
+
+- Smoke test (offline, `qgis/qgis:ltr` and `qgis/qgis:stable`): OK →
+  reopen restores codes/checks/dates and `get_filters()` is equal; Cancel
+  keeps the previous state; reset + OK equals a fresh dialog; clear drops
+  one key from `get_filters()`; unknown code is dropped; notice visible
+  only for non-default state; types do not share state.
+- Manual test in QGIS 3.44 and QGIS 4: the scenarios from the spec, plus
+  *Aktualizovat hesláře* between two openings.

openspec/changes/archive/2026-10-02-add-filter-memory-and-reset/proposal.md

@@ -0,0 +1,72 @@
+# Proposal
+
+## Why
+
+The filter dialog (`AmcrFilterDialog`) is created from scratch every time
+the user opens it, so every selection is lost after each download. Refining
+a query ("same area, add one more period") means re-entering every picker
+and date by hand. There is also no quick way back to the default state once
+many filters are set (issue #84).
+
+## What Changes
+
+- The filter dialog remembers the last confirmed filters **per data type**
+  (Fieldwork events, Sites, Individual finds) for the rest of the QGIS
+  run. Reopening the dialog for the same data type restores all pickers,
+  checkboxes and date ranges. Nothing is written to disk; after a QGIS
+  restart (or a plugin reload) the dialog starts from the defaults again.
+- State is remembered only when the dialog is confirmed with OK (after the
+  existing date-range validation passes). *Cancel* leaves the remembered
+  state unchanged.
+- A new *Obnovit výchozí* button (`RestoreDefaults` role) in the button
+  row resets the whole form to its **defaults**, not to an empty form:
+  *Omezit vyhledávání rozsahem okna* checked, *PIAN – přesnost* with its
+  three pre-selected levels, everything else empty. The reset is applied
+  to the form only; the remembered state changes only on OK.
+- When the dialog opens with restored filters that differ from the
+  defaults, a notice at the top says so and how many filters are active,
+  so a forgotten filter further down the scrollable form is not missed.
+- Each picker gets a small clear button (✕) that returns that single
+  filter to its **default** (empty for almost all pickers, the three
+  pre-selected accuracy levels for *PIAN – přesnost*); it is available
+  only while the filter differs from that default. "No PIAN
+  restriction" is still reachable by unchecking all levels in the
+  selection dialog.
+- Restored codes that are no longer in the current codelists (after
+  *Aktualizovat hesláře*) are dropped, and picker texts are rebuilt from
+  the current codelist labels.
+- README (section 3.3) and the v2.2.0 changelog entry in `metadata.txt`
+  describe the new behaviour.
+
+Out of scope:
+
+- Persisting filters across QGIS restarts (`QgsSettings`) or in the QGIS
+  project – considered in issue #84 as variants B and C, not chosen.
+- Sharing filter values between data types.
+
+## Capabilities
+
+### New Capabilities
+
+- `filter-dialog`: state of the filter dialog between openings – remembered
+  filters per data type, reset to defaults, clearing a single filter and
+  the notice about restored filters.
+
+### Modified Capabilities
+
+<!-- none – openspec/specs/ is not maintained (change-tracked) -->
+
+## Impact
+
+- Code: `amcr_viewer/amcr_dialog.py` (state capture/restore, defaults in
+  one place, reset button, per-picker clear button, notice);
+  `tests/smoke_test.py` (offline cases for restore, cancel, reset, clear
+  and dropped codes). `amcr_viewer/amcr_viewer.py` is not expected to
+  change – `run_download` keeps creating the dialog as today.
+- No change to the digiarchiv API requests: `get_filters()`, `get_bbox()`
+  and `get_komponenty()` keep their output for the same form state.
+- No change to layer attributes or stored settings (`QSettings` is not
+  touched).
+- Target branch `version/v2.2.0` (unreleased): the change joins the v2.2.0
+  changelog entry, no separate version bump.
+- Qt5/Qt6 rules from `AGENTS.md` apply; no new dependencies.

openspec/changes/archive/2026-10-02-add-filter-memory-and-reset/specs/filter-dialog/spec.md

@@ -0,0 +1,111 @@
+# Spec Delta
+
+## Purpose
+
+Keeps the filter dialog's selections between openings within one QGIS run,
+so a query can be refined without re-entering it, and gives quick ways back
+to the default state.
+
+## ADDED Requirements
+
+### Requirement: Confirmed filters are remembered per data type
+When the user confirms the filter dialog with OK, the plugin SHALL remember
+the whole form state (all pickers, checkboxes and date ranges) for that
+data type, and SHALL restore it the next time the dialog for the same data
+type is opened within the same QGIS run. Each data type (Fieldwork events,
+Sites, Individual finds) SHALL have its own remembered state.
+
+#### Scenario: Reopening after a download
+- **GIVEN** the user opened the Fieldwork events dialog, selected a region and a period, set a start-date range and confirmed with OK
+- **WHEN** the user opens the Fieldwork events dialog again
+- **THEN** the same region, period and date range are selected and confirming without changes sends the same filters as before
+
+#### Scenario: Data types do not share state
+- **GIVEN** filters were confirmed in the Fieldwork events dialog
+- **WHEN** the user opens the Sites dialog for the first time
+- **THEN** the Sites dialog shows its defaults
+
+#### Scenario: Cancel keeps the previous state
+- **GIVEN** a remembered state exists for a data type
+- **WHEN** the user changes filters and closes the dialog with Cancel
+- **THEN** reopening the dialog shows the remembered state, not the cancelled changes
+
+#### Scenario: Rejected date range is not remembered
+- **WHEN** the user confirms a reversed date range and the dialog refuses it
+- **THEN** the remembered state is unchanged
+
+### Requirement: Remembered state lives only for the QGIS run
+The remembered filters SHALL NOT be written to disk, QGIS settings or the
+project; after QGIS is restarted or the plugin is reloaded, every dialog
+SHALL open with its defaults.
+
+#### Scenario: QGIS restart
+- **GIVEN** filters were confirmed in a previous QGIS run
+- **WHEN** the user opens the dialog after restarting QGIS
+- **THEN** the dialog shows its defaults
+
+### Requirement: Reset restores the defaults
+The filter dialog SHALL offer a reset action that returns every field of
+the form to its default: the map-extent restriction checked, *PIAN –
+přesnost* with its three pre-selected accuracy levels (where the data type
+has it), and every other filter empty. The reset SHALL change only the
+form; the remembered state SHALL change only when the dialog is then
+confirmed with OK.
+
+#### Scenario: Reset and confirm
+- **GIVEN** several filters are set
+- **WHEN** the user resets the form and confirms with OK
+- **THEN** the sent filters equal those of a dialog opened for the first time, and reopening shows the defaults
+
+#### Scenario: Reset and cancel
+- **GIVEN** a remembered state exists
+- **WHEN** the user resets the form and closes the dialog with Cancel
+- **THEN** reopening the dialog shows the remembered state
+
+### Requirement: A single filter can be returned to its default
+Each codelist filter SHALL offer a per-picker action that returns only
+that filter to its default value (empty, or the three pre-selected
+accuracy levels for *PIAN – přesnost*). The action SHALL be available
+only while the filter differs from its default. Returning *PIAN –
+přesnost* to its default SHALL restore the three pre-selected accuracy
+levels; a completely empty *PIAN – přesnost* (no restriction) SHALL
+remain reachable by unchecking all levels in the picker's selection
+dialog.
+
+#### Scenario: Clearing one picker
+- **GIVEN** a region and a period are selected
+- **WHEN** the user clears the region filter
+- **THEN** the region filter shows nothing selected, the period stays selected and the region parameter is not sent
+
+#### Scenario: Returning PIAN to its default
+- **GIVEN** a Fieldwork events dialog is open with *PIAN – přesnost* at its default three accuracy levels
+- **WHEN** the user changes the PIAN selection (for example clears it)
+- **THEN** the picker's clear action becomes available and, when used, restores exactly the three pre-selected accuracy levels
+- **WHEN** the user unchecks all levels in the *PIAN – přesnost* selection dialog instead
+- **THEN** no accuracy restriction is sent
+
+### Requirement: Restored filters are announced
+When the dialog opens with a restored state that differs from the
+defaults, it SHALL show a notice at the top of the form stating that
+filters from the previous search were restored and how many filters
+differ from the defaults. The notice SHALL disappear once the form is
+reset to the defaults.
+
+#### Scenario: Notice after reopening
+- **GIVEN** a region and a period were confirmed
+- **WHEN** the dialog is reopened
+- **THEN** a notice at the top says filters were restored and that 2 filters are active
+
+#### Scenario: No notice for defaults
+- **WHEN** the dialog opens with no remembered state, or with a remembered state equal to the defaults
+- **THEN** no notice is shown
+
+### Requirement: Restored values follow the current codelists
+When restoring, the plugin SHALL drop selected codes that are no longer
+present in the current codelists and SHALL display the remaining
+selections with their current codelist labels.
+
+#### Scenario: Code removed by a codelist update
+- **GIVEN** a confirmed selection contains a code that a later codelist update removed
+- **WHEN** the dialog is reopened
+- **THEN** that code is not selected and not sent, and the other selected values remain

openspec/changes/archive/2026-10-02-add-filter-memory-and-reset/tasks.md

@@ -0,0 +1,82 @@
+# Tasks
+
+## 1. Form state in one place
+
+- [x] 1.1 In `amcr_viewer/amcr_dialog.py` add `DEFAULT_CODES` /
+  `DEFAULT_CHECKS` and `_default_state()`; remove the hard-coded
+  `pian_presnost` block from `setup_picker()` and apply the default
+  through the new path. Verify: smoke test case "filtrační dialogy"
+  still passes and a fresh `akce`/`lokalita` dialog still sends
+  `f_pian_presnost` with the three codes (assert in the new test 1.4)
+- [x] 1.2 Register pickers in `self.pickers` and add `_set_picker()`
+  (cache + display text rebuilt from the current codelist, unknown codes
+  dropped, clear-button state); route `open_dialog()` through it.
+  Verify: `python3 tests/check_sources.py`, `ruff check .`
+- [x] 1.3 Add `_snapshot()` / `_apply_state()` covering codes, checkboxes
+  and date ranges (ISO strings or `None`; empty picker via `clear()`).
+  Verify: smoke test round-trip – snapshot → apply on a fresh dialog →
+  equal `get_filters()`, `get_bbox()`, `get_komponenty()`
+- [x] 1.4 Extend `tests/smoke_test.py` with an offline case for 1.1–1.3
+  (defaults incl. PIAN, round-trip for all three data types, unknown code
+  dropped). Verify: smoke test passes in `qgis/qgis:ltr` and
+  `qgis/qgis:stable`
+
+## 2. Remember, reset, clear, notice
+
+- [x] 2.1 Module-level `_REMEMBERED_STATE` keyed by `typ_dat`; store the
+  snapshot in `accept()` after the date-range check, restore in the
+  constructor. Verify (smoke test): OK → reopen restores; Cancel keeps
+  the previous state; reversed range refused → state unchanged; another
+  data type starts from defaults
+- [x] 2.2 *Obnovit výchozí* button
+  (`QDialogButtonBox.StandardButton.RestoreDefaults`, Czech text) that
+  applies `_default_state()` to the form only. Verify (smoke test): reset
+  + OK equals a fresh dialog; reset + Cancel keeps the remembered state
+- [x] 2.3 `✕` button (`QToolButton`, tooltip *Vymazat výběr*, or
+  *Vrátit výchozí výběr* for a picker with a non-empty default) per
+  picker that returns that filter to its default, enabled only while it
+  differs from the default. Verify (smoke test): clearing one picker
+  removes only its key from `get_filters()`; the PIAN `✕` is disabled
+  on a fresh dialog, enabled after a change and restores the three
+  default levels
+- [x] 2.4 Notice label at the top, shown only when a restored state
+  differs from defaults, with the count of differing items; hidden on
+  reset. Verify (smoke test): hidden for a fresh dialog and for a
+  remembered default state, visible with the right count otherwise
+- [x] 2.5 Reset `_REMEMBERED_STATE` between smoke-test cases (in
+  `try/finally`) so cases stay independent; verify by running the smoke
+  test twice in one container
+
+## 3. Documentation and version
+
+- [x] 3.1 README section 3.3: remembered filters per data type for the
+  QGIS run, *Obnovit výchozí*, `✕` per filter, the notice; adjust the
+  PIAN default note (reset restores it, `✕` clears it). Verify by reading
+  the section against the spec
+- [x] 3.2 Add bullets to the existing v2.2.0 entry of `changelog=` in
+  `amcr_viewer/metadata.txt` (branch `version/v2.2.0` is unreleased, so
+  no new version; `CITATION.cff` already says 2.2.0). Verify:
+  `python3 tests/check_version_bump.py` (or the CI package job) passes
+
+## 4. Final verification
+
+- [x] 4.1 Run the AGENTS.md check set: `tests/check_sources.py`, bandit,
+  detect-secrets `--all-files`, `flake8 --isolated amcr_viewer/`,
+  `ruff check .`, `pyqgis4-checker` (log contains only the header), smoke
+  test in `qgis/qgis:ltr` and `qgis/qgis:stable`; delete
+  `amcr_viewer/__pycache__` afterwards
+- [x] 4.2 `openspec validate add-filter-memory-and-reset --strict` passes
+- [x] 4.3 Manual test in QGIS 3.44 and QGIS 4 (user): spec scenarios –
+  reopen after a download, Cancel, reset + OK / Cancel, `✕` on one
+  picker and on PIAN, notice text, separate state per data type,
+  *Aktualizovat hesláře* between two openings, defaults after a QGIS
+  restart
+  - User: look and function verified on Fieldwork events, Sites and
+    Individual finds; everything worked except two points – the notice
+    started with an odd "ℹ" and `✕` on PIAN emptied it instead of
+    restoring the default. Both fixed (commit d5e520d); the fix was
+    re-tested by the user on Fieldwork events, for Sites and Individual
+    finds it is covered by the smoke test.
+- [x] 4.4 Archive before merge:
+  `openspec archive add-filter-memory-and-reset --skip-specs` in the same
+  PR

openspec/changes/archive/2026-10-02-fix-component-feature-weight/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-02

openspec/changes/archive/2026-10-02-fix-component-feature-weight/design.md

@@ -0,0 +1,49 @@
+## Context
+
+`load_amcr_data` in `amcr_viewer/amcr_tools.py` (section B) builds, for each
+DJ with a PIAN and *Načíst komponenty* on, one metadata dict per component
+and appends it to `pian_lookup[pian_id]`. The weight is set as
+`'vaha': 1/komps_count` with `komps_count = len(komps)` computed **before**
+the loop that skips components failing `komp_projde_filtrem`. The empty-DJ
+branch leaves `vaha` out and the feature builder falls back to
+`meta.get('vaha', 1)`.
+
+## Goals / Non-Goals
+
+**Goals:** weights of one DJ sum to 1 under any filter; the rule is
+testable offline.
+
+**Non-Goals:** weighting across DJs or across records that share one PIAN
+(a PIAN shared by several DJs still yields several features – the weight
+only de-duplicates components of one DJ, as #55 asked); changing the layer
+schema.
+
+## Decisions
+
+1. **Filter first, then weigh.** Build the list of passing components, then
+   set `vaha = 1/len(passing)`. Alternative – a second counting pass with
+   `sum(komp_projde_filtrem(...))` – duplicates the filter call and drifts
+   if the filter changes (#70 replaces it).
+2. **Extract a small pure helper** (e.g. `_component_entries(dj_meta, komps,
+   passes)` returning the list of per-component dicts with `vaha`, where
+   `passes` is a predicate) so the smoke test can check weights without
+   QGIS layers or network. The helper must not depend on how components are
+   selected, so #70 can pass a different predicate.
+3. **Explicit weight 1 for a DJ without components** instead of relying on
+   the `meta.get('vaha', 1)` default – the default stays as a safety net.
+
+## Risks / Trade-offs
+
+- Floating-point: 1/3 weights sum to 0.999…; acceptable for analyses,
+  test with a tolerance.
+- The helper extraction touches a long function; keep the diff limited to
+  the component branch.
+
+## Verification
+
+- Smoke test cases: 4 components no filter → 4×0.25; filter keeps 1 of 4 →
+  weight 1; keeps 2 of 3 → 2×0.5; no components → 1 entry, weight 1.
+- Full AGENTS.md check set (ltr + stable smoke test, pyqgis4-checker).
+- Manual QGIS test by the user: download akce with *Načíst komponenty* and
+  a period filter, check in the attribute table that `prvek_vaha` sums to 1
+  per `dj_id`.

openspec/changes/archive/2026-10-02-fix-component-feature-weight/proposal.md

@@ -0,0 +1,42 @@
+## Why
+
+Issue #55 added the `prvek_vaha` (feature weight) attribute: when *Načíst
+komponenty* is on, every component of a documentation unit (DJ) becomes its
+own feature on the same PIAN geometry, and the weight 1/*n* lets spatial
+analyses count the geometry once. The unreleased implementation on
+`version/v2.2.0` takes *n* from **all** components of the DJ, before the
+period/area filter. With a component filter active the weights of one DJ no
+longer sum to 1 (DJ with 4 components, 1 passes the Neolithic filter → one
+feature with weight 0.25 instead of 1), so weighted counts are wrong exactly
+when users filter. See the comment on #55.
+
+## What Changes
+
+- *n* in `prvek_vaha = 1/n` is the number of component features actually
+  created for the DJ, i.e. components that pass the period/area filters.
+- The weights of all features created from one DJ sum to 1 with or without
+  filters.
+- A DJ without components keeps its single feature with weight 1 (today the
+  value comes from a default; it becomes explicit).
+- `README.md` documents `prvek_vaha` in the component fields table (it is
+  missing there today).
+- Changelog entry under v2.2.0 in `amcr_viewer/metadata.txt` is extended
+  (the feature is unreleased, no separate version bump).
+
+## Capabilities
+
+### New Capabilities
+- `component-features`: one feature per component of a fieldwork event or
+  site, and the weight attribute that de-duplicates shared geometries.
+
+### Modified Capabilities
+
+## Impact
+
+- `amcr_viewer/amcr_tools.py` – component feature creation in
+  `load_amcr_data` (section B, attribute parsing).
+- `tests/smoke_test.py` – offline check of the weights.
+- `README.md`, `amcr_viewer/metadata.txt` (changelog only).
+- No change to the digiarchiv API contract, layer schema or stored settings.
+- `filter-components-via-component-endpoint` (#70) changes how components
+  are selected; it builds on this change and must keep the weight rule.

openspec/changes/archive/2026-10-02-fix-component-feature-weight/specs/component-features/spec.md

@@ -0,0 +1,35 @@
+# Spec Delta
+
+## Purpose
+
+Describes how components of fieldwork events and sites become map features
+and how their weight lets spatial analyses count a shared geometry once.
+
+## ADDED Requirements
+
+### Requirement: Weight of component features sums to one per DJ
+When components are loaded as features, each feature SHALL carry the weight
+`prvek_vaha = 1/n`, where *n* is the number of features created from the
+same documentation unit in this download. Components excluded by the period
+or area filter SHALL NOT count towards *n*.
+
+#### Scenario: No component filter
+- **WHEN** a documentation unit has 4 components and no period or area filter is set
+- **THEN** 4 features are created, each with weight 0.25
+
+#### Scenario: Filter keeps some components
+- **WHEN** a documentation unit has 4 components and the period filter matches 1 of them
+- **THEN** 1 feature is created with weight 1
+
+#### Scenario: Filter keeps two of three components
+- **WHEN** a documentation unit has 3 components and the filter matches 2 of them
+- **THEN** 2 features are created, each with weight 0.5, and their weights sum to 1
+
+### Requirement: Documentation unit without components has weight one
+When components are loaded and a documentation unit has no component, the
+single feature created for it SHALL have weight 1 and empty component
+fields.
+
+#### Scenario: DJ without components, no filter
+- **WHEN** a documentation unit with a PIAN has no components and no component filter is set
+- **THEN** one feature is created with empty component fields and weight 1

openspec/changes/archive/2026-10-02-fix-component-feature-weight/tasks.md

@@ -0,0 +1,37 @@
+# Tasks
+
+## 1. Weight computed from passing components
+
+- [x] 1.1 In `amcr_viewer/amcr_tools.py` extract the per-component entry
+  building of the *Načíst komponenty* branch into a pure helper that takes
+  the DJ metadata, the component list and a pass predicate, filters first
+  and sets `vaha = 1/len(passing)`; set `vaha = 1` explicitly for a DJ
+  without components; verify with `python3 tests/check_sources.py`,
+  `flake8 --isolated amcr_viewer/` and `ruff check .`
+- [x] 1.2 Extend `tests/smoke_test.py` with an offline case for the helper
+  (4 components no filter → 4×0.25; 1 of 4 passes → 1.0; 2 of 3 pass →
+  2×0.5, sum 1 within tolerance; no components → 1 entry, weight 1);
+  verify the smoke test passes in `qgis/qgis:ltr` and `qgis/qgis:stable`
+
+## 2. Documentation
+
+- [x] 2.1 Add `prvek_vaha` (alias *Váha prvku*) to the component fields
+  table in `README.md` with the rule "1/n, n = features created from the
+  same documentation unit after filters"; verify by reading the rendered
+  table
+- [x] 2.2 Extend the v2.2.0 changelog bullet about the feature weight in
+  `amcr_viewer/metadata.txt` (weights of one documentation unit sum to 1
+  also with period/area filters); no version bump – 2.2.0 is unreleased and
+  `CITATION.cff` already says 2.2.0; verify both versions match
+
+## 3. Verification
+
+- [x] 3.1 Run the full local check set from `AGENTS.md` (check_sources,
+  bandit, detect-secrets `--all-files`, flake8 `--isolated`, ruff,
+  pyqgis4-checker log empty, smoke test ltr + stable); verify all clean
+- [x] 3.2 Manual test in QGIS (user): akce in a small window with *Načíst
+  komponenty* and one period filter; verify in the attribute table that
+  `prvek_vaha` sums to 1 per `dj_id`
+  - Verified by the maintainer 2026-10-02: akce and lokality with
+    *Načíst komponenty*, without and with a period filter – weights sum
+    to 1 per DJ and are computed only from the filtered components

openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-02

openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/design.md

@@ -0,0 +1,81 @@
+# Design
+
+## Context
+
+- The session lives only in memory (`amcr_tools.AMCR_SESSION`, a
+  `requests.Session` with the `JSESSIONID` cookie). `_get_session()` logs in
+  from stored credentials only when no session object exists, so after QGIS
+  start the first download always logs in; an expired session object is
+  reused forever.
+- All data requests of a download go through `_api_get_json()` (main query
+  pages and PIAN batches). `_is_auth_error()` there reacts to HTTP 401 or
+  error text – neither occurs on expiry (see proposal.md – Why).
+- Server behaviour (verified 2026-10-02, live API):
+  `GET /api/user/islogged` → `{"remaining": <s>}` when logged in,
+  `{"error": "nologged"}` otherwise, both HTTP 200. It does not extend the
+  session; any `search/query` does.
+- Codelists (`amcr_codelists.py`) use plain `requests.get` without the
+  session – unaffected by login state.
+
+## Goals / Non-Goals
+
+**Goals:**
+- One check at the start of `load_amcr_data`, before the first data request.
+- Reuse existing login code (`login_to_api`, `LoginDialog.get_credentials`).
+- Testable offline: the check takes its HTTP behaviour from the session
+  object so the smoke test can inject a fake.
+
+**Non-Goals:**
+- Checking before every page / PIAN batch (a download takes seconds to
+  minutes and every data request renews the sliding timeout).
+- Refactoring session handling into a class.
+
+## Decisions
+
+1. **New helper `_ensure_logged_in() -> str`** in `amcr_tools.py`, returning
+   one of `"anonymous"` (no session, no credentials – nothing to check),
+   `"logged_in"`, `"relogged"`, `"fallback"` (expected login, ended
+   anonymous), `"unknown"` (check failed, proceeding).
+   Flow: get session via `_get_session()` (logs in if needed); if none and no
+   credentials → `anonymous`; if none but credentials → login failed →
+   `fallback`; otherwise call `islogged`; `remaining` → `logged_in`;
+   `nologged` → drop session, re-login once, verify again → `relogged` or
+   `fallback`; exception / non-JSON → `unknown`.
+   *Alternative:* re-login unconditionally before each download – simpler,
+   but one POST with the password per download and no way to distinguish a
+   real failure; rejected.
+   *Alternative:* compare `remaining` with a local timestamp of last request
+   – fragile (server timeout may change); rejected.
+2. **Caller decides UI.** `load_amcr_data` pushes the message bar warning on
+   `fallback`; the helper only logs (keeps it free of `iface` for the test).
+3. **Interpretation of the response:** logged in iff the body is a dict with
+   key `remaining`. Anything else with an `error` key → not logged in. Unknown
+   shape → `unknown` (do not trigger a re-login loop on a format change).
+4. **Keep `_is_auth_error`** as a fallback, with a comment that the current
+   server never triggers it; removing it brings no benefit and it still
+   covers a possible future 401.
+5. **Never log the response of `islogged?wantsUser=true`** – we do not use
+   that parameter at all; only `remaining` (number) is logged.
+
+6. **Logout on credential removal** – new `logout_from_api()` in
+   `amcr_tools.py` called from `LoginDialog._forget_credentials`. The local
+   session is dropped first and unconditionally; the server call is best
+   effort (a failure is logged and reported in the dialog text). Without
+   it, the in-memory session would keep downloading logged-in data until
+   QGIS restarts even though the user believes he is "forgotten".
+
+## Risks / Trade-offs
+
+- [Extra request per download] → only for logged-in / credential users; cost
+  ~100 ms.
+- [Session expires during a very long download] → practically impossible:
+  each page request renews the 1 h sliding timeout.
+- [Re-login prompts for the QGIS master password] → `get_credentials()` is
+  already called on first download after start; behaviour unchanged.
+- [`islogged` endpoint changes shape] → `unknown`, logged warning, download
+  proceeds as today (no regression).
+
+## Migration Plan
+
+Plain plugin update; no settings or data migration. Rollback = previous
+release.

openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/proposal.md

@@ -0,0 +1,59 @@
+# Proposal
+
+## Why
+
+Login to digiarchiv expires after 1 h of inactivity (`sessionTimeout: 3600`)
+and the server then silently treats the request as anonymous: HTTP 200, no
+`error`, only `pristupnost=A` data. The plugin detects expiry only by HTTP 401
+or error text, which never arrives, so a logged-in user who downloads again
+after a pause gets incomplete data without any warning (issue #72, verified
+manually in QGIS and against the live API).
+
+## What Changes
+
+- Before each download the plugin checks the login state with
+  `GET /api/user/islogged` whenever the user is (or should be) logged in –
+  i.e. an in-memory session exists or credentials are stored.
+- When the server answers `{"error": "nologged"}` and credentials are stored,
+  the plugin logs in again and continues the download with the new session.
+- When the re-login fails (or credentials are missing), the plugin warns in
+  the QGIS message bar that the download runs anonymously and returns only
+  records with access level A – not only in the log.
+- Removing the stored credentials (*Odebrat uložené přihlašovací údaje*)
+  also logs the session out on the server (`GET /api/user/logout`) and
+  drops it from memory; today it stays logged in until QGIS restarts.
+- When the check itself cannot be completed (network error, invalid JSON),
+  the download is not blocked; the plugin logs a warning and proceeds.
+- The existing error-text based detection (`_is_auth_error`) stays as
+  a fallback; it is documented as not triggered by the current server.
+- Version bump + changelog (`metadata.txt`, `CITATION.cff`).
+
+Out of scope:
+
+- Keeping the session alive in the background (polling `islogged` does not
+  extend it anyway).
+- Showing the user's access level in the UI (`islogged?wantsUser=true`).
+- Codelist updates: `amcr_codelists` calls the API with plain `requests`
+  without the session, so login state does not affect them today.
+
+## Capabilities
+
+### New Capabilities
+
+- `amcr-session`: login session against digiarchiv – validating the session
+  before a download, transparent re-login and informing the user when data
+  are downloaded anonymously.
+
+### Modified Capabilities
+
+<!-- none – openspec/specs/ is empty -->
+
+## Impact
+
+- Code: `amcr_viewer/amcr_dialog.py` (logout when credentials are
+  removed); `amcr_viewer/amcr_tools.py` (logout helper, new login-state check, call at the start
+  of `load_amcr_data`, message bar warning); `tests/smoke_test.py` (offline
+  test of the check with a mocked HTTP session).
+- API: one extra `GET /api/user/islogged` per download, only when the user is
+  logged in or has stored credentials; anonymous users are unaffected.
+- No new dependencies; Qt5/Qt6 compatibility rules from `AGENTS.md` apply.

openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/specs/amcr-session/spec.md

@@ -0,0 +1,70 @@
+# Spec Delta
+
+## Purpose
+
+Keeps a logged-in user's data downloads from digiarchiv running under a valid
+login, and makes it visible when a download falls back to anonymous access.
+
+## ADDED Requirements
+
+### Requirement: Login state is verified before a download
+Before starting a data download, the plugin SHALL ask the server whether the
+current session is logged in, whenever an in-memory session exists or login
+credentials are stored. Users with neither SHALL download anonymously without
+this check.
+
+#### Scenario: Valid session
+- **WHEN** a session exists and the server reports it as logged in
+- **THEN** the download proceeds with that session and no re-login happens
+
+#### Scenario: Anonymous user without stored credentials
+- **WHEN** no session exists and no credentials are stored
+- **THEN** no login-state request is sent and the download proceeds anonymously without a warning
+
+### Requirement: Expired login is renewed transparently
+When the server reports the session as not logged in and credentials are
+stored, the plugin SHALL log in again and run the whole download with the new
+session.
+
+#### Scenario: Session expired after inactivity
+- **WHEN** the user downloads data more than one hour after the previous download within the same QGIS run
+- **THEN** the plugin logs in again with the stored credentials and the download returns the same records as for a fresh login
+
+#### Scenario: No session yet, credentials stored
+- **WHEN** the first download after QGIS start is requested and credentials are stored
+- **THEN** the plugin logs in and verifies that the new session is logged in before downloading
+
+### Requirement: Anonymous fallback is reported to the user
+When the plugin expected to be logged in but cannot obtain a logged-in
+session, it SHALL show a warning in the QGIS message bar stating that the
+download runs anonymously and contains only records with access level A.
+
+#### Scenario: Re-login fails
+- **WHEN** the session has expired and logging in again with stored credentials fails
+- **THEN** a warning appears in the message bar and the download continues anonymously
+
+#### Scenario: Session expired and credentials removed
+- **WHEN** an in-memory session has expired and no credentials are stored any more
+- **THEN** a warning appears in the message bar and the download continues anonymously
+
+### Requirement: Failed state check does not block the download
+If the login-state check cannot be completed (network error or a response
+that is not valid JSON), the plugin SHALL log a warning and proceed with the
+download using the current session.
+
+#### Scenario: Login-state endpoint unreachable
+- **WHEN** the login-state request fails with a network error
+- **THEN** a warning is written to the log and the download is attempted as usual
+
+### Requirement: Removing stored credentials logs the user out
+When the user removes the stored credentials, the plugin SHALL log the
+current session out on the server and discard it, so that later downloads
+run anonymously without restarting QGIS.
+
+#### Scenario: Credentials removed while logged in
+- **WHEN** the user removes the stored credentials while a logged-in session exists
+- **THEN** the session is logged out on the server and the next download is anonymous without a warning
+
+#### Scenario: Server unreachable during logout
+- **WHEN** the logout request fails with a network error
+- **THEN** the session is still discarded locally and the user is told the next download will be anonymous

openspec/changes/archive/2026-10-02-fix-session-expiry-islogged/tasks.md

@@ -0,0 +1,53 @@
+# Tasks
+
+## 1. Login-state check
+
+- [x] 1.1 Add `_ensure_logged_in()` to `amcr_viewer/amcr_tools.py` per
+  design.md (statuses `anonymous` / `logged_in` / `relogged` / `fallback` /
+  `unknown`, `GET /api/user/islogged` with the current session, one re-login
+  on `nologged`); verify with `python3 tests/check_sources.py` and
+  `ruff check .`
+- [x] 1.2 Add a comment to `_is_auth_error` that the current server never
+  returns such an error on expiry and the check is kept as a fallback;
+  verify by reading the diff
+- [x] 1.3 Extend `tests/smoke_test.py` with offline cases using a fake
+  session object (valid session, `nologged` + successful re-login,
+  `nologged` + failed re-login, no credentials, network error); verify the
+  smoke test passes in `qgis/qgis:ltr` and `qgis/qgis:stable`
+
+## 2. Integration into the download
+
+- [x] 2.1 Call `_ensure_logged_in()` in `load_amcr_data` after the
+  re-entrancy guard, before the first query; on `fallback` push a message
+  bar warning (Czech, scoped `Qgis.MessageLevel.Warning`) that the download
+  runs anonymously and contains only access level A; verify by smoke test
+  and code review
+- [x] 2.2 Live check without credentials: anonymous download path sends no
+  `islogged` request and a made-up `JSESSIONID` yields `nologged`
+  (curl / probe script in scratch); verify outputs recorded in the PR
+- [x] 2.3 Update `README.md` if it describes login/session behaviour; verify
+  the text matches the new behaviour (or note that nothing needed changing)
+
+## 2b. Logout when credentials are removed
+
+- [x] 2b.1 Add `logout_from_api()` to `amcr_tools.py` and call it from
+  `LoginDialog._forget_credentials`; extend the smoke test (session
+  logged out + dropped, network error still drops it, no session = no
+  request); update README and changelog; verify smoke test ltr + stable
+- [x] 2b.2 Manual test in QGIS: log in, download, remove the stored
+  credentials, download again; verify the log shows "Uživatel odhlášen"
+  and the count drops to the anonymous one
+
+## 3. Release preparation and verification
+
+- [x] 3.1 Add changelog entries under v2.2.0 in `amcr_viewer/metadata.txt`
+  (the fix ships with 2.2.0; `CITATION.cff` already says 2.2.0 and
+  `date-released` moves on release day); verify both versions match
+- [x] 3.2 Run the full local check set from `AGENTS.md` (check_sources,
+  bandit, detect-secrets `--all-files`, flake8 `--isolated`, ruff,
+  pyqgis4-checker log empty, smoke test ltr + stable); verify all clean
+- [x] 3.3 Manual test in QGIS with a researcher account: download SN for
+  whole CZ, simulate expiry in the Python console with
+  `amcr_tools.AMCR_SESSION.get("https://digiarchiv.aiscr.cz/api/user/logout")`,
+  download again; verify log shows re-login and the count matches the
+  logged-in count (not the anonymous one)

openspec/config.yaml

@@ -0,0 +1,65 @@
+schema: spec-driven
+
+# Seeded from aiscr-management
+# .agents/canonical_configs/templates/openspec/config_seed.yaml;
+# from now on the content is owned by this repository.
+
+context: |
+  Repository: aiscr-qgis-amcr-viewer — QGIS plugin (AMČR Viewer) for
+  downloading and visualising data from the AMČR Digital Archive
+  (digiarchiv.aiscr.cz).
+
+  OpenSpec posture: change-tracked.
+  This is the local reading of a posture declared and owned by the
+  management hub (aiscr-management, .agents/sync/repos.toml):
+    - change-tracked — change-scoped planning artifacts live under
+      `openspec/changes/`; no durable capability specs are maintained here.
+  Do not edit this line to unblock work in progress. Changing posture is
+  a decision taken deliberately with the hub and then applied here.
+
+  When OpenSpec fires: behaviour-changing work (user-visible behaviour,
+  layer attributes, the digiarchiv API contract the plugin relies on,
+  stored settings), cross-repo work, and governance-touching work. Not
+  typo and formatting fixes, dependency or tool-pin bumps that change no
+  behaviour, or refreshing a generated surface from its source.
+
+  Repository conventions: `AGENTS.md` is the single source of truth
+  (Qt5/Qt6 rules, versioning, branches, checks). Plugin code lives in
+  `amcr_viewer/` (entry point `amcr_viewer.py`, API and layers in
+  `amcr_tools.py`, dialogs in `amcr_dialog.py`, codelists in
+  `amcr_codelists.py`). User documentation is `README.md` (English);
+  planning artifacts, commits and PRs are in Czech or English as the
+  author prefers, code and identifiers in English.
+
+rules:
+  proposal:
+    - State what changes for a user of the plugin, not only in the code
+    - Name the affected modules under amcr_viewer/ explicitly
+    - Say when the change depends on or affects the digiarchiv API or
+      another AIS CR repository, and where
+  specs:
+    - Use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY)
+    - Use Given/When/Then scenarios for testable contracts
+    - Describe behaviour the plugin guarantees, not how the code does it
+  design:
+    - Record the alternatives considered and why the chosen one won
+    - Respect the QGIS 3.44 minimum and Qt5/Qt6 rules from AGENTS.md
+    - Name the verification that will show the change worked
+  tasks:
+    - Order tasks so each one is independently verifiable
+    - Name the command or check that proves each group is done
+    - Include the version bump (metadata.txt + CITATION.cff) when
+      behaviour changes
+    - Include a final verification task that runs the checks from
+      AGENTS.md (check_sources, bandit, detect-secrets, flake8, ruff,
+      pyqgis4-checker, smoke test in qgis/qgis:ltr and :stable)
+
+operations:
+  apply:
+    guidance:
+      - Completed artifacts are not approval to implement; wait for an
+        explicit request to apply the change
+  archive:
+    guidance:
+      - Posture is change-tracked, so archive with --skip-specs (no
+        openspec/specs/ tree is maintained)

pyproject.toml

@@ -5,15 +5,14 @@
 # jen k tomu, aby ruff choval stejně v CI, lokálně i za rok. Bez explicitní
 # konfigurace se výchozí sada pravidel mezi verzemi ruffu mění.
 #
-# Konfigurace flake8 je záměrně jinde: v amcr_viewer/.flake8, protože ji
+# Flake8 záměrně žádnou konfiguraci nemá a běží s výchozími pravidly – stejně
-# musí najít i scanner na plugins.qgis.org.
+# jako scanner na plugins.qgis.org. Config soubor v balíčku by plugin
+# označil jako „Validated (configured)“.
 
 [tool.ruff]
 line-length = 79
 # QGIS 3.44 běží na Pythonu 3.9 a novějším
 target-version = "py39"
-# Generovaný výstup pyrcc, "All changes made in this file will be lost"
-extend-exclude = ["amcr_viewer/resources.py"]
 
 [tool.ruff.lint]
 select = [

tests/api_contract.py

@@ -0,0 +1,904 @@
+# -*- coding: utf-8 -*-
+"""
+API contract test – checks that the live digiarchiv / AMCR OAI API still
+answers the way the plugin reads it. Plain requests, no QGIS.
+
+The plugin under test is amcr_viewer/ on this branch; the expectations here
+describe what its parsers (amcr_tools.g/g_list, amcr_codelists._facet_name)
+actually consume, not the official API documentation.
+
+Status model (per check):
+  OK          – the answer matches the recorded expectation
+  DRIFT       – the answer differs, but the plugin tolerates the new shape
+  FAIL        – the answer differs in a way the plugin does not tolerate
+  UNAVAILABLE – network error / timeout / HTTP 5xx after retries
+
+Exit code is 1 when any check is FAIL or DRIFT, 0 otherwise (a run where
+everything is UNAVAILABLE is green but visible in the summary).
+
+Outage fast-fail: once a host is unreachable after the full retry cycle,
+every later request to that host returns UNAVAILABLE immediately (circuit
+breaker, no network I/O) – an all-unreachable run finishes in seconds.
+
+Run (from the repository root, outside the repo use uv --no-project so no
+uv.lock appears):
+
+    uv run -q --no-project --with requests==2.34.2 \\
+        python tests/api_contract.py
+
+Outputs:
+  * stdout: a Markdown table of all checks
+  * results-api_contract.json next to the script (cwd) with one entry per
+    check: name, status, detail, request URL
+  * the same table appended to $GITHUB_STEP_SUMMARY when set
+
+Test area (probe 2026-10-02, anonymous = pristupnost A only):
+  TEST_BBOX (Mikulov, south Moravia) 48.8,16.6,48.9,16.75
+    akce 185, lokalita 18, samostatny_nalez 2, pian 294
+  PAGINATION_BBOX (Praha) 49.9,14.3,50.2,14.7 – akce 20 635 records,
+  paginated with rows=100; only akce is paginated here, the other entities
+  have few enough records in the small bbox.
+
+Env overrides (for the outage simulation):
+  AMCR_DA_URL    base URL of digiarchiv (default
+                  https://digiarchiv.aiscr.cz)
+  AMCR_OAI_URL   base URL of the AMCR OAI endpoint (default
+                  https://api.aiscr.cz/2.2/oai)
+  AMCR_TIMEOUT   per-request timeout in seconds (default 30)
+"""
+
+import json
+import os
+import re
+import sys
+import time
+import urllib.parse
+import xml.etree.ElementTree as ET  # nosec B405
+
+import requests
+
+JOB = "api_contract"
+DA_URL = os.environ.get("AMCR_DA_URL", "https://digiarchiv.aiscr.cz")
+OAI_URL = os.environ.get("AMCR_OAI_URL", "https://api.aiscr.cz/2.2/oai")
+TIMEOUT = int(os.environ.get("AMCR_TIMEOUT", "30"))
+
+# Small test area chosen by probe (see module docstring). Filter values are
+# taken from live facets of this same bbox in the same run, never from the
+# bundled codelists.
+TEST_BBOX = "48.8,16.6,48.9,16.75"
+PAGINATION_BBOX = "49.9,14.3,50.2,14.7"
+
+# Entities the plugin downloads (typ_dat_vocab in amcr_tools.py).
+ENTITIES = ["akce", "lokalita", "samostatny_nalez"]
+
+# OAI sets, mirroring amcr_codelists.slovnicek (name -> OAI set).
+OAI_SETS = {
+    "obdobi": "heslo:obdobi",
+    "typ_akce": "heslo:akce_typ",
+    "areal": "heslo:areal",
+    "kraj": "ruian_kraj",
+    "organizace": "organizace",
+    "okres": "ruian_okres",
+    "katastr": "ruian_katastr",
+    "pian_presnost": "heslo:pian_presnost",
+    "typ_lokality": "heslo:lokalita_typ",
+    "druh_lokality": "heslo:lokalita_druh",
+    "jistota": "heslo:jistota_urceni",
+    "lokalita_zachovalost": "heslo:stav_dochovani",
+    "pristupnost": "heslo:pristupnost",
+    "nalez_kategorie": "heslo:predmet_druh_kat",
+    "druh_nalezu": "heslo:predmet_druh",
+    "specifikace": "heslo:predmet_specifikace",
+    "nalezove_okolnosti": "heslo:nalezove_okolnosti",
+}
+
+# Facet-backed codelists (name -> (entity, facet field)), mirroring
+# amcr_codelists.slovnicek.
+FACET_SETS = {
+    "vedouci": ("akce", "f_vedouci"),
+    "nalezce": ("samostatny_nalez", "f_nalezce"),
+}
+
+# Expected facet item shape, as read by amcr_codelists._facet_name:
+# list form [str, int] is the current API (Solr 10 / digiarchiv v4.1.0,
+# json.nl=arrarr); the object form {"name": str, ...} is the old API
+# (pre v4.1.0) which the plugin still tolerates -> DRIFT, not FAIL.
+# Any other shape (scalar, empty list item, dict without "name") would
+# break the plugin -> FAIL.
+FACET_ITEM_FORMS = [
+    ("list", lambda x: isinstance(x, list) and len(x) == 2
+     and isinstance(x[0], str) and isinstance(x[1], int)),
+    ("object", lambda x: isinstance(x, dict)
+     and isinstance(x.get("name"), str)),
+]
+
+NS = {
+    "oai": "http://www.openarchives.org/OAI/2.0/",
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "oai_dc": "http://www.openarchives.org/OAI/2.0/oai_dc/",
+}
+
+SESSION = requests.Session()
+SESSION.headers.update({"User-Agent": "amcr-viewer-api-monitor/1.0"})
+RESULTS = []
+DEPLOYED_VERSION = None
+
+RETRY_BACKOFF = (2, 8)  # seconds, after 1st and 2nd attempt
+
+# Circuit breaker (fast outage): netlocs that came back unreachable after
+# the full retry cycle. Every later request to such a host returns None
+# immediately, without network I/O – an all-unreachable run then takes
+# seconds instead of tens of minutes of per-check retries.
+DEAD_HOSTS = set()
+
+
+def _retry_get(url, params=None):
+    """GET with retries on network errors, timeouts and HTTP 5xx.
+
+    Returns the response, or None when unreachable after all attempts.
+    HTTP 4xx and error bodies with status 200 are real answers –
+    the caller judges them by the contract.
+
+    Once a host (netloc) is found unreachable after full retries, it is
+    added to DEAD_HOSTS and every later request to it returns None
+    without touching the network (see the module docstring).
+    """
+    netloc = urllib.parse.urlparse(url).netloc
+    if netloc in DEAD_HOSTS:
+        return None
+    for attempt in range(3):
+        try:
+            resp = SESSION.get(url, params=params, timeout=TIMEOUT)
+            if resp.status_code < 500:
+                return resp
+        except requests.exceptions.RequestException:
+            pass
+        if attempt < 2:
+            time.sleep(RETRY_BACKOFF[attempt])
+    DEAD_HOSTS.add(netloc)
+    return None
+
+
+def record(name, status, detail, url=""):
+    RESULTS.append({
+        "name": name,
+        "status": status,
+        "detail": detail,
+        "url": url,
+    })
+    print(f"  {status:<12} {name} – {detail}")
+
+
+def get_json(url, params=None):
+    """GET + JSON parse with a friendly error, or None when unreachable."""
+    resp = _retry_get(url, params)
+    if resp is None:
+        return None
+    try:
+        return resp.json()
+    except ValueError:
+        return {"_invalid_json": True, "_status": resp.status_code}
+
+
+def load_deployed_version():
+    """Reads the deployed digiarchiv version from the web bundle.
+
+    Missing version is a DRIFT of its own check, never a FAIL.
+    """
+    global DEPLOYED_VERSION
+    resp = _retry_get(DA_URL + "/home")
+    if resp is None:
+        record("deployed-version", "UNAVAILABLE",
+               f"{DA_URL}/home unreachable")
+        return False
+    scripts = re.findall(r'(?:src|href)="([^"]*\.js)"', resp.text)
+    version = None
+    for script in scripts:
+        jresp = _retry_get(DA_URL + "/" + script.lstrip("/"))
+        if jresp is None:
+            continue
+        match = re.search(r'raw:"(v\d[^"]*)"', jresp.text)
+        if match:
+            version = match.group(1)
+            break
+    if version:
+        DEPLOYED_VERSION = version
+        record("deployed-version", "OK", f"{version}")
+        return True
+    record("deployed-version", "DRIFT",
+           "git-describe string raw:\"v…\" not found in the web bundle "
+           f"({len(scripts)} scripts scanned)")
+    return False
+
+
+def check_translations():
+    url = DA_URL + "/api/assets/i18n/cs.json"
+    data = get_json(url)
+    if data is None:
+        record("i18n cs.json", "UNAVAILABLE", "unreachable")
+        return
+    if not isinstance(data, dict) or not data:
+        record("i18n cs.json", "FAIL",
+               f"expected a non-empty dict, got {type(data).__name__}",
+               url)
+        return
+    # A few codes the plugin translates via tr_code() in live records
+    sample = [k for k in data if k.startswith("HES-")]
+    if not sample:
+        record("i18n cs.json", "DRIFT",
+               "no HES-* keys found – tr_code would return codes verbatim",
+               url)
+        return
+    record("i18n cs.json", "OK",
+           f"{len(data)} keys, {len(sample)} HES-* codes", url)
+
+
+def _status_of_field(types, good, drift=None):
+    """OK/DRIFT/FAIL for a set of observed field types."""
+    bad = types - good
+    if not bad:
+        return "OK"
+    if drift and bad <= drift:
+        return "DRIFT"
+    return "FAIL"
+
+
+def _check_doc_fields(name, docs, fields, url):
+    """Checks per-doc field presence and value types the plugin reads.
+
+    fields: {key: (ok_types, drift_types)}
+    Value normalization: amcr_tools.g() reads doc.get(key) and str()'s it –
+    lists are read as first item. g_list() iterates the value. So both a
+    scalar and a list of scalars are consumed; dict values are read with
+    .get() by dedicated code paths.
+    """
+    for key, (good, drift) in fields.items():
+        types = set()
+        missing = 0
+        for doc in docs:
+            if key not in doc or doc[key] is None:
+                missing += 1
+            else:
+                v = doc[key]
+                if isinstance(v, list):
+                    for item in v:
+                        types.add(type(item).__name__)
+                else:
+                    types.add(type(v).__name__)
+        if missing == len(docs):
+            record(f"{name} {key}", "FAIL",
+                   f"missing in all {len(docs)} docs", url)
+            continue
+        status = _status_of_field(types, good, drift)
+        detail = (f"types {sorted(types)}, "
+                  f"{missing}/{len(docs)} docs without the key")
+        record(f"{name} {key}", status, detail, url)
+
+
+def fetch_entity_docs(entity, bbox, rows=500):
+    """Main query exactly the way the plugin sends it. None = unavailable."""
+    params = {
+        "mapa": "true",
+        "sort": "ident_cely asc",
+        "entity": entity,
+        "rows": rows,
+        "loc_rpt": bbox,
+    }
+    url = DA_URL + "/api/search/query"
+    data = get_json(url, params)
+    if data is None:
+        return None, None
+    if "response" not in data:
+        return {}, data
+    return data["response"], data
+
+
+def check_main_queries():
+    """Main query per entity: keys and value types the plugin reads."""
+    strset = {"str"}
+    specs = {
+        "akce": {
+            "ident_cely": (strset, None),
+            "loc": (strset, None),  # g_list -> list of str
+            "pristupnost": (strset, None),
+            "az_okres": (strset, None),
+            "katastr": (strset, None),
+            "akce_hlavni_vedouci": (strset, None),
+            "akce_organizace": (strset, None),
+            "akce_specifikace_data": (strset, None),
+            "akce_datum_zahajeni": (strset, None),
+            "akce_datum_ukonceni": (strset, None),
+            "akce_hlavni_typ": (strset, None),
+            "akce_vedlejsi_typ": (strset, None),
+            "akce_je_nz": ({"bool"}, None),
+            "akce_projekt": (strset, None),
+            "az_dj_pian": (strset, None),
+            "az_chranene_udaje": ({"dict"}, None),
+            "akce_chranene_udaje": ({"dict"}, None),
+            "az_dokumentacni_jednotka": ({"dict"}, None),
+        },
+        "lokalita": {
+            "ident_cely": (strset, None),
+            "loc": (strset, None),
+            "pristupnost": (strset, None),
+            "az_okres": (strset, None),
+            "katastr": (strset, None),
+            "az_dj_pian": (strset, None),
+            "az_chranene_udaje": ({"dict"}, None),
+            "lokalita_chranene_udaje": ({"dict"}, None),
+            "lokalita_druh": (strset, None),
+            "lokalita_typ_lokality": (strset, None),
+            "lokalita_zachovalost": (strset, None),
+            "az_dokumentacni_jednotka": ({"dict"}, None),
+        },
+        "samostatny_nalez": {
+            "ident_cely": (strset, None),
+            "loc": (strset, None),
+            "pristupnost": (strset, None),
+            "samostatny_nalez_nalezce": (strset, None),
+            "samostatny_nalez_hloubka": ({"int", "float", "str"}, None),
+            "samostatny_nalez_okres": (strset, None),
+            "samostatny_nalez_chranene_udaje": ({"dict"}, None),
+            "samostatny_nalez_druh_nalezu": (strset, None),
+            "samostatny_nalez_obdobi": (strset, None),
+            "samostatny_nalez_specifikace": (strset, None),
+            "samostatny_nalez_datum_nalezu": (strset, None),
+            "samostatny_nalez_pocet": ({"str", "int", "float"}, None),
+        },
+    }
+    docs_by_entity = {}
+    for entity in ENTITIES:
+        resp, raw = fetch_entity_docs(entity, TEST_BBOX)
+        url = DA_URL + "/api/search/query"
+        if resp is None:
+            record(f"query {entity}", "UNAVAILABLE", "unreachable", url)
+            continue
+        if "numFound" not in resp and "docs" not in resp:
+            record(f"query {entity}", "FAIL",
+                   f"no response block: {json.dumps(raw)[:200]}", url)
+            continue
+        num_found = resp.get("numFound")
+        if not isinstance(num_found, int):
+            record(f"query {entity} numFound", "FAIL",
+                   f"expected int, got {type(num_found).__name__}", url)
+            continue
+        docs = resp.get("docs", [])
+        if not docs:
+            record(f"query {entity}", "FAIL",
+                   f"0 docs for the test bbox (numFound={num_found}) – "
+                   "the test area has no records", url)
+            continue
+        record(f"query {entity}", "OK",
+               f"numFound {num_found}, {len(docs)} docs", url)
+        docs_by_entity[entity] = docs
+        _check_doc_fields(f"{entity}", docs, specs[entity], url)
+
+    return docs_by_entity
+
+
+def check_numfound_int():
+    url = DA_URL + "/api/search/query"
+    for entity in ENTITIES:
+        resp, _ = fetch_entity_docs(entity, TEST_BBOX, rows=0)
+        if resp is None:
+            record(f"numFound {entity}", "UNAVAILABLE", "unreachable", url)
+            continue
+        if isinstance(resp.get("numFound"), int):
+            record(f"numFound {entity}", "OK", f"{resp['numFound']}", url)
+        else:
+            record(f"numFound {entity}", "FAIL",
+                   f"expected int, got {type(resp.get('numFound')).__name__}",
+                   url)
+
+
+def fetch_facets(entity, bbox=None):
+    """Facet request exactly the way amcr_codelists.fetch_set sends it."""
+    params = {
+        "entity": entity,
+        "rows": 0,
+        "noFacets": "false",
+        "onlyFacets": "true",
+    }
+    if bbox:
+        params["loc_rpt"] = bbox
+    url = DA_URL + "/api/search/query"
+    data = get_json(url, params)
+    if data is None:
+        return None
+    try:
+        return data["facet_counts"]["facet_fields"]
+    except (KeyError, TypeError):
+        return {}
+
+
+def check_facet_sets():
+    """Facet-backed codelists vedouci/nalezce: field exists, item shape."""
+    for name, (entity, field) in FACET_SETS.items():
+        url = DA_URL + "/api/search/query"
+        ff = fetch_facets(entity)
+        if ff is None:
+            record(f"facet {name}", "UNAVAILABLE", "unreachable", url)
+            continue
+        if field not in ff:
+            record(f"facet {name}", "FAIL",
+                   f"facet field {field} missing from entity {entity}", url)
+            continue
+        items = ff[field]
+        if not isinstance(items, list):
+            record(f"facet {name}", "FAIL",
+                   f"expected a list of items, got {type(items).__name__}",
+                   url)
+            continue
+        if not items:
+            record(f"facet {name}", "FAIL",
+                   f"facet field {field} came back empty", url)
+            continue
+        # classify each item's shape
+        bad = []
+        shapes = set()
+        for item in items:
+            for shape, test in FACET_ITEM_FORMS:
+                if test(item):
+                    shapes.add(shape)
+                    break
+            else:
+                bad.append(item)
+        if bad:
+            record(f"facet {name}", "FAIL",
+                   f"{len(bad)}/{len(items)} items in an unknown shape, "
+                   f"e.g. {json.dumps(bad[0])[:120]}", url)
+        elif shapes == {"list"}:
+            record(f"facet {name}", "OK",
+                   f"{len(items)} items, shape [value, count]", url)
+        elif shapes == {"object"}:
+            record(f"facet {name}", "DRIFT",
+                   f"{len(items)} items in the OLD object shape "
+                   '{"name": …} – the plugin still tolerates it via '
+                   "_facet_name, but this is a Solr json.nl change; "
+                   "expectation recorded: [value, count]", url)
+        else:
+            record(f"facet {name}", "DRIFT",
+                   f"mixed shapes {sorted(shapes)}", url)
+
+
+def check_oai_sets():
+    """Every OAI set in slovnicek: first page + resumptionToken paging."""
+    url = OAI_URL
+    for name, oai_set in OAI_SETS.items():
+        resp = _retry_get(url, params={
+            "verb": "ListRecords",
+            "metadataPrefix": "oai_dc",
+            "set": oai_set,
+        })
+        if resp is None:
+            record(f"oai {name}", "UNAVAILABLE", "unreachable", url)
+            continue
+        try:
+            root = ET.fromstring(resp.content)  # nosec B405 B314
+        except ET.ParseError as e:
+            record(f"oai {name}", "FAIL", f"XML parse error: {e}", url)
+            continue
+        error = root.find(".//oai:error", NS)
+        if error is not None:
+            record(f"oai {name}", "FAIL",
+                   f"OAI error {error.get('code')}: "
+                   f"{(error.text or '')[:100]}", url)
+            continue
+        records = root.findall(".//oai:record", NS)
+        if not records:
+            record(f"oai {name}", "FAIL",
+                   f"set {oai_set} returned no records", url)
+            continue
+        # record shape: identifier, titles, dc payload
+        ok_shape = all(
+            r.find(".//oai_dc:dc", NS) is not None
+            and r.find(".//dc:identifier", NS) is not None
+            for r in records
+        )
+        if not ok_shape:
+            record(f"oai {name}", "FAIL",
+                   "record missing oai_dc:dc or dc:identifier", url)
+            continue
+        token = root.find(".//oai:resumptionToken", NS)
+        token_ok = True
+        if token is not None and token.text:
+            # follow one page of the resumption token, the way fetch_set
+            # does; a broken token means an incomplete codelist
+            resp2 = _retry_get(url, params={
+                "verb": "ListRecords",
+                "resumptionToken": token.text,
+            })
+            if resp2 is None:
+                record(f"oai {name}", "UNAVAILABLE",
+                       "first page OK, token page unreachable", url)
+                continue
+            try:
+                root2 = ET.fromstring(resp2.content)  # nosec B405 B314
+            except ET.ParseError as e:
+                record(f"oai {name}", "FAIL",
+                       f"token page XML parse error: {e}", url)
+                continue
+            recs2 = root2.findall(".//oai:record", NS)
+            if not recs2:
+                token_ok = False
+            time.sleep(0.5)  # the plugin pauses between OAI pages
+        if token_ok:
+            desc = f"{len(records)} records"
+            if token is not None and token.text:
+                desc += ", token page followed"
+            record(f"oai {name}", "OK", desc, url)
+        else:
+            record(f"oai {name}", "FAIL",
+                   "resumptionToken page returned no records", url)
+
+
+def check_pagination():
+    """rows=100 pages over a larger area must not overlap."""
+    url = DA_URL + "/api/search/query"
+    seen = []
+    total = None
+    page = 0
+    while True:
+        params = {
+            "mapa": "true",
+            "sort": "ident_cely asc",
+            "entity": "akce",
+            "rows": 100,
+            "loc_rpt": PAGINATION_BBOX,
+        }
+        if page > 0:
+            params["page"] = page
+        data = get_json(url, params)
+        if data is None:
+            record("pagination akce", "UNAVAILABLE", "unreachable", url)
+            return
+        if "response" not in data:
+            record("pagination akce", "FAIL",
+                   f"error body on page {page}", url)
+            return
+        resp = data["response"]
+        if total is None:
+            total = resp.get("numFound")
+            if not isinstance(total, int):
+                record("pagination akce", "FAIL",
+                       "numFound is not an int", url)
+                return
+        docs = resp.get("docs", [])
+        if not docs:
+            break
+        seen.extend([d.get("ident_cely") for d in docs])
+        if len(seen) >= total:
+            break
+        page += 1
+        if page > 220:  # safety stop
+            break
+    unique = set(seen)
+    if len(unique) != len(seen):
+        dupes = len(seen) - len(unique)
+        record("pagination akce", "FAIL",
+               f"{dupes} duplicate ids across {page + 1} pages "
+               f"({len(seen)} ids)", url)
+    elif len(unique) < total:
+        record("pagination akce", "FAIL",
+               f"downloaded {len(unique)} of numFound {total}", url)
+    else:
+        record("pagination akce", "OK",
+               f"{len(unique)} unique ids across {page + 1} pages, "
+               f"numFound {total}", url)
+
+
+def check_bbox_restriction():
+    """loc_rpt must actually restrict: bbox count << global count."""
+    url = DA_URL + "/api/search/query"
+    for entity in ENTITIES:
+        resp, _ = fetch_entity_docs(entity, TEST_BBOX, rows=0)
+        if resp is None:
+            record(f"bbox {entity}", "UNAVAILABLE", "unreachable", url)
+            continue
+        global_resp = get_json(url, params={
+            "mapa": "true", "sort": "ident_cely asc", "entity": entity,
+            "rows": 0,
+        })
+        if global_resp is None or "response" not in global_resp:
+            record(f"bbox {entity}", "UNAVAILABLE", "global query failed",
+                   url)
+            continue
+        n_bbox = resp.get("numFound")
+        n_all = global_resp["response"].get("numFound")
+        if not isinstance(n_bbox, int) or not isinstance(n_all, int):
+            record(f"bbox {entity}", "FAIL", "numFound not int", url)
+            continue
+        if n_bbox >= n_all:
+            record(f"bbox {entity}", "FAIL",
+                   f"loc_rpt did not restrict: {n_bbox} vs {n_all} global",
+                   url)
+        else:
+            record(f"bbox {entity}", "OK",
+                   f"{n_bbox} in bbox vs {n_all} global", url)
+
+
+def check_pian_batch(docs_by_entity):
+    """PIAN batch geometry query, exactly the way load_amcr_data sends it."""
+    url = DA_URL + "/api/search/query"
+    if "akce" not in docs_by_entity:
+        record("pian-batch", "UNAVAILABLE",
+               "depends on the akce query, which is unavailable", url)
+        return
+    pian_ids = []
+    for doc in docs_by_entity["akce"]:
+        for dj in doc.get("az_dokumentacni_jednotka") or []:
+            dj_pian = dj.get("dj_pian") or {}
+            if dj_pian.get("id"):
+                pian_ids.append(dj_pian["id"])
+    if not pian_ids:
+        record("pian-batch", "FAIL",
+               "no dj_pian ids found in the akce docs", url)
+        return
+    batch = pian_ids[:50]  # small on purpose
+    fq = "ident_cely:(" + " OR ".join(batch) + ")"
+    data = get_json(url, params={
+        "mapa": "true",
+        "entity": "pian",
+        "q": fq,
+        "rows": len(batch),
+        "fl": "ident_cely,pian_typ,pian_chranene_udaje,pian_presnost",
+    })
+    if data is None:
+        record("pian-batch", "UNAVAILABLE", "unreachable", url)
+        return
+    if "response" not in data:
+        record("pian-batch", "FAIL",
+               f"error body: {json.dumps(data)[:200]}", url)
+        return
+    docs = data["response"].get("docs", [])
+    if not docs:
+        record("pian-batch", "FAIL", "0 docs for a known PIAN id batch", url)
+        return
+    with_wkt = 0
+    for d in docs:
+        raw = d.get("pian_chranene_udaje")
+        if isinstance(raw, list) and raw:
+            raw = raw[0]
+        jdata = (json.loads(raw) if isinstance(raw, str) else (raw or {}))
+        if isinstance(jdata, dict) and (
+            jdata.get("geom_sjtsk_wkt") or jdata.get("geom_wkt")
+        ):
+            with_wkt += 1
+    if with_wkt == len(docs):
+        record("pian-batch", "OK",
+               f"{len(docs)} PIAN docs, all with WKT geometry", url)
+    elif with_wkt:
+        record("pian-batch", "DRIFT",
+               f"{with_wkt}/{len(docs)} PIAN docs with WKT – "
+               "records without geometry are skipped by the plugin", url)
+    else:
+        record("pian-batch", "FAIL",
+               "no geom_sjtsk_wkt / geom_wkt in pian_chranene_udaje", url)
+
+
+def check_filters(docs_by_entity):
+    """Every filter key the dialog builds, values from live facets."""
+    url = DA_URL + "/api/search/query"
+    # (entity, filter key, facet field it draws its value from)
+    plan = [
+        ("akce", "f_kraj"), ("akce", "f_okres"), ("akce", "f_katastr"),
+        ("akce", "f_obdobi"), ("akce", "f_areal"),
+        ("akce", "f_pian_presnost"), ("akce", "f_typ_vyzkumu"),
+        ("akce", "f_vedouci"), ("akce", "f_organizace"),
+        ("lokalita", "f_typ_lokality"), ("lokalita", "f_druh_lokality"),
+        ("lokalita", "f_jistota"), ("lokalita", "f_lokalita_zachovalost"),
+        ("samostatny_nalez", "f_kategorie"),
+        ("samostatny_nalez", "f_druh_nalezu"),
+        ("samostatny_nalez", "f_specifikace"),
+        ("samostatny_nalez", "f_nalezove_okolnosti"),
+        ("samostatny_nalez", "f_nalezce"),
+    ]
+    for entity, key in plan:
+        ff = fetch_facets(entity, bbox=TEST_BBOX)
+        if ff is None:
+            record(f"filter {entity}.{key}", "UNAVAILABLE", "unreachable",
+                   url)
+            continue
+        items = ff.get(key) or []
+        if not items:
+            record(f"filter {entity}.{key}", "FAIL",
+                   f"no facet values for {key} in the test bbox", url)
+            continue
+        item = items[0]
+        value = item[0] if isinstance(item, list) else item.get("name")
+        if not value:
+            record(f"filter {entity}.{key}", "FAIL",
+                   f"facet item for {key} has no value", url)
+            continue
+        params = {
+            "mapa": "true",
+            "sort": "ident_cely asc",
+            "entity": entity,
+            "rows": 1,
+            "loc_rpt": TEST_BBOX,
+            key: [f"{value}:or"],
+        }
+        data = get_json(url, params)
+        if data is None:
+            record(f"filter {entity}.{key}", "UNAVAILABLE", "unreachable",
+                   url)
+            continue
+        if "response" not in data:
+            record(f"filter {entity}.{key}", "FAIL",
+                   f"API error for value {value!r}: "
+                   f"{json.dumps(data)[:150]}", url)
+            continue
+        num = data["response"].get("numFound")
+        record(f"filter {entity}.{key}", "OK",
+               f"value {value!r} accepted, numFound {num}", url)
+
+
+def check_date_ranges():
+    """Date range filter, sent the way the dialog builds it."""
+    url = DA_URL + "/api/search/query"
+    plan = [
+        ("akce", "akce_datum_zahajeni"),
+        ("akce", "akce_datum_ukonceni"),
+        ("samostatny_nalez", "samostatny_nalez_datum_nalezu"),
+    ]
+    for entity, field in plan:
+        params = {
+            "mapa": "true", "sort": "ident_cely asc", "entity": entity,
+            "rows": 1, "loc_rpt": TEST_BBOX,
+            field: "1900-01-01,2030-12-31",
+        }
+        data = get_json(url, params)
+        if data is None:
+            record(f"date {entity}.{field}", "UNAVAILABLE", "unreachable",
+                   url)
+            continue
+        if "response" not in data:
+            record(f"date {entity}.{field}", "FAIL",
+                   f"error body: {json.dumps(data)[:150]}", url)
+            continue
+        record(f"date {entity}.{field}", "OK",
+               f"numFound {data['response'].get('numFound')}", url)
+
+
+def check_special_params():
+    """pristupnost, posevidence, proj_akce – sent as the dialog sends."""
+    url = DA_URL + "/api/search/query"
+    plan = [
+        ("akce", {"pristupnost": ["A:or"]}),
+        ("akce", {"posevidence": "true"}),
+        ("akce", {"proj_akce": "true"}),
+    ]
+    for entity, extra in plan:
+        key = list(extra)[0]
+        params = {
+            "mapa": "true", "sort": "ident_cely asc", "entity": entity,
+            "rows": 1, "loc_rpt": TEST_BBOX, **extra
+        }
+        data = get_json(url, params)
+        if data is None:
+            record(f"param {entity}.{key}", "UNAVAILABLE", "unreachable",
+                   url)
+            continue
+        if "response" not in data:
+            record(f"param {entity}.{key}", "FAIL",
+                   f"error body: {json.dumps(data)[:150]}", url)
+            continue
+        record(f"param {entity}.{key}", "OK",
+               f"numFound {data['response'].get('numFound')}", url)
+
+
+def check_error_answers():
+    """Invalid parameter and unknown entity must be an error body, not
+    an empty result – the plugin reads the absence of 'response'."""
+    url = DA_URL + "/api/search/query"
+    data = get_json(url, params={
+        "entity": "akce", "akce_datum_zahajeni": "notadate"})
+    if data is None:
+        record("error invalid-parameter", "UNAVAILABLE", "unreachable", url)
+    elif isinstance(data, dict) and data.get("error"):
+        record("error invalid-parameter", "OK",
+               f"error body: {str(data['error'])[:100]}", url)
+    elif isinstance(data, dict) and "response" in data:
+        record("error invalid-parameter", "FAIL",
+               "invalid date was accepted as a normal response", url)
+    else:
+        record("error invalid-parameter", "FAIL",
+               f"unexpected body: {json.dumps(data)[:150]}", url)
+
+    data = get_json(url, params={"entity": "neexistujici_entity", "rows": 1})
+    if data is None:
+        record("error unknown-entity", "UNAVAILABLE", "unreachable", url)
+    elif isinstance(data, dict) and data.get("error"):
+        record("error unknown-entity", "OK",
+               f"error body: {str(data['error'])[:100]}", url)
+    elif isinstance(data, dict) and "response" in data:
+        record("error unknown-entity", "FAIL",
+               "unknown entity was accepted as a normal response", url)
+    else:
+        record("error unknown-entity", "FAIL",
+               f"unexpected body: {json.dumps(data)[:150]}", url)
+
+
+def check_login_error_path():
+    """login_to_api with wrong credentials: session None, error 'auth'."""
+    url = DA_URL + "/api/user/login"
+    # Deliberately wrong, obviously fake credentials – nothing secret.
+    wrong_user = "test@example.invalid"
+    wrong_login_value = "neutron-failure-horse-battery"
+    try:
+        resp = SESSION.post(
+            url,
+            json={"user": wrong_user, "pwd": wrong_login_value},
+            timeout=TIMEOUT,
+        )
+    except requests.exceptions.RequestException as e:
+        record("login wrong-credentials", "UNAVAILABLE",
+               f"{type(e).__name__}: {e}", url)
+        return
+    if resp.status_code >= 500:
+        record("login wrong-credentials", "UNAVAILABLE",
+               f"HTTP {resp.status_code}", url)
+        return
+    try:
+        body = resp.json()
+    except ValueError:
+        record("login wrong-credentials", "FAIL",
+               f"non-JSON body (HTTP {resp.status_code})", url)
+        return
+    if resp.status_code == 200 and body.get("error"):
+        record("login wrong-credentials", "OK",
+               f"error body: {str(body['error'])[:80]}", url)
+    elif resp.status_code in (401, 403):
+        record("login wrong-credentials", "OK",
+               f"HTTP {resp.status_code}", url)
+    else:
+        record("login wrong-credentials", "FAIL",
+               f"wrong credentials accepted (HTTP {resp.status_code}, "
+               f"body {json.dumps(body)[:120]})", url)
+
+
+def write_outputs():
+    """results JSON + Markdown table to stdout and GITHUB_STEP_SUMMARY."""
+    path = f"results-{JOB}.json"
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(RESULTS, f, ensure_ascii=False, indent=2)
+    lines = ["| check | status | detail |", "|---|---|---|"]
+    for r in RESULTS:
+        detail = str(r["detail"]).replace("|", "\\|").replace("\n", " ")
+        lines.append(f"| {r['name']} | {r['status']} | {detail} |")
+    table = "\n".join(lines)
+    print()
+    print(table)
+    summary = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary:
+        with open(summary, "a", encoding="utf-8") as f:
+            f.write(table + "\n")
+    print()
+    print(f"written: {path}")
+    bad = [r for r in RESULTS if r["status"] in ("FAIL", "DRIFT")]
+    print(f"checks: {len(RESULTS)}, FAIL/DRIFT: {len(bad)}")
+    return 1 if bad else 0
+
+
+def main():
+    print(f"API contract test against {DA_URL}")
+    print(f"test bbox: {TEST_BBOX} (Mikulov)")
+    load_deployed_version()
+    check_translations()
+    docs_by_entity = check_main_queries()
+    check_numfound_int()
+    check_facet_sets()
+    check_oai_sets()
+    check_pagination()
+    check_bbox_restriction()
+    check_pian_batch(docs_by_entity)
+    check_filters(docs_by_entity)
+    check_date_ranges()
+    check_special_params()
+    check_error_answers()
+    check_login_error_path()
+    return write_outputs()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/api_monitor_report.py

@@ -0,0 +1,245 @@
+# -*- coding: utf-8 -*-
+"""
+Issue reporting for the daily API monitor – turns the result JSONs of both
+test jobs into one tracking issue (label api-monitor) via gh.
+
+Cases (design decision 8):
+  * any FAIL/DRIFT, no open issue yet -> create it
+  * open issue, changed fingerprint (sorted names of non-OK checks,
+    stored in an HTML comment in the issue body) -> comment + update body
+  * open issue, identical fingerprint -> do nothing
+  * every check OK, open issue -> close it with a comment
+  * no FAIL/DRIFT but some UNAVAILABLE -> leave the issue as it is
+  * a job without its result file counts as one FAIL named after the job
+
+Runs only for schedule/workflow_dispatch on the default branch (the
+workflow guards it, the script trusts its inputs). Issue text is Czech,
+not hard-wrapped (GitHub GFM re-flows anyway).
+
+Dry run: API_MONITOR_DRY_RUN=1 prints the gh commands instead of
+executing them, and does not touch GitHub. Existing-issue input for
+local testing: API_MONITOR_EXISTING_ISSUE=<number> (simulate an open
+issue; the search is skipped).
+
+Usage inside the reporting job:
+
+    python3 tests/api_monitor_report.py <results-dir> <run-url>
+
+The deployed digiarchiv version is read from the deployed-version check
+in the contract results.
+
+Exit code: 0 always – a reporting problem must not mask the test results
+(the job's conclusion is already decided by the test jobs).
+"""
+
+import json
+import os
+import subprocess  # nosec B404 - volá jen gh se seznamem argumentů
+import sys
+
+LABEL = "api-monitor"
+FINGERPRINT_MARK = "<!-- api-monitor-fingerprint"
+
+RESULTS_DIR = sys.argv[1] if len(sys.argv) > 1 else "results"
+RUN_URL = sys.argv[2] if len(sys.argv) > 2 else ""
+# Filled in main() from the deployed-version check of the contract test
+VERSION = ""
+
+DRY = os.environ.get("API_MONITOR_DRY_RUN") == "1"
+EXISTING_ISSUE = os.environ.get("API_MONITOR_EXISTING_ISSUE", "")
+# Test hook: stands in for the body of the existing issue, so the
+# identical-fingerprint case can be exercised without GitHub
+EXISTING_BODY = os.environ.get("API_MONITOR_EXISTING_BODY", "")
+
+JOBS = ["api_contract", "plugin_live"]
+
+
+def gh(args, input_text=None):
+    """Runs gh (or prints the command in a dry run)."""
+    cmd = ["gh"] + args
+    if DRY:
+        shown = " ".join(cmd)
+        if input_text:
+            shown += f"  <<'EOF'\n{input_text}EOF"
+        print(f"[dry-run] {shown}")
+        return None
+    return subprocess.run(  # nosec B603 B607
+        cmd, input=input_text, text=True, capture_output=True, check=False
+    )
+
+
+def load_checks():
+    """One list of check dicts; a missing result file is a FAIL."""
+    checks = []
+    missing = []
+    for job in JOBS:
+        path = os.path.join(RESULTS_DIR, f"results-{job}.json")
+        if not os.path.exists(path):
+            missing.append(job)
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            checks.extend(data)
+        except (OSError, ValueError) as e:
+            missing.append(job)
+            print(f"cannot read {path}: {e}")
+    for job in missing:
+        # A crashed script or an image pull failure – the run is broken
+        # even though no check had the chance to fail
+        checks.append({
+            "name": f"job {job}",
+            "status": "FAIL",
+            "detail": "job did not produce its result file",
+            "url": "",
+        })
+    return checks
+
+
+def find_open_issue():
+    """Number of the open issue with the api-monitor label, or None."""
+    if EXISTING_ISSUE:
+        return EXISTING_ISSUE
+    res = gh(["issue", "list", "--label", LABEL, "--state", "open",
+              "--json", "number", "--limit", "1"])
+    if res is None:
+        return None
+    if res.returncode != 0:
+        print(f"issue search failed: {res.stderr}")
+        return None
+    try:
+        issues = json.loads(res.stdout)
+    except ValueError:
+        return None
+    return str(issues[0]["number"]) if issues else None
+
+
+def fingerprint(checks):
+    """Sorted names of the FAIL/DRIFT checks – the issue identity.
+
+    UNAVAILABLE is left out on purpose: a flaky endpoint next to a real
+    break would otherwise change the fingerprint and add a comment on
+    every run.
+    """
+    return ",".join(sorted(
+        c["name"] for c in checks if c["status"] in ("FAIL", "DRIFT")))
+
+
+def issue_body(checks):
+    """Czech GFM body with the fingerprint hidden in an HTML comment."""
+    lines = []
+    lines.append("Denní kontrola API (`api_monitor.yml`) našla problémy.")
+    lines.append("")
+    if VERSION and VERSION != "none":
+        lines.append(f"Nasazená verze digiarchivu: **{VERSION}**")
+        lines.append("")
+    lines.append("| kontrola | stav | detail |")
+    lines.append("|---|---|---|")
+    for c in checks:
+        if c["status"] == "OK":
+            continue
+        detail = str(c.get("detail", "")).replace("|", "\\|")
+        lines.append(f"| {c['name']} | {c['status']} | {detail} |")
+    if RUN_URL:
+        lines.append("")
+        lines.append(f"Běh: {RUN_URL}")
+    lines.append("")
+    lines.append("Lokální reprodukce:")
+    lines.append("")
+    lines.append("```sh")
+    lines.append("uv run -q --no-project --with requests==2.34.2 "
+                 "python tests/api_contract.py")
+    lines.append("")
+    lines.append("docker run --rm -v \"$PWD:/work:ro\" -w /work "
+                 "--user \"$(id -u):$(id -g)\" -e HOME=/tmp "
+                 "-e AMCR_RESULTS_DIR=/tmp/results "
+                 "qgis/qgis:ltr python3 tests/api_plugin_live.py")
+    lines.append("```")
+    lines.append("")
+    # Fingerprint must stay the last line – it is read back as-is
+    lines.append(f"{FINGERPRINT_MARK}: {fingerprint(checks)} -->")
+    return "\n".join(lines)
+
+
+def read_fingerprint(body):
+    """Extracts the fingerprint from an issue body, or None."""
+    for line in body.splitlines():
+        line = line.strip()
+        if line.startswith(FINGERPRINT_MARK):
+            rest = line[len(FINGERPRINT_MARK):]
+            # strip the ": " separator and the closing "-->"
+            rest = rest[:-3].strip() if rest.endswith("-->") else rest
+            return rest.lstrip(":").strip() or None
+    return None
+
+
+def deployed_version(checks):
+    """Version string from the deployed-version check, or ""."""
+    for c in checks:
+        if c["name"] == "deployed-version" and c["status"] == "OK":
+            return str(c.get("detail", ""))
+    return ""
+
+
+def main():
+    global VERSION
+    checks = load_checks()
+    VERSION = deployed_version(checks)
+    non_ok = [c for c in checks if c["status"] != "OK"]
+    bad = [c for c in checks if c["status"] in ("FAIL", "DRIFT")]
+    unavailable = [c for c in checks if c["status"] == "UNAVAILABLE"]
+    print(f"checks: {len(checks)}, FAIL/DRIFT: {len(bad)}, "
+          f"UNAVAILABLE: {len(unavailable)}")
+
+    # The label must exist before it can be used; --force does not touch
+    # an existing one with the same name
+    gh(["label", "create", LABEL, "--force",
+        "--description", "Denní kontrola API monitoru",
+        "--color", "d93f0b"])
+
+    if bad:
+        issue = find_open_issue()
+        new_fp = fingerprint(checks)
+        if issue is None:
+            gh(["issue", "create", "--label", LABEL, "--title",
+                "API monitor: kontrola API digiarchivu selhala",
+                "--body-file", "-"], input_text=issue_body(checks))
+            print("issue created (or would be)")
+        else:
+            if EXISTING_BODY:
+                old_fp = read_fingerprint(EXISTING_BODY)
+            else:
+                res = gh(["issue", "view", issue, "--json", "body",
+                          "--jq", ".body"])
+                old_fp = None
+                if res is not None and res.returncode == 0:
+                    old_fp = read_fingerprint(res.stdout)
+            if old_fp == new_fp:
+                print(f"issue #{issue}: identical fingerprint, "
+                      "no new comment")
+            else:
+                comment = ("Stav kontrol se změnil "
+                           f"(otisk: {new_fp or 'prázdný'}).\n\n"
+                           + issue_body(checks))
+                gh(["issue", "comment", issue, "--body-file", "-"],
+                   input_text=comment)
+                gh(["issue", "edit", issue, "--body-file", "-"],
+                   input_text=issue_body(checks))
+                print(f"issue #{issue}: comment + body updated")
+    elif non_ok:
+        # Only UNAVAILABLE – an outage proves neither break nor recovery
+        print("only UNAVAILABLE checks, leaving the issue as it is")
+    else:
+        issue = find_open_issue()
+        if issue is None:
+            print("all checks OK and no open issue")
+        else:
+            comment = ("Všechny kontroly prošly, "
+                       f"zavírám. {RUN_URL}".rstrip())
+            gh(["issue", "close", issue, "--comment", comment])
+            print(f"issue #{issue} closed with a comment")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/api_plugin_live.py

@@ -0,0 +1,401 @@
+# -*- coding: utf-8 -*-
+"""
+Live plugin test – calls the plugin's own functions against the live AMČR
+API inside a real (headless) QGIS and checks they still produce non-empty,
+well-formed results. Where the contract test says *what* changed, this test
+says *whether users break*.
+
+It is the API-sensitive counterpart of tests/smoke_test.py, which is
+deliberately offline.
+
+Run it from the repository root inside the qgis/qgis Docker image
+(requests is bundled with QGIS):
+
+    docker run --rm -v "$PWD:/work:ro" -w /work \
+      --user "$(id -u):$(id -g)" -e HOME=/tmp \
+      -e AMCR_RESULTS_DIR=/tmp/results \
+      qgis/qgis:ltr python3 tests/api_plugin_live.py
+
+The plugin package is imported as a package (amcr_viewer.amcr_tools), so
+its relative imports work – a bare spec_from_file_location would make
+load_amcr_data swallow the import error into "0 records".
+
+Status model and outputs match tests/api_contract.py: OK / DRIFT / FAIL /
+UNAVAILABLE per check, results-plugin_live.json + a Markdown table on
+stdout and in $GITHUB_STEP_SUMMARY, exit 1 on any FAIL or DRIFT. A run
+where everything is UNAVAILABLE is green but visible in the summary.
+
+Test area (probe 2026-10-02, anonymous): the same Mikulov bbox as the
+contract test, 48.8,16.6,48.9,16.75 – akce 185, lokalita 18,
+samostatny_nalez 2, pian 294 records. The fake canvas extent uses it
+directly in EPSG:4326, so no coordinate transformation is involved.
+
+Thresholds (design decision 6):
+  * fetch_set per codelist set: >= 1 item and >= 50 % of that category's
+    row count in the bundled codelists/heslar.csv (a shrunken codelist is
+    the #67 symptom)
+  * load_amcr_data per data type: >= 1 layer with >= 1 feature, valid
+    geometry and the expected attribute fields
+
+Env overrides (outage simulation; the plugin's own URLs are hard-coded,
+so the overrides only steer the availability probe and the codelist
+sets, whose URLs live in a module dict). An unreachable host fails fast:
+after the full retry cycle of the first probe, later probes to the same
+host do no network I/O:
+  AMCR_DA_URL    digiarchiv base URL (default
+                  https://digiarchiv.aiscr.cz)
+  AMCR_OAI_URL   AMCR OAI base URL (default
+                  https://api.aiscr.cz/2.2/oai)
+  AMCR_TIMEOUT   per-request timeout in seconds (default 15)
+"""
+
+import csv
+import json
+import os
+import sys
+import traceback
+
+# Offscreen, otherwise the widgets would need an X server
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+
+RESULTS_DIR = os.environ.get("AMCR_RESULTS_DIR", os.getcwd())
+DA_URL = os.environ.get("AMCR_DA_URL", "https://digiarchiv.aiscr.cz")
+OAI_URL = os.environ.get("AMCR_OAI_URL", "https://api.aiscr.cz/2.2/oai")
+TIMEOUT = int(os.environ.get("AMCR_TIMEOUT", "15"))
+TEST_BBOX = "48.8,16.6,48.9,16.75"  # minLat,minLon,maxLat,maxLon (Mikulov)
+BBOX_MIN_LAT, BBOX_MIN_LON, BBOX_MAX_LAT, BBOX_MAX_LON = (
+    float(x) for x in TEST_BBOX.split(",")
+)
+
+RESULTS = []
+JOB = "plugin_live"
+UNAVAILABLE_DA = False
+UNAVAILABLE_OAI = False
+
+
+def record(name, status, detail):
+    RESULTS.append({"name": name, "status": status, "detail": detail,
+                    "url": ""})
+    print(f"  {status:<12} {name} – {detail}")
+
+
+import requests  # noqa: E402
+
+# ---------------------------------------------------------------- QGIS setup
+from qgis.core import (  # noqa: E402
+    Qgis,
+    QgsApplication,
+    QgsCoordinateReferenceSystem,
+    QgsProject,
+    QgsRectangle,
+)
+
+print(f"QGIS {Qgis.QGIS_VERSION.split('-')[0]}")
+QgsApplication.setPrefixPath(os.environ.get("QGIS_PREFIX_PATH", "/usr"),
+                             True)
+qgs = QgsApplication([], True)
+qgs.initQgis()
+
+import amcr_viewer.amcr_codelists as codelists  # noqa: E402
+import amcr_viewer.amcr_tools as tools  # noqa: E402
+
+# Point the codelist sets at the overridden base URLs (outage simulation).
+# The data-download URL inside load_amcr_data is hard-coded and cannot be
+# steered from here; when the probe says digiarchiv is unreachable, the
+# download checks are reported UNAVAILABLE without calling the plugin.
+if DA_URL != "https://digiarchiv.aiscr.cz" \
+        or OAI_URL != "https://api.aiscr.cz/2.2/oai":
+    _new = {}
+    for key, (base, api_set) in codelists.slovnicek.items():
+        if "digiarchiv" in base:
+            base = DA_URL + "/api/search/query"
+        else:
+            base = OAI_URL
+        _new[key] = (base, api_set)
+    codelists.slovnicek.clear()
+    codelists.slovnicek.update(_new)
+
+
+# ------------------------------------------------------------------ fakes
+class FakeMessageBar:
+    """Collects messageBar() messages so failures can be diagnosed."""
+
+    def __init__(self):
+        self.messages = []
+
+    def pushMessage(self, title, text, level=Qgis.MessageLevel.Info):
+        self.messages.append((title, str(text), level))
+
+
+class FakeIface:
+    def __init__(self):
+        self._bar = FakeMessageBar()
+
+    def messageBar(self):
+        return self._bar
+
+    def mapCanvas(self):
+        return fake_canvas
+
+
+class FakeMapSettings:
+    def __init__(self, crs):
+        self._crs = crs
+
+    def destinationCrs(self):
+        return self._crs
+
+
+class FakeCanvas:
+    """Map canvas whose extent is the test bbox in EPSG:4326."""
+
+    def __init__(self):
+        self._extent = QgsRectangle(
+            BBOX_MIN_LON, BBOX_MIN_LAT, BBOX_MAX_LON, BBOX_MAX_LAT
+        )
+        self._settings = FakeMapSettings(
+            QgsCoordinateReferenceSystem("EPSG:4326"))
+
+    def extent(self):
+        return self._extent
+
+    def mapSettings(self):
+        return self._settings
+
+
+fake_canvas = FakeCanvas()
+fake_iface = FakeIface()
+
+# amcr_tools does "from qgis.utils import iface", which binds None in a
+# headless run – patch the module attribute, not qgis.utils
+tools.iface = fake_iface
+
+
+# ------------------------------------------------------------------ checks
+# Circuit breaker (fast outage), the same as in tests/api_contract.py:
+# once a host (netloc) is unreachable after full retries, later probes to
+# it return False without network I/O, so an all-unreachable run finishes
+# in seconds instead of tens of minutes.
+DEAD_HOSTS = set()
+
+
+def probe(url, params=None):
+    """Availability probe with retries; True when the API answers.
+
+    Once a host is found unreachable after the full retry cycle, it is
+    added to DEAD_HOSTS and later probes to it fail immediately.
+    """
+    import time
+    import urllib.parse
+    netloc = urllib.parse.urlparse(url).netloc
+    if netloc in DEAD_HOSTS:
+        return False
+    for attempt in range(3):
+        try:
+            resp = requests.get(url, params=params, timeout=TIMEOUT)
+            if resp.status_code < 500:
+                return True
+        except requests.exceptions.RequestException:
+            pass
+        if attempt < 2:
+            time.sleep((2, 8)[attempt])
+    DEAD_HOSTS.add(netloc)
+    return False
+
+
+def bundled_counts():
+    """Row count per category in the bundled codelists/heslar.csv."""
+    path = os.path.join(ROOT, "amcr_viewer", "codelists", "heslar.csv")
+    counts = {}
+    # utf-8-sig: the CSV carries a BOM on purpose (Excel)
+    with open(path, encoding="utf-8-sig", newline="") as f:
+        for row in csv.DictReader(f, delimiter=";"):
+            cat = (row.get("Kategorie") or "").strip()
+            if cat:
+                counts[cat] = counts.get(cat, 0) + 1
+    return counts
+
+
+def check_translations():
+    if UNAVAILABLE_DA:
+        record("load_translations", "UNAVAILABLE",
+               "digiarchiv unreachable after retries")
+        return
+    tools.TRANSLATIONS.clear()
+    try:
+        tools.load_translations()
+    except Exception:
+        record("load_translations", "FAIL",
+               traceback.format_exc().rstrip().splitlines()[-1])
+        return
+    if tools.TRANSLATIONS:
+        record("load_translations", "OK",
+               f"{len(tools.TRANSLATIONS)} keys")
+    else:
+        record("load_translations", "FAIL",
+               "TRANSLATIONS stayed empty after load_translations()")
+
+
+def check_fetch_set():
+    """fetch_set per set in slovnicek against the live API."""
+    bundled = bundled_counts()
+    for name, (base_url, api_set) in codelists.slovnicek.items():
+        unavailable = (UNAVAILABLE_OAI if "digiarchiv" not in base_url
+                       else UNAVAILABLE_DA)
+        if unavailable:
+            record(f"fetch_set {name}", "UNAVAILABLE",
+                   "API unreachable after retries")
+            continue
+        try:
+            data = codelists.fetch_set(base_url, name, api_set)
+        except Exception:
+            record(f"fetch_set {name}", "FAIL",
+                   traceback.format_exc().rstrip().splitlines()[-1])
+            continue
+        if data is None:
+            record(f"fetch_set {name}", "FAIL", "cancelled (task)")
+            continue
+        if not data:
+            record(f"fetch_set {name}", "FAIL",
+                   f"set {api_set} returned 0 items – the #67 symptom")
+            continue
+        expected = bundled.get(name, 0)
+        if expected and len(data) < expected * 0.5:
+            record(f"fetch_set {name}", "FAIL",
+                   f"{len(data)} items < 50 % of {expected} bundled rows "
+                   "– a shrunken codelist is the #67 symptom")
+        else:
+            record(f"fetch_set {name}", "OK",
+                   f"{len(data)} items"
+                   + (f" (bundled: {expected})" if expected else ""))
+
+
+def _layer_specs(typ_dat):
+    """Expected attribute fields per data type, from amcr_tools.py."""
+    common = ["pian", "presnost", "pian_typ", "dj", "typ_dj", typ_dat,
+              "definicni_body", "odkaz_do_digiarchivu", "okres", "katastr",
+              "dalsi_katastry", "pristupnost"]
+    if typ_dat == "akce":
+        common += ["akce_lokalizace", "vedouci", "organizace",
+                   "specifikace_data", "zahajeni", "ukonceni",
+                   "hlavni_typ", "vedlejsi_typ", "zjisteni",
+                   "nahrazuje_NZ", "projekt"]
+    elif typ_dat == "lokalita":
+        common += ["nazev_lokality", "popis_lokality", "typ_lokality",
+                   "druh_lokality", "zachovalost"]
+    elif typ_dat == "samostatny_nalez":
+        common = [typ_dat, "definicni_body", "odkaz_do_digiarchivu",
+                  "okres", "katastr", "dalsi_katastry", "projekt",
+                  "nalezce", "datum", "okolnosti", "hloubka_cm",
+                  "lokalizace", "obdobi", "presna_datace", "nalez",
+                  "material", "pocet", "poznamka", "pred_org",
+                  "evidencni", "pristupnost"]
+    return common
+
+
+def check_load_amcr_data():
+    """load_amcr_data per data type on the test bbox (fake iface/canvas).
+
+    The call is synchronous in the main thread (load_amcr_data pumps the
+    event loop itself, it is not a QgsTask), so a plain call is enough.
+    """
+    for typ_dat in ["akce", "lokalita", "samostatny_nalez"]:
+        if UNAVAILABLE_DA:
+            record(f"load_amcr_data {typ_dat}", "UNAVAILABLE",
+                   "digiarchiv unreachable after retries")
+            continue
+        # Layers from a previous data type must not mix into the check
+        project = QgsProject.instance()
+        project.removeAllMapLayers()
+        try:
+            tools.load_amcr_data(fake_canvas, "true", None,
+                                 typ_dat=typ_dat, komponenty="false")
+        except Exception:
+            record(f"load_amcr_data {typ_dat}", "FAIL",
+                   traceback.format_exc().rstrip().splitlines()[-1])
+            continue
+        layers = [lyr for lyr in project.mapLayers().values()
+                  if "amcr_" in lyr.name().lower()]
+        if not layers:
+            record(f"load_amcr_data {typ_dat}", "FAIL",
+                   "no AMCR layers were added to the project; messageBar: "
+                   + "; ".join(m[1] for m in fake_iface._bar.messages[-3:]))
+            continue
+        total_features = sum(lyr.featureCount() for lyr in layers)
+        if total_features < 1:
+            record(f"load_amcr_data {typ_dat}", "FAIL",
+                   f"{len(layers)} layers but 0 features")
+            continue
+        # valid geometry + expected fields on the populated layers
+        problems = []
+        expected_fields = _layer_specs(typ_dat)
+        for layer in layers:
+            if layer.featureCount() == 0:
+                continue
+            fields = {f.name() for f in layer.fields()}
+            missing = [fl for fl in expected_fields if fl not in fields]
+            if missing:
+                problems.append(f"{layer.name()}: missing fields "
+                                f"{missing}")
+            for feat in layer.getFeatures():
+                geom = feat.geometry()
+                if (geom is None or geom.isNull()
+                        or not geom.isGeosValid()):
+                    problems.append(f"{layer.name()}: invalid geometry")
+                    break
+        if problems:
+            record(f"load_amcr_data {typ_dat}", "FAIL",
+                   "; ".join(problems))
+        else:
+            record(f"load_amcr_data {typ_dat}", "OK",
+                   f"{len(layers)} layers, {total_features} features, "
+                   "fields and geometry valid")
+
+
+def write_outputs():
+    os.makedirs(RESULTS_DIR, exist_ok=True)
+    path = os.path.join(RESULTS_DIR, f"results-{JOB}.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(RESULTS, f, ensure_ascii=False, indent=2)
+    lines = ["| check | status | detail |", "|---|---|---|"]
+    for r in RESULTS:
+        detail = str(r["detail"]).replace("|", "\\|").replace("\n", " ")
+        lines.append(f"| {r['name']} | {r['status']} | {detail} |")
+    table = "\n".join(lines)
+    print()
+    print(table)
+    summary = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary:
+        with open(summary, "a", encoding="utf-8") as f:
+            f.write(table + "\n")
+    print()
+    print(f"written: {path}")
+    bad = [r for r in RESULTS if r["status"] in ("FAIL", "DRIFT")]
+    print(f"checks: {len(RESULTS)}, FAIL/DRIFT: {len(bad)}")
+    return 1 if bad else 0
+
+
+def main():
+    global UNAVAILABLE_DA, UNAVAILABLE_OAI
+    print("live plugin test against the production AMČR API")
+    print(f"test bbox: {TEST_BBOX} (Mikulov)")
+    UNAVAILABLE_DA = not probe(
+        DA_URL + "/api/search/query", params={"entity": "akce", "rows": 0})
+    UNAVAILABLE_OAI = not probe(
+        OAI_URL, params={"verb": "Identify"})
+    if UNAVAILABLE_DA:
+        print("digiarchiv unreachable after retries")
+    if UNAVAILABLE_OAI:
+        print("AMČR OAI unreachable after retries")
+    check_translations()
+    check_fetch_set()
+    check_load_amcr_data()
+    qgs.exitQgis()
+    return write_outputs()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/check_sources.py

@@ -23,10 +23,6 @@ import sys
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 BALICEK = os.path.join(ROOT, "amcr_viewer")
 
-# Files that belong in the plugin package even though the upload scanner
-# would otherwise call them hidden
-POVOLENE_SKRYTE = {".flake8", ".bandit", ".secrets.baseline"}
-
 # Extensions that have no business inside a plugin package
 PODEZRELE = {".exe", ".dll", ".so", ".dylib", ".sh", ".bat", ".cmd",
              ".pyc", ".pyd", ".jar", ".bin"}
@@ -72,7 +68,9 @@ for cesta in vsechny_soubory():
     if rezim & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
         nalezy.append(f"{zkratka(cesta)}: spustitelná práva "
                       f"({stat.filemode(rezim)})")
-    if jmeno.startswith(".") and jmeno not in POVOLENE_SKRYTE:
+    # No exceptions: scanner config files (.flake8, .bandit,
+    # .secrets.baseline) would mark the upload "Validated (configured)"
+    if jmeno.startswith("."):
         nalezy.append(f"{zkratka(cesta)}: skrytý soubor v balíčku pluginu")
     if os.path.splitext(jmeno)[1].lower() in PODEZRELE:
         nalezy.append(f"{zkratka(cesta)}: podezřelý typ souboru")

tests/check_version_bump.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""
+Guards the release PR (version/vX.Y.Z -> main).
+
+Checks that the version actually moved forward and that the three places
+that name it agree, because plugins.qgis.org and Zenodo both read from
+files a human has to remember to touch by hand:
+
+* amcr_viewer/metadata.txt: version= must be higher than on main, and the
+  first changelog entry must be for that exact version
+* CITATION.cff: version must match metadata.txt, and date-released must
+  not be left pointing at the old release
+* the branch name (version/vX.Y.Z) must match metadata.txt, so a stray
+  push to the wrong release branch is caught before merge
+
+Run from the repository root:
+
+    python3 tests/check_version_bump.py <base_sha> <head_ref>
+"""
+
+import datetime
+import re
+import subprocess
+import sys
+
+METADATA = "amcr_viewer/metadata.txt"
+CITATION = "CITATION.cff"
+
+VERZE_METADATA = re.compile(r"^version=(.+)$", re.MULTILINE)
+VERZE_CITATION = re.compile(r"^version:\s*'?([^'\n]+)'?\s*$", re.MULTILINE)
+DATUM_CITATION = re.compile(r"^date-released:\s*'?([^'\n]+)'?\s*$",
+                             re.MULTILINE)
+# Přeskočí úvodní řádek "Plný seznam změn ... /vX.Y.Z" a najde první
+# skutečnou položku changelogu.
+POLOZKA_CHANGELOGU = re.compile(r"^\s+v([0-9][^\s(]*)\s*\(", re.MULTILINE)
+BRANCH_VERZE = re.compile(r"^version/v(.+)$")
+
+nalezy = []
+
+
+def nacti_na_base(base_sha, cesta):
+    vysledek = subprocess.run(
+        ["git", "show", f"{base_sha}:{cesta}"],
+        capture_output=True, text=True,
+    )
+    if vysledek.returncode != 0:
+        nalezy.append(f"{cesta}: na cílové větvi nejde přečíst "
+                       f"(git show {base_sha}:{cesta} selhalo)")
+        return None
+    return vysledek.stdout
+
+
+def nacti(cesta):
+    with open(cesta, encoding="utf-8") as f:
+        return f.read()
+
+
+def hledej(vzor, text, cesta, popis):
+    shoda = vzor.search(text)
+    if not shoda:
+        nalezy.append(f"{cesta}: {popis} nenalezeno")
+        return None
+    return shoda.group(1).strip()
+
+
+def verze_tuple(verze):
+    jadro = verze.split("-", 1)[0]
+    try:
+        return tuple(int(c) for c in jadro.split("."))
+    except ValueError:
+        return None
+
+
+def je_bump(stara, nova):
+    if stara == nova:
+        return False
+    stara_t, nova_t = verze_tuple(stara), verze_tuple(nova)
+    if stara_t is None or nova_t is None:
+        # Nestandardní formát verze – nejde spolehlivě porovnat čísly,
+        # stačí tedy, že se řetězec liší.
+        return True
+    if nova_t != stara_t:
+        return nova_t > stara_t
+    # Stejné jádro (např. "-alpha" přípona): bump platí, pokud se text
+    # liší a nejde o couvnutí z release na prerelease.
+    return "-" in stara or "-" not in nova
+
+
+def datum(text):
+    try:
+        return datetime.date.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("použití: check_version_bump.py <base_sha> <head_ref>")
+        return 2
+    base_sha, head_ref = sys.argv[1], sys.argv[2]
+
+    base_metadata = nacti_na_base(base_sha, METADATA)
+    base_citation = nacti_na_base(base_sha, CITATION)
+    head_metadata = nacti(METADATA)
+    head_citation = nacti(CITATION)
+
+    if base_metadata is None or base_citation is None:
+        # Bez base souborů nejde nic dalšího smysluplně ověřit.
+        print("Nálezy:")
+        for nalez in nalezy:
+            print(f"  {nalez}")
+        return 1
+
+    stara_verze = hledej(VERZE_METADATA, base_metadata, METADATA,
+                          "verze na cílové větvi (version=)")
+    nova_verze = hledej(VERZE_METADATA, head_metadata, METADATA,
+                         "verze (version=)")
+    stara_citation_verze = hledej(VERZE_CITATION, base_citation, CITATION,
+                                   "verze na cílové větvi (version:)")
+    nova_citation_verze = hledej(VERZE_CITATION, head_citation, CITATION,
+                                  "verze (version:)")
+    stare_datum = hledej(DATUM_CITATION, base_citation, CITATION,
+                          "date-released na cílové větvi")
+    nove_datum = hledej(DATUM_CITATION, head_citation, CITATION,
+                         "date-released")
+
+    if None in (stara_verze, nova_verze, stara_citation_verze,
+                nova_citation_verze, stare_datum, nove_datum):
+        print("Nálezy:")
+        for nalez in nalezy:
+            print(f"  {nalez}")
+        return 1
+
+    # 1. metadata.txt: verze musí jít dopředu.
+    if not je_bump(stara_verze, nova_verze):
+        nalezy.append(
+            f"{METADATA}: verze nepovýšena ({stara_verze} -> {nova_verze})")
+
+    # 2. metadata.txt: první položka changelogu musí patřit nové verzi.
+    prvni_polozka = POLOZKA_CHANGELOGU.search(head_metadata)
+    if not prvni_polozka:
+        nalezy.append(f"{METADATA}: v changelog= nenalezena žádná položka "
+                       f"'vX.Y.Z (...)'")
+    elif prvni_polozka.group(1) != nova_verze:
+        nalezy.append(
+            f"{METADATA}: první položka changelogu je pro "
+            f"v{prvni_polozka.group(1)}, ale version={nova_verze}")
+
+    # 3. CITATION.cff: verze musí souhlasit s metadata.txt.
+    if nova_citation_verze != nova_verze:
+        nalezy.append(
+            f"{CITATION}: version: {nova_citation_verze} neodpovídá "
+            f"{METADATA} version={nova_verze}")
+
+    # 4. CITATION.cff: date-released se musí posunout, a ne dozadu.
+    stary_datum_obj, novy_datum_obj = datum(stare_datum), datum(nove_datum)
+    if stary_datum_obj is None or novy_datum_obj is None:
+        nalezy.append(f"{CITATION}: date-released není platné datum "
+                       f"ISO 8601 ({stare_datum!r} -> {nove_datum!r})")
+    elif novy_datum_obj < stary_datum_obj:
+        nalezy.append(
+            f"{CITATION}: date-released couvlo ({stare_datum} -> "
+            f"{nove_datum})")
+    elif (nove_datum == stare_datum
+          and stara_citation_verze != nova_citation_verze):
+        nalezy.append(
+            f"{CITATION}: version se změnila, ale date-released zůstalo "
+            f"na {stare_datum}")
+
+    # 5. Název release větve musí odpovídat verzi, kterou nese.
+    shoda_branch = BRANCH_VERZE.match(head_ref)
+    if shoda_branch and shoda_branch.group(1) != nova_verze:
+        nalezy.append(
+            f"větev {head_ref!r} neodpovídá {METADATA} "
+            f"version={nova_verze}")
+
+    if nalezy:
+        print("Nálezy:")
+        for nalez in nalezy:
+            print(f"  {nalez}")
+        return 1
+    print(f"Kontrola verze a changelogu: v{stara_verze} -> v{nova_verze}, "
+          f"bez nálezů")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/smoke_test.py

@@ -19,6 +19,8 @@ import os
 import sys
 import traceback
 
+import requests
+
 # Offscreen, otherwise the dialogs need an X server
 os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
 
@@ -117,10 +119,545 @@ def filtr_datumu():
     return hodnota
 
 
+class FalesnaSession:
+    """Offline stand-in for requests.Session: returns canned JSON
+    bodies for GET /api/user/islogged and counts the requests."""
+
+    def __init__(self, tela):
+        # tela: a list of (body, exception) pairs – one per GET call,
+        # consumed in order; None body means raise the exception
+        self.tela = list(tela)
+        self.get_volani = 0
+
+    def get(self, url, timeout=0):
+        self.get_volani += 1
+        polozka = self.tela.pop(0)
+        # A bare dict is a plain body; (None, exception) means raise
+        if isinstance(polozka, tuple):
+            tela, vyjimka = polozka
+        else:
+            tela, vyjimka = polozka, None
+        if tela is None and vyjimka is not None:
+            raise vyjimka
+
+        class Odpoved:
+            def __init__(self, tela):
+                self.telo = tela
+                self.text = str(tela)
+
+            def json(self):
+                if isinstance(self.telo, Exception):
+                    raise self.telo
+                return self.telo
+
+        return Odpoved(tela)
+
+
+def prihlasovaci_stav():
+    """
+    _ensure_logged_in with a fake session and monkeypatched login /
+    credentials / _get_session – everything stays offline.
+
+    Each case: (name, expected status, islogged bodies of the current
+    session, islogged bodies after re-login, fake login result,
+    stored credentials, expected number of islogged GETs).
+    """
+    pripady = [
+        # Valid session – no re-login, no extra request
+        ("platná session", "logged_in",
+         [{"remaining": 3500}], [], None, ("", ""), 1),
+        # nologged + successful re-login, verified again
+        ("expired + re-login", "relogged",
+         [{"error": "nologged"}], [{"remaining": 1800}],
+         "session", ("uzivatel", "heslo"), 1),
+        # nologged + failed re-login
+        ("expired + selhaný re-login", "fallback",
+         [{"error": "nologged"}], [], None, ("uzivatel", "heslo"), 1),
+        # nologged + no stored credentials
+        ("expired bez údajů", "fallback",
+         [{"error": "nologged"}], [], None, ("", ""), 1),
+        # No session and no credentials – no request at all
+        ("anonym bez údajů", "anonymous",
+         [], [], None, ("", ""), 0),
+        # Network error during the check
+        ("chyba sítě", "unknown",
+         [(None, requests.exceptions.ConnectionError("probe"))],
+         [], None, ("", ""), 1),
+        # 200 but invalid JSON
+        ("neplatný JSON", "unknown",
+         [(None, ValueError("Invalid JSON"))],
+         [], None, ("", ""), 1),
+    ]
+
+    tools = amcr_viewer.amcr_tools
+    puvodni = (tools.login_to_api, tools._get_session,
+               dialog.LoginDialog.__dict__["get_credentials"])
+    try:
+        return _prihlasovaci_stav(pripady, tools)
+    finally:
+        # Leave the modules as they were found, even when a case fails
+        (tools.login_to_api, tools._get_session,
+         dialog.LoginDialog.get_credentials) = puvodni
+        tools.AMCR_SESSION = None
+
+
+def _prihlasovaci_stav(pripady, tools):
+    """Runs the cases of prihlasovaci_stav()."""
+    vysledky = []
+    for (nazev, ocekavano, tela, tela_po_loginu, login_vysledek,
+         kredity, get_volani) in pripady:
+
+        # The current session (None = _get_session returns None);
+        # a successful fake re-login produces a new fake session
+        session = FalesnaSession(tela) if tela else None
+        login_hodnota = FalesnaSession(tela_po_loginu) \
+            if login_vysledek else None
+
+        tools.AMCR_SESSION = session
+
+        def fake_login(hodnota):
+            # Like the real login_to_api: stores the session globally
+            def login(uzivatel, heslo):
+                if hodnota is not None:
+                    tools.AMCR_SESSION = hodnota
+                return hodnota
+            return login
+
+        tools.login_to_api = fake_login(login_hodnota)
+        tools._get_session = (lambda s: lambda: s)(session) \
+            if session else (lambda: None)
+        dialog.LoginDialog.get_credentials = staticmethod(
+            (lambda k: lambda: k)(kredity)
+        )
+
+        stav = tools._ensure_logged_in()
+        assert stav == ocekavano, f"{nazev}: {stav} != {ocekavano}"
+
+        # The old session object must have been used for the checks
+        if session is not None:
+            assert session.get_volani == get_volani, \
+                f"{nazev}: {session.get_volani} != {get_volani}"
+
+        # The returned fake login session must become the global one
+        # and its login state must have been verified as well
+        if ocekavano == "relogged":
+            assert login_hodnota is not None
+            assert tools.AMCR_SESSION is login_hodnota
+            assert login_hodnota.get_volani == 1, \
+                f"{nazev}: nová session nebyla ověřena"
+
+        vysledky.append(f"{nazev} → {stav}")
+
+    return ", ".join(vysledky)
+
+
+def odhlaseni():
+    """logout_from_api with a fake session – offline."""
+    tools = amcr_viewer.amcr_tools
+    puvodni = tools.AMCR_SESSION
+    try:
+        # Logged-in session: one GET to /logout, session dropped
+        session = FalesnaSession([{"msg": "logged out"}])
+        session_get = session.get
+        urls = []
+
+        def get(url, timeout=0):
+            urls.append(url)
+            odpoved = session_get(url, timeout)
+            odpoved.raise_for_status = lambda: None
+            return odpoved
+
+        session.get = get
+        tools.AMCR_SESSION = session
+        assert tools.logout_from_api() is True
+        assert tools.AMCR_SESSION is None
+        assert urls and urls[0].endswith("/api/user/logout"), urls
+
+        # Network error: session still dropped locally
+        chyba = FalesnaSession(
+            [(None, requests.exceptions.ConnectionError("probe"))]
+        )
+        tools.AMCR_SESSION = chyba
+        assert tools.logout_from_api() is False
+        assert tools.AMCR_SESSION is None
+        assert chyba.get_volani == 1
+
+        # No session: nothing to do, no request
+        assert tools.logout_from_api() is True
+    finally:
+        tools.AMCR_SESSION = puvodni
+    return "odhlášení, chyba sítě → zahozeno lokálně, bez session → nic"
+
+
+def vaha_komponent():
+    """
+    _component_entries: the weight is 1/n of the components that pass
+    the predicate, so the weights of one documentation unit sum to 1
+    even with a period/area filter active.
+
+    The cases come from the spec of the fix (issue #55); the sums are
+    compared with a tolerance because 1/3 weights add up to 0.999…
+    """
+    tools = amcr_viewer.amcr_tools
+
+    def komponenta(ident, areal=None, obdobi=None):
+        return {
+            "ident_cely": ident,
+            "komponenta_areal": ({"id": areal} if areal else None),
+            "komponenta_obdobi": ({"id": obdobi} if obdobi else None),
+        }
+
+    dj_meta = {"dj_id": "X-M-000001"}
+
+    # 4 components, no filter: 4 features, each 0.25
+    komps = [komponenta(f"K{i}") for i in range(4)]
+    zaznamy = tools._component_entries(dj_meta, komps, lambda k: True)
+    assert len(zaznamy) == 4, len(zaznamy)
+    assert all(z["vaha"] == 0.25 for z in zaznamy), \
+        [z["vaha"] for z in zaznamy]
+
+    # Period filter keeps 1 of 4: single feature with weight 1
+    komps = [
+        komponenta("K0", obdobi="neolit"),
+        komponenta("K1"), komponenta("K2"), komponenta("K3"),
+    ]
+    zaznamy = tools._component_entries(
+        dj_meta, komps, lambda k: k["komponenta_obdobi"] is not None
+    )
+    assert len(zaznamy) == 1, len(zaznamy)
+    assert zaznamy[0]["vaha"] == 1.0, zaznamy[0]["vaha"]
+
+    # Filter keeps 2 of 3: 2 features, each 0.5, sum 1 within tolerance
+    komps = [
+        komponenta("K0", obdobi="neolit"), komponenta("K1", obdobi="bronz"),
+        komponenta("K2"),
+    ]
+    zaznamy = tools._component_entries(
+        dj_meta, komps, lambda k: k["komponenta_obdobi"] is not None
+    )
+    assert len(zaznamy) == 2, len(zaznamy)
+    assert all(z["vaha"] == 0.5 for z in zaznamy), \
+        [z["vaha"] for z in zaznamy]
+    assert abs(sum(z["vaha"] for z in zaznamy) - 1) < 1e-9
+
+    # Sum with tolerance also for an indivisible split (1/3)
+    komps = [komponenta(f"K{i}") for i in range(3)]
+    zaznamy = tools._component_entries(dj_meta, komps, lambda k: True)
+    assert abs(sum(z["vaha"] for z in zaznamy) - 1) < 1e-9
+
+    # No components: one entry with empty component fields, weight 1
+    zaznamy = tools._component_entries(dj_meta, [], lambda k: True)
+    assert len(zaznamy) == 1, zaznamy
+    assert zaznamy[0]["vaha"] == 1, zaznamy[0]["vaha"]
+    assert zaznamy[0]["komponenta_id"] == ""
+
+    # The shared DJ metadata and component fields travel along
+    komps = [komponenta("K0", areal="sidelni", obdobi="neolit")]
+    zaznamy = tools._component_entries(dj_meta, komps, lambda k: True)
+    assert zaznamy[0]["dj_id"] == "X-M-000001"
+    assert zaznamy[0]["komponenta_id"] == "K0"
+
+    return "4×0.25; 1/4 → 1.0; 2/3 → 2×0.5; prázdné → 1"
+
+
+def vychozi_filtry():
+    """
+    A fresh dialog starts from the defaults: the map-extent restriction
+    checked, PIAN – přesnost pre-selected for akce and lokalita, and
+    nothing (not even PIAN) sent for samostatny_nalez.
+    """
+    _stubuj_varovani()
+    try:
+        pian = ["HES-000861", "HES-000862", "HES-000863"]
+        for typ, ma_pian in (("akce", True), ("lokalita", True),
+                             ("samostatny_nalez", False)):
+            okno = dialog.AmcrFilterDialog(typ)
+            assert okno.get_bbox() == "true", typ
+            assert okno.get_komponenty() == "false", typ
+            if ma_pian:
+                assert okno.selection_cache["pian_presnost"] == pian, typ
+                assert okno.get_filters()["f_pian_presnost"] == pian, typ
+            else:
+                assert "f_pian_presnost" not in okno.get_filters(), typ
+            okno.close()
+        return ("PIAN 861/862/863 u akcí a lokalit, u nálezů bez "
+                "omezení, bbox zapnutý")
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
+def _stubuj_varovani():
+    # A modal warning would block the offscreen run forever
+    dialog.QMessageBox.warning = staticmethod(lambda *a, **k: None)
+
+
+def _kody(codelist, n=1):
+    """First n real codes of a codelist (label -> code dict)."""
+    return [code for code in codelist.values() if code][:n]
+
+
+def _napln(okno, typ):
+    """Fills a dialog with a non-default state for round-trip tests."""
+    okno._set_picker("kraj", _kody(dialog.KRAJE))
+    okno._set_picker("obdobi", _kody(dialog.OBDOBI, 2))
+    okno.chk_bbox.setChecked(False)
+    if typ == "akce":
+        okno.chk_posevidence.setChecked(True)
+        okno.chk_proj_akce.setChecked(True)
+        okno._set_picker("typ_akce", _kody(dialog.TYP_AKCE))
+        okno.date_ranges[0][2].setDate(QDate(2016, 1, 1))
+        okno.date_ranges[0][3].setDate(QDate(2017, 12, 31))
+    if typ == "lokalita":
+        okno.chk_komponenty.setChecked(True)
+        okno._set_picker("typ_lokality", _kody(dialog.TYP_LOKALITY))
+    if typ == "samostatny_nalez":
+        okno._set_picker("druh_nalezu", _kody(dialog.DRUH_NALEZU))
+        okno.date_ranges[0][3].setDate(QDate(2020, 6, 30))
+
+
+def pamet_snapshotu():
+    """
+    Snapshot -> apply on a fresh dialog keeps get_filters(),
+    get_bbox() and get_komponenty() identical; a code unknown to the
+    current codelist is dropped on the way.
+    """
+    _stubuj_varovani()
+    try:
+        for typ in ("akce", "lokalita", "samostatny_nalez"):
+            okno = dialog.AmcrFilterDialog(typ)
+            _napln(okno, typ)
+            stav = okno.get_filters()
+            snapshot = okno._snapshot()
+            okno.close()
+
+            obnovene = dialog.AmcrFilterDialog(typ)
+            obnovene._apply_state(snapshot)
+            assert obnovene._snapshot() == snapshot, typ
+            assert obnovene.get_filters() == stav, typ
+            assert obnovene.get_bbox() == okno.get_bbox(), typ
+            assert obnovene.get_komponenty() == okno.get_komponenty(), typ
+            obnovene.close()
+
+        # Unknown code: dropped, not sent
+        okno = dialog.AmcrFilterDialog("akce")
+        kraj = _kody(dialog.KRAJE)
+        okno._set_picker("kraj", kraj + ["XX-NEEXISTUJE"])
+        assert okno.selection_cache["kraj"] == kraj
+        assert okno.get_filters()["f_kraj"] == kraj
+        okno.close()
+
+        # The same through a remembered state, as after a codelist
+        # update removed the code: dropped on opening, the picker text
+        # is the current codelist label
+        stitek = next(k for k, v in dialog.KRAJE.items() if v == kraj[0])
+        stav = dialog.AmcrFilterDialog("akce")._snapshot()
+        stav["codes"]["kraj"] = kraj + ["XX-NEEXISTUJE"]
+        dialog._REMEMBERED_STATE["akce"] = stav
+        okno = dialog.AmcrFilterDialog("akce")
+        assert okno.get_filters()["f_kraj"] == kraj
+        assert okno.pickers["kraj"][1].text() == stitek
+        okno.close()
+        return "round-trip všech tří typů, neznámý kód zahozen"
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
+def pamet_potvrzeni():
+    """
+    OK remembers the form state for the next opening of the same data
+    type; Cancel and a refused reversed date range do not; another
+    data type starts from the defaults.
+    """
+    _stubuj_varovani()
+    try:
+        okno = dialog.AmcrFilterDialog("akce")
+        _napln(okno, "akce")
+        potvrzene = okno.get_filters()
+        okno.accept()
+        okno.close()
+
+        # OK -> reopen restores the same filters
+        znovu = dialog.AmcrFilterDialog("akce")
+        assert znovu.get_filters() == potvrzene
+        assert znovu.get_bbox() == "false"
+
+        # Another data type starts from the defaults
+        lokalita = dialog.AmcrFilterDialog("lokalita")
+        assert "f_kraj" not in lokalita.get_filters()
+        assert lokalita.get_bbox() == "true"
+        lokalita.close()
+
+        # Cancel keeps the remembered state
+        znovu._set_picker("kraj", [])
+        znovu.chk_bbox.setChecked(True)
+        znovu.reject()
+        znovu.close()
+        po_zruseni = dialog.AmcrFilterDialog("akce")
+        assert po_zruseni.get_filters() == potvrzene
+
+        # A reversed range is refused and the state stays unchanged
+        zapamatovano = dialog._REMEMBERED_STATE["akce"]
+        po_zruseni.date_ranges[0][2].setDate(QDate(2018, 1, 1))
+        po_zruseni.date_ranges[0][3].setDate(QDate(2017, 1, 1))
+        po_zruseni.accept()
+        assert po_zruseni.result() == 0, "obrácené rozmezí přijato"
+        assert dialog._REMEMBERED_STATE["akce"] == zapamatovano
+        po_zruseni.close()
+        return ("OK obnoví, Cancel i obrácené rozmezí ne, jiný typ "
+                "od výchozích")
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
+def obnoveni_vychozich():
+    """
+    Obnovit výchozí resets the form only: reset + OK behaves like a
+    fresh dialog, reset + Cancel keeps the remembered state.
+    """
+    _stubuj_varovani()
+    try:
+        # Default output, captured before anything is remembered
+        okno = dialog.AmcrFilterDialog("akce")
+        vychozi = okno.get_filters()
+        vychozi_bbox = okno.get_bbox()
+        vychozi_komponenty = okno.get_komponenty()
+        okno.close()
+
+        # A remembered non-default state
+        okno = dialog.AmcrFilterDialog("akce")
+        _napln(okno, "akce")
+        potvrzene = okno.get_filters()
+        okno.accept()
+        okno.close()
+
+        # Reset + Cancel: reopening shows the remembered state
+        okno = dialog.AmcrFilterDialog("akce")
+        okno.action_reset()
+        assert okno.get_filters() == vychozi
+        okno.reject()
+        okno.close()
+        okno = dialog.AmcrFilterDialog("akce")
+        assert okno.get_filters() == potvrzene
+        okno.close()
+
+        # Reset + OK: the sent filters and the next opening are default
+        okno = dialog.AmcrFilterDialog("akce")
+        okno.action_reset()
+        assert okno.get_filters() == vychozi
+        assert okno.get_bbox() == vychozi_bbox
+        assert okno.get_komponenty() == vychozi_komponenty
+        okno.accept()
+        okno.close()
+        okno = dialog.AmcrFilterDialog("akce")
+        assert okno.get_filters() == vychozi
+        okno.close()
+        return "reset + OK = čerstvý dialog, reset + Cancel zachová"
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
+def vymazani_vyberu():
+    """
+    The ✕ button returns only its own filter to its default (empty,
+    or the three pre-selected levels for PIAN – přesnost) and is
+    disabled while the filter already is at that default.
+    """
+    _stubuj_varovani()
+    try:
+        okno = dialog.AmcrFilterDialog("lokalita")
+        okno._set_picker("kraj", _kody(dialog.KRAJE))
+        okno._set_picker("obdobi", _kody(dialog.OBDOBI, 2))
+        pred = okno.get_filters()
+        assert "f_kraj" in pred and "f_obdobi" in pred
+
+        okno.pickers["kraj"][2].click()
+        assert okno.selection_cache["kraj"] == []
+        po = okno.get_filters()
+        assert "f_kraj" not in po
+        assert po["f_obdobi"] == pred["f_obdobi"]
+        assert not okno.pickers["kraj"][2].isEnabled()
+        okno.close()
+
+        okno = dialog.AmcrFilterDialog("akce")
+        assert "f_pian_presnost" in okno.get_filters()
+        # A fresh dialog is at the default, so ✕ is disabled
+        assert not okno.pickers["pian_presnost"][2].isEnabled()
+
+        # A reordered default list still counts as the default
+        vychozi = dialog.DEFAULT_CODES["pian_presnost"]
+        okno._set_picker("pian_presnost", list(reversed(vychozi)))
+        assert not okno.pickers["pian_presnost"][2].isEnabled()
+        assert "f_pian_presnost" in okno.get_filters()
+
+        # Emptied PIAN means no restriction and enables ✕
+        okno._set_picker("pian_presnost", [])
+        assert "f_pian_presnost" not in okno.get_filters()
+        assert okno.pickers["pian_presnost"][2].isEnabled()
+
+        # ✕ restores the three default levels and disables itself
+        okno.pickers["pian_presnost"][2].click()
+        assert sorted(okno.get_filters()["f_pian_presnost"]) == sorted(
+            vychozi
+        )
+        assert not okno.pickers["pian_presnost"][2].isEnabled()
+        okno.close()
+        return ("✕ vrací filtr na výchozí hodnotu, PIAN na tři "
+                "úrovně, jinak prázdné")
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
+def upozorneni_obnovy():
+    """
+    The notice is hidden for a fresh dialog and for a remembered
+    default state; with two filters set it is shown with the count 2
+    and hidden again by Obnovit výchozí.
+    """
+    _stubuj_varovani()
+    try:
+        okno = dialog.AmcrFilterDialog("akce")
+        assert okno.lbl_notice.isHidden()
+        okno.close()
+
+        # A remembered default state is not worth a notice
+        okno = dialog.AmcrFilterDialog("akce")
+        okno.accept()
+        okno.close()
+        okno = dialog.AmcrFilterDialog("akce")
+        assert okno.lbl_notice.isHidden()
+        okno.close()
+
+        # Two non-default filters -> a notice with the count 2
+        okno = dialog.AmcrFilterDialog("akce")
+        okno._set_picker("kraj", _kody(dialog.KRAJE))
+        okno._set_picker("obdobi", _kody(dialog.OBDOBI))
+        okno.accept()
+        okno.close()
+        okno = dialog.AmcrFilterDialog("akce")
+        assert not okno.lbl_notice.isHidden()
+        assert okno.lbl_notice.text().startswith("Načteny filtry")
+        assert "aktivní filtry: 2" in okno.lbl_notice.text()
+        okno.action_reset()
+        assert okno.lbl_notice.isHidden()
+        okno.close()
+        return "skryté pro výchozí, viditelné s počtem 2, reset skryje"
+    finally:
+        dialog._REMEMBERED_STATE.clear()
+
+
 zkouska("scoped enumy", enumy)
 zkouska("UpdateCodelistsTask", uloha)
 zkouska("filtrační dialogy", dialogy)
 zkouska("filtr podle data", filtr_datumu)
+zkouska("výchozí filtry", vychozi_filtry)
+zkouska("paměť snapshotu", pamet_snapshotu)
+zkouska("paměť potvrzení", pamet_potvrzeni)
+zkouska("obnovení výchozích", obnoveni_vychozich)
+zkouska("vymazání výběru", vymazani_vyberu)
+zkouska("upozornění obnovy", upozorneni_obnovy)
+zkouska("stav přihlášení", prihlasovaci_stav)
+zkouska("odhlášení", odhlaseni)
+zkouska("váha komponent", vaha_komponent)
 
 qgs.exitQgis()