Seed from NAS prod snapshot 20260130-190531

docs/QUICKSTART.md

@@ -0,0 +1,184 @@
+# Quickstart — 10 minutes (Proposer → Ticket → Apply → Tests)
+
+## 1) Pré-requis
+- Node.js + npm
+- Accès Gitea (compte) + PAT si usage API (apply-ticket)
+
+## 2) Lancer le site
+en bash :
+npm install
+npm run dev
+
+Dans le navigateur, url : http://localhost:4321
+
+## 3) Proposer une correction
+
+Ouvre une page (ex: Prologue).
+
+Sur un paragraphe : clique Proposer.
+
+Choisis :
+
+Type : Correction / Fact-check
+
+Category (optionnel)
+
+Un nouvel onglet Gitea s’ouvre sur une issue pré-remplie.
+
+Rédige :
+
+Proposition (remplacer par):
+
+Justification:
+
+## 4) Appliquer le ticket en local (<NUMERO> = numéro du ticket non pas id-paragraphe)
+
+En bash :
+
+# dry-run (recommandé)
+node scripts/apply-ticket.mjs <NUMERO> --dry-run
+
+# appliquer
+node scripts/apply-ticket.mjs <NUMERO>
+git diff
+git add <fichier>
+git commit -m "edit: apply ticket #<NUMERO> (...)"
+
+## 5) Vérifier avant push
+
+npm test
+
+## 6) Règle d’or
+
+Ne jamais éditer dist/ à la main.
+
+Toujours garder Chemin + Ancre + Proposition dans le ticket.
+
+Déplacer/ajouter les deux docs que je t’ai donnés
+- `docs/MANUEL_REFERENCE.md`
+- `docs/CONTRAT_TICKETS.md`
+
+*(Tu peux reprendre mes versions telles quelles.)*
+
+---
+
+## Commandes terminal P0 (copier-coller)
+En bash
+mkdir -p docs
+
+# crée/édite les fichiers avec ton éditeur habituel
+# README.md
+# docs/QUICKSTART.md
+# docs/MANUEL_REFERENCE.md
+# docs/CONTRAT_TICKETS.md
+
+git status -sb
+npm test
+git add docs/QUICKSTART.md docs/MANUEL_REFERENCE.md docs/CONTRAT_TICKETS.md
+git commit -m "docs: add quickstart + reference manual + ticket contract"
+git push
+
+## Checklist express (60 secondes) — valider l’outil d’édition
+Après `npm run dev` :
+
+1) Ouvrir un chapitre (page “reading”).
+2) Hover un paragraphe : les tools apparaissent à droite.
+3) Cliquer `Citer` : une citation est copiée (ou prompt fallback).
+4) Cliquer `Marque-page` puis vérifier le bouton `Reprendre la lecture` en haut.
+5) Cliquer `Proposer` :
+   - attendu : modal 2 étapes
+   - puis ouverture Gitea en nouvel onglet
+
+### Si “Proposer” ne déclenche pas le modal (Firefox)
+Console :
+- `document.querySelectorAll('a[data-propose]').length` doit être > 0
+- `typeof document.getElementById("propose-modal")?.showModal` doit retourner `"function"`
+
+______________________________________
+
+# Dernière mise à jour : 2026-01-29
+
+Ce quickstart couvre :
+- dev local (Mac / Linux)
+- build/test (anchors + aliases + pagefind)
+- pointeur vers déploiement production DS220+
+
+---
+
+## 1) Pré-requis
+
+- Node : `>=22 <23`
+- npm : `>=10 <11`
+
+Vérifie en bash :
+node -v
+npm -v
+
+## 2) Installer / lancer en local
+
+Dans le dossier projet :
+npm ci
+npm run dev
+
+Puis ouvrir l’URL affichée (souvent http://localhost:4321
+).
+
+## 3) Variables Gitea (fonction “Proposer”)
+
+La fonction “Proposer” construit des liens vers Gitea à partir de :
+
+PUBLIC_GITEA_BASE
+
+PUBLIC_GITEA_OWNER (⚠️ casse sensible)
+
+PUBLIC_GITEA_REPO
+
+En local : tu peux les mettre dans .env.local (ou .env.development) :
+PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me
+PUBLIC_GITEA_OWNER=Archicratia
+PUBLIC_GITEA_REPO=archicratie-edition
+
+## 4) Build “édition web” (avec Pagefind + aliases)
+
+Important : toujours builder via npm (pour exécuter postbuild) :
+npm run build
+
+Ce qui se passe :
+
+astro build génère dist/
+
+postbuild exécute :
+
+scripts/inject-anchor-aliases.mjs (aliases d’ancres)
+
+pagefind --site dist (index de recherche)
+
+## 5) Tests (incassable)
+npm test
+
+# Ce test enchaîne notamment :
+
+vérif aliases d’ancres
+
+build
+
+audit dist (IDs dupliqués)
+
+présence effective des aliases dans dist
+
+check anchors (et option update)
+
+check inline JS
+
+## 6) Import éditorial (docx → mdx)
+npm run import
+
+Puis publication via build.
+
+## 7) Production sur Synology DS220+
+
+Le déploiement “propre” (Docker multi-stage + Nginx statique + DSM Reverse Proxy + blue/green) est documenté ici :
+
+DEPLOY_PROD_SYNOLOGY_DS220.md
+
+OPS_COCKPIT.md