@atlashub/smartstack-cli 4.75.0 → 4.79.0

package/templates/skills/cli-app-sync/references/diff-entities.md

@@ -0,0 +1,162 @@
+# `/cli-app-sync diff-entities` — Reference
+
+> Detailed algorithm and rules for the `diff-entities` sub-mode of `/cli-app-sync`.
+
+## What it solves
+
+The default `cli-app-sync` mode compares **known file pairs** (Program.cs ↔ Program.cs.template, vite.config.ts ↔ inline `init.ts`, etc.). It is good at catching **explicit drift** in those known surfaces.
+
+It is blind to **trous** : when SmartStack.app introduces a brand-new entity (e.g. `AiTool` in v3.46) that no skill in `templates/skills/` mentions, nothing fires. The drift only surfaces during a manual audit (which is what just happened in the v3.46 alignment iteration 3 — 7 uncovered entities discovered by reading the `Domain/` directory by hand).
+
+`diff-entities` automates that audit : it enumerates every Domain entity and reports those without coverage in the CLI skills.
+
+## Inputs
+
+| Variable | Default | Source |
+|---|---|---|
+| `APP_PATH` | `D:/01 - projets/SmartStack.app/features/IA-Workflow` | `--app-path=...` flag, otherwise the IA-Workflow branch (current source of truth) |
+| `CLI_SKILLS` | `D:/01 - projets/SmartStack.cli/02-Develop/templates/skills` | hardcoded |
+| `MIN_REFS` | `3` | a "well-covered" entity has at least 3 mentions across templates |
+
+## Step-by-step algorithm
+
+### 1. Enumerate Domain entities (the haystack)
+
+Pattern (Bash + grep) :
+```bash
+APP_DOMAIN="$APP_PATH/src/SmartStack.Domain"
+
+grep -rPnh \
+  "^\s*public\s+(?:partial\s+)?(?:abstract\s+)?(?:class|record)\s+([A-Z][A-Za-z0-9]+)\s*:?\s*(?:BaseEntity|I[A-Z][A-Za-z]+Entity|IDomainEvent|DomainEvent)\b" \
+  "$APP_DOMAIN" --include='*.cs' \
+  | sed -E "s/.*\b(?:class|record)\s+([A-Z][A-Za-z0-9]+).*/\1/" \
+  | sort -u > /tmp/app-entities.txt
+```
+
+This captures :
+- Classes inheriting `BaseEntity` (most aggregate roots)
+- Classes implementing `IXxxEntity` interfaces (`ITenantEntity`, `IOptionalTenantEntity`, …)
+- Domain events (inheriting `DomainEvent` or implementing `IDomainEvent`)
+
+It deliberately excludes :
+- Pure value objects (no marker interface)
+- Internal helper classes
+- DTOs (those live in `Application/`)
+
+If you suspect an entity is missed, broaden the regex or add a manual entry in the exclusion list.
+
+### 2. Count references in CLI skills (the needles)
+
+For each entity name `E`, count how many `templates/skills/**/*.md|*.sh` files mention it as a whole word :
+
+```bash
+CLI_SKILLS="D:/01 - projets/SmartStack.cli/02-Develop/templates/skills"
+
+while IFS= read -r ENT; do
+  COUNT=$(grep -rl --include='*.md' --include='*.sh' -E "\\b${ENT}\\b" "$CLI_SKILLS" | wc -l)
+  echo -e "${ENT}\t${COUNT}"
+done < /tmp/app-entities.txt > /tmp/entity-coverage.tsv
+```
+
+Counting **distinct files** (not occurrences) is intentional — 50 mentions in one file ≈ 1 file with deep coverage, not 50 files of shallow coverage.
+
+### 3. Classify
+
+| Bucket | Rule | Action |
+|---|---|---|
+| `[NEW UNCOVERED]` | `count == 0` | Propose a skill destination (table below) |
+| `[THIN]` | `1 <= count < MIN_REFS` (default `MIN_REFS=3`) | Suggest extending an existing skill or adding a dedicated `references/` doc |
+| `[COVERED]` | `count >= MIN_REFS` | Hide from report unless `--verbose` |
+
+### 4. Suggest a skill destination
+
+Map the entity's namespace to a target skill :
+
+```python
+def suggest_skill(namespace, entity_name):
+    rules = [
+        ("Domain.AI.Evaluations",   "ai-prompt/references/eval-framework.md"),
+        ("Domain.AI.Tools",          "ai-prompt"),
+        ("Domain.AI.Agents",         "ai-prompt"),
+        ("Domain.AI.Skills",         "ai-prompt"),
+        ("Domain.AI",                "ai-prompt"),
+        ("Domain.Communications.Workflow",      "workflow"),
+        ("Domain.Communications.EmailTemplate", "notification"),
+        ("Domain.Communications",               "workflow"),
+        ("Domain.Navigation",                   "application"),
+        ("Domain.Platform.Administration.UiConfiguration", "application/references/themes-db-driven.md"),
+        ("Domain.Platform.Administration",      "application"),
+        ("Domain.Licensing",                    "apex/references/smartstack-api.md (Licensing section)"),
+        ("Domain.Common",                       "apex/references/smartstack-api.md"),
+        ("Domain.Support",                      "notification"),
+        ("Application.Common.Interfaces.Hooks", "apex/references/smartstack-api.md (Entity Lifecycle Hooks)"),
+    ]
+    for prefix, skill in rules:
+        if namespace.startswith(prefix):
+            return skill
+    return f"NEW SKILL — propose name based on namespace: {namespace.split('.')[-1].lower()}"
+```
+
+When the namespace doesn't match any rule, propose a brand-new skill name derived from the leaf segment.
+
+### 5. Render the report
+
+See the example output in `SKILL.md` (`<diff_entities_workflow>` section).
+
+Sort order : `[NEW UNCOVERED]` first, then `[THIN]`, then (only with `--verbose`) `[COVERED]`. Within each bucket, alphabetical.
+
+## Exclusion list
+
+Some entities are intentionally NOT documented by any skill — they are infrastructure plumbing the SDK abstracts away. Maintain this list manually :
+
+```
+EXCLUDED_ENTITIES = {
+    # Marker / framework types — not domain concepts
+    "DomainEvent",          # abstract base, not a concrete event
+    "BaseEntity",           # already documented in smartstack-api.md
+    "EntityScope",          # enum, documented inline
+
+    # Internal helpers — not part of the public SDK
+    # (add as needed)
+}
+```
+
+Implementation : after step 1, filter out names in this set before counting.
+
+## Output flags
+
+| Flag | Effect |
+|---|---|
+| `--verbose` | Show `[COVERED]` entities too (debugging) |
+| `--report-only` | Don't write cache, print to stdout only |
+| `--app-path=<path>` | Override the default APP_PATH (e.g. testing against `02-Develop` or another branch) |
+| `--min-refs=<n>` | Custom threshold for `[THIN]` vs `[COVERED]` (default 3) |
+| `--json` | Output machine-readable JSON instead of human report |
+
+## Exit code
+
+- 0 if zero entities classified `[NEW UNCOVERED]`
+- 1 otherwise (so `diff-entities` can be a CI quality gate)
+
+`[THIN]` entities do NOT fail the gate — they're warnings.
+
+## Performance
+
+- Step 1 (enumerate) : ~200-400 ms (grep over `Domain/` ≈ 100 files)
+- Step 2 (count) : ~2-5 s (grep over `templates/skills/` ≈ 350 files × N entities)
+- Total : < 10 s for a typical run — eligible for pre-commit hooks and CI
+
+## Limitations
+
+- **Heuristic regex for entity discovery** : may miss entities that don't follow the `class X : BaseEntity` pattern. Augment with explicit lookups for known patterns if false negatives appear.
+- **Word-boundary count** : `AiTool` matches `AiTool` exactly but also matches a `AiTool` mention in a code comment. Acceptable noise — the goal is to spot zero-reference entities.
+- **No DTO / Service coverage** : the skill only enumerates Domain entities. DTOs and Services live in `Application/` and are not in scope (they're typically auto-generated by MCP, so missing skill coverage is less impactful).
+- **Doesn't catch DELETED entities** : if an entity is removed from app but still cited in skills, this skill won't flag it. Use the existing `cli-app-sync report` for that direction.
+
+## Relation to other skills / checks
+
+- **`cli-app-sync report`** : detects **content drift** in known file pairs. Complementary, not redundant.
+- **`smoke-generation --quick`** : detects **broken imports** (the EntityLookup paradox). Catches references to things the CLI invented but the app doesn't have. `diff-entities` catches the inverse direction.
+- **`apex-verify`** : runs after generation, catches generated code that doesn't follow conventions. Operates at a different layer.
+
+Together, the trio `cli-app-sync report` + `cli-app-sync diff-entities` + `smoke-generation` covers the full bidirectional drift surface.

package/templates/skills/dev-start/SKILL.md

@@ -87,9 +87,9 @@ echo "=== MODE ==="
 echo "=== ENV ==="
 cat web/smartstack-web/.env.development 2>/dev/null || cat web/smartstack-web/.env.standalone 2>/dev/null || echo "NONE"
 echo "=== SQL ==="
-CS=$(grep -oP '"DefaultConnection":\s*"\K[^"]+' src/SmartStack.Api/appsettings.json 2>/dev/null)
-SN=$(echo "$CS" | grep -oiP '(?:Server|Data Source)=\K[^;]+' | sed 's/(local)/./')
-DB=$(echo "$CS" | grep -oiP '(?:Database|Initial Catalog)=\K[^;]+')
+CS=$(sed -n 's/.*"DefaultConnection":\s*"\([^"]*\)".*/\1/p' src/SmartStack.Api/appsettings.json 2>/dev/null)
+SN=$(echo "$CS" | sed -n 's/.*[Ss]erver=\([^;]*\).*/\1/p' | sed 's/(local)/./')
+DB=$(echo "$CS" | sed -n 's/.*[Dd]atabase=\([^;]*\).*/\1/p')
 sqlcmd -S "$SN" -Q "SET NOCOUNT ON;SELECT name FROM sys.databases WHERE name='$DB'" -t 5 -E -C -h -1 -W 2>/dev/null | grep -q "$DB" && echo "ok $SN $DB" || echo "warn $SN $DB"
 ```
 
@@ -177,8 +177,8 @@ for i in $(seq 1 20); do
   sleep 2
 done
 RESULT=$(timeout 20 smartstack admin reset --connection '{connection_string}' --force --json 2>&1 | grep -E '^\{')
-EMAIL=$(echo "$RESULT" | grep -oP '"email":"\K[^"]+')
-PASS=$(echo "$RESULT" | grep -oP '"password":"\K[^"]+')
+EMAIL=$(echo "$RESULT" | sed -n 's/.*"email":"\([^"]*\)".*/\1/p')
+PASS=$(echo "$RESULT" | sed -n 's/.*"password":"\([^"]*\)".*/\1/p')
 cat > .claude/dev-session.json << SESSEOF
 {"admin_email":"$EMAIL","admin_password":"$PASS","last_reset":"$(date -Iseconds)","api_port":{api_port},"web_port":{web_port},"environment":"{mode}","status":"ready"}
 SESSEOF
@@ -189,8 +189,8 @@ echo "CREDENTIALS: $EMAIL / $PASS"
 Single Bash — reset only (no wait needed):
 ```bash
 RESULT=$(timeout 20 smartstack admin reset --connection '{connection_string}' --force --json 2>&1 | grep -E '^\{')
-EMAIL=$(echo "$RESULT" | grep -oP '"email":"\K[^"]+')
-PASS=$(echo "$RESULT" | grep -oP '"password":"\K[^"]+')
+EMAIL=$(echo "$RESULT" | sed -n 's/.*"email":"\([^"]*\)".*/\1/p')
+PASS=$(echo "$RESULT" | sed -n 's/.*"password":"\([^"]*\)".*/\1/p')
 cat > .claude/dev-session.json << SESSEOF
 {"admin_email":"$EMAIL","admin_password":"$PASS","last_reset":"$(date -Iseconds)","api_port":{api_port},"web_port":{web_port},"environment":"{mode}","status":"ready"}
 SESSEOF

package/templates/skills/documentation/templates.md

@@ -116,7 +116,7 @@ import { Info } from 'lucide-react';
 
 function Annotation({ text }: { text: string }) {
   return (
-    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-blue-500/5 border border-blue-500/15 text-sm text-blue-700 dark:text-blue-400">
+    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-[var(--info-bg)] border border-[var(--info-border)] text-sm text-[var(--info-text)]">
       <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
       <span>{text}</span>
     </div>
@@ -168,7 +168,7 @@ import {
 // ═══════════════════════════════════════════════════
 function Annotation({ text }: { text: string }) {
   return (
-    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-blue-500/5 border border-blue-500/15 text-sm text-blue-700 dark:text-blue-400">
+    <div className="flex items-start gap-2 p-2.5 rounded-lg bg-[var(--info-bg)] border border-[var(--info-border)] text-sm text-[var(--info-text)]">
       <Info className="w-4 h-4 mt-0.5 flex-shrink-0" />
       <span>{text}</span>
     </div>
@@ -231,14 +231,14 @@ export default function {Module}DocPage() {
         <div className="card p-6">
           <div className="mb-6">
             <h3 className="font-semibold mb-3 flex items-center gap-2">
-              <Target className="w-5 h-5 text-red-500" />
+              <Target className="w-5 h-5 text-[var(--error-text)]" />
               {t('sections.problem')}
             </h3>
             <p className="text-[var(--text-secondary)]">{t('problem')}</p>
           </div>
 
-          <div className="p-4 rounded-lg bg-green-500/10 border border-green-500/20">
-            <h3 className="font-semibold mb-2 flex items-center gap-2 text-green-700">
+          <div className="p-4 rounded-lg bg-[var(--success-bg)] border border-[var(--success-border)]">
+            <h3 className="font-semibold mb-2 flex items-center gap-2 text-[var(--success-text)]">
               <Lightbulb className="w-5 h-5" />
               {t('sections.solution')}
             </h3>
@@ -371,8 +371,8 @@ export default function {Module}DocPage() {
           {[1, 2, 3].map((i) => (
             <div key={i} className="card p-6">
               <div className="flex items-center gap-3 mb-4">
-                <div className="w-10 h-10 rounded-full bg-blue-500/10 flex items-center justify-center">
-                  <Users className="w-5 h-5 text-blue-600" />
+                <div className="w-10 h-10 rounded-full bg-[var(--accent-bg)] flex items-center justify-center">
+                  <Users className="w-5 h-5 text-[var(--accent-text)]" />
                 </div>
                 <div>
                   <div className="font-semibold">{t(`useCases.${i}.persona`)}</div>
@@ -384,8 +384,8 @@ export default function {Module}DocPage() {
                   <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
                   <p>{t(`useCases.${i}.situation`)}</p>
                 </div>
-                <div className="text-sm p-3 rounded-lg bg-green-500/5 border border-green-500/15">
-                  <span className="font-medium text-green-600">Avec la fonctionnalite:</span>
+                <div className="text-sm p-3 rounded-lg bg-[var(--success-bg)] border border-[var(--success-border)]">
+                  <span className="font-medium text-[var(--success-text)]">Avec la fonctionnalite:</span>
                   <p>{t(`useCases.${i}.withFeature`)}</p>
                 </div>
               </div>
@@ -454,7 +454,7 @@ export default function {Module}DocPage() {
       <section id="reference" className="scroll-mt-4">
         <details className="card">
           <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-semibold flex items-center gap-2">
-            <span className="w-8 h-8 rounded-full bg-gray-500/10 text-gray-600 flex items-center justify-center text-sm">9</span>
+            <span className="w-8 h-8 rounded-full bg-[var(--bg-tertiary)] text-[var(--text-secondary)] flex items-center justify-center text-sm">9</span>
             {t('sections.technicalRef')}
           </summary>
           <div className="p-6 pt-2 space-y-8">
@@ -499,12 +499,12 @@ export default function {Module}DocPage() {
                     {apiEndpoints.map((ep, i) => (
                       <tr key={i} className="border-b border-[var(--border-color)]">
                         <td className="py-2 px-3">
-                          <span className={`px-2 py-0.5 rounded text-xs font-medium ${
-                            ep.method === 'GET' ? 'bg-blue-500/10 text-blue-600' :
-                            ep.method === 'POST' ? 'bg-green-500/10 text-green-600' :
-                            ep.method === 'PUT' ? 'bg-orange-500/10 text-orange-600' :
-                            ep.method === 'PATCH' ? 'bg-purple-500/10 text-purple-600' :
-                            'bg-red-500/10 text-red-600'
+                          <span className={`px-2 py-0.5 rounded text-xs font-medium border ${
+                            ep.method === 'GET'    ? 'bg-[var(--info-bg)] text-[var(--info-text)] border-[var(--info-border)]' :
+                            ep.method === 'POST'   ? 'bg-[var(--success-bg)] text-[var(--success-text)] border-[var(--success-border)]' :
+                            ep.method === 'PUT'    ? 'bg-[var(--warning-bg)] text-[var(--warning-text)] border-[var(--warning-border)]' :
+                            ep.method === 'PATCH'  ? 'bg-[var(--accent-bg)] text-[var(--accent-text)] border-[var(--accent-border)]' :
+                                                     'bg-[var(--error-bg)] text-[var(--error-text)] border-[var(--error-border)]'
                           }`}>{ep.method}</span>
                         </td>
                         <td className="py-2 px-3 font-mono text-xs">{ep.path}</td>

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>