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

2.1 Intégrer 4NK_template dans un projet existant

# Depuis le dépôt 4NK_template
bash scripts/deploy/setup.sh <git_url_du_projet> [--dest DIR] [--force]
# Compléter ensuite ~/.4nk_template/.env si nécessaire (OPENAI_*, BASE_URL, RELEASE_TOKEN)

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

5. Remplacer la CI par une exécution locale (recommandé)

• CI neutre par défaut: CI_SKIP=true dans le workflow; réactivez en le passant à false côté dépôt.
• Commits: contrôles rapides avant commit

npx -y markdownlint-cli "**/*.md" --ignore "archive/**"
AUTO_FIX=1 SCOPE=changed scripts/agents/run.sh
# Ajoutez [skip ci] dans le message de commit pour éviter les runs distants

• Push: contrôles complets pré‑push

AUTO_FIX=1 SCOPE=all scripts/agents/run.sh
bash scripts/security/audit.sh || true
# Si outillage présent (exemples): cargo check / go vet / npx eslint / tsc --noEmit / ruff…
bash scripts/release/guard.sh || true

• Release locale (puis push tag)

echo "vYYYY.MM.P" > TEMPLATE_VERSION
git add TEMPLATE_VERSION CHANGELOG.md
git commit -m "[skip ci] chore(release): vYYYY.MM.P"
git tag -a vYYYY.MM.P -m "release: vYYYY.MM.P (latest)"
git push && git push origin vYYYY.MM.P

Hooks conseillés

.git/hooks/pre-commit:

#!/usr/bin/env bash
set -e
npx -y markdownlint-cli "**/*.md" --ignore "archive/**"
AUTO_FIX=1 SCOPE=changed scripts/agents/run.sh

.git/hooks/pre-push:

#!/usr/bin/env bash
set -e
AUTO_FIX=1 SCOPE=all scripts/agents/run.sh
bash scripts/security/audit.sh || true
bash scripts/release/guard.sh || true

• 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