@atlashub/smartstack-cli 1.33.0 → 1.35.0

package/templates/skills/documentation/SKILL.md

@@ -8,14 +8,17 @@ description: |
   - User wants to document a module, table, tool, or test
   - After implementing a feature to generate its documentation
   Types: user module, developer tools, database ERD, testing tools
+argument-hint: "<module-name> [--type user|developer|database|testing|update]"
 ---
 
-# Skill Documentation SmartStack
-
-> **Note:** This skill works in synergy with the `/documentation:module` command.
+<objective>
+Generate and maintain technical documentation integrated into SmartStack web app.
+Works in synergy with the `/documentation:module` command.
 
 **Reference:** [_shared.md](../_shared.md) for architecture, i18n
+</objective>
 
+<quick_start>
 ## WHEN THIS SKILL ACTIVATES
 
 Claude automatically invokes this skill when it detects:
@@ -27,9 +30,33 @@ Claude automatically invokes this skill when it detects:
 | After implementation | "The feature is done, generate the doc" |
 | Structure question | "How is the documentation organized?" |
 | Keywords | "ERD", "schema", "diagram", "document" |
+| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
+| **Drift detected** | "The SLA documentation is stale" |
+</quick_start>
 
----
+<parameters>
+## DOCUMENTATION TYPES
+
+| Type | Description | Output |
+|------|-------------|--------|
+| `user` | User module (data-driven) | `docs/business/{app}/{module}/frd-data.ts` + `index.tsx` |
+| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
+| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
+| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
+| `update` | Update existing documentation | Updates `frd-data.ts` + i18n FR |
+
+### Available Developer tools
+
+| 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 |
+</parameters>
 
+<workflow>
 ## AUTOMATIC WORKFLOW
 
 ### STEP 1: TYPE DETECTION
@@ -53,40 +80,35 @@ Identify the specific name:
 
 ### STEP 3: EXECUTION
 
-Follow the workflow of the `/documentation:module` command:
+**For NEW documentation (type = user|developer|database|testing):**
 
-```
-TYPE = detected type (user|developer|database|testing)
-TARGET = extracted target
+Follow the data-driven workflow from [templates.md](templates.md):
 
-→ Execute the complete /documentation:module workflow
+```
+1. Read source data (FRD, BRD, code patterns)
+2. Generate frd-data.ts (data file, ~50 lines)
+3. Generate index.tsx (page wrapper, ~10 lines)
+4. Generate i18n FR file (source language only)
+5. Update docs-manifest.json
+6. Update App.tsx routing and parent indexes
 ```
 
----
-
-## QUICK REFERENCE
-
-### Documentation types
-
-| Type | Description | Output |
-|------|-------------|--------|
-| `user` | User module with UI mockups | `docs/user/{context}/{Module}DocPage.tsx` |
-| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
-| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
-| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
-
-### Available Developer tools
+**For UPDATE documentation (type = update):**
 
-| 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 |
+```
+1. Read docs-manifest.json → find target module
+2. Invoke docs-context-reader agent → get current doc state
+3. Identify code changes since last doc update (git diff)
+4. Map changes to documentation sections (see data-schema.md)
+5. Update frd-data.ts with new/modified data
+6. Update i18n FR file if labels changed
+7. Update docs-manifest.json timestamps
+```
 
----
+> **i18n simplifié:** Seul FR (source) est généré. EN/IT/DE sont déférés à un pipeline de traduction séparé.
+</workflow>
 
+<execution_rules>
 ## ABSOLUTE RULES
 
 1. **NEVER** hardcoded text → `useTranslation('docs')`
@@ -95,6 +117,17 @@ TARGET = extracted target
 4. **ALWAYS** confirm before creating
 5. **ALWAYS** update App.tsx and parent indexes
 6. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
+</execution_rules>
+
+---
+
+<success_criteria>
+- Documentation page renders correctly in React app
+- i18n files created for all 4 languages (FR, EN, IT, DE)
+- Route registered in App.tsx
+- docs-manifest.json updated
+- Module appears in UserIndexPage (if type = user)
+</success_criteria>
 
 ---
 
@@ -131,4 +164,8 @@ TARGET = extracted target
 ## ASSOCIATED FILES
 
 - **React Templates:** [templates.md](templates.md)
+- **Data Schema:** [data-schema.md](data-schema.md)
+- **FrdDocRenderer:** `web/smartstack-web/src/components/docs/FrdDocRenderer.tsx`
+- **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **Manifest Schema:** `_resources/docs-manifest-schema.md`
 - **Complete Command:** `.claude/commands/documentation-module.md`

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

@@ -0,0 +1,198 @@
+# Documentation Data Schema
+
+## Purpose
+
+This file describes how to generate `frd-data.ts` files for the `FrdDocRenderer` shared component.
+Instead of generating full TSX components (~250 lines) per module, generate only the data (~50 lines).
+
+## FrdData Interface Reference
+
+The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.
+
+## Data Extraction Mapping
+
+### From FRD (3-functional-specification.md)
+
+| FRD Section | FrdData Field | Extraction |
+|-------------|---------------|------------|
+| Section 1: Overview | `overview.objective` | Functional objective text |
+| Section 1: Overview | `overview.problem` | Problem statement |
+| Section 1: Overview | `overview.solution` | Solution statement |
+| Section 2: Use Cases | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
+| Section 3: Functional Requirements | `features[]` | FR-XXX entries grouped as features |
+| Section 5: Permission Matrix | `permissions[]` | Role-permission entries |
+| Section 6: Gherkin Scenarios | (used for test data, not doc) | - |
+| Section 7: Validations | `businessRules[]` | BR-XXX from BRD cross-referenced |
+
+### From BRD (2-business-requirements.md)
+
+| BRD Section | FrdData Field | Extraction |
+|-------------|---------------|------------|
+| Section 2: Business Objectives | `overview.stats` | Count objectives |
+| Section 3: Business Rules | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
+| Section 6: Integrations | `technicalRef` | Integration notes |
+
+### From Handoff (4-development-handoff.md)
+
+| Handoff Section | FrdData Field | Extraction |
+|-----------------|---------------|------------|
+| Section 3: Files to Create | `technicalRef.entityNames` | Entity names |
+| Section 6: API Endpoints | `apiEndpoints[]` | Endpoint entries |
+| Section 1: Quick Context | `technicalRef.permissionBase` | Permission base path |
+| Section 1: Quick Context | `technicalRef.controllerRoute` | Controller route |
+
+### Generated/Inferred Fields
+
+| Field | Source |
+|-------|--------|
+| `featureId` | From 00-context.md state |
+| `moduleName` | From 00-context.md state |
+| `applicationName` | From 00-context.md state |
+| `version` | "1.0" (initial) |
+| `benefits[]` | Inferred from BRD 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` |
+
+## Generated File Structure
+
+### frd-data.ts (per module, ~50-80 lines)
+
+```typescript
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/frd-data.ts
+import type { FrdData } from '@/components/docs';
+
+export const frdData: FrdData = {
+  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: 'business.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: 'business.support.sla.read', description: 'View SLA policies', roles: ['Admin', 'Manager', 'User', 'ReadOnly'] },
+    { path: 'business.support.sla.create', description: 'Create SLA policies', roles: ['Admin', 'Manager'] },
+    // ...
+  ],
+
+  apiEndpoints: [
+    { method: 'GET', path: '/api/business/sla', handler: 'GetAllSlaQuery', permission: '.read' },
+    { method: 'POST', path: '/api/business/sla', handler: 'CreateSlaCommand', permission: '.create' },
+    // ...
+  ],
+
+  screenshots: {
+    step1: '/assets/docs/sla/step-1.png',
+    step2: '/assets/docs/sla/step-2.png',
+  },
+
+  technicalRef: {
+    permissionBase: 'business.support.sla',
+    controllerRoute: 'business.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 { FrdDocRenderer } from '@/components/docs';
+import { frdData } from './frd-data';
+
+export default function {Module}DocPage() {
+  return (
+    <FrdDocRenderer
+      data={frdData}
+      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 économisé", "description": "Réduction de 70% du temps de suivi manuel" },
+        "quality": { "title": "Fiabilité", "description": "95% des SLA respectés grâce 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 prédéfinis sont disponibles pour les cas courants."
+        }
+      }
+    }
+  }
+}
+```
+
+> **Note:** Seul FR est généré. EN/IT/DE sont marqués comme "deferred" et générés par un pipeline de traduction séparé.
+
+## 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 `FrdDocRenderer` shows a "Screenshot à venir" placeholder when the image file is not found.

package/templates/skills/documentation/templates.md

@@ -22,7 +22,36 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 
 ---
 
-## Template User Module (Business-First)
+## Data-Driven Approach (Recommended)
+
+> **Principe:** Au lieu de générer un composant TSX complet (~250 lignes) par module,
+> générer uniquement un fichier de DONNÉES (`frd-data.ts`, ~50 lignes) + un wrapper minimal.
+> Le rendu est assuré par le composant partagé `FrdDocRenderer` dans `web/.../components/docs/`.
+
+### Fichiers à générer par module
+
+**1. Data file** (`frd-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.
+
+**2. Page wrapper** (`index.tsx`, ~10 lignes) :
+```tsx
+import { FrdDocRenderer } from '@/components/docs';
+import { frdData } from './frd-data';
+
+export default function {ModuleName}DocPage() {
+  return <FrdDocRenderer data={frdData} backPath="/docs/business/{app}" />;
+}
+```
+
+**3. i18n FR uniquement** : Générer la langue source (FR). EN/IT/DE sont déférés.
+
+> **Screenshots:** Chemins conventionnels `/assets/docs/{module}/step-{N}.png`.
+> Le renderer affiche un placeholder "Screenshot à venir" si l'image n'existe pas.
+
+---
+
+## Legacy: Template TSX Complet (référence)
+
+> **Déprécié:** Conservé pour référence. Utilisez l'approche data-driven ci-dessus.
 
 ```tsx
 // web/smartstack-web/src/pages/docs/user/{ModuleName}DocPage.tsx