diff --git a/docs/OPS-RUNBOOK-ARCHICRATIE-WEB.md b/docs/OPS-RUNBOOK-ARCHICRATIE-WEB.md
new file mode 100644
index 0000000..0fb2808
--- /dev/null
+++ b/docs/OPS-RUNBOOK-ARCHICRATIE-WEB.md
@@ -0,0 +1,69 @@
+# OPS Runbook — Archicratie Web (NAS Synology DS220 + Gitea)
+
+## 0. Objectif
+Ce document décrit la procédure **exacte** pour :
+- maintenir un état cohérent entre **Local (Mac Studio)**, **Gitea**, **NAS (prod)** ;
+- déployer proprement une release Docker (build, smoke, bascule) ;
+- éviter les régressions (branches protégées, CI bloquante, rollback).
+
+## 1. Invariants (à ne jamais violer)
+1) **La branche `main` sur Gitea = vérité canonique.**  
+2) La prod NAS doit être **rebuild** depuis `main` (pas de modifications “à la main” non versionnées).  
+3) Les variables `PUBLIC_GITEA_*` doivent pointer vers **le bon owner/repo** (sinon 404 / login loop).  
+4) En solo : PR requise OK, mais **0 approval** (sinon blocage). CI doit rester bloquante.  
+5) Interdiction : token/secret commité dans le repo.
+
+## 2. Topologie (NAS)
+- Arborescence :
+  - `/volume2/docker/archicratie-web/releases/<timestamp>/app`
+  - `/volume2/docker/archicratie-web/current` (symlink vers release active)
+- Services :
+  - `web_green` → port local typique `127.0.0.1:8082` (smoke)
+  - (optionnel) `web_blue` → `127.0.0.1:8081` (ancienne)
+- Script :
+  - `/volume2/docker/archicratie-web/ops/smoke.sh <port>`
+
+## 3. Standard Git (Gitea)
+### 3.1 Branches
+- `main` : branche de travail et de déploiement (par défaut)
+- `master` : branche legacy (archivée / conservée pour compat si nécessaire)
+- Stratégie : `master` est soit supprimée, soit alignée sur `main`, mais **pas** utilisée comme axe actif.
+
+### 3.2 Protection branches (solo recommandé)
+- `main` :
+  - ✅ Exiger PR (Require pull request)
+  - ✅ 0 approval (solo)
+  - ✅ Bloquer merge si CI KO (Prevent merge if checks fail)
+  - ✅ Désactiver force-push
+  - (optionnel) désactiver push direct (selon UI Gitea)
+- `master` :
+  - ✅ Interdire push direct
+  - ✅ Désactiver force-push
+  - ✅ Mention “legacy” (si UI le permet)
+
+## 4. Variables d’environnement (cause n°1 des 404)
+### 4.1 Variables publiques injectées au build
+- `PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me`
+- `PUBLIC_GITEA_OWNER=Archicratia`
+- `PUBLIC_GITEA_REPO=archicratie-edition`
+
+### 4.2 Règle d’or
+- Le site génère des liens `.../<OWNER>/<REPO>/issues/new?...`
+- Si OWNER/REPO est faux (ex: `archicratia/archicratie-web`) :
+  - `/issues` peut marcher
+  - MAIS `/issues/new` finit en 404 / redirect login / droits
+  - => corriger `.env` et rebuild
+
+## 5. Déploiement NAS (procédure protocolaire)
+### 5.1 Pré-check
+Sur NAS :
+- Vérifier qu’on est bien dans `/volume2/docker/archicratie-web/current`
+- Charger `.env` (pour build args)
+
+Commandes :
+```sh
+cd /volume2/docker/archicratie-web/current || exit 1
+set -a
+. ./.env
+set +a
+grep -nE '^PUBLIC_GITEA_(BASE|OWNER|REPO)=' .env