@atlashub/smartstack-cli 4.76.0 → 4.80.0

package/templates/skills/migrate/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: migrate
+description: Migrate an existing SmartStack client project from one platform version to another (currently v3.34 → v3.46). Detects the current version, applies declarative rules (renames, signature updates, layout consolidation, theme tokens), then runs validation checks. Designed for clients on older CLI versions who want to upgrade without redoing /apex from scratch.
+argument-hint: "[--from=<version>] [--to=<version>] [--scope=backend|frontend|all] [--dry-run] [--apply]"
+model: sonnet
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write
+---
+
+## Current state (auto-injected)
+
+- Project root: !`pwd 2>/dev/null`
+- Detected SmartStack package version: !`grep -oP '"@atlashub/smartstack":\s*"\K[^"]+' web/smartstack-web/package.json 2>/dev/null || cat src/SmartStack.Api/*.csproj 2>/dev/null | grep -oP 'SmartStack[A-Za-z.]*"\s*Version="\K[^"]+' | head -1 || echo "unknown"`
+- Detected legacy patterns: !`grep -rl "ApplicationZone\|<\(AdminLayout\|BusinessLayout\|UserLayout\)" src/ web/ 2>/dev/null | head -5 || echo "none"`
+- Last migration run: !`cat .claude/cache/migrate.json 2>/dev/null | head -3 || echo "no previous run"`
+
+<objective>
+Patch an existing client project (one already generated by an older CLI version) so that it conforms to the latest SmartStack platform version. Current rule set covers `v3.34 → v3.46` (the breaking changes shipped in iteration 1 of the v3.46 alignment work : `ApplicationZone` removal, layout consolidation 7→4, NavigationApplication.Create signature change, Tailwind tokenization).
+
+This skill exists because :
+- A client app generated on CLI v3.34 has `Zone = ApplicationZone.Business` hardcoded everywhere — **cannot compile** against v3.46 NuGet packages.
+- Re-running `/apex` from scratch would lose the client's business logic.
+- Manually patching is error-prone (40+ files to touch on a real project).
+
+The rules are **declarative** (in `references/v3.34-to-v3.46.md`), so adding a new migration target later is just a new reference doc + a register entry.
+</objective>
+
+<quick_start>
+```bash
+/migrate                              # Detect version + dry-run report
+/migrate --from=3.34 --to=3.46        # Explicit version pair
+/migrate --dry-run                    # Print proposed changes without writing
+/migrate --apply                      # Apply all rules (asks confirmation per category)
+/migrate --scope=frontend --apply     # Only frontend rules
+/migrate --scope=backend --apply      # Only backend rules
+```
+</quick_start>
+
+<subcommands>
+
+| Command | Effect |
+|---|---|
+| `/migrate` (no args) | Auto-detect from→to, run dry-run, print report |
+| `/migrate --from=X --to=Y` | Force version pair (for testing) |
+| `/migrate --dry-run` | Default — report only, no file edits |
+| `/migrate --apply` | Apply rules. Asks confirmation per category (backend / frontend / seed / config) |
+| `/migrate --scope=<s>` | Restrict to one layer |
+| `/migrate --rules` | List all available migration paths and their rule files |
+
+</subcommands>
+
+<workflow>
+
+## Step 0 — Detect from-version (if not provided)
+
+```bash
+# Look at @atlashub/smartstack version
+PKG_VER=$(grep -oP '"@atlashub/smartstack":\s*"\K[^"]+' web/smartstack-web/package.json 2>/dev/null | sed 's/[\^~]//g' | cut -d. -f1-2)
+
+# Look at SmartStack NuGet versions
+NUGET_VER=$(grep -hPoR 'PackageReference\s+Include="SmartStack[^"]*"\s+Version="\K[^"]+' src/ 2>/dev/null | sort -u | head -1 | cut -d. -f1-2)
+
+# Look at legacy patterns to confirm
+HAS_ZONE=$(grep -rl "ApplicationZone\." src/ 2>/dev/null | wc -l)
+HAS_LEGACY_LAYOUT=$(grep -rlE "<(AdminLayout|BusinessLayout|UserLayout|HRLayout|SalesLayout)\b" web/ src/ 2>/dev/null | wc -l)
+
+# Decide source version
+if [ "$HAS_ZONE" -gt 0 ] || [ "$HAS_LEGACY_LAYOUT" -gt 0 ]; then
+  FROM_VERSION="3.34"   # Pre-v3.46 platform
+else
+  FROM_VERSION="${PKG_VER:-unknown}"
+fi
+```
+
+## Step 1 — Pick the rule file
+
+Map `(from, to)` to a rule file under `references/` :
+
+| from → to | Rule file |
+|---|---|
+| `3.34 → 3.46` | [references/v3.34-to-v3.46.md](references/v3.34-to-v3.46.md) |
+| (future) `3.46 → 3.47` | references/v3.46-to-v3.47.md |
+| any unsupported pair | abort with explicit error + suggested manual path |
+
+Load the rule file and parse the rule list (each rule has `id`, `category`, `description`, `detect_pattern`, `replace_pattern`, `glob`, `severity`, `requires_confirmation`).
+
+## Step 2 — Detect applicable rules (dry-run)
+
+For each rule in the file :
+
+1. Run the `detect_pattern` (grep) over `glob` paths to find candidate files
+2. Compute the matched count
+3. If 0 matches : skip (already migrated)
+4. If ≥ 1 match : add to "applicable rules" list
+
+Build the dry-run report :
+
+```
+================================================================================
+              MIGRATION DRY-RUN — {from} → {to}
+================================================================================
+Project root: {pwd}
+Source version detected: {FROM_VERSION}  (via {package.json | NuGet | legacy patterns})
+Rule file:  references/v{from}-to-v{to}.md  ({total_rules} rules)
+
+[BACKEND]  ({applicable_be_count} of {total_be_count} rules applicable)
+
+  R-BE-001  ApplicationZone enum removal
+            severity: BLOCKING   files: 6
+            sample:  src/SmartStack.Infrastructure/Persistence/Seeding/Data/NavigationApplicationSeedData.cs:23
+                     Zone = ApplicationZone.Business
+
+  R-BE-002  NavigationApplication.Create signature
+            severity: BLOCKING   files: 2
+            sample:  src/SmartStack.Infrastructure/.../SeedDataProvider.cs:46
+                     NavigationApplication.Create(ApplicationZone.Business, code, label, ...)
+
+  R-BE-003  AddDbContext alias rename (if applicable)
+            severity: WARNING    files: 0    (no occurrence — skipped)
+
+[FRONTEND]  ({applicable_fe_count} of {total_fe_count} rules applicable)
+
+  R-FE-001  Legacy domain-specific layouts (AdminLayout, BusinessLayout, UserLayout, …)
+            severity: BLOCKING   files: 4
+            sample:  web/smartstack-web/src/App.tsx:127
+                     <Route path="/sales" element={<SalesLayout />}>
+
+  R-FE-002  Hardcoded Tailwind colors → CSS vars
+            severity: WARNING    files: 12
+
+  R-FE-003  mergeRoutes() → PageRegistry.register()
+            severity: BLOCKING   files: 1
+
+[SEED]  ({applicable_seed_count} of {total_seed_count} rules applicable)
+  …
+
+[CONFIG]  ({applicable_cfg_count} of {total_cfg_count} rules applicable)
+  …
+
+--------------------------------------------------------------------------------
+SUMMARY : {total_applicable} rules applicable across {total_files} files
+          {blocking} BLOCKING — must be fixed before the project compiles against v{to}
+          {warning} WARNING — should be fixed soon
+================================================================================
+```
+
+If `--dry-run` (default) → stop here, exit 0.
+
+## Step 3 — Apply mode (`--apply`)
+
+Group applicable rules by **category** (BACKEND / FRONTEND / SEED / CONFIG). For each category :
+
+```yaml
+AskUserQuestion:
+  header: "Apply BACKEND rules?"
+  question: "{N} BACKEND rules will modify {M} files (e.g. R-BE-001, R-BE-002). Apply?"
+  options:
+    - label: "Yes, apply all BACKEND rules"
+      description: "Run all BLOCKING + WARNING rules in this category"
+    - label: "Yes, BLOCKING only"
+      description: "Apply only BLOCKING (safer for review)"
+    - label: "Skip this category"
+      description: "Don't touch BACKEND files"
+    - label: "Review one by one"
+      description: "Confirm before each rule"
+```
+
+For each rule the user accepts :
+1. Read each candidate file
+2. Apply the `replace_pattern` (often a regex substitution, sometimes a whole-block rewrite — see rule definition)
+3. Save the file
+4. Track the change in a per-rule changelog
+
+After every rule in the batch is applied, build the post-apply report and run **post-validation** (Step 4).
+
+## Step 4 — Post-validation
+
+```bash
+# Backend compilation (smoke test)
+if [ "$SCOPE" != "frontend" ]; then
+  cd src/SmartStack.Api 2>/dev/null && dotnet build --nologo 2>&1 | tail -20 | tee /tmp/migrate-build-be.log
+fi
+
+# Frontend compilation
+if [ "$SCOPE" != "backend" ]; then
+  cd web/smartstack-web 2>/dev/null && npx tsc -b --noEmit 2>&1 | tail -20 | tee /tmp/migrate-build-fe.log
+fi
+
+# Run apex post-checks if available
+if [ -f templates/skills/apex/references/checks/seed-checks.sh ]; then
+  bash templates/skills/apex/references/checks/seed-checks.sh 2>&1 | tail -30
+fi
+```
+
+Print the validation report. If errors remain : explicit list of "manual fixes still needed" + suggested next action (`/debug` skill).
+
+## Step 5 — Cache and summary
+
+```bash
+mkdir -p .claude/cache
+cat > .claude/cache/migrate.json << EOF
+{
+  "lastRun": "$(date -Iseconds)",
+  "from": "{from}",
+  "to": "{to}",
+  "scope": "{scope}",
+  "rulesApplied": {N},
+  "filesChanged": {M},
+  "buildPassed": {true|false},
+  "remainingIssues": {K}
+}
+EOF
+```
+
+Print a final summary :
+
+```
+================================================================================
+              MIGRATION COMPLETE — {from} → {to}
+================================================================================
+Rules applied : {N} ({blocking} BLOCKING, {warning} WARNING)
+Files changed : {M}
+Build status  : {OK | FAILED}
+Manual fixes  : {K} remaining (see /tmp/migrate-build-*.log)
+
+Next steps :
+  1. Review changes: git diff
+  2. Run tests: dotnet test + npm test
+  3. Commit migration: /gitflow commit
+  4. If issues remain: /debug
+================================================================================
+```
+
+## Step 6 — Exit code
+
+- 0 if all rules applied and build passes
+- 1 if any rule failed to apply (likely needs manual intervention)
+- 2 if build doesn't pass after migration
+
+</workflow>
+
+<safety>
+
+- **Always run dry-run first** : the default mode. Forces the user to see the diff before any file is touched.
+- **Per-category confirmation** in `--apply` mode. No "yes to all" shortcut.
+- **Backup is the user's responsibility** — recommend `git stash` or `git commit` before running `--apply`. The skill will print this as a banner.
+- **Some rules cannot be safely automated** : signature changes that depend on context. Those rules have `requires_confirmation: true` in the rule file, and the skill walks through them one by one.
+- **Never modify files outside the project root** (cwd). Defensive `pwd`-based path resolution.
+
+</safety>
+
+<rule_file_format>
+
+Each `references/v{from}-to-v{to}.md` file contains a YAML-fenced rule list :
+
+````markdown
+# Migration rules: v{from} → v{to}
+
+```yaml
+rules:
+  - id: R-BE-001
+    category: backend
+    description: ApplicationZone enum removed in v3.46
+    detect_pattern: "ApplicationZone\\.\\w+"
+    replace_pattern: |
+      # Custom multi-line replacement (see "implementations" below)
+    glob: "src/**/Seeding/Data/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: false
+    references:
+      - templates/skills/apex/references/core-seed-data.md
+      - templates/skills/application/references/provider-template.md
+
+  - id: R-BE-002
+    category: backend
+    …
+```
+
+## Implementations
+
+Some rules are too complex for a single regex. The "implementation" section
+provides a step-by-step Bash/sed/Edit recipe per rule.
+
+### R-BE-001 — ApplicationZone removal
+
+For each file matching the glob :
+1. Remove the line `Zone = ApplicationZone.Business,`
+2. Insert two lines :  `IsPersonal = false,` and `IsOpen = false,`
+3. … (full recipe)
+````
+
+The skill parses the YAML block, then for each rule with `requires_confirmation: true` it falls back to the implementation recipe (read + execute step by step).
+
+</rule_file_format>
+
+<known_limitations>
+
+- **Single migration path supported today** : `v3.34 → v3.46`. Adding `v3.46 → v3.47` is a new rule file, not a code change.
+- **No multi-hop chaining yet** : if a project is on `v3.20`, you can't go straight to `v3.46`. Manual intervention required.
+- **Doesn't migrate database schema** — rules are code-only. Schema migration is `/efcore migration` territory.
+- **Heuristic version detection** : if `package.json` lacks `@atlashub/smartstack`, the skill falls back to grepping legacy patterns. Always confirm the detected version before `--apply`.
+
+</known_limitations>
+
+<success_criteria>
+- Detects current SmartStack version from project artifacts
+- Picks the correct rule file based on (from, to)
+- Dry-run report lists every applicable rule with file/line evidence
+- Apply mode confirms per category before touching files
+- Post-validation runs `dotnet build` and `tsc --noEmit` to catch new compile errors
+- Cache record allows subsequent `/migrate` runs to skip already-applied rules
+- Exit code reflects success/failure for CI scripting
+</success_criteria>

package/templates/skills/migrate/references/v3.34-to-v3.46.md

@@ -0,0 +1,289 @@
+# Migration rules: v3.34 → v3.46
+
+> Used by `/migrate --from=3.34 --to=3.46`.
+> Covers the breaking changes shipped during the v3.46 alignment work
+> (ApplicationZone removal, layout consolidation, NavigationApplication.Create
+> signature change, Tailwind tokenisation, mergeRoutes deprecation, AI patterns).
+
+## Rule list (machine-readable)
+
+```yaml
+rules:
+  # ──────────────────────────────────────────────────────────────────
+  # BACKEND — Domain / Seed / API
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-BE-001
+    category: backend
+    description: "ApplicationZone enum and Zone column removed (replaced by IsPersonal + IsOpen flags on NavigationApplication)."
+    detect_pattern: 'ApplicationZone\.\w+|Zone\s*=\s*ApplicationZone\.\w+|public\s+ApplicationZone\s+Zone'
+    glob: "src/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: false
+    references:
+      - templates/skills/apex/references/core-seed-data.md
+      - templates/skills/application/references/provider-template.md
+      - templates/skills/apex/references/checks/seed-checks.sh   # check C66 enforces this
+
+  - id: R-BE-002
+    category: backend
+    description: "NavigationApplication.Create() signature lost the first 'zone' parameter; gained isOpen + isPersonal at the end (both default false)."
+    detect_pattern: 'NavigationApplication\.Create\(\s*ApplicationZone\.\w+'
+    glob: "src/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: true   # contextual — review each call site
+    references:
+      - D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Navigation/NavigationApplication.cs
+
+  - id: R-BE-003
+    category: backend
+    description: "ApplicationMenuDto.Zone (string) field removed; consume IsPersonal + IsOpen instead."
+    detect_pattern: '\.Zone\b|"Zone"'
+    glob: "src/SmartStack.Application/Navigation/**/*.cs"
+    severity: BLOCKING
+    requires_confirmation: true
+
+  - id: R-BE-004
+    category: backend
+    description: "Migration to drop the 'Zone' column and add IsPersonal/IsOpen columns. Generate via dotnet ef if missing."
+    detect_pattern: 'Zone'
+    glob: "src/SmartStack.Infrastructure/Persistence/Migrations/*.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "If the project's last migration is older than core_v3.46.0, prompt user to run /efcore:migration RemoveApplicationZone."
+
+  - id: R-BE-005
+    category: backend
+    description: "Domain Hooks moved to SmartStack.Application.Common.Interfaces.Hooks namespace (previously: scattered)."
+    detect_pattern: 'SmartStack\.(?:Domain|Application)\.(?!Common\.Interfaces\.Hooks)\w+\.(?:IBeforeCreate|IAfterCreate|IBeforeUpdate|IAfterUpdate|IBeforeDelete|IAfterDelete)'
+    glob: "src/**/*.cs"
+    severity: WARNING
+    requires_confirmation: false
+    references:
+      - templates/skills/apex/references/smartstack-api.md   # Entity Lifecycle Hooks section
+
+  - id: R-BE-006
+    category: backend
+    description: "BaseEntity gained an ExtensionData (string JSON) property + 7 typed methods. EF configuration must include builder.Property(x => x.ExtensionData).HasColumnType(\"nvarchar(max)\").HasDefaultValue(\"{}\")."
+    detect_pattern: 'class\s+\w+Configuration\s*:\s*IEntityTypeConfiguration<\w+>'
+    glob: "src/SmartStack.Infrastructure/Persistence/Configurations/**/*.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Inspect each EF config file; only add the ExtensionData mapping where the entity inherits BaseEntity AND the table is meant to store extension data."
+
+  # ──────────────────────────────────────────────────────────────────
+  # FRONTEND — Layouts / Routing / Theme
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-FE-001
+    category: frontend
+    description: "Legacy domain-specific layouts (AdminLayout / BusinessLayout / UserLayout / HRLayout / SalesLayout) consolidated into AppLayout (sole authenticated shell)."
+    detect_pattern: '<\s*(AdminLayout|BusinessLayout|UserLayout|HRLayout|SalesLayout)\b|from\s+["\x27][^"\x27]*\/(AdminLayout|BusinessLayout|UserLayout|HRLayout|SalesLayout)["\x27]'
+    glob: "web/**/*.tsx"
+    severity: BLOCKING
+    requires_confirmation: false
+    references:
+      - templates/skills/application/references/frontend-route-naming.md
+      - templates/skills/apex/references/checks/seed-checks.sh   # check C67
+
+  - id: R-FE-002
+    category: frontend
+    description: "Hardcoded Tailwind colors must be replaced by CSS variables. Mapping table in themes-db-driven.md (24 rows: bg-blue-* → var(--info-bg), text-gray-900 → var(--text-primary), etc.)."
+    detect_pattern: '(bg|text|border)-(?!\[)(red|blue|green|gray|amber|yellow|orange|purple|indigo|violet|cyan|pink|emerald|rose|sky|teal|lime|fuchsia|stone|slate|zinc|neutral)-\d'
+    glob: "web/**/*.tsx"
+    severity: WARNING   # was BLOCKING in iteration 2 — but for a migration we relax to WARNING and let the user batch-fix
+    requires_confirmation: true
+    references:
+      - templates/skills/application/references/themes-db-driven.md   # Section 5: Migration map
+      - templates/skills/apex/references/checks/frontend-checks.sh    # check C9
+
+  - id: R-FE-003
+    category: frontend
+    description: "Tailwind dark: prefix removed. SmartStack toggles a .dark class on root; CSS vars adapt automatically."
+    detect_pattern: '\bdark:(bg|text|border)-'
+    glob: "web/**/*.tsx"
+    severity: WARNING
+    requires_confirmation: false
+
+  - id: R-FE-004
+    category: frontend
+    description: "mergeRoutes() and getStaticAppRoutes() removed in v3.7+. Pages must register via PageRegistry.register() in componentRegistry.generated.ts."
+    detect_pattern: 'mergeRoutes\s*\(|getStaticAppRoutes\s*\('
+    glob: "web/**/*.{ts,tsx}"
+    severity: BLOCKING
+    requires_confirmation: true
+    references:
+      - templates/skills/audit-route/references/routing-pattern.md
+      - templates/skills/application/references/smartstack-provider.md
+
+  - id: R-FE-005
+    category: frontend
+    description: "RouteGuard.tsx replaced by ProtectedRoute.tsx (API-driven permissions)."
+    detect_pattern: 'RouteGuard|from\s+["\x27][^"\x27]*\/RouteGuard["\x27]'
+    glob: "web/**/*.{ts,tsx}"
+    severity: BLOCKING
+    requires_confirmation: false
+
+  - id: R-FE-006
+    category: frontend
+    description: "useParams must use generic { id: string } (not custom names like { ticketId, userId }). Custom names go in the destructuration."
+    detect_pattern: 'useParams<\{\s*(?!id\s*:)\w+Id\s*:'
+    glob: "web/**/*.tsx"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Refactor: const { id: ticketId } = useParams<{ id: string }>(). Param URL must be 'id' for DynamicRouter."
+
+  - id: R-FE-007
+    category: frontend
+    description: "Client App.tsx must wrap with <SmartStackProvider config={...}> (replaces ad-hoc provider stacks)."
+    detect_pattern: 'AuthProvider|TenantProvider|ThemeProvider'   # if present in App.tsx without SmartStackProvider above
+    glob: "web/**/{App,main}.tsx"
+    severity: WARNING
+    requires_confirmation: true
+    references:
+      - templates/skills/application/references/smartstack-provider.md
+
+  # ──────────────────────────────────────────────────────────────────
+  # SEED — Navigation & Roles
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-SEED-001
+    category: seed
+    description: "NavigationApplicationSeedEntry must include IsPersonal + IsOpen (both bool, default false). Replaces the Zone field."
+    detect_pattern: 'NavigationApplicationSeedEntry'
+    glob: "src/**/*NavigationApplicationSeedData.cs"
+    severity: BLOCKING
+    requires_confirmation: false
+
+  - id: R-SEED-002
+    category: seed
+    description: "MySpace and Personal-scope apps should set IsPersonal = true."
+    detect_pattern: 'NavigationApplicationSeedEntry'
+    glob: "src/**/*MySpace*SeedData.cs"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Manual judgement: only set IsPersonal=true on apps that genuinely belong to user space."
+
+  # ──────────────────────────────────────────────────────────────────
+  # CONFIG — appsettings / package.json
+  # ──────────────────────────────────────────────────────────────────
+
+  - id: R-CFG-001
+    category: config
+    description: "@atlashub/smartstack peer must be at least 3.46.0."
+    detect_pattern: '"@atlashub/smartstack":\s*"\^?[0-2]\.|^"@atlashub/smartstack":\s*"\^?3\.[0-3][0-9]\.|^"@atlashub/smartstack":\s*"\^?3\.4[0-5]\.'
+    glob: "web/smartstack-web/package.json"
+    severity: BLOCKING
+    requires_confirmation: false
+    note: "Bump @atlashub/smartstack to ^3.46.0 (or latest)."
+
+  - id: R-CFG-002
+    category: config
+    description: "Tailwind v4 + @tailwindcss/vite required. Old @tailwindcss/postcss configuration deprecated."
+    detect_pattern: '"@tailwindcss/postcss"'
+    glob: "web/smartstack-web/package.json"
+    severity: WARNING
+    requires_confirmation: false
+    note: "Install @tailwindcss/vite, remove @tailwindcss/postcss, update vite.config.ts plugins list."
+
+  - id: R-CFG-003
+    category: config
+    description: "appsettings.json should include the new sections : SlaMonitoring, SolutionAutoClose, AutoAssignment, WorkflowExecution (added in v3.45/v3.46)."
+    detect_pattern: '^\s*"(?:Logging|Email)\s*"'
+    glob: "src/SmartStack.Api/appsettings.json"
+    severity: WARNING
+    requires_confirmation: true
+    note: "Compare against templates/project/appsettings.json.template ; add missing sections (defaults are safe)."
+```
+
+## Implementation recipes
+
+The rules above are declarative ; some need a step-by-step recipe when a single regex isn't enough. The skill's `--apply` mode falls back to these recipes for any rule with `requires_confirmation: true`.
+
+### R-BE-001 — `ApplicationZone` removal
+
+For each file matched :
+
+1. Remove every line that matches `^\s*Zone\s*=\s*ApplicationZone\.\w+,?\s*$`
+2. After the line `Id = ApplicationId,` (or the first property of the SeedEntry), insert :
+   ```
+   IsPersonal = false,
+   IsOpen = false,
+   ```
+3. Replace `public ApplicationZone Zone { get; init; }` (DTO) by :
+   ```csharp
+   public bool IsPersonal { get; init; }
+   public bool IsOpen { get; init; }
+   ```
+4. Remove `using` directives for `SmartStack.Domain.Navigation` if `ApplicationZone` was the only reason they were imported.
+
+### R-BE-002 — `NavigationApplication.Create()` signature
+
+For each call site :
+
+- Old signature : `NavigationApplication.Create(ApplicationZone.X, code, label, description, icon, iconType, route, displayOrder)`
+- New signature : `NavigationApplication.Create(code, label, description, icon, iconType, route, displayOrder, isOpen: bool, isPersonal: bool)`
+
+**Recipe** :
+1. Remove the first argument (`ApplicationZone.X`).
+2. Append two named arguments at the end : `isOpen: false, isPersonal: false` (or `true` based on context — see R-SEED-002).
+3. **Manual review** : if the original call passed `Personal` zone, propose `isPersonal: true`. If `Admin` zone (system app), propose `isOpen: true`.
+
+### R-FE-001 — Layout consolidation
+
+For each `.tsx` file containing `<AdminLayout>`, `<BusinessLayout>`, `<UserLayout>`, `<HRLayout>`, or `<SalesLayout>` :
+
+1. Replace the JSX tag (open + close) by `<AppLayout>` / `</AppLayout>`.
+2. Update the import : `import { AppLayout } from '@/layouts/AppLayout'`.
+3. Remove the old import line.
+
+If the file was `src/layouts/AdminLayout.tsx` (or similar), DELETE the file — it no longer has a purpose.
+
+### R-FE-002 — Tailwind tokenisation
+
+This rule is **bulk** but **noisy**. Apply only if the user accepts (default WARNING in migration ; was BLOCKING in iteration 2).
+
+Use the migration map in `templates/skills/application/references/themes-db-driven.md` Section 5. For each `(bg|text|border)-{color}-{shade}` occurrence, propose the canonical CSS-var replacement based on context :
+- Status badges (success/warning/error/info) → `var(--{status}-bg)` / `var(--{status}-text)` / `var(--{status}-border)`
+- Action buttons → `var(--color-accent-600)` / `hover:bg-[var(--color-accent-700)]`
+- Body text → `var(--text-primary)` / `var(--text-secondary)`
+- Card backgrounds → `var(--bg-card)`
+- Borders → `var(--border-color)`
+
+When the context is ambiguous (e.g. random `bg-blue-100`), prompt for the intent (info badge ? accent ? branding ?) and apply accordingly.
+
+### R-FE-004 — `mergeRoutes` / `getStaticAppRoutes` removal
+
+These calls usually live in `src/main.tsx` or `src/App.tsx`. Recipe :
+
+1. Open the file.
+2. Find the call to `mergeRoutes(...)` or `getStaticAppRoutes(...)`.
+3. For each route registered :
+   - Convert to `PageRegistry.register('module.section', lazy(() => import(...)))`
+   - Place those calls in `src/extensions/componentRegistry.generated.ts` (create the file if missing).
+4. Remove the original `mergeRoutes` call ; remove its imports.
+5. Ensure `main.tsx` imports `./extensions/componentRegistry.generated` early (before render).
+
+This is a refactor — the skill SHOULD prompt the user to confirm and provide a diff preview.
+
+### R-CFG-002 — Tailwind v4 migration
+
+```bash
+# Inside web/smartstack-web/
+npm uninstall @tailwindcss/postcss
+npm install --save-dev @tailwindcss/vite
+
+# Edit vite.config.ts:
+#  + import tailwindcss from '@tailwindcss/vite';
+#  + plugins: [react(), tailwindcss()],
+
+# Edit index.css to use the new @theme {} syntax (see themes-db-driven.md Section 3.3)
+```
+
+The skill prompts and applies one step at a time, since these touch different files.
+
+## Notes
+
+- This rule file is the single source of truth for `v3.34 → v3.46`. Add new rules here as breaking changes are discovered.
+- For future migrations (e.g. `v3.46 → v3.47`), create `references/v3.46-to-v3.47.md` and register it in the SKILL.md mapping table.
+- Always run with `--dry-run` first. Always commit before `--apply`.