diff --git a/README.md b/README.md
index b8f6996..66bacb4 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,46 @@
 
 Questo repository è un test per verificare il funzionamento delle **Actions** e dell'**automazione agentica** collegata a eventi su Gitea.
 
-Lo scopo è sperimentare l'esecuzione automatica di workflow in risposta a eventi come push, pull request e altri trigger, utilizzando agenti AI per operazioni di review, merge e gestione del repository.
\ No newline at end of file
+Lo scopo è sperimentare l'esecuzione automatica di workflow in risposta a eventi come push, pull request e altri trigger, utilizzando agenti AI per operazioni di review, merge e gestione del repository.
+
+## Workflow: `Gitea Actions Demo` (`.gitea/workflows/demo.yml`)
+
+Workflow dimostrativo che si attiva ad ogni **push** su qualsiasi branch. Esegue su un container `node:20-alpine` e stampa una serie di messaggi informativi via `echo` per illustrare il funzionamento base di Gitea Actions:
+- Mostra l'evento che ha scatenato il workflow (`gitea.event_name`)
+- Mostra il runner OS e il branch/repository coinvolto
+- Fa il checkout del codice tramite `actions/checkout@v4`
+- Elenca i file nella workspace
+- Comunica lo stato finale del job (`job.status`)
+
+Non esegue operazioni di modifica o deploy: è puramente a scopo educativo/dimostrativo.
+
+## Workflow: `OpenCode Gitea Integration` (`.gitea/workflows/opencode.yml`)
+
+Workflow di automazione agentica che integra **OpenCode** (agente AI) con Gitea. Si attiva su quattro eventi:
+
+| Evento | Descrizione |
+|---|---|
+| `issues: [opened]` | Apertura di una nuova issue |
+| `issue_comment: [created]` | Nuovo commento su una issue |
+| `pull_request_review_comment: [created]` | Nuovo commento su una PR (review) |
+| `workflow_dispatch` | Esecuzione manuale tramite UI / API |
+
+Il workflow procede solo se il corpo della issue/commento contiene `/oc` o `/opencode` (oppure se è un'esecuzione manuale). L'autore deve essere tra gli utenti autorizzati (`maria`, `nicola`), altrimenti il job viene interrotto.
+
+### Schema di esecuzione
+
+1. **Autorizzazione** — Verifica che l'utente sia nella whitelist.
+2. **Reazione 👀** — Aggiunge una reazione "eyes" al commento/issue di trigger (feedback visivo immediato senza generare nuovi eventi).
+3. **Checkout** — Clona il repository con storia completa (`fetch-depth: 0`).
+4. **Installazione OpenCode** — Scarica e installa la CLI di OpenCode via `curl | bash`.
+5. **Determinazione contesto** — Capisce se si è in una issue, in una PR o in esecuzione manuale:
+   - **PR**: fa il fetch e checkout del branch della PR.
+   - **Issue**: crea un nuovo branch `opencode-issue-<N>` a partire da `main`.
+   - **Manuale**: crea un branch `opencode-manual-<run_number>`.
+6. **Raccolta contesto** — Se si tratta di una PR, scarica il **diff** e i **commenti** recenti per fornire contesto all'agente.
+7. **Pulizia comando** — Rimuove `/oc` o `/opencode` dal prompt, lasciando solo le istruzioni utente.
+8. **Esecuzione OpenCode** — Lancia l'agente AI con modello `opencode/big-pickle`, passando il contesto raccolto e la richiesta dell'utente. L'agente può leggere, modificare e creare file nel repository.
+9. **Push e PR** — Se ci sono modifiche, le committa e le pusha sul branch. Se si sta lavorando su una issue (non PR), apre automaticamente una **Pull Request** verso `main`.
+10. **Reazione finale** — Aggiunge una reazione 🚀 in caso di successo o 😕 in caso di fallimento.
+
+Il workflow è progettato per evitare auto-trigger: le reazioni alle issue/commenti non generano eventi `issue_comment`, e il workflow non scrive mai commenti (solo reazioni), prevenendo loop infiniti.
\ No newline at end of file