diff --git a/docs/development.md b/docs/development.md
index 0b86690..f3c9ebd 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -150,25 +150,69 @@ Esempio: nuovo modulo `directions.py` che assorbe `EXIT_ALIASES` da
 
 ---
 
-## CI minima (Gitea Actions, opzionale)
+## CI/CD — Gitea Actions
 
-Esempio `.gitea/workflows/ci.yml`:
+I workflow vivono in `.gitea/workflows/`:
 
-```yaml
-name: CI
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.10"
-      - run: python -m pip install -e ".[dev]"
-      - run: pytest
-      - run: ruff check src tests
-```
+- **`ci.yml`** — ruff + matrix pytest su Python 3.10/3.11/3.12, trigger
+  su `push` e `pull_request` verso `main`. `concurrency.cancel-in-progress`
+  annulla i run sorpassati (utile per push consecutivi su PR).
+- **`release.yml`** — `gate` (ruff + pytest) → `build` (`python -m build`,
+  sdist + wheel) su tag `v*`. Gli artifact `viandante-*.tar.gz` e
+  `viandante-*.whl` finiscono nella pagina del job, scaricabili.
 
-Adatta ai vincoli del tuo runner Gitea (alcuni runner non hanno
-`actions/setup-python@v5`; pinning a versioni disponibili è tipico).
+**Stato operativit\u00e0**: l'infrastruttura YAML \u00e8 committata e pushata
+(v0.2.0 \u2192 `b20f3c0f`). Finch\u00e9 non registri un **runner** sul Gitea,
+i job restano in `queued` e il badge `[![ci](...)](...)` rimane grigio.
+Senza runner la pipeline non gira.
+
+### Setup del runner (una tantum)
+
+Sulla macchina che eseguir\u00e0 i job serve **Docker** (l'immagine
+`ubuntu-22.04` parte in un container):
+
+1. Genera il token di registrazione dalla UI:
+   `http://192.168.0.183:8085/-/admin/runners \u2192 "Crea nuovo runner"`
+   (NON \u00e8 il token account, \u00e8 un one-shot scelto da te).
+2. Avvia `act_runner` come container:
+
+   ```bash
+   docker run -d --name act_runner \
+     -e GITEA_INSTANCE_URL=http://192.168.0.183:8085 \
+     -e GITEA_RUNNER_REGISTRATION_TOKEN=<TOKEN_DEL_PUNTO_1> \
+     -e GITEA_RUNNER_NAME=homelab-runner \
+     -e GITEA_RUNNER_LABELS=self-hosted:docker://ubuntu-22.04:linux:amd64 \
+     -v /var/run/docker.sock:/var/run/docker.sock \
+     --restart unless-stopped \
+     gitea/act_runner:latest
+   ```
+
+3. Torna sulla UI `/-/admin/runners`: la riga `homelab-runner` passa a
+   `Online`. Da quel momento, ogni push triggera il workflow `ci.yml` e
+   il badge si colora.
+
+### Egress verso github.com (possibile blocker)
+
+Senza egress dal runner host a `github.com`, le action composite
+(`actions/checkout@v4`, `actions/setup-python@v5`,
+`actions/upload-artifact@v4`) non possono essere scaricate e il primo
+step fallisce con `failed to download action`. Workaround:
+
+- **Abilita il mirror Gitea** nel `app.ini` del server:
+  ```ini
+  [actions]
+  ENABLE_GITHUB_ACTIONS_MIRROR = true
+  ACTIONS_DEFAULT_BASE_URL = https://github.com
+  ```
+- Oppure bundle locale: pre-popolare le action in un image di runner.
+
+### Note pratiche
+
+- **Cache `pip`**: `cache: pip` + `cache-dependency-path: pyproject.toml`.
+  Cache key = `python-version + hash(pyproject.toml)`, quindi 3.10/3.11/3.12
+  hanno cache separate (no cross-version poisoning).
+- **Tag release pattern**: trigger su `v*` (`v0.2.0`, `v0.3`, `v1.0.0-rc1`).
+  Workflow di release: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+- **Badge `[![version](https://img.shields.io/...)](...)`** in README.md
+  \u00e8 hardcoded a `v0.2.0`: aggiornalo a mano a ogni release
+  (vedi checklist in `docs/gitea.md`).