@atlashub/smartstack-cli 3.36.0 → 3.38.0

package/templates/skills/apex/references/smartstack-frontend.md

@@ -15,7 +15,7 @@
 ```tsx
 // Named exports — use .then() to wrap
 const EmployeesPage = lazy(() =>
-  import('@/pages/Business/HumanResources/Employees/EmployeesPage')
+  import('@/pages/HumanResources/Employees/EmployeesPage')
     .then(m => ({ default: m.EmployeesPage }))
 );
 
@@ -32,7 +32,7 @@ import { PageLoader } from '@/components/ui/PageLoader';
 // Route element wrapping
 element: (
   <Suspense fallback={<PageLoader />}>
-    <PermissionGuard permissions={ROUTES['business.hr.employees'].permissions}>
+    <PermissionGuard permissions={ROUTES['hr.employees'].permissions}>
       <EmployeesPage />
     </PermissionGuard>
   </Suspense>
@@ -49,7 +49,7 @@ element: (
 **FORBIDDEN:**
 ```tsx
 // WRONG: static import in route file
-import { EmployeesPage } from '@/pages/Business/HumanResources/Employees/EmployeesPage';
+import { EmployeesPage } from '@/pages/HumanResources/Employees/EmployeesPage';
 
 // WRONG: no Suspense wrapper
 element: <EmployeesPage />
@@ -65,7 +65,7 @@ element: <EmployeesPage />
 **CORRECT — Lazy imports in client App.tsx:**
 ```tsx
 const ClientsListPage = lazy(() =>
-  import('@/pages/Business/HumanResources/Clients/ClientsListPage')
+  import('@/pages/HumanResources/Clients/ClientsListPage')
     .then(m => ({ default: m.ClientsListPage }))
 );
 ```
@@ -73,7 +73,7 @@ const ClientsListPage = lazy(() =>
 **FORBIDDEN — Static imports in client App.tsx:**
 ```tsx
 // WRONG: Static import kills code splitting
-import { ClientsListPage } from '@/pages/Business/HumanResources/Clients/ClientsListPage';
+import { ClientsListPage } from '@/pages/HumanResources/Clients/ClientsListPage';
 ```
 
 > **Note:** The `smartstackRoutes.tsx` from the npm package may use static imports internally — this is acceptable for the package. But client `App.tsx` code MUST always use lazy imports for business pages.
@@ -425,8 +425,8 @@ const handleTabClick = (tab: TabKey) => {
 
 | Action | Route pattern | Page component | File location |
 |--------|--------------|----------------|---------------|
-| Create | `/{module}/create` | `EntityCreatePage` | `src/pages/{Context}/{App}/{Module}/EntityCreatePage.tsx` |
-| Edit | `/{module}/:id/edit` | `EntityEditPage` | `src/pages/{Context}/{App}/{Module}/EntityEditPage.tsx` |
+| Create | `/{module}/create` | `EntityCreatePage` | `src/pages/{App}/{Module}/EntityCreatePage.tsx` |
+| Edit | `/{module}/:id/edit` | `EntityEditPage` | `src/pages/{App}/{Module}/EntityEditPage.tsx` |
 
 ### Create Page Template
 
@@ -562,11 +562,11 @@ export function EntityEditPage() {
 ```tsx
 // In route files — form pages are also lazy-loaded
 const EntityCreatePage = lazy(() =>
-  import('@/pages/Business/HumanResources/Employees/EntityCreatePage')
+  import('@/pages/HumanResources/Employees/EntityCreatePage')
     .then(m => ({ default: m.EntityCreatePage }))
 );
 const EntityEditPage = lazy(() =>
-  import('@/pages/Business/HumanResources/Employees/EntityEditPage')
+  import('@/pages/HumanResources/Employees/EntityEditPage')
     .then(m => ({ default: m.EntityEditPage }))
 );
 
@@ -610,7 +610,7 @@ const EntityEditPage = lazy(() =>
 // PermissionGuard for section-level routes
 element: (
   <Suspense fallback={<PageLoader />}>
-    <PermissionGuard permissions={ROUTES['business.app.module.section'].permissions}>
+    <PermissionGuard permissions={ROUTES['app.module.section'].permissions}>
       <SectionPage />
     </PermissionGuard>
   </Suspense>
@@ -742,7 +742,7 @@ interface EntityLookupOption {
 }
 
 interface EntityLookupProps {
-  /** API endpoint to search entities (e.g., '/api/business/human-resources/employees') */
+  /** API endpoint to search entities (e.g., '/api/human-resources/employees') */
   apiEndpoint: string;
   /** Currently selected entity ID */
   value: string | null;
@@ -948,7 +948,7 @@ import { EntityLookup } from '@/components/ui/EntityLookup';
 
 // Inside the form:
 <EntityLookup
-  apiEndpoint="/api/business/human-resources/employees"
+  apiEndpoint="/api/human-resources/employees"
   value={formData.employeeId}
   onChange={(id) => handleChange('employeeId', id)}
   label={t('module:form.employee', 'Employee')}
@@ -964,7 +964,7 @@ import { EntityLookup } from '@/components/ui/EntityLookup';
 
 // For DepartmentId FK:
 <EntityLookup
-  apiEndpoint="/api/business/human-resources/departments"
+  apiEndpoint="/api/human-resources/departments"
   value={formData.departmentId}
   onChange={(id) => handleChange('departmentId', id)}
   label={t('module:form.department', 'Department')}
@@ -1077,7 +1077,7 @@ public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
 **CORRECT — ONLY this pattern:**
 ```tsx
 <EntityLookup
-  apiEndpoint="/api/business/human-resources/departments"
+  apiEndpoint="/api/human-resources/departments"
   value={formData.departmentId}
   onChange={(id) => handleChange('departmentId', id)}
   label={t('module:form.department', 'Department')}
@@ -1156,7 +1156,7 @@ The `DocRenderer` shared component renders all 8 documentation sections (overvie
 If the automatic route mapping doesn't work for your module, pass a custom URL:
 
 ```tsx
-<DocToggleButton customDocUrl="/docs/business/human-resources/employees" />
+<DocToggleButton customDocUrl="/docs/human-resources/employees" />
 ```
 
 ### Rules
@@ -1181,7 +1181,7 @@ Before marking frontend tasks as complete, verify:
 - [ ] No hardcoded strings in JSX — all text goes through `t()`
 - [ ] CSS uses variables only — no hardcoded Tailwind colors (BLOCKING POST-CHECK 13)
 - [ ] Pages follow loading → error → content pattern
-- [ ] Pages use `src/pages/{Context}/{App}/{Module}/` hierarchy
+- [ ] Pages use `src/pages/{App}/{Module}/` hierarchy
 - [ ] API calls use generated hooks or `apiClient` (never raw axios)
 - [ ] Components use SmartTable/SmartFilter/EntityCard (never raw HTML tables)
 - [ ] **FK fields use `EntityLookup` — ZERO plain text inputs for Guid FK fields**
@@ -1470,7 +1470,7 @@ And in the module-specific translation files (e.g., `employees.json`):
 ### Test File Convention
 
 ```
-src/pages/{Context}/{App}/{Module}/
+src/pages/{App}/{Module}/
 ├── EntityCreatePage.tsx
 ├── EntityCreatePage.test.tsx    ← MANDATORY
 ├── EntityEditPage.tsx

package/templates/skills/apex/references/smartstack-layers.md

@@ -7,9 +7,9 @@
 
 ## Layer 0 — Domain (sequential)
 
-**Entities:** `Domain/Entities/{ContextPascal}/{App}/{Module}/`
-**Enums:** `Domain/Enums/{ContextPascal}/{App}/{Module}/`
-**Exceptions:** `Domain/Exceptions/{ContextPascal}/{App}/{Module}/`
+**Entities:** `Domain/Entities/{App}/{Module}/`
+**Enums:** `Domain/Enums/{App}/{Module}/`
+**Exceptions:** `Domain/Exceptions/{App}/{Module}/`
 
 | Action | Tool |
 |--------|------|
@@ -32,7 +32,7 @@
 
 ## Layer 0 — Infrastructure: EF Core (sequential)
 
-**Configs:** `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/`
+**Configs:** `Infrastructure/Persistence/Configurations/{App}/{Module}/`
 **Migrations:** `Infrastructure/Persistence/Migrations/` (NEVER subdirectories)
 
 | Action | Tool |
@@ -60,10 +60,10 @@
 
 ## Layer 1 — Application (parallel with API)
 
-**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/` (interface)
-**Service impls:** `Infrastructure/Services/{ContextPascal}/{App}/{Module}/` (implementation)
-**DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
-**Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`
+**Services:** `Application/Services/{App}/{Module}/` (interface)
+**Service impls:** `Infrastructure/Services/{App}/{Module}/` (implementation)
+**DTOs:** `Application/DTOs/{App}/{Module}/`
+**Validators:** `Application/Validators/{App}/{Module}/`
 
 | Action | Tool |
 |--------|------|
@@ -92,14 +92,7 @@
 
 ## Layer 1 — API (parallel with Application)
 
-**Controllers:** `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs`
-
-| Context | Controller Folder |
-|---------|-------------------|
-| `platform.administration` | `Admin` |
-| `platform.support` | `Support` |
-| `business.*` | `Business` |
-| `personal.*` | `User` |
+**Controllers:** `Api/Controllers/{AppPascal}/{Entity}Controller.cs`
 
 | Action | Tool |
 |--------|------|
@@ -110,13 +103,13 @@
 **Rules:**
 - `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
 - **NavRoute values MUST use kebab-case for ALL multi-word segments:**
-  - `[NavRoute("business.human-resources.employees")]` (CORRECT)
-  - `[NavRoute("business.humanresources.employees")]` (WRONG — missing hyphens)
-  - `[NavRoute("business.project-management.projects")]` (CORRECT)
-  - `[NavRoute("business.projectmanagement.projects")]` (WRONG)
-- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `business.human-resources.employees.read`)
+  - `[NavRoute("human-resources.employees")]` (CORRECT)
+  - `[NavRoute("humanresources.employees")]` (WRONG — missing hyphens)
+  - `[NavRoute("project-management.projects")]` (CORRECT)
+  - `[NavRoute("projectmanagement.projects")]` (WRONG)
+- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
 - FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
-- POST-CHECK 48 detects non-kebab-case NavRoute values. POST-CHECK 41 detects non-kebab-case permissions.
+- POST-CHECK 48 detects non-kebab-case NavRoute values. POST-CHECK 41 detects non-kebab-case permissions
 - **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 50)
 - `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
 - NEVER use `[Authorize]` without specific permission
@@ -130,7 +123,7 @@
 **Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
 
 > **Detailed templates:** See ralph-loop `references/core-seed-data.md` for complete C# code templates.
-> Navigation hierarchy: Context → Application → Module → Section → Resource (ALL levels need seed data).
+> Navigation hierarchy: Application → Module → Section → Resource (ALL levels need seed data).
 
 | Action | Tool |
 |--------|------|
@@ -163,20 +156,11 @@
 
 ### Deterministic GUID Pattern
 
-> **CRITICAL — NavigationContext IDs are NEVER generated.**
-> Contexts (`business`, `platform`, `personal`) are pre-seeded by SmartStack core with hardcoded GUIDs.
-> Look up the context at runtime: `db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == "business", ct)`
-> **FORBIDDEN:** `GenerateDeterministicGuid("nav:business")` or any ContextId in SeedConstants.
-
 ```csharp
 // Use SHA256 for deterministic GUIDs (reproducible across environments)
 // NOTE: Application/Module/Section/Resource IDs are deterministic.
-//       Context IDs are NOT — they are pre-seeded by SmartStack core.
 public static readonly Guid ModuleId = GenerateDeterministicGuid("nav-module-{app}-{module}");
 
-// FORBIDDEN — Context IDs must NOT be generated:
-// public static readonly Guid BusinessContextId = GenerateDeterministicGuid("nav:business"); // WRONG!
-
 private static Guid GenerateDeterministicGuid(string input)
 {
     var hash = System.Security.Cryptography.SHA256.HashData(
@@ -192,19 +176,18 @@ private static Guid GenerateDeterministicGuid(string input)
 > **Routes stored in DB drive the platform menu AND application-tracking.**
 > Short routes (e.g., `humanresources`) cause **400 Bad Request** on every page navigation.
 
-**Route format: `/{context}/{app-kebab}/{module-kebab}/{section-kebab}`**
+**Route format: `/{app-kebab}/{module-kebab}/{section-kebab}`**
 
 | Level | Code (C#) | Route (DB) |
 |-------|-----------|-----------|
-| Application | `human-resources` | `/business/human-resources` |
-| Module | `employees` | `/business/human-resources/employees` |
-| Section | `departments` | `/business/human-resources/employees/departments` |
-| Resource | `export` | `/business/human-resources/employees/departments/export` |
+| Application | `human-resources` | `/human-resources` |
+| Module | `employees` | `/human-resources/employees` |
+| Section | `departments` | `/human-resources/employees/departments` |
+| Resource | `export` | `/human-resources/employees/departments/export` |
 
-**Platform examples (verified from SmartStack.app):**
-- `/platform/administration` (not `administration`)
-- `/platform/administration/users` (not `users`)
-- `/personal/myspace/profile` (not `profile`)
+**Examples (verified from SmartStack.app):**
+- `/administration` (not `administration` without `/`)
+- `/administration/users` (not `users`)
 
 - PascalCase for C# code identifiers (`HumanResources`)
 - **kebab-case** for ALL URL routes in seed data (`human-resources`)
@@ -216,32 +199,31 @@ private static string ToKebabCase(string value)
     => System.Text.RegularExpressions.Regex.Replace(value, "([a-z])([A-Z])", "$1-$2").ToLowerInvariant();
 
 // Route construction:
-var appRoute = $"/{ToKebabCase(contextCode)}/{ToKebabCase(appCode)}";
-// → "/business/human-resources"
+var appRoute = $"/{ToKebabCase(appCode)}";
+// → "/human-resources"
 
 var moduleRoute = $"{appRoute}/{ToKebabCase(moduleCode)}";
-// → "/business/human-resources/employees"
+// → "/human-resources/employees"
 
 var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
-// → "/business/human-resources/employees/departments"
+// → "/human-resources/employees/departments"
 ```
 
 **ROUTE SPECIAL CASES (list and detail sections):**
 > `list` and `detail` are view modes of the module, NOT functional sub-areas.
-> - `list` section route = module route (e.g., `/business/human-resources/employees`) — NO `/list` suffix
-> - `detail` section route = module route + `/:id` (e.g., `/business/human-resources/employees/:id`) — NOT `/detail/:id`
+> - `list` section route = module route (e.g., `/human-resources/employees`) — NO `/list` suffix
+> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
 > - FORBIDDEN: `/employees/list`, `/employees/detail/:id`
 > - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
 
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
-- `DeterministicGuid("nav:business")` for ContextId → context IDs are pre-seeded by SmartStack core, look up by code at runtime
 - Missing translations (must have fr, en, it, de)
 - Empty seed classes with no seeding logic
 - PascalCase in route URLs → always kebab-case
 - Missing NavigationApplicationSeedData → menu invisible
-- **Short routes without `/` prefix** → `"humanresources"` must be `"/business/human-resources"`
-- **Routes without parent hierarchy** → `"employees"` must be `"/business/human-resources/employees"`
+- **Short routes without `/` prefix** → `"humanresources"` must be `"/human-resources"`
+- **Routes without parent hierarchy** → `"employees"` must be `"/human-resources/employees"`
 
 ---
 
@@ -249,7 +231,7 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 
 > **Detailed patterns:** See `references/smartstack-frontend.md` for complete code templates.
 
-**Pages:** `src/pages/{ContextPascal}/{AppPascal}/{Module}/`
+**Pages:** `src/pages/{AppPascal}/{Module}/`
 **Components:** `src/components/{Module}/`
 
 | Action | Tool |
@@ -259,13 +241,7 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 | Complex pages | /ui-components skill + `smartstack-frontend.md` patterns |
 | Validate routes | MCP `validate_frontend_routes` |
 
-**Layout mapping:**
-
-| Context | Layout | Route prefix |
-|---------|--------|-------------|
-| `platform.*` | `AdminLayout` | `/platform` |
-| `business.*` | `BusinessLayout` | `/business` |
-| `personal.*` | `UserLayout` | `/personal/myspace` |
+**Layout mapping:** Configured per application in the routing configuration.
 
 ### Lazy Loading (MANDATORY)
 
@@ -273,7 +249,7 @@ ALL page components MUST be lazy-loaded using `React.lazy()`:
 
 ```tsx
 const EmployeesPage = lazy(() =>
-  import('@/pages/Business/HumanResources/Employees/EmployeesPage')
+  import('@/pages/HumanResources/Employees/EmployeesPage')
     .then(m => ({ default: m.EmployeesPage }))
 );
 
@@ -326,7 +302,7 @@ If the module defines `{sections}`, generate frontend routes for EACH section as
 { path: '{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
 ```
 
-Section pages live in `src/pages/{ContextPascal}/{AppPascal}/{Module}/{Section}/`.
+Section pages live in `src/pages/{AppPascal}/{Module}/{Section}/`.
 
 ### FK Fields in Forms (CRITICAL)
 
@@ -335,7 +311,7 @@ Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST
 ```tsx
 // CORRECT — EntityLookup for FK field (ONLY acceptable pattern)
 <EntityLookup
-  apiEndpoint="/api/business/human-resources/employees"
+  apiEndpoint="/api/human-resources/employees"
   value={formData.employeeId}
   onChange={(id) => handleChange('employeeId', id)}
   label={t('module:form.employee', 'Employee')}
@@ -358,7 +334,7 @@ Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST
 See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` component definition and usage patterns.
 
 **FORBIDDEN:**
-- `src/pages/{Module}/` (flat, missing Context/App)
+- `src/pages/{Module}/` (flat, missing App)
 - `import axios` → use `@/services/api/apiClient`
 - `<table>` → use SmartTable
 - `<input type="text">` for FK Guid fields → use `EntityLookup`

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

@@ -1,6 +1,6 @@
 ---
 name: step-00-init
-description: Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge the need
+description: Parse flags, detect application, verify MCP, define hierarchy (4 levels), challenge the need
 model: sonnet
 next_step: steps/step-01-analyze.md
 ---
@@ -62,7 +62,6 @@ IF delegate_mode:
   Read prd.json from {delegate_prd_path}
 
   Extract context:
-    {context_code}      = prd.project.context          (e.g., "business")
     {app_name}          = prd.project.application       (e.g., "HumanResources")
     {module_code}       = prd.project.module            (e.g., "EmployeeManagement")
     {prd_path}          = {delegate_prd_path}
@@ -89,13 +88,13 @@ IF delegate_mode:
     {has_dependencies}   = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
     {key_properties}     = [] (extracted during step-01 from feature.json if available)
 
-  SKIP sections 2 (detect context), 4 (hierarchy), 5 (challenge questions)
+  SKIP sections 2 (detect application), 4 (hierarchy), 5 (challenge questions)
   Jump to section 3 (MCP verify) → then section 6 (determine needs, already set) → section 9 (summary)
 ```
 
 ---
 
-## 2. Detect SmartStack Context
+## 2. Detect SmartStack Application
 
 Scan the project to identify the SmartStack hierarchy:
 
@@ -107,7 +106,6 @@ Scan the project to identify the SmartStack hierarchy:
 ```
 
 **From task description, infer:**
-- `{context_code}`: business (default), platform, personal
 - `{app_name}`: application name
 - `{module_code}`: target module
 - `{sections}`: sections being added/modified
@@ -116,7 +114,7 @@ Scan the project to identify the SmartStack hierarchy:
 - `{prd_path}`: `.ralph/prd-{module_code}.json` if exists
 - `{feature_path}`: `docs/business/{app}/{module}/business-analyse/*/feature.json` if exists
 
-If hierarchy cannot be inferred → load context detection question from `references/challenge-questions.md`.
+If hierarchy cannot be inferred → load application question from `references/challenge-questions.md`.
 
 ---
 
@@ -131,24 +129,14 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 ---
 
-## 4. Define Navigation Hierarchy (5 Levels)
+## 4. Define Navigation Hierarchy (4 Levels)
 
-> **BLOCKING RULE:** SmartStack uses a 5-level navigation hierarchy:
-> **Context → Application → Module → Section → Resource**
->
-> **Every module MUST have at least one section.** A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
-
-### 4a. Validate Application Level
-
-Load and execute application question from `references/challenge-questions.md` section 4a.
-
-### 4b. Validate Module Level
-
-Load and execute module question from `references/challenge-questions.md` section 4b.
-
-### 4c. Define Sections (MANDATORY — at least one)
-
-Load and execute section questions from `references/challenge-questions.md` section 4c (includes validation and storage format).
+> **Reference:** Load `references/initialization-challenge-flow.md` for detailed challenge flow:
+> - 4-level hierarchy structure (Application → Module → Section → Resource)
+> - Challenge questions (4a: Application, 4b: Module, 4c: Sections)
+> - Validation rules (sections MUST have at least one entry)
+> - Storage format for each level
+> - Delegate mode skip (if -d)
 
 ### 4d. Resources (Optional)
 
@@ -163,8 +151,8 @@ Resources are OPTIONAL — only define if explicitly mentioned or inferred.
 Display before proceeding:
 
 ```
-{context_code} → {app_name} ({app_code}) → {module_code} → [{sections[].code}]
-Routes: /{context_code}/{app-kebab}/{module-kebab}/{section-kebab}
+{app_name} ({app_code}) → {module_code} → [{sections[].code}]
+Routes: /{app-kebab}/{module-kebab}/{section-kebab}
 ```
 
 ---
@@ -305,7 +293,7 @@ IF save_mode:
 ```
 APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
-Context: {context_code} → {app_name} → {module_code} → {sections[].code}
+Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
 PRD: {prd_path||none} | Feature: {feature_path||none} | Flags: {active_flags}
 MCP: {available|degraded} | Needs: migration/seed/workflow/notification = {yes|no}

package/templates/skills/apex/steps/step-01-analyze.md

@@ -141,149 +141,16 @@ Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedCons
 
 ---
 
-## 4. FK Field Detection
-
-For each entity found (or to be created), identify FK relationships:
-- Properties ending in "Id" with matching navigation property
-- Record: `{ entity, fkProperty, targetEntity, isRequired }`
-
-**Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>` — even with API-loaded options)
-2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
-
----
-
-## 4a. Tenant Mode Decision
-
-For each entity found (or to be created), determine the `tenantMode`:
-
-- **`strict`** (default) — Data belongs to a specific tenant. Examples: Employee, Order, Invoice, CustomerInteraction
-- **`optional`** — Data can be shared across tenants OR tenant-specific. Examples: Department, Currency, JobTitle, Language
-- **`scoped`** — Data has explicit visibility scope controlled by workflow/feature rules. Examples: Settings, Workflow, EmailTemplate, ApprovalConfig
-- **`none`** — Platform-wide data (never tenant-filtered). Examples: Navigation, Permission, User, SystemConfiguration
-
-**Why:** Tenant mode drives EF query filters, seed data generation, and API access control. Must be decided before planning.
-
-**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
-
----
-
-## 4b. Code Pattern Detection
-
-For each entity found (or to be created), identify code generation needs:
-
-```
-IF feature.json exists AND entity has codePattern:
-  → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
-  → Record in analysis: entity has auto-generated code
-
-ELSE IF feature.json exists BUT entity has NO codePattern:
-  → Record: entity needs codePattern decision in step-02
-  → Apply heuristic default based on entity name:
-    Invoice/Order/Receipt → timestamp-daily
-    Ticket/Incident → timestamp-minute
-    Contract/Policy → year-sequential
-    Reference/Category → uuid-short
-    Employee/Customer/Project → sequential
-
-ELSE (no feature.json):
-  → Propose codePattern during step-02 planning based on task description
-```
-
-**Why:** Code generation strategy drives CreateDto structure (Code field removed when auto-generated), service injection (ICodeGenerator<T>), and DI registration. Must be decided before planning.
-
-**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
-
----
-
-## 5. Gap Analysis
-
-Compare what EXISTS vs what the TASK REQUIRES:
-
-```
-For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
-```
-
-Cross-reference with step-00 challenge responses:
-- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
-- Each section: NavigationSectionSeedData, frontend route → exists/missing
-- If dependencies: verify FK target entities and their `?search=` support
-
----
-
-## 5b. Scope Re-Check (after exploration)
-
-> **Re-validate scope after code exploration reveals the true entity count.**
-> Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
-
-```
-IF NOT delegate_mode:
-  actual_entities = count of entities marked "create" in gap analysis
-  actual_sections = count of sections marked "create"
-
-  IF actual_entities > 6:
-    WARNING: "Code exploration reveals {actual_entities} entities to create.
-     This exceeds the recommended maximum (4) for a single /apex invocation.
-     Risk: incomplete migrations, lost conventions, missing pages.
-     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
-
-    AskUserQuestion: (same options as step-00 section 5d)
-```
-
----
-
-## 6. Analysis Validation (User Checkpoint)
-
-> **Objective:** Present findings and validate scope with the user BEFORE planning.
-
-### 6a. Present Findings
-
-```
-ANALYSIS FINDINGS
-═══════════════════════════════════════════════════════════════
-
-Entities expected / found / to create: {summary}
-Sections expected / found / to create: {summary}
-FK Relationships: {fkFields summary}
-Dependencies: {cross-module refs or "none"}
-Complexity: {module_complexity}
-```
-
-### 6b. Validate with User (if NOT auto_mode)
-
-```yaml
-questions:
-  - header: "Scope"
-    question: "Based on the analysis above, is the scope accurate?"
-    options:
-      - label: "Scope is correct (Recommended)"
-        description: "Proceed to planning with the identified elements"
-      - label: "Add elements"
-        description: "I need to add entities, properties, or sections"
-      - label: "Reduce scope"
-        description: "Remove some elements — smaller first iteration"
-      - label: "Change approach"
-        description: "The analysis reveals issues — let's adjust"
-    multiSelect: false
-```
-
-If "Add elements": update `{entities}`, `{sections}`, `{key_properties}`, re-run gap analysis.
-If "Reduce scope": update variables accordingly.
-If "Change approach": discuss with user, potentially restart from step-00.
-
----
-
-## 7. Analysis Summary
-
-```
-**APEX SmartStack - Analysis Complete**
-Navigation: {context_code} → {app_name} → {module_code} → {sections[].code}
-Entities: {entity_name → create | modify | skip}
-Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
-Required: create / modify / skip lists
-Profile: complexity, dependencies, FK fields, workflow, notifications
-ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
-```
+## 4-7. Analysis Methods & Validation
+
+> **Reference:** Load `references/analysis-methods.md` for detailed analysis procedures:
+> - FK field detection (frontend EntityLookup + backend search support)
+> - Tenant mode decision (strict/optional/scoped/none)
+> - Code pattern detection (auto-generated strategies)
+> - Gap analysis (exists/missing/modify classification)
+> - Scope re-check (entity count validation)
+> - Analysis validation checkpoint (user confirmation)
+> - Analysis summary output format
 
 ---