@atlashub/smartstack-cli 4.4.0 → 4.6.0

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

@@ -251,6 +251,7 @@ 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';
@@ -328,7 +329,34 @@ export function EntityListPage() {
         </div>
       </div>
 
-      {/* Content: SmartTable with row click → detail, edit action → /:id/edit */}
+      {/* 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>
   );
 }
@@ -434,19 +462,28 @@ const handleTabClick = (tab: TabKey) => {
 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 (data: CreateEntityDto) => {
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
     try {
       setSubmitting(true);
-      await entityApi.create(data);
+      setError(null);
+      await entityApi.create(formData);
       navigate(-1); // Back to list
     } catch (err: any) {
-      // Handle validation errors
+      setError(err.message || t('{module}:errors.createFailed', 'Creation failed'));
     } finally {
       setSubmitting(false);
     }
@@ -457,8 +494,9 @@ export function EntityCreatePage() {
       {/* Back button */}
       <button
         onClick={() => navigate(-1)}
-        className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+        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>
 
@@ -467,13 +505,61 @@ export function EntityCreatePage() {
         {t('{module}:actions.create', 'Create {Entity}')}
       </h1>
 
-      {/* SmartForm — NEVER in a modal */}
-      <SmartForm
-        fields={formFields}
-        onSubmit={handleSubmit}
-        onCancel={() => navigate(-1)}
-        submitting={submitting}
-      />
+      {/* 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 — NEVER in a 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 — ALWAYS use EntityLookup, NEVER <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>
   );
 }
@@ -485,21 +571,23 @@ export function EntityCreatePage() {
 import { useState, useEffect, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useNavigate, useParams } from 'react-router-dom';
-import { Loader2 } from 'lucide-react';
+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 [entity, setEntity] = useState<Entity | null>(null);
+  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!);
-      setEntity(result);
+      setFormData(result);
     } catch {
       navigate(-1);
     } finally {
@@ -509,7 +597,7 @@ export function EntityEditPage() {
 
   useEffect(() => { loadEntity(); }, [loadEntity]);
 
-  if (loading) {
+  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)]" />
@@ -517,13 +605,15 @@ export function EntityEditPage() {
     );
   }
 
-  const handleSubmit = async (data: UpdateEntityDto) => {
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
     try {
       setSubmitting(true);
-      await entityApi.update(entityId!, data);
+      setError(null);
+      await entityApi.update(entityId!, formData);
       navigate(-1); // Back to detail or list
     } catch (err: any) {
-      // Handle validation errors
+      setError(err.message || t('{module}:errors.updateFailed', 'Update failed'));
     } finally {
       setSubmitting(false);
     }
@@ -534,8 +624,9 @@ export function EntityEditPage() {
       {/* Back button */}
       <button
         onClick={() => navigate(-1)}
-        className="text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+        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>
 
@@ -544,14 +635,61 @@ export function EntityEditPage() {
         {t('{module}:actions.edit', 'Edit {Entity}')}
       </h1>
 
-      {/* SmartForm pre-filled — NEVER in a modal */}
-      <SmartForm
-        fields={formFields}
-        initialValues={entity}
-        onSubmit={handleSubmit}
-        onCancel={() => navigate(-1)}
-        submitting={submitting}
-      />
+      {/* 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 pre-filled — NEVER in a 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 — ALWAYS use EntityLookup, NEVER <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>
   );
 }
@@ -636,7 +774,7 @@ const [showCreateModal, setShowCreateModal] = useState(false);
 <Dialog open={editDialogOpen}><EditForm entity={selected} /></Dialog>
 
 // WRONG: drawer for form
-<Drawer open={isDrawerOpen}><SmartForm /></Drawer>
+<Drawer open={isDrawerOpen}><form>...</form></Drawer>
 
 // WRONG: inline form toggle
 {isEditing ? <EditForm /> : <DetailView />}
@@ -685,24 +823,25 @@ style={{ backgroundColor: '#ffffff', color: '#1a1a1a' }}
 
 ## 5. Component Rules
 
-| Need | Component | Source |
-|------|-----------|--------|
-| Data table | `SmartTable` | `@/components/SmartTable` |
-| Filters | `SmartFilter` | `@/components/SmartFilter` |
-| Entity cards | `EntityCard` | `@/components/EntityCard` |
-| Forms | `SmartForm` | `@/components/SmartForm` |
-| FK field lookup | `EntityLookup` | `@/components/ui/EntityLookup` |
-| Statistics | `StatCard` | `@/components/StatCard` |
-| Loading spinner | `Loader2` | `lucide-react` |
-| Page loader | `PageLoader` | `@/components/ui/PageLoader` |
+| 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
 
-- **NEVER** use raw `<table>` — use SmartTable
+- **NEVER** use raw `<table>` — use `DataTable` from `@/components/ui/DataTable`
 - **NEVER** create custom spinners — use `Loader2` from lucide-react
 - **NEVER** import axios directly — use `@/services/api/apiClient`
 - **ALWAYS** use `PageLoader` as Suspense fallback
 - **ALWAYS** use existing shared components before creating new ones
+- **ALWAYS** use `EntityLookup` for FK Guid fields (never `<select>` or `<input>` for GUIDs)
 
 ---
 
@@ -1183,7 +1322,7 @@ Before marking frontend tasks as complete, verify:
 - [ ] Pages follow loading → error → content pattern
 - [ ] 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)
+- [ ] Components use DataTable/EntityCard (never raw HTML `<table>`)
 - [ ] **FK fields use `EntityLookup` — ZERO plain text inputs for Guid FK fields**
 - [ ] **All FK fields have `mapOption` showing display name, not GUID**
 - [ ] **Backend APIs support `?search=` query parameter for EntityLookup**
@@ -1232,44 +1371,55 @@ export function EntityCreatePage() {
     <div className="space-y-6">
       {/* ... form header ... */}
 
-      <SmartForm fields={[
-        {
-          name: 'name',
-          type: 'text',
-          label: t('{module}:form.name', 'Name'),
-          required: true,
-        },
-        // Scope selector — binary toggle for optional entities
-        {
-          name: 'scope',
-          type: 'custom',
-          label: t('common:scope', 'Scope'),
-          render: () => (
-            <div className="space-y-2">
-              <label className="block text-sm font-medium text-[var(--text-primary)]">
-                {t('common:scope', 'Scope')}
-              </label>
-              <select
-                value={formData.isShared ? 'shared' : 'tenant'}
-                onChange={(e) => handleScopeChange(e.target.value)}
-                className="w-full px-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)] text-[var(--text-primary)]"
-              >
-                <option value="tenant">
-                  {t('common:scope.tenant', 'My Organization')}
-                </option>
-                <option value="shared">
-                  {t('common:scope.shared', 'Shared (All Organizations)')}
-                </option>
-              </select>
-              <p className="text-xs text-[var(--text-secondary)]">
-                {formData.isShared
-                  ? t('common:scope.shared.hint', 'This data will be accessible to all organizations')
-                  : t('common:scope.tenant.hint', 'This data will only be visible to your organization')}
-              </p>
-            </div>
-          ),
-        },
-      ]} />
+      <form onSubmit={handleSubmit} className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] p-6 space-y-4">
+        {/* Name 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>
+
+        {/* Scope selector — binary toggle for optional entities */}
+        <div className="space-y-2">
+          <label className="block text-sm font-medium text-[var(--text-primary)]">
+            {t('common:scope', 'Scope')}
+          </label>
+          <select
+            value={formData.isShared ? 'shared' : 'tenant'}
+            onChange={(e) => handleScopeChange(e.target.value)}
+            className="w-full px-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)] text-[var(--text-primary)]"
+          >
+            <option value="tenant">
+              {t('common:scope.tenant', 'My Organization')}
+            </option>
+            <option value="shared">
+              {t('common:scope.shared', 'Shared (All Organizations)')}
+            </option>
+          </select>
+          <p className="text-xs text-[var(--text-secondary)]">
+            {formData.isShared
+              ? t('common:scope.shared.hint', 'This data will be accessible to all organizations')
+              : t('common:scope.tenant.hint', 'This data will only be visible to your organization')}
+          </p>
+        </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)] disabled:opacity-50">
+            {submitting ? t('common:actions.saving', 'Saving...') : t('common:actions.save', 'Save')}
+          </button>
+        </div>
+      </form>
     </div>
   );
 }
@@ -1288,27 +1438,51 @@ export function EntityCreatePage() {
   });
 
   return (
-    <SmartForm fields={[
-      {
-        name: 'name',
-        type: 'text',
-        label: t('{module}:form.name', 'Name'),
-        required: true,
-      },
-      {
-        name: 'scope',
-        type: 'select',
-        label: t('common:scope', 'Scope'),
-        options: [
-          { value: 'Tenant', label: t('common:scope.tenant', 'My Organization') },
-          { value: 'Shared', label: t('common:scope.shared', 'Shared') },
-          { value: 'Platform', label: t('common:scope.platform', 'Platform (Admin Only)') },
-        ],
-        default: 'Tenant',
-        required: true,
-        help: t('common:scope.help', 'Select the visibility level for this data'),
-      },
-    ]} />
+    <form onSubmit={handleSubmit} className="bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)] p-6 space-y-4">
+      {/* Name 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>
+
+      {/* Scope selector — enum values for scoped entities */}
+      <div>
+        <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
+          {t('common:scope', 'Scope')}
+        </label>
+        <select
+          value={formData.scope}
+          onChange={(e) => setFormData(prev => ({ ...prev, scope: e.target.value }))}
+          className="w-full px-3 py-2 border border-[var(--border-color)] rounded-[var(--radius-input)] bg-[var(--bg-card)] text-[var(--text-primary)]"
+          required
+        >
+          <option value="Tenant">{t('common:scope.tenant', 'My Organization')}</option>
+          <option value="Shared">{t('common:scope.shared', 'Shared')}</option>
+          <option value="Platform">{t('common:scope.platform', 'Platform (Admin Only)')}</option>
+        </select>
+        <p className="text-xs text-[var(--text-secondary)] mt-1">
+          {t('common:scope.help', 'Select the visibility level for this data')}
+        </p>
+      </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)] disabled:opacity-50">
+          {submitting ? t('common:actions.saving', 'Saving...') : t('common:actions.save', 'Save')}
+        </button>
+      </div>
+    </form>
   );
 }
 ```
@@ -1382,7 +1556,7 @@ export function ScopeBadge({ tenantId, scope }: ScopeBadgeProps) {
 }
 ```
 
-### Using ScopeBadge in SmartTable Columns
+### Using ScopeBadge in DataTable Columns
 
 ```tsx
 // In the list page, add a scope column
@@ -1403,10 +1577,11 @@ const columns = [
 ];
 
 return (
-  <SmartTable
+  <DataTable
     columns={columns}
     data={data}
-    loading={loading}
+    searchable
+    pagination={{ pageSize: 10 }}
     onRowClick={(row) => navigate(`${row.id}`)}
   />
 );

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

@@ -315,7 +315,7 @@ const [loading, setLoading] = useState(true);
 
 ### Components & CSS
 
-**Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
+**Components:** DataTable, EntityCard, EntityLookup (NEVER raw HTML `<table>`)
 **CSS:** Variables ONLY — hardcoded Tailwind colors are **BLOCKING** in POST-CHECK 9:
 
 | Instead of | Use |
@@ -377,7 +377,7 @@ See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` co
 **FORBIDDEN:**
 - `src/pages/{Module}/` (flat, missing App)
 - `import axios` → use `@/services/api/apiClient`
-- `<table>` → use SmartTable
+- `<table>` → use DataTable
 - `<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`

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

@@ -299,12 +299,22 @@ test({module}): backend unit and integration tests
 For each module:
 - **API client:** MCP scaffold_api_client
 - **Routes:** MCP scaffold_routes (outputFormat: 'clientRoutes') → generates lazy imports + Suspense
+- **Wire Routes to App.tsx (BLOCKING):** After scaffold_routes, routes MUST be wired into App.tsx:
+  → Read App.tsx and detect the routing pattern
+  → **Pattern A** (`applicationRoutes: ApplicationRouteExtensions`): add routes to `applicationRoutes['{application_kebab}'][]` with RELATIVE paths
+  → **Pattern B** (JSX `<Route>`): nest routes inside `<Route path="/{application}" element={<AppLayout />}>` + duplicate in tenant block
+  → **FORBIDDEN:** Adding business routes to `clientRoutes[]` — it is ONLY for non-app routes (`/about`, `/pricing`)
+  → ALL business applications use `<AppLayout />` as layout wrapper
+  → See `references/frontend-route-wiring-app-tsx.md` for full Pattern A/B detection and examples
+  → Verify: `mcp__smartstack__validate_frontend_routes (scope: 'routes')`
 - **Pages:** use /ui-components skill — MUST follow smartstack-frontend.md patterns:
   → React.lazy() for all page imports (named export wrapping)
   → `<Suspense fallback={<PageLoader />}>` around all lazy components
   → Page structure: hooks → useEffect(load) → loading → error → content
   → CSS variables only: bg-[var(--bg-card)], text-[var(--text-primary)]
-  → SmartTable/SmartFilter/EntityCard (NEVER raw HTML)
+  → DataTable/EntityCard (NEVER raw HTML `<table>`)
+  → If entity has FK Guid fields: generate EntityLookup component in @/components/ui/EntityLookup (see smartstack-frontend.md section 6)
+  → Dashboard pages: generate StatCard + ChartCard locally (see ui-components patterns/dashboard-chart.md)
 - **FORM PAGES (CRITICAL):** Create/Edit forms are FULL PAGES with own routes:
   → EntityCreatePage.tsx with route /{module}/create
   → EntityEditPage.tsx with route /{module}/:id/edit
@@ -368,6 +378,13 @@ For each entity:
     **MANDATORY: Read references/smartstack-frontend.md FIRST**
     - API client: MCP scaffold_api_client
     - Routes: MCP scaffold_routes (outputFormat: 'clientRoutes')
+    - Wire Routes to App.tsx (BLOCKING): After scaffold_routes, wire into App.tsx:
+      → Read App.tsx, detect Pattern A (applicationRoutes) or Pattern B (JSX Route)
+      → Pattern A: add to applicationRoutes['{application_kebab}'][] with RELATIVE paths
+      → Pattern B: nest inside <Route path='/{application}' element={<AppLayout />}> + tenant block
+      → FORBIDDEN: Adding business routes to clientRoutes[] (ONLY for /about, /pricing)
+      → See references/frontend-route-wiring-app-tsx.md for full patterns
+      → Verify: mcp__smartstack__validate_frontend_routes (scope: 'routes')
     - Pages: /ui-components skill (ALL 4 types: List, Detail, Create, Edit)
     - I18n: 4 JSON files (fr, en, it, de)
     - FORM PAGES: Full pages with own routes (ZERO modals)

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

@@ -57,7 +57,7 @@ For each changed file, check:
 - [ ] Random GUIDs in seed data via Guid.NewGuid() (no deterministic/sequential/fixed)
 - [ ] 4 languages in translations
 - [ ] CSS variables (not hardcoded colors)
-- [ ] SmartTable/SmartForm (not raw HTML tables/forms)
+- [ ] DataTable (not raw HTML `<table>`) and concrete form markup (not non-existent SmartForm)
 - [ ] Correct Layout wrapper per application
 
 **FK Fields & Forms:**

package/templates/skills/ralph-loop/references/task-transform-legacy.md

@@ -77,7 +77,7 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
       id: taskId,
       description: `[frontend] Generate COMPLETE frontend for module ${moduleCode} via MCP (${frontendFiles.length} files)`,
       status: "pending", category: "frontend", dependencies: apiDepId ? [apiDepId] : [],
-      acceptance_criteria: `Pages in src/pages/${app}/${moduleCode}/; MCP scaffold_api_client + scaffold_routes; SmartTable for lists; CSS variables ONLY; 4-language i18n; npm run typecheck passes`,
+      acceptance_criteria: `Pages in src/pages/${app}/${moduleCode}/; MCP scaffold_api_client + scaffold_routes; DataTable for lists; CSS variables ONLY; 4-language i18n; npm run typecheck passes`,
       started_at: null, completed_at: null, iteration: null, commit_hash: null,
       files_changed: { created: frontendFiles.map(f => f.path), modified: [] },
       validation: null, error: null, module: moduleCode,
@@ -136,7 +136,7 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
     tasks.push({ id: taskId,
       description: `[frontend] Generate COMPLETE frontend for ${moduleCode} via MCP (${derivedFiles.length} files)`,
       status: "pending", category: "frontend", dependencies: [lastIdByCategory["api"] || lastIdByCategory["application"]].filter(Boolean),
-      acceptance_criteria: `Pages in src/pages/${app}/${moduleCode}/; SmartTable for lists; CSS variables ONLY; 4-language i18n; npm run typecheck passes`,
+      acceptance_criteria: `Pages in src/pages/${app}/${moduleCode}/; DataTable for lists; CSS variables ONLY; 4-language i18n; npm run typecheck passes`,
       started_at: null, completed_at: null, iteration: null, commit_hash: null,
       files_changed: { created: derivedFiles.map(f => f.path), modified: [] },
       validation: null, error: null, module: moduleCode,