@atlashub/smartstack-cli 4.31.0 → 4.33.0

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

@@ -1,16 +1,14 @@
 # SmartStack Frontend Patterns — Mandatory Reference
 
-> **Loaded by:** step-03 (execution) and step-04 (validation)
-> **Purpose:** Defines mandatory frontend patterns extracted from SmartStack.app.
+> **Loaded by:** step-03d (Layer 3, deferred) and step-04 (validation)
+> **Purpose:** Mandatory frontend conventions. `/ui-components` generates pages — this file provides guard rails.
 > **Enforcement:** POST-CHECKs in step-04 verify compliance.
 
 ---
 
 ## 1. Lazy Loading (React.lazy + Suspense)
 
-> **ALL page components MUST be lazy-loaded.** Only critical entry pages (HomePage, LoginPage) may use static imports.
-
-### Import Pattern
+ALL page components MUST be lazy-loaded. Only critical entry pages (HomePage, LoginPage) may use static imports.
 
 ```tsx
 // Named exports — use .then() to wrap
@@ -20,17 +18,7 @@ const EmployeesPage = lazy(() =>
     .then(m => ({ default: m.EmployeesPage }))
 );
 
-// Default exports — direct lazy
-const DashboardPage = lazy(() => import('@/pages/Platform/Admin/DashboardPage'));
-```
-
-### Suspense Wrapper
-
-```tsx
-import { Suspense } from 'react';
-import { PageLoader } from '@/components/ui/PageLoader';
-
-// Route element wrapping
+// Suspense wrapper with PermissionGuard
 element: (
   <Suspense fallback={<PageLoader />}>
     <PermissionGuard permissions={ROUTES['hr.employees'].permissions}>
@@ -40,74 +28,27 @@ element: (
 )
 ```
 
-### Rules
-
+**Rules:**
 - Do not static-import page components in route files
 - Use `<Suspense fallback={<PageLoader />}>` around lazy components
-- Use the `.then(m => ({ default: m.ComponentName }))` pattern for named exports
-- The unified AppLayout component is ALSO lazy-loaded
-
-**Incorrect patterns:**
-```tsx
-// WRONG: static import in route file
-import { EmployeesPage } from '@/pages/HumanResources/EmployeeManagement/Employees/EmployeesPage';
-
-// WRONG: no Suspense wrapper
-element: <EmployeesPage />
-
-// WRONG: no fallback
-<Suspense><EmployeesPage /></Suspense>
-```
-
-### Client App.tsx — Lazy Imports Required
-
-In the client `App.tsx` (where application routes are defined), all page imports must use `React.lazy()`.
-
-**Correct — Lazy imports in client App.tsx:**
-```tsx
-// Path includes module level: {App}/{Module}/{Section}/{Page}
-const ClientsListPage = lazy(() =>
-  import('@/pages/HumanResources/ClientManagement/Clients/ClientsListPage')
-    .then(m => ({ default: m.ClientsListPage }))
-);
-```
-
-**Do not use — Static imports in client App.tsx:**
-```tsx
-// WRONG: Static import kills code splitting
-import { ClientsListPage } from '@/pages/HumanResources/ClientManagement/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.
+- Use `.then(m => ({ default: m.ComponentName }))` for named exports
+- Unified AppLayout is also lazy-loaded
+- Client `App.tsx` MUST always use lazy imports for business pages (static imports kill code splitting)
 
 ---
 
 ## 2. I18n / Translations (react-i18next)
 
-> **ALL user-facing text MUST use translations.** 4 languages required: fr, en, it, de.
+ALL user-facing text MUST use translations. 4 languages required: fr, en, it, de.
 
 ### File Structure
 
 ```
-src/i18n/
-├── config.ts                    # i18n initialization
-├── locales/
-│   ├── fr/
-│   │   ├── common.json          # Shared keys (actions, errors, validation)
-│   │   ├── navigation.json      # Menu labels
-│   │   └── {module}.json        # Module-specific keys
-│   ├── en/
-│   │   └── {module}.json
-│   ├── it/
-│   │   └── {module}.json
-│   └── de/
-│       └── {module}.json
+src/i18n/locales/{lang}/{module}.json  # Per-module translation file (4 languages)
 ```
 
 ### Module JSON Template
 
-Each new module MUST generate a translation file with this structure:
-
 ```json
 {
   "title": "Module display name",
@@ -171,600 +112,111 @@ Each new module MUST generate a translation file with this structure:
 }
 ```
 
-### Usage in Components
+### Usage
 
 ```tsx
-// Hook — specify namespace(s)
 const { t } = useTranslation(['employees']);
-
-// Simple key — provide fallback value
-t('employees:title', 'Employees')
-
-// Key with interpolation
-t('employees:messages.created', '{{entity}} created successfully', { entity: 'Employee' })
-
-// Namespace prefix syntax
-t('employees:actions.create', 'Create employee')
-t('common:actions.save', 'Save')
-t('common:errors.network', 'Network error')
+t('employees:title', 'Employees')                                             // Simple key + fallback
+t('employees:messages.created', '{{entity}} created', { entity: 'Employee' }) // Interpolation
+t('common:actions.save', 'Save')                                              // Cross-namespace
 ```
 
-### Namespace Registration
-
-After creating i18n JSON files, register each namespace in the i18n config.
-Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
+### Namespace Registration (CRITICAL — POST-CHECK C39)
 
-In the i18n config file (`src/i18n/config.ts` or `src/i18n/index.ts`), add each new namespace:
+After creating i18n JSON files, register each namespace in `src/i18n/config.ts`:
 
 ```typescript
-// Example: registering new module namespaces
 import employees from './locales/fr/employees.json';
-import projects from './locales/fr/projects.json';
-import clients from './locales/fr/clients.json';
-
-// In resources configuration:
-resources: {
-  fr: { employees, projects, clients, common, navigation },
-  en: { employees: employeesEn, projects: projectsEn, clients: clientsEn, ... },
-  // ... it, de
-}
-
-// OR with ns array:
-ns: ['common', 'navigation', 'employees', 'projects', 'clients'],
+// In resources: fr: { employees, common, navigation, ... }
+// OR in ns array: ns: ['common', 'navigation', 'employees'],
 ```
 
-POST-CHECK C39 validates this. Unregistered namespaces must be registered.
-
-### Rules
+Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
 
-- Provide a fallback value as 2nd argument to `t()`
-- Use namespace prefix: `t('namespace:key')`
+**Rules:**
+- Provide fallback value as 2nd argument to `t()`
+- Use namespace prefix: `t('namespace:key')` — never `t('key')` without namespace
 - Generate 4 language files (fr, en, it, de) with identical key structures
 - Register new namespaces in i18n config file after creating JSON files
 - Do not hardcode user-facing strings in JSX
-- Do not use `t('key')` without namespace prefix
-
-**Incorrect patterns:**
-```tsx
-// WRONG: no fallback
-t('employees:title')
-
-// WRONG: no namespace
-t('title')
-
-// WRONG: hardcoded text
-<h1>Employees</h1>
-
-// WRONG: only 2 languages generated
-// Must have fr, en, it, de
-```
 
 ---
 
-## 3. Page Structure Pattern
+## 3. Page Structure
 
-> **ALL pages MUST follow this structure.** Extracted from SmartStack.app reference implementation.
+> `/ui-components` generates complete pages. These rules ensure compliance.
 
-### Standard List Page Template
+### Standard List Page Structure
 
-```tsx
-import { useState, useCallback, useEffect } from 'react';
-import { useTranslation } from 'react-i18next';
-import { useNavigate, useParams } from 'react-router-dom';
-import { Loader2 } from 'lucide-react';
-import { DocToggleButton } from '@/components/docs/DocToggleButton';
-import { DataTable } from '@/components/ui/DataTable';
-
-// API hook (generated by scaffold_api_client)
-import { useEntityList } from '@/hooks/useEntity';
-
-export function EntityListPage() {
-  // 1. HOOKS — always at the top
-  const { t } = useTranslation(['{module}']);
-  const navigate = useNavigate();
-
-  // 2. STATE
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [data, setData] = useState<Entity[]>([]);
-
-  // 3. DATA LOADING (useCallback + useEffect)
-  const loadData = useCallback(async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const result = await entityApi.getAll();
-      setData(result?.items ?? []);
-    } catch (err: any) {
-      setError(err.message || t('{module}:errors.loadFailed', 'Failed to load data'));
-    } finally {
-      setLoading(false);
-    }
-  }, [t]);
-
-  useEffect(() => {
-    loadData();
-  }, [loadData]);
-
-  // 4. LOADING STATE
-  if (loading) {
-    return (
-      <div className="flex items-center justify-center min-h-[400px]">
-        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
-      </div>
-    );
-  }
-
-  // 5. ERROR STATE
-  if (error) {
-    return (
-      <div className="flex items-center justify-center min-h-[400px]">
-        <div className="text-center">
-          <p className="text-[var(--text-secondary)]">{error}</p>
-          <button
-            onClick={loadData}
-            className="mt-4 px-4 py-2 bg-[var(--color-accent-500)] text-white rounded"
-          >
-            {t('common:actions.retry', 'Retry')}
-          </button>
-        </div>
-      </div>
-    );
-  }
-
-  // 6. CONTENT — create button navigates to /create route
-  return (
-    <div className="space-y-6">
-      {/* Header with DocToggleButton */}
-      <div className="flex items-center justify-between">
-        <h1 className="text-2xl font-bold text-[var(--text-primary)]">
-          {t('{module}:title', 'Module Title')}
-        </h1>
-        <div className="flex items-center gap-2">
-          <DocToggleButton />
-          <button
-            onClick={() => navigate('create')}
-            className="px-4 py-2 bg-[var(--color-accent-500)] text-white rounded"
-          >
-            {t('{module}:actions.create', 'Create')}
-          </button>
-        </div>
-      </div>
-
-      {/* Content: DataTable with row click → detail */}
-      {data.length === 0 ? (
-        <div className="text-center py-12 text-[var(--text-secondary)]">
-          {t('{module}:empty', 'No items found.')}
-        </div>
-      ) : (
-        <DataTable
-          data={data}
-          columns={[
-            { key: 'name', label: t('{module}:columns.name', 'Name'), sortable: true },
-            { key: 'code', label: t('{module}:columns.code', 'Code'), sortable: true },
-            { key: 'status', label: t('{module}:columns.status', 'Status'),
-              render: (item) => (
-                <span className={`px-2 py-0.5 rounded text-xs ${
-                  item.isActive
-                    ? 'bg-[var(--success-bg)] text-[var(--success-text)]'
-                    : 'bg-[var(--error-bg)] text-[var(--error-text)]'
-                }`}>
-                  {item.isActive ? t('common:status.active', 'Active') : t('common:status.inactive', 'Inactive')}
-                </span>
-              )
-            },
-          ]}
-          searchable
-          pagination={{ pageSize: 10 }}
-          onRowClick={(item) => navigate(`${item.id}`)}
-        />
-      )}
-    </div>
-  );
-}
-```
-
-> **DEFENSIVE RULE — API Response Guards:**
-> Always use `result?.items ?? []` when extracting arrays from API responses.
-> SmartStack's axios interceptor may resolve with `undefined` on auth failures (401/403)
-> instead of rejecting the promise. Without the guard, `data.length` will crash.
-
-### Detail Page Pattern
-
-```tsx
-export function EntityDetailPage() {
-  const { entityId } = useParams<{ entityId: string }>();
-  const { t } = useTranslation(['{module}']);
-  const navigate = useNavigate();
-
-  const [entity, setEntity] = useState<Entity | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [activeTab, setActiveTab] = useState('info');
-
-  // Lazy tab loading — load data only when tab is first visited
-  const visitedTabsRef = useRef<Set<string>>(new Set(['info']));
-
-  useEffect(() => {
-    if (!visitedTabsRef.current.has(activeTab)) {
-      visitedTabsRef.current.add(activeTab);
-      // Load tab-specific data here (e.g., fetch leaves for this employee)
-    }
-  }, [activeTab]);
-
-  // Edit button navigates to /:id/edit route (not modal)
-  const handleEdit = () => navigate(`edit`);
-
-  // ... loading/error/content pattern
-}
-```
-
-### Tab Behavior Rules
-
-Tabs on detail pages switch content locally, not by navigating to other pages.
-Each tab renders its content inline within the same page component.
-Sub-resource data (e.g., an employee's leaves) loads via API call filtered by the parent entity ID.
-
-**Tab state management:**
-- Tabs use `useState<TabKey>('info')` for the active tab — local React state only
-- Tab click handler: `onClick={() => setActiveTab(tabKey)}` — do not use `navigate()`
-- Tab content: conditional rendering `{activeTab === 'tabKey' && <TabContent />}`
-- Lazy loading: `visitedTabsRef` tracks which tabs have been visited to avoid redundant API calls
+1. **HOOKS** — `useTranslation`, `useNavigate` at the top
+2. **STATE** — `loading`, `error`, `data` via `useState`
+3. **DATA LOADING** — `useCallback` + `useEffect` pattern
+4. **LOADING STATE** — `Loader2` spinner centered (`min-h-[400px]`)
+5. **ERROR STATE** — error message + retry button
+6. **CONTENT** — header (title + `DocToggleButton` + create button) + `DataTable` or empty state
 
-**Tab content for sub-resources:**
-```tsx
-// CORRECT — sub-resource data loaded INLINE within the tab
-{activeTab === 'leaves' && (
-  <div>
-    <LeaveRequestsTable employeeId={entity.id} />
-    {/* Optional "View all" link INSIDE the tab content area */}
-    <Link to={`../leaves?employee=${entity.id}`}>
-      {t('employees:tabs.viewAllLeaves', 'View all leave requests')}
-    </Link>
-  </div>
-)}
-```
-
-**Incorrect tab patterns:**
-```tsx
-// Incorrect — tab click handler navigates to another page
-const handleTabClick = (tab: TabKey) => {
-  setActiveTab(tab);
-  if (tab === 'leaves') navigate(`../leaves?employee=${id}`);  // ← breaks tab UX
-};
+**API response guard (MANDATORY):** Always use `result?.items ?? []` when extracting arrays.
+SmartStack's axios interceptor may resolve with `undefined` on auth failures (401/403) instead of rejecting. Without the guard, `data.length` crashes.
 
-// Incorrect — tab content is empty because navigation already left the page
-{activeTab === 'info' && <div>...</div>}
-// Leaves tab: nothing renders here, user is already on another page
-```
-
-**Why this matters:**
-- Navigating away loses the detail page context (entity data, scroll position, other tab state)
-- Users expect tabs to switch content in-place, not redirect to a different page
-- The browser back button should go to the list page, not toggle between tabs
+### Detail Page Rules
 
-**POST-CHECK C37 enforces this rule.**
+- Edit button: `navigate('edit')` → separate edit page, not modal
+- Tabs: local `useState<TabKey>('info')` — do NOT `navigate()` on tab click
+- Tab content: inline conditional `{activeTab === 'tab' && <Content />}`
+- Lazy tab loading: `visitedTabsRef` tracks visited tabs to avoid redundant API calls
+- Sub-resource tabs load data filtered by parent entity ID inline
+- POST-CHECK C37 enforces: tabs switch content in-place, not redirect to other pages
 
 ---
 
-## 3b. Form Pages Pattern (Create / Edit)
+## 3b. Form Pages (Create / Edit)
 
-All forms must be full pages with their own URL route. Do not use modals, dialogs, drawers, or popups for create/edit forms.
+All forms MUST be full pages with their own URL route. Do NOT use modals, dialogs, drawers, or popups.
 
 ### Route Convention
 
-Route paths must use **kebab-case** matching the navigation seed data (which uses `ToKebabCase()`).
-- Single word: `employees` (no change needed)
-- Multi-word: `human-resources`, `time-management` (kebab-case with hyphens)
-- Incorrect: `humanresources`, `timemanagement` (concatenated words without hyphens)
-
-| Action | Route pattern | Page component | File location |
-|--------|--------------|----------------|---------------|
-| Create | `/{module}/create` | `EntityCreatePage` | `src/pages/{App}/{Module}/EntityCreatePage.tsx` |
-| Edit | `/{module}/:id/edit` | `EntityEditPage` | `src/pages/{App}/{Module}/EntityEditPage.tsx` |
-
-### Create Page Template
-
-```tsx
-import { useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import { useNavigate } from 'react-router-dom';
-import { ArrowLeft } from 'lucide-react';
-// For FK Guid fields: import { EntityLookup } from '@/components/ui/EntityLookup';
-
-export function EntityCreatePage() {
-  const { t } = useTranslation(['{module}']);
-  const navigate = useNavigate();
-  const [submitting, setSubmitting] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [formData, setFormData] = useState<CreateEntityDto>({
-    name: '',
-    // departmentId: '', ← FK Guid field (use EntityLookup below)
-  });
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    try {
-      setSubmitting(true);
-      setError(null);
-      await entityApi.create(formData);
-      navigate(-1); // Back to list
-    } catch (err: any) {
-      setError(err.message || t('{module}:errors.createFailed', 'Creation failed'));
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  return (
-    <div className="space-y-6">
-      {/* Back button */}
-      <button
-        onClick={() => navigate(-1)}
-        className="flex items-center gap-1 text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
-      >
-        <ArrowLeft className="w-4 h-4" />
-        {t('common:actions.back', 'Back')}
-      </button>
-
-      {/* Page title */}
-      <h1 className="text-2xl font-bold text-[var(--text-primary)]">
-        {t('{module}:actions.create', 'Create {Entity}')}
-      </h1>
-
-      {/* Error state */}
-      {error && (
-        <div className="p-4 bg-[var(--error-bg)] border border-[var(--error-border)] rounded-[var(--radius-card)]">
-          <span className="text-[var(--error-text)]">{error}</span>
-        </div>
-      )}
-
-      {/* Form page — not modal */}
-      <form onSubmit={handleSubmit} className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] p-6 space-y-4">
-        {/* Text field */}
-        <div>
-          <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
-            {t('{module}:form.name', 'Name')}
-          </label>
-          <input
-            type="text"
-            value={formData.name}
-            onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
-            className="w-full px-3 py-2 border border-[var(--border-color)] bg-[var(--bg-card)] text-[var(--text-primary)] rounded-[var(--radius-input)] focus:outline-none focus:ring-2 focus:ring-[var(--color-accent-500)]"
-            required
-          />
-        </div>
-
-        {/* FK Guid field — use EntityLookup, not <select> or <input> */}
-        {/* <div>
-          <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
-            {t('{module}:form.department', 'Department')}
-          </label>
-          <EntityLookup
-            apiEndpoint="/api/{app}/{module}/departments"
-            value={formData.departmentId}
-            onChange={(id) => setFormData(prev => ({ ...prev, departmentId: id }))}
-            mapOption={(dept) => ({ label: dept.name, value: dept.id })}
-            placeholder={t('{module}:form.selectDepartment', 'Select a department...')}
-          />
-        </div> */}
-
-        {/* Actions */}
-        <div className="flex justify-end gap-3 pt-4 border-t border-[var(--border-color)]">
-          <button
-            type="button"
-            onClick={() => navigate(-1)}
-            className="px-4 py-2 text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] rounded-[var(--radius-button)]"
-          >
-            {t('common:actions.cancel', 'Cancel')}
-          </button>
-          <button
-            type="submit"
-            disabled={submitting}
-            className="px-4 py-2 bg-[var(--color-accent-500)] text-white rounded-[var(--radius-button)] hover:bg-[var(--color-accent-600)] disabled:opacity-50"
-          >
-            {submitting ? t('common:actions.saving', 'Saving...') : t('common:actions.save', 'Save')}
-          </button>
-        </div>
-      </form>
-    </div>
-  );
-}
-```
+Route paths MUST use **kebab-case** matching navigation seed data (which uses `ToKebabCase()`).
 
-### Edit Page Template
+| Action | Route | Page component |
+|--------|-------|---------------|
+| Create | `/{module}/create` | `EntityCreatePage` |
+| Edit | `/{module}/:id/edit` | `EntityEditPage` |
 
-```tsx
-import { useState, useEffect, useCallback } from 'react';
-import { useTranslation } from 'react-i18next';
-import { useNavigate, useParams } from 'react-router-dom';
-import { Loader2, ArrowLeft } from 'lucide-react';
-// For FK Guid fields: import { EntityLookup } from '@/components/ui/EntityLookup';
-
-export function EntityEditPage() {
-  const { entityId } = useParams<{ entityId: string }>();
-  const { t } = useTranslation(['{module}']);
-  const navigate = useNavigate();
-  const [formData, setFormData] = useState<UpdateEntityDto | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [submitting, setSubmitting] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const loadEntity = useCallback(async () => {
-    try {
-      setLoading(true);
-      const result = await entityApi.getById(entityId!);
-      setFormData(result);
-    } catch {
-      navigate(-1);
-    } finally {
-      setLoading(false);
-    }
-  }, [entityId, navigate]);
-
-  useEffect(() => { loadEntity(); }, [loadEntity]);
-
-  if (loading || !formData) {
-    return (
-      <div className="flex items-center justify-center min-h-[400px]">
-        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
-      </div>
-    );
-  }
+> **v3.7+ (DynamicRouter):** Routes are resolved automatically from navigation seed data.
+> `ComponentKey` in seed data matches `PageRegistry.register('key', ...)` entries.
+> No manual route registration needed.
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    try {
-      setSubmitting(true);
-      setError(null);
-      await entityApi.update(entityId!, formData);
-      navigate(-1); // Back to detail or list
-    } catch (err: any) {
-      setError(err.message || t('{module}:errors.updateFailed', 'Update failed'));
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  return (
-    <div className="space-y-6">
-      {/* Back button */}
-      <button
-        onClick={() => navigate(-1)}
-        className="flex items-center gap-1 text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
-      >
-        <ArrowLeft className="w-4 h-4" />
-        {t('common:actions.back', 'Back')}
-      </button>
-
-      {/* Page title */}
-      <h1 className="text-2xl font-bold text-[var(--text-primary)]">
-        {t('{module}:actions.edit', 'Edit {Entity}')}
-      </h1>
-
-      {/* Error state */}
-      {error && (
-        <div className="p-4 bg-[var(--error-bg)] border border-[var(--error-border)] rounded-[var(--radius-card)]">
-          <span className="text-[var(--error-text)]">{error}</span>
-        </div>
-      )}
-
-      {/* Form page — not modal */}
-      <form onSubmit={handleSubmit} className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] p-6 space-y-4">
-        {/* Text field (pre-filled) */}
-        <div>
-          <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
-            {t('{module}:form.name', 'Name')}
-          </label>
-          <input
-            type="text"
-            value={formData.name}
-            onChange={(e) => setFormData(prev => prev ? { ...prev, name: e.target.value } : prev)}
-            className="w-full px-3 py-2 border border-[var(--border-color)] bg-[var(--bg-card)] text-[var(--text-primary)] rounded-[var(--radius-input)] focus:outline-none focus:ring-2 focus:ring-[var(--color-accent-500)]"
-            required
-          />
-        </div>
-
-        {/* FK Guid field — use EntityLookup, not <select> or <input> */}
-        {/* <div>
-          <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
-            {t('{module}:form.department', 'Department')}
-          </label>
-          <EntityLookup
-            apiEndpoint="/api/{app}/{module}/departments"
-            value={formData.departmentId}
-            onChange={(id) => setFormData(prev => prev ? { ...prev, departmentId: id } : prev)}
-            mapOption={(dept) => ({ label: dept.name, value: dept.id })}
-            placeholder={t('{module}:form.selectDepartment', 'Select a department...')}
-          />
-        </div> */}
-
-        {/* Actions */}
-        <div className="flex justify-end gap-3 pt-4 border-t border-[var(--border-color)]">
-          <button
-            type="button"
-            onClick={() => navigate(-1)}
-            className="px-4 py-2 text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] rounded-[var(--radius-button)]"
-          >
-            {t('common:actions.cancel', 'Cancel')}
-          </button>
-          <button
-            type="submit"
-            disabled={submitting}
-            className="px-4 py-2 bg-[var(--color-accent-500)] text-white rounded-[var(--radius-button)] hover:bg-[var(--color-accent-600)] disabled:opacity-50"
-          >
-            {submitting ? t('common:actions.saving', 'Saving...') : t('common:actions.save', 'Save')}
-          </button>
-        </div>
-      </form>
-    </div>
-  );
-}
-```
+### Route Registration
 
-### Lazy Loading for Form Pages
+> **Note (v3.7+):** With DynamicRouter + PageRegistry, route registration is automatic.
+> Run `scaffold_routes outputFormat="componentRegistry"` to generate `componentRegistry.generated.ts`,
+> then ensure `main.tsx` imports it. The patterns below apply only to legacy projects.
 
 ```tsx
-// In route files — form pages are also lazy-loaded
-// Path: @/pages/{App}/{Module}/{Section}/{Page}
-const EntityCreatePage = lazy(() =>
-  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityCreatePage')
-    .then(m => ({ default: m.EntityCreatePage }))
-);
-const EntityEditPage = lazy(() =>
-  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityEditPage')
-    .then(m => ({ default: m.EntityEditPage }))
-);
-
-// Route registration — Pattern B (JSX nested children):
-{
-  path: 'employee-management/employees',
-  children: [
-    { index: true, element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense> },
-    { path: 'create', element: <Suspense fallback={<PageLoader />}><EntityCreatePage /></Suspense> },
-    { path: ':id', element: <Suspense fallback={<PageLoader />}><EntityDetailPage /></Suspense> },
-    { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><EntityEditPage /></Suspense> },
-  ]
-}
-
-// Route registration — Pattern A (applicationRoutes flat paths):
-// CRITICAL: paths are RELATIVE to /{app}/ and MUST include the module segment
+// Pattern B (JSX nested children):
+{ path: '{module-kebab}', children: [
+    { index: true, element: <Suspense fallback={<PageLoader />}><ListPage /></Suspense> },
+    { path: 'create', element: <Suspense fallback={<PageLoader />}><CreatePage /></Suspense> },
+    { path: ':id', element: <Suspense fallback={<PageLoader />}><DetailPage /></Suspense> },
+    { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><EditPage /></Suspense> },
+]}
+
+// Pattern A (applicationRoutes — MUST include module segment in path):
 const applicationRoutes: ApplicationRouteExtensions = {
   'human-resources': [
-    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅ includes module
-    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
-    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
-    { path: 'employee-management/employees/:id/edit', element: <EditEmployeePage /> }, // ✅
-    // ❌ WRONG: { path: 'employees', ... } — missing module segment → 404 on nav click
+    { path: 'employee-management/employees', element: <ListPage /> },           // includes module
+    { path: 'employee-management/employees/create', element: <CreatePage /> },   // includes module
+    { path: 'employee-management/employees/:id', element: <DetailPage /> },      // includes module
+    { path: 'employee-management/employees/:id/edit', element: <EditPage /> },   // includes module
+    // WRONG: { path: 'employees', ... } — missing module segment → 404
   ],
 };
+```
 
-// Section-level routes — children of the module route (when module has sections)
-//
-// > **IMPORTANT:** The `list` and `detail` sections do NOT generate additional route entries.
-// > They are already covered by the module's `index: true` (list) and `path: ':id'` (detail) routes above.
-// > Only sections like `dashboard`, `approve`, `import`, etc. generate the section-kebab child routes below.
-// Note: Do not use `path: 'list'` or `path: 'detail'` — these create unreachable duplicate routes.
-//
-{
-  path: '{module-kebab}',
-  children: [
-    { index: true, element: <Suspense fallback={<PageLoader />}><{Module}Page /></Suspense> },
-    { path: 'create', element: <Suspense fallback={<PageLoader />}><Create{Module}Page /></Suspense> },
-    { path: ':id', element: <Suspense fallback={<PageLoader />}><{Module}DetailPage /></Suspense> },
-    { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Module}Page /></Suspense> },
-    // Section routes as children of module:
-    // IMPORTANT: "list" and "detail" are NOT separate path segments.
-    // - "list" section = already handled by the module's index route above (index: true)
-    // - "detail" section = already handled by the module's :id route above (path: ':id')
-    // - Only OTHER sections (dashboard, approve, import, etc.) add path segments:
-    { path: '{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
-    { path: '{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
-    { path: '{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
-    { path: '{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
-  ]
-}
+**Section-level routes:** `list` and `detail` do NOT add path segments (handled by `index: true` and `:id`). Only other sections (dashboard, approve, import) add `{section-kebab}` child routes.
 
-// PermissionGuard for section-level routes
+**PermissionGuard for sections:**
+```tsx
 element: (
   <Suspense fallback={<PageLoader />}>
     <PermissionGuard permissions={ROUTES['app.module.section'].permissions}>
@@ -774,30 +226,13 @@ element: (
 )
 ```
 
-### Rules
-
-- Do not use `<Modal>`, `<Dialog>`, `<Drawer>`, or `<Popup>` for create/edit forms
-- Do not use `useState(isOpen)` to toggle form visibility — forms are pages, not overlays
-- Create a dedicated `EntityCreatePage.tsx` and `EntityEditPage.tsx` page component
-- Register create/edit routes alongside list/detail routes
-- Use `navigate('create')` or `navigate(\`${id}/edit\`)` from list/detail pages
-- Include a back button that uses `navigate(-1)` to return to previous page
-
-**Incorrect patterns:**
-```tsx
-// WRONG: modal for create form
-const [showCreateModal, setShowCreateModal] = useState(false);
-<Modal open={showCreateModal}><CreateForm /></Modal>
-
-// WRONG: dialog for edit form
-<Dialog open={editDialogOpen}><EditForm entity={selected} /></Dialog>
-
-// WRONG: drawer for form
-<Drawer open={isDrawerOpen}><form>...</form></Drawer>
-
-// WRONG: inline form toggle
-{isEditing ? <EditForm /> : <DetailView />}
-```
+**Rules:**
+- Do NOT use `<Modal>`, `<Dialog>`, `<Drawer>` for create/edit forms
+- Do NOT use `useState(isOpen)` to toggle form visibility — forms are pages
+- Navigate: `navigate('create')` or `navigate(\`${id}/edit\`)`
+- Back button: `navigate(-1)`
+- Create dedicated `EntityCreatePage.tsx` and `EntityEditPage.tsx` page components
+- Form submitting state: `setSubmitting(true)` → API call → `navigate(-1)` on success
 
 ---
 
@@ -805,10 +240,8 @@ const [showCreateModal, setShowCreateModal] = useState(false);
 
 Do not use hardcoded Tailwind colors. Always use CSS variables for theme support.
 
-### Variable Reference
-
-| Usage | CSS Variable | Example |
-|-------|-------------|---------|
+| Usage | CSS Variable | Tailwind usage |
+|-------|-------------|---------------|
 | Background | `var(--bg-primary)` | `bg-[var(--bg-primary)]` |
 | Card background | `var(--bg-card)` | `bg-[var(--bg-card)]` |
 | Text primary | `var(--text-primary)` | `text-[var(--text-primary)]` |
@@ -816,9 +249,13 @@ Do not use hardcoded Tailwind colors. Always use CSS variables for theme support
 | Borders | `var(--border-color)` | `border-[var(--border-color)]` |
 | Accent | `var(--color-accent-500)` | `text-[var(--color-accent-500)]` |
 | Card radius | `var(--radius-card)` | `style={{ borderRadius: 'var(--radius-card)' }}` |
+| Input radius | `var(--radius-input)` | `rounded-[var(--radius-input)]` |
+| Button radius | `var(--radius-button)` | `rounded-[var(--radius-button)]` |
+| Hover background | `var(--bg-hover)` | `hover:bg-[var(--bg-hover)]` |
+| Success states | `var(--success-bg)`, `var(--success-text)` | Status badges |
+| Error states | `var(--error-bg)`, `var(--error-text)`, `var(--error-border)` | Error displays |
 
-### Card Pattern
-
+**Card pattern:**
 ```tsx
 <div
   className="bg-[var(--bg-card)] border border-[var(--border-color)] p-6"
@@ -829,64 +266,50 @@ Do not use hardcoded Tailwind colors. Always use CSS variables for theme support
 </div>
 ```
 
-**Incorrect:**
-```tsx
-// Do not use hardcoded Tailwind colors
-className="bg-white border-gray-200 text-gray-900"
-
-// Do not use hardcoded hex/rgb
-style={{ backgroundColor: '#ffffff', color: '#1a1a1a' }}
-```
+Do NOT use: `bg-white`, `border-gray-200`, `text-gray-900`, hardcoded hex/rgb.
 
 ---
 
 ## 5. Component Rules
 
-| Need | Component | Source | Notes |
-|------|-----------|--------|-------|
-| Data table | `DataTable` | `@/components/ui/DataTable` | Shared component (sorting, pagination, search) |
-| Entity cards | `EntityCard` | `@/components/ui/EntityCard` | Shared component (avatar, badges, actions) |
-| FK field lookup | `EntityLookup` | Generate in `@/components/ui/EntityLookup` | See section 6 for full pattern |
-| KPI statistics | `StatCard` | Generate locally per dashboard | See dashboard-chart.md pattern |
-| Chart wrapper | `ChartCard` | Generate locally per dashboard | See dashboard-chart.md pattern |
-| Loading spinner | `Loader2` | `lucide-react` | Shared |
-| Page loader | `PageLoader` | `@/components/ui/PageLoader` | Shared (Suspense fallback) |
-| Docs toggle | `DocToggleButton` | `@/components/docs/DocToggleButton` | Shared |
-
-### Rules
-
-- Do not use raw `<table>` — use `DataTable` from `@/components/ui/DataTable`
+| Need | Component | Source |
+|------|-----------|--------|
+| Data table | `DataTable` | `@/components/ui/DataTable` |
+| Entity cards | `EntityCard` | `@/components/ui/EntityCard` |
+| FK field lookup | `EntityLookup` | Generate via `/ui-components` (see §6) |
+| KPI statistics | `StatCard` | Generate locally per dashboard |
+| Loading spinner | `Loader2` | `lucide-react` |
+| Page loader | `PageLoader` | `@/components/ui/PageLoader` |
+| Docs toggle | `DocToggleButton` | `@/components/docs/DocToggleButton` |
+
+- Do not use raw `<table>` — use `DataTable`
 - Do not create custom spinners — use `Loader2` from lucide-react
 - Do not import axios directly — use `@/services/api/apiClient`
 - Use `PageLoader` as Suspense fallback
-- Use existing shared components before creating new ones
 - Use `EntityLookup` for FK Guid fields (not `<select>` or `<input>` for GUIDs)
 
 ---
 
 ## 6. Foreign Key Fields & Entity Lookup
 
-Do not render a foreign key (Guid) as a plain text input. FK fields must use a searchable lookup component.
-A form asking the user to type a GUID manually is a UX failure. All FK fields must provide entity search and selection.
+Do not render FK (Guid) fields as plain text input or `<select>`. FK fields MUST use `EntityLookup`.
 
 ### Field Type Classification
 
-When generating form fields, determine the field type from the entity property:
-
-| Property type | Form field type | Component |
-|---------------|----------------|-----------|
-| `string` | Text input | `<input type="text" />` |
-| `string?` | Text input (optional) | `<input type="text" />` |
+| Property type | Form field | Component |
+|---------------|-----------|-----------|
+| `string` / `string?` | Text input | `<input type="text" />` |
 | `Guid` (FK — e.g., `EmployeeId`, `DepartmentId`) | **Entity Lookup** | `<EntityLookup />` |
 | `bool` | Toggle/Checkbox | `<input type="checkbox" />` |
 | `int` / `decimal` | Number input | `<input type="number" />` |
-| `DateTime` / `DateOnly` | Date input | `<input type="date" className="..." />` — wrap with label + error state using CSS variables |
+| `DateTime` / `DateOnly` | Date input | `<input type="date" />` with CSS variables |
 | `enum` | Select dropdown | `<select>` |
 
-#### Date Field Pattern (styled with CSS variables)
+**How to detect FK fields:** Any property named `{Entity}Id` of type `Guid` with a corresponding navigation property.
+
+#### Date Field Pattern
 
 ```tsx
-{/* Date field — styled with CSS variables */}
 <div>
   <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
     {t('{module}:form.startDate', 'Start Date')}
@@ -901,362 +324,33 @@ When generating form fields, determine the field type from the entity property:
 </div>
 ```
 
-**How to detect FK fields:** Any property named `{Entity}Id` of type `Guid` that has a corresponding navigation property is a foreign key. Examples: `EmployeeId`, `DepartmentId`, `CategoryId`, `ParentId`.
-
-### EntityLookup Component Pattern
-
-```tsx
-import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
-import { useTranslation } from 'react-i18next';
-import { Search, X, ChevronDown } from 'lucide-react';
-import { apiClient } from '@/services/api/apiClient';
-
-interface EntityLookupOption {
-  id: string;
-  label: string;        // Display name (e.g., employee full name)
-  sublabel?: string;     // Secondary info (e.g., department, code)
-}
+### EntityLookup Props
 
+```typescript
 interface EntityLookupProps {
-  /** API endpoint to search entities (e.g., '/api/human-resources/employees') */
-  apiEndpoint: string;
-  /** Currently selected entity ID */
-  value: string | null;
-  /** Callback when entity is selected */
+  apiEndpoint: string;        // e.g., '/api/human-resources/employees'
+  value: string | null;       // Currently selected entity ID
   onChange: (id: string | null) => void;
-  /** Field label */
-  label: string;
-  /** Placeholder text */
+  label: string;              // Field label
   placeholder?: string;
-  /** Map API response item to display option */
-  mapOption: (item: any) => EntityLookupOption;
-  /** Whether the field is required */
+  mapOption: (item: any) => { id: string; label: string; sublabel?: string };
   required?: boolean;
-  /** Whether the field is disabled */
   disabled?: boolean;
-  /** Error message to display */
   error?: string;
 }
-
-export function EntityLookup({
-  apiEndpoint,
-  value,
-  onChange,
-  label,
-  placeholder,
-  mapOption,
-  required = false,
-  disabled = false,
-  error,
-}: EntityLookupProps) {
-  const { t } = useTranslation(['common']);
-  const [search, setSearch] = useState('');
-  const [options, setOptions] = useState<EntityLookupOption[]>([]);
-  const [selectedOption, setSelectedOption] = useState<EntityLookupOption | null>(null);
-  const [isOpen, setIsOpen] = useState(false);
-  const [loading, setLoading] = useState(false);
-  const containerRef = useRef<HTMLDivElement>(null);
-  const debounceRef = useRef<ReturnType<typeof setTimeout>>();
-
-  // Load selected entity display on mount (when value is set but no label)
-  useEffect(() => {
-    if (value && !selectedOption) {
-      apiClient.get(`${apiEndpoint}/${value}`)
-        .then(res => setSelectedOption(mapOption(res.data)))
-        .catch(() => { /* Entity not found — clear */ });
-    }
-  }, [value, apiEndpoint, mapOption, selectedOption]);
-
-  // Debounced search — 300ms delay, minimum 2 characters
-  const handleSearch = useCallback((term: string) => {
-    setSearch(term);
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-
-    if (term.length < 2) {
-      setOptions([]);
-      return;
-    }
-
-    debounceRef.current = setTimeout(async () => {
-      setLoading(true);
-      try {
-        const res = await apiClient.get(apiEndpoint, {
-          params: { search: term, pageSize: 20 },
-        });
-        setOptions((res.data.items || res.data).map(mapOption));
-      } catch {
-        setOptions([]);
-      } finally {
-        setLoading(false);
-      }
-    }, 300);
-  }, [apiEndpoint, mapOption]);
-
-  // Load initial options when dropdown opens (show first 20)
-  const handleOpen = useCallback(async () => {
-    if (disabled) return;
-    setIsOpen(true);
-    if (options.length === 0 && search.length < 2) {
-      setLoading(true);
-      try {
-        const res = await apiClient.get(apiEndpoint, {
-          params: { pageSize: 20 },
-        });
-        setOptions((res.data.items || res.data).map(mapOption));
-      } catch {
-        setOptions([]);
-      } finally {
-        setLoading(false);
-      }
-    }
-  }, [disabled, apiEndpoint, mapOption, options.length, search.length]);
-
-  // Select entity
-  const handleSelect = useCallback((option: EntityLookupOption) => {
-    setSelectedOption(option);
-    onChange(option.id);
-    setIsOpen(false);
-    setSearch('');
-  }, [onChange]);
-
-  // Clear selection
-  const handleClear = useCallback(() => {
-    setSelectedOption(null);
-    onChange(null);
-    setSearch('');
-  }, [onChange]);
-
-  // Close on outside click
-  useEffect(() => {
-    const handleClickOutside = (e: MouseEvent) => {
-      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
-        setIsOpen(false);
-      }
-    };
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
-
-  return (
-    <div ref={containerRef} className="relative">
-      <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
-        {label} {required && <span className="text-[var(--error-text)]">*</span>}
-      </label>
-
-      {/* Selected value display OR search input */}
-      {selectedOption && !isOpen ? (
-        <div className="flex items-center gap-2 px-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)]">
-          <div className="flex-1">
-            <span className="text-[var(--text-primary)]">{selectedOption.label}</span>
-            {selectedOption.sublabel && (
-              <span className="ml-2 text-sm text-[var(--text-secondary)]">{selectedOption.sublabel}</span>
-            )}
-          </div>
-          {!disabled && (
-            <button type="button" onClick={handleClear} className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]">
-              <X className="w-4 h-4" />
-            </button>
-          )}
-          <button type="button" onClick={handleOpen} className="text-[var(--text-secondary)]">
-            <ChevronDown className="w-4 h-4" />
-          </button>
-        </div>
-      ) : (
-        <div className="relative">
-          <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-[var(--text-secondary)]" />
-          <input
-            type="text"
-            value={search}
-            onChange={(e) => handleSearch(e.target.value)}
-            onFocus={handleOpen}
-            placeholder={placeholder || t('common:actions.search', 'Search...')}
-            disabled={disabled}
-            className="w-full pl-9 pr-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)] text-[var(--text-primary)] placeholder:text-[var(--text-secondary)] focus:ring-2 focus:ring-[var(--color-accent-500)] focus:border-transparent"
-          />
-        </div>
-      )}
-
-      {/* Dropdown */}
-      {isOpen && (
-        <div className="absolute z-50 w-full mt-1 bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] shadow-lg max-h-60 overflow-auto">
-          {loading ? (
-            <div className="p-3 text-center text-[var(--text-secondary)]">
-              {t('common:actions.loading', 'Loading...')}
-            </div>
-          ) : options.length === 0 ? (
-            <div className="p-3 text-center text-[var(--text-secondary)]">
-              {search.length < 2
-                ? t('common:actions.typeToSearch', 'Type at least 2 characters to search...')
-                : t('common:empty.noResults', 'No results found')}
-            </div>
-          ) : (
-            options.map((option) => (
-              <button
-                key={option.id}
-                type="button"
-                onClick={() => handleSelect(option)}
-                className="w-full px-3 py-2 text-left hover:bg-[var(--bg-hover)] transition-colors"
-              >
-                <div className="text-[var(--text-primary)]">{option.label}</div>
-                {option.sublabel && (
-                  <div className="text-sm text-[var(--text-secondary)]">{option.sublabel}</div>
-                )}
-              </button>
-            ))
-          )}
-        </div>
-      )}
-
-      {/* Error message */}
-      {error && (
-        <p className="mt-1 text-sm text-[var(--error-text)]">{error}</p>
-      )}
-    </div>
-  );
-}
 ```
 
-### Usage in Form Pages
+### Usage in Forms
 
 ```tsx
-// In EntityCreatePage.tsx or EntityEditPage.tsx
 import { EntityLookup } from '@/components/ui/EntityLookup';
 
-// Inside the form:
-<EntityLookup
-  apiEndpoint="/api/human-resources/employees"
-  value={formData.employeeId}
-  onChange={(id) => handleChange('employeeId', id)}
-  label={t('module:form.employee', 'Employee')}
-  placeholder={t('module:form.employeePlaceholder', 'Search for an employee...')}
-  mapOption={(emp) => ({
-    id: emp.id,
-    label: `${emp.firstName} ${emp.lastName}`,
-    sublabel: emp.department || emp.code,
-  })}
-  required
-  error={errors.employeeId}
-/>
-
-// For DepartmentId FK:
 <EntityLookup
   apiEndpoint="/api/human-resources/departments"
   value={formData.departmentId}
   onChange={(id) => handleChange('departmentId', id)}
   label={t('module:form.department', 'Department')}
   placeholder={t('module:form.departmentPlaceholder', 'Search for a department...')}
-  mapOption={(dept) => ({
-    id: dept.id,
-    label: dept.name,
-    sublabel: dept.code,
-  })}
-  required
-/>
-```
-
-### API Search Endpoint Convention (Backend)
-
-For EntityLookup to work, each entity's API MUST support search via query parameter:
-
-```
-GET /api/{resource}?search={term}&pageSize=20
-```
-
-Response format:
-```json
-{
-  "items": [
-    { "id": "guid", "code": "EMP001", "name": "John Doe", ... }
-  ],
-  "totalCount": 42
-}
-```
-
-The backend service's `GetAllAsync` method should accept search parameters:
-
-```csharp
-public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
-    string? search = null,
-    int page = 1,
-    int pageSize = 20,
-    CancellationToken ct = default)
-{
-    var query = _db.Entities
-        .Where(x => x.TenantId == _currentUser.TenantId);
-
-    if (!string.IsNullOrWhiteSpace(search))
-    {
-        query = query.Where(x =>
-            x.Name.Contains(search) ||
-            x.Code.Contains(search));
-    }
-
-    var totalCount = await query.CountAsync(ct);
-    var items = await query
-        .OrderBy(x => x.Name)
-        .Skip((page - 1) * pageSize)
-        .Take(pageSize)
-        .Select(x => new EntityResponseDto { ... })
-        .ToListAsync(ct);
-
-    return new PaginatedResult<EntityResponseDto>(items, totalCount, page, pageSize);
-}
-```
-
-### Rules
-
-- Do not render a `Guid` FK field as `<input type="text">` — use `EntityLookup`
-- Do not render a `Guid` FK field as `<select>` — even with API-loaded `<option>` elements, `<select>` is not acceptable
-- Do not ask the user to manually type or paste a GUID/ID
-- Provide a search-based selection via `<EntityLookup />` for FK fields
-- Show the entity's display name (Name, FullName, Code+Name) not the GUID
-- Include `mapOption` to define how the related entity is displayed
-- Load the selected entity's display name on mount (for edit forms)
-- Support clearing the selection (unless required + already set)
-
-**Why `<select>` is NOT acceptable for FK fields:**
-- `<select>` loads ALL options at once — fails with 100+ entities (performance + UX)
-- `<select>` has no search/filter — user must scroll through all options
-- `<select>` cannot show sublabels (code, department, etc.)
-- `EntityLookup` provides: debounced API search, paginated results, display name resolution, sublabels
-
-**Incorrect patterns:**
-```tsx
-// Do not use plain text input for FK field
-<input
-  type="text"
-  value={formData.employeeId}
-  onChange={(e) => handleChange('employeeId', e.target.value)}
-  placeholder="Enter Employee ID..."
-/>
-
-// Do not use <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 Department...</option>
-  {departments.map((dept) => (
-    <option key={dept.id} value={dept.id}>{dept.name}</option>
-  ))}
-</select>
-
-// Do not display raw GUID to user
-<span>{entity.departmentId}</span>
-
-// Do not use select with hardcoded options for FK
-<select onChange={(e) => handleChange('departmentId', e.target.value)}>
-  <option value="guid-1">Department A</option>
-</select>
-```
-
-**Correct pattern:**
-```tsx
-<EntityLookup
-  apiEndpoint="/api/human-resources/departments"
-  value={formData.departmentId}
-  onChange={(id) => handleChange('departmentId', id)}
-  label={t('module:form.department', 'Department')}
   mapOption={(dept) => ({ id: dept.id, label: dept.name, sublabel: dept.code })}
   required
 />
@@ -1264,7 +358,7 @@ public async Task<PaginatedResult<EntityResponseDto>> GetAllAsync(
 
 ### I18n Keys for EntityLookup
 
-Add these keys to the module's translation files:
+Add to the module's translation files:
 
 ```json
 {
@@ -1277,8 +371,26 @@ Add these keys to the module's translation files:
 }
 ```
 
+### API Search Convention (Backend)
+
+EntityLookup requires: `GET /api/{resource}?search={term}&pageSize=20`
+
+Response format: `{ "items": [...], "totalCount": 42 }`
+
+The backend service's `GetAllAsync` MUST accept `string? search` parameter and filter on display fields (Name, Code, etc.).
+
+### Rules
+
+- Do NOT render Guid FK as `<input type="text">` — user should never type/paste a GUID
+- Do NOT use `<select>` for FK fields — fails with 100+ entities (no search, loads all at once, no sublabels)
+- Show entity display name (Name, FullName, Code+Name), not the GUID
+- Include `mapOption` to define display mapping
+- Support clearing selection (unless required + already set)
+- Load selected entity display on mount (for edit forms with pre-existing value)
+- Debounced search (300ms), minimum 2 characters
+- Load initial options when dropdown opens (first 20)
+
 ---
 
 > **Sections 7-9 (Documentation, Testing, Compliance Gates) have been moved to `references/smartstack-frontend-compliance.md` for context reduction.**
 > Load that file for: DocToggleButton integration (§7), frontend checklist (§7b), cross-tenant UI patterns (§7c), form testing templates (§8), and 5 compliance gates (§9).
-