4NK_template/docs/project/USAGE.md

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