@atlashub/smartstack-cli 4.74.0 → 4.75.0

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

@@ -194,31 +194,36 @@ function renderSmartFormMockup(res) {
         html += '<div class="mock-form-tab-content' + (ti === 0 || isOnly ? ' active' : '') + '"';
         html += ' data-mockup="' + mockupId + '" data-tab="' + ti + '">';
 
-        var fields = tab.fields || [];
-        var rows = [];
-        for (var i = 0; i < fields.length; i += 2) {
-            rows.push(fields.slice(i, i + 2));
-        }
+        // Tab-level subtable: the entire tab is a subtable (type: "subtable", entity, columns)
+        if (tab.type === 'subtable') {
+            html += renderSubtableMockup(tab);
+        } else {
+            var fields = tab.fields || [];
+            var rows = [];
+            for (var i = 0; i < fields.length; i += 2) {
+                rows.push(fields.slice(i, i + 2));
+            }
 
-        rows.forEach(function(row) {
-            if (row.length === 1 && row[0].type === 'subtable') {
-                html += renderSubtableMockup(row[0]);
-            } else {
-                html += '<div class="mock-form-row">';
-                row.forEach(function(field) {
-                    html += '<div class="mock-form-group">';
-                    html += '<label class="mock-label">' + escapeHtml(field.label || field.field);
-                    if (field.required) html += ' <span style="color:var(--error);">*</span>';
-                    html += '</label>';
-                    html += renderFormFieldMockup(field);
+            rows.forEach(function(row) {
+                if (row.length === 1 && row[0].type === 'subtable') {
+                    html += renderSubtableMockup(row[0]);
+                } else {
+                    html += '<div class="mock-form-row">';
+                    row.forEach(function(field) {
+                        html += '<div class="mock-form-group">';
+                        html += '<label class="mock-label">' + escapeHtml(field.label || field.field);
+                        if (field.required) html += ' <span style="color:var(--error);">*</span>';
+                        html += '</label>';
+                        html += renderFormFieldMockup(field);
+                        html += '</div>';
+                    });
                     html += '</div>';
-                });
-                html += '</div>';
-            }
-        });
+                }
+            });
 
-        if (fields.length === 0) {
-            html += '<div style="padding:2rem;text-align:center;color:var(--text-muted);font-style:italic;">Contenu de l\'onglet &laquo; ' + escapeHtml(tab.label) + ' &raquo;</div>';
+            if (fields.length === 0) {
+                html += '<div style="padding:2rem;text-align:center;color:var(--text-muted);font-style:italic;">Contenu de l\'onglet &laquo; ' + escapeHtml(tab.label) + ' &raquo;</div>';
+            }
         }
 
         html += '</div>';
@@ -263,20 +268,39 @@ function renderSubtableMockup(field) {
 
 /* ---------- SmartCard ---------- */
 function renderSmartCardMockup(res) {
-    var columns = res.columns || res.fields || [];
+    var fields = res.fields || res.columns || [];
     var html = '<div class="mock-header"><span class="mock-title">' + escapeHtml(res.label || 'Cartes') + '</span></div>';
     html += '<div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;">';
 
     for (var i = 0; i < 4; i++) {
         html += '<div style="background:var(--bg-hover);border:1px solid var(--border);border-radius:8px;padding:1rem;">';
-        columns.forEach(function(col, ci) {
-            var label = col.label || col.field || col;
-            if (ci === 0) {
+        // Title/Subtitle pattern (SmartCard with title + subtitle + fields + actions)
+        if (res.title) {
+            html += '<div style="font-weight:600;color:var(--text-bright);margin-bottom:0.25rem;">' + escapeHtml(res.title) + ' #' + (i + 1) + '</div>';
+        }
+        if (res.subtitle) {
+            html += '<div style="font-size:0.8rem;color:var(--accent);margin-bottom:0.5rem;">' + escapeHtml(res.subtitle) + '</div>';
+        }
+        // Fields
+        fields.forEach(function(col, ci) {
+            var label = col.label || col.field || (typeof col === 'string' ? col : '');
+            var iconMap = { calendar: '&#128197; ', 'dollar-sign': '&#128176; ', 'alert-circle': '&#9888; ', mail: '&#9993; ', building: '&#127970; ', user: '&#128100; ' };
+            var icon = col.icon ? (iconMap[col.icon] || '&#9679; ') : '';
+            if (!res.title && ci === 0) {
                 html += '<div style="font-weight:600;color:var(--text-bright);margin-bottom:0.5rem;">' + escapeHtml(label) + ' #' + (i + 1) + '</div>';
             } else {
-                html += '<div style="font-size:0.8rem;color:var(--text-muted);margin-bottom:0.25rem;">' + escapeHtml(label) + ': <span style="color:var(--text);">valeur</span></div>';
+                html += '<div style="font-size:0.8rem;color:var(--text-muted);margin-bottom:0.25rem;">' + icon + escapeHtml(label) + ': <span style="color:var(--text);">valeur</span></div>';
             }
         });
+        // Actions
+        if (res.actions && res.actions.length > 0) {
+            html += '<div style="margin-top:0.75rem;display:flex;gap:0.4rem;">';
+            res.actions.forEach(function(a) {
+                var actionLabel = typeof a === 'string' ? a.replace(/-/g, ' ') : (a.label || a.action || '');
+                html += '<span class="mock-btn" style="font-size:0.75rem;">' + escapeHtml(actionLabel) + '</span>';
+            });
+            html += '</div>';
+        }
         html += '</div>';
     }
     html += '</div>';
@@ -285,7 +309,7 @@ function renderSmartCardMockup(res) {
 
 /* ---------- SmartKanban ---------- */
 function renderSmartKanbanMockup(res) {
-    var options = res.options || res.columns || ['À faire', 'En cours', 'Terminé'];
+    var options = (res.options && res.options.length > 0) ? res.options : (res.columns && res.columns.length > 0) ? res.columns : ['À faire', 'En cours', 'Terminé'];
     var html = '<div class="mock-header"><span class="mock-title">' + escapeHtml(res.label || 'Kanban') + '</span></div>';
     html += '<div style="display:flex;gap:1rem;overflow-x:auto;padding-bottom:0.5rem;">';
 
@@ -359,11 +383,42 @@ function kpiDisplayValue(kpi) {
 
 /* ---------- SmartFilter ---------- */
 function renderSmartFilterMockup(res) {
-    var options = res.options || [];
-    var html = '<div style="display:flex;gap:0.4rem;flex-wrap:wrap;padding:0.5rem 0;">';
-    html += '<span style="padding:0.3rem 0.7rem;border-radius:16px;font-size:0.8rem;background:var(--primary);color:#fff;cursor:pointer;">Tous</span>';
-    options.forEach(function(opt) {
-        html += '<span style="padding:0.3rem 0.7rem;border-radius:16px;font-size:0.8rem;background:var(--bg-hover);color:var(--text);border:1px solid var(--border);cursor:pointer;">' + escapeHtml(opt) + '</span>';
+    var filters = res.filters || [];
+    if (filters.length === 0) {
+        // Fallback: legacy options[] format (tag pills)
+        var options = res.options || [];
+        if (options.length === 0) return '<div style="padding:1rem;text-align:center;color:var(--text-muted);">Aucun filtre défini</div>';
+        var html = '<div style="display:flex;gap:0.4rem;flex-wrap:wrap;padding:0.5rem 0;">';
+        html += '<span style="padding:0.3rem 0.7rem;border-radius:16px;font-size:0.8rem;background:var(--primary);color:#fff;cursor:pointer;">Tous</span>';
+        options.forEach(function(opt) {
+            html += '<span style="padding:0.3rem 0.7rem;border-radius:16px;font-size:0.8rem;background:var(--bg-hover);color:var(--text);border:1px solid var(--border);cursor:pointer;">' + escapeHtml(typeof opt === 'string' ? opt : opt.label || '') + '</span>';
+        });
+        html += '</div>';
+        return html;
+    }
+
+    // Rich filter bar: render each filter based on its type
+    var html = '<div style="display:flex;gap:0.5rem;flex-wrap:wrap;align-items:flex-end;padding:0.5rem 0;">';
+    filters.forEach(function(f) {
+        var label = typeof f === 'string' ? f : (f.label || f.field || '');
+        var type = typeof f === 'string' ? 'text' : (f.type || 'text');
+        html += '<div style="display:flex;flex-direction:column;gap:0.2rem;">';
+        html += '<span style="font-size:0.7rem;color:var(--text-muted);">' + escapeHtml(label) + '</span>';
+        switch (type) {
+            case 'select':
+                var opts = f.options || ['Option 1', 'Option 2'];
+                html += '<span class="mock-input" style="width:auto;min-width:130px;font-size:0.8rem;color:var(--text-muted);">' + escapeHtml(opts[0]) + ' &#9662;</span>';
+                break;
+            case 'lookup':
+                html += '<span class="mock-input" style="width:auto;min-width:130px;font-size:0.8rem;color:var(--accent);">' + escapeHtml(f.entity || label) + ' &#128269;</span>';
+                break;
+            case 'daterange':
+                html += '<span class="mock-input" style="width:auto;min-width:180px;font-size:0.8rem;color:var(--text-muted);">01/01/2025 — 31/12/2025 &#128197;</span>';
+                break;
+            default:
+                html += '<span class="mock-input" style="width:auto;min-width:160px;font-size:0.8rem;color:var(--text-muted);">Rechercher... &#128269;</span>';
+        }
+        html += '</div>';
     });
     html += '</div>';
     return html;

package/templates/skills/business-analyse-html/html/src/scripts/12-render-diagrams.js

@@ -0,0 +1,116 @@
+/* ==========================================
+   MERMAID DIAGRAM RENDERING
+   Renders ERD, state machines, and sequence diagrams
+   from consolidation.mermaidDiagrams data.
+   ========================================== */
+
+function renderMermaidDiagrams() {
+    const data = window.FEATURE_DATA;
+    if (!data) return;
+
+    const diagrams = data.consolidation?.mermaidDiagrams;
+    if (!diagrams) return;
+
+    // 1. ERD in consol-datamodel (prepend before entity cards)
+    if (diagrams.erd) {
+        const erdContainer = document.getElementById('dataModelContainer');
+        if (erdContainer) {
+            const erdDiv = document.createElement('div');
+            erdDiv.className = 'diagram-container diagram-erd';
+            erdDiv.innerHTML =
+                '<div class="diagram-section-header">Diagramme Entit\u00e9-Relation (ERD)</div>' +
+                '<div class="mermaid">' + escapeHtml(diagrams.erd) + '</div>';
+            erdContainer.insertBefore(erdDiv, erdContainer.firstChild);
+        }
+    }
+
+    // 2. State machine diagrams — inject in module spec sections or consol-datamodel
+    if (diagrams.stateMachines && Object.keys(diagrams.stateMachines).length > 0) {
+        const smContainer = document.getElementById('dataModelContainer');
+        if (smContainer) {
+            const smSection = document.createElement('div');
+            smSection.innerHTML = '<div class="diagram-section-header">Cycles de vie (State Machines)</div>';
+
+            Object.entries(diagrams.stateMachines).forEach(function(entry) {
+                var entity = entry[0];
+                var def = entry[1];
+                var smDiv = document.createElement('div');
+                smDiv.className = 'diagram-container diagram-state-machine';
+                smDiv.innerHTML =
+                    '<h4>' + escapeHtml(entity) + '</h4>' +
+                    '<div class="mermaid">' + escapeHtml(def) + '</div>';
+                smSection.appendChild(smDiv);
+            });
+
+            smContainer.appendChild(smSection);
+        }
+    }
+
+    // 3. Sequence diagrams in consol-flows
+    if (diagrams.sequences && Object.keys(diagrams.sequences).length > 0) {
+        var flowsContainer = document.getElementById('consolFlowsContainer');
+        // Fallback: try the consol-flows section
+        if (!flowsContainer) {
+            var consolFlows = document.getElementById('consol-flows');
+            if (consolFlows) {
+                flowsContainer = consolFlows.querySelector('.section-body') || consolFlows;
+            }
+        }
+
+        if (flowsContainer) {
+            var seqSection = document.createElement('div');
+            seqSection.innerHTML = '<div class="diagram-section-header">Diagrammes de s\u00e9quence</div>';
+
+            Object.entries(diagrams.sequences).forEach(function(entry) {
+                var flowName = entry[0];
+                var def = entry[1];
+                var seqDiv = document.createElement('div');
+                seqDiv.className = 'diagram-container diagram-sequence';
+                seqDiv.innerHTML =
+                    '<h4>' + escapeHtml(flowName) + '</h4>' +
+                    '<div class="mermaid">' + escapeHtml(def) + '</div>';
+                seqSection.appendChild(seqDiv);
+            });
+
+            flowsContainer.appendChild(seqSection);
+        }
+    }
+
+    // 4. Render all mermaid elements
+    try {
+        if (typeof mermaid !== 'undefined' && mermaid.run) {
+            mermaid.run({ querySelector: '.mermaid' });
+        }
+    } catch (e) {
+        console.warn('Mermaid rendering failed:', e);
+        // Fallback: show raw text
+        document.querySelectorAll('.mermaid').forEach(function(el) {
+            if (!el.querySelector('svg')) {
+                el.style.whiteSpace = 'pre-wrap';
+                el.style.fontFamily = 'monospace';
+                el.style.fontSize = '0.85rem';
+                el.style.color = 'var(--text-muted)';
+            }
+        });
+    }
+}
+
+// Escape HTML for safe injection
+function escapeHtml(text) {
+    if (!text) return '';
+    // For mermaid content, we need to preserve the syntax
+    // Only escape actual HTML tags, not mermaid arrows
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Auto-run after consolidation rendering
+(function() {
+    // Wait for DOM and other render functions to complete
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function() {
+            setTimeout(renderMermaidDiagrams, 500);
+        });
+    } else {
+        setTimeout(renderMermaidDiagrams, 500);
+    }
+})();

package/templates/skills/business-analyse-html/html/src/styles/10-diagrams.css

@@ -0,0 +1,73 @@
+/* ==========================================
+   MERMAID DIAGRAMS
+   ========================================== */
+
+.diagram-container {
+    margin: 1.5rem 0;
+    padding: 1rem;
+    background: var(--bg-card);
+    border-radius: 8px;
+    border: 1px solid var(--border);
+    overflow-x: auto;
+}
+
+.diagram-container h3,
+.diagram-container h4 {
+    color: var(--text-bright);
+    margin-bottom: 1rem;
+    font-size: 1.1rem;
+}
+
+.diagram-container .mermaid {
+    display: flex;
+    justify-content: center;
+    min-height: 200px;
+}
+
+.diagram-container .mermaid svg {
+    max-width: 100%;
+    height: auto;
+}
+
+/* ERD specific */
+.diagram-erd {
+    margin-bottom: 2rem;
+    border-left: 3px solid var(--primary);
+}
+
+/* State machine specific */
+.diagram-state-machine {
+    border-left: 3px solid var(--accent);
+}
+
+/* Sequence diagram specific */
+.diagram-sequence {
+    border-left: 3px solid var(--success);
+}
+
+/* Diagram section header */
+.diagram-section-header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 1rem;
+    color: var(--text-bright);
+    font-size: 1.2rem;
+    font-weight: 600;
+}
+
+.diagram-section-header::before {
+    content: '';
+    width: 4px;
+    height: 1.2em;
+    background: var(--primary);
+    border-radius: 2px;
+}
+
+/* No diagrams fallback */
+.diagram-empty {
+    color: var(--text-muted);
+    font-style: italic;
+    padding: 1rem;
+    text-align: center;
+}

package/templates/skills/business-analyse-html/html/src/template.html

@@ -4,6 +4,8 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>{{APPLICATION_NAME}} - Analyse métier</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+    <script>mermaid.initialize({ startOnLoad: false, theme: 'dark', securityLevel: 'loose' });</script>
     <style>
 <!-- CSS_PLACEHOLDER -->
     </style>

package/templates/skills/business-analyse-html/references/02-embedded-artifacts-building.md

@@ -0,0 +1,144 @@
+# Reference: EMBEDDED_ARTIFACTS Building Details
+
+## wireframes{} — per moduleCode
+
+### Architecture: Flat File + Nested Structures
+
+**FLAT-FILE:** Wireframes come from `screens.json` in each module directory (collected in step-01),
+NOT from `moduleFeature.specification.uiWireframes`.
+
+### STEP 1: Collect wireframe sources from BOTH flat and nested structures
+
+```javascript
+const mod = collected_data.modules[moduleCode];
+
+// Flat: mod.screens.screens[] with mockupFormat/mockup at top level
+// Nested: mod.screens.sections[].resources[].wireframe (design step output)
+let rawWireframes = [];
+
+// Source A: flat screens[] array (original BA output or manually enriched)
+const flatScreens = mod.screens?.screens || [];
+rawWireframes.push(...flatScreens.filter(s => s.mockup || s.mockupFormat));
+
+// Source B: nested sections[].resources[].wireframe (design step output)
+const sections = mod.screens?.sections || [];
+for (const section of sections) {
+  // B1: wireframe directly on section (ba-004 style: sections[].wireframe)
+  if (section.wireframe) {
+    rawWireframes.push({
+      ...section.wireframe,
+      section: section.wireframe.section || section.id || section.code || section.sectionCode || "",
+      screen: section.wireframe.screen || section.id || section.code || section.sectionCode || ""
+    });
+  }
+  // B2: wireframe on resources (nested: sections[].resources[].wireframe)
+  for (const resource of (section.resources || [])) {
+    if (resource.wireframe) {
+      rawWireframes.push({
+        ...resource.wireframe,
+        section: resource.wireframe.section || section.sectionCode || section.id || "",
+        screen: resource.wireframe.screen || `${section.sectionCode || section.id}-${resource.code}` || ""
+      });
+    }
+  }
+}
+
+// Source C: screens/sections without mockup → auto-generate text description as wireframe fallback
+// C1: from flat screens[]
+const screensWithoutMockup = flatScreens.filter(s => !s.mockup && !s.mockupFormat);
+// C2: from sections[] (ba-004 style) — sections without wireframe property
+const sectionsWithoutWireframe = sections.filter(s => !s.wireframe);
+const allNoMockup = [
+  ...screensWithoutMockup.map(s => ({
+    type: s.componentType || "", columns: s.columns || [], tabs: s.tabs || [],
+    kpis: s.kpis || [], screen: s.screen || "", section: s.section || "",
+    description: s.sectionDescription || ""
+  })),
+  ...sectionsWithoutWireframe.map(s => ({
+    type: s.layout || s.componentType || "", columns: s.columns || [], tabs: s.tabs || [],
+    kpis: s.kpis || [], screen: s.id || s.code || "", section: s.id || s.code || "",
+    description: s.description || ""
+  }))
+];
+for (const screen of allNoMockup) {
+  const type = screen.type;
+  let desc = "";
+  if (type.includes("Table") || type.includes("Grid")) {
+    const cols = screen.columns;
+    desc = "Tableau avec " + cols.length + " colonnes : " + cols.map(c => c.label || c.displayName || c.code || c.name).join(", ");
+  } else if (type.includes("Form")) {
+    const tabs = screen.tabs;
+    desc = "Formulaire " + (tabs.length > 0 ? "avec " + tabs.length + " onglet(s)" : "");
+  } else if (type.includes("Dashboard")) {
+    desc = "Tableau de bord avec " + (screen.kpis.length || "") + " KPIs";
+  } else if (type.includes("Kanban")) {
+    desc = "Vue Kanban";
+  }
+  if (desc) {
+    rawWireframes.push({
+      screen: screen.screen, section: screen.section,
+      mockupFormat: "text", mockup: desc,
+      description: screen.description, elements: [], componentMapping: []
+    });
+  }
+}
+```
+
+### STEP 2: Map to HTML format (RENAME: mockupFormat → format, mockup → content)
+
+**FIELD RENAME WARNING:** Module JSON uses `mockupFormat`/`mockup`. HTML reads `format`/`content`. You MUST rename.
+
+```javascript
+wireframes: {
+  [moduleCode]: rawWireframes.map(wf => ({
+      screen: wf.screen || wf.name || wf.title || wf.id || "",
+      section: wf.section || "",
+      format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
+      content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
+      svgContent: null,
+      description: wf.description || "",
+      elements: wf.elements || [],
+      actions: wf.actions || [],
+      componentMapping: Array.isArray(wf.componentMapping)
+        ? wf.componentMapping.map(function(entry) {
+            if (entry.wireframeElement && entry.reactComponent) return entry; // canonical
+            // Shorthand: [{key: value}] → {wireframeElement, reactComponent}
+            var keys = Object.keys(entry);
+            if (keys.length === 1 && !entry.wireframeElement) {
+              return { wireframeElement: keys[0], reactComponent: entry[keys[0]] };
+            }
+            return entry;
+          })
+        : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
+          ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
+          : [],
+      layout: typeof wf.layout === 'object' ? wf.layout : null,
+      permissionsRequired: wf.permissionsRequired || []
+    }))
+}
+```
+
+## e2eFlows[]
+
+```javascript
+e2eFlows: (master.consolidation?.e2eFlows || []).map(flow => ({
+  name: flow.name,
+  diagram: flow.steps.map(s => s.action + "(" + s.module + ")").join(" ──→ "),
+  steps: flow.steps || [],
+  actors: [...new Set(flow.steps.map(s => s.permission?.split(".")[0]).filter(Boolean))].join(", "),
+  modules: [...new Set(flow.steps.map(s => s.module))].join(" → ")
+}))
+```
+
+## dependencyGraph
+
+```javascript
+dependencyGraph: {
+  nodes: (master.modules || []).map(m => ({
+    id: m.code, label: m.code, type: m.featureType || "data-centric"
+  })),
+  edges: (master.dependencyGraph?.edges || []).map(e => ({
+    from: e.from, to: e.to, description: e.description || ""
+  }))
+}
+```

package/templates/skills/business-analyse-html/references/02-feature-data-building.md

@@ -0,0 +1,141 @@
+# Reference: FEATURE_DATA Building Details
+
+## moduleSpecs{} — ONE entry per module (CRITICAL)
+
+### Architecture: Flat File Data Collection
+
+**FLAT-FILE ARCHITECTURE:** Module data comes from separate JSON files collected in step-01,
+NOT from index.json fields. Use `collected_data.modules[moduleCode].entities`, `.usecases`, etc.
+
+For EACH module, use the flat file data from `collected_data.modules[moduleCode]`:
+
+```javascript
+const mod = collected_data.modules[moduleCode];
+
+// NORMALIZE: usecases.json may use "useCases" (camelCase) or "usecases" (lowercase)
+const rawUCs = mod.usecases?.useCases || mod.usecases?.usecases || [];
+// NORMALIZE: rules.json may use "rules" or "businessRules"
+const rawBRs = mod.rules?.rules || mod.rules?.businessRules || [];
+
+moduleSpecs[moduleCode] = {
+  useCases: rawUCs.map(uc => ({
+    name: uc.name || uc.title || uc.id || "",
+    sectionCode: uc.sectionCode || "",
+    actor: uc.primaryActor || uc.actor || "",
+    // SAFETY NET: steps may be strings[] (mainScenario) or objects[] ({step, action})
+    steps: (uc.mainScenario || uc.steps || []).map(s =>
+      typeof s === 'string' ? s : (s.action || s.description || "")
+    ).join("\n"),
+    alternative: (uc.alternativeScenarios || uc.alternativeFlows || []).map(a =>
+      (a.name || a.trigger || "") + ": " + (a.steps || a.actions || []).map(s =>
+        typeof s === 'string' ? s : (s.action || s.description || "")
+      ).join(", ")
+    ).join("\n")
+  })),
+  businessRules: rawBRs.map(br => ({
+    name: br.name || br.id || "",
+    sectionCode: br.sectionCode || "",
+    category: br.category || "",
+    statement: br.statement || br.description || "",
+    example: (br.examples || []).map(e =>
+      typeof e === 'string' ? e : ((e.input || "") + " → " + (e.expected || ""))
+    ).join("; ")
+  })),
+  // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated
+  entities: (mod.entities?.entities || []).map(ent => ({
+    name: ent.name,
+    description: ent.description || "",
+    attributes: (ent.attributes || []).length > 0
+      ? ent.attributes.map(a => ({ name: a.name, type: a.type || "string", required: a.required || false, description: a.description || "" }))
+      : (ent.fields || []).map(f => ({ name: f.name, type: f.type || "string", required: f.required || false, description: f.description || "" })),
+    relationships: (ent.relationships || []).map(r =>
+      typeof r === 'string' ? r : r.target + " (" + r.type + ") - " + (r.description || ""))
+  })),
+  permissions: buildPermissionKeys(mod.permissions),
+  apiEndpoints: mod.usecases?.apiEndpoints || []
+}
+```
+
+### Building screens[] for HTML Interactive Mockups
+
+```javascript
+// BUILD screens[] for HTML interactive mockups — use helpers and format detection from references
+const flatScr = mod.screens?.screens || [];
+const sectionScr = mod.screens?.sections || [];
+let screens = [];
+
+// Apply normalization helpers from references/02-normalization-helpers.md
+// Apply format detection from references/02-screen-format-detection.md
+
+moduleSpecs[moduleCode].screens = screens;
+```
+
+### Enrich anticipatedSections with section-level UC/BR
+
+**CRITICAL for HTML viewer to display UC/BR grouped by section.**
+
+Execute AFTER moduleSpecs is built:
+
+```javascript
+// Post-processing: populate each section's useCases[] and businessRules[]
+// using the sectionCode field from moduleSpecs
+FEATURE_DATA.modules.forEach(m => {
+  const spec = FEATURE_DATA.moduleSpecs[m.code];
+  if (!spec) return;
+  (m.anticipatedSections || []).forEach(section => {
+    section.useCases = (spec.useCases || []).filter(uc => uc.sectionCode === section.code);
+    section.businessRules = (spec.businessRules || []).filter(br => br.sectionCode === section.code);
+  });
+});
+```
+
+## Top-Level Fields: dependencies, consolidation, handoff
+
+### dependencies[] (TOP-LEVEL — CRITICAL for HTML navigation)
+
+```javascript
+dependencies: (master.consolidation?.crossModuleInteractions || master.dependencyGraph?.edges || []).map(i => ({
+  from: i.fromModule || i.from || "",
+  to: i.toModule || i.to || "",
+  description: i.description || ""
+}))
+```
+
+**WARNING:** `data.dependencies` is used by the sidebar (navigation), module rendering, consolidation views,
+handoff summary, and export. If this array is missing, the entire HTML page crashes with a TypeError.
+ALWAYS include it, even if empty (`dependencies: []`).
+
+### consolidation
+
+```javascript
+consolidation: {
+  interactions: (master.consolidation?.crossModuleInteractions || []).map(i => ({
+    from: i.fromModule,
+    to: i.toModule,
+    description: i.description || ""
+  })),
+  sharedEntities: master.consolidation?.sharedEntities || [],
+  e2eFlows: (master.consolidation?.e2eFlows || []).map(f => ({
+    name: f.name,
+    steps: (f.steps || []).map(s => ({ module: s.module, action: s.action })),
+    actors: (f.steps || []).map(s => s.permission).join(", ")
+  }))
+}
+```
+
+### handoff
+
+```javascript
+handoff: {
+  complexity: master.handoff?.complexity,
+  implementationStrategy: master.handoff?.implementationStrategy,
+  moduleOrder: master.handoff?.moduleOrder,
+  filesToCreate: master.handoff?.filesToCreate,
+  brToCodeMapping: master.handoff?.brToCodeMapping,
+  apiEndpointSummary: master.handoff?.apiEndpointSummary
+}
+```
+
+## Helper Function: buildPermissionKeys()
+
+See `references/data-mapping.md` for `buildPermissionKeys()` implementation.