@atlashub/smartstack-cli 4.37.0 → 4.39.0

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

@@ -3,7 +3,7 @@ name: dev-start
 description: Launch SmartStack dev environment (backend + frontend + admin credentials)
 argument-hint: "[--stop] [--reset] [--backend-only] [--frontend-only]"
 model: haiku
-allowed-tools: Read, Bash, Glob, Write
+allowed-tools: Read, Bash, Glob, Write, TaskOutput
 ---
 
 ## Arguments
@@ -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,30 +49,75 @@ 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
 
-Find the API and Web directories:
-- API: `src/*.Api` (first match)
-- Web: `web/*-web` (first match)
+**Skip if CACHE_HIT=true (values loaded from cache in Step 0).**
+
+Find the API and Web directories using bash (Glob doesn't match directories):
+```bash
+API_DIR=$(ls -d src/*.Api 2>/dev/null | head -1)
+WEB_DIR=$(ls -d web/*-web 2>/dev/null | head -1)
+```
 
 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 |
@@ -90,8 +131,15 @@ Check if `appsettings.Local.json` exists in the API directory:
 - **Dev backend port**: Default `5142`
 - **Dev frontend port**: Default `6173`
 
+**IMPORTANT: Read config files in parallel.** Use a single message with multiple Read tool calls for:
+- `{API_DIR}/appsettings.json` (or `appsettings.Local.json`)
+- `{WEB_DIR}/.env.development` (or `.env.standalone`)
+- `{API_DIR}/Properties/launchSettings.json`
+
 ## 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 +190,82 @@ 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": 2,
+     "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}",
+     "connection_string": "{CONN_STR}",
+     "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
@@ -161,7 +285,20 @@ If NOT already running and NOT `--frontend-only`:
 cd {API_DIR} && dotnet run {LAUNCH_ARGS}
 ```
 
-Use `Bash(run_in_background=true)` so it runs in background.
+Use `Bash(run_in_background=true)` so it runs in background. **Save the task ID** returned by the background command.
+
+### Fail-fast crash detection
+
+After launching, wait 5 seconds then check if the process crashed:
+```bash
+sleep 5
+```
+Then call `TaskOutput(task_id="{TASK_ID}", block=false)` to read the background output.
+
+**If the output contains a stack trace, "Unhandled exception", or the process has already exited:**
+1. Display the error output to the user
+2. Display: `[FAIL] Backend crashed on startup. Fix the error above and retry /dev-start`
+3. **STOP immediately. Do NOT attempt to diagnose, fix, rebuild, or retry.**
 
 ## Step 6: Launch frontend
 
@@ -178,25 +315,29 @@ Use `Bash(run_in_background=true)` so it runs in background.
 
 1. If `.claude/dev-session.json` exists and contains a password and `--reset` NOT specified -> reuse stored credentials
 2. If `--reset` OR no stored password:
-   a. If backend was just launched, wait for it to be UP first:
+   a. If backend was just launched, wait for it to be UP first.
+      Run the full wait in a **single bash command** to avoid multiple tool calls:
       ```bash
       # Phase 1: Wait for port to be bound (up to 30s)
+      echo "Waiting for backend port ${API_PORT}..."
       for i in $(seq 1 10); do
-        netstat.exe -ano | grep ":${API_PORT} .*LISTENING" && break
+        netstat.exe -ano | grep ":${API_PORT} .*LISTENING" > /dev/null 2>&1 && echo "Port bound." && break
         sleep 3
       done
-      ```
-      ```bash
-      # Phase 2: Wait for API to actually respond to HTTP requests (up to 30s)
-      # Kestrel binds the port BEFORE the app is fully initialized.
-      # We must confirm the API actually responds before resetting the password.
+      # Phase 2: Wait for API to respond (up to 30s) — accept 200 or 302
+      echo "Waiting for API to respond..."
       for i in $(seq 1 10); do
-        curl -s -o /dev/null -w "%{http_code}" "http://localhost:${API_PORT}/scalar" 2>/dev/null | grep -q "200" && break
+        HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${API_PORT}/scalar" 2>/dev/null)
+        [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "302" ] && echo "API ready (HTTP $HTTP_CODE)." && break
         sleep 3
       done
       ```
-      If `/scalar` does not return 200 after 30s, warn the user and attempt the reset anyway.
-   b. Run: `smartstack admin reset --force --json`
+      If `/scalar` does not respond after 30s, warn the user and attempt the reset anyway.
+   b. Run admin reset using the connection string extracted from appsettings (Step 3):
+      ```bash
+      smartstack admin reset --connection "{CONN_STR}" --force --json
+      ```
+      **IMPORTANT:** Always pass `--connection` with the full connection string. Without it, the CLI shows an interactive environment picker that blocks execution.
    c. Parse JSON output to extract email and password
    d. Write `.claude/dev-session.json`:
       ```json
@@ -218,15 +359,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)
 ================================================================
 ```
 
@@ -234,12 +377,18 @@ Use `Bash(run_in_background=true)` so it runs in background.
 
 <important_notes>
 
-1. **Backend must be READY before admin reset** - First poll the port (netstat), then poll the `/health` endpoint (HTTP 200) to confirm the API is fully initialized. Kestrel binds the port before the app finishes starting, so port-only checks are insufficient.
-2. **Cross-worktree support** - Detect the correct API directory regardless of which worktree we're in
-3. **No MCP required** - This skill only uses bash commands and the `smartstack` CLI
-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`
+1. **NEVER debug or fix code** - This skill ONLY starts processes. If the backend or frontend fails to start, display the error and STOP. Do NOT attempt to: clean/restore/rebuild, upgrade packages, inspect DLLs, clear NuGet cache, read .csproj files, or any other diagnostic/repair action. The user will fix the issue themselves.
+2. **Fail-fast on crash** - After launching backend in background, wait 5s then check TaskOutput. If the process already exited or shows errors, report and STOP immediately.
+3. **Backend must be READY before admin reset** - First poll the port (netstat), then poll the `/scalar` endpoint (HTTP 200/302) to confirm the API is fully initialized. Kestrel binds the port before the app finishes starting, so port-only checks are insufficient.
+4. **Admin reset requires --connection** - Always pass `--connection "{CONN_STR}"` to avoid the interactive environment picker.
+5. **Read config files in parallel** - When reading appsettings, .env, and launchSettings, use multiple Read calls in a single message.
+6. **Cross-worktree support** - Detect the correct API directory regardless of which worktree we're in.
+7. **No MCP required** - This skill only uses bash commands and the `smartstack` CLI.
+8. **Config coherence is critical** - Mismatched ports between backend/frontend is the #1 cause of "it doesn't work" issues.
+9. **Idempotent** - Running twice should detect already-running processes and reuse stored credentials.
+10. **dev-session.json contains secrets** - Must be in `.gitignore`.
+11. **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.
+12. **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 +398,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>

package/templates/skills/efcore/SKILL.md

@@ -24,6 +24,7 @@ Parse `$ARGUMENTS` to determine the command:
 | `migration` | **Agent** `efcore-migration` | sonnet |
 | `squash` | **Agent** `efcore-squash` | sonnet |
 | `rebase-snapshot` | **Agent** `efcore-rebase-snapshot` | sonnet |
+| (none) | **Inline** `<command-help>` | — |
 
 **Inline commands:** Execute directly following the matching `<command-*>` section below.
 **Agent commands:** Delegate via Agent tool:
@@ -31,11 +32,19 @@ Parse `$ARGUMENTS` to determine the command:
 Agent(
   subagent_type: "{agent_name}",
   model: "sonnet",
-  prompt: "Execute /efcore {command} in {cwd}. Branch: {branch}. Flags: {flags}. Description: {description}"
+  prompt: "Execute /efcore {command}.
+    Working directory: {cwd}
+    Branch: {branch}
+    Context: {--context value if provided, else 'auto-detect'}
+    Force: {true if --force flag, else false}
+    Description: {user description if provided}
+  "
 )
 ```
 
-**Flags:** `--context <name>` (CoreDbContext/ExtensionsDbContext), `--force` (skip confirmations)
+**Flags:**
+- `--context <name>` — Force DbContext (`CoreDbContext` or `ExtensionsDbContext`), skip auto-detection
+- `--force` — Skip all confirmations (backup still created)
 
 </routing>
 
@@ -91,6 +100,8 @@ Pattern: `{context}_v{version}_{sequence}_{Description}`
 
 **READ-ONLY: Never modify database or migrations.**
 
+> **Troubleshooting:** See `references/troubleshooting.md` for common errors.
+
 1. Call MCP `mcp__smartstack__check_migrations` with `branch: {current_branch}`
 2. If MCP unavailable, fallback: `dotnet ef migrations list --no-build --context {Context}` per context
 3. Display compact summary
@@ -117,11 +128,14 @@ BRANCH: {branch}
 
 **ONLY runs `dotnet ef database update`. Never creates/deletes migrations.**
 
-1. Verify `appsettings.Local.json` exists in the API project
-2. Apply Core: `dotnet ef database update --context CoreDbContext --verbose`
-3. Apply Extensions: `dotnet ef database update --context ExtensionsDbContext --verbose`
+> **Reference:** See `references/database-operations.md` for connection test and migration count utilities.
+
+1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
+2. Verify `appsettings.Local.json` exists in the API project
+3. Apply Core: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
+4. Apply Extensions: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
 
-If connection fails: suggest verifying SQL Server, appsettings.Local.json, or `/efcore db-reset`.
+If connection fails: suggest verifying SQL Server, appsettings.Local.json, or `/efcore db-reset`. See `references/troubleshooting.md`.
 
 ```
 DB DEPLOY
@@ -138,15 +152,18 @@ DB DEPLOY
 
 **ONLY operates on database. Never creates/deletes migration files.**
 
-1. **Confirm** (MANDATORY unless `--force`):
+> **Reference:** See `references/reset-operations.md` for drop/recreate commands.
+
+1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
+2. **Confirm** (MANDATORY unless `--force`):
    ```
    AskUserQuestion({ question: "DELETE the database? All data will be lost.", options: ["Yes, delete", "No, cancel"] })
    ```
-2. **Backup** (optional): `sqlcmd -S "$SERVER" -E -Q "BACKUP DATABASE [$DB] TO DISK='$FILE' WITH FORMAT, INIT, COMPRESSION"`
-3. **Drop**: `dotnet ef database drop --force`
-4. **Recreate Core**: `dotnet ef database update --context CoreDbContext`
-5. **Recreate Extensions**: `dotnet ef database update --context ExtensionsDbContext`
-6. **Ask** if user wants `/efcore db-seed`
+3. **Backup** (optional): `sqlcmd -S "$SERVER" -E -Q "BACKUP DATABASE [$DB] TO DISK='$FILE' WITH FORMAT, INIT, COMPRESSION"`
+4. **Drop**: `dotnet ef database drop --force --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+5. **Recreate Core**: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+6. **Recreate Extensions**: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
+7. **Ask** if user wants `/efcore db-seed`
 
 Block if ASPNETCORE_ENVIRONMENT=Production.
 
@@ -167,6 +184,8 @@ Next: /efcore db-status, /efcore db-seed
 
 **Never drop or recreate database.**
 
+> **Reference:** See `references/seed-methods.md` for detection and execution details.
+
 1. **Detect** seeding method:
    - `HasData()` in EF configs → apply via `dotnet ef database update --context {Context}`
    - `IDataSeeder` / `--seed` CLI arg → `dotnet run --project {startup} -- --seed`
@@ -250,3 +269,27 @@ If conflict:
 ```
 
 </command-conflicts>
+
+<command-help>
+
+## (no command) — Show available commands
+
+Display the list of available `/efcore` commands:
+
+```
+EF CORE COMMANDS
+────────────────
+  db-status         Migration state check
+  db-deploy         Apply pending migrations
+  db-reset          Drop + recreate database
+  db-seed           Populate test data
+  scan              Cross-branch migration scanner
+  conflicts         Migration conflict analyzer
+  migration         Create/recreate migration
+  squash            Consolidate migrations
+  rebase-snapshot   Resync ModelSnapshot with parent
+
+Usage: /efcore <command> [--context <name>] [--force]
+```
+
+</command-help>

package/templates/skills/efcore/references/database-operations.md

@@ -7,8 +7,7 @@
 ```bash
 # Validate required variables from step-00-init
 for VAR_NAME in DBCONTEXT DBCONTEXT_TYPE INFRA_PROJECT STARTUP_PROJECT SELECTED_ENV; do
-  eval VAR_VALUE=\$$VAR_NAME
-  if [ -z "$VAR_VALUE" ]; then
+  if [ -z "${!VAR_NAME}" ]; then
     echo "ERROR: Required variable $VAR_NAME is not set"
     echo "Run step-00-init first"
     exit 1
@@ -38,7 +37,7 @@ fi
 ## Connection Test
 
 ```bash
-CONNECTION_TEST=$(dotnet ef database list \
+CONNECTION_TEST=$(dotnet ef migrations list \
   --context "$DBCONTEXT" \
   --project "$INFRA_PROJECT" \
   --startup-project "$STARTUP_PROJECT" 2>&1)

package/templates/skills/efcore/references/seed-methods.md

@@ -27,7 +27,7 @@ if grep -q "\-\-seed" ./src/*/Program.cs 2>/dev/null; then
 fi
 
 # WARNING: SQL scripts detected
-if [ -f "./scripts/seed.sql" ] || find . -name "seed*.sql" 2>/dev/null | grep -q .; then
+if [ -f "./scripts/seed.sql" ] || find src -name "seed*.sql" -not -path "*/bin/*" -not -path "*/obj/*" 2>/dev/null | grep -q .; then
   echo ""
   echo "WARNING: SQL seed scripts detected - FORBIDDEN by conventions"
   echo "Migrate to HasData() or IDataSeeder"