@atlashub/smartstack-cli 3.37.0 → 3.38.0

package/templates/skills/documentation/templates.md

@@ -11,24 +11,87 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 
 | # | Section | Objectif | Public cible |
 |---|---------|----------|--------------|
-| 1 | **Valeur Metier** | Pourquoi cette fonctionnalite existe | Decideurs, Managers |
-| 2 | **Cas d'usage** | Exemples concrets du quotidien | Utilisateurs finaux |
-| 3 | **Benefices** | Gains mesurables (temps, argent, qualite) | Decideurs |
-| 4 | **Avant/Apres** | Comparaison visuelle | Tous |
-| 5 | **Fonctionnalites** | Liste detaillee des capacites | Utilisateurs |
-| 6 | **Comment ca marche** | Guide pas a pas | Utilisateurs |
-| 7 | **FAQ Metier** | Questions non-techniques | Tous |
-| 8 | **Reference technique** | Permissions, API (optionnel) | Admins |
+| 1 | **Valeur Metier** | Pourquoi cette fonctionnalite existe (probleme + solution) | Decideurs, Managers |
+| 2 | **Acces** | Navigation breadcrumb + URL | Utilisateurs |
+| 3 | **Apercu de l'interface** | **Mock UI annote** reproduisant la page reelle | Utilisateurs |
+| 4 | **Formulaire de creation** | **Mock UI annote** du formulaire de creation | Utilisateurs |
+| 5 | **Vue detail** | **Mock UI annote** de la vue detail/edition | Utilisateurs |
+| 6 | **Cas d'usage** | Exemples concrets avec personas | Utilisateurs finaux |
+| 7 | **Fonctionnalites** | Liste detaillee des capacites avec exemples | Utilisateurs |
+| 8 | **FAQ** | Questions non-techniques | Tous |
+| 9 | **Reference technique** | Permissions, API, regles metier (collapsible) | Admins |
+
+> **SUPPRIME:** Les sections "Benefices" et "Avant/Apres" ne sont plus incluses.
+> Ce n'est pas un document de vente, mais une documentation utilisateur.
 
 ---
 
-## Data-Driven Approach (Recommended)
+## REGLE FONDAMENTALE: Lire la vraie page AVANT de generer
 
-> **Principe:** Au lieu de générer un composant TSX complet (~250 lignes) par module,
-> générer uniquement un fichier de DONNÉES (`doc-data.ts`, ~50 lignes) + un wrapper minimal.
-> Le rendu est assuré par le composant partagé `DocRenderer` dans `web/.../components/docs/`.
+> **OBLIGATOIRE:** Avant de generer le Mock UI, lire le composant TSX de la vraie page
+> (ex: `TenantsTemplatePage.tsx`, `UsersPage.tsx`). Le Mock UI doit reproduire
+> fidelement l'interface reelle, PAS une interface generique avec des KPI/tables.
+>
+> - Si la vraie page affiche 2 cartes template → le Mock UI montre 2 cartes template
+> - Si la vraie page est un tableau de gestion → le Mock UI montre un tableau
+> - Si la vraie page est un Kanban → le Mock UI montre un Kanban
 
-### Fichiers à générer par module
+---
+
+## Mock UI TSX Approach (TYPE: user — PRIMARY)
+
+> **Principe:** Pour les docs de type `user`, generer un **composant TSX autonome** (~400-600 lignes)
+> avec des Mock UI **annotes** qui reproduisent fidelement les vraies pages
+> de l'application. Chaque Mock UI est suivi d'annotations explicatives.
+>
+> **IMPORTANT:** NE PAS utiliser DocRenderer pour le type `user`. Generer un TSX standalone.
+
+### Fichiers a generer par module
+
+**1. Page TSX** (`index.tsx`, ~400-600 lignes) : Composant autonome avec Mock UI annotes.
+
+**2. i18n dans les 4 langues** : FR (source), EN, DE, IT. Tous les fichiers sont generes.
+
+### i18n JSON : Structure PLATE (pas de cle racine)
+
+> **IMPORTANT:** Pour les pages standalone (type `user`), le JSON i18n doit etre **PLAT** (pas de cle racine).
+> `useTranslation('docsAdministrationTenantsTemplate')` + `t('title')` resout en
+> `docsAdministrationTenantsTemplate.title`. Si le JSON a une cle racine, ca devient
+> `docsAdministrationTenantsTemplate.docsAdministrationTenantsTemplate.title` → ERREUR.
+
+```json
+// CORRECT pour standalone (type user) - JSON PLAT :
+{
+  "title": "Templates de Tenant",
+  "subtitle": "Description...",
+  "sections": { "businessValue": "Pourquoi ce module ?" }
+}
+
+// INCORRECT pour standalone :
+{
+  "docsAdministrationTenantsTemplate": {
+    "title": "Templates de Tenant"
+  }
+}
+
+// CORRECT pour DocRenderer (type developer/database/testing) - AVEC cle racine :
+{
+  "docsAdministrationUsers": {
+    "overview": { "objective": "..." }
+  }
+}
+```
+
+---
+
+## DocRenderer Approach (TYPE: developer|database|testing)
+
+> **Usage:** Pour les docs `developer`, `database`, et `testing` uniquement.
+> Genere un fichier de DONNEES (`doc-data.ts`, ~50 lignes) + un wrapper minimal.
+> Le rendu est assure par le composant partage `DocRenderer` dans `web/.../components/docs/`.
+> Voir [data-schema.md](data-schema.md) pour le mapping complet.
+
+### Fichiers a generer par module
 
 **1. Data file** (`doc-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.
 
@@ -42,54 +105,117 @@ export default function {ModuleName}DocPage() {
 }
 ```
 
-**3. i18n FR uniquement** : Générer la langue source (FR). EN/IT/DE sont déférés.
+---
 
-> **Screenshots:** Chemins conventionnels `/assets/docs/{module}/step-{N}.png`.
-> Le renderer affiche un placeholder "Screenshot à venir" si l'image n'existe pas.
+## Composant Helper: Annotation
 
----
+> **OBLIGATOIRE** pour chaque section Mock UI. Un Mock sans explication ne sert a rien.
+
+```tsx
+import { Info } from 'lucide-react';
+
+function Annotation({ text }: { text: string }) {
+  return (
+    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-blue-500/5 border border-blue-500/15 text-sm text-blue-700 dark:text-blue-400">
+      <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
+      <span>{text}</span>
+    </div>
+  );
+}
+```
 
-## Legacy: Template TSX Complet (référence)
+**Utilisation:** Apres chaque bloc Mock UI, ajouter un `<div className="space-y-2 mt-4">` contenant
+les `<Annotation text={t('section.annotations.key')} />` pour chaque element visuel.
 
-> **Déprécié:** Conservé pour référence. Utilisez l'approche data-driven ci-dessus.
+### Exemple d'annotation apres un Mock UI
 
 ```tsx
-// web/smartstack-web/src/pages/docs/user/{ModuleName}DocPage.tsx
+{/* Mock UI card ici */}
+<div className="card p-6">...</div>
+
+{/* Annotations explicatives */}
+<div className="space-y-2 mt-4">
+  <Annotation text={t('interface.annotations.icon')} />
+  <Annotation text={t('interface.annotations.title')} />
+  <Annotation text={t('interface.annotations.code')} />
+  <Annotation text={t('interface.annotations.defaultBadge')} />
+  <Annotation text={t('interface.annotations.cta')} />
+</div>
+```
+
+---
+
+## Template TSX Mock UI (TYPE: user)
+
+```tsx
+// web/smartstack-web/src/pages/docs/business/{application}/{module}/index.tsx
 
 import { Link } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import {
-  ArrowRight,
-  CheckCircle,
-  XCircle,
-  Lightbulb,
+  ArrowLeft,
+  Info,
   Target,
-  Clock,
-  DollarSign,
+  Lightbulb,
   Users,
-  TrendingUp,
   Zap,
-  Quote,
-  ArrowRightLeft
+  ChevronDown,
+  // + icones specifiques au module
 } from 'lucide-react';
 
-export function {ModuleName}DocPage() {
-  const { t } = useTranslation('docs');
+// ═══════════════════════════════════════════════════
+// Helper: Annotation (obligatoire pour chaque Mock UI)
+// ═══════════════════════════════════════════════════
+function Annotation({ text }: { text: string }) {
+  return (
+    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-blue-500/5 border border-blue-500/15 text-sm text-blue-700 dark:text-blue-400">
+      <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
+      <span>{text}</span>
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════
+// Data: API Endpoints (extraits du vrai controller)
+// ═══════════════════════════════════════════════════
+const apiEndpoints = [
+  // Remplir avec les vrais endpoints du controller
+  { method: 'GET', path: '/api/...', handler: 'GetAll', permission: '...' },
+];
+
+// ═══════════════════════════════════════════════════
+// Data: Business Rules (extraites du domain/tests)
+// ═══════════════════════════════════════════════════
+const businessRules = [
+  // Remplir avec les vraies regles metier
+  { id: 'BR-001', rule: '...' },
+];
+
+export default function {Module}DocPage() {
+  const { t } = useTranslation('docsAdministration{Module}');
 
   return (
-    <div className="space-y-8">
-      {/* HEADER avec proposition de valeur */}
+    <div className="space-y-8 max-w-5xl mx-auto pb-12">
+      {/* BREADCRUMB + BACK */}
+      <div>
+        <Link to="/docs/business/platform/administration/tenants"
+          className="inline-flex items-center gap-1.5 text-sm text-[var(--text-secondary)] hover:text-[var(--color-primary-600)] mb-4">
+          <ArrowLeft className="w-4 h-4" />
+          {t('nav.backToParent')}
+        </Link>
+      </div>
+
+      {/* HEADER */}
       <div>
         <h1 className="text-3xl font-bold mb-4 flex items-center gap-3">
           <ModuleIcon className="w-8 h-8 text-[var(--color-primary-600)]" />
-          {t('{module}.title')}
+          {t('title')}
         </h1>
-        {/* PROPOSITION DE VALEUR - 1 phrase percutante */}
         <p className="text-xl text-[var(--color-primary-600)] font-medium mb-2">
-          {t('{module}.valueProposition')}
+          {t('valueProposition')}
         </p>
         <p className="text-lg text-[var(--text-secondary)]">
-          {t('{module}.subtitle')}
+          {t('subtitle')}
         </p>
       </div>
 
@@ -99,304 +225,302 @@ export function {ModuleName}DocPage() {
       <section id="valeur" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">1</span>
-          Pourquoi ce module ?
+          {t('sections.businessValue')}
         </h2>
 
         <div className="card p-6">
-          {/* Probleme resolu */}
           <div className="mb-6">
             <h3 className="font-semibold mb-3 flex items-center gap-2">
               <Target className="w-5 h-5 text-red-500" />
-              Le probleme que nous resolvons
+              {t('sections.problem')}
             </h3>
-            <p className="text-[var(--text-secondary)]">
-              {t('{module}.problem')}
-            </p>
+            <p className="text-[var(--text-secondary)]">{t('problem')}</p>
           </div>
 
-          {/* Solution apportee */}
           <div className="p-4 rounded-lg bg-green-500/10 border border-green-500/20">
             <h3 className="font-semibold mb-2 flex items-center gap-2 text-green-700">
               <Lightbulb className="w-5 h-5" />
-              Notre solution
+              {t('sections.solution')}
             </h3>
-            <p className="text-[var(--text-secondary)]">
-              {t('{module}.solution')}
-            </p>
+            <p className="text-[var(--text-secondary)]">{t('solution')}</p>
           </div>
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 2: CAS D'USAGE - Exemples concrets                        */}
+      {/* SECTION 2: ACCES - Navigation                                     */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="cas-usage" className="scroll-mt-4">
+      <section id="acces" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">2</span>
-          Exemples d'utilisation
+          {t('sections.access')}
         </h2>
-
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-          {/* Cas d'usage 1 - avec persona */}
-          <div className="card p-6">
-            <div className="flex items-center gap-3 mb-4">
-              <div className="w-12 h-12 rounded-full bg-blue-500/10 flex items-center justify-center">
-                <Users className="w-6 h-6 text-blue-600" />
-              </div>
-              <div>
-                <div className="font-semibold">{t('{module}.useCases.1.persona')}</div>
-                <div className="text-sm text-[var(--text-secondary)]">{t('{module}.useCases.1.role')}</div>
-              </div>
-            </div>
-            <div className="space-y-3">
-              <div className="text-sm">
-                <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
-                <p>{t('{module}.useCases.1.situation')}</p>
-              </div>
-              <div className="text-sm">
-                <span className="font-medium text-green-600">Avec {t('{module}.title')}:</span>
-                <p>{t('{module}.useCases.1.withFeature')}</p>
-              </div>
-            </div>
-          </div>
-
-          {/* Cas d'usage 2 */}
-          <div className="card p-6">
-            <div className="flex items-center gap-3 mb-4">
-              <div className="w-12 h-12 rounded-full bg-purple-500/10 flex items-center justify-center">
-                <Users className="w-6 h-6 text-purple-600" />
-              </div>
-              <div>
-                <div className="font-semibold">{t('{module}.useCases.2.persona')}</div>
-                <div className="text-sm text-[var(--text-secondary)]">{t('{module}.useCases.2.role')}</div>
-              </div>
-            </div>
-            <div className="space-y-3">
-              <div className="text-sm">
-                <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
-                <p>{t('{module}.useCases.2.situation')}</p>
-              </div>
-              <div className="text-sm">
-                <span className="font-medium text-green-600">Avec {t('{module}.title')}:</span>
-                <p>{t('{module}.useCases.2.withFeature')}</p>
-              </div>
-            </div>
+        <div className="card p-6">
+          {/* Breadcrumb de navigation et URL */}
+          <div className="flex items-center gap-2 text-sm">
+            <span>Platform</span> <span>›</span>
+            <span>Administration</span> <span>›</span>
+            <span className="font-semibold">{t('title')}</span>
           </div>
+          <code className="mt-2 block text-xs text-[var(--text-secondary)]">
+            /platform/administration/{module}
+          </code>
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 3: BENEFICES MESURABLES                                   */}
+      {/* SECTION 3: APERCU DE L'INTERFACE — Mock UI ANNOTE                 */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="benefices" className="scroll-mt-4">
+      {/*                                                                    */}
+      {/* IMPORTANT: Le Mock UI ci-dessous doit reproduire fidelement       */}
+      {/* la VRAIE page TSX du module. Lire le composant source d'abord.    */}
+      {/*                                                                    */}
+      {/* Exemples:                                                          */}
+      {/*   - TenantsTemplatePage → 2 cartes template (Personal + Business)  */}
+      {/*   - UsersPage → tableau de gestion avec filtres                    */}
+      {/*   - TicketsPage → Kanban board avec colonnes par statut            */}
+      {/* ══════════════════════════════════════════════════════════════════ */}
+      <section id="interface" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">3</span>
-          Benefices concrets
+          {t('sections.interface')}
         </h2>
 
-        <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
-          {/* Benefice 1: Gain de temps */}
-          <div className="card p-6 text-center">
-            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-blue-500/10 flex items-center justify-center">
-              <Clock className="w-8 h-8 text-blue-600" />
-            </div>
-            <div className="text-3xl font-bold text-blue-600 mb-2">-70%</div>
-            <div className="font-semibold mb-1">Temps economise</div>
-            <p className="text-sm text-[var(--text-secondary)]">
-              {t('{module}.benefits.time.description')}
-            </p>
-          </div>
-
-          {/* Benefice 2: Reduction des erreurs */}
-          <div className="card p-6 text-center">
-            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-green-500/10 flex items-center justify-center">
-              <TrendingUp className="w-8 h-8 text-green-600" />
-            </div>
-            <div className="text-3xl font-bold text-green-600 mb-2">+95%</div>
-            <div className="font-semibold mb-1">Fiabilite</div>
-            <p className="text-sm text-[var(--text-secondary)]">
-              {t('{module}.benefits.quality.description')}
-            </p>
-          </div>
+        {/* Mock UI reproduisant la vraie page */}
+        <div className="card p-6">
+          {/* ... MOCK UI FIDELE A LA VRAIE PAGE ... */}
+        </div>
 
-          {/* Benefice 3: ROI */}
-          <div className="card p-6 text-center">
-            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-amber-500/10 flex items-center justify-center">
-              <DollarSign className="w-8 h-8 text-amber-600" />
-            </div>
-            <div className="text-3xl font-bold text-amber-600 mb-2">3x</div>
-            <div className="font-semibold mb-1">Retour sur investissement</div>
-            <p className="text-sm text-[var(--text-secondary)]">
-              {t('{module}.benefits.roi.description')}
-            </p>
-          </div>
+        {/* ANNOTATIONS OBLIGATOIRES apres le Mock UI */}
+        <div className="space-y-2 mt-4">
+          <Annotation text={t('interface.annotations.element1')} />
+          <Annotation text={t('interface.annotations.element2')} />
+          {/* ... une annotation par element visuel important ... */}
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 4: AVANT/APRES - Comparaison visuelle                     */}
+      {/* SECTION 4: FORMULAIRE DE CREATION — Mock UI ANNOTE                */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="avant-apres" className="scroll-mt-4">
+      <section id="form" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">4</span>
-          Avant / Apres
+          {t('sections.createForm')}
         </h2>
 
-        <div className="card p-6">
-          <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-            {/* AVANT */}
-            <div className="p-4 rounded-lg bg-red-500/5 border border-red-500/20">
-              <h3 className="font-semibold mb-4 flex items-center gap-2 text-red-600">
-                <XCircle className="w-5 h-5" />
-                Avant: Sans {t('{module}.title')}
-              </h3>
-              <ul className="space-y-2">
-                {[1, 2, 3, 4].map((i) => (
-                  <li key={i} className="flex items-start gap-2 text-sm">
-                    <XCircle className="w-4 h-4 text-red-500 mt-0.5 flex-shrink-0" />
-                    <span>{t(`{module}.before.${i}`)}</span>
-                  </li>
-                ))}
-              </ul>
-            </div>
+        {/* Paragraphe d'introduction */}
+        <p className="text-[var(--text-secondary)] mb-4">{t('form.desc')}</p>
 
-            {/* APRES */}
-            <div className="p-4 rounded-lg bg-green-500/5 border border-green-500/20">
-              <h3 className="font-semibold mb-4 flex items-center gap-2 text-green-600">
-                <CheckCircle className="w-5 h-5" />
-                Apres: Avec {t('{module}.title')}
-              </h3>
-              <ul className="space-y-2">
-                {[1, 2, 3, 4].map((i) => (
-                  <li key={i} className="flex items-start gap-2 text-sm">
-                    <CheckCircle className="w-4 h-4 text-green-500 mt-0.5 flex-shrink-0" />
-                    <span>{t(`{module}.after.${i}`)}</span>
-                  </li>
-                ))}
-              </ul>
-            </div>
+        {/* Mock UI du formulaire */}
+        <div className="border border-[var(--border-color)] rounded-lg p-6 bg-[var(--bg-secondary)]">
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            {/* Champs de formulaire adaptes au module */}
+          </div>
+          <div className="flex items-center gap-3 mt-6 pt-6 border-t border-[var(--border-color)]">
+            <button className="px-4 py-2 bg-[var(--color-primary-600)] text-white rounded-lg">
+              {t('form.create')}
+            </button>
+            <button className="px-4 py-2 border border-[var(--border-color)] rounded-lg">
+              {t('form.cancel')}
+            </button>
           </div>
         </div>
+
+        {/* ANNOTATIONS OBLIGATOIRES apres le formulaire */}
+        <div className="space-y-2 mt-4">
+          <Annotation text={t('form.annotations.field1')} />
+          <Annotation text={t('form.annotations.field2')} />
+          <Annotation text={t('form.annotations.actions')} />
+        </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 5: FONCTIONNALITES DETAILLEES                             */}
+      {/* SECTION 5: VUE DETAIL — Mock UI ANNOTE                            */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="fonctionnalites" className="scroll-mt-4">
+      <section id="detail" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">5</span>
-          Ce que vous pouvez faire
+          {t('sections.detailView')}
         </h2>
 
-        <div className="space-y-4">
-          {/* Feature Card avec exemple */}
-          <div className="card p-6">
-            <div className="flex items-start gap-4">
-              <div className="w-12 h-12 rounded-lg bg-[var(--color-primary-600)]/10 flex items-center justify-center flex-shrink-0">
-                <Zap className="w-6 h-6 text-[var(--color-primary-600)]" />
-              </div>
-              <div className="flex-1">
-                <h3 className="font-semibold mb-2">{t('{module}.features.1.title')}</h3>
-                <p className="text-[var(--text-secondary)] mb-3">
-                  {t('{module}.features.1.description')}
-                </p>
-                {/* Exemple concret */}
-                <div className="p-3 rounded-lg bg-[var(--bg-secondary)] text-sm">
-                  <span className="font-medium text-[var(--color-primary-600)]">Exemple: </span>
-                  {t('{module}.features.1.example')}
-                </div>
-              </div>
-            </div>
-          </div>
+        {/* Paragraphe d'introduction */}
+        <p className="text-[var(--text-secondary)] mb-4">{t('detail.desc')}</p>
 
-          {/* Repeter pour chaque fonctionnalite */}
+        {/* Mock UI de la vue detail */}
+        <div className="card p-6">
+          {/* ... MOCK UI FIDELE A LA VRAIE VUE DETAIL ... */}
+        </div>
+
+        {/* ANNOTATIONS OBLIGATOIRES */}
+        <div className="space-y-2 mt-4">
+          <Annotation text={t('detail.annotations.header')} />
+          <Annotation text={t('detail.annotations.tabs')} />
+          <Annotation text={t('detail.annotations.stats')} />
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 6: COMMENT CA MARCHE - Guide pas a pas                    */}
+      {/* SECTION 6: CAS D'USAGE - Exemples concrets                        */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="guide" className="scroll-mt-4">
+      <section id="cas-usage" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">6</span>
-          Comment demarrer
+          {t('sections.useCases')}
         </h2>
 
-        <div className="card p-6">
-          <div className="space-y-6">
-            {/* Etape 1 */}
-            <div className="flex gap-4">
-              <div className="flex flex-col items-center">
-                <div className="w-10 h-10 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center font-bold">
-                  1
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+          {[1, 2, 3].map((i) => (
+            <div key={i} className="card p-6">
+              <div className="flex items-center gap-3 mb-4">
+                <div className="w-10 h-10 rounded-full bg-blue-500/10 flex items-center justify-center">
+                  <Users className="w-5 h-5 text-blue-600" />
+                </div>
+                <div>
+                  <div className="font-semibold">{t(`useCases.${i}.persona`)}</div>
+                  <div className="text-sm text-[var(--text-secondary)]">{t(`useCases.${i}.role`)}</div>
                 </div>
-                <div className="w-0.5 h-full bg-[var(--border-color)] mt-2"></div>
               </div>
-              <div className="flex-1 pb-6">
-                <h4 className="font-semibold mb-2">{t('{module}.steps.1.title')}</h4>
-                <p className="text-sm text-[var(--text-secondary)] mb-3">
-                  {t('{module}.steps.1.description')}
-                </p>
-                {/* Screenshot ou illustration */}
-                <div className="p-4 rounded-lg bg-[var(--bg-secondary)] border-2 border-dashed border-[var(--border-color)] text-center text-sm text-[var(--text-tertiary)]">
-                  [Capture d'ecran de l'etape 1]
+              <div className="space-y-3">
+                <div className="text-sm">
+                  <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
+                  <p>{t(`useCases.${i}.situation`)}</p>
+                </div>
+                <div className="text-sm p-3 rounded-lg bg-green-500/5 border border-green-500/15">
+                  <span className="font-medium text-green-600">Avec la fonctionnalite:</span>
+                  <p>{t(`useCases.${i}.withFeature`)}</p>
                 </div>
               </div>
             </div>
-
-            {/* Repeter pour chaque etape */}
-          </div>
+          ))}
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 7: FAQ METIER                                             */}
+      {/* SECTION 7: FONCTIONNALITES DETAILLEES                             */}
       {/* ══════════════════════════════════════════════════════════════════ */}
-      <section id="faq" className="scroll-mt-4">
+      <section id="fonctionnalites" className="scroll-mt-4">
         <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
           <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">7</span>
-          Questions frequentes
+          {t('sections.features')}
         </h2>
 
         <div className="space-y-4">
-          {/* Question metier, pas technique */}
-          <div className="card p-4">
-            <h3 className="font-medium mb-2">
-              {t('{module}.faq.1.question')}
-            </h3>
-            <p className="text-sm text-[var(--text-secondary)]">
-              {t('{module}.faq.1.answer')}
-            </p>
-          </div>
+          {[1, 2, 3, 4, 5].map((i) => (
+            <div key={i} className="card p-6">
+              <div className="flex items-start gap-4">
+                <div className="w-10 h-10 rounded-lg bg-[var(--color-primary-600)]/10 flex items-center justify-center flex-shrink-0">
+                  <Zap className="w-5 h-5 text-[var(--color-primary-600)]" />
+                </div>
+                <div className="flex-1">
+                  <h3 className="font-semibold mb-2">{t(`features.${i}.title`)}</h3>
+                  <p className="text-[var(--text-secondary)] mb-3">{t(`features.${i}.description`)}</p>
+                  <div className="p-3 rounded-lg bg-[var(--bg-secondary)] text-sm">
+                    <span className="font-medium text-[var(--color-primary-600)]">Exemple: </span>
+                    {t(`features.${i}.example`)}
+                  </div>
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* ══════════════════════════════════════════════════════════════════ */}
+      {/* SECTION 8: FAQ                                                    */}
+      {/* ══════════════════════════════════════════════════════════════════ */}
+      <section id="faq" className="scroll-mt-4">
+        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
+          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">8</span>
+          {t('sections.faq')}
+        </h2>
+
+        <div className="space-y-3">
+          {[1, 2, 3, 4, 5].map((i) => (
+            <details key={i} className="card group">
+              <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-medium flex items-center justify-between">
+                {t(`faq.${i}.question`)}
+                <ChevronDown className="w-4 h-4 text-[var(--text-secondary)] group-open:rotate-180 transition-transform" />
+              </summary>
+              <div className="px-4 pb-4 text-sm text-[var(--text-secondary)]">
+                {t(`faq.${i}.answer`)}
+              </div>
+            </details>
+          ))}
         </div>
       </section>
 
       {/* ══════════════════════════════════════════════════════════════════ */}
-      {/* SECTION 8: REFERENCE TECHNIQUE (optionnel, pour admins)           */}
+      {/* SECTION 9: REFERENCE TECHNIQUE (collapsible)                      */}
       {/* ══════════════════════════════════════════════════════════════════ */}
       <section id="reference" className="scroll-mt-4">
         <details className="card">
           <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-semibold flex items-center gap-2">
-            <span className="w-8 h-8 rounded-full bg-gray-500/10 text-gray-600 flex items-center justify-center text-sm">8</span>
-            Reference technique (administrateurs)
+            <span className="w-8 h-8 rounded-full bg-gray-500/10 text-gray-600 flex items-center justify-center text-sm">9</span>
+            {t('sections.technicalRef')}
           </summary>
-          <div className="p-4 pt-0">
-            {/* Permissions, API, etc. */}
+          <div className="p-6 pt-2 space-y-8">
+
+            {/* Regles metier */}
+            <div>
+              <h3 className="font-semibold mb-3">{t('techRef.businessRules')}</h3>
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead>
+                    <tr className="bg-[var(--bg-secondary)]">
+                      <th className="text-left py-2 px-3 w-24">ID</th>
+                      <th className="text-left py-2 px-3">Regle</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {businessRules.map((rule) => (
+                      <tr key={rule.id} className="border-b border-[var(--border-color)]">
+                        <td className="py-2 px-3 font-mono text-xs">{rule.id}</td>
+                        <td className="py-2 px-3">{t(`techRef.rules.${rule.id}`)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+
+            {/* API Endpoints */}
+            <div>
+              <h3 className="font-semibold mb-3">{t('techRef.apiEndpoints')}</h3>
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead>
+                    <tr className="bg-[var(--bg-secondary)]">
+                      <th className="text-left py-2 px-3">Method</th>
+                      <th className="text-left py-2 px-3">Endpoint</th>
+                      <th className="text-left py-2 px-3">Handler</th>
+                      <th className="text-left py-2 px-3">Permission</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {apiEndpoints.map((ep, i) => (
+                      <tr key={i} className="border-b border-[var(--border-color)]">
+                        <td className="py-2 px-3">
+                          <span className={`px-2 py-0.5 rounded text-xs font-medium ${
+                            ep.method === 'GET' ? 'bg-blue-500/10 text-blue-600' :
+                            ep.method === 'POST' ? 'bg-green-500/10 text-green-600' :
+                            ep.method === 'PUT' ? 'bg-orange-500/10 text-orange-600' :
+                            ep.method === 'PATCH' ? 'bg-purple-500/10 text-purple-600' :
+                            'bg-red-500/10 text-red-600'
+                          }`}>{ep.method}</span>
+                        </td>
+                        <td className="py-2 px-3 font-mono text-xs">{ep.path}</td>
+                        <td className="py-2 px-3 text-[var(--text-secondary)]">{ep.handler}</td>
+                        <td className="py-2 px-3 font-mono text-xs">{ep.permission}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+
           </div>
         </details>
       </section>
-
-      {/* NAVIGATION */}
-      <div className="flex justify-between pt-6 border-t border-[var(--border-color)]">
-        <Link to="/docs/user/previous" className="flex items-center gap-2 text-[var(--text-secondary)] hover:text-[var(--color-primary-600)]">
-          <ArrowRight className="w-4 h-4 rotate-180" />
-          Module precedent
-        </Link>
-        <Link to="/docs/user/next" className="flex items-center gap-2 text-[var(--color-primary-600)]">
-          Module suivant
-          <ArrowRight className="w-4 h-4" />
-        </Link>
-      </div>
     </div>
   );
 }
@@ -404,77 +528,104 @@ export function {ModuleName}DocPage() {
 
 ---
 
-## Structure i18n (Business-First)
+## Structure i18n (4 langues obligatoires)
+
+> **IMPORTANT:** Generer les 4 langues: FR (source), EN, DE, IT.
+> Chaque fichier i18n est au format **PLAT** (pas de cle racine) pour les pages standalone.
+
+### Fichier: `docs-administration-{module}.json`
 
 ```json
 {
-  "{module}": {
-    "title": "Nom du module",
-    "valueProposition": "Une phrase qui resume la valeur (ex: 'Gerez vos prompts IA sans ecrire une ligne de code')",
-    "subtitle": "Description en 1-2 phrases",
-
-    "problem": "Description du probleme que vos utilisateurs rencontrent AVANT d'avoir cette fonctionnalite",
-    "solution": "Comment ce module resout ce probleme de maniere simple",
-
-    "useCases": {
-      "1": {
-        "persona": "Marie",
-        "role": "Responsable RH",
-        "situation": "Marie doit envoyer 50 emails personnalises aux candidats chaque semaine",
-        "withFeature": "Elle selectionne un template, importe sa liste, et envoie tout en 2 clics"
-      },
-      "2": {
-        "persona": "Thomas",
-        "role": "Directeur Commercial",
-        "situation": "Thomas veut suivre les performances de son equipe en temps reel",
-        "withFeature": "Il consulte le dashboard qui affiche les KPIs automatiquement"
-      }
-    },
-
-    "benefits": {
-      "time": { "value": "-70%", "description": "Reduction du temps passe sur les taches repetitives" },
-      "quality": { "value": "+95%", "description": "Moins d'erreurs grace a l'automatisation" },
-      "roi": { "value": "3x", "description": "Rentabilise en moins de 3 mois" }
-    },
-
-    "before": {
-      "1": "Processus manuel et chronophage",
-      "2": "Risque d'erreurs humaines eleve",
-      "3": "Pas de visibilite sur les performances",
-      "4": "Donnees eparpillees dans plusieurs outils"
-    },
-
-    "after": {
-      "1": "Automatisation des taches repetitives",
-      "2": "Validation automatique des donnees",
-      "3": "Tableaux de bord en temps reel",
-      "4": "Centralisation de toutes les informations"
-    },
-
-    "features": {
-      "1": {
-        "title": "Nom de la fonctionnalite",
-        "description": "Explication claire de ce que fait cette fonctionnalite",
-        "example": "Par exemple, vous pouvez creer un prompt 'Reponse Support' qui sera utilise automatiquement pour tous les tickets entrants"
-      }
-    },
-
-    "steps": {
-      "1": {
-        "title": "Accedez au module",
-        "description": "Depuis le menu principal, cliquez sur 'Administration' puis 'Intelligence Artificielle'"
-      }
-    },
-
-    "faq": {
-      "1": {
-        "question": "Dois-je etre technique pour utiliser ce module ?",
-        "answer": "Non, l'interface est concue pour etre utilisee par tous. Aucune connaissance en programmation n'est requise."
-      },
-      "2": {
-        "question": "Combien de temps faut-il pour le mettre en place ?",
-        "answer": "La configuration initiale prend environ 15 minutes. Vous pouvez commencer a utiliser le module immediatement apres."
-      }
+  "nav": {
+    "backToParent": "Retour a {Parent}"
+  },
+  "title": "Nom du module",
+  "valueProposition": "Une phrase percutante resumant la valeur",
+  "subtitle": "Description en 1-2 phrases",
+
+  "sections": {
+    "businessValue": "Pourquoi ce module ?",
+    "problem": "Le probleme",
+    "solution": "La solution",
+    "access": "Acces",
+    "interface": "Apercu de l'interface",
+    "createForm": "Formulaire de creation",
+    "detailView": "Vue detail",
+    "useCases": "Exemples d'utilisation",
+    "benefits": "Benefices concrets",
+    "beforeAfter": "Avant / Apres",
+    "features": "Ce que vous pouvez faire",
+    "faq": "Questions frequentes",
+    "technicalRef": "Reference technique (administrateurs)"
+  },
+
+  "problem": "Description du probleme AVANT cette fonctionnalite",
+  "solution": "Comment ce module resout le probleme",
+
+  "access": {
+    "navigation": "Navigation"
+  },
+
+  "interface": {
+    "sectionTitle": "Titre de la sous-section",
+    "annotations": {
+      "element1": "Explication de l'element visuel 1 du Mock UI",
+      "element2": "Explication de l'element visuel 2 du Mock UI"
+    }
+  },
+
+  "form": {
+    "desc": "Ce formulaire permet de creer un nouveau...",
+    "fieldLabel1": "Label du champ",
+    "create": "Creer",
+    "cancel": "Annuler",
+    "annotations": {
+      "field1": "Explication du champ 1",
+      "field2": "Explication du champ 2",
+      "actions": "Explication des boutons d'action"
+    }
+  },
+
+  "detail": {
+    "desc": "La vue detail s'ouvre lorsque...",
+    "annotations": {
+      "header": "Explication de l'en-tete",
+      "tabs": "Explication des onglets",
+      "stats": "Explication des indicateurs"
+    }
+  },
+
+  "useCases": {
+    "1": {
+      "persona": "Sophie",
+      "role": "Administratrice plateforme",
+      "situation": "Sophie doit...",
+      "withFeature": "Elle utilise..."
+    }
+  },
+
+  "features": {
+    "1": {
+      "title": "Nom de la fonctionnalite",
+      "description": "Explication claire",
+      "example": "Exemple concret"
+    }
+  },
+
+  "faq": {
+    "1": {
+      "question": "Question non-technique ?",
+      "answer": "Reponse claire et concise."
+    }
+  },
+
+  "techRef": {
+    "businessRules": "Regles metier",
+    "apiEndpoints": "Points de terminaison API",
+    "rules": {
+      "BR-001": "Description de la regle metier 1",
+      "BR-002": "Description de la regle metier 2"
     }
   }
 }
@@ -482,19 +633,26 @@ export function {ModuleName}DocPage() {
 
 ---
 
-## Checklist Documentation Business-First
+## Checklist Documentation (TYPE: user)
 
-Avant de valider une documentation, verifier:
+Avant de valider une documentation de module `user`, verifier:
 
+- [ ] **Standalone TSX** (PAS DocRenderer, PAS doc-data.ts)
+- [ ] **Lecture de la vraie page** TSX source AVANT generation du Mock UI
+- [ ] **Mock UI Section 3: Interface** reproduisant fidelement la vraie page
+- [ ] **Mock UI Section 4: Formulaire** avec champs du vrai formulaire
+- [ ] **Mock UI Section 5: Vue detail** avec onglets/stats de la vraie page
+- [ ] **Annotations** sur chaque section Mock UI (composant `Annotation`)
 - [ ] **Proposition de valeur** claire en 1 phrase
-- [ ] **Probleme** decrit du point de vue utilisateur (pas technique)
+- [ ] **Probleme/Solution** du point de vue utilisateur (pas technique)
 - [ ] **2-3 cas d'usage** avec personas nommes
-- [ ] **Benefices chiffres** (%, temps, argent)
-- [ ] **Avant/Apres** visuel
-- [ ] **Exemples concrets** pour chaque fonctionnalite
-- [ ] **Guide pas a pas** avec captures d'ecran
-- [ ] **FAQ metier** (pas technique)
-- [ ] **Reference technique** en section repliable (optionnelle)
+- [ ] **5 fonctionnalites** avec exemples concrets
+- [ ] **5 FAQ** non-techniques
+- [ ] **Reference technique** collapsible: regles metier + API endpoints reels
+- [ ] **Semantic colors** (`var(--success-*)`, `var(--error-*)`, etc.)
+- [ ] **i18n** via `useTranslation()` — pas de texte hardcode
+- [ ] **i18n 4 langues** : FR, EN, DE, IT (JSON plat, pas de cle racine)
+- [ ] **PAS de section "Benefices"** ni "Avant/Apres"
 
 ---