# 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

```bash
# 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)
```

### Intégration via Docker (recommandé)

```bash
# Build l’image unifiée
docker compose -f docker-compose.ci.yml build

# Appliquer le template depuis le conteneur (monter le repo projet sur /host)
docker run --rm -v "$PWD":/work -v "/chemin/vers/projet":/host 4nk-template-ci:latest \
  bash -lc "/work/scripts/deploy/setup.sh file:///host/.git --dest /host"
```

## 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
```bash
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
```bash
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)
```bash
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 (agents centralisés via 4NK_template)

`.git/hooks/pre-commit`:
```bash
#!/usr/bin/env bash
set -euo pipefail
PROJECT_DIR="$(git rev-parse --show-toplevel)"
TEMPLATE_DIR="$(cd "${PROJECT_DIR}/../4NK_template" && pwd)"
mkdir -p "${PROJECT_DIR}/tests/reports/agents"
"${TEMPLATE_DIR}/scripts/local/run_agents_for_project.sh" "${PROJECT_DIR}" "tests/reports/agents"
```

`.git/hooks/pre-push`:
```bash
#!/usr/bin/env bash
set -euo pipefail
PROJECT_DIR="$(git rev-parse --show-toplevel)"
TEMPLATE_DIR="$(cd "${PROJECT_DIR}/../4NK_template" && pwd)"
mkdir -p "${PROJECT_DIR}/tests/reports/agents"
"${TEMPLATE_DIR}/scripts/local/run_agents_for_project.sh" "${PROJECT_DIR}" "tests/reports/agents"
if [ -f "${PROJECT_DIR}/scripts/security/audit.sh" ]; then (cd "${PROJECT_DIR}" && bash scripts/security/audit.sh) || true; fi
if [ -f "${PROJECT_DIR}/scripts/release/guard.sh" ]; then (cd "${PROJECT_DIR}" && bash scripts/release/guard.sh) || true; fi
```

Ou installez-les automatiquement (les hooks fournis appellent déjà le runner centralisé):

```bash
bash scripts/local/install_hooks.sh
```

- Agents utiles en premier passage: `documentation`, `quality-technique`, `open-source`, `securite`, `deploiement`

### Script de merge local (main/develop)

```bash
# Merge de la branche courante vers main (valide localement avant)
bash scripts/local/merge_branch.sh main

# Merge vers develop
bash scripts/local/merge_branch.sh develop
```

## 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