@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -45,11 +45,11 @@ All documentation data is extracted from this file.
 
 | 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.scope.inScope` | `overview.objective` | Functional objective text (what the module does) |
 | `discovery.risks[]` | (optional) | Risk documentation |
 
+> `overview.problem` / `overview.solution`, `benefits[]` and `beforeAfter` are **no longer generated** — the doc leads with `objective` only (a factual description of what the module does), never a value-proposition pitch (SKILL.md rule #12). These fields remain optional in the `DocData` / `DocOverview` types for backward-compat, but the skill never authors them.
+
 #### Handoff section → DocData fields
 
 | feature.json Path | DocData Field | Extraction |
@@ -66,8 +66,6 @@ All documentation data is extracted from this file.
 | `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` |
@@ -99,9 +97,7 @@ export const docData: DocData = {
   version: '1.0',
 
   overview: {
-    objective: 'docs.support.sla.overview.objective',
-    problem: 'docs.support.sla.overview.problem',
-    solution: 'docs.support.sla.overview.solution',
+    objective: 'docsSupportSla.overview.objective',
     stats: { useCases: 4, businessRules: 6, permissions: 5, endpoints: 5 },
   },
 
@@ -110,17 +106,6 @@ export const docData: DocData = {
     // ...
   ],
 
-  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: '...' },
     // ...
@@ -133,7 +118,7 @@ export const docData: DocData = {
   ],
 
   faq: [
-    { questionKey: 'docs.support.sla.faq.1.question', answerKey: 'docs.support.sla.faq.1.answer' },
+    { questionKey: 'docsSupportSla.faq.1.question', answerKey: 'docsSupportSla.faq.1.answer' },
     // ...
   ],
 
@@ -188,25 +173,20 @@ export default function {Module}DocPage() {
 ### i18n file (FR source, ~30 lines)
 
 ```json
-// web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json
+// web/smartstack-web/src/i18n/locales/fr/docs-support-sla.json
+// NESTED under the namespace key for DocRenderer types (developer/database/testing) —
+// because DocRenderer resolves keys as t('<namespace>.overview.objective').
+// You author FLAT content; scaffold-doc wraps it under the namespace for these types.
+// (user-type standalone docs stay FLAT — no root key, resolved via t('title').)
 {
-  "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."
-        }
+  "docsSupportSla": {
+    "overview": {
+      "objective": "Gestion des niveaux de service (SLA)"
+    },
+    "faq": {
+      "1": {
+        "question": "Dois-je configurer chaque SLA manuellement ?",
+        "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
       }
     }
   }

package/templates/skills/documentation/steps/step-01-scan.md

@@ -1,113 +1,59 @@
----
-name: Scan - Source Code and Extract Data
-description: Scan source code and existing documentation, extract API endpoints and business rules
-next_step: step-02-generate.md
----
-
-## STEP 01: Scan — Source Code and Existing Documentation
-
-### Purpose
-
-Based on the type detected in step-00, scan the appropriate source and extract data needed for documentation generation.
-
-### Execution By Type
-
-#### For `user` Type (Functional Module)
-
-**MANDATORY FIRST STEP: Read the REAL page TSX before extracting.**
-The Mock UI must match the actual interface, NOT a generic KPI/table layout.
-
-**Workflow:**
-
-1. **Read the REAL page TSX**
-   - Find: `web/smartstack-web/src/pages/{Application}/{Module}Page.tsx` (e.g., `TenantsTemplatePage.tsx`, `UsersPage.tsx`)
-   - Understand the actual layout (cards, table, kanban, etc.)
-   - Note the exact components, icons, badges, stats shown
-
-2. **Extract API Endpoints** from the controller
-   - Locate: `src/SmartStack.Api/Controllers/{Module}Controller.cs` (singularized)
-   - Scan for `[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`
-   - Parse `[NavRoute]`, `[RequirePermission]` attributes
-   - Resolve permission constants from `Permissions.cs`
-
-3. **Extract Business Rules** from Domain entity and tests
-   - Locate: `src/SmartStack.Domain/Entities/{Module}/{Entity}.cs`
-   - Scan for guard clauses: `if (...) throw new DomainException("...")`
-   - Scan validation in Create/Update methods
-   - Find unit tests: `src/SmartStack.Domain.Tests/{Module}/{Entity}Tests.cs`
-   - Look for `[Fact]` test methods and edge case scenarios
-   - Auto-assign BR-XXX IDs and categorize:
-     - **Validation:** Required fields, format checks
-     - **Security:** Password rules, access control
-     - **Business Logic:** State transitions, calculations
-
-#### For `developer` Type (Development Tool)
-
-1. **Locate source reference**
-   - `_resources/developer-tools/` or web search for current versions
-   - Extract: purpose, installation, setup, common commands, screenshots
-
-2. **Reference available developer tools catalog**
-   - 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
-
-#### For `database` Type (Schema)
-
-1. **Locate schema configuration**
-   - Find: `src/SmartStack.Infrastructure/Persistence/Configurations/{Schema}Configuration.cs`
-   - Find: `ApplicationDbContextModelSnapshot.cs` for complete schema
-
-2. **Extract:**
-   - Table structure (columns, types, constraints)
-   - Relationships (foreign keys, one-to-many, many-to-many)
-   - Indexes and unique constraints
-
-#### For `testing` Type (Testing Tool)
-
-1. **Locate testing reference**
-   - Current test patterns in project
-   - External tool documentation (Playwright, NBomber, Snyk, etc.)
-
-2. **Extract:**
-   - Tool purpose and integration points
-   - Test execution patterns
-   - Result interpretation
-
-#### For `update` Type
-
-Re-read the real page TSX and controller to refresh extracted data:
-
-```
-1. Read real page TSX → check if interface changed
-2. Read controller → check for new/modified API endpoints
-3. Read Domain entity → check for new business rules
-4. Gather timestamps for doc-manifest.json update
-```
-
-### Output
-
-At end of this step, collected data:
-
-| Type | Data Collected |
-|------|-----------------|
-| `user` | Real page interface, API endpoints array, Business rules array |
-| `developer` | Tool metadata, setup steps, commands, examples |
-| `database` | Schema structure, relationships, constraints |
-| `testing` | Tool integration, test patterns, execution flow |
-| `update` | Changed UI elements, new endpoints, new rules, new timestamps |
-
-### Success Metrics
-
-- [x] Real page TSX read and interface documented (user type)
-- [x] API endpoints extracted with correct HTTP methods and routes
-- [x] Business rules categorized with BR-IDs and statements
-- [x] Permission constants resolved from Permissions.cs
-- [x] Mock data template identified (5+ realistic records)
-- [x] KPI stats template documented (Total, Active, Status breakdown)
-
-### Next Step
-
-→ **step-02-generate.md** — Generate documentation content based on scanned data.
+---
+name: Scan - Extract via the extract-doc CLI
+description: Run extract-doc to locate the real page, detect chart types, and extract endpoints / business rules / entity props
+next_step: step-02-generate.md
+---
+
+## STEP 01: Scan — run the `extract-doc` CLI
+
+### Purpose
+
+Gather the data needed for generation **deterministically** via the colocated
+`extract-doc` CLI, instead of parsing controllers/entities by hand. The CLI is
+read-only (writes nothing) and returns a JSON report.
+
+### Run it
+
+```bash
+npx tsx skills/documentation/cli/extract-doc/index.ts \
+  --spec '{"type":"user","target":"<module>","application":"<app>","projectPath":"<project-root>"}'
+```
+
+- Optional `"pagePath":"<relative .tsx>"` — force a specific page (skip auto-detection) when you already know which page to document.
+- `<project-root>` is the SmartStack project being documented (its layers are auto-detected — no hardcoded `SmartStack.*` paths).
+
+> **Windows note:** PowerShell mangles the inline JSON quotes when calling `npx`.
+> Invoke through the Bash tool (single-quoted JSON passes literally) or escape
+> every `"` as `\"`.
+
+### Read the `report`
+
+| Field | Use |
+|-------|-----|
+| `resolved.pageTsxPath` | **READ this file** and reproduce it faithfully as annotated Mock UI (do NOT invent a generic table/KPI layout). If `null`, author from the live app / pagespec. |
+| `resolved.pageCandidatesTried` | Other pages that matched — pick a different one via `pagePath` if the auto-pick is wrong. |
+| `charts[]` | For each chart, `mockUiPattern` tells you the faithful Mock UI shape (recharts type → histogram / donut / line / area). `rechartsType: null` = inspect the source yourself. |
+| `apiEndpoints[]` | Real endpoints (method, path, handler, resolved permission) for the Technical Reference section. |
+| `businessRules[]` | Domain guard rules (deduped) — raw material; **curate**, don't dump verbatim. |
+| `entity.properties[]` | Drives realistic form fields / table columns / mock records. |
+| `namespace`, `navRoute`, `suggestedRoutes` | Feed these into `scaffold-doc` in step-03. |
+| `existingDoc.forbiddenSections[]` | **Forbidden "sales" framing already in the EXISTING doc** (problème/solution, Bénéfices, Avant/Après) — each `{ file, line, token }`. **Non-empty → you MUST strip these while regenerating** (step-02). The step-03 gate re-runs this scan and blocks until empty. |
+| `existingDoc.missingRequired[]` | **Mandatory elements ABSENT from the EXISTING doc** (the mirror check). `"objective"` = no Objectif Section 1; `"summary"` (user) = no header accent tagline. **Non-empty → you MUST add them while regenerating** (step-02). The step-03 gate blocks until empty. |
+
+### developer / database / testing types
+
+`extract-doc` returns a thin report for these (they are authored from tool /
+schema knowledge, not project code). Gather as before:
+- **database** — read `…/Persistence/Configurations/*.cs` + the model snapshot for tables/relationships.
+- **developer / testing** — tool docs (WebSearch for current versions), integration points, commands.
+
+### Success metrics
+
+- [x] `extract-doc` ran and returned `success: true`
+- [x] (user) real page located and **read** before any Mock UI is written
+- [x] (user) each chart's recharts type noted for faithful reproduction
+- [x] endpoints + business rules + entity props captured as raw material to curate
+
+### Next step
+
+→ **step-02-generate.md** — author the doc content, then run `scaffold-doc`.