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

@@ -0,0 +1,35 @@
+<!--
+Děkujeme za příspěvek! Vyplň prosím sekce níže.
+Nepotřebné body můžeš smazat. Komentáře (<!-- ... -->) se v PR nezobrazují.
+-->
+
+## Souhrn
+
+<!-- Stručně co a proč. 1–3 věty. -->
+
+## Změny
+
+<!-- Co se konkrétně mění, ideálně po souborech / oblastech. -->
+-
+
+## Testování
+
+<!-- Jak ověřit, že to funguje (kroky v QGIS, scénáře). -->
+-
+
+## Zapojení AI
+
+<!-- Byla u změny použita AI? Jak? Např. "text navržen AI, ručně zkontrolováno
+     a upraveno". Smaž, pokud AI použita nebyla. -->
+-
+
+## 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` (+ `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>`)
+
+## Související issue
+
+<!-- Např. "Closes #123". Smaž, pokud se neváže k issue. -->

.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

@@ -0,0 +1,203 @@
+name: Code Quality
+
+# Pouští při každém PR tytéž kontroly, které se dosud dělaly ručně:
+#
+#  * co spouští plugins.qgis.org při uploadu (bandit, detect-secrets,
+#    flake8, analýza souborů) – https://plugins.qgis.org/docs/security-scanning
+#  * oficiální kontrolu kompatibility s Qt6 (pyqgis4-checker)
+#  * skutečné načtení pluginu v QGIS 3.44 (Qt5) i v QGIS 4 (Qt6)
+#  * sestavení ZIPu, který si recenzent stáhne a nainstaluje přímo z PR
+#
+# CodeQL a GitGuardian běží zvlášť, nastavené na úrovni organizace –
+# tady se schválně neduplikují.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # Verze se drží napevno, aby se výsledek nezměnil sám od sebe. Výchozí
+  # sada pravidel ruffu se mezi verzemi mění; povýšení je vědomý krok.
+  BANDIT: bandit==1.9.4
+  DETECT_SECRETS: detect-secrets==1.5.0
+  FLAKE8: flake8==7.3.0
+  RUFF: ruff==0.16.5
+  OPENSPEC: 1.14.0
+
+jobs:
+  # --------------------------------------------------------------------
+  # 1. Statické kontroly – běží první, protože trvají desítky sekund
+  # --------------------------------------------------------------------
+  lint:
+    name: Lint a bezpečnost
+    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 tools
+        run: pip install "$BANDIT" "$DETECT_SECRETS" "$FLAKE8" "$RUFF"
+
+      # Hygiena repozitáře: BOM, přímé importy z PyQt5/PyQt6, spustitelná
+      # práva a podezřelé typy souborů. Padá jako první, protože BOM
+      # zneviditelní soubor pro kontrolu níž.
+      - name: Source hygiene
+        run: python3 tests/check_sources.py
+
+      # Blokující kontrola na plugins.qgis.org
+      - name: Bandit
+        run: bandit -r amcr_viewer/
+
+      # Blokující kontrola na plugins.qgis.org.
+      # --all-files je podstatné: bez něj detect-secrets prohledá jen
+      # soubory sledované gitem a nesledovaný soubor tiše přeskočí.
+      - name: detect-secrets
+        run: |
+          detect-secrets scan --all-files amcr_viewer/ > vysledek.json
+          python3 -c "
+          import json, sys
+          nalezy = json.load(open('vysledek.json'))['results']
+          if nalezy:
+              print(json.dumps(nalezy, indent=2))
+              sys.exit(1)
+          print('detect-secrets: bez nálezů')
+          "
+
+      # Na plugins.qgis.org je informativní, tady blokuje. Bez konfigurace,
+      # tj. se stejnými výchozími pravidly jako scanner.
+      - name: Flake8
+        run: flake8 --isolated amcr_viewer/
+
+      # Nad rámec plugins.qgis.org; konfigurace v pyproject.toml
+      - name: Ruff
+        run: ruff check .
+
+  # --------------------------------------------------------------------
+  # 2. Kompatibilita s Qt6 – oficiální skript z QGISu
+  # --------------------------------------------------------------------
+  qt6:
+    name: Kompatibilita s Qt6
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        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.
+      - name: pyqgis4-checker
+        run: |
+          docker run --rm --user "$(id -u):$(id -g)" \
+            --workdir /workspace/ -v "$PWD:/workspace/" \
+            ghcr.io/qgis/pyqgis4-checker:main-ubuntu \
+            pyqt5_to_pyqt6.py --dry_run --logfile /workspace/pyqt6_checker.log .
+          echo "--- pyqt6_checker.log ---"
+          cat pyqt6_checker.log
+          nalezu=$(grep -v '=== dry_run mode | Start Logs ===' pyqt6_checker.log | wc -l)
+          if [ "$nalezu" -ne 0 ]; then
+            echo "::error::pyqgis4-checker nahlásil nálezy, viz log výše"
+            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
+  # --------------------------------------------------------------------
+  qgis:
+    name: Smoke test (QGIS ${{ matrix.qgis }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # ltr = 3.44 na Qt5, stable = 4.x na Qt6. Tagy se posouvají
+        # schválně: chceme vědět, že plugin drží krok s aktuálním QGISem.
+        qgis: [ltr, stable]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Smoke test
+        run: |
+          docker run --rm -v "$PWD:/work:ro" -w /work \
+            --user "$(id -u):$(id -g)" -e HOME=/tmp \
+            "qgis/qgis:${{ matrix.qgis }}" python3 tests/smoke_test.py
+
+  # --------------------------------------------------------------------
+  # 4. ZIP k instalaci – stejný postup jako v release_plugin.yml
+  # --------------------------------------------------------------------
+  package:
+    name: Balíček pluginu
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Zip plugin
+        run: zip -r amcr_viewer.zip amcr_viewer -x "*.git*"
+
+      # Verze v CITATION.cff se povyšuje ručně spolu s metadata.txt a snadno
+      # se zapomene – tag by pak nesl v citaci jinou verzi než plugin
+      - 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/LICENSE; do
+            unzip -l amcr_viewer.zip | grep -qF " $soubor" \
+              || { echo "::error::v ZIPu chybí $soubor"; exit 1; }
+          done
+          if unzip -l amcr_viewer.zip | grep -qE '\.git'; then
+            echo "::error::v ZIPu jsou git soubory"
+            exit 1
+          fi
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: amcr_viewer-plugin
+          path: amcr_viewer.zip
+          if-no-files-found: error

.github/workflows/release_plugin.yml

@@ -1,17 +1,28 @@
 name: Release QGIS Plugin
 
+# Spouští se na push tagu, ne na publikaci releasu. Organizace má zapnuté
+# immutable releases: k už publikovanému releasu nelze nic přiložit, příloha
+# tedy musí vzniknout dřív, než se release zveřejní. Workflow proto založí
+# koncept releasu i se ZIPem; text se dopisuje a publikuje ručně.
+#
+# Pozor: workflow se čte z commitu, na který tag ukazuje. Tag musí být
+# založen až na commitu, který tento soubor obsahuje.
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
 
 jobs:
   build-and-release:
     runs-on: ubuntu-latest
 
     steps:
-      # 1. Stáhne kód z repozitáře
+      # 1. Stáhne kód z tagu, který běh spustil
       - name: Checkout code
-        uses: actions/checkout@v2
+        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
@@ -20,11 +31,14 @@ jobs:
           # -r = rekurzivně, -x = ignorovat skryté git soubory
           zip -r amcr_viewer.zip amcr_viewer -x "*.git*"
 
-      # 3. Nahraje ZIP k Releasu
-      - name: Upload Release Asset
-        uses: softprops/action-gh-release@v1
-        if: startsWith(github.ref, 'refs/tags/')
+      # 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@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           files: amcr_viewer.zip
+          draft: true
+          name: AMCR Viewer ${{ github.ref_name }}
+          prerelease: ${{ contains(github.ref_name, '-') }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.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 }}"

.gitignore

@@ -210,3 +210,5 @@ __marimo__/
 
 README_files/
 README.html
+amcr_viewer.zip
+pyrefly.toml

AGENTS.md

@@ -0,0 +1,322 @@
+# AGENTS.md
+
+Pokyny pro AI agenty i lidské přispěvatele pracující v tomto repozitáři.
+Tento soubor je jediný zdroj pravdy; `CLAUDE.md` na něj pouze odkazuje.
+
+## O projektu
+
+**AMČR Viewer** je plugin do QGIS pro stahování a vizualizaci dat z Digitálního
+archivu Archeologické mapy ČR (AMČR / AIS CR) – akce (*Fieldwork events*),
+lokality (*Sites*) a jejich komponenty. Podporuje anonymní i přihlášený přístup
+přes AMČR účet.
+
+Zdroj dat: https://digiarchiv.aiscr.cz/ · Nápověda: https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html
+
+## Zařazení v ekosystému AIS CR
+
+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. Z hubu přebírá **OpenSpec** ve stupni `change-tracked` (viz
+níže). Ostatní mašinerii hubu (složka `.agents/`, sync skripty, vlastní
+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
+
+```
+amcr_viewer/            # vlastní kód pluginu (toto se balí do releasu)
+  amcr_viewer.py        # vstupní bod pluginu, integrace do QGIS
+  amcr_dialog.py        # dialogy a UI (filtry, přihlášení)
+  amcr_tools.py         # stahování dat z API, sestavení vrstev a atributů
+  amcr_codelists.py     # hesláře / číselníky (codelists)
+  codelists/heslar.csv  # lokální kopie číselníků
+  metadata.txt          # metadata pluginu + verze + changelog
+  i18n/                 # překlady (.ts)
+  *.png                 # ikony
+.github/workflows/      # CI – kontroly kvality a release pluginu
+openspec/               # OpenSpec – konfigurace a plánovací artefakty změn
+README.md               # uživatelská dokumentace (anglicky)
+```
+
+## Konvence
+
+### Jazyk
+- **Kód a identifikátory:** anglicky. Atributová pole vrstev musí být ASCII
+  kompatibilní (bez diakritiky) – viz historie změn v `metadata.txt`.
+- **README a uživatelská dokumentace:** anglicky.
+- **Commity, PR a komentáře v issue:** česky.
+
+### Commity
+- Styl odpovídá historii: česky, věcně, popisně; jeden commit = jedna logická
+  změna.
+- První řádek stručně a výstižně (ideálně v imperativu); podrobnosti do těla.
+- Pokud je commit připraven s pomocí AI, uveď to v těle commitu nebo v popisu PR.
+
+### Větve
+Konvence názvů je sladěná s hubem `aiscr-management`:
+
+- **lidé:** `feat/<téma>` (nová funkce), `fix/<téma>` (oprava), `docs/<téma>`
+  (dokumentace), `chore/<téma>` (údržba).
+- **AI agenti:** `agents/<jméno-agenta>/<téma>` (např. `agents/claude/oprava-pian`).
+
+Další pravidla:
+
+- Cílová větev pro nový vývoj je aktuální `version/v2.x.y` (ne přímo do
+  výchozí větve bez PR).
+- **Nikdy** nepushuj přímo do chráněných větví; vždy přes Pull Request.
+- Standardizační / nefunkční změny drž v samostatné větvi, ať se nemíchají do
+  feature PR.
+
+### Pravidla pro AI agenty (git)
+- AI ve výchozím stavu zůstává u **lokální práce na aktuální větvi**.
+- Bez **výslovného pokynu** uživatele AI nestageuje (`git add`), necommituje,
+  nepushuje ani samo nepřepíná/nezakládá větev pro vzdálené doručení.
+- Při výslovném požadavku na push/PR použij větev `agents/<jméno-agenta>/<téma>`;
+  pokud aktuální větev tomuto vzoru neodpovídá, vyžádej si nejdřív potvrzení.
+- Vytvoření větve, stage, commit, push ani draft PR AI běžně nenabízí; zmiňuj je
+  jen tehdy, když jsou pro splnění úkolu opravdu nutné.
+
+### QGIS specifika
+- Minimální podporovaná verze QGIS je **3.44** (`qgisMinimumVersion` v
+  `metadata.txt`); kód nesmí spoléhat na novější API.
+- Vrstvy a atributy se sestavují přes `QgsField` / QGIS API v `amcr_tools.py`.
+  Při přidání atributu je potřeba doplnit ho konzistentně na všech místech:
+  definice pole (`QgsField`), naplnění hodnoty z dokumentu, překlad hlavičky
+  sloupce a export atributů.
+
+### Kompatibilita s Qt6 / QGIS 4
+
+Plugin cílí na QGIS 3.44 i na QGIS 4 (`qgisMaximumVersion=4.99.0`), tedy na
+Qt5 i Qt6 zároveň. **Tohle se drží rigorózně** – ne až před releasem, ale při
+každé změně kódu. Chování obou větví se liší tiše: pod Qt5 projde i to, co
+QGIS 4 odmítne, takže lokální „funguje mi to“ nic nedokazuje.
+
+Závazná pravidla:
+
+- **Nikdy neimportuj přímo z `PyQt5` ani z `PyQt6`.** Vždy přes shim
+  `qgis.PyQt.*`. Ten mimo jiné pod Qt6 přetahuje `QAction`, `QActionGroup`
+  a `QShortcut` z `QtGui`, takže import z `qgis.PyQt.QtWidgets` je správně.
+- **Enumy vždy plně kvalifikované (scoped).** `Qgis.MessageLevel.Info`, ne
+  `Qgis.Info`; `QgsTask.Flag.CanCancel`, ne `QgsTask.CanCancel`;
+  `QgsWkbTypes.GeometryType.PointGeometry`, ne `QgsWkbTypes.PointGeometry`.
+  Totéž pro Qt: `Qt.CheckState.Checked`, `QDialogButtonBox.StandardButton.Ok`.
+  Zkrácené tvary sice v QGIS 4.2 zatím fungují, ale oficiální kontrola je
+  hlásí a do budoucna mizí.
+- **Zdrojové `.py` soubory ukládej bez BOM.** Kontrolní skript čte soubor
+  jako UTF-8 bez `utf-8-sig` a na BOM spadne s
+  `SyntaxError: invalid non-printable character U+FEFF`, takže se takový
+  soubor **vůbec nezkontroluje**. (`codelists/heslar.csv` BOM mít smí, tam je
+  kvůli Excelu.)
+- Nepoužívej API zrušená v Qt6: `exec_()`, `QRegExp`, `QDesktopWidget`,
+  `QApplication.desktop()`, `Qt.MidButton`, `QFontMetrics.width()`,
+  `setResizeMode`, atributy `AA_EnableHighDpiScaling` / `AA_UseHighDpiPixmaps`.
+- `supportsQt6=True` v `metadata.txt` **nepatří** – bylo zrušeno; o zařazení
+  mezi „QGIS 4 Ready“ rozhoduje rozsah `qgisMinimumVersion` až
+  `qgisMaximumVersion`.
+
+Ověření před PR, který mění Python kód:
+
+```sh
+# oficiální kontrola, kterou pouští i plugins.qgis.org (pyqgis4-checker)
+docker run --rm --pull always --user $(id -u):$(id -g) \
+  --workdir /workspace/ -v "$(pwd):/workspace/" \
+  ghcr.io/qgis/pyqgis4-checker:main-ubuntu \
+  pyqt5_to_pyqt6.py --dry_run --logfile /workspace/pyqt6_checker.log .
+```
+
+Prázdný log = čisté. Kontrola je na plugins.qgis.org informativní
+(neblokuje schválení), ale nález znamená, že plugin v QGIS 4 dříve nebo
+později přestane fungovat.
+
+Když je po ruce QGIS 4 (např. flatpak `org.qgis.qgis`), ověř navíc, že se
+plugin pod Qt6 opravdu načte:
+
+```sh
+flatpak run --command=sh org.qgis.qgis -c \
+  'PYTHONPATH=/app/share/qgis/python python3 -c "import qgis.core"'
+```
+
+## Verzování a release
+
+- 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
+  v UI. Workflow `.github/workflows/release_plugin.yml` zabalí složku
+  `amcr_viewer/` do `amcr_viewer.zip` a založí **koncept** releasu i s touto
+  přílohou; text se dopíše a release zveřejní ručně. Do ZIPu se nesmí dostat
+  `.git*` soubory.
+- Organizace má zapnuté **immutable releases** – k publikovanému releasu už
+  nelze nic přiložit. Proto příloha vzniká na konceptu, ještě před
+  zveřejněním; workflow spouštěný na `release: published` by vždy selhal.
+- Workflow se čte z commitu, na který **tag ukazuje**. Tag proto zakládej až
+  na commitu, který obsahuje aktuální podobu workflow – jinak se nespustí nic.
+
+## Pull requesty
+
+- Používej PR šablonu (`.github/pull_request_template.md`): Souhrn / Změny /
+  Testování / Kontrolní seznam.
+- 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.
+
+## Bezpečnost a soukromí
+
+- Do promptů, příkladů ani commitů **nevkládej** ostrá produkční data, plné
+  log dumpy ani reálné osobní údaje (PII).
+- **Rediguj** secrets, tokeny, API klíče a hesla z čehokoli, co posíláš AI;
+  nikdy je necommituj do repozitáře (ani přihlašovací údaje k AMČR účtu).
+- Pro interní infrastrukturu (URL, hostname, prostředí) používej placeholdery,
+  pokud konkrétní hodnota není nutná a povolená.
+
+## Lokální ověření
+
+Plugin se testuje načtením do QGIS (Plugins → Manage and Install Plugins →
+Install from ZIP, nebo nasazením složky `amcr_viewer/` do adresáře pluginů
+QGIS). **Ruční test v QGIS nic nenahrazuje** – automatické kontroly ověřují,
+že se plugin načte a že projde kontrolami kvality, ne že dělá správnou věc.
+
+### Automatické kontroly
+
+Workflow `.github/workflows/code_quality.yml` pouští při každém PR do `main`
+tohle:
+
+| job | co dělá |
+|---|---|
+| **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** | 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.
+
+Artefakt z posledního jobu se dá stáhnout ze stránky běhu a rovnou
+nainstalovat přes *Install from ZIP* – recenzent nemusí nic balit ručně.
+
+Totéž lokálně:
+
+```sh
+pip install bandit detect-secrets flake8 ruff
+
+python3 tests/check_sources.py
+bandit -r amcr_viewer/
+detect-secrets scan --all-files amcr_viewer/
+flake8 --isolated amcr_viewer/
+ruff check .
+
+# smoke test v obou verzích QGIS (docker, bez instalace čehokoli)
+for tag in ltr stable; do
+  docker run --rm -v "$PWD:/work:ro" -w /work \
+    --user "$(id -u):$(id -g)" -e HOME=/tmp \
+    "qgis/qgis:$tag" python3 tests/smoke_test.py
+done
+```
+
+Na co si dát pozor:
+
+- **`pyqgis4-checker` končí kódem 0, i když něco najde** – výsledek je jen
+  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.
+- **Flake8 běží bez konfigurace** (`--isolated`), tedy se stejnými
+  výchozími pravidly jako scanner na plugins.qgis.org. Do balíčku nepatří
+  `.flake8`, `.bandit` ani `.secrets.baseline`: scanner by plugin označil
+  jako „Validated (configured)“ a nález je lepší opravit v kódu.
+  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

@@ -20,11 +20,10 @@ identifiers:
     value: 10.5281/zenodo.18609813
 repository-code: 'https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer'
 abstract: >-
-  This QGIS plugin is intended for downloading the data
-  (Fieldwork events data only, at the time) from the
-  Digiarchive of the Archaeological Map of the Czech
-  Republic (AMCR). As of now, only publicly accessible data
-  can be downloaded.
+  This plugin is intended for downloading the data
+  (Fieldwork events, Sites, and their Components) from
+  the Digital archive of the Archaeological Map of the
+  Czech Republic (https://digiarchiv.aiscr.cz/).
 license: GPL-3.0
-version: '1.0.1'
-date-released: '2026-02-11'
+version: '2.2.0'
+date-released: '2026-10-02'

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -1,123 +1,473 @@
-# AMCR Viewer: QGIS Plugin Documentation
+# AMČR Viewer — QGIS plugin
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![QGIS 3.44 – 4.x](https://img.shields.io/badge/QGIS-3.44%20%E2%80%93%204.x-589632.svg)](https://qgis.org/)
+[![Code quality](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/actions/workflows/code_quality.yml/badge.svg)](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/actions/workflows/code_quality.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18609813.svg)](https://doi.org/10.5281/zenodo.18609813)
 
-**Platform:** QGIS 3.4.x
+**AMČR Viewer** queries the Digital Archive of the Archaeological Map of the
+Czech Republic (AMČR) and turns the result into ordinary QGIS vector layers.
+It removes the manual export/import round trip: you filter the archive from
+inside QGIS and the matching records arrive as point, line and polygon layers
+with a full attribute table.
 
-**Module Type:** Data Acquisition & Visualization
-
-**Source Data:** Archaeological Map of the Czech Republic (AIS CR)
+| | |
+| --- | --- |
+| **Source data** | [Digital Archive AMČR](https://digiarchiv.aiscr.cz/) (AIS CR) |
+| **Supported QGIS** | 3.44.0 – 4.99.0 (Qt 5 and Qt 6) |
+| **Output** | temporary `memory` layers, S-JTSK / **EPSG:5514** |
+| **Access** | anonymous by default; optional login for non-public records |
+| **UI language** | Czech |
+| **Licence** | GPL-3.0 |
 
 ---
 
-## 1. Overview
+## 1. What it can download
 
-**AMCR Viewer** is a QGIS plugin designed to facilitate direct access to the Digital Archive of the Archaeological Map of the Czech Republic (AMČR). It allows researchers to **query, retrieve, and visualize *Fieldwork events* and *Sites* data (metadata and geometry) directly within the GIS environment**, eliminating the need to manually export data from the web interface. Both *Fieldwork events* and *Sites* layers may be accompanied by a *Components* layer with additional information. **Only publicly accessible data are supported at the time** (accessibility = anonymous).
+The plugin covers three AMČR record types. Each has its own menu entry, its
+own set of filters and its own attribute table.
 
+| Entity | Menu entry | What it is |
+| --- | --- | --- |
+| **Fieldwork events** (`akce`) | *Stáhnout data akcí* | Records of archaeological finds and observations tied to a place, a responsible body and a time of execution. |
+| **Sites** (`lokalita`) | *Stáhnout data lokalit* | Records tied to a site, its characteristic archaeological manifestation and presumed function. |
+| **Individual finds** (`samostatny_nalez`) | *Stáhnout data samostatných nálezů* | Records of individual movable finds reported through **AMČR-PAS**, the portal for amateur collaborators. |
 
-### Key Features
+Fieldwork events and Sites can additionally carry **component** data (period
+and activity area) directly in the attribute table. Individual finds have no
+components — period and dating are attributes of the find itself.
 
-* **Spatial Querying:** Option to filter records based on the current map canvas extent (Bounding Box).
-* **Advanced Attribute Filtering:** Supports multi-criteria filtering using controlled vocabularies.
-* **Dynamic Geometry Retrieval:** Automatically downloads and categorizes spatial data into Point, Line, and Polygon layers.
-* **Semantic Interoperability:** Automatically translates internal system codes into human-readable labels using the AIS CR API.
+### Key features
+
+* **Spatial querying** — restrict the query to the current map canvas extent.
+* **Multi-criteria attribute filtering** driven by AMČR controlled
+  vocabularies (*hesláře*), with a searchable multi-select picker per filter.
+* **Date range filtering** for fieldwork start/end and for the date of finding.
+* **Automatic geometry retrieval**, split into Point, Line and Polygon layers
+  and reprojected to S-JTSK.
+* **Human-readable labels** — internal codes (`HES-xxxxxx`) are translated via
+  the AIS CR translation dictionary.
+* **Authenticated access** — an AMČR account unlocks non-public records;
+  credentials are stored encrypted in the QGIS Authentication Manager.
 
 ---
 
-## 2. Installation Guide
+## 2. Installation
 
-**Install the plugin from QGIS plugin repository.**  
+### From the QGIS plugin repository (recommended)
 
-**OR**  
+*Plugins → Manage and Install Plugins… → search for* **AMČR Viewer** *→
+Install*.
 
-*1. Obtain the [plugin distribution package](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases) (ZIP archive containing the `amcr_viewer` directory).*  
-*2. Launch QGIS.*  
-*3. Navigate to Plugins → Manage and Install Plugins...*  
-*4. Select the Install from ZIP tab.*  
-*5. Locate the source ZIP file and click Install Plugin.*  
-*6. Upon successful installation, the AMCR download button (load AMCR data) will appear in the interface.*  
+### From a ZIP archive (older versions, or a build from source)
+
+1. Download a [release package](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases)
+   (a ZIP containing the `amcr_viewer` directory).
+2. In QGIS go to *Plugins → Manage and Install Plugins… → Install from ZIP*.
+3. Select the archive and click *Install Plugin*.
+
+Every successful CI run also publishes a ready-to-install `amcr_viewer.zip`
+as a build artifact, which is handy for testing a branch before release.
+
+After installation the **AMČR Viewer** button appears in the toolbar as a
+dropdown.
+
+### Requirements
+
+The plugin needs the **`requests`** library. It ships with the QGIS installers
+for Windows and macOS. On Linux distribution packages it may have to be
+installed separately (e.g. `python3-requests`).
 
 ---
 
-## 3. User Manual
+## 3. User manual
 
-### 3.1 Data Retrieval
+### 3.1 Toolbar and menu
 
-To initiate a search query, click either the **Stáhnout data akcí** or the **Stáhnout data lokalit** icon from the dropdown menu. The filter dialog provides the following options. Shown options vary based on the choosed tool.
+The toolbar button is a dropdown; the default action is *Stáhnout data akcí*.
 
-* **Spatial Filter:** *Checkbox "Limit search to current map extent":* If checked, the query is restricted to the geographical area currently visible in the QGIS canvas. If unchecked, the query searches the entire database (use with caution regarding data volume).
-* It is possible to view only those Fieldwork events with positive outcome, if "Positive findings only" is checked. Only *PIANs* marked as (or rather *PIANs* belonging to Documentation units marked as) "Type of evidence" = "positive" are rendered.
+| Menu entry | Action |
+| --- | --- |
+| *Stáhnout data akcí* | Opens the filter dialog for Fieldwork events. |
+| *Stáhnout data samostatných nálezů* | Opens the filter dialog for Individual finds. |
+| *Stáhnout data lokalit* | Opens the filter dialog for Sites. |
+| *Přihlásit se* | Opens the login dialog (see 3.2). |
+| *Nápověda AMČR Help* | Opens the online documentation in a browser. |
 
+### 3.2 Authentication (optional)
 
-* **Attribute Filters:**
-  * The dialog utilizes "Picker" widgets for controlled vocabularies (common: Region, District, Cadastral area, Period, Activity Area, *PIAN* accuracy; *events* related: Organisation, Researcher, Event type; *sites* related: Site type and class, Level of confidence, State of preservation).
-  * Click **Select...** to open a searchable selection window. Multiple values can be selected simultaneously (Logic: OR).
+By default the plugin sees only publicly accessible records. Logging in with
+an AMČR account extends the result set to everything the account is allowed
+to see.
 
+* The credentials are **verified against the API before they are stored** —
+  a wrong password never reaches the Authentication Manager. If the server is
+  unreachable, the plugin offers to store them unverified.
+* 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. The plugin checks
+  the login state before every download (via the `islogged` endpoint)
+  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*). Removing them also logs you out
+  of the Digital Archive, so the next download runs anonymously.
 
-* **Fieldwork Manager (Dynamic List):**
-  * Due to the dynamic nature of the persons database, the list of Fieldwork Managers is retrieved from the AIS CR servers and needs to be updated the first time (and subsequently, if there is need).
-  * To refresh the list from the server, click the **Refresh (🔄)** button next to the selection field. This downloads the latest list of researchers from the API.
+### 3.3 The filter dialog
 
-* **Components:** The *components* data are downloaded as well upon checking the corresponding check box. This enriches the main (*Events* and *Sites*) layers with additional information (period and activity area).
+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.
 
-* If no filter is used, all accessible Fieldwork events/PIANs are returned (although the number of Fieldwork events to be loaded is capped at 20000 records; it is advisable to set at least one filter).  
+#### Remembered filters, reset, clearing one filter
 
-For a more in-depth tutorial refer to the [AMČR Documentation](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
+* 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 |
+| --- | :---: | :---: | :---: | --- |
+| Omezit vyhledávání rozsahem okna | ✓ | ✓ | ✓ | `loc_rpt` |
+| Pouze pozitivní zjištění | ✓ | — | — | `posevidence` |
+| Pouze projektové akce | ✓ | — | — | `proj_akce` |
+| Kraj | ✓ | ✓ | ✓ | `f_kraj` |
+| Okres | ✓ | ✓ | ✓ | `f_okres` |
+| Katastr | ✓ | ✓ | ✓ | `f_katastr` |
+| Přístupnost | ✓ | ✓ | ✓ | `pristupnost` |
+| PIAN – přesnost | ✓ | ✓ | — | `f_pian_presnost` |
+| Organizace | ✓ | — | ✓ | `f_organizace` |
+| Vedoucí výzkumu | ✓ | — | — | `f_vedouci` |
+| Typ výzkumu | ✓ | — | — | `f_typ_vyzkumu` |
+| Datum — *Zahájení* / *Ukončení* | ✓ | — | — | `akce_datum_zahajeni`, `akce_datum_ukonceni` |
+| Lokalita – typ | — | ✓ | — | `f_typ_lokality` |
+| Lokalita – druh | — | ✓ | — | `f_druh_lokality` |
+| Lokalita – jistota určení | — | ✓ | — | `f_jistota` |
+| Lokalita – stav dochování | — | ✓ | — | `f_lokalita_zachovalost` |
+| Období | ✓ | ✓ | ✓ | `f_obdobi` |
+| Kategorie nálezu | — | — | ✓ | `f_kategorie` |
+| Druh nálezu | — | — | ✓ | `f_druh_nalezu` |
+| Materiál | — | — | ✓ | `f_specifikace` |
+| Okolnosti nálezu | — | — | ✓ | `f_nalezove_okolnosti` |
+| Nálezce | — | — | ✓ | `f_nalezce` |
+| Datum nálezu | — | — | ✓ | `samostatny_nalez_datum_nalezu` |
+| Areál | ✓ | ✓ | — | `f_areal` |
+| Načíst komponenty | ✓ | ✓ | — | — |
 
-### 3.2 Layer Structure & Attributes
+#### Spatial restriction
 
-Upon successful retrieval, the plugin generates four temporary memory layers:
+*Omezit vyhledávání rozsahem okna* is **checked by default**. The canvas
+extent is transformed from the project CRS to WGS-84 and sent as a bounding
+box. Unchecking it queries the whole database — do so with an attribute
+filter in place, otherwise you will hit the record cap (see 4.5).
 
-1. **AMCR Plochy (Polygons)**
-2. **AMČR Linie (Lines)**
-3. **AMČR Body (Points)**
-4. **AMČR Komponenty (*Components*/no geometry)**
+#### PIAN accuracy has a non-empty default
 
-The Attribute Table includes standardized fields with important metadata. The components layer has no geometry on its own and depend solely on a relation with the other three layers.
+> ⚠ *PIAN – přesnost* is the one filter that is **pre-selected**. For
+> Fieldwork events and Sites the dialog starts with *odchylka jednotky metrů*,
+> *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. *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
+
+Each date block has a *from* and a *to* picker; an empty picker shows
+*neomezeno* and means an open bound. The API rejects a one-sided range, so the
+plugin substitutes a sentinel (`0001-01-01` / `9999-12-31`) for the empty
+side. A block with **both** pickers empty adds no filter at all.
+
+A reversed range (start later than end) is refused when you confirm the
+dialog — such a query would come back empty and would be indistinguishable
+from a genuinely empty result.
+
+#### Codelists (hesláře)
+
+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
+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
+than a published vocabulary: *Vedoucí výzkumu* (`f_vedouci`, faceted over
+fieldwork events) and *Nálezce* (`f_nalezce`, faceted over individual finds).
+
+#### Components
+
+Check **Načíst komponenty** (Events and Sites only) to bring the period and
+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. 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
+dropped from the result.
+
+### 3.4 Output layers
+
+Up to three temporary `memory` layers are created per download, in **S-JTSK
+(EPSG:5514)**:
+
+* `AMCR_Akce_Body` / `_Linie` / `_Polygony`
+* `AMCR_Lokalita_Body` / `_Linie` / `_Polygony`
+* `AMCR_Samostatný_nález_Body` / `_Linie` / `_Polygony`
+
+A layer is only created if the query actually returned that geometry type.
+All layers of one download share the same attribute schema. Field names are
+ASCII; the human-readable names visible in the attribute table are QGIS field
+aliases.
+
+> Memory layers are **not persistent** — export them (GeoPackage, Shapefile,
+> …) before closing the project.
+
+Geometry is taken from the record's S-JTSK WKT when present; otherwise the
+WGS-84 fallback is reprojected. Invalid geometries are repaired rather than
+dropped.
+
+The tables below group the fields by meaning. In the layer they appear in the
+order *common → entity-specific → `pristupnost` → component fields*.
+
+#### Common fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `pian` | PIAN | Spatial unit (PIAN) identifier. *Events and Sites only.* |
+| `presnost` | Přesnost | Spatial accuracy \[units / tens / hundreds of metres / defined by cadastre\]. *Events and Sites only.* |
+| `pian_typ` | PIAN – typ | \[point / line / polygon\]. *Events and Sites only.* |
+| `dj` | Dokumentační jednotka | Documentation unit identifier. *Events and Sites only.* |
+| `typ_dj` | Typ dokumentační jednotky | \[trench / event part / whole event / cadastral territory\]. *Events and Sites only.* |
+| `akce` / `lokalita` / `samostatny_nalez` | Akce / Lokalita / Samostatný nález | Record identifier. |
+| `definicni_body` | Definiční bod(y) (WGS-84) | Feature centroid(s) in WGS-84. |
+| `odkaz_do_digiarchivu` | Odkaz do Digitálního archivu AMČR | Permalink to the record. |
+| `okres` | Okres | District. |
+| `katastr` | Katastr | Main cadastral area. |
+| `dalsi_katastry` | Další katastry | Other cadastral areas. *Always empty for individual finds.* |
+| `pristupnost` | Přístupnost | Record accessibility \[A/B/C/D\]. |
+
+#### Fieldwork event fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `akce_lokalizace` | Akce – lokalizace | Verbal description of the location. |
+| `vedouci` | Vedoucí akce | Main fieldwork manager. |
+| `organizace` | Organizace | Organisation conducting the research. |
+| `specifikace_data` | Specifikace data | \[exact date / exact years / sometime in years\]. |
+| `zahajeni` | Datum zahájeni | Start date. |
+| `ukonceni` | Datum ukončení | End date. |
+| `hlavni_typ` | Hlavní typ | Primary research method. |
+| `vedlejsi_typ` | Vedlejší typ | Secondary research methods. |
+| `zjisteni` | Zjištění | Whether the **documentation unit** is positive or negative evidence \[Pozitivní / Negativní\]. |
+| `nahrazuje_NZ` | Akce – nahrazuje NZ | Replaces a fieldwork report \[Ano / Ne\]. |
+| `projekt` | Projekt | Identifier of the related project, if any. |
+
+#### Site fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `nazev_lokality` | Název lokality | Site name. |
+| `popis_lokality` | Popis lokality | Site description. |
+| `typ_lokality` | Typ lokality | Site classification by definition method. |
+| `druh_lokality` | Druh lokality | Site classification by the nature of the field relics. |
+| `zachovalost` | Zachovalost | State of preservation. |
+
+#### Individual find fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `projekt` | Projekt | Identifier of the related project. |
+| `nalezce` | Nálezce | Finder. |
+| `datum` | Datum nálezu | Date of finding. |
+| `okolnosti` | Nálezové okolnosti | Finding context. |
+| `hloubka_cm` | Hloubka (cm) | Depth below surface. |
+| `lokalizace` | Lokalizace | Verbal description of the find spot. |
+| `obdobi` | Období | Period. |
+| `presna_datace` | Přesná datace | Precise dating, if known. |
+| `nalez` | Nález | Find class. |
+| `material` | Materiál | Find specification / material. |
+| `pocet` | Počet předmětů | Number of objects. |
+| `poznamka` | Poznámka/bližší popis | Note or closer description. |
+| `pred_org` | Předáno organizaci | Organisation the find was handed over to. |
+| `evidencni` | Evidenční číslo | Reference number. |
+
+#### Component fields (only with *Načíst komponenty*)
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `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
+
+Progress and errors are written to the QGIS *Messages* panel, tab **AMČR**
+(login goes to **AMČR login**). The log contains the **exact request URL**,
+so a suspicious query can be replayed in a browser instead of being
+reconstructed from the code. Distinct messages tell apart an empty result, an
+API error, a network failure and a result without any geometry.
+
+Only one download can run at a time; starting a second one while the first is
+still running is refused with a message.
+
+For a step-by-step tutorial see the
+[AMČR documentation](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html)
+(Czech only).
 
 ---
 
-## 4. Technical Architecture
+## 4. Technical notes
 
-The plugin is developed in **Python 3** using the **PyQt5** framework for the GUI and the **Requests** library for HTTP communication.
+The plugin is plain **Python 3** with **`requests`** for HTTP. The GUI is
+built through the **`qgis.PyQt`** compatibility layer rather than importing
+`PyQt5`/`PyQt6` directly, which is what lets a single source tree run on both
+QGIS 3.44 (Qt 5) and QGIS 4 (Qt 6). Every enum is referenced in its scoped
+form (`Qt.CheckState.Checked`, …), as required by Qt 6.
 
-### 4.1 File Structure
+### 4.1 Repository layout
 
-* `amcr_viewer.py`: Entry point; handles GUI integration and initialization.
-* `amcr_dialog.py`: Manages the UI logic, including the custom `FilterableSelectionDialog` for handling large vocabularies.
-* `amcr_tools.py`: Core logic module. Handles API requests, pagination, data parsing, and vector layer generation.
-* `amcr_codelists.py`: Manages local caching of controlled vocabularies (`codelists/*.csv`).
+```
+amcr_viewer/            the plugin package (this is what gets zipped)
+  __init__.py           classFactory() entry point for QGIS
+  amcr_viewer.py        toolbar/menu integration, login flow, dispatch
+  amcr_dialog.py        AmcrFilterDialog, FilterableSelectionDialog,
+                        LoginDialog, UpdateCodelistsTask
+  amcr_tools.py         API access, pagination, parsing, layer building
+  amcr_codelists.py     codelist download and CSV cache
+  codelists/heslar.csv  cached controlled vocabularies
+  i18n/                 Qt translation files
+  *.png                 toolbar and menu icons
+  metadata.txt          plugin metadata and changelog
+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
+```
 
-### 4.2 Data Flow & API Integration
+### 4.2 API endpoints
 
-The plugin interacts with three primary endpoints of the AIS CR infrastructure:
+| 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. |
 
-1. **Search API (Solr):**
-* Endpoint: `https://digiarchiv.aiscr.cz/api/search/query`
-* Method: `GET`
-* Parameters: `entity=akce`, `rows/page` (pagination).
-* Logic: The plugin implements a `while True` loop to handle pagination, processing data in batches of 500 records to ensure stability.
+### 4.3 Processing pipeline
 
+1. **Metadata** are paged in batches of **500** records, deduplicated by
+   `ident_cely`, until the reported `numFound` is reached or the cap is hit.
+2. Records **without geometry are skipped**; the rest are expanded into
+   documentation units and — if requested — into components.
+3. **Geometries** (PIAN) are fetched separately in batches of **200**
+   identifiers, to stay under URL length limits.
+4. Features are built, reprojected to EPSG:5514, sorted by geometry type and
+   added to the project in a single batch per layer.
 
-2. **Translation API:**
-* Endpoint: `https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json`
-* Function: Retrieves the mapping between system codes (e.g., `HES-xxxx`) and Czech labels. This dictionary is cached in memory during the session.
+### 4.4 Data persistence
 
+* **Codelists** — `amcr_viewer/codelists/heslar.csv`, rewritten only when the
+  user asks for an update.
+* **Credentials** — QGIS Authentication Manager; the config ID is kept in
+  `QSettings` under `amcr_viewer/auth_config_id`.
+* **Layers** — `memory` only, lost when QGIS closes.
 
-### 4.3 Data Persistence
+### 4.5 Limits
 
-* **Vocabularies:** Static vocabularies (e.g., Periods, Regions) are stored in `codelists/heslar.csv`.
-* **Dynamic Data:** The list of researchers is downloaded on-demand and cached in `codelists/vedouci.csv`.
-* **Layers:** Output layers are created as `memory` layers. They are non-persistent and will be lost if QGIS is closed without saving.
+* **20 000 records** per query (safety cap; QGIS would otherwise freeze).
+* **500** records per metadata request, **200** identifiers per geometry
+  request.
+* With components loaded, one output feature equals one component, so a
+  single PIAN can appear several times in the layer.
 
-### 4.4 Constraints
+---
 
-* **Record Limit:** A safety cap of 20,000 records is enforced.
-* **Batch Processing:** Geometry fetching is batched (50 IDs per request) to comply with URL length limitations and server load balancing.
+## 5. Development
+
+Contributor rules, branch naming and the manual QGIS test checklist live in
+[`AGENTS.md`](./AGENTS.md).
+
+Every pull request runs
+[`.github/workflows/code_quality.yml`](.github/workflows/code_quality.yml),
+which mirrors what plugins.qgis.org checks on upload and adds what it does
+not:
+
+| Job | What it does |
+| --- | --- |
+| **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 |
+
+Reproducing them locally:
+
+```bash
+python3 tests/check_sources.py
+ruff check .
+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
+```
+
+---
 
 ## 6. Links and resources
 
-* [AMCR/Digiarchive Documentation](https://amcr-help.aiscr.cz/) (only in Czech).
-* [AMCR Viewer tutorial](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
+* [AMČR / Digiarchiv documentation](https://amcr-help.aiscr.cz/) (Czech only)
+* [AMČR Viewer tutorial](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html)
+  (Czech only)
+* [AMČR-PAS](https://amcr-info.aiscr.cz/amcr-pas/) — the amateur collaborator
+  portal behind the Individual finds records
+* [Import/Export. Pluginy propojující QGIS s AMČR \[poster\]](https://zenodo.org/records/20504909)
+  (Czech only; describes v1.3.2)
+
+## Citing
+
+Cite the plugin using [`CITATION.cff`](./CITATION.cff) or the concept DOI
+[10.5281/zenodo.18609813](https://doi.org/10.5281/zenodo.18609813), which
+always resolves to the latest release.
+
+## Licence
+
+GPL-3.0 — see [`LICENSE`](./LICENSE).

amcr_viewer/__init__.py

@@ -31,6 +31,5 @@ def classFactory(iface):  # pylint: disable=invalid-name
     :param iface: A QGIS interface instance.
     :type iface: QgsInterface
     """
-    #
     from .amcr_viewer import AmcrViewer
     return AmcrViewer(iface)

amcr_viewer/amcr_codelists.py

@@ -1,19 +1,59 @@
-# -*- coding: utf-8 -*-
-import os
+# -*- coding: utf-8 -*-
 import csv
+import os
+import time
+import xml.etree.ElementTree as ET  # nosec
+
 import requests
+from qgis.core import Qgis, QgsMessageLog
 
 # Define paths for the plugin and its codelists directory
 PLUGIN_DIR = os.path.dirname(__file__)
 CODELISTS_DIR = os.path.join(PLUGIN_DIR, 'codelists')
+BASE_URL_AMCR = "https://api.aiscr.cz/2.2/oai"
+BASE_URL_DA = "https://digiarchiv.aiscr.cz/api/search/query"
+OUTPUT_FILE = os.path.join(CODELISTS_DIR, 'heslar.csv')
+
+slovnicek = {
+    'obdobi': (BASE_URL_AMCR, 'heslo:obdobi'),
+    'typ_akce': (BASE_URL_AMCR, 'heslo:akce_typ'),
+    'areal': (BASE_URL_AMCR, 'heslo:areal'),
+    'kraj': (BASE_URL_AMCR, 'ruian_kraj'),
+    'organizace': (BASE_URL_AMCR, 'organizace'),
+    'okres': (BASE_URL_AMCR, 'ruian_okres'),
+    'katastr': (BASE_URL_AMCR, 'ruian_katastr'),
+    'pian_presnost': (BASE_URL_AMCR, 'heslo:pian_presnost'),
+    'typ_lokality': (BASE_URL_AMCR, 'heslo:lokalita_typ'),
+    'druh_lokality': (BASE_URL_AMCR, 'heslo:lokalita_druh'),
+    'jistota': (BASE_URL_AMCR, 'heslo:jistota_urceni'),
+    'lokalita_zachovalost': (BASE_URL_AMCR, 'heslo:stav_dochovani'),
+    'pristupnost': (BASE_URL_AMCR, 'heslo:pristupnost'),
+    'nalez_kategorie': (BASE_URL_AMCR, 'heslo:predmet_druh_kat'),
+    'druh_nalezu': (BASE_URL_AMCR, 'heslo:predmet_druh'),
+    'specifikace': (BASE_URL_AMCR, 'heslo:predmet_specifikace'),
+    'nalezove_okolnosti': (BASE_URL_AMCR, 'heslo:nalezove_okolnosti'),
+    'vedouci': (BASE_URL_DA, 'f_vedouci'),
+    'nalezce': (BASE_URL_DA, 'f_nalezce'),
+}
+
+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/'
+}
+
 
 def ensure_codelists_dir():
     """Creates the codelists directory if it does not exist."""
     if not os.path.exists(CODELISTS_DIR):
         os.makedirs(CODELISTS_DIR)
 
+
 def parse_codelist_file(filename, target_dict=None):
-    """Reads a CSV codelist file and populates the target dictionary grouped by categories."""
+    """
+    Reads a CSV codelist file and populates
+    the target dictionary grouped by categories.
+    """
     if target_dict is None:
         target_dict = {}
 
@@ -25,7 +65,7 @@ def parse_codelist_file(filename, target_dict=None):
 
     try:
         # Open the file using standard UTF-8 encoding
-        with open(path, 'r', encoding='utf-8') as f:
+        with open(path, encoding='utf-8') as f:
             reader = csv.reader(f, delimiter=';')
 
             # Skip the CSV header row
@@ -39,108 +79,319 @@ def parse_codelist_file(filename, target_dict=None):
                     cat = row[2].strip()
                     clean = code if code else None
 
-                    # Initialize a new dictionary for a category if encountered for the first time
+                    # Initialize a new dictionary for a category if encountered
+                    # for the first time
                     if cat not in target_dict:
                         target_dict[cat] = {}
 
-                    # Assign the extracted code to the corresponding label within the category
+                    # Assign the extracted code to the corresponding label
+                    # within the category
                     target_dict[cat][label] = clean
+
     except Exception as e:
-        print(f"AMČR Codelist Read Error for {filename}: {e}")
+        QgsMessageLog.logMessage(
+            f"AMČR Codelist Read Error for {filename}: {e}",
+            "AMČR", Qgis.MessageLevel.Critical)
 
     return target_dict
 
+
 def load_all_data():
-    """Loads all static and dynamic codelists during plugin startup."""
+    """Loads the codelist during plugin startup."""
     ensure_codelists_dir()
-    
-    # Initialize the base structure with empty dictionaries for all expected categories
-    categorized_data = {
-        'obdobi': {}, 'typ_akce': {}, 'areal': {}, 
-        'kraj': {}, 'organizace': {}, 'okres': {}, 'katastr': {},
-        'vedouci': {}, 'pian_presnost': {}, 'typ_lokality': {}, 'druh_lokality': {},
-        'jistota': {}, 'lokalita_zachovalost': {}
-    }
-    
-    # Parse the default static codelist and the dynamically generated leaders codelist
+    categorized_data = {k: {} for k in slovnicek}
     parse_codelist_file('heslar.csv', categorized_data)
-    parse_codelist_file('vedouci.csv', categorized_data)
-    
     return categorized_data
 
-def download_vedouci():
-    """Fetches the list of leaders from the AMČR API and saves it to a CSV file."""
-    ensure_codelists_dir()
 
-    # API endpoint for fetching facet data for leaders
-    url = "https://digiarchiv.aiscr.cz/api/search/query?entity=akce&sort=datestamp%20desc&page=0&onlyFacets=True&rows=0"
+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 = {
+        "verb": "ListRecords",
+        "metadataPrefix": "oai_dc",
+        "set": api_set
+    }
+    params_da = {
+        "entity": "samostatny_nalez" if internal_name == "nalezce" else "akce",
+        "rows": 0,
+        "noFacets": "false",
+        "onlyFacets": "true"
+    }
+
+    while True:
+        # Check for cancellation at each iteration
+        if task and task.isCanceled():
+            return None
 
         try:
-        # Execute the GET request with a 20-second timeout
-        r = requests.get(url, timeout=20)
-        r.raise_for_status()
-        data = r.json()
+            if "digiarchiv" not in base_url:
+                response = requests.get(
+                    base_url, params=params_amcr, timeout=30
+                )
+                response.raise_for_status()
+                root = ET.fromstring(response.content)  # nosec
 
-        # Extract the leaders list from the JSON response using safe dict getters
-        vedouci_list = data.get('facet_counts', {}).get('f_vedouci', [])
-        if not vedouci_list:
-             vedouci_list = data.get('facet_counts', {}).get('facet_fields', {}).get('f_vedouci', [])
+                records = root.findall('.//oai:record', NS)
+                for rec in records:
+                    metadata = rec.find('.//oai_dc:dc', NS)
+                    if metadata is not None:
+                        # Code (identifier)
+                        identifier_el = metadata.find('dc:identifier', NS)
+                        kod = (
+                            identifier_el.text
+                            if identifier_el is not None
+                            else ""
+                        )
 
-        csv_path = os.path.join(CODELISTS_DIR, 'vedouci.csv')
+                        # Title – filter out system labels "AMČR - ..."
+                        titles = metadata.findall('dc:title', NS)
+                        nazev = ""
+                        for t in titles:
+                            if (
+                                t.text
+                                and not t.text.startswith("AMČR -")
+                                and not t.text.startswith(" AMČR -")
+                            ):
+                                nazev = t.text
+                                break
+                        # If no title passed the filter, fall back
+                        # to the first available one
+                        if not nazev and titles:
+                            nazev = titles[0].text
 
-        count = 0
+                        specialni_pripady = ['okres', 'katastr']
 
-        # Open the target CSV file for writing without extra blank lines
-        with open(csv_path, 'w', encoding='utf-8', newline='') as f:
-            writer = csv.writer(f, delimiter=';')
+                        if internal_name in specialni_pripady:
+                            kod = nazev
 
-            # Write the standard header required by the parser function
-            writer.writerow(['Název', 'Kód', 'Kategorie'])
+                        if internal_name == 'pristupnost':
+                            kod = next(
+                                (
+                                    t.text for t in titles
+                                    if t.text
+                                    and len(t.text) == 1
+                                    and t.text.isalpha()
+                                ),
+                                None
+                            )
+                            # Skip records without a valid one-letter code –
+                            # a None code would end up in the CSV and later
+                            # in the API filter as the string "None"
+                            if not kod:
+                                continue
 
-            # Iterate through the API results and format them for the CSV
-            for item in vedouci_list:
-                name = None
-                if isinstance(item, dict):
-                    name = item.get('name')
-                elif isinstance(item, str):
-                    name = item
+                        dataset.append({
+                            'Název': nazev,
+                            'Kód': kod,
+                            'Kategorie': internal_name
+                        })
 
-                # Ignore pure numbers (which are usually counts) and write valid names
-                if name and not str(name).isdigit():
-                    writer.writerow([name, name, 'vedouci'])
-                    count += 1
+                # Pagination
+                token = root.find('.//oai:resumptionToken', NS)
+                if token is not None and token.text:
+                    params_amcr = {
+                        "verb": "ListRecords",
+                        "resumptionToken": token.text
+                    }
+                    time.sleep(0.5)
+                else:
+                    break
 
-        return True, f"Staženo {count} jmen."
+            else:
+                response = requests.get(base_url, params=params_da, timeout=30)
+                response.raise_for_status()
+                data_json = response.json()
+
+                records = data_json['facet_counts']['facet_fields'][api_set]
+
+                for r in records:
+
+                    nazev = _facet_name(r)
+                    if not nazev:
+                        continue
+
+                    dataset.append({
+                            'Název': nazev,
+                            'Kód': nazev,
+                            'Kategorie': internal_name
+                        })
+
+                break
 
         except Exception as e:
-        return False, str(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)
+            return []
 
-# Initialize global codelist data when the module is imported
-_DATA = load_all_data()
+    return dataset
 
-# Safely extract individual categories into global variables for easy access across the plugin
-OBDOBI = _DATA.get('obdobi', {})
-TYP_AKCE = _DATA.get('typ_akce', {})
-AREAL = _DATA.get('areal', {})
-KRAJE = _DATA.get('kraj', {})
-ORGANIZACE = _DATA.get('organizace', {})
-OKRESY = _DATA.get('okres', {})
-KATASTRY = _DATA.get('katastr', {})
-VEDOUCI = _DATA.get('vedouci', {})
-PIAN_PRESNOST = _DATA.get('pian_presnost', {})
-TYP_LOKALITY = _DATA.get('typ_lokality', {})
-DRUH_LOKALITY = _DATA.get('druh_lokality', {})
-JISTOTA = _DATA.get('jistota', {})
-LOKALITA_ZACHOVALOST = _DATA.get('lokalita_zachovalost', {})
 
-def refresh_vedouci_cache():
-    """Reloads only the 'vedouci.csv' file to quickly update the cache without full initialization."""
-    # Parse only the targeted file containing the updated leaders
-    temp_data = parse_codelist_file('vedouci.csv')
-    new_vedouci = temp_data.get('vedouci', {})
+def _read_existing_rows():
+    """
+    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
 
-    # Clear the existing global dictionary and update it with the fresh data
+
+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)
+    for index, (key, value) in enumerate(slovnicek.items()):
+
+        base_url = value[0]
+        interni = key
+        api_nazev = value[1]
+
+        # Check if the user cancelled the task via the QGIS taskbar
+        if task and task.isCanceled():
+            return False
+
+        QgsMessageLog.logMessage(
+            f"Zpracovávám kategorii: {interni}...",
+            "AMČR", Qgis.MessageLevel.Info)
+
+        # Pass the task correctly to the updated fetch function
+        data = fetch_set(base_url, interni, api_nazev, task=task)
+
+        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)
+        if task:
+            progress = (index + 1) / total_sets * 100
+            task.setProgress(progress)
+
+    # 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=';',
+                                extrasaction='ignore')
+        writer.writeheader()
+        writer.writerows(all_data)
+
+    return True
+
+
+def refresh_globals():
+    """Reloads data from files into the global variables."""
+    data = load_all_data()
+
+    OBDOBI.clear()
+    OBDOBI.update(data.get('obdobi', {}))
+    TYP_AKCE.clear()
+    TYP_AKCE.update(data.get('typ_akce', {}))
+    AREAL.clear()
+    AREAL.update(data.get('areal', {}))
+    KRAJE.clear()
+    KRAJE.update(data.get('kraj', {}))
+    ORGANIZACE.clear()
+    ORGANIZACE.update(data.get('organizace', {}))
+    OKRESY.clear()
+    OKRESY.update(data.get('okres', {}))
+    KATASTRY.clear()
+    KATASTRY.update(data.get('katastr', {}))
     VEDOUCI.clear()
-    VEDOUCI.update(new_vedouci)
+    VEDOUCI.update(data.get('vedouci', {}))
+    PIAN_PRESNOST.clear()
+    PIAN_PRESNOST.update(data.get('pian_presnost', {}))
+    TYP_LOKALITY.clear()
+    TYP_LOKALITY.update(data.get('typ_lokality', {}))
+    DRUH_LOKALITY.clear()
+    DRUH_LOKALITY.update(data.get('druh_lokality', {}))
+    JISTOTA.clear()
+    JISTOTA.update(data.get('jistota', {}))
+    LOKALITA_ZACHOVALOST.clear()
+    LOKALITA_ZACHOVALOST.update(data.get('lokalita_zachovalost', {}))
+    PRISTUPNOST.clear()
+    PRISTUPNOST.update(data.get('pristupnost', {}))
+    NALEZ_KATEGORIE.clear()
+    NALEZ_KATEGORIE.update(data.get('nalez_kategorie', {}))
+    DRUH_NALEZU.clear()
+    DRUH_NALEZU.update(data.get('druh_nalezu', {}))
+    SPECIFIKACE.clear()
+    SPECIFIKACE.update(data.get('specifikace', {}))
+    NALEZOVE_OKOLNOSTI.clear()
+    NALEZOVE_OKOLNOSTI.update(data.get('nalezove_okolnosti', {}))
+    NALEZCE.clear()
+    NALEZCE.update(data.get('nalezce', {}))
 
-    return len(VEDOUCI)
+
+# Initialize empty dicts that will be populated immediately below
+OBDOBI = {}
+TYP_AKCE = {}
+AREAL = {}
+KRAJE = {}
+ORGANIZACE = {}
+OKRESY = {}
+KATASTRY = {}
+VEDOUCI = {}
+PIAN_PRESNOST = {}
+TYP_LOKALITY = {}
+DRUH_LOKALITY = {}
+JISTOTA = {}
+LOKALITA_ZACHOVALOST = {}
+PRISTUPNOST = {}
+NALEZ_KATEGORIE = {}
+DRUH_NALEZU = {}
+SPECIFIKACE = {}
+NALEZOVE_OKOLNOSTI = {}
+NALEZCE = {}
+
+refresh_globals()

amcr_viewer/amcr_viewer.py

@@ -1,13 +1,15 @@
 # -*- coding: utf-8 -*-
-from qgis.PyQt.QtCore import QSettings, QTranslator, QCoreApplication
-from qgis.PyQt.QtGui import QIcon
-from qgis.PyQt.QtWidgets import QMenu, QAction, QToolButton
-
-from .amcr_tools import load_amcr_data
-from .amcr_dialog import AmcrFilterDialog
-from .resources import *
 import os.path
 
+from qgis.core import Qgis
+from qgis.PyQt.QtCore import QCoreApplication, QSettings, QTranslator, QUrl
+from qgis.PyQt.QtGui import QDesktopServices, QIcon
+from qgis.PyQt.QtWidgets import QAction, QDialog, QMenu, QToolButton
+
+from .amcr_dialog import AmcrFilterDialog, LoginDialog
+from .amcr_tools import load_amcr_data, login_to_api
+
+
 class AmcrViewer:
     """
     Main plugin class that manages the GUI elements, menu entries,
@@ -22,14 +24,17 @@ class AmcrViewer:
         self.iface = iface
         self.plugin_dir = os.path.dirname(__file__)
 
-        # Determine the user's locale to load appropriate translation files
-        locale = QSettings().value('locale/userLocale')[0:2]
+        # Determine the user's locale to load appropriate translation files.
+        # The setting may be missing (None) on a fresh QGIS install.
+        locale = str(QSettings().value('locale/userLocale') or 'en')[0:2]
         locale_path = os.path.join(
             self.plugin_dir,
             'i18n',
-            'AmcrViewer_{}.qm'.format(locale))
+            f'AmcrViewer_{locale}.qm'
+        )
 
-        # Install the translator if a translation file for the current locale exists
+        # Install the translator if a translation file
+        # for the current locale exists
         if os.path.exists(locale_path):
             self.translator = QTranslator()
             self.translator.load(locale_path)
@@ -37,11 +42,14 @@ class AmcrViewer:
 
         # Initialize internal state
         self.actions = []
-        self.menu = self.tr(u'&AMČR Viewer')
+        self.menu = self.tr('&AMČR Viewer')
         self.first_start = None
 
     def tr(self, message):
-        """Helper method for translating strings within the AmcrViewer context."""
+        """
+        Helper method for translating strings within
+        the AmcrViewer context.
+        """
         return QCoreApplication.translate('AmcrViewer', message)
 
     def add_action(self, icon_path, text, callback, enabled_flag=True,
@@ -69,7 +77,8 @@ class AmcrViewer:
         if add_to_menu:
             self.iface.addPluginToMenu(self.menu, action)
 
-        # Store only actions that are directly attached to the QGIS UI for later cleanup
+        # Store only actions that are directly attached
+        # to the QGIS UI for later cleanup
         if add_to_toolbar or add_to_menu:
             self.actions.append(action)
 
@@ -82,16 +91,19 @@ class AmcrViewer:
         """
         # Define paths for action-specific icons
         icon_akce_path = os.path.join(self.plugin_dir, 'akce.png')
+        icon_pas_path = os.path.join(self.plugin_dir, 'sn.png')
         icon_lokality_path = os.path.join(self.plugin_dir, 'lokality.png')
+        icon_amcr_help_path = os.path.join(self.plugin_dir, 'amcr-help.png')
 
         # 1. Create a container menu for the plugin
         self.plugin_menu = QMenu()
 
         # 2. Create sub-actions (Download Projects / Download Sites)
-        # add_to_menu/toolbar is False because these go into our custom dropdown menu
+        # add_to_menu/toolbar is False because these go into our
+        # custom dropdown menu
         self.action_download_akce = self.add_action(
             icon_path=icon_akce_path,
-            text=self.tr(u'Stáhnout data akcí | AMČR Viewer'),
+            text=self.tr('Stáhnout data akcí | AMČR Viewer'),
             callback=lambda checked=False: self.run_download('akce'),
             parent=self.iface.mainWindow(),
             add_to_menu=False,
@@ -99,9 +111,20 @@ class AmcrViewer:
         )
         self.plugin_menu.addAction(self.action_download_akce)
 
+        self.action_download_pas = self.add_action(
+            icon_path=icon_pas_path,
+            text=self.tr('Stáhnout data samostatných nálezů | AMČR Viewer'),
+            callback=lambda checked=False: self.run_download(
+                'samostatny_nalez'),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_download_pas)
+
         self.action_download_lokality = self.add_action(
             icon_path=icon_lokality_path,
-            text=self.tr(u'Stáhnout data lokalit | AMČR Viewer'),
+            text=self.tr('Stáhnout data lokalit | AMČR Viewer'),
             callback=lambda checked=False: self.run_download('lokalita'),
             parent=self.iface.mainWindow(),
             add_to_menu=False,
@@ -109,9 +132,33 @@ class AmcrViewer:
         )
         self.plugin_menu.addAction(self.action_download_lokality)
 
+        self.action_login_dialog = self.add_action(
+            icon_path=icon_pas_path,
+            text=self.tr('Přihlásit se | AMČR Viewer'),
+            callback=lambda checked=False: self.login(),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_login_dialog)
+
+        self.action_amcr_help = self.add_action(
+            icon_path=icon_amcr_help_path,
+            text=self.tr('Nápověda AMČR Help | AMČR Viewer'),
+            callback=lambda checked=False: self.open_help(),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_amcr_help)
+
         # 3. Create the main project action and attach the menu to it
         main_icon = QIcon(icon_akce_path)
-        self.main_action = QAction(main_icon, 'AMČR Viewer', self.iface.mainWindow())
+        self.main_action = QAction(
+            main_icon,
+            'AMČR Viewer',
+            self.iface.mainWindow()
+        )
         self.main_action.setMenu(self.plugin_menu)
         self.iface.addPluginToMenu(self.menu, self.main_action)
 
@@ -120,9 +167,12 @@ class AmcrViewer:
         self.tool_button = QToolButton()
         self.tool_button.setMenu(self.plugin_menu)
         self.tool_button.setDefaultAction(self.action_download_akce)
-        self.tool_button.setPopupMode(QToolButton.MenuButtonPopup)
+        self.tool_button.setPopupMode(
+            QToolButton.ToolButtonPopupMode.MenuButtonPopup
+        )
 
-        # Add the widget directly to the toolbar and store the reference for cleanup
+        # Add the widget directly to the toolbar
+        # and store the reference for cleanup
         self.toolbar_action = self.iface.addToolBarWidget(self.tool_button)
 
         self.first_start = True
@@ -160,12 +210,38 @@ class AmcrViewer:
         dlg = AmcrFilterDialog(typ_dat)
         result = dlg.exec()
 
-        # If user confirmed the dialog (OK button), gather filters and load data
-        if result == 1:
+        # If user confirmed the dialog (OK button),
+        # gather filters and load data
+        if result == QDialog.DialogCode.Accepted:
             filters = dlg.get_filters()
             bbox = dlg.get_bbox()
             komponenty = dlg.get_komponenty()
 
-            # Access the map canvas and start the fetch/render process from amcr_tools
+            # Access the map canvas and start
+            # the fetch/render process from amcr_tools
             canvas = self.iface.mapCanvas()
             load_amcr_data(canvas, bbox, filters, typ_dat, komponenty)
+
+    def login(self):
+        dlg = LoginDialog(parent=self.iface.mainWindow())
+        result = dlg.exec()
+        if result == QDialog.DialogCode.Accepted:
+            username, password = LoginDialog.get_credentials()
+            session = login_to_api(username, password)
+            if session:
+                self.iface.messageBar().pushMessage(
+                    "AMČR",
+                    "Přihlášení proběhlo úspěšně.",
+                    level=Qgis.MessageLevel.Success
+                )
+            else:
+                self.iface.messageBar().pushMessage(
+                    "AMČR",
+                    "Přihlášení se nezdařilo – viz záložka AMČR login "
+                    "v panelu Zprávy.",
+                    level=Qgis.MessageLevel.Critical
+                )
+
+    def open_help(self):
+        help_url = "https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html"
+        QDesktopServices.openUrl(QUrl(help_url))

amcr_viewer/metadata.txt

@@ -5,13 +5,14 @@
 
 [general]
 name=AMČR Viewer
-qgisMinimumVersion=3.4
+qgisMinimumVersion=3.44.0
+qgisMaximumVersion=4.99.0
 description=Viewing and downloading the AMČR data.
-version=1.2.0
+version=2.2.0
 author=David Spáčil
 email=spacil@arub.cz
 
-about=This plugin is intended for downloading the data (Fieldwork events, Sites and their Components) from the Digiarchive of the Archaeological Map of the Czech Republic (https://digiarchiv.aiscr.cz/). As of now, only publicly accessible data can be downloaded.
+about=This plugin is intended for downloading the data (Fieldwork events, Sites, and their Components) from the Digital archive of the Archaeological Map of the Czech Republic (https://digiarchiv.aiscr.cz/).
 
 tracker=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/issues
 repository=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer
@@ -21,14 +22,55 @@ repository=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer
 
 hasProcessingProvider=no
 # Uncomment the following line and add your changelog:
-# changelog=
+changelog=
+  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
+  v2.1.1 (2026-09-01)
+   * Added download of Individual finds (PAS), including a dedicated menu entry
+   * Added filtering by date
+   * Added filtering of project fieldwork events and a Project column in the attribute table
+   * Codelists are now built from the Digiarchiv API as well, not only from OAI-PMH; persons come from its facets by role (finder, fieldwork leader)
+   * Updated the bundled codelist file
+   * Filter dialog is now scrollable
+   * Empty API results are now diagnosable from the Messages panel: the query URL and API errors are logged
+   * Code clean-up
+  v2.0.2 (2026-06-13)
+   * Plugin-wide fixes and optimalizations (details https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/pull/49)
+  v2.0.1 (2026-06-10)
+   * Fixed QGIS minimum version
+  v2.0.0 (2026-06-05)
+   * Added warning regarding the feature duplication when loading components to the dialog 
+   * Added Help button to the plugin menu
+   * Code clean-up
+  v2.0.0-alpha.4 (2026-06-03)
+   * Backend filtering of the results based on the component-related filters improvement (plugin not only loads the results from API, it filters them further)
+  v2.0.0-alpha.2–3 (2026-05-19)
+   * Security vulnerabilities fix
+  v2.0.0-alpha.1 (2026-05-19):
+   * Attribute fields renamed to be ASCII compliant
+   * Codelist update; codelist can be recompiled from AMČR API
+   * Base element changed from Documentation Unit to Component if user asks for components to simplify result filtering
+   * Plugin now supports logging with an AMČR account and enables the downloading of Events and Sites available to the roles Researcher and higher 
 
 # Tags are comma separated with spaces allowed
-tags=python,AMCR,AIS CR,archaeology,PIAN,AMČR
+tags=python,AMCR,AIS CR,archaeology,PIAN,AMČR,archeologie
 
 homepage=https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html
 category=Vector
-icon=download.png
+icon=akce.png
 # experimental flag
 experimental=False
 
@@ -40,9 +82,6 @@ deprecated=False
 # Check the documentation for more information.
 # plugin_dependencies=
 
-# Category of the plugin: Raster, Vector, Database or Web
-# category=
-
 # If the plugin can run on QGIS Server.
 server=False
 

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 PyQt5 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

@@ -0,0 +1,43 @@
+# Konfigurace lintů pro tento repozitář.
+#
+# Plugin se nedistribuuje jako Python balíček (do QGISu jde ZIP složky
+# amcr_viewer/), takže tenhle soubor nic nebalí ani neinstaluje – slouží
+# 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í.
+#
+# Flake8 záměrně žádnou konfiguraci nemá a běží s výchozími pravidly – stejně
+# 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"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle – chyby
+    "W",    # pycodestyle – varování
+    "F",    # pyflakes
+    "I",    # pořadí importů
+    "UP",   # zastaralé konstrukce
+    "B",    # bugbear
+    "C4",   # comprehensions
+    "SIM",  # zjednodušení
+    "RET",  # návratové hodnoty
+    "BLE",  # holé except
+]
+ignore = [
+    # Hlavička "# -*- coding: utf-8 -*-" je konvence šablony Plugin
+    # Builderu a drží se v celém projektu jednotně.
+    "UP009",
+    # "except Exception" je v pluginu záměr: výjimka nesmí propadnout do
+    # QGISu, chyba se uživateli ukáže v liště zpráv.
+    "BLE001",
+    # Obě dotčená místa mají ke každé větvi vysvětlující komentář,
+    # sloučením do jednoho výrazu by se čitelnost zhoršila.
+    "SIM103",
+    # contextlib.suppress() by kvůli jednomu místu přidal import a odsunul
+    # komentář, který vysvětluje, proč tam ta výjimka je.
+    "SIM105",
+]

src/icon.svg

@@ -9,7 +9,7 @@
    id="svg1"
    xml:space="preserve"
    sodipodi:docname="icon.svg"
-   inkscape:version="1.4.3 (0d15f75, 2025-12-25)"
+   inkscape:version="1.4.4 (dcaf3e7d9e, 2026-05-05)"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
    xmlns="http://www.w3.org/2000/svg"
@@ -24,12 +24,12 @@
      inkscape:deskcolor="#d1d1d1"
      inkscape:document-units="mm"
      inkscape:zoom="22.627417"
-     inkscape:cx="6.8059028"
-     inkscape:cy="14.606174"
+     inkscape:cx="0.57452426"
+     inkscape:cy="15.556349"
      inkscape:window-width="1920"
-     inkscape:window-height="1009"
-     inkscape:window-x="1912"
-     inkscape:window-y="-8"
+     inkscape:window-height="1131"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
      inkscape:window-maximized="1"
      inkscape:current-layer="layer1" /><defs
      id="defs1"><clipPath
@@ -96,4 +96,20 @@
        d="M 3.3486328 2.4970052 L 3.3486328 3.8323242 L 2.7424683 3.8323242 L 4.2085286 5.738151 L 5.674589 3.8323242 L 5.0684245 3.8323242 L 5.0684245 2.4970052 L 3.3486328 2.4970052 z "
        inkscape:export-filename="path32.png"
        inkscape:export-xdpi="3000"
-       inkscape:export-ydpi="3000" /></g></svg>
+       inkscape:export-ydpi="3000" /><rect
+       style="opacity:1;fill:#85140e;fill-opacity:1;stroke:none;stroke-width:0.414999;stroke-linecap:butt;stroke-linejoin:round;stroke-dasharray:none;paint-order:stroke fill markers"
+       id="rect1"
+       width="1.672105"
+       height="1.2511554"
+       x="-4.501821"
+       y="4.2814822" /><text
+       xml:space="preserve"
+       style="font-size:0.705556px;font-family:'Open Sans';-inkscape-font-specification:'Open Sans';text-align:start;writing-mode:lr-tb;direction:ltr;text-anchor:start;opacity:1;fill:#85140e;fill-opacity:1;stroke:none;stroke-width:0.414999;stroke-linecap:butt;stroke-linejoin:round;stroke-dasharray:none;paint-order:stroke fill markers"
+       x="-2.6360023"
+       y="5.1136947"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="font-size:0.705556px;fill:#85140e;fill-opacity:1;stroke-width:0.415"
+         x="-2.6360023"
+         y="5.1136947">lokality</tspan></text></g></svg>

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

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""
+Repository hygiene rules that need no QGIS and therefore run first.
+
+Each rule guards a mistake that has already happened here at least once,
+or one the plugins.qgis.org file analysis reports:
+
+* a UTF-8 BOM makes the official pyqgis4-checker skip the file entirely,
+  so a broken file looks clean – it is silent, which is what makes it bad
+* a direct PyQt5/PyQt6 import breaks the other Qt version
+* an executable or hidden file in the package is reported on upload
+
+Run it from the repository root:
+
+    python3 tests/check_sources.py
+"""
+
+import os
+import re
+import stat
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BALICEK = os.path.join(ROOT, "amcr_viewer")
+
+# Extensions that have no business inside a plugin package
+PODEZRELE = {".exe", ".dll", ".so", ".dylib", ".sh", ".bat", ".cmd",
+             ".pyc", ".pyd", ".jar", ".bin"}
+
+PRIMY_IMPORT = re.compile(r"^\s*(?:from|import)\s+PyQt[56]\b", re.MULTILINE)
+
+nalezy = []
+
+
+def zdrojaky():
+    for adresar, _, soubory in os.walk(BALICEK):
+        for soubor in sorted(soubory):
+            if soubor.endswith(".py"):
+                yield os.path.join(adresar, soubor)
+
+
+def vsechny_soubory():
+    for adresar, _, soubory in os.walk(BALICEK):
+        for soubor in sorted(soubory):
+            yield os.path.join(adresar, soubor)
+
+
+def zkratka(cesta):
+    return os.path.relpath(cesta, ROOT)
+
+
+for cesta in zdrojaky():
+    with open(cesta, "rb") as f:
+        zacatek = f.read(3)
+    if zacatek == b"\xef\xbb\xbf":
+        nalezy.append(f"{zkratka(cesta)}: UTF-8 BOM na začátku souboru")
+
+    with open(cesta, encoding="utf-8-sig") as f:
+        text = f.read()
+    for shoda in PRIMY_IMPORT.finditer(text):
+        radek = text[:shoda.start()].count("\n") + 1
+        nalezy.append(f"{zkratka(cesta)}:{radek}: přímý import z PyQt5/PyQt6, "
+                      f"použij shim qgis.PyQt")
+
+for cesta in vsechny_soubory():
+    jmeno = os.path.basename(cesta)
+    rezim = os.stat(cesta).st_mode
+    if rezim & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+        nalezy.append(f"{zkratka(cesta)}: spustitelná práva "
+                      f"({stat.filemode(rezim)})")
+    # 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")
+
+if nalezy:
+    print("Nálezy:")
+    for nalez in nalezy:
+        print(f"  {nalez}")
+    sys.exit(1)
+print("Kontrola zdrojáků: bez nálezů")

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

@@ -0,0 +1,667 @@
+# -*- coding: utf-8 -*-
+"""
+Smoke test: loads the plugin inside a real QGIS and exercises the parts
+that differ between Qt5 and Qt6.
+
+It is deliberately offline – no request ever leaves the machine, so the
+test says nothing about the AMCR API, only about the plugin loading and
+its widgets being constructible.
+
+Run it from the repository root:
+
+    python3 tests/smoke_test.py
+
+QGIS must be importable (inside the qgis/qgis Docker image it already is).
+The exit code is 0 when everything passed, 1 otherwise.
+"""
+
+import os
+import sys
+import traceback
+
+import requests
+
+# Offscreen, otherwise the dialogs 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)
+
+selhani = []
+
+
+def zkouska(nazev, funkce):
+    """Runs one check and keeps going even when it raises."""
+    try:
+        detail = funkce()
+    except Exception:
+        selhani.append(nazev)
+        print(f"  FAIL  {nazev}")
+        print(traceback.format_exc().rstrip())
+    else:
+        print(f"  OK    {nazev}" + (f" – {detail}" if detail else ""))
+
+
+from qgis.core import (  # noqa: E402
+    Qgis,
+    QgsApplication,
+    QgsTask,
+    QgsWkbTypes,
+)
+from qgis.PyQt import QtCore  # noqa: E402
+from qgis.PyQt.QtCore import QDate  # noqa: E402
+
+print(f"QGIS {Qgis.QGIS_VERSION.split('-')[0]} | Qt {QtCore.QT_VERSION_STR} "
+      f"| PyQt {QtCore.PYQT_VERSION_STR}")
+
+QgsApplication.setPrefixPath(os.environ.get("QGIS_PREFIX_PATH", "/usr"), True)
+qgs = QgsApplication([], True)
+qgs.initQgis()
+
+import amcr_viewer.amcr_codelists  # noqa: E402,F401
+import amcr_viewer.amcr_dialog as dialog  # noqa: E402
+import amcr_viewer.amcr_tools  # noqa: E402,F401
+import amcr_viewer.amcr_viewer  # noqa: E402,F401
+
+print("  OK    import všech modulů pluginu")
+
+
+def enumy():
+    """
+    The scoped enum forms must exist. Unscoped aliases still resolve in
+    QGIS 4.2, so a plain import proves nothing – these are read explicitly.
+    """
+    return (f"QgsTask.Flag.CanCancel={int(QgsTask.Flag.CanCancel)}, "
+            f"PointGeometry={int(QgsWkbTypes.GeometryType.PointGeometry)}, "
+            f"MessageLevel.Info={int(Qgis.MessageLevel.Info)}")
+
+
+def uloha():
+    ukol = dialog.UpdateCodelistsTask("smoke")
+    assert ukol.canCancel() is True
+    return "canCancel=True"
+
+
+def dialogy():
+    # A modal warning would block the offscreen run forever
+    dialog.QMessageBox.warning = staticmethod(lambda *a, **k: None)
+    popis = []
+    for typ in ("akce", "lokalita", "samostatny_nalez"):
+        okno = dialog.AmcrFilterDialog(typ)
+        okno.show()
+        QgsApplication.processEvents()
+        popis.append(f"{typ}: {len(okno.date_ranges)} rozmezí")
+        okno.close()
+    return ", ".join(popis)
+
+
+def filtr_datumu():
+    """
+    A half-filled range must be completed with the sentinel. The API
+    rejects a one-sided range, so this is the part worth guarding.
+
+    The expected value is written out on purpose – comparing against
+    dialog.DATE_OPEN_TO would only prove the module agrees with itself.
+    """
+    okno = dialog.AmcrFilterDialog("samostatny_nalez")
+    pole, _, od, _do = okno.date_ranges[0]
+    od.setDate(QDate(2016, 1, 1))
+    hodnota = okno.get_filters()[pole]
+    assert hodnota == "2016-01-01,9999-12-31", hodnota
+
+    # A range left completely empty must add no filter at all
+    prazdne = dialog.AmcrFilterDialog("samostatny_nalez")
+    pole_prazdne = prazdne.date_ranges[0][0]
+    assert pole_prazdne not in prazdne.get_filters()
+    prazdne.close()
+
+    okno.close()
+    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()
+
+if selhani:
+    print(f"\nNEPROŠLO: {', '.join(selhani)}")
+    sys.exit(1)
+print("\nVše prošlo")