diff --git a/.forgejo/workflows/buildAndTest.yml b/.forgejo/workflows/buildAndTest.yml
index ea58d2fef..b9e6f17b2 100644
--- a/.forgejo/workflows/buildAndTest.yml
+++ b/.forgejo/workflows/buildAndTest.yml
@@ -31,6 +31,7 @@ jobs:
steps:
- name: Clone yavsc
run: |
+ set -e
cd /src
git clone https://forgejo.pschneider.fr/notazof/yavsc.git _src
cd _src
@@ -40,12 +41,23 @@ jobs:
fi
git submodule update --init --recursive
echo "✅ Checked out at $(git rev-parse HEAD) on $(git branch --show-current 2>/dev/null || echo detached HEAD)"
-
+ - name: Secret scan
+ run: |
+ echo "🔍 Scanning for secrets..."
+ cd /src/_src && dotnet tool restore && dotnet picket git --verbose --redact --exit-code 1 --log-opts -n10 \
+ - name: Build
+ run: |
+ echo "🏗️ Building the solution..."
+ cd /src/_src && dotnet build --verbosity normal
+ - name: Install SkiaSharp native dependencies
+ run: |
+ echo "📦 Installing libfontconfig/libfreetype for SkiaSharp (Avalonia.Headless)..."
+ apt-get update && apt-get install -y --no-install-recommends \
+ libfontconfig1 libfreetype6 libexpat1 zlib1g libbz2-1.0 libpng16-16 libbrotli1 \
+ && rm -rf /var/lib/apt/lists/*
- name: Test
run: |
echo "🚀 Lancement des tests..."
cd /src/_src && dotnet test \
--verbosity normal \
- --filter="Category!=Platform-Android" \
- --logger "xunit;LogFileName=test-results.xml" \
- && echo "✅ Success !" || echo "❌ Fail ($?)!"
+ --filter="Category!=Platform-Android"
diff --git a/.forgejo/workflows/release.yml b/.forgejo/workflows/release.yml
index a72f92bd6..911fc831d 100644
--- a/.forgejo/workflows/release.yml
+++ b/.forgejo/workflows/release.yml
@@ -175,6 +175,12 @@ jobs:
run: |
cd /src/_src
dotnet restore
+ - name: Test
+ run: |
+ cd /src/_src && dotnet test \
+ --verbosity normal \
+ --filter="Category!=Platform-Android" \
+ --logger "xunit;LogFileName=test-results.xml"
- name: Build de PostIt.Android ARM64
run: |
@@ -200,6 +206,7 @@ jobs:
RELEASE_BODY: ${{ env.RELEASE_BODY }}
IS_PRERELEASE: ${{ env.IS_PRERELEASE }}
run: |
+ set -e
if [[ -z "$TAG" ]]; then
echo "::error::No tag resolved for the API call."
exit 1
diff --git a/.gitignore b/.gitignore
index b7813f604..056cf69d2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,6 +35,7 @@ appsettings-*.*.json
generated/
*.tmp
+tmp/
DataDir/
*.tests.trx
diff --git a/.gitleaksignore b/.gitleaksignore
new file mode 100644
index 000000000..056cf69d2
--- /dev/null
+++ b/.gitleaksignore
@@ -0,0 +1,45 @@
+# Exclure uniquement les dossiers de sortie de compilation
+bin/
+obj/
+src/*/bin/
+src/*/obj/
+test/*/bin/
+test/*/obj/
+
+# Toolchain front (Node / esbuild)
+node_modules/
+build/
+package-lock.json
+
+# Exclure les caches lourds
+.git/
+.vs/
+
+.env
+
+.*.env
+
+*.csproj.lscache
+data/
+appsettings.*.json
+appsettings-*.*.json
+
+# Exception: the Testing-environment override for Yavsc.Org is a tracked
+# configuration source, not a secrets file. TestWebApplicationFactory
+# (Yavsc.Org.Tests) flips ASPNETCORE_ENVIRONMENT to "Testing" so
+# AddConfiguration("org") in Program.Main loads this file as the
+# last in the chain (it is optional). It overrides the connection
+# string and SMTP section for the in-memory test host and contains
+# no production secrets.
+!src/Yavsc.Org/appsettings-org.Testing.json
+
+generated/
+*.tmp
+tmp/
+DataDir/
+
+*.tests.trx
+*.tests.html
+
+*.log
+
diff --git a/.vscode/launch.json b/.vscode/launch.json
index dc8d3c68d..d5088f01d 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -4,6 +4,22 @@
// Pour plus d'informations, visitez : https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
+ {
+ "name": "PostIt Desktop",
+ "type": "dotnet",
+ "request": "launch",
+ "projectPath": "${workspaceFolder}/src/PostIt/PostIt.Desktop/PostIt.Desktop.csproj"
+ },
+ {
+ "name": "PostIt Desktop local",
+ "type": "coreclr",
+ "request": "launch",
+ "program": "${workspaceFolder}/src/PostIt/PostIt.Desktop/bin/Debug/net10.0/PostIt.Desktop.dll",
+ "env": {
+ "POSTIT_SETTINGS_JSON": "/home/paul/Workspace/yavsc/src/PostIt/PostIt/postit-settings.json"
+ },
+ "preLaunchTask": "dotnet: build-postit-desktop"
+ },
{
"name": "Android Debug",
"type": "mono",
@@ -20,10 +36,10 @@
"port": 55555
},
{
- "name": "API",
+ "name": "Yavsc API",
"type": "dotnet",
"request": "launch",
- "projectPath": "${workspaceFolder}/src/Api/Api.csproj"
+ "projectPath": "${workspaceFolder}/src/Yavsc.Api/Yavsc.Api.csproj"
},
{
"name": "Yavsc Org",
@@ -37,12 +53,7 @@
"request": "launch",
"projectPath": "${workspaceFolder}/src/Yavsc.Blogs/Yavsc.Blogs.csproj"
},
- {
- "name": "PostIt Desktop",
- "type": "dotnet",
- "request": "launch",
- "projectPath": "${workspaceFolder}/src/PostIt/PostIt.Desktop/PostIt.Desktop.csproj",
- },
+
{
"name": "Test PostIt.Android launch (Xamarin.UITest)",
"type": "coreclr",
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index fd46437ac..71384cd8c 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -7,7 +7,7 @@
"fileLocation": ["relative", "${workspaceFolder}"],
"source": "dotnet",
"pattern": {
- "regexp": "^\\s+(.*)\\((\\d+),(\\d+)\\):\\s+(error|warning) (.+): (.*)$",
+ "regexp": "^\\s*(.*)\\((\\d+),(\\d+)\\):\\s+(error|warning) (.*)$",
"file": 1,
"line": 2,
"column": 3,
@@ -47,7 +47,10 @@
"group": "build",
"isBuildCommand": true,
"isTestCommand": false,
- "isBackground": true
+ "isBackground": true,
+ "options": {
+ "cwd": "${workspaceFolder}"
+ }
},
{
"label": "test blogs backend",
@@ -63,6 +66,28 @@
"isDefault": false
}
},
+ {
+ "label": "test api backend (npgsql)",
+ "type": "process",
+ "problemMatcher": "$msCompile",
+ "command": "dotnet",
+ "args": [
+ "test",
+ "Yavsc.Api.Test.csproj",
+ "-v",
+ "minimal"
+ ],
+ "options": {
+ "cwd": "src/Yavsc.Api.Test",
+ "env": {
+ "YAVSC_API_TEST_DB_PROVIDER": "npgsql"
+ }
+ },
+ "group": {
+ "kind": "test",
+ "isDefault": false
+ }
+ },
{
"label": "build-webapi",
"type": "process",
@@ -76,6 +101,21 @@
"kind": "build"
},
"isBackground": true
+ },
+ {
+ "label": "dotnet: build-postit-desktop",
+ "type": "process",
+ "isBuildCommand": true,
+ "isTestCommand": false,
+ "isBackground": true,
+ "command": "dotnet",
+ "args": ["build", "/property:GenerateFullPaths=true"],
+ "options": {
+ "cwd": "src/PostIt/PostIt.Desktop"
+ },
+ "group": {
+ "kind": "build"
+ }
}
]
}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7c3209c6..111c1491a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,97 @@
# Changelog
+## [1.0.8-rc14] - unstable
+
+### Added
+
+* [PostIt] Ajout d'un `BillingQueryDetailsPageViewModel` et de sa page associee pour afficher le detail d'une commande billing depuis l'historique.
+* [PostIt] Ajout d'un mode detail avec section metier (statut, date, description, motif, infos) et section technique repliable (code, client, provision, lieu, prestations).
+* [PostIt] Ajout d'un badge de statut enrichi (couleur + pictogramme) sur le detail d'une commande pour visualiser l'etat en un coup d'oeil.
+* [PostIt] Ajout d'un bloc d'actions rapide en tete du detail (`Retour`, `Ouvrir en edition`) pour eviter le scroll jusqu'au bas de page.
+* [PostIt] Ajout d'un style monospace sur les metadonnees techniques (code billing, client, provision, lieu, prestations) pour faciliter la lecture des identifiants et valeurs brutes.
+
+### Changed
+
+* [PostIt] Le bouton d'ouverture depuis la liste billing ouvre maintenant une page de detail dediee avant l'eventuelle edition.
+* [PostIt] Amelioration UX des pages billing: badges de statut colores, actions remontees en haut de page, et typographie monospace sur les metadonnees techniques.
+
+### Fixed
+
+* [Yavsc.Api] Correction d'un 500 sur le refresh du catalogue d'activites lorsque `Activity.Description` est `NULL` en base (nullabilite explicite + projection null-safe + gardes sur codes vides).
+* [Yavsc.Api] Correction des erreurs 400/500 sur les routes billing (`Rdv`, `Brush`, `MBrush`) en imposant `ClientId` depuis l'utilisateur authentifie et en ignorant les champs server-owned lors de la validation modele.
+* [Yavsc.Api] Correction du `PUT /api/v1/billing/Rdv/{id}`: mise a jour controlee de l'entite existante (et non remplacement brut du graphe JSON), ce qui supprime les `BadRequest` parasites.
+* [Yavsc.Api] Correction PostgreSQL `timestamptz` sur RDV: normalisation UTC de `EventDate` sur `POST/PUT /api/v1/billing/Rdv` pour eviter l'erreur `Cannot write DateTime with Kind=Local`.
+* [Yavsc.Api] Correction du flux FrontOffice accept/reject de query: sauvegarde avec contexte utilisateur et fallback d'injection pour `IBillingService` afin d'eviter les erreurs serveur en environnement de test.
+* [Yavsc.Blogs] Correction des `BadRequest` sur `POST/PUT /api/v1/blogspot` avec payload JSON (PostIt): les proprietes de navigation/serveur (`Author`, `Tags`, `Comments`, audit) ne bloquent plus la validation.
+* [Yavsc.Org] Correction du flux MVC de creation de commentaire: `SaveChangesAsync(userId)` est utilise pour renseigner les champs d'audit requis (`UserCreated`/`UserModified`).
+* [Yavsc.Api.Test] Stabilisation des fixtures de seed billing: remplissage des metadonnees d'audit (`UserCreated`, `UserModified`, dates) pour eviter les echecs SQLite `NOT NULL`.
+
+## [1.0.8-rc13] - unstable
+
+### Added
+
+* [PostIt] Integration d'un selecteur de lieu RDV base sur Mapsui (carte interactive dans le formulaire `Rdv`).
+* [PostIt] Ajout d'un marqueur de position et d'une action de recentrage sur la carte RDV.
+* [PostIt] Ajout d'un service de reverse geocoding pour suggerer une adresse a partir des coordonnees carte.
+* [PostIt] Cache et debounce des resolutions d'adresse RDV pour limiter les appels reseau et lisser l'UX.
+* [PostIt.Tests] Nouvelles non-regressions sur le panneau d'adresse suggeree RDV et le comportement de la carte.
+* [Yavsc.Abstract] Activation de `#nullable enable annotations` sur les fichiers legacy avec annotations nullable.
+* [Yavsc.Server] Activation de `#nullable enable annotations` sur les fichiers legacy avec annotations nullable.
+
+### Changed
+
+* [PostIt] Generalisation de la barre de statut d'action (severite explicite) sur pages principales, dialogues et formulaires billing.
+* [PostIt] Harmonisation des messages de statut utilisateur en francais.
+* [PostIt] Renforcement des gardes de navigation dans les flux de gestion des membres de cercle.
+* [PostIt] Le flux RDV conserve l'adresse saisie manuellement et propose l'adresse resolue comme suggestion explicite.
+* [PostIt] Le flux de geolocalisation RDV tolere les positions proches dans le cache de suggestion d'adresse.
+
+### Fixed
+
+* [PostIt.Desktop] Correction d'un crash au demarrage OIDC (`No authority specified`) via durcissement des valeurs par defaut de configuration d'authentification.
+* [PostIt] Correction de la persistance des settings: l'etat runtime de statut n'est plus serialize dans le JSON utilisateur.
+* [PostIt.Tests] Ajout d'un verrou de non-regression sur le premier chargement des settings.
+* [PostIt] Correction du binding de la date RDV: `DatePicker.SelectedDate` est aligne sur un proxy `DateTimeOffset?` (`EventDateSelection`).
+
+## [1.0.8-rc12] - unstable
+
+### Added
+
+* [PostIt] Nouveau helper d'image `ImageHelper` pour charger des bitmaps depuis les ressources et depuis le web.
+* [PostIt] Affichage de l'avatar XS dans la liste des performers d'activites, avec fallback visuel (initiale utilisateur).
+* [PostIt.Tests] Nouveaux tests autour des URLs avatar et de la source d'autorite.
+* [contrib] Ajout d'un `README.md` utilitaire pour les symboles/icones.
+
+### Changed
+
+* [PostIt] Les avatars ne sont plus relies en string sur `Image.Source`: ils sont telecharges et lies en `Bitmap`.
+* [Yavsc.Api.Client] `ActivityApiClient` accepte une base d'avatar dediee et construit les URLs avatar depuis l'autorite d'identification.
+* [PostIt] Les clients Activites/Billing utilisent maintenant `ApiUrl` en lecture dynamique: un changement via Parametres prend effet sans redemarrer l'application (apres sauvegarde et rafraichissement de la page).
+* [PostIt] Le header de `MainPage` n'utilise plus `ScrollViewer`; remplacement par une barre de commandes basee sur `WrapPanel`.
+* [PostIt] Alignement de la navigation blogs: renommage `PushMainPageAsync` -> `PushBlogsPageAsync` et ajustement de `HomePageViewModel`.
+
+### Fixed
+
+* [PostIt.Android] Correction d'un 404 sur la page Activites au premier lancement: la configuration embarquee pointait `ApiUrl` vers le host Blogs au lieu de l'API metier.
+* [PostIt] Correction du bouton Sauver de la page Parametres: binding vers `SaveCommand` pour persister correctement `ApiUrl`/`BlogsApiUrl`.
+
+## [1.0.8-rc11] - unstable
+
+### Added
+
+nothing
+
+### Changed
+
+* [Yavsc.Api.Test] Mise a jour de `Microsoft.EntityFrameworkCore.Sqlite` vers `10.0.11` afin de supprimer l'alerte NU1903 liee a `SQLitePCLRaw.lib.e_sqlite3` 2.1.11.
+* [Yavsc.Org] Nettoyage de la configuration NuGet pour le restore: suppression du fichier local `Directory.Packages.props` au profit du fichier racine centralise.
+* [Yavsc.Org] Suppression de references de packages redondantes dans le projet, sans impact fonctionnel attendu.
+
+### Fixed
+
+* [Yavsc.Api.Test] Le restore n'emet plus le warning de vulnerabilite `NU1903` sur `SQLitePCLRaw.lib.e_sqlite3`.
+* [Yavsc.Org] Suppression d'une vulnerabilite de severite elevee sur AutoMapper apres publication et consommation de la nouvelle version candidate de `HigginsSoft.IdentityServer8`.
+
## [1.0.8-rc10] - unstable
### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fd408c5c1..8aa0567d3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -49,6 +49,19 @@ Les tests sont répartis en :
item « Tests d'intégration smoke par BC ».
- `src/PostIt.Tests/` — tests unitaires du client desktop PostIt.
+## Onboarding assiste par agents IA
+
+Pour accelerer la prise en main du depot avec Copilot/Plan/Explore :
+
+- Parcours pas-a-pas : [doc/onboarding-agents.md](./doc/onboarding-agents.md)
+- Playbook d'usage des agents : [doc/agent-playbook.md](./doc/agent-playbook.md)
+- Matrice intentions -> agent -> preuves : [doc/agent-intent-matrix.md](./doc/agent-intent-matrix.md)
+
+Regle minimale en contribution assistee par agent :
+- expliciter l'impact architecture,
+- justifier le niveau de tests execute,
+- documenter les risques residuels.
+
## Le CHANGELOG.md
Le `CHANGELOG.md` est un document de changement de version
@@ -61,8 +74,8 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
À noter : la **parité du numéro de patch** porte une signification de canal :
-- **patch pair** (ex. `1.0.0`, `1.0.2`) → **stable**
-- **patch impair** (ex. `1.0.1`, `1.0.3`) → **preview**
+- **patch pair** (ex. `1.0.0`, `1.0.2`) → **preview**
+- **patch impair** (ex. `1.0.1`, `1.0.3`) → **stable**
- **suffixe** (ex. `1.0.0-rc1`, `1.0.0-alpha`) → **instable**
Cette convention est partagée avec le dépôt
diff --git a/Directory.Packages.props b/Directory.Packages.props
index 7505c8512..f1be93f91 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -1,15 +1,31 @@
true
+ 8.1.0-pazofrc007
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -17,14 +33,24 @@
-
+
+
+
+
+
+
+
+
+
+
+
-
\ No newline at end of file
+
diff --git a/Makefile b/Makefile
index 08f0461d2..d99fe5e5e 100644
--- a/Makefile
+++ b/Makefile
@@ -48,70 +48,4 @@ docker-build:
docker-run:
docker run -d -p 5000:5000 --name yavsc yavsc
-# Crée une branche release/ depuis main, met à jour les
-# `` des .csproj via dotnet-gitversion, et la
-# pousse sur origin.
-#
-# Usage : make release V=1.0.7-rc1
-#
-# Pré-requis : être sur main, working tree clean. La cible
-# vérifie les deux et refuse sinon — elle ne fait JAMAIS
-# de checkout automatique, c'est à l'opérateur de s'être
-# positionné sur la bonne branche au préalable (sinon le
-# bump pourrait partir sur une branche tierce par accident).
-#
-# Notes :
-# - Le nom de branche vient de l'argument V (ex: 1.0.7-rc1
-# donne release/1.0.7-rc1). C'est une étiquette d'intention,
-# pas la version assembly.
-# - La version dans les .csproj vient de GitVersion qui la
-# calcule depuis l'historique git (tag le plus proche +
-# nombre de commits). C'est la version assembly réelle.
-# - L'ordre (fetch → branche → bump → push) garantit qu'on
-# part d'un main synchro et qu'on ne pollue pas main avec
-# le bump (qui vit sur la branche release).
-# - Fail-fast si la branche existe déjà en local ou sur origin.
-release:
- @if [ -z "$(V)" ]; then \
- echo "Usage: make release V="; \
- echo " V : version semver (ex. 1.0.7-rc1) — sert à nommer la branche."; \
- exit 1; \
- fi
- @if [ -n "$$(git status --porcelain)" ]; then \
- echo "Working tree sale, refus de créer une branche release."; \
- git status --short; \
- exit 1; \
- fi
- @BRANCH="release/$(V)"; \
- if git show-ref --verify --quiet "refs/heads/$$BRANCH"; then \
- echo "La branche $$BRANCH existe déjà en local."; \
- echo " Pour la supprimer : git branch -D $$BRANCH"; \
- exit 1; \
- fi; \
- if git ls-remote --exit-code --heads origin "$$BRANCH" >/dev/null 2>&1; then \
- echo "La branche $$BRANCH existe déjà sur origin."; \
- exit 1; \
- fi; \
- echo "==> Fetch + vérification synchro main"; \
- git fetch origin main; \
- if ! git merge-base --is-ancestor origin/main HEAD; then \
- echo "main a avancé plus loin que HEAD. Fais :"; \
- echo " git pull --ff-only origin main"; \
- exit 1; \
- fi; \
- echo "==> Création de $$BRANCH depuis main"; \
- git checkout -b "$$BRANCH"; \
- echo "==> dotnet-gitversion /updateprojectfiles"; \
- dotnet-gitversion /updateprojectfiles; \
- echo "==> Commit du bump"; \
- git add .; \
- if git diff --cached --quiet; then \
- echo "Pas de changements à committer (gitversion n'a produit aucune diff)."; \
- else \
- git commit -m "chore(release): bump version via gitversion for $(V)"; \
- fi; \
- echo "==> Push de $$BRANCH sur origin"; \
- git push -u origin "$$BRANCH"; \
- echo "==> Terminé. Branche $$BRANCH live sur origin."
-
-.PHONY: test release
+.PHONY: test install docker-image docker-build docker-run
diff --git a/README.md b/README.md
index b132f3f20..549348f4a 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,10 @@ sous [`doc/`](./doc/). Voir l'[index de la documentation](./doc/README.md)
pour le sommaire complet. La racine de l'architecture est
[Architecture.md](./doc/Architecture.md).
+Pour une prise en main guidee avec agents IA:
+- parcours onboarding: [doc/onboarding-agents.md](./doc/onboarding-agents.md)
+- playbook d'usage: [doc/agent-playbook.md](./doc/agent-playbook.md)
+
# Construction et déploiement
diff --git a/contrib/Makefile b/contrib/Makefile
index 79145668f..4e4ef4df6 100644
--- a/contrib/Makefile
+++ b/contrib/Makefile
@@ -95,6 +95,15 @@ showConfig:
@echo CONFIGURATION: $(CONFIGURATION)
@echo BASEAPPDIR: $(BASEAPPDIR)
+showApiLogs:
+ @sudo journalctl -u yavscApi.service -S "2 min ago" | tee yavscApi.log
+
+showOrgLogs:
+ @sudo journalctl -u yavscOrg.service -S "2 min ago" | tee yavscOrg.log
+
+showBlogsLogs:
+ @sudo journalctl -u yavscBlogs.service -S "2 min ago" | tee yavscBlogs.log
+
clean:
@rm -rf generated
diff --git a/doc/README.md b/doc/README.md
index 912a2e562..fb9bea943 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -18,6 +18,9 @@ La racine de l'architecture est [Architecture.md](Architecture.md).
| [architecture/postit.md](architecture/postit.md) | PostIt — topologie des projets, ViewLocator custo, navigation, DI, conventions de binding |
| [architecture/decoupage-organisation.md](architecture/decoupage-organisation.md) | Découpage des projets .NET (Abstract, Server, Org, Api, Blogs, Web, Org.Tests) |
| [testing.md](testing.md) | Stratégie de test : conventions des dossiers, EF Core in-memory, auth stubs, scaffold partagé |
+| [onboarding-agents.md](onboarding-agents.md) | Parcours pas-à-pas pour prise en main agents IA + architecture + tests |
+| [agent-playbook.md](agent-playbook.md) | Playbook d'usage de Copilot, Plan, Explore avec scénarios et anti-patterns |
+| [agent-intent-matrix.md](agent-intent-matrix.md) | Matrice intentions développeur -> agent -> preuves attendues |
## Roadmap & design exploration
diff --git a/doc/agent-intent-matrix.md b/doc/agent-intent-matrix.md
new file mode 100644
index 000000000..975cd7b79
--- /dev/null
+++ b/doc/agent-intent-matrix.md
@@ -0,0 +1,20 @@
+# Matrice intentions -> agent -> preuves
+
+Cette matrice aide a choisir rapidement l'agent adapte et a exiger
+une sortie verifiable.
+
+| Intention developpeur | Agent principal | Entrees minimales | Sortie minimale attendue | Verification |
+|---|---|---|---|---|
+| Comprendre un BC avant changement | Explore | BC cible, profondeur, contrainte de perimetre | Composants, points d'entree, tests relies, risques | Lire les fichiers cites + confirmer tests proposes |
+| Decomposer une tache transverse | Plan | Objectif, contraintes, definition of done | Etapes ordonnees, dependances, criteres de verif | Verifier que chaque etape a une preuve observable |
+| Implementer une modif locale | Copilot | Fichier cible, comportement attendu, conventions | Patch minimal, justification courte | Build/test du projet impacte |
+| Ajouter un test smoke | Copilot (+Explore) | Route/endpoint, projet de test cible | Test + commande cible | Execution test cible |
+| Corriger une regression | Plan + Copilot | Symptome, zone suspecte, test attendu | Fix + test NonRegression | Test rouge avant, vert apres |
+| Diagnostiquer flux PostIt/OIDC | Explore + Plan | Flux, symptome, plateforme | Carte du flux + hypotheses testables | Verification manuelle + tests existants |
+
+## Regles d'arbitrage
+
+- Si l'intention est "comprendre": commencer par Explore.
+- Si l'intention est "orchestrer": commencer par Plan.
+- Si l'intention est "produire": utiliser Copilot apres cadrage.
+- Si une sortie n'inclut pas de preuve, elle est incomplete.
diff --git a/doc/agent-playbook.md b/doc/agent-playbook.md
new file mode 100644
index 000000000..ecc14f1d2
--- /dev/null
+++ b/doc/agent-playbook.md
@@ -0,0 +1,101 @@
+# Playbook d'usage des agents IA (Yavsc)
+
+Ce playbook normalise l'usage de Copilot, Plan et Explore dans le depot.
+Il privilegie des sorties verifiables: fichiers, commandes tests, risques.
+
+## Quand utiliser quel agent
+
+- Plan: quand la tache est ambigue, transverse ou risquee.
+- Explore: quand il faut cartographier rapidement des zones du code.
+- Copilot: quand les specifications sont claires et localisees.
+
+## Prompt type (base)
+
+Utiliser ce squelette avant toute tache non triviale:
+
+```text
+Contexte:
+Objectif:
+Contraintes: