@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/documentation/data-schema.md

@@ -1,227 +1,227 @@
-# Documentation Data Schema
-
-> **SCOPE:** This schema applies to `developer`, `database`, and `testing` doc types ONLY.
-> For `user` type modules, generate standalone Mock UI TSX pages — see [templates.md](templates.md).
-
-## Purpose
-
-This file describes how to generate `doc-data.ts` files for the `DocRenderer` shared component.
-Used for non-user doc types (`developer`, `database`, `testing`).
-
-## DocData Interface Reference
-
-The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.
-
-## Data Extraction Mapping
-
-### From feature.json (single source of truth)
-
-The business analysis skill (`/business-analyse`) produces a `feature.json` file per module at:
-`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
-
-All documentation data is extracted from this file.
-
-#### Specification section → DocData fields
-
-| feature.json Path | DocData Field | Extraction |
-|-------------------|---------------|------------|
-| `specification.useCases[]` | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
-| `specification.functionalRequirements[]` | `features[]` | FR-XXX entries grouped as features |
-| `specification.permissionsMatrix` | `permissions[]` | Role-permission entries |
-| `specification.apiEndpoints[]` | `apiEndpoints[]` | Endpoint entries (method, path, handler, permission) |
-| `specification.wireframes[]` | `steps[]` | Inferred from wireframe descriptions |
-| `specification.gherkinScenarios` | (used for test data, not doc) | - |
-
-#### Analysis section → DocData fields
-
-| feature.json Path | DocData Field | Extraction |
-|-------------------|---------------|------------|
-| `analysis.businessRules[]` | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
-| `analysis.objectives[]` | `overview.stats` | Count objectives |
-| `analysis.entities[]` | `technicalRef.entityNames` | Entity names from analysis |
-| `analysis.integrations[]` | `technicalRef` | Integration notes |
-
-#### Discovery section → DocData fields
-
-| feature.json Path | DocData Field | Extraction |
-|-------------------|---------------|------------|
-| `discovery.problem` | `overview.problem` | Problem statement |
-| `discovery.scope.inScope` | `overview.objective` | Functional objective text |
-| `discovery.scope.outOfScope` | `overview.solution` | Solution statement (inferred) |
-| `discovery.risks[]` | (optional) | Risk documentation |
-
-#### Handoff section → DocData fields
-
-| feature.json Path | DocData Field | Extraction |
-|-------------------|---------------|------------|
-| `handoff.filesToCreate.domain` | `technicalRef.entityNames` | Entity names |
-| `handoff.apiEndpointSummary[]` | `apiEndpoints[]` | Endpoint entries (cross-validate) |
-| `handoff.brToCodeMapping[]` | `technicalRef` | BR-to-code mapping |
-
-### Generated/Inferred Fields
-
-| Field | Source |
-|-------|--------|
-| `featureId` | `metadata.featureId` from feature.json |
-| `moduleName` | `metadata.moduleName` from feature.json |
-| `applicationName` | `metadata.applicationName` from feature.json |
-| `version` | `metadata.version` from feature.json |
-| `benefits[]` | Inferred from analysis objectives or i18n |
-| `beforeAfter` | Inferred from discovery problem/solution |
-| `steps[]` | Inferred from use cases main scenario |
-| `faq[]` | Inferred from discovery open questions |
-| `screenshots` | Convention: `/assets/docs/{module}/step-{N}.png` |
-
-## Fallback: No feature.json Available
-
-If no feature.json exists (e.g., module was created without `/business-analyse`),
-the `/documentation` skill extracts data directly from code:
-
-| Source | DocData Field | Extraction |
-|--------|---------------|------------|
-| Controller `[Http*]` attributes | `apiEndpoints[]` | Method, path, permission |
-| `Permissions.cs` constants | `permissions[]` | Permission paths |
-| `Domain/Entities/*.cs` | `technicalRef.entityNames` | Entity class names |
-| i18n JSON files | `overview`, `features` | Existing translations |
-
-## Generated File Structure
-
-### doc-data.ts (per module, ~50-80 lines)
-
-```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/doc-data.ts
-import type { DocData } from '@/components/docs';
-
-export const docData: DocData = {
-  featureId: 'FEAT-001',
-  moduleName: 'Sla',
-  applicationName: 'Support',
-  version: '1.0',
-
-  overview: {
-    objective: 'docs.support.sla.overview.objective',
-    problem: 'docs.support.sla.overview.problem',
-    solution: 'docs.support.sla.overview.solution',
-    stats: { useCases: 4, businessRules: 6, permissions: 5, endpoints: 5 },
-  },
-
-  useCases: [
-    { id: 'UC-001', name: 'Create SLA', actor: 'Admin', description: '...', permission: 'support.sla.create', priority: 'Must' },
-    // ...
-  ],
-
-  benefits: [
-    { icon: 'time', titleKey: 'docs.support.sla.benefits.time.title', value: '-70%', descriptionKey: 'docs.support.sla.benefits.time.description' },
-    { icon: 'quality', titleKey: 'docs.support.sla.benefits.quality.title', value: '+95%', descriptionKey: 'docs.support.sla.benefits.quality.description' },
-    { icon: 'roi', titleKey: 'docs.support.sla.benefits.roi.title', value: '3x', descriptionKey: 'docs.support.sla.benefits.roi.description' },
-  ],
-
-  beforeAfter: {
-    beforeItems: ['Manual SLA tracking', 'No escalation alerts', 'No compliance visibility', 'Scattered data'],
-    afterItems: ['Automated SLA monitoring', 'Real-time escalation', 'Compliance dashboard', 'Centralized metrics'],
-  },
-
-  features: [
-    { id: 'F-001', title: 'SLA Configuration', description: '...', example: '...' },
-    // ...
-  ],
-
-  steps: [
-    { number: 1, title: 'Navigate to SLA module', description: '...', screenshotKey: 'step1' },
-    { number: 2, title: 'Create SLA policy', description: '...', screenshotKey: 'step2' },
-    // ...
-  ],
-
-  faq: [
-    { questionKey: 'docs.support.sla.faq.1.question', answerKey: 'docs.support.sla.faq.1.answer' },
-    // ...
-  ],
-
-  businessRules: [
-    { id: 'BR-001', name: 'SLA Time Calculation', category: 'Calculation', statement: '...' },
-    // ...
-  ],
-
-  permissions: [
-    { path: 'support.sla.read', description: 'View SLA policies', roles: ['Admin', 'Manager', 'User', 'ReadOnly'] },
-    { path: 'support.sla.create', description: 'Create SLA policies', roles: ['Admin', 'Manager'] },
-    // ...
-  ],
-
-  apiEndpoints: [
-    { method: 'GET', path: '/api/support/sla', handler: 'GetAllSlaQuery', permission: '.read' },
-    { method: 'POST', path: '/api/support/sla', handler: 'CreateSlaCommand', permission: '.create' },
-    // ...
-  ],
-
-  screenshots: {
-    step1: '/assets/docs/sla/step-1.png',
-    step2: '/assets/docs/sla/step-2.png',
-  },
-
-  technicalRef: {
-    permissionBase: 'support.sla',
-    controllerRoute: 'support.sla',
-    entityNames: ['Sla', 'SlaPolicy', 'SlaEscalation'],
-  },
-};
-```
-
-### Page wrapper (per module, ~10 lines)
-
-```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/index.tsx
-import { DocRenderer } from '@/components/docs';
-import { docData } from './doc-data';
-
-export default function {Module}DocPage() {
-  return (
-    <DocRenderer
-      data={docData}
-      backPath="/docs/business/{app}"
-      backLabel="nav.backToApp"
-    />
-  );
-}
-```
-
-### i18n file (FR source, ~30 lines)
-
-```json
-// web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json
-{
-  "support": {
-    "sla": {
-      "overview": {
-        "objective": "Gestion des niveaux de service (SLA)",
-        "problem": "Les engagements de service ne sont pas suivis, les escalades sont manuelles",
-        "solution": "Monitoring automatique des SLA avec alertes et escalades configurables"
-      },
-      "benefits": {
-        "time": { "title": "Temps economise", "description": "Reduction de 70% du temps de suivi manuel" },
-        "quality": { "title": "Fiabilite", "description": "95% des SLA respectes grace au monitoring" },
-        "roi": { "title": "ROI", "description": "Retour sur investissement en 3 mois" }
-      },
-      "faq": {
-        "1": {
-          "question": "Dois-je configurer chaque SLA manuellement ?",
-          "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
-        }
-      }
-    }
-  }
-}
-```
-
-> **Note:** Seul FR est genere. EN/IT/DE sont marques comme "deferred" et generes par un pipeline de traduction separe.
-
-## Screenshot Convention
-
-| Key | Path | Description |
-|-----|------|-------------|
-| `step{N}` | `/assets/docs/{module}/step-{N}.png` | Step-by-step guide screenshots |
-| `overview` | `/assets/docs/{module}/overview.png` | Module overview screenshot |
-| `dashboard` | `/assets/docs/{module}/dashboard.png` | Dashboard view |
-
-Screenshots are added manually or via Playwright E2E tests.
-The `DocRenderer` shows a "Screenshot a venir" placeholder when the image file is not found.
+# Documentation Data Schema
+
+> **SCOPE:** This schema applies to `developer`, `database`, and `testing` doc types ONLY.
+> For `user` type modules, generate standalone Mock UI TSX pages — see [templates.md](templates.md).
+
+## Purpose
+
+This file describes how to generate `doc-data.ts` files for the `DocRenderer` shared component.
+Used for non-user doc types (`developer`, `database`, `testing`).
+
+## DocData Interface Reference
+
+The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.
+
+## Data Extraction Mapping
+
+### From feature.json (single source of truth)
+
+The business analysis skill (`/business-analyse`) produces a `feature.json` file per module at:
+`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
+
+All documentation data is extracted from this file.
+
+#### Specification section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `specification.useCases[]` | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
+| `specification.functionalRequirements[]` | `features[]` | FR-XXX entries grouped as features |
+| `specification.permissionsMatrix` | `permissions[]` | Role-permission entries |
+| `specification.apiEndpoints[]` | `apiEndpoints[]` | Endpoint entries (method, path, handler, permission) |
+| `specification.wireframes[]` | `steps[]` | Inferred from wireframe descriptions |
+| `specification.gherkinScenarios` | (used for test data, not doc) | - |
+
+#### Analysis section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `analysis.businessRules[]` | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
+| `analysis.objectives[]` | `overview.stats` | Count objectives |
+| `analysis.entities[]` | `technicalRef.entityNames` | Entity names from analysis |
+| `analysis.integrations[]` | `technicalRef` | Integration notes |
+
+#### Discovery section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `discovery.problem` | `overview.problem` | Problem statement |
+| `discovery.scope.inScope` | `overview.objective` | Functional objective text |
+| `discovery.scope.outOfScope` | `overview.solution` | Solution statement (inferred) |
+| `discovery.risks[]` | (optional) | Risk documentation |
+
+#### Handoff section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `handoff.filesToCreate.domain` | `technicalRef.entityNames` | Entity names |
+| `handoff.apiEndpointSummary[]` | `apiEndpoints[]` | Endpoint entries (cross-validate) |
+| `handoff.brToCodeMapping[]` | `technicalRef` | BR-to-code mapping |
+
+### Generated/Inferred Fields
+
+| Field | Source |
+|-------|--------|
+| `featureId` | `metadata.featureId` from feature.json |
+| `moduleName` | `metadata.moduleName` from feature.json |
+| `applicationName` | `metadata.applicationName` from feature.json |
+| `version` | `metadata.version` from feature.json |
+| `benefits[]` | Inferred from analysis objectives or i18n |
+| `beforeAfter` | Inferred from discovery problem/solution |
+| `steps[]` | Inferred from use cases main scenario |
+| `faq[]` | Inferred from discovery open questions |
+| `screenshots` | Convention: `/assets/docs/{module}/step-{N}.png` |
+
+## Fallback: No feature.json Available
+
+If no feature.json exists (e.g., module was created without `/business-analyse`),
+the `/documentation` skill extracts data directly from code:
+
+| Source | DocData Field | Extraction |
+|--------|---------------|------------|
+| Controller `[Http*]` attributes | `apiEndpoints[]` | Method, path, permission |
+| `Permissions.cs` constants | `permissions[]` | Permission paths |
+| `Domain/Entities/*.cs` | `technicalRef.entityNames` | Entity class names |
+| i18n JSON files | `overview`, `features` | Existing translations |
+
+## Generated File Structure
+
+### doc-data.ts (per module, ~50-80 lines)
+
+```typescript
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/doc-data.ts
+import type { DocData } from '@/components/docs';
+
+export const docData: DocData = {
+  featureId: 'FEAT-001',
+  moduleName: 'Sla',
+  applicationName: 'Support',
+  version: '1.0',
+
+  overview: {
+    objective: 'docs.support.sla.overview.objective',
+    problem: 'docs.support.sla.overview.problem',
+    solution: 'docs.support.sla.overview.solution',
+    stats: { useCases: 4, businessRules: 6, permissions: 5, endpoints: 5 },
+  },
+
+  useCases: [
+    { id: 'UC-001', name: 'Create SLA', actor: 'Admin', description: '...', permission: 'support.sla.create', priority: 'Must' },
+    // ...
+  ],
+
+  benefits: [
+    { icon: 'time', titleKey: 'docs.support.sla.benefits.time.title', value: '-70%', descriptionKey: 'docs.support.sla.benefits.time.description' },
+    { icon: 'quality', titleKey: 'docs.support.sla.benefits.quality.title', value: '+95%', descriptionKey: 'docs.support.sla.benefits.quality.description' },
+    { icon: 'roi', titleKey: 'docs.support.sla.benefits.roi.title', value: '3x', descriptionKey: 'docs.support.sla.benefits.roi.description' },
+  ],
+
+  beforeAfter: {
+    beforeItems: ['Manual SLA tracking', 'No escalation alerts', 'No compliance visibility', 'Scattered data'],
+    afterItems: ['Automated SLA monitoring', 'Real-time escalation', 'Compliance dashboard', 'Centralized metrics'],
+  },
+
+  features: [
+    { id: 'F-001', title: 'SLA Configuration', description: '...', example: '...' },
+    // ...
+  ],
+
+  steps: [
+    { number: 1, title: 'Navigate to SLA module', description: '...', screenshotKey: 'step1' },
+    { number: 2, title: 'Create SLA policy', description: '...', screenshotKey: 'step2' },
+    // ...
+  ],
+
+  faq: [
+    { questionKey: 'docs.support.sla.faq.1.question', answerKey: 'docs.support.sla.faq.1.answer' },
+    // ...
+  ],
+
+  businessRules: [
+    { id: 'BR-001', name: 'SLA Time Calculation', category: 'Calculation', statement: '...' },
+    // ...
+  ],
+
+  permissions: [
+    { path: 'support.sla.read', description: 'View SLA policies', roles: ['Admin', 'Manager', 'User', 'ReadOnly'] },
+    { path: 'support.sla.create', description: 'Create SLA policies', roles: ['Admin', 'Manager'] },
+    // ...
+  ],
+
+  apiEndpoints: [
+    { method: 'GET', path: '/api/support/sla', handler: 'GetAllSlaQuery', permission: '.read' },
+    { method: 'POST', path: '/api/support/sla', handler: 'CreateSlaCommand', permission: '.create' },
+    // ...
+  ],
+
+  screenshots: {
+    step1: '/assets/docs/sla/step-1.png',
+    step2: '/assets/docs/sla/step-2.png',
+  },
+
+  technicalRef: {
+    permissionBase: 'support.sla',
+    controllerRoute: 'support.sla',
+    entityNames: ['Sla', 'SlaPolicy', 'SlaEscalation'],
+  },
+};
+```
+
+### Page wrapper (per module, ~10 lines)
+
+```typescript
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/index.tsx
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
+
+export default function {Module}DocPage() {
+  return (
+    <DocRenderer
+      data={docData}
+      backPath="/docs/business/{app}"
+      backLabel="nav.backToApp"
+    />
+  );
+}
+```
+
+### i18n file (FR source, ~30 lines)
+
+```json
+// web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json
+{
+  "support": {
+    "sla": {
+      "overview": {
+        "objective": "Gestion des niveaux de service (SLA)",
+        "problem": "Les engagements de service ne sont pas suivis, les escalades sont manuelles",
+        "solution": "Monitoring automatique des SLA avec alertes et escalades configurables"
+      },
+      "benefits": {
+        "time": { "title": "Temps economise", "description": "Reduction de 70% du temps de suivi manuel" },
+        "quality": { "title": "Fiabilite", "description": "95% des SLA respectes grace au monitoring" },
+        "roi": { "title": "ROI", "description": "Retour sur investissement en 3 mois" }
+      },
+      "faq": {
+        "1": {
+          "question": "Dois-je configurer chaque SLA manuellement ?",
+          "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
+        }
+      }
+    }
+  }
+}
+```
+
+> **Note:** Seul FR est genere. EN/IT/DE sont marques comme "deferred" et generes par un pipeline de traduction separe.
+
+## Screenshot Convention
+
+| Key | Path | Description |
+|-----|------|-------------|
+| `step{N}` | `/assets/docs/{module}/step-{N}.png` | Step-by-step guide screenshots |
+| `overview` | `/assets/docs/{module}/overview.png` | Module overview screenshot |
+| `dashboard` | `/assets/docs/{module}/dashboard.png` | Dashboard view |
+
+Screenshots are added manually or via Playwright E2E tests.
+The `DocRenderer` shows a "Screenshot a venir" placeholder when the image file is not found.

package/templates/skills/documentation/steps/step-00-init.md

@@ -1,70 +1,70 @@
----
-name: Init - Detect and Gather Context
-description: Detect documentation type and gather context from request
-next_step: step-01-scan.md
----
-
-## STEP 00: Init — Detect Documentation Type and Gather Context
-
-### Purpose
-
-Analyze the user request to identify documentation type, target name, and gather execution context before proceeding to scanning.
-
-### Execution Sequence
-
-#### 1. Type Detection
-
-Analyze the request to identify:
-
-| Clue | → Type |
-|------|--------|
-| Functional module (SLA, Tickets, Users) | `user` |
-| Dev tool (Docker, Postman, VS Code) | `developer` |
-| Tables, schema, database | `database` |
-| Tests (security, load, E2E) | `testing` |
-
-#### 2. Target Extraction
-
-Identify the specific name:
-- **Module:** `sla`, `tickets`, `users`, `permissions`
-- **Tool:** `docker`, `postman`, `playwright`, `maildev`
-- **Schema:** `support`, `auth`, `nav`, `usr`
-- **Test:** `security`, `load`, `e2e`
-
-#### 3. Documentation Mode Detection
-
-Determine if this is:
-- **NEW documentation** (type = user|developer|database|testing) → Generate from scratch
-- **UPDATE documentation** (explicit "update" flag or drift detected) → Refresh existing content
-
-#### 4. Available Developer Tools Reference
-
-| Category | Tools |
-|----------|-------|
-| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
-| API Testing | Postman, REST Client, Swagger/OpenAPI |
-| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
-| Load Testing | NBomber (.NET), k6, Azure Load Testing |
-| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
-
-### Output
-
-At end of this step, you should have:
-
-| Variable | Value | Example |
-|----------|-------|---------|
-| `type` | user \| developer \| database \| testing \| update | `user` |
-| `target` | Module/Tool/Schema name | `users` |
-| `application` | Parent app (for user type) | `administration` |
-| `mode` | new \| update | `new` |
-
-### Success Metrics
-
-- [x] Type correctly identified from request
-- [x] Target name extracted and validated
-- [x] Application assigned (if type = user)
-- [x] Mode determined (new vs update)
-
-### Next Step
-
-→ **step-01-scan.md** — Scan source code and existing documentation based on detected type.
+---
+name: Init - Detect and Gather Context
+description: Detect documentation type and gather context from request
+next_step: step-01-scan.md
+---
+
+## STEP 00: Init — Detect Documentation Type and Gather Context
+
+### Purpose
+
+Analyze the user request to identify documentation type, target name, and gather execution context before proceeding to scanning.
+
+### Execution Sequence
+
+#### 1. Type Detection
+
+Analyze the request to identify:
+
+| Clue | → Type |
+|------|--------|
+| Functional module (SLA, Tickets, Users) | `user` |
+| Dev tool (Docker, Postman, VS Code) | `developer` |
+| Tables, schema, database | `database` |
+| Tests (security, load, E2E) | `testing` |
+
+#### 2. Target Extraction
+
+Identify the specific name:
+- **Module:** `sla`, `tickets`, `users`, `permissions`
+- **Tool:** `docker`, `postman`, `playwright`, `maildev`
+- **Schema:** `support`, `auth`, `nav`, `usr`
+- **Test:** `security`, `load`, `e2e`
+
+#### 3. Documentation Mode Detection
+
+Determine if this is:
+- **NEW documentation** (type = user|developer|database|testing) → Generate from scratch
+- **UPDATE documentation** (explicit "update" flag or drift detected) → Refresh existing content
+
+#### 4. Available Developer Tools Reference
+
+| Category | Tools |
+|----------|-------|
+| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
+| API Testing | Postman, REST Client, Swagger/OpenAPI |
+| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
+| Load Testing | NBomber (.NET), k6, Azure Load Testing |
+| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
+
+### Output
+
+At end of this step, you should have:
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `type` | user \| developer \| database \| testing \| update | `user` |
+| `target` | Module/Tool/Schema name | `users` |
+| `application` | Parent app (for user type) | `administration` |
+| `mode` | new \| update | `new` |
+
+### Success Metrics
+
+- [x] Type correctly identified from request
+- [x] Target name extracted and validated
+- [x] Application assigned (if type = user)
+- [x] Mode determined (new vs update)
+
+### Next Step
+
+→ **step-01-scan.md** — Scan source code and existing documentation based on detected type.