@atlashub/smartstack-cli 4.52.0 → 4.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.52.0",
+  "version": "4.54.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/business-analyse/references/canonical-json-formats.md

@@ -0,0 +1,200 @@
+# Canonical JSON Formats Reference
+
+> **Purpose:** Single source of truth for all JSON file formats produced by the BA pipeline.
+> **Used by:** `/business-analyse` (step-03), `/business-analyse-design` (step-01), `/business-analyse-html`, `/business-analyse-handoff`, `/business-analyse-develop`
+> **Rule:** All producers MUST write canonical format. All consumers MUST accept canonical + deprecated fallbacks.
+
+---
+
+## entities.json
+
+```json
+{
+  "entities": [
+    {
+      "name": "Employee",
+      "description": "...",
+      "personRoleConfig": { "variant": "mandatory", "userFields": ["firstName", "lastName", "email"] },
+      "attributes": [
+        { "name": "code", "type": "string", "required": true, "description": "..." },
+        { "name": "userId", "type": "string", "required": true, "description": "FK auth_Users (ASP.NET Identity)" }
+      ],
+      "versionedAttributes": [
+        { "entity": "Salary", "attributes": ["grossAmount", "effectiveDate"], "reason": "..." }
+      ],
+      "relationships": [
+        { "target": "Department", "type": "ManyToOne", "description": "..." }
+      ]
+    }
+  ]
+}
+```
+
+**Convention guards:**
+- Person entities → `personRoleConfig` + `userId` (string), NO firstName/lastName/email
+- Versioned data → `versionedAttributes[]`, NOT inline fields
+- FK naming → always `{entity}Id` suffix
+- FK to auth_Users → type `string` (ASP.NET Identity), NOT `guid`
+
+---
+
+## usecases.json
+
+```json
+{
+  "useCases": [
+    {
+      "id": "UC-MODULE-001",
+      "name": "Créer un employé",
+      "sectionCode": "list",
+      "primaryActor": "Responsable RH",
+      "preconditions": ["..."],
+      "mainScenario": [
+        "L'utilisateur ouvre la page de création",
+        "Il remplit les champs obligatoires"
+      ],
+      "alternativeScenarios": [
+        { "name": "Données invalides", "steps": ["Le système affiche les erreurs"] }
+      ],
+      "businessRules": ["BR-VAL-MODULE-001"],
+      "result": "L'entité est créée"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `useCases` (root) | `usecases` | camelCase is canonical |
+| `primaryActor` | `actor` | |
+| `mainScenario` (string[]) | `steps` (object[] or string[]) | MUST be strings, never `{step, action}` objects |
+| `alternativeScenarios` (object[]) | `alternativeFlows`, `alternative` (string) | Must be `[{name, steps}]` |
+
+---
+
+## rules.json
+
+```json
+{
+  "rules": [
+    {
+      "id": "BR-VAL-MODULE-001",
+      "name": "Validation date",
+      "category": "validation",
+      "sectionCode": "list",
+      "statement": "La date ne peut pas être dans le futur",
+      "example": "Date = 2027-01-01 → erreur",
+      "entities": ["Employee"],
+      "severity": "blocking"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives |
+|---------------|------------------------|
+| `rules` (root) | `businessRules` |
+| `statement` | `description` |
+| `id` | `name` (as identifier) |
+
+Categories: `validation`, `calculation`, `workflow`, `security`, `data`, `notification`
+
+---
+
+## permissions.json
+
+```json
+{
+  "roles": [
+    { "role": "RH Admin", "description": "..." }
+  ],
+  "permissionPaths": [
+    "HumanResources.Employees.Read",
+    "HumanResources.Employees.Create"
+  ],
+  "matrix": {
+    "roleAssignments": [
+      { "role": "RH Admin", "permissions": ["HumanResources.Employees.*"] }
+    ]
+  }
+}
+```
+
+---
+
+## screens.json
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employés",
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "label": "Grille des employés",
+          "columns": [
+            { "field": "code", "label": "Code", "type": "text", "sortable": true }
+          ],
+          "filters": [
+            { "field": "status", "type": "select", "label": "Statut" }
+          ],
+          "actions": ["create", "export"],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `sections` (root) | `screens` (flat array) | `sections[]` with `resources[]` is canonical |
+| `sectionCode` | `id`, `code` | |
+| `sectionLabel` | `displayName`, `label` | |
+| resource `type` | `layout`, `componentType` | Must be: SmartTable, SmartForm, SmartDashboard, SmartKanban, SmartCard, SmartFilter |
+| column `field` | `code`, `name`, `id`, `fieldCode` | |
+| column `label` | `displayName` | |
+
+**DEPRECATED format (do NOT produce):**
+```json
+{
+  "screens": [
+    { "screen": "employees-list", "section": "list", "componentType": "SmartTable", "columns": [...] }
+  ]
+}
+```
+
+---
+
+## Consumer normalization pattern
+
+All downstream consumers should normalize input using this priority chain:
+
+```javascript
+// usecases
+const rawUCs = data.useCases || data.usecases || [];
+const uc = {
+  name: raw.name || raw.title || raw.id,
+  actor: raw.primaryActor || raw.actor,
+  steps: (raw.mainScenario || raw.steps || []).map(s =>
+    typeof s === 'string' ? s : (s.action || s.description || "")
+  ),
+  alternatives: raw.alternativeScenarios || raw.alternativeFlows || []
+};
+
+// screens
+const sections = data.sections || [];
+const flatScreens = data.screens || [];
+// If flat format: wrap each screen as a section with 1 resource
+
+// columns
+const col = {
+  field: raw.field || raw.code || raw.name || raw.id,
+  label: raw.label || raw.displayName || raw.code,
+  type: raw.renderAs === "badge" ? "badge" : (raw.type || raw.dataType || "text")
+};
+```

package/templates/skills/business-analyse/steps/step-01-cadrage.md

@@ -120,11 +120,68 @@ IF docs/**/*.md files found:
 - Pre-identify integration points: new feature may depend on or extend existing modules
 - NEVER re-specify what's already handed-off (status = "handed-off") — reference it instead
 
+### 2d. Domain Research (WebSearch — BEFORE engaging the client)
+
+> **Ground the analysis in real-world patterns. This prevents greenfield mistakes
+> (e.g., putting firstName on Employee instead of linking to User).**
+> This step takes 30-60 seconds and dramatically improves entity design quality.
+
+**WHEN to search:** ALWAYS for the main business domain. Skip only if the domain is purely SmartStack-internal (e.g., config, admin tools).
+
+**HOW to search:** Use WebSearch tool with targeted queries based on the detected domain.
+
+```
+1. DOMAIN MODEL SEARCH
+   Query: "{detected_domain} data model best practices" (e.g., "HR management data model best practices")
+   → Extract: standard entities, common relationships, industry patterns
+   → Store key findings in {domain_research}.dataModel
+
+2. ENTITY PATTERN SEARCH (for the 2-3 most complex detected entities)
+   Query: "{entity_name} entity design pattern ERP" (e.g., "employee entity design pattern ERP")
+   → Extract: standard attributes, versioning patterns, common pitfalls
+   → Store in {domain_research}.entityPatterns[entity_name]
+
+3. WORKFLOW SEARCH (if the domain involves approval/validation flows)
+   Query: "{domain} approval workflow pattern" (e.g., "timesheet approval workflow pattern")
+   → Extract: standard states, transition rules, multi-level approval
+   → Store in {domain_research}.workflows
+```
+
+**WHAT to extract (ULTRATHINK — internal only):**
+```yaml
+domain_research:
+  domain: "{detected domain — e.g., HR, CRM, Billing}"
+  dataModel:
+    standardEntities: ["Entity1", "Entity2"]     # what the industry considers standard
+    commonRelationships: ["Entity1 → Entity2"]   # typical FK patterns
+    antiPatterns: ["storing salary directly on employee"]  # mistakes to avoid
+  entityPatterns:
+    Employee:
+      standardAttributes: ["code", "userId", "departmentId", "hireDate", "status"]
+      versionedData: ["salary → separate table with effectiveDate"]
+      personPattern: "link to User via FK, never duplicate personal info"
+    Invoice:
+      standardAttributes: ["number", "clientId", "issueDate", "dueDate", "status"]
+      calculatedFields: ["subtotal", "taxAmount", "total"]
+      workflowStates: ["Draft", "Sent", "Paid", "Overdue", "Cancelled"]
+  workflows:
+    timesheetApproval: "Draft → Submitted → ManagerApproved → ClientApproved"
+    invoiceLifecycle: "Draft → Validated → Sent → Paid"
+```
+
+> **CRITICAL:** This research is INTERNAL context. Do NOT show raw search results to the client.
+> Use the findings to:
+> - Improve pre-analysis quality (detect shadow zones the client won't mention)
+> - Ground entity architecture decisions in Phase 4d-bis
+> - Inform proactive suggestions in Phase 4 (ANTICIPATION)
+> - Prevent common anti-patterns during step-03 entity specification
+
 ### 2b. Silent Pre-Analysis (ULTRATHINK — no output to client)
 
 > **The AI prepares the conversation before speaking. This is NOT output — it's internal reasoning.**
+> **INCLUDES domain research findings from 2d above.**
 
-Analyze `{feature_description}` silently:
+Analyze `{feature_description}` AND `{domain_research}` silently:
 
 1. **Identify problem type** from keywords (replace, automate, centralize, new tool)
 2. **Extract explicit modules/features** mentioned in the description
@@ -143,6 +200,12 @@ _preAnalysis:
   detected_modules: [{name, description, detected_sections}]
   shadow_zones: [{topic, why_it_matters, challenge_question}]
   anticipated_suggestions: [{suggestion, justification, module}]
+  domain_research:                          # from Phase 2d web search
+    domain: "{detected domain}"
+    standardEntities: [...]
+    antiPatterns: [...]
+    entityPatterns: {entity: {standardAttributes, versionedData, personPattern}}
+    workflows: {name: "state1 → state2 → state3"}
 ```
 
 ---

package/templates/skills/business-analyse/steps/step-03-specify.md

@@ -43,9 +43,41 @@ For each module, execute these sub-steps:
 
 Load via ba-reader:
 - Module's `index.json` (if exists from previous run)
-- Application `cadrage.json` for stakeholder context
+- Application `cadrage.json` for stakeholder context (including `_preAnalysis.domain_research`)
 - Completed modules' summaries (compact, <100 lines each)
 
+### A-bis. Entity Pattern Research (WebSearch — per module)
+
+> **Before defining entities, validate design against industry best practices.**
+> Uses domain_research from step-01 as baseline, then does targeted searches for this specific module.
+
+```
+IF cadrage._preAnalysis.domain_research exists:
+  → Load as baseline (already researched in step-01)
+ELSE:
+  → Run a quick WebSearch: "{module_domain} entity data model best practices"
+
+FOR each main entity in this module (max 2-3 searches):
+  Query: "{entity_name} entity design pattern {domain}"
+  (e.g., "invoice entity design ERP", "timesheet data model best practices")
+
+  EXTRACT (ULTRATHINK — internal only):
+  - Standard attributes for this entity type
+  - Common relationships and cardinality
+  - Versioned vs. inline data patterns (e.g., salary history)
+  - Workflow states if applicable
+  - Known anti-patterns to avoid
+
+  CROSS-CHECK against SmartStack conventions (B-bis rules):
+  - Would this entity trigger Person Extension Pattern?
+  - Are there attributes that should be versioned (salary, rate)?
+  - Does this entity already exist in the SmartStack socle DB?
+```
+
+> **CRITICAL:** This research informs entity design but does NOT override SmartStack conventions.
+> If web research suggests putting firstName on Employee, the B-bis guard still blocks it
+> because SmartStack uses auth_Users for personal data.
+
 ### B. Entities
 
 For each entity identified in step 02:
@@ -54,25 +86,56 @@ For each entity identified in step 02:
 {
   "name": "Employee",
   "description": "Représente un employé de l'entreprise",
+  "personRoleConfig": { "variant": "mandatory", "userFields": ["firstName", "lastName", "email"] },
   "attributes": [
-    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique" },
-    { "name": "userId", "type": "guid", "required": true, "description": "Référence vers l'utilisateur" },
+    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique auto-généré" },
+    { "name": "userId", "type": "string", "required": true, "description": "FK vers auth_Users (ASP.NET Identity — type string, NOT guid)" },
     { "name": "departmentId", "type": "guid", "required": true, "description": "Département d'affectation" },
     { "name": "hireDate", "type": "date", "required": true, "description": "Date d'embauche" },
     { "name": "position", "type": "string", "description": "Poste occupé" },
-    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "defaultValue": "Active", "description": "Statut de l'employé" },
-    { "name": "salary", "type": "decimal", "validation": { "min": 0 }, "description": "Salaire mensuel" }
+    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "defaultValue": "Active", "description": "Statut de l'employé" }
+  ],
+  "versionedAttributes": [
+    { "entity": "Salary", "attributes": ["grossAmount", "netAmount", "effectiveDate", "currency"], "reason": "Historique salarial versionné" }
   ],
   "estimatedVolume": { "monthly": 50, "total2y": 1200 },
   "searchableFields": ["code", "position", "status"],
   "defaultFilters": ["status"],
   "relationships": [
     { "target": "Department", "type": "ManyToOne", "description": "Appartient à un département" },
-    { "target": "Contract", "type": "OneToMany", "description": "Possède plusieurs contrats" }
+    { "target": "Contract", "type": "OneToMany", "description": "Possède plusieurs contrats" },
+    { "target": "Salary", "type": "OneToMany", "description": "Historique de salaires versionnés" }
   ]
 }
 ```
 
+### B-bis. SmartStack Entity Convention Guards (MANDATORY)
+
+Before finalizing each entity, apply these rules:
+
+**B-bis-1. Person Extension Pattern** (ref: `entity-architecture-decision.md` section 0)
+IF the entity matches a person role (Employee, Customer, Manager, Consultant, etc.):
+- **DO NOT** add firstName, lastName, email, phoneNumber as direct attributes
+- **DO** add `userId` (type: `string`, FK to auth_Users — ASP.NET Identity uses string IDs)
+- **DO** add `personRoleConfig` metadata with variant (mandatory/optional)
+- Personal fields come from User, not from the domain entity
+
+**B-bis-2. Versioned Sensitive Data**
+IF the entity has attributes that change over time with audit requirements (salary, rate, grade):
+- **DO NOT** put them directly on the entity as single fields
+- **DO** extract into a versioned satellite table (e.g., Employee → Salary with effectiveDate)
+- Mark with `"versionedAttributes"` in entity spec
+
+**B-bis-3. SmartStack Socle Entities (NEVER redefine)**
+- Users/Identity → `auth_Users` (managed by SmartStack Identity)
+- Tenants → `tenant_Tenants` (managed by SmartStack Core)
+- Departments → `ref_Departments` or `rh_Departments` (check if exists in target DB)
+
+**B-bis-4. Foreign Key Conventions**
+- All FK attributes MUST end with `Id` suffix (e.g., `departmentId`, `userId`)
+- FK to Identity users MUST use type `string` (ASP.NET Identity convention, NOT guid)
+- FK to domain entities MUST use type `guid`
+
 ### C. Business Rules
 
 For each entity/process, identify rules. **Each rule MUST specify `sectionCode`** matching a code from `anticipatedSections[]`:
@@ -111,23 +174,39 @@ Exemple de règle de calcul :
 
 For each stakeholder action. **Each use case MUST specify `sectionCode`** matching a code from `anticipatedSections[]` — this links the UC to the screen/page where it happens:
 
+> **CANONICAL FORMAT (MANDATORY):** The usecases.json file MUST use these exact keys:
+> - Root key: `"useCases"` (camelCase, NOT "usecases")
+> - Actor field: `"primaryActor"` (NOT "actor")
+> - Steps field: `"mainScenario"` (string[], NOT "steps" with objects)
+> - Alternatives: `"alternativeScenarios"` (object[] with `{name, steps}`, NOT "alternative" as flat string)
+> - This matches specification-schema.json. Deviation causes normalization overhead in 4+ downstream skills.
+
 ```json
 {
-  "id": "UC-EMPLOYEES-001",
-  "name": "Créer un employé",
-  "sectionCode": "list",
-  "actor": "Responsable RH",
-  "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
-  "steps": [
-    "L'utilisateur ouvre la page de création",
-    "Il remplit les champs obligatoires (nom, département, date embauche)",
-    "Il valide le formulaire",
-    "Le système vérifie les règles métier (BR-VAL-EMPLOYEES-001)",
-    "Le système crée l'employé et affiche la fiche"
-  ],
-  "alternative": "Si les données sont invalides, le système affiche les erreurs",
-  "businessRules": ["BR-VAL-EMPLOYEES-001"],
-  "result": "L'employé est créé avec le statut 'Actif'"
+  "useCases": [
+    {
+      "id": "UC-EMPLOYEES-001",
+      "name": "Créer un employé",
+      "sectionCode": "list",
+      "primaryActor": "Responsable RH",
+      "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
+      "mainScenario": [
+        "L'utilisateur ouvre la page de création",
+        "Il remplit les champs obligatoires (nom, département, date embauche)",
+        "Il valide le formulaire",
+        "Le système vérifie les règles métier (BR-VAL-EMPLOYEES-001)",
+        "Le système crée l'employé et affiche la fiche"
+      ],
+      "alternativeScenarios": [
+        {
+          "name": "Données invalides",
+          "steps": ["Le système affiche les erreurs de validation", "L'utilisateur corrige et re-soumet"]
+        }
+      ],
+      "businessRules": ["BR-VAL-EMPLOYEES-001"],
+      "result": "L'employé est créé avec le statut 'Actif'"
+    }
+  ]
 }
 ```
 
@@ -250,6 +329,33 @@ for (const mod of modules) {
     for (const a of (e.attributes || [])) {
       if (!a.type) warnings.push(mod.code + ": entity " + e.name + " attr '" + a.name + "' missing type");
       if (a.type === 'enum' && !a.defaultValue) errors.push(mod.code + ": enum attr '" + a.name + "' missing defaultValue");
+      // FK naming convention: must end with "Id"
+      if ((a.type === 'guid' || a.type === 'string') && a.foreignKey && !a.name.endsWith('Id'))
+        warnings.push(mod.code + ": entity " + e.name + " FK attr '" + a.name + "' should end with 'Id'");
+    }
+    // Person Extension Pattern check
+    const personFields = ['firstName', 'lastName', 'email', 'phoneNumber', 'phone'];
+    const foundPersonFields = (e.attributes || []).filter(a => personFields.includes(a.name));
+    if (foundPersonFields.length >= 3 && !e.personRoleConfig) {
+      errors.push(mod.code + ": entity '" + e.name + "' has " + foundPersonFields.length +
+        " person fields (" + foundPersonFields.map(f => f.name).join(", ") +
+        ") but no personRoleConfig — use Person Extension Pattern (entity-architecture-decision.md section 0). " +
+        "Person fields (firstName, lastName, email) belong on auth_Users, not on the domain entity.");
+    }
+  }
+
+  // Canonical usecases key check
+  const rawUCFile = READ(mod.dir + '/usecases.json');
+  if (rawUCFile && !rawUCFile.useCases && rawUCFile.usecases) {
+    errors.push(mod.code + ": usecases.json uses 'usecases' key instead of canonical 'useCases' — fix before proceeding");
+  }
+  // Check steps serialization format
+  for (const uc of ucs) {
+    if (uc.steps && Array.isArray(uc.steps) && uc.steps.length > 0 && typeof uc.steps[0] === 'object') {
+      errors.push(mod.code + ": UC '" + uc.id + "' uses steps[] with objects — must use mainScenario[] with strings");
+    }
+    if (uc.actor && !uc.primaryActor) {
+      warnings.push(mod.code + ": UC '" + uc.id + "' uses 'actor' instead of canonical 'primaryActor'");
     }
   }
 

package/templates/skills/business-analyse-design/steps/step-01-screens.md

@@ -149,28 +149,65 @@ Map entity attribute types to UI component types:
 
 For each module, write via ba-writer:
 
+> **CANONICAL FORMAT (MANDATORY):** screens.json MUST use the `sections[]` wrapper format below.
+> Keys MUST be `sectionCode` and `sectionLabel` (not `id`/`displayName`/`code`/`label`).
+> Each section MUST have a `resources[]` array with typed resource objects (SmartTable, SmartForm, etc.).
+> The flat `screens[]` format (one object per screen with componentType at top level) is **DEPRECATED**.
+> All downstream consumers (business-analyse-html, business-analyse-handoff, business-analyse-develop) expect `sections[]`.
+
 ```json
 {
   "sections": [
     {
       "sectionCode": "list",
       "sectionLabel": "Liste des employes",
-      "resources": [ /* SmartTable, filters */ ]
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "label": "Grille des employes",
+          "columns": [ /* ... */ ],
+          "filters": [ /* ... */ ],
+          "actions": ["create", "export"],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
     },
     {
-      "sectionCode": "form",
+      "sectionCode": "detail",
       "sectionLabel": "Fiche employe",
-      "resources": [ /* SmartForm with tabs */ ]
+      "resources": [
+        {
+          "code": "employee-form",
+          "type": "SmartForm",
+          "label": "Fiche employe",
+          "tabs": [ /* ... */ ],
+          "actions": ["save", "cancel"],
+          "permission": "HumanResources.Employees.Update"
+        }
+      ]
     },
     {
       "sectionCode": "dashboard",
       "sectionLabel": "Tableau de bord",
-      "resources": [ /* SmartDashboard */ ]
+      "resources": [
+        {
+          "code": "employees-dashboard",
+          "type": "SmartDashboard",
+          "label": "Tableau de bord RH",
+          "kpis": [ /* ... */ ],
+          "charts": [ /* ... */ ],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
     }
   ]
 }
 ```
 
+> **Key naming:** Use `sectionCode` (not `id`, `code`). Use `sectionLabel` (not `displayName`, `label`).
+> Resource `type` must be one of: `SmartTable`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`, `SmartFilter`.
+
 Update `index.json` with screens.json hash and status.
 
 ## Validation

package/templates/skills/business-analyse-handoff/steps/step-01-transform.md

@@ -72,10 +72,19 @@ Transform module "{moduleCode}" for handoff.
 ## Instructions
 Read the following 5 files from {moduleDir}:
   1. entities.json → entities[]
-  2. usecases.json → useCases[]
-  3. rules.json → rules[]
+  2. usecases.json → useCases[] (canonical key: "useCases", fallback: "usecases")
+  3. rules.json → rules[] (canonical key: "rules", fallback: "businessRules")
   4. permissions.json → roles[], matrix[], permissionPaths[]
-  5. screens.json → screens[]
+  5. screens.json → sections[] (canonical key: "sections", fallback: "screens")
+
+### Normalization Safety Net (BACKWARD COMPAT)
+When reading flat files, prefer canonical keys but fall back to alternatives:
+  - useCases: `data.useCases || data.usecases || []`
+  - primaryActor: `uc.primaryActor || uc.actor`
+  - mainScenario: `uc.mainScenario || uc.steps` (if steps[] contains objects, extract `.action`)
+  - rules: `data.rules || data.businessRules || []`
+  - screens: `data.sections || data.screens` (if screens[] exists, treat each screen as a section with 1 resource)
+This safety net handles pre-4.52 BA outputs. It should become unnecessary once step-03-specify enforces canonical keys.
 
 Then build the handoff data following these rules:
 

package/templates/skills/business-analyse-html/html/ba-interactive.html

@@ -4663,16 +4663,43 @@ function renderSmartDashboardMockup(res) {
         { label: 'Taux', value: '80%' }
     ];
     kpis.forEach(function(kpi) {
-        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(kpi.value || '0') + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
+        var displayValue = kpiDisplayValue(kpi);
+        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(displayValue) + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
     });
     html += '</div>';
 
-    // Chart placeholder
-    html += '<div class="mock-chart-placeholder">Graphique</div>';
+    // Chart placeholders
+    var charts = res.charts || [{ label: 'Graphique' }];
+    charts.forEach(function(chart) {
+        html += '<div class="mock-chart-placeholder">' + escapeHtml(chart.label || chart.type || 'Graphique') + '</div>';
+    });
 
     return html;
 }
 
+function kpiDisplayValue(kpi) {
+    var v = kpi.value || '0';
+    // If value is already a simple display value (number, percentage), use it
+    if (/^\d[\d,.\s]*%?$/.test(v)) return v;
+    // Detect formula patterns and generate realistic sample values
+    if (v.indexOf('(') !== -1) {
+        var label = (kpi.label || '').toLowerCase();
+        var color = (kpi.color || '').toLowerCase();
+        // Percentage indicators
+        if (v.indexOf('ratio') !== -1 || v.indexOf('%') !== -1 || label.indexOf('taux') !== -1 || label.indexOf('rate') !== -1)
+            return '87.5%';
+        // Average
+        if (v.indexOf('avg') !== -1 || label.indexOf('moyen') !== -1 || label.indexOf('average') !== -1)
+            return '12.4';
+        // Sum (monetary or hours)
+        if (v.indexOf('sum') !== -1)
+            return label.indexOf('jour') !== -1 || label.indexOf('day') !== -1 ? '156' : '45,678';
+        // Count (default)
+        return '1,234';
+    }
+    return v;
+}
+
 /* ---------- SmartFilter ---------- */
 function renderSmartFilterMockup(res) {
     var options = res.options || [];

package/templates/skills/business-analyse-html/html/src/scripts/06-render-mockups.js

@@ -303,16 +303,43 @@ function renderSmartDashboardMockup(res) {
         { label: 'Taux', value: '80%' }
     ];
     kpis.forEach(function(kpi) {
-        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(kpi.value || '0') + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
+        var displayValue = kpiDisplayValue(kpi);
+        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(displayValue) + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
     });
     html += '</div>';
 
-    // Chart placeholder
-    html += '<div class="mock-chart-placeholder">Graphique</div>';
+    // Chart placeholders
+    var charts = res.charts || [{ label: 'Graphique' }];
+    charts.forEach(function(chart) {
+        html += '<div class="mock-chart-placeholder">' + escapeHtml(chart.label || chart.type || 'Graphique') + '</div>';
+    });
 
     return html;
 }
 
+function kpiDisplayValue(kpi) {
+    var v = kpi.value || '0';
+    // If value is already a simple display value (number, percentage), use it
+    if (/^\d[\d,.\s]*%?$/.test(v)) return v;
+    // Detect formula patterns and generate realistic sample values
+    if (v.indexOf('(') !== -1) {
+        var label = (kpi.label || '').toLowerCase();
+        var color = (kpi.color || '').toLowerCase();
+        // Percentage indicators
+        if (v.indexOf('ratio') !== -1 || v.indexOf('%') !== -1 || label.indexOf('taux') !== -1 || label.indexOf('rate') !== -1)
+            return '87.5%';
+        // Average
+        if (v.indexOf('avg') !== -1 || label.indexOf('moyen') !== -1 || label.indexOf('average') !== -1)
+            return '12.4';
+        // Sum (monetary or hours)
+        if (v.indexOf('sum') !== -1)
+            return label.indexOf('jour') !== -1 || label.indexOf('day') !== -1 ? '156' : '45,678';
+        // Count (default)
+        return '1,234';
+    }
+    return v;
+}
+
 /* ---------- SmartFilter ---------- */
 function renderSmartFilterMockup(res) {
     var options = res.options || [];

package/templates/skills/business-analyse-html/steps/step-02-build-data.md

@@ -192,6 +192,29 @@ function normalizeAction(a) {
   return a.code || a.id || a.label || a.actionCode || "";
 }
 
+// Helper: normalize a KPI — replace formula values with sample display values
+function normalizeKpi(k) {
+  if (typeof k !== 'object') return { label: String(k), value: "0" };
+  const label = k.label || k.displayName || "";
+  const rawValue = k.value || k.metric || "0";
+  let displayValue = rawValue;
+  // Detect formula patterns (e.g., count(...), sum(...), ratio(...), avg(...))
+  if (typeof rawValue === 'string' && rawValue.includes('(')) {
+    const lbl = label.toLowerCase();
+    if (rawValue.includes('ratio') || rawValue.includes('%') || lbl.includes('taux') || lbl.includes('rate'))
+      displayValue = "87.5%";
+    else if (rawValue.includes('avg') || lbl.includes('moyen') || lbl.includes('average'))
+      displayValue = "12.4";
+    else if (rawValue.includes('sum'))
+      displayValue = (lbl.includes('jour') || lbl.includes('day') || lbl.includes('heure') || lbl.includes('hour')) ? "156" : "45,678";
+    else
+      displayValue = "1,234";
+  }
+  // Also handle format hint from the KPI definition
+  if (k.format === 'percentage' && displayValue === rawValue) displayValue = "80%";
+  return { label: label, value: displayValue };
+}
+
 if (flatScr.length > 0) {
   // FORMAT A: flat screens[] array (ba-003 style)
   const bySec = {};
@@ -214,9 +237,7 @@ if (flatScr.length > 0) {
         fields: (t.fields || []).map(normalizeField)
       })),
       actions: (s.actions || []).map(normalizeAction),
-      kpis: (s.kpis || []).map(k => typeof k === 'object'
-        ? { label: k.label || k.displayName || "", value: k.value || k.metric || "0" }
-        : { label: String(k), value: "0" }),
+      kpis: (s.kpis || []).map(normalizeKpi),
       options: s.options || [],
       permission: s.permission || "",
       notes: s.description || s.sectionDescription || ""
@@ -224,39 +245,65 @@ if (flatScr.length > 0) {
   });
   screens = Object.values(bySec);
 } else if (sectionScr.length > 0) {
-  // FORMAT B: sections[] array (ba-004 style — id/displayName/layout convention)
-  // Each section IS a screen resource (columns, tabs, filters are ON the section itself)
-  const bySec = {};
-  sectionScr.forEach(sec => {
-    const secId = sec.id || sec.code || sec.sectionCode || "";
-    const secLabel = sec.displayName || sec.label || sec.sectionLabel || secId;
-    const componentType = sec.layout || sec.componentType || "unknown";
-    if (!bySec[secId]) bySec[secId] = {
-      sectionCode: secId,
-      sectionLabel: secLabel,
-      resources: []
-    };
-    bySec[secId].resources.push({
-      code: secId,
-      label: secLabel,
-      type: componentType,
-      columns: (sec.columns || []).map(normalizeColumn),
-      filters: (sec.filters || []).map(normalizeFilter),
-      fields: [],
-      tabs: (sec.tabs || []).map(t => ({
-        label: t.displayName || t.label || t.code || t.id || "",
-        fields: (t.fields || []).map(normalizeField)
-      })),
-      actions: (sec.actions || []).map(normalizeAction),
-      kpis: (sec.kpis || []).map(k => typeof k === 'object'
-        ? { label: k.displayName || k.label || "", value: k.format === "percentage" ? "80%" : "1,234" }
-        : { label: String(k), value: "0" }),
-      options: sec.options || [],
-      permission: (typeof sec.permissions === 'object' ? sec.permissions?.view : sec.permission) || "",
-      notes: sec.description || ""
+  // DETECT sub-format: canonical (resources[] inside sections) vs ba-004 (data on section itself)
+  const hasNestedResources = sectionScr.some(sec => (sec.resources || []).length > 0);
+
+  if (hasNestedResources) {
+    // FORMAT B-CANONICAL: sections[] with resources[] (ba-005+ style — sectionCode/sectionLabel/resources[])
+    // Resources have their own code/type/columns/tabs/kpis — iterate over them
+    screens = sectionScr.map(sec => ({
+      sectionCode: sec.sectionCode || sec.id || sec.code || "",
+      sectionLabel: sec.sectionLabel || sec.displayName || sec.label || sec.sectionCode || "",
+      resources: (sec.resources || []).map(res => ({
+        code: res.code || res.id || "",
+        label: res.label || res.displayName || res.code || "",
+        type: res.type || res.componentType || res.layout || "unknown",
+        columns: (res.columns || []).map(normalizeColumn),
+        filters: (res.filters || []).map(normalizeFilter),
+        fields: [],
+        tabs: (res.tabs || []).map(t => ({
+          label: t.label || t.displayName || t.code || t.id || "",
+          fields: (t.fields || []).map(normalizeField)
+        })),
+        actions: (res.actions || []).map(normalizeAction),
+        kpis: (res.kpis || []).map(normalizeKpi),
+        options: res.options || [],
+        permission: res.permission || "",
+        notes: res.notes || res.description || ""
+      }))
+    }));
+  } else {
+    // FORMAT B-LEGACY: sections[] without resources[] (ba-004 style — data directly on section)
+    const bySec = {};
+    sectionScr.forEach(sec => {
+      const secId = sec.id || sec.code || sec.sectionCode || "";
+      const secLabel = sec.displayName || sec.label || sec.sectionLabel || secId;
+      const componentType = sec.layout || sec.componentType || "unknown";
+      if (!bySec[secId]) bySec[secId] = {
+        sectionCode: secId,
+        sectionLabel: secLabel,
+        resources: []
+      };
+      bySec[secId].resources.push({
+        code: secId,
+        label: secLabel,
+        type: componentType,
+        columns: (sec.columns || []).map(normalizeColumn),
+        filters: (sec.filters || []).map(normalizeFilter),
+        fields: [],
+        tabs: (sec.tabs || []).map(t => ({
+          label: t.displayName || t.label || t.code || t.id || "",
+          fields: (t.fields || []).map(normalizeField)
+        })),
+        actions: (sec.actions || []).map(normalizeAction),
+        kpis: (sec.kpis || []).map(normalizeKpi),
+        options: sec.options || [],
+        permission: (typeof sec.permissions === 'object' ? sec.permissions?.view : sec.permission) || "",
+        notes: sec.description || ""
+      });
     });
-  });
-  screens = Object.values(bySec);
+    screens = Object.values(bySec);
+  }
 }
 moduleSpecs[moduleCode].screens = screens;
 ```