docs(project): add usage guide and index links

docs/project/INDEX.md

@@ -1,9 +1,14 @@
 # Index — Documentation du dépôt 4NK_template
 
-- AGENTS_RUNTIME.md — Exécution des agents
-- GITEA_SETUP.md — Configuration Gitea
-- SSH_UPDATE.md — Mises à jour des scripts SSH
-- DEPLOYMENT.md — Stratégie de déploiement
-- SECURITY_AUDIT.md — Audit sécurité (socle template)
+- README.md — Présentation du template
+- USAGE.md — Guide d’usage du template
+- ARCHITECTURE.md — Architecture et arborescence de référence
+- CONFIGURATION.md — Paramètres et conventions
+- QUALITY_STANDARDS.md — Standards de qualité
+- OPEN_SOURCE_GUIDE.md — Bonnes pratiques open source
+- AGENTS_RUNTIME.md — Exécution et intégration des agents
+- GITEA_SETUP.md — Configuration et CI Gitea
+- SECURITY_AUDIT.md — Posture et contrôles de sécurité
+- DEPLOYMENT.md — Publication et déploiement (template)
 - RELEASE_PLAN.md — Plan de release du template
 - ROADMAP.md — Roadmap du template

docs/project/README.md

@@ -1,10 +1,30 @@
 # README — 4NK_template
 
-Ce dépôt fournit un template (docs, CI, scripts, sécurité) pour démarrer des projets 4NK cohérents.
+## Présentation
+Template documentaire, CI et scripts de qualité/sécurité pour initier des projets 4NK cohérents et industrialisés.
 
-- Documentation du dépôt: `docs/project/INDEX.md`
-- Squelettes pour projets: `docs/templates/INDEX.md`
-- Standards qualité: `docs/QUALITY_STANDARDS.md`
-- Guide open source: `docs/OPEN_SOURCE_GUIDE.md`
+## Objectifs
+- Offrir des modèles de documentation prêts à l’emploi
+- Standardiser qualité, tests, sécurité et release
+- Faciliter l’exécution d’agents de conformité
 
-Agents (contrôles): `scripts/agents/run.sh . tests/reports/agents all`
+## Périmètre
+- Documentation générique (non applicative)
+- CI Gitea (tests, security-audit, release-guard, bash-required)
+- Scripts d’agents (bash recommandé, fallback PowerShell)
+
+## Structure
+- `docs/project/**` — Documentation du template
+- `docs/templates/**` — Modèles à copier dans les projets
+- `scripts/agents/**` — Agents et outillage
+- `tests/**` — Structure, journaux et rapports
+
+## Utilisation
+- Lire `docs/project/INDEX.md`
+- Consulter `docs/project/USAGE.md` pour l’usage détaillé
+- Exécuter les agents pour un diagnostic: rapport dans `tests/reports/agents`
+
+## Gouvernance
+- Standards: `docs/QUALITY_STANDARDS.md`
+- Open source: `docs/OPEN_SOURCE_GUIDE.md`
+- Publication: `docs/project/RELEASE_PLAN.md`

docs/project/USAGE.md

@@ -0,0 +1,55 @@
+# 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>`
+- Rapports: `tests/reports/agents/*.md`
+- 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