@atlashub/smartstack-cli 4.47.0 → 4.49.0

package/templates/skills/business-analyse-handoff/references/acceptance-criteria.md

@@ -51,6 +51,12 @@ These verify data that `/business-analyse-handoff` step-01 generates:
 | AC-09 | BR-to-code mapping present | 1 | `handoff.brToCodeMapping[]` | YES |
 | AC-10 | API endpoint summary present | 1 | `handoff.apiEndpointSummary[]` | YES |
 | AC-11 | SeedData entries have category | ALL | `handoff.filesToCreate.seedData[].category` | YES |
+| AC-12 | `specificationFiles` present with 5 paths | 5 | `handoff.specificationFiles` | YES |
+| AC-13 | Companion entities file exists and count matches source | match | `.ralph/prd-{module}.entities.json` | YES |
+| AC-14 | Companion rules file exists and count matches source | match | `.ralph/prd-{module}.rules.json` | YES |
+| AC-15 | Companion usecases file exists and count matches source | match | `.ralph/prd-{module}.usecases.json` | YES |
+| AC-16 | Companion screens file exists (if screens.json exists) | exists | `.ralph/prd-{module}.screens.json` | YES |
+| AC-17 | Each `brToCodeMapping[].statement` non-empty | ALL | `handoff.brToCodeMapping[].statement` | YES |
 
 ---
 
@@ -240,11 +246,51 @@ if (noCat.length > 0) {
   console.error('FAIL: AC-11: ' + noCat.length + ' seedData entries missing category field');
 }
 
+// AC-12: specificationFiles present with 5 paths
+const specFiles = handoff.specificationFiles || {};
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+const missingSpecs = specKeys.filter(k => !specFiles[k]);
+if (missingSpecs.length > 0) {
+  fails.push('AC-12: specificationFiles missing keys: ' + missingSpecs.join(', '));
+  console.error('FAIL: AC-12: specificationFiles missing keys: ' + missingSpecs.join(', '));
+}
+
+// AC-13 to AC-16: Companion files exist and counts match
+const ralphDir = path.dirname(process.argv[1]);
+const companionChecks = [
+  { ac: 'AC-13', key: 'entities', arrayKey: 'entities' },
+  { ac: 'AC-14', key: 'rules', arrayKey: 'rules' },
+  { ac: 'AC-15', key: 'usecases', arrayKey: 'useCases' },
+  { ac: 'AC-16', key: 'screens', arrayKey: 'screens' }
+];
+for (const check of companionChecks) {
+  const companionPath = specFiles[check.key] ? path.join(ralphDir, specFiles[check.key]) : null;
+  if (companionPath && fs.existsSync(companionPath)) {
+    const companionData = JSON.parse(fs.readFileSync(companionPath, 'utf-8'));
+    const arr = companionData[check.arrayKey] || companionData[check.arrayKey.toLowerCase()] || [];
+    if (arr.length === 0 && check.ac !== 'AC-16') {
+      fails.push(check.ac + ': companion ' + check.key + ' file is empty');
+      console.error('FAIL: ' + check.ac + ': companion ' + check.key + ' file has 0 entries');
+    }
+  } else if (companionPath) {
+    fails.push(check.ac + ': companion file missing: ' + specFiles[check.key]);
+    console.error('FAIL: ' + check.ac + ': companion file not found: ' + specFiles[check.key]);
+  }
+}
+
+// AC-17: Each brToCodeMapping[].statement non-empty
+const brMapping = handoff.brToCodeMapping || [];
+const emptyStatements = brMapping.filter(br => !br.statement || br.statement.trim() === '');
+if (emptyStatements.length > 0) {
+  fails.push('AC-17: ' + emptyStatements.length + ' BRs with empty statement');
+  console.error('FAIL: AC-17: ' + emptyStatements.length + ' brToCodeMapping entries have empty statement: ' + emptyStatements.slice(0, 3).map(b => b.ruleId).join(', '));
+}
+
 if (fails.length > 0) {
   console.error('\\nBLOCKING: ' + fails.length + ' output acceptance criteria FAILED');
   process.exit(1);
 }
-console.log('PASS: All output acceptance criteria met (AC-08 to AC-11)');
+console.log('PASS: All output acceptance criteria met (AC-08 to AC-17)');
 " "$MODULE_JSON"
 ```
 
@@ -264,3 +310,9 @@ console.log('PASS: All output acceptance criteria met (AC-08 to AC-11)');
 | AC-09 | Re-run `/business-analyse-handoff` step-01 transform (BR mapping) |
 | AC-10 | Re-run `/business-analyse-handoff` step-01 transform (API endpoints) |
 | AC-11 | Re-run `/business-analyse-handoff` step-01 transform (seedData categories) |
+| AC-12 | Re-run `/business-analyse-handoff` step-01 transform (specificationFiles missing) |
+| AC-13 | Re-run `/business-analyse-handoff` step-01 transform (entities companion missing/empty) |
+| AC-14 | Re-run `/business-analyse-handoff` step-01 transform (rules companion missing/empty) |
+| AC-15 | Re-run `/business-analyse-handoff` step-01 transform (usecases companion missing/empty) |
+| AC-16 | Re-run `/business-analyse-handoff` step-01 transform (screens companion missing) |
+| AC-17 | Re-run `/business-analyse-handoff` step-01 transform (BR statements empty — copy from rules.json) |

package/templates/skills/business-analyse-handoff/references/handoff-file-templates.md

@@ -153,3 +153,45 @@ From `screens.json > screens[]` and `usecases.json > useCases[]`:
 
 Include: Technical documentation data, API specification files, user guides.
 This category can be an empty array `[]` if no documentation is planned at this stage. It will be populated by the `/documentation` skill after `/business-analyse-develop` completes.
+
+## 4.9 Specification Files (Companion Files)
+
+> **Purpose:** Enable `/apex` and `/business-analyse-develop` to load full BA specifications per layer, avoiding monolithic context loading.
+
+Each PRD MUST include a `specificationFiles` object referencing 5 companion files:
+
+```json
+"specificationFiles": {
+  "entities": "prd-{moduleCode}.entities.json",
+  "rules": "prd-{moduleCode}.rules.json",
+  "usecases": "prd-{moduleCode}.usecases.json",
+  "screens": "prd-{moduleCode}.screens.json",
+  "permissions": "prd-{moduleCode}.permissions.json"
+}
+```
+
+### Naming Convention
+
+`prd-{moduleCode}.{section}.json` — all files colocated in `.ralph/` alongside the PRD.
+
+| File | Source | Content |
+|------|--------|---------|
+| `prd-{moduleCode}.entities.json` | `{moduleDir}/entities.json` | VERBATIM copy |
+| `prd-{moduleCode}.rules.json` | `{moduleDir}/rules.json` | VERBATIM copy |
+| `prd-{moduleCode}.usecases.json` | `{moduleDir}/usecases.json` | VERBATIM copy |
+| `prd-{moduleCode}.screens.json` | `{moduleDir}/screens.json` | VERBATIM copy |
+| `prd-{moduleCode}.permissions.json` | `{moduleDir}/permissions.json` | VERBATIM copy |
+
+### Rules
+
+- **VERBATIM copy:** Each companion file is a 1:1 copy of the BA source file. Zero transformation, zero filtering.
+- **Colocated:** All companion files live in `.ralph/` alongside the PRD file.
+- **Mandatory:** All 5 companion files MUST be generated for every module PRD.
+- **Layer loading:** `/apex` loads only the companion files needed per layer (see loading plan below).
+
+| Layer | Files loaded | Estimated context |
+|-------|-------------|-------------------|
+| Layer 0 (domain) | `entities.json` | ~200-400 lines |
+| Layer 1 (seed) | `entities.json` + `permissions.json` | ~300-500 lines |
+| Layer 2 (backend) | `rules.json` + `usecases.json` | ~300-600 lines |
+| Layer 3 (frontend) | `screens.json` + `usecases.json` | ~300-500 lines |

package/templates/skills/business-analyse-handoff/references/handoff-mappings.md

@@ -12,6 +12,13 @@ Generate complete mapping for each BR:
     {
       "ruleId": "BR-VAL-001",
       "title": "Order total must equal sum of item prices",
+      "statement": "The order total amount must equal the sum of all order item prices multiplied by their quantities",
+      "example": "Order with 3 items at $10, $20, $30 → total must be $60. If total = $50 → validation error",
+      "formula": null,
+      "conditions": [],
+      "entities": ["Order", "OrderItem"],
+      "category": "validation",
+      "sectionCode": "orders",
       "module": "{moduleCode}",
       "severity": "critical",
       "implementationPoints": [
@@ -27,7 +34,14 @@ Generate complete mapping for each BR:
 
 For each BR include:
 - **ruleId**: Reference to `rules.json > rules[].id`
-- **title**: The rule statement
+- **title**: Short descriptive title
+- **statement**: VERBATIM copy of `rules.json > rules[].statement` — the full rule text, NOT a paraphrase
+- **example**: VERBATIM copy of `rules.json > rules[].example` — concrete example illustrating the rule (null if absent)
+- **formula**: VERBATIM copy of `rules.json > rules[].formula` — formula for BR-CALC-* rules (null if absent)
+- **conditions**: VERBATIM copy of `rules.json > rules[].conditions[]` — conditions of applicability (empty array if absent)
+- **entities**: Array of entity names this rule applies to (from `rules.json > rules[].entities[]` or inferred from rule context)
+- **category**: Rule category from `rules.json > rules[].category` — one of: validation, calculation, workflow, security, data
+- **sectionCode**: Section this rule belongs to (from `rules.json > rules[].sectionCode` or inferred)
 - **module**: Which module it belongs to
 - **severity**: From `rule.severity` (blocking, info, etc.) mapped to "critical", "high", "medium", "low"
 - **implementationPoints**: Array of {layer, component, method, implementation}

package/templates/skills/business-analyse-handoff/references/prd-generation.md

@@ -80,6 +80,47 @@ ss business-analyse-handoff --feature {path} --output .ralph/prd-{moduleCode}.js
 
 ---
 
+### 2b. PRD v4.0 Structure (spec-oriented)
+
+> **v4 PRDs are generated with `--v4` flag.** They use `expectedFiles` instead of `implementation.filesToCreate`.
+
+```json
+{
+  "$version": "4.0.0",
+  "objectives": [
+    { "description": "...", "acceptanceCriteria": ["..."] }
+  ],
+  "expectedFiles": {
+    "domain": [...],
+    "application": [...],
+    "infrastructure": [...],
+    "api": [...],
+    "frontend": [...],
+    "seedData": [...],
+    "tests": [...],
+    "documentation": [...]
+  },
+  "gates": { /* declarative quality gate definitions */ }
+}
+```
+
+**Key differences from v3:**
+
+| Aspect | v3 (`$version: "3.0.0"`) | v4 (`$version: "4.0.0"`) |
+|--------|--------------------------|--------------------------|
+| File manifest | `implementation.filesToCreate` | `expectedFiles` (root level) |
+| Task model | `tasks[]` (pre-computed) | `objectives[]` (goal-oriented) |
+| Execution | Batch iterations (compact-loop) | Continuous (compaction-enabled) |
+
+**Consumer code must handle both:**
+```javascript
+const fileManifest = prd.$version === '4.0.0'
+  ? prd.expectedFiles
+  : prd.implementation?.filesToCreate;
+```
+
+---
+
 ### 3. Eight Categories (MANDATORY)
 
 All PRD files MUST include these 8 categories under `implementation.filesToCreate`:
@@ -167,6 +208,64 @@ Each file entry in a category array must have:
 
 ---
 
+### 6. Specification Files (MANDATORY)
+
+Each PRD MUST include a `specificationFiles` object and 5 companion files in `.ralph/`:
+
+```json
+{
+  "$version": "3.0.0",
+  "implementation": { "filesToCreate": { /* 8 categories */ } },
+  "brToCodeMapping": [ /* enriched with statement, example, formula */ ],
+  "apiEndpointSummary": [ /* ... */ ],
+  "specificationFiles": {
+    "entities": "prd-{moduleCode}.entities.json",
+    "rules": "prd-{moduleCode}.rules.json",
+    "usecases": "prd-{moduleCode}.usecases.json",
+    "screens": "prd-{moduleCode}.screens.json",
+    "permissions": "prd-{moduleCode}.permissions.json"
+  }
+}
+```
+
+**Companion files** are VERBATIM copies of BA source files, colocated in `.ralph/`:
+
+```
+.ralph/
+  prd-Employees.json                  # PRD manifest (compact)
+  prd-Employees.entities.json         # VERBATIM copy of entities.json
+  prd-Employees.rules.json            # VERBATIM copy of rules.json
+  prd-Employees.usecases.json         # VERBATIM copy of usecases.json
+  prd-Employees.screens.json          # VERBATIM copy of screens.json
+  prd-Employees.permissions.json      # VERBATIM copy of permissions.json
+```
+
+**Validation:**
+```javascript
+const specFiles = prd.specificationFiles;
+if (!specFiles) {
+  BLOCKING_ERROR('specificationFiles missing from PRD');
+}
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+for (const key of specKeys) {
+  if (!specFiles[key]) {
+    BLOCKING_ERROR(`specificationFiles.${key} missing`);
+  }
+  const filePath = path.join('.ralph', specFiles[key]);
+  if (!fs.existsSync(filePath)) {
+    BLOCKING_ERROR(`Companion file not found: ${filePath}`);
+  }
+}
+```
+
+**Why companion files matter:**
+- `/apex` loads only the specs needed per layer (entities for L0, rules+usecases for L2, screens for L3)
+- Context per layer is ~200-500 lines instead of ~2000 lines monolithic
+- Zero risk of specs being lost at the bottom of a large context window
+- Full BA detail available for oneshot generation (attributes, formulas, screen columns)
+
+---
+
 ## Validation Checklist
 
 Use this checklist when validating PRD files:
@@ -178,6 +277,7 @@ Use this checklist when validating PRD files:
 | **Categories** | All 8 categories present | PASS/FAIL |
 | **File Counts** | PRD counts match index.json handoff.filesToCreate | PASS/FAIL |
 | **File Schemas** | All files have path, type, module | PASS/FAIL |
+| **Spec Files** | `specificationFiles` present with 5 paths, all companion files exist | PASS/FAIL |
 
 **All checks must PASS before proceeding to /business-analyse-develop**
 

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

@@ -151,13 +151,39 @@ Write via ba-writer.enrichModuleHandoff with the complete handoff payload:
 - totalFiles, totalTasks, handedOffAt (ISO timestamp)
 - featureDescription: {featureDescription}
 
+### Specification Files (MANDATORY)
+After writing the handoff data, ALSO write 5 companion files:
+1. `.ralph/prd-{moduleCode}.entities.json` = VERBATIM copy of `{moduleDir}/entities.json`
+2. `.ralph/prd-{moduleCode}.rules.json` = VERBATIM copy of `{moduleDir}/rules.json`
+3. `.ralph/prd-{moduleCode}.usecases.json` = VERBATIM copy of `{moduleDir}/usecases.json`
+4. `.ralph/prd-{moduleCode}.screens.json` = VERBATIM copy of `{moduleDir}/screens.json`
+5. `.ralph/prd-{moduleCode}.permissions.json` = VERBATIM copy of `{moduleDir}/permissions.json`
+
+Add `specificationFiles` to the PRD referencing these files (relative names, all in `.ralph/`):
+```json
+"specificationFiles": {
+  "entities": "prd-{moduleCode}.entities.json",
+  "rules": "prd-{moduleCode}.rules.json",
+  "usecases": "prd-{moduleCode}.usecases.json",
+  "screens": "prd-{moduleCode}.screens.json",
+  "permissions": "prd-{moduleCode}.permissions.json"
+}
+```
+
 ### POST-CHECK (BLOCKING)
 After writing, verify:
 1. Handoff not empty
 2. All 8 categories present
 3. brToCodeMapping non-empty
 4. Section resources have entity field
-Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped"
+5. SeedData contains CORE entries (NavigationModuleSeedData, NavigationSectionSeedData if sections exist, PermissionsSeedData, RolesSeedData)
+6. For FIRST module only: SeedData contains APP-LEVEL CORE entries (NavigationApplicationSeedData, ApplicationRolesSeedData)
+7. All 5 companion files exist in `.ralph/` and are non-empty
+8. `specificationFiles` present in the PRD with all 5 paths
+9. Entity count in companion matches source: `prd-{moduleCode}.entities.json` entities[] count = `{moduleDir}/entities.json` entities[] count
+10. BR count in companion matches source: `prd-{moduleCode}.rules.json` rules[] count = `{moduleDir}/rules.json` rules[] count
+11. Each `brToCodeMapping[].statement` is non-empty (not just a title paraphrase)
+Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {coreCount} core seeds, 5 companion files"
 ```
 
 ### 3. Display Progress

package/templates/skills/business-analyse-handoff/steps/step-02-export.md

@@ -91,6 +91,26 @@ for (const cat of categories) {
     BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
   }
 }
+
+// Check 5: Specification files (companion files)
+const specFiles = prd.specificationFiles;
+if (!specFiles) {
+  BLOCKING_ERROR("specificationFiles missing from PRD");
+}
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+for (const key of specKeys) {
+  if (!specFiles[key]) {
+    BLOCKING_ERROR(`specificationFiles.${key} path missing`);
+  }
+  const companionPath = `.ralph/${specFiles[key]}`;
+  if (!fileExists(companionPath)) {
+    BLOCKING_ERROR(`Companion file not found: ${companionPath}`);
+  }
+  const companionSize = fileSize(companionPath);
+  if (companionSize < 10) {
+    BLOCKING_ERROR(`Companion file empty or too small: ${companionPath} (${companionSize} bytes)`);
+  }
+}
 ```
 
 Display verification table showing all 8 categories match between module JSON files and prd.json.
@@ -99,11 +119,13 @@ Display verification table showing all 8 categories match between module JSON fi
 
 ```json
 {
-  "queue": [
-    { "moduleCode": "{code}", "order": 1, "dependencies": [], "complexity": "simple" },
-    { "moduleCode": "{code}", "order": 2, "dependencies": ["{dep}"], "complexity": "medium" }
+  "modules": [
+    { "code": "{code}", "prdFile": ".ralph/prd-{code}.json", "status": "pending", "order": 1, "dependencies": [], "complexity": "simple" },
+    { "code": "{code}", "prdFile": ".ralph/prd-{code}.json", "status": "pending", "order": 2, "dependencies": ["{dep}"], "complexity": "medium" }
   ],
-  "totalModules": {count},
+  "currentIndex": 0,
+  "totalModules": "{count}",
+  "completedModules": 0,
   "strategy": "topological"
 }
 ```
@@ -185,10 +207,15 @@ Readiness Scores:
 └──────────────┴────────────┴──────────────┘
 
 Artifacts generated:
-  .ralph/prd-{module}.json      — Task breakdown per module
-  .ralph/progress.txt           — Progression tracker
-  .ralph/modules-queue.json     — Module execution order (if multi-module)
-  docs/index.json               — BA manifest (status: handed-off)
+  .ralph/prd-{module}.json                — Task breakdown per module
+  .ralph/prd-{module}.entities.json       — Entity specifications (companion)
+  .ralph/prd-{module}.rules.json          — Business rules (companion)
+  .ralph/prd-{module}.usecases.json       — Use cases (companion)
+  .ralph/prd-{module}.screens.json        — Screen specifications (companion)
+  .ralph/prd-{module}.permissions.json    — Permissions (companion)
+  .ralph/progress.txt                     — Progression tracker
+  .ralph/modules-queue.json               — Module execution order (if multi-module)
+  docs/index.json                         — BA manifest (status: handed-off)
 
 [NEXT] Development:
   1. Run /business-analyse-develop to begin implementation
@@ -208,5 +235,8 @@ Artifacts generated:
 4. `docs/index.json` updated with correct entry count and status "handed-off"
 5. All PRD files have $version=3.0.0 or 4.0.0, file manifest present, 8 categories
 6. File counts match between PRD and handoff for all categories
+7. For EACH module: 5 companion files exist in `.ralph/` (entities, rules, usecases, screens, permissions)
+8. Each PRD contains `specificationFiles` with all 5 paths
+9. Each companion file is non-empty (>10 bytes)
 
 **IF any check fails -> fix before completing.**

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

@@ -378,13 +378,13 @@ body {
 .nav-icon-section { font-size: 0.5rem; color: var(--accent); }
 .nav-icon-resource { font-size: 0.7rem; color: var(--border-light); }
 .nav-resource-link {
-    cursor: default;
+    cursor: pointer;
     font-size: 0.72rem;
     color: var(--text-muted);
     padding-top: 0.2rem;
     padding-bottom: 0.2rem;
 }
-.nav-resource-link:hover { background: transparent; color: var(--text-muted); }
+.nav-resource-link:hover { background: var(--bg-hover); color: var(--accent); }
 .nav-resources { margin-left: 0.5rem; }
 
 
@@ -1031,6 +1031,44 @@ body {
     color: var(--text-muted);
 }
 
+/* ============================================
+   STRUCTURE LEGEND
+   ============================================ */
+.struct-legend {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 0.75rem 1rem;
+    margin-bottom: 1.25rem;
+}
+.struct-legend-title {
+    font-size: 0.8rem;
+    font-weight: 600;
+    color: var(--text-muted);
+    margin-bottom: 0.5rem;
+}
+.struct-legend-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 0.4rem 1.5rem;
+}
+.struct-legend-item {
+    font-size: 0.78rem;
+    color: var(--text-muted);
+    line-height: 1.4;
+}
+.struct-legend-code {
+    display: inline-block;
+    font-weight: 600;
+    color: var(--accent);
+    background: rgba(6,182,212,0.1);
+    padding: 0.05rem 0.4rem;
+    border-radius: 3px;
+    font-size: 0.72rem;
+    margin-right: 0.3rem;
+    font-family: monospace;
+}
+
 /* ============================================
    SECTION GROUPS (Hierarchical Mode)
    ============================================ */
@@ -2762,7 +2800,7 @@ function renderModuleNavItem(mod) {
                 html += '<div class="nav-children nav-resources">';
                 resources.forEach(function(res) {
                     var resName = typeof res === 'string' ? res : (res.code || res.name || '');
-                    html += '<a class="nav-item nav-resource-link">';
+                    html += '<a class="nav-item nav-resource-link" onclick="showSection(\'module-spec-' + code + '\');switchTab(\'' + code + '\',\'mock\');scrollToMockup(\'' + code + '\',\'' + section.code + '\')">';
                     html += '<span class="nav-icon nav-icon-resource">&#8226;</span> ' + escapeHtml(resName);
                     html += '</a>';
                 });
@@ -2785,6 +2823,18 @@ function renderModuleTabNavItem(code, tabId, label, badge) {
     '</a>';
 }
 
+function scrollToMockup(moduleCode, sectionCode) {
+    setTimeout(function() {
+        var el = document.getElementById('screen-' + moduleCode + '-' + sectionCode);
+        if (el) {
+            el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            el.style.outline = '2px solid var(--accent)';
+            el.style.borderRadius = '10px';
+            setTimeout(function() { el.style.outline = ''; el.style.borderRadius = ''; }, 2000);
+        }
+    }, 150);
+}
+
 /* ---------- Collapse/Expand ---------- */
 
 function toggleNavGroup(groupId) {
@@ -3916,7 +3966,16 @@ function renderModuleStructure(code) {
             '</div>';
     }
 
-    return sections.map(function(section) {
+    var legend = '<div class="struct-legend">' +
+        '<div class="struct-legend-title">&#9432; Types de sections</div>' +
+        '<div class="struct-legend-grid">' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">list</span> Page principale — grille de données avec filtres, tri et actions (créer, exporter)</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">detail</span> Fiche détaillée — affichée au clic sur une ligne, avec onglets (infos, relations, historique)</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">dashboard</span> Tableau de bord — KPIs, graphiques et métriques du module</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">approve</span> Workflow — file de validation avec actions (approuver, rejeter, mettre en attente)</div>' +
+        '</div></div>';
+
+    return legend + sections.map(function(section) {
         var resources = section.resources || [];
         var sectionUCs = section.useCases || [];
         var sectionBRs = section.businessRules || [];
@@ -4295,7 +4354,7 @@ function renderScreenMockups(code) {
 
     return screens.map(function(screen, si) {
         var resources = screen.resources || [];
-        return '<div class="screen-section" style="margin-bottom:2rem;">' +
+        return '<div class="screen-section" id="screen-' + code + '-' + screen.sectionCode + '" style="margin-bottom:2rem;">' +
             '<h3 style="color:var(--text-bright);font-size:1rem;margin-bottom:1rem;">' +
             '<span style="color:var(--accent);">&#9656;</span> ' + escapeHtml(screen.sectionLabel || screen.sectionCode) +
             '</h3>' +

package/templates/skills/business-analyse-html/html/src/scripts/02-navigation.js

@@ -182,7 +182,7 @@ function renderModuleNavItem(mod) {
                 html += '<div class="nav-children nav-resources">';
                 resources.forEach(function(res) {
                     var resName = typeof res === 'string' ? res : (res.code || res.name || '');
-                    html += '<a class="nav-item nav-resource-link">';
+                    html += '<a class="nav-item nav-resource-link" onclick="showSection(\'module-spec-' + code + '\');switchTab(\'' + code + '\',\'mock\');scrollToMockup(\'' + code + '\',\'' + section.code + '\')">';
                     html += '<span class="nav-icon nav-icon-resource">&#8226;</span> ' + escapeHtml(resName);
                     html += '</a>';
                 });
@@ -205,6 +205,18 @@ function renderModuleTabNavItem(code, tabId, label, badge) {
     '</a>';
 }
 
+function scrollToMockup(moduleCode, sectionCode) {
+    setTimeout(function() {
+        var el = document.getElementById('screen-' + moduleCode + '-' + sectionCode);
+        if (el) {
+            el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            el.style.outline = '2px solid var(--accent)';
+            el.style.borderRadius = '10px';
+            setTimeout(function() { el.style.outline = ''; el.style.borderRadius = ''; }, 2000);
+        }
+    }, 150);
+}
+
 /* ---------- Collapse/Expand ---------- */
 
 function toggleNavGroup(groupId) {

package/templates/skills/business-analyse-html/html/src/scripts/05-render-specs.js

@@ -620,7 +620,16 @@ function renderModuleStructure(code) {
             '</div>';
     }
 
-    return sections.map(function(section) {
+    var legend = '<div class="struct-legend">' +
+        '<div class="struct-legend-title">&#9432; Types de sections</div>' +
+        '<div class="struct-legend-grid">' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">list</span> Page principale — grille de données avec filtres, tri et actions (créer, exporter)</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">detail</span> Fiche détaillée — affichée au clic sur une ligne, avec onglets (infos, relations, historique)</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">dashboard</span> Tableau de bord — KPIs, graphiques et métriques du module</div>' +
+        '<div class="struct-legend-item"><span class="struct-legend-code">approve</span> Workflow — file de validation avec actions (approuver, rejeter, mettre en attente)</div>' +
+        '</div></div>';
+
+    return legend + sections.map(function(section) {
         var resources = section.resources || [];
         var sectionUCs = section.useCases || [];
         var sectionBRs = section.businessRules || [];

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

@@ -11,7 +11,7 @@ function renderScreenMockups(code) {
 
     return screens.map(function(screen, si) {
         var resources = screen.resources || [];
-        return '<div class="screen-section" style="margin-bottom:2rem;">' +
+        return '<div class="screen-section" id="screen-' + code + '-' + screen.sectionCode + '" style="margin-bottom:2rem;">' +
             '<h3 style="color:var(--text-bright);font-size:1rem;margin-bottom:1rem;">' +
             '<span style="color:var(--accent);">&#9656;</span> ' + escapeHtml(screen.sectionLabel || screen.sectionCode) +
             '</h3>' +

package/templates/skills/business-analyse-html/html/src/styles/03-navigation.css

@@ -110,11 +110,11 @@
 .nav-icon-section { font-size: 0.5rem; color: var(--accent); }
 .nav-icon-resource { font-size: 0.7rem; color: var(--border-light); }
 .nav-resource-link {
-    cursor: default;
+    cursor: pointer;
     font-size: 0.72rem;
     color: var(--text-muted);
     padding-top: 0.2rem;
     padding-bottom: 0.2rem;
 }
-.nav-resource-link:hover { background: transparent; color: var(--text-muted); }
+.nav-resource-link:hover { background: var(--bg-hover); color: var(--accent); }
 .nav-resources { margin-left: 0.5rem; }

package/templates/skills/business-analyse-html/html/src/styles/05-modules.css

@@ -443,6 +443,44 @@
     color: var(--text-muted);
 }
 
+/* ============================================
+   STRUCTURE LEGEND
+   ============================================ */
+.struct-legend {
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 0.75rem 1rem;
+    margin-bottom: 1.25rem;
+}
+.struct-legend-title {
+    font-size: 0.8rem;
+    font-weight: 600;
+    color: var(--text-muted);
+    margin-bottom: 0.5rem;
+}
+.struct-legend-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 0.4rem 1.5rem;
+}
+.struct-legend-item {
+    font-size: 0.78rem;
+    color: var(--text-muted);
+    line-height: 1.4;
+}
+.struct-legend-code {
+    display: inline-block;
+    font-weight: 600;
+    color: var(--accent);
+    background: rgba(6,182,212,0.1);
+    padding: 0.05rem 0.4rem;
+    border-radius: 3px;
+    font-size: 0.72rem;
+    margin-right: 0.3rem;
+    font-family: monospace;
+}
+
 /* ============================================
    SECTION GROUPS (Hierarchical Mode)
    ============================================ */