@atlashub/smartstack-cli 4.29.0 → 4.31.0

package/templates/skills/ba-generate-html/steps/step-02-build-data.md

@@ -50,7 +50,11 @@ context: {
 stakeholders: master.cadrage.stakeholders.map(s => ({
   role: s.role,
   function: s.function || "",
-  tasks: s.tasks || [],
+  tasks: Array.isArray(s.tasks)
+    ? s.tasks
+    : typeof s.tasks === 'string'
+      ? s.tasks.split(',').map(t => t.trim()).filter(Boolean)
+      : [],
   frequency: mapFrequency(s.frequency),     // "Quotidien"→"daily", "Hebdomadaire"→"weekly", "Mensuel"→"monthly"
   access: mapAccess(s.involvement),         // "decision-maker"→"admin", "end-user"→"contributor", "observer"→"viewer"
   frustrations: (s.painPoints || []).join("\n")
@@ -60,10 +64,8 @@ stakeholders: master.cadrage.stakeholders.map(s => ({
 **cadrage.scope** (KEY CONVERSION — CRITICAL):
 ```javascript
 scope: {
-  vital: (master.cadrage.globalScope?.mustHave || []).map(item => ({ name: item, description: "" })),
-  important: (master.cadrage.globalScope?.shouldHave || []).map(item => ({ name: item, description: "" })),
-  optional: (master.cadrage.globalScope?.couldHave || []).map(item => ({ name: item, description: "" })),
-  excluded: (master.cadrage.globalScope?.outOfScope || []).map(item => ({ name: item, description: "" }))
+  inscope: (master.cadrage.globalScope?.inScope || []).map(item => ({ name: item, description: "" })),
+  outofscope: (master.cadrage.globalScope?.outOfScope || []).map(item => ({ name: item, description: "" }))
 }
 ```
 
@@ -77,7 +79,6 @@ modules: master.modules.map(m => ({
   name: m.name || m.code,                   // display name (MANDATORY)
   description: m.description || "",
   featureType: m.featureType || "data-centric",
-  priority: m.priority || "must",
   entities: m.entities || [],
   anticipatedSections: m.anticipatedSections || [],
   dependencies: m.dependencies || [],
@@ -235,7 +236,7 @@ dependencyGraph: {
 ## VALIDATION
 
 - FEATURE_DATA.moduleSpecs must have ONE entry per module
-- cadrage.scope uses HTML keys (vital/important/optional/excluded)
+- cadrage.scope uses HTML keys (inscope/outofscope)
 - Wireframe fields use format/content (NOT mockupFormat/mockup)
 
 ## NEXT STEP

package/templates/skills/ba-generate-html/steps/step-04-verify.md

@@ -30,9 +30,9 @@ if ! grep -q '"moduleSpecs"' ba-interactive.html; then
 fi
 ```
 
-**Check 3 — cadrage.scope uses HTML keys (vital/important, NOT mustHave):**
+**Check 3 — cadrage.scope uses HTML keys (inscope/outofscope, NOT inScope):**
 ```
-if grep -q '"mustHave"' ba-interactive.html; then
+if grep -q '"inScope"' ba-interactive.html; then
   BLOCKING_ERROR("cadrage.scope still has JSON keys — conversion failed")
 fi
 ```

package/templates/skills/ba-review/references/review-data-mapping.md

@@ -17,15 +17,13 @@ The ba-review.json is exported from the interactive HTML with the same structure
 ### Scope (HTML → index.json)
 
 ```javascript
-// HTML format: { vital: [{name, description}], important: [...], optional: [...], excluded: [...] }
-// index.json format: { mustHave: [string], shouldHave: [string], couldHave: [string], outOfScope: [string] }
+// HTML format: { inscope: [{name, description}], outofscope: [{name, description}] }
+// index.json format: { inScope: [string], outOfScope: [string] }
 
 reverseScope(reviewCadrage) {
   return {
-    mustHave: (reviewCadrage.scope?.vital || []).map(s => s.name),
-    shouldHave: (reviewCadrage.scope?.important || []).map(s => s.name),
-    couldHave: (reviewCadrage.scope?.optional || []).map(s => s.name),
-    outOfScope: (reviewCadrage.scope?.excluded || []).map(s => s.name)
+    inScope: (reviewCadrage.scope?.inscope || []).map(s => s.name),
+    outOfScope: (reviewCadrage.scope?.outofscope || []).map(s => s.name)
   };
 }
 ```

package/templates/skills/ba-review/steps/step-01-apply.md

@@ -91,10 +91,8 @@ Read the new version's cadrage.json and apply reverse mapping from review data:
 
 ```
 1. Scope mapping (review → cadrage.json):
-   - cadrage.scope.vital[] → cadrage.globalScope.mustHave[]
-   - cadrage.scope.important[] → cadrage.globalScope.shouldHave[]
-   - cadrage.scope.optional[] → cadrage.globalScope.couldHave[]
-   - cadrage.scope.excluded[] → cadrage.globalScope.outOfScope[]
+   - cadrage.scope.inscope[] → cadrage.globalScope.inScope[]
+   - cadrage.scope.outofscope[] → cadrage.globalScope.outOfScope[]
    (Extract name from {name, description} objects)
 
 2. Stakeholders mapping:

package/templates/skills/business-analyse/patterns/suggestion-catalog.md

@@ -75,7 +75,7 @@ Suggests system integrations based on requirements:
 
 ### 4.1 Trigger Point
 
-After step-01-cadrage completes scope definition (scope.mustHave + scope.shouldHave populated):
+After step-01-cadrage completes scope definition (scope.inScope populated):
 
 ```
 Step-01: Analyse → Define Scope → Load Suggestion Catalog → Present Suggestions
@@ -86,10 +86,10 @@ Step-01: Analyse → Define Scope → Load Suggestion Catalog → Present Sugges
 ```
 Input: index.json (module name, keywords, must-haves, should-haves)
 
-1. Read scope.mustHave + scope.shouldHave (user-defined features)
+1. Read scope.inScope (user-defined features)
 2. Extract primary keywords (module type) from scope.description
 3. Match against Module Patterns table → Suggested Modules
-4. Analyze scope.mustHave + scope.shouldHave for conditions → Suggested Sections
+4. Analyze scope.inScope for conditions → Suggested Sections
 5. Detect mentions of integrations → Suggested Integrations
 6. Filter out already-present modules/sections
 7. Rank by relevance (keyword match > condition confidence)
@@ -207,7 +207,7 @@ Select all that apply: [ ] [ ] [ ] [ ]
 
 When user selects suggestions:
 
-1. **Add Selected Modules:** Update scope.mustHave with new modules
+1. **Add Selected Modules:** Update scope.inScope with new modules
 2. **Add Selected Sections:** Update specification.sections (in step-02)
 3. **Add Selected Integrations:** Update specification.integrations
 4. **Store Decisions:** Log in index.json.suggestions[]

package/templates/skills/business-analyse/questionnaire.md

@@ -35,7 +35,7 @@
 | File | Questions | Phase | Focus |
 |------|-----------|-------|-------|
 | `questionnaire/01-context.md` | 3 | step-01-cadrage | Business process, friction points, vision |
-| `questionnaire/02-stakeholders-scope.md` | 10 | step-01-cadrage | User profiles, access levels, scope boundaries, MoSCoW |
+| `questionnaire/02-stakeholders-scope.md` | 10 | step-01-cadrage | User profiles, access levels, scope boundaries |
 | `questionnaire/03-data-ui.md` | ~15 | step-03-specify (per module) | Data entities, UI expectations, dashboards |
 | `questionnaire/04-risks-metrics.md` | — | NOT USED | Risks/metrics out of BA scope |
 | `questionnaire/05-cross-module.md` | ~8 | step-03-specify (conditional) | Cross-module dependencies, integration impact |

package/templates/skills/business-analyse/react/schema.md

@@ -69,9 +69,7 @@ export interface ApplicationCadrage {
 }
 
 export interface GlobalScope {
-  mustHave: string[];
-  shouldHave: string[];
-  couldHave: string[];
+  inScope: string[];
   outOfScope: string[];
 }
 
@@ -88,7 +86,6 @@ export interface ApplicationModule {
   description: string;
   featureType: string;
   entities: string[];
-  priority: 'must' | 'should' | 'could';
   estimatedComplexity: 'simple' | 'medium' | 'complex';
   status: 'pending' | 'in-progress' | 'specified' | 'validated';
   featureJsonPath?: string;
@@ -246,9 +243,7 @@ export interface Stakeholder {
 }
 
 export interface FeatureScope {
-  mustHave: string[];
-  shouldHave: string[];
-  couldHave: string[];
+  inScope: string[];
   outOfScope: string[];
   mainFlow: string[];
   alternativeFlows: AlternativeFlow[];

package/templates/skills/business-analyse/schemas/application-schema.json

@@ -133,9 +133,7 @@
         "globalScope": {
           "type": "object",
           "properties": {
-            "mustHave": { "type": "array", "items": { "type": "string" } },
-            "shouldHave": { "type": "array", "items": { "type": "string" } },
-            "couldHave": { "type": "array", "items": { "type": "string" } },
+            "inScope": { "type": "array", "items": { "type": "string" } },
             "outOfScope": { "type": "array", "items": { "type": "string" } }
           }
         },
@@ -193,7 +191,7 @@
             "required": ["item", "category", "module"],
             "properties": {
               "item": { "type": "string", "description": "Requirement from the original brief" },
-              "category": { "type": "string", "enum": ["mustHave", "shouldHave", "couldHave", "outOfScope", "implicit"] },
+              "category": { "type": "string", "enum": ["inScope", "outOfScope", "implicit"] },
               "module": { "type": ["string", "null"], "description": "Module code that covers this requirement (null if cross-cutting)" },
               "ucRef": { "type": ["string", "null"], "description": "UC ID if already assigned" },
               "notes": { "type": "string" },
@@ -246,11 +244,6 @@
             "type": ["string", "null"],
             "description": "Path to the module-level index.json once created"
           },
-          "priority": {
-            "type": "string",
-            "enum": ["must", "should", "could"],
-            "description": "Priority level from global scope"
-          },
           "sortOrder": {
             "type": "integer",
             "description": "Position in topological order (0-based)"

package/templates/skills/business-analyse/schemas/project-schema.json

@@ -118,11 +118,9 @@
         },
         "globalScope": {
           "type": "object",
-          "description": "Project-wide MoSCoW scope",
+          "description": "Project-wide binary scope",
           "properties": {
-            "mustHave": { "type": "array", "items": { "type": "string" } },
-            "shouldHave": { "type": "array", "items": { "type": "string" } },
-            "couldHave": { "type": "array", "items": { "type": "string" } },
+            "inScope": { "type": "array", "items": { "type": "string" } },
             "outOfScope": { "type": "array", "items": { "type": "string" } }
           }
         },
@@ -189,7 +187,7 @@
             "required": ["item", "category"],
             "properties": {
               "item": { "type": "string", "description": "Requirement from the original brief" },
-              "category": { "type": "string", "enum": ["mustHave", "shouldHave", "couldHave", "outOfScope", "implicit"] },
+              "category": { "type": "string", "enum": ["inScope", "outOfScope", "implicit"] },
               "application": { "type": ["string", "null"], "description": "Application code (null if cross-cutting)" },
               "module": { "type": ["string", "null"], "description": "Module code (null if application-level)" },
               "notes": { "type": "string" },
@@ -251,9 +249,7 @@
             "type": "object",
             "description": "Application-specific scope (subset of global scope)",
             "properties": {
-              "mustHave": { "type": "array", "items": { "type": "string" } },
-              "shouldHave": { "type": "array", "items": { "type": "string" } },
-              "couldHave": { "type": "array", "items": { "type": "string" } }
+              "inScope": { "type": "array", "items": { "type": "string" } }
             }
           },
           "modules": {

package/templates/skills/business-analyse/schemas/sections/discovery-schema.json

@@ -27,9 +27,7 @@
     "scope": {
       "type": "object",
       "properties": {
-        "mustHave": { "type": "array", "items": { "type": "string" } },
-        "shouldHave": { "type": "array", "items": { "type": "string" } },
-        "couldHave": { "type": "array", "items": { "type": "string" } },
+        "inScope": { "type": "array", "items": { "type": "string" } },
         "outOfScope": { "type": "array", "items": { "type": "string" } },
         "mainFlow": { "type": "string" },
         "decisionPoints": { "type": "array", "items": { "type": "string" } },

package/templates/skills/business-analyse/steps/step-01-cadrage.md

@@ -232,10 +232,9 @@ Ask in 1-2 batches. After each batch:
 
 #### 4c. Functional Scope (ALWAYS — from `questionnaire/02-stakeholders-scope.md`)
 
-**Mandatory minimum:** Q2.13 (must-have), Q2.15 (exclusions), Q2.16 (main journey).
+**Mandatory minimum:** Q2.13 (in-scope), Q2.15 (exclusions), Q2.16 (main journey).
 
 Ask in 1-2 batches. After each batch:
-- If everything is "must-have" → **BLOCKING**: apply MoSCoW prioritization question
 - If no exclusions → probe: "What should this system explicitly NOT do?"
 - If journey is too simple → detail: "What happens when something goes wrong? When someone cancels?"
 
@@ -252,10 +251,6 @@ Ask in 1-2 batches. After each batch:
 > ```
 >
 > These error flows become **Business Rules** in step-03 (BR-WF category: workflow/guard conditions).
->
-> **BLOCKING RULE — MoSCoW DISTRIBUTION:**
-> If the client classifies ALL features as "must-have", you MUST challenge this BEFORE proceeding.
-> If client moves items → update categories. If client confirms ALL mustHave → accept but log in changelog.
 
 #### 4d. Challenge Implicit Assumptions (CRITICAL)
 
@@ -435,7 +430,7 @@ options:
 | Choice | Action |
 |--------|--------|
 | **Géré dans l'app** | Entity becomes a sub-entity of the parent module. Add as a **tab in the detail page** of the referencing module. Note in coverageMatrix with `parentModule` field. |
-| **Nouveau module dédié** | **Add new module to `{pre_analysis}.detected_modules[]`** with the proposed architecture (sections, detail tabs, dependencies). Add to `coverageMatrix` as mustHave. The `list` section is ALWAYS the main section. Additional sections ONLY for distinct functional zones (dashboard, approve, import...). `create` and `edit` are ACTIONS within `list` and detail pages, NEVER standalone sections. |
+| **Nouveau module dédié** | **Add new module to `{pre_analysis}.detected_modules[]`** with the proposed architecture (sections, detail tabs, dependencies). Add to `coverageMatrix` as inScope. The `list` section is ALWAYS the main section. Additional sections ONLY for distinct functional zones (dashboard, approve, import...). `create` and `edit` are ACTIONS within `list` and detail pages, NEVER standalone sections. |
 | **Système externe** | Flag for integration specification. Add to `coverageMatrix` as integration. Load questionnaire materials on integrations if not already covered. |
 | **Liste simple en config** | Entity becomes a lookup/reference table (no dedicated module, no section). Note in coverageMatrix as config data. |
 
@@ -586,7 +581,7 @@ BEFORE transitioning to step-02:
 2. Re-read ALL answers collected during phases 2-4
 3. For EACH distinct feature/requirement identified:
    - Create an entry in `cadrage.coverageMatrix[]`
-   - Assign it to mustHave, shouldHave, couldHave, or outOfScope
+   - Assign it to inScope or outOfScope
    - Assign the module that will cover it (or null if cross-cutting)
    - List anticipated sections (Level 4) — ONLY functional zones
    - List anticipated resources (Level 5) for each section
@@ -644,9 +639,7 @@ ba-writer.enrichSection({
     toBe: {from Phase 3, section 4a — Q1.8 answer},
     stakeholders: [{from Phase 3, section 4b}],
     globalScope: {
-      mustHave: [{from Phase 3, section 4c + Phase 4 accepted suggestions}],
-      shouldHave: [{from coverage matrix}],
-      couldHave: [{from coverage matrix}],
+      inScope: [{from Phase 3, section 4c + Phase 4 accepted suggestions + coverage matrix}],
       outOfScope: [{from Phase 3, section 4c — Q2.15 exclusions}]
     },
     applicationRoles: [{from Phase 5, section 6}],
@@ -667,7 +660,7 @@ ba-writer.updateStatus({feature_id}, "framed")
 | Aspect | Count |
 |--------|-------|
 | Stakeholders | {count} |
-| Must-have scope items | {count} |
+| In-scope items | {count} |
 | Application roles | {count} |
 | Suggestions accepted | {count} |
 | Anticipated sections | {total across all modules} |

package/templates/skills/business-analyse/steps/step-02-structure.md

@@ -60,7 +60,6 @@ For each module:
   - ApplicationCode (parent app)
   - Description
   - FeatureType (data-centric | workflow | reporting | integration | full-module)
-  - Priority (must | should | could)
   - Entities (preliminary list)
 ```
 
@@ -137,14 +136,14 @@ Display the complete hierarchy for validation:
 
 ```
 [App: HumanResources]
-  ├── [Module: Employees] (must)
+  ├── [Module: Employees]
   │   ├── list → SmartTable (employees-grid)
   │   └── detail → SmartForm (employee-form)
-  ├── [Module: Absences] (must)
+  ├── [Module: Absences]
   │   ├── list → SmartTable (absences-grid)
   │   ├── detail → SmartForm (absence-form)
   │   └── calendar → SmartKanban (absences-calendar)
-  └── [Module: Reports] (should)
+  └── [Module: Reports]
       └── dashboard → SmartDashboard (hr-dashboard)
 ```
 
@@ -170,7 +169,6 @@ Write via ba-writer:
       "applicationCode": "HumanResources",
       "name": "Employés",
       "featureType": "data-centric",
-      "priority": "must",
       "entities": ["Employee", "Contract"],
       "anticipatedSections": [
         { "code": "list", "label": "Liste", "sectionType": "primary", "permissionMode": "crud", "resources": [{ "code": "employees-grid", "type": "SmartTable" }] },

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

@@ -0,0 +1,242 @@
+---
+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
+---
+
+## Arguments
+$ARGUMENTS
+
+## Current state (auto-injected)
+
+- 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"`
+
+<objective>
+Launch the SmartStack development environment in one command: detect configuration, validate config coherence, start backend + frontend, and provide admin credentials.
+Idempotent: safe to run multiple times. Detects already-running processes.
+</objective>
+
+<quick_start>
+```bash
+/dev-start                  # Launch everything (idempotent)
+/dev-start --stop           # Stop backend + frontend
+/dev-start --reset          # Force admin password reset
+/dev-start --backend-only   # Launch only the backend
+/dev-start --frontend-only  # Launch only the frontend
+```
+</quick_start>
+
+<subcommands>
+
+| Command | Description |
+|---------|-------------|
+| `/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 --backend-only` | Launch only backend |
+| `/dev-start --frontend-only` | Launch only frontend |
+
+</subcommands>
+
+<workflow>
+
+## Handle --stop
+
+If `--stop` argument detected, execute the stop workflow and exit:
+
+1. 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:
+   ```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.
+
+If no processes found, display "Nothing running" and exit.
+
+## Step 1: Detect project
+
+Find the API and Web directories:
+- API: `src/*.Api` (first match)
+- Web: `web/*-web` (first match)
+
+If neither found, display error and exit.
+
+## Step 2: Detect environment and ports
+
+Check if `appsettings.Local.json` exists in the API directory:
+
+| Condition | Mode | Backend | Frontend | Backend command | Frontend command |
+|-----------|------|---------|----------|-----------------|------------------|
+| `appsettings.Local.json` exists | **Local** | Port from `Kestrel:Endpoints:Http:Url` | Port from `.env.standalone` or `package.json` local script | `dotnet run --launch-profile Local` | `npm run local` |
+| No local config | **Development** | Port 5142 (launchSettings http profile) | Port 6173 (vite default) | `dotnet run --environment Development` | `npm run dev` |
+
+**Reading ports:**
+- **Local backend port**: Parse `appsettings.Local.json` -> `Kestrel.Endpoints.Http.Url` -> extract port from URL (e.g., `http://localhost:5290` -> `5290`)
+- **Local frontend port**: Parse `.env.standalone` -> look for port in `VITE_API_URL`, or parse `package.json` -> `scripts.local` for `--port` flag
+- **Dev backend port**: Default `5142`
+- **Dev frontend port**: Default `6173`
+
+## Step 3: Validate config coherence
+
+**CRITICAL: Verify that backend and frontend configs are consistent.**
+
+### Rules to check:
+
+| Rule | Backend source | Frontend source | Validation |
+|------|---------------|-----------------|------------|
+| Frontend calls correct backend | Port API (Kestrel or launchSettings) | `VITE_API_URL` in `.env.standalone` (Local) or `.env.development` (Dev) | Port in VITE_API_URL must match API port |
+| Backend allows frontend (CORS) | `SmartStack:CorsOrigins[]` in appsettings | Frontend port | CorsOrigins must contain `http://localhost:{WEB_PORT}` |
+| OAuth redirects to correct frontend | `Authentication:FrontendUrl` in appsettings | Frontend port | FrontendUrl must point to `http://localhost:{WEB_PORT}` |
+| Local files exist in pairs | `appsettings.Local.json` | `.env.standalone` | If one exists, the other must too |
+
+### In Local mode:
+
+1. Read `appsettings.Local.json` -> extract `Kestrel:Endpoints:Http:Url` (API port)
+2. Read `appsettings.Local.json` -> extract `Authentication:FrontendUrl` (expected frontend URL)
+3. Read `.env.standalone` -> extract `VITE_API_URL` (expected API URL by frontend)
+4. Verify `VITE_API_URL` port matches Kestrel port
+5. Verify `Authentication:FrontendUrl` port matches frontend port
+6. If `appsettings.Local.json` exists but NOT `.env.standalone` -> **create `.env.standalone`** with correct values (ask user first)
+7. If `.env.standalone` exists but NOT `appsettings.Local.json` -> **warn** (config incomplete)
+
+### In Development mode:
+
+1. Verify `.env.development` contains `VITE_API_URL=http://localhost:5142` (NOT 5290 which is Local profile)
+2. Verify `appsettings.json` -> `SmartStack:CorsOrigins` contains `http://localhost:6173`
+3. Verify `Authentication:FrontendUrl` = `http://localhost:6173`
+
+### If incoherence detected:
+
+1. Display a clear WARNING with detected values vs expected values
+2. Propose to auto-correct (write the correct files)
+3. If user refuses, continue with a warning
+
+### Output format for coherence:
+
+```
+Config Coherence Check:
+  [OK] VITE_API_URL matches backend port (5290)
+  [OK] CORS allows frontend (http://localhost:3000)
+  [OK] OAuth redirect matches frontend
+  [OK] Local config files paired
+
+  -- OR --
+
+  [WARN] VITE_API_URL=http://localhost:5290 but backend runs on port 5142
+         Expected: VITE_API_URL=http://localhost:5142
+  [WARN] .env.standalone missing (appsettings.Local.json exists)
+         -> Creating .env.standalone with correct values...
+```
+
+## Step 4: Check if already running
+
+```bash
+netstat.exe -ano | grep ":${API_PORT} .*LISTENING"
+netstat.exe -ano | grep ":${WEB_PORT} .*LISTENING"
+```
+
+If `--backend-only`: skip frontend checks.
+If `--frontend-only`: skip backend checks.
+
+## Step 5: Launch backend
+
+If NOT already running and NOT `--frontend-only`:
+
+```bash
+# cd into the API directory first
+cd {API_DIR} && dotnet run {LAUNCH_ARGS}
+```
+
+Use `Bash(run_in_background=true)` so it runs in background.
+
+## Step 6: Launch frontend
+
+If NOT already running and NOT `--backend-only`:
+
+```bash
+# cd into the Web directory first
+cd {WEB_DIR} && npm run {SCRIPT}
+```
+
+Use `Bash(run_in_background=true)` so it runs in background.
+
+## Step 7: Handle admin password
+
+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:
+      ```bash
+      # Poll up to 30 seconds (10 attempts x 3s)
+      for i in $(seq 1 10); do
+        netstat.exe -ano | grep ":${API_PORT} .*LISTENING" && break
+        sleep 3
+      done
+      ```
+   b. Run: `smartstack admin reset --force --json`
+   c. Parse JSON output to extract email and password
+   d. Write `.claude/dev-session.json`:
+      ```json
+      {
+        "admin_password": "...",
+        "admin_email": "local.admin@smartstack.local",
+        "last_reset": "2026-03-10T14:30:00Z",
+        "api_port": 5142,
+        "web_port": 6173,
+        "environment": "Development"
+      }
+      ```
+   e. Verify `.claude/dev-session.json` is in `.gitignore`. If not, warn the user (contains credentials).
+
+## Step 8: Display connection info
+
+```
+================================================================
+          SMARTSTACK DEV ENVIRONMENT
+================================================================
+
+  Backend:   http://localhost:{API_PORT}        [RUNNING|STARTING]
+  Frontend:  http://localhost:{WEB_PORT}        [RUNNING|STARTING]
+  Swagger:   http://localhost:{API_PORT}/scalar
+
+  Email:     local.admin@smartstack.local
+  Password:  xxxxxxxxxxxxxx
+
+  Environment: {Development|Local}
+  Config:      OK | WARNING (details)
+================================================================
+```
+
+</workflow>
+
+<important_notes>
+
+1. **Backend must be UP before admin reset** - Poll the port (2-3s intervals, max 30s) before attempting password reset
+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`
+
+</important_notes>
+
+<success_criteria>
+- Backend and frontend detected and launched (or already running)
+- Config coherence validated (or warnings displayed)
+- Admin credentials available (reused or freshly reset)
+- Connection info displayed in clear format
+- No errors on repeated invocations (idempotent)
+</success_criteria>

package/templates/skills/ui-components/SKILL.md

@@ -156,7 +156,7 @@ export function EntityListPage() {
       setLoading(true);
       setError(null);
       const result = await entityApi.getAll();
-      setData(result.items);
+      setData(result?.items ?? []);
     } catch (err: any) {
       setError(err.message || t('{module}:errors.loadFailed', 'Failed to load data'));
     } finally {

package/templates/skills/ui-components/patterns/data-table.md

@@ -49,7 +49,7 @@ export function UsersPage() {
       setLoading(true);
       setError(null);
       const result = await usersApi.getAll();
-      setUsers(result.items);
+      setUsers(result?.items ?? []);
     } catch (err: any) {
       setError(err.message || t('users:errors.loadFailed', 'Failed to load users'));
     } finally {