# Guide agent — Écho du Huit

Extension **Firefox** (Manifest V3) qui pousse une sélection d'événements du
calendrier Nextcloud de L'Atelier du Huit vers le formulaire de l'agenda mairie
de Cugnaux. Voir [`README.md`](README.md) pour la vue d'ensemble.

## Avant de coder

1. Lis [`docs/RECHERCHE.md`](docs/RECHERCHE.md) : faits **vérifiés** (URLs, ids
   de champs, valeurs du thème, structure de l'agenda, cas limites de l'ICS).
   Ne redécouvre pas ce qui y est déjà confirmé.
2. Lis [`docs/DECISIONS.md`](docs/DECISIONS.md) : choix actés et leur pourquoi.
   Ne les relitige pas sans raison nouvelle.
3. Le backlog vit dans **Piaire** (tenant `perso`, projet `echo-du-huit`).
   Le code est la seule source de vérité du comportement réel.

## Contraintes structurantes (ne pas violer sans accord)

- **JS vanilla, pas de build, pas de runtime.** L'extension tourne dans le
  navigateur. Pas de Bun/Node au runtime, pas de bundler. Dépendance externe
  uniquement si vendorée en `.js` (ex. `ical.js` de Mozilla pour le parsing).
  Bun est autorisé **uniquement comme outil de dev** (`bun test`, vendoring) —
  jamais embarqué dans l'extension livrée.
- **Aucun secret stocké.** L'accès Nextcloud passe par la session du navigateur
  (`credentials: 'include'` + `host_permissions`). Ne jamais écrire de mot de
  passe dans le repo ou la config.
- **Pas d'auto-submit du formulaire mairie.** On pré-remplit le DOM ; l'humain
  relit, complète et envoie. Le formulaire est modéré et les descriptions
  méritent souvent un enrichissement.
- **Image = manuelle.** Un content script ne peut pas remplir un `<input
  type=file>`. L'extension aide à glisser l'affiche, ne l'injecte pas.
- **Statut partagé dans Nextcloud.** *ignoré* / *soumis* = tag `CATEGORIES`
  écrit en CalDAV (visible par tous les bénévoles, durable). *publié* = dérivé
  de l'agenda mairie. Pas d'état privé local pour ces statuts.

## Conventions

- Code simple et expressif ; commentaires seulement pour le *pourquoi*.
- Nouveaux paramètres/fonctions : obligatoires par défaut (optionnels seulement
  si la rétrocompat l'exige).
- Messages et UI en français (public = bénévoles associatifs).
- TDD quand c'est pertinent.

## Ne pas committer

`config.local.json` (organisateur/email), artefacts de packaging, `.env`.