# 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