@atlashub/smartstack-cli 4.37.0 → 4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/efcore/migration.md

@@ -114,48 +114,11 @@ rm Persistence/Migrations/*${OLD_NAME}*.cs
 
 > **Note:** `$MCP_NAME` is obtained via MCP call, never computed locally.
 
-## SQL Objects Post-Injection (MANDATORY after every migration creation)
+## SQL Objects (NO injection needed)
 
-**This step is NON-OPTIONAL.** After EVERY `dotnet ef migrations add`, you MUST check for SQL objects and inject them into the generated migration. Skipping this step causes runtime 500 errors on ALL endpoints (TVFs like `fn_GetUserGroupHierarchy` won't exist in the database).
+SQL objects (TVFs, views, stored procedures) are applied **automatically at application startup** via `SqlObjectHelper.ApplyAllAsync(dbContext)` in `SmartStackExtensions.InitializeSmartStackAsync()`, right after `MigrateAsync()`.
 
-```bash
-# Detect the generated migration file (the main .cs, not .Designer.cs)
-MIGRATION_FILE=$(find "$MIGRATIONS_DIR" -name "*${MCP_NAME}.cs" ! -name "*.Designer.cs" | head -1)
-SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
-SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
-
-if [ "$SQL_FILES" -gt 0 ]; then
-  echo "Found $SQL_FILES SQL object(s) — injecting SqlObjectHelper.ApplyAll()..."
-
-  # Add using directive if not present
-  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
-    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
-  fi
-
-  # Add SqlObjectHelper.ApplyAll at the end of Up() method
-  # Use Edit tool to insert before the closing brace of Up()
-  # Target: the last "        }" before "protected override void Down"
-  sed -i '/protected override void Down/i\
-\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
-\            SqlObjectHelper.ApplyAll(migrationBuilder);' "$MIGRATION_FILE"
-
-  # VERIFY injection succeeded — FAIL if not
-  if ! grep -q "SqlObjectHelper.ApplyAll" "$MIGRATION_FILE"; then
-    echo "ERROR: Auto-injection failed. Use Edit tool to manually add:"
-    echo "  1. Add 'using SmartStack.Infrastructure.Persistence.SqlObjects;' at top"
-    echo "  2. Add 'SqlObjectHelper.ApplyAll(migrationBuilder);' at end of Up() method"
-    echo "  File: $MIGRATION_FILE"
-    # DO NOT CONTINUE — fix this before proceeding
-  else
-    echo "  SqlObjectHelper.ApplyAll(migrationBuilder) injected successfully"
-    find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do echo "  - $f"; done
-  fi
-else
-  echo "No SQL objects found in SqlObjects/ — skipping injection"
-fi
-```
-
-> **CRITICAL:** If the bash `sed` injection fails (indentation mismatch), use the **Edit tool** to manually insert the lines. NEVER skip this step — it causes cascading 500 errors at runtime.
+**You do NOT need to add `SqlObjectHelper.ApplyAll(migrationBuilder)` in migrations.** The startup process handles this with `CREATE OR ALTER` (idempotent). Modifying a `.sql` file only requires an application restart — no new migration needed.
 
 ## Context Detection
 
@@ -230,8 +193,7 @@ After rebase on develop:
 **ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
 
 - All SQL objects (functions, views, procedures, TVFs) MUST be `.sql` files in `Persistence/SqlObjects/`
-- Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` in the `Up()` method
-- If `Persistence/SqlObjects/*.sql` files exist, inject the call automatically after migration creation
+- SQL objects are applied **automatically at startup** via `SqlObjectHelper.ApplyAllAsync()` — no migration injection needed
 - **Never** write raw SQL directly inside migration `Up()` or `Down()` methods
 
 ## Important Notes

package/templates/agents/efcore/rebase-snapshot.md

@@ -26,7 +26,7 @@ fi
 **FORBIDDEN:** Raw SQL inline in migrations (e.g., `migrationBuilder.Sql("CREATE FUNCTION ...")`)
 
 **ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
-Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` — never inline SQL.
+SQL objects are applied **automatically at startup** via `SqlObjectHelper.ApplyAllAsync()` — no migration injection needed.
 
 ## Workflow
 
@@ -70,41 +70,8 @@ mcp__smartstack__suggest_migration({ description: "...", context: DBCONTEXT_TYPE
 
 dotnet ef migrations add "$MIGRATION_NAME" --context "$DBCONTEXT"
 
-# ═══════════════════════════════════════════════════════════════════════════
-# MANDATORY: SQL Objects Post-Injection
-# Without this, TVFs (fn_GetUserGroupHierarchy etc.) won't exist in DB
-# and ALL endpoints will return 500 at runtime
-# ═══════════════════════════════════════════════════════════════════════════
-MIGRATION_FILE=$(find Migrations -name "*${MIGRATION_NAME}.cs" ! -name "*.Designer.cs" | head -1)
-SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
-SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
-
-if [ "$SQL_FILES" -gt 0 ]; then
-  echo "Found $SQL_FILES SQL object(s) — injecting SqlObjectHelper.ApplyAll()..."
-
-  # Add using directive if not present
-  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
-    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
-  fi
-
-  # Inject SqlObjectHelper.ApplyAll before Down() method
-  sed -i '/protected override void Down/i\
-\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
-\            SqlObjectHelper.ApplyAll(migrationBuilder);' "$MIGRATION_FILE"
-
-  # VERIFY — FAIL if injection didn't work
-  if ! grep -q "SqlObjectHelper.ApplyAll" "$MIGRATION_FILE"; then
-    echo "ERROR: Auto-injection failed. Use Edit tool to manually add:"
-    echo "  1. 'using SmartStack.Infrastructure.Persistence.SqlObjects;' at top"
-    echo "  2. 'SqlObjectHelper.ApplyAll(migrationBuilder);' at end of Up()"
-    echo "  File: $MIGRATION_FILE"
-  else
-    echo "  SqlObjectHelper.ApplyAll(migrationBuilder) injected"
-    find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do echo "  - $f"; done
-  fi
-else
-  echo "No SQL objects found — skipping injection"
-fi
+# NOTE: SQL objects (TVFs, views, SPs) are applied automatically at startup
+# via SqlObjectHelper.ApplyAllAsync() — no injection needed in migrations.
 
 # Validate
 dotnet build
@@ -130,7 +97,6 @@ core_v1.7.0_001_ReleaseInitial
 - [ ] Backup created
 - [ ] Build OK after rebase
 - [ ] SQL script can be generated
-- [ ] SQL objects injected (if `Persistence/SqlObjects/*.sql` exists)
 
 ## Error Recovery
 
@@ -140,7 +106,7 @@ core_v1.7.0_001_ReleaseInitial
 | MCP unavailable | Check `.claude/mcp-status.json`, run `/mcp healthcheck` |
 | Snapshot fetch fails | Verify `origin/$BASE_BRANCH` exists: `git fetch origin $BASE_BRANCH` |
 | Migration creation fails | Restore backup, check `dotnet build` output |
-| SQL objects injection fails | Manual step: add `SqlObjectHelper.ApplyAll(migrationBuilder)` in Up() |
+| SQL objects missing at runtime | SQL objects are applied at startup — restart the application |
 
 **Automatic recovery:** On ANY failure after backup:
 1. Restore all files from backup directory

package/templates/agents/efcore/squash.md

@@ -3,7 +3,7 @@ name: efcore-squash
 description: EF Core migration squasher - combine multiple migrations into one
 color: magenta
 model: sonnet
-tools: Bash, Glob, Read
+tools: Bash, Glob, Read, Edit
 ---
 
 # EF Core Squash Agent
@@ -26,7 +26,7 @@ fi
 **FORBIDDEN:** Raw SQL inline in migrations (e.g., `migrationBuilder.Sql("CREATE FUNCTION ...")`)
 
 **ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
-Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` — never inline SQL.
+SQL objects are applied **automatically at startup** via `SqlObjectHelper.ApplyAllAsync()` — no migration injection needed.
 
 ## Core Principle
 
@@ -51,8 +51,7 @@ WARNING: NEVER retrieve only the snapshot without the migrations!
 5. **Fetch**: Retrieve **ModelSnapshot AND migrations** from parent branch (CRUCIAL!)
 6. **Delete**: Remove branch-specific migrations ONLY
 7. **Create**: Create consolidated migration (MCP mandatory)
-8. **Inject SQL Objects**: If `Persistence/SqlObjects/` contains `.sql` files, inject `SqlObjectHelper.ApplyAll(migrationBuilder)` in `Up()`
-9. **Validate**: Build + script OK
+8. **Validate**: Build + script OK
 
 ## Key Commands
 
@@ -100,41 +99,8 @@ mcp__smartstack__suggest_migration({ description: "...", context: DBCONTEXT_TYPE
 
 dotnet ef migrations add "$MIGRATION_NAME_FROM_MCP" --context "$DBCONTEXT"
 
-# ═══════════════════════════════════════════════════════════════════════════
-# MANDATORY: SQL Objects Post-Injection
-# Without this, TVFs (fn_GetUserGroupHierarchy etc.) won't exist in DB
-# and ALL endpoints will return 500 at runtime
-# ═══════════════════════════════════════════════════════════════════════════
-MIGRATION_FILE=$(find Migrations -name "*${MIGRATION_NAME_FROM_MCP}.cs" ! -name "*.Designer.cs" | head -1)
-SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
-SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
-
-if [ "$SQL_FILES" -gt 0 ]; then
-  echo "Found $SQL_FILES SQL object(s) — injecting SqlObjectHelper.ApplyAll()..."
-
-  # Add using directive if not present
-  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
-    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
-  fi
-
-  # Inject SqlObjectHelper.ApplyAll before Down() method
-  sed -i '/protected override void Down/i\
-\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
-\            SqlObjectHelper.ApplyAll(migrationBuilder);' "$MIGRATION_FILE"
-
-  # VERIFY — FAIL if injection didn't work
-  if ! grep -q "SqlObjectHelper.ApplyAll" "$MIGRATION_FILE"; then
-    echo "ERROR: Auto-injection failed. Use Edit tool to manually add:"
-    echo "  1. 'using SmartStack.Infrastructure.Persistence.SqlObjects;' at top"
-    echo "  2. 'SqlObjectHelper.ApplyAll(migrationBuilder);' at end of Up()"
-    echo "  File: $MIGRATION_FILE"
-  else
-    echo "  SqlObjectHelper.ApplyAll(migrationBuilder) injected"
-    find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do echo "  - $f"; done
-  fi
-else
-  echo "No SQL objects found — skipping injection"
-fi
+# NOTE: SQL objects (TVFs, views, SPs) are applied automatically at startup
+# via SqlObjectHelper.ApplyAllAsync() — no injection needed in migrations.
 
 # Validate
 dotnet build && dotnet ef migrations script --idempotent > /dev/null
@@ -149,7 +115,6 @@ dotnet build && dotnet ef migrations script --idempotent > /dev/null
 - [ ] **Parent snapshot retrieved** (origin/$BASE_BRANCH)
 - [ ] **Parent migrations retrieved** (.cs AND .Designer.cs files)
 - [ ] Branch-specific migrations deleted (not inherited ones!)
-- [ ] **SQL Objects injected** (if `Persistence/SqlObjects/*.sql` exists)
 - [ ] Build OK after squash
 - [ ] Script can be generated
 
@@ -189,7 +154,7 @@ Next: /efcore db-reset, /efcore db-deploy
 | MCP unavailable | Check `.claude/mcp-status.json`, run `/mcp healthcheck` |
 | Snapshot fetch fails | Verify `origin/$BASE_BRANCH` exists: `git fetch origin $BASE_BRANCH` |
 | Script generation fails | Restore backup, then investigate migration content |
-| SQL objects injection fails | Manual step: add `SqlObjectHelper.ApplyAll(migrationBuilder)` in Up() |
+| SQL objects missing at runtime | SQL objects are applied at startup — restart the application |
 
 **Automatic recovery:** On ANY failure after backup:
 1. Restore all files from backup directory

package/templates/project/claude-md/infrastructure.CLAUDE.md.template

@@ -152,7 +152,7 @@ dotnet ef migrations remove --context ExtensionsDbContext -p src/{{ProjectName}}
 3. **Repositories** implement interfaces from Application
 4. **DbContext** implements `IExtensionsDbContext` from Application
 5. **Migrations** stay in this project under `Persistence/Migrations/`
-6. **SQL objects via SqlObjectHelper** - TVFs/views use `SqlObjectHelper.ApplyAll(migrationBuilder)` and embedded `.sql` files
+6. **SQL objects via SqlObjectHelper** - TVFs/views use `SqlObjectHelper.ApplyAllAsync()` at startup and embedded `.sql` files (no migration injection needed)
 7. **NO sequential/deterministic GUIDs in seed data** - All GUIDs must be generated via `[guid]::NewGuid()`
 8. **Schema prefix pattern** - Table names use format `{prefix}_{EntityName}` with schema `extensions`. Use `SchemaConstants.Extensions` constant.
 

package/templates/skills/application/references/migration-checklist-troubleshooting.md

@@ -34,24 +34,13 @@ The migration should include:
 - RolePermissions (role assignments)
 - Domain entity table
 - Indexes and constraints
-- SQL Objects injection (if any .sql files exist)
+- SQL Objects: applied automatically at startup (no migration injection needed)
 
 ---
 
-## SQL Objects Injection
+## SQL Objects
 
-Check if any SQL object files exist:
-```
-Glob: **/Persistence/SqlObjects/Functions/*.sql
-```
-
-If SQL files are found, the migration's `Up()` method should include a call to re-apply all SQL objects:
-```csharp
-// At the end of the Up() method:
-SqlObjectHelper.ApplyAll(migrationBuilder);
-```
-
-This ensures SQL functions/views are re-applied with each migration (`CREATE OR ALTER` = idempotent).
+SQL objects (TVFs, views, stored procedures) are applied **automatically at application startup** via `SqlObjectHelper.ApplyAllAsync()` in `SmartStackExtensions.InitializeSmartStackAsync()`. No injection into migrations is needed — just restart the application after modifying `.sql` files.
 
 ---
 
@@ -92,7 +81,6 @@ dotnet ef database update --context CoreDbContext
 - [ ] Migration name suggested via MCP
 - [ ] Migration created with correct context
 - [ ] Migration includes navigation, permissions, and entity table
-- [ ] SQL objects injected (if applicable)
 - [ ] Migration applied successfully
 - [ ] Database updated without errors
 - [ ] DbSet registered in DbContext

package/templates/skills/application/steps/step-06-migration.md

@@ -86,10 +86,6 @@ dotnet ef migrations add {suggested_migration_name} --context ExtensionsDbContex
 > NEVER create subdirectories under `Migrations/` (e.g., `Migrations/Extensions/`).
 > All migrations for a given DbContext MUST share the same namespace to avoid EF Core errors.
 
-### 2b. Inject SQL Objects (if any exist)
-
-See [references/migration-checklist-troubleshooting.md](../references/migration-checklist-troubleshooting.md) for SQL Objects injection pattern.
-
 ### 3. Verify Migration Content
 
 See [references/migration-checklist-troubleshooting.md](../references/migration-checklist-troubleshooting.md) for complete migration content verification checklist.

package/templates/skills/application/templates-seed.md

@@ -955,7 +955,7 @@ Level 4: RESOURCE (finest granularity)
 ## SQL OBJECTS INFRASTRUCTURE
 
 > **Usage:** SQL Server functions (TVFs, scalar), views, and stored procedures managed as embedded resources
-> **Pattern:** Same as SmartStack.app — `CREATE OR ALTER` for idempotency, applied via migrations
+> **Pattern:** Same as SmartStack.app — `CREATE OR ALTER` for idempotency, applied automatically at startup
 > **Location:** `Infrastructure/Persistence/SqlObjects/`
 
 ### Directory Structure
@@ -983,7 +983,7 @@ namespace {BaseNamespace}.Infrastructure.Persistence.SqlObjects;
 
 /// <summary>
 /// Helper for applying SQL objects from embedded resources.
-/// SQL files use CREATE OR ALTER for idempotency — safe to re-run on any migration or squash.
+/// SQL files use CREATE OR ALTER for idempotency — applied automatically at startup.
 /// </summary>
 public static class SqlObjectHelper
 {
@@ -991,8 +991,19 @@ public static class SqlObjectHelper
     private const string ResourcePrefix = "{BaseNamespace}.Infrastructure.Persistence.SqlObjects.";
 
     /// <summary>
-    /// Applies all SQL objects (functions, views, stored procedures).
-    /// Call in Up() method of a migration, especially after a squash.
+    /// Applies all SQL objects directly to the database via DbContext.
+    /// Called at startup after MigrateAsync() — ensures SQL objects are always up-to-date
+    /// without requiring a new migration when a .sql file changes.
+    /// </summary>
+    public static async Task ApplyAllAsync(DbContext dbContext)
+    {
+        await ApplyCategoryToDbAsync(dbContext, "Functions");
+        // Future: await ApplyCategoryToDbAsync(dbContext, "Views");
+        // Future: await ApplyCategoryToDbAsync(dbContext, "StoredProcedures");
+    }
+
+    /// <summary>
+    /// Applies all SQL objects via MigrationBuilder (legacy, kept for backward compatibility).
     /// </summary>
     public static void ApplyAll(MigrationBuilder migrationBuilder)
     {
@@ -1004,12 +1015,6 @@ public static class SqlObjectHelper
         ApplyCategory(migrationBuilder, "Functions");
     }
 
-    public static void ApplyOne(MigrationBuilder migrationBuilder, string resourceName)
-    {
-        var sql = ReadSqlObject(resourceName);
-        migrationBuilder.Sql(sql);
-    }
-
     public static string ReadSqlObject(string resourceName)
     {
         var fullName = ResourcePrefix + resourceName;
@@ -1037,6 +1042,22 @@ public static class SqlObjectHelper
             migrationBuilder.Sql(reader.ReadToEnd());
         }
     }
+
+    private static async Task ApplyCategoryToDbAsync(DbContext dbContext, string category)
+    {
+        var prefix = ResourcePrefix + category + ".";
+        var resources = Assembly.GetManifestResourceNames()
+            .Where(n => n.StartsWith(prefix, StringComparison.Ordinal)
+                     && n.EndsWith(".sql", StringComparison.Ordinal))
+            .OrderBy(n => n, StringComparer.Ordinal);
+
+        foreach (var resource in resources)
+        {
+            using var stream = Assembly.GetManifestResourceStream(resource)!;
+            using var reader = new StreamReader(stream);
+            await dbContext.Database.ExecuteSqlRawAsync(reader.ReadToEnd());
+        }
+    }
 }
 ```
 
@@ -1073,24 +1094,9 @@ RETURN
 );
 ```
 
-### Migration Integration
+### Startup Integration
 
-In a migration's `Up()` method, call SqlObjectHelper to apply/re-apply SQL objects:
-
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    // ... table creation, indexes, etc.
-
-    // Apply all SQL objects (idempotent — CREATE OR ALTER)
-    SqlObjectHelper.ApplyAll(migrationBuilder);
-}
-```
-
-Or apply a single function:
-```csharp
-SqlObjectHelper.ApplyOne(migrationBuilder, "Functions.fn_GetEntityHierarchy.sql");
-```
+SQL objects are applied **automatically at application startup** via `SqlObjectHelper.ApplyAllAsync(dbContext)`, called in `SmartStackExtensions.InitializeSmartStackAsync()` right after `MigrateAsync()`. No migration injection needed — just add/modify `.sql` files and restart the application.
 
 ### When to Use SQL Objects
 

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

@@ -11,25 +11,21 @@ $ARGUMENTS
 
 ## Current state (auto-injected)
 
+- Dev cache: !`cat .claude/config/dev-run.json 2>/dev/null || echo "no cache"`
 - Dev session: !`cat .claude/dev-session.json 2>/dev/null || echo "no session"`
-- Backend port check: !`netstat.exe -ano 2>/dev/null | grep -E ":(5142|5290) .*LISTENING" | head -5 || echo "no backend listening"`
-- Frontend port check: !`netstat.exe -ano 2>/dev/null | grep -E ":(6173|3000) .*LISTENING" | head -5 || echo "no frontend listening"`
-- API directory: !`ls -d src/*.Api 2>/dev/null || echo "no API found"`
-- Web directory: !`ls -d web/*-web 2>/dev/null || echo "no web found"`
-- Local config: !`cat src/*.Api/appsettings.Local.json 2>/dev/null || echo "no local config"`
-- Frontend env standalone: !`cat web/*-web/.env.standalone 2>/dev/null || echo "no .env.standalone"`
-- Frontend env development: !`cat web/*-web/.env.development 2>/dev/null || echo "no .env.development"`
+- Ports running: !`netstat.exe -ano 2>/dev/null | grep -E "LISTENING" | grep -E ":(5[0-9]{3}|6173|3000) " | head -5 || echo "none"`
 
 <objective>
-Launch the SmartStack development environment in one command: detect configuration, validate config coherence, start backend + frontend, and provide admin credentials.
+Launch the SmartStack development environment in one command: detect configuration, validate config coherence, check SQL connectivity, start backend + frontend, and provide admin credentials.
 Idempotent: safe to run multiple times. Detects already-running processes.
+Uses a config cache to skip re-detection on subsequent runs when config files haven't changed.
 </objective>
 
 <quick_start>
 ```bash
 /dev-start                  # Launch everything (idempotent)
 /dev-start --stop           # Stop backend + frontend
-/dev-start --reset          # Force admin password reset
+/dev-start --reset          # Force admin password reset + re-detect config
 /dev-start --backend-only   # Launch only the backend
 /dev-start --frontend-only  # Launch only the frontend
 ```
@@ -41,7 +37,7 @@ Idempotent: safe to run multiple times. Detects already-running processes.
 |---------|-------------|
 | `/dev-start` | Launch all (idempotent) + validate configs |
 | `/dev-start --stop` | Stop backend + frontend via taskkill.exe |
-| `/dev-start --reset` | Force reset admin password |
+| `/dev-start --reset` | Force reset admin password + re-detect config |
 | `/dev-start --backend-only` | Launch only backend |
 | `/dev-start --frontend-only` | Launch only frontend |
 
@@ -53,22 +49,63 @@ Idempotent: safe to run multiple times. Detects already-running processes.
 
 If `--stop` argument detected, execute the stop workflow and exit:
 
-1. Find backend PID:
+1. Determine ports to stop:
+   - If `.claude/config/dev-run.json` exists → read `api_port` and `web_port` from cache
+   - Otherwise → scan default ports: 5142, 5290 (API) and 6173, 3000 (Web)
+
+2. Find backend PID:
    ```bash
    netstat.exe -ano | grep ":${API_PORT} .*LISTENING" | awk '{print $5}' | head -1
    ```
-2. If found: `taskkill.exe /PID $PID /F`
-3. Find frontend PID:
+3. If found: `taskkill.exe /PID $PID /F`
+4. Find frontend PID:
    ```bash
    netstat.exe -ano | grep ":${WEB_PORT} .*LISTENING" | awk '{print $5}' | head -1
    ```
-4. If found: `taskkill.exe /PID $PID /F`
-5. Display stopped status and exit.
+5. If found: `taskkill.exe /PID $PID /F`
+6. Display stopped status and exit.
 
 If no processes found, display "Nothing running" and exit.
 
+## Step 0: Load cache
+
+If `--stop` argument → skip this step entirely (--stop uses netstat only).
+
+1. Read cache file:
+   ```bash
+   cat .claude/config/dev-run.json 2>/dev/null
+   ```
+
+2. **If no cache OR `--reset` argument** → CACHE_HIT=false, go to Step 1.
+
+3. **If cache exists**, verify config files haven't changed:
+   ```bash
+   API_DIR=$(grep -o '"api_dir": *"[^"]*"' .claude/config/dev-run.json | cut -d'"' -f4)
+   WEB_DIR=$(grep -o '"web_dir": *"[^"]*"' .claude/config/dev-run.json | cut -d'"' -f4)
+   MODE=$(grep -o '"mode": *"[^"]*"' .claude/config/dev-run.json | cut -d'"' -f4)
+
+   if [ "$MODE" = "Local" ]; then
+     CURRENT_HASH=$(stat -c %Y "$API_DIR/appsettings.Local.json" "$WEB_DIR/.env.standalone" "$API_DIR/Properties/launchSettings.json" 2>/dev/null | md5sum | cut -d' ' -f1)
+   else
+     CURRENT_HASH=$(stat -c %Y "$API_DIR/appsettings.json" "$WEB_DIR/.env.development" "$API_DIR/Properties/launchSettings.json" 2>/dev/null | md5sum | cut -d' ' -f1)
+   fi
+
+   CACHED_HASH=$(grep -o '"config_hash": *"[^"]*"' .claude/config/dev-run.json | cut -d'"' -f4)
+   ```
+
+4. **If CURRENT_HASH = CACHED_HASH** → CACHE_HIT=true :
+   - Load all values from cache (api_dir, web_dir, mode, ports, commands, sql_status)
+   - Display: `[CACHE] Using cached config (from {cached_at})`
+   - **Skip directly to Step 4** (check if already running)
+
+5. **If hash mismatch** → CACHE_HIT=false :
+   - Display: `[CACHE] Config changed, re-detecting...`
+   - Continue to Step 1
+
 ## Step 1: Detect project
 
+**Skip if CACHE_HIT=true (values loaded from cache in Step 0).**
+
 Find the API and Web directories:
 - API: `src/*.Api` (first match)
 - Web: `web/*-web` (first match)
@@ -77,6 +114,8 @@ If neither found, display error and exit.
 
 ## Step 2: Detect environment and ports
 
+**Skip if CACHE_HIT=true (values loaded from cache in Step 0).**
+
 Check if `appsettings.Local.json` exists in the API directory:
 
 | Condition | Mode | Backend | Frontend | Backend command | Frontend command |
@@ -92,6 +131,8 @@ Check if `appsettings.Local.json` exists in the API directory:
 
 ## Step 3: Validate config coherence
 
+**Skip if CACHE_HIT=true (values loaded from cache in Step 0).**
+
 **CRITICAL: Verify that backend and frontend configs are consistent.**
 
 ### Rules to check:
@@ -142,6 +183,81 @@ Config Coherence Check:
          -> Creating .env.standalone with correct values...
 ```
 
+### Rule 5: SQL Server connectivity
+
+1. Extract connection string from appsettings:
+   - **Local mode**: `appsettings.Local.json` → `ConnectionStrings.DefaultConnection`
+   - **Dev mode**: `appsettings.json` → `ConnectionStrings.DefaultConnection`
+
+2. Parse server and database:
+   ```bash
+   SQL_SERVER=$(echo "$CONN_STR" | grep -oiP '(?:Server|Data Source)=\K[^;]+')
+   SQL_DATABASE=$(echo "$CONN_STR" | grep -oiP '(?:Database|Initial Catalog)=\K[^;]+')
+   USE_WIN_AUTH=$(echo "$CONN_STR" | grep -qi 'Integrated Security=true\|Trusted_Connection=true' && echo "true" || echo "false")
+   ```
+
+3. Test connectivity (5s timeout):
+   ```bash
+   # Normalize (local) → .
+   SQL_SERVER_NORM=$(echo "$SQL_SERVER" | sed 's/(local)/./')
+
+   if [ "$USE_WIN_AUTH" = "true" ]; then
+     sqlcmd -S "$SQL_SERVER_NORM" -d master -Q "SELECT 1" -t 5 -E -C -h -1 -W 2>/dev/null
+   else
+     SQL_USER=$(echo "$CONN_STR" | grep -oiP '(?:User Id|Uid)=\K[^;]+')
+     SQL_PASS=$(echo "$CONN_STR" | grep -oiP '(?:Password|Pwd)=\K[^;]+')
+     sqlcmd -S "$SQL_SERVER_NORM" -d master -Q "SELECT 1" -t 5 -U "$SQL_USER" -P "$SQL_PASS" -C -h -1 -W 2>/dev/null
+   fi
+   ```
+
+4. If reachable, check database exists:
+   ```bash
+   sqlcmd -S "$SQL_SERVER_NORM" -Q "SET NOCOUNT ON; SELECT name FROM sys.databases WHERE name = '$SQL_DATABASE'" -t 5 -E -C -h -1 -W 2>/dev/null
+   ```
+
+5. Output format:
+   | Scenario | Output | Blocking? |
+   |----------|--------|-----------|
+   | Server OK + DB exists | `[OK] SQL Server (server) — Database 'db' exists` | No |
+   | Server OK + DB missing | `[WARN] Database 'db' not found (AutoMigrate will create it)` | No |
+   | Server unreachable | `[FAIL] SQL Server (server) unreachable — Is the service running?` | No |
+   | sqlcmd not installed | `[SKIP] sqlcmd not found — SQL check skipped` | No |
+   | No connection string | `[SKIP] No connection string — SQL check skipped` | No |
+
+## Step 3b: Write cache
+
+**Only execute if CACHE_HIT=false (Steps 1-3 were executed).**
+
+1. Ensure directory exists: `mkdir -p .claude/config`
+
+2. Compute config hash:
+   ```bash
+   if [ "$MODE" = "Local" ]; then
+     CONFIG_HASH=$(stat -c %Y "$API_DIR/appsettings.Local.json" "$WEB_DIR/.env.standalone" "$API_DIR/Properties/launchSettings.json" 2>/dev/null | md5sum | cut -d' ' -f1)
+   else
+     CONFIG_HASH=$(stat -c %Y "$API_DIR/appsettings.json" "$WEB_DIR/.env.development" "$API_DIR/Properties/launchSettings.json" 2>/dev/null | md5sum | cut -d' ' -f1)
+   fi
+   ```
+
+3. Write `.claude/config/dev-run.json` using the Write tool with all detected values:
+   ```json
+   {
+     "version": 1,
+     "api_dir": "{API_DIR}",
+     "web_dir": "{WEB_DIR}",
+     "mode": "{MODE}",
+     "api_port": {API_PORT},
+     "web_port": {WEB_PORT},
+     "backend_cmd": "{BACKEND_CMD}",
+     "frontend_cmd": "{FRONTEND_CMD}",
+     "sql_server": "{SQL_SERVER}",
+     "sql_database": "{SQL_DATABASE}",
+     "sql_status": "{ok|unreachable|db_missing|skipped}",
+     "config_hash": "{CONFIG_HASH}",
+     "cached_at": "{ISO_TIMESTAMP}"
+   }
+   ```
+
 ## Step 4: Check if already running
 
 ```bash
@@ -218,15 +334,17 @@ Use `Bash(run_in_background=true)` so it runs in background.
           SMARTSTACK DEV ENVIRONMENT
 ================================================================
 
-  Backend:   http://localhost:{API_PORT}        [RUNNING|STARTING]
-  Frontend:  http://localhost:{WEB_PORT}        [RUNNING|STARTING]
-  Swagger:   http://localhost:{API_PORT}/scalar
+  Backend:     http://localhost:{API_PORT}       [RUNNING|STARTING]
+  Frontend:    http://localhost:{WEB_PORT}       [RUNNING|STARTING]
+  Swagger:     http://localhost:{API_PORT}/scalar
+  SQL Server:  {SQL_SERVER}/{SQL_DATABASE}       [OK|WARN|FAIL|SKIP]
 
-  Email:     local.admin@smartstack.local
-  Password:  xxxxxxxxxxxxxx
+  Email:       local.admin@smartstack.local
+  Password:    xxxxxxxxxxxxxx
 
   Environment: {Development|Local}
   Config:      OK | WARNING (details)
+  Cache:       HIT (from {cached_at}) | MISS (re-detected)
 ================================================================
 ```
 
@@ -240,6 +358,8 @@ Use `Bash(run_in_background=true)` so it runs in background.
 4. **Config coherence is critical** - Mismatched ports between backend/frontend is the #1 cause of "it doesn't work" issues
 5. **Idempotent** - Running twice should detect already-running processes and reuse stored credentials
 6. **dev-session.json contains secrets** - Must be in `.gitignore`
+7. **Cache** - Config detection is cached in `.claude/config/dev-run.json`. Cache is invalidated when config files change (mtime-based hash). Use `--reset` to force re-detection.
+8. **SQL check is non-blocking** - A failed SQL check displays a warning but does not prevent launch. AutoMigrate may create the database on startup.
 
 </important_notes>
 
@@ -249,4 +369,6 @@ Use `Bash(run_in_background=true)` so it runs in background.
 - Admin credentials available (reused or freshly reset)
 - Connection info displayed in clear format
 - No errors on repeated invocations (idempotent)
+- Cache written on first run, reused on subsequent runs
+- SQL Server connectivity reported
 </success_criteria>