@atlashub/smartstack-cli 3.31.0 → 3.32.0

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

@@ -17,7 +17,12 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
-- Inherit `BaseEntity`, implement `ITenantEntity` + `IAuditableEntity`
+- Inherit `BaseEntity`, choose tenant interface based on data isolation requirements:
+  - **`ITenantEntity`** (strict mode, default): User can only access their tenant's data. Implement `Guid TenantId { get; set; }`. Service MUST filter by `_currentTenant.TenantId` with guard clause.
+  - **`IOptionalTenantEntity`** (optional mode): Cross-tenant data (shared lookup tables, public content). Implement `Guid? TenantId { get; set; }`. Service MAY accept null TenantId. EF global filter handles both shared (null) and tenant-scoped (TenantId == current) rows automatically.
+  - **`IScopedTenantEntity`** (scoped mode): Data scoped by Scope + TenantId combination. Validate both match current context in service layer.
+  - **No tenant interface** (none mode): Cross-tenant system data (no isolation). No TenantId property, no filtering needed.
+- Also implement `IAuditableEntity` for CreatedBy/UpdatedBy tracking
 - See `references/smartstack-api.md` for exact BaseEntity API (Id, CreatedAt, UpdatedAt only)
 - No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
 - Domain events for state changes
@@ -62,8 +67,12 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
-- **ALL services MUST inject `ICurrentUserService` + `ICurrentTenantService` and filter by `TenantId`** (see `smartstack-api.md` Service Pattern)
-- **ALL services MUST use guard clause:** `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (returns 400, NOT 401 — a missing tenant is a bad request, not an auth failure)
+- **Tenant injection depends on entity tenant mode** (see entity rules below):
+  - **strict mode (default):** Inject `ICurrentTenantService` + guard clause: `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (mandatory, returns 400)
+  - **optional mode:** Inject `ICurrentTenantService`, no guard: `var tenantId = _currentTenant.TenantId;` (nullable). EF global filter handles shared+tenant data.
+  - **scoped mode:** Inject `ICurrentTenantService`, validate Scope + TenantId consistency. Tenant scope requires TenantId.
+  - **none mode:** No `ICurrentTenantService` injection needed (cross-tenant data, no filtering)
+- **ALL services MUST inject `ICurrentUserService`** for audit trails
 - **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
 - FluentValidation for all commands
@@ -272,7 +281,19 @@ const [loading, setLoading] = useState(true);
 ### Components & CSS
 
 **Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
-**CSS:** Variables only → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`, `border-[var(--border-color)]`
+**CSS:** Variables ONLY — hardcoded Tailwind colors are **BLOCKING** in POST-CHECK 13:
+
+| Instead of | Use |
+|-----------|-----|
+| `bg-white` | `bg-[var(--bg-card)]` |
+| `bg-gray-50` | `bg-[var(--bg-primary)]` |
+| `text-gray-900` | `text-[var(--text-primary)]` |
+| `text-gray-500` | `text-[var(--text-secondary)]` |
+| `border-gray-200` | `border-[var(--border-color)]` |
+| `bg-blue-600` | `bg-[var(--color-accent-500)]` |
+| `hover:bg-blue-700` | `hover:bg-[var(--color-accent-600)]` |
+| `text-red-500` | `text-[var(--error-text)]` |
+
 **Loader:** `Loader2` from `lucide-react` for spinners, `PageLoader` for Suspense fallback
 
 ### Section Routes (when module has sections)
@@ -291,10 +312,10 @@ Section pages live in `src/pages/{ContextPascal}/{AppPascal}/{Module}/{Section}/
 
 ### FK Fields in Forms (CRITICAL)
 
-Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST use the `EntityLookup` component — NEVER a plain text input. Users cannot type GUIDs manually.
+Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST use the `EntityLookup` component — NEVER a `<select>` dropdown, NEVER a `<input type="text">`. Users cannot type GUIDs manually, and `<select>` fails at scale (no search, loads all options).
 
 ```tsx
-// CORRECT — EntityLookup for FK field
+// CORRECT — EntityLookup for FK field (ONLY acceptable pattern)
 <EntityLookup
   apiEndpoint="/api/business/human-resources/employees"
   value={formData.employeeId}
@@ -306,6 +327,12 @@ Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST
 
 // WRONG — plain text input for FK GUID
 <input type="text" value={formData.employeeId} placeholder="Enter employee ID" />
+
+// WRONG — <select> dropdown for FK field (even with API-loaded options)
+<select value={formData.departmentId} onChange={(e) => setFormData({...formData, departmentId: e.target.value})}>
+  <option value="">Select...</option>
+  {departments.map(d => <option key={d.id} value={d.id}>{d.name}</option>)}
+</select>
 ```
 
 **Backend requirement:** Each target entity's GetAll endpoint MUST accept `?search=` parameter. See `smartstack-api.md` Service Pattern.
@@ -317,6 +344,7 @@ See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` co
 - `import axios` → use `@/services/api/apiClient`
 - `<table>` → use SmartTable
 - `<input type="text">` for FK Guid fields → use `EntityLookup`
+- `<select>` for FK Guid fields → use `EntityLookup` (even with API-loaded options)
 - Placeholder "Enter ID" or "Enter GUID" → use `EntityLookup`
 - Hardcoded Tailwind colors (`bg-white`, `text-gray-900`) → use CSS variables
 - Static page imports in route files → use `React.lazy()`
@@ -346,7 +374,26 @@ t('{module}:actions.create', 'Create entity') // ALWAYS with namespace prefix
 
 ---
 
-## Layer 3 — Tests (sequential, if -t)
+## Layer 2b — Documentation (after frontend pages exist)
+
+> **After frontend pages are created, generate module documentation.**
+
+| Action | Tool |
+|--------|------|
+| Generate doc-data.ts + page wrapper | `/documentation` skill (type: user) |
+| Verify DocToggleButton in pages | POST-CHECK 29 |
+
+**Output files:**
+- `src/pages/docs/business/{app}/{module}/doc-data.ts` — data-driven documentation
+- `src/pages/docs/business/{app}/{module}/index.tsx` — page wrapper using `DocRenderer`
+- `src/i18n/locales/fr/docs-{app}-{module}.json` — French doc translations
+
+**DocToggleButton (MANDATORY):** Every list/detail page must include `DocToggleButton` in its header.
+See `references/smartstack-frontend.md` section 7 for the component pattern.
+
+---
+
+## Layer 3 — Tests (sequential)
 
 | Action | Tool |
 |--------|------|

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

@@ -28,7 +28,7 @@ Extract flags from the raw input:
 ```
 Input: "{raw_input}"
 
-Flags to detect: -a, -x, -s, -t, -e, -r, -pr
+Flags to detect: -a, -x, -s, -e, -r, -pr
 Remaining text after flag removal = {task_description}
 ```
 
@@ -38,7 +38,6 @@ Remaining text after flag removal = {task_description}
 auto_mode: false
 examine_mode: false
 save_mode: false
-test_mode: false
 economy_mode: false
 pr_mode: false
 resume_mode: false

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

@@ -111,8 +111,51 @@ For each entity found (or to be created), identify FK relationships:
 - Record: `{ entity, fkProperty, targetEntity, isRequired }`
 
 **Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `EntityLookup` (NEVER plain text for GUIDs)
-2. **Backend:** Each target entity's GetAll MUST support `?search=`
+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.
 
 ---
 

package/templates/skills/apex/steps/step-02-plan.md

@@ -32,6 +32,17 @@ For each element identified in step-01 (create or modify), assign to a SmartStac
 | 2 | I18n (translations) | Parallel |
 | 3 | Tests | Sequential |
 
+**Entity Definition Template:** Each entity in the plan MUST include:
+```
+Entity: {EntityName}
+  - tenantMode: strict | optional | scoped | none
+  - codePattern: auto-generated strategy (if applicable)
+  - fkFields: [{field, targetEntity}] (if applicable)
+  - acceptance criteria: [AC1, AC2, ...]
+```
+
+The `tenantMode` decision (from step-01, section 4a) drives EF query filters, seed data approach, and API authorization. See `smartstack-layers.md` for tenant mode seed data strategies.
+
 ---
 
 ## 2. Assign Skill/MCP per File
@@ -56,6 +67,7 @@ For EACH file in the plan, specify HOW it will be created/modified:
 | 6 | Api/Controllers/.../MyController.cs | create | /controller skill |
 | 7 | Seeding/Data/NavigationApplicationSeedData.cs | create | ref smartstack-layers.md (once per app) |
 | 7b | Seeding/Data/ApplicationRolesSeedData.cs | create | ref smartstack-layers.md (once per app) |
+| 7c | Infrastructure/Services/CodeGeneration/ | create | ref code-generation.md (ICodeGenerator<T> + DI, per entity with codePattern != manual) |
 | 8 | Seeding/Data/.../NavigationModuleSeedData.cs | create | ref smartstack-layers.md |
 | 8b | Application/Authorization/Permissions.cs | create | MCP generate_permissions → static constants |
 | 9 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
@@ -76,7 +88,14 @@ For EACH file in the plan, specify HOW it will be created/modified:
 
 **FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6). The corresponding backend GetAll endpoints (Layer 1) MUST support `?search=` parameter.
 
-### Layer 3 — Tests (sequential, if -t)
+### Layer 2b — Documentation (after frontend pages exist)
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 14b | src/pages/docs/business/{app}/{module}/doc-data.ts | create | /documentation skill |
+| 14c | src/pages/docs/business/{app}/{module}/index.tsx | create | /documentation skill |
+
+### Layer 3 — Tests (sequential)
 
 | # | File | Action | Tool |
 |---|------|--------|------|
@@ -114,6 +133,8 @@ Verify the plan respects dependencies:
 ```
 - Migration AFTER EF configs (always)
 - Application services AFTER domain entities (always)
+- Code generator service AFTER entity + EF config (needs DbSet for sequence query)
+- CreateDto adjustments AFTER code pattern decision (remove Code property if auto-generated)
 - Controllers AFTER application services (always)
 - Frontend AFTER API controllers (API contract needed)
 - Seed data AFTER navigation module exists
@@ -130,7 +151,7 @@ feat({module}): [domain+infra] {description}
 feat({module}): [app+api] {description}
 feat({module}): [frontend] {description}
 feat({module}): [seed] {description}
-feat({module}): [tests] {description}    # if -t
+feat({module}): [tests] {description}
 ```
 
 ---

package/templates/skills/apex/steps/step-03-execute.md

@@ -69,12 +69,32 @@ dotnet build
 
 Execute each item from the plan sequentially using skills and MCP.
 
+### Code Generation (if entities have codePattern != "manual")
+
+For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
+
+```
+1. Create CodePatternConfig for the entity (strategy, prefix, digits from codePattern)
+2. Register ICodeGenerator<TEntity> in DependencyInjection.cs (Infrastructure layer)
+   → See references/code-generation.md for DI registration pattern
+3. Update CreateDto: REMOVE Code property (auto-generated, not user-provided)
+4. Update CreateDtoValidator: REMOVE Code regex rule (not in DTO anymore)
+5. Update service CreateAsync: inject ICodeGenerator<TEntity>, call NextCodeAsync()
+   → Code is auto-generated BEFORE entity creation
+   → See references/code-generation.md for service integration pattern
+6. Keep Code in ResponseDto (returned to frontend after creation)
+7. Keep Code in UpdateDto ONLY if code is mutable (rare — discuss with user)
+```
+
+**CRITICAL:** If `codePattern.strategy == "manual"` (or no codePattern), keep the current behavior:
+Code stays in CreateDto, user provides it, validator has regex rule.
+
 **For frontend tasks (economy_mode):** Follow the same rules as exec-frontend above:
 - `MCP scaffold_api_client` → API client + types + React Query hook
 - `MCP scaffold_routes` with `outputFormat: 'clientRoutes'` for lazy imports
 - Pages: use `/ui-components` skill — MANDATORY for entity lists, grids, tables, dashboards
 - **Form pages: Create `EntityCreatePage.tsx` (route: `/create`) and `EntityEditPage.tsx` (route: `/:id/edit`)**
-- **FK FIELDS (CRITICAL):** Any Guid FK property (e.g., EmployeeId, DepartmentId) MUST use `EntityLookup` component — NEVER a plain text input. See `smartstack-frontend.md` section 6.
+- **FK FIELDS (CRITICAL):** Any Guid FK property (e.g., EmployeeId, DepartmentId) MUST use `EntityLookup` component — NEVER a `<select>` dropdown, NEVER a `<input type="text">`. A `<select>` loaded from API state is NOT a substitute for EntityLookup. See `smartstack-frontend.md` section 6.
 - **ZERO modals/popups/drawers for forms — ALL forms are full pages with their own URL**
 - **Form tests: Generate `EntityCreatePage.test.tsx` and `EntityEditPage.test.tsx` (co-located)**
 - **SECTION PERMISSIONS:** After calling `MCP generate_permissions` for the module navRoute (3 segments: `{context}.{app}.{module}`), also call it for EACH section navRoute (4 segments: `{context}.{app}.{module}.{section}`)
@@ -127,9 +147,11 @@ Spawn 2 teammates (Opus, full tools):
       → Back button with navigate(-1) on every form page
       → See smartstack-frontend.md section 3b for templates
     - **FK FIELDS (CRITICAL):** Foreign key Guid fields (e.g., EmployeeId) MUST use EntityLookup:
-      → NEVER render FK fields as plain text inputs — users cannot type GUIDs
-      → Use EntityLookup from @/components/ui/EntityLookup for searchable selection
+      → NEVER render FK fields as `<input>` — users cannot type GUIDs
+      → NEVER render FK fields as `<select>` — even with API-loaded options, `<select>` is NOT acceptable
+      → ONLY use `<EntityLookup />` from @/components/ui/EntityLookup for searchable selection
       → Each FK field needs: apiEndpoint, mapOption (display name), search support on backend
+      → FORBIDDEN: `<select value={formData.departmentId}>`, `<option value={dept.id}>`, `e.target.value` for FK fields
       → See smartstack-frontend.md section 6 for the full EntityLookup pattern
     - **FORM TESTS (MANDATORY):**
       → EntityCreatePage.test.tsx (co-located next to page)
@@ -173,6 +195,28 @@ shutdown_request → shutdown_response → TeamDelete("apex-exec")
 
 ---
 
+## Layer 2b — Documentation (after frontend pages exist)
+
+> **After frontend pages are created, generate module documentation via `/documentation` skill.**
+
+```
+Invoke /documentation {module_code} --type user
+
+This generates:
+- src/pages/docs/business/{app}/{module}/doc-data.ts (data file)
+- src/pages/docs/business/{app}/{module}/index.tsx (page wrapper)
+- src/i18n/locales/fr/docs-{app}-{module}.json (French doc translations)
+- Updates App.tsx routing for doc page
+- Updates docs-manifest.json
+```
+
+**Verify DocToggleButton presence in list/detail pages:**
+- Every `*ListPage.tsx` and `*DetailPage.tsx` MUST import and render `DocToggleButton` in their header
+- Import: `import { DocToggleButton } from '@/components/docs/DocToggleButton';`
+- Placement: inside the header actions area (see `smartstack-frontend.md` section 7)
+
+---
+
 ## Layer 2 — Final Seed Data + Validation (sequential)
 
 After Layer 1 completes:
@@ -192,14 +236,160 @@ After Layer 1 completes:
 
 ---
 
+## FRONTEND COMPLIANCE GATE (MANDATORY before commit)
+
+> **BLOCKING:** Do NOT commit frontend changes until ALL checks pass.
+> These issues are the most common failures in generated code — verify EVERY item.
+
+**Run these checks on ALL generated/modified `.tsx` files BEFORE creating the frontend commit:**
+
+### Gate 1: CSS Variables (Theme System)
+
+```bash
+# Check for hardcoded Tailwind colors — MUST use CSS variables
+ALL_PAGES=$(find src/pages/ src/components/ -name "*.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\.")
+if [ -n "$ALL_PAGES" ]; then
+  HARDCODED=$(grep -Pn '(bg|text|border)-(?!\[)(red|blue|green|gray|white|black|slate|zinc|neutral|stone)-' $ALL_PAGES 2>/dev/null)
+  if [ -n "$HARDCODED" ]; then
+    echo "FAIL: Hardcoded Tailwind colors found — must use CSS variables"
+    echo "$HARDCODED"
+  else
+    echo "PASS: CSS variables"
+  fi
+fi
+```
+
+**If hardcoded colors found, replace BEFORE committing:**
+- `bg-white` → `bg-[var(--bg-card)]`
+- `bg-gray-50` → `bg-[var(--bg-primary)]`
+- `text-gray-900` → `text-[var(--text-primary)]`
+- `text-gray-500/600` → `text-[var(--text-secondary)]`
+- `border-gray-200` → `border-[var(--border-color)]`
+- `bg-blue-600` / `text-blue-600` → `bg-[var(--color-accent-500)]` / `text-[var(--color-accent-500)]`
+- `hover:bg-blue-700` → `hover:bg-[var(--color-accent-600)]`
+- `text-red-500` → `text-[var(--error-text)]`
+- `bg-green-500` → `bg-[var(--success-bg)]`
+
+### Gate 2: Forms as Pages (ZERO Modals/Drawers/Slide-overs)
+
+```bash
+# Check for modal/dialog/drawer/slide-over imports and inline form patterns — FORBIDDEN
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null)
+if [ -n "$PAGE_FILES" ]; then
+  FAIL=false
+
+  # 2a. Component imports
+  MODAL_IMPORTS=$(grep -Pn "import.*(?:Modal|Dialog|Drawer|Popup|Sheet|SlideOver|Overlay)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_IMPORTS" ]; then
+    echo "FAIL: Modal/Dialog/Drawer component imports — forms MUST be full pages"
+    echo "$MODAL_IMPORTS"
+    FAIL=true
+  fi
+
+  # 2b. State variables for inline forms (catches drawers/slide-overs without imports)
+  MODAL_STATE=$(grep -Pn "useState.*(?:isOpen|showModal|showDialog|showCreate|showEdit|showForm|isCreating|isEditing|showDrawer|showPanel|showSlideOver|selectedEntity|editingEntity)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_STATE" ]; then
+    echo "FAIL: Inline form state detected — forms MUST be separate page components with own routes"
+    echo "$MODAL_STATE"
+    FAIL=true
+  fi
+
+  if [ "$FAIL" = true ]; then
+    echo ""
+    echo "Fix: Create EntityCreatePage.tsx (route: /create) and EntityEditPage.tsx (route: /:id/edit)"
+    echo "See smartstack-frontend.md section 3b"
+  else
+    echo "PASS: No modals/drawers"
+  fi
+fi
+```
+
+**If modals/drawers found:** Replace with separate `EntityCreatePage.tsx` (route: `/{module}/create`) and `EntityEditPage.tsx` (route: `/{module}/:id/edit`). See `smartstack-frontend.md` section 3b.
+
+### Gate 3: I18n File Structure
+
+```bash
+# Verify translation files exist as separate JSON per language
+if [ ! -d "src/i18n/locales" ]; then
+  echo "FAIL: Missing src/i18n/locales/ directory — create it with 4 languages"
+else
+  for LANG in fr en it de; do
+    JSON_FILES=$(find "src/i18n/locales/$LANG" -name "*.json" 2>/dev/null | wc -l)
+    if [ "$JSON_FILES" -eq 0 ]; then
+      echo "FAIL: No JSON files in src/i18n/locales/$LANG/"
+    else
+      echo "PASS: $LANG ($JSON_FILES files)"
+    fi
+  done
+fi
+```
+
+**If i18n structure wrong:** Create `src/i18n/locales/{fr,en,it,de}/{module}.json` following the template in `smartstack-frontend.md` section 2. NEVER embed translations in a single `.ts` file.
+
+### Gate 4: Lazy Loading
+
+```bash
+# Check for static page imports in route/App files
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+ROUTE_FILES=$(find src/routes/ -name "*.tsx" -o -name "*.ts" 2>/dev/null)
+if [ -n "$APP_TSX" ]; then
+  STATIC_IMPORTS=$(grep -Pn "^import .+ from '@/pages/" "$APP_TSX" $ROUTE_FILES 2>/dev/null)
+  if [ -n "$STATIC_IMPORTS" ]; then
+    echo "FAIL: Static page imports in App.tsx/routes — MUST use React.lazy()"
+    echo "$STATIC_IMPORTS"
+  else
+    echo "PASS: Lazy loading"
+  fi
+fi
+```
+
+### Gate 5: useTranslation in Pages
+
+```bash
+# Verify pages use i18n
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null | grep -v "\.test\." | grep -v node_modules)
+if [ -n "$PAGE_FILES" ]; then
+  TOTAL=$(echo "$PAGE_FILES" | wc -l)
+  WITH_I18N=$(grep -l "useTranslation" $PAGE_FILES 2>/dev/null | wc -l)
+  if [ "$WITH_I18N" -eq 0 ]; then
+    echo "FAIL: No pages use useTranslation — all text must be translated"
+  else
+    echo "PASS: $WITH_I18N/$TOTAL pages use useTranslation"
+  fi
+fi
+```
+
+> **ALL 5 gates MUST pass before creating the frontend commit.** If ANY gate fails, fix the issues first.
+
+### Explicit I18n File Creation
+
+When creating i18n files, generate EXACTLY this structure:
+
+```
+src/i18n/locales/
+├── fr/{module}.json    ← French (primary)
+├── en/{module}.json    ← English
+├── it/{module}.json    ← Italian
+└── de/{module}.json    ← German
+```
+
+Each file MUST contain these keys: `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`. See `smartstack-frontend.md` section 2 for the complete JSON template.
+
+**When delegating to `/ui-components`:** ALWAYS include these explicit instructions in the delegation context:
+- "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`. NEVER use hardcoded Tailwind colors like `bg-white` or `text-gray-900`."
+- "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`). NEVER use modals/dialogs."
+- "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
+
+---
+
 ## Commits Per Layer
 
-After each layer completes and builds pass:
+After each layer completes, gates pass, and builds pass:
 
 ```
 Layer 0: feat({module}): [domain+infra] {short description}
 Layer 1: feat({module}): [app+api] {short description}
-Layer 1: feat({module}): [frontend] {short description}  # if applicable
+Layer 1: feat({module}): [frontend] {short description}  # if applicable — AFTER all 5 gates pass
 Layer 2: feat({module}): [seed] {short description}       # if applicable
 ```
 

package/templates/skills/apex/steps/step-04-examine.md

@@ -178,8 +178,8 @@ AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
 | Frontend | routes, lazy loading, forms as pages, i18n (4 langs + keys) | PASS / N/A |
 | Security | TenantId filter, RequirePermission, no Guid.Empty, no !.Value | PASS / N/A |
 | Seed data | completeness, deterministic GUIDs, no ContextId/RoleId constants | PASS / N/A |
-| Code quality | PaginatedResult, EntityLookup, CSS vars, search param | PASS / N/A |
-| POST-CHECKs | 21 checks from references/post-checks.md | PASS / N/A |
+| Code quality | PaginatedResult, EntityLookup (no FK select/input), CSS vars, search param | PASS / N/A |
+| POST-CHECKs | 30 checks from references/post-checks.md | PASS / N/A |
 | Acceptance criteria | AC1..ACn | {X}/{Y} PASS |
 ```
 
@@ -191,10 +191,23 @@ Write to `{output_dir}/04-examine.md` with validation results.
 
 ---
 
-## 10. Route to Next Step
+## 10. Route to Next Step — TESTS ARE MANDATORY
+
+> **CRITICAL — DO NOT STOP HERE.**
+> Step-04 (eXamine) is NOT the final step. Tests MUST be scaffolded and run.
+> Completing APEX without tests violates the methodology — skip is FORBIDDEN.
 
 ```
-examine_mode → step-05-deep-review | test_mode → step-07-tests | pr_mode → create PR | else → final summary
+IF examine_mode (-x flag):
+  → Load steps/step-05-deep-review.md (adversarial review)
+  → Then step-06 (resolve) if BLOCKING findings
+  → Then step-07 (tests) — ALWAYS
+
+ELSE:
+  → Load steps/step-07-tests.md — IMMEDIATELY after eXamine completes
 ```
 
-**FINAL SUMMARY (if no more steps):** task, context, files created/modified, validation status, commits count, next steps.
+**BLOCKING RULE:** The APEX workflow is NOT complete until steps 07-08 execute.
+The success criteria require: "Tests: 100% pass, >= 80% coverage" — this is impossible without step-07.
+
+**NEXT ACTION:** Load `steps/step-07-tests.md` now.

package/templates/skills/apex/steps/step-05-deep-review.md

@@ -61,9 +61,10 @@ For each changed file, check:
 - [ ] Correct Layout wrapper per context
 
 **FK Fields & Forms:**
-- [ ] FK Guid fields use `EntityLookup` component (NEVER plain text `<input>`)
-- [ ] No placeholder text asking user to "Enter ID" or "Enter GUID"
-- [ ] Create/Edit forms are full pages with own routes (ZERO modals/dialogs)
+- [ ] FK Guid fields use `EntityLookup` component (NEVER `<input>`, NEVER `<select>`)
+- [ ] No `<select>` with `<option>` elements for FK fields (even API-loaded options)
+- [ ] No placeholder text asking user to "Enter ID", "Enter GUID", or "Select {Entity}..."
+- [ ] No inline forms in drawers/slide-overs — Create/Edit forms are full pages with own routes (ZERO modals/dialogs/drawers)
 - [ ] Backend GetAll endpoints support `?search=` param for EntityLookup
 - [ ] Each EntityLookup has `apiEndpoint`, `mapOption`, `label` props
 
@@ -118,14 +119,11 @@ Write to `{output_dir}/05-deep-review.md` with all findings.
 
 ```
 IF BLOCKING findings exist:
-  → Load steps/step-06-resolve.md
-
-ELSE IF test_mode = true:
-  → Load steps/step-07-tests.md
-
-ELSE IF pr_mode = true:
-  → Create PR and show final summary
+  → Load steps/step-06-resolve.md (fix BLOCKING findings first)
+  → Then step-07-tests.md (tests are MANDATORY)
 
 ELSE:
-  → Show final summary and exit
+  → Load steps/step-07-tests.md — IMMEDIATELY
 ```
+
+> **REMINDER:** Tests are MANDATORY. Do NOT stop after Deep Review — proceed to step-07.

package/templates/skills/apex/steps/step-06-resolve.md

@@ -92,14 +92,10 @@ Write to `{output_dir}/06-resolve.md` with resolution log.
 
 ```
 IF remaining BLOCKING > 0:
-  → Loop: fix remaining, re-validate
+  → Loop: fix remaining, re-validate (max 3 iterations)
+  → If stuck, ask user before continuing
 
-IF test_mode = true:
-  → Load steps/step-07-tests.md
-
-ELSE IF pr_mode = true:
-  → Create PR and show final summary
-
-ELSE:
-  → Show final summary and exit
+→ Load steps/step-07-tests.md — MANDATORY, do NOT skip
 ```
+
+> **REMINDER:** Tests are MANDATORY. After resolving all findings, proceed to step-07 immediately.

package/templates/skills/apex/steps/step-07-tests.md

@@ -6,12 +6,77 @@ prev_step: steps/step-06-resolve.md
 next_step: steps/step-08-run-tests.md
 ---
 
-# Step 7: Tests (if -t)
+# Step 7: Tests
+
+> **MANDATORY STEP — This is NOT optional.** APEX requires tests for completion.
+> If you reached this step, you MUST scaffold and run tests before finishing.
 
 **Goal:** Scaffold comprehensive tests using MCP tools. Target: >= 80% coverage.
 
 ---
 
+## 0. Ensure Frontend Test Tooling Exists (if frontend was generated)
+
+> **Before scaffolding frontend tests, the test infrastructure must be in place.**
+
+```bash
+# Check if Vitest is installed
+WEB_DIR=$(find . -name "package.json" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | head -1)
+if [ -n "$WEB_DIR" ]; then
+  cd "$WEB_DIR"
+
+  # Install test dependencies if missing
+  if ! grep -q '"vitest"' package.json 2>/dev/null; then
+    npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom @types/testing-library__jest-dom
+  fi
+
+  # Create vitest.config.ts if missing
+  if [ ! -f "vitest.config.ts" ]; then
+    cat > vitest.config.ts << 'VITEST_EOF'
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    css: true,
+    include: ['src/**/*.test.{ts,tsx}'],
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});
+VITEST_EOF
+  fi
+
+  # Create test setup file if missing
+  mkdir -p src/test
+  if [ ! -f "src/test/setup.ts" ]; then
+    cat > src/test/setup.ts << 'SETUP_EOF'
+import '@testing-library/jest-dom';
+SETUP_EOF
+  fi
+
+  # Add test script to package.json if missing
+  if ! grep -q '"test"' package.json 2>/dev/null; then
+    # Use npm pkg set for safe JSON manipulation
+    npm pkg set scripts.test="vitest run"
+    npm pkg set scripts.test:watch="vitest"
+    npm pkg set scripts.test:coverage="vitest run --coverage"
+  fi
+
+  cd -
+fi
+```
+
+---
+
 ## 1. Ensure Test Projects Exist
 
 ### 1a. Unit Test Project