# 4NK Project Template — Qualité, Sécurité, Open Source ✨

Bienvenue dans le template 4NK. Objectifs: démarrer vite, rester propre, publier serein. Vous y trouverez des règles, des workflows CI, des scripts d’agents et une documentation prête à adapter.

## 📦 Ce que vous obtenez

- Standards de qualité et sécurité (lint, audit, release‑guard)
- Agents automatisés (qualité, docs, tests, sécurité, déploiement)
- CI Gitea prête à l’emploi (self‑hosted, linux)
- Documentation structurée: `docs/project/**` (ce dépôt) et `docs/templates/**` (modèles pour vos projets)

## 🐧 Linux (Debian) — Prérequis rapides

```bash
sudo apt update
sudo apt install -y bash git curl jq ca-certificates
# Lint Markdown
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
```

## ⚙️ Configuration locale (secrets)

```bash
bash scripts/deploy/setup.sh   # crée ~/.4nk_template/.env (chmod 600)
```

À renseigner ensuite dans `~/.4nk_template/.env` (extraits):

- OPENAI_API_KEY, OPENAI_MODEL (si agents IA)
- RELEASE_TOKEN (release via API Gitea)
- BASE_URL (optionnel, par défaut `https://git.4nkweb.com`)

Plus d’infos: `docs/project/CONFIGURATION.md` et `docs/project/GITEA_SETUP.md`.

## 🤖 Exécuter les agents

```bash
scripts/agents/run.sh              # exécution complète, rapports dans tests/reports/agents
scripts/agents/run.sh . . documentation  # exécution ciblée (facultatif)
```

Fallback Windows: `scripts/agents/run.ps1`.

Guide complet: `docs/project/AGENTS_RUNTIME.md`.

## 🐳 Conteneur unifié (runner + agents)

```bash
# Build
docker compose -f docker-compose.ci.yml build

# Exécuter les agents sur le dépôt courant
docker compose -f docker-compose.ci.yml up --abort-on-container-exit
# Rapports: tests/reports/agents/*.md

# Lancer le runner dans ce conteneur
RUNNER_MODE=runner BASE_URL="https://git.4nkweb.com" REGISTRATION_TOKEN="<token>" \
  docker compose -f docker-compose.ci.yml up -d
```

## 🔁 CI/CD (Gitea Actions)

- Runners: labels requis `self-hosted,linux` (voir `docs/project/GITEA_SETUP.md`)
- Jobs clés: `markdownlint`, `agents-smoke`, `release-guard`, `release-create`
- Secrets/Variables: `RELEASE_TOKEN`, `OPENAI_API_KEY`, `BASE_URL`, `OPENAI_*`

## 🚀 Release

```bash
# Vérifier/mettre à jour la version
cat TEMPLATE_VERSION

# Tagger (déclenche la release via API si RELEASE_TOKEN existe côté dépôt)
git tag -a vYYYY.MM.P -m 'release: vYYYY.MM.P (latest)'
git push origin vYYYY.MM.P
```

Changelog: `CHANGELOG.md`. Gardien de release: `release-guard` en CI.

## 📚 Documentation

- Projet (ce dépôt): `docs/project/`
- Modèles à réutiliser: `docs/templates/`
- Standards de qualité: `docs/project/QUALITY_STANDARDS.md`

## 🤝 Contribution

- Fork → branche → PR (CI verte, docs/changelog à jour)
- Respect des règles éditoriales (français, pas de secrets, pas d’exemples applicatifs)

## 📄 Licence

MIT — voir `LICENSE`.

## 🆘 Support

- Lire `docs/project/INDEX.md`
- Ouvrir une issue si besoin