# Guide d’usage — 4NK_template (projet)

Ce document explique comment utiliser le template pour initier, documenter, contrôler et publier des projets dérivés, en respectant les standards qualité, sécurité et open source.

## 1. Pré‑requis

- Git opérationnel et accès à votre forge (Gitea recommandé)
- CI activée sur le repository
- bash disponible pour les agents (recommandé). À défaut, fallback PowerShell local

## 2. Démarrer un projet dérivé

1) Créer un repository à partir de 4NK_template
2) Copier/adapter la documentation depuis `docs/templates/**` vers votre `docs/**`
3) Tenir `docs/INDEX.md` et `CHANGELOG.md` à jour
4) Activer les workflows CI et vérifier `release-guard`/`security-audit`

## 3. Documentation

- Utiliser les squelettes de `docs/templates/**` comme base
- Documenter uniquement votre domaine applicatif (le template reste générique)
- À chaque changement de code/dépendance/CI, synchroniser la doc correspondante

## 4. Agents (contrôles)

- Recommandé (bash): `scripts/agents/run.sh [target_dir] [output_dir] [agent]`
- Windows fallback: `scripts/agents/run.ps1 -TargetDir . -OutputDir tests/reports/agents -Agent <nom>`
- Conteneur (option): `docker compose -f docker-compose.ci.yml up --abort-on-container-exit`
  - Rapports: `tests/reports/agents/*.md`
  - Variables utiles: `RUNNER_MODE`, `BASE_URL`, `REGISTRATION_TOKEN`
  - Script helper: `scripts/dev/run_project_ci.sh`
  - Auto‑corrections: `AUTO_FIX=1` pour créer la structure de tests et des squelettes docs
 - Agents utiles en premier passage: `documentation`, `quality-technique`, `open-source`, `securite`, `deploiement`

## 5. Qualité et CI

- Jobs attendus: qualité, tests (catégories pertinentes), documentation, security‑audit, bash‑required, release‑guard
- `bash-required` garantit la présence de bash et du runner des agents
- `release-guard` bloque les publications si tests/doc/build/sécurité/version/changelog/tag ne sont pas cohérents

## 6. Sécurité

- Secrets uniquement via la CI (variables d’environnement), jamais en clair dans le dépôt
- Audit sécurité automatisé (job `security-audit`) et remédiations tracées dans `CHANGELOG.md`

## 7. Workflow quotidien

- Éditer: code et documentation (toujours en parallèle)
- Exécuter: tests locaux, agents (diagnostics)
- Vérifier: sorties CI, rapports `tests/reports/`
- Commiter: messages clairs, PR petites et ciblées

## 8. Publication

- Choisir `latest` (tag `vX.Y.Z`) ou `wip` (ex: `vX.Y.Z-wip.N`)
- Aligner: fichier de version, `CHANGELOG.md`, tag git
- Déployer si pipeline défini; sinon documenter la procédure

## 9. Dépannage

- Agents fallback PowerShell si bash indisponible localement
- Consulter `tests/reports/agents/*.md` pour les écarts à corriger
- Vérifier les logs de la CI et le job `release-guard`

## 10. Bonnes pratiques

- Pas d’exemples applicatifs dans le template
- Toujours mettre à jour la documentation et le changelog
- Réduire la dérive: synchroniser régulièrement vos projets avec les squelettes et standards