docs(ops): add triple-source sync + troubleshooting + proposer spec

docs/FEATURE-PROPOSER.md

@@ -0,0 +1,103 @@
+# FEATURE — “Proposer” (édition par paragraphe → issue Gitea)
+
+Dernière mise à jour : 2026-02-01
+
+Cette feature permet à un lecteur de proposer une correction/amélioration d’un paragraphe, en générant une issue pré-remplie dans Gitea.
+
+---
+
+## 0) Objectif fonctionnel
+Depuis une page chapitre :
+1) clic sur **Proposer** sur un paragraphe
+2) choix #1 (type)
+3) choix #2 (state/catégorie selon UI)
+4) ouverture d’un seul onglet vers Gitea : `/issues/new?...`
+5) issue pré-remplie avec :
+   - chemin / URL / ancre
+   - texte actuel (citation)
+   - champs “Proposition / Justification”
+6) l’utilisateur valide, et le runner/CI traite.
+
+---
+
+## 1) Dépendances de configuration (critique)
+
+Le lien Gitea est construit à partir de variables publiques injectées au build Astro :
+
+- `PUBLIC_GITEA_BASE` (ex: `https://gitea.archicratie.trans-hands.synology.me`)
+- `PUBLIC_GITEA_OWNER` (**casse sensible**, ex: `Archicratia`)
+- `PUBLIC_GITEA_REPO` (ex: `archicratie-edition`)
+
+### Symptômes si mauvais
+- mauvais repo → 404
+- redirect login inattendu
+- création d’issues impossible
+
+---
+
+## 2) Contrat “une seule ouverture d’onglet”
+Le flow ne doit jamais ouvrir deux onglets.
+
+### Contrat
+- pas de `window.open(...)`
+- un seul `a.target="_blank"` (ou équivalent) déclenché
+- sur click : handler doit neutraliser les propagations parasites
+
+### Vérification (NAS)
+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
+
+Doit retourner 0 ligne.
+
+## 3) Diagnostic “trace ouverture onglet” (navigateur)
+
+Dans la console, tu peux surcharger temporairement les mécanismes d’ouverture pour tracer :
+
+si un window.open survient,
+
+ou si un a.click target _blank est appelé.
+
+But : prouver qu’il n’y a qu’un seul événement d’ouverture.
+
+## 4) URL attendue (forme)
+
+L’onglet doit ressembler à :
+
+{PUBLIC_GITEA_BASE}/{OWNER}/{REPO}/issues/new?title=...&body=...
+
+Important : owner et repo doivent être exactement ceux du repo canonique.
+
+## 5) Pré-requis d’accès
+
+L’utilisateur doit être loggé sur Gitea pour accéder à /issues/new
+
+Si non loggé : redirect vers /user/login (comportement normal)
+
+## 6) Tests fonctionnels (checklist)
+
+Ouvrir une page chapitre (ex chapitre 4)
+
+Clic Proposer (sur un paragraphe)
+
+Choix 1 puis choix 2
+
+Vérifier :
+
+1 seul onglet
+
+URL du repo correct
+
+formulaire new issue visible
+
+title/body pré-remplis (chemin + ancre + texte actuel)
+
+Créer l’issue → vérifier le traitement CI/runner
+
+## 7) Pannes typiques + causes
+
+404 sur issue/new : PUBLIC_GITEA_OWNER/REPO faux (souvent casse)
+
+2 onglets : double handler (bubbling + ouverture multiple)
+
+pas de favicon : cache ou absence dans public/ → rebuild