@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -1,280 +1,101 @@
----
-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 added as **child** of `/docs/business` group (not standalone) in DynamicRouter.tsx
-- [ ] DocsLayout sidebar updated (if applicable)
-- [ ] 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 added as **child** of `/system/docs` group (not standalone) in DynamicRouter.tsx
-- [ ] DocsLayout sidebar updated (if applicable)
-
-#### 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`
-
-#### DynamicRouter.tsx Routing
-
-Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:
-
-- **`/docs/business`** → Business module docs (user type) — uses `<DocsLayout />`
-- **`/system/docs`** → Developer/database/testing docs — uses `<DocsLayout />`
-
-> **Note:** The `<Suspense fallback={<PageLoader />}>` is already in place at the global level (wrapping the entire Routes tree). Do NOT add per-route `<Suspense>` wrappers.
-
-**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group in `DynamicRouter.tsx`:
-
-```tsx
-// 1. Add lazy import at top of DynamicRouter.tsx
-const {Module}DocPage = lazy(() =>
-  import('@/pages/docs/business/{application}/{module}')
-);
-
-// 2. Find the existing <Route path="/docs/business" element={<DocsLayout />}> group
-//    Add as CHILD route (not standalone):
-<Route path="/docs/business" element={<DocsLayout />}>
-  {/* ... existing doc routes ... */}
-  <Route path="{application}/{module}" element={<{Module}DocPage />} />
-</Route>
-```
-
-**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group in `DynamicRouter.tsx`:
-
-```tsx
-// 1. Add lazy import at top of DynamicRouter.tsx
-const {Tool}DocPage = lazy(() =>
-  import('@/pages/docs/{category}/{tool}')
-);
-
-// 2. Find the existing <Route path="/system/docs" element={<DocsLayout />}> group
-//    Add as CHILD route:
-<Route path="/system/docs" element={<DocsLayout />}>
-  {/* ... existing doc routes ... */}
-  <Route path="{category}/{tool}" element={<{Tool}DocPage />} />
-</Route>
-```
-
-#### DynamicRouter Documentation Routes
-
-Documentation routes are statically defined in `DynamicRouter.tsx` (not dynamically generated from the navigation API). When adding new documentation pages, add the lazy import and `<Route>` entry in the documentation section of `DynamicRouter.tsx`.
-
-#### DocsLayout Sidebar Update
-
-If the new documentation page should appear in the sidebar navigation, update the `navigation` array in `DocsLayout.tsx` with the new entry (label, path, icon).
-
-#### Important Notes
-
-- Documentation routes do **NOT** use `AppLayout`, `ProtectedRoute`, or `LicenseGuard`
-- Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
-- Documentation routes require **no specific permission** to access
-
-#### 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 added as child of correct DocsLayout group in DynamicRouter.tsx
-- [x] Route added in DynamicRouter.tsx documentation section
-- [x] DocsLayout sidebar updated (if applicable)
-- [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 - ui-polish + verify wiring
+description: Enforce theme tokens via the ui-polish CLI, verify the scaffold-doc outputs + applied wiring, then typecheck
+next_step: null
+---
+
+## STEP 03: Validate — ui-polish + verify integration
+
+`scaffold-doc` (step-02) already wrote the i18n files, upserted
+`docs-manifest.json`, and handed you the wiring plan you applied. This step
+**enforces colours deterministically** and **verifies** the result.
+
+### 0. Structure gate (blocking)
+
+The doc must lead with a factual **objective** and carry **no** value-proposition
+pitch (SKILL.md rule #12). Re-run `extract-doc` on the module and assert the scan
+of the **now-generated** artifacts is both clean and complete:
+
+```bash
+npx tsx skills/documentation/cli/extract-doc/index.ts \
+  --spec '{"type":"<type>","target":"<module>","application":"<app>","projectPath":"<project-root>"}'
+```
+
+Two mirror conditions, both hard gates:
+
+- **`report.existingDoc.forbiddenSections` MUST be empty.** If non-empty, the doc
+  is **not** done: for each `{ file, line, token }`, remove the offending section
+  (problème/solution, Bénéfices, Avant/Après — see step-02 "Correcting an existing
+  doc"), then re-run until it returns 0.
+- **`report.existingDoc.missingRequired` MUST be empty.** It can list:
+  - `"objective"` — the mandatory Section 1 is absent: add the **Objectif** section
+    first (i18n `sections.objective` + `objective`, or `overview.objective` for
+    DocRenderer; rendered via `t('objective')`) — the header subtitle does NOT count.
+  - `"summary"` (user) — the header accent tagline is absent: add the `summary` key
+    and render it between title and subtitle (`text-xl … text-[var(--color-accent-600)]`),
+    with the inline stats line.
+
+  Fix each and re-run until it returns 0.
+
+This reuses the exact same deterministic detection as step-01 — no separate rules.
+
+### 1. Colour / theme compliance → run ui-polish
+
+Theme-token compliance is NOT checked by hand here — the ui-polish CLI does it.
+Run it on the generated page (apply mode, regeneration disabled so the page is
+never rebuilt — only colour utilities are rewritten):
+
+```bash
+npx tsx skills/development/frontend/ui-polish/cli/ui-polish/index.ts \
+  --project-path "<web-root>" --mode apply --regenerate-threshold 0 \
+  --page "src/pages/docs/business/<group>/<app>/<module>/index.tsx" \
+  --rules R2,R3,R7,R12,R13,R14,R15,R16,R17
+```
+
+Then re-run in `--mode audit` and confirm **0 errors**. Finish the residual
+neutral cases the CLI flags (see the `/ui-components` skill). Doc-specific intent
+the CLI can't infer — verify by eye: dashboard chart series use `--dataviz-*`
+(not accent), highlight blocks use the discreet accent pattern.
+
+### 2. Verify the scaffold-doc outputs
+
+- [ ] 4 i18n files at `src/i18n/locales/{fr,en,de,it}/docs-{kebab}.json` — `user` FLAT (no root key); `developer/database/testing` nested under the namespace key
+- [ ] `docs-manifest.json` has the entry (correct `id`, `path`, `i18nNamespace`, `languages`)
+- [ ] **Wiring applied** (each plan item's `idempotencyMarker` now present):
+  - `i18n/config.ts` — namespace in all 4 spots (destructured var, `import()`, return object, `ns: [ … ]`)
+  - `components/routing/DocRoutes.tsx` — lazy import + `<Route>` child under the `/docs/business` group
+  - `contexts/DocPanelContext.tsx` — `docMapping` keys (+ `appDocMapping` if default)
+  - `pages/system/docs/user/UserIndexPage.tsx` — module entry (user type) + its `user.modules.<x>.name/.description` i18n keys
+
+### 3. Quality checks (user type — the Mock UI is yours)
+
+- [ ] Mock UI faithfully reproduces the real page (not a generic KPI/table)
+- [ ] Each chart matches the real recharts TYPE (from `extract-doc` `charts[]`)
+- [ ] Expressive mock data: ratio max/min(>0) ≥ 5x, peak ≥ 90% + valley ≤ 15%, height ≥ `h-24`/`h-20`
+- [ ] Every Mock UI block has an `Annotation`, inside the same padded container
+- [ ] No DocPanel overflow: `overflow-hidden` on chart cards, `min-w-0` on flex children, no fixed px widths
+- [ ] Root container `<div className="space-y-8 max-w-5xl mx-auto pb-12">` (no horizontal padding)
+- [ ] Section 1 is **Objectif** (description of what the module does) — no problème/solution, Bénéfices or Avant-Après (enforced by the §0 gate)
+
+### 4. Typecheck
+
+At the web root: `npm run typecheck` (or `tsc --noEmit`) — phantom imports or a
+malformed wiring edit fail here. Fix before finishing.
+
+### Artifact reference (verified against the app)
+
+| Artifact | Path |
+|----------|------|
+| User doc page | `src/pages/docs/business/{platform\|personal}/{app}/{module}/index.tsx` (route omits the `platform/personal` segment) |
+| i18n (central) | `src/i18n/locales/{lang}/docs-{kebab}.json` (FLAT for user; nested under the namespace for DocRenderer) |
+| i18n registration | `src/i18n/config.ts` |
+| Routing | `src/components/routing/DocRoutes.tsx` (NOT `DynamicRouter.tsx` — it only calls `{DocRoutes()}`) |
+| Manifest | `src/pages/docs/docs-manifest.json` |
+| Contextual panel | `src/contexts/DocPanelContext.tsx` |
+| User index | `src/pages/system/docs/user/UserIndexPage.tsx` |
+
+### Completion
+
+Documentation is generated, themed (ui-polish), wired, internationalised (4 langs)
+and listed in the manifest. Route renders inside `DocsLayout`; the DocPanel edge
+button opens it for the module's routes.