Merge pull request 'docs(ops): clarify canonical deploy doc + mark runbook/legacy' (#69) from docs/ops-sync-20260201 into main

Reviewed-on: #69

.env

@@ -1,3 +0,0 @@
-PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me
-PUBLIC_GITEA_OWNER=Archicratia
-PUBLIC_GITEA_REPO=archicratie-edition

.env.development

@@ -1,4 +0,0 @@
-PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me
-PUBLIC_GITEA_OWNER=Archicratia
-PUBLIC_GITEA_REPO=archicratie-edition
-PUBLIC_SITE=https://archicratie.trans-hands.synology.me

.env.local

@@ -1,5 +0,0 @@
-FORGE_API=http://192.168.1.20:3000
-FORGE_BASE=https://gitea.archicratie.trans-hands.synology.me
-FORGE_TOKEN=aW73wpfJ4MiN2!3UU69qL*vWF9$9V7f@2
-PUBLIC_GITEA_OWNER=Archicratia
-PUBLIC_GITEA_REPO=archicratie-edition

.env.production

@@ -1,6 +0,0 @@
-PUBLIC_SITE=https://archicratie.trans-hands.synology.me
-PUBLIC_RELEASE=0.1.0
-
-PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me
-PUBLIC_GITEA_OWNER=Archicratia
-PUBLIC_GITEA_REPO=archicratie-edition

docs/DEPLOY_PROD_SYNOLOGY_DS220.md

@@ -1,5 +1,15 @@
 # Déploiement production (Synology DS220+ / DSM 7.3) — Astro → Nginx statique
 
+> ✅ **CANONIQUE** — Procédure de référence “prod DS220+ / DSM 7.3”.
+
+> Toute modif de déploiement doit être faite **ici**, via PR sur Gitea/main (pas d’édition à la main en prod).
+
+> Périmètre : build Docker (Node→Nginx), blue/green 8081/8082, Reverse Proxy DSM, smoke, rollback.
+
+> Dépendances critiques : variables PUBLIC_GITEA_* (sinon “Proposer” part en 404/login loop).
+
+> Voir aussi : OPS-REFERENCE.md (index), OPS_COCKPIT.md (checklist), TROUBLESHOOTING.md (incidents).
+
 Dernière mise à jour : 2026-02-01
 
 Ce document décrit une mise en place stable sur NAS :

docs/OPS-DEPLOYMENT.md

@@ -1,6 +1,16 @@
-OPS — Déploiement Archicratie Web Edition (Mac Studio → DS220+)
+# OPS — Déploiement Archicratie Web Edition (Mac Studio → DS220+)
 Objectif : déployer une nouvelle version du site sur le NAS (DS220+) sans jamais casser la prod, en utilisant un schéma blue/green piloté par DSM Reverse Proxy, avec une procédure robuste même quand docker compose build est instable sur le NAS.
 
+> 🟧 **LEGACY / HISTORIQUE** — Ce document n’est plus la source de vérité.
+
+> Référence actuelle : docs/DEPLOY_PROD_SYNOLOGY_DS220.md (canonique).
+
+> Statut : gelé (on n’édite plus que pour ajouter un lien vers le canonique, si nécessaire).
+
+> Raison : doublon → risque de divergence → risque d’erreur en prod.
+
+> Si tu lis ceci pour déployer : stop → ouvre le canonique.
+
 ## 0) Repères essentiels
 Noms & domaines
     • Site public (prod) : https://archicratie.trans-hands.synology.me

docs/OPS-RUNBOOK-ARCHICRATIE-WEB.md

@@ -1,5 +1,15 @@
 # OPS Runbook — Archicratie Web (NAS Synology DS220 + Gitea)
 
+> 🟦 **ALIAS (résumé)** — Runbook 1-page pour opérer vite sans se tromper.
+
+> La procédure détaillée **canonique** est : docs/DEPLOY_PROD_SYNOLOGY_DS220.md.
+
+> Source Git : Gitea/main ; déploiement = rebuild depuis main ; pas de hotfix non versionné.
+
+> Déploiement : build sur slot inactif → smoke → bascule DSM → rollback si besoin.
+
+> Incidents connus : voir docs/TROUBLESHOOTING.md.
+
 ## 0. Objectif
 Ce document décrit la procédure **exacte** pour :
 - maintenir un état cohérent entre **Local (Mac Studio)**, **Gitea**, **NAS (prod)** ;

docs/OPS-SYNC-TRIPLE-SOURCE.md

@@ -71,8 +71,8 @@ Ce document décrit la synchronisation **sans ambiguïté** entre :
 
 ### Étape B — NAS : aligner `current` sur `origin/main`
 Sur NAS, git n’est pas forcément installé : on utilise un conteneur git.
+en sh :
 
-```sh
 APP="/volume2/docker/archicratie-web/current"
 U_ID="$(id -u)"; G_ID="$(id -g)"
 
@@ -89,3 +89,34 @@ git checkout -B main
 git reset --hard origin/main
 git status -sb
 '
+
+### Étape C — NAS : rebuild du slot inactif + smoke + bascule
+
+Rebuild de l’image (slot inactif recommandé).
+
+docker compose up -d --force-recreate --no-build web_green (ou blue)
+
+smoke test via script ou curl
+
+bascule DSM vers le port du slot actif
+
+## 4) Checkpoints rapides (sanity)
+### 4.1 Vérifier que NAS = origin/main
+
+git rev-parse --short HEAD sur NAS (via alpine/git)
+
+doit égaler origin/main.
+
+### 4.2 Vérifier “Proposer” (points minimum)
+
+PUBLIC_GITEA_OWNER=Archicratia (casse sensible)
+
+PUBLIC_GITEA_REPO=archicratie-edition
+
+Flow : Proposer → choix 1 → choix 2 → onglet Gitea /issues/new?... OK
+
+## 5) Rollback
+
+DSM reverse proxy : repasser sur l’autre port (8081/8082).
+
+En cas de code cassé : réaligner NAS sur origin/main précédent (tag/release) ou repointer /current vers une release précédente.

docs/TROUBLESHOOTING.md

@@ -53,6 +53,161 @@ Chercher `window.open` dans la page générée :
 - la commande doit retourner 0 lignes.
 
 Sur NAS :
-```sh
+en sh :
+
 curl -fsS http://127.0.0.1:8082/archicratie/archicrat-ia/chapitre-4/ > /tmp/page.html
 grep -n "window.open" /tmp/page.html | head
+
+Fix
+
+garder un seul mécanisme d’ouverture
+
+sur click : preventDefault() + stopImmediatePropagation()
+
+## 3) Favicon 504 / erreurs console sur favicon
+# Symptôme
+
+Console navigateur : GET /favicon.ico 504
+
+# Cause fréquente
+
+Cache du navigateur (ancienne erreur conservée).
+
+# Diagnostic
+
+Comparer :
+
+curl -I http://127.0.0.1:8082/favicon.ico
+
+curl -kI https://<domaine>/favicon.ico
+
+Si curl = 200 et navigateur = 504 → cache.
+
+# Fix
+
+Désactiver cache dans l’onglet Réseau (devtools)
+
+hard refresh
+
+vérifier droits fichiers dans dist/
+
+## 4) Sur NAS : git: command not found
+# Symptôme
+
+git fetch impossible sur le NAS.
+
+# Cause
+
+Git non installé sur DSM shell.
+
+# Fix standard (recommandé)
+
+Utiliser un conteneur git :
+
+APP="/volume2/docker/archicratie-web/current"
+U_ID="$(id -u)"; G_ID="$(id -g)"
+
+sudo docker run --rm --network host \
+  -u "$U_ID:$G_ID" -e HOME=/tmp \
+  -v "$APP":/repo -w /repo \
+  --entrypoint sh alpine/git -lc '
+set -eu
+git config --global --add safe.directory /repo
+git config http.sslVerify false
+git fetch origin --prune
+git status -sb
+'
+
+## 5) Git : “dubious ownership in repository”
+# Symptôme
+
+fatal: detected dubious ownership
+
+# Fix
+
+Dans le conteneur git (ou machine locale) :
+git config --global --add safe.directory /repo
+
+## 6) Git : non-fast-forward au push
+# Symptôme
+
+rejected (non-fast-forward)
+
+# Cause
+
+Ta branche locale est en retard vs remote.
+
+# Fix
+
+En général :
+
+on fait une PR depuis une branche
+
+ou on rebase/merge origin/main avant push
+
+Sur une branche de travail :
+git fetch origin
+git rebase origin/main
+# ou
+git merge origin/main
+
+## 7) Gitea : “Not allowed to push to protected branch main”
+# Symptôme
+
+pre-receive hook declined
+
+# Cause
+
+Protection de branche (normal/attendu).
+
+# Fix
+
+Push sur une branche
+
+Ouvrir PR
+
+Merger via UI Gitea
+
+## 8) Docker build : BuildKit / buildx / API version
+# Symptômes typiques
+
+the --network option requires BuildKit
+
+BuildKit is enabled but the buildx component is missing
+
+client version ... too new. Maximum supported API version ...
+
+# Fix “robuste” (principe)
+
+installer buildx si nécessaire
+
+si DSM/docker API ancienne : définir DOCKER_API_VERSION=<compatible> (selon ton environnement)
+
+garder le build en --network host si nécessaire
+
+## 9) Container Manager / Docker : “database is locked” (logging driver db)
+# Symptôme
+
+failed to initialize logging driver : database is locked
+
+# Cause
+
+Le driver de logs Docker est db (Synology) et sa DB est verrouillée.
+
+# Fix rapide
+
+Redémarrer “Container Manager” depuis le centre de paquets DSM.
+
+Vérifier que le conteneur redémarre ensuite.
+
+## 10) Checklist “tout marche”
+
+curl -I http://127.0.0.1:8082/ => 200
+
+curl -kI https://<domaine>/ => 200
+
+PUBLIC_GITEA_* corrects
+
+“Proposer” : 1 onglet, pas de 404, issue pré-remplie
+
+CI passe sur PR merge