merge: chore/docs-agents-ci-2025-08-27 → main (v2025.08.3)

.gitea/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
   # Job de vérification du code
   code-quality:
     name: Code Quality
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     steps:
     - name: Checkout code
@@ -64,7 +64,7 @@ jobs:
   # Job de tests unitaires
   unit-tests:
     name: Unit Tests
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     steps:
     - name: Checkout code
@@ -100,7 +100,7 @@ jobs:
   # Job de tests d'intégration
   integration-tests:
     name: Integration Tests
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     services:
       docker:
@@ -147,7 +147,7 @@ jobs:
   # Job de tests de sécurité
   security-tests:
     name: Security Tests
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     steps:
     - name: Checkout code
@@ -184,7 +184,7 @@ jobs:
   # Job de build et test Docker
   docker-build:
     name: Docker Build & Test
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     services:
       docker:
@@ -227,7 +227,7 @@ jobs:
   # Job de tests de documentation
   documentation-tests:
     name: Documentation Tests
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     steps:
     - name: Checkout code
@@ -242,7 +242,7 @@ jobs:
 
   markdownlint:
     name: Markdown Lint
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -272,7 +272,7 @@ jobs:
 
   bash-required:
     name: Bash Requirement
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -289,7 +289,7 @@ jobs:
 
   agents-smoke:
     name: Agents Smoke (no AI)
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -309,7 +309,7 @@ jobs:
 
   openia-agents:
     name: Agents with OpenIA
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     if: ${{ secrets.OPENAI_API_KEY != '' }}
     env:
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -333,7 +333,7 @@ jobs:
 
   deployment-checks:
     name: Deployment Checks
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -350,7 +350,7 @@ jobs:
 
   security-audit:
     name: Security Audit
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
@@ -368,7 +368,7 @@ jobs:
   # Job de release guard (cohérence release)
   release-guard:
     name: Release Guard
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     needs: [code-quality, unit-tests, documentation-tests, markdownlint, security-audit, deployment-checks, bash-required]
     steps:
     - name: Checkout code
@@ -430,7 +430,7 @@ jobs:
   # Job de tests de performance
   performance-tests:
     name: Performance Tests
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
 
     steps:
     - name: Checkout code
@@ -455,7 +455,7 @@ jobs:
   # Job de notification
   notify:
     name: Notify
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, linux]
     needs: [code-quality, unit-tests, integration-tests, security-tests, docker-build, documentation-tests]
     if: always()
 

.gitea/workflows/template-sync.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   check-and-sync:
-    runs-on: linux
+    runs-on: [self-hosted, linux]
     steps:
       - name: Lire TEMPLATE_VERSION et .4nk-sync.yml
         # Doit charger ref courant, source_repo et périmètre paths

CHANGELOG.md

@@ -26,14 +26,22 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Déploiement: copie étendue (.cursor, AGENTS.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, TEMPLATE_VERSION, .markdownlint.json, .cursorignore, .gitignore, security/, scripts/)
 
 ### Changed
+
+## [2025.08.3] - 2025-08-27
+
+### Changed
+
+- README refondu (ludique) avec Quickstart Debian, exécution agents sans arguments, secrets et CI
+- Workflows Gitea configurés pour runners `self-hosted, linux` (docs mises à jour)
+
 ## [2025.08.2] - 2025-08-27
 
 ### Changed
+
 - Renommage variable CI/Docs `GITEA_BASE_URL` → `BASE_URL`
 - Exécution des agents simplifiée: `scripts/agents/run.sh` sans arguments par défaut
 - CI mise à jour pour utiliser l’exécution sans paramètres
 
-
 ## [2025.08.1] - 2025-08-27
 
 ### Added

README.md

@@ -1,128 +1,84 @@
-# 4NK Project Template — Qualité, Sécurité et Open Source
+# 4NK Project Template — Qualité, Sécurité, Open Source ✨
 
-Ce dépôt est le template de référence 4NK. Il formalise la démarche de qualité, de sécurité et d’open source applicable à tous les projets 4NK et fournit des supports initiaux (modèles CI/CD, règles Cursor, scripts, guides). Chaque projet doit l’adapter à ses spécificités, et proposer des améliorations en retour (feedback) vers ce template.
+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.
 
-## 📋 Table des Matières
+## 📦 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)
 
-## 🏗️ Architecture
+## 🐧 Linux (Debian) — Prérequis rapides
 
-### 🔄 Flux de Données
+```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)
 
-## 🚀 Démarrage Rapide
+```bash
+bash scripts/deploy/setup.sh   # crée ~/.4nk_template/.env (chmod 600)
+```
 
-### Prérequis
+À 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`)
 
-### Installation
+Plus d’infos: `docs/project/CONFIGURATION.md` et `docs/project/GITEA_SETUP.md`.
 
+## 🤖 Exécuter les agents
 
-### Configuration SSH (Recommandé)
+```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`.
+
+## 🔁 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
 
-### 📖 Guides Principaux
+- Projet (ce dépôt): `docs/project/`
-
+- Modèles à réutiliser: `docs/templates/`
-- docs/TEMPLATE_ADAPTATION.md — Comment adapter ce template à votre projet
+- Standards de qualité: `docs/project/QUALITY_STANDARDS.md`
-- docs/TEMPLATE_FEEDBACK.md — Comment proposer des améliorations au template
-
-
-### 🔧 Guides Techniques
-
-
-### 🧪 Guides de Test
-
-### 🌐 Guides Réseau
-
-
-## 🔧 Configuration
-
-### Services Disponibles
-
-
-### Variables d'Environnement
-
-
-## 🧪 Tests et Monitoring
-
-### Tests de Base
-
-### Monitoring
-
-
-### Tests de Performance
-
-
-## 🌐 Réseau de Relais
-
-### Architecture Mesh
-
-
-### Ajout de Nœuds Externes
-
-
-### Configuration Externe
-
-
-## 🛠️ Développement
-
-### Structure du Projet
-
-
-### Ajout d'un Nouveau Service
-
-
-### Modification de la Configuration
-
-
-## 🚨 Dépannage
-
-### Problèmes Courants
-
-#### 1. Ports Déjà Utilisés
-
-
-#### 2. Problèmes de Synchronisation
-
-
-#### 3. Problèmes de Connectivité
-
-### Logs Détaillés
-
-
-### Healthchecks
-
-
-## 📈 Performance
-
-### Ressources Recommandées
-
-### Optimisations
-
 
 ## 🤝 Contribution
 
-1. Fork le repository
+- Fork → branche → PR (CI verte, docs/changelog à jour)
-2. Créer une branche feature (`git checkout -b feature/nouvelle-fonctionnalite`)
+- Respect des règles éditoriales (français, pas de secrets, pas d’exemples applicatifs)
-3. Commit les changements (`git commit -am 'Ajout de nouvelle fonctionnalité'`)
-4. Push la branche (`git push origin feature/nouvelle-fonctionnalite`)
-5. Créer une Pull Request
-
-Pour les améliorations du template lui‑même (règles, CI, scripts), se référer à `docs/TEMPLATE_FEEDBACK.md` et utiliser le type d’issue « Template Feedback ».
 
 ## 📄 Licence
 
-Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
+MIT — voir `LICENSE`.
 
 ## 🆘 Support
 
-Pour obtenir de l'aide :
+- Lire `docs/project/INDEX.md`
-
+- Ouvrir une issue si besoin
-1. Consulter la [documentation](docs/)
-2. Vérifier les [issues existantes](https://git.4nkweb.com/4nk/4NK_node/issues)
-3. Créer une nouvelle issue avec les détails du problème
-4. Inclure les logs et la configuration utilisée
-
----

TEMPLATE_VERSION

@@ -1,2 +1,2 @@
-v2025.08.2
+v2025.08.3
 

docs/project/GITEA_SETUP.md

@@ -22,6 +22,13 @@
 - Nom: `RELEASE_TOKEN` ; Valeur: un token personnel avec portée API sur le dépôt
 - Le job `release-create` utilisera ce secret lors d’un push de tag `v*`
 
+### Runner Gitea (labels)
+
+- Configurez votre runner avec labels: `self-hosted,linux`
+- Exemple (act_runner):
+  - Enregistrement: `./act_runner register --labels "self-hosted,linux"`
+  - Service: définissez `RUNNER_LABELS="self-hosted,linux"`
+
 ## 4. Workflows requis
 
 - `code-quality`, `unit-tests`, `documentation-tests`, `security-audit`