@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/documentation/steps/step-03-validate.md

@@ -1,238 +1,251 @@
----
-name: Validate - Completeness and Integration
-description: Validate documentation completeness, accuracy, and integrate into SmartStack app
-next_step: null
----
-
-## STEP 03: Validate — Completeness and Integration
-
-### Purpose
-
-Validate that generated documentation is complete and accurate, then integrate into the SmartStack app with proper routing and i18n configuration.
-
-### Validation Checklist
-
-#### All Types
-
-- [ ] Documentation page renders correctly in React app
-- [ ] i18n files created in ALL 4 languages (FR, EN, DE, IT)
-- [ ] Files saved to correct directory paths
-- [ ] docs-manifest.json updated with new entry
-- [ ] NO "Benefices" or "Avant/Apres" sections present
-
-#### For `user` Type Only
-
-- [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
-- [ ] Every Mock UI section has `Annotation` components explaining each visual element
-- [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
-- [ ] Route registered in App.tsx
-- [ ] Module appears in UserIndexPage.tsx (if applicable)
-- [ ] DocPanelContext.tsx mapping updated for all module routes
-- [ ] i18n/config.ts updated with new namespace
-- [ ] BookOpen edge button opens correct doc for the module's routes
-
-#### For `developer|database|testing` Types
-
-- [ ] i18n JSON uses root key matching namespace
-- [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
-- [ ] doc-data.ts contains structured data (~50 lines)
-- [ ] Route registered in App.tsx and parent indexes
-
-#### For `update` Type
-
-- [ ] Mock UI updates reflect current interface
-- [ ] API endpoints verified against current controller
-- [ ] Business rules updated with any new validation rules
-- [ ] docs-manifest.json timestamps refreshed
-- [ ] All 4 language files updated
-
-### Integration Steps
-
-#### UserIndexPage Integration (TYPE: user only)
-
-**MANDATORY** for `user` modules: Add the module to the navigation hierarchy.
-
-| File | Modification |
-|------|--------------|
-| `UserIndexPage.tsx` | Add icon + entry in `modules[]` of parent application |
-| `fr/docs.json` | Add `user.modules.{module}.name` and `.description` |
-| `en/docs.json` | Add `user.modules.{module}.name` and `.description` |
-
-**Parent applications:**
-- `Administration`: admin modules (users, roles, ai, entra...)
-- `Support`: support modules (tickets, sla, templates...)
-- `MySpace`: personal modules (profile, preferences...)
-
-**Verification:** The module should appear on `/docs/user` under its application.
-
-#### DocPanelContext Integration (TYPE: user only)
-
-**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.
-
-**File to update:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
-
-**What to add:** For each module, add entries in the `docMapping` object for ALL the module's routes:
-
-```typescript
-const docMapping: Record<string, string> = {
-  // Administration > {Module}
-  '{module}': '/docs/business/administration/{module}',
-  '{module}/list': '/docs/business/administration/{module}',
-  '{module}/create': '/docs/business/administration/{module}',
-  '{module}/dashboard': '/docs/business/administration/{module}',
-  // ... add ALL sub-routes that exist for the module
-};
-```
-
-**Also update `appDocMapping`** if the module is the "default" for its application:
-
-```typescript
-const appDocMapping: Record<string, string> = {
-  'administration': '/docs/business/administration/users',  // default for admin
-};
-```
-
-**Key resolution logic:** The `getDocUrlForPath()` function extracts segments from the pathname:
-- `/administration/users/list` → tries `users/list`, then `users`
-- `/support/tickets/123` → tries `tickets/123`, then `tickets`
-
-#### App.tsx Routing
-
-**For `user` type:** Add dynamic import and route:
-
-```tsx
-const {Module}DocPage = lazy(() =>
-  import('@/pages/docs/business/{application}/{module}')
-);
-
-// In routes array:
-{
-  path: '/docs/business/{application}/{module}',
-  element: <Suspense><{Module}DocPage /></Suspense>
-}
-```
-
-**For `developer|database|testing` types:** Add to appropriate category:
-
-```tsx
-const {Tool}DocPage = lazy(() =>
-  import('@/pages/docs/developer/{category}/{tool}')
-);
-
-// In routes array:
-{
-  path: '/docs/developer/{category}/{tool}',
-  element: <Suspense><{Tool}DocPage /></Suspense>
-}
-```
-
-#### i18n Config Update
-
-**File:** `web/smartstack-web/src/i18n/config.ts`
-
-Add the new namespace to `loadLanguageResources`:
-
-```typescript
-// 1. Add to destructured imports
-const {
-  docsAdministrationUsers,
-  docsAdministrationPermissions,
-  docsAdministrationNewModule, // NEW
-  // ...
-} = resources;
-
-// 2. Add dynamic import with fallback
-const docsAdministrationNewModule = await import(
-  '@i18n/docs-administration-new-module.json'
-).catch(() => ({ default: {} }));
-
-// 3. Add to return object
-return {
-  // ...
-  docsAdministrationNewModule,
-};
-
-// 4. Add to ns array in i18n.init()
-ns: [
-  'common',
-  'nav',
-  'docsAdministrationUsers',
-  'docsAdministrationPermissions',
-  'docsAdministrationNewModule', // NEW
-  // ...
-]
-```
-
-#### docs-manifest.json Update
-
-Add or update entry with metadata:
-
-```json
-{
-  "id": "{module}",
-  "type": "user",
-  "title": "Module Title",
-  "application": "administration",
-  "path": "/docs/business/administration/{module}",
-  "created_at": "2026-02-17T10:30:00Z",
-  "refreshed_at": "2026-02-17T10:30:00Z",
-  "i18n_namespace": "docsAdministration{Module}",
-  "routes": [
-    "{module}",
-    "{module}/list",
-    "{module}/create"
-  ]
-}
-```
-
-### Data Sources Reference
-
-| Data | Source |
-|------|--------|
-| DB schemas | `src/SmartStack.Infrastructure/Persistence/Configurations/` |
-| Tables | `ApplicationDbContextModelSnapshot.cs` |
-| Existing documentation | `web/smartstack-web/src/pages/docs/` |
-| Testing tools | WebSearch (current versions) |
-| Real UI pages | `web/smartstack-web/src/pages/{Application}/` |
-| Controllers | `src/SmartStack.Api/Controllers/` |
-| Domain entities | `src/SmartStack.Domain/Entities/` |
-| Permissions | `src/SmartStack.Domain/Authorization/Permissions.cs` |
-
-### Associated Files Reference
-
-- **React Templates:** `templates.md`
-- **Data Schema:** `data-schema.md`
-- **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
-- **Types:** `web/smartstack-web/src/components/docs/types.ts`
-- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
-- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
-- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
-- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
-- **Manifest Schema:** `_resources/docs-manifest-schema.md`
-- **Complete Command:** `.claude/commands/documentation-module.md`
-
-### Success Metrics
-
-- [x] Documentation page renders correctly in React app
-- [x] Mock UI faithfully reproduces the real page interface (user type)
-- [x] Every Mock UI section has `Annotation` components (user type)
-- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
-- [x] Route registered in App.tsx
-- [x] docs-manifest.json updated
-- [x] i18n/config.ts updated with new namespace
-- [x] Module appears in UserIndexPage (if type = user)
-- [x] DocPanelContext.tsx mapping updated (if type = user)
-- [x] BookOpen edge button opens correct doc for the module's routes
-- [x] NO "Benefices" or "Avant/Apres" sections present
-- [x] All tests pass and app builds successfully
-
-### Completion
-
-**Documentation workflow complete.** The generated documentation is now:
-- Fully integrated into SmartStack app
-- Accessible via routing system
-- Accessible via DocPanel contextual button
-- Internationalized in FR, EN, DE, IT
-- Listed in docs-manifest.json for discovery
-
-**Next:** Monitor for feedback on documentation accuracy and completeness. Use step-03 validation checklist for future updates.
+---
+name: Validate - Completeness and Integration
+description: Validate documentation completeness, accuracy, and integrate into SmartStack app
+next_step: null
+---
+
+## STEP 03: Validate — Completeness and Integration
+
+### Purpose
+
+Validate that generated documentation is complete and accurate, then integrate into the SmartStack app with proper routing and i18n configuration.
+
+### Validation Checklist
+
+#### All Types
+
+- [ ] Documentation page renders correctly in React app
+- [ ] i18n files created in ALL 4 languages (FR, EN, DE, IT)
+- [ ] Files saved to correct directory paths
+- [ ] docs-manifest.json updated with new entry
+- [ ] NO "Benefices" or "Avant/Apres" sections present
+
+#### For `user` Type Only
+
+- [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
+- [ ] Every Mock UI section has `Annotation` components explaining each visual element
+- [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
+- [ ] Route registered in App.tsx
+- [ ] Module appears in UserIndexPage.tsx (if applicable)
+- [ ] DocPanelContext.tsx mapping updated for all module routes
+- [ ] i18n/config.ts updated with new namespace
+- [ ] BookOpen edge button opens correct doc for the module's routes
+
+#### For `developer|database|testing` Types
+
+- [ ] i18n JSON uses root key matching namespace
+- [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
+- [ ] doc-data.ts contains structured data (~50 lines)
+- [ ] Route registered in App.tsx and parent indexes
+
+#### For `update` Type
+
+- [ ] Mock UI updates reflect current interface
+- [ ] API endpoints verified against current controller
+- [ ] Business rules updated with any new validation rules
+- [ ] docs-manifest.json timestamps refreshed
+- [ ] All 4 language files updated
+
+### Integration Steps
+
+#### UserIndexPage Integration (TYPE: user only)
+
+**MANDATORY** for `user` modules: Add the module to the navigation hierarchy.
+
+| File | Modification |
+|------|--------------|
+| `UserIndexPage.tsx` | Add icon + entry in `modules[]` of parent application |
+| `fr/docs.json` | Add `user.modules.{module}.name` and `.description` |
+| `en/docs.json` | Add `user.modules.{module}.name` and `.description` |
+
+**Parent applications:**
+- `Administration`: admin modules (users, roles, ai, entra...)
+- `Support`: support modules (tickets, sla, templates...)
+- `MySpace`: personal modules (profile, preferences...)
+
+**Verification:** The module should appear on `/docs/user` under its application.
+
+#### DocPanelContext Integration (TYPE: user only)
+
+**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.
+
+**File to update:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+
+**What to add:** For each module, add entries in the `docMapping` object for ALL the module's routes.
+Keys MUST be prefixed with the application code to avoid ambiguity:
+
+```typescript
+const docMapping: Record<string, string> = {
+  // Administration > {Module}
+  'administration/{module}': '/docs/business/administration/{module}',
+  'administration/{module}/list': '/docs/business/administration/{module}',
+  'administration/{module}/create': '/docs/business/administration/{module}',
+  'administration/{module}/dashboard': '/docs/business/administration/{module}',
+  // ... add ALL sub-routes that exist for the module
+
+  // Support > {Module}
+  'support/{module}': '/system/docs/user/support-{module}',
+  // ... add ALL sub-routes
+
+  // MySpace > {Module}
+  'myspace/{module}': '/system/docs/user/modules',
+  // ... add ALL sub-routes
+};
+```
+
+**Also update `appDocMapping`** if the module is the "default" for its application:
+
+```typescript
+const appDocMapping: Record<string, string> = {
+  'administration': '/docs/business/administration/users',  // default for admin
+  'support': '/system/docs/user/support-dashboard',
+  'myspace': '/system/docs/user/modules',
+};
+```
+
+**Key resolution logic:** The `getDocUrlForPath()` function extracts segments from the pathname,
+detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app}/{module}/...`:
+- `/administration/users/list` → tries `administration/users/list`, then `administration/users`
+- `/support/tickets/123` → tries `support/tickets/123`, then `support/tickets`
+- `/t/my-company/administration/users` → strips tenant prefix, then tries `administration/users`
+
+#### App.tsx Routing
+
+**For `user` type:** Add dynamic import and route:
+
+```tsx
+const {Module}DocPage = lazy(() =>
+  import('@/pages/docs/business/{application}/{module}')
+);
+
+// In routes array:
+{
+  path: '/docs/business/{application}/{module}',
+  element: <Suspense><{Module}DocPage /></Suspense>
+}
+```
+
+**For `developer|database|testing` types:** Add to appropriate category:
+
+```tsx
+const {Tool}DocPage = lazy(() =>
+  import('@/pages/docs/developer/{category}/{tool}')
+);
+
+// In routes array:
+{
+  path: '/docs/developer/{category}/{tool}',
+  element: <Suspense><{Tool}DocPage /></Suspense>
+}
+```
+
+#### i18n Config Update
+
+**File:** `web/smartstack-web/src/i18n/config.ts`
+
+Add the new namespace to `loadLanguageResources`:
+
+```typescript
+// 1. Add to destructured imports
+const {
+  docsAdministrationUsers,
+  docsAdministrationPermissions,
+  docsAdministrationNewModule, // NEW
+  // ...
+} = resources;
+
+// 2. Add dynamic import with fallback
+const docsAdministrationNewModule = await import(
+  '@i18n/docs-administration-new-module.json'
+).catch(() => ({ default: {} }));
+
+// 3. Add to return object
+return {
+  // ...
+  docsAdministrationNewModule,
+};
+
+// 4. Add to ns array in i18n.init()
+ns: [
+  'common',
+  'nav',
+  'docsAdministrationUsers',
+  'docsAdministrationPermissions',
+  'docsAdministrationNewModule', // NEW
+  // ...
+]
+```
+
+#### docs-manifest.json Update
+
+Add or update entry with metadata:
+
+```json
+{
+  "id": "{module}",
+  "type": "user",
+  "title": "Module Title",
+  "application": "administration",
+  "path": "/docs/business/administration/{module}",
+  "created_at": "2026-02-17T10:30:00Z",
+  "refreshed_at": "2026-02-17T10:30:00Z",
+  "i18n_namespace": "docsAdministration{Module}",
+  "routes": [
+    "{module}",
+    "{module}/list",
+    "{module}/create"
+  ]
+}
+```
+
+### Data Sources Reference
+
+| Data | Source |
+|------|--------|
+| DB schemas | `src/SmartStack.Infrastructure/Persistence/Configurations/` |
+| Tables | `ApplicationDbContextModelSnapshot.cs` |
+| Existing documentation | `web/smartstack-web/src/pages/docs/` |
+| Testing tools | WebSearch (current versions) |
+| Real UI pages | `web/smartstack-web/src/pages/{Application}/` |
+| Controllers | `src/SmartStack.Api/Controllers/` |
+| Domain entities | `src/SmartStack.Domain/Entities/` |
+| Permissions | `src/SmartStack.Domain/Authorization/Permissions.cs` |
+
+### Associated Files Reference
+
+- **React Templates:** `templates.md`
+- **Data Schema:** `data-schema.md`
+- **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
+- **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
+- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
+- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
+- **Manifest Schema:** `_resources/docs-manifest-schema.md`
+- **Complete Command:** `.claude/commands/documentation-module.md`
+
+### Success Metrics
+
+- [x] Documentation page renders correctly in React app
+- [x] Mock UI faithfully reproduces the real page interface (user type)
+- [x] Every Mock UI section has `Annotation` components (user type)
+- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
+- [x] Route registered in App.tsx
+- [x] docs-manifest.json updated
+- [x] i18n/config.ts updated with new namespace
+- [x] Module appears in UserIndexPage (if type = user)
+- [x] DocPanelContext.tsx mapping updated (if type = user)
+- [x] BookOpen edge button opens correct doc for the module's routes
+- [x] NO "Benefices" or "Avant/Apres" sections present
+- [x] All tests pass and app builds successfully
+
+### Completion
+
+**Documentation workflow complete.** The generated documentation is now:
+- Fully integrated into SmartStack app
+- Accessible via routing system
+- Accessible via DocPanel contextual button
+- Internationalized in FR, EN, DE, IT
+- Listed in docs-manifest.json for discovery
+
+**Next:** Monitor for feedback on documentation accuracy and completeness. Use step-03 validation checklist for future updates.