@atlashub/smartstack-cli 3.36.0 → 3.38.0

package/templates/skills/application/references/test-coverage-requirements.md

@@ -0,0 +1,213 @@
+# Test Generation: Coverage Requirements & Categories
+
+> Referenced from `steps/step-07-tests.md` — Test coverage minimums and category definitions.
+
+---
+
+## Minimum Test Coverage Per Category
+
+| Category | Minimum Tests | Focus Areas |
+|----------|---------------|------------|
+| Controller (mock) | 10 | CRUD routing, auth/tenant handling, error responses |
+| Controller (real integration) | 8 | CRUD with actual DB persistence, tenant isolation, 404/409 cases |
+| Service | 8 | Business logic, CRUD, error handling, edge cases |
+| Entity | 5 | Factory method, property updates, validation, soft delete |
+| Validator | 8 | Code validation, name validation, security rules |
+| Repository | 8 | CRUD, tenant filtering, pagination, indexes |
+| Security | 10 | Auth bypass attempts, injection attacks, header validation |
+
+**Total minimum:** ~67 tests per entity
+
+---
+
+## Real Integration Test Coverage
+
+Integration tests (with actual DB):
+- GET all → 200 with list
+- GET by ID → 200 when exists, 404 when not
+- POST → 201/200 when valid, persist to DB, read back to verify
+- POST → 400 when invalid data
+- POST → 409 when duplicate code
+- PUT → 200 when valid, persist changes, read back to verify
+- PUT → 404 when not exists
+- DELETE → 204 when exists
+- DELETE → 404 when not exists
+- Tenant isolation → create in tenant A, invisible in tenant B (REAL DB)
+- Authorization → 401 when not authenticated
+
+---
+
+## Test Naming Convention (BLOCKING)
+
+All test methods MUST follow: `{Method}_When{Condition}_Should{Result}`
+
+**FORBIDDEN patterns:**
+- `Test1`, `Test2`, `TestMethod`, `MyTest`
+- `Should_Return_OK`, `test_get_all`
+
+**REQUIRED pattern:**
+```csharp
+GetAll_WhenCalled_ShouldReturn200WithList
+Create_WhenDuplicateCode_ShouldThrowException
+Delete_WhenNotAuthenticated_ShouldReturn401
+```
+
+---
+
+## Test Structure (BLOCKING)
+
+All tests MUST follow Arrange-Act-Assert:
+
+```csharp
+// CORRECT
+[Fact]
+public async Task GetById_WhenExists_ShouldReturn200()
+{
+    // Arrange
+    var id = Guid.NewGuid();
+    // ... setup
+
+    // Act
+    var response = await _client.GetAsync($"/api/{entityCode}/{id}");
+
+    // Assert
+    response.StatusCode.Should().Be(HttpStatusCode.OK);
+}
+
+// FORBIDDEN - No structure
+[Fact]
+public void TestGetById()
+{
+    var response = _client.GetAsync("/api/product/1");
+    Assert.Equal(200, response.StatusCode);
+}
+```
+
+---
+
+## Dependencies Check (BLOCKING)
+
+Verify test project uses:
+- `FluentAssertions` (NOT `Assert.Equal`)
+- `Moq` (NOT manual fakes)
+- `xunit` (NOT NUnit or MSTest)
+
+---
+
+## Test Categories
+
+### 1. Controller Mock Tests
+
+Unit tests with mocked dependencies:
+- Routing validation
+- Authentication/Authorization
+- Error response formatting
+- Input validation
+
+```csharp
+[Fact]
+public async Task GetAll_WhenCalled_ShouldReturn200WithList()
+{
+    // Mock service
+    _mockService.Setup(s => s.GetAllAsync(It.IsAny<CancellationToken>()))
+        .ReturnsAsync(new List<ProductDto>());
+
+    // Act & Assert
+    ...
+}
+```
+
+### 2. Controller Integration Tests
+
+REAL tests with actual DB (via WebApplicationFactory):
+- Full HTTP flow
+- Database persistence
+- Tenant isolation
+- Query validation
+
+### 3. Service Tests
+
+Unit tests for business logic:
+- CRUD operations
+- Error handling
+- Validation logic
+
+### 4. Entity Tests
+
+Domain model tests:
+- Factory methods
+- Property validation
+- State transitions
+- Soft delete
+
+### 5. Validator Tests
+
+Input validation:
+- Code format validation
+- Name constraints
+- Security rules (XSS, SQL injection detection)
+
+### 6. Repository Tests
+
+Data access tests:
+- Query correctness
+- Tenant filtering
+- Pagination
+- Indexes
+
+### 7. Security Tests
+
+OWASP coverage:
+- Authentication bypass attempts
+- Authorization bypass attempts
+- SQL injection attempts
+- XSS payload handling
+- CSRF token validation
+- Tenant isolation breach attempts
+- Header injection attempts
+
+---
+
+## Build & Run Checks (BLOCKING)
+
+```bash
+# Build
+dotnet build tests/{SolutionName}.Tests/{SolutionName}.Tests.csproj
+
+# Run
+dotnet test tests/{SolutionName}.Tests/{SolutionName}.Tests.csproj --no-build --verbosity normal
+```
+
+**ALL tests MUST pass.** If tests fail:
+1. Read the failure output carefully
+2. Fix the failing tests or the code they test
+3. Re-run until all tests pass
+4. Do NOT proceed to the next step until all tests are green
+
+---
+
+## Frontend Test Categories
+
+| File | Category | Focus |
+|------|----------|-------|
+| `{EntityName}Page.test.tsx` | Page | Loading, error, render with data |
+| `{EntityName}ListView.test.tsx` | List | Pagination, filtering, view toggle |
+| `{EntityName}DetailPage.test.tsx` | Detail | Tab switching, back navigation |
+| `use{EntityName}Preferences.test.ts` | Hooks | State persistence, local storage |
+| `{entityName}Api.test.ts` | API Client | MSW mocking, HTTP methods |
+
+---
+
+## Validation Checklist
+
+- [ ] All test methods follow `{Method}_When{Condition}_Should{Result}` naming
+- [ ] All tests use Arrange-Act-Assert structure
+- [ ] FluentAssertions used throughout (not Assert.Equal)
+- [ ] Moq used for mock-based tests only
+- [ ] Minimum test count met per category
+- [ ] Real integration tests verify DB persistence
+- [ ] Security tests cover OWASP top 10 issues
+- [ ] Backend tests build successfully
+- [ ] **ALL backend tests pass**
+- [ ] Frontend tests build successfully
+- [ ] **ALL frontend tests pass**

package/templates/skills/application/references/test-frontend.md

@@ -53,9 +53,9 @@ Args:
 ```
 
 This generates:
-- `src/pages/{context}/{application}/__tests__/{EntityName}Page.test.tsx` - Page rendering, loading, error states
-- `src/pages/{context}/{application}/__tests__/{EntityName}ListView.test.tsx` - List display, pagination, view toggle
-- `src/pages/{context}/{application}/__tests__/{EntityName}DetailPage.test.tsx` - Detail view, tabs, back navigation
+- `src/pages/{application}/__tests__/{EntityName}Page.test.tsx` - Page rendering, loading, error states
+- `src/pages/{application}/__tests__/{EntityName}ListView.test.tsx` - List display, pagination, view toggle
+- `src/pages/{application}/__tests__/{EntityName}DetailPage.test.tsx` - Detail view, tabs, back navigation
 - `src/hooks/__tests__/use{EntityName}Preferences.test.ts` - Preference get/set
 - `src/services/api/__tests__/{entityName}Api.test.ts` - API client calls with MSW
 

package/templates/skills/application/steps/step-00-init.md

@@ -22,156 +22,26 @@ Initialize the application/module creation by parsing parameters, detecting leve
 
 ## EXECUTION SEQUENCE
 
-### 1. Detect Navigation Level
+### 1-4. Parameter Detection & Project Analysis
 
-From user request, identify the level:
-
-| Hint in Request | → Level | Parent Required |
-|-----------------|---------|-----------------|
-| "context", "workspace", "nouveau contexte" | context | No |
-| "application", "app", "nouvelle application" | application | Yes (context) |
-| "module", "feature", "nouveau module" | module | Yes (context.application) |
-| "section", "tab", "nouvelle section" | section | Yes (context.app.module) |
-
-### 2. Extract Parameters
-
-```yaml
-# Required
-level: context | application | module | section
-code: kebab-case (e.g., "products", "order-management")
-labels:
-  fr: "Label français"
-  en: "English label"
-  it: "Etichetta italiana"
-  de: "Deutsche Bezeichnung"
-icon: Lucide icon name (e.g., "Package", "ShoppingCart")
-displayOrder: number
-
-# Conditional (required for non-context levels)
-parentPath: "context.application.module" (dot-separated)
-```
-
-### 3. MCP Prerequisite Check (BLOCKING)
-
-**CRITICAL:** This check is **BLOCKING** - the skill cannot proceed without MCP.
-
-> See `_shared.md` → "MCP Prerequisite Guard (BLOCKING)" for the full pattern.
-
-```
-Call: mcp__smartstack__validate_conventions
-Args: { checks: ["tables"] }
-```
-
-**On success:** Set `mcp_available = true`, continue to Step 4.
-
-**On failure (STOP):**
-
-```
-═══════════════════════════════════════════════════════════════
-  MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
-═══════════════════════════════════════════════════════════════
-
-  The SmartStack MCP server is required for the application
-  skill but could not be reached.
-
-  To install:
-    claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
-
-  To verify:
-    /mcp:healthcheck
-
-  After installation, restart Claude Code and retry.
-
-═══════════════════════════════════════════════════════════════
-```
-
-**DO NOT** offer manual instructions or degraded execution.
-**DO NOT** proceed with step files.
-**STOP the skill immediately.**
-
-### 4. Detect Project Type
-
-Read `.smartstack/config.json` at the project root to determine the seeding strategy:
-
-```
-Read: .smartstack/config.json
-Extract: projectType, dbContext
-```
-
-| projectType | dbContext | Seeding Strategy |
-|-------------|----------|-----------------|
-| `core` | `core` | HasData() in Configuration files (existing pattern) |
-| `client` | `extensions` | IClientSeedDataProvider (runtime seeding) |
-
-**If file not found or projectType missing:** Default to `core` / `hasdata`.
-
-Store:
-```
-{project_type} = "core" or "client"
-{db_context} = "core" or "extensions"
-{seeding_strategy} = "hasdata" or "provider"
-```
-
-### 4b. Detect Feature.json Context (Optional Enrichment)
-
-Search for a Business Analysis feature.json for the target module:
-
-```
-Glob: docs/business/*/{code}/business-analyse/v*/feature.json
-      .business-analyse/business/*/modules/{code}/features/*/feature.json
-```
-
-**If found (status = "handed-off" or "consolidated"):**
-
-Read the feature.json and extract context for subsequent steps:
-
-| feature.json Section | Used In Step | Extracted Data |
-|----------------------|-------------|----------------|
-| `analysis.entities[]` | step-04 (backend) | Entity names, attributes, relationships, validations |
-| `specification.useCases[]` | step-04 (backend) | API endpoint definitions beyond basic CRUD |
-| `specification.permissionMatrix` | step-02 (permissions) | Custom permission paths and role assignments |
-| `specification.apiEndpoints[]` | step-04 (backend) | Exact HTTP methods, routes, DTOs |
-| `specification.navigation` | step-01 (navigation) | Navigation hierarchy with labels and icons |
-| `specification.i18nKeys` | step-05 (frontend) | Pre-defined translation keys |
-| `specification.validations[]` | step-04 (backend) | Field-level validation rules |
-| `specification.uiWireframes[]` | step-05 (frontend) | UI layout guidance |
-| `specification.seedDataCore` | step-01, step-02, step-03 | Pre-computed seeds |
-| `analysis.businessRules[]` | step-04, step-07 | Business rules for service logic and tests |
-| `specification.lifeCycles[]` | step-04 (backend) | Entity state machines |
-| `specification.dashboards` | step-05 (frontend) | Dashboard KPIs and chart specs |
-| `documentation` | step-08 | userDocRequired / techDocRequired flags |
-
-Store:
-```
-{feature_json_path} = "path/to/feature.json" or null
-{has_feature_context} = true or false
-{feature_data} = parsed feature.json object (if found)
-```
-
-**If NOT found or status not in ["handed-off", "consolidated"]:**
-
-```
-{has_feature_context} = false
-```
-
-Continue normally. All subsequent steps use their standard generation logic (generic CRUD).
-
-> **When `{has_feature_context} = true`**, subsequent steps SHOULD use the feature.json data
-> to generate more accurate code: entities with correct attributes and relationships, custom
-> permissions beyond basic CRUD, specific API routes, validation rules, and business logic
-> in services. This reduces post-generation manual corrections significantly.
+See [references/init-parameter-detection.md](../references/init-parameter-detection.md) for:
+- Navigation level detection (application/module/section)
+- Parameter extraction (code, labels, icon, displayOrder)
+- Project type & seeding strategy detection
+- Feature.json context enrichment (optional)
+- MCP prerequisite validation (BLOCKING)
 
 ### 5. Build Full Path
 
 ```
 {full_path} = {parentPath}.{code}  (if parentPath exists)
-{full_path} = {code}               (if context level)
+{full_path} = {code}               (if application level)
 
 Example:
   level: module
-  parentPath: erp.sales
+  parentPath: sales
   code: products
-  → full_path: erp.sales.products
+  → full_path: sales.products
 ```
 
 ### 6. Infer Descriptions (if not provided)
@@ -218,7 +88,7 @@ descriptions:
 
 | Variable | Description |
 |----------|-------------|
-| `{level}` | context, application, module, or section |
+| `{level}` | application, module, or section |
 | `{code}` | kebab-case identifier |
 | `{full_path}` | Complete navigation path |
 | `{parent_path}` | Parent path (null for context) |

package/templates/skills/application/steps/step-01-navigation.md

@@ -29,7 +29,7 @@ From step-00-init:
 
 | Variable | Description |
 |----------|-------------|
-| `{level}` | context, application, module, or section |
+| `{level}` | application, module, or section |
 | `{code}` | kebab-case identifier |
 | `{full_path}` | Complete navigation path |
 | `{parent_path}` | Parent path (null for context) |
@@ -55,7 +55,7 @@ Tool: mcp__smartstack__scaffold_navigation
 Args:
   level: "{level}"
   code: "{code}"
-  parentPath: "{parent_path}"  # Omit if level is "context"
+  parentPath: "{parent_path}"  # Omit if level is "application" (top-level)
   labels:
     fr: "{labels.fr}"
     en: "{labels.en}"
@@ -158,7 +158,7 @@ See [references/nav-fallback-procedure.md](../references/nav-fallback-procedure.
 
 ## FAILURE MODES
 
-- Missing parent path for non-context level (return to step-00)
+- Missing parent path for non-application level (return to step-00)
 - Invalid level (return to step-00)
 - Parent entity not found in existing seeds (ask user for parent GUID)
 

package/templates/skills/application/steps/step-02-permissions.md

@@ -28,7 +28,7 @@ From previous steps:
 
 | Variable | Description |
 |----------|-------------|
-| `{level}` | context, application, module, or section |
+| `{level}` | application, module, or section |
 | `{full_path}` | Complete navigation path (navRoute) |
 | `{navigation_guid}` | GUID of the navigation entity |
 | `{labels}` | Object with fr, en, it, de |
@@ -45,7 +45,7 @@ For permissions, the navRoute is the `{full_path}`:
 
 ```
 navRoute = "{full_path}"
-Example: "erp.sales.products"
+Example: "sales.products"
 ```
 
 ### 2. Call MCP generate_permissions
@@ -76,7 +76,7 @@ Add to `Application/Common/Authorization/Permissions.cs`:
 
 **Usage in Controller:**
 ```csharp
-[RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
+[RequirePermission(Permissions.{Application}.{Module}.Read)]
 public async Task<ActionResult> GetAll() { ... }
 ```
 ```
@@ -186,7 +186,7 @@ If MCP call fails:
 ## FAILURE MODES
 
 - MCP call failed (display error, stop)
-- Invalid navRoute format (must be context.application.module)
+- Invalid navRoute format (must be application.module)
 - Missing navigation entity (return to step-01)
 
 ---

package/templates/skills/application/steps/step-03-roles.md

@@ -37,7 +37,7 @@ From previous steps:
 | Variable | Description |
 |----------|-------------|
 | `{full_path}` | Complete navigation path (navRoute) |
-| `{level}` | context, application, module, or section |
+| `{level}` | application, module, or section |
 | `{permission_guids}` | GUIDs for generated permissions |
 | `{mcp_available}` | Boolean - MCP connectivity status |
 | `{project_type}` | "core" or "client" |
@@ -49,13 +49,10 @@ From previous steps:
 
 ### 1. Determine Default Role Assignments
 
-Based on navigation context, apply default role mappings:
-
-| Context | PlatformAdmin | TenantAdmin | StandardUser |
-|---------|---------------|-------------|--------------|
-| `platform.*` | Full CRUD | Read only | None |
-| `business.*` | Full CRUD | Full CRUD | Read only |
-| `personal.*` | None | Full CRUD | Full CRUD |
+See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
+- Default role mapping table by application prefix
+- ApplicationRolesSeedData.cs requirements (once per application)
+- {Module}RolePermissionSeedData.cs requirements (per module)
 
 ### 2. Call MCP scaffold_role_permissions
 
@@ -134,178 +131,24 @@ If MCP call fails or `{mcp_available}` = false:
 
 > **Condition:** `{seeding_strategy}` = "provider"
 
-**For core (`{seeding_strategy}` = "hasdata"):** Write in RolePermissionConfiguration.cs (existing pattern)
-
-**For client (`{seeding_strategy}` = "provider"):** DO NOT write in RolePermissionConfiguration.cs (does not exist in client projects).
-
-Instead, create TWO files:
-
-### 1. ApplicationRolesSeedData.cs (ONCE per application)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
-
-**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
-
-**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
-
-See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
-
-**Key requirements:**
-- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
-- 4 roles: Admin, Manager, Contributor, Viewer
-- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
-- `ApplicationId` references the navigation application GUID
-- `IsSystem = false` (application-scoped, not system roles)
-
-**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
-
-### 2. {Module}RolePermissionSeedData.cs (PER module)
-
-**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
-
-**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
-
-Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
-These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
-
-**After creating both files:** Proceed to step-03b-provider.md (which will skip for core projects).
+See [references/roles-client-project-handling.md](../references/roles-client-project-handling.md) for:
+- ApplicationRolesSeedData.cs creation (once per application)
+- {Module}RolePermissionSeedData.cs creation (per module)
+- Role code naming and GUID generation rules
+- Detection of existing ApplicationRolesSeedData.cs
 
 ---
 
 ## FALLBACK PROCEDURE (When MCP Unavailable)
 
-> This procedure generates role-permission HasData entries following SmartStack.app patterns.
-
-### F1. Read Existing RolePermissionConfiguration.cs
-
-```
-Glob: **/Persistence/Configurations/Authorization/RolePermissionConfiguration.cs
-```
-
-Read the file to determine:
-- Existing role-permission mappings
-- The GetSeedData() method structure
-- Which roles already have which permissions
-- The GUID generation method used (deterministic or hardcoded)
-
-### F2. Read Role GUIDs
-
-**System-level roles** (well-known GUIDs):
-
-| Role | GUID |
-|------|------|
-| SuperAdmin | `11111111-1111-1111-1111-111111111111` |
-| PlatformAdmin | `22222222-2222-2222-2222-222222222222` |
-| TenantAdmin | `33333333-3333-3333-3333-333333333333` |
-| StandardUser | `44444444-4444-4444-4444-444444444444` |
-
-**IMPORTANT:** Read the actual `RoleSeedData.cs` or `RoleConfiguration.cs` in the target project to confirm the actual role GUIDs. The above are defaults; the project may use different values.
-
-**Application-scoped roles** (deterministic GUIDs based on application):
-
-```csharp
-// Read the existing GenerateDeterministicGuid method in RolePermissionConfiguration.cs
-// Typically uses MD5 hash:
-private static Guid GenerateDeterministicGuid(Guid applicationId, string roleType)
-{
-    using var md5 = System.Security.Cryptography.MD5.Create();
-    var input = $"{applicationId}-{roleType}";
-    var hash = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(input));
-    return new Guid(hash);
-}
-// roleType values: "admin", "manager", "contributor", "viewer"
-```
-
-Find the `applicationId` from `NavigationApplicationSeedData.cs` matching `{full_path}`.
-
-### F3. Determine Context-Based Default Mappings
-
-Based on `{full_path}` prefix:
-
-| Context Prefix | SuperAdmin | PlatformAdmin | App Admin | App Manager | App Contributor | App Viewer |
-|----------------|------------|---------------|-----------|-------------|-----------------|------------|
-| `platform.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
-| `business.*` | wildcard | Full CRUD | Full CRUD | CRU | CR | R |
-| `personal.*` | wildcard | None | Full CRUD | CRU | CR | R |
-
-### F4. Generate RolePermission HasData Entries
-
-Using `{permission_guids}` from step-02:
-
-```csharp
-// In RolePermissionConfiguration.cs - GetSeedData() method
-var seedDate = SeedConstants.SeedDate;
-
-// ============================================================
-// {MODULE_NAME} PERMISSIONS
-// ============================================================
-
-// SuperAdmin: already has *.* wildcard - no individual entries needed
-
-// PlatformAdmin (for platform.* context)
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = platformAdminRoleId, PermissionId = {permission_guids.delete}, AssignedAt = seedDate });
-
-// Application-scoped: Admin → wildcard
-rolePermissions.Add(new { RoleId = appAdminRoleId, PermissionId = {permission_guids.wildcard}, AssignedAt = seedDate });
-
-// Application-scoped: Manager → CRU (read + create + update — no delete)
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appManagerRoleId, PermissionId = {permission_guids.update}, AssignedAt = seedDate });
-
-// Application-scoped: Contributor → CR
-rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-rolePermissions.Add(new { RoleId = appContributorRoleId, PermissionId = {permission_guids.create}, AssignedAt = seedDate });
-
-// Application-scoped: Viewer → R
-rolePermissions.Add(new { RoleId = appViewerRoleId, PermissionId = {permission_guids.read}, AssignedAt = seedDate });
-```
-
-### F5. Write Code to RolePermissionConfiguration.cs
-
-**CRITICAL:** Do NOT just display code. WRITE it to the actual file.
-
-1. Open `RolePermissionConfiguration.cs`
-2. Find the `GetSeedData()` method
-3. Add the new role-permission entries to the list
-4. Add necessary permission GUID references (import from PermissionConfiguration or use inline)
-5. Add comments grouping the new entries: `// {MODULE_NAME} PERMISSIONS`
-
-### F6. Present Summary
-
-```markdown
-## Role-Permission Mappings Generated (Fallback)
-
-| Role | Permissions |
-|------|-------------|
-| SuperAdmin | Already has wildcard access |
-| PlatformAdmin | {full_path}.read, .create, .update, .delete |
-| App Admin | {full_path}.* (wildcard) |
-| App Manager | {full_path}.read, .create, .update |
-| App Contributor | {full_path}.read, .create |
-| App Viewer | {full_path}.read |
-
-Written to: RolePermissionConfiguration.cs
-```
-
-### F7. Offer User Adjustment
-
-```yaml
-questions:
-  - header: "Role Access"
-    question: "Default role-permission mappings have been applied. Adjust?"
-    options:
-      - label: "Keep defaults (Recommended)"
-        description: "Standard role hierarchy applied"
-      - label: "Custom adjustments"
-        description: "I want to change specific role permissions"
-    multiSelect: false
-```
-
-If user selects "Custom adjustments", ask which roles/permissions to change and update the file accordingly.
+See [references/roles-fallback-procedure.md](../references/roles-fallback-procedure.md) for the complete 7-step fallback:
+- **F1:** Read existing RolePermissionConfiguration.cs to determine state
+- **F2:** Read role GUIDs (system-level and application-scoped)
+- **F3:** Determine default mappings based on application prefix
+- **F4:** Generate RolePermission HasData entries using permission GUIDs
+- **F5:** Write code to RolePermissionConfiguration.cs (CRITICAL: WRITE not display)
+- **F6:** Present summary
+- **F7:** Offer user adjustment option
 
 ---