gcomneno · Sep 19, 2026 · Sep 19, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,42 @@
+# Changelog
+
+All notable public changes to Lotto Digit Coverage Dynamics are recorded here.
+
+## [1.2.0] - 2026-09-19
+
+### Added
+
+- local/offline Svelte GUI and bilingual presentation infrastructure;
+- complete annual and consolidated historical archive tooling;
+- GiadaWare AI dynamic research translation boundary;
+- `db ask` semantic read-query interpretation for free Italian and English
+  historical queries;
+- Cifrolotto-owned versioned semantic query context;
+- structural SQLite read-query authority and bounded read-only executor;
+- model qualification documentation and deterministic semantic-query tests.
+
+### Changed
+
+- documentation authority is explicitly English-first, with Italian retained as
+  derived public presentation;
+- database maintenance supports safe multi-year orchestration and rollover;
+- CLI discovery and localization cover the expanded command surface;
+- natural-language database queries now use semantic grounding rather than the
+  superseded fixed-intent prototype.
+
+### Safety and reproducibility
+
+- model-generated SQL remains untrusted;
+- DML, DDL, administrative operations, undeclared schema access and unbounded
+  result execution fail closed;
+- deterministic CI does not require a real LLM;
+- real-model availability is explicitly separated from semantic qualification.
+
+## [1.1.0] - 2026-07-31
+
+- added historical occurrence tracing from a reference draw;
+- added same-wheel positional highlighting and validation;
+- published bilingual documentation for the feature.
+
+[1.2.0]: https://github.com/gcomneno/lotto-digit-coverage-dynamics/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/gcomneno/lotto-digit-coverage-dynamics/releases/tag/v1.1.0
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use this software or its published data in research, please cite it using the metadata below."
+title: "Lotto Digit Coverage Dynamics"
+type: software
+authors:
+  - family-names: "Comneno"
+    given-names: "Giancarlo Cicellyn"
+repository-code: "https://github.com/gcomneno/lotto-digit-coverage-dynamics"
+url: "https://github.com/gcomneno/lotto-digit-coverage-dynamics"
+license: MIT
+version: "1.2.0"
+date-released: "2026-09-19"
+keywords:
+  - Italian Lotto
+  - finite-state model
+  - Markov chain
+  - reproducibility
+  - historical data
+  - SQLite
+abstract: >-
+  Exact finite-state modelling and reproducible historical analysis of decimal
+  digit coverage in Italian Lotto draws, including deterministic mathematical
+  artifacts, historical SQLite archives and read-only semantic query tooling.
diff --git a/README.it.md b/README.it.md
@@ -154,8 +154,9 @@ Vedere il
 
 ## Interfaccia unificata da riga di comando
 
-I 16 strumenti eseguibili restano utilizzabili autonomamente, mentre `lotto.py`
-li espone attraverso un unico dispatcher facilmente esplorabile:
+I 20 strumenti principali restano utilizzabili autonomamente. `lotto.py`
+li espone attraverso un unico dispatcher, mentre `db ask` è un ulteriore
+comando annidato per interrogazioni storiche in linguaggio naturale:
 
 ```bash
 ./lotto.py list
@@ -194,7 +195,9 @@ Eseguire l’intera suite automatizzata:
 python3 -m unittest discover -v
 ```
 
-La suite corrente contiene 242 test.
+Al checkpoint release candidate del 19 settembre 2026 la suite esegue 465
+test; 2 test di integrazione vengono saltati quando il relativo database
+esterno non è disponibile.
 
 Verificare indipendentemente il kernel esatto:
 
@@ -269,7 +272,7 @@ una raccomandazione di gioco.
 ├── generated/                    artefatti matematici deterministici
 ├── strategies/                   implementazioni di riferimento
 ├── tests/                        test matematici e dei dati
-├── lotto.py                      dispatcher unico per tutti i 16 CLI
+├── lotto.py                      20 tool principali più il comando db ask
 ├── analyze_*.py                  analisi storiche e dello stato corrente
 ├── generate_state_atlas.py       atlante completo dei 1.023 stati
 ├── generate_structural_analysis.py
@@ -312,6 +315,36 @@ originariamente dichiarati; le nuove analisi devono specificare database,
 cutoff e trattamento dei cambiamenti di regime storico prima di valutare i
 risultati.
 
+## Query storiche in linguaggio naturale
+
+`db ask` interpreta richieste libere in italiano o inglese attraverso il
+contratto pubblico di GiadaWare AI, ma l'output del modello non acquisisce mai
+autorità SQL.
+
+Installare la dipendenza AI fissata a commit:
+
+```bash
+python3 -m pip install -r requirements-ai.txt
+```
+
+Per una prova basata esclusivamente su dati tracciati nel repository:
+
+```bash
+./lotto.py db ask \
+    --database data/lotto-2025.sqlite3 \
+    "Cos'è uscito su Napoli nell'ultima estrazione?"
+```
+
+Senza `--database`, il comando usa `data/lotto-current.sqlite3`, archivio
+corrente mutabile e intenzionalmente escluso da Git. Va quindi creato o
+aggiornato localmente con `./lotto.py db update`.
+
+La disponibilità di un modello reale non equivale a qualificazione semantica.
+Le valutazioni di riferimento attualmente registrate a monte per
+`qwen2.5:1.5b-instruct` e `qwen3.5:2b-q4_K_M` risultano entrambe
+**NOT QUALIFIED**. I gate Cifrolotto di autorizzazione ed esecuzione rimangono
+indipendenti e fail-closed.
+
 ## Licenza
 
 Distribuito secondo i termini della [licenza MIT](LICENSE).

diff --git a/README.md b/README.md
@@ -148,8 +148,9 @@ See the complete
 
 ## Unified command-line interface
 
-The 17 executable tools remain independently usable, while `lotto.py` exposes
-them through one discoverable dispatcher:
+The 20 top-level tools remain independently usable. `lotto.py` exposes them
+through one discoverable dispatcher, while `db ask` is an additional nested
+natural-language read-query command:
 
 ```bash
 ./lotto.py list
@@ -186,7 +187,9 @@ Run the complete automated suite:
 python3 -m unittest discover -v
 ```
 
-The current suite contains 242 tests.
+At the 19 September 2026 release-candidate checkpoint, the suite runs 465
+tests; 2 integration tests are skipped when their external database fixture is
+not available.
 
 Verify the exact transition kernel independently:
 
@@ -295,7 +298,7 @@ recommendation.
 ├── generated/                    deterministic mathematical artifacts
 ├── strategies/                   reference model implementations
 ├── tests/                        automated mathematical and data tests
-├── lotto.py                      unified dispatcher for all 18 CLI tools
+├── lotto.py                      dispatcher for 20 top-level tools plus db ask
 ├── analyze_*.py                  historical and current-state analyses
 ├── generate_state_atlas.py       complete 1,023-state atlas
 ├── generate_structural_analysis.py
@@ -354,18 +357,36 @@ Install the pinned GiadaWare AI dependency in an isolated Python environment:
 python3 -m pip install -r requirements-ai.txt
 ```
 
-Examples:
+Examples using a database tracked in the repository:
 
 ```bash
-./lotto.py db ask "Cos'è uscito su Napoli nell'ultima estrazione?"
-./lotto.py db ask --language en "Show Milan draws containing 18."
+./lotto.py db ask \
+    --database data/lotto-2025.sqlite3 \
+    "Cos'è uscito su Napoli nell'ultima estrazione?"
+
+./lotto.py db ask \
+    --database data/lotto-2025.sqlite3 \
+    --language en \
+    "Show Milan draws containing 18."
 ```
 
+Without `--database`, `db ask` uses `data/lotto-current.sqlite3`. That mutable
+current-year database is intentionally ignored by Git; create/update it locally
+with `./lotto.py db update` before relying on the default path.
+
 Italian is the default request and presentation language for `db ask` only. The repository-wide canonical locale remains English.
 
 GiadaWare AI interpretation does not grant SQL execution authority. Candidate queries are independently authorized and executed through SQLite read-only controls.
 
-Real-model availability is not semantic qualification. Deterministic CI uses controlled backends and does not require Ollama.
+Real-model availability is not semantic qualification. Deterministic CI uses
+controlled backends and does not require Ollama.
+
+The default local model name is an infrastructure convenience, not a statement
+of qualification. The reference evaluations currently recorded upstream for
+`qwen2.5:1.5b-instruct` and `qwen3.5:2b-q4_K_M` are both **NOT QUALIFIED** for
+the semantic read-query capability. The Cifrolotto authorization and execution
+boundary remains valid independently and fails closed when interpretation does
+not satisfy the contract.
 
 
 ### Opt-in real-runtime qualification

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -22,17 +22,20 @@ All original scripts remain directly executable.
 
 | Command | Underlying executable | Purpose |
 |:---|:---|:---|
-| `current` | `analyze_current_coverage.py` | Current Markov ranking, transversal row and active anomalies |
+| `current` | `analyze_current_consensus.py` | Current Markov ranking, transversal row and active anomalies |
 | `update` | `update_lotto_database.py` | Conservative current-database update |
 | `db update` | `update_lotto_databases.py` | Safe single-year, range and rollover orchestration |
 | `db` | `view_lotto_database.sh` | Terminal database browser |
+| `db ask` | semantic read-query pipeline | Natural-language read-only queries over declared Lotto data |
+| `gui` | `lotto_digit_coverage/interfaces/gui/launcher.py` | Local/offline GIADA UI application |
 | `anomalies` | `analyze_coverage_anomalies.py` | Historical A1–A4 anomaly analysis |
 | `completion` | `analyze_coverage_completion.py` | Natural-cycle completion analysis |
 | `residuals` | `analyze_coverage_markov_residuals.py` | Theoretical and observed residual-time comparison |
 | `validation` | `analyze_coverage_markov_validation.py` | Empirical calibration of Markov probabilities |
 | `digit-coverage` | `analyze_digit_coverage.py` | Digit coverage over moving windows |
 | `rolling-frequency` | `analyze_rolling_frequency.py` | Walk-forward rolling-frequency backtest against equal-size random sets |
 | `coverage-hits` | `analyze_coverage_hit_statistics.py` | Recent near-closure statistics by TOP and missing-digit counts |
+| `twins` | `analyze_twin_numbers.py` | Ex-ante twin-number analysis against the declared null |
 | `return-times` | `analyze_digit_return_times.py` | Digit return-time analysis |
 | `cycles` | `analyze_historical_cycle_distribution.py` | Historical cycle-duration comparison |
 | `symmetry-history` | `analyze_historical_symmetry_classes.py` | Historical structural-class analysis |
@@ -48,10 +51,48 @@ Aliases:
 - `digits` → `digit-coverage`;
 - `rolling` → `rolling-frequency`;
 - `hits` → `coverage-hits`;
+- `gemelli` → `twins`;
 - `returns` → `return-times`;
 - `cycle-distribution` → `cycles`;
 - `symmetry` → `symmetry-history`.
 
+## Natural-language database queries
+
+`db ask` accepts free Italian or English read requests over the versioned
+Cifrolotto semantic context.
+
+Install the pinned GiadaWare AI dependency:
+
+```bash
+python3 -m pip install -r requirements-ai.txt
+```
+
+Use a tracked historical database for a reproducible repository-only example:
+
+```bash
+./lotto.py db ask \
+  --database data/lotto-2025.sqlite3 \
+  "Cos'è uscito su Napoli nell'ultima estrazione?"
+
+./lotto.py db ask \
+  --database data/lotto-2025.sqlite3 \
+  --language en \
+  "Show Milan draws containing 18."
+```
+
+Without `--database`, the command selects the mutable ignored
+`data/lotto-current.sqlite3`, which must first be created or updated locally.
+
+GiadaWare AI provides semantic interpretation only. Candidate SQL is untrusted
+and must independently pass Cifrolotto's structural SQL authority and read-only
+SQLite execution boundary.
+
+Real-model qualification is opt-in and model-specific. The currently recorded
+reference evaluations for `qwen2.5:1.5b-instruct` and
+`qwen3.5:2b-q4_K_M` are both **NOT QUALIFIED** for this capability.
+Deterministic CI therefore uses controlled backends and does not claim that a
+locally available model is semantically qualified.
+
 ## Rolling-frequency backtest
 
 ```bash

diff --git a/docs/index.md b/docs/index.md
@@ -11,6 +11,8 @@ English documentation is authoritative. Italian documentation is derived present
 - [Limitations](limitations.md)
 - [Reproducibility](reproducibility.md)
 - [Command-line reference](cli-reference.md)
+- [Release history](../CHANGELOG.md)
+- [Citation metadata](../CITATION.cff)
 - [Glossary](glossary.md)
 
 ## Mathematical model

diff --git a/docs/it/cli-reference.md b/docs/it/cli-reference.md
@@ -22,17 +22,20 @@ Tutti gli script originali restano direttamente eseguibili.
 
 | Comando | Eseguibile sottostante | Scopo |
 |:---|:---|:---|
-| `current` | `analyze_current_coverage.py` | Classifica Markov corrente, riga trasversale e anomalie attive |
+| `current` | `analyze_current_consensus.py` | Classifica Markov corrente, riga trasversale e anomalie attive |
 | `update` | `update_lotto_database.py` | Aggiornamento prudente del database corrente |
 | `db update` | `update_lotto_databases.py` | Orchestrazione sicura per anno, intervallo e rollover |
 | `db` | `view_lotto_database.sh` | Esplorazione del database da terminale |
+| `db ask` | pipeline semantica read-query | Query in linguaggio naturale sui dati Lotto dichiarati |
+| `gui` | `lotto_digit_coverage/interfaces/gui/launcher.py` | Applicazione locale/offline basata su GIADA UI |
 | `anomalies` | `analyze_coverage_anomalies.py` | Analisi storica delle anomalie A1–A4 |
 | `completion` | `analyze_coverage_completion.py` | Analisi del completamento dei cicli naturali |
 | `residuals` | `analyze_coverage_markov_residuals.py` | Confronto dei tempi residui teorici e osservati |
 | `validation` | `analyze_coverage_markov_validation.py` | Calibrazione empirica delle probabilità Markov |
 | `digit-coverage` | `analyze_digit_coverage.py` | Copertura delle cifre su finestre mobili |
 | `rolling-frequency` | `analyze_rolling_frequency.py` | Backtest walk-forward delle frequenze rolling contro rose casuali equivalenti |
 | `coverage-hits` | `analyze_coverage_hit_statistics.py` | Statistiche recenti delle quasi-chiusure per quantità TOP e Mancanti |
+| `twins` | `analyze_twin_numbers.py` | Analisi ex ante dei numeri gemelli rispetto al null dichiarato |
 | `return-times` | `analyze_digit_return_times.py` | Analisi dei tempi di ritorno delle cifre |
 | `cycles` | `analyze_historical_cycle_distribution.py` | Confronto storico delle durate dei cicli |
 | `symmetry-history` | `analyze_historical_symmetry_classes.py` | Analisi storica delle classi strutturali |
@@ -48,10 +51,42 @@ Alias:
 - `digits` → `digit-coverage`;
 - `rolling` → `rolling-frequency`;
 - `hits` → `coverage-hits`;
+- `gemelli` → `twins`;
 - `returns` → `return-times`;
 - `cycle-distribution` → `cycles`;
 - `symmetry` → `symmetry-history`.
 
+## Query del database in linguaggio naturale
+
+`db ask` accetta richieste libere in italiano o inglese sul contesto semantico
+versionato di Cifrolotto.
+
+Installare la dipendenza GiadaWare AI fissata a commit:
+
+```bash
+python3 -m pip install -r requirements-ai.txt
+```
+
+Esempio riproducibile con un database storico tracciato:
+
+```bash
+./lotto.py db ask \
+  --database data/lotto-2025.sqlite3 \
+  "Cos'è uscito su Napoli nell'ultima estrazione?"
+```
+
+Senza `--database` viene usato il database mutabile e ignorato
+`data/lotto-current.sqlite3`, che deve prima essere creato o aggiornato
+localmente.
+
+GiadaWare AI interpreta la richiesta ma non concede autorità SQL. La query
+candidata deve superare indipendentemente l'authority strutturale Cifrolotto e
+l'esecuzione SQLite in sola lettura.
+
+La qualificazione dei modelli reali è separata e opt-in. Le valutazioni di
+riferimento attualmente registrate per `qwen2.5:1.5b-instruct` e
+`qwen3.5:2b-q4_K_M` risultano entrambe **NOT QUALIFIED**.
+
 ## Backtest delle frequenze rolling
 
 ```bash