# AGENTS.md — Instructions obligatoires du dépôt ObsiGate

> Ces instructions s'appliquent à **toute** intervention (humaine ou IA) sur ce dépôt.
> Documentation et réponses en **français**.

## Règle n°1 — Méthode de livraison unique

Avant toute tâche (fonctionnalité, bug, refactor), **lire et appliquer**
[`docs/DELIVERY_WORKFLOW.md`](./docs/DELIVERY_WORKFLOW.md) (Definition of Done).
Aucune tâche n'est terminée avant que sa checklist soit complète **et le CI vert**
(jobs `lint`, `test`, `security`, `build`, `e2e` de `.gitea/workflows/ci.yml`).

## Avant de commencer

1. Lire [`docs/ROADMAP.md`](./docs/ROADMAP.md) (travail à venir + index) et
   [`docs/ISSUES_TODOLIST.md`](./docs/ISSUES_TODOLIST.md) (bugs).
2. Identifier ou créer l'**ID stable** (`#NN` pour une feature, `BUG-NNN` pour un bug —
   jamais réutilisé) et passer son statut à « en cours » **avant** de coder.

## Architecture (ce qui n'est pas obvious)

- **Backend** : FastAPI/Python 3.11, point d'entrée `backend/main.py` (endpoints + rendu
  markdown), index en mémoire (`indexer.py`, `search.py`), watcher (`watcher.py`),
  auth dans `backend/auth/`. Pas de base de données : JSON dans `data/`.
- **Frontend** : vanilla JS **zéro framework, zéro build npm** (`frontend/app.js`,
  `index.html`, `style.css`). Ne pas ajouter de dépendances npm ni d'étape de build.
- **Desktop** : Tauri (Rust) dans `desktop/` ; `tauri.conf.json` embarque `backend/**` et
  `frontend/**` depuis `desktop/` — les scripts de build font le **staging** (copie) avant
  `cargo tauri build`, sinon le build échoue.
- **i18n** : tout texte d'interface doit exister en FR **et** EN
  (`frontend/locales/fr.json` + `en.json`).

## Vérifications locales (pwsh, à faire passer avant tout commit/push)

```powershell
# Backend (venv à la racine)
.\.venv\Scripts\python.exe -m pytest tests/
.\.venv\Scripts\python.exe -m ruff check backend/
.\.venv\Scripts\python.exe -m mypy backend/ --ignore-missing-imports

# Frontend : scripts Node à exécuter directement (pas de runner)
node tests/frontend/validate-imports.mjs
node tests/frontend/unit.test.mjs
# Tests JSDOM : node_modules dans tests/frontend/ (npm install là-bas si absent), ex :
node tests/frontend/pane-manager.test.mjs

# E2E (si UI touchée, ~10 min) : reproduit le job CI e2e (port 2029, auth désactivée)
npm run test:e2e                    # prérequis : uv, Node >= 20, npx playwright install chromium
bash scripts/run-e2e-local.sh -g "nom du test"   # filtre / --headed

# Windows sans bash exploitable (WSL HS, git-bash bloqué par App Control) :
npm run test:e2e:ps                 # équivalent PowerShell, mêmes conditions que le CI
pwsh -File scripts/run-e2e-local.ps1 -PlaywrightArgs @('-g','nom du test')
```

- Un seul test backend : `.\.venv\Scripts\python.exe -m pytest tests/test_search.py -q`.
- **Sélection E2E** : vérifier chaque sélecteur dans le DOM réel avant de l'utiliser dans un
  test ; tout test nouveau/modifié doit passer en local avant push ; pas de contournement
  qui masque la flakiness (`waitForTimeout` arbitraires, fallbacks silencieux).
- La suite E2E doit finir à **100 %** sans s'appuyer sur les retries. Jamais de `git push`
  avant que les 5 étapes locales soient vertes.

## Version & hooks (pièges)

- `VERSION` (racine) = **source unique de vérité** (SemVer), incrémenté **automatiquement à
  chaque commit** par le hook `.githooks/prepare-commit-msg` — `feat` → mineur,
  `!:` / `BREAKING CHANGE` → majeur, sinon correctif. Le même commit resynchronise
  `package.json`, le desktop Tauri, `README.md`/`README.fr.md`, `docs/ROADMAP.md` et publie
  la section `[Unreleased]` du `CHANGELOG.md` en `[X.Y.Z] — date` ; tag `vX.Y.Z` créé au
  commit, publié au push (`push.followTags`).
- Hooks **obligatoires**, à installer une fois par clone : `scripts/install-hooks.sh`
  (sinon la version ne suit plus et le CI échoue via le garde-fou `tests/test_version.py`).
- Le rattachement des fichiers de bump se fait par un `--amend` immédiat : **le SHA affiché
  par `git commit` change** — ne pas s'y fier.
- Commit sans incrément (exceptionnel) : `SKIP_VERSION_BUMP=1 git commit …`.
- Ne jamais réécrire une version déjà publiée dans le CHANGELOG ; jamais de détail dupliqué
  entre Roadmap et CHANGELOG.

## À la fin de chaque tâche (obligatoire)

- Tests unitaires ajoutés/mis à jour (correctif sans test de non-régression = pas terminé).
- Toutes les vérifications locales ci-dessus vertes (`E2E` si UI).
- Documentation mise à jour : `CHANGELOG.md` (`[Unreleased]`), `docs/ROADMAP.md` (statut +
  index), fiche `docs/features/` **ou** `docs/archive/`, `docs/ISSUES_TODOLIST.md` (si bug),
  guide utilisateur i18n FR/EN + README si impact utilisateur, docstrings +
  `response_model` si API.
- **Commit** conventionnel référençant l'ID (`feat: … #12`), puis **push** et **CI vert**.

## Cartographie documentaire

| Sujet | Fichier |
|---|---|
| Méthode de livraison / DoD | `docs/DELIVERY_WORKFLOW.md` |
| Version livrée (source unique) | `VERSION` + `scripts/bump_version.py` |
| Travail à venir + index | `docs/ROADMAP.md` |
| Historique des versions | `CHANGELOG.md` |
| Conception par feature | `docs/features/<slug>.md` |
| Guides d'utilisation | `docs/GUIDES/` |
| Archive du complété | `docs/archive/COMPLETED_v1-v2.md` |
| Bugs / TODO | `docs/ISSUES_TODOLIST.md` |
| Build & releases | `docs/DEVELOPMENT_AND_RELEASES.md` |
| Standards de code | `docs/CONTRIBUTING.md` |

## Conventions

- Commits : `type: description` — `feat`, `fix`, `perf`, `refactor`, `docs`, `style`, `chore`, `test`.
- Sécurité : tout chemin fichier fourni par l'utilisateur passe par `_resolve_safe_path()`.
- **Ne jamais** committer de secrets, clés ou tokens (`.env` jamais committé ; secrets dans
  `data/api_keys.json` ou variables `OBSIGATE_*`).
- Respecter le style du code existant (ruff/mypy 0 erreur ; CSS variables, pas de couleurs
  hardcodées ; `safeCreateIcons()` plutôt que `lucide.createIcons()` direct).